@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/graphql/helpers/parsePrefixes.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import parsePrefixes from "./parsePrefixes.js";
+
+describe("parsePrefixes", () => {
+  it("returns the default prefix map for no entries", () => {
+    const prefixes = parsePrefixes([]);
+    expect(prefixes).toEqual(PREFIX_MAP);
+  });
+
+  it("merges entries on top of the defaults", () => {
+    const prefixes = parsePrefixes(["ex=http://example.org/"]);
+    expect(prefixes.ex).toBe("http://example.org/");
+    expect(prefixes.ds).toBe(PREFIX_MAP.ds);
+  });
+
+  it("lets entries override default prefixes", () => {
+    const prefixes = parsePrefixes(["ds=http://other.example/"]);
+    expect(prefixes.ds).toBe("http://other.example/");
+  });
+
+  it("splits on the first equals sign only", () => {
+    const prefixes = parsePrefixes(["ex=http://example.org/?q=1"]);
+    expect(prefixes.ex).toBe("http://example.org/?q=1");
+  });
+
+  it("throws structured error for an entry without equals sign", () => {
+    expect(() => parsePrefixes(["nonsense"])).toThrowError(
+      expect.objectContaining({ code: "INVALID_INPUT" }),
+    );
+  });
+
+  it("throws structured error for an entry without a name", () => {
+    expect(() => parsePrefixes(["=http://example.org/"])).toThrowError(
+      expect.objectContaining({ code: "INVALID_INPUT" }),
+    );
+  });
+
+  it("throws structured error for an entry without a namespace", () => {
+    expect(() => parsePrefixes(["ex="])).toThrowError(
+      expect.objectContaining({ code: "INVALID_INPUT" }),
+    );
+  });
+});

package/src/domains/graphql/helpers/parsePrefixes.ts

@@ -0,0 +1,38 @@
+import { PragmaError } from "#error";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+
+/**
+ * Parse repeated `--prefix name=namespace` entries into a prefix map.
+ *
+ * User-supplied prefixes are merged on top of pragma's default
+ * {@link PREFIX_MAP}, so `ds:` and the W3C vocabularies stay available
+ * unless explicitly overridden.
+ *
+ * @param entries - Raw `name=namespace` strings from the CLI.
+ * @returns The merged prefix map for store creation and compilation.
+ * @throws PragmaError with code `INVALID_INPUT` when an entry is malformed.
+ */
+export default function parsePrefixes(
+  entries: readonly string[],
+): Record<string, string> {
+  const prefixes: Record<string, string> = { ...PREFIX_MAP };
+
+  for (const entry of entries) {
+    const separator = entry.indexOf("=");
+    const name = separator === -1 ? "" : entry.slice(0, separator).trim();
+    const namespace = separator === -1 ? "" : entry.slice(separator + 1).trim();
+
+    if (!name || !namespace) {
+      throw PragmaError.invalidInput("prefix", entry, {
+        recovery: {
+          message:
+            "Use name=namespace, e.g. --prefix ds=https://ds.canonical.com/.",
+        },
+      });
+    }
+
+    prefixes[name] = namespace;
+  }
+
+  return prefixes;
+}

package/src/domains/graphql/helpers/resolveSourceFiles.test.ts

@@ -0,0 +1,56 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import resolveSourceFiles from "./resolveSourceFiles.js";
+
+describe("resolveSourceFiles", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-graphql-sources-"));
+    writeFileSync(join(dir, "a.ttl"), "# a");
+    writeFileSync(join(dir, "b.ttl"), "# b");
+    writeFileSync(join(dir, "notes.txt"), "ignore me");
+    mkdirSync(join(dir, "nested"));
+    writeFileSync(join(dir, "nested", "c.ttl"), "# c");
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("resolves relative literal paths against cwd", () => {
+    const files = resolveSourceFiles(["a.ttl"], dir);
+    expect(files).toEqual([join(dir, "a.ttl")]);
+  });
+
+  it("keeps absolute literal paths", () => {
+    const files = resolveSourceFiles([join(dir, "b.ttl")], dir);
+    expect(files).toEqual([join(dir, "b.ttl")]);
+  });
+
+  it("skips missing literal paths", () => {
+    const files = resolveSourceFiles(["missing.ttl"], dir);
+    expect(files).toEqual([]);
+  });
+
+  it("expands glob patterns", () => {
+    const files = resolveSourceFiles(["*.ttl"], dir);
+    expect(files.sort()).toEqual([join(dir, "a.ttl"), join(dir, "b.ttl")]);
+  });
+
+  it("expands recursive glob patterns", () => {
+    const files = resolveSourceFiles(["**/*.ttl"], dir);
+    expect(files.sort()).toEqual([
+      join(dir, "a.ttl"),
+      join(dir, "b.ttl"),
+      join(dir, "nested", "c.ttl"),
+    ]);
+  });
+
+  it("combines multiple patterns in order", () => {
+    const files = resolveSourceFiles(["b.ttl", "nested/*.ttl"], dir);
+    expect(files).toEqual([join(dir, "b.ttl"), join(dir, "nested", "c.ttl")]);
+  });
+});

