@malloy-publisher/server 0.0.234 → 0.0.236

package/src/mcp/tools/compile_tool.spec.ts

@@ -1,315 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { formatDiagnosticsText, registerCompileTool } from "./compile_tool";
-import type { EnvironmentStore } from "../../service/environment_store";
-import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
-
-// Capture the handler registerCompileTool passes to McpServer.tool, so it can
-// be exercised against a mocked EnvironmentStore. The tool builds a
-// CompileController internally, which calls environment.compileSource, so the
-// mock only needs getEnvironment -> { compileSource }.
-type Content = Array<{
-   type?: string;
-   text?: string;
-   resource?: { text: string };
-}>;
-
-type Handler = (params: Record<string, unknown>) => Promise<{
-   isError?: boolean;
-   content: Content;
-}>;
-
-function captureHandler(store: Partial<EnvironmentStore>): Handler {
-   let handler: Handler | undefined;
-   const fakeServer = {
-      tool: (_name: string, _desc: string, _shape: unknown, h: Handler) => {
-         handler = h;
-      },
-   };
-   registerCompileTool(fakeServer as never, store as EnvironmentStore);
-   if (!handler) throw new Error("handler was not registered");
-   return handler;
-}
-
-function parse(result: { content: Content }) {
-   return JSON.parse(result.content[0].resource!.text);
-}
-
-function textBlock(result: { content: Content }) {
-   return result.content.find((b) => b.type === "text")?.text;
-}
-
-function storeReturning(
-   problems: Array<Record<string, unknown>>,
-   sql?: string,
-): Partial<EnvironmentStore> {
-   return {
-      getEnvironment: async () =>
-         ({
-            compileSource: async () => ({ problems, sql }),
-         }) as never,
-   };
-}
-
-const args = {
-   environmentName: "malloy-samples",
-   packageName: "ecommerce",
-   modelPath: "ecommerce.malloy",
-   source: "run: order_items -> { aggregate: c is count() }",
-};
-
-describe("malloy_compile tool", () => {
-   it("returns status success and empty diagnostics for a clean compile", async () => {
-      const handler = captureHandler(storeReturning([]));
-      const result = await handler(args);
-      expect(result.isError).toBe(false);
-      expect(parse(result)).toEqual({ status: "success", diagnostics: [] });
-   });
-
-   it("flattens an error diagnostic and sets isError", async () => {
-      const handler = captureHandler(
-         storeReturning([
-            {
-               severity: "error",
-               message: "'nope' is not defined",
-               code: "field-not-found",
-               at: {
-                  range: {
-                     start: { line: 2, character: 3 },
-                     end: { line: 2, character: 7 },
-                  },
-               },
-               replacement: undefined,
-            },
-         ]),
-      );
-      const result = await handler(args);
-      expect(result.isError).toBe(true);
-      const parsed = parse(result);
-      expect(parsed.status).toBe("error");
-      expect(parsed.diagnostics).toEqual([
-         {
-            severity: "error",
-            message: "'nope' is not defined",
-            code: "field-not-found",
-            line: 2,
-            character: 3,
-            endLine: 2,
-            endCharacter: 7,
-         },
-      ]);
-   });
-
-   it("also states the diagnostics in a text block", async () => {
-      // The regression pin for the isError path that matters most: a bad Malloy
-      // snippet. A client that renders only text blocks on isError sees nothing
-      // without this, and reports a bare "Unknown error" while the diagnostics
-      // sit unread in the resource block.
-      const handler = captureHandler(
-         storeReturning([
-            {
-               severity: "error",
-               message: "'nope' is not defined",
-               code: "field-not-found",
-               at: {
-                  range: {
-                     start: { line: 2, character: 3 },
-                     end: { line: 2, character: 7 },
-                  },
-               },
-            },
-         ]),
-      );
-      const result = await handler(args);
-      expect(textBlock(result)).toBe(
-         "Compile failed with 1 error (positions are 0-based):\n\n" +
-            "- 'nope' is not defined (line 2, character 3) [field-not-found]",
-      );
-   });
-
-   it("adds no text block to a clean compile", async () => {
-      // Success stays resource-only: the payload is the answer, and duplicating
-      // it as prose would double every response for no gain.
-      const handler = captureHandler(storeReturning([]));
-      expect(textBlock(await handler(args))).toBeUndefined();
-   });
-
-   it("treats a warning as a clean compile (status success, isError false)", async () => {
-      const handler = captureHandler(
-         storeReturning([
-            {
-               severity: "warn",
-               message: "deprecated syntax",
-               code: "deprecated",
-               at: {
-                  range: {
-                     start: { line: 0, character: 0 },
-                     end: { line: 0, character: 4 },
-                  },
-               },
-            },
-         ]),
-      );
-      const result = await handler(args);
-      expect(result.isError).toBe(false);
-      const parsed = parse(result);
-      expect(parsed.status).toBe("success");
-      expect(parsed.diagnostics[0].severity).toBe("warn");
-   });
-
-   it("includes sql when the controller returns it", async () => {
-      const handler = captureHandler(storeReturning([], "SELECT 1"));
-      const parsed = parse(await handler({ ...args, includeSql: true }));
-      expect(parsed.sql).toBe("SELECT 1");
-   });
-
-   it("surfaces a thrown error as a tool error, not a transport fault", async () => {
-      const handler = captureHandler({
-         getEnvironment: async () => {
-            throw new Error("Environment 'nope' could not be resolved");
-         },
-      });
-      const result = await handler({ ...args, environmentName: "nope" });
-      expect(result.isError).toBe(true);
-      const parsed = parse(result);
-      expect(parsed.error).toBeDefined();
-   });
-
-   it("reports a missing package as not-found, not as a Malloy syntax problem", async () => {
-      // Pin the remediation text, not just that an error came back. Asserting
-      // only that `error` is defined passes even when every class funnels
-      // through the Malloy helper, which is the bug classifyToolError exists to
-      // fix: a typo'd package name told the caller to check its Malloy syntax.
-      const handler = captureHandler({
-         getEnvironment: async () => {
-            throw new PackageNotFoundError("Package 'nope' not found");
-         },
-      });
-      const parsed = parse(await handler({ ...args, packageName: "nope" }));
-      expect(parsed.error).toContain("Resource not found");
-      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
-   });
-
-   it("reports back-pressure as retryable, not as a Malloy syntax problem", async () => {
-      const handler = captureHandler({
-         getEnvironment: async () => {
-            throw new ServiceUnavailableError("Memory limit reached");
-         },
-      });
-      const parsed = parse(await handler(args));
-      expect(parsed.error).toContain("Memory limit reached");
-      expect(JSON.stringify(parsed.suggestions)).toContain("Retry");
-      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
-   });
-
-   it("reports an unexpected internal error without blaming the Malloy", async () => {
-      // The catch-all used to hand a TypeError to the Malloy helper, so a bug
-      // in our own code told the agent to go edit a model that was fine.
-      const handler = captureHandler({
-         getEnvironment: async () => {
-            throw new TypeError("cannot read properties of undefined");
-         },
-      });
-      const parsed = parse(await handler(args));
-      expect(parsed.error).toContain("unexpected internal error");
-      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
-   });
-
-   it("omits position fields when a diagnostic has no location", async () => {
-      const handler = captureHandler(
-         storeReturning([
-            { severity: "error", message: "no location", code: "syntax" },
-         ]),
-      );
-      const parsed = parse(await handler(args));
-      expect(parsed.diagnostics[0]).toEqual({
-         severity: "error",
-         message: "no location",
-         code: "syntax",
-      });
-   });
-
-   describe("formatDiagnosticsText", () => {
-      it("renders only the error-severity diagnostics", () => {
-         const text = formatDiagnosticsText([
-            { severity: "warn", message: "deprecated syntax", code: "dep" },
-            { severity: "error", message: "first", line: 1, character: 0 },
-            { severity: "error", message: "second", line: 4, character: 2 },
-         ]);
-         expect(text).toBe(
-            "Compile failed with 2 errors (positions are 0-based):\n\n" +
-               "- first (line 1, character 0)\n" +
-               "- second (line 4, character 2)",
-         );
-         expect(text).not.toContain("deprecated syntax");
-      });
-
-      it("omits the position when a diagnostic has no location", () => {
-         expect(
-            formatDiagnosticsText([
-               { severity: "error", message: "no location", code: "syntax" },
-            ]),
-         ).toBe(
-            "Compile failed with 1 error (positions are 0-based):\n\n" +
-               "- no location [syntax]",
-         );
-      });
-
-      it("renders line 0 / character 0 rather than dropping them", () => {
-         // 0 is a real position, not a missing one; a falsy check here would
-         // silently swallow the first line of the file.
-         expect(
-            formatDiagnosticsText([
-               {
-                  severity: "error",
-                  message: "at the top",
-                  line: 0,
-                  character: 0,
-               },
-            ]),
-         ).toContain("- at the top (line 0, character 0)");
-      });
-
-      it("defaults character to 0 when only the line is known", () => {
-         expect(
-            formatDiagnosticsText([
-               { severity: "error", message: "line only", line: 7 },
-            ]),
-         ).toContain("- line only (line 7, character 0)");
-      });
-
-      it("falls back to every diagnostic when none has error severity", () => {
-         // Defensive: status is "error" only when an error-severity diagnostic
-         // exists, so this should be unreachable. It must not render an empty
-         // list if that ever changes.
-         expect(
-            formatDiagnosticsText([
-               { severity: "warn", message: "only a warn" },
-            ]),
-         ).toBe(
-            "Compile failed with 1 error (positions are 0-based):\n\n" +
-               "- only a warn",
-         );
-      });
-   });
-
-   it("forwards givens to compileSource", async () => {
-      let captured: unknown;
-      const handler = captureHandler({
-         getEnvironment: async () =>
-            ({
-               compileSource: async (
-                  _pkg: string,
-                  _model: string,
-                  _source: string,
-                  _includeSql: boolean,
-                  givens: unknown,
-               ) => {
-                  captured = givens;
-                  return { problems: [] };
-               },
-            }) as never,
-      });
-      await handler({ ...args, givens: { region: "west" } });
-      expect(captured).toEqual({ region: "west" });
-   });
-});

