@mcp-graph-workflow/mcp-graph 5.6.1 → 5.7.0

package/README.md

@@ -114,7 +114,7 @@ mcp-graph serve --port 3000    # or: npm run dev
 
 | | Count | Reference |
 |---|---|---|
-| **MCP Tools** | 26 | [MCP-TOOLS-REFERENCE.md](docs/MCP-TOOLS-REFERENCE.md) |
+| **MCP Tools** | 32 | [MCP-TOOLS-REFERENCE.md](docs/MCP-TOOLS-REFERENCE.md) |
 | **REST Endpoints** | 44 (17 routers) | [REST-API-REFERENCE.md](docs/REST-API-REFERENCE.md) |
 | **CLI Commands** | 6 | `init`, `import`, `index`, `stats`, `serve`, `doctor` |
 
@@ -145,7 +145,7 @@ npm run test:all    # Everything
 |----------|-------------|
 | [Getting Started](docs/GETTING-STARTED.md) | Step-by-step guide for new users |
 | [Architecture](docs/ARCHITECTURE-GUIDE.md) | System layers, modules, data flows |
-| [MCP Tools Reference](docs/MCP-TOOLS-REFERENCE.md) | 26 tools with full parameters |
+| [MCP Tools Reference](docs/MCP-TOOLS-REFERENCE.md) | 32 tools with full parameters |
 | [REST API Reference](docs/REST-API-REFERENCE.md) | 17 routers, 44 endpoints |
 | [Knowledge Pipeline](docs/KNOWLEDGE-PIPELINE.md) | RAG, embeddings, context assembly |
 | [Integrations](docs/INTEGRATIONS-GUIDE.md) | Serena, GitNexus, Context7, Playwright |

package/dist/core/importer/import-graph.d.ts

@@ -0,0 +1,23 @@
+import type { SqliteStore } from "../store/sqlite-store.js";
+import type { GraphDocument } from "../graph/graph-types.js";
+export interface MergeGraphOptions {
+    dryRun?: boolean;
+}
+export interface MergeGraphResult {
+    nodesInserted: number;
+    nodesSkipped: number;
+    edgesInserted: number;
+    edgesSkipped: number;
+    edgesOrphaned: number;
+    sourceProject: string;
+}
+/**
+ * Merge an exported GraphDocument into the local store without overriding existing data.
+ *
+ * - Nodes with IDs already present locally are SKIPPED (local version wins).
+ * - Edges with the same (from, to, relationType) are SKIPPED via INSERT OR IGNORE.
+ * - Edges referencing nodes that don't exist (locally or in the import) are SKIPPED as orphans.
+ * - In dryRun mode, no data is written; only counts are returned.
+ */
+export declare function mergeGraph(store: SqliteStore, incoming: GraphDocument, options?: MergeGraphOptions): MergeGraphResult;
+//# sourceMappingURL=import-graph.d.ts.map

package/dist/core/importer/import-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-graph.d.ts","sourceRoot":"","sources":["../../../src/core/importer/import-graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,yBAAyB,CAAC;AAKxE,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CA+HlB"}

package/dist/core/importer/import-graph.js

