@bugsbunnycodes1998/cartographer-core 0.1.0

package/dist/errors.js

@@ -0,0 +1,39 @@
+export class CartographerError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "CartographerError";
+    }
+}
+export class IngestionError extends CartographerError {
+    constructor(message, code = "INGESTION_ERROR", options) {
+        super(message, code, options);
+        this.name = "IngestionError";
+    }
+}
+export class AnalysisError extends CartographerError {
+    constructor(message, code = "ANALYSIS_ERROR", options) {
+        super(message, code, options);
+        this.name = "AnalysisError";
+    }
+}
+export class GraphError extends CartographerError {
+    constructor(message, code = "GRAPH_ERROR", options) {
+        super(message, code, options);
+        this.name = "GraphError";
+    }
+}
+export class GitError extends CartographerError {
+    constructor(message, code = "GIT_ERROR", options) {
+        super(message, code, options);
+        this.name = "GitError";
+    }
+}
+export class LlmError extends CartographerError {
+    constructor(message, code = "LLM_ERROR", options) {
+        super(message, code, options);
+        this.name = "LlmError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAGxB;IAFlB,YACE,OAAe,EACC,IAAY,EAC5B,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAQ;QAI5B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,iBAAiB;IACnD,YAAY,OAAe,EAAE,OAAe,iBAAiB,EAAE,OAAsB;QACnF,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IAClD,YAAY,OAAe,EAAE,OAAe,gBAAgB,EAAE,OAAsB;QAClF,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,UAAW,SAAQ,iBAAiB;IAC/C,YAAY,OAAe,EAAE,OAAe,aAAa,EAAE,OAAsB;QAC/E,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,QAAS,SAAQ,iBAAiB;IAC7C,YAAY,OAAe,EAAE,OAAe,WAAW,EAAE,OAAsB;QAC7E,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,OAAO,QAAS,SAAQ,iBAAiB;IAC7C,YAAY,OAAe,EAAE,OAAe,WAAW,EAAE,OAAsB;QAC7E,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/expeditions/custom.d.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+import type { GraphNode, GraphEdge, Expedition } from "../types/index.js";
+import type { OpenAIClient } from "../analysis/semantic/openai-client.js";
+/**
+ * Generate a custom expedition from a user's natural-language question.
+ *
+ * Sends the question along with a summary of available nodes and edges
+ * to the LLM, which returns a structured Expedition JSON.
+ */
+export declare function generateCustomExpedition(question: string, nodes: GraphNode[], edges: GraphEdge[], client: OpenAIClient, db: Database.Database): Promise<Expedition>;
+//# sourceMappingURL=custom.d.ts.map

package/dist/expeditions/custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../src/expeditions/custom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAmB1E;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,SAAS,EAAE,EAClB,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE,QAAQ,CAAC,QAAQ,GACpB,OAAO,CAAC,UAAU,CAAC,CAiErB"}

package/dist/expeditions/custom.js

@@ -0,0 +1,61 @@
+import { expeditionPrompt } from "../analysis/semantic/prompts.js";
+import { createCacheKey, getCachedResult, setCachedResult } from "../analysis/semantic/cache.js";
+import { logger } from "../logger.js";
+/**
+ * Generate a custom expedition from a user's natural-language question.
+ *
+ * Sends the question along with a summary of available nodes and edges
+ * to the LLM, which returns a structured Expedition JSON.
+ */
+export async function generateCustomExpedition(question, nodes, edges, client, db) {
+    // Build compact summaries for the LLM
+    const moduleSummaries = nodes
+        .filter((n) => n.kind === "module")
+        .map((n) => ({ name: n.name, id: n.id, summary: n.summary ?? "no summary" }));
+    const callGraphSummary = edges
+        .filter((e) => e.kind === "calls")
+        .slice(0, 50) // Limit to keep prompt size reasonable
+        .map((e) => `${e.sourceId} -> ${e.targetId}`);
+    const nodeIds = new Set(nodes.map((n) => n.id));
+    // Check cache
+    const cacheInput = `${question}|${moduleSummaries.map((m) => m.id).join(",")}`;
+    const cacheKey = createCacheKey(cacheInput, "expedition");
+    const cached = getCachedResult(db, cacheKey, "expedition");
+    if (cached) {
+        try {
+            return JSON.parse(cached);
+        }
+        catch {
+            logger.debug("Cached expedition parse failed, regenerating");
+        }
+    }
+    const { system, user } = expeditionPrompt(question, callGraphSummary.join("\n"), moduleSummaries.map((m) => `- ${m.name} (${m.id}): ${m.summary}`));
+    const { result, tokensUsed } = await client.completeJSON([
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ], "gpt-4o");
+    // Validate and sanitize node IDs — only keep steps with valid nodeIds
+    const validSteps = result.steps
+        .filter((step) => nodeIds.has(step.nodeId))
+        .map((step) => ({
+        nodeId: step.nodeId,
+        zoomLevel: (Math.min(Math.max(step.zoomLevel, 0), 3)),
+        narration: step.narration,
+        highlightEdges: step.highlightEdges ?? [],
+        highlightNodes: (step.highlightNodes ?? []).filter((id) => nodeIds.has(id)),
+        duration: step.duration ?? 6,
+        action: step.action,
+    }));
+    const expedition = {
+        id: `expedition:custom-${Date.now()}`,
+        title: result.title || `Custom: ${question.slice(0, 40)}`,
+        description: result.description || question,
+        kind: "custom",
+        estimatedMinutes: Math.max(1, Math.round(validSteps.length * 6 / 60)),
+        steps: validSteps,
+    };
+    // Cache the result
+    setCachedResult(db, cacheKey, "gpt-4o", "expedition", JSON.stringify(expedition), tokensUsed);
+    return expedition;
+}
+//# sourceMappingURL=custom.js.map

package/dist/expeditions/custom.js.map

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

package/dist/expeditions/danger-zones.d.ts

@@ -0,0 +1,9 @@
+import type { GraphNode, Expedition } from "../types/index.js";
+/**
+ * Generate a "Danger Zones" expedition that visits the most problematic
+ * files in the codebase — low health, high complexity, high churn.
+ *
+ * No LLM required.
+ */
+export declare function generateDangerZones(fileNodes: GraphNode[]): Expedition;
+//# sourceMappingURL=danger-zones.d.ts.map

package/dist/expeditions/danger-zones.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"danger-zones.d.ts","sourceRoot":"","sources":["../../src/expeditions/danger-zones.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAc/E;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,EAAE,GACrB,UAAU,CA6BZ"}

package/dist/expeditions/danger-zones.js

@@ -0,0 +1,42 @@
+/**
+ * Score a file node for "danger" based on health, complexity, and churn.
+ * Higher score = more dangerous.
+ */
+function dangerScore(node) {
+    return ((100 - node.healthScore) * 0.4 +
+        node.complexity * 0.3 +
+        node.churnScore * 100 * 0.3);
+}
+/**
+ * Generate a "Danger Zones" expedition that visits the most problematic
+ * files in the codebase — low health, high complexity, high churn.
+ *
+ * No LLM required.
+ */
+export function generateDangerZones(fileNodes) {
+    // Score and sort descending
+    const scored = fileNodes
+        .filter((n) => n.kind === "file")
+        .map((n) => ({ node: n, score: dangerScore(n) }))
+        .sort((a, b) => b.score - a.score);
+    // Take top 7
+    const topDanger = scored.slice(0, 7);
+    const steps = topDanger.map(({ node }) => ({
+        nodeId: node.id,
+        zoomLevel: 1,
+        narration: `Warning: ${node.name} — Health: ${node.healthScore}/100, Complexity: ${node.complexity}. ${node.summary ?? ""}`.trim(),
+        highlightEdges: [],
+        highlightNodes: [node.id],
+        duration: 8,
+    }));
+    const estimatedMinutes = Math.max(1, Math.round(steps.length * 8 / 60));
+    return {
+        id: "expedition:danger-zones",
+        title: "Danger Zones",
+        description: "Tour the most problematic files — high complexity, low health, and frequent changes.",
+        kind: "danger_zones",
+        estimatedMinutes,
+        steps,
+    };
+}
+//# sourceMappingURL=danger-zones.js.map

package/dist/expeditions/danger-zones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"danger-zones.js","sourceRoot":"","sources":["../../src/expeditions/danger-zones.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,SAAS,WAAW,CAAC,IAAe;IAClC,OAAO,CACL,CAAC,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,GAAG;QAC9B,IAAI,CAAC,UAAU,GAAG,GAAG;QACrB,IAAI,CAAC,UAAU,GAAG,GAAG,GAAG,GAAG,CAC5B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAsB;IAEtB,4BAA4B;IAC5B,MAAM,MAAM,GAAG,SAAS;SACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SAChD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAErC,aAAa;IACb,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAErC,MAAM,KAAK,GAAqB,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,SAAS,EAAE,CAAU;QACrB,SAAS,EAAE,YAAY,IAAI,CAAC,IAAI,cAAc,IAAI,CAAC,WAAW,qBAAqB,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;QAClI,cAAc,EAAE,EAAE;QAClB,cAAc,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,QAAQ,EAAE,CAAC;KACZ,CAAC,CAAC,CAAC;IAEJ,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAExE,OAAO;QACL,EAAE,EAAE,yBAAyB;QAC7B,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,sFAAsF;QACnG,IAAI,EAAE,cAAc;QACpB,gBAAgB;QAChB,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/expeditions/generator.d.ts

@@ -0,0 +1,21 @@
+import type Database from "better-sqlite3";
+import type { GraphNode, GraphEdge, Expedition, ModuleInfo, ProgressEvent } from "../types/index.js";
+import type { OpenAIClient } from "../analysis/semantic/openai-client.js";
+export interface GenerateExpeditionsOptions {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    callEdges: GraphEdge[];
+    modules: ModuleInfo[];
+    client?: OpenAIClient;
+    db?: Database.Database;
+    onProgress?: (event: ProgressEvent) => void;
+}
+/**
+ * Generate all available expeditions for the analyzed codebase.
+ *
+ * - Grand Tour is always generated (no LLM needed).
+ * - Danger Zones is always generated (no LLM needed).
+ * - Request Flow is generated when call edges are available.
+ */
+export declare function generateExpeditions(options: GenerateExpeditionsOptions): Promise<Expedition[]>;
+//# sourceMappingURL=generator.d.ts.map

package/dist/expeditions/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/expeditions/generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACrG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAM1E,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,EAAE,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACvB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,UAAU,EAAE,CAAC,CA4EvB"}

package/dist/expeditions/generator.js

@@ -0,0 +1,78 @@
+import { generateGrandTour } from "./grand-tour.js";
+import { generateDangerZones } from "./danger-zones.js";
+import { generateRequestFlow } from "./request-flow.js";
+import { logger } from "../logger.js";
+/**
+ * Generate all available expeditions for the analyzed codebase.
+ *
+ * - Grand Tour is always generated (no LLM needed).
+ * - Danger Zones is always generated (no LLM needed).
+ * - Request Flow is generated when call edges are available.
+ */
+export async function generateExpeditions(options) {
+    const { nodes, edges, callEdges, onProgress } = options;
+    const expeditions = [];
+    const emit = (message) => {
+        onProgress?.({ stage: "expeditions", message });
+    };
+    // Module-level nodes and edges for grand tour
+    const moduleNodes = nodes.filter((n) => n.kind === "module");
+    const moduleEdges = edges.filter((e) => e.kind === "imports" && e.sourceId.startsWith("mod:") && e.targetId.startsWith("mod:"));
+    // 1. Grand Tour (always)
+    if (moduleNodes.length > 0) {
+        emit("Generating Grand Tour...");
+        try {
+            const grandTour = generateGrandTour(moduleNodes, moduleEdges);
+            expeditions.push(grandTour);
+            logger.debug(`Grand Tour: ${grandTour.steps.length} steps`);
+        }
+        catch (err) {
+            logger.warn(`Grand Tour generation failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // 2. Danger Zones (always)
+    const fileNodes = nodes.filter((n) => n.kind === "file");
+    if (fileNodes.length > 0) {
+        emit("Generating Danger Zones...");
+        try {
+            const dangerZones = generateDangerZones(fileNodes);
+            if (dangerZones.steps.length > 0) {
+                expeditions.push(dangerZones);
+                logger.debug(`Danger Zones: ${dangerZones.steps.length} steps`);
+            }
+        }
+        catch (err) {
+            logger.warn(`Danger Zones generation failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // 3. Request Flow (when call edges available)
+    if (callEdges.length > 0 || edges.some((e) => e.kind === "calls")) {
+        emit("Generating Request Flow...");
+        try {
+            const allCallEdges = [
+                ...callEdges,
+                ...edges.filter((e) => e.kind === "calls"),
+            ];
+            // Deduplicate
+            const seen = new Set();
+            const uniqueCallEdges = allCallEdges.filter((e) => {
+                const key = `${e.sourceId}|${e.targetId}`;
+                if (seen.has(key))
+                    return false;
+                seen.add(key);
+                return true;
+            });
+            const requestFlow = await generateRequestFlow(nodes, uniqueCallEdges, moduleEdges, options.client, options.db);
+            if (requestFlow) {
+                expeditions.push(requestFlow);
+                logger.debug(`Request Flow: ${requestFlow.steps.length} steps`);
+            }
+        }
+        catch (err) {
+            logger.warn(`Request Flow generation failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    emit(`Generated ${expeditions.length} expedition(s)`);
+    return expeditions;
+}
+//# sourceMappingURL=generator.js.map

package/dist/expeditions/generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../src/expeditions/generator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAYtC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAmC;IAEnC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE;QAC/B,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC;IAEF,8CAA8C;IAC9C,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAC9F,CAAC;IAEF,yBAAyB;IACzB,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,iBAAiB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YAC9D,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC5B,MAAM,CAAC,KAAK,CAAC,eAAe,SAAS,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,iCAAiC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IACzD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,IAAI,CAAC,4BAA4B,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,WAAW,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;YACnD,IAAI,WAAW,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC9B,MAAM,CAAC,KAAK,CAAC,iBAAiB,WAAW,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,mCAAmC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,4BAA4B,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG;gBACnB,GAAG,SAAS;gBACZ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;aAC3C,CAAC;YACF,cAAc;YACd,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,MAAM,eAAe,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBAChD,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAC1C,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,OAAO,KAAK,CAAC;gBAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;YAEH,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAC3C,KAAK,EACL,eAAe,EACf,WAAW,EACX,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,EAAE,CACX,CAAC;YACF,IAAI,WAAW,EAAE,CAAC;gBAChB,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC9B,MAAM,CAAC,KAAK,CAAC,iBAAiB,WAAW,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,mCAAmC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAED,IAAI,CAAC,aAAa,WAAW,CAAC,MAAM,gBAAgB,CAAC,CAAC;IACtD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/expeditions/grand-tour.d.ts

@@ -0,0 +1,10 @@
+import type { GraphNode, GraphEdge, Expedition } from "../types/index.js";
+/**
+ * Generate a "Grand Tour" expedition that visits every module in
+ * topological dependency order (leaf deps first, entry points last).
+ *
+ * No LLM required — uses module summaries if available, otherwise
+ * template narration.
+ */
+export declare function generateGrandTour(modules: GraphNode[], moduleEdges: GraphEdge[]): Expedition;
+//# sourceMappingURL=grand-tour.d.ts.map

package/dist/expeditions/grand-tour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grand-tour.d.ts","sourceRoot":"","sources":["../../src/expeditions/grand-tour.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAwD1F;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,EAAE,EACpB,WAAW,EAAE,SAAS,EAAE,GACvB,UAAU,CA8CZ"}

package/dist/expeditions/grand-tour.js

@@ -0,0 +1,96 @@
+/**
+ * Topologically sort module IDs by their dependency edges.
+ * Leaf dependencies come first, entry points last.
+ * Falls back to original order for any cycle participants.
+ */
+function topologicalSort(moduleIds, edges) {
+    const adj = new Map();
+    const inDegree = new Map();
+    const idSet = new Set(moduleIds);
+    for (const id of moduleIds) {
+        adj.set(id, []);
+        inDegree.set(id, 0);
+    }
+    for (const edge of edges) {
+        if (!idSet.has(edge.sourceId) || !idSet.has(edge.targetId))
+            continue;
+        // sourceId imports from targetId, so target is a dependency
+        // We want dependencies first, so edge direction: targetId -> sourceId in topo order
+        adj.get(edge.targetId).push(edge.sourceId);
+        inDegree.set(edge.sourceId, (inDegree.get(edge.sourceId) ?? 0) + 1);
+    }
+    // Kahn's algorithm
+    const queue = [];
+    for (const [id, deg] of inDegree) {
+        if (deg === 0) {
+            queue.push(id);
+        }
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        sorted.push(node);
+        for (const neighbor of adj.get(node) ?? []) {
+            const newDeg = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDeg);
+            if (newDeg === 0) {
+                queue.push(neighbor);
+            }
+        }
+    }
+    // Append any modules not reached (cycle participants) at the end
+    for (const id of moduleIds) {
+        if (!sorted.includes(id)) {
+            sorted.push(id);
+        }
+    }
+    return sorted;
+}
+/**
+ * Generate a "Grand Tour" expedition that visits every module in
+ * topological dependency order (leaf deps first, entry points last).
+ *
+ * No LLM required — uses module summaries if available, otherwise
+ * template narration.
+ */
+export function generateGrandTour(modules, moduleEdges) {
+    const moduleIds = modules.map((m) => m.id);
+    const sortedIds = topologicalSort(moduleIds, moduleEdges);
+    // Map for quick lookup
+    const moduleMap = new Map(modules.map((m) => [m.id, m]));
+    const steps = [];
+    for (const modId of sortedIds) {
+        const mod = moduleMap.get(modId);
+        if (!mod)
+            continue;
+        const narration = mod.summary ?? `Module: ${mod.name}`;
+        // Step 1: Satellite view — highlight the module
+        steps.push({
+            nodeId: modId,
+            zoomLevel: 0,
+            narration: `Overview of ${mod.name}: ${narration}`,
+            highlightEdges: [],
+            highlightNodes: [modId],
+            duration: 5,
+        });
+        // Step 2: Fly into the neighborhood
+        steps.push({
+            nodeId: modId,
+            zoomLevel: 1,
+            narration: `Exploring ${mod.name} — ${mod.loc} lines of code, health score ${mod.healthScore}/100.`,
+            highlightEdges: [],
+            highlightNodes: [modId],
+            duration: 5,
+        });
+    }
+    const estimatedMinutes = Math.max(1, Math.round(modules.length * 0.3));
+    return {
+        id: "expedition:grand-tour",
+        title: "Grand Tour",
+        description: "A guided tour through every module, following the dependency chain from foundations to entry points.",
+        kind: "grand_tour",
+        estimatedMinutes,
+        steps,
+    };
+}
+//# sourceMappingURL=grand-tour.js.map

package/dist/expeditions/grand-tour.js.map

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

package/dist/expeditions/request-flow.d.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+import type { GraphNode, GraphEdge, Expedition } from "../types/index.js";
+import type { OpenAIClient } from "../analysis/semantic/openai-client.js";
+/**
+ * Generate a "Request Flow" expedition that traces a request from an
+ * entry point through the call graph.
+ *
+ * Returns null if no entry points are found.
+ */
+export declare function generateRequestFlow(nodes: GraphNode[], callEdges: GraphEdge[], moduleEdges: GraphEdge[], client?: OpenAIClient, db?: Database.Database): Promise<Expedition | null>;
+//# sourceMappingURL=request-flow.d.ts.map

package/dist/expeditions/request-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-flow.d.ts","sourceRoot":"","sources":["../../src/expeditions/request-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAwG1E;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,SAAS,EAAE,EAClB,SAAS,EAAE,SAAS,EAAE,EACtB,WAAW,EAAE,SAAS,EAAE,EACxB,MAAM,CAAC,EAAE,YAAY,EACrB,EAAE,CAAC,EAAE,QAAQ,CAAC,QAAQ,GACrB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyD5B"}

package/dist/expeditions/request-flow.js

@@ -0,0 +1,138 @@
+import { logger } from "../logger.js";
+const ENTRY_POINT_PATTERN = /route|handler|controller|main|app|index/i;
+const API_LAYERS = new Set(["api", "presentation"]);
+/**
+ * Find likely entry-point nodes (API handlers, controllers, etc.).
+ */
+function findEntryPoints(nodes) {
+    const candidates = [];
+    for (const node of nodes) {
+        if (node.kind !== "file")
+            continue;
+        // Match by architectural layer
+        if (node.layer && API_LAYERS.has(node.layer)) {
+            candidates.push(node);
+            continue;
+        }
+        // Match by name pattern
+        if (node.name && ENTRY_POINT_PATTERN.test(node.name)) {
+            candidates.push(node);
+        }
+    }
+    // Sort by relevance: layer-matched first, then by name pattern
+    candidates.sort((a, b) => {
+        const aLayer = a.layer && API_LAYERS.has(a.layer) ? 0 : 1;
+        const bLayer = b.layer && API_LAYERS.has(b.layer) ? 0 : 1;
+        return aLayer - bLayer;
+    });
+    return candidates;
+}
+/**
+ * BFS from entry point through call edges, collecting visited nodes
+ * in order (max `limit` steps).
+ */
+function traceCallPath(entryNodeId, callEdges, nodeMap, limit) {
+    // Build adjacency: source -> target[] (caller calls callee)
+    const adj = new Map();
+    for (const edge of callEdges) {
+        const list = adj.get(edge.sourceId) ?? [];
+        list.push(edge.targetId);
+        adj.set(edge.sourceId, list);
+    }
+    // For entry at file level, find function nodes that are children of this file
+    const entryNode = nodeMap.get(entryNodeId);
+    const startIds = [];
+    if (entryNode?.kind === "file") {
+        // Find function nodes that belong to this file
+        for (const [id, node] of nodeMap) {
+            if (node.kind === "function" && node.parentId === entryNodeId) {
+                startIds.push(id);
+            }
+        }
+        // If no function children found, start from the file node itself
+        if (startIds.length === 0) {
+            startIds.push(entryNodeId);
+        }
+    }
+    else {
+        startIds.push(entryNodeId);
+    }
+    const visited = new Set();
+    const path = [];
+    const queue = [...startIds];
+    // Always include the entry file node first
+    if (entryNode) {
+        path.push(entryNode);
+        visited.add(entryNodeId);
+    }
+    while (queue.length > 0 && path.length < limit) {
+        const currentId = queue.shift();
+        visited.add(currentId);
+        const current = nodeMap.get(currentId);
+        if (current && !path.includes(current)) {
+            path.push(current);
+        }
+        for (const targetId of adj.get(currentId) ?? []) {
+            if (!visited.has(targetId)) {
+                queue.push(targetId);
+            }
+        }
+    }
+    return path;
+}
+/**
+ * Generate a "Request Flow" expedition that traces a request from an
+ * entry point through the call graph.
+ *
+ * Returns null if no entry points are found.
+ */
+export async function generateRequestFlow(nodes, callEdges, moduleEdges, client, db) {
+    const entryPoints = findEntryPoints(nodes);
+    if (entryPoints.length === 0) {
+        logger.debug("No entry points found for request flow expedition");
+        return null;
+    }
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    // Use the first (most relevant) entry point
+    const entry = entryPoints[0];
+    const tracedPath = traceCallPath(entry.id, callEdges, nodeMap, 15);
+    if (tracedPath.length < 2) {
+        logger.debug("Request flow trace too short (< 2 nodes), skipping");
+        return null;
+    }
+    const steps = tracedPath.map((node, idx) => {
+        // Progress from zoom level 1 to 2 as we go deeper
+        const zoomLevel = idx < 2 ? 1 : 2;
+        // Find edges from previous node to this node for highlighting
+        const highlightEdges = [];
+        if (idx > 0) {
+            const prevNode = tracedPath[idx - 1];
+            for (const edge of callEdges) {
+                if (edge.sourceId === prevNode.id && edge.targetId === node.id) {
+                    highlightEdges.push(`${edge.sourceId}|${edge.targetId}`);
+                }
+            }
+        }
+        const narration = node.kind === "function"
+            ? `Step ${idx + 1}: Function ${node.name} — ${node.summary ?? `${node.loc} lines, complexity ${node.complexity}`}`
+            : `Step ${idx + 1}: ${node.name} — ${node.summary ?? `${node.loc} lines of code`}`;
+        return {
+            nodeId: node.id,
+            zoomLevel,
+            narration,
+            highlightEdges,
+            highlightNodes: [node.id],
+            duration: 6,
+        };
+    });
+    const estimatedMinutes = Math.max(1, Math.round(steps.length * 6 / 60));
+    return {
+        id: "expedition:request-flow",
+        title: "Request Lifecycle",
+        description: `Trace a request from ${entry.name} through the call graph to see how data flows through the system.`,
+        kind: "request_flow",
+        estimatedMinutes,
+        steps,
+    };
+}
+//# sourceMappingURL=request-flow.js.map

package/dist/expeditions/request-flow.js.map

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

package/dist/graph/builder.d.ts

@@ -0,0 +1,23 @@
+import type { GraphNode, GraphEdge, ModuleInfo, FileAnalysis } from "../types/index.js";
+import type { FileMetrics, ModuleMetrics } from "../analysis/metrics.js";
+import type { GitArchaeologyResult } from "../analysis/git/archaeology.js";
+import type { SummarizationResult } from "../analysis/semantic/summarizer.js";
+import type { CallGraphResult } from "../analysis/call-graph.js";
+export interface BuildGraphOptions {
+    modules: ModuleInfo[];
+    analyses: FileAnalysis[];
+    moduleEdges: GraphEdge[];
+    fileMetrics: Map<string, FileMetrics>;
+    moduleMetrics: Map<string, ModuleMetrics>;
+    rootDir: string;
+    gitResult?: GitArchaeologyResult;
+    healthScores?: Map<string, number>;
+    summarization?: SummarizationResult;
+    callGraphResult?: CallGraphResult;
+}
+export interface BuildGraphResult {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export declare function buildGraph(opts: BuildGraphOptions): BuildGraphResult;
+//# sourceMappingURL=builder.d.ts.map

package/dist/graph/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/graph/builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAMjE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACtC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AA2BD,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CA0HpE"}