@canonical/pragma-cli 0.27.0 → 0.29.0

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

@@ -0,0 +1,139 @@
+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 structured error when sources are missing", async () => {
+    const ctx = makeCtx();
+
+    await expect(checkCommand.execute({}, ctx)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: {
+        message: "Provide at least one TTL file or glob pattern.",
+      },
+    });
+  });
+});

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

@@ -0,0 +1,87 @@
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createExitResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { PragmaError } from "#error";
+import { selectFormatter } from "../../shared/formatters.js";
+import { reportFormatters } from "../formatters/index.js";
+import { 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 source files or glob patterns",
+      type: "multiselect",
+      positional: true,
+      required: 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 = readStringArray(params.sources);
+    if (sources.length === 0) {
+      throw PragmaError.invalidInput("sources", "(empty)", {
+        recovery: {
+          message: "Provide at least one TTL file or glob pattern.",
+        },
+      });
+    }
+
+    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,4 @@
+/** @module Barrel for graphql command builders. */
+
+export { default as buildCommand } from "./build.js";
+export { default as checkCommand } from "./check.js";

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/index.ts

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

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/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @module GraphQL domain barrel.
+ *
+ * Compiles TTL ontologies into GraphQL schema artifacts via the
+ * ke-graphql pipeline. Commands boot their own ke store from explicit
+ * TTL sources, so they run on the store-skip pipeline path.
+ */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import { buildCommand, checkCommand } from "./commands/index.js";
+
+/**
+ * Returns all command definitions for the graphql domain.
+ *
+ * @returns An array of command definitions (`graphql build`, `graphql check`).
+ */
+export function commands(): CommandDefinition[] {
+  return [buildCommand, checkCommand];
+}
+
+export { compileSchema } from "./operations/index.js";

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

@@ -0,0 +1,119 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hashSources } from "@canonical/ke-graphql";
+import { afterEach, beforeEach, 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 };
+
+describe("compileSchema", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "pragma-graphql-compile-"));
+    writeFileSync(join(dir, "clean.ttl"), GRAPHQL_CLEAN_TTL);
+    writeFileSync(join(dir, "error.ttl"), GRAPHQL_ERROR_TTL);
+    writeFileSync(join(dir, "fatal.ttl"), GRAPHQL_FATAL_TTL);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("compiles a clean ontology into SDL", async () => {
+    const outcome = await compileSchema({
+      sources: ["clean.ttl"],
+      prefixes: PREFIXES,
+      cwd: dir,
+    });
+
+    expect(outcome.status).toBe("ok");
+    expect(outcome.compiled?.sdl).toContain("type Thing");
+    expect(outcome.diagnostics).toEqual([]);
+    expect(outcome.files).toEqual([join(dir, "clean.ttl")]);
+  });
+
+  it("hashes the exact raw file contents", async () => {
+    const outcome = await compileSchema({
+      sources: ["clean.ttl"],
+      prefixes: PREFIXES,
+      cwd: dir,
+    });
+
+    const raw = readFileSync(join(dir, "clean.ttl"), "utf-8");
+    expect(outcome.sourcesHash).toBe(hashSources([raw]));
+  });
+
+  it("resolves glob patterns to source files", async () => {
+    const outcome = await compileSchema({
+      sources: ["clean*.ttl"],
+      prefixes: PREFIXES,
+      cwd: dir,
+    });
+
+    expect(outcome.status).toBe("ok");
+    expect(outcome.files).toEqual([join(dir, "clean.ttl")]);
+  });
+
+  it("surfaces error diagnostics without failing the compile", async () => {
+    const outcome = await compileSchema({
+      sources: ["error.ttl"],
+      prefixes: PREFIXES,
+      cwd: dir,
+    });
+
+    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: ["fatal.ttl"],
+      prefixes: PREFIXES,
+      cwd: dir,
+    });
+
+    expect(outcome.status).toBe("failed");
+    expect(outcome.compiled).toBeUndefined();
+    expect(
+      outcome.diagnostics.some(
+        (d) => d.severity === "error" && d.code === "C003",
+      ),
+    ).toBe(true);
+  });
+
+  it("throws structured error when no sources resolve", async () => {
+    await expect(
+      compileSchema({
+        sources: ["missing.ttl"],
+        prefixes: PREFIXES,
+        cwd: dir,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_INPUT" });
+  });
+
+  it("throws structured error on invalid TTL syntax", async () => {
+    writeFileSync(join(dir, "broken.ttl"), "this is not turtle .");
+
+    await expect(
+      compileSchema({
+        sources: ["broken.ttl"],
+        prefixes: PREFIXES,
+        cwd: dir,
+      }),
+    ).rejects.toMatchObject({ code: "STORE_ERROR" });
+  });
+});