@kernlang/review 3.3.8 → 3.4.0

package/dist/telemetry.js

@@ -0,0 +1,303 @@
+import { createHash } from 'crypto';
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { inferReviewPolicy } from './policy.js';
+import { getRuleQualityProfile } from './rule-quality.js';
+export function buildReviewTelemetry(reports, options = {}) {
+    const findings = reports.flatMap((report) => report.findings);
+    const suppressed = reports.flatMap((report) => report.suppressedFindings ?? []);
+    const allForRuleCounts = [...findings, ...suppressed];
+    const rootCauseKeys = new Set(findings.map((finding) => finding.rootCause?.key).filter(Boolean));
+    const healthEntries = reports.flatMap((report) => report.health?.entries ?? []);
+    const rules = buildRuleTelemetry(allForRuleCounts, suppressed);
+    return {
+        schemaVersion: 1,
+        generatedAt: options.generatedAt ?? new Date().toISOString(),
+        policy: options.policy ?? inferReviewPolicy(),
+        files: reports.length,
+        findings: {
+            total: findings.length,
+            errors: findings.filter((finding) => finding.severity === 'error').length,
+            warnings: findings.filter((finding) => finding.severity === 'warning').length,
+            notes: findings.filter((finding) => finding.severity === 'info').length,
+        },
+        suppressed: {
+            total: suppressed.length,
+        },
+        rootCauses: rootCauseKeys.size,
+        health: {
+            status: healthEntries.some((entry) => entry.kind === 'error')
+                ? 'partial'
+                : healthEntries.length > 0
+                    ? 'degraded'
+                    : 'ok',
+            errors: healthEntries.filter((entry) => entry.kind === 'error').length,
+            fallbacks: healthEntries.filter((entry) => entry.kind === 'fallback').length,
+            skipped: healthEntries.filter((entry) => entry.kind === 'skipped').length,
+        },
+        rules,
+        ...(options.durationMs !== undefined ? { performance: { durationMs: options.durationMs } } : {}),
+        ...(options.includeFindings
+            ? {
+                findingRows: findings.map((f) => toFindingRow(f, options.policy ?? inferReviewPolicy(), options.redactPaths ?? false)),
+            }
+            : {}),
+    };
+}
+export function writeReviewTelemetrySnapshot(reports, options = {}) {
+    const outputPath = resolve(options.outputPath ?? '.kern/cache/review-telemetry.jsonl');
+    const snapshot = buildReviewTelemetry(reports, options);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    const line = `${JSON.stringify(snapshot)}\n`;
+    if (options.append === false) {
+        writeFileSync(outputPath, line, 'utf-8');
+    }
+    else {
+        appendFileSync(outputPath, line, 'utf-8');
+    }
+    return { outputPath, snapshot };
+}
+export function parseReviewTelemetryJsonl(source) {
+    const snapshots = [];
+    const lines = source.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            throw new Error(`telemetry line ${i + 1} is not valid JSON: ${err.message}`);
+        }
+        if (!isTelemetrySnapshot(parsed)) {
+            throw new Error(`telemetry line ${i + 1} is not a KERN review telemetry snapshot`);
+        }
+        snapshots.push(parsed);
+    }
+    return snapshots;
+}
+export function readReviewTelemetrySnapshots(path) {
+    return parseReviewTelemetryJsonl(readFileSync(path, 'utf-8'));
+}
+export function summarizeReviewTelemetry(snapshots) {
+    const ruleMap = new Map();
+    const durations = snapshots.map((snapshot) => snapshot.performance?.durationMs).filter(isNumber);
+    const sortedDates = snapshots.map((snapshot) => snapshot.generatedAt).sort();
+    for (const snapshot of snapshots) {
+        for (const rule of snapshot.rules) {
+            const existing = ruleMap.get(rule.ruleId) ??
+                {
+                    ruleId: rule.ruleId,
+                    findings: 0,
+                    suppressed: 0,
+                    errors: 0,
+                    warnings: 0,
+                    notes: 0,
+                    rootCauses: 0,
+                    runs: 0,
+                    suppressionRate: 0,
+                    averageFindingsPerRun: 0,
+                    ...(rule.precision ? { precision: rule.precision } : {}),
+                    ...(rule.lifecycle ? { lifecycle: rule.lifecycle } : {}),
+                    ...(rule.ciDefault ? { ciDefault: rule.ciDefault } : {}),
+                };
+            existing.findings += rule.findings;
+            existing.suppressed += rule.suppressed;
+            existing.errors += rule.errors;
+            existing.warnings += rule.warnings;
+            existing.notes += rule.notes;
+            existing.rootCauses += rule.rootCauses;
+            existing.runs++;
+            ruleMap.set(rule.ruleId, existing);
+        }
+    }
+    const rules = Array.from(ruleMap.values())
+        .map((rule) => {
+        const totalObserved = rule.findings + rule.suppressed;
+        return {
+            ...rule,
+            suppressionRate: totalObserved > 0 ? rule.suppressed / totalObserved : 0,
+            averageFindingsPerRun: snapshots.length > 0 ? rule.findings / snapshots.length : 0,
+        };
+    })
+        .sort((a, b) => b.findings + b.suppressed - (a.findings + a.suppressed) || a.ruleId.localeCompare(b.ruleId));
+    return {
+        runs: snapshots.length,
+        ...(sortedDates[0] ? { firstRun: sortedDates[0] } : {}),
+        ...(sortedDates[sortedDates.length - 1] ? { lastRun: sortedDates[sortedDates.length - 1] } : {}),
+        files: snapshots.reduce((sum, snapshot) => sum + snapshot.files, 0),
+        findings: {
+            total: snapshots.reduce((sum, snapshot) => sum + snapshot.findings.total, 0),
+            errors: snapshots.reduce((sum, snapshot) => sum + snapshot.findings.errors, 0),
+            warnings: snapshots.reduce((sum, snapshot) => sum + snapshot.findings.warnings, 0),
+            notes: snapshots.reduce((sum, snapshot) => sum + snapshot.findings.notes, 0),
+        },
+        suppressed: {
+            total: snapshots.reduce((sum, snapshot) => sum + snapshot.suppressed.total, 0),
+        },
+        rootCauses: snapshots.reduce((sum, snapshot) => sum + snapshot.rootCauses, 0),
+        health: {
+            partial: snapshots.filter((snapshot) => snapshot.health.status === 'partial').length,
+            degraded: snapshots.filter((snapshot) => snapshot.health.status === 'degraded').length,
+            ok: snapshots.filter((snapshot) => snapshot.health.status === 'ok').length,
+            errors: snapshots.reduce((sum, snapshot) => sum + snapshot.health.errors, 0),
+            fallbacks: snapshots.reduce((sum, snapshot) => sum + snapshot.health.fallbacks, 0),
+            skipped: snapshots.reduce((sum, snapshot) => sum + snapshot.health.skipped, 0),
+        },
+        performance: {
+            ...(durations.length > 0
+                ? {
+                    averageDurationMs: Math.round(durations.reduce((sum, duration) => sum + duration, 0) / durations.length),
+                    maxDurationMs: Math.max(...durations),
+                }
+                : {}),
+        },
+        rules,
+        noisyRules: rules.filter((rule) => rule.suppressed >= 3 && rule.suppressionRate >= 0.5),
+        promotionCandidates: rules.filter((rule) => rule.precision === 'high' &&
+            rule.lifecycle === 'stable' &&
+            rule.ciDefault !== 'on' &&
+            rule.findings > 0 &&
+            rule.suppressionRate <= 0.1),
+    };
+}
+export function formatReviewTelemetrySummary(summary) {
+    const lines = [
+        'KERN Review Telemetry',
+        '',
+        `Runs: ${summary.runs}`,
+        `Files: ${summary.files}`,
+        `Findings: ${summary.findings.total} (${summary.findings.errors} errors, ${summary.findings.warnings} warnings, ${summary.findings.notes} notes)`,
+        `Suppressed: ${summary.suppressed.total}`,
+        `Root causes: ${summary.rootCauses}`,
+        `Health: ${summary.health.ok} ok, ${summary.health.degraded} degraded, ${summary.health.partial} partial`,
+    ];
+    if (summary.performance.averageDurationMs !== undefined) {
+        lines.push(`Duration: avg ${summary.performance.averageDurationMs}ms, max ${summary.performance.maxDurationMs ?? 0}ms`);
+    }
+    lines.push('', 'Top Rules:');
+    for (const rule of summary.rules.slice(0, 10)) {
+        const suppressionPct = `${Math.round(rule.suppressionRate * 100)}%`;
+        lines.push(`  ${rule.ruleId}: ${rule.findings} findings, ${rule.suppressed} suppressed (${suppressionPct} suppressed)`);
+    }
+    if (summary.noisyRules.length > 0) {
+        lines.push('', 'Noisy Rules:');
+        for (const rule of summary.noisyRules.slice(0, 10)) {
+            lines.push(`  ${rule.ruleId}: ${Math.round(rule.suppressionRate * 100)}% suppression rate`);
+        }
+    }
+    if (summary.promotionCandidates.length > 0) {
+        lines.push('', 'Promotion Candidates:');
+        for (const rule of summary.promotionCandidates.slice(0, 10)) {
+            lines.push(`  ${rule.ruleId}: high/stable with low suppression`);
+        }
+    }
+    return lines.join('\n');
+}
+function buildRuleTelemetry(findings, suppressedFindings) {
+    const suppressedKeys = new Set(suppressedFindings.map((finding) => `${finding.ruleId}:${finding.fingerprint}`));
+    const byRule = new Map();
+    for (const finding of findings) {
+        const existing = byRule.get(finding.ruleId) ?? makeRuleTelemetry(finding.ruleId);
+        const isSuppressed = suppressedKeys.has(`${finding.ruleId}:${finding.fingerprint}`);
+        if (isSuppressed) {
+            existing.suppressed++;
+            switch (finding.suppressionReason) {
+                case 'false-positive':
+                    existing.suppressedAsFalsePositive = (existing.suppressedAsFalsePositive ?? 0) + 1;
+                    break;
+                case 'wont-fix':
+                    existing.suppressedAsWontFix = (existing.suppressedAsWontFix ?? 0) + 1;
+                    break;
+                case 'intentional':
+                    existing.suppressedAsIntentional = (existing.suppressedAsIntentional ?? 0) + 1;
+                    break;
+                case 'not-applicable':
+                    existing.suppressedAsNotApplicable = (existing.suppressedAsNotApplicable ?? 0) + 1;
+                    break;
+            }
+        }
+        else {
+            existing.findings++;
+            if (finding.severity === 'error')
+                existing.errors++;
+            else if (finding.severity === 'warning')
+                existing.warnings++;
+            else
+                existing.notes++;
+            if (finding.rootCause?.key)
+                existing.rootCauseKeys.add(finding.rootCause.key);
+        }
+        byRule.set(finding.ruleId, existing);
+    }
+    return Array.from(byRule.values())
+        .map(({ rootCauseKeys, ...rule }) => {
+        const fp = rule.suppressedAsFalsePositive ?? 0;
+        const denom = rule.findings + fp;
+        const fpRateEstimate = denom > 0 && fp > 0 ? fp / denom : undefined;
+        return {
+            ...rule,
+            rootCauses: rootCauseKeys.size,
+            ...(fpRateEstimate !== undefined ? { fpRateEstimate } : {}),
+        };
+    })
+        .sort((a, b) => b.findings - a.findings || a.ruleId.localeCompare(b.ruleId));
+}
+function makeRuleTelemetry(ruleId) {
+    const profile = getRuleQualityProfile(ruleId);
+    return {
+        ruleId,
+        findings: 0,
+        suppressed: 0,
+        errors: 0,
+        warnings: 0,
+        notes: 0,
+        rootCauses: 0,
+        rootCauseKeys: new Set(),
+        ...(profile
+            ? {
+                precision: profile.precision,
+                lifecycle: profile.lifecycle,
+                ciDefault: profile.ciDefault,
+            }
+            : {}),
+    };
+}
+function toFindingRow(finding, policy, redactPaths) {
+    return {
+        file: redactPaths ? hashPath(finding.primarySpan.file) : finding.primarySpan.file,
+        ruleId: finding.ruleId,
+        severity: finding.severity,
+        ...(finding.confidence !== undefined ? { confidence: finding.confidence } : {}),
+        ...(finding.rootCause?.key ? { rootCauseKey: finding.rootCause.key } : {}),
+        ...(policy === 'audit' && finding.calibrationTrail && finding.calibrationTrail.length > 0
+            ? { calibrationTrail: finding.calibrationTrail }
+            : {}),
+    };
+}
+/**
+ * Stable, prefix-truncated hash of a file path. 16 hex chars = 64 bits of
+ * entropy — collision-resistant within any single project, while opaque to
+ * a multi-tenant telemetry consumer.
+ */
+function hashPath(p) {
+    return `path:${createHash('sha256').update(p).digest('hex').slice(0, 16)}`;
+}
+function isTelemetrySnapshot(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return (candidate.schemaVersion === 1 &&
+        typeof candidate.generatedAt === 'string' &&
+        typeof candidate.policy === 'string' &&
+        typeof candidate.files === 'number' &&
+        Boolean(candidate.findings) &&
+        Boolean(candidate.suppressed) &&
+        Array.isArray(candidate.rules));
+}
+function isNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -50,6 +50,15 @@ export interface ProvenanceChain {
     /** Optional one-line summary shown before expanding the chain */
     summary?: string;
 }
