projscan 3.5.0 → 3.7.0

package/dist/core/collisionDetector.js

@@ -0,0 +1,222 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { scanRepository } from './repositoryScanner.js';
+import { buildCodeGraph, importersOf } from './codeGraph.js';
+import { computeImpact } from './impact.js';
+import { getChangedFiles } from '../utils/changedFiles.js';
+const execFileAsync = promisify(execFile);
+/** Parse `git worktree list --porcelain` into structured refs. Local-first. */
+export async function listWorktrees(rootPath) {
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: rootPath,
+            maxBuffer: 8 * 1024 * 1024,
+        }));
+    }
+    catch {
+        return [];
+    }
+    const refs = [];
+    let current = null;
+    const flush = () => {
+        if (current)
+            refs.push(current);
+        current = null;
+    };
+    for (const line of stdout.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            flush();
+            current = { path: line.slice('worktree '.length).trim(), branch: null, head: null };
+        }
+        else if (current && line.startsWith('HEAD ')) {
+            current.head = line.slice('HEAD '.length).trim();
+        }
+        else if (current && line.startsWith('branch ')) {
+            current.branch = line.slice('branch '.length).trim().replace(/^refs\/heads\//, '');
+        }
+        else if (current && line.trim() === 'detached') {
+            current.branch = null;
+        }
+        else if (line.trim() === '') {
+            flush();
+        }
+    }
+    flush();
+    return refs;
+}
+/**
+ * Detect collisions across the repo's in-flight worktrees. Needs at least two
+ * worktrees (otherwise there's nothing to coordinate). The dependency edges
+ * come from the current repo's import graph (HEAD); a file added only inside a
+ * worktree simply has no edges yet and is still caught by same-file overlap.
+ */
+export async function detectCollisions(rootPath, options = {}) {
+    const worktrees = await listWorktrees(rootPath);
+    if (worktrees.length < 2) {
+        return {
+            schemaVersion: 1,
+            available: false,
+            reason: worktrees.length === 0
+                ? 'not a git repository, or git worktrees are unavailable'
+                : 'only one worktree — collision detection needs at least two in-flight worktrees',
+            worktrees: worktrees.map((w) => ({ path: w.path, branch: w.branch, changedFileCount: 0, baseRef: null })),
+            collisions: [],
+        };
+    }
+    // Changed files per worktree (repo-relative, POSIX).
+    const changes = await Promise.all(worktrees.map(async (w) => {
+        const result = await getChangedFiles(w.path, options.baseRef);
+        return {
+            ref: w,
+            files: result.available ? result.files : [],
+            baseRef: result.baseRef,
+        };
+    }));
+    // Import graph of the current repo for dependency (blast-radius) edges.
+    const scan = await scanRepository(rootPath);
+    const graph = await buildCodeGraph(rootPath, scan.files);
+    const collisions = [];
+    for (let i = 0; i < changes.length; i++) {
+        for (let j = i + 1; j < changes.length; j++) {
+            const a = changes[i];
+            const b = changes[j];
+            const aFiles = a.files;
+            const bSet = new Set(b.files);
+            const aSet = new Set(a.files);
+            // Same-file overlap — both worktrees changed the same file.
+            for (const file of aFiles) {
+                if (bSet.has(file)) {
+                    collisions.push({
+                        kind: 'same-file',
+                        severity: 'high',
+                        worktreeA: a.ref.path,
+                        fileA: file,
+                        worktreeB: b.ref.path,
+                        fileB: file,
+                        reason: `Both worktrees changed ${file}.`,
+                    });
+                }
+            }
+            // Dependency overlap — one worktree changed a file the other's change
+            // imports (1-hop import edge). Skip files already flagged same-file.
+            for (const file of aFiles) {
+                if (bSet.has(file))
+                    continue;
+                const importers = new Set(importersOf(graph, file));
+                for (const other of b.files) {
+                    if (other === file || aSet.has(other))
+                        continue;
+                    if (importers.has(other)) {
+                        collisions.push({
+                            kind: 'dependency',
+                            severity: 'medium',
+                            worktreeA: a.ref.path,
+                            fileA: file,
+                            worktreeB: b.ref.path,
+                            fileB: other,
+                            distance: 1,
+                            reason: `${other} (changed in the other worktree) imports ${file} (changed here).`,
+                        });
+                    }
+                }
+            }
+            for (const file of b.files) {
+                if (aSet.has(file))
+                    continue;
+                const importers = new Set(importersOf(graph, file));
+                for (const other of aFiles) {
+                    if (other === file || bSet.has(other))
+                        continue;
+                    if (importers.has(other)) {
+                        collisions.push({
+                            kind: 'dependency',
+                            severity: 'medium',
+                            worktreeA: a.ref.path,
+                            fileA: other,
+                            worktreeB: b.ref.path,
+                            fileB: file,
+                            distance: 1,
+                            reason: `${other} (changed here) imports ${file} (changed in the other worktree).`,
+                        });
+                    }
+                }
+            }
+            // Transitive overlap (opt-in) — multi-hop dependency edges via the impact
+            // graph. Only distance >= 2 here; distance 1 is the precise pass above.
+            if (options.transitive) {
+                const maxDistance = options.maxDistance ?? 5;
+                for (const file of aFiles) {
+                    if (bSet.has(file))
+                        continue;
+                    for (const node of computeImpact(graph, { kind: 'file', value: file }, { maxDistance }).reachable) {
+                        if (node.distance >= 2 && bSet.has(node.file) && !aSet.has(node.file)) {
+                            collisions.push({
+                                kind: 'dependency',
+                                severity: 'medium',
+                                worktreeA: a.ref.path,
+                                fileA: file,
+                                worktreeB: b.ref.path,
+                                fileB: node.file,
+                                distance: node.distance,
+                                reason: `${node.file} (changed in the other worktree) transitively imports ${file} (changed here), ${node.distance} hops away.`,
+                            });
+                        }
+                    }
+                }
+                for (const file of b.files) {
+                    if (aSet.has(file))
+                        continue;
+                    for (const node of computeImpact(graph, { kind: 'file', value: file }, { maxDistance }).reachable) {
+                        if (node.distance >= 2 && aSet.has(node.file) && !bSet.has(node.file)) {
+                            collisions.push({
+                                kind: 'dependency',
+                                severity: 'medium',
+                                worktreeA: a.ref.path,
+                                fileA: node.file,
+                                worktreeB: b.ref.path,
+                                fileB: file,
+                                distance: node.distance,
+                                reason: `${node.file} (changed here) transitively imports ${file} (changed in the other worktree), ${node.distance} hops away.`,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return {
+        schemaVersion: 1,
+        available: true,
+        worktrees: changes.map((c) => ({
+            path: c.ref.path,
+            branch: c.ref.branch,
+            changedFileCount: c.files.length,
+            baseRef: c.baseRef,
+        })),
+        collisions: dedupeCollisions(collisions),
+    };
+}
+/**
+ * Same-file collisions pass through; dependency collisions are deduped per
+ * oriented (worktreeA, fileA, worktreeB, fileB) pair, keeping the shortest
+ * distance — so a transitive path can't re-report a pair the direct (distance
+ * 1) pass already found.
+ */
+function dedupeCollisions(list) {
+    const sameFile = [];
+    const bestDependency = new Map();
+    for (const c of list) {
+        if (c.kind === 'same-file') {
+            sameFile.push(c);
+            continue;
+        }
+        const key = `${c.worktreeA}|${c.fileA}|${c.worktreeB}|${c.fileB}`;
+        const existing = bestDependency.get(key);
+        if (!existing || (c.distance ?? Infinity) < (existing.distance ?? Infinity)) {
+            bestDependency.set(key, c);
+        }
+    }
+    return [...sameFile, ...bestDependency.values()];
+}
+//# sourceMappingURL=collisionDetector.js.map

package/dist/core/collisionDetector.js.map

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

package/dist/core/coordination.d.ts

@@ -0,0 +1,62 @@
+import { type CollisionReport } from './collisionDetector.js';
+import { type Claim } from './claims.js';
+import { type MergeRiskReport } from './mergeRisk.js';
+/**
+ * Coordination summary (4.x arc, epic 5 — the capstone).
+ *
+ * Composes the three swarm primitives — collisions, claims, and merge-risk —
+ * into one budget-shaped read with a `readiness` verdict, so an agent gets a
+ * single coordination signal instead of three calls. It is also the arc's
+ * measurable outcome surface: the counts (collisions caught, contended claims,
+ * merge hotspots) quantify what the coordination layer surfaced. Local-first.
+ */
+export type CoordinationReadiness = 'clear' | 'caution' | 'conflicted';
+export interface CoordinationSummary {
+    schemaVersion: 1;
+    available: boolean;
+    reason?: string;
+    worktreeCount: number;
+    collisions: {
+        total: number;
+        high: number;
+        medium: number;
+    };
+    claims: {
+        total: number;
+        contendedTargets: number;
+    };
+    mergeRisk: {
+        hotspotCount: number;
+        integrationOrder: Array<{
+            worktree: string;
+            branch: string | null;
+            riskScore: number;
+        }>;
+    };
+    readiness: CoordinationReadiness;
+    summary: string[];
+}
+export interface CoordinationInputs {
+    collisionReport: CollisionReport;
+    claims: Claim[];
+    mergeRisk: MergeRiskReport;
+}
+/** Pure: fold the three swarm signals into a summary + readiness verdict. */
+export declare function summarizeCoordination(inputs: CoordinationInputs): CoordinationSummary;
+/**
+ * Compact, agent-facing hints derived from a coordination summary — for
+ * surfacing inside other reports (e.g. agent briefs). Empty when coordination
+ * is unavailable or the swarm is clear, so it adds nothing in the common
+ * single-worktree case.
+ */
+export declare function coordinationHints(summary: CoordinationSummary): string[];
+/**
+ * A stable fingerprint of the coordination state — readiness, worktree count,
+ * collision counts, and contention. `--watch` mode re-emits only when this
+ * changes between ticks, so stable state stays quiet.
+ */
+export declare function coordinationSignature(summary: CoordinationSummary): string;
+/** Run the full coordination read for the repo's in-flight worktrees. */
+export declare function computeCoordination(rootPath: string, options?: {
+    baseRef?: string;
+}): Promise<CoordinationSummary>;

package/dist/core/coordination.js

@@ -0,0 +1,121 @@
+import { detectCollisions } from './collisionDetector.js';
+import { listClaims, findContendedClaims } from './claims.js';
+import { deriveMergeRisk } from './mergeRisk.js';
+/** Pure: fold the three swarm signals into a summary + readiness verdict. */
+export function summarizeCoordination(inputs) {
+    const { collisionReport, claims, mergeRisk } = inputs;
+    if (!collisionReport.available) {
+        return {
+            schemaVersion: 1,
+            available: false,
+            ...(collisionReport.reason ? { reason: collisionReport.reason } : {}),
+            worktreeCount: collisionReport.worktrees.length,
+            collisions: { total: 0, high: 0, medium: 0 },
+            claims: { total: claims.length, contendedTargets: 0 },
+            mergeRisk: { hotspotCount: 0, integrationOrder: [] },
+            readiness: 'clear',
+            summary: [collisionReport.reason ?? 'Coordination unavailable.'],
+        };
+    }
+    const high = collisionReport.collisions.filter((c) => c.severity === 'high').length;
+    const medium = collisionReport.collisions.filter((c) => c.severity === 'medium').length;
+    const contendedTargets = new Set(findContendedClaims(claims).map((c) => c.target)).size;
+    const readiness = high > 0 || contendedTargets > 0
+        ? 'conflicted'
+        : medium > 0
+            ? 'caution'
+            : 'clear';
+    const summary = [];
+    summary.push(`${collisionReport.worktrees.length} in-flight worktree(s).`);
+    if (high + medium > 0) {
+        summary.push(`${high + medium} collision(s): ${high} high, ${medium} medium.`);
+    }
+    else {
+        summary.push('No collisions across worktrees.');
+    }
+    if (contendedTargets > 0)
+        summary.push(`${contendedTargets} claim target(s) contended by multiple agents.`);
+    if (mergeRisk.hotFiles.length > 0)
+        summary.push(`${mergeRisk.hotFiles.length} merge hotspot file(s).`);
+    if (mergeRisk.integrationOrder.length > 0) {
+        const first = mergeRisk.integrationOrder[0];
+        summary.push(`Merge ${first.branch ?? first.worktree} first (lowest risk).`);
+    }
+    return {
+        schemaVersion: 1,
+        available: true,
+        worktreeCount: collisionReport.worktrees.length,
+        collisions: { total: collisionReport.collisions.length, high, medium },
+        claims: { total: claims.length, contendedTargets },
+        mergeRisk: {
+            hotspotCount: mergeRisk.hotFiles.length,
+            integrationOrder: mergeRisk.integrationOrder.map((o) => ({
+                worktree: o.worktree,
+                branch: o.branch,
+                riskScore: o.riskScore,
+            })),
+        },
+        readiness,
+        summary,
+    };
+}
+/**
+ * Compact, agent-facing hints derived from a coordination summary — for
+ * surfacing inside other reports (e.g. agent briefs). Empty when coordination
+ * is unavailable or the swarm is clear, so it adds nothing in the common
+ * single-worktree case.
+ */
+export function coordinationHints(summary) {
+    if (!summary.available || summary.readiness === 'clear')
+        return [];
+    const hints = [`Swarm readiness: ${summary.readiness} — run \`projscan coordinate\` for details.`];
+    if (summary.collisions.high > 0) {
+        hints.push(`${summary.collisions.high} high-severity collision(s) (same file edited by two worktrees).`);
+    }
+    if (summary.collisions.medium > 0) {
+        hints.push(`${summary.collisions.medium} dependency collision(s) across worktrees.`);
+    }
+    if (summary.claims.contendedTargets > 0) {
+        hints.push(`${summary.claims.contendedTargets} claim target(s) contended by multiple agents.`);
+    }
+    const first = summary.mergeRisk.integrationOrder[0];
+    if (first)
+        hints.push(`Merge ${first.branch ?? first.worktree} first (lowest risk).`);
+    return hints;
+}
+/**
+ * A stable fingerprint of the coordination state — readiness, worktree count,
+ * collision counts, and contention. `--watch` mode re-emits only when this
+ * changes between ticks, so stable state stays quiet.
+ */
+export function coordinationSignature(summary) {
+    return [
+        summary.available ? 'a' : 'u',
+        summary.readiness,
+        summary.worktreeCount,
+        summary.collisions.high,
+        summary.collisions.medium,
+        summary.claims.contendedTargets,
+        summary.mergeRisk.hotspotCount,
+    ].join(':');
+}
+/** Run the full coordination read for the repo's in-flight worktrees. */
+export async function computeCoordination(rootPath, options = {}) {
+    // One collision pass feeds both the summary and the merge-risk derivation —
+    // detectCollisions builds the code graph, so we must not run it twice.
+    const [collisionReport, claims] = await Promise.all([
+        detectCollisions(rootPath, options),
+        listClaims(rootPath),
+    ]);
+    const { integrationOrder, hotFiles } = deriveMergeRisk(collisionReport);
+    const mergeRisk = {
+        schemaVersion: 1,
+        available: collisionReport.available,
+        ...(collisionReport.reason ? { reason: collisionReport.reason } : {}),
+        integrationOrder,
+        hotFiles,
+        collisions: collisionReport.collisions,
+    };
+    return summarizeCoordination({ collisionReport, claims, mergeRisk });
+}
+//# sourceMappingURL=coordination.js.map

package/dist/core/coordination.js.map

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

package/dist/core/embeddings.js

@@ -67,28 +67,41 @@ async function getPipeline(model, onFirstLoad) {
     const mod = await tryLoadTransformers();
     if (!mod)
         return null;
-    let existing = pipelines.get(model);
-    if (existing) {
+    let loading = pipelines.get(model);
+    if (loading) {
         // Bump on access so the LRU cache treats the recently-used model as
         // hot. Map insertion order = recency.
         pipelines.delete(model);
-        pipelines.set(model, existing);
-        return existing;
+        pipelines.set(model, loading);
     }
-    onFirstLoad?.(`Loading embedding model ${model} (first run downloads ~25MB)...`);
-    existing = mod.pipeline('feature-extraction', model, {
-        quantized: true,
-    });
-    pipelines.set(model, existing);
-    // Evict the least-recently-used pipeline when over the bound. Map
-    // iteration is in insertion order, so the first key is the oldest.
-    while (pipelines.size > MAX_CACHED_PIPELINES) {
-        const oldest = pipelines.keys().next().value;
-        if (oldest === undefined)
-            break;
-        pipelines.delete(oldest);
+    else {
+        onFirstLoad?.(`Loading embedding model ${model} (first run downloads ~25MB)...`);
+        loading = mod.pipeline('feature-extraction', model, {
+            quantized: true,
+        });
+        pipelines.set(model, loading);
+        // Evict the least-recently-used pipeline when over the bound. Map
+        // iteration is in insertion order, so the first key is the oldest.
+        while (pipelines.size > MAX_CACHED_PIPELINES) {
+            const oldest = pipelines.keys().next().value;
+            if (oldest === undefined)
+                break;
+            pipelines.delete(oldest);
+        }
+    }
+    try {
+        return await loading;
+    }
+    catch (err) {
+        // Model download / instantiation failed — offline, an HTTP 429 from the
+        // model host (huggingface.co rate-limits unauthenticated CI traffic), or a
+        // corrupt local cache. Drop the rejected promise so it can't poison the
+        // cache for the rest of the process, and degrade gracefully to null so
+        // callers fall back to BM25 instead of throwing.
+        pipelines.delete(model);
+        process.stderr.write(`[projscan] embedding model "${model}" failed to load: ${err instanceof Error ? err.message : String(err)}. Semantic features disabled for this run.\n`);
+        return null;
     }
-    return existing;
 }
 /**
  * Test-only: drop all cached pipelines. Lets unit tests verify LRU

package/dist/core/embeddings.js.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/core/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,CAAC,MAAM,aAAa,GAAG,yBAAyB,CAAC;AACvD,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAuBjC,IAAI,YAAmD,CAAC;AAExD,kEAAkE;AAClE,qEAAqE;AACrE,sEAAsE;AACtE,gEAAgE;AAChE,uEAAuE;AACvE,mEAAmE;AACnE,6CAA6C;AAC7C,EAAE;AACF,qEAAqE;AACrE,wEAAwE;AACxE,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAC/B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAqC,CAAC;AAE/D,KAAK,UAAU,mBAAmB;IAChC,IAAI,aAAa,EAAE;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAuB,CAAC;QACzE,YAAY,GAAG,GAAG,CAAC;QACnB,yEAAyE;QACzE,mDAAmD;QACnD,IAAI,GAAG,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC1C,GAAG,CAAC,GAA+B,CAAC,gBAAgB,GAAG,KAAK,CAAC;QAChE,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAAwB,CAAC;QACnC,IAAI,CAAC,CAAC,IAAI,KAAK,sBAAsB,IAAI,CAAC,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YACvE,YAAY,GAAG,IAAI,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,6EAA6E;QAC7E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sCAAsC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjH,YAAY,GAAG,IAAI,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,GAAG,GAAG,MAAM,mBAAmB,EAAE,CAAC;IACxC,OAAO,GAAG,KAAK,IAAI,CAAC;AACtB,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,KAAa,EAAE,WAAiC;IACzE,MAAM,GAAG,GAAG,MAAM,mBAAmB,EAAE,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,IAAI,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,QAAQ,EAAE,CAAC;QACb,oEAAoE;QACpE,sCAAsC;QACtC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,WAAW,EAAE,CAAC,2BAA2B,KAAK,iCAAiC,CAAC,CAAC;IACjF,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,oBAAoB,EAAE,KAAK,EAAE;QACnD,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;IACH,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC/B,kEAAkE;IAClE,mEAAmE;IACnE,OAAO,SAAS,CAAC,IAAI,GAAG,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC7C,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM;QAChC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B;IAC5C,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iCAAiC;IAC/C,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAY,EACZ,UAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtE,OAAO,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAe,EACf,UAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,kEAAkE;IAClE,2DAA2D;IAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IACxG,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAAC,CAAe,EAAE,CAAe;IAC/D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,cAAc,CAAC,IAA6B;IACnD,OAAO,IAAI,YAAY,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,YAAY,GAAG,SAAS,CAAC;IACzB,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../src/core/embeddings.ts"],"names":[],"mappings":"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"}

package/dist/core/intentRouter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Intent router (4.x agent-ergonomics, epic 4).
+ *
+ * projscan exposes 40+ MCP tools. An agent shouldn't have to reason over all of
+ * them every turn — it should be able to state a goal and get pointed at the one
+ * right tool. `routeIntent` does exactly that: a deterministic, curated map from
+ * common agent intents to the tool + exact call. No LLM (projscan never embeds
+ * inference); ranking is keyword overlap against a hand-curated catalog.
+ *
+ * This is the additive, non-breaking half of the epic — a discovery entry point.
+ * Actually shrinking the advertised tool surface (hiding the long tail behind
+ * this router) is a breaking change reserved for 4.0.
+ */
+export interface RouteEntry {
+    /** Short intent label. */
+    intent: string;
+    category: string;
+    tool: string;
+    cli: string;
+    /** What the tool does, one line. */
+    what: string;
+    /** When to reach for it. */
+    why: string;
+    /** A runnable example. */
+    example: string;
+    /** Terms that signal this intent. */
+    keywords: string[];
+}
+export interface RouteResult {
+    intent: string | null;
+    matched: boolean;
+    matches: RouteEntry[];
+}
+export declare const ROUTE_CATALOG: RouteEntry[];
+/**
+ * Map a stated intent to the best-matching projscan tool(s). With no intent,
+ * returns the full catalog grouped by category. Ranking is keyword overlap;
+ * ties keep catalog order (deterministic).
+ */
+export declare function routeIntent(intent: string | undefined): RouteResult;