@@ -0,0 +1,127 @@
+import { z } from "zod/v4";
+import { GraphDocumentSchema } from "../../schemas/graph.schema.js";
+import { ValidationError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Merge an exported GraphDocument into the local store without overriding existing data.
+ *
+ * - Nodes with IDs already present locally are SKIPPED (local version wins).
+ * - Edges with the same (from, to, relationType) are SKIPPED via INSERT OR IGNORE.
+ * - Edges referencing nodes that don't exist (locally or in the import) are SKIPPED as orphans.
+ * - In dryRun mode, no data is written; only counts are returned.
+ */
+export function mergeGraph(store, incoming, options) {
+    // 1. Validate incoming document
+    try {
+        GraphDocumentSchema.parse(incoming);
+    }
+    catch (err) {
+        if (err instanceof z.ZodError) {
+            throw new ValidationError("Invalid graph document", err.issues);
+        }
+        throw err;
+    }
+    const sourceProject = incoming.project.name;
+    const dryRun = options?.dryRun ?? false;
+    logger.info("merge-graph:start", {
+        sourceProject,
+        incomingNodes: incoming.nodes.length,
+        incomingEdges: incoming.edges.length,
+        dryRun,
+    });
+    // 2. Collect existing node IDs
+    const existingNodes = store.getAllNodes();
+    const existingNodeIds = new Set(existingNodes.map((n) => n.id));
+    // 3. Partition incoming nodes
+    const nodesToInsert = [];
+    let nodesSkipped = 0;
+    for (const node of incoming.nodes) {
+        if (existingNodeIds.has(node.id)) {
+            nodesSkipped++;
+        }
+        else {
+            // Tag with merge origin metadata
+            const taggedNode = {
+                ...node,
+                metadata: {
+                    ...node.metadata,
+                    mergedFrom: sourceProject,
+                },
+            };
+            nodesToInsert.push(taggedNode);
+        }
+    }
+    // 4. Build set of all available node IDs (existing + to-be-inserted)
+    const availableNodeIds = new Set(existingNodeIds);
+    for (const node of nodesToInsert) {
+        availableNodeIds.add(node.id);
+    }
+    // 5. Filter edges: keep only those where both from and to exist
+    const validEdges = [];
+    let edgesOrphaned = 0;
+    for (const edge of incoming.edges) {
+        if (availableNodeIds.has(edge.from) && availableNodeIds.has(edge.to)) {
+            validEdges.push(edge);
+        }
+        else {
+            edgesOrphaned++;
+        }
+    }
+    // 6. In dry-run mode, estimate edge skips without writing
+    if (dryRun) {
+        // We can't know exact edge skip counts without trying INSERT OR IGNORE,
+        // but we can count edges whose (from, to, relationType) match existing edges
+        const existingEdges = store.getAllEdges();
+        const existingEdgeKeys = new Set(existingEdges.map((e) => `${e.from}|${e.to}|${e.relationType}`));
+        let edgesInserted = 0;
+        let edgesSkipped = 0;
+        for (const edge of validEdges) {
+            const key = `${edge.from}|${edge.to}|${edge.relationType}`;
+            if (existingEdgeKeys.has(key)) {
+                edgesSkipped++;
+            }
+            else {
+                edgesInserted++;
+            }
+        }
+        logger.info("merge-graph:dry-run", {
+            nodesInserted: nodesToInsert.length,
+            nodesSkipped,
+            edgesInserted,
+            edgesSkipped,
+            edgesOrphaned,
+        });
+        return {
+            nodesInserted: nodesToInsert.length,
+            nodesSkipped,
+            edgesInserted,
+            edgesSkipped,
+            edgesOrphaned,
+            sourceProject,
+        };
+    }
+    // 7. Create snapshot before merge (safety net)
+    store.createSnapshot();
+    // 8. Perform merge insert
+    const { nodesInserted, edgesInserted } = store.mergeInsert(nodesToInsert, validEdges);
+    const edgesSkipped = validEdges.length - edgesInserted;
+    // 9. Record import
+    store.recordImport(`merge:${sourceProject}`, nodesInserted, edgesInserted);
+    logger.info("merge-graph:done", {
+        sourceProject,
+        nodesInserted,
+        nodesSkipped,
+        edgesInserted,
+        edgesSkipped,
+        edgesOrphaned,
+    });
+    return {
+        nodesInserted,
+        nodesSkipped,
+        edgesInserted,
+        edgesSkipped,
+        edgesOrphaned,
+        sourceProject,
+    };
+}
+//# sourceMappingURL=import-graph.js.map

package/dist/core/importer/import-graph.js.map

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

package/dist/core/rag/benchmark-indexer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Benchmark Indexer — indexes performance benchmark results as knowledge documents.
+ * Enables RAG queries about performance metrics, token economy, and SLA compliance.
+ */
+import type { KnowledgeStore } from "../store/knowledge-store.js";
+export interface BenchmarkMetric {
+    name: string;
+    value: number;
+    target: number;
+    passed: boolean;
+}
+export interface BenchmarkData {
+    timestamp: string;
+    metrics: BenchmarkMetric[];
+    tokenEconomy?: {
+        avgCompression: number;
+        totalTokensSaved: number;
+    };
+    toolUsage?: Record<string, {
+        inputTokens: number;
+        outputTokens: number;
+    }>;
+}
+export interface BenchmarkIndexResult {
+    documentsIndexed: number;
+}
+/**
+ * Index benchmark results into the knowledge store.
+ * Creates documents for metrics summary and token economy.
+ */
+export declare function indexBenchmarkResults(store: KnowledgeStore, data: BenchmarkData): BenchmarkIndexResult;
+//# sourceMappingURL=benchmark-indexer.d.ts.map

package/dist/core/rag/benchmark-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark-indexer.d.ts","sourceRoot":"","sources":["../../../src/core/rag/benchmark-indexer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAGlE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,aAAa,GAClB,oBAAoB,CAwFtB"}

package/dist/core/rag/benchmark-indexer.js

@@ -0,0 +1,85 @@
+/**
+ * Benchmark Indexer — indexes performance benchmark results as knowledge documents.
+ * Enables RAG queries about performance metrics, token economy, and SLA compliance.
+ */
+import { logger } from "../utils/logger.js";
+/**
+ * Index benchmark results into the knowledge store.
+ * Creates documents for metrics summary and token economy.
+ */
+export function indexBenchmarkResults(store, data) {
+    let documentsIndexed = 0;
+    // Index metrics summary
+    if (data.metrics.length > 0) {
+        const metricsLines = data.metrics.map((m) => {
+            const status = m.passed ? "PASSED" : "FAILED — exceeded target";
+            return `- ${m.name}: ${m.value} (target: ${m.target}) [${status}]`;
+        });
+        const passing = data.metrics.filter((m) => m.passed).length;
+        const failing = data.metrics.length - passing;
+        const content = [
+            `## Benchmark Results (${data.timestamp})`,
+            "",
+            `Summary: ${passing} passed, ${failing} failed out of ${data.metrics.length} metrics.`,
+            "",
+            ...metricsLines,
+        ].join("\n");
+        store.insert({
+            sourceType: "benchmark",
+            sourceId: `benchmark:${data.timestamp}`,
+            title: `Benchmark Results ${data.timestamp}`,
+            content,
+            chunkIndex: 0,
+            metadata: {
+                timestamp: data.timestamp,
+                totalMetrics: data.metrics.length,
+                passing,
+                failing,
+            },
+        });
+        documentsIndexed++;
+    }
+    // Index token economy
+    if (data.tokenEconomy) {
+        const content = [
+            `## Token Economy (${data.timestamp})`,
+            "",
+            `- Average compression ratio: ${data.tokenEconomy.avgCompression}`,
+            `- Total tokens saved: ${data.tokenEconomy.totalTokensSaved}`,
+        ].join("\n");
+        store.insert({
+            sourceType: "benchmark",
+            sourceId: `benchmark:token-economy:${data.timestamp}`,
+            title: `Token Economy ${data.timestamp}`,
+            content,
+            chunkIndex: 0,
+            metadata: {
+                timestamp: data.timestamp,
+                avgCompression: data.tokenEconomy.avgCompression,
+                totalTokensSaved: data.tokenEconomy.totalTokensSaved,
+            },
+        });
+        documentsIndexed++;
+    }
+    // Index tool usage
+    if (data.toolUsage && Object.keys(data.toolUsage).length > 0) {
+        const lines = Object.entries(data.toolUsage).map(([tool, usage]) => `- ${tool}: input=${usage.inputTokens}, output=${usage.outputTokens}`);
+        const content = [
+            `## Tool Token Usage (${data.timestamp})`,
+            "",
+            ...lines,
+        ].join("\n");
+        store.insert({
+            sourceType: "benchmark",
+            sourceId: `benchmark:tool-usage:${data.timestamp}`,
+            title: `Tool Token Usage ${data.timestamp}`,
+            content,
+            chunkIndex: 0,
+            metadata: { timestamp: data.timestamp },
+        });
+        documentsIndexed++;
+    }
+    logger.info("Benchmark results indexed", { documentsIndexed, timestamp: data.timestamp });
+    return { documentsIndexed };
+}
+//# sourceMappingURL=benchmark-indexer.js.map

package/dist/core/rag/benchmark-indexer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark-indexer.js","sourceRoot":"","sources":["../../../src/core/rag/benchmark-indexer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAuB5C;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAqB,EACrB,IAAmB;IAEnB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IAEzB,wBAAwB;IACxB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC1C,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,0BAA0B,CAAC;YAChE,OAAO,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,MAAM,MAAM,MAAM,GAAG,CAAC;QACrE,CAAC,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;QAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC;QAE9C,MAAM,OAAO,GAAG;YACd,yBAAyB,IAAI,CAAC,SAAS,GAAG;YAC1C,EAAE;YACF,YAAY,OAAO,YAAY,OAAO,kBAAkB,IAAI,CAAC,OAAO,CAAC,MAAM,WAAW;YACtF,EAAE;YACF,GAAG,YAAY;SAChB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,KAAK,CAAC,MAAM,CAAC;YACX,UAAU,EAAE,WAAW;YACvB,QAAQ,EAAE,aAAa,IAAI,CAAC,SAAS,EAAE;YACvC,KAAK,EAAE,qBAAqB,IAAI,CAAC,SAAS,EAAE;YAC5C,OAAO;YACP,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE;gBACR,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;gBACjC,OAAO;gBACP,OAAO;aACR;SACF,CAAC,CAAC;QACH,gBAAgB,EAAE,CAAC;IACrB,CAAC;IAED,sBAAsB;IACtB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG;YACd,qBAAqB,IAAI,CAAC,SAAS,GAAG;YACtC,EAAE;YACF,gCAAgC,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE;YAClE,yBAAyB,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE;SAC9D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,KAAK,CAAC,MAAM,CAAC;YACX,UAAU,EAAE,WAAW;YACvB,QAAQ,EAAE,2BAA2B,IAAI,CAAC,SAAS,EAAE;YACrD,KAAK,EAAE,iBAAiB,IAAI,CAAC,SAAS,EAAE;YACxC,OAAO;YACP,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE;gBACR,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,cAAc,EAAE,IAAI,CAAC,YAAY,CAAC,cAAc;gBAChD,gBAAgB,EAAE,IAAI,CAAC,YAAY,CAAC,gBAAgB;aACrD;SACF,CAAC,CAAC;QACH,gBAAgB,EAAE,CAAC;IACrB,CAAC;IAED,mBAAmB;IACnB,IAAI,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAC9C,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAChB,KAAK,IAAI,WAAW,KAAK,CAAC,WAAW,YAAY,KAAK,CAAC,YAAY,EAAE,CACxE,CAAC;QAEF,MAAM,OAAO,GAAG;YACd,wBAAwB,IAAI,CAAC,SAAS,GAAG;YACzC,EAAE;YACF,GAAG,KAAK;SACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,KAAK,CAAC,MAAM,CAAC;YACX,UAAU,EAAE,WAAW;YACvB,QAAQ,EAAE,wBAAwB,IAAI,CAAC,SAAS,EAAE;YAClD,KAAK,EAAE,oBAAoB,IAAI,CAAC,SAAS,EAAE;YAC3C,OAAO;YACP,UAAU,EAAE,CAAC;YACb,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;SACxC,CAAC,CAAC;QACH,gBAAgB,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IAE1F,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAC9B,CAAC"}

package/dist/core/rag/citation-mapper.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Citation Mapper — maps search results to citations with source traceability.
+ *
+ * Each chunk in the assembled context gets a [N] citation marker,
+ * enabling users to trace information back to its source.
+ */
+import type { RankedResult } from "./multi-strategy-retrieval.js";
+export interface Citation {
+    id: string;
+    chunkId: string;
+    sourceType: string;
+    sourceId: string;
+    title: string;
+    snippet: string;
+    relevanceScore: number;
+    position: number;
+}
+export interface CitedContext {
+    assembledText: string;
+    citations: Citation[];
+    sourceBreakdown: Record<string, number>;
+}
+/**
+ * Create citations from ranked results.
+ * Each result gets a position-based citation (1-indexed).
+ */
+export declare function mapCitations(results: RankedResult[]): Citation[];
+/**
+ * Build a cited context: assembled text with [N] markers + citation list + source breakdown.
+ */
+export declare function buildCitedContext(results: RankedResult[]): CitedContext;
+//# sourceMappingURL=citation-mapper.d.ts.map

package/dist/core/rag/citation-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-mapper.d.ts","sourceRoot":"","sources":["../../../src/core/rag/citation-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGlE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,QAAQ,EAAE,CAahE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,CAoBvE"}

package/dist/core/rag/citation-mapper.js

@@ -0,0 +1,45 @@
+/**
+ * Citation Mapper — maps search results to citations with source traceability.
+ *
+ * Each chunk in the assembled context gets a [N] citation marker,
+ * enabling users to trace information back to its source.
+ */
+import { generateId } from "../utils/id.js";
+const MAX_SNIPPET_LENGTH = 400;
+/**
+ * Create citations from ranked results.
+ * Each result gets a position-based citation (1-indexed).
+ */
+export function mapCitations(results) {
+    return results.map((r, i) => ({
+        id: generateId("cite"),
+        chunkId: r.id,
+        sourceType: r.sourceType,
+        sourceId: r.sourceId,
+        title: r.title,
+        snippet: r.content.length > MAX_SNIPPET_LENGTH
+            ? r.content.slice(0, MAX_SNIPPET_LENGTH)
+            : r.content,
+        relevanceScore: r.score,
+        position: i + 1,
+    }));
+}
+/**
+ * Build a cited context: assembled text with [N] markers + citation list + source breakdown.
+ */
+export function buildCitedContext(results) {
+    if (results.length === 0) {
+        return { assembledText: "", citations: [], sourceBreakdown: {} };
+    }
+    const citations = mapCitations(results);
+    const sourceBreakdown = {};
+    const textParts = [];
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        textParts.push(`[${i + 1}] ${r.content}`);
+        sourceBreakdown[r.sourceType] = (sourceBreakdown[r.sourceType] ?? 0) + 1;
+    }
+    const assembledText = textParts.join("\n\n");
+    return { assembledText, citations, sourceBreakdown };
+}
+//# sourceMappingURL=citation-mapper.js.map

