@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,5 +0,0 @@
-/** @module Barrel for graphql command builders. */
-
-export { default as buildCommand } from "./build.js";
-export { default as checkCommand } from "./check.js";
-export { default as serveCommand } from "./serve.js";

package/src/domains/graphql/commands/serve.test.ts

@@ -1,40 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import type { PragmaContext } from "../../shared/context.js";
-import serveCommand, { readPort } from "./serve.js";
-
-describe("readPort", () => {
-  it("parses a valid port", () => {
-    expect(readPort("4001")).toBe(4001);
-  });
-
-  it("falls back to the default for non-string values", () => {
-    expect(readPort(undefined)).toBe(4000);
-    expect(readPort(4001)).toBe(4000);
-  });
-
-  it("falls back to the default for out-of-range or unparseable values", () => {
-    expect(readPort("0")).toBe(4000);
-    expect(readPort("70000")).toBe(4000);
-    expect(readPort("not-a-port")).toBe(4000);
-  });
-});
-
-describe("graphql serve command", () => {
-  const ctx = { cwd: process.cwd() } as PragmaContext;
-  const original = (globalThis as Record<string, unknown>).Bun;
-
-  afterEach(() => {
-    (globalThis as Record<string, unknown>).Bun = original;
-  });
-
-  it("requires the Bun runtime", async () => {
-    (globalThis as Record<string, unknown>).Bun = undefined;
-
-    await expect(serveCommand.execute({}, ctx)).rejects.toMatchObject({
-      code: "STORE_ERROR",
-      recovery: {
-        message: "Run the compiled `pragma` binary or use `bun run`.",
-      },
-    });
-  });
-});

package/src/domains/graphql/commands/serve.ts

@@ -1,131 +0,0 @@
-import {
-  type CommandDefinition,
-  type CommandResult,
-  createOutputResult,
-} from "@canonical/cli-core";
-import { PragmaError } from "#error";
-import { DEFAULT_PORT } from "../constants.js";
-import { gatherSources, parsePrefixes } from "../helpers/index.js";
-import routeGraphql from "../helpers/routeGraphql.js";
-import createSchemaServer, {
-  type SchemaServer,
-} from "../operations/createSchemaServer.js";
-
-/** Narrow an unknown param to a string array. */
-function readStringArray(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value.filter((item): item is string => typeof item === "string")
-    : [];
-}
-
-/** Parse the --port flag, falling back to the default on anything invalid. */
-export function readPort(value: unknown): number {
-  if (typeof value !== "string") {
-    return DEFAULT_PORT;
-  }
-  const port = Number.parseInt(value, 10);
-  return Number.isInteger(port) && port > 0 && port < 65536
-    ? port
-    : DEFAULT_PORT;
-}
-
-/**
- * Listen on `port` and block until the process is interrupted, then stop
- * the server and dispose the store.
- *
- * @note Impure — opens a network listener and registers signal handlers.
- */
-/* v8 ignore start -- the live Bun.serve listener and signal loop run under `pragma graphql serve`, not unit tests */
-async function listen(server: SchemaServer, port: number): Promise<void> {
-  const httpServer = Bun.serve({
-    port,
-    fetch: (request) => routeGraphql(request, server.handler, port),
-  });
-  await new Promise<void>((resolve) => {
-    const shutdown = (): void => {
-      httpServer.stop();
-      server.dispose();
-      resolve();
-    };
-    process.once("SIGINT", shutdown);
-    process.once("SIGTERM", shutdown);
-  });
-}
-/* v8 ignore stop */
-
-/**
- * Builds the `pragma graphql serve` command definition.
- *
- * Compiles the configured ontologies (or explicit TTL sources) and serves
- * a local GraphQL + GraphiQL endpoint until interrupted. With no positional
- * sources it serves every TTL across the semantic packages in
- * `pragma.config.json`.
- */
-const serveCommand: CommandDefinition = {
-  path: ["graphql", "serve"],
-  description:
-    "Serve a local GraphQL + GraphiQL endpoint over the configured ontologies",
-  parameters: [
-    {
-      name: "sources",
-      description:
-        "TTL files or globs to serve (default: the configured semantic packages)",
-      type: "multiselect",
-      positional: true,
-    },
-    {
-      name: "port",
-      description: `Port to listen on (default ${DEFAULT_PORT})`,
-      type: "string",
-    },
-    {
-      name: "prefix",
-      description: "Ontology prefix as name=namespace (repeatable)",
-      type: "multiselect",
-    },
-  ],
-  meta: {
-    examples: [
-      "pragma graphql serve",
-      "pragma graphql serve ontology.ttl --port 4001",
-    ],
-  },
-  async execute(params, ctx): Promise<CommandResult> {
-    if (typeof Bun === "undefined") {
-      throw PragmaError.storeError(
-        "`pragma graphql serve` requires the Bun runtime.",
-        {
-          recovery: {
-            message: "Run the compiled `pragma` binary or use `bun run`.",
-          },
-        },
-      );
-    }
-
-    const sources = await gatherSources(
-      readStringArray(params.sources),
-      ctx.cwd,
-    );
-    const prefixes = parsePrefixes(readStringArray(params.prefix));
-    const port = readPort(params.port);
-
-    const server = await createSchemaServer({ sources, prefixes });
-    const errorCount = server.diagnostics.filter(
-      (d) => d.severity === "error",
-    ).length;
-    process.stdout.write(
-      `[ke-graphql] schema compiled — ${server.diagnostics.length} diagnostic(s)${
-        errorCount > 0 ? `, ${errorCount} error(s)` : ""
-      }\n[ke-graphql] GraphiQL on http://localhost:${port}/graphql (Ctrl-C to stop)\n`,
-    );
-
-    await listen(server, port);
-
-    return createOutputResult(
-      { port, diagnostics: server.diagnostics },
-      { plain: () => `Stopped the graphql server on port ${port}.` },
-    );
-  },
-};
-
-export default serveCommand;

