@n-dx/core 0.1.0

package/packages/sourcevision/dist/analyzers/context.js

@@ -0,0 +1,175 @@
+/**
+ * CONTEXT.md generator — dense, structured summary optimized for
+ * Claude context windows. Uses XML-style markers for reliable parsing.
+ */
+import { buildClassificationMap } from "./classify.js";
+import { deriveNextSteps } from "./next-steps.js";
+export function generateContext(manifest, inventory, imports, zones, components, classifications) {
+    const lines = [];
+    const projectName = manifest.targetPath.split("/").pop() || "project";
+    lines.push(`# ${projectName} — CONTEXT`);
+    lines.push("");
+    lines.push("<!-- Machine-readable codebase context. Generated by Sourcevision. -->");
+    lines.push("<!-- When using this context: group related items together, separate unrelated concerns. -->");
+    lines.push("");
+    // ── Architecture ────────────────────────────────────────────────────────
+    lines.push("<architecture>");
+    lines.push("");
+    const gitParts = [manifest.gitBranch, manifest.gitSha?.slice(0, 7)].filter(Boolean);
+    lines.push(`Project: ${projectName}`);
+    if (gitParts.length)
+        lines.push(`Git: ${gitParts.join(" @ ")}`);
+    lines.push(`Files: ${inventory.summary.totalFiles}, Lines: ${inventory.summary.totalLines}`);
+    const topLangs = Object.entries(inventory.summary.byLanguage)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, 5)
+        .map(([lang, count]) => `${lang}(${count})`)
+        .join(" ");
+    lines.push(`Languages: ${topLangs}`);
+    const describedZones = zones.zones.filter((z) => z.description).length;
+    lines.push(`Zones: ${zones.zones.length}, Described: ${describedZones}`);
+    lines.push(`Import edges: ${imports.summary.totalEdges}, External packages: ${imports.summary.totalExternal}`);
+    if (imports.summary.circularCount > 0) {
+        lines.push(`Circulars: ${imports.summary.circularCount}`);
+    }
+    lines.push("");
+    lines.push("</architecture>");
+    lines.push("");
+    // ── Zones ───────────────────────────────────────────────────────────────
+    const archetypeMap = buildClassificationMap(classifications);
+    if (zones.zones.length > 0) {
+        lines.push("<zones>");
+        lines.push("");
+        for (const zone of zones.zones) {
+            const metrics = `coh=${zone.cohesion.toFixed(2)} coup=${zone.coupling.toFixed(2)}`;
+            lines.push(`[${zone.id}] ${zone.name} (${zone.files.length} files, ${metrics})`);
+            if (zone.description) {
+                lines.push(`  ${zone.description}`);
+            }
+            // Condensed file list with archetype labels
+            const fileList = zone.files.slice(0, 10).map((f) => {
+                const arch = archetypeMap.get(f);
+                return arch ? `${f} [${arch}]` : f;
+            }).join(", ");
+            const more = zone.files.length > 10 ? ` +${zone.files.length - 10}` : "";
+            lines.push(`  files: ${fileList}${more}`);
+        }
+        if (zones.unzoned.length > 0) {
+            lines.push(`[unzoned] ${zones.unzoned.length} files: ${zones.unzoned.slice(0, 5).join(", ")}${zones.unzoned.length > 5 ? " ..." : ""}`);
+        }
+        lines.push("");
+        lines.push("Detailed zone context: .sourcevision/zones/{id}/context.md");
+        lines.push("");
+        lines.push("</zones>");
+        lines.push("");
+    }
+    // ── Import Graph (adjacency format) ─────────────────────────────────────
+    if (imports.summary.mostImported.length > 0) {
+        lines.push("<imports>");
+        lines.push("");
+        // Show most-imported files with their importers
+        lines.push("Most imported:");
+        for (const item of imports.summary.mostImported.slice(0, 10)) {
+            const importers = imports.edges
+                .filter((e) => e.to === item.path)
+                .map((e) => e.from)
+                .slice(0, 5);
+            const more = imports.edges.filter((e) => e.to === item.path).length > 5
+                ? ` +${imports.edges.filter((e) => e.to === item.path).length - 5}`
+                : "";
+            lines.push(`  ${item.path} ← ${importers.join(", ")}${more}`);
+        }
+        if (imports.summary.circulars.length > 0) {
+            lines.push("");
+            lines.push("Circular chains:");
+            for (const circ of imports.summary.circulars.slice(0, 3)) {
+                lines.push(`  ${circ.cycle.join(" → ")}`);
+            }
+        }
+        lines.push("");
+        lines.push("</imports>");
+        lines.push("");
+    }
+    // ── Routes ──────────────────────────────────────────────────────────────
+    const hasClientRoutes = components && components.routeModules.length > 0;
+    const hasServerRoutes = components && components.serverRoutes.length > 0;
+    if (hasClientRoutes || hasServerRoutes) {
+        lines.push("<routes>");
+        lines.push("");
+        if (hasClientRoutes) {
+            lines.push(`Route modules: ${components.summary.totalRouteModules}`);
+            lines.push(`Components: ${components.summary.totalComponents}`);
+            lines.push(`Usage edges: ${components.summary.totalUsageEdges}`);
+            if (components.routeTree.length > 0) {
+                lines.push("");
+                printTree(components.routeTree, lines, 0);
+            }
+            const conventions = Object.entries(components.summary.routeConventions);
+            if (conventions.length > 0) {
+                lines.push("");
+                lines.push(`Conventions: ${conventions.map(([k, v]) => `${k}(${v})`).join(" ")}`);
+            }
+        }
+        if (hasServerRoutes) {
+            if (hasClientRoutes)
+                lines.push("");
+            lines.push(`Server routes: ${components.summary.totalServerRoutes} endpoints in ${components.serverRoutes.length} handler(s)`);
+            lines.push("");
+            for (const group of components.serverRoutes) {
+                const handler = group.handler ? ` (${group.handler})` : "";
+                lines.push(`${group.prefix}${handler} — ${group.file}`);
+                for (const r of group.routes) {
+                    lines.push(`  ${r.method.padEnd(7)} ${r.path}`);
+                }
+            }
+        }
+        lines.push("");
+        lines.push("</routes>");
+        lines.push("");
+    }
+    // ── Findings (warning + critical only) ──────────────────────────────────
+    const findings = (zones.findings ?? []).filter((f) => f.severity === "warning" || f.severity === "critical");
+    if (findings.length > 0) {
+        lines.push("<findings>");
+        lines.push("");
+        for (const f of findings.slice(0, 15)) {
+            const scope = f.scope !== "global" ? ` [${f.scope}]` : "";
+            lines.push(`[${f.severity}] ${f.text}${scope}`);
+        }
+        if (findings.length > 15) {
+            lines.push(`... +${findings.length - 15} more`);
+        }
+        lines.push("");
+        lines.push("</findings>");
+        lines.push("");
+    }
+    // ── Next Steps ──────────────────────────────────────────────────────
+    // Only show high and medium priority next steps in the dense context
+    // format — low-priority items are noise for LLMs consuming CONTEXT.md.
+    const nextSteps = deriveNextSteps(zones).filter((s) => s.priority !== "low");
+    if (nextSteps.length > 0) {
+        lines.push("<next-steps>");
+        lines.push("");
+        for (const step of nextSteps.slice(0, 15)) {
+            const zone = zones.zones.find((z) => z.id === step.scope);
+            const files = zone ? zone.files.slice(0, 3).join(", ") : "";
+            lines.push(`[${step.priority}] ${step.title}`);
+            if (files) {
+                lines.push(`  files: ${files}`);
+            }
+            lines.push(`  category: ${step.category}`);
+        }
+        lines.push("");
+        lines.push("</next-steps>");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function printTree(nodes, lines, depth) {
+    for (const node of nodes) {
+        const indent = "  ".repeat(depth);
+        lines.push(`${indent}${node.routePattern} (${node.file})`);
+        printTree(node.children, lines, depth + 1);
+    }
+}
+//# sourceMappingURL=context.js.map

package/packages/sourcevision/dist/analyzers/context.js.map

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

package/packages/sourcevision/dist/analyzers/convergence.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Convergence tracking for zone metrics across analysis runs.
+ *
+ * After each analysis, a snapshot of zone metrics is created and optionally
+ * persisted. On subsequent runs, the current snapshot is compared against
+ * the previous one to produce a delta report showing which zones improved,
+ * regressed, or remained stable.
+ *
+ * This enables the improvement loop to detect whether overrides are actually
+ * fixing problems or just suppressing warnings.
+ */
+import type { Zone } from "../schema/index.js";
+/** Snapshot of a single zone's metrics at a point in time. */
+export interface ZoneMetricSnapshot {
+    zoneId: string;
+    zoneName: string;
+    cohesion: number;
+    coupling: number;
+    riskScore: number;
+    fileCount: number;
+    timestamp: string;
+    gitSha?: string;
+}
+/** Full convergence report persisted after each analysis run. */
+export interface ConvergenceReport {
+    schemaVersion: string;
+    snapshots: ZoneMetricSnapshot[];
+    analyzedAt: string;
+    gitSha?: string;
+}
+/** Direction of metric change for a single zone. */
+export type MetricDirection = "improved" | "regressed" | "stable";
+/** Delta for a single zone between two snapshots. */
+export interface ZoneDelta {
+    zoneId: string;
+    cohesionDelta: number;
+    couplingDelta: number;
+    riskDelta: number;
+    direction: MetricDirection;
+}
+/** Summary of deltas across all zones. */
+export interface DeltaSummary {
+    improved: number;
+    regressed: number;
+    stable: number;
+    overallRiskDelta: number;
+}
+/** Full delta report comparing current vs previous snapshots. */
+export interface DeltaReport {
+    zoneDeltas: ZoneDelta[];
+    newZones: string[];
+    removedZones: string[];
+    summary: DeltaSummary;
+}
+/**
+ * Create a snapshot of current zone metrics.
+ */
+export declare function createSnapshot(zones: Zone[], gitSha?: string): ZoneMetricSnapshot[];
+/**
+ * Compute deltas between current and previous snapshots.
+ */
+export declare function computeDeltas(current: ZoneMetricSnapshot[], previous: ZoneMetricSnapshot[]): DeltaReport;
+/**
+ * Load the most recent convergence report from the history directory.
+ */
+export declare function loadLatestReport(svDir: string): Promise<ConvergenceReport | null>;
+/**
+ * Save a convergence report to the history directory and prune old entries.
+ */
+export declare function saveReport(svDir: string, report: ConvergenceReport): Promise<void>;
+/**
+ * Format a delta report as human-readable text lines.
+ */
+export declare function formatDeltaReport(delta: DeltaReport): string[];

package/packages/sourcevision/dist/analyzers/convergence.js

@@ -0,0 +1,144 @@
+/**
+ * Convergence tracking for zone metrics across analysis runs.
+ *
+ * After each analysis, a snapshot of zone metrics is created and optionally
+ * persisted. On subsequent runs, the current snapshot is compared against
+ * the previous one to produce a delta report showing which zones improved,
+ * regressed, or remained stable.
+ *
+ * This enables the improvement loop to detect whether overrides are actually
+ * fixing problems or just suppressing warnings.
+ */
+import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/** Minimum risk delta to consider a zone as changed (not stable). */
+const STABILITY_THRESHOLD = 0.02;
+/** Maximum number of history files to retain. */
+const MAX_HISTORY_FILES = 30;
+/**
+ * Create a snapshot of current zone metrics.
+ */
+export function createSnapshot(zones, gitSha) {
+    const timestamp = new Date().toISOString();
+    return zones.map((zone) => ({
+        zoneId: zone.id,
+        zoneName: zone.name,
+        cohesion: zone.cohesion,
+        coupling: zone.coupling,
+        riskScore: zone.riskMetrics?.riskScore ?? ((1 - zone.cohesion) + zone.coupling) / 2,
+        fileCount: zone.files.length,
+        timestamp,
+        ...(gitSha ? { gitSha } : {}),
+    }));
+}
+/**
+ * Compute deltas between current and previous snapshots.
+ */
+export function computeDeltas(current, previous) {
+    const prevMap = new Map(previous.map((s) => [s.zoneId, s]));
+    const currMap = new Map(current.map((s) => [s.zoneId, s]));
+    const zoneDeltas = [];
+    const newZones = [];
+    const removedZones = [];
+    for (const curr of current) {
+        const prev = prevMap.get(curr.zoneId);
+        if (!prev) {
+            newZones.push(curr.zoneId);
+            continue;
+        }
+        const cohesionDelta = +(curr.cohesion - prev.cohesion).toFixed(4);
+        const couplingDelta = +(curr.coupling - prev.coupling).toFixed(4);
+        const riskDelta = +(curr.riskScore - prev.riskScore).toFixed(4);
+        let direction;
+        if (Math.abs(riskDelta) <= STABILITY_THRESHOLD) {
+            direction = "stable";
+        }
+        else if (riskDelta < 0) {
+            direction = "improved";
+        }
+        else {
+            direction = "regressed";
+        }
+        zoneDeltas.push({ zoneId: curr.zoneId, cohesionDelta, couplingDelta, riskDelta, direction });
+    }
+    for (const prev of previous) {
+        if (!currMap.has(prev.zoneId)) {
+            removedZones.push(prev.zoneId);
+        }
+    }
+    const improved = zoneDeltas.filter((d) => d.direction === "improved").length;
+    const regressed = zoneDeltas.filter((d) => d.direction === "regressed").length;
+    const stable = zoneDeltas.filter((d) => d.direction === "stable").length;
+    const overallRiskDelta = zoneDeltas.length > 0
+        ? +(zoneDeltas.reduce((sum, d) => sum + d.riskDelta, 0) / zoneDeltas.length).toFixed(4)
+        : 0;
+    return {
+        zoneDeltas,
+        newZones,
+        removedZones,
+        summary: { improved, regressed, stable, overallRiskDelta },
+    };
+}
+/**
+ * Load the most recent convergence report from the history directory.
+ */
+export async function loadLatestReport(svDir) {
+    const historyDir = join(svDir, "history");
+    try {
+        const files = await readdir(historyDir);
+        const jsonFiles = files.filter((f) => f.endsWith(".json")).sort();
+        if (jsonFiles.length === 0)
+            return null;
+        const latest = jsonFiles[jsonFiles.length - 1];
+        const raw = await readFile(join(historyDir, latest), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save a convergence report to the history directory and prune old entries.
+ */
+export async function saveReport(svDir, report) {
+    const historyDir = join(svDir, "history");
+    await mkdir(historyDir, { recursive: true });
+    const filename = `${report.analyzedAt.replace(/[:.]/g, "-")}.json`;
+    await writeFile(join(historyDir, filename), JSON.stringify(report, null, 2), "utf-8");
+    // Prune old files
+    const files = (await readdir(historyDir)).filter((f) => f.endsWith(".json")).sort();
+    if (files.length > MAX_HISTORY_FILES) {
+        const { unlink } = await import("node:fs/promises");
+        const toRemove = files.slice(0, files.length - MAX_HISTORY_FILES);
+        for (const f of toRemove) {
+            await unlink(join(historyDir, f));
+        }
+    }
+}
+/**
+ * Format a delta report as human-readable text lines.
+ */
+export function formatDeltaReport(delta) {
+    const lines = [];
+    if (delta.zoneDeltas.length === 0 && delta.newZones.length === 0) {
+        lines.push("No previous analysis to compare against.");
+        return lines;
+    }
+    const { summary } = delta;
+    lines.push(`Convergence: ${summary.improved} improved, ${summary.regressed} regressed, ${summary.stable} stable` +
+        ` (overall risk Δ: ${summary.overallRiskDelta >= 0 ? "+" : ""}${summary.overallRiskDelta.toFixed(3)})`);
+    for (const d of delta.zoneDeltas.filter((d) => d.direction !== "stable")) {
+        const arrow = d.direction === "improved" ? "↓" : "↑";
+        lines.push(`  ${arrow} ${d.zoneId}: risk ${d.riskDelta >= 0 ? "+" : ""}${d.riskDelta.toFixed(3)}` +
+            ` (cohesion ${d.cohesionDelta >= 0 ? "+" : ""}${d.cohesionDelta.toFixed(3)},` +
+            ` coupling ${d.couplingDelta >= 0 ? "+" : ""}${d.couplingDelta.toFixed(3)})`);
+    }
+    if (delta.newZones.length > 0) {
+        lines.push(`  New zones: ${delta.newZones.join(", ")}`);
+    }
+    if (delta.removedZones.length > 0) {
+        lines.push(`  Removed zones: ${delta.removedZones.join(", ")}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=convergence.js.map

package/packages/sourcevision/dist/analyzers/convergence.js.map

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

package/packages/sourcevision/dist/analyzers/enrich-batch.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Batch processing for AI enrichment.
+ *
+ * Handles single-batch enrichment with retry logic and prompt construction.
+ * Also handles meta-evaluation (pass 5+) which uses a single prompt.
+ */
+import type { Zone, ZoneCrossing, Zones, Finding, AnalyzeTokenUsage } from "../schema/index.js";
+import type { PassConfig } from "./enrich-config.js";
+/** Result from enriching a single batch of zones. */
+export interface BatchResult {
+    parsed: any;
+    batchZones: Zone[];
+    tokenUsage: AnalyzeTokenUsage;
+}
+/** Result from meta-evaluation pass. */
+export interface MetaEvalResult {
+    newZoneInsights: Map<string, string[]>;
+    newGlobalInsights: string[];
+    newFindings: Finding[];
+    updatedFindings: Finding[];
+    tokenUsage: AnalyzeTokenUsage;
+}
+/**
+ * Run meta-evaluation pass (pass 5+): review existing findings and adjust
+ * severities or add new cross-cutting insights.
+ *
+ * Returns null on auth/structural failure (caller should return empty).
+ */
+export declare function runMetaEvaluation(zones: Zone[], existingFindings: Finding[], crossings: ZoneCrossing[], passNumber: number, passConfig: PassConfig, hints?: string): Promise<MetaEvalResult | null>;
+/**
+ * Enrich a single batch of zones via active LLM vendor with retry.
+ * Returns the parsed response + batch zones, or null on total failure.
+ * On auth error, returns { authError: true } to signal caller to stop.
+ */
+export declare function enrichBatch(batchZones: Zone[], allZones: Zone[], crossingSummary: [string, number][], passNumber: number, passConfig: PassConfig, previousZones: Zones | undefined, batchIndex: number, totalBatches: number, enrichedNames?: Map<string, string>, fileArchetypes?: Map<string, string | null>, hints?: string): Promise<BatchResult | null | {
+    authError: true;
+}>;
+/** Aggregated data from all successful batch results. */
+export interface AggregatedBatchData {
+    allParsedZones: any[];
+    dedupedInsights: string[];
+    allParsedFindings: any[];
+    totalTokenUsage: AnalyzeTokenUsage;
+    successfulBatchIds: Set<string>;
+}
+/** Aggregate token usage, parsed zones, insights, and findings from all batches. */
+export declare function aggregateBatchResults(results: BatchResult[]): AggregatedBatchData;