@techninja/clearstack 0.4.3 → 0.4.5

package/lib/check.js

@@ -6,15 +6,41 @@
 
 import { existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
+import { runCmd } from './spec-utils.js';
+import { countFiles, checkFileLines, checkImports } from './spec-scan.js';
 import { checkI18n } from './spec-i18n.js';
 import { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
-export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
+export { runCmd, elapsed } from './spec-utils.js';
+export { findFiles, countFiles, checkFileLines, checkImports } from './spec-scan.js';
 export { checkI18n } from './spec-i18n.js';
 export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
-/** @typedef {{ key: string, name: string, parent?: string, run: (opts?: object) => boolean }} Check */
+/**
+ * Load project-level spec extensions from `clearstack.spec.js` in the project root.
+ * The file may export a default array of Check objects. Any check whose key matches
+ * a built-in check replaces it; new keys are appended.
+ * @param {string} projectDir
+ * @returns {Promise<Check[]>}
+ */
+async function loadExtensions(projectDir) {
+  const extPath = resolve(projectDir, 'clearstack.spec.js');
+  if (!existsSync(extPath)) return [];
+  try {
+    const mod = await import(extPath);
+    const exts = mod.default ?? [];
+    if (!Array.isArray(exts)) {
+      console.warn('⚠ clearstack.spec.js default export must be an array — extensions ignored');
+      return [];
+    }
+    return exts;
+  } catch (e) {
+    console.warn(`⚠ Failed to load clearstack.spec.js: ${e.message}`);
+    return [];
+  }
+}
+
+/** @typedef {{ key: string, name: string, parent?: string, watchExts?: string[], run: (opts?: object) => (boolean | import('./spec-utils.js').CheckResult | Promise<import('./spec-utils.js').CheckResult>) }} Check */
 
 /** Find all jsconfig.json files — main config + subdirectories. */
 function findTypeConfigs(dir, runner) {
@@ -28,42 +54,47 @@ function findTypeConfigs(dir, runner) {
   }
   return configs.map((c) => ({
     key: c.key, name: `JSDoc types — ${c.label}`, parent: 'types',
-    run: () => runCmd(`Types (${c.label})`, `${runner} tsc --project ${c.path}`, dir).pass,
+    run: (o) => runCmd(`Types (${c.label})`, `${runner} tsc --project ${c.path} --noEmit`, dir, undefined, o),
   }));
 }
 
 /**
  * Build the unified checks array. Children have a `parent` key.
- * @returns {Check[]}
+ * Extensions from clearstack.spec.js are merged in: same key = replace, new key = append.
+ * @returns {Promise<Check[]>}
  */
-export function buildChecks(dir, cfg, cmds) {
+export async function buildChecks(dir, cfg, cmds) {
   const js = () => countFiles(dir, ['.js'], cfg.ignore);
   const css = () => countFiles(dir, ['.css'], cfg.ignore);
   const md = () => countFiles(dir, ['.md'], cfg.ignore);
   const runner = detectRunner(dir);
-  return [
+  const builtin = [
     { key: 'es', name: 'ESLint', parent: 'lint',
-      run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`).pass },
+      run: (o) => runCmd('ESLint', cmds.lint, dir, `${js()} files`, o) },
     { key: 'css', name: 'Stylelint', parent: 'lint',
-      run: () => runCmd('Stylelint', cmds.stylelint, dir, `${css()} files`).pass },
+      run: (o) => runCmd('Stylelint', cmds.stylelint, dir, `${css()} files`, o) },
     { key: 'md', name: 'Markdown lint', parent: 'lint',
-      run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`).pass },
+      run: (o) => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`, o) },
     { key: 'prettier', name: 'Prettier', parent: 'format',
-      run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`).pass },
+      run: (o) => runCmd('Prettier', cmds.prettier, dir, `${js()} files`, o) },
     { key: 'lines', name: `Code (max ${cfg.codeMax} lines)`, parent: 'code',
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern }).pass },
+      run: (o) => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern, ...o }) },
     { key: 'i18n', name: 'i18n readiness', parent: 'code',
-      run: (runOpts) => checkI18n(dir, cfg.ignore, 'i18n readiness', runOpts).pass },
+      run: (o) => checkI18n(dir, cfg.ignore, 'i18n readiness', o) },
     { key: 'tests', name: `Tests (max ${cfg.testMax} lines)`,
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern }).pass },
+      run: (o) => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern, ...o }) },
     { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
-      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`).pass },
+      run: (o) => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`, o) },
     { key: 'imports', name: 'Import map aliases (no ../ imports)',
-      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)').pass },
+      run: (o) => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)', o) },
     ...findTypeConfigs(dir, runner),
     { key: 'audit', name: 'Security audit',
-      run: () => runCmd('Security audit', cmds.audit, dir).pass },
+      run: (o) => runCmd('Security audit', cmds.audit, dir, undefined, o) },
   ];
