Linting¶

The AI Linter checks flow definitions for best practices and catches common mistakes that don't qualify as hard errors but indicate problems.

Usage¶

CLI¶

# Lint all flows in a directory
hbia lint flows/

# Strict mode: treat warnings as errors (non-zero exit code)
hbia lint flows/ --strict

Python¶

from honey_badgeria.back.lint import AILinter

linter = AILinter()
issues = linter.lint(yaml_dict)

for issue in issues:
    print(f"[{issue.code}] {issue.severity}: {issue.message}")
    if issue.suggestion:
        print(f"  → {issue.suggestion}")

Lint Codes¶

Errors¶

Code	Message	Description
`E001`	Vertex referenced in `next` not defined	A vertex lists a target in `next` that doesn't exist in the flow
`E002`	Flow has zero edges	A flow with vertices but no `next` connections — nothing is wired up

Warnings¶

Code	Message	Description
`W001`	Missing `effect` field	Vertex doesn't declare `pure` or `side_effect`. Critical for AI understanding.
`W002`	Missing `version` field	Vertex doesn't declare a version. Important for change tracking.
`W003`	Missing `handler` field	Vertex has no handler path.
`W005`	Missing `outputs` declaration	Vertex doesn't declare what it produces.
`W006`	Vertex name not in `snake_case`	Naming convention violation (e.g., `FetchUser` instead of `fetch_user`).
`W007`	Single-vertex flow	Flow contains only one vertex — likely an incomplete pipeline.

LintIssue¶

Each issue is a LintIssue object:

@dataclass
class LintIssue:
    code: str           # "E001", "W002", etc.
    severity: str       # "error" or "warning"
    message: str        # Human-readable description
    suggestion: str     # Recommended fix (optional)

Issues are returned sorted by severity: errors first, then warnings.

Strict Mode¶

In strict mode (--strict), warnings are treated as errors. The CLI exits with a non-zero code if any issues are found. This is useful for CI pipelines:

# CI configuration
hbia lint flows/ --strict || exit 1

Why Linting Matters¶

The linter enforces the conventions that make HBIA effective for AI agents:

effect declarations tell the engine what's safe to cache and parallelize, and tell AI agents where side effects happen.
version tracking supports the rewrite-over-patch workflow.
outputs declarations enable data flow tracing — without them, AI agents can't predict what a vertex produces.
snake_case naming keeps the YAML consistent and machine-parseable.
Connected flows ensure every vertex is reachable and useful.