Add Malloy Source Compile-Check API Endpoint (#619)

* feat(server): add compile-check API endpoint

Add POST /api/v0/projects/:projectName/compile endpoint that accepts
Malloy source code, compiles it against the project's connections, and
returns success/error status with any compilation problems.

- Add compileSource() method to Project class that creates a virtual
  file, intercepts the URL reader, and compiles via Malloy Runtime
- Add CompileController to handle the HTTP request and map compilation
  results to a status response
- Register the new POST route in server.ts

New files:
  packages/server/src/controller/compile.controller.ts

Modified files:
  packages/server/src/service/project.ts
  packages/server/src/server.ts

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* refactor(server): scope compile endpoint to package/model path

Update the compile endpoint route from:
  POST /api/v0/projects/:projectName/compile
to:
  POST /api/v0/projects/:projectName/packages/:packageName/models/:modelName/compile

Place the virtual compile file in the model's directory instead of the
project root so that relative imports resolve correctly against sibling
model files.

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* docs(api): add compile endpoint to OpenAPI spec

Add POST /projects/{projectName}/packages/{packageName}/models/{path}/compile
path and CompileRequest, CompileResult, CompileProblem schemas to api-doc.yaml.

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* fix(server): inherit model import context in compile endpoint

Extract the model file's preamble (pragmas, imports, comments) and
prepend it to the submitted source before compilation. This allows
raw queries referencing imported sources (e.g. run: my_source -> {...})
to compile successfully, matching the context available in the query
endpoint.

- Extract preamble parsing into exported extractPreamble() and
  extractPreambleFromSource() functions for testability
- Add project_compile.spec.ts with 14 tests covering edge cases

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* fix: prettier formatting

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* feat: add includeSql option to compile endpoint

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* feat: add includeSql option to compile endpoint

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

* fix:linting

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

---------

Signed-off-by: Adam Ribaudo <aribaudo@form-function.co>

Author: adamribaudo-ff

.vscode/tasks.json

@@ -0,0 +1,15 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "build:server-deploy",
+      "type": "shell",
+      "command": "bun run build:server-deploy",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": []
+    }
+  ]
+}

api-doc.yaml

@@ -1318,6 +1318,57 @@ paths:
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
+  /projects/{projectName}/packages/{packageName}/models/{path}/compile:
+    post:
+      tags:
+        - models
+      operationId: compile-model-source
+      summary: Compile Malloy source code
+      description: |
+        Compiles Malloy source code in the context of a specific model's directory,
+        allowing relative imports to resolve correctly against sibling model files.
+        Returns compilation status and any problems (errors or warnings) found.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            type: string
+        - name: path
+          in: path
+          description: Path to the model within the package (used to resolve relative imports)
+          required: true
+          schema:
+            $ref: "#/components/schemas/PathPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CompileRequest"
+      responses:
+        "200":
+          description: Compilation result with status and any problems
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompileResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
   /projects/{projectName}/packages/{packageName}/notebooks:
     get:
       tags:
@@ -2390,3 +2441,59 @@ components:
         errorMessage:
           type: string
           description: Error message if the connection test failed, null if successful
+
+    CompileRequest:
+      type: object
+      description: Request body for compiling Malloy source code
+      properties:
+        source:
+          type: string
+          description: Malloy source code to compile
+        includeSql:
+          type: boolean
+          default: false
+          description: If true, returns the generated SQL alongside compilation results (only available when compilation succeeds and the source contains a runnable query).
+      required:
+        - source
+
+    CompileResult:
+      type: object
+      description: Result of a Malloy source compilation check
+      properties:
+        status:
+          type: string
+          description: Overall compilation status — "error" if any problems have error severity
+          enum: ["success", "error"]
+        problems:
+          type: array
+          description: List of compilation problems (errors and warnings)
+          items:
+            $ref: "#/components/schemas/CompileProblem"
+        sql:
+          type: string
+          description: Generated SQL for the compiled query. Only present when includeSql is true and compilation succeeds with a runnable query.
+
+    CompileProblem:
+      type: object
+      description: A compilation problem reported by the Malloy compiler
+      properties:
+        message:
+          type: string
+          description: Human-readable problem description
+        severity:
+          type: string
+          description: Severity level of the problem
+          enum: ["error", "warn", "debug"]
+        code:
+          type: string
+          description: Machine-readable error code
+        at:
+          type: object
+          description: Source location of the problem
+          properties:
+            url:
+              type: string
+              description: URL of the source file
+            range:
+              type: object
+              description: Character range within the source file

