Skip to content

ara check: assign rule codes to validate-layer diagnostics (name the rule for every finding) #43

Description

@EYH0602

Problem

ara check (added in #41) emits two kinds of diagnostic lines, and only one carries a rule id:

Format-lint layer (the 4 canonicalization rules) — named:

ARA002 [fixable]: trace/exploration_tree.yaml: `reason:` on a dead_end node is an alias; canonical key is `why_failed:`
ARA004 [fixable]: logic/claims.md: claim header uses a dash separator; canonical form is `## <id>: <title>`

Validate layer (reused from ara validate) — unnamed:

error:   nodes[N03].evidence[0]: evidence references unknown claim `C01`
warning: nodes[N02]: unknown field `reason`
error:   claims[C01]: duplicate claim id

So today only ARA001ARA004 are attributable to a named rule. The semantic/structural checks — unknown claim ref, duplicate id, cycle, missing id/type, unknown field, also_depends_on to unknown node, etc. — report what and where but not a coded rule. Tools like ruff put a code (E501, F401) on every finding, which makes suppression, per-rule config (see #40), CI annotations, and docs cross-linking uniform.

Proposed change

Assign stable rule codes to the validate-layer diagnostics as well, so every ara check finding names the rule it violates. Sketch of a code space (final numbering TBD):

  • ARA0xx — format/canonicalization (existing fixable rules ARA001ARA004).
  • ARA1xx — structural/reference errors (unknown claim ref, also_depends_on unknown node, duplicate id, cycle, both/neither tree:/root:, …).
  • ARA2xx — field/schema warnings (unknown field, missing optional, …).

Each existing Diagnostic (currently severity + path + message) would gain a rule code, surfaced in both the human output (ARA1xx error: …) and the --json report so CI annotators can group by rule.

Constraints

  • Do not change ara validate's output. The plan for feat: add ara check fixable ARA linter + reusable CI action (#39) #41 deliberately kept validate byte-stable because other tooling/docs depend on it. Codes should be added in the check presentation layer (or in a way that leaves validate's existing text untouched) — decide during design whether codes live on Diagnostic itself (and are only rendered by check) or are mapped in check.
  • Codes must be stable once published (they become an API surface for suppression/config).
  • Pairs cleanly with per-rule config (ara check: per-rule config via .ara-check.toml #40): config keys off the codes.

Acceptance

  • Every ara check finding (both layers) carries a documented, stable rule code in human and --json output.
  • ara validate's output is unchanged.
  • Codes documented in docs/stage-5-check.md (a table: code → meaning → severity → fixable?).

Follow-up from #41.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions