@papyruslabsai/seshat-mcp 0.1.0 → 0.3.0

package/dist/tools/functors.js

@@ -0,0 +1,554 @@
+/**
+ * Interpretation Functor 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).
+ */
+import { computeBlastRadius } from '../graph.js';
+import { getLoader, getGraph, validateProject, entityLayer, entitySummary, } from './index.js';
+// ─── Layer ordering for violation detection ──────────────────────
+const LAYER_ORDER = {
+    route: 0,
+    controller: 1,
+    middleware: 2,
+    service: 3,
+    hook: 4,
+    repository: 5,
+    model: 6,
+    schema: 7,
+    utility: 8,
+    component: 1, // UI components are peers to controllers
+};
+// ─── Functor 1: find_dead_code ───────────────────────────────────
+export function findDeadCode(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const { include_tests = false } = args;
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    const entities = loader.getEntities(args.project);
+    // Entry points: routes, exported functions, test files, plugin registrations
+    const entryPointIds = new Set();
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        const layer = entityLayer(e);
+        // Routes and controllers are entry points
+        if (layer === 'route' || layer === 'controller') {
+            entryPointIds.add(e.id);
+            continue;
+        }
+        // Test entities are entry points
+        if (layer === 'test') {
+            entryPointIds.add(e.id);
+            continue;
+        }
+        // Plugin registrations
+        if (e.context?.exposure === 'framework') {
+            entryPointIds.add(e.id);
+            continue;
+        }
+        // Exported functions at the top level are entry points
+        if (typeof e.struct !== 'string' && e.struct?.exported) {
+            entryPointIds.add(e.id);
+        }
+    }
+    // BFS from all entry points through callees
+    const reachable = new Set(entryPointIds);
+    const queue = [...entryPointIds];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const calleeSet = g.callees.get(current);
+        if (!calleeSet)
+            continue;
+        for (const calleeId of calleeSet) {
+            if (!reachable.has(calleeId)) {
+                reachable.add(calleeId);
+                queue.push(calleeId);
+            }
+        }
+    }
+    // Unreachable = dead code candidates
+    let deadEntities = entities.filter(e => e.id && !reachable.has(e.id));
+    if (!include_tests) {
+        deadEntities = deadEntities.filter(e => entityLayer(e) !== 'test');
+    }
+    // Group by layer for overview
+    const byLayer = new Map();
+    for (const e of deadEntities) {
+        const l = entityLayer(e);
+        byLayer.set(l, (byLayer.get(l) || 0) + 1);
+    }
+    return {
+        totalEntities: entities.length,
+        entryPoints: entryPointIds.size,
+        reachable: reachable.size,
+        deadCount: deadEntities.length,
+        deadByLayer: Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1])),
+        dead: deadEntities.slice(0, 100).map(entitySummary),
+    };
+}
+// ─── Functor 2: find_layer_violations ────────────────────────────
+export function findLayerViolations(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args?.project);
+    const violations = [];
+    for (const [callerId, calleeIds] of g.callees) {
+        const callerEntity = g.entityById.get(callerId);
+        if (!callerEntity)
+            continue;
+        const callerLayer = entityLayer(callerEntity);
+        const callerOrder = LAYER_ORDER[callerLayer];
+        if (callerOrder === undefined)
+            continue;
+        for (const calleeId of calleeIds) {
+            const calleeEntity = g.entityById.get(calleeId);
+            if (!calleeEntity)
+                continue;
+            const calleeLayer = entityLayer(calleeEntity);
+            const calleeOrder = LAYER_ORDER[calleeLayer];
+            if (calleeOrder === undefined)
+                continue;
+            // Skip same-layer calls
+            if (callerLayer === calleeLayer)
+                continue;
+            // Backward call: lower layer calling higher layer
+            if (callerOrder > calleeOrder) {
+                violations.push({
+                    from: entitySummary(callerEntity),
+                    to: entitySummary(calleeEntity),
+                    type: `backward: ${callerLayer}(${callerOrder}) -> ${calleeLayer}(${calleeOrder})`,
+                });
+            }
+            // Skip-layer: jumping over more than 1 layer
+            else if (calleeOrder - callerOrder > 2) {
+                violations.push({
+                    from: entitySummary(callerEntity),
+                    to: entitySummary(calleeEntity),
+                    type: `skip-layer: ${callerLayer}(${callerOrder}) -> ${calleeLayer}(${calleeOrder})`,
+                });
+            }
+        }
+    }
+    // Group violations by type
+    const byType = new Map();
+    for (const v of violations) {
+        const typePrefix = v.type.split(':')[0];
+        byType.set(typePrefix, (byType.get(typePrefix) || 0) + 1);
+    }
+    return {
+        totalViolations: violations.length,
+        byType: Object.fromEntries(byType),
+        violations: violations.slice(0, 100),
+    };
+}
+// ─── Functor 3: get_coupling_metrics ─────────────────────────────
+export function getCouplingMetrics(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const { group_by = 'module' } = args;
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    const entities = loader.getEntities(args.project);
+    // Group entities
+    const groups = new Map();
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        const key = group_by === 'module'
+            ? (e.context?.module || 'unknown')
+            : entityLayer(e);
+        if (!groups.has(key))
+            groups.set(key, new Set());
+        groups.get(key).add(e.id);
+    }
+    const metrics = [];
+    for (const [groupName, memberIds] of groups) {
+        let internalEdges = 0;
+        let outgoingEdges = 0;
+        let incomingEdges = 0;
+        for (const memberId of memberIds) {
+            const calleeSet = g.callees.get(memberId);
+            if (calleeSet) {
+                for (const calleeId of calleeSet) {
+                    if (memberIds.has(calleeId)) {
+                        internalEdges++;
+                    }
+                    else {
+                        outgoingEdges++;
+                    }
+                }
+            }
+            const callerSet = g.callers.get(memberId);
+            if (callerSet) {
+                for (const callerId of callerSet) {
+                    if (!memberIds.has(callerId)) {
+                        incomingEdges++;
+                    }
+                }
+            }
+        }
+        const size = memberIds.size;
+        const maxInternalEdges = size * (size - 1); // directed
+        const cohesion = maxInternalEdges > 0 ? internalEdges / maxInternalEdges : 0;
+        const totalExternal = outgoingEdges + incomingEdges;
+        const coupling = totalExternal;
+        const instability = totalExternal > 0 ? outgoingEdges / totalExternal : 0;
+        metrics.push({
+            group: groupName,
+            size,
+            internalEdges,
+            externalEdges: totalExternal,
+            cohesion: Math.round(cohesion * 1000) / 1000,
+            coupling,
+            instability: Math.round(instability * 1000) / 1000,
+        });
+    }
+    // Sort by coupling (most coupled first)
+    metrics.sort((a, b) => b.coupling - a.coupling);
+    return {
+        groupBy: group_by,
+        groupCount: metrics.length,
+        metrics: metrics.slice(0, 50),
+    };
+}
+// ─── Functor 4: get_auth_matrix ──────────────────────────────────
+export function getAuthMatrix(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args?.project);
+    const apiEntities = entities.filter(e => {
+        const layer = entityLayer(e);
+        return layer === 'route' || layer === 'controller' ||
+            e.context?.exposure === 'api';
+    });
+    const withAuth = [];
+    const withoutAuth = [];
+    const inconsistencies = [];
+    for (const e of apiEntities) {
+        const constraints = e.constraints;
+        const hasAuth = constraints && !Array.isArray(constraints) &&
+            constraints.auth && constraints.auth !== 'none';
+        const summary = entitySummary(e);
+        if (hasAuth) {
+            withAuth.push({
+                ...summary,
+                auth: constraints.auth,
+            });
+        }
+        else {
+            withoutAuth.push(summary);
+        }
+        // Check for inconsistencies: has auth decorator but marked as public
+        if (hasAuth && e.context?.visibility === 'public') {
+            inconsistencies.push({
+                entity: summary,
+                issue: 'Has auth requirements but visibility is public',
+            });
+        }
+        // Has DB access but no auth
+        if (!hasAuth) {
+            const sideEffects = constraints && !Array.isArray(constraints)
+                ? constraints.sideEffects : undefined;
+            if (Array.isArray(sideEffects) && sideEffects.some((s) => s === 'db' || s === 'database')) {
+                inconsistencies.push({
+                    entity: summary,
+                    issue: 'DB access without auth — potential security gap',
+                });
+            }
+        }
+    }
+    return {
+        totalApiEntities: apiEntities.length,
+        withAuth: withAuth.length,
+        withoutAuth: withoutAuth.length,
+        inconsistencies: inconsistencies.length,
+        authenticated: withAuth.slice(0, 50),
+        unauthenticated: withoutAuth.slice(0, 50),
+        issues: inconsistencies.slice(0, 50),
+    };
+}
+// ─── Functor 5: find_error_gaps ──────────────────────────────────
+export function findErrorGaps(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const g = getGraph(args?.project);
+    const entities = loader.getEntities(args?.project);
+    // Find all fallible entities (throws === true or has THROWS tag)
+    const fallibleIds = new Set();
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        // Check kappa.throws
+        const constraints = e.constraints;
+        if (constraints && !Array.isArray(constraints) && constraints.throws) {
+            fallibleIds.add(e.id);
+            continue;
+        }
+        // Check tau.self.fallible
+        const traits = e.traits;
+        if (traits && !Array.isArray(traits) && traits.self?.fallible) {
+            fallibleIds.add(e.id);
+            continue;
+        }
+        // Check for network/db side effects (implicitly fallible)
+        if (constraints && !Array.isArray(constraints) && Array.isArray(constraints.sideEffects)) {
+            const effects = constraints.sideEffects;
+            if (effects.some((s) => s === 'network' || s === 'db' || s === 'database' || s === 'filesystem' || s === 'fs')) {
+                fallibleIds.add(e.id);
+            }
+        }
+    }
+    // Find callers of fallible entities that lack error handling
+    const gaps = [];
+    for (const fallibleId of fallibleIds) {
+        const callerSet = g.callers.get(fallibleId);
+        if (!callerSet)
+            continue;
+        const fallibleEntity = g.entityById.get(fallibleId);
+        if (!fallibleEntity)
+            continue;
+        for (const callerId of callerSet) {
+            const callerEntity = g.entityById.get(callerId);
+            if (!callerEntity)
+                continue;
+            // Check if caller has error handling
+            const callerConstraints = callerEntity.constraints;
+            const hasErrorHandling = callerConstraints && !Array.isArray(callerConstraints) &&
+                callerConstraints.errorHandling &&
+                (callerConstraints.errorHandling.tryCatch || callerConstraints.errorHandling.catchClause);
+            if (!hasErrorHandling) {
+                gaps.push({
+                    caller: entitySummary(callerEntity),
+                    fallibleCallee: entitySummary(fallibleEntity),
+                    issue: 'Calls fallible function without try/catch',
+                });
+            }
+        }
+    }
+    return {
+        totalFallible: fallibleIds.size,
+        errorGaps: gaps.length,
+        gaps: gaps.slice(0, 100),
+    };
+}
+// ─── Functor 6: get_test_coverage ────────────────────────────────
+export function getTestCoverage(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const { weight_by_blast_radius = false } = args;
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    const entities = loader.getEntities(args.project);
+    // Partition into test and non-test entities
+    const testIds = new Set();
+    const productionEntities = [];
+    for (const e of entities) {
+        if (!e.id)
+            continue;
+        if (entityLayer(e) === 'test') {
+            testIds.add(e.id);
+        }
+        else {
+            productionEntities.push(e);
+        }
+    }
+    // BFS from test entities through callees to find what they exercise
+    const exercised = new Set();
+    const queue = [...testIds];
+    const visited = new Set(testIds);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const calleeSet = g.callees.get(current);
+        if (!calleeSet)
+            continue;
+        for (const calleeId of calleeSet) {
+            if (!visited.has(calleeId)) {
+                visited.add(calleeId);
+                if (!testIds.has(calleeId)) {
+                    exercised.add(calleeId);
+                }
+                queue.push(calleeId);
+            }
+        }
+    }
+    const covered = productionEntities.filter(e => exercised.has(e.id));
+    const uncovered = productionEntities.filter(e => !exercised.has(e.id));
+    const result = {
+        totalProduction: productionEntities.length,
+        totalTests: testIds.size,
+        coveredCount: covered.length,
+        uncoveredCount: uncovered.length,
+        coveragePercent: productionEntities.length > 0
+            ? Math.round((covered.length / productionEntities.length) * 1000) / 10
+            : 0,
+    };
+    if (weight_by_blast_radius && uncovered.length > 0) {
+        // Compute blast radius for each uncovered entity to prioritize what to test
+        const prioritized = uncovered
+            .map(e => {
+            const br = computeBlastRadius(g, new Set([e.id]));
+            return {
+                ...entitySummary(e),
+                blastRadius: br.affected.length,
+            };
+        })
+            .sort((a, b) => b.blastRadius - a.blastRadius);
+        result.uncoveredByPriority = prioritized.slice(0, 50);
+    }
+    else {
+        // Group uncovered by layer
+        const byLayer = new Map();
+        for (const e of uncovered) {
+            const l = entityLayer(e);
+            byLayer.set(l, (byLayer.get(l) || 0) + 1);
+        }
+        result.uncoveredByLayer = Object.fromEntries([...byLayer.entries()].sort((a, b) => b[1] - a[1]));
+        result.uncovered = uncovered.slice(0, 50).map(entitySummary);
+    }
+    return result;
+}
+// ─── Functor 7: get_optimal_context ──────────────────────────────
+export function getOptimalContext(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const { target_entity, max_tokens = 8000, strategy = 'bfs' } = args;
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    const entity = loader.getEntityById(target_entity, args.project) || loader.getEntityByName(target_entity, args.project);
+    if (!entity) {
+        return { error: `Entity not found: ${target_entity}` };
+    }
+    const targetId = entity.id;
+    // Estimate tokens for an entity based on its dimensions
+    function estimateTokens(e) {
+        let tokens = 50; // Base: name, id, layer
+        if (e.struct && typeof e.struct !== 'string') {
+            tokens += 20; // signature
+            tokens += (e.struct.params?.length || 0) * 10;
+        }
+        if (e.edges?.calls)
+            tokens += e.edges.calls.length * 8;
+        if (e.edges?.imports)
+            tokens += e.edges.imports.length * 6;
+        if (e.data?.inputs)
+            tokens += e.data.inputs.length * 10;
+        if (e.constraints && typeof e.constraints === 'object' && !Array.isArray(e.constraints)) {
+            tokens += 30;
+        }
+        return tokens;
+    }
+    const candidates = [];
+    if (strategy === 'blast_radius') {
+        // Use blast radius to get all related entities with depth
+        const br = computeBlastRadius(g, new Set([targetId]));
+        for (const id of br.affected) {
+            if (id === targetId)
+                continue;
+            const e = g.entityById.get(id);
+            if (!e)
+                continue;
+            const depth = Math.abs(br.depthMap[id] || 99);
+            const tokens = estimateTokens(e);
+            // Relevance decays with distance; direct callers/callees are most valuable
+            const relevance = 1 / (1 + depth);
+            candidates.push({
+                entity: entitySummary(e),
+                relevance: Math.round(relevance * 1000) / 1000,
+                distance: depth,
+                direction: (br.depthMap[id] || 0) < 0 ? 'upstream' : 'downstream',
+                tokens,
+            });
+        }
+    }
+    else {
+        // BFS from target in both directions with distance tracking
+        const distances = new Map();
+        // BFS callees (downstream)
+        const downQueue = [[targetId, 0]];
+        const downVisited = new Set([targetId]);
+        while (downQueue.length > 0) {
+            const [current, d] = downQueue.shift();
+            if (d > 5)
+                continue;
+            const calleeSet = g.callees.get(current);
+            if (!calleeSet)
+                continue;
+            for (const id of calleeSet) {
+                if (!downVisited.has(id)) {
+                    downVisited.add(id);
+                    distances.set(id, { dist: d + 1, dir: 'downstream' });
+                    downQueue.push([id, d + 1]);
+                }
+            }
+        }
+        // BFS callers (upstream)
+        const upQueue = [[targetId, 0]];
+        const upVisited = new Set([targetId]);
+        while (upQueue.length > 0) {
+            const [current, d] = upQueue.shift();
+            if (d > 5)
+                continue;
+            const callerSet = g.callers.get(current);
+            if (!callerSet)
+                continue;
+            for (const id of callerSet) {
+                if (!upVisited.has(id)) {
+                    upVisited.add(id);
+                    // Only override if not already found with shorter distance
+                    if (!distances.has(id) || distances.get(id).dist > d + 1) {
+                        distances.set(id, { dist: d + 1, dir: 'upstream' });
+                    }
+                    upQueue.push([id, d + 1]);
+                }
+            }
+        }
+        for (const [id, { dist, dir }] of distances) {
+            const e = g.entityById.get(id);
+            if (!e)
+                continue;
+            const tokens = estimateTokens(e);
+            const relevance = 1 / (1 + dist);
+            candidates.push({
+                entity: entitySummary(e),
+                relevance: Math.round(relevance * 1000) / 1000,
+                distance: dist,
+                direction: dir,
+                tokens,
+            });
+        }
+    }
+    // Greedy knapsack: sort by relevance/token ratio, fill until budget
+    candidates.sort((a, b) => (b.relevance / b.tokens) - (a.relevance / a.tokens));
+    const selected = [];
+    const targetTokens = estimateTokens(entity);
+    let usedTokens = targetTokens; // Reserve space for the target itself
+    for (const candidate of candidates) {
+        if (usedTokens + candidate.tokens > max_tokens)
+            continue;
+        selected.push(candidate);
+        usedTokens += candidate.tokens;
+    }
+    return {
+        target: {
+            ...entitySummary(entity),
+            tokens: targetTokens,
+        },
+        maxTokens: max_tokens,
+        usedTokens,
+        contextEntities: selected.length,
+        totalCandidates: candidates.length,
+        context: selected,
+    };
+}

