@papyruslabsai/seshat-mcp 0.20.0 → 0.20.1

package/dist/graph.js

@@ -1,272 +0,0 @@
-/**
- * Call Graph Construction & Blast Radius Computation
- *
- * Computes the set of entities affected by a change:
- *   affected(e) = ancestors(e) ∪ descendants(e) ∪ {e}
- *
- * Ancestors = all transitive callers (upstream).
- * Descendants = all transitive callees (downstream).
- */
-/**
- * Local part of a (possibly file-qualified) entity id.
- * `src/rooms/participants.js#addParticipant~2` → `addParticipant`.
- */
-function localIdOf(id) {
-    const i = id.lastIndexOf('#');
-    const local = i === -1 ? id : id.slice(i + 1);
-    return local.replace(/~\d+$/, '');
-}
-function sourceFileOf(entity) {
-    return entity.sourceFile || entity._sourceFile || null;
-}
-/**
- * Build a bidirectional call graph from entities' dependency data.
- *
- * Reference resolution is identity-honest: a bare-name target resolves to the
- * unique entity with that local name, or the unique same-file match when the
- * name is ambiguous repo-wide. A reference that stays ambiguous produces NO
- * edge — first-wins matching used to silently attribute edges to whichever
- * same-named entity was indexed first.
- */
-export function buildCallGraph(entities) {
-    const callers = new Map();
-    const callees = new Map();
-    const entityById = new Map();
-    const entityByModule = new Map();
-    const byLocal = new Map(); // local name → entities
-    const bySuffix = new Map(); // last dotted segment of local → entities
-    // Index entities
-    for (const entity of entities) {
-        if (!entity.id)
-            continue;
-        entityById.set(entity.id, entity);
-        callers.set(entity.id, new Set());
-        callees.set(entity.id, new Set());
-        const local = localIdOf(entity.id);
-        if (!byLocal.has(local))
-            byLocal.set(local, []);
-        byLocal.get(local).push(entity);
-        const suffix = local.includes('.') ? local.split('.').pop() : null;
-        if (suffix) {
-            if (!bySuffix.has(suffix))
-                bySuffix.set(suffix, []);
-            bySuffix.get(suffix).push(entity);
-        }
-        if (entity.context?.module) {
-            const mod = entity.context.module;
-            if (!entityByModule.has(mod))
-                entityByModule.set(mod, []);
-            entityByModule.get(mod).push(entity);
-        }
-    }
-    /** Unique candidate, or unique same-file candidate, else null. */
-    function pick(candidates, contextFile) {
-        if (!candidates || candidates.length === 0)
-            return null;
-        if (candidates.length === 1)
-            return candidates[0];
-        if (contextFile) {
-            const same = candidates.filter(e => sourceFileOf(e) === contextFile);
-            if (same.length === 1)
-                return same[0];
-        }
-        return null;
-    }
-    const stats = { resolved: 0, ambiguous: 0, unknown: 0 };
-    /** Resolve a reference string to an entity id, with file context. */
-    function resolveRef(target, contextFile) {
-        const found = (id) => { stats.resolved++; return id; };
-        if (entityById.has(target))
-            return found(target);
-        const direct = pick(byLocal.get(target), contextFile);
-        if (direct)
-            return found(direct.id);
-        if (target.includes('.')) {
-            const dotIdx = target.indexOf('.');
-            const modulePart = target.substring(0, dotIdx);
-            const methodPart = target.substring(dotIdx + 1);
-            const moduleEntities = entityByModule.get(modulePart);
-            if (moduleEntities) {
-                const matches = moduleEntities.filter(e => {
-                    const name = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-                    return localIdOf(e.id) === methodPart || name === methodPart;
-                });
-                const m = pick(matches, contextFile);
-                if (m)
-                    return found(m.id);
-            }
-            const method = pick(byLocal.get(methodPart), contextFile);
-            if (method)
-                return found(method.id);
-        }
-        const suffixed = pick(bySuffix.get(target), contextFile);
-        if (suffixed)
-            return found(suffixed.id);
-        const hadCandidates = (byLocal.get(target)?.length || 0) + (bySuffix.get(target)?.length || 0) > 1;
-        if (hadCandidates)
-            stats.ambiguous++;
-        else
-            stats.unknown++;
-        return null;
-    }
-    // File index for import resolution: repo-relative path (sans extension) → entities
-    const byFileBase = new Map();
-    for (const entity of entities) {
-        const f = sourceFileOf(entity);
-        if (!f)
-            continue;
-        const base = f.replace(/\.[^./]+$/, '');
-        if (!byFileBase.has(base))
-            byFileBase.set(base, []);
-        byFileBase.get(base).push(entity);
-    }
-    /** `src/app.js` + `./rooms/participants.js` → `src/rooms/participants` (extensionless). */
-    function resolveRelativeImport(importerFile, source) {
-        const stack = importerFile.split('/').slice(0, -1);
-        for (const part of source.split('/')) {
-            if (part === '.' || part === '')
-                continue;
-            if (part === '..') {
-                if (stack.length === 0)
-                    return null;
-                stack.pop();
-                continue;
-            }
-            stack.push(part);
-        }
-        return stack.join('/').replace(/\.[^./]+$/, '');
-    }
-    // Build call edges from dependency data
-    for (const caller of entities) {
-        if (!caller.id || !caller.edges)
-            continue;
-        const callerFile = sourceFileOf(caller);
-        // Process direct function/method calls
-        const callsArray = caller.edges.calls;
-        if (Array.isArray(callsArray)) {
-            for (const call of callsArray) {
-                if (!call.target)
-                    continue;
-                const calleeId = resolveRef(call.target, callerFile);
-                if (calleeId && calleeId !== caller.id) {
-                    callees.get(caller.id)?.add(calleeId);
-                    callers.get(calleeId)?.add(caller.id);
-                }
-            }
-        }
-        // Process lexical imports — resolve the import PATH against the importer's
-        // file, then link each specifier to the same-named entity in the resolved
-        // file. Basename matching used to link any same-named file first-wins.
-        const importsArray = caller.edges.imports;
-        if (Array.isArray(importsArray) && callerFile) {
-            for (const imp of importsArray) {
-                const source = imp.source || imp.module;
-                if (!source || !source.startsWith('.'))
-                    continue; // package import — no repo entity
-                const resolvedBase = resolveRelativeImport(callerFile, source);
-                if (!resolvedBase)
-                    continue;
-                const targetEntities = byFileBase.get(resolvedBase) || byFileBase.get(`${resolvedBase}/index`);
-                if (!targetEntities)
-                    continue;
-                const names = (imp.specifiers || [])
-                    .map((s) => s.imported || s.local)
-                    .filter(Boolean);
-                for (const name of names) {
-                    const match = targetEntities.find(e => localIdOf(e.id) === name);
-                    if (match && match.id !== caller.id) {
-                        callees.get(caller.id)?.add(match.id);
-                        callers.get(match.id)?.add(caller.id);
-                    }
-                }
-            }
-        }
-        // Process IoC / Dynamic Dispatch (calledBy)
-        const calledByArray = caller.edges.calledBy;
-        if (Array.isArray(calledByArray)) {
-            for (const cb of calledByArray) {
-                if (!cb.source)
-                    continue;
-                // In this relationship, the current entity (`caller` in this loop
-                // context, despite the name) is actually the CALLEE, and the
-                // `source` is the true CALLER.
-                const callerId = resolveRef(cb.source, callerFile);
-                if (callerId && callerId !== caller.id) {
-                    callees.get(callerId)?.add(caller.id); // true caller calls this entity
-                    callers.get(caller.id)?.add(callerId); // this entity is called by true caller
-                }
-            }
-        }
-    }
-    return { callers, callees, entityById, resolutionStats: stats };
-}
-/**
- * Compute blast radius: all entities affected by changes to the given IDs.
- * Traverses both callers (upstream) and callees (downstream).
- */
-export function computeBlastRadius(graph, changedIds, maxDepth = 10) {
-    const ancestors = new Set();
-    const descendants = new Set();
-    const depthMap = {};
-    // BFS upstream (callers)
-    function bfsUp(startIds) {
-        const queue = [];
-        for (const id of startIds) {
-            queue.push([id, 0]);
-        }
-        const visited = new Set(startIds);
-        while (queue.length > 0) {
-            const [current, depth] = queue.shift();
-            if (depth > maxDepth)
-                continue;
-            const callerSet = graph.callers.get(current);
-            if (!callerSet)
-                continue;
-            for (const callerId of callerSet) {
-                if (!visited.has(callerId)) {
-                    visited.add(callerId);
-                    ancestors.add(callerId);
-                    depthMap[callerId] = Math.min(depthMap[callerId] ?? Infinity, -(depth + 1));
-                    queue.push([callerId, depth + 1]);
-                }
-            }
-        }
-    }
-    // BFS downstream (callees)
-    function bfsDown(startIds) {
-        const queue = [];
-        for (const id of startIds) {
-            queue.push([id, 0]);
-        }
-        const visited = new Set(startIds);
-        while (queue.length > 0) {
-            const [current, depth] = queue.shift();
-            if (depth > maxDepth)
-                continue;
-            const calleeSet = graph.callees.get(current);
-            if (!calleeSet)
-                continue;
-            for (const calleeId of calleeSet) {
-                if (!visited.has(calleeId)) {
-                    visited.add(calleeId);
-                    descendants.add(calleeId);
-                    depthMap[calleeId] = Math.min(depthMap[calleeId] ?? Infinity, depth + 1);
-                    queue.push([calleeId, depth + 1]);
-                }
-            }
-        }
-    }
-    bfsUp(changedIds);
-    bfsDown(changedIds);
-    // Mark changed entities at depth 0
-    for (const id of changedIds) {
-        depthMap[id] = 0;
-    }
-    const allAffected = new Set([...changedIds, ...ancestors, ...descendants]);
-    return {
-        affected: [...allAffected],
-        depthMap,
-        ancestors: [...ancestors],
-        descendants: [...descendants],
-    };
-}

