@canonical/pragma-cli 0.31.0 → 0.32.0

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

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

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

@@ -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,46 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-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("uses the default when the flag is absent", () => {
-    expect(readPort(undefined)).toBe(4000);
-    expect(readPort("")).toBe(4000);
-  });
-
-  it("rejects an out-of-range or unparseable provided port", () => {
-    for (const value of ["0", "70000", "not-a-port"]) {
-      expect(() => readPort(value)).toThrowError(PragmaError);
-      try {
-        readPort(value);
-      } catch (error) {
-        expect((error as PragmaError).code).toBe("INVALID_INPUT");
-      }
-    }
-  });
-});
-
-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,141 +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. A missing flag uses the default; a provided value
- * must be a valid port (1–65535), otherwise it is rejected rather than
- * silently falling back and masking the user's mistake.
- *
- * @throws PragmaError INVALID_INPUT when a provided `--port` is not a valid port.
- */
-export function readPort(value: unknown): number {
-  if (value === undefined || value === null || value === "") {
-    return DEFAULT_PORT;
-  }
-  const text = String(value).trim();
-  const port = Number(text);
-  if (!/^\d+$/.test(text) || port < 1 || port > 65535) {
-    throw PragmaError.invalidInput("port", String(value), {
-      recovery: { message: "Provide a port between 1 and 65535." },
-    });
-  }
-  return 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";