+/** Semantic root cause used to group findings that describe the same underlying issue. */
+export interface RootCause {
+    /** Stable grouping key. Prefer graph/concept IDs over raw line numbers. */
+    key: string;
+    /** Coarse class of the underlying issue source. */
+    kind: 'api-call' | 'route' | 'data-flow' | 'symbol' | 'file' | 'unknown';
+    /** Optional structured facets for dashboards and future explainers. */
+    facets?: Record<string, string>;
+}
 /** Unified finding from any review layer */
 export interface ReviewFinding {
     /** Which layer produced this finding */
@@ -82,6 +91,44 @@ export interface ReviewFinding {
     distance?: number;
     /** Evidence chain explaining WHY the finding fired (taint path, boundary walk, etc.) */
     provenance?: ProvenanceChain;
+    /** Semantic grouping key for cross-rule/root-cause ownership. */
+    rootCause?: RootCause;
+    /**
+     * Per-stage calibration record. Populated by applyRuleQualityCalibration when a
+     * factor actually changes severity or confidence. Lets audit policy show why a
+     * finding was demoted/dropped without recomputing the chain.
+     */
+    calibrationTrail?: CalibrationStage[];
+    /**
+     * Set true after applyRuleQualityCalibration runs over this finding so that
+     * subsequent calls (e.g. graph-mode rerun after cross-file injection) skip it.
+     * Prevents compounding multipliers when Phase 1 role/overlap factors land.
+     */
+    calibrated?: boolean;
+    /**
+     * If this finding was suppressed by a `// kern-ignore [reason: …]` directive,
+     * the closed-enum reason is propagated here so telemetry can compute per-rule
+     * FP/intent rates without scanning source again. Closed-enum: any free text
+     * is rejected at parse time.
+     */
+    suppressionReason?: import('./suppression/types.js').SuppressionReason;
+}
+/** One step of calibration applied to a finding. */
+export interface CalibrationStage {
+    /** Identifier for the stage that ran (e.g. 'rule-quality:demote-advisory'). */
+    stage: string;
+    /** Multiplicative factor applied to confidence (1.0 = no change). */
+    factor: number;
+    /** Why this stage acted on this finding. */
+    reason: string;
+    /** Confidence before this stage (undefined if confidence was unset). */
+    beforeConfidence?: number;
+    /** Confidence after this stage. */
+    afterConfidence?: number;
+    /** Severity before this stage, if changed. */
+    beforeSeverity?: ReviewFinding['severity'];
+    /** Severity after this stage, if changed. */
+    afterSeverity?: ReviewFinding['severity'];
 }
 /** Confidence level for an inference match */
 export type Confidence = 'high' | 'medium' | 'low';
@@ -216,6 +263,18 @@ export interface ReviewStats {
     /** Number of KERN-expressible constructs */
     constructCount: number;
 }
+/** Named review posture. Guard is low-noise default, CI is strict, audit is broad. */
+export type ReviewPolicy = 'guard' | 'ci' | 'audit';
+export interface ReviewTelemetryConfig {
+    /** When true, persist a machine-readable telemetry snapshot for this review run. */
+    enabled?: boolean;
+    /** Output file. Defaults to .kern/cache/review-telemetry.jsonl when telemetry is enabled. */
+    outputPath?: string;
+    /** Append JSONL snapshots instead of replacing the file. Defaults to true. */
+    append?: boolean;
+    /** Include per-finding rows in addition to aggregate counts. Defaults to false. */
+    includeFindings?: boolean;
+}
 /** Enforcement result for CI */
 export interface EnforceResult {
     /** Whether enforcement passed */
@@ -262,6 +321,16 @@ export interface ReviewConfig {
     format?: 'text' | 'json' | 'sarif';
     /** Build target — activates framework-specific rules */
     target?: string;
+    /**
+     * Cross-stack review precision mode.
+     *   guard — default, high precision / low noise for KERN Guard and CI.
+     *   audit — broader exploratory findings for local investigations.
+     */
+    crossStackMode?: 'guard' | 'audit';
+    /** Explicit review policy. Used by CLI/defaulting/telemetry to distinguish CI, guard, and audit runs. */
+    policy?: ReviewPolicy;
+    /** Optional persistent telemetry for rule/noise calibration. */
+    telemetry?: ReviewTelemetryConfig;
     /** Minimum confidence for findings to count in enforcement (default: 0) */
     minConfidence?: number;
     /** Show confidence scores in output */
@@ -311,7 +380,7 @@ export interface ReviewConfig {
      * names (`src/routes.ts`) never collide. Rules that consult
      * `ctx.allConcepts` treat the keys opaquely.
      */
-    externalConcepts?: Map<string, import('@kernlang/core').ConceptMap>;
+    externalConcepts?: ReadonlyMap<string, unknown>;
 }
 /** Runtime boundary determined by position in the import tree */
 export type RuntimeBoundary = 'server' | 'client' | 'api' | 'middleware' | 'shared' | 'unknown';
@@ -350,7 +419,24 @@ export interface RuleContext {
 }
 /** A review rule function */
 export type ReviewRule = (ctx: RuleContext) => ReviewFinding[];
-export type GraphEdgeKind = 'side-effect-import' | 'default-import' | 'named-import' | 'namespace-import' | 'named-reexport' | 'export-all';
+export type GraphEdgeKind = 'side-effect-import' | 'default-import' | 'named-import' | 'namespace-import' | 'named-reexport' | 'export-all'
+/**
+ * `export * as ns from './m'` — distinct from bare `export *` because the
+ * namespace alias gives us a concrete local name (`ns`) that Producer 1
+ * can attach a symbol-scoped blocker to when the target fails to resolve.
+ * Bare `export *` stays under `'export-all'` and produces no blocker
+ * (no symbol to pin).
+ */
+ | 'namespace-reexport'
+/**
+ * Literal `import('./mod')` — emitted by the graph walker when the argument
+ * is a StringLiteral or NoSubstitutionTemplateLiteral. Distinct from the
+ * static-import variants so a strongest-path traversal can prefer a static
+ * (full-confidence) edge over a dynamic (capped) edge to the same target.
+ * Non-literal `import(expr)` does NOT produce an edge — it produces a
+ * `ReachabilityBlocker` instead (see step 9b).
+ */
+ | 'dynamic-import';
 export interface GraphEdge {
     from: string;
     to: string;
@@ -365,7 +451,26 @@ export interface GraphEdge {
 }
 /** A file node in the import graph */
 export interface GraphFile {
+    /**
+     * Display path — caller-facing (whatever the user passed in for entry
+     * files; whatever ts-morph reports for BFS-reached files). Use this
+     * for `report.filePath`, finding `primarySpan.file`, and any UI
+     * surface. NEVER use this as a Map key for cross-file resolution —
+     * symlinks (pnpm, macOS /var → /private/var) cause the same physical
+     * file to have multiple display paths and would silently produce
+     * twin entries (red-team #9).
+     */
     path: string;
+    /**
+     * Internal identity key — `realpathSync(path)` with a graceful fallback
+     * for paths that don't exist on disk. ALL Map keys, ts-morph
+     * `addSourceFileAtPath` calls, and cross-file binding lookups MUST use
+     * this form so two display paths pointing at the same physical file
+     * collapse to a single entry. The two forms are equal for normal
+     * projects without symlinks, so this is a no-op there. See
+     * `path-canonical.ts` for the canonicaliser invariant.
+     */
+    canonicalPath: string;
     distance: number;
     imports: string[];
     importedBy: string[];
@@ -381,12 +486,77 @@ export interface GraphResult {
     /** ts-morph Project used to resolve the graph. Exposed so downstream
      *  analyses (call graph, cross-file taint) can reuse it without re-parsing. */
     project?: import('ts-morph').Project;
+    /**
+     * Symbol-scoped reachability blockers discovered during graph resolution.
+     * Currently fed by Producer 1 (named re-export with unresolved relative
+     * target). Consumed by deadExportRule to cap finding confidence at 0.4
+     * with severity=info instead of emitting at full strength. Empty when
+     * every re-export resolved cleanly. NEVER file-scope — see jsdoc on
+     * ReachabilityBlocker.
+     */
+    blockers?: ReachabilityBlocker[];
+    /**
+     * Telemetry-only counter: number of `import(expr)` call sites where the
+     * specifier is non-literal. Cannot derive a target file or export name
+     * from these, so they NEVER produce a blocker (would re-introduce the
+     * red-team CRITICAL #1 file-scope silencer). Reported via review-health
+     * so consumers know dead-export findings on files containing such
+     * dynamic dispatch may include FPs that the cap mechanism cannot reach.
+     */
+    unmappedDynamicImports?: number;
+    /**
+     * Telemetry-only counter: number of static import declarations that
+     * threw when ts-morph tried to read them (malformed AST, transient FS
+     * error, etc.). Surfaced via review-health so a silent catch never
+     * hides a category of failures from operators. Set KERN_DEBUG to also
+     * log the underlying error per occurrence.
+     */
+    malformedImports?: number;
+}
+/**
+ * A reachability blocker — recorded when the call-graph cannot resolve an
+ * edge to a single concrete target (filePath, exportName) and so cannot
+ * prove a candidate dead export is unreachable.
+ *
+ * Blockers are SYMBOL-SCOPED. A non-literal dynamic import inside one
+ * function must NEVER suppress findings on unrelated exports in the same
+ * file — that was the killing red-team finding against Plan v3 ("one
+ * dynamic import silenced 50 unrelated symbols"). Each blocker carries the
+ * exact `(filePath, exportName)` it applies to. When the resolver cannot
+ * derive an exportName (e.g. fully non-literal `import(expr)`), it must
+ * NOT fall back to file scope; emit health/telemetry instead.
+ *
+ * Blockers do NOT hard-suppress. They cap finding confidence at 0.4 (see
+ * step 9b) and append a `CalibrationStage` to the finding's audit trail.
+ * Telemetry still sees the finding so `fpRateEstimate` stays honest.
+ */
+export type ReachabilityBlockerReason = 
+/** `import(expr)` where `expr` is not a string literal — target unknown. */
+'non-literal-dynamic-import'
+/** A re-export (`export * from`, `export { x } from`) whose target file
+ *  resolved but the symbol couldn't be tied to a concrete declaration. */
+ | 'unresolved-re-export'
+/** A public-API seed (package.json `exports`, framework convention) that
+ *  pointed at a symbol the call graph never observed declaring. */
+ | 'unmapped-public-surface';
+export interface ReachabilityBlocker {
+    reason: ReachabilityBlockerReason;
+    /** The candidate export this blocker applies to. SYMBOL scope, not file. */
+    filePath: string;
+    exportName: string;
+    /** Where the blocker decision was made — for the audit trail. */
+    site: {
+        file: string;
+        line: number;
+    };
 }
 /** Options for resolveImportGraph */
 export interface GraphOptions {
     maxDepth?: number;
     tsConfigFilePath?: string;
     project?: import('ts-morph').Project;
+    /** Optional graph already resolved by the caller, used to avoid duplicate resolution in CLI/watch flows. */
+    precomputedGraph?: GraphResult;
 }
 /** Create a stable fingerprint for dedup across sources and runs.
  *  Returns the raw composite key — collision-free by construction. */

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2bH,4EAA4E;AAE5E;sEACsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,SAAiB,EAAE,QAAgB;IACnF,OAAO,GAAG,MAAM,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwmBH,4EAA4E;AAE5E;sEACsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,SAAiB,EAAE,QAAgB;IACnF,OAAO,GAAG,MAAM,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;AAC9C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernlang/review",
-  "version": "3.3.8",
+  "version": "3.4.0",
   "description": "Kern Review — scan TS, infer .kern IR, roundtrip diff, report",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,10 +26,11 @@
   "license": "AGPL-3.0",
   "dependencies": {
     "ts-morph": "^28.0.0",
-    "@kernlang/core": "3.3.8"
+    "@kernlang/core": "3.4.0"
   },
   "scripts": {
     "build": "tsc -b",
-    "test": "node --experimental-vm-modules ../../node_modules/jest/bin/jest.js --config jest.config.js"
+    "test": "node --experimental-vm-modules ../../node_modules/jest/bin/jest.js --config jest.config.js",
+    "test:handles": "node --experimental-vm-modules ../../node_modules/jest/bin/jest.js --config jest.config.js --detectOpenHandles --runInBand"
   }
 }