package/src/domains/graphql/constants.ts

@@ -1,10 +0,0 @@
-/** Default port `pragma graphql serve` listens on. */
-const DEFAULT_PORT = 4000;
-
-/** Default output path for the SDL written by `pragma graphql build`. */
-const DEFAULT_SDL_PATH = "./schema.graphql";
-
-/** Default output path for the extraction artifact written by `pragma graphql build`. */
-const DEFAULT_EXTRACTION_PATH = "./extraction.json";
-
-export { DEFAULT_EXTRACTION_PATH, DEFAULT_PORT, DEFAULT_SDL_PATH };

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

@@ -1,3 +0,0 @@
-/** @module Barrel for graphql formatters. */
-
-export { default as reportFormatters } from "./report.js";

package/src/domains/graphql/formatters/report.ts

@@ -1,78 +0,0 @@
-import type { Diagnostic } from "@canonical/ke-graphql";
-import chalk from "chalk";
-import type { Formatters } from "../../shared/formatters.js";
-import type { GraphqlCompileReport } from "../types.js";
-
-/** Count diagnostics of one severity. */
-function countSeverity(
-  diagnostics: readonly Diagnostic[],
-  severity: Diagnostic["severity"],
-): number {
-  return diagnostics.filter((d) => d.severity === severity).length;
-}
-
-/** Pluralize a count: `1 error`, `2 errors`. */
-function plural(count: number, word: string): string {
-  return `${count} ${word}${count !== 1 ? "s" : ""}`;
-}
-
-/** One-line summary of diagnostic counts and compiled sources. */
-function summaryLine(report: GraphqlCompileReport): string {
-  const errors = countSeverity(report.diagnostics, "error");
-  const warnings = countSeverity(report.diagnostics, "warning");
-  const infos = countSeverity(report.diagnostics, "info");
-  return `${plural(report.files.length, "source file")}: ${plural(errors, "error")}, ${plural(warnings, "warning")}, ${infos} info`;
-}
-
-function colorSeverity(severity: Diagnostic["severity"]): string {
-  if (severity === "error") return chalk.red(severity);
-  if (severity === "warning") return chalk.yellow(severity);
-  return chalk.dim(severity);
-}
-
-/**
- * Formatters for `pragma graphql build` and `pragma graphql check` output.
- *
- * - **plain**: one line per diagnostic (severity, code, message, source),
- *   a summary line with counts, and `Wrote <path>` lines for artifacts.
- * - **llm**: condensed Markdown under a `## GraphQL Compile` heading.
- * - **json**: serialized {@link GraphqlCompileReport} as indented JSON.
- */
-const formatters: Formatters<GraphqlCompileReport> = {
-  plain(report) {
-    const lines = report.diagnostics.map(
-      (d) =>
-        `${colorSeverity(d.severity)} ${chalk.bold(d.code)}: ${d.message}${d.source ? ` (${d.source})` : ""}`,
-    );
-    lines.push(summaryLine(report));
-    if (report.artifacts) {
-      lines.push(`Wrote ${report.artifacts.sdl}`);
-      lines.push(`Wrote ${report.artifacts.extraction}`);
-    }
-    return lines.join("\n");
-  },
-
-  llm(report) {
-    const lines = ["## GraphQL Compile", ""];
-    for (const d of report.diagnostics) {
-      lines.push(
-        `- **${d.severity}** \`${d.code}\`: ${d.message}${d.source ? ` (\`${d.source}\`)` : ""}`,
-      );
-    }
-    if (report.diagnostics.length > 0) {
-      lines.push("");
-    }
-    lines.push(`**Summary:** ${summaryLine(report)}`);
-    if (report.artifacts) {
-      lines.push(`**SDL:** \`${report.artifacts.sdl}\``);
-      lines.push(`**Extraction:** \`${report.artifacts.extraction}\``);
-    }
-    return lines.join("\n");
-  },
-
-  json(report) {
-    return JSON.stringify(report, null, 2);
-  },
-};
-
-export default formatters;

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