package/dist/index.d.ts

@@ -1,9 +0,0 @@
-#!/usr/bin/env node
-/**
- * @papyruslabs/seshat-mcp — Structural Code Analysis MCP Server (Cloud Proxy)
- *
- * Declares the Seshat tool suite to Claude/AI clients. All tool calls are
- * proxied to the Ptah Cloud API. Tool descriptions are written as triggers —
- * they tell the LLM *when* to reach for each tool, not just what it does.
- */
-export {};

package/dist/loader.d.ts

@@ -1,62 +0,0 @@
-/**
- * Bundle Loader
- *
- * Discovers and loads .seshat/_bundle.json from the current working directory.
- * Falls back to checking common alternative locations.
- */
-import type { JstfEntity, Topology, Manifest, ProjectInfo, ProjectLoader } from './types.js';
-export declare class BundleLoader {
-    private entities;
-    private topology;
-    private manifest;
-    private loaded;
-    private seshatDir;
-    private bundleMtime;
-    constructor(cwd?: string);
-    /**
-     * Check if the bundle file on disk has changed since last load.
-     * If so, reload transparently. Called by all accessors.
-     */
-    private ensureFresh;
-    load(): void;
-    getEntities(): JstfEntity[];
-    getTopology(): Topology | null;
-    getManifest(): Manifest | null;
-    getEntityById(id: string): JstfEntity | undefined;
-    getEntityByName(name: string): JstfEntity | undefined;
-    isLoaded(): boolean;
-}
-/**
- * Wraps N BundleLoader instances for multi-project access.
- * In single-project mode (1 dir), behaves identically to BundleLoader.
- * In multi-project mode, `project` param is required on all accessors.
- */
-export declare class MultiLoader implements ProjectLoader {
-    private projects;
-    private projectPaths;
-    private projectEntities;
-    private loaded;
-    private dirs;
-    constructor(projectDirs: string[]);
-    load(): void;
-    private loadProject;
-    /** Get the resolved project name when only one project is loaded. */
-    private defaultProject;
-    private resolveProject;
-    getEntities(project?: string): JstfEntity[];
-    getTopology(project?: string): Topology | null;
-    getManifest(project?: string): Manifest | null;
-    getEntityById(id: string, project?: string): JstfEntity | undefined;
-    getEntityByName(name: string, project?: string): JstfEntity | undefined;
-    getProjectNames(): string[];
-    getProjectInfo(): ProjectInfo[];
-    isMultiProject(): boolean;
-    isLoaded(): boolean;
-    hasProject(name: string): boolean;
-    /**
-     * Register a virtual entity in memory.
-     * Used for Phase 1/2 of the Harness to reason about entities that haven't been written to disk yet.
-     */
-    registerVirtualEntity(entity: JstfEntity, project?: string): void;
-    totalEntities(): number;
-}

