@n-dx/core 0.1.0

package/packages/sourcevision/dist/analyzers/zone-output.js

@@ -0,0 +1,252 @@
+/**
+ * Per-zone output emitter — writes zone-scoped context and summary files
+ * to .sourcevision/zones/{zone-id}/.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { toCanonicalJSON } from "../util/sort.js";
+/** Generate context.md content for a single zone. */
+export function generateZoneContext(zone, inventory, imports, zones) {
+    const lines = [];
+    const fileSet = new Set(zone.files);
+    lines.push(`# ${zone.name} — Zone Context`);
+    lines.push("");
+    lines.push("<!-- Per-zone context generated by Sourcevision. -->");
+    lines.push("");
+    // ── Zone header ──
+    lines.push("<zone>");
+    lines.push("");
+    lines.push(`Zone: ${zone.name} (\`${zone.id}\`)`);
+    lines.push(`Files: ${zone.files.length}, Cohesion: ${zone.cohesion.toFixed(2)}, Coupling: ${zone.coupling.toFixed(2)}`);
+    if (zone.riskMetrics) {
+        lines.push(`Risk: ${zone.riskMetrics.riskLevel} (score: ${zone.riskMetrics.riskScore.toFixed(2)})`);
+    }
+    if (zone.description) {
+        lines.push(`Description: ${zone.description}`);
+    }
+    if (zone.entryPoints.length > 0) {
+        lines.push(`Entry points: ${zone.entryPoints.join(", ")}`);
+    }
+    // Line count from inventory
+    const zoneLineCount = inventory.files
+        .filter((f) => fileSet.has(f.path))
+        .reduce((sum, f) => sum + f.lineCount, 0);
+    lines.push(`Lines: ${zoneLineCount}`);
+    lines.push("");
+    lines.push("</zone>");
+    lines.push("");
+    // ── Files ──
+    lines.push("<files>");
+    lines.push("");
+    const zoneFiles = inventory.files.filter((f) => fileSet.has(f.path));
+    for (const f of zoneFiles) {
+        lines.push(`${f.path} (${f.language}, ${f.lineCount} lines, ${f.role})`);
+    }
+    lines.push("");
+    lines.push("</files>");
+    lines.push("");
+    // ── Imports ──
+    const internalEdges = imports.edges.filter((e) => fileSet.has(e.from) && fileSet.has(e.to));
+    const boundaryCrossings = zones.crossings.filter((c) => c.fromZone === zone.id || c.toZone === zone.id);
+    if (internalEdges.length > 0 || boundaryCrossings.length > 0) {
+        lines.push("<imports>");
+        lines.push("");
+        if (internalEdges.length > 0) {
+            lines.push("Internal:");
+            for (const e of internalEdges) {
+                const symbols = e.symbols.length > 0 ? ` {${e.symbols.join(", ")}}` : "";
+                lines.push(`  ${e.from} → ${e.to}${symbols}`);
+            }
+        }
+        if (boundaryCrossings.length > 0) {
+            // Group by target zone
+            const outgoing = boundaryCrossings.filter((c) => c.fromZone === zone.id);
+            const incoming = boundaryCrossings.filter((c) => c.toZone === zone.id);
+            if (outgoing.length > 0) {
+                lines.push("");
+                lines.push("Outgoing (this zone → other zones):");
+                const byTarget = groupBy(outgoing, (c) => c.toZone);
+                for (const [targetZone, crossings] of sortedEntries(byTarget)) {
+                    const files = crossings.map((c) => `${c.from} → ${c.to}`);
+                    lines.push(`  → ${targetZone}: ${files.join("; ")}`);
+                }
+            }
+            if (incoming.length > 0) {
+                lines.push("");
+                lines.push("Incoming (other zones → this zone):");
+                const bySource = groupBy(incoming, (c) => c.fromZone);
+                for (const [sourceZone, crossings] of sortedEntries(bySource)) {
+                    const files = crossings.map((c) => `${c.from} → ${c.to}`);
+                    lines.push(`  ← ${sourceZone}: ${files.join("; ")}`);
+                }
+            }
+        }
+        lines.push("");
+        lines.push("</imports>");
+        lines.push("");
+    }
+    // ── Findings ──
+    const zoneFindings = (zones.findings ?? []).filter((f) => f.scope === zone.id);
+    if (zoneFindings.length > 0) {
+        lines.push("<findings>");
+        lines.push("");
+        for (const f of zoneFindings) {
+            const sev = f.severity ? ` [${f.severity}]` : "";
+            lines.push(`[${f.type}]${sev} ${f.text}`);
+        }
+        lines.push("");
+        lines.push("</findings>");
+        lines.push("");
+    }
+    // ── Insights ──
+    if (zone.insights && zone.insights.length > 0) {
+        lines.push("<insights>");
+        lines.push("");
+        for (const insight of zone.insights) {
+            lines.push(`- ${insight}`);
+        }
+        lines.push("");
+        lines.push("</insights>");
+        lines.push("");
+    }
+    // ── Sub-crossings ──
+    if (zone.subCrossings && zone.subCrossings.length > 0) {
+        lines.push("<sub-crossings>");
+        lines.push("");
+        lines.push("Cross-dependencies between sub-zones:");
+        // Group by directed zone pair and count
+        const pairCounts = new Map();
+        for (const c of zone.subCrossings) {
+            const key = `${c.fromZone} → ${c.toZone}`;
+            pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+        }
+        for (const [pair, count] of sortedEntries(pairCounts)) {
+            lines.push(`  ${pair}: ${count}`);
+        }
+        lines.push("");
+        lines.push("</sub-crossings>");
+        lines.push("");
+    }
+    // ── Sub-zones ──
+    if (zone.subZones && zone.subZones.length > 0) {
+        lines.push("<sub-zones>");
+        lines.push("");
+        lines.push(`This zone has ${zone.subZones.length} sub-zone(s):`);
+        lines.push("");
+        for (const subZone of zone.subZones) {
+            lines.push(`- **${subZone.name}** (\`${subZone.id}\`): ${subZone.files.length} files, cohesion ${subZone.cohesion}, coupling ${subZone.coupling}`);
+            if (subZone.subZones && subZone.subZones.length > 0) {
+                lines.push(`  - Has ${subZone.subZones.length} nested sub-zone(s)`);
+            }
+        }
+        lines.push("");
+        lines.push("Detailed sub-zone context available in `zones/{sub-zone-id}/context.md`");
+        lines.push("");
+        lines.push("</sub-zones>");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** Build summary.json for a single zone. */
+export function buildZoneSummary(zone, inventory) {
+    const fileSet = new Set(zone.files);
+    const lineCount = inventory.files
+        .filter((f) => fileSet.has(f.path))
+        .reduce((sum, f) => sum + f.lineCount, 0);
+    const summary = {
+        id: zone.id,
+        name: zone.name,
+        description: zone.description,
+        files: zone.files,
+        entryPoints: zone.entryPoints,
+        cohesion: zone.cohesion,
+        coupling: zone.coupling,
+        fileCount: zone.files.length,
+        lineCount,
+    };
+    // Include risk metrics when available on the zone
+    if (zone.riskMetrics) {
+        summary.riskMetrics = zone.riskMetrics;
+    }
+    return summary;
+}
+/**
+ * Emit per-zone output files to .sourcevision/zones/{zone-id}/.
+ * Creates context.md and summary.json for each zone.
+ * Recursively emits sub-zone outputs to nested directories.
+ */
+export function emitZoneOutputs(outputDir, inventory, imports, zones) {
+    const zonesDir = join(outputDir, "zones");
+    pruneStaleZoneFolders(zonesDir, zones);
+    for (const zone of zones.zones) {
+        emitSingleZoneOutput(zonesDir, zone, inventory, imports, zones);
+    }
+}
+/**
+ * Remove zone folders that no longer correspond to any active zone.
+ * Prevents stale folders from accumulating when zone IDs change between runs.
+ */
+export function pruneStaleZoneFolders(zonesDir, zones) {
+    if (!existsSync(zonesDir))
+        return;
+    // Collect all active zone folder names (leaf segment of zone.id, colon→dash)
+    const activeNames = new Set();
+    function collectNames(zoneList) {
+        for (const zone of zoneList) {
+            const dirName = zone.id.includes("/")
+                ? zone.id.split("/").pop().replace(/:/g, "-")
+                : zone.id.replace(/:/g, "-");
+            activeNames.add(dirName);
+            if (zone.subZones)
+                collectNames(zone.subZones);
+        }
+    }
+    collectNames(zones.zones);
+    for (const entry of readdirSync(zonesDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && !activeNames.has(entry.name)) {
+            rmSync(join(zonesDir, entry.name), { recursive: true });
+        }
+    }
+}
+/**
+ * Emit output files for a single zone and its sub-zones recursively.
+ */
+function emitSingleZoneOutput(parentDir, zone, inventory, imports, zones) {
+    // Zone ID may contain "/" for nested zones (e.g., "hench/agent")
+    // For nested zones, we use just the last segment as the directory name
+    // Zone ID may contain ":" for sub-analysis zones (e.g., "packages-rex:cli")
+    // Replace with "-" since ":" is not valid in Windows paths
+    let dirName = zone.id.includes("/") ? zone.id.split("/").pop() : zone.id;
+    dirName = dirName.replace(/:/g, "-");
+    const zoneDir = join(parentDir, dirName);
+    mkdirSync(zoneDir, { recursive: true });
+    const contextMd = generateZoneContext(zone, inventory, imports, zones);
+    writeFileSync(join(zoneDir, "context.md"), contextMd);
+    const summary = buildZoneSummary(zone, inventory);
+    writeFileSync(join(zoneDir, "summary.json"), toCanonicalJSON(summary));
+    // Recursively emit sub-zones
+    if (zone.subZones && zone.subZones.length > 0) {
+        const subZonesDir = join(zoneDir, "zones");
+        for (const subZone of zone.subZones) {
+            emitSingleZoneOutput(subZonesDir, subZone, inventory, imports, zones);
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function groupBy(items, key) {
+    const map = new Map();
+    for (const item of items) {
+        const k = key(item);
+        let list = map.get(k);
+        if (!list) {
+            list = [];
+            map.set(k, list);
+        }
+        list.push(item);
+    }
+    return map;
+}
+function sortedEntries(map) {
+    return [...map.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+//# sourceMappingURL=zone-output.js.map

package/packages/sourcevision/dist/analyzers/zone-output.js.map

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

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

@@ -0,0 +1,224 @@
+/**
+ * Deterministic zone analyzer using Louvain community detection.
+ *
+ * Zones represent natural architectural boundaries discovered from the import
+ * graph. Each zone has two key metrics:
+ *
+ * - **Cohesion** (0–1): ratio of internal edges to total edges from the zone.
+ *   A value of 1.0 means all imports stay within the zone — perfect encapsulation.
+ *
+ * - **Coupling** (0–1): ratio of external edges to total edges. A value of 0.0
+ *   means no imports cross the zone boundary — complete independence.
+ *
+ * These metrics validate architectural quality: well-structured packages with
+ * clean abstractions naturally achieve high cohesion and low coupling, confirming
+ * that the Louvain algorithm correctly identified the intended boundaries.
+ *
+ * @see {@link "./louvain.ts"} for the community detection algorithm
+ * @see {@link generateStructuralInsights} for automated metric interpretation
+ */
+import type { Inventory, Imports, ImportEdge, Zone, ZoneCrossing, Zones, Finding, AnalyzeTokenUsage } from "../schema/index.js";
+import type { SubAnalysis } from "./workspace.js";
+/** Result from analyzeZones, including the zones data and optional token usage. */
+export interface AnalyzeZonesResult {
+    zones: Zones;
+    tokenUsage?: AnalyzeTokenUsage;
+    /** True when zone structure changed and enrichment pass was reset to 1 */
+    structureChanged: boolean;
+}
+/** Options for the reusable zone detection pipeline. */
+export interface ZonePipelineOptions {
+    /** Import edges to cluster (pre-filtered for scope). */
+    edges: ImportEdge[];
+    /** Full inventory for zone descriptions and file metadata. */
+    inventory: Inventory;
+    /** Full imports for entry point detection and crossing computation. */
+    imports: Imports;
+    /** File paths in scope for zone assignment. */
+    scopeFiles: string[];
+    /** Maximum number of root-level zones. Default: 15. */
+    maxZones?: number;
+    /**
+     * Maximum percentage of scope files a single zone may contain (1–100).
+     * Default: {@link DEFAULT_MAX_ZONE_PERCENT} (15%).
+     * Set to `100` to disable the zone size cap.
+     */
+    maxZonePercent?: number;
+    /** Parent zone ID for sub-zone ID derivation. Reserved for subdivision. */
+    parentId?: string;
+    /** Current recursion depth. Reserved for subdivision. */
+    depth?: number;
+    /** Test files excluded from cohesion/coupling metric computation. */
+    testFiles?: Set<string>;
+    /**
+     * Manual zone overrides: file path → target zone ID.
+     * Files listed here are moved to the specified zone after Louvain detection
+     * and proximity assignment, overriding the algorithmic placement.
+     * Stored in `.n-dx.json` under `sourcevision.zones.pins`.
+     */
+    zonePins?: Record<string, string>;
+}
+/** Result of running the zone detection pipeline. */
+export interface ZonePipelineResult {
+    zones: Zone[];
+    crossings: ZoneCrossing[];
+    unzoned: string[];
+    /** Zone IDs that were derived from filename patterns rather than directory structure. */
+    filenameBasedZoneIds: Set<string>;
+}
+/**
+ * Derive a zone ID from the most common directory segment among files.
+ * Root-level files → "root".
+ *
+ * When `parentId` is provided (for sub-zone derivation), the parent's ID
+ * segments are treated as generic and skipped, producing deeper, more
+ * specific names (e.g., "agent" instead of "hench").
+ */
+export declare function deriveZoneId(files: string[], parentId?: string): string;
+/**
+ * Disambiguate a zone ID by finding the most common path segment that
+ * appears AFTER the baseId segment in file paths. Returns `${baseId}-${next}`
+ * (e.g., "routes-admin") or just `baseId` if no discriminator found.
+ */
+export declare function disambiguateZoneId(baseId: string, files: string[], parentId?: string): string;
+/**
+ * Derive a zone ID from the dominant theme word in filename stems.
+ * Used as a fallback when directory-based derivation produces duplicate IDs.
+ *
+ * Algorithm:
+ * 1. Filter out test files (*.test.ts, *.spec.ts)
+ * 2. Extract filename stems, split by `-`, `_`, and camelCase boundaries
+ * 3. Skip generic words (index, utils, types, etc.)
+ * 4. Count word frequency (deduplicated per file)
+ * 5. Return the most common word if it appears in ≥30% of source files (min 2 files)
+ * 6. Tie-break lexicographically for determinism
+ */
+export declare function deriveZoneIdFromFilenames(files: string[]): string | null;
+/**
+ * Title-case a zone ID: "detail-panel" → "Detail Panel"
+ */
+export declare function deriveZoneName(id: string): string;
+/**
+ * Assign unzoned files to their nearest zone by directory proximity.
+ * Walks up each file's directory tree until finding a directory containing
+ * files from an existing zone.
+ */
+export declare function assignByProximity(zones: Zone[], unzonedFiles: string[], maxZoneSize?: number): {
+    zones: Zone[];
+    remaining: string[];
+};
+/**
+ * Apply manual zone pins by moving files from their detected zone to the
+ * pinned target zone. Files whose target zone doesn't exist are skipped.
+ * This runs after Louvain detection and proximity assignment.
+ */
+export declare function applyZonePins(zones: Zone[], pins: Record<string, string>): Zone[];
+/** Zones with more than this many files are subdivided recursively. */
+export declare const SUBDIVISION_THRESHOLD = 50;
+/** Maximum recursion depth for subdivision to prevent infinite loops. */
+export declare const MAX_SUBDIVISION_DEPTH = 3;
+/**
+ * Subdivide a large zone by running the full zone pipeline on its internal
+ * import graph. Returns sub-zones with IDs prefixed by parent zone ID.
+ *
+ * Uses the same algorithm at every zoom level (resolution escalation,
+ * proximity edges, splitLargeCommunities, mergeSameIdCommunities) and
+ * stores cross-sub-zone edges on `zone.subCrossings`.
+ */
+export declare function subdivideZone(zone: Zone, imports: Imports, inventory: Inventory, testFiles?: Set<string>, depth?: number): Zone[];
+/**
+ * Hash the structural zone groupings for change detection between runs.
+ * Same codebase + same imports → same hash → safe to preserve previous insights.
+ */
+export declare function computeStructureHash(zones: Zone[]): string;
+/**
+ * Hash a zone's file contents for change detection between runs.
+ * Uses inventory content hashes (already computed) so we detect code changes
+ * even when the zone structure (file membership) stays the same.
+ */
+export declare function computeZoneContentHash(zone: Zone, fileHashes: Map<string, string>): string;
+export { computeGlobalContentHash } from "./zone-hash.js";
+/**
+ * Generate deterministic, actionable insights from graph metrics.
+ *
+ * Recomputed every run — same structure always produces the same insights.
+ * These insights translate raw cohesion/coupling numbers into architectural
+ * guidance:
+ *
+ * - **Isolated files**: multiple files with no import edges — cohesion is
+ *   unmeasurable (reported as 0). Not inherently bad, but the grouping is
+ *   based on proximity rather than structural evidence.
+ * - **High cohesion** (≥0.8): files are tightly interconnected — good sign.
+ *   Perfect cohesion (1.0) means the zone is fully self-contained.
+ * - **Low cohesion** (<0.4): files are loosely related — consider splitting.
+ * - **High coupling** (>0.5): heavy cross-zone imports — may need refactoring.
+ * - **Size imbalance**: uneven zone sizes suggest decomposition issues.
+ * - **Large zone with sub-zones**: zones exceeding 35% of project files that
+ *   have been successfully subdivided get an informational insight rather than
+ *   a "consider splitting" warning — the subdivision already addresses breadth.
+ * - **Hub files**: files imported across 3+ zones are cross-cutting dependencies.
+ * - **Bidirectional coupling**: zone pairs that import from each other.
+ *
+ * When all connected zones achieve perfect cohesion, it validates that the
+ * Louvain community detection successfully identified the codebase's natural
+ * architectural boundaries. Isolated-file zones (cohesion 0) are excluded
+ * from this assessment — their grouping is proximity-based, not structural.
+ */
+export declare function generateStructuralInsights(zones: Zone[], crossings: ZoneCrossing[], imports: Imports, totalFiles: number, callGraphStats?: {
+    zoneStats: Array<{
+        zoneId: string;
+        internalCalls: number;
+        outgoingCalls: number;
+        incomingCalls: number;
+        callCohesion: number;
+        callCoupling: number;
+    }>;
+    crossZonePatterns: Array<{
+        fromZone: string;
+        toZone: string;
+        callCount: number;
+    }>;
+}, filenameBasedZoneIds?: Set<string>): {
+    zoneInsights: Map<string, string[]>;
+    globalInsights: string[];
+    findings: Finding[];
+};
+/**
+ * Maximum percentage of project files a single zone should contain.
+ * Zones exceeding this threshold are split via internal Louvain subdivision.
+ * Default: 15% — prevents over-aggregation where one zone dominates the codebase.
+ */
+export declare const DEFAULT_MAX_ZONE_PERCENT = 15;
+/**
+ * Run the full zone detection pipeline: graph construction, Louvain community
+ * detection, community merging/splitting, zone construction with subdivision,
+ * proximity assignment, and crossing computation.
+ *
+ * This is the shared pipeline used by both root-level analysis and (future)
+ * recursive zone subdivision.
+ */
+export declare function runZonePipeline(options: ZonePipelineOptions): ZonePipelineResult;
+export declare function analyzeZones(inventory: Inventory, imports: Imports, options?: {
+    enrich?: boolean;
+    previousZones?: Zones;
+    perZone?: boolean;
+    subAnalyses?: SubAnalysis[];
+    /** Called when structure change is detected, before AI enrichment begins. */
+    onReset?: (fromPass: number, toPass: number) => void;
+    /** File archetype classifications for enrichment prompts. */
+    fileArchetypes?: Map<string, string | null>;
+    /** Project context from .sourcevision/hints.md, injected into enrichment prompts. */
+    hints?: string;
+    /**
+     * Maximum percentage of project files a single zone may contain (1–100).
+     * Zones exceeding this are split via internal Louvain subdivision.
+     * Default: {@link DEFAULT_MAX_ZONE_PERCENT} (15%).
+     * Set to `100` to disable the zone size cap.
+     */
+    maxZonePercent?: number;
+    /**
+     * Manual zone overrides: file path → target zone ID.
+     * Passed through to the zone pipeline to override Louvain placement.
+     */
+    zonePins?: Record<string, string>;
+}): Promise<AnalyzeZonesResult>;