@@ -1,92 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { GRAPHQL_CLEAN_TTL } from "#testing";
-import resolveConfiguredGraphs from "../../shared/resolveConfiguredGraphs.js";
-import gatherSources from "./gatherSources.js";
-
-vi.mock("../../shared/resolveConfiguredGraphs.js", () => ({
-  default: vi.fn(),
-}));
-
-const mockResolve = vi.mocked(resolveConfiguredGraphs);
-
-describe("gatherSources", () => {
-  let dir: string;
-
-  beforeEach(() => {
-    dir = mkdtempSync(join(tmpdir(), "pragma-gather-"));
-    writeFileSync(join(dir, "a.ttl"), GRAPHQL_CLEAN_TTL);
-    writeFileSync(join(dir, "b.ttl"), GRAPHQL_CLEAN_TTL);
-    mockResolve.mockReset();
-  });
-
-  afterEach(() => {
-    rmSync(dir, { recursive: true, force: true });
-  });
-
-  it("reads explicit files into inline sources, ignoring the config", async () => {
-    const sources = await gatherSources(["a.ttl"], dir);
-
-    expect(sources).toEqual([
-      {
-        content: GRAPHQL_CLEAN_TTL,
-        format: "turtle",
-        path: join(dir, "a.ttl"),
-      },
-    ]);
-    expect(mockResolve).not.toHaveBeenCalled();
-  });
-
-  it("expands glob patterns", async () => {
-    const sources = await gatherSources(["*.ttl"], dir);
-
-    expect(sources.map((source) => source.path).sort()).toEqual([
-      join(dir, "a.ttl"),
-      join(dir, "b.ttl"),
-    ]);
-  });
-
-  it("throws when explicit sources match nothing", async () => {
-    await expect(gatherSources(["none-*.ttl"], dir)).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      recovery: {
-        message: "No files matched the given paths or glob patterns.",
-      },
-    });
-  });
-
-  it("falls back to the configured package graphs when no sources are given", async () => {
-    mockResolve.mockResolvedValue([
-      {
-        path: "definitions/ontology.ttl",
-        content: GRAPHQL_CLEAN_TTL,
-        format: "turtle",
-      },
-    ]);
-
-    const sources = await gatherSources([], dir);
-
-    expect(mockResolve).toHaveBeenCalledWith(dir);
-    expect(sources).toEqual([
-      {
-        content: GRAPHQL_CLEAN_TTL,
-        format: "turtle",
-        path: "definitions/ontology.ttl",
-      },
-    ]);
-  });
-
-  it("throws when no sources are given and no packages resolve", async () => {
-    mockResolve.mockResolvedValue([]);
-
-    await expect(gatherSources([], dir)).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      recovery: {
-        message:
-          "No TTL sources given and no semantic packages resolved. Pass TTL files or globs, or configure `packages` in pragma.config.json and install them.",
-      },
-    });
-  });
-});

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

