@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,44 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { DEFAULT_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(DEFAULT_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(DEFAULT_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

@@ -1,38 +0,0 @@
-import { PragmaError } from "#error";
-import { DEFAULT_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 DEFAULT_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> = { ...DEFAULT_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

@@ -1,65 +0,0 @@
-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")]);
-  });
-
-  it("skips a directory path instead of treating it as a file", () => {
-    // A directory would later crash readFileSync with EISDIR.
-    expect(resolveSourceFiles(["nested"], dir)).toEqual([]);
-  });
-
-  it("resolves the empty string (the cwd directory) to no files", () => {
-    expect(resolveSourceFiles([""], dir)).toEqual([]);
-  });
-});

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

@@ -1,66 +0,0 @@
-/**
- * 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 { globSync, statSync } from "node:fs";
-import { resolve } from "node:path";
-
-/**
- * Whether a path points at an existing regular file.
- *
- * Guards against a directory (or the empty-string path, which resolves to the
- * cwd directory) slipping through as a "source" and later crashing readFileSync
- * with EISDIR.
- *
- * @param absPath - Absolute path to check.
- * @returns True when the path exists and is a regular file.
- */
-function isRegularFile(absPath: string): boolean {
-  try {
-    return statSync(absPath).isFile();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * 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 })) {
-        const absPath = resolve(cwd, file);
-        if (isRegularFile(absPath)) {
-          files.push(absPath);
-        }
-      }
-    } else {
-      const absPath = resolve(cwd, pattern);
-      if (isRegularFile(absPath)) {
-        files.push(absPath);
-      }
-    }
-  }
-
-  return files;
-}

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

@@ -1,43 +0,0 @@
-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

@@ -1,28 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-/**
- * @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

@@ -1,95 +0,0 @@
-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 { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
-import compileSchema from "./compileSchema.js";
-
-const PREFIXES = { ...DEFAULT_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

@@ -1,107 +0,0 @@
-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

@@ -1,50 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { EX_NAMESPACE, GRAPHQL_CLEAN_TTL } from "#testing";
-import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
-import createSchemaServer, { type SchemaServer } from "./createSchemaServer.js";
-
-const PREFIXES = { ...DEFAULT_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

@@ -1,75 +0,0 @@
-/**
- * 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(),
-  };
-}