@canonical/pragma-cli 0.38.0 → 0.40.0

package/src/capabilities/create/create.verb.ts

@@ -453,10 +453,12 @@ function createVerb(
   summary: string,
   params: ParamSpec[],
   examples: VerbSpec["examples"],
+  guidance: Required<Pick<VerbSpec, "useWhen" | "example">>,
 ): VerbSpec<Record<string, unknown>, GeneratorResult> {
   return {
     path: ["create", kind],
     summary,
+    ...guidance,
     params,
     output: CREATE_OUTPUT,
     examples,
@@ -507,6 +509,11 @@ export const createVerbs: Record<
         note: "preview the files without writing",
       },
     ],
+    {
+      useWhen:
+        "when asked to start a new React, Svelte or Lit component with its tests, stories and styles",
+      example: { framework: "react", componentPath: "src/components/Button" },
+    },
   ),
   package: createVerb(
     "package",
@@ -520,6 +527,10 @@ export const createVerbs: Record<
         cmd: `${BIN_NAME} create package --name @canonical/my-tool --no-run-install`,
       },
     ],
+    {
+      useWhen: "when asked to start a new npm package inside the monorepo",
+      example: { name: "@canonical/my-lib", type: "library" },
+    },
   ),
   application: createVerb(
     "application",
@@ -530,5 +541,10 @@ export const createVerbs: Record<
       { cmd: `${BIN_NAME} create application react my-app --relay` },
       { cmd: `${BIN_NAME} create application react my-app --rendering spa` },
     ],
+    {
+      useWhen:
+        "when asked to start a new React application, server-rendered or client-only",
+      example: { appPath: "my-app" },
+    },
   ),
 };

package/src/capabilities/create/createGrammar.test.ts

