@papyruslabsai/seshat-mcp 0.20.0 → 0.20.1

package/dist/tools/diff.js

@@ -1,604 +0,0 @@
-/**
- * Cross-Bundle Analysis Tools: diff_bundle + conflict_matrix
- *
- * diff_bundle: Compare entities between a worktree and the loaded project.
- * conflict_matrix: Classify conflict tiers for parallel task scheduling.
- *
- * These tools compare TWO entity sets (base vs branch, or task vs task),
- * unlike the single-bundle queries in index.ts and functors.ts.
- */
-import fs from 'fs';
-import path from 'path';
-import { bootstrap } from '../bootstrap.js';
-import { computeBlastRadius } from '../graph.js';
-import { getGraph, validateProject, entityName, entityLayer, } from './index.js';
-import { tableContract } from './dbops.js';
-// ─── Entity Identity ─────────────────────────────────────────────
-// Ported from api-v2/translator/seshat-pipeline/src/incremental/diff-engine.mjs
-/**
- * Generate a unique key for an entity: <relative_path>::<id>
- *
- * Uses _sourceFile (already relative in bundles) or derives from
- * sourceFile (absolute path) by stripping the repo root.
- */
-function entityKey(entity, repoRoot) {
-    let relativePath = entity._sourceFile || null;
-    // If _sourceFile not set, try deriving from sourceFile (absolute)
-    if (!relativePath) {
-        const raw = entity;
-        const sourceFile = (raw.sourceFile || '').replace(/\\/g, '/');
-        if (repoRoot && sourceFile) {
-            const normalizedRoot = repoRoot.replace(/\\/g, '/').replace(/\/+$/, '') + '/';
-            if (sourceFile.startsWith(normalizedRoot)) {
-                relativePath = sourceFile.substring(normalizedRoot.length);
-            }
-            else {
-                // Case-insensitive match (Windows paths)
-                const lowerFile = sourceFile.toLowerCase();
-                const lowerRoot = normalizedRoot.toLowerCase();
-                if (lowerFile.startsWith(lowerRoot)) {
-                    relativePath = sourceFile.substring(normalizedRoot.length);
-                }
-            }
-        }
-        if (!relativePath) {
-            relativePath = sourceFile || 'unknown';
-        }
-    }
-    // Normalize path separators
-    relativePath = (relativePath || 'unknown').replace(/\\/g, '/');
-    const id = entity.id || (typeof entity.struct === 'string' ? entity.struct : entity.struct?.name) || 'anonymous';
-    return `${relativePath}::${id}`;
-}
-// ─── Bundle Loading ───────────────────────────────────────────────
-/**
- * Load a branch bundle from a worktree path.
- * Does NOT add to the global MultiLoader — this is a transient comparison target.
- *
- * 1. Check <worktree_path>/.seshat/_bundle.json — parse if exists
- * 2. If not, run bootstrap() to extract on-the-fly
- * 3. Apply the same field remapping as BundleLoader (sourceFile → _sourceFile, etc.)
- */
-async function loadBranchBundle(worktreePath) {
-    const absPath = path.resolve(worktreePath);
-    const bundlePath = path.join(absPath, '.seshat', '_bundle.json');
-    let bundle;
-    if (fs.existsSync(bundlePath)) {
-        const raw = fs.readFileSync(bundlePath, 'utf-8');
-        bundle = JSON.parse(raw);
-    }
-    else {
-        // Auto-extract via bootstrap
-        const result = await bootstrap(absPath);
-        if (!result.success) {
-            throw new Error(`Failed to extract bundle from ${absPath}: ${result.error}`);
-        }
-        // Read the freshly generated bundle
-        if (!fs.existsSync(bundlePath)) {
-            throw new Error(`Bootstrap succeeded but no bundle found at ${bundlePath}`);
-        }
-        const raw = fs.readFileSync(bundlePath, 'utf-8');
-        bundle = JSON.parse(raw);
-    }
-    const entities = bundle.entities || [];
-    // Apply the same field remapping as BundleLoader.load()
-    for (const e of entities) {
-        const raw = e;
-        if (raw.sourceFile && !e._sourceFile) {
-            e._sourceFile = raw.sourceFile;
-        }
-        if (raw.sourceLanguage && !e._sourceLanguage) {
-            e._sourceLanguage = raw.sourceLanguage;
-        }
-    }
-    // Try to get commit SHA from manifest
-    let commitSha = '';
-    const manifestPath = path.join(absPath, '.seshat', 'manifest.json');
-    if (fs.existsSync(manifestPath)) {
-        try {
-            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-            commitSha = manifest.commitSha || '';
-        }
-        catch { /* ignore */ }
-    }
-    return {
-        entities,
-        source: bundle.source || absPath,
-        commitSha,
-        entityCount: entities.length,
-    };
-}
-// ─── Field Comparison ─────────────────────────────────────────────
-/** The entity fields to compare, mapped to user-facing names (v0.4.2 convention) */
-const FIELD_MAP = [
-    ['struct', 'structure'],
-    ['edges', 'call_graph'],
-    ['data', 'data_flow'],
-    ['constraints', 'constraints'],
-    ['context', 'context'],
-    ['ownership', 'ownership'],
-    ['traits', 'type_info'],
-    ['runtime', 'runtime'],
-    ['semantics', 'logic'],
-];
-/**
- * Compare two entities field-by-field. Returns which fields changed
- * using user-facing names.
- */
-function compareEntityFields(baseEntity, branchEntity) {
-    const changed = [];
-    for (const [field, displayName] of FIELD_MAP) {
-        const baseVal = baseEntity[field];
-        const branchVal = branchEntity[field];
-        // Both undefined/null → no change
-        if (baseVal == null && branchVal == null)
-            continue;
-        // One null, other not → changed
-        if (baseVal == null || branchVal == null) {
-            changed.push(displayName);
-            continue;
-        }
-        // Deep compare via JSON
-        if (JSON.stringify(baseVal) !== JSON.stringify(branchVal)) {
-            changed.push(displayName);
-        }
-    }
-    return changed;
-}
-// ─── Tool: diff_bundle ───────────────────────────────────────────
-export async function diffBundle(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const baseEntities = loader.getEntities(args.project);
-    const baseManifest = loader.getManifest(args.project);
-    if (baseEntities.length === 0) {
-        return { error: 'No base entities loaded. Ensure the project has been extracted.' };
-    }
-    // Load branch bundle
-    let branchData;
-    try {
-        branchData = await loadBranchBundle(args.worktree_path);
-    }
-    catch (err) {
-        return { error: `Failed to load branch bundle: ${err.message}` };
-    }
-    const branchEntities = branchData.entities;
-    // Build entity maps by key
-    const baseSource = baseManifest?.commitSha ? '' : ''; // base entities have relative paths already
-    const baseMap = new Map();
-    for (const entity of baseEntities) {
-        const key = entityKey(entity);
-        baseMap.set(key, entity);
-    }
-    const branchMap = new Map();
-    for (const entity of branchEntities) {
-        const key = entityKey(entity);
-        branchMap.set(key, entity);
-    }
-    // Classify entities
-    const added = [];
-    const removed = [];
-    const modified = [];
-    const unchanged = [];
-    // Added: in branch but not base
-    for (const [key, entity] of branchMap) {
-        if (!baseMap.has(key)) {
-            added.push({
-                id: entity.id,
-                name: entityName(entity),
-                sourceFile: entity._sourceFile || null,
-                layer: entityLayer(entity),
-            });
-        }
-    }
-    // Removed: in base but not branch
-    for (const [key, entity] of baseMap) {
-        if (!branchMap.has(key)) {
-            removed.push({
-                id: entity.id,
-                name: entityName(entity),
-                sourceFile: entity._sourceFile || null,
-                layer: entityLayer(entity),
-            });
-        }
-    }
-    // Modified / Unchanged: in both
-    for (const [key, branchEntity] of branchMap) {
-        const baseEntity = baseMap.get(key);
-        if (!baseEntity)
-            continue; // already in added
-        const changedFields = compareEntityFields(baseEntity, branchEntity);
-        if (changedFields.length > 0) {
-            modified.push({
-                id: branchEntity.id,
-                name: entityName(branchEntity),
-                sourceFile: branchEntity._sourceFile || null,
-                layer: entityLayer(branchEntity),
-                changedFields,
-            });
-        }
-        else if (args.include_unchanged) {
-            unchanged.push({
-                id: branchEntity.id,
-                name: entityName(branchEntity),
-                sourceFile: branchEntity._sourceFile || null,
-                layer: entityLayer(branchEntity),
-            });
-        }
-    }
-    // Count unique files touched
-    const touchedFiles = new Set();
-    for (const e of [...added, ...removed, ...modified]) {
-        if (e.sourceFile)
-            touchedFiles.add(e.sourceFile);
-    }
-    const totalChanges = added.length + removed.length + modified.length;
-    const result = {
-        base: {
-            project: baseManifest?.projectName || args.project || 'default',
-            commitSha: baseManifest?.commitSha || '',
-            entityCount: baseEntities.length,
-        },
-        branch: {
-            path: args.worktree_path,
-            commitSha: branchData.commitSha,
-            entityCount: branchData.entityCount,
-        },
-        summary: {
-            added: added.length,
-            removed: removed.length,
-            modified: modified.length,
-            unchanged: baseEntities.length - removed.length - modified.length,
-        },
-        added,
-        removed,
-        modified,
-        _summary: `Branch modifies ${totalChanges} entities (${added.length} added, ${removed.length} removed, ${modified.length} modified) across ${touchedFiles.size} files`,
-    };
-    if (args.include_unchanged) {
-        result.unchanged = unchanged;
-    }
-    return result;
-}
-/**
- * Entropy weights — measured, not asserted. Instance-weighted Shannon entropy
- * per dimension, FUNCTION-LEVEL entities only (conflict tasks target functions;
- * import/const entities dilute all-entities numbers). Re-measured 2026-06-11 on
- * the CLEAN substrate (honest κ, derived χ, collapsed ε — sniffr-backend snap
- * 205 + ptah snap 207 + second-brain snap 210, ~2,059 JS function instances):
- * the original 56-project corpus was extracted pre-Testimony-Rule, so part of
- * its κ entropy was false-positive variety and its χ was path-substring noise.
- * Clean JS vector: ε .225, Σ .146, δ .140, χ .114, κ .107, σ .089; ρ 0
- * everywhere. Notable shift vs the corrupted corpus: χ (.087→.114) overtakes
- * σ (.107→.089) — topology-derived layers carry real discrimination. See
- * ptah/docs/dimension-entropy-2026-06-clean.json (by_language_functions) and
- * DIMENSION-ENTROPY-FINDINGS.md (clean re-run section).
- */
-const CONFLICT_WEIGHTS = {
-    symbols: 0.09, // σ — direct entity overlap
-    epsilon: 0.23, // ε — shared call-graph neighborhood
-    delta: 0.14, // δ — shared data contracts (tables)
-    files: 0.11, // χ-adjacent — shared files
-    // Historical co-change from the lineage record (entity_transitions):
-    // entities that changed together in past commits are coupled IN PRACTICE,
-    // whatever static analysis says. Weight provisional — revisit once
-    // corpus-wide lineage allows an entropy-style calibration.
-    history: 0.10,
-};
-function jaccard(a, b) {
-    if (a.size === 0 && b.size === 0)
-        return 0;
-    let inter = 0;
-    for (const x of a)
-        if (b.has(x))
-            inter++;
-    return inter / (a.size + b.size - inter);
-}
-function intersect(a, b) {
-    const out = [];
-    for (const x of a)
-        if (b.has(x))
-            out.push(x);
-    return out;
-}
-/** Co-change pairs between two tasks, from a pre-fetched pair→count map keyed `${idA}
${idB}` (sorted). */
-function coChangePairs(taskA, taskB, coChange) {
-    if (!coChange || coChange.size === 0)
-        return [];
-    const out = [];
-    for (const a of taskA.entityIds) {
-        for (const b of taskB.entityIds) {
-            if (a === b)
-                continue;
-            const key = a < b ? `${a}
${b}` : `${b}
${a}`;
-            const n = coChange.get(key);
-            if (n && n >= 2)
-                out.push({ a, b, sharedCommits: n });
-        }
-    }
-    return out.sort((x, y) => y.sharedCommits - x.sharedCommits);
-}
-// ≥ this many shared commits between a cross-task entity pair = coupled in
-// practice, escalate to Tier 2 even when statically disjoint everywhere.
-const CO_CHANGE_TIER2_THRESHOLD = 3;
-function classifyConflictTier(taskA, taskB, coChange = null) {
-    const sharedEntities = intersect(taskA.entityIds, taskB.entityIds);
-    const sharedFiles = intersect(taskA.files, taskB.files);
-    const sharedNeighbors = intersect(taskA.neighbors, taskB.neighbors);
-    // δ-contract overlap with read/write direction per side
-    const sharedTables = [];
-    const allTables = new Set([
-        ...taskA.tablesRead, ...taskA.tablesWritten,
-        ...taskB.tablesRead, ...taskB.tablesWritten,
-    ]);
-    for (const table of allTables) {
-        const aW = taskA.tablesWritten.has(table);
-        const aR = taskA.tablesRead.has(table) || aW;
-        const bW = taskB.tablesWritten.has(table);
-        const bR = taskB.tablesRead.has(table) || bW;
-        if (aR && bR && (aW || bW)) {
-            // overlap matters only when at least one side writes
-            sharedTables.push({ table, taskA: aW ? 'write' : 'read', taskB: bW ? 'write' : 'read' });
-        }
-    }
-    const writeWrite = sharedTables.filter(t => t.taskA === 'write' && t.taskB === 'write');
-    const readWrite = sharedTables.filter(t => t.taskA !== t.taskB);
-    // Historical co-change (lineage evidence)
-    const sharedHistory = coChangePairs(taskA, taskB, coChange);
-    const maxShared = sharedHistory[0]?.sharedCommits || 0;
-    // Entropy-weighted evidence score in [0,1]
-    const tablesA = new Set([...taskA.tablesRead, ...taskA.tablesWritten]);
-    const tablesB = new Set([...taskB.tablesRead, ...taskB.tablesWritten]);
-    const w = CONFLICT_WEIGHTS;
-    const totalW = w.symbols + w.epsilon + w.delta + w.files + w.history;
-    const conflictScore = Math.round(((w.symbols * jaccard(taskA.entityIds, taskB.entityIds) +
-        w.epsilon * jaccard(taskA.neighbors, taskB.neighbors) +
-        w.delta * jaccard(tablesA, tablesB) +
-        w.files * jaccard(taskA.files, taskB.files) +
-        w.history * Math.min(1, maxShared / 5)) / totalW) * 1000) / 1000;
-    const base = { conflictScore, sharedFiles, sharedEntities, sharedTables, sharedNeighbors, sharedHistory };
-    // Tier 3 — must sequence
-    if (sharedEntities.length > 0) {
-        return {
-            ...base,
-            tier: 3,
-            reason: `${sharedEntities.length} shared symbols — MUST sequence to maintain surgical splice integrity`,
-        };
-    }
-    if (writeWrite.length > 0) {
-        return {
-            ...base,
-            tier: 3,
-            reason: `shared data contract — both tasks WRITE table(s) ${writeWrite.map(t => t.table).join(', ')}; ` +
-                'symbols are disjoint but the tasks collide through the data layer — MUST sequence',
-        };
-    }
-    // Tier 2 — parallelize with care
-    if (readWrite.length > 0) {
-        return {
-            ...base,
-            tier: 2,
-            reason: `read/write data contract overlap on table(s) ${readWrite.map(t => t.table).join(', ')} — ` +
-                'parallel-safe only if the reader tolerates the writer\'s changes',
-        };
-    }
-    if (sharedFiles.length > 0) {
-        return {
-            ...base,
-            tier: 2,
-            reason: `${sharedFiles.length} shared files but different symbols — safe to parallelize via surgical splicing`,
-        };
-    }
-    if (sharedNeighbors.length > 0) {
-        return {
-            ...base,
-            tier: 2,
-            reason: `call-graph adjacency — tasks touch ${sharedNeighbors.length} shared neighbor(s) within 1 hop ` +
-                `(e.g. ${sharedNeighbors.slice(0, 3).join(', ')}) — review the shared interface before parallelizing`,
-        };
-    }
-    if (maxShared >= CO_CHANGE_TIER2_THRESHOLD) {
-        const top = sharedHistory[0];
-        return {
-            ...base,
-            tier: 2,
-            reason: `historical co-change — ${top.a.split('#').pop()} and ${top.b.split('#').pop()} changed together ` +
-                `in ${top.sharedCommits} past commits (${sharedHistory.length} coupled pair${sharedHistory.length === 1 ? '' : 's'} total); ` +
-                'statically disjoint but coupled in practice — review for an implicit shared contract before parallelizing',
-        };
-    }
-    if (conflictScore > 0) {
-        return {
-            ...base,
-            tier: 1,
-            reason: 'No conflicting overlap (weak affinity only — shared read-only tables or nearby code) — safe to parallelize',
-        };
-    }
-    return { ...base, tier: 1, reason: 'No shared symbols, files, data contracts, or call-graph adjacency — safe to parallelize' };
-}
-// ─── Execution Plan Builder ───────────────────────────────────────
-/**
- * Build execution plan from tier-3 conflict graph using connected components.
- * Tasks with no tier-3 edges to each other run in parallel.
- * Tasks in the same tier-3 component run sequentially.
- */
-function buildExecutionPlan(taskIds, tier3Edges) {
-    // Build adjacency list for tier-3 conflicts
-    const adj = new Map();
-    for (const id of taskIds) {
-        adj.set(id, new Set());
-    }
-    for (const [a, b] of tier3Edges) {
-        adj.get(a)?.add(b);
-        adj.get(b)?.add(a);
-    }
-    // Find connected components via BFS
-    const visited = new Set();
-    const components = [];
-    for (const id of taskIds) {
-        if (visited.has(id))
-            continue;
-        const component = [];
-        const queue = [id];
-        visited.add(id);
-        while (queue.length > 0) {
-            const current = queue.shift();
-            component.push(current);
-            const neighbors = adj.get(current);
-            if (neighbors) {
-                for (const neighbor of neighbors) {
-                    if (!visited.has(neighbor)) {
-                        visited.add(neighbor);
-                        queue.push(neighbor);
-                    }
-                }
-            }
-        }
-        components.push(component);
-    }
-    // Build groups
-    const groups = components.map(component => {
-        if (component.length === 1) {
-            return { tasks: component, sequential: false };
-        }
-        return { tasks: component, sequential: true, order: component };
-    });
-    // Count parallelizable groups
-    const parallelGroups = groups.length;
-    const sequentialCount = groups.filter(g => g.sequential).length;
-    const parallelCount = groups.filter(g => !g.sequential).length;
-    let summaryParts = [`${taskIds.length} tasks`];
-    if (parallelCount > 0) {
-        summaryParts.push(`${parallelCount === taskIds.length ? 'all' : parallelCount} can run in parallel`);
-    }
-    if (sequentialCount > 0) {
-        const seqTasks = groups.filter(g => g.sequential).reduce((sum, g) => sum + g.tasks.length, 0);
-        summaryParts.push(`${seqTasks} must be sequenced (${sequentialCount} sequential group${sequentialCount > 1 ? 's' : ''})`);
-    }
-    return {
-        parallelGroups,
-        groups,
-        _summary: summaryParts.join(': '),
-    };
-}
-// ─── Tool: conflict_matrix ────────────────────────────────────────
-export async function conflictMatrix(args, loader, extras = {}) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { tasks } = args;
-    if (!tasks || tasks.length < 2) {
-        return { error: 'At least 2 tasks are required to compute a conflict matrix.' };
-    }
-    const warnings = [];
-    // Resolve entity sets for each task
-    const resolvedTasks = [];
-    const graph = getGraph(args.project, loader);
-    for (const task of tasks) {
-        const entityIds = new Set();
-        const files = new Set();
-        const entities = [];
-        const notFound = [];
-        const dimensions = new Set(task.dimensions || []);
-        for (const nameOrId of task.entity_ids) {
-            const entity = loader.getEntityById(nameOrId, args.project)
-                || loader.getEntityByName(nameOrId, args.project);
-            if (entity) {
-                entityIds.add(entity.id);
-                entities.push(entity);
-                if (entity._sourceFile)
-                    files.add(entity._sourceFile);
-            }
-            else {
-                notFound.push(nameOrId);
-            }
-        }
-        if (notFound.length > 0) {
-            warnings.push(`Task "${task.id}": entities not found: ${notFound.join(', ')}`);
-        }
-        // Expand blast radius if requested
-        if (task.expand_blast_radius && entityIds.size > 0) {
-            const blastResult = computeBlastRadius(graph, entityIds);
-            for (const affectedId of blastResult.affected) {
-                if (!entityIds.has(affectedId)) {
-                    entityIds.add(affectedId);
-                    const affectedEntity = graph.entityById.get(affectedId);
-                    if (affectedEntity) {
-                        entities.push(affectedEntity);
-                        if (affectedEntity._sourceFile)
-                            files.add(affectedEntity._sourceFile);
-                    }
-                }
-            }
-        }
-        // δ-contract surface: tables read/written by the task's entities
-        const { reads: tablesRead, writes: tablesWritten } = tableContract(entities);
-        // ε surface: 1-hop call-graph neighborhood (always computed — cheap, and
-        // it catches adjacent-task conflicts even without blast-radius expansion)
-        const neighbors = new Set();
-        for (const id of entityIds) {
-            for (const c of graph.callers.get(id) || [])
-                if (!entityIds.has(c))
-                    neighbors.add(c);
-            for (const c of graph.callees.get(id) || [])
-                if (!entityIds.has(c))
-                    neighbors.add(c);
-        }
-        resolvedTasks.push({ id: task.id, entityIds, files, entities, dimensions, tablesRead, tablesWritten, neighbors });
-    }
-    // Pairwise comparison
-    const matrix = [];
-    // Lineage-backed co-change evidence, fetched once for all tasks' entities
-    let coChange = null;
-    if (extras.fetchCoChanges) {
-        try {
-            const allIds = [...new Set(resolvedTasks.flatMap(t => [...t.entityIds]))];
-            coChange = await extras.fetchCoChanges(allIds);
-        }
-        catch {
-            warnings.push('co-change history unavailable for this run (lineage lookup failed) — tiers computed from static evidence only');
-        }
-    }
-    const tier3Edges = [];
-    for (let i = 0; i < resolvedTasks.length; i++) {
-        for (let j = i + 1; j < resolvedTasks.length; j++) {
-            const taskA = resolvedTasks[i];
-            const taskB = resolvedTasks[j];
-            const result = classifyConflictTier(taskA, taskB, coChange);
-            const entry = {
-                taskA: taskA.id,
-                taskB: taskB.id,
-                tier: result.tier,
-                reason: result.reason,
-                conflictScore: result.conflictScore,
-            };
-            if (result.sharedFiles.length > 0)
-                entry.sharedFiles = result.sharedFiles;
-            if (result.sharedEntities.length > 0)
-                entry.sharedEntities = result.sharedEntities;
-            if (result.sharedTables.length > 0)
-                entry.sharedTables = result.sharedTables;
-            if (result.sharedNeighbors.length > 0)
-                entry.sharedNeighbors = result.sharedNeighbors.slice(0, 10);
-            if (result.sharedHistory && result.sharedHistory.length > 0)
-                entry.sharedHistory = result.sharedHistory.slice(0, 10);
-            matrix.push(entry);
-            if (result.tier === 3) {
-                tier3Edges.push([taskA.id, taskB.id]);
-            }
-        }
-    }
-    // Build execution plan
-    const taskIds = resolvedTasks.map(t => t.id);
-    const executionPlan = buildExecutionPlan(taskIds, tier3Edges);
-    const result = {
-        taskCount: tasks.length,
-        matrix,
-        executionPlan,
-    };
-    if (warnings.length > 0) {
-        result.warnings = warnings;
-    }
-    return result;
-}