package/src/mcp/tools/compile_tool.ts

@@ -1,208 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import type { GivenValue } from "@malloydata/malloy";
-import { logger } from "../../logger";
-import { EnvironmentStore } from "../../service/environment_store";
-import { CompileController } from "../../controller/compile.controller";
-import { type ErrorDetails } from "../error_messages";
-import { buildMalloyUri, classifyToolError } from "../handler_utils";
-import { jsonResource, jsonToolError } from "../tool_response";
-
-// Zod shape for malloy_compile. environmentName/packageName mirror the other
-// tools and point the agent at malloy_getContext for name discovery.
-const compileShape = {
-   environmentName: z
-      .string()
-      .describe(
-         "Environment name. Call malloy_getContext with no arguments to list the available environments.",
-      ),
-   packageName: z
-      .string()
-      .describe(
-         "Package containing the model. Call malloy_getContext with just environmentName to list its packages.",
-      ),
-   modelPath: z
-      .string()
-      .describe(
-         "Path to the .malloy model whose namespace the source compiles against. The source is appended to this model, so its imports, sources, and queries are in scope.",
-      ),
-   source: z
-      .string()
-      .describe(
-         "The Malloy source to validate. Compiled in the context of modelPath and not executed.",
-      ),
-   includeSql: z
-      .boolean()
-      .optional()
-      .describe(
-         "When true and the source ends in a runnable query, also return the generated SQL for inspection. The query is still not run.",
-      ),
-   givens: z
-      .record(z.unknown())
-      .optional()
-      .describe(
-         "Given values for the model's given: block. Also required to satisfy any #(authorize) gate on the target model, whether or not includeSql is set.",
-      ),
-};
-
-const COMPILE_DESCRIPTION = `Compile-check Malloy source against a model and return structured diagnostics WITHOUT running a query. Use this to validate a model or a change while authoring, instead of firing a throwaway malloy_executeQuery just to see whether it parses.
-
-## Parameters
-- environmentName, packageName, modelPath (required): the model whose namespace the source compiles against. The source is appended to that model, so its imports, sources, and queries are in scope, and modelPath is real context, not a label.
-- source (required): the Malloy text to validate.
-- includeSql (optional): also return the generated SQL when the source ends in a runnable query. The query is still not executed and no data is scanned.
-
-## Checking part of a source
-Your source is APPENDED, so it must stand alone as top-level Malloy: a bare \`view:\`, \`dimension:\` or \`measure:\` does not compile on its own, and resubmitting a source the model already declares reports "Cannot redefine". docs/ai-agents.md gives the two forms that work.
-
-## Response
-A JSON object with status ("success" or "error") and diagnostics: an array of { severity ("error" / "warn" / "debug"), message, code, line, character, endLine, endCharacter, replacement }. Positions are 0-based (line and character start at 0) and relative to the model file with your source appended to it, so a diagnostic in your submitted source lands after the model's own line count, and a diagnostic may point at pre-existing content in the model rather than at your source. Any wrapper you add counts toward that offset too. A clean compile can still return warnings; status is "error" only when at least one diagnostic has error severity. When status is "error" the response also states the error diagnostics in a plain text block alongside the JSON, so the failure is legible without parsing the payload.`;
-
-/** The flattened diagnostic shape this tool returns. */
-type CompileDiagnostic = {
-   severity: string;
-   message: string;
-   code?: string;
-   line?: number;
-   character?: number;
-};
-
-/**
- * Renders error diagnostics as the prose a text-only client will show.
- *
- * A failed compile is an isError result whose diagnostics live in the resource
- * block, so a client that renders only text blocks on isError sees nothing —
- * which is how a real compile error gets reported as a bare "Unknown error".
- * The resource block stays the parseable channel; this is the legible one.
- * Positions are labelled 0-based to match the payload rather than introduce a
- * second convention for the same numbers.
- *
- * Only error-severity diagnostics are rendered: status is "error" because of
- * those, and they are what the caller has to fix. Falling back to every
- * diagnostic keeps the text non-empty if that invariant ever breaks.
- *
- * Exported so a spec can pin the rendering rather than merely its presence.
- */
-export function formatDiagnosticsText(
-   diagnostics: CompileDiagnostic[],
-): string {
-   const errors = diagnostics.filter((d) => d.severity === "error");
-   const shown = errors.length > 0 ? errors : diagnostics;
-   const lines = shown.map((d) => {
-      const at =
-         d.line !== undefined
-            ? ` (line ${d.line}, character ${d.character ?? 0})`
-            : "";
-      const code = d.code ? ` [${d.code}]` : "";
-      return `- ${d.message}${at}${code}`;
-   });
-   const noun = shown.length === 1 ? "error" : "errors";
-   return `Compile failed with ${shown.length} ${noun} (positions are 0-based):\n\n${lines.join("\n")}`;
-}
-
-/**
- * Registers the malloy_compile MCP tool: validates Malloy source against a model
- * and returns structured diagnostics without executing a query. Wraps the same
- * in-process compile path the REST /compile endpoint uses (CompileController).
- */
-export function registerCompileTool(
-   mcpServer: McpServer,
-   environmentStore: EnvironmentStore,
-): void {
-   const compileController = new CompileController(environmentStore);
-
-   mcpServer.tool(
-      "malloy_compile",
-      COMPILE_DESCRIPTION,
-      compileShape,
-      async (params) => {
-         const {
-            environmentName,
-            packageName,
-            modelPath,
-            source,
-            includeSql,
-            givens,
-         } = params;
-
-         logger.info("[MCP Tool compile] Compiling source", {
-            environmentName,
-            packageName,
-            modelPath,
-            includeSql: !!includeSql,
-         });
-
-         const uri = buildMalloyUri(
-            {
-               environment: environmentName,
-               package: packageName,
-               resourceType: "models",
-               resourceName: modelPath,
-            },
-            "compile",
-         );
-
-         try {
-            const result = await compileController.compile(
-               environmentName,
-               packageName,
-               modelPath,
-               source,
-               includeSql ?? false,
-               givens as Record<string, GivenValue> | undefined,
-            );
-
-            // Flatten each LogMessage's nested at.range into line/character so
-            // agents do not have to walk it. Positions are 0-based (LSP-style).
-            const diagnostics = result.problems.map((p) => ({
-               severity: p.severity,
-               message: p.message,
-               code: p.code,
-               line: p.at?.range.start.line,
-               character: p.at?.range.start.character,
-               endLine: p.at?.range.end.line,
-               endCharacter: p.at?.range.end.character,
-               replacement: p.replacement,
-            }));
-
-            const payload = {
-               status: result.status,
-               diagnostics,
-               ...(result.sql !== undefined && { sql: result.sql }),
-            };
-
-            // A compile that returns error diagnostics is still a successful
-            // tool call in the transport sense, but isError tells the agent not
-            // to treat the model as valid. This is the most common way the tool
-            // fails, so it carries a text block for the same reason the catch
-            // below does: the diagnostics are only the message to a client that
-            // parses the resource. The payload keeps its documented
-            // {status, diagnostics} shape rather than the {error, suggestions}
-            // of jsonToolError, so parsing clients are unaffected.
-            const isError = result.status === "error";
-            return jsonResource(uri, payload, {
-               isError,
-               ...(isError && { text: formatDiagnosticsText(diagnostics) }),
-            });
-         } catch (error) {
-            // Unknown environment/package, a notebook (.malloynb) rejected up
-            // front, an authorize denial, or a system error: surface as a clean
-            // isError payload rather than a transport fault. A missing modelPath
-            // does NOT error here; compileSource compiles the source against an
-            // empty namespace, so a typo in modelPath yields a normal result.
-            logger.warn("[MCP Tool compile] compile failed", {
-               environmentName,
-               packageName,
-               modelPath,
-               error: error instanceof Error ? error.message : String(error),
-            });
-            const errorDetails: ErrorDetails = classifyToolError(
-               "compile",
-               `${environmentName}/${packageName}/${modelPath}`,
-               error,
-            );
-            return jsonToolError(uri, errorDetails);
-         }
-      },
-   );
-}