@@ -286,7 +286,7 @@ describe("the mounted create grammar (subprocess)", () => {
     expect(matchedEnvelope.error.suggestions).toBeUndefined();
     // D5's third route, pinned as the INVARIANT and not only the output:
     // this cli is COMPUTED at the mount (chain[0] = the root program's
-    // name), bypassing cliRecovery and invisible to copy.test.ts's
+    // name), bypassing callRecovery and invisible to copy.test.ts's
     // quoted-literal position rule — so the expectation is COMPOSED from
     // the same constant the derivation must land on. A `startsWith` check
     // behind an exact literal could never fail (the literal throws first

package/src/capabilities/distribution.test.ts

@@ -63,7 +63,7 @@ describe("the distribution's declared stories (PROTECTED)", () => {
     },
   );
 
-  it('every declared filter names "values" or a "vocabulary"', () => {
+  it('every declared filter names "values", a "vocabulary" or a "noun"', () => {
     // The rule the round-trip above already enforces, said OUT LOUD. It was
     // only implied there — a story satisfies the whole grammar or it does not,
     // and a reader looking for this particular property found no assertion
@@ -87,6 +87,7 @@ describe("the distribution's declared stories (PROTECTED)", () => {
       "implementation list --library",
       "implementation list --platform",
       "standard list --category",
+      "token consumers --block",
       "token consumers --key",
       "token consumers --state",
       "token consumers --symbol",
@@ -105,8 +106,10 @@ describe("the distribution's declared stories (PROTECTED)", () => {
     ]);
     for (const [label, filter] of filters) {
       expect(
-        filter.values !== undefined || filter.vocabulary !== undefined,
-        `${label} declares neither "values" nor a "vocabulary"`,
+        filter.values !== undefined ||
+          filter.vocabulary !== undefined ||
+          filter.noun !== undefined,
+        `${label} declares no "values", "vocabulary" or "noun"`,
       ).toBe(true);
       // And never both — a declared set IS the vocabulary.
       expect(

package/src/capabilities/distribution.ts

@@ -22,6 +22,7 @@ import conf from "../../pragma.conf.js";
 import { compileStoryModule } from "../kernel/packs/compile.js";
 import {
   distributionSource,
+  type NounLookups,
   type PackDefinition,
 } from "../kernel/packs/types.js";
 import { DEFAULT_PREFIX_MAP } from "../kernel/render/index.js";
@@ -34,6 +35,10 @@ export const declaredStories: ReadonlyMap<string, PackDefinition> = new Map(
     .map((story): readonly [string, PackDefinition] => [story.noun, story]),
 );
 
+/** The lookup each declared noun resolves names through, for a filter naming it. */
+export const declaredLookups: NounLookups = (noun) =>
+  declaredStories.get(noun)?.lookup;
+
 /**
  * Those stories compiled to capability modules, by noun.
  *
@@ -49,6 +54,7 @@ export const storyModules: ReadonlyMap<string, CapabilityModule> = new Map(
       story,
       distributionSource("pragma.conf.ts"),
       DEFAULT_PREFIX_MAP,
+      declaredLookups,
     ),
   ]),
 );

package/src/capabilities/doctor/checks/checkPackageRefs.ts

@@ -28,7 +28,10 @@ import {
 import { activeStories } from "../../../kernel/runtime/graphpack/stories.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
 import type { SourcesDecision } from "../../../kernel/runtime/resolveSources.js";
-import { resolveSources } from "../../../kernel/runtime/resolveSources.js";
+import {
+  describeIgnoredPack,
+  resolveSources,
+} from "../../../kernel/runtime/resolveSources.js";
 import type { CheckItem, CheckResult } from "../types.js";
 
 /**
@@ -148,6 +151,15 @@ export async function checkPackageRefs(
   const composition = `${packs.length} ${packs.length === 1 ? "pack" : "packs"}, ${entities} entities${suffix}`;
 
   if (decision.kind === "embedded") {
+    // A pack this project built, passed over because an older CLI built it. The
+    // check still PASSES — the snapshot is answering and its answers are the
+    // current ones — so the account of the pack goes in the detail, next to the
+    // account of what IS answering, and the remedy stays unset: there is
+    // nothing to fix, only two ways to change it, and the sentence names both.
+    const ignored =
+      decision.ignoredPack === undefined
+        ? ""
+        : ` · ${describeIgnoredPack(decision.ignoredPack)}`;
     return {
       name,
       status: "pass",
@@ -157,7 +169,7 @@ export async function checkPackageRefs(
       // neither. "shipped with the CLI" rather than "embedded snapshot" — the
       // reader needs to know where these packs came from, not what the build
       // calls the artefact.
-      detail: `shipped with the CLI — ${composition} · run \`${BIN_NAME} sources update\` to build from your own configured packs instead`,
+      detail: `shipped with the CLI — ${composition} · run \`${BIN_NAME} sources update\` to build from your own configured packs instead${ignored}`,
       ...(items.length > 0 ? { items } : {}),
     };
   }

package/src/capabilities/doctor/doctor.test.ts

@@ -16,12 +16,13 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { ConfigLayers } from "../../kernel/config/types.js";
 import { executeVerb } from "../../kernel/project/cli/dispatch.js";
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import { createQueryFacade } from "../../kernel/runtime/facade.js";
+import { activePackPath, packDir } from "../../kernel/runtime/paths.js";
 import type {
   GlobalFlags,
   LazyStore,
@@ -212,6 +213,42 @@ describe("doctor — the pack-refs check", () => {
     }
   });
 
+  it("still passes when a pack an older CLI built is passed over — and names it", async () => {
+    // The upgrade state. The check PASSES: the snapshot is answering and its
+    // answers are the current ones, so there is nothing to fix — only a pack to
+    // account for, and two ways to change it. Hence a detail, not a remedy.
+    const cwd = tmp("pragma-proj-");
+    const hash = "b".repeat(64);
+    const dir = packDir(hash);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "data.nq"), "<urn:s> <urn:p> <urn:o> .\n");
+    writeFileSync(join(dir, "schema.json"), "{}");
+    writeFileSync(join(dir, "index.json"), "{}");
+    writeFileSync(join(dir, "stories.json"), "[]");
+    writeFileSync(
+      join(dir, "manifest.json"),
+      JSON.stringify({
+        name: "pragma",
+        version: "0.1.0",
+        sourceRef: "t",
+        contentHash: hash,
+        prefixes: {},
+        createdAt: "2026-09-10T21:49:00.411Z",
+      }),
+    );
+    mkdirSync(dirname(activePackPath(cwd)), { recursive: true });
+    writeFileSync(activePackPath(cwd), hash);
+
+    const pkgRefs = await checkPackageRefs(bootRuntime(FLAGS, cwd));
+    expect(pkgRefs.status).toBe("pass");
+    expect(pkgRefs.detail).toContain("shipped with the CLI");
+    expect(pkgRefs.detail).toContain(
+      "a pack built by pragma 0.1.0 on 2026-09-10 is ignored",
+    );
+    expect(pkgRefs.detail).toContain("pragma sources reset");
+    expect(pkgRefs.remedy).toBeUndefined();
+  });
+
   it("a project with its OWN packs and nothing built is an attributable fail", async () => {
     // The install that must never read healthy: `origins.packs` is "project",
     // so the embedded snapshot is a DIFFERENT graph and every read throws

package/src/capabilities/doctor/doctor.verb.ts

@@ -27,6 +27,8 @@ const doctorVerb: VerbSpec<Record<string, unknown>, DoctorData> = {
   // (`toolDescriptions.test.ts`), so the inventory's widening is described as
   // "the verbose global flag" rather than by its spelling.
   doc: "Reports the environment checks first, then one row per setup target — once for your home directory, once for this project. Each row is pass, fail, available (an optional integration you have not set up yet), or skip (nothing to do here, and the row says why), with the next step printed inline. Every row is named after the setup target that repairs it, except `harnesses`: a listing, per scope, of the AI harnesses found on this machine and whether this CLI's MCP server is registered in each — the ones actually found, or every harness it knows about under the verbose global flag. Needs no store; the store check boots lazily and never fails the run.",
+  useWhen: "when something is not working, to find out what",
+  category: "diagnostic",
   params: [],
   output: { formatters: doctorFormatters },
   examples: [

package/src/capabilities/emptyRecovery.test.ts

@@ -174,6 +174,11 @@ describe("pack list empty-state (U5, PROTECTED)", () => {
       const notice = formatters.notice?.(empty);
       expect(notice).toContain(`No ${pack.noun} entries found.`);
       expect(notice).toMatch(hint);
+      // Over MCP the same hint ends in a TOOL CALL: an agent cannot run a
+      // command, and `meta.notice` is the only place it reads this.
+      const overMcp = formatters.notice?.(empty, "mcp");
+      expect(overMcp).toMatch(/Call `[a-z]+_[a-z]+ \{.*\}`\./);
+      expect(overMcp).not.toMatch(hint);
       // JSON is the uniform empty array — unchanged by the message.
       expect(formatters.json(empty)).toBe("[]");
       // The llm view stays non-blank too (the `(0)` heading plus the message).

package/src/capabilities/graph/connect.verb.ts

@@ -103,6 +103,8 @@ const connectVerb: VerbSpec<Record<string, unknown>, ConnectResult> = {
   path: ["graph", "connect"],
   summary: "Show the shortest relation paths between two entities.",
   doc: "Finds every shortest path of RELATION edges between two entities, and says which kind of nothing it found when there is no path. An edge counts as a relation only where it does not fan out into a roster — membership of a class, a tier or a family is answered by that noun's list verb, not by a path — so most pairs are correctly reported as unconnected. Address each endpoint by prefixed name (ds:global.component.button) or absolute IRI. Every answer states the hop limit, the fan-in threshold, and the packs searched.",
+  useWhen: "when asked whether and how two things are related",
+  example: { a: "ds:global.component.button", b: "dt:color.text" },
   params: [
     {
       kind: "string",

package/src/capabilities/graph/inspect.render.ts

@@ -11,6 +11,7 @@ import { toTurtle } from "../../kernel/render/turtle.js";
 import type {
   InboundGroup,
   InspectResult,
+  PredicateGroup,
   ReadTerm,
 } from "../../kernel/runtime/readEntity.js";
 import type { Formatters } from "../../kernel/spec/index.js";
@@ -39,6 +40,13 @@ function inboundHeading(group: InboundGroup): string {
   return `${short(group.predicate)} (${suffix})`;
 }
 
+/** `predicate (24 objects, showing 10)` — a cut group says what it was cut from. */
+function outboundHeading(group: PredicateGroup): string {
+  return group.truncated
+    ? `${short(group.predicate)} (${group.count} objects, showing ${group.objects.length})`
+    : short(group.predicate);
+}
+
 export const inspectFormatters: Formatters<InspectResult> = {
   plain(data) {
     const title = data.label
@@ -46,7 +54,7 @@ export const inspectFormatters: Formatters<InspectResult> = {
       : (data.prefixed ?? data.uri);
     const lines = [title, "═".repeat(Math.max(title.length, 24)), ""];
     for (const group of data.groups) {
-      lines.push(`  ${short(group.predicate)}:`);
+      lines.push(`  ${outboundHeading(group)}:`);
       for (const object of group.objects) lines.push(`    ${named(object)}`);
     }
     for (const [via, rows] of Object.entries(data.nested)) {

package/src/capabilities/graph/inspect.test.ts

@@ -333,3 +333,76 @@ describe("bounds and losslessness the review surfaced", () => {
     });
   });
 });
+
+describe("an outbound predicate is cut below `detailed`, and says so", () => {
+  // One subject asserting a wide predicate both ways: 14 named objects, and 12
+  // blank ones that inline as records.
+  const indexes = Array.from({ length: 14 }, (_, index) => index);
+  const WIDE_TTL = [
+    "@prefix ds: <https://ds.canonical.com/> .",
+    `ds:wide ds:name "Wide" ;`,
+    `  ds:uses ${indexes.map((index) => `ds:part.${index}`).join(", ")} ;`,
+    `  ds:binds ${indexes
+      .slice(0, 12)
+      .map((index) => `[ ds:rank ${index} ]`)
+      .join(", ")} .`,
+  ].join("\n");
+
+  const readAt = async (
+    detail: "summary" | "standard" | "detailed",
+  ): Promise<InspectResult> => {
+    const fixture = await buildFixtureRuntime({
+      ttl: WIDE_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail,
+    });
+    try {
+      return (await inspectVerb.run(
+        { uri: "ds:wide" },
+        fixture.rt,
+      )) as InspectResult;
+    } finally {
+      (await fixture.rt.store.get()).store.dispose();
+    }
+  };
+  const group = (result: InspectResult, local: string) =>
+    result.groups.find((g) => g.predicate.value === `${DS}${local}`);
+
+  it("lists the head and states the true count at standard", async () => {
+    const result = await readAt("standard");
+    expect(group(result, "uses")).toMatchObject({ truncated: true, count: 14 });
+    expect(group(result, "uses")?.objects).toHaveLength(10);
+    // The inlined records follow the objects that survived the cut.
+    expect(group(result, "binds")?.count).toBe(12);
+    expect(result.nested["ds:binds"]).toHaveLength(10);
+    // A predicate under the cap carries neither marker.
+    expect(group(result, "name")).not.toHaveProperty("truncated");
+    expect(group(result, "name")).not.toHaveProperty("count");
+  });
+
+  it("keeps a few at summary rather than none", async () => {
+    expect(group(await readAt("summary"), "uses")?.objects).toHaveLength(3);
+  });
+
+  it("cuts nothing at detailed", async () => {
+    const result = await readAt("detailed");
+    expect(group(result, "uses")?.objects).toHaveLength(14);
+    expect(group(result, "uses")).not.toHaveProperty("truncated");
+    expect(result.nested["ds:binds"]).toHaveLength(12);
+  });
+
+  it("prints the count in the plain and the Turtle forms", async () => {
+    const result = await readAt("standard");
+    const formatters = inspectVerb.output.formatters;
+    expect(formatters.plain(result)).toContain(
+      "ds:uses (14 objects, showing 10):",
+    );
+    const turtle = formatters.llm(result);
+    expect(turtle).toContain(
+      "  # ds:uses — 14 objects, showing 10\n  ds:uses ",
+    );
+    expect(turtle).toContain(
+      "  # ds:binds — 12 objects, showing 10\n  ds:binds\n",
+    );
+  });
+});

package/src/capabilities/graph/inspect.verb.ts

@@ -25,6 +25,8 @@ const inspectVerb: VerbSpec<Record<string, unknown>, InspectResult> = {
   summary:
     "Show every triple where a URI is the subject, grouped by predicate.",
   doc: "Inspect one entity: all predicate/object pairs asserted on the subject. Address it by prefixed name (ds:global.component.button) or absolute IRI.",
+  useWhen: "when asked for everything recorded about one identifier",
+  example: { uri: "ds:global.component.button" },
   params: [
     {
       kind: "string",

package/src/capabilities/graph/query.render.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { queryFormatters } from "./query.render.js";
+
+const EMPTY = { type: "select", bindings: [] } as never;
+
+describe("graph query — zero rows names the next call", () => {
+  it("says the query ran, and points at the catalogue and the namespaces as commands on the CLI", () => {
+    const notice = queryFormatters.notice?.(EMPTY) as string;
+    expect(notice).toContain("the query ran and matched nothing");
+    expect(notice).toContain("`pragma capabilities`");
+    expect(notice).toContain("`pragma ontology list`");
+    // The condensed form is one stream, so it carries the same sentence.
+    expect(queryFormatters.llm(EMPTY)).toBe(notice);
+  });
+
+  it("spells them as tool calls over MCP, and names no domain tool", () => {
+    const notice = queryFormatters.notice?.(EMPTY, "mcp") as string;
+    expect(notice).toContain("`capabilities {}`");
+    expect(notice).toContain("`ontology_list {}`");
+    expect(notice).not.toContain("pragma ");
+    // Which tool answers the question is the catalogue's to say, not this
+    // renderer's: the only tools it may name are the two it points at.
+    const named = [...notice.matchAll(/`([a-z_]+) \{/g)].map((m) => m[1]);
+    expect(named.sort()).toEqual(["capabilities", "ontology_list"]);
+  });
+
+  it("says nothing when there are rows", () => {
+    expect(
+      queryFormatters.notice?.({
+        type: "select",
+        bindings: [{ s: "ds:x" }],
+      } as never),
+    ).toBeUndefined();
+  });
+});

package/src/capabilities/graph/query.render.ts

@@ -9,11 +9,12 @@
  * - json: the serialized {@link QueryResult}.
  */
 
-import type { Formatters } from "../../kernel/spec/index.js";
+import { quoteCall } from "../../kernel/spec/call.js";
+import type { Call, Formatters, Surface } from "../../kernel/spec/index.js";
 
 // Inline `import("…")` type (no `from`) — keeps the ke types off the static
 // import graph the lazy-dispatch probe walks (see query.verb.ts).
-type QueryResult = import("@canonical/ke").QueryResult;
+type QueryAnswer = import("./runQuery.js").QueryAnswer;
 
 /**
  * Render CONSTRUCT triples as readable `subject\tpredicate\tobject` lines,
@@ -35,13 +36,46 @@ function formatTriples(
     .join("\n");
 }
 
-export const queryFormatters: Formatters<QueryResult> = {
+/**
+ * Where an empty SELECT points. Deliberately no domain tool: which one answers
+ * the caller's question is the catalogue's to say, so the pointer is to the
+ * catalogue — and to the namespaces that exist, since an invented prefix parses
+ * and matches nothing.
+ */
+export const EMPTY_QUERY_CALLS = {
+  catalogue: { verb: "capabilities" },
+  namespaces: { verb: "ontology list" },
+} as const satisfies Record<string, Call>;
+
+/**
+ * What zero rows says for itself. "No results." read as a failed tool to an
+ * agent with nowhere to go next. The query RAN; when its own text declares a
+ * prefix this graph does not have, that is the reason and it is said exactly.
+ */
+function describeEmptySelect(result: QueryAnswer, surface: Surface): string {
+  const { catalogue, namespaces } = EMPTY_QUERY_CALLS;
+  const invented = (result.unknownPrefixes ?? [])
+    .map(
+      ({ prefix, iri }) =>
+        `Prefix \`${prefix}:\` <${iri}> is not a namespace of this graph, so nothing under it can match.`,
+    )
+    .join(" ");
+  return [
+    "No results: the query ran and matched nothing.",
+    invented,
+    `The namespaces that exist are listed by ${quoteCall(namespaces, surface)} (an invented prefix matches nothing). A domain tool may answer this without SPARQL: ${quoteCall(catalogue, surface)} lists the tools by the question each answers.`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+export const queryFormatters: Formatters<QueryAnswer> = {
   // Zero rows/triples: plain stdout stays empty — the notice is
   // `notice`, routed to stderr (exit 0) by the dispatcher so a pipe
   // reads no prose. ASK always has a result and never goes empty.
-  notice(result) {
+  notice(result, surface = "cli") {
     if (result.type === "select" && result.bindings.length === 0) {
-      return "No results.";
+      return describeEmptySelect(result, surface);
     }
     if (result.type === "construct" && result.triples.length === 0) {
       return "No triples.";
@@ -65,7 +99,9 @@ export const queryFormatters: Formatters<QueryResult> = {
 
   llm(result) {
     if (result.type === "select") {
-      if (result.bindings.length === 0) return "_No results._";
+      if (result.bindings.length === 0) {
+        return describeEmptySelect(result, "cli");
+      }
       const cols = Object.keys(result.bindings[0] ?? {});
       const header = `| ${cols.join(" | ")} |`;
       const divider = `| ${cols.map(() => "---").join(" | ")} |`;
@@ -84,6 +120,8 @@ export const queryFormatters: Formatters<QueryResult> = {
   },
 
   json(result) {
-    return JSON.stringify(result);
+    // The payload is the engine's own shape; the prefix finding is the notice's.
+    const { unknownPrefixes: _unknownPrefixes, ...data } = result;
+    return JSON.stringify(data);
   },
 };

package/src/capabilities/graph/query.shipped.exec.test.ts

@@ -64,3 +64,47 @@ describe("a name pragma printed can be pasted back (PROTECTED)", () => {
     expect(prefixed).toEqual(absolute);
   });
 });
+
+describe("an invented namespace is named, not answered with silence", () => {
+  // The recorded failure: nine queries against a namespace that does not
+  // exist, nine "No results", and a guess. A declared PREFIX always parses, so
+  // only a check against the store's own prefix map can say why nothing matched.
+  const INVENTED =
+    "PREFIX tok: <https://example.invalid/tokens#> SELECT ?c WHERE { ?c tok:uses ?t }";
+
+  it("says exactly which prefix is not a namespace of this graph, on both surfaces", async () => {
+    const result = await queryVerb.run({ sparql: INVENTED }, rt);
+    const { notice, json } = queryVerb.output.formatters;
+    const cli = notice?.(result, "cli") as string;
+    expect(cli).toContain(
+      "Prefix `tok:` <https://example.invalid/tokens#> is not a namespace of this graph",
+    );
+    expect(cli).toContain("`pragma ontology list`");
+    expect(notice?.(result, "mcp")).toContain("`ontology_list {}`");
+    // The finding explains the emptiness; the payload stays the engine's shape.
+    const payload = JSON.parse(json(result));
+    expect(payload).toMatchObject({ type: "select", bindings: [] });
+    expect(payload).not.toHaveProperty("unknownPrefixes");
+  });
+
+  it("says nothing about prefixes when the query declares only real ones, or has rows", async () => {
+    const real = await queryVerb.run(
+      {
+        sparql:
+          "PREFIX ds: <https://ds.canonical.com/> SELECT ?s WHERE { ?s a ds:NoSuchClass }",
+      },
+      rt,
+    );
+    const notice = queryVerb.output.formatters.notice?.(real, "cli") as string;
+    expect(notice).toContain("the query ran and matched nothing");
+    expect(notice).not.toContain("is not a namespace");
+    const hit = await queryVerb.run(
+      {
+        sparql: `${INVENTED.replace("WHERE { ?c tok:uses ?t }", "WHERE { ?c ?p ?t } LIMIT 1")}`,
+      },
+      rt,
+    );
+    expect(queryVerb.output.formatters.notice?.(hit, "cli")).toBeUndefined();
+    expect(hit).not.toHaveProperty("unknownPrefixes");
+  });
+});

package/src/capabilities/graph/query.verb.ts

@@ -24,6 +24,8 @@ const queryVerb: VerbSpec<Record<string, unknown>, QueryResult> = {
   path: ["graph", "query"],
   summary: "Run a raw SPARQL query against the loaded graph.",
   doc: "Executes an arbitrary SPARQL query (SELECT / ASK / CONSTRUCT) against the store. Prefixes are applied automatically from the pack's namespace map; list the ontology namespaces to discover the available prefixes.",
+  useWhen: "only when no other tool answers: SPARQL joins or counts",
+  example: { sparql: "SELECT ?s WHERE { ?s a ds:Component } LIMIT 5" },
   params: [
     {
       kind: "string",

package/src/capabilities/graph/queryText.test.ts

@@ -10,7 +10,11 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { expandPrefixedNames, trimQueryError } from "./queryText.js";
+import {
+  expandPrefixedNames,
+  findUnknownPrefixes,
+  trimQueryError,
+} from "./queryText.js";
 
 const PREFIXES = {
   ds: "https://ds.canonical.com/",
@@ -119,3 +123,53 @@ describe("trimQueryError — the caller's own position", () => {
     );
   });
 });
+
+describe("findUnknownPrefixes — only a prefix that can explain the emptiness", () => {
+  const KNOWN = { ds: "https://ds.canonical.com/" };
+  const BAD = "https://example.invalid/t#";
+
+  it("reports a declared, used prefix whose IRI is no namespace of the graph", () => {
+    expect(
+      findUnknownPrefixes(
+        `PREFIX tok: <${BAD}> PREFIX ds: <https://ds.canonical.com/> SELECT ?c WHERE { ?c tok:uses ds:x }`,
+        KNOWN,
+      ),
+    ).toEqual([{ prefix: "tok", iri: BAD }]);
+  });
+
+  it("ignores a PREFIX in a comment or inside a string literal", () => {
+    expect(
+      findUnknownPrefixes(
+        `# PREFIX tok: <${BAD}>\nSELECT ?s WHERE { ?s ds:label "PREFIX tok: <${BAD}> tok:x" }`,
+        KNOWN,
+      ),
+    ).toEqual([]);
+  });
+
+  it("ignores a declared prefix the body never uses", () => {
+    expect(
+      findUnknownPrefixes(
+        `PREFIX tok: <${BAD}> SELECT ?s WHERE { ?s a ds:Component }`,
+        KNOWN,
+      ),
+    ).toEqual([]);
+  });
+
+  it("does not judge a relative IRI, which BASE resolves", () => {
+    expect(
+      findUnknownPrefixes(
+        "BASE <https://ds.canonical.com/> PREFIX rel: <tokens/> SELECT ?s WHERE { ?s rel:p ?o }",
+        KNOWN,
+      ),
+    ).toEqual([]);
+  });
+
+  it("reports the default prefix too, when the body uses it", () => {
+    expect(
+      findUnknownPrefixes(
+        `PREFIX : <${BAD}> SELECT ?s WHERE { ?s :p ?o }`,
+        KNOWN,
+      ),
+    ).toEqual([{ prefix: "", iri: BAD }]);
+  });
+});

package/src/capabilities/graph/queryText.ts

@@ -238,3 +238,50 @@ function cut(text: string): string {
     ? text
     : `${text.slice(0, MAX_PARSER_DETAIL - 1).trimEnd()}…`;
 }
+
+/** A `PREFIX` the caller declared whose IRI is none of the store's namespaces. */
+export interface UnknownPrefix {
+  readonly prefix: string;
+  readonly iri: string;
+}
+
+/**
+ * Find the prefixes a query declares, USES, and binds to an IRI the store does
+ * not know as a namespace.
+ *
+ * A declared prefix always parses, so an invented one fails silently: every
+ * pattern under it simply matches nothing, and the caller reads "no results"
+ * as "no such data". Checked against the store's own prefix map, this is the
+ * one emptiness the query's text can explain.
+ *
+ * Read through the same {@link SCANNER} the expander uses, so a `PREFIX` in a
+ * comment or inside a string literal is not a declaration. A declared prefix
+ * the body never uses cannot be why nothing matched, and a relative IRI
+ * (resolved against `BASE`) cannot be judged from the text, so neither is
+ * reported.
+ *
+ * @param sparql - The query text as the caller wrote it.
+ * @param prefixes - The store's prefix map (prefix → namespace IRI).
+ * @returns The used declarations whose IRI is not a known namespace, in order.
+ */
+export function findUnknownPrefixes(
+  sparql: string,
+  prefixes: Readonly<Record<string, string>>,
+): UnknownPrefix[] {
+  const known = new Set(Object.values(prefixes));
+  const code = sparql.replace(SCANNER, (token) =>
+    /^[#"']/.test(token) ? " " : token,
+  );
+  const body = code.replace(PREFIX_DECLARATION, " ");
+  const used = new Set(
+    [...body.matchAll(/(?:^|[^\w<:.-])([A-Za-z][\w.-]*)?:(?!\/\/)/g)].map(
+      (match) => match[1] ?? "",
+    ),
+  );
+  return [...code.matchAll(PREFIX_DECLARATION)]
+    .map((match) => ({ prefix: match[1] ?? "", iri: match[2] ?? "" }))
+    .filter(
+      ({ prefix, iri }) =>
+        /^[a-z][a-z0-9+.-]*:/i.test(iri) && used.has(prefix) && !known.has(iri),
+    );
+}