Module error_catalog 

Error-catalog extractor: build an LLM-facing catalog of every diagnostic emitted by the workspace, straight from rustdoc JSON.

Consumer contract (zero coupling)

Consumer crates need no dependency on cargo-aidoc. To have a struct or enum picked up as an error entry, the crate simply:

1. Derives miette::Diagnostic on the type (already the de facto Rust standard for structured diagnostics).
2. Passes code(...) inside #[diagnostic(...)]. help(...) and url(...) are optional but recommended — they land verbatim in the catalog output.
3. Optionally embeds fenced code blocks in the type’s doc comment with a code=<CODE> tag in the info-string, e.g. ```ebp,code=EBP001 or ```ebp,code=EBP001,fix. Any fence whose info-string contains code=<this-entry's-code> is collected as a snippet under that entry.

This mirrors the docs.rs bridge model: cargo-aidoc is the reader, consumers only ever emit information that already lives in their rustdoc JSON. A future Layer 2 (aidoc-attrs) can add opt-in #[aidoc::...] attributes gated behind #[cfg_attr(aidoc, ...)] for cases miette doesn’t cover, without changing this contract.

Extraction pipeline

extract walks every crate in the workspace, and for each rustdoc item whose attrs contain a #[diagnostic(...)] line, produces one ErrorEntry. Entries are sorted by their code for deterministic output.

The attribute parser (parse_diagnostic_attr) accepts the exact literal form rustdoc emits — including the \n that rustdoc inserts after commas inside the attribute — but is intentionally a hand-rolled string reader, not a proc-macro / syn parser. The surface area we care about is small (code(NAME) / help("...") / url("...")), and pulling in syn at this layer would drag in a large dependency tree for very little payoff.

What is covered

• Struct-level #[diagnostic(code(...), ...)] — one entry per struct.
• Enum-level #[diagnostic(code(...), ...)] — one entry per enum (rare; miette allows at most one code per enum).
• Per-variant #[diagnostic(code(...), ...)] on enum variants — one entry per catalogued variant. This is the dominant thiserror + miette shape and is what most real crates use; see try_build_entry and the walk driven by walk_enum_variants.

Not covered by MVP

• Variant-level source_code / label / related metadata from miette is intentionally not surfaced yet — those are runtime-facing, not spec-facing.
• Non-miette diagnostic frameworks (bevy_error, custom derives) would need their own attr shape; the extractor is written so another parser can be added alongside parse_diagnostic_attr without touching the walk.

Structs

ErrorEntry

One catalogued diagnostic: everything cargo-aidoc knows about a single error code, sourced from a single item in the workspace.

Snippet

A fenced code block extracted from an error’s doc comment.

Functions

extract

Walk the workspace and produce every catalogued diagnostic.