package/dist/core/rag/citation-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-mapper.js","sourceRoot":"","sources":["../../../src/core/rag/citation-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAmB5C,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAuB;IAClD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5B,EAAE,EAAE,UAAU,CAAC,MAAM,CAAC;QACtB,OAAO,EAAE,CAAC,CAAC,EAAE;QACb,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,kBAAkB;YAC5C,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC;YACxC,CAAC,CAAC,CAAC,CAAC,OAAO;QACb,cAAc,EAAE,CAAC,CAAC,KAAK;QACvB,QAAQ,EAAE,CAAC,GAAG,CAAC;KAChB,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuB;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC;IACnE,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,eAAe,GAA2B,EAAE,CAAC;IAEnD,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAE1C,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,aAAa,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE7C,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;AACvD,CAAC"}

package/dist/core/rag/enrichment-pipeline.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Enrichment Pipeline — enriches text chunks with keywords, entities, and summaries
+ * before indexation into the knowledge store.
+ *
+ * Transforms raw TextChunks into EnrichedChunks with:
+ * - TF-IDF-based keyword extraction (top-N terms)
+ * - Regex-based entity detection (PascalCase, camelCase, file paths)
+ * - Auto-generated summary (first sentence or markdown heading)
+ * - Parent-child chunk linking for later chunk stitching
+ */
+import type { TextChunk } from "./chunk-text.js";
+export interface EnrichedChunk extends TextChunk {
+    /** Top-N keywords extracted via TF-IDF term frequency */
+    keywords: string[];
+    /** Detected entities: class names, function names, file paths */
+    entities: string[];
+    /** Auto-generated summary (first sentence or heading) */
+    summary: string;
+    /** Source type discriminator */
+    sourceType: string;
+    /** Reference to parent chunk index for chunk stitching */
+    parentChunkIndex?: number;
+}
+/**
+ * Extract top-N keywords from text using term frequency scoring.
+ * Uses the project tokenizer (handles PT + EN, strips stopwords).
+ */
+export declare function extractKeywords(text: string, topN?: number): string[];
+/**
+ * Extract named entities from text using regex patterns.
+ * Detects PascalCase types, camelCase functions, and file paths.
+ */
+export declare function extractEntities(text: string): string[];
+/**
+ * Generate a short summary from chunk content.
+ * Prefers markdown heading if present, otherwise first sentence.
+ */
+export declare function generateSummary(text: string): string;
+/**
+ * Enrich a single text chunk with keywords, entities, summary, and source metadata.
+ */
+export declare function enrichChunk(chunk: TextChunk, sourceType: string, parentChunkIndex?: number): EnrichedChunk;
+/**
+ * Enrich multiple chunks from the same document.
+ * Applies parent-child linking for multi-chunk documents.
+ */
+export declare function enrichChunks(chunks: TextChunk[], sourceType: string): EnrichedChunk[];
+//# sourceMappingURL=enrichment-pipeline.d.ts.map

