@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/graph/formatters/inspect.ts

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import { formatHeading } from "#pipeline";
 import compactUri from "../../shared/compactUri.js";
 import type { Formatters } from "../../shared/formatters.js";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import type { InspectResult } from "../../shared/types/index.js";
 
 /**
@@ -15,13 +15,13 @@ import type { InspectResult } from "../../shared/types/index.js";
 const formatters: Formatters<InspectResult> = {
   plain(result) {
     const lines: string[] = [];
-    lines.push(formatHeading(compactUri(result.uri, PREFIX_MAP)));
+    lines.push(formatHeading(compactUri(result.uri, DEFAULT_PREFIX_MAP)));
 
     for (const g of result.groups) {
       lines.push("");
-      lines.push(chalk.bold(compactUri(g.predicate, PREFIX_MAP)));
+      lines.push(chalk.bold(compactUri(g.predicate, DEFAULT_PREFIX_MAP)));
       for (const o of g.objects) {
-        lines.push(`  ${compactUri(o, PREFIX_MAP)}`);
+        lines.push(`  ${compactUri(o, DEFAULT_PREFIX_MAP)}`);
       }
     }
 
@@ -30,13 +30,13 @@ const formatters: Formatters<InspectResult> = {
 
   llm(result) {
     const lines = [
-      `## ${compactUri(result.uri, PREFIX_MAP)} (${result.uri})`,
+      `## ${compactUri(result.uri, DEFAULT_PREFIX_MAP)} (${result.uri})`,
       "",
     ];
     for (const g of result.groups) {
-      lines.push(`**${compactUri(g.predicate, PREFIX_MAP)}:**`);
+      lines.push(`**${compactUri(g.predicate, DEFAULT_PREFIX_MAP)}:**`);
       for (const o of g.objects) {
-        lines.push(`  - ${compactUri(o, PREFIX_MAP)}`);
+        lines.push(`  - ${compactUri(o, DEFAULT_PREFIX_MAP)}`);
       }
     }
     return lines.join("\n");

package/src/domains/graph/formatters/query.test.ts

@@ -0,0 +1,87 @@
+import type { QueryResult } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import formatters from "./query.js";
+
+const selectResult = {
+  type: "select",
+  bindings: [
+    { s: "a", n: "1" },
+    { s: "b", n: "2" },
+  ],
+} as unknown as QueryResult;
+
+const emptySelect = {
+  type: "select",
+  bindings: [],
+} as unknown as QueryResult;
+
+const askResult = { type: "ask", result: true } as unknown as QueryResult;
+
+const constructResult = {
+  type: "construct",
+  triples: [
+    { subject: "s1", predicate: "p1", object: "line one\nline two" },
+    { subject: "s2", predicate: "p2", object: "o2" },
+  ],
+} as unknown as QueryResult;
+
+const emptyConstruct = {
+  type: "construct",
+  triples: [],
+} as unknown as QueryResult;
+
+describe("graph query formatters — plain", () => {
+  it("renders SELECT as a tab table", () => {
+    const text = formatters.plain(selectResult);
+    expect(text.split("\n")).toEqual(["s\tn", "a\t1", "b\t2"]);
+  });
+
+  it("reports no results for an empty SELECT", () => {
+    expect(formatters.plain(emptySelect)).toBe("No results.");
+  });
+
+  it("renders ASK as a boolean", () => {
+    expect(formatters.plain(askResult)).toBe("ASK: true");
+  });
+
+  it("renders CONSTRUCT as one-line triples", () => {
+    const text = formatters.plain(constructResult);
+    expect(text).toContain("s1\tp1\tline one line two");
+    expect(text).toContain("s2\tp2\to2");
+  });
+
+  it("reports no triples for an empty CONSTRUCT", () => {
+    expect(formatters.plain(emptyConstruct)).toBe("No triples.");
+  });
+});
+
+describe("graph query formatters — llm", () => {
+  it("renders SELECT as a Markdown table", () => {
+    const text = formatters.llm(selectResult);
+    expect(text).toContain("| s | n |");
+    expect(text).toContain("| --- | --- |");
+    expect(text).toContain("| a | 1 |");
+  });
+
+  it("renders an empty SELECT as italic no-results", () => {
+    expect(formatters.llm(emptySelect)).toBe("_No results._");
+  });
+
+  it("renders ASK as bold", () => {
+    expect(formatters.llm(askResult)).toBe("**ASK** → true");
+  });
+
+  it("renders CONSTRUCT triples as a bullet list", () => {
+    const text = formatters.llm(constructResult);
+    expect(text).toContain("- s1\tp1\tline one line two");
+  });
+});
+
+describe("graph query formatters — json", () => {
+  it("serializes the raw result", () => {
+    expect(JSON.parse(formatters.json(askResult))).toMatchObject({
+      type: "ask",
+      result: true,
+    });
+  });
+});

package/src/domains/graph/formatters/query.ts

@@ -1,12 +1,33 @@
 import type { QueryResult } from "@canonical/ke";
 import type { Formatters } from "../../shared/formatters.js";
 
+/**
+ * Render CONSTRUCT triples as readable `subject  predicate  object` lines,
+ * collapsing any newlines in literal objects so each triple stays on one line.
+ */
+function formatTriples(
+  triples: ReadonlyArray<{
+    subject: string;
+    predicate: string;
+    object: string;
+  }>,
+): string {
+  if (triples.length === 0) return "No triples.";
+  return triples
+    .map((t) => {
+      const object = t.object.replace(/\s*\n\s*/g, " ").trim();
+      return `${t.subject}\t${t.predicate}\t${object}`;
+    })
+    .join("\n");
+}
+
 /**
  * Formatters for `pragma graph query` output.
  *
- * - **plain**: tab-separated table for SELECT results, `ASK: true/false` for ASK
- *   queries, JSON fallback for CONSTRUCT.
- * - **llm**: indented JSON for all query types.
+ * - **plain**: tab-separated table for SELECT, `ASK: true/false` for ASK, and
+ *   readable triple lines for CONSTRUCT.
+ * - **llm**: condensed Markdown (table for SELECT, one line for ASK, a triple
+ *   list for CONSTRUCT) rather than a raw JSON dump.
  * - **json**: serialized {@link QueryResult} as indented JSON.
  */
 const formatters: Formatters<QueryResult> = {
@@ -22,11 +43,27 @@ const formatters: Formatters<QueryResult> = {
     if (result.type === "ask") {
       return `ASK: ${String(result.result)}`;
     }
-    return JSON.stringify(result, null, 2);
+    return formatTriples(result.triples);
   },
 
   llm(result) {
-    return JSON.stringify(result, null, 2);
+    if (result.type === "select") {
+      if (result.bindings.length === 0) return "_No results._";
+      const cols = Object.keys(result.bindings[0] ?? {});
+      const header = `| ${cols.join(" | ")} |`;
+      const divider = `| ${cols.map(() => "---").join(" | ")} |`;
+      const rows = result.bindings.map(
+        (b) => `| ${cols.map((c) => b[c] ?? "").join(" | ")} |`,
+      );
+      return [header, divider, ...rows].join("\n");
+    }
+    if (result.type === "ask") {
+      return `**ASK** → ${String(result.result)}`;
+    }
+    return formatTriples(result.triples)
+      .split("\n")
+      .map((line) => (line.includes("\t") ? `- ${line}` : line))
+      .join("\n");
   },
 
   json(result) {

package/src/domains/graph/helpers/resolveUri.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import resolveUri from "./resolveUri.js";
+
+const prefixes = {
+  ds: "https://ds.canonical.com/",
+  cs: "http://pragma.canonical.com/codestandards#",
+} as const;
+
+describe("resolveUri", () => {
+  it("expands a registered prefix", () => {
+    expect(resolveUri("ds:UIBlock", prefixes)).toBe(
+      "https://ds.canonical.com/UIBlock",
+    );
+  });
+
+  it("passes through a full http(s) IRI", () => {
+    expect(resolveUri("https://ds.canonical.com/global", prefixes)).toBe(
+      "https://ds.canonical.com/global",
+    );
+  });
+
+  it("passes through a urn: IRI", () => {
+    expect(resolveUri("urn:isbn:0451450523", prefixes)).toBe(
+      "urn:isbn:0451450523",
+    );
+  });
+
+  it("passes through a foreign scheme:// IRI", () => {
+    expect(resolveUri("ftp://example.org/thing", prefixes)).toBe(
+      "ftp://example.org/thing",
+    );
+  });
+
+  it("throws for an unknown prefix", () => {
+    expect(() => resolveUri("unknown:something", prefixes)).toThrow(
+      PragmaError,
+    );
+  });
+
+  it("throws for a bare string without a prefix", () => {
+    expect(() => resolveUri("button", prefixes)).toThrow(PragmaError);
+  });
+
+  it("throws for an IRI with unsafe characters", () => {
+    expect(() =>
+      resolveUri("https://example.com/<injected>", prefixes),
+    ).toThrow(PragmaError);
+  });
+});

package/src/domains/graph/helpers/resolveUri.ts

@@ -6,12 +6,20 @@ import { PragmaError } from "#error";
  */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
 
+/**
+ * Matches a general absolute IRI: any scheme with an authority (`scheme://…`,
+ * covering http, https, ftp, ws, and foreign schemes) or a `urn:` opaque IRI.
+ * Broader than an http(s)-only check so foreign ontologies resolve.
+ */
+const ABSOLUTE_IRI_PATTERN = /^(?:[A-Za-z][A-Za-z0-9+.-]*:\/\/|urn:)\S/i;
+
 /**
  * Resolves a potentially prefixed URI (e.g. `ds:UIBlock`) to a full URI.
  *
- * If the URI is already a full URI (starts with `http`), validates IRI safety
- * and returns it as-is. Otherwise, expands the prefix using the provided
- * prefix map.
+ * A registered prefix always wins: `ds:UIBlock` expands via the prefix map.
+ * Otherwise a general absolute IRI (`scheme://…` or `urn:…`) is validated and
+ * returned as-is, so foreign ontologies are not rejected as unknown prefixes.
+ * Any other `token:rest` is treated as an unknown prefix.
  *
  * @param uri - A full or prefixed URI string.
  * @param prefixes - Registered prefix-to-namespace mapping from the store.
@@ -22,11 +30,6 @@ export default function resolveUri(
   uri: string,
   prefixes: Readonly<Record<string, string>>,
 ): string {
-  if (uri.startsWith("http://") || uri.startsWith("https://")) {
-    assertSafeIri(uri);
-    return uri;
-  }
-
   const colonIdx = uri.indexOf(":");
   if (colonIdx === -1) {
     throw PragmaError.invalidInput("uri", uri, {
@@ -38,23 +41,27 @@ export default function resolveUri(
   }
 
   const prefix = uri.slice(0, colonIdx);
-  const localName = uri.slice(colonIdx + 1);
   const namespace = prefixes[prefix];
 
-  if (namespace === undefined) {
-    throw PragmaError.invalidInput("prefix", prefix, {
-      validOptions: Object.keys(prefixes),
-      recovery: {
-        message: "List known ontology prefixes.",
-        cli: "pragma ontology list",
-        mcp: { tool: "ontology_list" },
-      },
-    });
+  if (namespace !== undefined) {
+    const resolved = `${namespace}${uri.slice(colonIdx + 1)}`;
+    assertSafeIri(resolved);
+    return resolved;
+  }
+
+  if (ABSOLUTE_IRI_PATTERN.test(uri)) {
+    assertSafeIri(uri);
+    return uri;
   }
 
-  const resolved = `${namespace}${localName}`;
-  assertSafeIri(resolved);
-  return resolved;
+  throw PragmaError.invalidInput("prefix", prefix, {
+    validOptions: Object.keys(prefixes),
+    recovery: {
+      message: "List known ontology prefixes.",
+      cli: "pragma ontology list",
+      mcp: { tool: "ontology_list" },
+    },
+  });
 }
 
 /**

package/src/domains/graph/operations/inspectUri.test.ts

@@ -2,7 +2,7 @@ import type { Store } from "@canonical/ke";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { PragmaError } from "#error";
 import { createTestStore, DS_ALL_TTL } from "#testing";
-import { P, PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP, P } from "../../shared/prefixes.js";
 import inspectUri from "./inspectUri.js";
 
 let store: Store;
@@ -19,7 +19,7 @@ afterAll(() => cleanup());
 describe("inspectUri", () => {
   it("returns grouped triples for a known URI", async () => {
     const result = await inspectUri(store, `${P.ds}global.component.button`);
-    expect(result.uri).toBe(`${PREFIX_MAP.ds}global.component.button`);
+    expect(result.uri).toBe(`${DEFAULT_PREFIX_MAP.ds}global.component.button`);
     expect(result.groups.length).toBeGreaterThan(0);
 
     const predicates = result.groups.map((g) => g.predicate);
@@ -30,15 +30,15 @@ describe("inspectUri", () => {
 
   it("resolves prefixed URIs", async () => {
     const result = await inspectUri(store, `${P.ds}global.component.button`);
-    expect(result.uri).toBe(`${PREFIX_MAP.ds}global.component.button`);
+    expect(result.uri).toBe(`${DEFAULT_PREFIX_MAP.ds}global.component.button`);
   });
 
   it("accepts full URIs", async () => {
     const result = await inspectUri(
       store,
-      `${PREFIX_MAP.ds}global.component.button`,
+      `${DEFAULT_PREFIX_MAP.ds}global.component.button`,
     );
-    expect(result.uri).toBe(`${PREFIX_MAP.ds}global.component.button`);
+    expect(result.uri).toBe(`${DEFAULT_PREFIX_MAP.ds}global.component.button`);
     expect(result.groups.length).toBeGreaterThan(0);
   });
 

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

@@ -181,13 +181,15 @@ describe("graphql build command", () => {
     expect(printed).toContain("C003");
   });
 
-  it("throws structured error when sources are missing", async () => {
+  it("throws a structured error when explicit sources match nothing", async () => {
     const ctx = makeCtx();
 
-    await expect(buildCommand.execute({}, ctx)).rejects.toMatchObject({
+    await expect(
+      buildCommand.execute({ sources: ["no-such-*.ttl"] }, ctx),
+    ).rejects.toMatchObject({
       code: "INVALID_INPUT",
       recovery: {
-        message: "Provide at least one TTL file or glob pattern.",
+        message: "No files matched the given paths or glob patterns.",
       },
     });
   });

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

@@ -7,16 +7,13 @@ import {
   createOutputResult,
 } from "@canonical/cli-core";
 import { serializeExtraction } from "@canonical/ke-graphql";
-import { PragmaError } from "#error";
 import { selectFormatter } from "../../shared/formatters.js";
+import { DEFAULT_EXTRACTION_PATH, DEFAULT_SDL_PATH } from "../constants.js";
 import { reportFormatters } from "../formatters/index.js";
-import { parsePrefixes } from "../helpers/index.js";
+import { gatherSources, 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)
@@ -37,10 +34,10 @@ const buildCommand: CommandDefinition = {
   parameters: [
     {
       name: "sources",
-      description: "TTL source files or glob patterns",
+      description:
+        "TTL files or globs (default: the configured semantic packages)",
       type: "multiselect",
       positional: true,
-      required: true,
     },
     {
       name: "sdl",
@@ -68,15 +65,10 @@ const buildCommand: CommandDefinition = {
     ],
   },
   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 sources = await gatherSources(
+      readStringArray(params.sources),
+      ctx.cwd,
+    );
     const prefixes = parsePrefixes(readStringArray(params.prefix));
     const outcome = await compileSchema({ sources, prefixes, cwd: ctx.cwd });
     const format = selectFormatter(ctx, reportFormatters);

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

@@ -126,13 +126,15 @@ describe("graphql check command", () => {
     expect(parsed.artifacts).toBeUndefined();
   });
 
-  it("throws structured error when sources are missing", async () => {
+  it("throws a structured error when explicit sources match nothing", async () => {
     const ctx = makeCtx();
 
-    await expect(checkCommand.execute({}, ctx)).rejects.toMatchObject({
+    await expect(
+      checkCommand.execute({ sources: ["no-such-*.ttl"] }, ctx),
+    ).rejects.toMatchObject({
       code: "INVALID_INPUT",
       recovery: {
-        message: "Provide at least one TTL file or glob pattern.",
+        message: "No files matched the given paths or glob patterns.",
       },
     });
   });

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

@@ -4,10 +4,9 @@ import {
   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 { gatherSources, parsePrefixes } from "../helpers/index.js";
 import { compileSchema } from "../operations/index.js";
 import type { GraphqlCompileReport } from "../types.js";
 
@@ -31,10 +30,10 @@ const checkCommand: CommandDefinition = {
   parameters: [
     {
       name: "sources",
-      description: "TTL source files or glob patterns",
+      description:
+        "TTL files or globs (default: the configured semantic packages)",
       type: "multiselect",
       positional: true,
-      required: true,
     },
     {
       name: "prefix",
@@ -49,15 +48,10 @@ const checkCommand: CommandDefinition = {
     ],
   },
   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 sources = await gatherSources(
+      readStringArray(params.sources),
+      ctx.cwd,
+    );
     const prefixes = parsePrefixes(readStringArray(params.prefix));
     const outcome = await compileSchema({ sources, prefixes, cwd: ctx.cwd });
 

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

@@ -2,3 +2,4 @@
 
 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,46 @@
+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`.",
+      },
+    });
+  });
+});