@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/kernel/packs/filteredEmpty.test.ts

@@ -58,7 +58,7 @@ ex:slider a ex:Widget ; ex:name "Slider" ; ex:kind "input" .
 const EMPTY_RECOVERY = {
   message:
     "Widgets are recorded by the catalogue build, and a store built before it ran records none.",
-  cli: "sources update",
+  call: { verb: "sources update" },
 } as const;
 
 const listShape = (uriClass: string) => ({
@@ -133,10 +133,12 @@ describe("a zero-row answer names the filter and keeps the recovery", () => {
     expect(outcome.exitCode).toBe(0);
     const said = `${outcome.stdout ?? ""}${outcome.stderr ?? ""}`;
     expect(said).toContain("No widget matches `--search zzzznotreal`.");
-    // The filter is the news; the story's account of where widgets come from is
-    // the other half, and a reader who mistyped nothing needs it.
+    // The filter is the news, with how to widen; the story's account of where
+    // widgets come from is kept — and the rebuild is not advised, because a
+    // filter that missed says nothing about the store.
+    expect(said).toContain("drop the argument, or loosen it");
     expect(said).toContain("recorded by the catalogue build");
-    expect(said).toContain("pragma sources update");
+    expect(said).not.toContain("sources update");
   });
 
   it("every filter in force is named", async () => {
@@ -195,7 +197,7 @@ describe("a zero-row answer names the filter and keeps the recovery", () => {
     const said = `${outcome.stderr ?? ""}`;
     expect(said).toContain("No gadget matches `--kind input`.");
     expect(said).toContain("recorded by the catalogue build");
-    expect(said).toContain("pragma sources update");
+    expect(said).not.toContain("sources update");
   });
 
   it("an EMPTY POPULATION unfiltered gets the kernel's own sentence", async () => {
@@ -210,4 +212,19 @@ describe("a zero-row answer names the filter and keeps the recovery", () => {
     expect(outcome.stderr).toContain("recorded by the catalogue build");
     expect(outcome.stderr).toContain("pragma sources update");
   });
+
+  it("a story with no recovery of its own: rebuild unfiltered, never when filtered", async () => {
+    const bare: PackDefinition = {
+      ...GADGET_PACK,
+      list: { ...listShape("ex:Gadget") },
+    };
+    const said = async (params: Record<string, unknown>): Promise<string> =>
+      (await executeVerb(listVerb(bare), params, REAL, as(PLAIN))).stderr ?? "";
+
+    expect(await said({})).toContain("pragma sources update");
+    const filtered = await said({ kind: "input" });
+    expect(filtered).toContain("drop the argument, or loosen it");
+    expect(filtered).not.toContain("sources update");
+    expect(filtered).not.toContain("needs building");
+  });
 });

package/src/kernel/packs/graphql/fetchGraphqlLookup.ts

@@ -14,7 +14,7 @@
  * composed only from validated pack terms and compiled schema names.
  */
 
-import { cliRecovery, PragmaError } from "../../error/index.js";
+import { callRecovery, PragmaError } from "../../error/index.js";
 import type { PragmaRuntime } from "../../runtime/index.js";
 import type { PackChildRow, PackEntity, PackLookup } from "../types.js";
 import {
@@ -56,10 +56,9 @@ export async function fetchGraphqlLookup(
       .join("; ");
     throw PragmaError.storeUnavailable(`GraphQL lookup failed: ${messages}`, {
       // `graph inspect` needs a <uri>; `ontology list` is runnable as-is.
-      recovery: cliRecovery(
-        "ontology list",
+      recovery: callRecovery(
+        { verb: "ontology list" },
         "Check the loaded ontology and namespaces.",
-        { tool: "ontology_list" },
       ),
     });
   }
@@ -72,8 +71,8 @@ export async function fetchGraphqlLookup(
     throw new PragmaError({
       code: "ENTITY_NOT_FOUND",
       message: `Cannot resolve <${entityUri}> — its rdf:type may be missing from the ontology.`,
-      recovery: cliRecovery(
-        `graph inspect ${entityUri}`,
+      recovery: callRecovery(
+        { verb: "graph inspect", params: { uri: entityUri } },
         "Inspect the entity's triples to check its rdf:type.",
       ),
     });

package/src/kernel/packs/graphqlSource.test.ts

@@ -14,6 +14,7 @@ import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
 import type { PragmaRuntime, StoreSession } from "../runtime/types.js";
 import { compilePack } from "./compile.js";
 import { buildLookupDocument } from "./graphql/buildLookupDocument.js";
+import { fetchGraphqlLookup } from "./graphql/fetchGraphqlLookup.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackLookup } from "./types.js";
@@ -320,6 +321,47 @@ describe("GraphQL engine — against the compiled fixture schema (PROTECTED)", (
 
   const lookup = GBLOCK.lookup as PackLookup;
 
+  /** The fixture runtime with its GraphQL executor replaced by a canned answer. */
+  const answering = (answer: unknown): PragmaRuntime =>
+    ({
+      ...rt,
+      query: { ...rt.query, graphql: async () => answer },
+    }) as PragmaRuntime;
+  const fetchWith = (answer: unknown) =>
+    fetchGraphqlLookup(
+      answering(answer),
+      lookup,
+      "https://ds.canonical.com/x",
+      "X",
+      "t",
+      BLOCK_PREFIXES,
+    );
+
+  it("an execution error recovers to the namespace list, in both spellings", async () => {
+    await expect(
+      fetchWith({ errors: [{ message: "boom" }] }),
+    ).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+      recovery: {
+        cli: "pragma ontology list",
+        mcp: { tool: "ontology_list", params: {} },
+      },
+    });
+  });
+
+  it("a resolved IRI with no typed node recovers to inspecting THAT entity", async () => {
+    await expect(fetchWith({ data: { node: null } })).rejects.toMatchObject({
+      code: "ENTITY_NOT_FOUND",
+      recovery: {
+        cli: "pragma graph inspect https://ds.canonical.com/x",
+        mcp: {
+          tool: "graph_inspect",
+          params: { uri: "https://ds.canonical.com/x" },
+        },
+      },
+    });
+  });
+
   it("generates one document with derived names, Relay envelopes, subtype scoping", () => {
     const plan = buildLookupDocument(lookup, schema, "t");
     expect(plan.source).toContain("query PackLookup($uri: ID!)");

package/src/kernel/packs/iri.ts

@@ -7,7 +7,7 @@
  * before it can be interpolated into a generated `<iri>` query token.
  */
 
-import { cliRecovery, PragmaError } from "../error/index.js";
+import { callRecovery, PragmaError } from "../error/index.js";
 
 /** Characters not allowed inside a SPARQL `<IRI>`. */
 const UNSAFE_IRI_PATTERN = /[<>"{}|\\^`\s]/;
@@ -86,9 +86,10 @@ function tryResolveUri(
 
   return PragmaError.invalidInput("prefix", prefix, {
     validOptions: Object.keys(prefixes),
-    recovery: cliRecovery("ontology list", "List known ontology prefixes.", {
-      tool: "ontology_list",
-    }),
+    recovery: callRecovery(
+      { verb: "ontology list" },
+      "List known ontology prefixes.",
+    ),
   });
 }
 

package/src/kernel/packs/listNotice.test.ts

@@ -46,7 +46,7 @@ ex:slider a ex:Widget ; ex:name "Slider" ; ex:kind "input" .
 /** The recovery a story authors for an EMPTY POPULATION — never for a filter. */
 const EMPTY_RECOVERY = {
   message: "No widgets in the store.",
-  cli: "sources update",
+  call: { verb: "sources update" },
 } as const;
 
 const WIDGET_LIST = {

package/src/kernel/packs/nounLink.test.ts

@@ -0,0 +1,385 @@
+/**
+ * A filter that names a noun accepts what that noun's lookup accepts, and a
+ * `many` expand field adds values to a row, never rows.
+ */
+
+import { beforeAll, describe, expect, it } from "vitest";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { ConfigLayers } from "../config/index.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import type { CapabilityModule, VerbSpec } from "../spec/types.js";
+import { assembleEffectiveModules, screenPackageStories } from "./collect.js";
+import { compilePack, compileStoryModule } from "./compile.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import { parsePackDefinition } from "./schema.js";
+import {
+  distributionSource,
+  type PackDefinition,
+  type PackPage,
+} from "./types.js";
+import { verbKey } from "./uniqueness.js";
+
+const PREFIXES = {
+  ex: "https://example.org/shop#",
+  owl: "http://www.w3.org/2002/07/owl#",
+};
+
+const TTL = `
+@prefix ex: <https://example.org/shop#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+
+ex:Maker a owl:Class .
+ex:Widget a owl:Class .
+
+ex:acme a ex:Maker ; ex:name "Acme" ; ex:code "A1" .
+ex:acme2 a ex:Maker ; ex:name "Acme" .
+ex:bolt a ex:Maker ; ex:name "Bolt" .
+ex:idle a ex:Maker ; ex:name "Idle" .
+
+ex:button a ex:Widget ; ex:name "Button" ; ex:madeBy ex:acme ;
+  ex:alias "btn" , "Btn" , "push-button" .
+ex:label a ex:Widget ; ex:name "Label" ; ex:madeBy ex:acme2 .
+ex:slider a ex:Widget ; ex:name "Slider" ; ex:madeBy ex:bolt .
+
+ex:bolt ex:part
+  [ ex:group "g" ; ex:label "f" ; ex:tag "x" , "y" ] ,
+  [ ex:group "g" ; ex:label "c" ; ex:tag "x" ] ,
+  [ ex:group "g" ; ex:label "e" ] ,
+  [ ex:group "g" ; ex:label "a" ; ex:tag "y" ] ,
+  [ ex:group "g" ; ex:label "d" ; ex:tag "x" ] ,
+  [ ex:group "g" ; ex:label "b" ] .
+`;
+
+const MAKER: PackDefinition = {
+  noun: "maker",
+  lookup: {
+    by: "ex:name",
+    type: "ex:Maker",
+    expand: [
+      {
+        name: "widgets",
+        kind: "table",
+        relation: "^ex:madeBy",
+        select: [
+          { name: "name", property: "ex:name", noun: "widget" },
+          { name: "aliases", property: "ex:alias", many: true },
+        ],
+      },
+      {
+        name: "parts",
+        kind: "table",
+        relation: "ex:part",
+        // Every part ties on the one declared key.
+        orderBy: ["group"],
+        select: [
+          { name: "group", property: "ex:group" },
+          { name: "label", property: "ex:label" },
+          { name: "tags", property: "ex:tag", many: true },
+        ],
+      },
+    ],
+  },
+};
+
+const WIDGET: PackDefinition = {
+  noun: "widget",
+  list: {
+    query: [
+      "SELECT ?uri ?name ?maker ?makerUri WHERE {",
+      "  ?uri a ex:Widget ; ex:name ?name ; ex:madeBy ?makerUri .",
+      "  ?makerUri ex:name ?maker .",
+      "} ORDER BY ?name",
+    ].join("\n"),
+    columns: [
+      { field: "name", label: "Name" },
+      { field: "maker", label: "Maker", noun: "maker" },
+    ],
+    filters: [
+      { param: "maker", variable: "maker", noun: "maker", entity: "makerUri" },
+    ],
+  },
+  lookup: { by: "ex:name", type: "ex:Widget" },
+};
+
+const STORIES = new Map([MAKER, WIDGET].map((story) => [story.noun, story]));
+
+const verb = (story: PackDefinition, name: string): VerbSpec =>
+  compilePack(
+    story,
+    distributionSource("test:links"),
+    PREFIXES,
+    (noun) => STORIES.get(noun)?.lookup,
+  ).find((v) => verbKey(v.path) === `${story.noun} ${name}`) as VerbSpec;
+
+let rt: PragmaRuntime;
+beforeAll(async () => {
+  ({ rt } = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES }));
+});
+
+const widgetsBy = async (maker: unknown): Promise<PackPage["rows"]> =>
+  ((await verb(WIDGET, "list").run({ maker }, rt)) as PackPage).rows;
+
+describe("a filter that names a noun", () => {
+  it("takes a name, and a shared name means every entity it reaches", async () => {
+    const rows = await widgetsBy("acme");
+    expect(rows.map((row) => row.name)).toEqual(["Button", "Label"]);
+  });
+
+  it("takes a prefixed IRI and an absolute IRI, which reach one entity", async () => {
+    expect((await widgetsBy("ex:acme2")).map((row) => row.name)).toEqual([
+      "Label",
+    ]);
+    expect(
+      (await widgetsBy("https://example.org/shop#bolt")).map((row) => row.name),
+    ).toEqual(["Slider"]);
+  });
+
+  it("takes several values as a union", async () => {
+    const rows = await widgetsBy(["Bolt", "ex:acme"]);
+    expect(rows.map((row) => row.name)).toEqual(["Button", "Slider"]);
+  });
+
+  it("leaves the entity variable out of the rows", async () => {
+    expect(Object.keys((await widgetsBy("Bolt"))[0] ?? {})).toEqual([
+      "uri",
+      "name",
+      "maker",
+    ]);
+  });
+
+  it("answers a calm empty list for an entity that exists and no row names", async () => {
+    expect(await widgetsBy("Idle")).toEqual([]);
+  });
+
+  it("refuses a value the noun's lookup cannot resolve, offering what a lookup miss offers", async () => {
+    await expect(widgetsBy(["Bolt", "Bolts"])).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      message: 'No maker is named "Bolts".',
+      suggestions: ["Bolt"],
+    });
+  });
+
+  it("refuses an empty value as empty input", async () => {
+    await expect(widgetsBy("")).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+      message: 'Invalid maker "(empty)".',
+    });
+  });
+
+  it("is a configuration error when no story declares the noun", async () => {
+    const orphan = compilePack(
+      WIDGET,
+      distributionSource("test:links"),
+      PREFIXES,
+    )[0] as VerbSpec;
+    await expect(orphan.run({ maker: "Acme" }, rt)).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+    });
+  });
+});
+
+describe("a noun filter across the shipped and the project's stories", () => {
+  const shipped = (...stories: PackDefinition[]): CapabilityModule[] =>
+    stories.map((story) =>
+      compileStoryModule(
+        story,
+        distributionSource("test:shipped"),
+        PREFIXES,
+        (noun) => STORIES.get(noun)?.lookup,
+      ),
+    );
+  const project = (stories: unknown[]): ConfigLayers =>
+    ({
+      config: { stories, prefixes: PREFIXES },
+      origins: { packs: "default", stories: "project" },
+    }) as unknown as ConfigLayers;
+  const makerFilter = (modules: readonly CapabilityModule[], maker: string) =>
+    (
+      modules
+        .flatMap((module) => module.verbs)
+        .find((v) => verbKey(v.path) === "widget list") as VerbSpec
+    ).run({ maker: [maker] }, rt) as Promise<PackPage>;
+
+  it("a project story resolves its filter through a shipped noun", async () => {
+    const modules = assembleEffectiveModules(shipped(MAKER), project([WIDGET]));
+    const page = await makerFilter(modules, "Bolt");
+    expect(page.rows.map((row) => row.name)).toEqual(["Slider"]);
+  });
+
+  it("a shipped filter resolves through the project's override of the noun it names", async () => {
+    const byCode = {
+      noun: "maker",
+      lookup: { by: "ex:code", type: "ex:Maker" },
+    };
+    const modules = assembleEffectiveModules(
+      shipped(MAKER, WIDGET),
+      project([byCode]),
+    );
+    const page = await makerFilter(modules, "A1");
+    expect(page.rows.map((row) => row.name)).toEqual(["Button"]);
+    await expect(makerFilter(modules, "Acme")).rejects.toMatchObject({
+      code: "INVALID_INPUT",
+    });
+  });
+
+  it("refuses a story naming a noun no story declares, where it is assembled", () => {
+    expect(() => assembleEffectiveModules([], project([WIDGET]))).toThrow(
+      /Invalid story in config: "widget" names the noun "maker"/,
+    );
+  });
+
+  it("a project overriding a named noun with no lookup breaks only the filter, when used", async () => {
+    const listOnly = { noun: "maker", list: WIDGET.list };
+    const modules = assembleEffectiveModules(
+      shipped(MAKER, WIDGET),
+      project([listOnly]),
+    );
+    const widgets = modules
+      .flatMap((module) => module.verbs)
+      .find((v) => verbKey(v.path) === "widget list") as VerbSpec;
+    expect(((await widgets.run({}, rt)) as PackPage).rows).toHaveLength(3);
+    await expect(makerFilter(modules, "Bolt")).rejects.toMatchObject({
+      code: "CONFIG_ERROR",
+      message: expect.stringMatching(
+        /The "maker" story in config declares no lookup/,
+      ),
+    });
+  });
+
+  it("a package story is screened against the assembled nouns, whatever the order", () => {
+    const entry = { source: "pkg/stories/widget.json", definition: WIDGET };
+    const withMaker = screenPackageStories(
+      assembleEffectiveModules([], project([MAKER]), [entry]),
+    );
+    expect(withMaker.modules.map((module) => module.name)).toContain("widget");
+    expect(withMaker.problems).toEqual([]);
+
+    const other = { noun: "gadget", lookup: MAKER.lookup };
+    const without = screenPackageStories(
+      assembleEffectiveModules([], project([other]), [entry]),
+    );
+    expect(without.modules.map((module) => module.name)).toEqual(["gadget"]);
+    expect(without.problems).toEqual([
+      {
+        source: "pkg/stories/widget.json",
+        message: 'it names the noun "maker", and no story declares it.',
+      },
+    ]);
+  });
+});
+
+describe("a many expand field", () => {
+  it("is one cell per child holding every value, sorted", async () => {
+    const output = (await verb(MAKER, "lookup").run(
+      { name: ["ex:acme"] },
+      rt,
+    )) as LookupOutput;
+    const widgets = output.results[0]?.widgets as { aliases?: string }[];
+    expect(widgets).toHaveLength(1);
+    expect(widgets[0]?.aliases).toBe("Btn btn push-button");
+  });
+});
+
+describe("a grouped expand", () => {
+  it("orders rows that tie on orderBy the same way on every store", async () => {
+    const labels: string[] = [];
+    for (let boot = 0; boot < 3; boot += 1) {
+      const fresh = await buildFixtureRuntime({ ttl: TTL, prefixes: PREFIXES });
+      const output = (await verb(MAKER, "lookup").run(
+        { name: ["Bolt"] },
+        fresh.rt,
+      )) as LookupOutput;
+      const parts = output.results[0]?.parts as { label: string }[];
+      labels.push(parts.map((part) => part.label).join(""));
+    }
+    expect(labels).toEqual(["abcdef", "abcdef", "abcdef"]);
+  });
+});
+
+describe("the grammar", () => {
+  const withFilter = (filter: Record<string, unknown>): unknown => ({
+    ...WIDGET,
+    list: { ...WIDGET.list, filters: [filter] },
+  });
+
+  it("accepts both stories as declared", () => {
+    expect(() => parsePackDefinition(MAKER, "test")).not.toThrow();
+    expect(() => parsePackDefinition(WIDGET, "test")).not.toThrow();
+  });
+
+  it.each([
+    [
+      "a noun filter with no entity",
+      { param: "maker", variable: "maker", noun: "maker" },
+      /must declare the "entity"/,
+    ],
+    [
+      "a noun filter with a vocabulary of its own",
+      {
+        param: "maker",
+        variable: "maker",
+        noun: "maker",
+        entity: "makerUri",
+        values: ["Acme"],
+      },
+      /mutually exclusive/,
+    ],
+    [
+      "an entity the query does not project",
+      { param: "maker", variable: "maker", noun: "maker", entity: "absent" },
+      /"absent" is filtered or searched but not projected/,
+    ],
+    [
+      "an entity without a noun",
+      {
+        param: "maker",
+        variable: "maker",
+        values: ["Acme"],
+        entity: "makerUri",
+      },
+      /belong to a filter that names a "noun"/,
+    ],
+  ])("refuses %s", (_, filter, reason) => {
+    expect(() => parsePackDefinition(withFilter(filter), "test")).toThrow(
+      reason,
+    );
+  });
+
+  it.each([
+    [
+      "many with blankWhenSelf",
+      { many: true, blankWhenSelf: true },
+      {},
+      /mutually exclusive/,
+    ],
+    [
+      "many on the GraphQL lane",
+      { many: true },
+      { source: "graphql" },
+      /sets "many", which only the SPARQL lane/,
+    ],
+    [
+      "ordering by a many field",
+      { many: true },
+      { orderBy: ["aliases"] },
+      /a "many" field/,
+    ],
+  ])("refuses %s", (_, field, expand, reason) => {
+    const lookup = MAKER.lookup as NonNullable<PackDefinition["lookup"]>;
+    const story = {
+      ...MAKER,
+      lookup: {
+        ...lookup,
+        ...("source" in expand ? { source: "graphql" } : {}),
+        expand: [
+          {
+            ...lookup.expand?.[0],
+            ...("orderBy" in expand ? expand : {}),
+            select: [{ name: "aliases", property: "ex:alias", ...field }],
+          },
+        ],
+      },
+    };
+    expect(() => parsePackDefinition(story, "test")).toThrow(reason);
+  });
+});