knosky 0.6.3 → 0.7.0

package/core/fs-indexer.mjs

@@ -1,218 +1,218 @@
-// KC fs indexer (Phase 1b): a real local folder -> contract v2. Deterministic, $0-token.
-// Pointers + projections ONLY (no file bodies). Dir-name categorizer (always-works fallback).
-// Honors IGNORE_DEFAULTS + .gitignore + .kcignore. Council fixes: allowlist+scrub via contract.serializeNode.
-import fs from 'node:fs';
-import path from 'node:path';
-import { execSync } from 'node:child_process';
-import { SCHEMA_VERSION, IGNORE_DEFAULTS, deriveCategories, serializeNode, validateCity, setRedactTerms, findSecrets } from './contract.mjs';
-import { extractImportSpecifiers, resolveSpec } from './edges.mjs';
-import { gitChurn } from './churn.mjs';
-import { computeLedgerSeq } from './freshness.mjs';
-
-const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => a.startsWith('--') ? [a.slice(2), arr[i + 1]] : []).filter(Boolean));
-const ROOT = args.root && path.resolve(args.root);
-const OUT = args.out || null;
-// Validate --max: a non-numeric/zero/negative value must NOT silently disable the
-// cap (NaN comparisons are always false, so `scanned > MAX` would never trip) —
-// that's a resource-exhaustion opening on a hostile/malformed CI invocation.
-const MAX = (() => { const n = parseInt(args.max || '6000', 10); return (Number.isFinite(n) && n > 0) ? n : 6000; })();
-const SHARE_SAFE = process.argv.includes('--share-safe');
-const INCLUDE_ABS = process.argv.includes('--include-absolute-root');
-const ALLOW_LEAKS = process.argv.includes('--allow-leaks');
-const NO_GRAPH = process.argv.includes('--no-graph');
-const NO_CHURN = process.argv.includes('--no-churn');
-if (!ROOT || !fs.existsSync(ROOT)) { console.log('usage: node fs-indexer.mjs --root <dir> [--out <file>] [--max N] [--redact a,b]'); process.exit(1); }
-const REDACT = (args.redact || '').split(',').map(s => s.trim()).filter(Boolean);
-if (REDACT.length) setRedactTerms(REDACT);
-const REDACT_RX = REDACT.map(t => new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i'));
-
-const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|c|cc|cpp|h|hpp|cs|swift|kt|sh|sql)$/i;
-const DOC = /\.(md|markdown|mdx|txt|rst|adoc)$/i;
-const TEXT_READABLE = /\.(md|markdown|mdx|txt|rst|adoc|ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|c|cc|cpp|h|hpp|cs|swift|kt|sh|sql|json|ya?ml|toml|ini|cfg)$/i;
-
-function gitRev(root) {
-  try { return 'git:' + execSync('git rev-parse --short HEAD', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
-  catch { return 'fs:' + new Date().toISOString().slice(0, 10); }
-}
-// Parse .gitignore/.kcignore into conservative matchers (dir names + basenames + *.ext).
-function loadIgnore(root) {
-  const pats = [];
-  for (const f of ['.gitignore', '.kcignore']) {
-    try {
-      for (let ln of fs.readFileSync(path.join(root, f), 'utf8').split(/\r?\n/)) {
-        ln = ln.trim(); if (!ln || ln.startsWith('#') || ln.startsWith('!')) continue;
-        ln = ln.replace(/^\/+/, '').replace(/\/+$/, '');
-        if (!ln) continue;
-        const rx = '(^|/)' + ln.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '(/|$)';
-        pats.push(new RegExp(rx, 'i'));
-      }
-    } catch { /* no file */ }
-  }
-  return pats;
-}
-const REV = gitRev(ROOT);
-const IGN = [...IGNORE_DEFAULTS, ...loadIgnore(ROOT)];
-const ignored = (rel) => IGN.some(re => re.test(rel));
-
-const flags = [];
-let scanned = 0, capped = false, redactedPaths = 0;
-const raw = []; // pre-serialize nodes
-
-function excerptAndHeadings(fp, isDoc) {
-  let txt = '';
-  try { const fd = fs.openSync(fp, 'r'); const buf = Buffer.alloc(4096); const n = fs.readSync(fd, buf, 0, 4096, 0); fs.closeSync(fd); txt = buf.slice(0, n).toString('utf8'); }
-  catch { return { title: null, summary: '', headings: [] }; }
-  let title = null; const headings = [];
-  if (isDoc) {
-    const h1 = txt.match(/^#\s+(.+)$/m); if (h1) title = h1[1].trim();
-    for (const m of txt.matchAll(/^#{2,3}\s+(.+)$/gm)) { headings.push(m[1].trim()); if (headings.length >= 8) break; }
-  }
-  // first prose line: skip frontmatter + headings/code fences
-  const prose = txt.replace(/^---[\s\S]*?---/, '').split(/\r?\n/).map(s => s.trim())
-    .find(s => s && !s.startsWith('#') && !s.startsWith('```') && !s.startsWith('|') && !s.startsWith('<')) || '';
-  return { title, summary: prose, headings };
-}
-
-function walk(dir, depth) {
-  if (capped) return;
-  let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-  for (const e of ents) {
-    if (capped) return;
-    const fp = path.join(dir, e.name);
-    const rel = path.relative(ROOT, fp).split(path.sep).join('/');
-    if (ignored(rel)) continue;
-    if (e.isDirectory()) { if (depth < 12) walk(fp, depth + 1); continue; }
-    if (!e.isFile()) continue;
-    if (REDACT_RX.some(re => re.test(rel))) { redactedPaths++; continue; }
-    scanned++;
-    if (scanned > MAX) { capped = true; flags.push(`capped at ${MAX} files`); return; }
-    const parts = rel.split('/');
-    const category = parts.length > 1 ? parts[0] : '(root)';
-    const ext = path.extname(rel);
-    const kind = DOC.test(rel) ? 'doc' : CODE.test(rel) ? 'code' : 'file';
-    const readable = TEXT_READABLE.test(rel);
-    const { title, summary, headings } = readable ? excerptAndHeadings(fp, DOC.test(rel)) : { title: null, summary: '', headings: [] };
-    raw.push({
-      id: 'fs:' + rel,
-      kind,
-      title: title || parts[parts.length - 1],
-      summary,
-      category,
-      status: 'present',
-      tags: ext ? [ext.slice(1)] : [],
-      headings,
-      links: [],
-      importSpecs: (!NO_GRAPH && readable) ? extractImportSpecifiers(fp) : [],
-      provenance: { store: 'fs', ref: rel, source_rev: REV, fetched_at: new Date().toISOString() },
-      visibility: 'internal',
-    });
-  }
-}
-
-walk(ROOT, 0);
-
-// Accurate ignore inside a git repo: let git decide (catches .gitignore patterns the conservative parser misses).
-try {
-  const NL = String.fromCharCode(10);
-  const rels = raw.map(n => n.provenance.ref);
-  if (rels.length) {
-    let ignoredOut = '';
-    try { ignoredOut = execSync('git check-ignore --stdin', { cwd: ROOT, input: rels.join(NL), encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }); }
-    catch (e) { ignoredOut = (e && e.stdout) ? String(e.stdout) : ''; }   // exit 1 (none ignored) / 128 (not a repo) -> empty
-    const gi = new Set(ignoredOut.split(NL).map(s => s.trim()).filter(Boolean));
-    if (gi.size) for (let i = raw.length - 1; i >= 0; i--) if (gi.has(raw[i].provenance.ref)) raw.splice(i, 1);
-  }
-} catch (e) { /* git unavailable: keep the conservative-parser result */ }
-
-// File Connections (D-155): resolve import specifiers to indexed files; store ONLY file-to-file edges.
-const relSet = new Set(raw.map(n => n.provenance.ref));
-if (!NO_GRAPH) {
-  for (const n of raw) {
-    const targets = new Set();
-    for (const spec of (n.importSpecs || [])) {
-      const t = resolveSpec(n.provenance.ref, spec, relSet);
-      if (t) { const id = 'fs:' + t; if (id !== n.id) targets.add(id); }
-    }
-    n.links = [...targets];
-  }
-}
-for (const n of raw) delete n.importSpecs;   // discard specifiers; only the resolved file-to-file edge survives
-
-// Churn overlay (D-155): per-file commit count + last-commit ts only (no messages/diffs/authors/lines).
-if (!NO_CHURN) {
-  const ch = gitChurn(ROOT);
-  for (const n of raw) {
-    const c = ch.counts[n.provenance.ref] || 0;
-    if (c > 0) n.churn = { c, t: ch.last[n.provenance.ref] || 0, b: c >= 6 ? 3 : c >= 3 ? 2 : 1 };
-  }
-}
-
-// --- fail-closed secret scan on RAW projections, BEFORE scrubbing (the decisive boundary).
-// Scans exactly the text that will be emitted (title/summary/headings/tags + relative path) in
-// its un-scrubbed form, so detection cannot be defeated by serializeNode()'s scrub. ---
-const _NL = String.fromCharCode(10);
-const rawText = raw.map(n => [
-  n.title, n.summary,
-  (n.headings || []).join(_NL),
-  (n.tags || []).join(' '),
-  n.provenance && n.provenance.ref,
-].filter(Boolean).join(_NL)).join(_NL);
-const preHits = findSecrets(rawText);
-const preTotal = preHits.reduce((a, h) => a + h[1], 0);
-const preList = preHits.map(h => h[0] + ':' + h[1]).join(', ');
-
-const nodes = raw.map(serializeNode);
-const catIds = [...new Set(nodes.map(n => n.category))].sort();
-const categories = deriveCategories(catIds);
-// Ledger-anchored freshness (SAT-444): monotone commit count, used as a
-// replay-resistant sequence number.  Consumers compare against the last
-// accepted ledger_seq (V13 high-water-mark guard) to detect rollbacks.
-const ledger_seq = computeLedgerSeq(ROOT);
-const city = {
-  schema_version: SCHEMA_VERSION,
-  generated_at: new Date().toISOString(),
-  source: { kind: 'fs', ref: INCLUDE_ABS ? ROOT : path.basename(ROOT), rev: REV },
-  ledger_seq,
-  categories, node_count: nodes.length, nodes,
-};
-
-const res = validateCity(city);
-const dist = {}; for (const n of nodes) dist[n.category] = (dist[n.category] || 0) + 1;
-
-// leakage audit: scan emitted projections for secret-ish patterns + employer strings
-const blob = JSON.stringify(nodes);
-const leakHits = (blob.match(/\b(AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)\b/g) || []).length
-  + (blob.match(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g) || []).length;
-
-console.log('--- fs index:', INCLUDE_ABS ? ROOT : path.basename(ROOT), '---');
-console.log('rev', REV, '| scanned files:', scanned, '| nodes:', nodes.length, '| categories:', catIds.length);
-console.log('byKind:', JSON.stringify(nodes.reduce((a, n) => (a[n.kind] = (a[n.kind] || 0) + 1, a), {})));
-console.log('top categories:', Object.entries(dist).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([k, v]) => `${k}:${v}`).join(', '));
-console.log('VALID:', res.ok, res.ok ? '' : '\n - ' + res.errors.slice(0, 8).join('\n - '));
-console.log('post-scrub leak hits (emails/keys, should be ~0):', leakHits);
-console.log('redacted-path files skipped:', redactedPaths);
-if (flags.length) console.log('flags:', flags.join('; '));
-
-// --- fail-closed safe-share audit.
-// PRIMARY   = pre-scrub detection (preTotal, computed above) -> the real boundary.
-// SECONDARY = post-scrub residual on the emitted artifact -> flags scrub gaps (defense in depth). ---
-const residualHits = findSecrets(blob);
-const residualTotal = residualHits.reduce((a, h) => a + h[1], 0);
-const residualList = residualHits.map(h => h[0] + ':' + h[1]).join(', ');
-if (SHARE_SAFE) {
-  console.log('');
-  console.log('KnoSky safety report');
-  console.log('- Files scanned:', scanned);
-  console.log('- Files skipped (redact-path):', redactedPaths);
-  console.log('- Secrets found (pre-scrub):', preTotal, preTotal ? '[' + preList + ']' : '');
-  console.log('- Residual after scrub (should be 0):', residualTotal, residualTotal ? '[' + residualList + ']' : '');
-  console.log('- Absolute path in output:', INCLUDE_ABS ? 'INCLUDED' : 'removed (basename only)');
-  console.log('- Risk level:', (preTotal || residualTotal) ? 'HIGH' : 'Low');
-}
-if ((preTotal || residualTotal) && !ALLOW_LEAKS) {
-  const why = preTotal ? preList : residualList;
-  console.error('BLOCKED: ' + (preTotal || residualTotal) + ' secret-like value(s) detected [' + why + ']. Nothing written.');
-  console.error('Add the offending paths to .kcignore or pass --redact <term>, then rebuild. Override with --allow-leaks (not recommended).');
-  process.exit(1);
-}
-if (OUT) { fs.writeFileSync(OUT, JSON.stringify(city, null, 2) + '\n'); console.log('wrote', OUT); }
+// KC fs indexer (Phase 1b): a real local folder -> contract v2. Deterministic, $0-token.
+// Pointers + projections ONLY (no file bodies). Dir-name categorizer (always-works fallback).
+// Honors IGNORE_DEFAULTS + .gitignore + .kcignore. Council fixes: allowlist+scrub via contract.serializeNode.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { SCHEMA_VERSION, IGNORE_DEFAULTS, deriveCategories, serializeNode, validateCity, setRedactTerms, findSecrets } from './contract.mjs';
+import { extractImportSpecifiers, resolveSpec } from './edges.mjs';
+import { gitChurn } from './churn.mjs';
+import { computeLedgerSeq } from './freshness.mjs';
+
+const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => a.startsWith('--') ? [a.slice(2), arr[i + 1]] : []).filter(Boolean));
+const ROOT = args.root && path.resolve(args.root);
+const OUT = args.out || null;
+// Validate --max: a non-numeric/zero/negative value must NOT silently disable the
+// cap (NaN comparisons are always false, so `scanned > MAX` would never trip) —
+// that's a resource-exhaustion opening on a hostile/malformed CI invocation.
+const MAX = (() => { const n = parseInt(args.max || '6000', 10); return (Number.isFinite(n) && n > 0) ? n : 6000; })();
+const SHARE_SAFE = process.argv.includes('--share-safe');
+const INCLUDE_ABS = process.argv.includes('--include-absolute-root');
+const ALLOW_LEAKS = process.argv.includes('--allow-leaks');
+const NO_GRAPH = process.argv.includes('--no-graph');
+const NO_CHURN = process.argv.includes('--no-churn');
+if (!ROOT || !fs.existsSync(ROOT)) { console.log('usage: node fs-indexer.mjs --root <dir> [--out <file>] [--max N] [--redact a,b]'); process.exit(1); }
+const REDACT = (args.redact || '').split(',').map(s => s.trim()).filter(Boolean);
+if (REDACT.length) setRedactTerms(REDACT);
+const REDACT_RX = REDACT.map(t => new RegExp('\\b' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i'));
+
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|c|cc|cpp|h|hpp|cs|swift|kt|sh|sql)$/i;
+const DOC = /\.(md|markdown|mdx|txt|rst|adoc)$/i;
+const TEXT_READABLE = /\.(md|markdown|mdx|txt|rst|adoc|ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|c|cc|cpp|h|hpp|cs|swift|kt|sh|sql|json|ya?ml|toml|ini|cfg)$/i;
+
+function gitRev(root) {
+  try { return 'git:' + execSync('git rev-parse --short HEAD', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return 'fs:' + new Date().toISOString().slice(0, 10); }
+}
+// Parse .gitignore/.kcignore into conservative matchers (dir names + basenames + *.ext).
+function loadIgnore(root) {
+  const pats = [];
+  for (const f of ['.gitignore', '.kcignore']) {
+    try {
+      for (let ln of fs.readFileSync(path.join(root, f), 'utf8').split(/\r?\n/)) {
+        ln = ln.trim(); if (!ln || ln.startsWith('#') || ln.startsWith('!')) continue;
+        ln = ln.replace(/^\/+/, '').replace(/\/+$/, '');
+        if (!ln) continue;
+        const rx = '(^|/)' + ln.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '(/|$)';
+        pats.push(new RegExp(rx, 'i'));
+      }
+    } catch { /* no file */ }
+  }
+  return pats;
+}
+const REV = gitRev(ROOT);
+const IGN = [...IGNORE_DEFAULTS, ...loadIgnore(ROOT)];
+const ignored = (rel) => IGN.some(re => re.test(rel));
+
+const flags = [];
+let scanned = 0, capped = false, redactedPaths = 0;
+const raw = []; // pre-serialize nodes
+
+function excerptAndHeadings(fp, isDoc) {
+  let txt = '';
+  try { const fd = fs.openSync(fp, 'r'); const buf = Buffer.alloc(4096); const n = fs.readSync(fd, buf, 0, 4096, 0); fs.closeSync(fd); txt = buf.slice(0, n).toString('utf8'); }
+  catch { return { title: null, summary: '', headings: [] }; }
+  let title = null; const headings = [];
+  if (isDoc) {
+    const h1 = txt.match(/^#\s+(.+)$/m); if (h1) title = h1[1].trim();
+    for (const m of txt.matchAll(/^#{2,3}\s+(.+)$/gm)) { headings.push(m[1].trim()); if (headings.length >= 8) break; }
+  }
+  // first prose line: skip frontmatter + headings/code fences
+  const prose = txt.replace(/^---[\s\S]*?---/, '').split(/\r?\n/).map(s => s.trim())
+    .find(s => s && !s.startsWith('#') && !s.startsWith('```') && !s.startsWith('|') && !s.startsWith('<')) || '';
+  return { title, summary: prose, headings };
+}
+
+function walk(dir, depth) {
+  if (capped) return;
+  let ents; try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of ents) {
+    if (capped) return;
+    const fp = path.join(dir, e.name);
+    const rel = path.relative(ROOT, fp).split(path.sep).join('/');
+    if (ignored(rel)) continue;
+    if (e.isDirectory()) { if (depth < 12) walk(fp, depth + 1); continue; }
+    if (!e.isFile()) continue;
+    if (REDACT_RX.some(re => re.test(rel))) { redactedPaths++; continue; }
+    scanned++;
+    if (scanned > MAX) { capped = true; flags.push(`capped at ${MAX} files`); return; }
+    const parts = rel.split('/');
+    const category = parts.length > 1 ? parts[0] : '(root)';
+    const ext = path.extname(rel);
+    const kind = DOC.test(rel) ? 'doc' : CODE.test(rel) ? 'code' : 'file';
+    const readable = TEXT_READABLE.test(rel);
+    const { title, summary, headings } = readable ? excerptAndHeadings(fp, DOC.test(rel)) : { title: null, summary: '', headings: [] };
+    raw.push({
+      id: 'fs:' + rel,
+      kind,
+      title: title || parts[parts.length - 1],
+      summary,
+      category,
+      status: 'present',
+      tags: ext ? [ext.slice(1)] : [],
+      headings,
+      links: [],
+      importSpecs: (!NO_GRAPH && readable) ? extractImportSpecifiers(fp) : [],
+      provenance: { store: 'fs', ref: rel, source_rev: REV, fetched_at: new Date().toISOString() },
+      visibility: 'internal',
+    });
+  }
+}
+
+walk(ROOT, 0);
+
+// Accurate ignore inside a git repo: let git decide (catches .gitignore patterns the conservative parser misses).
+try {
+  const NL = String.fromCharCode(10);
+  const rels = raw.map(n => n.provenance.ref);
+  if (rels.length) {
+    let ignoredOut = '';
+    try { ignoredOut = execSync('git check-ignore --stdin', { cwd: ROOT, input: rels.join(NL), encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }); }
+    catch (e) { ignoredOut = (e && e.stdout) ? String(e.stdout) : ''; }   // exit 1 (none ignored) / 128 (not a repo) -> empty
+    const gi = new Set(ignoredOut.split(NL).map(s => s.trim()).filter(Boolean));
+    if (gi.size) for (let i = raw.length - 1; i >= 0; i--) if (gi.has(raw[i].provenance.ref)) raw.splice(i, 1);
+  }
+} catch (e) { /* git unavailable: keep the conservative-parser result */ }
+
+// File Connections (D-155): resolve import specifiers to indexed files; store ONLY file-to-file edges.
+const relSet = new Set(raw.map(n => n.provenance.ref));
+if (!NO_GRAPH) {
+  for (const n of raw) {
+    const targets = new Set();
+    for (const spec of (n.importSpecs || [])) {
+      const t = resolveSpec(n.provenance.ref, spec, relSet);
+      if (t) { const id = 'fs:' + t; if (id !== n.id) targets.add(id); }
+    }
+    n.links = [...targets];
+  }
+}
+for (const n of raw) delete n.importSpecs;   // discard specifiers; only the resolved file-to-file edge survives
+
+// Churn overlay (D-155): per-file commit count + last-commit ts only (no messages/diffs/authors/lines).
+if (!NO_CHURN) {
+  const ch = gitChurn(ROOT);
+  for (const n of raw) {
+    const c = ch.counts[n.provenance.ref] || 0;
+    if (c > 0) n.churn = { c, t: ch.last[n.provenance.ref] || 0, b: c >= 6 ? 3 : c >= 3 ? 2 : 1 };
+  }
+}
+
+// --- fail-closed secret scan on RAW projections, BEFORE scrubbing (the decisive boundary).
+// Scans exactly the text that will be emitted (title/summary/headings/tags + relative path) in
+// its un-scrubbed form, so detection cannot be defeated by serializeNode()'s scrub. ---
+const _NL = String.fromCharCode(10);
+const rawText = raw.map(n => [
+  n.title, n.summary,
+  (n.headings || []).join(_NL),
+  (n.tags || []).join(' '),
+  n.provenance && n.provenance.ref,
+].filter(Boolean).join(_NL)).join(_NL);
+const preHits = findSecrets(rawText);
+const preTotal = preHits.reduce((a, h) => a + h[1], 0);
+const preList = preHits.map(h => h[0] + ':' + h[1]).join(', ');
+
+const nodes = raw.map(serializeNode);
+const catIds = [...new Set(nodes.map(n => n.category))].sort();
+const categories = deriveCategories(catIds);
+// Ledger-anchored freshness (SAT-444): monotone commit count, used as a
+// replay-resistant sequence number.  Consumers compare against the last
+// accepted ledger_seq (V13 high-water-mark guard) to detect rollbacks.
+const ledger_seq = computeLedgerSeq(ROOT);
+const city = {
+  schema_version: SCHEMA_VERSION,
+  generated_at: new Date().toISOString(),
+  source: { kind: 'fs', ref: INCLUDE_ABS ? ROOT : path.basename(ROOT), rev: REV },
+  ledger_seq,
+  categories, node_count: nodes.length, nodes,
+};
+
+const res = validateCity(city);
+const dist = {}; for (const n of nodes) dist[n.category] = (dist[n.category] || 0) + 1;
+
+// leakage audit: scan emitted projections for secret-ish patterns + employer strings
+const blob = JSON.stringify(nodes);
+const leakHits = (blob.match(/\b(AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)\b/g) || []).length
+  + (blob.match(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g) || []).length;
+
+console.log('--- fs index:', INCLUDE_ABS ? ROOT : path.basename(ROOT), '---');
+console.log('rev', REV, '| scanned files:', scanned, '| nodes:', nodes.length, '| categories:', catIds.length);
+console.log('byKind:', JSON.stringify(nodes.reduce((a, n) => (a[n.kind] = (a[n.kind] || 0) + 1, a), {})));
+console.log('top categories:', Object.entries(dist).sort((a, b) => b[1] - a[1]).slice(0, 8).map(([k, v]) => `${k}:${v}`).join(', '));
+console.log('VALID:', res.ok, res.ok ? '' : '\n - ' + res.errors.slice(0, 8).join('\n - '));
+console.log('post-scrub leak hits (emails/keys, should be ~0):', leakHits);
+console.log('redacted-path files skipped:', redactedPaths);
+if (flags.length) console.log('flags:', flags.join('; '));
+
+// --- fail-closed safe-share audit.
+// PRIMARY   = pre-scrub detection (preTotal, computed above) -> the real boundary.
+// SECONDARY = post-scrub residual on the emitted artifact -> flags scrub gaps (defense in depth). ---
+const residualHits = findSecrets(blob);
+const residualTotal = residualHits.reduce((a, h) => a + h[1], 0);
+const residualList = residualHits.map(h => h[0] + ':' + h[1]).join(', ');
+if (SHARE_SAFE) {
+  console.log('');
+  console.log('KnoSky safety report');
+  console.log('- Files scanned:', scanned);
+  console.log('- Files skipped (redact-path):', redactedPaths);
+  console.log('- Secrets found (pre-scrub):', preTotal, preTotal ? '[' + preList + ']' : '');
+  console.log('- Residual after scrub (should be 0):', residualTotal, residualTotal ? '[' + residualList + ']' : '');
+  console.log('- Absolute path in output:', INCLUDE_ABS ? 'INCLUDED' : 'removed (basename only)');
+  console.log('- Risk level:', (preTotal || residualTotal) ? 'HIGH' : 'Low');
+}
+if ((preTotal || residualTotal) && !ALLOW_LEAKS) {
+  const why = preTotal ? preList : residualList;
+  console.error('BLOCKED: ' + (preTotal || residualTotal) + ' secret-like value(s) detected [' + why + ']. Nothing written.');
+  console.error('Add the offending paths to .kcignore or pass --redact <term>, then rebuild. Override with --allow-leaks (not recommended).');
+  process.exit(1);
+}
+if (OUT) { fs.writeFileSync(OUT, JSON.stringify(city, null, 2) + '\n'); console.log('wrote', OUT); }