@n-dx/core 0.1.0

package/packages/sourcevision/dist/analyzers/llms-txt.js

@@ -0,0 +1,268 @@
+/**
+ * llms.txt generator — structured Markdown summary of a codebase
+ * for consumption by LLMs and AI tools.
+ */
+import { buildClassificationMap } from "./classify.js";
+import { deriveNextSteps } from "./next-steps.js";
+export function generateLlmsTxt(manifest, inventory, imports, zones, components, classifications) {
+    const lines = [
+        ...buildProjectIdentity(manifest, inventory, zones),
+        ...buildArchitectureZones(zones),
+        ...buildKeyDependencies(imports),
+        ...buildRouteStructure(components),
+        ...buildFindings(zones),
+        ...buildNextSteps(zones),
+        ...buildFileInventory(inventory, zones, classifications),
+        ...buildTooling(),
+    ];
+    return lines.join("\n");
+}
+// ── Section builders ──────────────────────────────────────────────────────
+function buildProjectIdentity(manifest, inventory, zones) {
+    const lines = [];
+    const projectName = manifest.targetPath.split("/").pop() || "project";
+    lines.push(`# ${projectName}`);
+    lines.push("");
+    lines.push("> Codebase analysis generated by Sourcevision.");
+    lines.push("> When using this document: group related items together and separate unrelated concerns.");
+    lines.push("");
+    const gitInfo = [manifest.gitBranch, manifest.gitSha?.slice(0, 7)]
+        .filter(Boolean)
+        .join(" @ ");
+    lines.push("## Project Overview");
+    lines.push("");
+    lines.push(`- **Files**: ${inventory.summary.totalFiles}`);
+    lines.push(`- **Lines of code**: ${inventory.summary.totalLines.toLocaleString()}`);
+    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} (${describedZones} with descriptions)`);
+    if (gitInfo) {
+        lines.push(`- **Git**: ${gitInfo}`);
+    }
+    lines.push(`- **Analyzed**: ${manifest.analyzedAt}`);
+    lines.push("");
+    return lines;
+}
+function buildArchitectureZones(zones) {
+    if (zones.zones.length === 0)
+        return [];
+    const lines = [];
+    lines.push("## Architecture Zones");
+    lines.push("");
+    for (const zone of zones.zones) {
+        lines.push(`### ${zone.name} (\`${zone.id}\`)`);
+        lines.push("");
+        if (zone.description) {
+            lines.push(zone.description);
+            lines.push("");
+        }
+        lines.push(`- Files: ${zone.files.length}`);
+        lines.push(`- Cohesion: ${zone.cohesion.toFixed(2)}, Coupling: ${zone.coupling.toFixed(2)}`);
+        if (zone.entryPoints.length > 0) {
+            lines.push(`- Entry points: ${zone.entryPoints.slice(0, 5).join(", ")}${zone.entryPoints.length > 5 ? ` (+${zone.entryPoints.length - 5} more)` : ""}`);
+        }
+        lines.push(`- Detail: \`.sourcevision/zones/${zone.id.replace(/:/g, "-")}/context.md\``);
+        lines.push("");
+    }
+    return lines;
+}
+function buildKeyDependencies(imports) {
+    const lines = [];
+    lines.push("## Key Dependencies");
+    lines.push("");
+    if (imports.summary.mostImported.length > 0) {
+        lines.push("### Most-Imported Files");
+        lines.push("");
+        for (const item of imports.summary.mostImported.slice(0, 10)) {
+            lines.push(`- \`${item.path}\` (${item.count} imports)`);
+        }
+        lines.push("");
+    }
+    if (imports.external.length > 0) {
+        const topExternal = [...imports.external]
+            .sort((a, b) => b.importedBy.length - a.importedBy.length)
+            .slice(0, 10);
+        lines.push("### External Packages");
+        lines.push("");
+        for (const pkg of topExternal) {
+            lines.push(`- \`${pkg.package}\` (used by ${pkg.importedBy.length} files)`);
+        }
+        lines.push("");
+    }
+    if (imports.summary.circularCount > 0) {
+        lines.push("### Circular Dependencies");
+        lines.push("");
+        lines.push(`Found ${imports.summary.circularCount} circular dependency chain(s):`);
+        lines.push("");
+        for (const circ of imports.summary.circulars.slice(0, 5)) {
+            lines.push(`- ${circ.cycle.map((f) => `\`${f}\``).join(" → ")}`);
+        }
+        if (imports.summary.circulars.length > 5) {
+            lines.push(`- ... and ${imports.summary.circulars.length - 5} more`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function buildRouteStructure(components) {
+    const hasClientRoutes = components && components.routeModules.length > 0;
+    const hasServerRoutes = components && components.serverRoutes.length > 0;
+    if (!hasClientRoutes && !hasServerRoutes)
+        return [];
+    const lines = [];
+    lines.push("## Route Structure");
+    lines.push("");
+    if (hasClientRoutes) {
+        if (components.routeTree.length > 0) {
+            lines.push("### Route Tree");
+            lines.push("");
+            lines.push("```");
+            printRouteTree(components.routeTree, lines, 0);
+            lines.push("```");
+            lines.push("");
+        }
+        lines.push("### Convention Exports");
+        lines.push("");
+        for (const [kind, count] of Object.entries(components.summary.routeConventions)) {
+            lines.push(`- ${kind}: ${count} modules`);
+        }
+        lines.push("");
+    }
+    if (hasServerRoutes) {
+        lines.push("### Server API Routes");
+        lines.push("");
+        for (const group of components.serverRoutes) {
+            const handler = group.handler ? ` (${group.handler})` : "";
+            lines.push(`**${group.prefix}**${handler} — \`${group.file}\``);
+            lines.push("");
+            lines.push("```");
+            for (const r of group.routes) {
+                lines.push(`${r.method.padEnd(7)} ${r.path}`);
+            }
+            lines.push("```");
+            lines.push("");
+        }
+    }
+    if (components && components.summary.totalComponents > 0) {
+        lines.push(`### Components: ${components.summary.totalComponents} total, ${components.summary.totalUsageEdges} usage edges`);
+        lines.push("");
+        if (components.summary.mostUsedComponents.length > 0) {
+            lines.push("Most used:");
+            for (const comp of components.summary.mostUsedComponents.slice(0, 10)) {
+                lines.push(`- \`${comp.name}\` in \`${comp.file}\` (${comp.usageCount} uses)`);
+            }
+            lines.push("");
+        }
+    }
+    return lines;
+}
+function buildFindings(zones) {
+    const findings = zones.findings ?? [];
+    if (findings.length === 0)
+        return [];
+    const lines = [];
+    lines.push("## Findings");
+    lines.push("");
+    // Group by type
+    const byType = new Map();
+    for (const f of findings) {
+        if (!byType.has(f.type))
+            byType.set(f.type, []);
+        byType.get(f.type).push(f);
+    }
+    const typeOrder = ["anti-pattern", "pattern", "relationship", "observation", "suggestion"];
+    for (const type of typeOrder) {
+        const group = byType.get(type);
+        if (!group?.length)
+            continue;
+        lines.push(`### ${type.charAt(0).toUpperCase() + type.slice(1)}s`);
+        lines.push("");
+        for (const f of group.slice(0, 10)) {
+            const sev = f.severity ? ` [${f.severity}]` : "";
+            const scope = f.scope !== "global" ? ` (${f.scope})` : "";
+            lines.push(`- ${f.text}${sev}${scope}`);
+        }
+        if (group.length > 10) {
+            lines.push(`- ... and ${group.length - 10} more`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function buildNextSteps(zones) {
+    const nextSteps = deriveNextSteps(zones);
+    if (nextSteps.length === 0)
+        return [];
+    const lines = [];
+    lines.push("## Next Steps");
+    lines.push("");
+    lines.push("Prioritized work items derived from analysis:");
+    lines.push("");
+    const byPriority = { high: [], medium: [], low: [] };
+    for (const step of nextSteps) {
+        byPriority[step.priority].push(step);
+    }
+    for (const [priority, steps] of Object.entries(byPriority)) {
+        if (steps.length === 0)
+            continue;
+        lines.push(`### ${priority.charAt(0).toUpperCase() + priority.slice(1)} Priority`);
+        lines.push("");
+        for (const step of steps.slice(0, 10)) {
+            const zone = zones.zones.find((z) => z.id === step.scope);
+            const files = zone ? zone.files.slice(0, 3).map((f) => `\`${f}\``).join(", ") : "";
+            lines.push(`1. **${step.title}**`);
+            if (files) {
+                lines.push(`   Files: ${files}`);
+            }
+            lines.push("");
+        }
+    }
+    return lines;
+}
+function buildFileInventory(inventory, zones, classifications) {
+    const lines = [];
+    lines.push("## File Inventory");
+    lines.push("");
+    // Build zone lookup
+    const fileToZone = new Map();
+    for (const zone of zones.zones) {
+        for (const file of zone.files) {
+            fileToZone.set(file, zone.id);
+        }
+    }
+    const archetypeMap = buildClassificationMap(classifications);
+    lines.push("| Path | Role | Archetype | Zone |");
+    lines.push("|------|------|-----------|------|");
+    for (const file of inventory.files) {
+        const zone = fileToZone.get(file.path) ?? "";
+        const archetype = archetypeMap.get(file.path) ?? "";
+        lines.push(`| \`${file.path}\` | ${file.role} | ${archetype} | ${zone} |`);
+    }
+    lines.push("");
+    return lines;
+}
+function buildTooling() {
+    return [
+        "## Tooling",
+        "",
+        "This project uses n-dx for codebase analysis (Sourcevision) and requirement",
+        "tracking (Rex). MCP tools are available for interactive access to analysis",
+        "data and PRD management. Skills available: /plan, /status, /capture,",
+        "/zone, /work, /configure.",
+        "",
+    ];
+}
+// ── Shared helpers ────────────────────────────────────────────────────────
+function printRouteTree(nodes, lines, depth) {
+    for (const node of nodes) {
+        const indent = "  ".repeat(depth);
+        lines.push(`${indent}${node.routePattern} → ${node.file}`);
+        printRouteTree(node.children, lines, depth + 1);
+    }
+}
+//# sourceMappingURL=llms-txt.js.map

package/packages/sourcevision/dist/analyzers/llms-txt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt.js","sourceRoot":"","sources":["../../src/analyzers/llms-txt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,SAAoB,EACpB,OAAgB,EAChB,KAAY,EACZ,UAA8B,EAC9B,eAAwC;IAExC,MAAM,KAAK,GAAa;QACtB,GAAG,oBAAoB,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC;QACnD,GAAG,sBAAsB,CAAC,KAAK,CAAC;QAChC,GAAG,oBAAoB,CAAC,OAAO,CAAC;QAChC,GAAG,mBAAmB,CAAC,UAAU,CAAC;QAClC,GAAG,aAAa,CAAC,KAAK,CAAC;QACvB,GAAG,cAAc,CAAC,KAAK,CAAC;QACxB,GAAG,kBAAkB,CAAC,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC;QACxD,GAAG,YAAY,EAAE;KAClB,CAAC;IAEF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,6EAA6E;AAE7E,SAAS,oBAAoB,CAAC,QAAkB,EAAE,SAAoB,EAAE,KAAY;IAClF,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,MAAM,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,SAAS,CAAC;IACtE,KAAK,CAAC,IAAI,CAAC,KAAK,WAAW,EAAE,CAAC,CAAC;IAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,CAAC,2FAA2F,CAAC,CAAC;IACxG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;SAC/D,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,KAAK,CAAC,CAAC;IAEf,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,SAAS,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC3D,KAAK,CAAC,IAAI,CAAC,wBAAwB,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAEpF,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC;SAC1D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SAC7B,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC;SAC5C,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,KAAK,CAAC,IAAI,CAAC,oBAAoB,QAAQ,EAAE,CAAC,CAAC;IAE3C,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;IACvE,KAAK,CAAC,IAAI,CAAC,gBAAgB,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,cAAc,qBAAqB,CAAC,CAAC;IAEvF,IAAI,OAAO,EAAE,CAAC;QACZ,KAAK,CAAC,IAAI,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,mBAAmB,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAY;IAC1C,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7F,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1J,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,mCAAmC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;QACzF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,oBAAoB,CAAC,OAAgB;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAClC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YAC7D,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,KAAK,WAAW,CAAC,CAAC;QAC3D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;aACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;aACzD,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,eAAe,GAAG,CAAC,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC;QAC9E,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,aAAa,gCAAgC,CAAC,CAAC;QACnF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACzD,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC;QACvE,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAAC,UAA8B;IACzD,MAAM,eAAe,GAAG,UAAU,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,UAAU,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IAEzE,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe;QAAE,OAAO,EAAE,CAAC;IAEpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,UAAU,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,cAAc,CAAC,UAAU,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;YAChF,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,UAAU,CAAC,CAAC;QAC5C,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,eAAe,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,KAAK,OAAO,QAAQ,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAChD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,IAAI,UAAU,IAAI,UAAU,CAAC,OAAO,CAAC,eAAe,GAAG,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,mBAAmB,UAAU,CAAC,OAAO,CAAC,eAAe,WAAW,UAAU,CAAC,OAAO,CAAC,eAAe,cAAc,CAAC,CAAC;QAC7H,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,IAAI,UAAU,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;gBACtE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,WAAW,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,UAAU,QAAQ,CAAC,CAAC;YACjF,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa,CAAC,KAAY;IACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACtC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAErC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,gBAAgB;IAChB,MAAM,MAAM,GAAG,IAAI,GAAG,EAA2B,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,SAAS,GAAG,CAAC,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;IAC3F,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,EAAE,MAAM;YAAE,SAAS;QAE7B,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACnE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,MAAM,GAAG,EAAE,OAAO,CAAC,CAAC;QACpD,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,KAAY;IAClC,MAAM,SAAS,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACzC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,MAAM,UAAU,GAAG,EAAE,IAAI,EAAE,EAAsB,EAAE,MAAM,EAAE,EAAsB,EAAE,GAAG,EAAE,EAAsB,EAAE,CAAC;IACjH,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;QAC7B,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACjC,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QACnF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,EAAE,CAAC;gBACV,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,EAAE,CAAC,CAAC;YACnC,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,SAAoB,EAAE,KAAY,EAAE,eAAwC;IACtG,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,oBAAoB;IACpB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,sBAAsB,CAAC,eAAe,CAAC,CAAC;IAE7D,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IACjD,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACpD,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,IAAI,MAAM,SAAS,MAAM,IAAI,IAAI,CAAC,CAAC;IAC7E,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,YAAY;IACnB,OAAO;QACL,YAAY;QACZ,EAAE;QACF,6EAA6E;QAC7E,4EAA4E;QAC5E,sEAAsE;QACtE,2BAA2B;QAC3B,EAAE;KACH,CAAC;AACJ,CAAC;AAED,6EAA6E;AAE7E,SAAS,cAAc,CAAC,KAAgD,EAAE,KAAe,EAAE,KAAa;IACtG,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,YAAY,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3D,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,123 @@
+/**
+ * Louvain community detection for zone analysis.
+ *
+ * Identifies natural architectural boundaries (zones) from the import graph
+ * using the Louvain modularity optimization algorithm. The algorithm groups
+ * tightly-interconnected files into communities while minimizing cross-group
+ * edges, mirroring how developers naturally organize code.
+ *
+ * ## Why Louvain works for codebases
+ *
+ * Import graphs exhibit strong community structure: files within a feature
+ * or package import each other frequently but rarely reach across boundaries.
+ * Louvain detects this automatically, producing zones that match intuitive
+ * architectural groupings without any configuration.
+ *
+ * ## Cohesion scoring
+ *
+ * When the algorithm finds zones with cohesion 1.0 and coupling 0.0, it means
+ * all import edges for that zone's files stay within the zone — a sign of
+ * excellent encapsulation. This typically happens with well-structured packages
+ * that expose clean public interfaces.
+ *
+ * Zones where multiple files have **no** import edges at all receive cohesion
+ * 0.0 — the absence of edges means cohesion is unmeasurable, not perfect.
+ * Single-file zones are the exception: cohesion is trivially 1.0.
+ *
+ * ## Pipeline
+ *
+ * 1. {@link buildUndirectedGraph} — convert directed imports to weighted edges
+ * 2. {@link louvainPhase1} — modularity optimization (deterministic)
+ * 3. {@link mergeBidirectionalCoupling} — combine over-coupled communities
+ * 4. {@link mergeSmallCommunities} — absorb tiny fragments into neighbors
+ * 5. {@link capZoneCount} — enforce maximum zone limit
+ * 6. {@link splitLargeCommunities} — subdivide oversized communities
+ *
+ * All steps are deterministic: same import graph → same zones every time.
+ *
+ * @module
+ */
+import type { ImportEdge } from "../schema/index.js";
+/** Adjacency map: node → neighbor → weight */
+export type UndirectedGraph = Map<string, Map<string, number>>;
+/**
+ * Convert directed import edges into an undirected weighted graph.
+ * Weight = number of symbols imported (min 1).
+ */
+export declare function buildUndirectedGraph(edges: ImportEdge[]): UndirectedGraph;
+/**
+ * Louvain modularity optimization (phase 1).
+ * Returns a map of node → community ID.
+ *
+ * Deterministic: nodes processed in sorted order, ties broken lexicographically.
+ */
+export declare function louvainPhase1(graph: UndirectedGraph, maxPasses?: number, resolution?: number): Map<string, string>;
+/**
+ * Communities with fewer than `minSize` files get absorbed into
+ * their most-connected neighbor community.
+ */
+export declare function mergeSmallCommunities(community: Map<string, string>, graph: UndirectedGraph, minSize?: number): Map<string, string>;
+/**
+ * Merge communities that are bidirectionally over-coupled.
+ *
+ * For each pair of communities, compute:
+ *   crossEdges(A, B) / min(internalEdges(A), internalEdges(B))
+ *
+ * If this ratio exceeds `threshold`, the smaller community is absorbed
+ * into the larger one. Single pass, conservative — only merges clearly
+ * over-coupled pairs.
+ */
+export declare function mergeBidirectionalCoupling(community: Map<string, string>, graph: UndirectedGraph, threshold?: number): Map<string, string>;
+/**
+ * Absorb small communities that are more coupled to their neighbors than
+ * internally cohesive. These "satellites" are too small and too dependent
+ * to justify a separate zone.
+ *
+ * For each community with ≤ `maxSize` files, compute:
+ *   externalEdges / totalEdges (= coupling ratio)
+ *
+ * If this ratio exceeds `couplingThreshold`, the community is absorbed into
+ * its most-connected neighbor. Iterates until no more merges occur.
+ */
+export declare function mergeSatelliteCommunities(community: Map<string, string>, graph: UndirectedGraph, maxSize?: number, couplingThreshold?: number): Map<string, string>;
+/**
+ * Split communities that exceed `maxSize` files by running Louvain
+ * internally on their subgraph with increasing resolution (γ).
+ *
+ * Standard Louvain (γ=1) has a resolution limit that prevents it from
+ * finding sub-communities inside dense, uniformly-connected subgraphs —
+ * exactly what happens when routes → components → utils form one big
+ * cluster. Increasing γ penalises large communities, forcing splits.
+ *
+ * Iterates until no oversized communities remain or no further splits
+ * are possible. Deterministic: processes communities in sorted order.
+ */
+export declare function splitLargeCommunities(community: Map<string, string>, graph: UndirectedGraph, maxSize: number): Map<string, string>;
+/**
+ * Add chain-topology edges between files sharing a parent directory.
+ *
+ * Groups files by immediate parent directory, sorts each group, then adds
+ * edges between sorted adjacent pairs. This brings import-isolated files
+ * (configs, scripts, etc.) into the Louvain graph and gives the algorithm
+ * directory-structure awareness — critical for convention-based frameworks
+ * where directory layout defines architecture.
+ *
+ * Chain topology produces O(n) edges per directory (vs O(n²) for clique),
+ * providing enough signal without overwhelming import-based edge weights.
+ *
+ * @param weight - Edge weight for proximity edges (default 0.2).
+ *   Low enough to not override import edges (weight ≥1) but high enough
+ *   to influence clustering of otherwise-disconnected files.
+ */
+export declare function addDirectoryProximityEdges(graph: UndirectedGraph, files: string[], weight?: number): void;
+export declare function capZoneCount(community: Map<string, string>, graph: UndirectedGraph, maxZones: number): Map<string, string>;
+/**
+ * Split files into communities based on directory structure.
+ * Used as a fallback when Louvain cannot split an oversized community
+ * (e.g., fully-connected import graph with no internal structure).
+ *
+ * Groups files by their directory prefix (depth 2, falling back to depth 3
+ * if all files share the same depth-2 prefix). Returns null if files cannot
+ * be meaningfully split by directory.
+ */
+export declare function splitByDirectory(files: string[], _maxSize: number): Map<string, string> | null;