@papyruslabsai/seshat-mcp 0.4.1 → 0.6.0

package/dist/tools/diff.js

@@ -0,0 +1,491 @@
+/**
+ * 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 { getLoader, getGraph, validateProject, entityName, entityLayer, } from './index.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) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    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;
+}
+// ─── Conflict Tier Classification ─────────────────────────────────
+const ZONE_1 = new Set(['edges', 'imports', 'ε']); // Header / Far from body
+const ZONE_2 = new Set(['struct', 'σ', 'constraints', 'κ', 'traits', 'τ', 'ownership', 'λ']); // Signature / Decorators (High collision risk)
+const ZONE_3 = new Set(['semantics', 'Σ', 'data', 'δ', 'runtime', 'ρ']); // Body / Implementation
+function getZones(dimensions) {
+    const zones = new Set();
+    for (const d of dimensions) {
+        const lower = d.toLowerCase();
+        if (ZONE_1.has(lower))
+            zones.add(1);
+        if (ZONE_2.has(lower))
+            zones.add(2);
+        if (ZONE_3.has(lower))
+            zones.add(3);
+    }
+    return zones;
+}
+function classifyConflictTier(taskA, taskB) {
+    // Check entity overlap
+    const sharedEntities = [];
+    for (const id of taskA.entityIds) {
+        if (taskB.entityIds.has(id)) {
+            sharedEntities.push(id);
+        }
+    }
+    if (sharedEntities.length > 0) {
+        // Both touch same entity. Check dimensions to see if we can downgrade from Tier 4 (Sequential) to Tier 3 (Parallelizable Orthogonal)
+        if (taskA.dimensions.size > 0 && taskB.dimensions.size > 0) {
+            const zonesA = getZones(taskA.dimensions);
+            const zonesB = getZones(taskB.dimensions);
+            let spatialCollision = false;
+            for (const z of zonesA) {
+                if (zonesB.has(z))
+                    spatialCollision = true;
+            }
+            if (!spatialCollision) {
+                return {
+                    tier: 3,
+                    reason: `${sharedEntities.length} shared entities, but orthogonal Spatial Zones (Tier 3) — safe to parallelize`,
+                    sharedFiles: [],
+                    sharedEntities,
+                };
+            }
+        }
+        return {
+            tier: 4,
+            reason: `${sharedEntities.length} shared entities in same/unknown Spatial Zone (Tier 4) — MUST sequence to prevent git conflict`,
+            sharedFiles: [],
+            sharedEntities,
+        };
+    }
+    // Check file overlap → Tier 1 or 2
+    const sharedFiles = [];
+    for (const file of taskA.files) {
+        if (taskB.files.has(file)) {
+            sharedFiles.push(file);
+        }
+    }
+    if (sharedFiles.length === 0) {
+        return {
+            tier: 1,
+            reason: 'No shared files — safe to parallelize',
+            sharedFiles: [],
+            sharedEntities: [],
+        };
+    }
+    return {
+        tier: 2,
+        reason: `${sharedFiles.length} shared files but different entities — git auto-merge handles it`,
+        sharedFiles,
+        sharedEntities: [],
+    };
+}
+// ─── Execution Plan Builder ───────────────────────────────────────
+/**
+ * Build execution plan from tier-4 conflict graph using connected components.
+ * Tasks with no tier-4 edges to each other run in parallel.
+ * Tasks in the same tier-4 component run sequentially.
+ */
+function buildExecutionPlan(taskIds, tier4Edges) {
+    // Build adjacency list for tier-4 conflicts
+    const adj = new Map();
+    for (const id of taskIds) {
+        adj.set(id, new Set());
+    }
+    for (const [a, b] of tier4Edges) {
+        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 function conflictMatrix(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    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 = [];
+    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 g = getGraph(args.project);
+            const blastResult = computeBlastRadius(g, entityIds);
+            for (const affectedId of blastResult.affected) {
+                if (!entityIds.has(affectedId)) {
+                    entityIds.add(affectedId);
+                    const affectedEntity = g.entityById.get(affectedId);
+                    if (affectedEntity) {
+                        entities.push(affectedEntity);
+                        if (affectedEntity._sourceFile)
+                            files.add(affectedEntity._sourceFile);
+                    }
+                }
+            }
+        }
+        resolvedTasks.push({ id: task.id, entityIds, files, entities, dimensions });
+    }
+    // Pairwise comparison
+    const matrix = [];
+    const tier4Edges = [];
+    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);
+            const entry = {
+                taskA: taskA.id,
+                taskB: taskB.id,
+                tier: result.tier,
+                reason: result.reason,
+            };
+            if (result.sharedFiles.length > 0)
+                entry.sharedFiles = result.sharedFiles;
+            if (result.sharedEntities.length > 0)
+                entry.sharedEntities = result.sharedEntities;
+            matrix.push(entry);
+            if (result.tier === 4) {
+                tier4Edges.push([taskA.id, taskB.id]);
+            }
+        }
+    }
+    // Build execution plan
+    const taskIds = resolvedTasks.map(t => t.id);
+    const executionPlan = buildExecutionPlan(taskIds, tier4Edges);
+    const result = {
+        taskCount: tasks.length,
+        matrix,
+        executionPlan,
+    };
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    return result;
+}

package/dist/tools/functors.d.ts

@@ -1,15 +1,15 @@
 /**
- * Interpretation Functor Tools
+ * Analysis Tools
  *
- * Each functor is I: J -> D — projecting the 9D JSTF-T coordinate space
- * onto a domain-specific judgment. These are composite analyses built
- * from the primitive dimensions (sigma, epsilon, delta, kappa, chi, tau, rho).
+ * Composite analyses built from the extracted code entity graph.
+ * Each tool computes derived insights (dead code, layer violations,
+ * coupling metrics, auth coverage, etc.) from the entity data.
  */
 import type { JstfEntity } from '../types.js';
 /**
  * Estimate the token cost of loading an entity's source code into an LLM context.
  * Uses real sourceTokens from the extraction pipeline when available (v0.3.2+),
- * falls back to heuristic estimation from 9D coordinates for older bundles.
+ * falls back to heuristic estimation for older bundles.
  */
 export declare function estimateTokens(e: JstfEntity): number;
 export declare function findDeadCode(args: {
@@ -66,3 +66,13 @@ export declare function reportActualBurn(args: {
     project?: string;
     notes?: string;
 }): Promise<unknown>;
+export declare function find_runtime_violations(args?: {
+    project?: string;
+}): unknown;
+export declare function find_ownership_violations(args?: {
+    project?: string;
+}): unknown;
+export declare function query_traits(args: {
+    trait: string;
+    project?: string;
+}): unknown;