@canonical/pragma-cli 0.27.0 → 0.29.0

package/src/domains/doctor/operations/checks/checkPackageRefs.ts

@@ -1,19 +1,20 @@
 /**
  * Doctor check: report how each semantic package is resolved.
  *
- * Shows whether packages resolve from npm, file://, or git cache,
- * and warns if a configured ref is missing its cache.
+ * Uses the loader chain (local > git > bundled) to show where each
+ * package resolves from, its version, and graph/skill counts.
  */
 
-import { existsSync } from "node:fs";
 import { readConfig } from "#config";
-import {
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../../../refs/operations/parseRef.js";
-import { gitCacheDir } from "../../../refs/operations/paths.js";
+import { parsePackageEntry } from "../../../refs/operations/parseRef.js";
 import readGlobalRefs from "../../../refs/operations/readGlobalRefs.js";
+import {
+  createBundledLoader,
+  createGitLoader,
+  createLocalLoader,
+} from "../../../shared/loaders/index.js";
 import { DEFAULT_PACKAGES } from "../../../shared/packages.js";
+import { resolveSemanticPackages } from "../../../shared/semanticPackage.js";
 import type { CheckContext, CheckResult } from "../types.js";
 
 export default async function checkPackageRefs(
@@ -23,46 +24,39 @@ export default async function checkPackageRefs(
   const globalEntries = readGlobalRefs();
 
   const hasProjectRefs = config.packages && config.packages.length > 0;
-  const hasGlobalRefs = globalEntries.length > 0;
 
-  if (!hasProjectRefs && !hasGlobalRefs) {
-    return {
-      name: "package refs",
-      status: "pass",
-      detail: `${DEFAULT_PACKAGES.length} packages (all npm, defaults)`,
-    };
-  }
+  const rawEntries = hasProjectRefs
+    ? config.packages!
+    : globalEntries.length > 0
+      ? globalEntries
+      : DEFAULT_PACKAGES;
 
-  const entries: ReadonlyArray<RawPackageEntry> =
-    config.packages ?? globalEntries;
+  const refs = [...rawEntries].map(parsePackageEntry);
+  const loaders = [
+    createLocalLoader(),
+    createGitLoader(),
+    createBundledLoader(),
+  ];
+  const packages = await resolveSemanticPackages(refs, loaders);
 
   const details: string[] = [];
   let hasIssue = false;
 
-  for (const entry of entries) {
-    const ref = parsePackageEntry(entry);
+  for (const ref of refs) {
+    const resolved = packages.find((p) => p.name === ref.pkg);
 
-    switch (ref.kind) {
-      case "npm":
-        details.push(`${ref.pkg}: npm`);
-        break;
-      case "file":
-        if (existsSync(ref.path)) {
-          details.push(`${ref.pkg}: file (${ref.path})`);
-        } else {
-          details.push(`${ref.pkg}: file MISSING (${ref.path})`);
-          hasIssue = true;
-        }
-        break;
-      case "git": {
-        const cached = existsSync(gitCacheDir(ref.pkg, ref.ref));
-        if (cached) {
-          details.push(`${ref.pkg}: git #${ref.ref} (cached)`);
-        } else {
-          details.push(`${ref.pkg}: git #${ref.ref} NOT CACHED`);
-          hasIssue = true;
-        }
-        break;
+    if (resolved) {
+      details.push(
+        `${ref.pkg}: ${resolved.source} v${resolved.version} (${resolved.graphs.length} graphs, ${resolved.skills.length} skills)`,
+      );
+    } else {
+      // Check if covered by bundled fallback
+      const bundled = packages.find((p) => p.name === "(bundled)");
+      if (bundled) {
+        details.push(`${ref.pkg}: bundled v${bundled.version}`);
+      } else {
+        details.push(`${ref.pkg}: NOT RESOLVED`);
+        hasIssue = true;
       }
     }
   }

package/src/domains/doctor/operations/checks.test.ts

@@ -75,7 +75,10 @@ describe("checkKeStore", () => {
       query: vi.fn(),
       dispose: vi.fn(),
     };
-    vi.mocked(bootStore).mockResolvedValue(mockStore as never);
+    vi.mocked(bootStore).mockResolvedValue({
+      store: mockStore,
+      packages: [],
+    } as never);
     vi.mocked(collectStoreSummary).mockResolvedValue({
       tripleCount: 12847,
       graphNames: [],

package/src/domains/doctor/operations/runChecks.test.ts

@@ -22,6 +22,7 @@ import {
   checkSkillsSymlinked,
 } from "./checks/index.js";
 import runChecks from "./runChecks.js";
+import type { CheckResult } from "./types.js";
 
 const pass = (name: string) => ({
   name,
@@ -92,4 +93,75 @@ describe("runChecks", () => {
     expect(data.checks[4].name).toBe("store");
     expect(data.checks[7].name).toBe("skills");
   });
+
+  it("preserves order even when checks resolve out of order", async () => {
+    const delayed = (result: CheckResult, ms: number) =>
+      new Promise<CheckResult>((resolve) =>
+        setTimeout(() => resolve(result), ms),
+      );
+
+    // Resolve the first check slowest and the last fastest to prove the report
+    // order follows declaration order, not completion order.
+    vi.mocked(checkNodeVersion).mockReturnValue(delayed(pass("Node"), 30));
+    vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
+    vi.mocked(checkConfigFile).mockResolvedValue(pass("config"));
+    vi.mocked(checkPackageRefs).mockResolvedValue(pass("refs"));
+    vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
+    vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
+    vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkSkillsSymlinked).mockReturnValue(delayed(pass("skills"), 0));
+
+    const data = await runChecks({ cwd: "/test" });
+    expect(data.checks.map((c) => c.name)).toEqual([
+      "Node",
+      "pragma",
+      "config",
+      "refs",
+      "store",
+      "completions",
+      "mcp",
+      "skills",
+    ]);
+  });
+
+  it("surfaces a thrown check as an attributable fail instead of aborting", async () => {
+    vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
+    vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
+    vi.mocked(checkConfigFile).mockRejectedValue(new Error("disk on fire"));
+    vi.mocked(checkPackageRefs).mockResolvedValue(pass("refs"));
+    vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
+    vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
+    vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
+
+    const data = await runChecks({ cwd: "/test" });
+
+    // The whole run still completes; the thrown check becomes a fail in place.
+    expect(data.checks).toHaveLength(8);
+    expect(data.passed).toBe(7);
+    expect(data.failed).toBe(1);
+    const failed = data.checks[2];
+    expect(failed.status).toBe("fail");
+    // Fallback name matches checkConfigFile's own `name` so a thrown check
+    // reports the same label as a normal pass/fail.
+    expect(failed.name).toBe("pragma.config.json");
+    expect(failed.detail).toContain("disk on fire");
+    expect(failed.remedy).toBeDefined();
+  });
+
+  it("handles a non-Error rejection without crashing", async () => {
+    vi.mocked(checkNodeVersion).mockResolvedValue(pass("Node"));
+    vi.mocked(checkPragmaVersion).mockResolvedValue(pass("pragma"));
+    vi.mocked(checkConfigFile).mockResolvedValue(pass("config"));
+    vi.mocked(checkPackageRefs).mockResolvedValue(pass("refs"));
+    vi.mocked(checkKeStore).mockRejectedValue("string failure");
+    vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
+    vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
+
+    const data = await runChecks({ cwd: "/test" });
+    expect(data.failed).toBe(1);
+    expect(data.checks[4].name).toBe("ke store");
+    expect(data.checks[4].detail).toContain("string failure");
+  });
 });

package/src/domains/doctor/operations/runChecks.ts

@@ -11,8 +11,35 @@ import {
 import type { CheckContext, CheckResult, DoctorData } from "./types.js";
 
 /**
- * Orchestrate all environment health checks sequentially and return
- * a DoctorData summary with pass/fail/skip counts.
+ * Each check paired with the display name used if it rejects. The checks are
+ * mutually independent, so they run concurrently; this list also fixes the
+ * stable display order of the results. The fallback name must match the
+ * `name` each check returns on success, so a thrown check reports the same
+ * label as a normal pass/fail and stays correlatable.
+ */
+function buildChecks(
+  ctx: CheckContext,
+): readonly [string, Promise<CheckResult>][] {
+  return [
+    ["Node version", checkNodeVersion()],
+    ["pragma version", checkPragmaVersion()],
+    ["pragma.config.json", checkConfigFile(ctx)],
+    ["package refs", checkPackageRefs(ctx)],
+    ["ke store", checkKeStore(ctx)],
+    ["Shell completions", checkShellCompletions()],
+    ["MCP configured", checkMcpConfigured(ctx)],
+    ["Skills symlinked", checkSkillsSymlinked(ctx)],
+  ];
+}
+
+/**
+ * Orchestrate all environment health checks concurrently and return a
+ * DoctorData summary with pass/fail/skip counts.
+ *
+ * Checks run concurrently; results are collected in declaration order so the
+ * report is deterministic. A check that throws is surfaced as a fail (rather
+ * than aborting `pragma doctor`), tagged with the check's name so the failure
+ * remains attributable.
  *
  * @param ctx - Check context containing the working directory.
  * @returns Aggregated check results.
@@ -21,16 +48,25 @@ import type { CheckContext, CheckResult, DoctorData } from "./types.js";
 export default async function runChecks(
   ctx: CheckContext,
 ): Promise<DoctorData> {
-  const checks: CheckResult[] = [];
-
-  checks.push(await checkNodeVersion());
-  checks.push(await checkPragmaVersion());
-  checks.push(await checkConfigFile(ctx));
-  checks.push(await checkPackageRefs(ctx));
-  checks.push(await checkKeStore(ctx));
-  checks.push(await checkShellCompletions());
-  checks.push(await checkMcpConfigured(ctx));
-  checks.push(await checkSkillsSymlinked(ctx));
+  // buildChecks starts every check eagerly, so they run concurrently; each is
+  // guarded so a thrown check becomes an attributable fail rather than
+  // rejecting the whole run. Mapping preserves declaration order.
+  const checks: CheckResult[] = await Promise.all(
+    buildChecks(ctx).map(async ([name, promise]): Promise<CheckResult> => {
+      try {
+        return await promise;
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+          name,
+          status: "fail",
+          detail: `Check threw an unexpected error: ${reason}`,
+          remedy:
+            "Re-run `pragma doctor`; if it persists, report this as a bug.",
+        };
+      }
+    }),
+  );
 
   const passed = checks.filter((c) => c.status === "pass").length;
   const failed = checks.filter((c) => c.status === "fail").length;

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

@@ -0,0 +1,194 @@
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CommandDefinition } from "@canonical/cli-core";
+import { hashSources } from "@canonical/ke-graphql";
+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 buildCommand from "./build.js";
+
+let dir: string;
+let stdoutSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "pragma-graphql-build-"));
+  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;
+}
+
+async function executeOutput(
+  cmd: CommandDefinition,
+  params: Record<string, unknown>,
+  ctx: PragmaContext,
+): Promise<{ value: GraphqlCompileReport; text: string }> {
+  const result = await cmd.execute(params, ctx);
+  expect(result.tag).toBe("output");
+  if (result.tag !== "output") throw new Error("Expected output result");
+  return {
+    value: result.value as GraphqlCompileReport,
+    text: result.render.plain(result.value),
+  };
+}
+
+describe("graphql build command", () => {
+  it("writes the SDL and extraction artifacts to the default paths", async () => {
+    const ctx = makeCtx();
+    const { value } = await executeOutput(
+      buildCommand,
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    const sdl = readFileSync(join(dir, "schema.graphql"), "utf-8");
+    expect(sdl).toContain("type Thing");
+
+    const artifact = JSON.parse(
+      readFileSync(join(dir, "extraction.json"), "utf-8"),
+    ) as { version: number; sourcesHash: string };
+    expect(artifact.version).toBe(1);
+
+    const raw = readFileSync(join(dir, "clean.ttl"), "utf-8");
+    expect(artifact.sourcesHash).toBe(hashSources([raw]));
+    expect(value.artifacts).toEqual({
+      sdl: join(dir, "schema.graphql"),
+      extraction: join(dir, "extraction.json"),
+    });
+  });
+
+  it("writes artifacts to custom --sdl and --extraction paths", async () => {
+    const ctx = makeCtx();
+    await executeOutput(
+      buildCommand,
+      {
+        sources: ["clean.ttl"],
+        prefix: [EX_PREFIX_ENTRY],
+        sdl: "out/api.graphql",
+        extraction: "out/api-extraction.json",
+      },
+      ctx,
+    );
+
+    expect(readFileSync(join(dir, "out", "api.graphql"), "utf-8")).toContain(
+      "type Thing",
+    );
+    expect(
+      JSON.parse(
+        readFileSync(join(dir, "out", "api-extraction.json"), "utf-8"),
+      ),
+    ).toMatchObject({ version: 1 });
+  });
+
+  it("renders plain output with a summary and artifact paths", async () => {
+    const ctx = makeCtx();
+    const { text } = await executeOutput(
+      buildCommand,
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(text).toContain("1 source file: 0 errors, 0 warnings, 0 info");
+    expect(text).toContain(`Wrote ${join(dir, "schema.graphql")}`);
+    expect(text).toContain(`Wrote ${join(dir, "extraction.json")}`);
+  });
+
+  it("prints error diagnostics but still writes artifacts", async () => {
+    const ctx = makeCtx();
+    const { text } = await executeOutput(
+      buildCommand,
+      { sources: ["error.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(text).toContain("M001");
+    expect(text).toContain("1 error");
+    expect(existsSync(join(dir, "schema.graphql"))).toBe(true);
+    expect(existsSync(join(dir, "extraction.json"))).toBe(true);
+  });
+
+  it("renders llm output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const { text } = await executeOutput(
+      buildCommand,
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    expect(text).toContain("## GraphQL Compile");
+    expect(text).toContain("**Summary:**");
+  });
+
+  it("renders json output", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: false, format: "json" as const, verbose: false },
+    });
+    const { text } = await executeOutput(
+      buildCommand,
+      { sources: ["clean.ttl"], prefix: [EX_PREFIX_ENTRY] },
+      ctx,
+    );
+
+    const parsed = JSON.parse(text) as GraphqlCompileReport;
+    expect(parsed.diagnostics).toEqual([]);
+    expect(parsed.files).toEqual([join(dir, "clean.ttl")]);
+  });
+
+  it("exits non-zero and writes no artifacts when compilation fails", async () => {
+    const ctx = makeCtx();
+    const result = await buildCommand.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(existsSync(join(dir, "schema.graphql"))).toBe(false);
+    expect(existsSync(join(dir, "extraction.json"))).toBe(false);
+
+    const printed = stdoutSpy.mock.calls.map((call) => call[0]).join("");
+    expect(printed).toContain("C003");
+  });
+
+  it("throws structured error when sources are missing", async () => {
+    const ctx = makeCtx();
+
+    await expect(buildCommand.execute({}, ctx)).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      recovery: {
+        message: "Provide at least one TTL file or glob pattern.",
+      },
+    });
+  });
+});

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

@@ -0,0 +1,125 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createExitResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { serializeExtraction } from "@canonical/ke-graphql";
+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";
+
+const DEFAULT_SDL_PATH = "./schema.graphql";
+const DEFAULT_EXTRACTION_PATH = "./extraction.json";
+
+/** 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 build` command definition.
+ *
+ * Compiles TTL sources into a GraphQL schema, writes the SDL and the
+ * extraction artifact, and prints all compiler diagnostics. Exits
+ * non-zero when schema composition fails.
+ */
+const buildCommand: CommandDefinition = {
+  path: ["graphql", "build"],
+  description: "Compile TTL sources into GraphQL schema artifacts",
+  parameters: [
+    {
+      name: "sources",
+      description: "TTL source files or glob patterns",
+      type: "multiselect",
+      positional: true,
+      required: true,
+    },
+    {
+      name: "sdl",
+      description: "Output path for the GraphQL SDL",
+      type: "string",
+      default: DEFAULT_SDL_PATH,
+    },
+    {
+      name: "extraction",
+      description: "Output path for the extraction artifact",
+      type: "string",
+      default: DEFAULT_EXTRACTION_PATH,
+    },
+    {
+      name: "prefix",
+      description: "Ontology prefix as name=namespace (repeatable)",
+      type: "multiselect",
+    },
+  ],
+  meta: {
+    examples: [
+      "pragma graphql build ontology.ttl",
+      'pragma graphql build "data/*.ttl" --sdl out/schema.graphql --extraction out/extraction.json',
+      "pragma graphql build ontology.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 format = selectFormatter(ctx, reportFormatters);
+
+    if (outcome.status === "failed" || !outcome.compiled) {
+      const report: GraphqlCompileReport = {
+        diagnostics: outcome.diagnostics,
+        files: outcome.files,
+        sourcesHash: outcome.sourcesHash,
+      };
+      process.stdout.write(`${format(report)}\n`);
+      return createExitResult(1);
+    }
+
+    const sdlPath = resolve(
+      ctx.cwd,
+      typeof params.sdl === "string" ? params.sdl : DEFAULT_SDL_PATH,
+    );
+    const extractionPath = resolve(
+      ctx.cwd,
+      typeof params.extraction === "string"
+        ? params.extraction
+        : DEFAULT_EXTRACTION_PATH,
+    );
+
+    mkdirSync(dirname(sdlPath), { recursive: true });
+    writeFileSync(sdlPath, outcome.compiled.sdl, "utf-8");
+    mkdirSync(dirname(extractionPath), { recursive: true });
+    writeFileSync(
+      extractionPath,
+      serializeExtraction(outcome.compiled.extraction, outcome.sourcesHash),
+      "utf-8",
+    );
+
+    const report: GraphqlCompileReport = {
+      diagnostics: outcome.diagnostics,
+      files: outcome.files,
+      sourcesHash: outcome.sourcesHash,
+      artifacts: { sdl: sdlPath, extraction: extractionPath },
+    };
+
+    return createOutputResult(report, { plain: format });
+  },
+};
+
+export default buildCommand;