Pular para conteúdo

AUR-447 — aurumcode docs documents Rust and C# like the pipeline already does

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

aurumcode docs --source <projeto Rust ou C#> generates real documentation pages the same way cmd/regenerate-docs already does. Command syntax, flags, defaults and exit codes are unchanged from docs/specs/AUR-426.md; this card fixes what languages the CLI's copy of the registration list covers.

Achado (revisao do AUR-427)

Before this card, cmd/aurumcode/docs.go carried its own registerDocsExtractors that predated AUR-427 and was never updated when AUR-427 gave cmd/regenerate-docs native, tool-free Rust and C# extractors. A reviewer reproduced the defect directly:

$ aurumcode docs --source ./tests/fixtures/docs/rustproject --output /tmp/site
aurumcode docs: documentation extraction produced no documentation: 1 source
files, 0 processed, 0 docs generated, 0 error(s), 1 language(s) skipped
{skipped: rust: no extractor registered [1 file(s)]}
$ echo $?
1

while cmd/regenerate-docs (AURUMCODE_SOURCE_DIR=... AURUMCODE_OUTPUT_DIR=... go run ./cmd/regenerate-docs) documented the same tree correctly, because its own registerLanguageExtractors already registered internal/documentation/extractors/rust.NewNativeExtractor() and .../csharp.NewNativeExtractor() by default (AUR-427).

Fix

cmd/aurumcode/docs.go's registerDocsExtractors now registers the same two native extractors, reused unmodified from internal/documentation/ extractors/rust and .../csharp — no extraction logic is reimplemented. The CLI's registered language set is now: Go, JavaScript, TypeScript, Python, C++, Rust, C#, Bash, PowerShell — the exact set cmd/regenerate-docs registers by default (its opt-in AURUMCODE_ALLOW_REPO_CODE_EXECUTION toolchain left off).

Achado e desenho: por que isto nao virou um registro unico compartilhado

The ideal fix is a single function both cmd/aurumcode and cmd/regenerate-docs call, so a future new language extractor can never be added to one binary's list and forgotten in the other's — exactly the defect this card fixes. That requires two things neither of which fits inside this card's paths:

  1. A home for the shared function. cmd/regenerate-docs's registerLanguageExtractors and cmd/aurumcode's (former) registerDocsExtractors are each defined in a package main — Go does not allow importing a main package, from either direction. A shared function has to live in an importable package, which here means internal/pipeline or internal/documentation.
  2. cmd/regenerate-docs/main.go calling it. Creating the shared function alone does not unify anything: cmd/regenerate-docs would keep using its own inline list unless its main.go is rewritten to call the new function instead.

Both are outside this card's paths (cmd/aurumcode, the declared test files, and this document only; cmd/regenerate-docs and internal/pipeline are read_paths, not writable). Rewriting cmd/regenerate-docs is also explicitly out of scope on its own terms — this card's Non-goals state "Reescrever pacote existente que ja cumpre a funcao; este card integra o que existe em vez de recriar", and cmd/regenerate-docs already documents Rust and C# correctly; it is not the package with the defect.