packages/server/src/controller/compile.controller.ts

@@ -0,0 +1,35 @@
+import type { LogMessage } from "@malloydata/malloy";
+import { ProjectStore } from "../service/project_store";
+
+export class CompileController {
+   private projectStore: ProjectStore;
+
+   constructor(projectStore: ProjectStore) {
+      this.projectStore = projectStore;
+   }
+
+   public async compile(
+      projectName: string,
+      packageName: string,
+      modelName: string,
+      source: string,
+      includeSql: boolean = false,
+   ): Promise<{ status: string; problems: LogMessage[]; sql?: string }> {
+      const project = await this.projectStore.getProject(projectName, false);
+      const { problems, sql } = await project.compileSource(
+         packageName,
+         modelName,
+         source,
+         includeSql,
+      );
+
+      // Determine overall status based on presence of errors
+      const hasErrors = problems.some((p) => p.severity === "error");
+
+      return {
+         status: hasErrors ? "error" : "success",
+         problems: problems,
+         ...(sql !== undefined && { sql }),
+      };
+   }
+}

packages/server/src/server.ts

@@ -13,6 +13,7 @@ import * as http from "http";
 import { createProxyMiddleware } from "http-proxy-middleware";
 import { AddressInfo } from "net";
 import * as path from "path";
+import { CompileController } from "./controller/compile.controller";
 import { ConnectionController } from "./controller/connection.controller";
 import { DatabaseController } from "./controller/database.controller";
 import { ModelController } from "./controller/model.controller";
@@ -126,6 +127,7 @@ const modelController = new ModelController(projectStore);
 const packageController = new PackageController(projectStore);
 const databaseController = new DatabaseController(projectStore);
 const queryController = new QueryController(projectStore);
+const compileController = new CompileController(projectStore);
 
 export const mcpApp = express();
 
@@ -917,6 +919,26 @@ app.get(
    },
 );
 
