projscan 3.5.0 → 3.6.0

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":"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"}
+{"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;

package/dist/core/intentRouter.js

@@ -0,0 +1,213 @@
+/**
+ * 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 const ROUTE_CATALOG = [
+    {
+        intent: 'Understand a repo before editing',
+        category: 'Understand',
+        tool: 'projscan_understand',
+        cli: 'projscan understand',
+        what: 'Cited repo/flow/contract/change/verify maps.',
+        why: 'Orient in an unfamiliar codebase before making a change.',
+        example: 'projscan understand --view map --format json',
+        keywords: ['understand', 'orient', 'overview', 'map', 'comprehend', 'unfamiliar', 'learn', 'explore', 'architecture'],
+    },
+    {
+        intent: 'Review a PR or a set of changes',
+        category: 'Review',
+        tool: 'projscan_review',
+        cli: 'projscan review',
+        what: 'One-call structural PR review with a verdict.',
+        why: 'Assess risk of a diff: cycles, taint, dataflow, contracts.',
+        example: 'projscan review --format json',
+        keywords: ['review', 'pr', 'pull', 'request', 'diff', 'changes', 'verdict', 'assess'],
+    },
+    {
+        intent: 'See what breaks if I change something',
+        category: 'Impact',
+        tool: 'projscan_impact',
+        cli: 'projscan impact',
+        what: 'Transitive blast radius for a file or symbol.',
+        why: 'Before renaming or deleting, see every caller that breaks.',
+        example: 'projscan impact --symbol buildCodeGraph --format json',
+        keywords: ['impact', 'breaks', 'break', 'blast', 'radius', 'rename', 'delete', 'depends', 'affect', 'callers', 'breaking'],
+    },
+    {
+        intent: 'Check if it is safe to edit / commit / merge',
+        category: 'Safety gate',
+        tool: 'projscan_preflight',
+        cli: 'projscan preflight',
+        what: 'proceed / caution / block verdict with evidence.',
+        why: 'A safety gate before an edit, commit, or merge.',
+        example: 'projscan preflight --mode before_commit --format json',
+        keywords: ['safe', 'safety', 'gate', 'commit', 'merge', 'edit', 'proceed', 'block', 'preflight', 'allowed', 'risky'],
+    },
+    {
+        intent: 'Find the riskiest files / where to start',
+        category: 'Hotspots',
+        tool: 'projscan_hotspots',
+        cli: 'projscan hotspots',
+        what: 'Files ranked by churn × complexity × issues.',
+        why: 'Decide where to focus review or refactoring.',
+        example: 'projscan hotspots --format json',
+        keywords: ['hotspot', 'risky', 'riskiest', 'where', 'start', 'focus', 'churn', 'complexity', 'dangerous'],
+    },
+    {
+        intent: 'Detect conflicts between parallel agents',
+        category: 'Swarm coordination',
+        tool: 'projscan_collision',
+        cli: 'projscan collisions',
+        what: 'Same-file + dependency overlaps across worktrees.',
+        why: 'Two agents editing one repo: surface collisions pre-merge.',
+        example: 'projscan collisions --format json',
+        keywords: ['coordinate', 'coordination', 'parallel', 'agents', 'swarm', 'conflict', 'conflicts', 'collision', 'worktree', 'worktrees', 'overlap', 'simultaneous'],
+    },
+    {
+        intent: 'Claim a file so other agents know who owns it',
+        category: 'Swarm coordination',
+        tool: 'projscan_claim',
+        cli: 'projscan claim',
+        what: 'Advisory claims/leases over files, dirs, symbols.',
+        why: 'Tell the swarm who is working where; warn on contention.',
+        example: 'projscan claim add src/auth.ts --agent me',
+        keywords: ['claim', 'lease', 'owns', 'ownership', 'who', 'reserve', 'lock', 'coordinate', 'parallel', 'agents', 'swarm'],
+    },
+    {
+        intent: 'Decide the order to merge in-flight branches',
+        category: 'Swarm coordination',
+        tool: 'projscan_merge_risk',
+        cli: 'projscan merge-risk',
+        what: 'Safe integration order + conflict hotspots.',
+        why: 'Multiple in-flight worktrees: which to merge first.',
+        example: 'projscan merge-risk --format json',
+        keywords: ['merge', 'integrate', 'integration', 'order', 'sequence', 'first', 'conflict', 'hotspot', 'coordinate', 'parallel', 'swarm'],
+    },
+    {
+        intent: 'Run a project health check',
+        category: 'Health',
+        tool: 'projscan_doctor',
+        cli: 'projscan doctor',
+        what: 'Health score + detected issues.',
+        why: 'A quick overall health read on a repo.',
+        example: 'projscan doctor --format json',
+        keywords: ['health', 'doctor', 'score', 'issues', 'check', 'quality', 'lint'],
+    },
+    {
+        intent: 'Search the codebase',
+        category: 'Search',
+        tool: 'projscan_search',
+        cli: 'projscan search',
+        what: 'Symbol / file / content search (BM25 + optional semantic).',
+        why: 'Find where something is defined or used.',
+        example: 'projscan search "auth token" --format json',
+        keywords: ['search', 'find', 'locate', 'where', 'grep', 'lookup', 'symbol'],
+    },
+    {
+        intent: 'Trace dataflow / find injection risk',
+        category: 'Security',
+        tool: 'projscan_dataflow',
+        cli: 'projscan dataflow',
+        what: 'Source-to-sink dataflow risks.',
+        why: 'Spot request-data reaching dangerous sinks.',
+        example: 'projscan dataflow --format json',
+        keywords: ['dataflow', 'taint', 'security', 'injection', 'source', 'sink', 'vulnerability', 'sql', 'xss'],
+    },
+    {
+        intent: 'Get a fix for an issue',
+        category: 'Fix',
+        tool: 'projscan_fix_suggest',
+        cli: 'projscan fix-suggest',
+        what: 'Structured action prompt for an open issue.',
+        why: 'Turn a detected issue into a concrete fix plan.',
+        example: 'projscan fix-suggest <issue-id> --format json',
+        keywords: ['fix', 'suggest', 'resolve', 'repair', 'remediate', 'how', 'issue'],
+    },
+    {
+        intent: 'Orient on first use / set up projscan',
+        category: 'Onboarding',
+        tool: 'projscan_start',
+        cli: 'projscan start',
+        what: 'First-60-seconds orientation + next commands.',
+        why: 'New to this repo or to projscan.',
+        example: 'projscan start --format json',
+        keywords: ['start', 'begin', 'setup', 'onboard', 'first', 'getting', 'started', 'new'],
+    },
+    {
+        intent: 'Plan the next agent work',
+        category: 'Agent planning',
+        tool: 'projscan_workplan',
+        cli: 'projscan workplan',
+        what: 'Ordered agent execution plan with verification.',
+        why: 'Turn evidence into prioritized, verifiable tasks.',
+        example: 'projscan workplan --mode bug_hunt --format json',
+        keywords: ['plan', 'workplan', 'tasks', 'next', 'todo', 'prioritize', 'roadmap'],
+    },
+    {
+        intent: 'Find bugs to fix',
+        category: 'Agent planning',
+        tool: 'projscan_bug_hunt',
+        cli: 'projscan bug-hunt',
+        what: 'Ranked fix queue from doctor/preflight/hotspots.',
+        why: 'Decide which bugs to tackle first.',
+        example: 'projscan bug-hunt --format json',
+        keywords: ['bug', 'bugs', 'hunt', 'queue', 'defect', 'broken'],
+    },
+    {
+        intent: 'Check dependency health / outdated / audit',
+        category: 'Dependencies',
+        tool: 'projscan_outdated',
+        cli: 'projscan outdated',
+        what: 'Outdated deps, audit, and upgrade preview.',
+        why: 'Assess dependency freshness and vulnerabilities.',
+        example: 'projscan outdated --format json',
+        keywords: ['dependency', 'dependencies', 'outdated', 'audit', 'upgrade', 'vulnerable', 'package', 'npm'],
+    },
+];
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'i', 'to', 'my', 'is', 'it', 'of', 'in', 'on', 'and', 'or', 'for', 'this', 'that',
+    'do', 'how', 'what', 'me', 'we', 'with', 'can', 'should', 'if', 'be', 'am', 'are',
+]);
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+/**
+ * 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 function routeIntent(intent) {
+    if (!intent || intent.trim() === '') {
+        const grouped = [...ROUTE_CATALOG].sort((a, b) => a.category.localeCompare(b.category));
+        return { intent: null, matched: grouped.length > 0, matches: grouped };
+    }
+    const tokens = new Set(tokenize(intent));
+    const scored = ROUTE_CATALOG.map((entry, index) => {
+        let score = 0;
+        for (const kw of entry.keywords) {
+            if (tokens.has(kw))
+                score += 1;
+        }
+        return { entry, score, index };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score || a.index - b.index);
+    return {
+        intent,
+        matched: scored.length > 0,
+        matches: scored.map((s) => s.entry),
+    };
+}
+//# sourceMappingURL=intentRouter.js.map

package/dist/core/intentRouter.js.map

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

package/dist/core/mergeRisk.d.ts

@@ -0,0 +1,42 @@
+import { type CollisionReport, type Collision } from './collisionDetector.js';
+/**
+ * Merge-risk preflight (4.x coordination arc, epic 3).
+ *
+ * Builds on collision detection: given the repo's in-flight worktrees and the
+ * collisions between them, answer the two integration questions —
+ *   1. In what order is it safe to merge? (integration order)
+ *   2. Where does conflict risk concentrate? (hotspot files)
+ * Local-first; reuses `detectCollisions` (no new git/graph machinery).
+ */
+export interface IntegrationStep {
+    worktree: string;
+    branch: string | null;
+    /** Number of collisions this worktree is involved in. */
+    collisionCount: number;
+    changedFileCount: number;
+    /** Sum of collision weights (high = 2, medium = 1) — lower merges first. */
+    riskScore: number;
+}
+export interface RiskHotspot {
+    file: string;
+    /** Distinct worktrees that changed this file (>= 2 = contended). */
+    worktrees: string[];
+    severity: 'high' | 'medium';
+}
+export interface MergeRiskReport {
+    schemaVersion: 1;
+    available: boolean;
+    reason?: string;
+    integrationOrder: IntegrationStep[];
+    hotFiles: RiskHotspot[];
+    collisions: Collision[];
+}
+/** Pure derivation: turn a collision report into integration order + hotspots. */
+export declare function deriveMergeRisk(report: CollisionReport): {
+    integrationOrder: IntegrationStep[];
+    hotFiles: RiskHotspot[];
+};
+/** Compute merge-risk for the repo's in-flight worktrees. */
+export declare function computeMergeRisk(rootPath: string, options?: {
+    baseRef?: string;
+}): Promise<MergeRiskReport>;

package/dist/core/mergeRisk.js

@@ -0,0 +1,71 @@
+import { detectCollisions } from './collisionDetector.js';
+const WEIGHT = { high: 2, medium: 1 };
+/** Pure derivation: turn a collision report into integration order + hotspots. */
+export function deriveMergeRisk(report) {
+    if (!report.available)
+        return { integrationOrder: [], hotFiles: [] };
+    // Per-worktree collision involvement and risk weight.
+    const involvement = new Map();
+    const bump = (worktree, weight) => {
+        const cur = involvement.get(worktree) ?? { count: 0, risk: 0 };
+        cur.count += 1;
+        cur.risk += weight;
+        involvement.set(worktree, cur);
+    };
+    for (const c of report.collisions) {
+        bump(c.worktreeA, WEIGHT[c.severity]);
+        bump(c.worktreeB, WEIGHT[c.severity]);
+    }
+    const integrationOrder = report.worktrees
+        .map((w) => {
+        const inv = involvement.get(w.path) ?? { count: 0, risk: 0 };
+        return {
+            worktree: w.path,
+            branch: w.branch,
+            collisionCount: inv.count,
+            changedFileCount: w.changedFileCount,
+            riskScore: inv.risk,
+        };
+    })
+        // Merge the cleanest branch first: lowest risk, then fewest changed files,
+        // then path for a stable, deterministic order.
+        .sort((a, b) => a.riskScore - b.riskScore ||
+        a.changedFileCount - b.changedFileCount ||
+        a.worktree.localeCompare(b.worktree));
+    // Hotspot files: a file changed by >= 2 distinct worktrees (the highest-risk
+    // merge-conflict signal). Tracks the worst severity seen for that file.
+    const fileWorktrees = new Map();
+    const fileSeverity = new Map();
+    const record = (file, worktree, severity) => {
+        if (!fileWorktrees.has(file))
+            fileWorktrees.set(file, new Set());
+        fileWorktrees.get(file).add(worktree);
+        if (severity === 'high' || !fileSeverity.has(file))
+            fileSeverity.set(file, severity);
+    };
+    for (const c of report.collisions) {
+        record(c.fileA, c.worktreeA, c.severity);
+        record(c.fileB, c.worktreeB, c.severity);
+    }
+    const hotFiles = [...fileWorktrees.entries()]
+        .filter(([, wts]) => wts.size >= 2)
+        .map(([file, wts]) => ({ file, worktrees: [...wts], severity: fileSeverity.get(file) ?? 'medium' }))
+        .sort((a, b) => b.worktrees.length - a.worktrees.length ||
+        (a.severity === b.severity ? 0 : a.severity === 'high' ? -1 : 1) ||
+        a.file.localeCompare(b.file));
+    return { integrationOrder, hotFiles };
+}
+/** Compute merge-risk for the repo's in-flight worktrees. */
+export async function computeMergeRisk(rootPath, options = {}) {
+    const collisionReport = await detectCollisions(rootPath, options);
+    const { integrationOrder, hotFiles } = deriveMergeRisk(collisionReport);
+    return {
+        schemaVersion: 1,
+        available: collisionReport.available,
+        ...(collisionReport.reason ? { reason: collisionReport.reason } : {}),
+        integrationOrder,
+        hotFiles,
+        collisions: collisionReport.collisions,
+    };
+}
+//# sourceMappingURL=mergeRisk.js.map

package/dist/core/mergeRisk.js.map

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