package/src/domains/graphql/helpers/resolveSourceFiles.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve TTL source patterns to absolute file paths.
+ *
+ * Mirrors ke's own source resolution (wildcard detection + `globSync`,
+ * literal paths checked for existence) so the files the CLI reads and
+ * hashes are exactly the files `createStore` loads.
+ *
+ * @note Impure — reads filesystem to expand globs and check existence.
+ */
+
+import { existsSync, globSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Expand file paths and glob patterns into absolute file paths.
+ *
+ * @param patterns - Literal paths or glob patterns (`*`, `?`, `[`).
+ * @param cwd - Base directory for resolving relative patterns.
+ * @returns Absolute paths of all matched, existing files.
+ */
+export default function resolveSourceFiles(
+  patterns: readonly string[],
+  cwd: string,
+): string[] {
+  const files: string[] = [];
+
+  for (const pattern of patterns) {
+    if (
+      pattern.includes("*") ||
+      pattern.includes("?") ||
+      pattern.includes("[")
+    ) {
+      for (const file of globSync(pattern, { cwd })) {
+        files.push(resolve(cwd, file));
+      }
+    } else {
+      const absPath = resolve(cwd, pattern);
+      if (existsSync(absPath)) {
+        files.push(absPath);
+      }
+    }
+  }
+
+  return files;
+}

package/src/domains/graphql/helpers/routeGraphql.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from "vitest";
+import routeGraphql from "./routeGraphql.js";
+
+describe("routeGraphql", () => {
+  it("delegates /graphql to the handler", async () => {
+    const handler = vi.fn(() => new Response("handled"));
+    const request = new Request("http://localhost:4000/graphql");
+
+    const response = await routeGraphql(request, handler, 4000);
+
+    expect(handler).toHaveBeenCalledWith(request);
+    expect(await response.text()).toBe("handled");
+  });
+
+  it("redirects / to /graphql", async () => {
+    const handler = vi.fn();
+
+    const response = await routeGraphql(
+      new Request("http://localhost:4000/"),
+      handler,
+      4000,
+    );
+
+    expect(response.status).toBe(302);
+    expect(response.headers.get("location")).toBe(
+      "http://localhost:4000/graphql",
+    );
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("404s any other path", async () => {
+    const handler = vi.fn();
+
+    const response = await routeGraphql(
+      new Request("http://localhost:4000/favicon.ico"),
+      handler,
+      4000,
+    );
+
+    expect(response.status).toBe(404);
+    expect(handler).not.toHaveBeenCalled();
+  });
+});

package/src/domains/graphql/helpers/routeGraphql.ts

@@ -0,0 +1,28 @@
+/**
+ * Route an incoming request for the graphql dev server: `/graphql` to the
+ * GraphQL + GraphiQL handler, `/` to a redirect there, and everything else
+ * to 404. Mounting is intentionally the host's job, which keeps the handler
+ * itself path-agnostic.
+ *
+ * @param request - The incoming fetch Request.
+ * @param handler - The GraphQL fetch handler for `/graphql`.
+ * @param port - The listen port, used to build the root redirect target.
+ * @returns The response (or a promise of one) for the route.
+ */
+
+type GraphQLHandler = (request: Request) => Response | Promise<Response>;
+
+export default function routeGraphql(
+  request: Request,
+  handler: GraphQLHandler,
+  port: number,
+): Response | Promise<Response> {
+  const { pathname } = new URL(request.url);
+  if (pathname === "/graphql") {
+    return handler(request);
+  }
+  if (pathname === "/") {
+    return Response.redirect(`http://localhost:${port}/graphql`, 302);
+  }
+  return new Response(null, { status: 404 });
+}

package/src/domains/graphql/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @module GraphQL domain barrel.
+ *
+ * Compiles TTL ontologies into GraphQL schema artifacts via the ke-graphql
+ * pipeline, and serves them locally. Commands boot their own ke store —
+ * from explicit TTL sources or, when none are given, the semantic packages
+ * configured in `pragma.config.json` — so they run on the store-skip
+ * pipeline path.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import { buildCommand, checkCommand, serveCommand } from "./commands/index.js";
+
+/**
+ * Returns all command definitions for the graphql domain.
+ *
+ * @returns The `graphql build`, `graphql check`, and `graphql serve`
+ *   command definitions.
+ */
+export function commands(): CommandDefinition[] {
+  return [buildCommand, checkCommand, serveCommand];
+}
+
+export { compileSchema } from "./operations/index.js";

package/src/domains/graphql/operations/compileSchema.test.ts

@@ -0,0 +1,95 @@
+import { hashSources } from "@canonical/ke-graphql";
+import { describe, expect, it } from "vitest";
+import {
+  EX_NAMESPACE,
+  GRAPHQL_CLEAN_TTL,
+  GRAPHQL_ERROR_TTL,
+  GRAPHQL_FATAL_TTL,
+} from "#testing";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import compileSchema from "./compileSchema.js";
+
+const PREFIXES = { ...PREFIX_MAP, ex: EX_NAMESPACE };
+
+const inline = (content: string, path: string) => ({
+  content,
+  format: "turtle" as const,
+  path,
+});
+
+describe("compileSchema", () => {
+  it("compiles a clean ontology into SDL", async () => {
+    const outcome = await compileSchema({
+      sources: [inline(GRAPHQL_CLEAN_TTL, "clean.ttl")],
+      prefixes: PREFIXES,
+    });
+
+    expect(outcome.status).toBe("ok");
+    expect(outcome.compiled?.sdl).toContain("type Thing");
+    expect(outcome.diagnostics).toEqual([]);
+    expect(outcome.files).toEqual(["clean.ttl"]);
+  });
+
+  it("hashes the exact raw source contents", async () => {
+    const outcome = await compileSchema({
+      sources: [inline(GRAPHQL_CLEAN_TTL, "clean.ttl")],
+      prefixes: PREFIXES,
+    });
+
+    expect(outcome.sourcesHash).toBe(hashSources([GRAPHQL_CLEAN_TTL]));
+  });
+
+  it("labels a source without a path as 'inline'", async () => {
+    const outcome = await compileSchema({
+      sources: [{ content: GRAPHQL_CLEAN_TTL, format: "turtle" }],
+      prefixes: PREFIXES,
+    });
+
+    expect(outcome.files).toEqual(["inline"]);
+  });
+
+  it("surfaces error diagnostics without failing the compile", async () => {
+    const outcome = await compileSchema({
+      sources: [inline(GRAPHQL_ERROR_TTL, "error.ttl")],
+      prefixes: PREFIXES,
+    });
+
+    expect(outcome.status).toBe("ok");
+    expect(outcome.compiled).toBeDefined();
+    expect(
+      outcome.diagnostics.some(
+        (d) => d.severity === "error" && d.code === "M001",
+      ),
+    ).toBe(true);
+  });
+
+  it("converts CompilationError into a failed result with diagnostics", async () => {
+    const outcome = await compileSchema({
+      sources: [inline(GRAPHQL_FATAL_TTL, "fatal.ttl")],
+      prefixes: PREFIXES,
+    });
+
+    expect(outcome.status).toBe("failed");
+    expect(outcome.compiled).toBeUndefined();
+    expect(
+      outcome.diagnostics.some(
+        (d) => d.severity === "error" && d.code === "C003",
+      ),
+    ).toBe(true);
+  });
+
+  it("throws a structured error when given no sources", async () => {
+    await expect(
+      compileSchema({ sources: [], prefixes: PREFIXES }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
+  it("throws a structured error on invalid TTL syntax", async () => {
+    await expect(
+      compileSchema({
+        sources: [inline("this is not turtle .", "broken.ttl")],
+        prefixes: PREFIXES,
+      }),
+    ).rejects.toMatchObject({ code: "STORE_ERROR" });
+  });
+});

package/src/domains/graphql/operations/compileSchema.ts

@@ -0,0 +1,107 @@
+import { createStore, type InlineSource } from "@canonical/ke";
+import {
+  CompilationError,
+  type CompilerResult,
+  compile,
+  createStoreQueryFn,
+  type Diagnostic,
+  hashSources,
+} from "@canonical/ke-graphql";
+import { PragmaError } from "#error";
+
+export interface CompileSchemaOptions {
+  /** In-memory TTL sources (content + provenance path) to compile. */
+  readonly sources: readonly InlineSource[];
+  /** Prefix map handed to both the ke store and the compiler. */
+  readonly prefixes: Readonly<Record<string, string>>;
+  /** Working directory, passed through to the store (unused for inline). */
+  readonly cwd?: string;
+}
+
+export interface CompileSchemaResult {
+  /** `"ok"` when a schema was produced, `"failed"` when composition aborted. */
+  readonly status: "ok" | "failed";
+  /** All compiler diagnostics, including those carried by a CompilationError. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Provenance paths of the sources that were loaded. */
+  readonly files: readonly string[];
+  /** Fingerprint of the raw source contents (matches ke's onLoad hashing). */
+  readonly sourcesHash: string;
+  /** Full compiler output; absent when compilation failed. */
+  readonly compiled?: CompilerResult;
+}
+
+/**
+ * Compile in-memory TTL sources into a GraphQL schema via the ke-graphql
+ * pipeline.
+ *
+ * Hashes the raw source contents (the exact bytes ke loads, so the
+ * artifact's `sourcesHash` matches what `createSchemaPlugin` computes from
+ * ke's onLoad), boots a throwaway ke store, and runs the compiler. A
+ * {@link CompilationError} (schema composition failed) is converted into a
+ * `"failed"` result carrying its diagnostics; the store is always disposed.
+ *
+ * @note Impure — boots a ke store (WASM + TTL).
+ *
+ * @param options - In-memory sources and prefixes.
+ * @returns The compile outcome with diagnostics, files, and sources hash.
+ * @throws PragmaError with code `INVALID_INPUT` when given no sources.
+ * @throws PragmaError with code `STORE_ERROR` when the store fails to load.
+ */
+export default async function compileSchema(
+  options: CompileSchemaOptions,
+): Promise<CompileSchemaResult> {
+  const { sources } = options;
+
+  if (sources.length === 0) {
+    throw PragmaError.invalidInput("sources", "(empty)", {
+      recovery: {
+        message: "Provide at least one TTL source.",
+      },
+    });
+  }
+
+  const sourcesHash = hashSources(sources.map((source) => source.content));
+  const files = sources.map((source) => source.path ?? "inline");
+
+  let store: Awaited<ReturnType<typeof createStore>>;
+  try {
+    store = await createStore({
+      sources: [...sources],
+      prefixes: options.prefixes,
+      cwd: options.cwd,
+    });
+  } catch (error) {
+    throw PragmaError.storeError(
+      error instanceof Error ? error.message : String(error),
+      {
+        recovery: {
+          message: "Check the TTL syntax of the provided sources.",
+        },
+      },
+    );
+  }
+
+  try {
+    const compiled = await compile(createStoreQueryFn(store), options.prefixes);
+    return {
+      status: "ok",
+      diagnostics: compiled.diagnostics,
+      files,
+      sourcesHash,
+      compiled,
+    };
+  } catch (error) {
+    if (error instanceof CompilationError) {
+      return {
+        status: "failed",
+        diagnostics: error.diagnostics,
+        files,
+        sourcesHash,
+      };
+    }
+    throw error;
+  } finally {
+    store.dispose();
+  }
+}

package/src/domains/graphql/operations/createSchemaServer.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { EX_NAMESPACE, GRAPHQL_CLEAN_TTL } from "#testing";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import createSchemaServer, { type SchemaServer } from "./createSchemaServer.js";
+
+const PREFIXES = { ...PREFIX_MAP, ex: EX_NAMESPACE };
+
+describe("createSchemaServer", () => {
+  let server: SchemaServer | undefined;
+
+  afterEach(() => {
+    server?.dispose();
+    server = undefined;
+  });
+
+  it("compiles inline sources and serves an introspectable schema", async () => {
+    server = await createSchemaServer({
+      sources: [
+        { content: GRAPHQL_CLEAN_TTL, format: "turtle", path: "clean.ttl" },
+      ],
+      prefixes: PREFIXES,
+    });
+
+    const response = await server.handler(
+      new Request("http://localhost/graphql", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          query: "{ __schema { queryType { name } } }",
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as {
+      data?: { __schema?: { queryType?: { name?: string } } };
+    };
+    expect(body.data?.__schema?.queryType?.name).toBe("Query");
+    expect(Array.isArray(server.diagnostics)).toBe(true);
+  });
+
+  it("throws a STORE_ERROR on invalid TTL", async () => {
+    await expect(
+      createSchemaServer({
+        sources: [{ content: "not turtle .", format: "turtle", path: "x.ttl" }],
+        prefixes: PREFIXES,
+      }),
+    ).rejects.toMatchObject({ code: "STORE_ERROR" });
+  });
+});

package/src/domains/graphql/operations/createSchemaServer.ts

@@ -0,0 +1,75 @@
+/**
+ * Boot a persistent ke store over in-memory TTL sources with the
+ * ke-graphql schema plugin attached, and build the `/http` fetch handler
+ * (GraphiQL + GraphQL, CORS, incremental delivery) over the compiled
+ * schema. The caller owns the returned `dispose`.
+ *
+ * @note Impure — boots a ke store (WASM + TTL) and compiles the schema.
+ */
+
+import { createStore, type InlineSource, type Plugin } from "@canonical/ke";
+import {
+  createSchemaPlugin,
+  type Diagnostic,
+  type SchemaPluginApi,
+} from "@canonical/ke-graphql";
+import { createGraphQLHandler } from "@canonical/ke-graphql/http";
+import { PragmaError } from "#error";
+
+export interface CreateSchemaServerOptions {
+  /** In-memory TTL sources to load into the store. */
+  readonly sources: readonly InlineSource[];
+  /** Prefix map handed to both the ke store and the compiler. */
+  readonly prefixes: Readonly<Record<string, string>>;
+}
+
+export interface SchemaServer {
+  /** Runtime-neutral fetch handler over the compiled schema. */
+  readonly handler: ReturnType<typeof createGraphQLHandler>;
+  /** Compiler diagnostics produced while building the schema. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Releases the underlying ke store. */
+  readonly dispose: () => void;
+}
+
+export default async function createSchemaServer(
+  options: CreateSchemaServerOptions,
+): Promise<SchemaServer> {
+  const plugin = createSchemaPlugin({ incremental: true });
+
+  let store: Awaited<ReturnType<typeof createStore>>;
+  try {
+    store = await createStore({
+      sources: [...options.sources],
+      prefixes: options.prefixes,
+      // biome-ignore lint/suspicious/noExplicitAny: Plugin generic variance
+      plugins: [plugin as Plugin<any>],
+    });
+  } catch (error) {
+    throw PragmaError.storeError(
+      error instanceof Error ? error.message : String(error),
+      { recovery: { message: "Check the TTL syntax of the sources." } },
+    );
+  }
+
+  const api = store.api<SchemaPluginApi>("ke-graphql");
+  if (!api) {
+    store.dispose();
+    throw PragmaError.storeError("ke-graphql plugin did not register its API", {
+      recovery: { message: "This is an internal error; please report it." },
+    });
+  }
+
+  const handler = createGraphQLHandler(api.schema, {
+    context: () => api.createContext(store),
+    graphiql: true,
+    cors: true,
+    incremental: true,
+  });
+
+  return {
+    handler,
+    diagnostics: api.diagnostics,
+    dispose: () => store.dispose(),
+  };
+}

package/src/domains/graphql/operations/index.ts

@@ -0,0 +1,12 @@
+/** @module Barrel for graphql operations. */
+
+export type {
+  CompileSchemaOptions,
+  CompileSchemaResult,
+} from "./compileSchema.js";
+export { default as compileSchema } from "./compileSchema.js";
+export type {
+  CreateSchemaServerOptions,
+  SchemaServer,
+} from "./createSchemaServer.js";
+export { default as createSchemaServer } from "./createSchemaServer.js";

package/src/domains/graphql/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Type definitions for the graphql domain.
+ *
+ * The compile report is the shared output shape for `graphql build` and
+ * `graphql check`: the full diagnostic list plus source and artifact
+ * metadata, rendered by the report formatters.
+ */
+
+import type { Diagnostic } from "@canonical/ke-graphql";
+
+/** Artifact paths written by `pragma graphql build`. */
+export interface GraphqlArtifacts {
+  /** Absolute path of the written GraphQL SDL file. */
+  readonly sdl: string;
+  /** Absolute path of the written extraction artifact. */
+  readonly extraction: string;
+}
+
+/** Output shape rendered by `graphql build` and `graphql check`. */
+export interface GraphqlCompileReport {
+  /** All compiler diagnostics (errors, warnings, info). */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Resolved absolute TTL file paths that were compiled. */
+  readonly files: readonly string[];
+  /** Combined fingerprint of the raw TTL source contents. */
+  readonly sourcesHash: string;
+  /** Written artifact paths (present only for a successful `build`). */
+  readonly artifacts?: GraphqlArtifacts;
+}