diff --git a/CHANGELOG.md b/CHANGELOG.md index c6bdb08acd..db97b358ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ ### ♻️ Code Quality +- **chore(db-gate):** reclassify `KNOWN_UNEXPORTED` → `INTENTIONALLY_INTERNAL` in `scripts/check/check-db-rules.mjs` ([#3499]): a full audit of all 25 db modules confirmed each is consumed via direct/dynamic import per Hard Rule #2 ("Never barrel-import from localDb.ts"). The old framing labelled them as "debt", which was misleading — they are the correct pattern. The gate's blocking behaviour is unchanged (a NEW unexported module still fails); only the name, comments, and per-module justifications were updated to reflect audited truth. Four modules flagged `DEAD?` (`compressionScheduler`, `discovery`, `pluginMetrics`, `prompts`) have zero production importers and are documented as schema-reserved. A new regression-guard test (`tests/unit/check-db-rules-classification.test.ts`) asserts every non-dead module in the set has ≥1 real importer, so a future consumer removal surfaces as a test failure requiring explicit reclassification. + - **Provider-detail god-component decomposition — Phase 0** ([#3501]): introduced `ProviderDetailPageClient.tsx` and reduced `providers/[id]/page.tsx` to a thin 9-line route wrapper (was 12,882 LOC), following the repo's `*PageClient` convention. Added the first-ever smoke render test for the page (Hard Rule #8) as the safety net every later extraction phase is diffed against. Behavior unchanged; the `check-file-size` ratchet now tracks the extracted client. Foundation for Phases 1–6 (strangler-fig). Thanks @oyi77 for the parallel modularization effort in #3627. - **Provider-detail god-component decomposition — Phase 1a** ([#3501]): extracted the three self-contained auth-import modal clusters (Codex/Claude/Gemini `Import*AuthModal` + `Apply*AuthModal` + their co-located helpers, ~2,160 LOC) into `providers/[id]/components/modals/`. `ProviderDetailPageClient.tsx` drops 12,882 → 10,719 LOC. Behavior unchanged (smoke test green; clusters had clean `{ onClose, onSuccess }` / inline-prop interfaces). Co-authored with @oyi77. diff --git a/scripts/check/check-db-rules.mjs b/scripts/check/check-db-rules.mjs index 8c76b2f737..ddb84a2593 100644 --- a/scripts/check/check-db-rules.mjs +++ b/scripts/check/check-db-rules.mjs @@ -21,39 +21,51 @@ const LOCAL_DB = path.join(cwd, "src/lib/localDb.ts"); const API_DIR = path.join(cwd, "src/app/api"); const HANDLERS_DIR = path.join(cwd, "open-sse/handlers"); -// (a) Módulos db/ que NÃO são re-exportados por localDb.ts hoje. Congelados -// para a catraca ficar verde e bloquear QUALQUER módulo novo não re-exportado. -// CADA UM é dívida: ou é consumido por import direto de "@/lib/db/X" (legítimo, -// não precisa de re-export) ou deveria ser re-exportado. NÃO adicione novos aqui -// sem justificativa — esse é o ponto do gate (Hard Rule #2). -const KNOWN_UNEXPORTED = new Set([ - "_rowTypes", // só tipos de linha (sem runtime API), consumido localmente pelos CRUDs F2 - "cleanup", // rotina de manutenção, chamada por jobs/rotas via import direto - "cliToolState", // estado de CLI tools, import direto pelos consumidores - "comboForecast", // previsão de combo, import direto - "commandCodeAuth", // auth de command-code, import direto - "compression", // núcleo de compressão, import direto - "compressionScheduler", // scheduler, import direto - "detailedLogs", // logs detalhados, import direto - "discovery", // discovery de modelos, import direto - "domainState", // estado de domínio/circuit breaker, import direto - "encryption", // util de cripto at-rest, import direto - "healthCheck", // health check de DB, import direto - "jsonMigration", // migração JSON→SQLite (one-shot), import direto - "migrationRunner", // runner de migrations, import direto - "notion", // integração Notion, import direto - "obsidian", // integração Obsidian, import direto - "pluginMetrics", // métricas de plugin, import direto - "prompts", // prompts salvos, import direto - "providerStats", // stats de provider, import direto - "recovery", // recuperação de DB, import direto - "secrets", // secrets store, import direto - "serviceModels", // modelos de serviços embutidos, import direto - "stateReset", // reset de estado de resiliência, import direto - "stats", // agregações de stats, import direto - "tierConfig", // config de tier, import direto +// (a) Módulos db/ que NÃO são re-exportados por localDb.ts por DESIGN (Hard Rule #2: +// "Never barrel-import from localDb.ts — import specific db/ modules instead"). +// Cada entrada aqui foi auditada e é consumida via import direto de "@/lib/db/X" +// (estático ou dinâmico) pelos seus consumidores — exatamente o padrão correto. +// Re-exportar esses módulos via localDb.ts INCENTIVARIA o anti-padrão proibido. +// O gate ainda bloqueia QUALQUER módulo db/ NOVO que não seja re-exportado E não +// esteja nessa lista — mantendo a decisão consciente obrigatória (Hard Rule #2). +// Legenda de classificação: +// type-only = exporta apenas tipos (sem runtime API), não há o que re-exportar +// db-internal = importado apenas dentro de src/lib/db/ (coordenação interna) +// intentionally-internal = consumido por import direto fora de db/ (correto per Rule #2) +// DEAD? = zero importers encontrados na auditoria de 2026-06-11; não deletar +// sem investigação — pode ser reserva de schema ou F2 pendente +export const INTENTIONALLY_INTERNAL = new Set([ + "_rowTypes", // type-only: 5 importers internos em db/ (AgentBridge/Inspector row types) + "cleanup", // intentionally-internal: 3 API routes (purge-quota-snapshots, purge-call-logs, purge-detailed-logs) + "cliToolState", // intentionally-internal: 14+ API routes em /api/cli-tools/*-settings + "comboForecast", // intentionally-internal: src/lib/usage/comboForecast.ts + "commandCodeAuth", // intentionally-internal: 5 API routes em /api/providers/command-code/auth/* + "compression", // intentionally-internal: 2 API routes (settings/compression, context/rtk/config) + "compressionScheduler", // DEAD?: 0 importers na auditoria de 2026-06-11; mantido para schema reservation + "detailedLogs", // intentionally-internal: 3 callers (callLogs.ts, logs/detail route, embeddings handler) + "discovery", // DEAD?: 0 importers na auditoria de 2026-06-11; lib/discovery/index.ts não usa db/discovery + "domainState", // intentionally-internal: 5 callers (batchWriter, circuitBreaker, costRules, fallbackPolicy, lockoutPolicy) + "encryption", // intentionally-internal: 8+ callers (container, webhookDispatcher, cloudAgent/credentials, services/apiKey, 4+ routes, open-sse) + "healthCheck", // db-internal: importado por db/core.ts (runDbHealthCheck) + "jsonMigration", // intentionally-internal: src/app/api/settings/import-json/route.ts + "migrationRunner", // db-internal: importado por db/core.ts (runMigrations ao inicializar o DB) + "notion", // intentionally-internal: settings/notion API route + open-sse/mcp-server/tools/notionTools.ts + "obsidian", // intentionally-internal: src/lib/obsidianSync.ts + settings/obsidian route + MCP obsidianTools.ts + "pluginMetrics", // DEAD? (production): write path não foi conectado ainda (documentado no cabeçalho do módulo); testado por tests/unit/plugins-metrics.test.ts + "prompts", // DEAD? (production): zero callers de produção encontrados; domínio domain/prompts.ts é independente; testado por tests/integration/proxy-pipeline.test.ts + "providerStats", // intentionally-internal: src/app/api/provider-stats/route.ts + "recovery", // intentionally-internal: bin/cli/runtime.mjs (import() dinâmico) + tests + "secrets", // intentionally-internal: src/instrumentation-node.ts (import() dinâmico na inicialização) + "serviceModels", // intentionally-internal: 3 callers (services/modelSync, services/bootstrap, /api/services/9router/models) + "stateReset", // db-internal: 3 callers dentro de src/lib/db/ (core, backup, apiKeys) para coordenação de reset + "stats", // intentionally-internal: src/app/api/settings/database/refresh-stats/route.ts + "tierConfig", // intentionally-internal: open-sse/services/tierResolver.ts (require() dinâmico) ]); +// Alias para retrocompatibilidade com os testes existentes que importam KNOWN_UNEXPORTED. +// O comportamento do gate é idêntico — só o nome e os comentários mudaram (#3499). +export const KNOWN_UNEXPORTED = INTENTIONALLY_INTERNAL; + // (c) Ofensores de SQL cru PRÉ-EXISTENTES em rotas/handlers. Congelados para a // catraca ficar verde e bloquear QUALQUER nova rota/handler com SQL inline. // CADA UM é dívida da Hard Rule #5: mover para um módulo src/lib/db/. NÃO @@ -112,8 +124,10 @@ export function extractReexportedModules(localDbSource) { return out; } -// (a) Módulos db/ que não são re-exportados e não estão congelados. -export function findMissingReexports(dbModules, reexported, allowlist = KNOWN_UNEXPORTED) { +// (a) Módulos db/ que não são re-exportados e não estão na lista de +// intencionalmente-internos (INTENTIONALLY_INTERNAL). O gate falha para +// qualquer módulo NOVO que não seja re-exportado nem justificado. +export function findMissingReexports(dbModules, reexported, allowlist = INTENTIONALLY_INTERNAL) { return dbModules.filter((mod) => !reexported.has(mod) && !allowlist.has(mod)); } @@ -216,7 +230,7 @@ function main() { `[#2 re-export] ${missing.length} módulo(s) db/ não re-exportado(s) por src/lib/localDb.ts:\n` + missing.map((m) => ` ✗ src/lib/db/${m}.ts`).join("\n") + `\n → re-exporte de src/lib/localDb.ts (apenas a lista de re-export, nada de lógica)` + - ` ou adicione a KNOWN_UNEXPORTED com justificativa (import direto de "@/lib/db/${missing[0]}").` + ` ou adicione a INTENTIONALLY_INTERNAL com justificativa (import direto de "@/lib/db/${missing[0]}").` ); } @@ -245,7 +259,7 @@ function main() { } console.log( `[check-db-rules] OK (${dbModules.length} módulos db/, ${reexported.size} re-exportados, ` + - `${KNOWN_UNEXPORTED.size} congelados; ${KNOWN_RAW_SQL.size} ofensores de SQL congelados)` + `${INTENTIONALLY_INTERNAL.size} intencionalmente-internos (Rule #2); ${KNOWN_RAW_SQL.size} ofensores de SQL congelados)` ); } diff --git a/tests/unit/check-db-rules-classification.test.ts b/tests/unit/check-db-rules-classification.test.ts new file mode 100644 index 0000000000..7c3d6a804c --- /dev/null +++ b/tests/unit/check-db-rules-classification.test.ts @@ -0,0 +1,213 @@ +/** + * Regression guard for INTENTIONALLY_INTERNAL classification (#3499). + * + * Every module in INTENTIONALLY_INTERNAL must be genuinely consumed via a + * direct/dynamic import somewhere in src/, open-sse/, bin/, or within + * src/lib/db/ itself (for db-internal coordination modules like stateReset, + * healthCheck, migrationRunner), OR documented as type-only / DEAD?. + * + * Purpose: if a future cleanup removes the last consumer of a module that is + * still in INTENTIONALLY_INTERNAL, this test turns red and forces a conscious + * reclassification decision — the DEAD? category must be explicitly expanded, + * not silently accumulated. + * + * Hard Rule #18 compliance: this test was written BEFORE the fix was applied, + * confirmed to fail on the old framing, and now passes on the audited truth. + */ +import { test } from "node:test"; +import assert from "node:assert"; +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { INTENTIONALLY_INTERNAL } from "../../scripts/check/check-db-rules.mjs"; + +const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), "../../.."); + +// ── Helpers ──────────────────────────────────────────────────────────────── + +/** + * Walk a directory tree, calling cb(absolutePath) for every file. + */ +function walkSync(dir: string, cb: (p: string) => void): void { + if (!fs.existsSync(dir)) return; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + // Skip well-known non-source dirs to keep the walk fast + if (["node_modules", ".git", ".next", "dist", "out"].includes(entry.name)) continue; + walkSync(full, cb); + } else { + cb(full); + } + } +} + +/** + * Returns true if any file in the search roots imports db/ (static or dynamic). + * Patterns matched: + * from "@/lib/db/" + * from "../db/" (any relative path ending /db/) + * import("@/lib/db/") + * require(".../db/") + * import(`${...}/db/.ts`) — dynamic template (bin/cli/runtime.mjs pattern) + */ +function hasImporter(mod: string, roots: string[]): boolean { + // Escape special regex chars in mod name (underscore-prefixed names like _rowTypes) + const escaped = mod.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + const patterns = [ + // static: from "…/db/" + new RegExp(`from\\s+['""][^'"]+/db/${escaped}['"]`), + // dynamic: import("…/db/") or require("…/db/") + new RegExp(`(?:import|require)\\s*\\(\\s*['""][^'"]+/db/${escaped}['"]`), + // dynamic template: import(`…/db/.ts`) — bin/cli/runtime.mjs uses template literals + new RegExp(`import\\s*\\(\`[^'"\`]+/db/${escaped}\\.ts\`\\)`), + // relative import within db/: from "./" or from "./" + new RegExp(`from\\s+['"]\\.\\.?/${escaped}['"]`), + ]; + // The canonical db module path — we must skip ONLY this exact file, not all files + // that happen to share the same basename (e.g. src/lib/usage/comboForecast.ts must + // NOT be skipped when searching for importers of src/lib/db/comboForecast.ts). + const dbModulePath = path.join(REPO_ROOT, "src", "lib", "db", `${mod}.ts`); + let found = false; + for (const root of roots) { + if (found) break; + walkSync(root, (filePath) => { + if (found) return; + // Only scan TS/JS/MJS source files + if (!/\.(ts|tsx|mjs|js|cjs)$/.test(filePath)) return; + // Skip only the db module itself (not same-name files in other dirs) + if (filePath === dbModulePath) return; + let src: string; + try { + src = fs.readFileSync(filePath, "utf8"); + } catch { + return; + } + if (patterns.some((rx) => rx.test(src))) found = true; + }); + } + return found; +} + +// ── Audit roots ──────────────────────────────────────────────────────────── + +// Modules marked "type-only": exports only TypeScript types; no runtime import +// needed — the ts compiler erases them. These are genuinely correct as-is. +const TYPE_ONLY = new Set(["_rowTypes"]); + +// Modules explicitly documented as DEAD? in the classification comments. +// They remain in INTENTIONALLY_INTERNAL for schema-reservation reasons. +// Flag them but do NOT fail — a separate decision is needed to remove them. +const DOCUMENTED_DEAD = new Set([ + "compressionScheduler", // DEAD?: 0 production importers as of 2026-06-11 + "discovery", // DEAD?: 0 importers; lib/discovery/index.ts is independent + "pluginMetrics", // DEAD? (production): write path not yet wired (self-documented) + "prompts", // DEAD? (production): zero production callers; integration test only verifies interface shape +]); + +const SEARCH_ROOTS = [ + path.join(REPO_ROOT, "src"), + path.join(REPO_ROOT, "open-sse"), + path.join(REPO_ROOT, "bin"), + path.join(REPO_ROOT, "tests"), +]; + +// ── Tests ────────────────────────────────────────────────────────────────── + +test("INTENTIONALLY_INTERNAL is exported from check-db-rules.mjs", () => { + assert.ok( + INTENTIONALLY_INTERNAL instanceof Set, + "INTENTIONALLY_INTERNAL must be a Set exported from the gate script" + ); + assert.ok(INTENTIONALLY_INTERNAL.size > 0, "INTENTIONALLY_INTERNAL must not be empty"); +}); + +test("INTENTIONALLY_INTERNAL contains the expected 25 audited modules", () => { + const expected = [ + "_rowTypes", + "cleanup", + "cliToolState", + "comboForecast", + "commandCodeAuth", + "compression", + "compressionScheduler", + "detailedLogs", + "discovery", + "domainState", + "encryption", + "healthCheck", + "jsonMigration", + "migrationRunner", + "notion", + "obsidian", + "pluginMetrics", + "prompts", + "providerStats", + "recovery", + "secrets", + "serviceModels", + "stateReset", + "stats", + "tierConfig", + ]; + for (const mod of expected) { + assert.ok( + INTENTIONALLY_INTERNAL.has(mod), + `Expected ${mod} to be in INTENTIONALLY_INTERNAL after audit` + ); + } + assert.equal( + INTENTIONALLY_INTERNAL.size, + expected.length, + `INTENTIONALLY_INTERNAL has ${INTENTIONALLY_INTERNAL.size} entries; expected ${expected.length}` + ); +}); + +test("every non-type-only, non-dead module in INTENTIONALLY_INTERNAL has ≥1 real importer", () => { + const failures: string[] = []; + for (const mod of INTENTIONALLY_INTERNAL) { + if (TYPE_ONLY.has(mod)) continue; // type-only: no runtime import expected + if (DOCUMENTED_DEAD.has(mod)) continue; // dead modules exempted with explicit flag + if (!hasImporter(mod, SEARCH_ROOTS)) { + failures.push(mod); + } + } + assert.deepEqual( + failures, + [], + `These INTENTIONALLY_INTERNAL modules have ZERO importers — either they became dead ` + + `(add to DOCUMENTED_DEAD with a DEAD? comment) or they were misclassified:\n ${failures.join(", ")}` + ); +}); + +test("type-only module _rowTypes is imported within src/lib/db/ by its consumers", () => { + // _rowTypes exports only TypeScript interfaces, so the import is always `import type`. + // It should be consumed within db/ itself (AgentBridge, Inspector CRUD modules). + const dbDir = path.join(REPO_ROOT, "src/lib/db"); + let found = false; + if (fs.existsSync(dbDir)) { + for (const entry of fs.readdirSync(dbDir, { withFileTypes: true })) { + if (!entry.isFile() || !/\.ts$/.test(entry.name)) continue; + if (entry.name === "_rowTypes.ts") continue; + const src = fs.readFileSync(path.join(dbDir, entry.name), "utf8"); + if (/from\s+['"]\.\/_rowTypes['"]/.test(src)) { + found = true; + break; + } + } + } + assert.ok( + found, + "_rowTypes must be imported (as type) by at least one sibling module in src/lib/db/" + ); +}); + +test("DOCUMENTED_DEAD modules are still in INTENTIONALLY_INTERNAL (dead list must stay honest)", () => { + for (const mod of DOCUMENTED_DEAD) { + assert.ok( + INTENTIONALLY_INTERNAL.has(mod), + `DOCUMENTED_DEAD module "${mod}" is no longer in INTENTIONALLY_INTERNAL — ` + + `remove it from DOCUMENTED_DEAD in this test if it was intentionally removed from the gate` + ); + } +});