Context
ORB already has apps/gittensory-ui/src/lib/selfhost-docs-audit.ts, a script/test that parses its self-host deployment docs and asserts the claimed env vars, file paths, and CLI details still exist in code, failing CI on drift. packages/gittensory-miner/DEPLOYMENT.md has no equivalent check: nothing verifies that the env-var names, file paths (e.g. SQLite store locations), or CLI subcommands it documents still match reality, so a rename or move can leave the doc silently stale.
Dependencies
None — independently shippable. It may be easier to implement by reusing the env-var scanner introduced by the generated-env-reference issue in this same batch (npm run miner:env-reference) if that PR lands first, but this is not a hard blocker — this check can parse DEPLOYMENT.md and cross-check against the source tree directly without it.
Requirements
- Add a script or test (e.g.
packages/gittensory-miner/scripts/docs-audit.js or test/unit/miner-deployment-docs-audit.test.ts) mirroring selfhost-docs-audit.ts's approach.
- Parse
DEPLOYMENT.md and extract every claimed GITTENSORY_MINER_*/MINER_* env-var name referenced in prose or code blocks.
- Extract every claimed file path referenced in DEPLOYMENT.md (e.g. SQLite store paths, config file paths, Dockerfile/compose file references).
- Extract every claimed CLI subcommand (e.g.
gittensory-miner <subcommand>) referenced in DEPLOYMENT.md.
- For each extracted env var, assert a corresponding read still exists somewhere under
packages/gittensory-miner/**.
- For each extracted file path, assert it still exists on disk (or matches a documented, still-valid pattern if it's a runtime-generated path).
- For each extracted CLI subcommand, assert it is still registered in the CLI's command table.
- Wire this check into CI (as part of
npm run test:ci or a dedicated npm run docs:audit step referenced from the CI workflow) so a mismatch fails the build with a clear message naming exactly which claim is stale.
Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the parser's success and failure paths for each claim type (env var, file path, CLI subcommand) against both in-sync and deliberately-stale fixture docs, (2) an invariant test asserting the audit check fails (never silently passes) whenever DEPLOYMENT.md references an env var, path, or subcommand that no longer exists in the source tree, and (3) a regression test reproducing a concrete stale-doc scenario (e.g. a renamed env var left undocumented) to confirm the check catches exactly the drift class this issue exists to prevent.
Codecov visibility note: packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.
Expected Outcome
A renamed env var, moved SQLite path, or removed CLI subcommand in packages/gittensory-miner/** now fails CI immediately instead of silently leaving DEPLOYMENT.md wrong for operators.
Links & Resources
apps/gittensory-ui/src/lib/selfhost-docs-audit.ts — the pattern being mirrored
packages/gittensory-miner/DEPLOYMENT.md — the doc being audited
packages/gittensory-miner/** — the source of truth being checked against
- Theme: Self-host packaging & docs
Context
ORB already has
apps/gittensory-ui/src/lib/selfhost-docs-audit.ts, a script/test that parses its self-host deployment docs and asserts the claimed env vars, file paths, and CLI details still exist in code, failing CI on drift.packages/gittensory-miner/DEPLOYMENT.mdhas no equivalent check: nothing verifies that the env-var names, file paths (e.g. SQLite store locations), or CLI subcommands it documents still match reality, so a rename or move can leave the doc silently stale.Dependencies
None — independently shippable. It may be easier to implement by reusing the env-var scanner introduced by the generated-env-reference issue in this same batch (
npm run miner:env-reference) if that PR lands first, but this is not a hard blocker — this check can parse DEPLOYMENT.md and cross-check against the source tree directly without it.Requirements
packages/gittensory-miner/scripts/docs-audit.jsortest/unit/miner-deployment-docs-audit.test.ts) mirroringselfhost-docs-audit.ts's approach.DEPLOYMENT.mdand extract every claimedGITTENSORY_MINER_*/MINER_*env-var name referenced in prose or code blocks.gittensory-miner <subcommand>) referenced in DEPLOYMENT.md.packages/gittensory-miner/**.npm run test:cior a dedicatednpm run docs:auditstep referenced from the CI workflow) so a mismatch fails the build with a clear message naming exactly which claim is stale.Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the parser's success and failure paths for each claim type (env var, file path, CLI subcommand) against both in-sync and deliberately-stale fixture docs, (2) an invariant test asserting the audit check fails (never silently passes) whenever DEPLOYMENT.md references an env var, path, or subcommand that no longer exists in the source tree, and (3) a regression test reproducing a concrete stale-doc scenario (e.g. a renamed env var left undocumented) to confirm the check catches exactly the drift class this issue exists to prevent.
Codecov visibility note:
packages/gittensory-miner/**,apps/gittensory-miner-ui/**, andapps/gittensory-miner-extension/**currently sit entirely outside vitest'scoverage.includeglob, socodecov/patchcannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change underpackages/gittensory-engine/src/**or the repo's ownsrc/**remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.Expected Outcome
A renamed env var, moved SQLite path, or removed CLI subcommand in
packages/gittensory-miner/**now fails CI immediately instead of silently leaving DEPLOYMENT.md wrong for operators.Links & Resources
apps/gittensory-ui/src/lib/selfhost-docs-audit.ts— the pattern being mirroredpackages/gittensory-miner/DEPLOYMENT.md— the doc being auditedpackages/gittensory-miner/**— the source of truth being checked against