projscan 3.5.0 → 3.6.0

package/dist/cli/index.js

@@ -17,6 +17,11 @@ import { registerReview } from './commands/review.js';
 import { registerFixSuggest } from './commands/fixSuggest.js';
 import { registerExplainIssue } from './commands/explainIssue.js';
 import { registerImpact } from './commands/impact.js';
+import { registerCollision } from './commands/collision.js';
+import { registerClaim } from './commands/claim.js';
+import { registerMergeRisk } from './commands/mergeRisk.js';
+import { registerRoute } from './commands/route.js';
+import { registerCoordinate } from './commands/coordinate.js';
 import { registerWatch } from './commands/watch.js';
 import { registerWorkspaces } from './commands/workspaces.js';
 import { registerOutdated } from './commands/outdated.js';
@@ -70,6 +75,11 @@ registerReview();
 registerFixSuggest();
 registerExplainIssue();
 registerImpact();
+registerCollision();
+registerClaim();
+registerMergeRisk();
+registerRoute();
+registerCoordinate();
 registerWatch();
 registerWorkspaces();
 registerOutdated();

package/dist/cli/index.js.map

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

package/dist/core/claims.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Swarm claims / leases (4.x coordination arc).
+ *
+ * An agent can claim a file, directory, or symbol so the rest of the swarm sees
+ * who is working where. Claims are advisory (not a hard lock) — claiming an
+ * already-claimed target still succeeds, but returns the contending claims so
+ * the agent can coordinate.
+ *
+ * The store is shared across all git worktrees of the repo: it lives under the
+ * **git common dir** (`git rev-parse --git-common-dir`), not the per-worktree
+ * `.projscan-cache`, because two agents coordinating are in different worktrees
+ * of the same repo. Strictly local-first — no network, no server.
+ */
+export interface Claim {
+    id: string;
+    /** Claimed target: a repo-relative file/dir path, or a symbol name. */
+    target: string;
+    /** Who holds the claim. */
+    agent: string;
+    note?: string;
+    /** ISO timestamp. */
+    claimedAt: string;
+    /** ISO expiry (lease). Absent = never expires. */
+    expiresAt?: string;
+}
+export interface AddClaimResult {
+    claim: Claim;
+    /** Existing claims by OTHER agents whose target overlaps this one. */
+    contention: Claim[];
+}
+/** Two targets overlap if equal, or one is a directory ancestor of the other. */
+export declare function claimTargetsOverlap(a: string, b: string): boolean;
+/** Claims held by more than one agent on overlapping targets (contention). */
+export declare function findContendedClaims(claims: Claim[]): Claim[];
+/** All active claims, shared across the repo's worktrees. */
+export declare function listClaims(rootPath: string): Promise<Claim[]>;
+/**
+ * Record a claim. Returns the new claim plus any contending claims (held by a
+ * different agent on an overlapping target). The claim is recorded regardless —
+ * it's advisory; contention is surfaced for the agent to act on.
+ */
+export declare function addClaim(rootPath: string, input: {
+    target: string;
+    agent: string;
+    note?: string;
+    ttlSeconds?: number;
+}, now?: () => Date): Promise<AddClaimResult>;
+/** A claim is active unless its lease (expiresAt) has passed. No expiry = active. */
+export declare function isClaimActive(claim: Claim, now?: Date): boolean;
+/** Remove expired-lease claims. Returns the claims that were pruned. */
+export declare function pruneClaims(rootPath: string, now?: Date): Promise<Claim[]>;
+/**
+ * Release claims by id, by target (optionally scoped to an agent), or all of an
+ * agent's claims. Returns the claims that were removed.
+ */
+export declare function releaseClaim(rootPath: string, selector: {
+    id?: string;
+    target?: string;
+    agent?: string;
+}): Promise<Claim[]>;

package/dist/core/claims.js

