Pular para conteúdo

AUR-483: A documentacao gerada e do produto, nao dos testes dele

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

Problem

Measured on this repository: of the 613 code files internal/pipeline.ExtractorPipeline scanned, 489 (79%) were test or fixture code (tests/ alone: 399 files). shouldSkipPath (internal/pipeline/extractor_pipeline.go) already skipped node_modules, .git, .github, vendor, target, dist, build, _site, .taskmaster and .aurumcode, but never tests/, testdata/ or fixtures/. The published site (https://mpaape.github.io/AurumCode/) was therefore roughly 80% raw enumeration of the repository's own test scaffolding. Since the rule lives in the generator, not this repository, every user pointing AurumCode at their own repository inherited the same noise ratio.

Fix

internal/pipeline/extractor_pipeline.go adds:

  • IsTestScopePath(path string) bool -- reports whether path is test or fixture scope: a directory component (not substring) equal to tests, testdata or fixtures, or a filename stem (not substring) ending in _test. Matching a whole path component/stem, never a substring, is what keeps internal/attestation, cmd/latest and a file named contest.go out of scope even though each contains the letters "test" (AC-003).
  • ExtractorPipelineConfig.IncludeTests bool and (*ExtractorPipeline).IncludeTests() bool -- the latter is true when either the config field is set or the process environment carries AURUMCODE_INCLUDE_TEST_DOCS (1/true/yes/on, case-insensitive). Default: false -- test/fixture scope is excluded unless explicitly turned back on (AC-002).
  • determineFilesToProcess excludes test/fixture-scope files from the file-discovery walk (both the full-extraction and incremental branches) when IncludeTests() is false, and its log always states the outcome: "scope: excluded N file(s) as test or fixture scope (...)" in the default case, or that the exclusion was disabled by config, in the opt-in case (AC-001's declaration requirement).
  • buildScopedSourceView / sourceDirForExtraction / Run -- why file-discovery filtering alone is not enough: every language extractor (ExtractRequest carries no file list) discovers its own files by independently walking SourceDir, so narrowing determineFilesToProcess's own file list changes only its accounting, never what an extractor actually reads. Run therefore builds a scoped copy (not a symlink tree -- some extractors' own walks may not treat a symlink DirEntry as a regular file) of SourceDir with test/fixture scope removed, and points every extractor at that copy instead, whenever !IncludeTests() and the run is not incremental. IncludeTests()==true (or incremental mode) leaves SourceDir completely untouched -- byte-for-byte the pre-AUR-483 code path.

No extractor and no page-rendering code was touched (out of scope per the card's Non-goals); internal/documentation/extractors/* and internal/documentation/site/welcome are read-only context for this card.

Measured result (this repository, this worktree)

cmd/regenerate-docs run against this repository's own root, no LLM provider configured:

pages generated
before (pre-AUR-483) 236
after (AUR-483 default) 57

A 76% drop, consistent with the card's own 79%-noise measurement.

Configuring test documentation back on

Set AURUMCODE_INCLUDE_TEST_DOCS=true in the process environment of whichever binary invokes internal/pipeline (cmd/regenerate-docs, aurumcode docs, or a direct caller of the Go API via ExtractorPipelineConfig.IncludeTests = true). The environment variable is read directly by internal/pipeline itself, not plumbed through either CLI's own flag/env parsing -- both of which are read_paths for this card, not paths, and were not modified -- so the opt-in reaches every entrypoint without any of them needing a code change.

One caveat, not introduced by this card: the Go extractor (internal/documentation/extractors/go) has always hardcoded testdata in its own, separate package-discovery skip list, unconditional on any flag. Setting AURUMCODE_INCLUDE_TEST_DOCS=true restores tests/ and fixtures/ Go packages; a testdata/ Go package stays excluded by that pre-existing, unrelated mechanism, which this card's paths do not include.

Acceptance

  • AC-001 (nominal): default generation excludes tests/, testdata/, fixtures/ and *_test files; the run declares how many files it excluded by scope; the number of generated pages drops.
  • AC-002 (configurable): AURUMCODE_INCLUDE_TEST_DOCS=true restores test documentation; the capability was not removed.
  • AC-003 (component, not substring): internal/attestation, cmd/latest and contest.go are always documented.

tests/unit/AUR-483.go::TestAUR483 proves IsTestScopePath/IncludeTests in isolation. tests/integration/AUR-483.go::IntegrationAUR483 runs the real ExtractorPipeline.Run against the committed fixture (tests/fixtures/docs/AUR-483) and inspects the markdown pages it writes. tests/e2e/AUR-483.sh::E2EAUR483 runs the real cmd/regenerate-docs binary end to end and inspects both the generated pages and the stderr declaration. tests/acceptance/AUR-483.sh orchestrates all of the above plus MUT-001 (neutralizes the default-exclusion gate in Run) and MUT-002 (rewrites IsTestScopePath to match by substring), each proving the mutant is rejected by the same accept command.