fix(db): reclassify localDb unexported modules as intentionally-internal (#3499) (#3635)

Closes #3499 — reclassify localDb unexported modules as intentionally-internal (audit + honest gate framing).

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.
 

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)`
   );
 }
 

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/<mod> (static or dynamic).
+ * Patterns matched:
+ *   from "@/lib/db/<mod>"
+ *   from "../db/<mod>"   (any relative path ending /db/<mod>)
+ *   import("@/lib/db/<mod>")
+ *   require(".../db/<mod>")
+ *   import(`${...}/db/<mod>.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/<mod>"
+    new RegExp(`from\\s+['""][^'"]+/db/${escaped}['"]`),
+    // dynamic: import("…/db/<mod>") or require("…/db/<mod>")
+    new RegExp(`(?:import|require)\\s*\\(\\s*['""][^'"]+/db/${escaped}['"]`),
+    // dynamic template: import(`…/db/<mod>.ts`) — bin/cli/runtime.mjs uses template literals
+    new RegExp(`import\\s*\\(\`[^'"\`]+/db/${escaped}\\.ts\`\\)`),
+    // relative import within db/: from "./<mod>" or from "./<mod>"
+    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`
+    );
+  }
+});