tribunal-kit 9.2.5 → 9.2.6

package/scripts/context_compiler.js

@@ -1,1143 +0,0 @@
-#!/usr/bin/env node
-/**
- * context_compiler.js — Tribunal Kit SOTA Context Compiler Engine
- * ════════════════════════════════════════════════════════════════════
- * Deterministic, high-speed context extraction engine for:
- *   1. Single Files (Flight Data HUD Dossier)
- *   2. Multi-File Pairs (Interface Bridge Dossier)
- *   3. Project Folders (Subsystem Macro Dossier)
- *   4. Batch Vault Crawling (--crawl)
- *   5. Semantic Drift Sentinel (--check)
- *
- * Designed for both CLI execution and in-process MCP server integration.
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-
-// Optional ANSI colors
-let C = {
-  GREEN: '\x1b[92m',
-  YELLOW: '\x1b[93m',
-  CYAN: '\x1b[96m',
-  RED: '\x1b[91m',
-  BLUE: '\x1b[94m',
-  BOLD: '\x1b[1m',
-  DIM: '\x1b[2m',
-  RESET: '\x1b[0m',
-};
-
-try {
-  const colorsMod = require('./_colors');
-  if (colorsMod) C = Object.assign({}, C, colorsMod);
-} catch {
-  try {
-    const colorsMod = require('../.agent/scripts/_colors');
-    if (colorsMod) C = Object.assign({}, C, colorsMod);
-  } catch {
-    // Fallback C used
-  }
-}
-
-// ── Hashing Helpers ─────────────────────────────────────────────────────────
-
-function computeSha256(content) {
-  const normalized = content.replace(/\r\n/g, '\n').trim();
-  return crypto.createHash('sha256').update(normalized, 'utf8').digest('hex').substring(0, 16);
-}
-
-function computeInterfaceHash(signatures) {
-  const text = signatures
-    .map(s => `${s.kind}:${s.name}:${s.signature}`)
-    .sort()
-    .join('\n');
-  return crypto.createHash('sha256').update(text, 'utf8').digest('hex').substring(0, 16);
-}
-
-// ── Multi-Language AST / Regex Skeleton Extractor ───────────────────────────
-
-function extractFileSkeleton(filePath, rawContent) {
-  const ext = path.extname(filePath).toLowerCase();
-  const lines = rawContent.split(/\r?\n/);
-  const imports = [];
-  const exports = [];
-  const types = [];
-  const landmines = [];
-
-  // 1. Comments and Landmines (Chesterton's Fences)
-  lines.forEach((line, idx) => {
-    const trimmed = line.trim();
-    if (
-      trimmed.includes('// VERIFY') ||
-      trimmed.includes('// NOTE') ||
-      trimmed.includes('// FIX') ||
-      trimmed.includes('// HACK') ||
-      trimmed.includes('// CAUTION') ||
-      trimmed.includes('// INVARIANT') ||
-      trimmed.includes('// DO NOT') ||
-      trimmed.includes('# VERIFY') ||
-      trimmed.includes('# NOTE')
-    ) {
-      landmines.push({
-        line: idx + 1,
-        content: trimmed,
-      });
-    }
-  });
-
-  // 2. Language-Specific Parsers
-  if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs') {
-    // Phase 1: Try Rust AST Extraction
-    try {
-      const absPath = path.resolve(process.cwd(), filePath);
-      let corePath = null;
-      try {
-        const { getBinaryPath } = require('../.agent/scripts/_utils');
-        corePath = getBinaryPath();
-      } catch (_) {
-        try {
-          const { getBinaryPath } = require('./_utils');
-          corePath = getBinaryPath();
-        } catch (_2) {
-          try {
-            const wrapper = require('../bin/wrapper');
-            corePath = wrapper.getBinaryPath ? wrapper.getBinaryPath() : null;
-          } catch (_3) {}
-        }
-      }
-
-      if (
-        !corePath &&
-        process.env.TRIBUNAL_CORE_PATH &&
-        fs.existsSync(process.env.TRIBUNAL_CORE_PATH)
-      ) {
-        corePath = process.env.TRIBUNAL_CORE_PATH;
-      }
-
-      if (corePath && fs.existsSync(corePath)) {
-        const result = require('child_process').execFileSync(corePath, ['ast-extract', '--file', absPath], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-        const data = JSON.parse(result);
-        if (data && data.success) {
-          // We map the Rust JSON into the exact format expected by the rest of the JS code
-          const mappedImports = data.imports.map(i => ({
-            source: i.source,
-            specifiers: i.specifiers,
-            line: 0,
-          }));
-          const mappedExports = data.exports.map(e => ({
-            kind: e.kind,
-            name: e.name,
-            signature: e.signature,
-            line: 0,
-          }));
-          const mappedTypes = data.types.map(t => ({
-            kind: t.kind,
-            name: t.name,
-            signature: t.signature,
-            line: 0,
-          }));
-
-          return {
-            imports: mappedImports,
-            exports: mappedExports,
-            types: mappedTypes,
-            landmines: data.landmines,
-            interfaceHash: computeInterfaceHash(mappedExports.concat(mappedTypes)),
-          };
-        }
-      }
-    } catch (_e) {
-      // Silent fallback to Regex parsing
-    }
-
-    lines.forEach((line, idx) => {
-      const trimmed = line.trim();
-
-      // Imports
-      const importMatch = trimmed.match(
-        /^import\s+(?:type\s+)?(?:(.+?)\s+from\s+)?['"]([^'"]+)['"]/,
-      );
-      if (importMatch) {
-        imports.push({
-          source: importMatch[2],
-          specifiers: importMatch[1] ? importMatch[1].trim() : '*',
-          line: idx + 1,
-        });
-      }
-      const requireMatch = trimmed.match(
-        /(?:const|let|var)\s+(.+?)\s*=\s*require\(['"]([^'"]+)['"]\)/,
-      );
-      if (requireMatch) {
-        imports.push({
-          source: requireMatch[2],
-          specifiers: requireMatch[1].trim(),
-          line: idx + 1,
-        });
-      }
-
-      // Exports
-      const exportFunc = trimmed.match(
-        /^export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)\s*(\(.*?\))/,
-      );
-      if (exportFunc) {
-        exports.push({
-          kind: 'function',
-          name: exportFunc[1],
-          signature: `function ${exportFunc[1]}${exportFunc[2]}`,
-          line: idx + 1,
-        });
-      }
-
-      const exportConst = trimmed.match(
-        /^export\s+const\s+(\w+)(?:\s*:\s*([^=]+))?\s*=\s*(?:async\s+)?(?:\((.*?)\)|(\w+))\s*=>/,
-      );
-      if (exportConst) {
-        exports.push({
-          kind: 'arrow_function',
-          name: exportConst[1],
-          signature: `const ${exportConst[1]}: (${exportConst[3] || exportConst[4] || ''}) => ...`,
-          line: idx + 1,
-        });
-      }
-
-      const exportClass = trimmed.match(
-        /^export\s+(?:default\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?/,
-      );
-      if (exportClass) {
-        exports.push({
-          kind: 'class',
-          name: exportClass[1],
-          signature: `class ${exportClass[1]}${exportClass[2] ? ' extends ' + exportClass[2] : ''}`,
-          line: idx + 1,
-        });
-      }
-
-      // Types & Interfaces
-      const exportType = trimmed.match(/^export\s+type\s+(\w+)(?:<.*?>)?\s*=/);
-      if (exportType) {
-        types.push({
-          kind: 'type',
-          name: exportType[1],
-          signature: trimmed.replace(/;?$/, ''),
-          line: idx + 1,
-        });
-      }
-
-      const exportInterface = trimmed.match(
-        /^export\s+interface\s+(\w+)(?:<.*?>)?(?:\s+extends\s+.*?)?\s*\{?/,
-      );
-      if (exportInterface) {
-        types.push({
-          kind: 'interface',
-          name: exportInterface[1],
-          signature: trimmed.replace(/\{?$/, '').trim(),
-          line: idx + 1,
-        });
-      }
-    });
-  } else if (ext === '.rs') {
-    lines.forEach((line, idx) => {
-      const trimmed = line.trim();
-
-      // Use statements
-      const useMatch = trimmed.match(/^(?:pub\s+)?use\s+([^;]+);/);
-      if (useMatch) {
-        imports.push({
-          source: useMatch[1].trim(),
-          specifiers: useMatch[1].trim(),
-          line: idx + 1,
-        });
-      }
-
-      // Public Functions
-      const pubFn = trimmed.match(
-        /^pub(?:\(.*?\))?\s+(?:async\s+)?fn\s+(\w+)(?:<.*?>)?\s*(\(.*?\))(?:\s*->\s*([^{;]+))?/,
-      );
-      if (pubFn) {
-        exports.push({
-          kind: 'function',
-          name: pubFn[1],
-          signature: `pub fn ${pubFn[1]}${pubFn[2]}${pubFn[3] ? ' -> ' + pubFn[3].trim() : ''}`,
-          line: idx + 1,
-        });
-      }
-
-      // Structs & Enums
-      const pubStruct = trimmed.match(/^pub(?:\(.*?\))?\s+struct\s+(\w+)/);
-      if (pubStruct) {
-        types.push({
-          kind: 'struct',
-          name: pubStruct[1],
-          signature: `pub struct ${pubStruct[1]}`,
-          line: idx + 1,
-        });
-      }
-
-      const pubEnum = trimmed.match(/^pub(?:\(.*?\))?\s+enum\s+(\w+)/);
-      if (pubEnum) {
-        types.push({
-          kind: 'enum',
-          name: pubEnum[1],
-          signature: `pub enum ${pubEnum[1]}`,
-          line: idx + 1,
-        });
-      }
-
-      const pubTrait = trimmed.match(/^pub(?:\(.*?\))?\s+trait\s+(\w+)/);
-      if (pubTrait) {
-        types.push({
-          kind: 'trait',
-          name: pubTrait[1],
-          signature: `pub trait ${pubTrait[1]}`,
-          line: idx + 1,
-        });
-      }
-    });
-  } else if (ext === '.py') {
-    lines.forEach((line, idx) => {
-      const trimmed = line.trim();
-
-      const importMatch = trimmed.match(/^(?:from\s+([\w.]+)\s+)?import\s+(.+)$/);
-      if (importMatch) {
-        imports.push({
-          source: importMatch[1] || importMatch[2],
-          specifiers: importMatch[2],
-          line: idx + 1,
-        });
-      }
-
-      const defMatch = trimmed.match(
-        /^(?:async\s+)?def\s+([a-zA-Z_]\w*)\s*(\(.*?\))(?:\s*->\s*([^:]+))?:/,
-      );
-      if (defMatch && !defMatch[1].startsWith('_')) {
-        exports.push({
-          kind: 'function',
-          name: defMatch[1],
-          signature: `def ${defMatch[1]}${defMatch[2]}${defMatch[3] ? ' -> ' + defMatch[3].trim() : ''}`,
-          line: idx + 1,
-        });
-      }
-
-      const classMatch = trimmed.match(/^class\s+([a-zA-Z_]\w*)(?:\((.*?)\))?:/);
-      if (classMatch && !classMatch[1].startsWith('_')) {
-        types.push({
-          kind: 'class',
-          name: classMatch[1],
-          signature: `class ${classMatch[1]}${classMatch[2] ? '(' + classMatch[2] + ')' : ''}`,
-          line: idx + 1,
-        });
-      }
-    });
-  }
-
-  const allSignatures = exports.concat(types);
-  const interfaceHash = computeInterfaceHash(allSignatures);
-
-  return {
-    imports,
-    exports,
-    types,
-    landmines,
-    interfaceHash,
-  };
-}
-
-// ── Inbound Callers Discovery ───────────────────────────────────────────────
-
-function findInboundCallers(targetFilePath, exportNames, workspaceRoot = process.cwd()) {
-  const callers = [];
-  const baseName = path.basename(targetFilePath);
-  const stem = baseName.replace(/\.[^.]+$/, '');
-  const relativeTarget = path.relative(workspaceRoot, targetFilePath).replace(/\\/g, '/');
-
-  // Search tokens: module stem and exported symbol names
-  const searchTokens = new Set([stem]);
-  exportNames.slice(0, 8).forEach(n => searchTokens.add(n));
-
-  // Try using git grep or ripgrep if available
-  // SECURITY: Use execFileSync with argument arrays to prevent OS command injection (CWE-78).
-  // The token is derived from the filename and may contain shell metacharacters like $(...).
-  // Using execFileSync bypasses the shell entirely, so no interpolation attack is possible.
-  const grepOutputs = [];
-  try {
-    const { execFileSync } = require('child_process');
-    for (const token of searchTokens) {
-      if (!token || token.length < 3) continue;
-      try {
-        const res = execFileSync('git', [
-          'grep', '-n', '-I', '-e', token, '--',
-          ':!docs/', ':!node_modules/', ':!src/', ':!target/', ':!*.lock'
-        ], {
-          cwd: workspaceRoot,
-          stdio: ['ignore', 'pipe', 'ignore'],
-          encoding: 'utf8',
-        });
-        if (res) grepOutputs.push(...res.split('\n').filter(Boolean));
-      } catch {
-        // Ripgrep fallback
-        try {
-          const res = execFileSync('rg', [
-            '-n', '--no-heading', '--color=never', '-e', token,
-            '-g', '!docs/**', '-g', '!node_modules/**', '-g', '!target/**', '-g', '!src/**'
-          ], {
-            cwd: workspaceRoot,
-            stdio: ['ignore', 'pipe', 'ignore'],
-            encoding: 'utf8',
-          });
-          if (res) grepOutputs.push(...res.split('\n').filter(Boolean));
-        } catch {
-          // Silent catch
-        }
-      }
-    }
-  } catch {
-    // Grep unavailable
-  }
-
-  const seenSites = new Set();
-
-  for (const line of grepOutputs) {
-    const parts = line.split(':');
-    if (parts.length < 3) continue;
-    const callerFile = parts[0].replace(/\\/g, '/');
-    const lineNum = parseInt(parts[1], 10);
-    const lineContent = parts.slice(2).join(':').trim();
-
-    // Ignore self-references and context docs
-    if (
-      callerFile === relativeTarget ||
-      callerFile.includes('.context.md') ||
-      callerFile.includes('INDEX.md')
-    ) {
-      continue;
-    }
-
-    const key = `${callerFile}:${lineNum}`;
-    if (seenSites.has(key)) continue;
-    seenSites.add(key);
-
-    callers.push({
-      file: callerFile,
-      line: lineNum,
-      snippet: lineContent.substring(0, 100),
-      isDirectImport:
-        lineContent.includes('import') ||
-        lineContent.includes('require') ||
-        lineContent.includes('use '),
-    });
-
-    if (callers.length >= 12) break; // Cap callers for token efficiency
-  }
-
-  return callers;
-}
-
-// ── Test & Skill Discovery ──────────────────────────────────────────────────
-
-function discoverTests(targetFilePath, workspaceRoot = process.cwd()) {
-  const tests = [];
-  const baseName = path.basename(targetFilePath);
-  const stem = baseName.replace(/\.[^.]+$/, '');
-
-  const testPatterns = [`${stem}.test.`, `${stem}.spec.`, `${stem}_test.`, `test_${stem}.`];
-
-  function walk(dir) {
-    if (!fs.existsSync(dir)) return;
-    try {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (
-          entry.name === 'node_modules' ||
-          entry.name === 'target' ||
-          entry.name === '.git' ||
-          entry.name === 'dist'
-        ) {
-          continue;
-        }
-        const full = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          // Only walk tests dirs or immediate directories
-          if (
-            entry.name === 'tests' ||
-            entry.name === '__tests__' ||
-            entry.name === 'test' ||
-            entry.name === 'crates'
-          ) {
-            walk(full);
-          }
-        } else if (entry.isFile()) {
-          for (const pat of testPatterns) {
-            if (entry.name.includes(pat)) {
-              tests.push(path.relative(workspaceRoot, full).replace(/\\/g, '/'));
-              break;
-            }
-          }
-        }
-      }
-    } catch {
-      // Ignore read errors
-    }
-  }
-
-  walk(workspaceRoot);
-  return Array.from(new Set(tests)).slice(0, 5);
-}
-
-function resolveSkills(targetFilePath, content) {
-  const skills = [];
-  const ext = path.extname(targetFilePath).toLowerCase();
-  const lowerContent = content.toLowerCase();
-
-  if (ext === '.rs') skills.push('rust-pro');
-  if (ext === '.py') skills.push('python-pro');
-  if (ext === '.ts' || ext === '.tsx' || ext === '.js') {
-    if (lowerContent.includes('react') || ext.endsWith('x')) skills.push('react-specialist');
-    else skills.push('clean-code');
-  }
-
-  if (
-    lowerContent.includes('auth') ||
-    lowerContent.includes('jwt') ||
-    lowerContent.includes('token') ||
-    lowerContent.includes('crypto')
-  ) {
-    skills.push('backend-security-expert');
-  }
-  if (
-    lowerContent.includes('query') ||
-    lowerContent.includes('prisma') ||
-    lowerContent.includes('sql') ||
-    lowerContent.includes('database')
-  ) {
-    skills.push('database-architect');
-  }
-  if (
-    lowerContent.includes('compress') ||
-    lowerContent.includes('tokens') ||
-    lowerContent.includes('prompt')
-  ) {
-    skills.push('context-engineering-pro');
-  }
-
-  skills.push('fabel-protocol');
-  return Array.from(new Set(skills));
-}
-
-function resolvePath(targetPath, workspaceRoot = process.cwd()) {
-  const clean = targetPath.replace(/^['"]|['"]$/g, '');
-  if (path.isAbsolute(clean) && fs.existsSync(clean)) return clean;
-
-  const direct = path.resolve(workspaceRoot, clean);
-  if (fs.existsSync(direct)) return direct;
-
-  if (clean.startsWith('tribunal-kit/') || clean.startsWith('tribunal-kit\\')) {
-    const stripped = clean.replace(/^tribunal-kit[/\\]/, '');
-    const strippedPath = path.resolve(workspaceRoot, stripped);
-    if (fs.existsSync(strippedPath)) return strippedPath;
-  }
-
-  const parentPath = path.resolve(workspaceRoot, '..', clean);
-  if (fs.existsSync(parentPath)) return parentPath;
-
-  return direct;
-}
-
-function getDocsDir(workspaceRoot = process.cwd()) {
-  const local = path.join(workspaceRoot, 'docs', 'context');
-  if (fs.existsSync(local)) {
-    try {
-      const files = fs
-        .readdirSync(local)
-        .filter(f => f.endsWith('.context.md') || f.endsWith('.bridge.md'));
-      if (files.length > 0) return local;
-    } catch {
-      // fallback
-    }
-  }
-  const parent = path.join(workspaceRoot, '..', 'docs', 'context');
-  if (fs.existsSync(parent)) {
-    try {
-      const files = fs
-        .readdirSync(parent)
-        .filter(f => f.endsWith('.context.md') || f.endsWith('.bridge.md'));
-      if (files.length > 0) return parent;
-    } catch {
-      // fallback
-    }
-  }
-  return local;
-}
-
-// ── Single-File Context Analysis ────────────────────────────────────────────
-
-function analyzeSingleFile(targetPath, workspaceRoot = process.cwd()) {
-  const absPath = resolvePath(targetPath, workspaceRoot);
-  if (!fs.existsSync(absPath)) {
-    throw new Error(`File not found: ${absPath}`);
-  }
-
-  const rawContent = fs.readFileSync(absPath, 'utf8');
-  const relativePath = path.relative(workspaceRoot, absPath).replace(/\\/g, '/');
-  const sourceHash = computeSha256(rawContent);
-  const skeleton = extractFileSkeleton(relativePath, rawContent);
-  const exportNames = skeleton.exports.map(e => e.name).concat(skeleton.types.map(t => t.name));
-  const callers = findInboundCallers(absPath, exportNames, workspaceRoot);
-  const tests = discoverTests(absPath, workspaceRoot);
-  const skills = resolveSkills(relativePath, rawContent);
-
-  // Determine domain layer
-  let domainLayer = 'Core Logic / Utility';
-  if (relativePath.includes('api') || relativePath.includes('route'))
-    domainLayer = 'API / Gateway Layer';
-  else if (relativePath.includes('service')) domainLayer = 'Service / Business Logic';
-  else if (
-    relativePath.includes('model') ||
-    relativePath.includes('schema') ||
-    relativePath.includes('db')
-  )
-    domainLayer = 'Data / Persistence Layer';
-  else if (relativePath.includes('components') || relativePath.includes('ui'))
-    domainLayer = 'UI / Presentation Layer';
-  else if (relativePath.includes('commands')) domainLayer = 'Command / Dispatch Layer';
-
-  return {
-    mode: 'single_file',
-    filePath: relativePath,
-    sourceHash,
-    interfaceHash: skeleton.interfaceHash,
-    domainLayer,
-    imports: skeleton.imports,
-    exports: skeleton.exports,
-    types: skeleton.types,
-    landmines: skeleton.landmines,
-    callers,
-    tests,
-    skills,
-    lineCount: rawContent.split('\n').length,
-    byteSize: Buffer.byteLength(rawContent, 'utf8'),
-  };
-}
-
-// ── Multi-File Interface Bridge Analysis ────────────────────────────────────
-
-function analyzeMultiFileBridge(pathA, pathB, workspaceRoot = process.cwd()) {
-  const metaA = analyzeSingleFile(pathA, workspaceRoot);
-  const metaB = analyzeSingleFile(pathB, workspaceRoot);
-
-  const aImportsB = metaA.imports.some(imp =>
-    imp.source.includes(path.basename(metaB.filePath).replace(/\.[^.]+$/, '')),
-  );
-  const bImportsA = metaB.imports.some(imp =>
-    imp.source.includes(path.basename(metaA.filePath).replace(/\.[^.]+$/, '')),
-  );
-
-  const sharedTypes = [];
-  const typeNamesA = new Set(metaA.types.map(t => t.name));
-  for (const t of metaB.types) {
-    if (typeNamesA.has(t.name)) sharedTypes.push(t.name);
-  }
-
-  return {
-    mode: 'multi_file_bridge',
-    fileA: metaA,
-    fileB: metaB,
-    coupling: {
-      aImportsB,
-      bImportsA,
-      sharedTypes,
-      relationship:
-        aImportsB && bImportsA
-          ? 'Bidirectional Coupling'
-          : aImportsB
-            ? 'A depends on B'
-            : bImportsA
-              ? 'B depends on A'
-              : 'Sibling / Peer Modules',
-    },
-  };
-}
-
-// ── Directory / Project Subsystem Analysis ──────────────────────────────────
-
-function analyzeDirectory(dirPath, workspaceRoot = process.cwd()) {
-  const absDir = path.isAbsolute(dirPath) ? dirPath : path.resolve(workspaceRoot, dirPath);
-  if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
-    throw new Error(`Directory not found: ${absDir}`);
-  }
-
-  const relativeDir = path.relative(workspaceRoot, absDir).replace(/\\/g, '/') || '.';
-  const manifests = [];
-  const subsystems = [];
-  let totalFiles = 0;
-  const langCounts = {};
-
-  const ignoreSet = new Set([
-    'node_modules',
-    'target',
-    '.git',
-    'dist',
-    'coverage',
-    '.gemini',
-    'build',
-  ]);
-
-  // Check top-level manifests
-  if (fs.existsSync(path.join(absDir, 'package.json'))) manifests.push('package.json');
-  if (fs.existsSync(path.join(absDir, 'Cargo.toml'))) manifests.push('Cargo.toml');
-  if (fs.existsSync(path.join(absDir, 'pyproject.toml'))) manifests.push('pyproject.toml');
-
-  const entries = fs.readdirSync(absDir, { withFileTypes: true });
-
-  for (const entry of entries) {
-    if (ignoreSet.has(entry.name) || entry.name.startsWith('.')) continue;
-    const subFull = path.join(absDir, entry.name);
-    if (entry.isDirectory()) {
-      try {
-        const subFiles = fs.readdirSync(subFull);
-        subsystems.push({
-          name: entry.name,
-          fileCount: subFiles.length,
-          keySample: subFiles.slice(0, 3).join(', '),
-        });
-      } catch {
-        // Ignore unreadable
-      }
-    } else if (entry.isFile()) {
-      totalFiles++;
-      const ext = path.extname(entry.name).toLowerCase() || 'other';
-      langCounts[ext] = (langCounts[ext] || 0) + 1;
-    }
-  }
-
-  return {
-    mode: 'directory_subsystem',
-    dirPath: relativeDir,
-    manifests,
-    subsystems,
-    directFiles: totalFiles,
-    langCounts,
-  };
-}
-
-// ── Markdown Dossier Generators ─────────────────────────────────────────────
-
-function renderSingleFileDossier(data) {
-  const callersTable =
-    data.callers.length > 0
-      ? data.callers
-          .map(
-            c =>
-              `| \`${c.file}:${c.line}\` | \`${c.snippet}\` | ${c.isDirectImport ? 'Direct Import' : 'Symbol Reference'} |`,
-          )
-          .join('\n')
-      : '| *None detected (potential root entrypoint or test)* | - | - |';
-
-  const typesTable =
-    data.exports.concat(data.types).length > 0
-      ? data.exports
-          .concat(data.types)
-          .slice(0, 10)
-          .map(s => `| \`${s.name}\` | \`${s.kind}\` | \`${s.signature}\` | Line ${s.line} |`)
-          .join('\n')
-      : '| *No explicit exported symbols detected* | - | - | - |';
-
-  const landminesContent =
-    data.landmines.length > 0
-      ? data.landmines.map(l => `> [!CAUTION]\n> **Line ${l.line}:** \`${l.content}\``).join('\n\n')
-      : '> [!NOTE]\n> No explicit defensive comments (`// VERIFY`, `// NOTE`, `// HACK`) found in source code.';
-
-  const testCommand = data.tests.length > 0 ? `npm test -- ${data.tests[0]}` : `npm test`;
-
-  return `---
-version: 2.0.0
-source_file: "${data.filePath}"
-source_hash: "${data.sourceHash}"
-interface_hash: "${data.interfaceHash}"
-last_synced: "${new Date().toISOString().split('T')[0]}"
-domain_layer: "${data.domainLayer}"
-associated_skills:
-${data.skills.map(s => `  - ${s}`).join('\n')}
-associated_tests:
-${data.tests.length > 0 ? data.tests.map(t => `  - ${t}`).join('\n') : '  - none'}
----
-
-<!-- AI_QUICK_INJECT_START -->
-> [!TIP]
-> **AI Prompt Injection Card (Copy into future prompts touching this file):**
-> \`\`\`yaml
-> Target: ${data.filePath} (${data.domainLayer})
-> Role: Core logic for ${path.basename(data.filePath)}.
-> Exports: [${data.exports
-    .map(e => e.name)
-    .slice(0, 6)
-    .join(', ')}]
-> Inbound Callers: ${data.callers.length} active consumer sites.
-> Invariant Check: Verify test passing before merge: ${testCommand}
-> \`\`\`
-<!-- AI_QUICK_INJECT_END -->
-
-# 🧭 FILE DOSSIER: \`${path.basename(data.filePath)}\`
-\`${data.filePath}\` • **${data.domainLayer}** • **Hash:** \`${data.sourceHash}\`
-
-| Freshness | Blast Radius | Exports Count | Test Coverage | Primary Callers |
-| :--- | :--- | :--- | :--- | :--- |
-| 🟢 **Fresh** (\`${data.sourceHash}\`) | **${data.callers.length} Callers** | **${data.exports.length} Symbols** | ${data.tests.length > 0 ? '✅ Linked (' + data.tests.length + ' files)' : '⚠️ Unlinked'} | \`${data.callers[0] ? data.callers[0].file : 'Entrypoint'}\` |
-
----
-
-## ⚡ 30-Second Mental Model
-> **Mission:** Implements ${data.domainLayer.toLowerCase()} responsibilities for \`${data.filePath}\`, exposing verified interfaces to callers while adhering to Tribunal safety standards.
-
----
-
-## 📋 Public API & Type Contract Matrix
-
-| Symbol | Kind | Signature | Location |
-| :--- | :--- | :--- | :--- |
-${typesTable}
-
----
-
-## 🔗 Blast Radius & Call Topology
-
-\`\`\`mermaid
-graph LR
-    classDef target fill:#1e293b,stroke:#3b82f6,stroke-width:2px,color:#fff;
-    classDef ext fill:#0f172a,stroke:#64748b,stroke-width:1px,color:#94a3b8;
-
-    subgraph Inbound Callers
-${
-  data.callers
-    .slice(0, 4)
-    .map((c, i) => `        C${i}["${c.file}"]:::ext`)
-    .join('\n') || '        C0["Entrypoint / CLI"]:::ext'
-}
-    end
-
-    T["${path.basename(data.filePath)}"]:::target
-
-    subgraph Dependencies
-${
-  data.imports
-    .slice(0, 4)
-    .map((imp, i) => `        D${i}["${imp.source}"]:::ext`)
-    .join('\n') || '        D0["Stdlib"]:::ext'
-}
-    end
-
-${
-  data.callers
-    .slice(0, 4)
-    .map((_, i) => `    C${i} --> T`)
-    .join('\n') || '    C0 --> T'
-}
-${
-  data.imports
-    .slice(0, 4)
-    .map((_, i) => `    T --> D${i}`)
-    .join('\n') || '    T --> D0'
-}
-\`\`\`
-
-### Inbound Consumer Sites
-| Caller File | Line Snippet | Vector |
-| :--- | :--- | :--- |
-${callersTable}
-
----
-
-## ⚠️ Chesterton's Fences & Non-Obvious Quirks
-
-${landminesContent}
-
----
-
-## 🧪 Verification & Test Harness
-
-\`\`\`bash
-# Run isolated tests for this module:
-${testCommand}
-\`\`\`
-`;
-}
-
-function renderBridgeDossier(data) {
-  return `---
-version: 2.0.0
-bridge: "${data.fileA.filePath} <--> ${data.fileB.filePath}"
-relationship: "${data.coupling.relationship}"
-last_synced: "${new Date().toISOString().split('T')[0]}"
----
-
-# 🌉 INTERFACE BRIDGE DOSSIER
-**Module A:** \`${data.fileA.filePath}\`  
-**Module B:** \`${data.fileB.filePath}\`  
-**Coupling Relationship:** \`${data.coupling.relationship}\`
-
----
-
-## 🗺️ Cross-Boundary Topology
-
-\`\`\`mermaid
-graph LR
-    A["${path.basename(data.fileA.filePath)}"]
-    B["${path.basename(data.fileB.filePath)}"]
-
-    ${data.coupling.aImportsB ? 'A -->|"Imports & Calls"| B' : ''}
-    ${data.coupling.bImportsA ? 'B -->|"Imports & Calls"| A' : ''}
-    ${!data.coupling.aImportsB && !data.coupling.bImportsA ? 'A -.->|"Sibling / Parallel"| B' : ''}
-\`\`\`
-
-## 📦 Shared Types & Interfaces
-${
-  data.coupling.sharedTypes.length > 0
-    ? data.coupling.sharedTypes.map(t => `- \`${t}\``).join('\n')
-    : '- *No identical type names detected between modules.*'
-}
-
-## 📋 Interface Alignment Summary
-- **${path.basename(data.fileA.filePath)} Exports:** ${data.fileA.exports.length} symbols.
-- **${path.basename(data.fileB.filePath)} Exports:** ${data.fileB.exports.length} symbols.
-`;
-}
-
-function renderDirectoryDossier(data) {
-  return `---
-version: 2.0.0
-target_dir: "${data.dirPath}"
-manifests: [${data.manifests.join(', ')}]
-last_synced: "${new Date().toISOString().split('T')[0]}"
----
-
-<!-- PROJECT_AI_ONBOARDING_CARD -->
-Project Subsystem: ${data.dirPath}
-Manifests: ${data.manifests.join(', ') || 'None'}
-Subsystems: ${data.subsystems.map(s => s.name).join(', ')}
-<!-- /PROJECT_AI_ONBOARDING_CARD -->
-
-# 🏛️ SUBSYSTEM DOSSIER: \`${data.dirPath}\`
-
-## 🗺️ Subsystem Architecture Clusters
-\`\`\`mermaid
-graph TD
-${data.subsystems.map(s => `    S_${s.name}["${s.name} (${s.fileCount} files)"]`).join('\n')}
-\`\`\`
-
-## 📂 Subsystem Breakdown
-| Subsystem Folder | File Count | Samples |
-| :--- | :--- | :--- |
-${data.subsystems.map(s => `| \`${s.name}/\` | ${s.fileCount} | \`${s.keySample}\` |`).join('\n')}
-`;
-}
-
-// ── Living Vault Manager ───────────────────────────────────────────────────
-
-function syncVaultIndex(workspaceRoot = process.cwd()) {
-  const docsDir = getDocsDir(workspaceRoot);
-  const indexFile = path.join(docsDir, 'INDEX.md');
-
-  if (!fs.existsSync(docsDir)) {
-    fs.mkdirSync(docsDir, { recursive: true });
-  }
-
-  const files = fs
-    .readdirSync(docsDir)
-    .filter(f => f.endsWith('.context.md') || f.endsWith('.bridge.md'));
-
-  const rows = [];
-  for (const f of files) {
-    const content = fs.readFileSync(path.join(docsDir, f), 'utf8');
-    const sourceMatch = content.match(/source_file:\s*["']?([^"'\n]+)/);
-    const bridgeMatch = content.match(/bridge:\s*["']?([^"'\n]+)/);
-    const dirMatch = content.match(/target_dir:\s*["']?([^"'\n]+)/);
-    const hashMatch = content.match(/source_hash:\s*["']?([^"'\n]+)/);
-    const domainMatch = content.match(/domain_layer:\s*["']?([^"'\n]+)/);
-
-    let source = f;
-    let domain = 'General';
-    const hash = hashMatch ? hashMatch[1] : 'n/a';
-    let status = '🟢 Fresh';
-
-    if (sourceMatch) {
-      source = sourceMatch[1].replace(/["']/g, '');
-      domain = domainMatch ? domainMatch[1].replace(/["']/g, '') : 'Single Module';
-      const absSource = resolvePath(source, workspaceRoot);
-      if (fs.existsSync(absSource)) {
-        const curHash = computeSha256(fs.readFileSync(absSource, 'utf8'));
-        if (curHash !== hash) {
-          status = '🔴 Stale';
-        }
-      } else {
-        status = '⚪ Missing';
-      }
-    } else if (bridgeMatch) {
-      source = bridgeMatch[1].replace(/["']/g, '');
-      domain = 'Interface Bridge';
-      status = '🟢 Linked';
-    } else if (dirMatch) {
-      source = dirMatch[1].replace(/["']/g, '');
-      domain = 'Subsystem Cluster';
-      const absDir = resolvePath(source, workspaceRoot);
-      status = fs.existsSync(absDir) ? '🟢 Active' : '⚪ Missing';
-    }
-
-    rows.push(`| [\`${source}\`](${f}) | ${domain} | \`${hash}\` | ${status} |`);
-  }
-
-  const indexContent = `# 📚 Codebase Context Vault Registry
-> Living architectural catalog generated and verified by \`/context\`.
-
-| Source Target | Domain Layer | Hash Snapshot | Status |
-| :--- | :--- | :--- | :--- |
-${rows.join('\n') || '| *No context dossiers generated yet. Run `/context <file>` to begin.* | - | - | - |'}
-
----
-*Run \`node scripts/context_compiler.js --check\` to audit context freshness across all files.*
-`;
-
-  fs.writeFileSync(indexFile, indexContent, 'utf8');
-  return { indexedCount: files.length, indexFile };
-}
-
-function checkDrift(workspaceRoot = process.cwd()) {
-  const syncRes = syncVaultIndex(workspaceRoot);
-  const content = fs.readFileSync(syncRes.indexFile, 'utf8');
-  const staleCount = (content.match(/🔴 Stale/g) || []).length;
-  const freshCount = (content.match(/🟢 Fresh/g) || []).length;
-
-  return {
-    total: syncRes.indexedCount,
-    fresh: freshCount,
-    stale: staleCount,
-    isHealthy: staleCount === 0,
-  };
-}
-
-// ── CLI Dispatcher ─────────────────────────────────────────────────────────
-
-function main() {
-  const args = process.argv.slice(2);
-  const workspaceRoot = process.cwd();
-
-  if (args.includes('--check')) {
-    const drift = checkDrift(workspaceRoot);
-    if (args.includes('--json')) {
-      console.log(JSON.stringify(drift));
-      process.exit(0);
-    }
-    console.log(`\n${C.BOLD}═══ Context Vault Drift Audit ═══${C.RESET}`);
-    console.log(`Total Dossiers: ${drift.total}`);
-    console.log(`🟢 Fresh:       ${drift.fresh}`);
-    console.log(`🔴 Stale:       ${drift.stale}`);
-    console.log(
-      `Status:         ${drift.isHealthy ? C.GREEN + 'HEALTHY' : C.RED + 'DRIFT DETECTED'}${C.RESET}\n`,
-    );
-    process.exit(drift.isHealthy ? 0 : 1);
-  }
-
-  let fileArg = null;
-  let dirArg = null;
-  let multiArgs = [];
-  const writeFlag = args.includes('--write');
-  const jsonFlag = args.includes('--json');
-
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--file' && args[i + 1]) {
-      fileArg = args[++i];
-    } else if (args[i] === '--dir' && args[i + 1]) {
-      dirArg = args[++i];
-    } else if (args[i] === '--multi' && args[i + 1] && args[i + 2]) {
-      multiArgs = [args[++i], args[++i]];
-    } else if (!args[i].startsWith('--')) {
-      if (!fileArg && !dirArg) {
-        // Autodetect positional arg
-        const candidate = args[i].replace(/^['"]|['"]$/g, '');
-        if (fs.existsSync(candidate)) {
-          if (fs.statSync(candidate).isDirectory()) {
-            dirArg = candidate;
-          } else {
-            fileArg = candidate;
-          }
-        }
-      }
-    }
-  }
-
-  if (multiArgs.length === 2) {
-    const result = analyzeMultiFileBridge(multiArgs[0], multiArgs[1], workspaceRoot);
-    if (jsonFlag) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const md = renderBridgeDossier(result);
-      if (writeFlag) {
-        const outName = `${path.basename(multiArgs[0]).replace(/\.[^.]+$/, '')}__${path.basename(multiArgs[1]).replace(/\.[^.]+$/, '')}.bridge.md`;
-        const dest = path.join(workspaceRoot, 'docs', 'context', outName);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, md, 'utf8');
-        syncVaultIndex(workspaceRoot);
-        console.log(`${C.GREEN}✔ Bridge Dossier written to ${dest}${C.RESET}`);
-      } else {
-        console.log(md);
-      }
-    }
-  } else if (dirArg) {
-    const result = analyzeDirectory(dirArg, workspaceRoot);
-    if (jsonFlag) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const md = renderDirectoryDossier(result);
-      if (writeFlag) {
-        const outName = `${path.basename(dirArg)}.context.md`;
-        const dest = path.join(workspaceRoot, 'docs', 'context', outName);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, md, 'utf8');
-        syncVaultIndex(workspaceRoot);
-        console.log(`${C.GREEN}✔ Directory Dossier written to ${dest}${C.RESET}`);
-      } else {
-        console.log(md);
-      }
-    }
-  } else if (fileArg) {
-    const result = analyzeSingleFile(fileArg, workspaceRoot);
-    if (jsonFlag) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      const md = renderSingleFileDossier(result);
-      if (writeFlag) {
-        const outName = `${path.basename(fileArg).replace(/\.[^.]+$/, '')}.context.md`;
-        const dest = path.join(workspaceRoot, 'docs', 'context', outName);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, md, 'utf8');
-        syncVaultIndex(workspaceRoot);
-        console.log(`${C.GREEN}✔ Single-File Dossier written to ${dest}${C.RESET}`);
-      } else {
-        console.log(md);
-      }
-    }
-  } else {
-    console.error(
-      `${C.RED}Error: Provide --file <path>, --dir <path>, --multi <fileA> <fileB>, or --check${C.RESET}`,
-    );
-    process.exit(1);
-  }
-}
-
-// Export functions for in-process MCP server use
-module.exports = {
-  analyzeSingleFile,
-  analyzeMultiFileBridge,
-  analyzeDirectory,
-  renderSingleFileDossier,
-  renderBridgeDossier,
-  renderDirectoryDossier,
-  syncVaultIndex,
-  checkDrift,
-};
-
-if (require.main === module) {
-  main();
-}