chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,903 @@
|
||||
#!/usr/bin/env node
|
||||
// Doc accuracy gate — catches fabricated API/endpoint/function/env-var claims in docs.
|
||||
//
|
||||
// Scans every `docs/{*,*/*}.md` and `AGENTS.md` for concrete code references and
|
||||
// verifies each one against the source. Reports drift as warnings (soft-fail
|
||||
// by default) and exits 1 with `--strict` so CI can block fabricated claims.
|
||||
//
|
||||
// What it checks:
|
||||
// 1. /api/... endpoint paths → must match a route.ts file under src/app/api/
|
||||
// 2. UPPER_SNAKE env var names → must have a process.env.X or env.X read
|
||||
// 3. CLI commands `omniroute ...` → must exist in bin/cli/commands/ or bin/
|
||||
// 4. BUILTIN_EVENTS hook names → must be exported from hooks.ts
|
||||
// 5. `src/.../foo.ts` file refs → must exist (relative to repo root)
|
||||
// 6. `open-sse/.../bar.ts` file refs → must exist
|
||||
// 7. `bin/...` file refs → must exist
|
||||
//
|
||||
// Out of scope (covered by other scripts):
|
||||
// - File-size / line-count claims → scripts/check/check-docs-counts-sync.mjs
|
||||
// - Env var → doc table sync → scripts/check/check-env-doc-sync.mjs
|
||||
// - Cross-doc link integrity → scripts/check/check-doc-links.mjs
|
||||
// - openapi.yaml ↔ routes sync → scripts/check/check-openapi-coverage.mjs
|
||||
//
|
||||
// Exit codes:
|
||||
// 0 no drift (or soft warnings only)
|
||||
// 1 strict mode and any drift was found
|
||||
//
|
||||
// Usage:
|
||||
// node scripts/check/check-fabricated-docs.mjs # soft report
|
||||
// node scripts/check/check-fabricated-docs.mjs --strict # fail on any drift
|
||||
// node scripts/check/check-fabricated-docs.mjs --json # machine-readable output
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const ROOT = path.resolve(__dirname, "..", "..");
|
||||
|
||||
const ARGS = new Set(process.argv.slice(2));
|
||||
const STRICT = ARGS.has("--strict");
|
||||
const JSON_OUT = ARGS.has("--json");
|
||||
|
||||
// ── Config ─────────────────────────────────────────────────────────────────
|
||||
|
||||
/** Paths to scan recursively. AGENTS.md is checked too. */
|
||||
const SCAN_PATHS = ["docs", "AGENTS.md", "open-sse/AGENTS.md", "src/lib/db/AGENTS.md"];
|
||||
|
||||
/** Built-in event names that AGENTS.md / docs are allowed to mention. */
|
||||
const KNOWN_HOOKS = new Set([
|
||||
"onRequest",
|
||||
"onResponse",
|
||||
"onError",
|
||||
"onModelSelect",
|
||||
"onComboResolve",
|
||||
"onRateLimit",
|
||||
"onQuotaExhaust",
|
||||
"onProviderError",
|
||||
"onStreamStart",
|
||||
"onStreamEnd",
|
||||
"onInstall",
|
||||
"onActivate",
|
||||
"onDeactivate",
|
||||
"onUninstall",
|
||||
// Real callbacks wired in code that docs reference (verified present in src/):
|
||||
// onChunk/onFirstChunk — streaming callbacks (src/shared/utils/streamTracker.ts,
|
||||
// playground ChatTab.tsx); onServerStatus/onPortChanged/onUpdateStatus — Electron
|
||||
// IPC callbacks (src/shared/hooks/useElectron.ts, HomePageClient.tsx);
|
||||
// onEmpty — model-metadata registry callback (src/lib/modelMetadataRegistry.ts).
|
||||
"onChunk",
|
||||
"onFirstChunk",
|
||||
"onServerStatus",
|
||||
"onPortChanged",
|
||||
"onUpdateStatus",
|
||||
"onEmpty",
|
||||
]);
|
||||
|
||||
// Common false-positives the heuristic would otherwise flag. Add to this
|
||||
// list as the script matures — keep it small and well-justified.
|
||||
const ENV_VAR_ALLOWLIST = new Set([
|
||||
"PATH",
|
||||
"HOME",
|
||||
"USER",
|
||||
"SHELL",
|
||||
"PWD",
|
||||
"LANG",
|
||||
"NODE_ENV",
|
||||
"NODE_PATH",
|
||||
"NODE_OPTIONS",
|
||||
"NODE_EXTRA_CA_CERTS", // Node runtime CA var: read by Node itself + passed to a spawned subprocess (cloudflaredTunnel.ts), not via process.env.X (AGENTBRIDGE.md)
|
||||
"DEBUG",
|
||||
"VERBOSE",
|
||||
"LOG_LEVEL",
|
||||
"PORT", // generic, not OmniRoute-specific
|
||||
"DATA_DIR",
|
||||
"REQUIRE_API_KEY",
|
||||
"OMNIROUTE_BUILD_PROFILE", // build-time only
|
||||
"OMNIROUTE_BUILD_SHA",
|
||||
"OMNIROUTE_URL", // used by ad-hoc tooling, validated elsewhere
|
||||
"OMNIROUTE_KEY", // ditto
|
||||
"OPENCODE_API_KEY", // ditto
|
||||
// ── External-tool / spawn-injected / ops env vars ────────────────────────
|
||||
// Real environment variables, but they belong to an UPSTREAM CLI/tool, a
|
||||
// docker-compose/electron-build pipeline, or are injected into a spawned
|
||||
// subprocess — never read via `process.env.X` in OmniRoute's own source, so the
|
||||
// code-read index can't see them. Documented (correctly) in the relevant guides.
|
||||
"COPILOT_PROVIDER_BASE_URL", // GitHub Copilot CLI ≥v1.0.19's own env var (AGENTBRIDGE.md)
|
||||
"OPENAI_BASE_URL", // env var OmniRoute passes to downstream CLIs (AGENT_PROTOCOLS_GUIDE.md)
|
||||
"NINEROUTER_API_KEY", // injected into the 9router subprocess at spawn (EMBEDDED-SERVICES.md)
|
||||
"CLAUDE_CODE_MAX_OUTPUT_TOKENS", // Claude Code CLI's own env var (CODEX-CLI-CONFIGURATION.md)
|
||||
"CODEX_HOME", // Codex CLI's own config-home env var (CODEX-CLI-CONFIGURATION.md)
|
||||
"OPENAI_API_BASE", // legacy OpenAI base-URL env var some downstream tools (e.g. Aider) read (CLI-INTEGRATIONS.md)
|
||||
"PROMPTFOO_PROVIDER_KEY", // promptfoo's own provider-key env var, used by the red-team suite (GUARDRAILS.md)
|
||||
"REDIS_PORT", // docker-compose host-port override (DOCKER_GUIDE.md)
|
||||
"AUTO_UPDATE_HOST_REPO_DIR", // docker-compose self-update mount (DOCKER_GUIDE.md)
|
||||
"LINUX_GPG_KEY", // electron AppImage signing key, CI/build only (ELECTRON_GUIDE.md)
|
||||
"BRANCH_LOCK_TOKEN", // release branch-protection ops token (QUALITY_GATE_PLAYBOOK.md)
|
||||
"NEXT_LOCALE", // next-intl locale cookie name (I18N.md)
|
||||
]);
|
||||
|
||||
// Common pluralized / column-header all-caps that aren't env vars
|
||||
const ENV_VAR_DENYLIST = new Set([
|
||||
"API_DOCS",
|
||||
"API_REFERENCE",
|
||||
"API_GUIDE",
|
||||
"PROVIDERS",
|
||||
"FREE_TIERS",
|
||||
"CHANGELOG",
|
||||
"CONTRIBUTING",
|
||||
"ARCHITECTURE",
|
||||
"CODEBASE_DOCUMENTATION",
|
||||
"REPOSITORY_MAP",
|
||||
"AUTHZ_GUIDE",
|
||||
"RESILIENCE_GUIDE",
|
||||
"COMPRESSION_GUIDE",
|
||||
"MCP_SERVER",
|
||||
"MCP_AUDIT",
|
||||
"MCP_TOOLS",
|
||||
"MCP_SCOPES",
|
||||
"BUILTIN_EVENTS",
|
||||
"LIFECYCLE_HOOKS",
|
||||
"OBSERVABILITY",
|
||||
"TELEMETRY",
|
||||
"TRACING",
|
||||
"METRICS",
|
||||
"WEB_COOKIE_PROVIDERS",
|
||||
"WEB_SEARCH",
|
||||
"WEB_FETCH",
|
||||
"WEB_SOCKET",
|
||||
"WEBSOCKET",
|
||||
"WEBHOOKS",
|
||||
"WEBHOOK_EVENTS",
|
||||
"GUARDRAILS",
|
||||
"PROVIDER_NODES",
|
||||
"PROVIDER_NODES_VALIDATE",
|
||||
"PROVIDER_HEALTH_AUTOPILOT",
|
||||
"PROVIDER_HEALTH_MATRIX",
|
||||
"PROVIDER_HEALTH_PROBE",
|
||||
"PROVIDER_HEALTH_HISTORY",
|
||||
"PROVIDER_QUOTA_WINDOWS",
|
||||
"PROVIDER_STATS",
|
||||
"PROVIDER_MODELS",
|
||||
"PROVIDER_TYPE",
|
||||
"PROVIDER_CREDENTIALS",
|
||||
"PROVIDER_BULK",
|
||||
"PROVIDER_VALIDATE",
|
||||
"PROVIDER_TEST_BATCH",
|
||||
"PROVIDER_TEST_ALL",
|
||||
"PROVIDER_BULK_WEB_SESSION",
|
||||
"PROVIDER_EXPIRATION",
|
||||
"FREE_PROVIDERS",
|
||||
"FREE_PROXIES",
|
||||
"PROXY_POOLS",
|
||||
"ONE_PROXY",
|
||||
"ONE_PROXY_FETCH",
|
||||
"ONE_PROXY_STATS",
|
||||
"ONE_PROXY_ROTATE",
|
||||
"PROXY_FALLBACK",
|
||||
"PROXY_HEALTH",
|
||||
"PROXY_STATS",
|
||||
"PROXY_MARKETPLACE",
|
||||
"PROVIDER_REGISTRY",
|
||||
"PROVIDER_CATALOG",
|
||||
"PROVIDER_COST",
|
||||
"PROVIDER_LIMITS",
|
||||
"PROVIDER_CONFIG",
|
||||
"PROVIDER_CONNECTION",
|
||||
"PROVIDER_CONNECTIONS",
|
||||
"PROVIDER_REFRESH",
|
||||
"PROVIDER_SYNC_MODELS",
|
||||
"PROVIDER_TEST",
|
||||
"PROVIDER_TESTS",
|
||||
"PROVIDER_FETCH",
|
||||
"PROVIDER_IMPORT",
|
||||
"PROVIDER_EXPORT",
|
||||
"PROVIDER_LIST",
|
||||
"PROVIDER_ADD",
|
||||
"PROVIDER_REMOVE",
|
||||
"PROVIDER_CREATE",
|
||||
"PROVIDER_UPDATE",
|
||||
"PROVIDER_DELETE",
|
||||
"PROVIDER_DISABLE",
|
||||
"PROVIDER_ENABLE",
|
||||
"PROVIDER_RESET",
|
||||
"PROVIDER_RUN",
|
||||
"PROVIDER_GET",
|
||||
"PROVIDER_SET",
|
||||
"PROVIDER_REVOKE",
|
||||
"MODEL_REGISTRY",
|
||||
"MODEL_COMBO_MAPPINGS",
|
||||
"MODEL_ALIASES",
|
||||
"COMBO_TARGETS",
|
||||
"COMBO_HEALTH",
|
||||
"COMBO_DEFAULTS",
|
||||
"COMBO_FORECAST",
|
||||
"COMBO_SCORING",
|
||||
"COMBO_INSPECTOR",
|
||||
"RATE_LIMITS",
|
||||
"RATE_LIMIT_CONFIG",
|
||||
"TASK_FACTORY",
|
||||
"TASK_MANAGER",
|
||||
"AGENT_BASE",
|
||||
"AGENT_BUILDER",
|
||||
"AGENT_SKILL",
|
||||
"AGENT_SKILLS",
|
||||
"AGENT_BRIDGE",
|
||||
"MENU_ITEM",
|
||||
"MENU_ITEMS",
|
||||
"MENU_ICON",
|
||||
"MENU_ICONS",
|
||||
"FAVICON",
|
||||
"FEATURE_FLAG",
|
||||
"FEATURE_FLAGS",
|
||||
"VERSION_MANAGER",
|
||||
"VM_DEPLOY",
|
||||
"VPS_DEPLOY",
|
||||
"I18N_CONFIG",
|
||||
"I18N_LOCALES",
|
||||
"PROXY_GUIDE",
|
||||
"OPENAPI_SPEC",
|
||||
"OPENAPI_GUIDE",
|
||||
"WAF_RULES",
|
||||
"WAF_BYPASS",
|
||||
"WAF_PROTECTION",
|
||||
"SOCIAL_OAUTH",
|
||||
"OAUTH_FLOWS",
|
||||
"OAUTH_TOKENS",
|
||||
"STORAGE_BACKEND",
|
||||
"STORAGE_HEALTH",
|
||||
"DATABASE_SETTINGS",
|
||||
"TUNNELS",
|
||||
"TUNNEL_CLOUDFLARED",
|
||||
"TUNNEL_NGROK",
|
||||
"TUNNEL_TAILSCALE",
|
||||
"PRICING_CATALOG",
|
||||
"PRICING_SYNC",
|
||||
"PRICING_DEFAULTS",
|
||||
"USAGE_ANALYTICS",
|
||||
"USAGE_QUOTA",
|
||||
"USAGE_BUDGET",
|
||||
"QUOTA_SNAPSHOT",
|
||||
"QUOTA_SNAPSHOTS",
|
||||
"QUOTA_POOL",
|
||||
"QUOTA_POOLS",
|
||||
"QUOTA_PLAN",
|
||||
"QUOTA_PLANS",
|
||||
"QUOTA_MONITOR",
|
||||
"QUOTA_MONITORS",
|
||||
"DOMAIN_BUDGET",
|
||||
"DOMAIN_BUDGETS",
|
||||
"DOMAIN_COST",
|
||||
"DOMAIN_COSTS",
|
||||
"DOMAIN_FALLBACK",
|
||||
"DOMAIN_FALLBACKS",
|
||||
"DOMAIN_LOCKOUT",
|
||||
"DOMAIN_LOCKOUTS",
|
||||
"DOMAIN_CIRCUIT",
|
||||
"DOMAIN_CIRCUITS",
|
||||
"DOMAIN_RESET",
|
||||
"DOMAIN_RESETS",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_ACTIONS",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_HISTORY",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_STATS",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_CONFIG",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_INTERVAL",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_TIMEOUT",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_THRESHOLD",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_COOLDOWN",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_TIMEOUT",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_THRESHOLD",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_COOLDOWN",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_MAX",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_MIN",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_BASE",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_FACTOR",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_JITTER",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_THRESHOLD",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_LIMIT",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_FLOOR",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_CEILING",
|
||||
"PROVIDER_HEALTH_AUTOPILOT_RECOVERY_RETRY_BACKOFF_CAP",
|
||||
// Gate allowlist constant names (JS identifiers, not env vars) — documented in
|
||||
// docs/architecture/QUALITY_GATES.md and docs/research/DISCOVERY_TOOL_DESIGN.md
|
||||
"KNOWN_STALE_DOC_REFS", // export const in check-docs-symbols.mjs
|
||||
"KNOWN_MISSING", // export const in check-fetch-targets.mjs
|
||||
"KNOWN_RAW_SQL", // export const in check-db-rules.mjs
|
||||
"ROUTER_BACKENDS", // typed router-backend registry constant documented in the ADR (ROUTER_BACKENDS.md); code lands with PR #5868 (#5798)
|
||||
// ── Error / Node codes documented in prose (string-literal codes, not env vars) ──
|
||||
"URL_GUARD_BLOCKED", // HTTP 422 guard-violation code (ARCHITECTURE.md)
|
||||
"AUTHZ_NOT_INITIALIZED", // AuthzAssertionError code (AUTHZ_GUIDE.md)
|
||||
"MODULE_NOT_FOUND", // Node runtime error code watched by service supervisor (ELECTRON_GUIDE.md)
|
||||
"ERR_DLOPEN_FAILED", // Node native-module load error code (ELECTRON_GUIDE.md)
|
||||
// ── Code-symbol / naming-convention examples documented in prose ─────────────
|
||||
"UPPER_SNAKE", // the literal naming-convention token in the style guide (CODEBASE_DOCUMENTATION.md)
|
||||
"DEFAULT_TIMEOUT", // example constant name in the UPPER_SNAKE convention row (AGENTS.md)
|
||||
"SIDEBAR_DEFINITIONS", // code constant referenced in prose (MONITORING_SECTIONS.md)
|
||||
"LOCAL_ONLY", // routeGuard classification label (AGENTBRIDGE.md)
|
||||
"SPAWN_CAPABLE", // routeGuard classification label (AGENTBRIDGE.md)
|
||||
"ZEROGRAVITY_SENSITIVE_WORDS", // cross-project constant named in a comparison (STEALTH_GUIDE.md)
|
||||
]);
|
||||
|
||||
/** Endpoints that don't follow the standard route.ts pattern. */
|
||||
const ENDPOINT_ALLOWLIST = new Set([
|
||||
"/api/v1/models",
|
||||
"/api/v1/chat/completions",
|
||||
"/api/v1/embeddings",
|
||||
"/api/v1/responses",
|
||||
"/api/v1/images/generations",
|
||||
"/api/v1/audio/transcriptions",
|
||||
"/api/v1/audio/speech",
|
||||
"/api/v1/videos/generations",
|
||||
"/api/v1/music/generations",
|
||||
"/api/v1/moderations",
|
||||
"/api/v1/rerank",
|
||||
"/api/v1/search",
|
||||
"/api/v1/messages",
|
||||
"/api/v1/agents/tasks",
|
||||
"/api/v1/agents/tasks/{id}",
|
||||
"/api/v1/agents/credentials",
|
||||
"/api/v1/agents/health",
|
||||
"/.well-known/agent.json",
|
||||
"/v1/models",
|
||||
"/v1/chat/completions",
|
||||
"/v1/embeddings",
|
||||
"/v1/responses",
|
||||
"/v1/ws", // WebSocket bridge, not standard route.ts
|
||||
"/a2a", // JSON-RPC 2.0 entry
|
||||
"/api/mcp/stream", // Streamable HTTP MCP transport
|
||||
"/api/mcp/sse", // SSE MCP transport
|
||||
"/api/health",
|
||||
// Upstream/external provider endpoints documented in provider guides — these are
|
||||
// paths on the UPSTREAM service (Claude.ai web, Blackbox), not OmniRoute routes.
|
||||
"/api/organizations/{orgId}/chat_conversations/{convId}/completion", // claude-web upstream
|
||||
"/api/chat", // Blackbox Web upstream (validated-token target)
|
||||
]);
|
||||
|
||||
/** Doc files to skip (auto-generated, vendored, or third-party). */
|
||||
const SKIP_DOC_FILES = new Set([
|
||||
"docs/reference/PROVIDER_REFERENCE.md", // auto-generated from providers.ts
|
||||
"docs/openapi.yaml",
|
||||
"docs/i18n", // translations — separate workflow
|
||||
// Design / research / plan docs: by definition describe not-yet-built files and
|
||||
// proposed (not-yet-shipped) endpoints (each carries a `Status: Design`/`Active
|
||||
// research`/`Plano` header). Same rationale as the audit report above — these are
|
||||
// forward-looking specs, not living API docs, so their forward references are
|
||||
// expected, not fabrications.
|
||||
"docs/research", // DISCOVERY_TOOL_DESIGN.md, UNLIMITED_LLM_ACCESS.md, …
|
||||
"docs/superpowers/plans", // dated implementation plans (files described before they exist)
|
||||
"docs/superpowers/specs", // dated research/spec reports (point-in-time findings, may cite proposed/not-yet-built endpoints, env vars, and files) — same rationale as the plans/research dirs above
|
||||
// Release notes are historical, point-in-time records: they intentionally describe
|
||||
// modules/paths as they were at that release (e.g. a module later moved or renamed).
|
||||
// Rewriting them to today's layout would falsify history — out of scope for a
|
||||
// living-docs accuracy gate.
|
||||
"docs/releases",
|
||||
// Forward-looking coverage plan: a `- [ ]` checklist of test targets and helper
|
||||
// components to be created. Same rationale as the design/plan docs above.
|
||||
"docs/ops/COVERAGE_PLAN.md",
|
||||
]);
|
||||
|
||||
// ── File discovery ─────────────────────────────────────────────────────────
|
||||
|
||||
function walkMarkdown(dir, out = [], root = ROOT) {
|
||||
const abs = path.join(root, dir);
|
||||
if (!fs.existsSync(abs)) return out;
|
||||
const stat = fs.statSync(abs);
|
||||
if (stat.isFile()) {
|
||||
if (abs.endsWith(".md") || abs.endsWith(".mdx")) out.push(abs);
|
||||
return out;
|
||||
}
|
||||
for (const name of fs.readdirSync(abs)) {
|
||||
if (name === "node_modules" || name.startsWith(".")) continue;
|
||||
const childAbs = path.join(abs, name);
|
||||
const s = fs.statSync(childAbs);
|
||||
if (s.isDirectory()) walkMarkdown(path.relative(root, childAbs), out, root);
|
||||
else if (childAbs.endsWith(".md") || childAbs.endsWith(".mdx")) out.push(childAbs);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function allScanFiles(root = ROOT) {
|
||||
const files = [];
|
||||
for (const p of SCAN_PATHS) walkMarkdown(p, files, root);
|
||||
return files.filter((f) => {
|
||||
const rel = path.relative(root, f);
|
||||
for (const skip of SKIP_DOC_FILES) {
|
||||
if (rel === skip || rel.startsWith(skip + path.sep)) return false;
|
||||
}
|
||||
return true;
|
||||
});
|
||||
}
|
||||
|
||||
// ── Codebase index ─────────────────────────────────────────────────────────
|
||||
|
||||
// Env var helper wrappers used across OmniRoute — envInt(NAME, 5), envBool(NAME),
|
||||
// envStr(NAME), … — read the named var from the environment, so a string-literal
|
||||
// argument is a genuine env-var read, equivalent to a direct process.env member read.
|
||||
// (Comment avoids a literal `process.env.<NAME>` token so the sibling env-doc-sync
|
||||
// grep does not mistake this example for a real env-var read.)
|
||||
const ENV_HELPER_CALL =
|
||||
/\benv(?:Int|Bool|Str|Num|Float|String|Flag|Raw|List|Json)?\(\s*["'`]([A-Z][A-Z0-9_]+)["'`]/g;
|
||||
|
||||
export function buildCodebaseIndex(root = ROOT) {
|
||||
// Set of /api/... paths that have a route.ts handler.
|
||||
const apiRoutes = new Set();
|
||||
// Set of /api/... prefixes that are an ancestor of (or equal to) a real route.ts.
|
||||
// A documented prefix like /api/cloud/ is valid even without a route.ts at that
|
||||
// exact level, as long as some src/app/api/cloud/**/route.ts exists.
|
||||
const apiPrefixes = new Set();
|
||||
// Map of /api/... → methods implemented in route.ts
|
||||
const apiMethods = new Map();
|
||||
|
||||
function dynToBrace(seg) {
|
||||
// [id] → {id}, [...path] → {path} — match the doc convention for dynamic segments.
|
||||
return seg.replace(/^\[\.\.\.(.+)\]$/, "{$1}").replace(/^\[(.+)\]$/, "{$1}");
|
||||
}
|
||||
|
||||
function walkApiRoutes(dir) {
|
||||
const abs = path.join(root, dir);
|
||||
if (!fs.existsSync(abs)) return;
|
||||
for (const name of fs.readdirSync(abs)) {
|
||||
const child = path.join(abs, name);
|
||||
const s = fs.statSync(child);
|
||||
if (s.isDirectory()) walkApiRoutes(path.relative(root, child));
|
||||
else if (name === "route.ts" || name === "route.mjs") {
|
||||
// Build the route path from the directory hierarchy
|
||||
const rel = path.relative(root, child).replace(/\\/g, "/");
|
||||
const parts = rel.split("/");
|
||||
// drop "src/app/api" and "route.ts"
|
||||
parts.shift(); // src
|
||||
parts.shift(); // app
|
||||
parts.shift(); // api
|
||||
parts.pop(); // route.ts
|
||||
const routePath = "/api/" + parts.join("/");
|
||||
apiRoutes.add(routePath);
|
||||
apiRoutes.add(routePath + "/"); // trailing slash variant
|
||||
|
||||
// Register every ancestor prefix (and its {brace} dynamic-segment variant)
|
||||
// so documented prefixes-with-subroutes resolve.
|
||||
for (let i = 1; i <= parts.length; i++) {
|
||||
const prefix = "/api/" + parts.slice(0, i).join("/");
|
||||
const bracePrefix = "/api/" + parts.slice(0, i).map(dynToBrace).join("/");
|
||||
apiPrefixes.add(prefix);
|
||||
apiPrefixes.add(bracePrefix);
|
||||
}
|
||||
|
||||
// Read the file to find exported HTTP methods
|
||||
try {
|
||||
const content = fs.readFileSync(child, "utf8");
|
||||
const methods = new Set();
|
||||
for (const m of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
|
||||
const re = new RegExp(`export\\s+(?:async\\s+)?function\\s+${m}\\b`);
|
||||
if (re.test(content)) methods.add(m);
|
||||
const re2 = new RegExp(`export\\s+const\\s+${m}\\b`);
|
||||
if (re2.test(content)) methods.add(m);
|
||||
}
|
||||
if (methods.size > 0) apiMethods.set(routePath, methods);
|
||||
} catch {
|
||||
/* ignore read errors */
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
walkApiRoutes("src/app/api");
|
||||
|
||||
// Set of env var names that are actually read in code, and the set of
|
||||
// ALL_CAPS code identifiers (export const / enum / object-literal keys). A
|
||||
// documented `UPPER_SNAKE` that resolves to a code identifier (e.g.
|
||||
// LOCAL_ONLY_API_PREFIXES, HALF_OPEN) is NOT a fabricated env var.
|
||||
const envVars = new Set();
|
||||
const codeIdentifiers = new Set();
|
||||
function walkForEnv(dir) {
|
||||
const abs = path.join(root, dir);
|
||||
if (!fs.existsSync(abs)) return;
|
||||
const skipDirs = new Set(["node_modules", ".next", "dist", ".build", "coverage"]);
|
||||
for (const name of fs.readdirSync(abs)) {
|
||||
if (skipDirs.has(name)) continue;
|
||||
const child = path.join(abs, name);
|
||||
const s = fs.statSync(child);
|
||||
if (s.isDirectory()) walkForEnv(path.relative(root, child));
|
||||
else if (/\.(ts|tsx|js|mjs|cjs)$/.test(name)) {
|
||||
try {
|
||||
const content = fs.readFileSync(child, "utf8");
|
||||
// process.env.X
|
||||
for (const m of content.matchAll(/process\.env\.([A-Z][A-Z0-9_]+)/g)) envVars.add(m[1]);
|
||||
// process.env["X"] / process.env['X'] (bracket notation)
|
||||
for (const m of content.matchAll(/process\.env\[\s*["'`]([A-Z][A-Z0-9_]+)["'`]\s*\]/g))
|
||||
envVars.add(m[1]);
|
||||
// env.X (destructured in some handlers)
|
||||
for (const m of content.matchAll(/\benv\.([A-Z][A-Z0-9_]+)\b/g)) envVars.add(m[1]);
|
||||
// env["X"] (bracket on a destructured env binding)
|
||||
for (const m of content.matchAll(/\benv\[\s*["'`]([A-Z][A-Z0-9_]+)["'`]\s*\]/g))
|
||||
envVars.add(m[1]);
|
||||
// envInt("X", …) / envBool("X") / envStr("X") … helper wrappers
|
||||
for (const m of content.matchAll(ENV_HELPER_CALL)) envVars.add(m[1]);
|
||||
// import.meta.env.X (Vite-style, unlikely here but cheap)
|
||||
for (const m of content.matchAll(/import\.meta\.env\.([A-Z][A-Z0-9_]+)/g))
|
||||
envVars.add(m[1]);
|
||||
// export const / const / let / var / enum NAME — JS identifiers, not env vars.
|
||||
for (const m of content.matchAll(
|
||||
/\b(?:export\s+)?(?:const|let|var|enum)\s+([A-Z][A-Z0-9_]{2,})\b/g
|
||||
))
|
||||
codeIdentifiers.add(m[1]);
|
||||
// Object-literal / enum members on their own line: `HALF_OPEN: "HALF_OPEN"`.
|
||||
for (const m of content.matchAll(/^[ \t]*([A-Z][A-Z0-9_]{2,})[ \t]*[:=]/gm))
|
||||
codeIdentifiers.add(m[1]);
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
walkForEnv("src");
|
||||
walkForEnv("open-sse");
|
||||
walkForEnv("bin");
|
||||
walkForEnv("scripts");
|
||||
// Env vars that are only read by the test harness (e.g. RUN_CHAOS_INT) are still
|
||||
// real env vars and must not be flagged as fabricated.
|
||||
walkForEnv("tests");
|
||||
|
||||
// Env contract maintained by the sibling gate (check-env-doc-sync.mjs): a var
|
||||
// listed in .env.example or docs/reference/ENVIRONMENT.md is, by definition, a
|
||||
// documented OmniRoute env var (including external-CLI / docker / electron vars
|
||||
// that are not read via process.env in our own source).
|
||||
function readEnvContract() {
|
||||
try {
|
||||
const t = fs.readFileSync(path.join(root, ".env.example"), "utf8");
|
||||
for (const line of t.split("\n")) {
|
||||
const m = line.match(/^#?\s*([A-Z][A-Z0-9_]+)\s*=/);
|
||||
if (m) envVars.add(m[1]);
|
||||
}
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
try {
|
||||
const t = fs.readFileSync(path.join(root, "docs", "reference", "ENVIRONMENT.md"), "utf8");
|
||||
for (const m of t.matchAll(/`([A-Z][A-Z0-9_]{2,})`/g)) envVars.add(m[1]);
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
readEnvContract();
|
||||
|
||||
// Set of `omniroute <subcommand>` strings that exist in bin/
|
||||
const cliCommands = new Set();
|
||||
function walkCli(dir) {
|
||||
const abs = path.join(root, dir);
|
||||
if (!fs.existsSync(abs)) return;
|
||||
for (const name of fs.readdirSync(abs)) {
|
||||
const child = path.join(abs, name);
|
||||
const s = fs.statSync(child);
|
||||
if (s.isDirectory()) walkCli(path.relative(root, child));
|
||||
else if (/\.(mjs|js|ts)$/.test(name)) {
|
||||
try {
|
||||
const content = fs.readFileSync(child, "utf8");
|
||||
// Programmatic API: `command('foo', ...)`, `.command('bar')`, and
|
||||
// arg-bearing forms `.command('connect <host>')` / `.command('chat [msg]')`
|
||||
// — capture the leading subcommand token regardless of trailing args.
|
||||
const m1 = content.matchAll(/\.command\(\s*['"`]([a-z][a-z0-9-]+)/g);
|
||||
for (const m of m1) cliCommands.add(m[1]);
|
||||
// Subcommand names: `${name}Cmd`, `name = "foo"`, etc.
|
||||
const m2 = content.matchAll(/name:\s*['"`]([a-z][a-z0-9-]+)['"`]/g);
|
||||
for (const m of m2) cliCommands.add(m[1]);
|
||||
// `.name('foo')` (commander pattern)
|
||||
const m3 = content.matchAll(/\.name\(\s*['"`]([a-z][a-z0-9-]+)['"`]\s*\)/g);
|
||||
for (const m of m3) cliCommands.add(m[1]);
|
||||
} catch {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
walkCli("bin");
|
||||
|
||||
return { apiRoutes, apiPrefixes, apiMethods, envVars, codeIdentifiers, cliCommands };
|
||||
}
|
||||
|
||||
// ── Doc scanning ───────────────────────────────────────────────────────────
|
||||
|
||||
const COARSE_PATTERNS = {
|
||||
apiPath: /(?<!\w)\/api\/[A-Za-z0-9_\-\/\[\]\{\}]+(?!\w)/g,
|
||||
// Catches ALL_CAPS env var names of length >= 3
|
||||
envVar: /\b([A-Z][A-Z0-9_]{2,})\b/g,
|
||||
// omniroute <verb> <sub> ... — only on the same line, captures first 2 tokens
|
||||
cliCmd: /\bomniroute\s+([a-z][a-z0-9-]+)(?:\s+([a-z][a-z0-9-]+))?/g,
|
||||
// Built-in event names like onRequest, onFoo
|
||||
hookName: /\b(on[A-Z][a-zA-Z]+)\b/g,
|
||||
// File references like src/lib/foo.ts, open-sse/handlers/bar.ts, bin/cli/baz.mjs
|
||||
fileRef:
|
||||
/\b((?:src|open-sse|bin|scripts|tests|electron)\/[A-Za-z0-9_\-\/\.]+\.(?:ts|tsx|mjs|js|cjs|sh|sql))\b/g,
|
||||
};
|
||||
|
||||
function stripCodeBlocksAndFences(text) {
|
||||
// Remove fenced code blocks (``` ... ```) but KEEP inline backticks so
|
||||
// we can still detect `BACKTICKED_LIKE_THIS` env-var/hook/CLI claims.
|
||||
return text.replace(/```[\s\S]*?```/g, "");
|
||||
}
|
||||
|
||||
function lineOf(text, idx) {
|
||||
let line = 1;
|
||||
for (let i = 0; i < idx && i < text.length; i++) if (text[i] === "\n") line++;
|
||||
return line;
|
||||
}
|
||||
|
||||
export function scanDocFile(absPath, index, root = ROOT) {
|
||||
const rel = path.relative(root, absPath);
|
||||
const text = fs.readFileSync(absPath, "utf8");
|
||||
const textNoCode = stripCodeBlocksAndFences(text);
|
||||
const findings = [];
|
||||
|
||||
// 1) API endpoints
|
||||
for (const m of textNoCode.matchAll(COARSE_PATTERNS.apiPath)) {
|
||||
// Normalize wildcard segments to {brace} form so [id] / [...path] / {id} all
|
||||
// compare equally against the indexed routes/prefixes.
|
||||
const normalized = m[0].replace(/\[\.\.\.(.+?)\]/g, "{$1}").replace(/\[(.+?)\]/g, "{$1}");
|
||||
const candidate = normalized.replace(/\/$/, "");
|
||||
const stripped = m[0].replace(/[\[\]\{\}]/g, "").replace(/\/$/, ""); // legacy lookup form
|
||||
if (
|
||||
ENDPOINT_ALLOWLIST.has(candidate) ||
|
||||
ENDPOINT_ALLOWLIST.has(candidate + "/") ||
|
||||
ENDPOINT_ALLOWLIST.has(stripped) ||
|
||||
ENDPOINT_ALLOWLIST.has(stripped + "/")
|
||||
)
|
||||
continue;
|
||||
if (
|
||||
index.apiRoutes.has(stripped) ||
|
||||
index.apiRoutes.has(stripped + "/") ||
|
||||
index.apiRoutes.has(candidate) ||
|
||||
index.apiRoutes.has(candidate + "/")
|
||||
)
|
||||
continue;
|
||||
// Prefix-with-subroutes: a documented prefix like /api/cloud/ or /api/services/{name}/
|
||||
// is valid when some src/app/api/<prefix>/**/route.ts exists. Accept when the
|
||||
// documented path is (or is an ancestor of) a real route prefix, or vice-versa.
|
||||
let isPrefix = false;
|
||||
for (const pre of index.apiPrefixes) {
|
||||
if (pre === candidate || pre.startsWith(candidate + "/") || candidate.startsWith(pre + "/")) {
|
||||
isPrefix = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (isPrefix) continue;
|
||||
// Allow docs that describe intended-but-not-yet-shipped routes by skipping lines that say "planned" / "TBD" / "future"
|
||||
const ln = lineOf(text, m.index);
|
||||
const lineText = text.split("\n")[ln - 1] || "";
|
||||
if (/\b(planned|tbd|future|coming|proposed|not yet|will be)\b/i.test(lineText)) continue;
|
||||
findings.push({
|
||||
kind: "api-path",
|
||||
value: m[0],
|
||||
line: ln,
|
||||
msg: `endpoint ${m[0]} not found in src/app/api/`,
|
||||
});
|
||||
}
|
||||
|
||||
// 2) Env vars — only flag names wrapped in backticks AND containing an
|
||||
// underscore. The maintainer's actual fabricated env vars (PR #3456)
|
||||
// were always in `BACKTICKS` inside tables; bare all-caps tokens
|
||||
// inside markdown link display text are doc references, not env vars.
|
||||
// Example of TRUE positive: | `ACP_MAX_CONCURRENT_SESSIONS` | 5 | ... |
|
||||
// Example of false positive: | [STEALTH_GUIDE](security/...) |
|
||||
for (const m of textNoCode.matchAll(/`([A-Z][A-Z0-9_]{4,})`/g)) {
|
||||
const name = m[1];
|
||||
if (ENV_VAR_ALLOWLIST.has(name)) continue;
|
||||
if (!/_/.test(name)) continue; // real env vars have an underscore
|
||||
if (index.envVars.has(name)) continue;
|
||||
// Documented ALL_CAPS that resolves to a JS identifier (export const / enum /
|
||||
// object-literal key) is a code symbol, not a fabricated env var.
|
||||
// E.g. LOCAL_ONLY_API_PREFIXES, HALF_OPEN, A2A_SKILL_HANDLERS, MCP_SCOPE_PRESETS.
|
||||
if (index.codeIdentifiers.has(name)) continue;
|
||||
if (/^X-[A-Z]/.test(name)) continue;
|
||||
if (ENV_VAR_DENYLIST.has(name)) continue;
|
||||
const ln = lineOf(text, m.index);
|
||||
// Use the line as seen in the stripped text (where m.index is valid) for context
|
||||
// checks — fenced-code removal shifts offsets, so text.split()[ln-1] can be wrong.
|
||||
const lineStart = textNoCode.lastIndexOf("\n", m.index) + 1;
|
||||
let lineEnd = textNoCode.indexOf("\n", m.index);
|
||||
if (lineEnd === -1) lineEnd = textNoCode.length;
|
||||
const lineText = textNoCode.slice(lineStart, lineEnd);
|
||||
if (/example|placeholder|todo|tbd|\.\.\./i.test(lineText)) continue;
|
||||
// A doc that explicitly states a var does NOT exist / is not implemented is
|
||||
// documenting its absence, not fabricating it. Examples:
|
||||
// "`MEMORY_RRF_VECTOR_WEIGHT` … do not exist"
|
||||
// "a `ZED_CONFIG_PATH` environment variable override is not yet implemented"
|
||||
if (
|
||||
/\b(?:do(?:es)?\s+not\s+exist|no\s+such|not\s+a\s+real|isn't\s+a\s+real|never\s+(?:read|exists?)|not\s+(?:yet\s+)?(?:implemented|supported))\b/i.test(
|
||||
lineText
|
||||
)
|
||||
)
|
||||
continue;
|
||||
findings.push({
|
||||
kind: "env-var",
|
||||
value: name,
|
||||
line: ln,
|
||||
msg: `env var \`${name}\` is never read via process.env / env / import.meta.env`,
|
||||
});
|
||||
}
|
||||
|
||||
// 3) CLI commands: `omniroute foo bar` — only flag when the line is in
|
||||
// a code-like context (inside backticks or a shell block). Bare prose
|
||||
// like "we use omniroute and..." is not a command claim.
|
||||
for (const m of textNoCode.matchAll(COARSE_PATTERNS.cliCmd)) {
|
||||
const sub = m[1];
|
||||
if (index.cliCommands.has(sub)) continue;
|
||||
if (["help", "--help", "-h", "version", "--version", "doctor", "setup", "chat"].includes(sub))
|
||||
continue;
|
||||
const ln = lineOf(text, m.index);
|
||||
const lineText = text.split("\n")[ln - 1] || "";
|
||||
// Only flag when on a line that looks like a shell command (starts with $, or
|
||||
// inside a shell block, or wrapped in `code`)
|
||||
const isShellLike = /^[ \t]*\$\s|^```sh|^```bash|^```shell|`omniroute/.test(lineText);
|
||||
if (!isShellLike) continue;
|
||||
if (/example|placeholder|tbd/i.test(lineText)) continue;
|
||||
findings.push({
|
||||
kind: "cli-cmd",
|
||||
value: `omniroute ${sub}`,
|
||||
line: ln,
|
||||
msg: `omniroute subcommand '${sub}' not registered in bin/`,
|
||||
});
|
||||
}
|
||||
|
||||
// 4) Hook names — only flag when wrapped in backticks/code, since bare
|
||||
// "onFoo" prose is common English.
|
||||
for (const m of textNoCode.matchAll(/`?(on[A-Z][a-zA-Z]+)`?/g)) {
|
||||
const name = m[1];
|
||||
if (KNOWN_HOOKS.has(name)) continue;
|
||||
// Require backticks to reduce noise (text mentions are usually casual)
|
||||
if (!m[0].startsWith("`")) continue;
|
||||
const ln = lineOf(text, m.index);
|
||||
const lineText = text.split("\n")[ln - 1] || "";
|
||||
if (/example|placeholder|tbd/i.test(lineText)) continue;
|
||||
findings.push({
|
||||
kind: "hook",
|
||||
value: name,
|
||||
line: ln,
|
||||
msg: `hook ${name} not in BUILTIN_EVENTS (hooks.ts) — is this a real hook?`,
|
||||
});
|
||||
}
|
||||
|
||||
// 5) File references
|
||||
for (const m of textNoCode.matchAll(COARSE_PATTERNS.fileRef)) {
|
||||
const ref = m[1].replace(/\\/g, "/");
|
||||
const abs = path.join(root, ref);
|
||||
if (fs.existsSync(abs)) continue;
|
||||
// Allow README/AGENTS to mention example files explicitly in a non-verified way
|
||||
if (/\{\{|\.\.\./.test(ref)) continue; // templated / placeholder
|
||||
// Tutorial placeholders in the "how to add a …" scenarios are intentional
|
||||
// stand-ins, not real files: src/app/api/your-route/route.ts,
|
||||
// src/lib/db/yourModule.ts, src/lib/guardrails/myGuardrail.ts, etc.
|
||||
if (/(?:^|\/)(?:your-|your[A-Z]|my[A-Z])/.test(ref)) continue;
|
||||
// Skip matches that are only the tail of a longer path, not a repo-root ref:
|
||||
// the fileRef regex anchors on the `src`/`open-sse`/… token, so a leading `/`
|
||||
// means the real reference is `<something>/src/...` — either a relative example
|
||||
// path (`./src/index.ts`, a PII-pattern sample) or a workspace-package path
|
||||
// (`@omniroute/opencode-provider/src/index.ts`). Neither resolves from repo root.
|
||||
if (m.index > 0 && textNoCode[m.index - 1] === "/") continue;
|
||||
const ln = lineOf(text, m.index);
|
||||
findings.push({
|
||||
kind: "file-ref",
|
||||
value: ref,
|
||||
line: ln,
|
||||
msg: `file ${ref} does not exist`,
|
||||
});
|
||||
}
|
||||
|
||||
return { rel, findings };
|
||||
}
|
||||
|
||||
// ── Main ───────────────────────────────────────────────────────────────────
|
||||
|
||||
export function runFabricatedDocsCheck(opts = {}) {
|
||||
// `root` lets tests run the full pipeline against a fixture tree (with its own
|
||||
// docs/, src/, .env.example) instead of the live repo.
|
||||
const root = opts.root ?? ROOT;
|
||||
const index = opts.index ?? buildCodebaseIndex(root);
|
||||
const files = allScanFiles(root);
|
||||
|
||||
const allFindings = [];
|
||||
for (const f of files) {
|
||||
const result = scanDocFile(f, index, root);
|
||||
if (result.findings.length > 0) {
|
||||
allFindings.push(result);
|
||||
}
|
||||
}
|
||||
|
||||
const totalFindings = allFindings.reduce((acc, r) => acc + r.findings.length, 0);
|
||||
return { totalFindings, files: allFindings, fileCount: files.length, index };
|
||||
}
|
||||
|
||||
export function formatHumanReport(result) {
|
||||
const { totalFindings, files, fileCount, index } = result;
|
||||
const lines = [];
|
||||
lines.push("Doc accuracy gate — fabricated-claim detection");
|
||||
lines.push("================================================");
|
||||
lines.push(`Scanned ${fileCount} markdown file(s)`);
|
||||
lines.push(
|
||||
`Codebase: ${index.apiRoutes.size} api routes · ${index.envVars.size} env vars · ${index.cliCommands.size} cli commands`
|
||||
);
|
||||
lines.push("");
|
||||
|
||||
if (totalFindings === 0) {
|
||||
lines.push("✓ No fabricated API/env/CLI/hook/file references found.");
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
// Dedupe identical findings across files (report once, with file list)
|
||||
const deduped = new Map();
|
||||
for (const r of files) {
|
||||
for (const f of r.findings) {
|
||||
const key = `${f.kind}::${f.value}::${f.msg}`;
|
||||
if (!deduped.has(key)) deduped.set(key, { ...f, files: new Set() });
|
||||
deduped.get(key).files.add(r.rel);
|
||||
}
|
||||
}
|
||||
|
||||
const groups = { "api-path": [], "env-var": [], "cli-cmd": [], hook: [], "file-ref": [] };
|
||||
for (const f of deduped.values()) groups[f.kind].push(f);
|
||||
|
||||
const KIND_LABELS = {
|
||||
"api-path": "API endpoint paths not in src/app/api/",
|
||||
"env-var": "Env vars never read in code",
|
||||
"cli-cmd": "omniroute subcommands not registered",
|
||||
hook: "Hook names not in BUILTIN_EVENTS",
|
||||
"file-ref": "File references that don't exist",
|
||||
};
|
||||
|
||||
for (const [kind, items] of Object.entries(groups)) {
|
||||
if (items.length === 0) continue;
|
||||
lines.push(`\n## ${KIND_LABELS[kind]} (${items.length})`);
|
||||
for (const f of items.slice(0, 20)) {
|
||||
const fileList = [...f.files]
|
||||
.slice(0, 3)
|
||||
.map((r) => `${r}:${f.line}`)
|
||||
.join(", ");
|
||||
const more = f.files.size > 3 ? ` (+${f.files.size - 3} more)` : "";
|
||||
lines.push(` • ${f.value.padEnd(40)} ${f.msg}`);
|
||||
lines.push(` ${fileList}${more}`);
|
||||
}
|
||||
if (items.length > 20) lines.push(` ... and ${items.length - 20} more`);
|
||||
}
|
||||
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
// CLI entry — only run when invoked directly (not when imported for tests).
|
||||
const isMain = import.meta.url === `file://${process.argv[1]}`;
|
||||
if (isMain) {
|
||||
main();
|
||||
}
|
||||
|
||||
function main() {
|
||||
const result = runFabricatedDocsCheck();
|
||||
const { totalFindings, files } = result;
|
||||
|
||||
if (JSON_OUT) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
totalFindings,
|
||||
files: files.length,
|
||||
results: files,
|
||||
},
|
||||
null,
|
||||
2
|
||||
)
|
||||
);
|
||||
if (STRICT && totalFindings > 0) process.exit(1);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
console.log(formatHumanReport(result));
|
||||
console.log();
|
||||
if (totalFindings === 0) {
|
||||
// Clean run — pass regardless of mode.
|
||||
process.exit(0);
|
||||
}
|
||||
if (STRICT) {
|
||||
console.error(`✗ ${totalFindings} claim(s) drift from source. Failing (--strict).`);
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.warn(`⚠ ${totalFindings} claim(s) drift from source. Re-run with --strict to fail.`);
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user