package/dist/core/rag/enrichment-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment-pipeline.d.ts","sourceRoot":"","sources":["../../../src/core/rag/enrichment-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,yDAAyD;IACzD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAsB,GAAG,MAAM,EAAE,CAepF;AAcD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA0BpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,gBAAgB,CAAC,EAAE,MAAM,GACxB,aAAa,CAoBf;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EAAE,EACnB,UAAU,EAAE,MAAM,GACjB,aAAa,EAAE,CASjB"}

package/dist/core/rag/enrichment-pipeline.js

@@ -0,0 +1,127 @@
+/**
+ * Enrichment Pipeline — enriches text chunks with keywords, entities, and summaries
+ * before indexation into the knowledge store.
+ *
+ * Transforms raw TextChunks into EnrichedChunks with:
+ * - TF-IDF-based keyword extraction (top-N terms)
+ * - Regex-based entity detection (PascalCase, camelCase, file paths)
+ * - Auto-generated summary (first sentence or markdown heading)
+ * - Parent-child chunk linking for later chunk stitching
+ */
+import { tokenize } from "../search/tokenizer.js";
+import { logger } from "../utils/logger.js";
+const MAX_SUMMARY_LENGTH = 200;
+const DEFAULT_TOP_N = 5;
+/**
+ * Extract top-N keywords from text using term frequency scoring.
+ * Uses the project tokenizer (handles PT + EN, strips stopwords).
+ */
+export function extractKeywords(text, topN = DEFAULT_TOP_N) {
+    const tokens = tokenize(text);
+    if (tokens.length === 0)
+        return [];
+    // Count term frequencies
+    const freq = new Map();
+    for (const token of tokens) {
+        freq.set(token, (freq.get(token) ?? 0) + 1);
+    }
+    // Sort by frequency descending, then alphabetically for stability
+    const sorted = Array.from(freq.entries())
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    return sorted.slice(0, topN).map(([term]) => term);
+}
+// ── Entity detection patterns ──────────────────────────────
+/** PascalCase: at least two words joined (e.g., GraphNode, SqliteStore) */
+// eslint-disable-next-line security/detect-unsafe-regex -- bounded pattern, safe for short identifiers
+const PASCAL_CASE_RE = /\b([A-Z][a-z]+(?:[A-Z][a-z0-9]*)+)\b/g;
+/** camelCase: starts lowercase, has at least one uppercase (e.g., findNextTask) */
+const CAMEL_CASE_RE = /\b([a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*)\b/g;
+/** File paths: src/... or similar path patterns ending in common extensions */
+const FILE_PATH_RE = /\b((?:src|lib|dist|test|tests)\/[\w\-./]+\.(?:ts|js|tsx|jsx|json|md|sql))\b/g;
+/**
+ * Extract named entities from text using regex patterns.
+ * Detects PascalCase types, camelCase functions, and file paths.
+ */
+export function extractEntities(text) {
+    const entities = new Set();
+    let match;
+    // PascalCase (reset lastIndex before each scan)
+    PASCAL_CASE_RE.lastIndex = 0;
+    while ((match = PASCAL_CASE_RE.exec(text)) !== null) {
+        entities.add(match[1]);
+    }
+    // camelCase
+    CAMEL_CASE_RE.lastIndex = 0;
+    while ((match = CAMEL_CASE_RE.exec(text)) !== null) {
+        entities.add(match[1]);
+    }
+    // File paths
+    FILE_PATH_RE.lastIndex = 0;
+    while ((match = FILE_PATH_RE.exec(text)) !== null) {
+        entities.add(match[1]);
+    }
+    return Array.from(entities);
+}
+/**
+ * Generate a short summary from chunk content.
+ * Prefers markdown heading if present, otherwise first sentence.
+ */
+export function generateSummary(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return "";
+    // Check for markdown heading
+    const headingMatch = trimmed.match(/^#{1,6}\s+(.+)/m);
+    if (headingMatch) {
+        const heading = headingMatch[1].trim();
+        return heading.length > MAX_SUMMARY_LENGTH
+            ? heading.slice(0, MAX_SUMMARY_LENGTH)
+            : heading;
+    }
+    // First sentence (ends with . ! or ?)
+    const sentenceMatch = trimmed.match(/^[^.!?]+[.!?]/);
+    if (sentenceMatch) {
+        const sentence = sentenceMatch[0].trim();
+        return sentence.length > MAX_SUMMARY_LENGTH
+            ? sentence.slice(0, MAX_SUMMARY_LENGTH)
+            : sentence;
+    }
+    // Fallback: truncate to MAX_SUMMARY_LENGTH
+    return trimmed.length > MAX_SUMMARY_LENGTH
+        ? trimmed.slice(0, MAX_SUMMARY_LENGTH)
+        : trimmed;
+}
+/**
+ * Enrich a single text chunk with keywords, entities, summary, and source metadata.
+ */
+export function enrichChunk(chunk, sourceType, parentChunkIndex) {
+    const keywords = extractKeywords(chunk.content);
+    const entities = extractEntities(chunk.content);
+    const summary = generateSummary(chunk.content);
+    logger.debug("Chunk enriched", {
+        index: chunk.index,
+        sourceType,
+        keywordCount: keywords.length,
+        entityCount: entities.length,
+    });
+    return {
+        ...chunk,
+        keywords,
+        entities,
+        summary,
+        sourceType,
+        parentChunkIndex,
+    };
+}
+/**
+ * Enrich multiple chunks from the same document.
+ * Applies parent-child linking for multi-chunk documents.
+ */
+export function enrichChunks(chunks, sourceType) {
+    if (chunks.length <= 1) {
+        return chunks.map((c) => enrichChunk(c, sourceType));
+    }
+    // For multi-chunk documents, first chunk (index 0) is the "parent" reference
+    return chunks.map((c, i) => enrichChunk(c, sourceType, i === 0 ? undefined : 0));
+}
+//# sourceMappingURL=enrichment-pipeline.js.map

package/dist/core/rag/enrichment-pipeline.js.map

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

package/dist/core/rag/post-retrieval.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Post-Retrieval Pipeline — processes search results after initial retrieval.
+ *
+ * Pipeline stages:
+ * 1. Deduplication — remove results with identical content
+ * 2. Reranking — boost results with higher query keyword overlap
+ * 3. Chunk stitching — merge adjacent chunks from the same source
+ * 4. Limit — enforce maxResults
+ */
+import type { RankedResult } from "./multi-strategy-retrieval.js";
+export interface PostRetrievalOptions {
+    query: string;
+    results: RankedResult[];
+    maxResults: number;
+    chunkMeta?: Map<string, number>;
+}
+export interface PostRetrievalResult {
+    results: RankedResult[];
+    deduplicated: number;
+    stitchedChunks: number;
+}
+/**
+ * Remove results with identical content, keeping the highest-scored one.
+ */
+export declare function deduplicateResults(results: RankedResult[]): RankedResult[];
+/**
+ * Rerank results by keyword overlap with the query.
+ * Combines original score with keyword overlap boost.
+ */
+export declare function rerankByKeywordOverlap(results: RankedResult[], query: string): RankedResult[];
+/**
+ * Merge adjacent chunks from the same source document.
+ * Chunks are considered adjacent if their chunk indices differ by 1.
+ */
+export declare function stitchAdjacentChunks(results: RankedResult[], chunkMeta: Map<string, number>): RankedResult[];
+/**
+ * Full post-retrieval pipeline.
+ */
+export declare function postRetrievalPipeline(options: PostRetrievalOptions): PostRetrievalResult;
+//# sourceMappingURL=post-retrieval.d.ts.map

package/dist/core/rag/post-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-retrieval.d.ts","sourceRoot":"","sources":["../../../src/core/rag/post-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAY1E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,EAAE,MAAM,GACZ,YAAY,EAAE,CAchB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,YAAY,EAAE,EACvB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,YAAY,EAAE,CAmDhB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,mBAAmB,CA2BxF"}