package/dist/loader.js

@@ -1,264 +0,0 @@
-/**
- * Bundle Loader
- *
- * Discovers and loads .seshat/_bundle.json from the current working directory.
- * Falls back to checking common alternative locations.
- */
-import fs from 'fs';
-import path from 'path';
-export class BundleLoader {
-    entities = [];
-    topology = null;
-    manifest = null;
-    loaded = false;
-    seshatDir;
-    bundleMtime = 0;
-    constructor(cwd) {
-        const root = cwd || process.cwd();
-        this.seshatDir = path.join(root, '.seshat');
-    }
-    /**
-     * Check if the bundle file on disk has changed since last load.
-     * If so, reload transparently. Called by all accessors.
-     */
-    ensureFresh() {
-        if (!this.loaded) {
-            this.load();
-            return;
-        }
-        const bundlePath = path.join(this.seshatDir, '_bundle.json');
-        try {
-            const currentMtime = fs.statSync(bundlePath).mtimeMs;
-            if (currentMtime !== this.bundleMtime) {
-                process.stderr.write(`[seshat] Bundle changed on disk, reloading…\n`);
-                this.load();
-            }
-        }
-        catch {
-            // File may have been deleted — keep stale data rather than crash
-        }
-    }
-    load() {
-        const bundlePath = path.join(this.seshatDir, '_bundle.json');
-        if (!fs.existsSync(bundlePath)) {
-            throw new Error(`No .seshat/_bundle.json found in ${path.dirname(this.seshatDir)}.\n` +
-                `Run the Seshat extraction pipeline first:\n` +
-                `  node ci/extract-and-generate.mjs <repo-path> .seshat <project-name>\n` +
-                `Or add the CI workflow to auto-generate on push to main.`);
-        }
-        this.bundleMtime = fs.statSync(bundlePath).mtimeMs;
-        const raw = fs.readFileSync(bundlePath, 'utf-8');
-        const bundle = JSON.parse(raw);
-        this.entities = bundle.entities || [];
-        // Remap bundle field names to internal _ prefixed names.
-        // The extraction pipeline outputs `sourceFile`, `sourceLanguage`
-        // but the entity type expects `_sourceFile`, `_sourceLanguage`.
-        for (const e of this.entities) {
-            const raw = e;
-            if (raw.sourceFile && !e._sourceFile) {
-                e._sourceFile = raw.sourceFile;
-            }
-            if (raw.sourceLanguage && !e._sourceLanguage) {
-                e._sourceLanguage = raw.sourceLanguage;
-            }
-        }
-        // Load topology if available
-        const topoPath = path.join(this.seshatDir, '_topology.json');
-        if (fs.existsSync(topoPath)) {
-            this.topology = JSON.parse(fs.readFileSync(topoPath, 'utf-8'));
-        }
-        // Load manifest if available
-        const manifestPath = path.join(this.seshatDir, 'manifest.json');
-        if (fs.existsSync(manifestPath)) {
-            this.manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-        }
-        this.loaded = true;
-    }
-    getEntities() {
-        this.ensureFresh();
-        return this.entities;
-    }
-    getTopology() {
-        this.ensureFresh();
-        return this.topology;
-    }
-    getManifest() {
-        this.ensureFresh();
-        return this.manifest;
-    }
-    getEntityById(id) {
-        return this.getEntities().find(e => e.id === id);
-    }
-    getEntityByName(name) {
-        return this.getEntities().find(e => {
-            const structName = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-            return e.id === name || localIdOfRef(e.id) === name || structName === name;
-        });
-    }
-    isLoaded() {
-        return this.loaded;
-    }
-}
-/** Local part of a (possibly file-qualified) entity id. */
-function localIdOfRef(id) {
-    const i = id.lastIndexOf('#');
-    const local = i === -1 ? id : id.slice(i + 1);
-    return local.replace(/~\d+$/, '');
-}
-// ─── Multi-Project Loader ─────────────────────────────────────────
-/**
- * Wraps N BundleLoader instances for multi-project access.
- * In single-project mode (1 dir), behaves identically to BundleLoader.
- * In multi-project mode, `project` param is required on all accessors.
- */
-export class MultiLoader {
-    projects = new Map();
-    projectPaths = new Map();
-    projectEntities = new Map();
-    loaded = false;
-    dirs;
-    constructor(projectDirs) {
-        this.dirs = projectDirs.length > 0 ? projectDirs : [process.cwd()];
-    }
-    load() {
-        for (const dir of this.dirs) {
-            this.loadProject(dir);
-        }
-        this.loaded = true;
-    }
-    loadProject(dir) {
-        const loader = new BundleLoader(dir);
-        try {
-            loader.load();
-            const manifest = loader.getManifest();
-            const name = manifest?.projectName || path.basename(dir);
-            this.projects.set(name, loader);
-            this.projectPaths.set(name, dir);
-            // Stamp entities with _project
-            const entities = loader.getEntities();
-            for (const e of entities) {
-                e._project = name;
-            }
-            this.projectEntities.set(name, entities);
-        }
-        catch (err) {
-            process.stderr.write(`Warning: Skipping ${dir}: ${err.message}\n`);
-        }
-    }
-    /** Get the resolved project name when only one project is loaded. */
-    defaultProject() {
-        if (this.projects.size === 1)
-            return [...this.projects.keys()][0];
-        return undefined;
-    }
-    resolveProject(project) {
-        return project || this.defaultProject();
-    }
-    getEntities(project) {
-        if (!this.loaded)
-            this.load();
-        const p = this.resolveProject(project);
-        if (!p)
-            return [];
-        // Delegate to BundleLoader (which checks mtime via ensureFresh),
-        // then re-stamp and cache if the reference changed.
-        const loader = this.projects.get(p);
-        if (!loader)
-            return [];
-        const fresh = loader.getEntities();
-        const cached = this.projectEntities.get(p);
-        if (fresh !== cached) {
-            for (const e of fresh) {
-                e._project = p;
-            }
-            this.projectEntities.set(p, fresh);
-        }
-        return fresh;
-    }
-    getTopology(project) {
-        if (!this.loaded)
-            this.load();
-        const p = this.resolveProject(project);
-        if (p)
-            return this.projects.get(p)?.getTopology() || null;
-        return null;
-    }
-    getManifest(project) {
-        if (!this.loaded)
-            this.load();
-        const p = this.resolveProject(project);
-        if (p)
-            return this.projects.get(p)?.getManifest() || null;
-        return null;
-    }
-    getEntityById(id, project) {
-        return this.getEntities(project).find(e => e.id === id);
-    }
-    getEntityByName(name, project) {
-        return this.getEntities(project).find(e => {
-            const structName = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-            return e.id === name || localIdOfRef(e.id) === name || structName === name;
-        });
-    }
-    getProjectNames() {
-        if (!this.loaded)
-            this.load();
-        return [...this.projects.keys()];
-    }
-    getProjectInfo() {
-        if (!this.loaded)
-            this.load();
-        const result = [];
-        for (const [name, loader] of this.projects) {
-            const manifest = loader.getManifest();
-            result.push({
-                name,
-                path: this.projectPaths.get(name) || '',
-                entityCount: loader.getEntities().length,
-                languages: manifest?.languages || [],
-                commitSha: manifest?.commitSha || '',
-                extractedAt: manifest?.extractedAt || '',
-                layers: manifest?.layers || {},
-            });
-        }
-        return result;
-    }
-    isMultiProject() {
-        return this.projects.size > 1;
-    }
-    isLoaded() {
-        return this.loaded && this.projects.size > 0;
-    }
-    hasProject(name) {
-        return this.projects.has(name);
-    }
-    /**
-     * Register a virtual entity in memory.
-     * Used for Phase 1/2 of the Harness to reason about entities that haven't been written to disk yet.
-     */
-    registerVirtualEntity(entity, project) {
-        if (!this.loaded)
-            this.load();
-        const p = this.resolveProject(project);
-        if (!p)
-            return;
-        const entities = this.projectEntities.get(p) || [];
-        entity._project = p;
-        // If entity already exists, update it, otherwise append
-        const existingIdx = entities.findIndex(e => e.id === entity.id);
-        if (existingIdx !== -1) {
-            entities[existingIdx] = { ...entities[existingIdx], ...entity };
-        }
-        else {
-            entities.push(entity);
-        }
-        this.projectEntities.set(p, entities);
-    }
-    totalEntities() {
-        let total = 0;
-        for (const entities of this.projectEntities.values()) {
-            total += entities.length;
-        }
-        return total;
-    }
-}