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

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

@@ -0,0 +1,141 @@
+import { mkdtempSync, readdirSync, 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 {
+  EX_PREFIX_ENTRY,
+  GRAPHQL_CLEAN_TTL,
+  GRAPHQL_ERROR_TTL,
+  GRAPHQL_FATAL_TTL,
+} from "#testing";
+import type { PragmaContext } from "../../shared/context.js";
+import type { GraphqlCompileReport } from "../types.js";
+import checkCommand from "./check.js";
+
+let dir: string;
+let stdoutSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "pragma-graphql-check-"));
+  writeFileSync(join(dir, "clean.ttl"), GRAPHQL_CLEAN_TTL);
+  writeFileSync(join(dir, "error.ttl"), GRAPHQL_ERROR_TTL);
+  writeFileSync(join(dir, "fatal.ttl"), GRAPHQL_FATAL_TTL);
+  stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+  stdoutSpy.mockRestore();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    cwd: dir,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    store: {} as PragmaContext["store"],
+    config: { tier: undefined, channel: "normal" },
+    ...overrides,
+  } as PragmaContext;
+}
+
+function printedOutput(): string {
+  return stdoutSpy.mock.calls.map((call) => call[0]).join("");
+}
+
+describe("graphql check command", () => {
+  it("passes a clean ontology with a summary line", async () => {
+    const ctx = makeCtx();
+    const result = await checkCommand.execute(
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(result.tag).toBe("output");
+    if (result.tag !== "output") throw new Error("Expected output result");
+    const text = result.render.plain(result.value);
+    expect(text).toContain("1 source file: 0 errors, 0 warnings, 0 info");
+  });
+
+  it("exits non-zero and prints diagnostics on error diagnostics", async () => {
+    const ctx = makeCtx();
+    const result = await checkCommand.execute(
+      { sources: ["error.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(result.tag).toBe("exit");
+    if (result.tag !== "exit") throw new Error("Expected exit result");
+    expect(result.code).toBe(1);
+
+    const printed = printedOutput();
+    expect(printed).toContain("M001");
+    expect(printed).toContain("error");
+    expect(printed).toContain("1 error, 2 warnings, 0 info");
+  });
+
+  it("exits non-zero when compilation fails entirely", async () => {
+    const ctx = makeCtx();
+    const result = await checkCommand.execute(
+      { sources: ["fatal.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(result.tag).toBe("exit");
+    if (result.tag !== "exit") throw new Error("Expected exit result");
+    expect(result.code).toBe(1);
+    expect(printedOutput()).toContain("C003");
+  });
+
+  it("passes with warnings when prefixes are not registered", async () => {
+    const ctx = makeCtx();
+    const result = await checkCommand.execute({ sources: ["clean.ttl"] }, ctx);
+
+    expect(result.tag).toBe("output");
+    if (result.tag !== "output") throw new Error("Expected output result");
+    const text = result.render.plain(result.value);
+    expect(text).toContain("1 warning");
+    expect(text).toContain("0 errors");
+  });
+
+  it("writes no artifacts", async () => {
+    const ctx = makeCtx();
+    const before = readdirSync(dir).sort();
+    await checkCommand.execute(
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(readdirSync(dir).sort()).toEqual(before);
+  });
+
+  it("renders json output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const result = await checkCommand.execute(
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(result.tag).toBe("output");
+    if (result.tag !== "output") throw new Error("Expected output result");
+    const parsed = JSON.parse(
+      result.render.plain(result.value),
+    ) as GraphqlCompileReport;
+    expect(parsed.diagnostics).toEqual([]);
+    expect(parsed.artifacts).toBeUndefined();
+  });
+
+  it("throws a structured error when explicit sources match nothing", async () => {
+    const ctx = makeCtx();
+
+    await expect(
+      checkCommand.execute({ sources: ["no-such-*.ttl"] }, ctx),
+    ).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: {
+        message: "No files matched the given paths or glob patterns.",
+      },
+    });
+  });
+});

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

@@ -0,0 +1,81 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createExitResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { selectFormatter } from "../../shared/formatters.js";
+import { reportFormatters } from "../formatters/index.js";
+import { gatherSources, parsePrefixes } from "../helpers/index.js";
+import { compileSchema } from "../operations/index.js";
+import type { GraphqlCompileReport } from "../types.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")
+    : [];
+}
+
+/**
+ * Builds the `pragma graphql check` command definition.
+ *
+ * Runs the same compile as `graphql build` but writes no artifacts —
+ * a CI gate. Prints all compiler diagnostics and exits non-zero when
+ * compilation fails or any error-severity diagnostic is produced.
+ */
+const checkCommand: CommandDefinition = {
+  path: ["graphql", "check"],
+  description: "Compile TTL sources and fail on error diagnostics",
+  parameters: [
+    {
+      name: "sources",
+      description:
+        "TTL files or globs (default: the configured semantic packages)",
+      type: "multiselect",
+      positional: true,
+    },
+    {
+      name: "prefix",
+      description: "Ontology prefix as name=namespace (repeatable)",
+      type: "multiselect",
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma graphql check ontology.ttl",
+      'pragma graphql check "data/*.ttl" --prefix ds=https://ds.canonical.com/',
+    ],
+  },
+  async execute(params, ctx): Promise<CommandResult> {
+    const sources = await gatherSources(
+      readStringArray(params.sources),
+      ctx.cwd,
+    );
+    const prefixes = parsePrefixes(readStringArray(params.prefix));
+    const outcome = await compileSchema({ sources, prefixes, cwd: ctx.cwd });
+
+    const report: GraphqlCompileReport = {
+      diagnostics: outcome.diagnostics,
+      files: outcome.files,
+      sourcesHash: outcome.sourcesHash,
+    };
+
+    const hasErrors =
+      outcome.status === "failed" ||
+      outcome.diagnostics.some((d) => d.severity === "error");
+
+    if (hasErrors) {
+      process.stdout.write(
+        `${selectFormatter(ctx, reportFormatters)(report)}\n`,
+      );
+      return createExitResult(1);
+    }
+
+    return createOutputResult(report, {
+      plain: selectFormatter(ctx, reportFormatters),
+    });
+  },
+};
+
+export default checkCommand;

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,6 @@
+/** @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";