@papyruslabsai/seshat-mcp 0.4.1 → 0.6.0

package/dist/tools/functors.js

@@ -1,9 +1,9 @@
 /**
- * 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 { computeBlastRadius } from '../graph.js';
 import { getLoader, getGraph, validateProject, entityLayer, entitySummary, } from './index.js';
@@ -25,7 +25,7 @@ const LAYER_ORDER = {
 /**
  * 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 function estimateTokens(e) {
     // Use real source token count from extraction pipeline
@@ -33,7 +33,7 @@ export function estimateTokens(e) {
     const st = raw.sourceTokens;
     if (st?.estimated)
         return st.estimated;
-    // Fallback: heuristic from 9D coordinates (pre-v0.3.2 bundles)
+    // Fallback: heuristic estimation (pre-v0.3.2 bundles)
     let tokens = 50; // Base: name, id, layer
     if (e.struct && typeof e.struct !== 'string') {
         tokens += 20; // signature
@@ -53,7 +53,7 @@ export function estimateTokens(e) {
 /**
  * Detect which estimator was used for an entity.
  * Returns 'syntactic' if tree-sitter leaf node count was used,
- * 'charDiv4' if chars/4 heuristic was used, 'heuristic' for 9D fallback.
+ * 'charDiv4' if chars/4 heuristic was used, 'heuristic' for legacy fallback.
  */
 function detectEstimator(e) {
     const raw = e;
@@ -80,7 +80,7 @@ function dominantEstimator(entities) {
         return 'charDiv4';
     return 'heuristic';
 }
-// ─── Functor 1: find_dead_code ───────────────────────────────────
+// ─── Tool: find_dead_code ────────────────────────────────────────
 export function findDeadCode(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -150,7 +150,7 @@ export function findDeadCode(args) {
         dead: deadEntities.slice(0, 100).map(entitySummary),
     };
 }
-// ─── Functor 2: find_layer_violations ────────────────────────────
+// ─── Tool: find_layer_violations ─────────────────────────────────
 export function findLayerViolations(args) {
     const projErr = validateProject(args?.project);
     if (projErr)
@@ -206,7 +206,7 @@ export function findLayerViolations(args) {
         violations: violations.slice(0, 100),
     };
 }
-// ─── Functor 3: get_coupling_metrics ─────────────────────────────
+// ─── Tool: get_coupling_metrics ──────────────────────────────────
 export function getCouplingMetrics(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -278,7 +278,7 @@ export function getCouplingMetrics(args) {
         metrics: metrics.slice(0, 50),
     };
 }
-// ─── Functor 4: get_auth_matrix ──────────────────────────────────
+// ─── Tool: get_auth_matrix ───────────────────────────────────────
 export function getAuthMatrix(args) {
     const projErr = validateProject(args?.project);
     if (projErr)
@@ -336,7 +336,7 @@ export function getAuthMatrix(args) {
         issues: inconsistencies.slice(0, 50),
     };
 }
-// ─── Functor 5: find_error_gaps ──────────────────────────────────
+// ─── Tool: find_error_gaps ───────────────────────────────────────
 export function findErrorGaps(args) {
     const projErr = validateProject(args?.project);
     if (projErr)
@@ -349,13 +349,13 @@ export function findErrorGaps(args) {
     for (const e of entities) {
         if (!e.id)
             continue;
-        // Check kappa.throws
+        // Check constraints.throws
         const constraints = e.constraints;
         if (constraints && !Array.isArray(constraints) && constraints.throws) {
             fallibleIds.add(e.id);
             continue;
         }
-        // Check tau.self.fallible
+        // Check traits.self.fallible
         const traits = e.traits;
         if (traits && !Array.isArray(traits) && traits.self?.fallible) {
             fallibleIds.add(e.id);
@@ -403,7 +403,7 @@ export function findErrorGaps(args) {
         gaps: gaps.slice(0, 100),
     };
 }
-// ─── Functor 6: get_test_coverage ────────────────────────────────
+// ─── Tool: get_test_coverage ─────────────────────────────────────
 export function getTestCoverage(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -482,7 +482,7 @@ export function getTestCoverage(args) {
     }
     return result;
 }
-// ─── Functor 7: get_optimal_context ──────────────────────────────
+// ─── Tool: get_optimal_context ───────────────────────────────────
 export function getOptimalContext(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -598,7 +598,7 @@ export function getOptimalContext(args) {
         context: selected,
     };
 }
-// ─── Functor 8: estimate_task_cost ───────────────────────────────
+// ─── Tool: estimate_task_cost ────────────────────────────────────
 /**
  * Estimate token cost of a code change BEFORE starting work.
  * Computes blast radius, sums source token counts, and projects total burn.
@@ -763,7 +763,7 @@ export async function estimateTaskCost(args) {
     }
     return result;
 }
-// ─── Functor 9: report_actual_burn ───────────────────────────────
+// ─── Tool: report_actual_burn ────────────────────────────────────
 /**
  * Close the calibration feedback loop by reporting actual token usage
  * against a prior prediction from estimate_task_cost.
@@ -866,3 +866,129 @@ export async function reportActualBurn(args) {
         _summary: `Prediction ${updated.id.slice(0, 8)}… closed. Predicted ${updated.predicted_total} tokens, actual ${updated.actual_total_tokens} tokens. Drift: ${updated.drift_ratio != null ? `${(updated.drift_ratio * 100).toFixed(1)}%` : 'N/A'}.`,
     };
 }
+// ─── Tool: find_runtime_violations (ρ Dimension) ─────────────────
+export function find_runtime_violations(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 callerFramework = callerEntity.runtime?.framework || 'agnostic';
+        for (const calleeId of calleeIds) {
+            const calleeEntity = g.entityById.get(calleeId);
+            if (!calleeEntity)
+                continue;
+            const calleeFramework = calleeEntity.runtime?.framework;
+            // If caller is framework-agnostic but calls framework-specific code (e.g., pure logic calling React)
+            if (callerFramework === 'agnostic' && calleeFramework && calleeFramework !== 'agnostic') {
+                violations.push({
+                    caller: { ...entitySummary(callerEntity), framework: callerFramework },
+                    callee: { ...entitySummary(calleeEntity), framework: calleeFramework },
+                    issue: `Framework leak: Agnostic caller depends on ${calleeFramework}-specific callee`,
+                });
+            }
+            // If mixing frameworks directly (e.g., Vue calling React)
+            if (callerFramework !== 'agnostic' && calleeFramework && calleeFramework !== 'agnostic' && callerFramework !== calleeFramework) {
+                violations.push({
+                    caller: { ...entitySummary(callerEntity), framework: callerFramework },
+                    callee: { ...entitySummary(calleeEntity), framework: calleeFramework },
+                    issue: `Cross-framework boundary: ${callerFramework} calling ${calleeFramework}`,
+                });
+            }
+        }
+    }
+    return {
+        totalViolations: violations.length,
+        _summary: `Found ${violations.length} runtime/framework boundary violations (ρ dimension)`,
+        violations: violations.slice(0, 100),
+    };
+}
+// ─── Tool: find_ownership_violations (λ Dimension) ───────────────
+export function find_ownership_violations(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args?.project);
+    const violations = [];
+    for (const e of entities) {
+        if (!e.ownership || Object.keys(e.ownership).length === 0)
+            continue;
+        // We look for 'unsafe', 'escapes', 'mutates_borrowed', or complex lifetime constraints
+        const own = e.ownership;
+        if (own.unsafe) {
+            violations.push({
+                entity: entitySummary(e),
+                ownership_details: own,
+                issue: 'Unsafe memory access or pointer manipulation flagged',
+            });
+        }
+        else if (own.escapes) {
+            violations.push({
+                entity: entitySummary(e),
+                ownership_details: own,
+                issue: 'Value potentially escapes its lifetime boundary',
+            });
+        }
+        else if (own.mutates_borrowed) {
+            violations.push({
+                entity: entitySummary(e),
+                ownership_details: own,
+                issue: 'Attempts to mutate an immutably borrowed reference',
+            });
+        }
+    }
+    return {
+        totalViolations: violations.length,
+        _summary: `Found ${violations.length} entities with strict/violating ownership constraints (λ dimension)`,
+        violations: violations.slice(0, 100),
+    };
+}
+// ─── Tool: query_traits (τ Dimension) ────────────────────────────
+export function query_traits(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const target = args.trait.toLowerCase();
+    const loader = getLoader();
+    const entities = loader.getEntities(args.project);
+    const results = entities.filter(e => {
+        if (!e.traits)
+            return false;
+        // Handle array of strings [ 'asyncContext', 'generator' ]
+        if (Array.isArray(e.traits)) {
+            return e.traits.some(t => t.toLowerCase().includes(target));
+        }
+        // Handle structured traits { self: { fallible: true } }
+        if (typeof e.traits === 'object') {
+            const tr = e.traits;
+            if (tr.self && typeof tr.self === 'object') {
+                const selfTraits = tr.self;
+                for (const [key, val] of Object.entries(selfTraits)) {
+                    if (key.toLowerCase().includes(target) && val === true)
+                        return true;
+                }
+            }
+            if (tr.params && typeof tr.params === 'object') {
+                const paramTraits = tr.params;
+                for (const p of Object.values(paramTraits)) {
+                    if (p.bounds && Array.isArray(p.bounds) && p.bounds.some((b) => b.toLowerCase().includes(target)))
+                        return true;
+                    if (p.markers && Array.isArray(p.markers) && p.markers.some((m) => m.toLowerCase().includes(target)))
+                        return true;
+                }
+            }
+        }
+        return false;
+    });
+    return {
+        trait: args.trait,
+        total: results.length,
+        _summary: `Found ${results.length} entities implementing the '${args.trait}' trait (τ dimension)`,
+        entities: results.slice(0, 100).map(entitySummary),
+    };
+}

package/dist/tools/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Semantic MCP Tool Implementations
  *
- * Each tool exposes a dimension or computation over the 9D JSTF-T coordinate space.
+ * Each tool exposes a query or computation over the extracted code entity graph.
  * 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

package/dist/tools/index.js

@@ -1,7 +1,7 @@
 /**
  * Semantic MCP Tool Implementations
  *
- * Each tool exposes a dimension or computation over the 9D JSTF-T coordinate space.
+ * Each tool exposes a query or computation over the extracted code entity graph.
  * 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
@@ -208,25 +208,21 @@ export function getEntity(args) {
     if (!entity) {
         return { error: `Entity not found: ${args.id}` };
     }
-    // Return the full 9D coordinate dump
     return {
         id: entity.id,
         name: entityName(entity),
         ...(entity._project ? { project: entity._project } : {}),
         sourceFile: entity._sourceFile,
         sourceLanguage: entity._sourceLanguage,
-        jstfFilename: entity._jstfFilename,
-        dimensions: {
-            sigma_struct: entity.struct,
-            epsilon_edges: entity.edges,
-            delta_data: entity.data,
-            kappa_constraints: entity.constraints,
-            chi_context: entity.context,
-            lambda_ownership: entity.ownership,
-            tau_traits: entity.traits,
-            rho_runtime: entity.runtime,
-            sigma_semantics: entity.semantics,
-        },
+        structure: entity.struct,
+        call_graph: entity.edges,
+        data_flow: entity.data,
+        constraints: entity.constraints,
+        context: entity.context,
+        ownership: entity.ownership,
+        type_info: entity.traits,
+        runtime: entity.runtime,
+        logic: entity.semantics,
     };
 }
 // ─── Tool: get_dependencies ───────────────────────────────────────
@@ -258,7 +254,7 @@ export function getDependencies(args) {
             return e ? entitySummary(e) : { id: cId };
         });
     }
-    // Also include direct imports from ε
+    // Also include direct imports
     if (entity.edges?.imports) {
         result.imports = entity.edges.imports;
     }

package/dist/types.d.ts

@@ -1,10 +1,9 @@
 /**
- * JSTF-T Entity — 9D Semantic Coordinate
+ * Code Entity — the core unit of analysis
  *
  * Each entity represents a code unit (function, class, module, schema)
- * positioned in the 9-dimensional semantic space 𝕁:
- *   σ (struct), ε (edges), δ (data), κ (constraints),
- *   χ (context), λ (ownership), τ (traits), ρ (runtime), Σ (semantics)
+ * with extracted properties: structure, call graph, data flow, constraints,
+ * context, ownership, type info, runtime, and logic.
  */
 export interface JstfEntity {
     id: string;
@@ -12,7 +11,11 @@ export interface JstfEntity {
     _sourceFile?: string | null;
     _sourceLanguage?: string;
     _project?: string;
-    /** σ — Structure: function shape, signature, modifiers */
+    _sourceLocation?: {
+        startLine: number;
+        endLine: number;
+    };
+    /** Structure: function shape, signature, modifiers */
     struct?: {
         name?: string;
         type?: string;
@@ -25,7 +28,7 @@ export interface JstfEntity {
         returnType?: string;
         [key: string]: unknown;
     } | string;
-    /** ε — Edges: call graph, dependencies, imports */
+    /** Call graph: dependencies, imports, callers */
     edges?: {
         calls?: Array<{
             target: string;
@@ -41,7 +44,7 @@ export interface JstfEntity {
         }>;
         [key: string]: unknown;
     };
-    /** δ — Data: data flow, sources, sinks, mutations */
+    /** Data flow: inputs, outputs, mutations */
     data?: {
         inputs?: Array<{
             name: string;
@@ -61,7 +64,7 @@ export interface JstfEntity {
         returns?: unknown[];
         [key: string]: unknown;
     };
-    /** κ — Constraints: behavioral contracts, validation, purity */
+    /** Constraints: behavioral contracts, validation, purity */
     constraints?: {
         security?: string[];
         performance?: Record<string, unknown>;
@@ -82,7 +85,7 @@ export interface JstfEntity {
         };
         [key: string]: unknown;
     } | string[];
-    /** χ — Context: architectural position, visibility, layer */
+    /** Context: architectural position, visibility, layer */
     context?: {
         layer?: string;
         layerSource?: string;
@@ -94,9 +97,9 @@ export interface JstfEntity {
         criticality?: string;
         [key: string]: unknown;
     };
-    /** λ — Ownership: memory ownership, lifetimes, borrowing */
+    /** Ownership: memory management, lifetimes, borrowing (Rust/C++) */
     ownership?: Record<string, unknown>;
-    /** τ — Traits: type capabilities, bounds, markers */
+    /** Type info: type capabilities, bounds, markers */
     traits?: string[] | {
         self?: {
             asyncContext?: boolean;
@@ -109,14 +112,14 @@ export interface JstfEntity {
         }>;
         [key: string]: unknown;
     };
-    /** ρ — Runtime: reactive model, async platform, framework */
+    /** Runtime: async model, platform, framework */
     runtime?: {
         async?: string;
         framework?: string;
         platform?: string;
         [key: string]: unknown;
     };
-    /** Σ — Semantics: operational content, normalized logic tree */
+    /** Logic: operational content, normalized logic tree */
     semantics?: unknown[];
     [key: string]: unknown;
 }

package/dist/types.js

@@ -1,9 +1,8 @@
 /**
- * JSTF-T Entity — 9D Semantic Coordinate
+ * Code Entity — the core unit of analysis
  *
  * Each entity represents a code unit (function, class, module, schema)
- * positioned in the 9-dimensional semantic space 𝕁:
- *   σ (struct), ε (edges), δ (data), κ (constraints),
- *   χ (context), λ (ownership), τ (traits), ρ (runtime), Σ (semantics)
+ * with extracted properties: structure, call graph, data flow, constraints,
+ * context, ownership, type info, runtime, and logic.
  */
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.4.1",
-  "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
+  "version": "0.6.0",
+  "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {
     "seshat-mcp": "./dist/index.js"
@@ -30,6 +30,12 @@
     "url": "https://github.com/papyruslabs-ai/seshat.git",
     "directory": "packages/seshat-mcp"
   },
-  "keywords": ["mcp", "jstf", "semantic", "code-analysis", "seshat"],
+  "keywords": [
+    "mcp",
+    "semantic",
+    "code-analysis",
+    "seshat",
+    "static-analysis"
+  ],
   "license": "MIT"
 }