AUR-425 - Warn (and fail) when no documentation page was generated

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

Outcome

When a run of the documentation generator produces zero pages, the command states the reason and exits non-zero. Before this card, that run logged a warning and exited 0, indistinguishable from success for every caller that checks the exit status - the composite action, CI, and any script chaining on &&.

The command

The card's AC-001 phrase aurumcode docs --source <dir> is realized by the one real shape this repository ships for documentation generation - the cmd/regenerate-docs binary with its source directory knob - which is exactly how every shipped consumer invokes it (action.yml, scripts/action-entrypoint.sh, tests/e2e/smoke_test.go). At the time this card was authored, cmd/aurumcode published only review (AUR-430) and had no docs subcommand. cmd/aurumcode later gained a flag-driven docs subcommand delivered by AUR-426 (cmd/aurumcode/docs.go, wired at cmd/aurumcode/main.go's case "docs":), which is now the discoverable, --help-documented way to run the same pipeline. cmd/aurumcode remains outside this card's paths, so cmd/regenerate-docs stays the real shape this card's own AC-001 exercises and this spec documents.

AURUMCODE_SOURCE_DIR=./projeto-sem-suporte go run ./cmd/regenerate-docs

Options (environment)

Variable	Meaning
AURUMCODE_SOURCE_DIR	Tree to document (default ., resolved absolute)
AURUMCODE_OUTPUT_DIR	Where pages are written (default .aurumcode)
AURUMCODE_DOCS_DIR	Site directory (default: the output directory)
AURUMCODE_LANGUAGES	Comma-separated language filter; empty means all
AURUMCODE_INCREMENTAL	true documents only files changed since the last documented commit
LLM_API_KEY / OPENAI_API_KEY	Optional welcome-page providers; unset runs fully offline

Exit codes

Exit	Verdict line	Meaning
0	result=ok	Pages generated, servable scaffold
0	result=partial	Pages generated; some languages skipped or failed
1	result=failed	Pipeline error and nothing (or nothing trustworthy) on disk
1	result=unpublishable	Pages generated but every indexed page excluded by the consumer's _config.yml
1	result=empty	This card. The run hit no error and still produced zero pages

result=empty keeps its distinct machine-readable token so a consumer can still tell "nothing was documentable" from "the pipeline broke"; only the process exit status changed, from 0 to 1.

Failure diagnostic

The reason is built from the run's own configuration and printed both on the ❌ NO DOCUMENTATION PRODUCED log line and in the fatal message:

no documentation page was produced: no supported source file was documented under /abs/projeto-sem-suporte

with a cause appended for each knob that was actually in force:

• ; the language filter AURUMCODE_LANGUAGES=python,rust may exclude every supported file - when a filter is set (a documentable tree can be emptied by the filter alone);
• ; incremental mode (AURUMCODE_INCREMENTAL=true) documents only files changed since the last documented commit - when incremental mode is on.

The zero-page branch is only reachable when file discovery matched nothing: a detected-but-unsupported language (e.g. Java) ends as a skip inside a pipeline error (result=failed/result=partial), never as result=empty. Note that the page count is what is on disk after the run: an incremental no-op over previously generated pages still counts those pages and stays result=ok.

Runnable example (no secret required)

mkdir -p /tmp/projeto-sem-suporte
echo 'plain text' > /tmp/projeto-sem-suporte/notes.txt
AURUMCODE_SOURCE_DIR=/tmp/projeto-sem-suporte \
AURUMCODE_OUTPUT_DIR=/tmp/aur425-out \
go run ./cmd/regenerate-docs
echo "exit=$?"   # exit=1, reason printed, summary line: aurumcode: result=empty ...

Validation

• Unit tests/unit/AUR-425.go::TestAUR425: unsupported-only project, real binary, exit exactly 1, stated reason, result=empty, no success marker.
• Integration tests/integration/AUR-425.go::IntegrationAUR425: an all-excluding AURUMCODE_LANGUAGES filter fails with the filter named; the same project without the filter documents and exits 0 (no overshoot).
• E2E tests/e2e/AUR-425.sh::E2EAUR425: the declared command twice - exit 1, reason with the real directory, deterministic output (timestamps and run-scoped paths normalized), AURUM_SECRET_CANARY never surfaces, and a positive control that still documents a real Go project with exit 0.
• Acceptance tests/acceptance/AUR-425.sh: the lanes above plus a regression lane (go test ./cmd/regenerate-docs, the package this card changed). Pre-fix the accept fails AUR-425/AC-001/behavior-missing; under MUT-001 (zero pages exiting 0 again) it fails registering AUR-425/AC-001/MUT-001.

Sealed-acceptance inputs (measured)

Every lane must execute the real binary - the promised contract is a raw process exit status, and MUT-001 is only falsifiable there - so the accept needs the compile closure of cmd/regenerate-docs: 19 local packages (go list -deps: internal/documentation/extractors and its seven language subpackages, internal/documentation/{incremental,normalizer,site,welcome}, internal/llm, internal/llm/{cost,httpbase}, internal/llm/provider/{litellm,openai}, internal/pipeline) plus gopkg.in/yaml.v3 from an offline module cache. When the runner does not materialize these read inputs, tests/acceptance/AUR-425.sh exits 69 naming the first missing path (closure_not_materialized:<path>): blocked/inconclusive per the card's Review clause, never a pass and never a behavioural failure.