@@ -0,0 +1,139 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteFile } from '../utils/atomicWrite.js';
+const execFileAsync = promisify(execFile);
+async function claimStorePath(rootPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--git-common-dir'], { cwd: rootPath });
+        // --git-common-dir is the SAME directory for every worktree of the repo, so
+        // the claim store is shared across the swarm. It may be relative to cwd.
+        return path.join(path.resolve(rootPath, stdout.trim()), 'projscan', 'claims.json');
+    }
+    catch {
+        // Not a git repo — fall back to the local cache (single-worktree only).
+        return path.join(rootPath, '.projscan-cache', 'claims.json');
+    }
+}
+/** Normalize a target for comparison: POSIX separators, no trailing slash. */
+function normalizeTarget(target) {
+    const t = target.trim().split('\\').join('/');
+    return t.endsWith('/') && t.length > 1 ? t.slice(0, -1) : t;
+}
+/** Two targets overlap if equal, or one is a directory ancestor of the other. */
+export function claimTargetsOverlap(a, b) {
+    const na = normalizeTarget(a);
+    const nb = normalizeTarget(b);
+    if (na === nb)
+        return true;
+    return nb.startsWith(`${na}/`) || na.startsWith(`${nb}/`);
+}
+/** Claims held by more than one agent on overlapping targets (contention). */
+export function findContendedClaims(claims) {
+    const contended = new Set();
+    for (let i = 0; i < claims.length; i++) {
+        for (let j = i + 1; j < claims.length; j++) {
+            if (claims[i].agent !== claims[j].agent && claimTargetsOverlap(claims[i].target, claims[j].target)) {
+                contended.add(claims[i]);
+                contended.add(claims[j]);
+            }
+        }
+    }
+    return [...contended];
+}
+function isWellShapedClaim(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const c = value;
+    return (typeof c.id === 'string' &&
+        typeof c.target === 'string' &&
+        typeof c.agent === 'string' &&
+        typeof c.claimedAt === 'string');
+}
+async function readStore(rootPath) {
+    try {
+        const raw = await fs.readFile(await claimStorePath(rootPath), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const claims = Array.isArray(parsed.claims) ? parsed.claims.filter(isWellShapedClaim) : [];
+        return { schemaVersion: 1, claims };
+    }
+    catch {
+        return { schemaVersion: 1, claims: [] };
+    }
+}
+async function writeStore(rootPath, store) {
+    const file = await claimStorePath(rootPath);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await atomicWriteFile(file, JSON.stringify(store, null, 2) + '\n');
+}
+/** All active claims, shared across the repo's worktrees. */
+export async function listClaims(rootPath) {
+    return (await readStore(rootPath)).claims;
+}
+/**
+ * Record a claim. Returns the new claim plus any contending claims (held by a
+ * different agent on an overlapping target). The claim is recorded regardless —
+ * it's advisory; contention is surfaced for the agent to act on.
+ */
+export async function addClaim(rootPath, input, now = () => new Date()) {
+    const target = normalizeTarget(input.target);
+    const at = now();
+    const store = await readStore(rootPath);
+    // Only ACTIVE claims (not expired leases) by a different agent contend.
+    const contention = store.claims.filter((c) => c.agent !== input.agent && isClaimActive(c, at) && claimTargetsOverlap(c.target, target));
+    const claim = {
+        id: randomUUID(),
+        target,
+        agent: input.agent,
+        ...(input.note ? { note: input.note } : {}),
+        claimedAt: at.toISOString(),
+        ...(input.ttlSeconds && input.ttlSeconds > 0
+            ? { expiresAt: new Date(at.getTime() + input.ttlSeconds * 1000).toISOString() }
+            : {}),
+    };
+    store.claims.push(claim);
+    await writeStore(rootPath, store);
+    return { claim, contention };
+}
+/** A claim is active unless its lease (expiresAt) has passed. No expiry = active. */
+export function isClaimActive(claim, now = new Date()) {
+    if (!claim.expiresAt)
+        return true;
+    return new Date(claim.expiresAt).getTime() > now.getTime();
+}
+/** Remove expired-lease claims. Returns the claims that were pruned. */
+export async function pruneClaims(rootPath, now = new Date()) {
+    const store = await readStore(rootPath);
+    const pruned = store.claims.filter((c) => !isClaimActive(c, now));
+    if (pruned.length === 0)
+        return [];
+    store.claims = store.claims.filter((c) => isClaimActive(c, now));
+    await writeStore(rootPath, store);
+    return pruned;
+}
+/**
+ * Release claims by id, by target (optionally scoped to an agent), or all of an
+ * agent's claims. Returns the claims that were removed.
+ */
+export async function releaseClaim(rootPath, selector) {
+    const store = await readStore(rootPath);
+    const target = selector.target !== undefined ? normalizeTarget(selector.target) : undefined;
+    const matches = (c) => {
+        if (selector.id !== undefined)
+            return c.id === selector.id;
+        if (target !== undefined)
+            return c.target === target && (selector.agent === undefined || c.agent === selector.agent);
+        if (selector.agent !== undefined)
+            return c.agent === selector.agent;
+        return false;
+    };
+    const removed = store.claims.filter(matches);
+    if (removed.length === 0)
+        return [];
+    store.claims = store.claims.filter((c) => !matches(c));
+    await writeStore(rootPath, store);
+    return removed;
+}
+//# sourceMappingURL=claims.js.map

package/dist/core/claims.js.map

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

package/dist/core/collisionDetector.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Swarm collision detection (4.x coordination arc).
+ *
+ * When several agents edit one repo in parallel — each in its own git worktree
+ * — their changes collide if they touch the same file, or if one edits a file
+ * the other's change depends on. This surfaces those overlaps BEFORE the
+ * branches are merged, using the existing import graph for blast radius.
+ *
+ * Strictly local-first: it reads the repo's own `git worktree list` (same
+ * machine, same repo) and never reaches the network or a coordination server.
+ */
+export interface WorktreeRef {
+    /** Absolute worktree path. */
+    path: string;
+    /** Branch name (no refs/heads/ prefix), or null when detached. */
+    branch: string | null;
+    /** HEAD commit sha, or null. */
+    head: string | null;
+}
+export type CollisionKind = 'same-file' | 'dependency';
+export interface Collision {
+    kind: CollisionKind;
+    severity: 'high' | 'medium';
+    worktreeA: string;
+    fileA: string;
+    worktreeB: string;
+    fileB: string;
+    reason: string;
+}
+export interface CollisionWorktreeSummary {
+    path: string;
+    branch: string | null;
+    changedFileCount: number;
+    baseRef: string | null;
+}
+export interface CollisionReport {
+    schemaVersion: 1;
+    available: boolean;
+    reason?: string;
+    worktrees: CollisionWorktreeSummary[];
+    collisions: Collision[];
+}
+export interface DetectCollisionsOptions {
+    /** Base ref each worktree is diffed against. Defaults to the usual fallbacks. */
+    baseRef?: string;
+}
+/** Parse `git worktree list --porcelain` into structured refs. Local-first. */
+export declare function listWorktrees(rootPath: string): Promise<WorktreeRef[]>;
+/**
+ * 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 declare function detectCollisions(rootPath: string, options?: DetectCollisionsOptions): Promise<CollisionReport>;

package/dist/core/collisionDetector.js

@@ -0,0 +1,156 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { scanRepository } from './repositoryScanner.js';
+import { buildCodeGraph, importersOf } from './codeGraph.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,
+                            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,
+                            reason: `${other} (changed here) imports ${file} (changed in the other worktree).`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    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,
+    };
+}
+//# 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,49 @@
+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;
+/** 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,71 @@
+import { detectCollisions } from './collisionDetector.js';
+import { listClaims, findContendedClaims } from './claims.js';
+import { computeMergeRisk } 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,
+    };
+}
+/** Run the full coordination read for the repo's in-flight worktrees. */
+export async function computeCoordination(rootPath, options = {}) {
+    const [collisionReport, claims, mergeRisk] = await Promise.all([
+        detectCollisions(rootPath, options),
+        listClaims(rootPath),
+        computeMergeRisk(rootPath, options),
+    ]);
+    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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"}