@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/setup/operations/setupLsp.test.ts

@@ -18,8 +18,9 @@ describe("setupLsp", () => {
   it("logs info messages before and after exec", () => {
     const result = dryRun(setupLsp("/project"));
     const logs = result.effects.filter((e) => e._tag === "Log");
-    expect(logs.some((l) => l.message.includes("Installing"))).toBe(true);
-    expect(logs.some((l) => l.message.includes("✓"))).toBe(true);
+    expect(logs.some((l) => l.message.includes("Ensuring"))).toBe(true);
+    // Reports an idempotent "up to date" outcome, not a fresh install claim.
+    expect(logs.some((l) => l.message.includes("up to date"))).toBe(true);
   });
 
   it("collects effects without execution", () => {

package/src/domains/setup/operations/setupLsp.ts

@@ -10,8 +10,13 @@ import { $, exec, gen, info, type Task } from "@canonical/task";
  */
 export default function setupLsp(root: string): Task<void> {
   return gen(function* () {
-    yield* $(info("Installing Terrazzo LSP extension for VS Code..."));
+    yield* $(
+      info("Ensuring the Terrazzo LSP VS Code extension is installed..."),
+    );
+    // The extension installer is idempotent — it installs if missing and is a
+    // no-op if already present — so this reports "ensured", not a fresh install
+    // (pragma does not inspect VS Code's extension state to tell them apart).
     yield* $(exec("bunx", ["@canonical/terrazzo-lsp-extension"], root));
-    yield* $(info("✓ Terrazzo LSP extension installed."));
+    yield* $(info("✓ Terrazzo LSP extension is installed (up to date)."));
   });
 }

package/src/domains/setup/operations/setupMcp.test.ts

@@ -10,7 +10,12 @@ const mockExists =
 function mocks(
   existsPredicate: (path: string) => boolean,
 ): Map<string, (effect: Effect) => unknown> {
-  return new Map([["Exists", mockExists(existsPredicate)]]);
+  return new Map<string, (effect: Effect) => unknown>([
+    ["Exists", mockExists(existsPredicate)],
+    // An existing config reads back as an empty-but-valid JSON object, so a
+    // write merges into it rather than failing closed on the dry-run placeholder.
+    ["ReadFile", () => "{}"],
+  ]);
 }
 
 describe("setupMcp", () => {

package/src/domains/shared/bootStore.bareCore.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Bare-core boot — pragma must serve the generic `graph`, `graphql`, and
+ * `ontology` surfaces with zero semantic packages loaded. This pins the P0
+ * invariant that the core no longer depends on the design-system packages:
+ * a store booted with no packages resolves generic queries and each
+ * generic operation returns cleanly instead of crashing.
+ */
+
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { EX_NAMESPACE, GRAPHQL_CLEAN_TTL } from "#testing";
+import inspectUri from "../graph/operations/inspectUri.js";
+import compileSchema from "../graphql/operations/compileSchema.js";
+import listOntologies from "../ontology/operations/listOntologies.js";
+import { bootStore } from "./bootStore.js";
+import { PREFIX_MAP, resolvePrefixes } from "./prefixes.js";
+
+let store: Store;
+
+beforeAll(async () => {
+  // The `sources` override boots with zero resolved packages (bare core).
+  const boot = await bootStore({ sources: [] });
+  store = boot.store;
+  expect(boot.packages).toEqual([]);
+});
+
+afterAll(() => store?.dispose());
+
+describe("bare-core boot", () => {
+  it("carries the generic core prefixes on the store", () => {
+    expect(store.prefixes.rdf).toBe(PREFIX_MAP.rdf);
+    expect(store.prefixes.owl).toBe(PREFIX_MAP.owl);
+  });
+
+  it("serves generic SPARQL without any packages loaded", async () => {
+    const result = await store.query(
+      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }",
+    );
+    expect(result.type).toBe("select");
+  });
+
+  it("serves `ontology` — listOntologies returns cleanly, not a crash", async () => {
+    await expect(listOntologies(store)).resolves.toEqual([]);
+  });
+
+  it("serves `graph` — inspecting an unknown URI reports not-found, not a crash", async () => {
+    await expect(
+      inspectUri(store, "https://example.org/nothing"),
+    ).rejects.toMatchObject({ code: "ENTITY_NOT_FOUND" });
+  });
+
+  it("serves `graphql` — compiles a generic ontology with core-only prefixes", async () => {
+    const outcome = await compileSchema({
+      sources: [
+        { content: GRAPHQL_CLEAN_TTL, format: "turtle", path: "x.ttl" },
+      ],
+      // Package-style prefix layered over the bare core — no DS packages.
+      prefixes: resolvePrefixes([{ prefixes: { ex: EX_NAMESPACE } }]),
+    });
+    expect(outcome.status).toBe("ok");
+    expect(outcome.compiled?.sdl).toContain("type Thing");
+  });
+});

package/src/domains/shared/bootStore.test.ts

@@ -0,0 +1,82 @@
+import { createStore } from "@canonical/ke";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createGraphLoaderPlugin } from "./bootStore.js";
+
+const PREFIXES = { ds: "https://ds.canonical.com/" };
+
+const goodGraph = (path: string, subject: string) => ({
+  path,
+  content: `@prefix ds: <https://ds.canonical.com/>.\nds:${subject} a ds:Component.\n`,
+  format: "turtle" as const,
+});
+
+/** Mirrors the malformed `ds:hasSubcomponent ds:global..` shipped by upstream. */
+const badGraph = (path: string) => ({
+  path,
+  content:
+    "@prefix ds: <https://ds.canonical.com/>.\nds:global.component.broken a ds:Component;\n    ds:hasSubcomponent ds:global...\n",
+  format: "turtle" as const,
+});
+
+async function countTriples(
+  graphs: readonly ReturnType<typeof goodGraph>[],
+): Promise<number> {
+  const store = await createStore({
+    sources: [],
+    prefixes: PREFIXES,
+    plugins: [createGraphLoaderPlugin(graphs)],
+  });
+  // Always dispose the WASM-backed store so it can't leak across tests.
+  try {
+    const result = await store.query(
+      "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }",
+    );
+    return Number(
+      result.type === "select" ? (result.bindings[0]?.n ?? "0") : "0",
+    );
+  } finally {
+    store.dispose();
+  }
+}
+
+let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+  stderrSpy.mockRestore();
+});
+
+const stderrText = (): string =>
+  stderrSpy.mock.calls.map((call) => String(call[0])).join("");
+
+describe("createGraphLoaderPlugin", () => {
+  it("loads every graph when all are well-formed", async () => {
+    const count = await countTriples([
+      goodGraph("a.ttl", "global.component.a"),
+      goodGraph("b.ttl", "global.component.b"),
+    ]);
+    expect(count).toBe(2);
+    expect(stderrText()).toBe("");
+  });
+
+  it("skips a malformed graph but still boots and loads the good ones", async () => {
+    const count = await countTriples([
+      goodGraph("a.ttl", "global.component.a"),
+      badGraph("data/global/component/broken.ttl"),
+      goodGraph("b.ttl", "global.component.b"),
+    ]);
+    // The two good graphs load; the malformed one is skipped, not fatal.
+    expect(count).toBe(2);
+  });
+
+  it("warns with the offending file path and parse error", async () => {
+    await countTriples([badGraph("data/global/component/broken.ttl")]);
+    const text = stderrText();
+    expect(text).toContain("skipping malformed graph");
+    expect(text).toContain("data/global/component/broken.ttl");
+    expect(text).toContain("Check the TTL syntax");
+  });
+});

package/src/domains/shared/bootStore.ts

@@ -23,7 +23,7 @@ import {
   createLocalLoader,
 } from "./loaders/index.js";
 import { DEFAULT_PACKAGES } from "./packages.js";
-import { PREFIX_MAP } from "./prefixes.js";
+import { resolvePrefixes } from "./prefixes.js";
 import type { GraphContent, SemanticPackage } from "./semanticPackage.js";
 import { resolveSemanticPackages } from "./semanticPackage.js";
 
@@ -38,6 +38,8 @@ export interface BootStoreOptions {
   refs?: ReadonlyArray<PackageRef>;
   /** Enable query tracing (from config). Env var PRAGMA_TRACE=1 overrides. */
   trace?: boolean;
+  /** Additional namespace prefixes merged over the built-in prefix map. */
+  prefixes?: Readonly<Record<string, string>>;
 }
 
 export interface BootResult {
@@ -60,11 +62,13 @@ export async function bootStore(
   options: BootStoreOptions = {},
 ): Promise<BootResult> {
   try {
-    // Testing/programmatic override — use explicit sources
+    // Testing/programmatic override — use explicit sources. No packages are
+    // resolved, so the prefix map is the core base plus the transitional DS
+    // fallback and any caller override.
     if (options.sources) {
       const store = await createStore({
         sources: options.sources,
-        prefixes: PREFIX_MAP,
+        prefixes: resolvePrefixes([], options.prefixes),
         cache: options.cache,
         cwd: options.cwd,
       });
@@ -87,19 +91,11 @@ export async function bootStore(
     // Collect all graph content from resolved packages
     const allGraphs = packages.flatMap((pkg) => pkg.graphs);
 
-    // Use a ke plugin to load graph content during store creation.
-    // The onReady hook has access to ctx.load() which loads raw content.
-    const graphLoaderPlugin = definePlugin({
-      name: "pragma-graph-loader",
-      onReady(ctx) {
-        for (const graph of allGraphs) {
-          ctx.load(graph.content, { format: graph.format });
-        }
-      },
-    });
-
-    // biome-ignore lint: Plugin generic variance requires explicit unknown
-    const plugins: Plugin<any>[] = [graphLoaderPlugin];
+    // `Plugin<T>` is invariant in its API type and createStore expects
+    // `Plugin<void>[]`, so heterogeneous plugins (graph loader + trace) can only
+    // share an array via `any`. `unknown` does not satisfy `Plugin<void>`.
+    // biome-ignore lint/suspicious/noExplicitAny: intentional — see above
+    const plugins: Plugin<any>[] = [createGraphLoaderPlugin(allGraphs)];
     const traceEnabled =
       process.env.PRAGMA_TRACE === "1" || options.trace === true;
     if (traceEnabled) {
@@ -108,9 +104,12 @@ export async function bootStore(
       plugins.push(createTracePlugin({ traceDir: traceDir() }));
     }
 
+    // Merge every resolved package's declared prefixes (and the transitional
+    // DS fallback) over the generic core, then config overrides — so the
+    // store and every query see the packages' own namespaces.
     const store = await createStore({
       sources: [],
-      prefixes: PREFIX_MAP,
+      prefixes: resolvePrefixes(packages, options.prefixes),
       cache: options.cache,
       cwd: options.cwd,
       plugins,
@@ -124,9 +123,49 @@ export async function bootStore(
       {
         recovery: {
           message:
-            "Ensure design system packages are installed: bun add -D @canonical/design-system @canonical/code-standards @canonical/anatomy-dsl",
+            "If this is a parser error, check the TTL syntax of the source graphs " +
+            "(the message above names the line and column). Otherwise ensure design " +
+            "system packages are installed: bun add -D @canonical/design-system " +
+            "@canonical/code-standards @canonical/anatomy-dsl",
         },
       },
     );
   }
 }
+
+/**
+ * Build the ke plugin that loads resolved graph content into the store.
+ *
+ * Each graph is loaded independently inside its own try/catch: a single
+ * malformed TTL file (e.g. invalid Turtle emitted by an upstream authoring
+ * tool) must not abort the entire boot and take the whole CLI down with it.
+ * Failed graphs are skipped and surfaced as warnings, mirroring the
+ * resilience the story loader already provides ("one bad file cannot break
+ * boot"). A store built from N-1 good graphs is far more useful than a store
+ * that refuses to boot because of one bad graph.
+ *
+ * @note Impure — writes warnings to stderr on parse failure.
+ */
+export function createGraphLoaderPlugin(
+  graphs: readonly GraphContent[],
+): Plugin {
+  return definePlugin({
+    name: "pragma-graph-loader",
+    onReady(ctx) {
+      for (const graph of graphs) {
+        try {
+          ctx.load(graph.content, { format: graph.format });
+        } catch (error) {
+          const reason = error instanceof Error ? error.message : String(error);
+          // Name the offending file and the parse error, and point at the fix.
+          // The store still boots from the remaining graphs, so this is a
+          // warning, not a fatal error.
+          process.stderr.write(
+            `Warning: skipping malformed graph "${graph.path}" — ${reason}. ` +
+              "Check the TTL syntax of this source file; the remaining graphs still load.\n",
+          );
+        }
+      }
+    },
+  });
+}

package/src/domains/shared/compactUri.test.ts

@@ -18,4 +18,15 @@ describe("compactUri", () => {
       "https://example.com/thing",
     );
   });
+
+  it("picks the longest matching namespace when namespaces overlap", () => {
+    const overlapping = {
+      base: "https://ex.org/",
+      sub: "https://ex.org/sub/",
+    } as const;
+    // Both `base` and `sub` are prefixes of the URI; the longer wins.
+    expect(compactUri("https://ex.org/sub/Thing", overlapping)).toBe(
+      "sub:Thing",
+    );
+  });
 });

package/src/domains/shared/compactUri.ts

@@ -1,16 +1,21 @@
 /**
- * Convert a full URI to its compact prefixed form when a matching prefix exists.
- * Falls back to the original URI when no namespace matches.
+ * Convert a full URI to its compact prefixed form using the longest matching
+ * namespace. When two registered namespaces are both prefixes of the URI
+ * (e.g. a base namespace and a sub-namespace), the longer — more specific —
+ * one wins. Falls back to the original URI when no namespace matches.
  */
 export default function compactUri(
   fullUri: string,
   prefixes: Readonly<Record<string, string>>,
 ): string {
+  let best: { prefix: string; namespace: string } | undefined;
   for (const [prefix, namespace] of Object.entries(prefixes)) {
-    if (fullUri.startsWith(namespace)) {
-      return `${prefix}:${fullUri.slice(namespace.length)}`;
+    if (!fullUri.startsWith(namespace)) continue;
+    if (best === undefined || namespace.length > best.namespace.length) {
+      best = { prefix, namespace };
     }
   }
 
-  return fullUri;
+  if (best === undefined) return fullUri;
+  return `${best.prefix}:${fullUri.slice(best.namespace.length)}`;
 }

package/src/domains/shared/context.ts

@@ -7,10 +7,10 @@
  * cli-core remains unaware of Store or FilterConfig.
  */
 
-import type { GlobalFlags, InteractiveHandler } from "@canonical/cli-core";
+import type { GlobalFlags, PromptSessionFactory } from "@canonical/cli-core";
 import type { PragmaRuntime } from "./types/index.js";
 
 export interface PragmaContext extends PragmaRuntime {
   readonly globalFlags: GlobalFlags;
-  readonly interactive?: InteractiveHandler | undefined;
+  readonly promptSession?: PromptSessionFactory | undefined;
 }

package/src/domains/shared/contracts.ts

@@ -50,6 +50,15 @@ export interface ListResult<T> {
     | { readonly level: "detailed" };
 }
 
+/** Aggregate metadata about a multi-query lookup. */
+export interface LookupResultMeta {
+  /**
+   * Number of queries that failed with an unexpected (non-Pragma) error.
+   * Each such failure is also present in `errors` with code `INTERNAL_ERROR`.
+   */
+  readonly internalErrorCount: number;
+}
+
 export interface LookupResult<T> {
   readonly results: readonly T[];
   readonly errors: readonly {
@@ -58,6 +67,8 @@ export interface LookupResult<T> {
     message: string;
     suggestions?: readonly string[];
   }[];
+  /** Populated by `lookupMany`; may be absent on hand-built results. */
+  readonly meta?: LookupResultMeta;
 }
 
 export interface ShowContract<T> {