feat(affinescript-mcp): expand cartridge from 7 to 12 tools — add lint, compile, hover, goto-def, complete

hyperpolymath · claude · hyperpolymath · commit a0d7543614b8 · 2026-04-11T23:57:12.000+01:00
- affinescript_lint: lint --json, returns structured diagnostic report
- affinescript_compile: compile --json with wasm/wasm-gc/julia target selection
- affinescript_hover: hover FILE LINE COL, returns JSON symbol info
- affinescript_goto_def: goto-def FILE LINE COL, returns definition location
- affinescript_complete: complete FILE LINE COL, returns JSON completion array
- affinescript_check: upgraded to --json mode (structured stderr, not regex-scraped)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/cartridges/affinescript-mcp/cartridge.json b/cartridges/affinescript-mcp/cartridge.json
@@ -4,7 +4,7 @@
   "copyright": "Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)",
   "name": "affinescript-mcp",
   "version": "0.1.0",
-  "description": "AffineScript language cartridge -- type checking, parsing, formatting, error explanation, stdlib browsing, and syntax reference for the AffineScript language (substructural type system with affine/linear types, algebraic effects)",
+  "description": "AffineScript language cartridge -- type checking, parsing, formatting, linting, compiling, hover/goto-def/completion queries, error explanation, stdlib browsing, and syntax reference for the AffineScript language (substructural type system with affine/linear types, algebraic effects)",
   "domain": "Languages",
   "tier": "Ayo",
   "protocols": ["MCP", "REST"],
@@ -20,7 +20,7 @@
   "tools": [
     {
       "name": "affinescript_check",
-      "description": "Type-check AffineScript source code and return diagnostics (errors, warnings, hints). Invokes the compiler's check mode.",
+      "description": "Type-check AffineScript source code and return structured JSON diagnostics (errors, warnings, hints). Invokes the compiler's check mode with --json output.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -98,6 +98,70 @@
         },
         "required": ["source"]
       }
+    },
+    {
+      "name": "affinescript_lint",
+      "description": "Lint AffineScript source code for code quality issues (naming conventions, dead code, style). Returns structured JSON diagnostics.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source": { "type": "string", "description": "AffineScript source code to lint" },
+          "filename": { "type": "string", "description": "Virtual filename for diagnostic reporting (default: input.as)" }
+        },
+        "required": ["source"]
+      }
+    },
+    {
+      "name": "affinescript_compile",
+      "description": "Compile AffineScript source to a target (wasm, wasm-gc, julia). Returns structured JSON diagnostics and reports whether compilation succeeded.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source": { "type": "string", "description": "AffineScript source code to compile" },
+          "target": { "type": "string", "description": "Compilation target: 'wasm' (default), 'wasm-gc', or 'julia'" },
+          "filename": { "type": "string", "description": "Virtual filename for diagnostic reporting (default: input.as)" }
+        },
+        "required": ["source"]
+      }
+    },
+    {
+      "name": "affinescript_hover",
+      "description": "Return type and symbol information for the symbol at a cursor position in AffineScript source code. Runs the full pipeline (parse → resolve → typecheck) and returns JSON hover info.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source": { "type": "string", "description": "AffineScript source code" },
+          "line": { "type": "number", "description": "1-based line number" },
+          "col": { "type": "number", "description": "1-based column number" }
+        },
+        "required": ["source", "line", "col"]
+      }
+    },
+    {
+      "name": "affinescript_goto_def",
+      "description": "Return the definition location of the symbol at a cursor position in AffineScript source code. Returns JSON with file, line, and column of the definition site.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source": { "type": "string", "description": "AffineScript source code" },
+          "line": { "type": "number", "description": "1-based line number" },
+          "col": { "type": "number", "description": "1-based column number" }
+        },
+        "required": ["source", "line", "col"]
+      }
+    },
+    {
+      "name": "affinescript_complete",
+      "description": "Return completion candidates at a cursor position in AffineScript source code. Returns a JSON array of items with name, kind, type, and detail fields.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source": { "type": "string", "description": "AffineScript source code" },
+          "line": { "type": "number", "description": "1-based line number" },
+          "col": { "type": "number", "description": "1-based column number" }
+        },
+        "required": ["source", "line", "col"]
+      }
     }
   ]
 }