@@ -1,58 +0,0 @@
-/**
- * Resolve the TTL sources for a graphql command.
- *
- * When positional paths or globs are given they win; otherwise the sources
- * are the union of every configured semantic package's graphs (the
- * `pragma.config.json` packages, falling back to the defaults). Either way
- * the result is a list of ke `InlineSource`s (content + provenance path),
- * so the compiler and the dev server load the exact same bytes.
- *
- * @note Impure — reads files and resolves packages from disk.
- *
- * @param positional - Explicit TTL file paths or glob patterns (may be empty).
- * @param cwd - Working directory for file and config resolution.
- * @returns In-memory TTL sources to compile or serve.
- * @throws PragmaError (INVALID_INPUT) when nothing resolves.
- */
-
-import { readFileSync } from "node:fs";
-import type { InlineSource } from "@canonical/ke";
-import { PragmaError } from "#error";
-import resolveConfiguredGraphs from "../../shared/resolveConfiguredGraphs.js";
-import resolveSourceFiles from "./resolveSourceFiles.js";
-
-export default async function gatherSources(
-  positional: readonly string[],
-  cwd: string,
-): Promise<InlineSource[]> {
-  if (positional.length > 0) {
-    const files = resolveSourceFiles([...positional], cwd);
-    if (files.length === 0) {
-      throw PragmaError.invalidInput("sources", positional.join(", "), {
-        recovery: {
-          message: "No files matched the given paths or glob patterns.",
-        },
-      });
-    }
-    return files.map((path) => ({
-      content: readFileSync(path, "utf-8"),
-      format: "turtle" as const,
-      path,
-    }));
-  }
-
-  const graphs = await resolveConfiguredGraphs(cwd);
-  if (graphs.length === 0) {
-    throw PragmaError.invalidInput("sources", "(none)", {
-      recovery: {
-        message:
-          "No TTL sources given and no semantic packages resolved. Pass TTL files or globs, or configure `packages` in pragma.config.json and install them.",
-      },
-    });
-  }
-  return graphs.map((graph) => ({
-    content: graph.content,
-    format: graph.format,
-    path: graph.path,
-  }));
-}

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

@@ -1,6 +0,0 @@
-/** @module Barrel for graphql helpers. */
-
-export { default as gatherSources } from "./gatherSources.js";
-export { default as parsePrefixes } from "./parsePrefixes.js";
-export { default as resolveSourceFiles } from "./resolveSourceFiles.js";
-export { default as routeGraphql } from "./routeGraphql.js";

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

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

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

@@ -1,56 +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")]);
-  });
-});

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

@@ -1,45 +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 { 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

@@ -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();
-  });
-});