@codeledger/cli 0.6.9 → 0.7.0

package/dist/commands/context.js

@@ -0,0 +1,687 @@
+/**
+ * context — DCOL v2 context introspection subcommand
+ *
+ * Subcommands:
+ *   explain   Why each file/symbol was selected
+ *   diff      Show context change between two bundle iterations
+ *   graph     Output Mermaid dependency diagram
+ *   validate  Run execution-aware context validation
+ *
+ * Usage:
+ *   codeledger context explain [--bundle <path>] [--json]
+ *   codeledger context diff [--from <bundle-id>] [--to <bundle-id>] [--json]
+ *   codeledger context graph [--bundle <path>] [--output <path>]
+ *   codeledger context validate [--bundle <path>] [--json]
+ */
+import { readFileSync, existsSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { computeCcs, loadEntries, historicalSuccessContext, checkIntentSufficiency } from '@codeledger/engine';
+// ─── Entry Point ─────────────────────────────────────────────────────────────
+export async function runContext(cwd, flags) {
+    const sub = flags['_sub'] ?? 'explain';
+    switch (sub) {
+        case 'explain':
+            return runContextExplain(cwd, flags);
+        case 'diff':
+            return runContextDiff(cwd, flags);
+        case 'graph':
+            return runContextGraph(cwd, flags);
+        case 'validate':
+            return runContextValidate(cwd, flags);
+        default:
+            console.error(`❌ Unknown context subcommand: ${sub}`);
+            console.error(`   Valid: explain | diff | graph | validate`);
+            process.exit(1);
+    }
+}
+// ─── context explain ─────────────────────────────────────────────────────────
+async function runContextExplain(cwd, flags) {
+    const bundle = loadBundle(cwd, flags['bundle']);
+    if (!bundle)
+        return;
+    const jsonMode = flags['json'] === 'true';
+    if (jsonMode) {
+        console.log(JSON.stringify(buildExplainPayload(bundle), null, 2));
+        return;
+    }
+    console.log(`\n📋 Context Explanation — Bundle ${bundle.bundle_id}\n`);
+    console.log(`   Task: ${bundle.task}`);
+    console.log(`   Files: ${bundle.files.length}   Tokens: ${bundle.total_tokens.toLocaleString()}`);
+    if (bundle.confidence) {
+        const c = bundle.confidence;
+        console.log(`   Confidence: ${c.level.toUpperCase()} (${(c.score * 100).toFixed(0)}%)`);
+    }
+    console.log('');
+    for (const file of bundle.files) {
+        const reasons = file.reasons.join(', ');
+        const score = file.score.toFixed(3);
+        const tokens = file.token_estimate?.toLocaleString() ?? '—';
+        const stub = file.is_stub ? ' [stub]' : '';
+        const exemplar = file.is_exemplar ? ' [exemplar]' : '';
+        const shadow = file.shadow_reason ? ` [shadow affinity=${file.shadow_reason.affinity.toFixed(2)}]` : '';
+        console.log(`  ${score}  ${file.path}${stub}${exemplar}${shadow}`);
+        console.log(`         reasons: ${reasons}   tokens: ${tokens}`);
+        // Feature breakdown (if explain data present)
+        if (bundle.explain?.[file.path]) {
+            const f = bundle.explain[file.path];
+            const parts = [];
+            if (f.keyword > 0)
+                parts.push(`keyword=${f.keyword.toFixed(2)}`);
+            if (f.centrality > 0)
+                parts.push(`centrality=${f.centrality.toFixed(2)}`);
+            if (f.churn > 0)
+                parts.push(`churn=${f.churn.toFixed(2)}`);
+            if (f.recent_touch > 0)
+                parts.push(`recent_touch=${f.recent_touch.toFixed(2)}`);
+            if (f.test_relevance > 0)
+                parts.push(`test=${f.test_relevance.toFixed(2)}`);
+            if (f.error_infrastructure > 0)
+                parts.push(`error_infra=${f.error_infrastructure.toFixed(2)}`);
+            if (f.branch_changed > 0)
+                parts.push(`branch=${f.branch_changed.toFixed(2)}`);
+            if (f.security_surface > 0)
+                parts.push(`security=${f.security_surface.toFixed(2)}`);
+            if (parts.length > 0) {
+                console.log(`         features: ${parts.join('  ')}`);
+            }
+        }
+        console.log('');
+    }
+    if (bundle.near_misses && bundle.near_misses.length > 0) {
+        console.log(`  Near-misses (files that almost made the cut):`);
+        for (const nm of bundle.near_misses.slice(0, 5)) {
+            console.log(`    ${nm.score.toFixed(3)}  ${nm.path}  [gap: ${nm.budget_gap_tokens} tokens]`);
+            if (nm.suggestion)
+                console.log(`           → ${nm.suggestion}`);
+        }
+        console.log('');
+    }
+}
+function buildExplainPayload(bundle) {
+    return {
+        bundle_id: bundle.bundle_id,
+        task: bundle.task,
+        total_files: bundle.files.length,
+        total_tokens: bundle.total_tokens,
+        confidence: bundle.confidence,
+        files: bundle.files.map((f) => ({
+            path: f.path,
+            score: f.score,
+            reasons: f.reasons,
+            token_estimate: f.token_estimate,
+            is_stub: f.is_stub,
+            is_exemplar: f.is_exemplar,
+            features: bundle.explain?.[f.path],
+            shadow_reason: f.shadow_reason,
+        })),
+        near_misses: bundle.near_misses,
+    };
+}
+// ─── context diff ─────────────────────────────────────────────────────────────
+async function runContextDiff(cwd, flags) {
+    const jsonMode = flags['json'] === 'true';
+    // Load two bundles for comparison
+    const fromId = flags['from'];
+    const toId = flags['to'];
+    const artifactsDir = join(cwd, '.codeledger', 'artifacts');
+    const bundlesDir = join(artifactsDir, 'bundles');
+    let fromBundle = null;
+    let toBundle = null;
+    if (fromId) {
+        // Try bundles/ subdirectory first, then artifacts/ root
+        const p1 = join(bundlesDir, `${fromId}.json`);
+        const p2 = join(artifactsDir, `${fromId}.json`);
+        const p = existsSync(p1) ? p1 : p2;
+        fromBundle = existsSync(p)
+            ? JSON.parse(readFileSync(p, 'utf-8'))
+            : null;
+    }
+    // Default: compare previous vs current active bundle
+    const activeBundlePath = join(cwd, '.codeledger', 'active-bundle.md');
+    // Look in bundles/ subdirectory first, fall back to artifacts/ root
+    const bundlesDirResult = loadLatestBundles(bundlesDir, 2);
+    const bundleArtifacts = bundlesDirResult.length >= 2
+        ? bundlesDirResult
+        : loadLatestBundles(artifactsDir, 2);
+    if (!fromBundle && bundleArtifacts.length >= 2) {
+        fromBundle = bundleArtifacts[bundleArtifacts.length - 2] ?? null;
+    }
+    if (!toBundle) {
+        if (toId) {
+            const p1 = join(bundlesDir, `${toId}.json`);
+            const p2 = join(artifactsDir, `${toId}.json`);
+            const p = existsSync(p1) ? p1 : p2;
+            toBundle = existsSync(p)
+                ? JSON.parse(readFileSync(p, 'utf-8'))
+                : null;
+        }
+        else {
+            toBundle = bundleArtifacts[bundleArtifacts.length - 1] ?? null;
+        }
+    }
+    if (!fromBundle || !toBundle) {
+        console.error('❌ Need two bundles to diff. Use --from <id> --to <id> or generate 2+ bundles first.');
+        if (!existsSync(activeBundlePath)) {
+            console.error('   No active bundle found. Run: codeledger activate --task "..."');
+        }
+        process.exit(1);
+    }
+    const diff = computeContextDiff(fromBundle, toBundle);
+    if (jsonMode) {
+        console.log(JSON.stringify(diff, null, 2));
+        return;
+    }
+    console.log(`\n📊 Context Diff\n`);
+    console.log(`   From: ${diff.from_bundle_id}  →  To: ${diff.to_bundle_id}`);
+    const sign = diff.token_delta >= 0 ? '+' : '';
+    console.log(`   Token delta: ${sign}${diff.token_delta.toLocaleString()}\n`);
+    if (diff.added.length > 0) {
+        console.log(`  ✅ Added to context (${diff.added.length}):`);
+        for (const f of diff.added)
+            console.log(`     + ${f}`);
+        console.log('');
+    }
+    if (diff.removed.length > 0) {
+        console.log(`  ❌ Removed from context (${diff.removed.length}):`);
+        for (const f of diff.removed)
+            console.log(`     - ${f}`);
+        console.log('');
+    }
+    if (diff.score_changed.length > 0) {
+        console.log(`  📈 Score changed (${diff.score_changed.length}):`);
+        for (const sc of diff.score_changed) {
+            const delta = sc.to_score - sc.from_score;
+            const sign2 = delta >= 0 ? '+' : '';
+            console.log(`     ~ ${sc.path}  ${sc.from_score.toFixed(3)} → ${sc.to_score.toFixed(3)} (${sign2}${delta.toFixed(3)})`);
+        }
+        console.log('');
+    }
+    if (diff.added.length === 0 && diff.removed.length === 0 && diff.score_changed.length === 0) {
+        console.log('  ✓ No changes between bundles.');
+    }
+}
+function computeContextDiff(from, to) {
+    const fromPaths = new Set(from.files.map((f) => f.path));
+    const toPaths = new Set(to.files.map((f) => f.path));
+    const fromScores = new Map(from.files.map((f) => [f.path, f.score]));
+    const toScores = new Map(to.files.map((f) => [f.path, f.score]));
+    const added = to.files.filter((f) => !fromPaths.has(f.path)).map((f) => f.path);
+    const removed = from.files.filter((f) => !toPaths.has(f.path)).map((f) => f.path);
+    const scoreChanged = [];
+    for (const path of fromPaths) {
+        if (toPaths.has(path)) {
+            const fromScore = fromScores.get(path) ?? 0;
+            const toScore = toScores.get(path) ?? 0;
+            if (Math.abs(toScore - fromScore) > 0.005) {
+                scoreChanged.push({ path, from_score: fromScore, to_score: toScore });
+            }
+        }
+    }
+    scoreChanged.sort((a, b) => Math.abs(b.to_score - b.from_score) - Math.abs(a.to_score - a.from_score));
+    return {
+        from_bundle_id: from.bundle_id,
+        to_bundle_id: to.bundle_id,
+        added,
+        removed,
+        score_changed: scoreChanged,
+        token_delta: to.total_tokens - from.total_tokens,
+        generated_at: new Date().toISOString(),
+    };
+}
+// ─── context graph ────────────────────────────────────────────────────────────
+async function runContextGraph(cwd, flags) {
+    const bundle = loadBundle(cwd, flags['bundle']);
+    if (!bundle)
+        return;
+    const outputPath = flags['output'];
+    const graph = buildMermaidGraph(bundle, cwd);
+    if (outputPath) {
+        writeFileSync(outputPath, graph.markup, 'utf-8');
+        console.log(`✅ Mermaid diagram written to: ${outputPath}`);
+        console.log(`   Nodes: ${graph.included_files.length} files`);
+        return;
+    }
+    console.log(`\n🗂  Context Dependency Graph — Bundle ${bundle.bundle_id}\n`);
+    console.log('```mermaid');
+    console.log(graph.markup);
+    console.log('```');
+    console.log(`\n   Files: ${graph.included_files.length}`);
+    console.log('   Paste the above into https://mermaid.live to visualize.\n');
+}
+function buildMermaidGraph(bundle, _cwd) {
+    const files = bundle.files.map((f) => f.path);
+    const relationships = bundle.file_relationships ?? [];
+    // Shorten paths for readability
+    const shortName = (p) => {
+        const parts = p.split('/');
+        return parts.slice(-2).join('/').replace(/\.[tj]sx?$/, '');
+    };
+    // Assign layers
+    const layerOf = (p) => {
+        if (/\.(test|spec)\.[tj]sx?$/.test(p))
+            return 'tests';
+        if (/\/types?(\/|$)/.test(p) || p.endsWith('.d.ts'))
+            return 'types';
+        if (/\/models?(\/|$)/.test(p) || /\.(schema|entity|model)\.[tj]sx?$/.test(p))
+            return 'models';
+        if (/\/routes?(\/|$)/.test(p) || /\.(route|handler|controller)\.[tj]sx?$/.test(p))
+            return 'routes';
+        if (/\/services?(\/|$)/.test(p) || /\.service\.[tj]sx?$/.test(p))
+            return 'services';
+        if (/\/config(\/|$)/.test(p) || /\.(config|env)\.[tj]sx?$/.test(p))
+            return 'config';
+        return 'unknown';
+    };
+    // Group files by layer for subgraph
+    const byLayer = new Map();
+    for (const f of files) {
+        const layer = layerOf(f);
+        const existing = byLayer.get(layer) ?? [];
+        existing.push(f);
+        byLayer.set(layer, existing);
+    }
+    // Build node ID map (sanitize for Mermaid)
+    const nodeId = (p) => p.replace(/[^a-zA-Z0-9]/g, '_').replace(/__+/g, '_');
+    const lines = ['flowchart TD'];
+    // Subgraphs per layer
+    const layerOrder = ['types', 'models', 'services', 'routes', 'tests', 'config', 'unknown'];
+    for (const layer of layerOrder) {
+        const layerFiles = byLayer.get(layer);
+        if (!layerFiles || layerFiles.length === 0)
+            continue;
+        lines.push(`  subgraph ${layer}`);
+        for (const f of layerFiles) {
+            const id = nodeId(f);
+            const label = shortName(f);
+            // High-score files get a highlighted style
+            const file = bundle.files.find((bf) => bf.path === f);
+            const style = (file?.score ?? 0) >= 0.7 ? `["🔥 ${label}"]` : `["${label}"]`;
+            lines.push(`    ${id}${style}`);
+        }
+        lines.push('  end');
+    }
+    // Edges from file_relationships
+    const fileSet = new Set(files);
+    for (const rel of relationships) {
+        if (fileSet.has(rel.from) && fileSet.has(rel.to)) {
+            lines.push(`  ${nodeId(rel.from)} --> ${nodeId(rel.to)}`);
+        }
+    }
+    return {
+        diagram_type: 'flowchart',
+        markup: lines.join('\n'),
+        included_files: files,
+        generated_at: new Date().toISOString(),
+    };
+}
+// ─── context validate ─────────────────────────────────────────────────────────
+async function runContextValidate(cwd, flags) {
+    const bundle = loadBundle(cwd, flags['bundle']);
+    if (!bundle)
+        return;
+    const jsonMode = flags['json'] === 'true';
+    const forceMode = flags['force'] === 'true';
+    // ── ISC — Intent Sufficiency Check (PRE-CONTEXT gate) ─────────────────────
+    const taskText = flags['task'] ?? bundle.task ?? '';
+    const isc = checkIntentSufficiency(taskText);
+    const iscBlocked = isc.decision === 'INSUFFICIENT' && !forceMode;
+    if (jsonMode) {
+        if (iscBlocked) {
+            console.log(JSON.stringify({ isc, ccs: null, validation: null, forced: false }, null, 2));
+            process.exit(1);
+            return;
+        }
+    }
+    else {
+        printIscSummary(isc, forceMode);
+        if (iscBlocked) {
+            process.exit(1);
+            return;
+        }
+    }
+    // ── Structural validation ─────────────────────────────────────────────────
+    const result = validateContextBundle(bundle, cwd);
+    // ── CCS — Context Confidence Score ────────────────────────────────────────
+    const taskKeywords = extractTaskKeywords(bundle, taskText);
+    const expansionLevel = parseInt(flags['expansion-level'] ?? '1', 10);
+    const ledgerEntries = loadEntries(cwd);
+    const intentSig = bundle.bundle_intent_hash ?? '';
+    const { rate: histRate, sampleSize } = historicalSuccessContext(ledgerEntries, intentSig);
+    // WEAK ISC applies a -0.05 CCS penalty via intentConfidence
+    const iscIntentConfidence = isc.decision === 'WEAK' ? Math.max(0, isc.score - 0.05) : isc.score;
+    const ccs = computeCcs({
+        bundle,
+        taskKeywords,
+        expansionLevel: isNaN(expansionLevel) ? 1 : expansionLevel,
+        historicalSuccessRate: histRate,
+        historySampleSize: sampleSize,
+        intentConfidence: iscIntentConfidence,
+    });
+    // Determine final gate decision (--force overrides BLOCK)
+    const blocked = !result.passed || ccs.recommendation === 'block';
+    const shouldExit = blocked && !forceMode;
+    if (jsonMode) {
+        console.log(JSON.stringify({ isc, validation: result, ccs, forced: forceMode && blocked }, null, 2));
+        if (shouldExit)
+            process.exit(1);
+        return;
+    }
+    const validIcon = result.passed ? '✅' : '❌';
+    console.log(`\n${validIcon} Context Validation — Bundle ${bundle.bundle_id}\n`);
+    // ── CCS Summary ────────────────────────────────────────────────────────────
+    printCcsSummary(ccs, forceMode);
+    // ── Validation Issues ──────────────────────────────────────────────────────
+    if (result.issues.length === 0) {
+        console.log('   No structural issues found.\n');
+    }
+    else {
+        const errors = result.issues.filter((i) => i.severity === 'error');
+        const warnings = result.issues.filter((i) => i.severity === 'warning');
+        const infos = result.issues.filter((i) => i.severity === 'info');
+        if (errors.length > 0) {
+            console.log(`  Errors (${errors.length}):`);
+            for (const e of errors)
+                printIssue(e, '  ❌');
+        }
+        if (warnings.length > 0) {
+            console.log(`  Warnings (${warnings.length}):`);
+            for (const w of warnings)
+                printIssue(w, '  ⚠️');
+        }
+        if (infos.length > 0) {
+            console.log(`  Info (${infos.length}):`);
+            for (const i of infos)
+                printIssue(i, '  ℹ️');
+        }
+        console.log('');
+    }
+    if (result.missing_dependencies.length > 0) {
+        console.log(`  Missing dependencies (files not in context):`);
+        for (const d of result.missing_dependencies)
+            console.log(`    • ${d}`);
+        console.log('');
+    }
+    if (result.uncovered_files.length > 0) {
+        console.log(`  Files without test coverage:`);
+        for (const f of result.uncovered_files)
+            console.log(`    • ${f}`);
+        console.log('');
+    }
+    if (result.boundary_violations.length > 0) {
+        console.log(`  Architecture boundary violations:`);
+        for (const v of result.boundary_violations) {
+            console.log(`    ${v.from} → ${v.to}: ${v.reason}`);
+        }
+        console.log('');
+    }
+    if (shouldExit)
+        process.exit(1);
+}
+function printIscSummary(isc, forced = false) {
+    const icon = isc.decision === 'SUFFICIENT'
+        ? '🟢'
+        : isc.decision === 'WEAK'
+            ? '🟡'
+            : forced
+                ? '🔴'
+                : '🔴';
+    const pct = (isc.score * 100).toFixed(0);
+    const decisionLabel = isc.decision === 'INSUFFICIENT' && forced
+        ? 'INSUFFICIENT (overridden by --force)'
+        : isc.decision;
+    console.log(`  ── Intent Sufficiency Check (ISC) ───────────────────────`);
+    console.log(`  ${icon} Score: ${pct}%  Decision: ${decisionLabel}`);
+    const f = isc.factors;
+    console.log(`     token signal     : ${(f.tokenSignalScore * 100).toFixed(0)}%` +
+        (isc.detectedOperation ? `   op: ${isc.detectedOperation}` : ''));
+    console.log(`     operation clarity: ${(f.operationClarityScore * 100).toFixed(0)}%` +
+        (isc.detectedDomain ? `   domain: ${isc.detectedDomain}` : ''));
+    console.log(`     domain clarity   : ${(f.domainClarityScore * 100).toFixed(0)}%`);
+    console.log(`     target specificity: ${(f.targetSpecificityScore * 100).toFixed(0)}%` +
+        (isc.detectedTargets && isc.detectedTargets.length > 0
+            ? `   targets: ${isc.detectedTargets.slice(0, 3).join(', ')}`
+            : ''));
+    console.log(`     constraint present: ${(f.constraintPresenceScore * 100).toFixed(0)}%`);
+    if (isc.issues.length > 0) {
+        console.log(`\n  ISC issues:`);
+        for (const issue of isc.issues)
+            console.log(`    • ${issue}`);
+    }
+    if (isc.decision === 'INSUFFICIENT' && !forced) {
+        console.log(`\n  Context construction blocked. Improve your task prompt:`);
+        for (const rec of isc.recommendations)
+            console.log(`    → ${rec}`);
+        console.log(`\n  Use --force to bypass this gate.\n`);
+    }
+    else if (isc.decision === 'WEAK') {
+        console.log(`\n  Weak intent: CCS receives a -0.05 penalty. Consider refining your prompt:`);
+        for (const rec of isc.recommendations)
+            console.log(`    → ${rec}`);
+    }
+    console.log('');
+}
+function printCcsSummary(ccs, forced = false) {
+    const pct = (ccs.score * 100).toFixed(0);
+    const levelIcon = ccs.level === 'high' ? '🟢' : ccs.level === 'medium' ? '🟡' : '🔴';
+    const decisionLabel = {
+        proceed: 'PROCEED',
+        expand: `EXPAND → suggest Level ${ccs.suggestedExpansionLevel ?? '?'}`,
+        block: forced ? 'BLOCK (overridden by --force)' : 'BLOCK',
+    };
+    console.log(`  ── Context Confidence Score (CCS) ──────────────────────`);
+    console.log(`  ${levelIcon} Score: ${pct}%  Decision: ${decisionLabel[ccs.recommendation] ?? ccs.recommendation.toUpperCase()}`);
+    console.log(`     dep coverage  : ${(ccs.factors.dependencyCoverage * 100).toFixed(0)}%`);
+    console.log(`     test coverage : ${(ccs.factors.testCoverageMapping * 100).toFixed(0)}%`);
+    // Historical confidence: show sample size + effective weight
+    const histPct = (ccs.factors.historicalSuccessRate * 100).toFixed(0);
+    const weightPct = (ccs.factors.adjustedHistoricalWeight * 100 / 0.20).toFixed(0); // as % of max
+    const sampleLabel = ccs.factors.historySampleSize === 0
+        ? 'no data'
+        : `${ccs.factors.historySampleSize} entries, weight ${weightPct}% of full`;
+    console.log(`     hist success  : ${histPct}%  (${sampleLabel})`);
+    console.log(`     symbol comp.  : ${(ccs.factors.symbolCompleteness * 100).toFixed(0)}%`);
+    console.log(`     expansion eff.: ${(100 - ccs.factors.expansionLevelPenalty * 100 / 0.3).toFixed(0)}%`);
+    if (ccs.issues.length > 0) {
+        console.log(`\n  CCS issues:`);
+        for (const issue of ccs.issues)
+            console.log(`    • ${issue}`);
+    }
+    console.log('');
+}
+/** Extract task keywords from bundle task description or explicit --task flag. */
+function extractTaskKeywords(bundle, taskOverride) {
+    const raw = taskOverride || bundle.task || '';
+    if (!raw)
+        return [];
+    // Simple tokenization: split on whitespace, strip punctuation, keep ≥3 chars
+    return raw
+        .toLowerCase()
+        .split(/\s+/)
+        .map((t) => t.replace(/[^a-z0-9_-]/g, ''))
+        .filter((t) => t.length >= 3);
+}
+function printIssue(issue, prefix) {
+    const location = issue.file ? ` [${issue.file}${issue.symbol ? `::${issue.symbol}` : ''}]` : '';
+    console.log(`  ${prefix} [${issue.code}]${location}: ${issue.message}`);
+}
+function validateContextBundle(bundle, cwd) {
+    const issues = [];
+    const missingDependencies = [];
+    const uncoveredFiles = [];
+    const boundaryViolations = [];
+    const bundlePaths = new Set(bundle.files.map((f) => f.path));
+    // 1. Check for missing dependencies (imported files not in bundle)
+    if (bundle.file_relationships) {
+        for (const rel of bundle.file_relationships) {
+            if (!bundlePaths.has(rel.to)) {
+                missingDependencies.push(rel.to);
+                issues.push({
+                    code: 'MISSING_DEP',
+                    severity: 'warning',
+                    message: `Dependency ${rel.to} is imported but not in context`,
+                    file: rel.from,
+                });
+            }
+        }
+    }
+    // 2. Check for files without test coverage
+    const testMap = bundle.files.filter((f) => f.path.match(/\.(test|spec)\.[tj]sx?$/));
+    const testedSources = new Set();
+    for (const t of testMap) {
+        // Infer source from test file name
+        const source = t.path.replace(/\.(test|spec)\./, '.').replace(/\/__tests__\//, '/');
+        testedSources.add(source);
+    }
+    for (const f of bundle.files) {
+        if (!f.path.match(/\.(test|spec)\.[tj]sx?$/) && !f.is_stub && !f.is_exemplar) {
+            if (!testedSources.has(f.path) && !f.reasons.includes('test_relevant')) {
+                uncoveredFiles.push(f.path);
+            }
+        }
+    }
+    if (uncoveredFiles.length > bundle.files.length * 0.5) {
+        issues.push({
+            code: 'LOW_TEST_COVERAGE',
+            severity: 'warning',
+            message: `${uncoveredFiles.length}/${bundle.files.length} context files have no linked tests`,
+        });
+    }
+    // 3. Check token budget
+    const maxTokens = 16000;
+    if (bundle.total_tokens > maxTokens) {
+        issues.push({
+            code: 'BUDGET_EXCEEDED',
+            severity: 'warning',
+            message: `Context is ${bundle.total_tokens.toLocaleString()} tokens (recommend ≤ ${maxTokens.toLocaleString()})`,
+        });
+    }
+    // 4. Check confidence (if available)
+    if (bundle.confidence && bundle.confidence.level === 'low') {
+        issues.push({
+            code: 'LOW_CONFIDENCE',
+            severity: 'warning',
+            message: `Bundle confidence is LOW (${(bundle.confidence.score * 100).toFixed(0)}%). Consider running with --expand.`,
+        });
+    }
+    // 5. Check for architecture boundary violations
+    // (test files importing from non-test files at the wrong layer)
+    const layerOf = (p) => {
+        if (/\.(test|spec)\.[tj]sx?$/.test(p))
+            return 'tests';
+        if (/\/types?(\/|$)/.test(p))
+            return 'types';
+        if (/\/routes?(\/|$)/.test(p))
+            return 'routes';
+        if (/\/services?(\/|$)/.test(p))
+            return 'services';
+        return 'impl';
+    };
+    if (bundle.file_relationships) {
+        for (const rel of bundle.file_relationships) {
+            const fromLayer = layerOf(rel.from);
+            const toLayer = layerOf(rel.to);
+            // Routes should not import from tests
+            if (fromLayer === 'routes' && toLayer === 'tests') {
+                boundaryViolations.push({
+                    from: rel.from,
+                    to: rel.to,
+                    reason: 'Route file imports from test file',
+                });
+            }
+        }
+    }
+    // 6. Check for stale/addressed files
+    if (bundle.addressed_files && bundle.addressed_files.length > 0) {
+        const ratio = bundle.addressed_files.length / bundle.files.length;
+        if (ratio > 0.5) {
+            issues.push({
+                code: 'STALE_BUNDLE',
+                severity: 'info',
+                message: `${bundle.addressed_files.length} of ${bundle.files.length} bundle files have been committed. Consider refreshing: codeledger activate --task "..."`,
+            });
+        }
+    }
+    // Read existence checks only if cwd is provided
+    if (cwd) {
+        for (const f of bundle.files) {
+            const abs = join(cwd, f.path);
+            if (!existsSync(abs)) {
+                issues.push({
+                    code: 'FILE_NOT_FOUND',
+                    severity: 'error',
+                    message: `Bundle file no longer exists on disk`,
+                    file: f.path,
+                });
+            }
+        }
+    }
+    const hasErrors = issues.some((i) => i.severity === 'error');
+    return {
+        passed: !hasErrors,
+        issues,
+        missing_dependencies: [...new Set(missingDependencies)],
+        uncovered_files: uncoveredFiles,
+        boundary_violations: boundaryViolations,
+        validated_at: new Date().toISOString(),
+    };
+}
+// ─── Shared Utilities ─────────────────────────────────────────────────────────
+function loadBundle(cwd, bundlePath) {
+    // If explicit path provided
+    if (bundlePath) {
+        if (!existsSync(bundlePath)) {
+            console.error(`❌ Bundle file not found: ${bundlePath}`);
+            process.exit(1);
+        }
+        try {
+            return JSON.parse(readFileSync(bundlePath, 'utf-8'));
+        }
+        catch {
+            console.error(`❌ Failed to parse bundle: ${bundlePath}`);
+            process.exit(1);
+        }
+    }
+    // Try latest artifact in .codeledger/artifacts/bundles/ then artifacts/
+    const artifactsDir = join(cwd, '.codeledger', 'artifacts');
+    const bundlesDir = join(artifactsDir, 'bundles');
+    const bundlesDirResult = loadLatestBundles(bundlesDir, 1);
+    const bundles = bundlesDirResult.length > 0
+        ? bundlesDirResult
+        : loadLatestBundles(artifactsDir, 1);
+    if (bundles.length > 0)
+        return bundles[0];
+    // Try active-bundle.md (extract JSON if present)
+    const activePath = join(cwd, '.codeledger', 'active-bundle.md');
+    if (!existsSync(activePath)) {
+        console.error('❌ No active bundle found. Run: codeledger activate --task "..."');
+        process.exit(1);
+    }
+    console.error('⚠️  Active bundle is in Markdown format. Use --bundle <json-path> for full data.');
+    console.error('   JSON bundles are written to .codeledger/artifacts/bundles/ by default.');
+    process.exit(1);
+}
+function loadLatestBundles(artifactsDir, limit) {
+    if (!existsSync(artifactsDir))
+        return [];
+    try {
+        const files = readdirSync(artifactsDir)
+            .filter((f) => f.endsWith('.json') && !f.includes('policy') && !f.includes('manifest'))
+            .map((f) => ({ name: f, mtime: statSync(join(artifactsDir, f)).mtime.getTime() }))
+            .sort((a, b) => b.mtime - a.mtime)
+            .slice(0, limit)
+            .map((f) => {
+            try {
+                return JSON.parse(readFileSync(join(artifactsDir, f.name), 'utf-8'));
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((b) => b !== null);
+        return files;
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=context.js.map