diff --git a/cartridges/affinescript-mcp/mod.js b/cartridges/affinescript-mcp/mod.js
@@ -4,12 +4,17 @@
 // affinescript-mcp/mod.js -- AffineScript language cartridge implementation.
 //
 // Provides MCP tool handlers for AffineScript compiler operations:
-//   - Type checking (via local `affinescript check`)
-//   - Parsing (via `affinescript parse`)
-//   - Formatting (built-in indentation formatter)
-//   - Error code explanation (static lookup)
+//   - Type checking    (via `affinescript check --json`)
+//   - Parsing          (via `affinescript parse`)
+//   - Formatting       (built-in indentation formatter)
+//   - Linting          (via `affinescript lint --json`)
+//   - Compilation      (via `affinescript compile --json`)
+//   - Hover            (via `affinescript hover FILE LINE COL`)
+//   - Goto-definition  (via `affinescript goto-def FILE LINE COL`)
+//   - Completion       (via `affinescript complete FILE LINE COL`)
+//   - Error explanation  (static lookup)
 //   - Standard library browsing (static reference)
-//   - Syntax reference (static lookup)
+//   - Syntax reference   (static lookup)
 //   - Snippet evaluation (via `affinescript eval`)
 //
 // Auth: None required — local compiler invocation.
@@ -184,20 +189,24 @@ export async function handleTool(toolName, args) {
     case "affinescript_check": {
       if (!args.source) return { error: "Missing required field: source" };
 
-      const filename = args.filename || "input.as";
       const tmpFile = `/tmp/boj_afs_${crypto.randomUUID()}.as`;
 
       try {
         await Deno.writeTextFile(tmpFile, args.source);
-        const result = await runCompiler(["check", tmpFile], null);
+        // --json emits a structured JSON object on stderr
+        const result = await runCompiler(["check", "--json", tmpFile], null);
+
+        let report;
+        try {
+          report = JSON.parse(result.stderr.trim());
+        } catch {
+          // Fallback: compiler stderr was not JSON (unexpected)
+          report = { success: result.exitCode === 0, diagnostics: [], raw: result.stderr };
+        }
 
         return {
           status: result.exitCode === 0 ? 200 : 422,
-          data: {
-            success: result.exitCode === 0,
-            diagnostics: parseDiagnostics(result.stderr, filename),
-            stdout: result.stdout || undefined,
-          },
+          data: report,
         };
       } finally {
         try { await Deno.remove(tmpFile); } catch { /* ignore */ }
@@ -366,6 +375,167 @@ export async function handleTool(toolName, args) {
       }
     }
 
+    // --- Linting ---
+
+    case "affinescript_lint": {
+      if (!args.source) return { error: "Missing required field: source" };
+
+      const tmpFile = `/tmp/boj_afs_${crypto.randomUUID()}.as`;
+
+      try {
+        await Deno.writeTextFile(tmpFile, args.source);
+        const result = await runCompiler(["lint", "--json", tmpFile], null);
+
+        let report;
+        try {
+          report = JSON.parse(result.stderr.trim());
+        } catch {
+          report = { success: result.exitCode === 0, diagnostics: [], raw: result.stderr };
+        }
+
+        return {
+          status: result.exitCode === 0 ? 200 : 422,
+          data: report,
+        };
+      } finally {
+        try { await Deno.remove(tmpFile); } catch { /* ignore */ }
+      }
+    }
+
+    // --- Compilation ---
+
+    case "affinescript_compile": {
+      if (!args.source) return { error: "Missing required field: source" };
+
+      const target = args.target || "wasm";
+      const tmpSrc = `/tmp/boj_afs_${crypto.randomUUID()}.as`;
+      const ext = target === "julia" ? "jl" : "wasm";
+      const tmpOut = `/tmp/boj_afs_out_${crypto.randomUUID()}.${ext}`;
+
+      const compileArgs = ["compile", "--json"];
+      if (target === "wasm-gc") compileArgs.push("--wasm-gc");
+      compileArgs.push("-o", tmpOut, tmpSrc);
+
+      try {
+        await Deno.writeTextFile(tmpSrc, args.source);
+        const result = await runCompiler(compileArgs, null);
+
+        let report;
+        try {
+          report = JSON.parse(result.stderr.trim());
+        } catch {
+          report = { success: result.exitCode === 0, diagnostics: [], raw: result.stderr };
+        }
+
+        return {
+          status: result.exitCode === 0 ? 200 : 422,
+          data: { ...report, target },
+        };
+      } finally {
+        try { await Deno.remove(tmpSrc); } catch { /* ignore */ }
+        try { await Deno.remove(tmpOut); } catch { /* ignore */ }
+      }
+    }
+
+    // --- Hover ---
+
+    case "affinescript_hover": {
+      if (!args.source) return { error: "Missing required field: source" };
+      if (args.line == null) return { error: "Missing required field: line" };
+      if (args.col == null) return { error: "Missing required field: col" };
+
+      const tmpFile = `/tmp/boj_afs_${crypto.randomUUID()}.as`;
+
+      try {
+        await Deno.writeTextFile(tmpFile, args.source);
+        // hover outputs JSON on stdout; line/col are 1-based
+        const result = await runCompiler(
+          ["hover", tmpFile, String(args.line), String(args.col)],
+          null
+        );
+
+        let info;
+        try {
+          info = JSON.parse(result.stdout.trim());
+        } catch {
+          info = { found: false, raw: result.stdout };
+        }
+
+        return {
+          status: 200,
+          data: info,
+        };
+      } finally {
+        try { await Deno.remove(tmpFile); } catch { /* ignore */ }
+      }
+    }
+
+    // --- Goto-definition ---
+
+    case "affinescript_goto_def": {
+      if (!args.source) return { error: "Missing required field: source" };
+      if (args.line == null) return { error: "Missing required field: line" };
+      if (args.col == null) return { error: "Missing required field: col" };
+
+      const tmpFile = `/tmp/boj_afs_${crypto.randomUUID()}.as`;
+
+      try {
+        await Deno.writeTextFile(tmpFile, args.source);
+        // goto-def outputs JSON on stdout; line/col are 1-based
+        const result = await runCompiler(
+          ["goto-def", tmpFile, String(args.line), String(args.col)],
+          null
+        );
+
+        let info;
+        try {
+          info = JSON.parse(result.stdout.trim());
+        } catch {
+          info = { found: false, raw: result.stdout };
+        }
+
+        return {
+          status: 200,
+          data: info,
+        };
+      } finally {
+        try { await Deno.remove(tmpFile); } catch { /* ignore */ }
+      }
+    }
+
+    // --- Completion ---
+
+    case "affinescript_complete": {
+      if (!args.source) return { error: "Missing required field: source" };
+      if (args.line == null) return { error: "Missing required field: line" };
+      if (args.col == null) return { error: "Missing required field: col" };
+
+      const tmpFile = `/tmp/boj_afs_${crypto.randomUUID()}.as`;
+
+      try {
+        await Deno.writeTextFile(tmpFile, args.source);
+        // complete outputs a JSON array on stdout; line/col are 1-based
+        const result = await runCompiler(
+          ["complete", tmpFile, String(args.line), String(args.col)],
+          null
+        );
+
+        let items;
+        try {
+          items = JSON.parse(result.stdout.trim());
+        } catch {
+          items = [];
+        }
+
+        return {
+          status: 200,
+          data: { items, count: Array.isArray(items) ? items.length : 0 },
+        };
+      } finally {
+        try { await Deno.remove(tmpFile); } catch { /* ignore */ }
+      }
+    }
+
     default:
       return { error: `Unknown affinescript-mcp tool: ${toolName}` };
   }
@@ -407,5 +577,5 @@ export const metadata = {
   domain: "Languages",
   tier: "Ayo",
   protocols: ["MCP", "REST"],
-  toolCount: 7,
+  toolCount: 12,
 };
