Repository navigation
ci(docs): harden fabricated-docs checker + enforce --strict (QG v2 Fase 9 T9) - #4149
Merged
Merged
Conversation
…x/tests-env/hooks precision) + tests
Eliminate the ~90% false-positive rate that blocked enforcing the
fabricated-docs gate in --strict mode, WITHOUT blinding it to real
fabrications (anti-over-suppression tests prove this):
- env-var: skip documented UPPER_SNAKE that resolve to a code identifier
(export const / enum / object-literal key), and broaden the env-read
index to bracket notation (process.env["X"]), env helper wrappers
(envInt("X")), the tests/ tree, and the env contract (.env.example +
ENVIRONMENT.md). Also skip lines that explicitly state a var does not
exist / is not implemented.
- api-path: a documented prefix (/api/cloud/, /api/services/{name}/) is
valid when any route.ts exists under it (ancestor-prefix index), with
[id]/[...path] -> {id}/{path} dynamic-segment normalization.
- hook: add the 6 real callbacks docs reference (onChunk, onFirstChunk,
onServerStatus, onPortChanged, onUpdateStatus, onEmpty).
- file-ref: skip tutorial placeholders (your-*/my*) and path tails of a
longer ref (./src/... examples, @scope/pkg/src/... package paths).
- skip point-in-time docs (design/research/plans, release notes, the
coverage plan) — forward/historical refs are expected there.
- fix latent main() bug: --strict now exits 0 on a clean run.
Parameterize buildCodebaseIndex/scanDocFile/runFabricatedDocsCheck on a
root dir so the new tests exercise the real heuristic against fixture
repos. 20 tests, including 4 anti-over-suppression guards proving a
genuinely missing file / fabricated env var / fabricated API path is
STILL flagged.
QG v2 Fase 9 T9.
…aths
Correct file/path references that no longer resolve, each verified against
the real target via git ls-files:
- ARCHITECTURE.md: src/lib/domain/* -> src/domain/* (costRules, fallbackPolicy,
comboResolver, lockoutPolicy); the others moved out of the domain layer ->
src/shared/constants/errorCodes.ts, src/shared/utils/{requestId,fetchTimeout,
requestTelemetry}.ts, src/lib/compliance/index.ts, src/lib/evals/evalRunner.ts;
circuit breaker open-sse/services/circuitBreaker.ts -> src/shared/utils/circuitBreaker.ts.
- src/lib/db/AGENTS.md: src/lib/db/localDb.ts -> src/lib/localDb.ts.
- ENVIRONMENT.md: scripts/check-env-doc-sync.mjs -> scripts/check/check-env-doc-sync.mjs.
- ERROR_SANITIZATION.md: src/lib/log/redaction.ts -> src/shared/utils/logRedaction.ts.
- MONITORING_SECTIONS.md: drop non-existent src/i18n/fallback.ts; the fallback is
next-intl, configured in src/i18n/config.ts.
- REPOSITORY_MAP.md: remove the stale generate-docs-index.mjs row (script and its
docs-auto-generated.ts output were both removed in the Fumadocs migration, v3.8.3).
- PLAYGROUND_STUDIO.md: migration 076_playground_presets.sql -> 084_playground_presets.sql.
- PROVIDERS.md: src/lib/providers/wrappers/claudeWeb.ts (removed) -> the cookie
utilities' real home src/lib/providers/webCookieAuth.ts.
- CLI-TOOLS.md: the non-interactive setup table claimed 5 OMNIROUTE_* env vars that
are not wired (only OMNIROUTE_API_KEY is bound via Commander .env()); document the
real flags (--password/--provider/...) instead.
QG v2 Fase 9 T9.
Flip check:fabricated-docs to --strict so the docs-sync-strict CI job (ci.yml: npm run check:docs-all) now FAILS on any fabricated API path / env var / hook / file reference, instead of only warning. Safe to enforce now that the checker is precise (prior commit took the strict count from 506 findings -> 0) and the genuine stale refs are fixed. check:docs-all exits 0.
Contributor
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Merged
tkgo11
pushed a commit
to tkgo11/OmniRoute
that referenced
this pull request
Sep 23, 2026
…se 9 T9) (cheaper-inference#4149) Harden fabricated-docs checker (precision: env helpers/code-identifiers/api-prefixes/env-contract/tutorial-placeholders) + enforce --strict (QG v2 Fase 9 T9). Inclui testes anti-over-suppression + correção de refs stale de docs. Integrado em release/v3.8.29.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Contexto (QG v2 Fase 9 — Task 9)
O gate
check:fabricated-docsafirmava rodar--strictna doc, mas no CI rodava SOFT (viacheck:docs-all, sem--strict). Flipar direto era inviável: o heurístico emitia 506 achados, ~90% falso-positivo (confundiaexport const/enum com env vars, não entendia prefixos de rota, allowlist de hooks incompleta). Este PR torna o gate strict significativo — precisão real, não supressão.O que mudou (3 commits)
feat(quality): harden fabricated-docs checker— 4 fixes de precisão + extras: exclui identificadores de código (export const/enum) do heurístico env-var; indexatests/+.env.example/ENVIRONMENT.md(contrato de env) + leituras bracket/helper; reconhece prefixos de API com sub-rotas (/api/cloud/,/api/services/{name}/); expandeKNOWN_HOOKS; pula placeholders de tutorial. Corrigiu também um bug latente domain()(strict dava exit 1 com 0 achados). +20 testes incluindo 4 guardas anti-over-suppression (arquivo/env/API fabricado AINDA é flagueado).docs(architecture): fix stale paths— refs reais quebradas corrigidas (alvo confirmado viagit ls-files):src/lib/domain/*→src/domain/*(+ os que saíram do domain layer p/shared/constants/shared/utils/lib/compliance/lib/evals),circuitBreaker→src/shared/utils/,localDb→src/lib/localDb.ts,webCookieAuth→src/lib/providers/, migration076→084,claudeWeb.ts(removido)→webCookieAuth.ts, e CLI-TOOLS.md (5 env varsOMNIROUTE_*que não estão wired — só flags; sóOMNIROUTE_API_KEY+DATA_DIRsão env).ci(docs): enforce fabricated-docs --strict— flip nopackage.json.Resultado: 506 → 0 achados. 36 FPs irredutíveis (env vars de CLIs externas, Node error codes, constantes de código em prosa, paths upstream) foram para allowlists existentes com justificativa por-entrada — verificado individualmente, sem mass-allowlist.
Validação
node --import tsx/esm --test tests/unit/check-fabricated-docs.test.ts→ 20/20 PASS (inclui guardas anti-mascaramento).node scripts/check/check-fabricated-docs.mjs --strict→ exit 0;npm run check:docs-all(o que o CI roda em ci.yml:274) → exit 0.src/totally/fake/x.ts+/api/fake/probenuma doc → strict pega ambos (checker não cegou).typecheck:coreexit 0; lint dos arquivos tocados limpo.🤖 Generated with Claude Code