package/src/mcp/tools/docs_search/build_docs_index.ts

@@ -1,132 +0,0 @@
-/**
- * Build a bundled lunr index over the Malloy documentation for the malloy_searchDocs MCP tool.
- *
- * The output JSON is committed as a build-time asset so the server has no runtime network
- * dependency. Regenerate it from a Malloy docs checkout when the docs are updated.
- *
- * Usage:
- *   bun run packages/server/src/mcp/tools/docs_search/build_docs_index.ts <docs-dir> [out.json]
- *
- * <docs-dir> points at the documentation root of a Malloy docs checkout, e.g.
- *   .../malloydata.github.io/src/documentation
- */
-import * as fs from "fs";
-import * as path from "path";
-import lunr from "lunr";
-
-const DOCS_BASE_URL = "https://docs.malloydata.dev";
-const DOC_EXTENSIONS = new Set([".md", ".malloynb"]);
-
-interface DocRecord {
-   id: string;
-   title: string;
-   path: string;
-   url: string;
-   body: string;
-}
-
-function walk(dir: string, acc: string[] = []): string[] {
-   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-         walk(full, acc);
-      } else if (DOC_EXTENSIONS.has(path.extname(entry.name))) {
-         acc.push(full);
-      }
-   }
-   return acc;
-}
-
-/** First markdown heading, else a title-cased file name. */
-function deriveTitle(body: string, relPath: string): string {
-   const heading = body.match(/^#\s+(.+)$/m);
-   if (heading) return heading[1].trim();
-   const base = path.basename(relPath).replace(/\.[^.]+$/, "");
-   return base.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-/** docs/foo/bar.md -> https://docs.malloydata.dev/documentation/foo/bar */
-function deriveUrl(relPath: string): string {
-   const noExt = relPath.replace(/\.[^.]+$/, "");
-   return `${DOCS_BASE_URL}/documentation/${noExt}`;
-}
-
-/** A short, single-line excerpt: first prose line that is not a heading or fence. */
-function deriveExcerpt(body: string): string {
-   for (const raw of body.split("\n")) {
-      const line = raw.trim();
-      if (
-         !line ||
-         line.startsWith("#") ||
-         line.startsWith("```") ||
-         line.startsWith(">>>") ||
-         line === "---"
-      )
-         continue;
-      return line.replace(/\s+/g, " ").slice(0, 280);
-   }
-   return "";
-}
-
-function main(): void {
-   const docsDir = process.argv[2];
-   const outFile =
-      process.argv[3] || path.join(import.meta.dir, "malloy_docs_index.json");
-   if (!docsDir || !fs.existsSync(docsDir)) {
-      console.error(
-         `docs dir not found: ${docsDir}\nUsage: bun run build_docs_index.ts <docs-dir> [out.json]`,
-      );
-      process.exit(1);
-   }
-
-   const files = walk(docsDir);
-   const docs: DocRecord[] = files.map((file, i) => {
-      const body = fs.readFileSync(file, "utf8");
-      const relPath = path.relative(docsDir, file);
-      return {
-         id: String(i),
-         title: deriveTitle(body, relPath),
-         path: relPath,
-         url: deriveUrl(relPath),
-         body,
-      };
-   });
-
-   const index = lunr(function () {
-      this.ref("id");
-      this.field("title", { boost: 4 });
-      this.field("body");
-      for (const doc of docs) {
-         this.add({ id: doc.id, title: doc.title, body: doc.body });
-      }
-   });
-
-   // Store metadata + excerpt per doc for the tool's response; the raw body is not
-   // shipped (only the serialized lunr postings are needed for matching).
-   const store: Record<string, Omit<DocRecord, "body">> = {};
-   for (const doc of docs) {
-      store[doc.id] = {
-         id: doc.id,
-         title: doc.title,
-         path: doc.path,
-         url: doc.url,
-         excerpt: deriveExcerpt(doc.body),
-      } as Omit<DocRecord, "body">;
-   }
-
-   fs.writeFileSync(
-      outFile,
-      JSON.stringify({
-         builtFrom: docsDir,
-         docCount: docs.length,
-         index,
-         store,
-      }),
-   );
-   console.log(`Wrote ${docs.length} docs to ${outFile}`);
-}
-
-// Only run when invoked directly (bun run ...), not when imported by a test.
-if (import.meta.main) {
-   main();
-}