feat(miner): generated env-var reference with CI drift check (#5179)

[RealDiligent]

Summary

• Add packages/gittensory-miner/scripts/generate-env-reference.mjs scanning bin/, lib/, and scripts/ for GITTENSORY_MINER_* / MINER_* env reads (including resolveLocalStoreDbPath literals)
• Generate packages/gittensory-miner/docs/env-reference.md via npm run miner:env-reference
• Wire miner:env-reference:check into test:ci so stale docs fail the build
• Cross-link the doc from packages/gittensory-miner/README.md

Closes #5179

Test plan

• npm run miner:env-reference:check
• npx vitest run test/unit/miner-env-reference-script.test.ts (determinism + stale-doc regression)
• Initial generated doc committed (20 vars)

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.36%. Comparing base (fb9fb20) to head (1cfc725).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5295   +/-   ##
=======================================
  Coverage   94.36%   94.36%           
=======================================
  Files         474      474           
  Lines       40124    40124           
  Branches    14629    14629           
=======================================
  Hits        37865    37865           
  Misses       1583     1583           
  Partials      676      676           

Flag	Coverage Δ
shard-1	46.55% <ø> (+0.13%)	⬆️
shard-2	34.63% <ø> (-0.06%)	⬇️
shard-3	32.06% <ø> (ø)
shard-4	32.10% <ø> (ø)
shard-5	33.68% <ø> (ø)
shard-6	44.83% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gittensory-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-12 13:31:33 UTC}

7 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): scripts/gen-selfhost-env-reference.mjs (matched scripts/**).

Review summary
This adds a generator script for a miner env-var reference doc, wires a CI drift check via `miner:env-reference:check`, and includes tests that exercise the real regex/AST extraction and determinism paths rather than fabricated scenarios. The shared `scripts/gen-selfhost-env-reference.mjs` also gained a new `resolveLocalStoreDbPath`-literal-arg detector, which is reused by both the miner and self-host generators — worth confirming the self-host doc wasn't left stale by this shared change. The PR closes #5179, is narrowly scoped to the stated intent, and the tests actually run the extraction logic against fixture files rather than mocking output.

Nits — 6 non-blocking

• packages/gittensory-miner/scripts/generate-env-reference.mjs: DEFAULT_PATTERNS uses eight near-duplicate regexes for quote-style/trim variants — consider collapsing to fewer patterns with alternation to ease future maintenance.
• scripts/gen-selfhost-env-reference.mjs:118-124: the new `isEnvNameLiteralArgHelperCall`/`ENV_NAME_LITERAL_ARG_HELPERS` addition is shared by both generators — confirm `apps/gittensory-ui/src/lib/selfhost-env-reference.ts` doesn't need regeneration if any self-host source root also calls `resolveLocalStoreDbPath` with a literal name.
• packages/gittensory-miner/scripts/generate-env-reference.mjs:96 (walkSourceFiles): nested nesting depth is a bit high; could extract the directory-vs-file branch into a helper for readability.
• The generated `docs/env-reference.md` table has no explanation of what the "Default" column means when a var has no literal default (e.g. DB path vars) — a one-line legend in the doc header could help readers.
• Add a short comment or doc note next to `ENV_NAME_LITERAL_ARG_HELPERS` in the shared script clarifying that adding an entry there affects both the self-host and miner generated docs, since a future contributor editing one may not realize the other needs regenerating too.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#5179
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 310 registered-repo PR(s), 145 merged, 24 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 310 PR(s), 24 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 310 PR(s), 24 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review