+  const extensions = await loadExtensions(dir);
+  if (!extensions.length) return builtin;
+  const extKeys = new Set(extensions.map((e) => e.key));
+  return [...builtin.filter((c) => !extKeys.has(c.key)), ...extensions];
 }
 
 /** Resolve a scope like 'lint', 'lint es', or 'code' to runnable check(s). */
@@ -88,7 +119,7 @@ export function parentKeys(checks) {
 export async function check(projectDir, scope, opts) {
   const cfg = loadConfig(projectDir);
   const cmds = buildCmds(projectDir);
-  const checks = buildChecks(projectDir, cfg, cmds);
+  const checks = await buildChecks(projectDir, cfg, cmds);
 
   if (scope && scope !== 'all') {
     const matched = resolveChecks(checks, scope);
@@ -98,14 +129,16 @@ export async function check(projectDir, scope, opts) {
       console.log(`Available: ${[...tops, ...parentKeys(checks)].join(', ')}`);
       process.exit(1);
     }
-    const ok = matched.every((c) => c.run(opts));
+    const results = await Promise.all(matched.map((c) => c.run(opts)));
+    const ok = results.every((r) => typeof r === 'boolean' ? r : r.pass);
     if (!ok) process.exit(1);
     return;
   }
 
   console.log('🔍 Clearstack compliance checking now... 💙\n');
-  const results = checks.map((c) => c.run(opts));
-  const passed = results.filter(Boolean).length;
+  const results = await Promise.all(checks.map((c) => c.run(opts)));
+  const passes = results.map((r) => typeof r === 'boolean' ? r : r.pass);
+  const passed = passes.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);
   console.log(`${passed}/${results.length} checks passed.`);
   if (passed < results.length) process.exit(1);

package/lib/server-proc.js

@@ -0,0 +1,150 @@
+/**
+ * Dev server child process manager for spec watch dashboard.
+ * Spawns the server, captures output, and maintains a status row
+ * that the dashboard can render without any extra logic.
+ * @module lib/server-proc
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Detect the dev server command. Prefers SPEC_SERVER_CMD from env,
+ * then probes common entry points. Returns null for static projects.
+ * @param {string} dir @param {object} cfg @returns {string|null}
+ */
+export function detectServerCmd(dir, cfg) {
+  if (cfg.serverCmd) return cfg.serverCmd;
+  for (const entry of ['src/server.js', 'server.js', 'index.js']) {
+    if (existsSync(resolve(dir, entry))) return `node --watch ${entry}`;
+  }
+  return null;
+}
+
+/**
+ * Kill whatever process is listening on a given port.
+ * No-ops silently if nothing is found.
+ * @param {number} port
+ */
+export function killPort(port) {
+  try {
+    const pid = execSync(`lsof -ti tcp:${port}`, { encoding: 'utf-8' }).trim();
+    if (pid) execSync(`kill ${pid}`);
+  } catch { /* nothing listening, or kill already gone */ }
+}
+
+/** @typedef {'starting'|'running'|'restarting'|'crashed'|'disabled'} ServerStatus */
+
+/**
+ * @typedef {object} ServerRow
+ * @property {'server'} key
+ * @property {string} label
+ * @property {ServerStatus} status
+ * @property {boolean|null} pass
+ * @property {string} detail
+ * @property {string} [_errLine]
+ * @property {() => void} kill
+ */
+
+/** Lines from Node --watch we don't want to surface as the detail. */
+const NOISE = /^Debugger|^Waiting for|^\s*$/;
+
+/**
+ * Spawn the dev server and return a live ServerRow.
+ * The row object is mutated in place as output arrives — the dashboard
+ * just reads it on each render cycle.
+ *
+ * @param {string} cmd   e.g. 'node --watch src/server.js'
+ * @param {string} cwd   project root
+ * @param {object} env   merged into process.env for the child
+ * @param {() => void} onUpdate  called whenever status/detail changes
+ * @returns {ServerRow}
+ */
+export function spawnServer(cmd, cwd, env, onUpdate) {
+  /** @type {ServerRow} */
+  const row = {
+    key: 'server',
+    label: 'server',
+    status: 'starting',
+    pass: null,
+    detail: 'starting…',
+    kill: () => {},
+  };
+
+  const [bin, ...args] = cmd.split(/\s+/);
+  const child = spawn(bin, args, {
+    cwd,
+    env: { ...process.env, ...env, FORCE_COLOR: '0' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  row.kill = () => child.kill('SIGTERM');
+
+  /**
+   *
+   */
+  function onLine(line, isStderr) {
+    line = line.trim();
+    if (!line || NOISE.test(line)) return;
+
+    if (/restarting/i.test(line)) {
+      row.status = 'restarting';
+      row.pass = null;
+      row.detail = 'restarting…';
+      onUpdate();
+      return;
+    }
+    // Errors on stderr always override — don't let a stale URL persist
+    if (isStderr || /error|EADDR|EACCES|ENOENT/i.test(line)) {
+      row.status = 'crashed';
+      row.pass = false;
+      // Prefer 'Error: ...' lines; only upgrade, never downgrade
+      const isRich = /^Error:/i.test(line);
+      if (!row._errLine || (isRich && !/^Error:/i.test(row._errLine))) {
+        row._errLine = line.slice(0, 60);
+        row.detail = row._errLine;
+        onUpdate();
+      }
+      return;
+    }
+    if (/https?:\/\//i.test(line) || /listening|started|ready/i.test(line)) {
+      row.status = 'running';
+      row.pass = true;
+      row.detail = line;
+      onUpdate();
+      return;
+    }
+    if (row.status !== 'running') {
+      row.detail = line.slice(0, 60);
+      onUpdate();
+    }
+  }
+
+  child.stdout?.setEncoding('utf-8');
+  child.stderr?.setEncoding('utf-8');
+  /** @type {Array<[import('stream').Readable|null, boolean]>} */
+  const streams = [[child.stdout, false], [child.stderr, true]];
+  for (const [stream, isStderr] of streams) {
+    if (!stream) continue;
+    let buf = '';
+    stream.on('data', (chunk) => {
+      buf += chunk;
+      const lines = buf.split('\n');
+      buf = lines.pop();
+      for (const l of lines) onLine(l, isStderr);
+    });
+  }
+
+  child.on('close', (code, signal) => {
+    if (signal === 'SIGTERM') return;
+    row.status = 'crashed';
+    row.pass = false;
+    if (!row.detail || row.detail === 'starting…' || row.detail === 'restarting…') {
+      row.detail = `exited (code ${code ?? signal})`;
+    }
+    onUpdate();
+  });
+
+  return row;
+}

package/lib/spec-config.js

@@ -35,6 +35,8 @@ export function loadConfig(projectDir) {
   const local = existsSync(localPath) ? parseEnv(readFileSync(localPath, 'utf-8')) : {};
   const env = { ...base, ...local };
   return {
+    serverCmd: env.SPEC_SERVER_CMD || null,
+    rawEnv: env,
     codeMax: parseInt(env.SPEC_CODE_MAX_LINES) || 150,
     testMax: parseInt(env.SPEC_TEST_MAX_LINES) || 300,
     docsMax: parseInt(env.SPEC_DOCS_MAX_LINES) || 500,
@@ -45,14 +47,56 @@ export function loadConfig(projectDir) {
   };
 }
 
-/** Build check commands for the detected package manager. */
-export function buildCmds(projectDir) {
+/**
+ * Default ext→check-key mapping for built-ins.
+ * Extensions override this by declaring a `watchExts` array on their check object.
+ * @type {Record<string, string[]>}
+ */
+const EXT_DEFAULTS = {
+  '.js':  ['lines', 'es', 'prettier', 'frontend', 'imports', 'i18n'],
+  '.mjs': ['lines', 'es', 'frontend', 'imports'],
+  '.css': ['lines', 'css'],
+  '.md':  ['docs', 'md'],
+  '.json': ['i18n'],
+  '.php': [],
+};
+
+/** Checks that run on pure file reads — no subprocess, sub-millisecond. */
+export const FAST_CHECKS = new Set(['lines', 'docs', 'imports', 'i18n', 'tests']);
+
+/**
+ * Build ext→keys map, merging EXT_DEFAULTS with `watchExts` declared on extension checks.
+ * @param {object[]} checks
+ * @returns {(ext: string) => string[]}
+ */
+export function makeExtMap(checks) {
+  const map = new Map(Object.entries(EXT_DEFAULTS).map(([k, v]) => [k, new Set(v)]));
+  for (const c of checks) {
+    if (!c.watchExts) continue;
+    for (const ext of c.watchExts) {
+      if (!map.has(ext)) map.set(ext, new Set());
+      map.get(ext).add(c.key);
+    }
+  }
+  return (ext) => [...(map.get(ext) ?? [])];
+}
+
+/**
+ * @param {string} projectDir
+ * @param {{ watch?: boolean }} [opts]
+ */
+export function buildCmds(projectDir, opts) {
   const runner = detectRunner(projectDir);
-  // pnpm 9.x audit hits a retired npm endpoint (410). Use --ignore-registry-errors
-  // to avoid failing on registry issues outside the user's control.
   const audit = runner === 'pnpm exec'
     ? 'pnpm audit --prod --ignore-registry-errors'
     : 'npm audit --omit=dev';
+  if (opts?.watch) return {
+    lint: `${runner} eslint --config .configs/eslint.config.js .`,
+    stylelint: `${runner} stylelint --config .configs/.stylelintrc.json "src/**/*.css"`,
+    prettier: `${runner} prettier --config .configs/.prettierrc --check src scripts`,
+    mdlint: `${runner} markdownlint-cli2 --config .configs/.markdownlint.jsonc "docs/**/*.md" "*.md"`,
+    audit,
+  };
   return {
     lint: `${runner} eslint --config .configs/eslint.config.js . --fix`,
     stylelint: `${runner} stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix`,

package/lib/spec-i18n-locales.js

@@ -0,0 +1,86 @@
+/**
+ * Locale file parsing helpers for i18n spec check.
+ * @module lib/spec-i18n-locales
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolve } from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Try to run `npx hybrids extract ./src` and parse the JSON output.
+ * @param {string} root
+ * @returns {Promise<Record<string, object>|null>}
+ */
+export async function tryHybridsExtract(root) {
+  const srcDir = resolve(root, 'src');
+  if (!existsSync(srcDir)) return null;
+  try {
+    const { stdout } = await execFileAsync('npx', ['hybrids', 'extract', './src'], {
+      cwd: root,
+      encoding: 'utf-8',
+      timeout: 30000,
+    });
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse locale keys from a .js file that calls localize(lang, {...}).
+ * Extracts top-level string keys from the object literal.
+ * @param {string} filePath
+ * @returns {Set<string>}
+ */
+export function parseLocaleJs(filePath) {
+  const src = readFileSync(filePath, 'utf-8');
+  const keys = new Set();
+  const re = /^\s*(['"])(.*?)\1\s*:/gm;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    const key = m[2].replace(/\\'/g, "'").replace(/\\"/g, '"');
+    keys.add(key);
+  }
+  return keys;
+}
+
+/**
+ * Parse locale keys from a .json file.
+ * @param {string} filePath
+ * @returns {Set<string>}
+ */
+export function parseLocaleJson(filePath) {
+  try {
+    const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+    return new Set(Object.keys(data));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Find locale files and return { lang, keys } for each.
+ * @param {string} localesDir
+ * @returns {Array<{lang: string, keys: Set<string>, file: string}>}
+ */
+export function loadLocales(localesDir) {
+  if (!localesDir) return [];
+  const files = readdirSync(localesDir);
+  const locales = [];
+  for (const f of files) {
+    if (f === 'overrides.json' || f === 'en.json') continue;
+    const full = resolve(localesDir, f);
+    if (f.endsWith('.json')) {
+      const lang = f.replace(/\.json$/, '');
+      locales.push({ lang, keys: parseLocaleJson(full), file: f });
+    } else if (f.endsWith('.js') && !f.includes('init')) {
+      const lang = f.replace(/\.js$/, '');
+      locales.push({ lang, keys: parseLocaleJs(full), file: f });
+    }
+  }
+  return locales;
+}

package/lib/spec-i18n.js

@@ -1,24 +1,42 @@
 /**
- * i18n readiness check — detects patterns, locale files, hardcoded prose density.
+ * i18n readiness check — uses Hybrids extract when available, falls back to regex.
  * Always passes (informational). Surfaces coverage gaps without blocking the build.
  * @module lib/spec-i18n
  */
 
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findFiles, elapsed } from './spec-utils.js';
+import { elapsed } from './spec-utils.js';
+import { findFiles } from './spec-scan.js';
+import { tryHybridsExtract, loadLocales, parseLocaleJson } from './spec-i18n-locales.js';
 
 /** @typedef {import('./spec-utils.js').CheckResult} CheckResult */
 
-const PROSE_RE = />\s*[A-Z][a-z]{2,}[^<$`\\]{3,}\s*[<$]/g;
 const T_RE = /\bt\s*\(/;
 const MSG_RE = /\bmsg`/;
 const LOC_RE = /\blocalize\s*\(/;
-const INIT_RE = /loadLocale|localize\s*\(/;
-const TPL_RE = /html`[\s\S]*?`/g;
 
-/** Strip leading > and trailing <$ from a prose match, trim. */
-const cleanHit = (h) => h.replace(/^>\s*/, '').replace(/\s*[<$]$/, '').trim();
+/**
+ * Extract keys from the DEFAULTS object in a t()-based i18n.js file.
+ * @param {string} root
+ * @returns {string[]|null}
+ */
+function extractTDefaults(root) {
+  const candidates = ['src/utils/i18n.js', 'src/i18n.js', 'utils/i18n.js'];
+  for (const rel of candidates) {
+    const p = resolve(root, rel);
+    if (!existsSync(p)) continue;
+    const src = readFileSync(p, 'utf-8');
+    const block = src.match(/const DEFAULTS\s*=\s*\{([\s\S]*?)\};/);
+    if (!block) continue;
+    const keys = [];
+    const re = /['"]([\.\w]+)['"]\s*:/g;
+    let m;
+    while ((m = re.exec(block[1])) !== null) keys.push(m[1]);
+    if (keys.length) return keys;
+  }
+  return null;
+}
 
 /**
  * Check i18n readiness — informational, always passes.
@@ -26,10 +44,11 @@ const cleanHit = (h) => h.replace(/^>\s*/, '').replace(/\s*[<$]$/, '').trim();
  * @param {string[]} ignoreDirs
  * @param {string} label
  * @param {{ quiet?: boolean, verbose?: boolean }} [opts]
- * @returns {CheckResult}
+ * @returns {Promise<CheckResult>}
  */
-export function checkI18n(root, ignoreDirs, label, opts) {
+export async function checkI18n(root, ignoreDirs, label, opts) {
   const start = performance.now();
+
   const srcFiles = findFiles(root, ['.js'], ignoreDirs, root).filter(
     (f) =>
       f.startsWith('src/') &&
@@ -38,39 +57,12 @@ export function checkI18n(root, ignoreDirs, label, opts) {
       !f.endsWith('.test.js'),
   );
 
-  let usesT = 0,
-    usesMsg = 0,
-    usesLocalize = 0,
-    hasInit = false,
-    hardcodedHits = 0,
-    templateFiles = 0;
-  /** @type {Array<{file: string, text: string, line: number}>} */
-  const verboseHits = [];
-
+  let usesT = 0, usesMsg = 0, usesLocalize = 0;
   for (const file of srcFiles) {
     const src = readFileSync(resolve(root, file), 'utf-8');
     if (T_RE.test(src)) usesT++;
     if (MSG_RE.test(src)) usesMsg++;
     if (LOC_RE.test(src)) usesLocalize++;
-    if (/router\/index|app.*init|main\.js/.test(file) && INIT_RE.test(src)) hasInit = true;
-    const templates = src.match(TPL_RE);
-    if (templates) {
-      templateFiles++;
-      for (const tpl of templates) {
-        const hits = tpl.match(PROSE_RE);
-        if (hits) {
-          hardcodedHits += hits.length;
-          if (opts?.verbose) {
-            for (const h of hits) {
-              const text = cleanHit(h);
-              const idx = src.indexOf(text);
-              const line = idx >= 0 ? src.slice(0, idx).split('\n').length : 0;
-              verboseHits.push({ file, text, line });
-            }
-          }
-        }
-      }
-    }
   }
 
   const localesDir = existsSync(resolve(root, 'src/locales'))
@@ -79,11 +71,10 @@ export function checkI18n(root, ignoreDirs, label, opts) {
       ? resolve(root, 'locales')
       : null;
 
-  const localeFiles = localesDir
-    ? readdirSync(localesDir).filter((f) => f.endsWith('.json') && f !== 'overrides.json')
-    : [];
-  const languages = localeFiles.map((f) => f.replace(/\.json$/, '').replace(/^overrides\./, ''));
   const hasOverrides = localesDir ? existsSync(resolve(localesDir, 'overrides.json')) : false;
+  const extracted = await tryHybridsExtract(root);
+  const extractedKeys = extracted ? Object.keys(extracted) : null;
+  const locales = loadLocales(localesDir);
 
   const patternParts = [
     usesT ? `t() \u00d7${usesT}` : '',
@@ -92,28 +83,35 @@ export function checkI18n(root, ignoreDirs, label, opts) {
   ].filter(Boolean);
 
   const time = elapsed(start);
-  if (!opts?.quiet) {
-    const icon = patternParts.length ? '\u2705' : '\u26a0\ufe0f ';
-    const pattern = patternParts.length ? patternParts.join(', ') : 'none detected';
-    const langs = languages.length ? languages.join(', ') : 'en only';
-    const init = `${hasInit ? 'yes' : 'not detected'} \u00b7 Overrides: ${hasOverrides ? 'yes' : 'no'} \u00b7 Languages: ${langs}`;
-    const unwrapped = hardcodedHits > 0 ? `\n     Unwrapped: ~${hardcodedHits} prose strings across ${templateFiles} template files` : '';
-    console.log(`  ${icon} ${label} (${time})\n     Pattern:   ${pattern}\n     Init:      ${init}${unwrapped}`);
-    if (opts?.verbose && verboseHits.length) {
-      console.log('');
-      const byFile = {};
-      for (const v of verboseHits) {
-        (byFile[v.file] ||= []).push(v);
-      }
-      for (const [file, entries] of Object.entries(byFile)) {
-        console.log(`     ${file}`);
-        for (const e of entries) {
-          const truncated = e.text.length > 60 ? e.text.slice(0, 60) + '\u2026' : e.text;
-          console.log(`       L${e.line || '?'} ${truncated}`);
-        }
+  const coverage = [];
+  if (localesDir) {
+    // Key source priority: t() DEFAULTS + overrides → hybrids extract → overrides.json alone
+    const tKeys = extractTDefaults(root);
+    const overrideKeys = hasOverrides
+      ? [...parseLocaleJson(resolve(localesDir, 'overrides.json'))]
+      : [];
+    const masterKeys = tKeys
+      ? [...new Set([...tKeys, ...overrideKeys])]
+      : (extractedKeys ?? (overrideKeys.length ? overrideKeys : null));
+    if (masterKeys?.length && locales.length) {
+      for (const loc of locales) {
+        const translated = masterKeys.filter((k) => loc.keys.has(k)).length;
+        const pct = Math.round((translated / masterKeys.length) * 100);
+        const missing = masterKeys.length - translated;
+        coverage.push({ lang: loc.lang, pct, missing, total: masterKeys.length });
       }
     }
   }
 
-  return { pass: true, label, time };
+  const coverageDetail = coverage.length
+    ? coverage.map((c) => `${c.lang} ${c.pct}%${c.missing ? ` (${c.missing} missing)` : ' ✓'}`).join(' · ')
+    : (locales.length === 0 ? 'en only' : '');
+
+  if (!opts?.quiet) {
+    const icon = patternParts.length ? '✅' : '⚠️ ';
+    const detail = coverageDetail || (patternParts.length ? patternParts.join(', ') : 'no i18n patterns detected');
+    console.log(`  ${icon} ${label} — ${detail} (${time})`);
+  }
+
+  return { pass: true, label, time, detail: coverageDetail };
 }