What this card does instead: cmd/aurumcode/docs.go's registerDocsExtractors is written to register, extractor-for-extractor, the exact same default set cmd/regenerate-docs's registerLanguageExtractors registers (its second, opt-in AURUMCODE_ALLOW_REPO_CODE_EXECUTION path stays cmd/regenerate-docs-only, since that logic lives inside its unimportable main package and executes code from the documented repository — wiring it a second time here is outside what this card's --help promises, same boundary docs/specs/AUR-426.md already drew). Both functions now import and call the identical extractor constructors (rustExtractor.NewNativeExtractor(), csharpExtractor.NewNativeExtractor(), and every other extractor already shared before this card) from the single place those constructors are actually defined (internal/documentation/extractors/*) — no extraction logic is duplicated, only the two short registration call lists remain separately maintained. The residual risk is the literal one this card's own root cause demonstrates: a language added to one list in the future and not mirrored in the other. Closing that risk structurally is a follow-up card whose paths would need to include internal/pipeline (or internal/documentation) and cmd/regenerate-docs.

What is intentionally out of scope

Unchanged from docs/specs/AUR-426.md, with the Rust/C# line corrected:

  • Welcome-page LLM generation and Jekyll-build validation are not wired into this subcommand.
  • The repository-code-executing Rust/C# toolchain (cmd/regenerate-docs's cargo/dotnet-backed RustExtractor/ CSharpExtractor, opt-in via AURUMCODE_ALLOW_REPO_CODE_EXECUTION) is not wired into this subcommand. Only the native, tool-free extractors are — see "Achado e desenho" above for why that boundary cannot move inside this card's paths.
  • --incremental, --docs-dir, --base-url and the other cmd/regenerate-docs knobs are not exposed as flags.

docs/specs/AUR-426.md's own "What is intentionally out of scope" section still says "Rust and C# extractors are not registered here" — that line is superseded by this card. docs/specs/AUR-426.md sits outside this card's paths, so it is not edited here; this document is the current, accurate statement of what aurumcode docs registers.

Command and exit codes

Unchanged from docs/specs/AUR-426.md:

aurumcode docs [--source <dir>] [--output <dir>] [--languages <list>]
aurumcode docs --help
Code Meaning
0 --help was requested: usage printed to stdout.
0 Documentation was generated: at least one page exists on disk after the run.
1 --source does not exist or is not a directory.
1 The pipeline failed outright.
1 The run produced zero documentation pages — aurumcode docs: no documentation page was generated on stderr.
2 Usage error: an unknown flag or a value a flag cannot parse.

Example (no secrets)

$ aurumcode docs --source ./tests/fixtures/docs/rustproject --output /tmp/rust-site
Generated 1 documentation page(s) in /tmp/rust-site:
  - /tmp/rust-site/rust/src__lib.md
$ echo $?
0
$ grep -F 'pub struct Entry' /tmp/rust-site/rust/src__lib.md
### struct pub struct Entry

The same fixture, run through cmd/regenerate-docs (AURUMCODE_SOURCE_DIR=./tests/fixtures/docs/rustproject AURUMCODE_OUTPUT_DIR=/tmp/rust-site2 go run ./cmd/regenerate-docs), writes the same rust/src__lib.md page with the same real symbols, because both callers now drive the same set of registered extractors against the same internal/pipeline engine.

No environment variable carrying a secret is read by this command path, same as before this card. A path derived from --source/--output (or from an extractor's underlying error) is passed through the AUR-009/AUR-432 redaction filter before it reaches stdout or stderr.

Failure diagnosis

Unchanged from docs/specs/AUR-426.md, except the "nothing any registered extractor recognizes" example: a Rust-only or C#-only project is now documented, not one of the causes of a zero-page run. The remaining causes (a --languages name with the wrong case or spelling; a filter matching nothing present in --source; a source tree with no file any registered extractor recognizes at all, e.g. Java-only) are unchanged.

MUT-001 note

The skeptical mutation flips cmd/aurumcode/docs.go's registerNativeRustAndCSharp constant from true to false, keeping both rustExtractor.NewNativeExtractor() and csharpExtractor.NewNativeExtractor() referenced in source (so the mutant still compiles — a compile break is explicitly disqualified as RED/mutation evidence by this card's TDD proof, the same constraint AUR-427's own MUT-001 solved this way) while skipping both registrations at runtime. Run against the card's own Rust fixture, the mutant reproduces the exact defect this card fixes: exit non-zero, "no extractor registered", zero Rust pages. tests/unit/AUR-447.go's Rust-generation subtest independently catches the same mutation when rebuilt against the mutated tree.

Compatibility

  • aurumcode review in every form AUR-430/431/435/436/438 published is byte-for-byte unchanged; this card's only edits are inside cmd/aurumcode/docs.go's extractor registration and its package documentation.
  • aurumcode docs's flags, defaults, --help text and exit codes (docs/specs/AUR-426.md) are unchanged. Only the set of languages a --source tree can be documented in grows, from seven to nine.
  • cmd/regenerate-docs is untouched by this card (outside paths) and keeps generating documentation exactly as before.