+app.post(
+   `${API_PREFIX}/projects/:projectName/packages/:packageName/models/:modelName/compile`,
+   async (req, res) => {
+      try {
+         const result = await compileController.compile(
+            req.params.projectName,
+            req.params.packageName,
+            req.params.modelName,
+            req.body.source,
+            req.body.includeSql === true,
+         );
+         res.status(200).json(result);
+      } catch (error) {
+         logger.error("Compilation error", { error });
+         const { json, status } = internalErrorToHttpError(error as Error);
+         res.status(status).json(json);
+      }
+   },
+);
+
 // Modify the catch-all route to only serve index.html in production
 if (!isDevelopment) {
    app.get("*", (_req, res) => res.sendFile(path.resolve(ROOT, "index.html")));

packages/server/src/service/project.ts

@@ -1,3 +1,5 @@
+import type { LogMessage } from "@malloydata/malloy";
+import { FixedConnectionMap, MalloyError, Runtime } from "@malloydata/malloy";
 import { BaseConnection } from "@malloydata/malloy/connection";
 import { Mutex } from "async-mutex";
 import * as fs from "fs";
@@ -10,6 +12,7 @@ import {
    ProjectNotFoundError,
 } from "../errors";
 import { logger } from "../logger";
+import { URL_READER } from "../utils";
 import { createProjectConnections, InternalConnection } from "./connection";
 import { ApiConnection } from "./model";
 import { Package } from "./package";
@@ -159,6 +162,71 @@ export class Project {
       return this.metadata;
    }
 
+   public async compileSource(
+      packageName: string,
+      modelName: string,
+      source: string,
+      includeSql: boolean = false,
+   ): Promise<{ problems: LogMessage[]; sql?: string }> {
+      // Place the virtual file in the model's directory so relative imports resolve correctly.
+      const modelDir = path.dirname(
+         path.join(this.projectPath, packageName, modelName),
+      );
+      const virtualUri = `file://${path.join(modelDir, "__compile_check.malloy")}`;
+      const virtualUrl = new URL(virtualUri);
+
+      // Read the model file and extract its preamble (pragmas + imports) so that
+      // the user's query inherits the model's import context.
+      const modelPath = path.join(this.projectPath, packageName, modelName);
+      const preamble = await extractPreamble(modelPath);
+      const fullSource = preamble ? `${preamble}\n${source}` : source;
+
+      // Create a URL Reader that serves the source string for the virtual file,
+      // but falls back to the disk for everything else (imports).
+      const interceptingReader = {
+         readURL: async (url: URL) => {
+            if (url.toString() === virtualUri) {
+               return fullSource;
+            }
+            return URL_READER.readURL(url);
+         },
+      };
+
+      // Initialize Runtime with the project's active connections
+      const runtime = new Runtime({
+         urlReader: interceptingReader,
+         connections: new FixedConnectionMap(this.malloyConnections, "duckdb"),
+      });
+
+      // Attempt to compile
+      try {
+         const modelMaterializer = runtime.loadModel(virtualUrl);
+         const model = await modelMaterializer.getModel();
+
+         // If includeSql is requested and compilation succeeded, attempt to extract SQL
+         let sql: string | undefined;
+         if (includeSql) {
+            try {
+               const queryMaterializer = modelMaterializer.loadFinalQuery();
+               sql = await queryMaterializer.getSQL();
+            } catch {
+               // Source may not contain a runnable query (e.g. only source definitions),
+               // in which case we simply omit the sql field.
+            }
+         }
+
+         // If successful, return any non-fatal warnings
+         return { problems: model.problems, sql };
+      } catch (error) {
+         // If parsing/compilation fails, return the errors
+         if (error instanceof MalloyError) {
+            return { problems: error.problems };
+         }
+         // If it's a system error (e.g. file not found), throw it up
+         throw error;
+      }
+   }
+
    public listApiConnections(): ApiConnection[] {
       return this.apiConnections;
    }
@@ -548,3 +616,43 @@ export class Project {
          });
    }
 }
+
+/**
+ * Extracts the preamble from a Malloy model file — the leading block of
+ * `##!` pragmas, `import` statements, blank lines, and comments that appear
+ * before any `source:`, `query:`, or `run:` definition. This allows a
+ * submitted query to inherit the model's import context.
+ */
+export async function extractPreamble(modelPath: string): Promise<string> {
+   try {
+      const content = await fs.promises.readFile(modelPath, "utf8");
+      return extractPreambleFromSource(content);
+   } catch {
+      // If the model file can't be read, return empty preamble
+      // and let the compilation surface any import errors naturally.
+      return "";
+   }
+}
+
+/**
+ * Extracts the preamble from Malloy source text. Exported for testing.
+ */
+export function extractPreambleFromSource(content: string): string {
+   const lines = content.split("\n");
+   const preambleLines: string[] = [];
+
+   for (const line of lines) {
+      const trimmed = line.trim();
+      // Stop at the first source/query/run definition
+      if (
+         trimmed.startsWith("source:") ||
+         trimmed.startsWith("query:") ||
+         trimmed.startsWith("run:")
+      ) {
+         break;
+      }
+      preambleLines.push(line);
+   }
+
+   return preambleLines.join("\n").trimEnd();
+}