package/dist/tools/index.d.ts

@@ -3,10 +3,33 @@
  *
  * Each tool exposes a dimension or computation over the 9D JSTF-T coordinate space.
  * Tools operate on the in-memory entity bundle loaded from .seshat/_bundle.json.
+ *
+ * Multi-project: when multiple projects are loaded, each tool accepts an optional
+ * `project` parameter. In multi-project mode, `project` is required.
+ */
+import type { JstfEntity } from '../types.js';
+import { MultiLoader } from '../loader.js';
+import { type CallGraph } from '../graph.js';
+export declare function initTools(multiLoader: MultiLoader): void;
+export declare function getLoader(): MultiLoader;
+export declare function getGraph(project?: string): CallGraph;
+/**
+ * Validate project param. Returns error string if invalid, null if OK.
+ * In single-project mode, project is optional (defaults to the only project).
+ * In multi-project mode, project is required.
  */
-import { BundleLoader } from '../loader.js';
-export declare function initTools(bundleLoader: BundleLoader): void;
+export declare function validateProject(project?: string): string | null;
+export declare function entityName(e: JstfEntity): string;
+export declare function entityLayer(e: JstfEntity): string;
+export declare function entitySummary(e: JstfEntity): Record<string, unknown>;
+export declare function normalizeConstraints(constraints: JstfEntity['constraints']): string[];
+/**
+ * Deep search constraints — matches against raw constraint object fields too,
+ * not just normalized tags.
+ */
+export declare function constraintMatches(constraints: JstfEntity['constraints'], target: string): boolean;
 export declare function queryEntities(args: {
+    project?: string;
     query?: string;
     layer?: string;
     module?: string;
@@ -15,22 +38,31 @@ export declare function queryEntities(args: {
 }): unknown;
 export declare function getEntity(args: {
     id: string;
+    project?: string;
 }): unknown;
 export declare function getDependencies(args: {
     entity_id: string;
     direction?: 'callers' | 'callees' | 'both';
     depth?: number;
+    project?: string;
 }): unknown;
+export declare function collectTransitive(adjacency: Map<string, Set<string>>, startId: string, maxDepth: number): string[];
 export declare function getDataFlow(args: {
     entity_id: string;
+    project?: string;
 }): unknown;
 export declare function findByConstraint(args: {
     constraint: string;
+    project?: string;
 }): unknown;
 export declare function getBlastRadius(args: {
     entity_ids: string[];
+    project?: string;
 }): unknown;
 export declare function listModules(args: {
     group_by?: 'layer' | 'module' | 'file' | 'language';
+    project?: string;
+}): unknown;
+export declare function getTopology(args?: {
+    project?: string;
 }): unknown;
-export declare function getTopology(): unknown;