@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/packs/renderPack.ts

@@ -16,14 +16,16 @@ import type {
   RenderListOptions,
   RenderLookupOptions,
   SectionDef,
-} from "../render/contracts.js";
+} from "../render/index.js";
+import { compactUri } from "../render/index.js";
 import {
+  renderListEmptyNotice,
   renderListLlm,
   renderListPlain,
   renderLookupLlm,
   renderLookupPlain,
 } from "../render/renderers.js";
-import type { Formatters } from "../spec/types.js";
+import type { Formatters } from "../spec/index.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import type {
   PackChildRow,
@@ -53,7 +55,7 @@ export interface RenderMeta {
  * list on a BUILT store (a cold store would have failed with STORE_UNAVAILABLE
  * first) means "nothing matched", so point at both possible fixes.
  */
-const DEFAULT_EMPTY_HINT = `If you haven't built the store yet, run \`${BIN_NAME} sources update\`; otherwise broaden your filter or channel.`;
+const DEFAULT_EMPTY_HINT = `Either nothing matched — try a wider filter — or the store has nothing in it yet: build it with \`${BIN_NAME} sources update\`.`;
 
 /** Build the list formatters for a list-shaped verb (list or an extra verb). */
 export function listFormatters(
@@ -82,9 +84,13 @@ export function listFormatters(
     emptyHint,
   };
   return {
-    plain: (rows) => renderListPlain(rows, options),
+    plain: (rows, context) => renderListPlain(rows, options, context),
     llm: (rows) => renderListLlm(rows, options),
     json: (rows) => JSON.stringify(rows, null, 2),
+    // Zero rows: the dispatcher routes this to stderr (exit 0) so the plain
+    // stdout stream stays pure data; llm/json keep their own empty shapes.
+    notice: (rows) =>
+      rows.length === 0 ? renderListEmptyNotice(options) : undefined,
   };
 }
 
@@ -115,14 +121,18 @@ export function lookupOptions(
     }),
   );
   return {
-    title: (entity) => scalar(entity.name) ?? scalar(entity.uri) ?? "(unnamed)",
+    // An entity reached by IRI need not carry a `by` value, so the IRI is a
+    // real title, not a fallback nobody hits — and it is titled in the form the
+    // user addressed it with, not the expanded one they never typed.
+    title: (entity) =>
+      scalar(entity.name) ?? compactScalar(entity.uri, prefixes) ?? "(unnamed)",
     fields,
     sections: [...flatSections, ...expandSections],
     prefixes,
   };
 }
 
-/** Build the lookup formatters (renders every resolved entity, then any errors). */
+/** Build the lookup formatters (every resolved entity, then errors, then the notice). */
 export function lookupFormatters(
   lookup: PackLookup,
   prefixes: Readonly<Record<string, string>>,
@@ -193,6 +203,15 @@ function scalar(
   return typeof value === "string" ? value : undefined;
 }
 
+/** A scalar URI in its prefixed display form, or undefined when it is neither. */
+function compactScalar(
+  value: string | readonly PackChildRow[] | undefined,
+  prefixes: Readonly<Record<string, string>>,
+): string | undefined {
+  const uri = scalar(value);
+  return uri === undefined ? undefined : compactUri(uri, prefixes);
+}
+
 function capitalize(value: string): string {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }

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

@@ -0,0 +1,274 @@
+/**
+ * Lookup ADDRESSING (PROTECTED): which argument shapes a pack lookup accepts,
+ * and whether the answer is the same twice.
+ *
+ * A lookup's `<name...>` positional is documented — in the generated reference,
+ * in the MCP tool schema, and by shell completion, which offers prefixed IRIs
+ * and nothing else — as accepting a name, a prefixed name, an absolute IRI, or
+ * a glob. These assert that the resolver honours the shape it is handed rather
+ * than the source its pack declares, that an entity is addressable by IRI even
+ * when it carries no `by` value, and that an ambiguous name answers with the
+ * same entity on every store and every machine — while NAMING the ones it did
+ * not answer with.
+ *
+ * That last clause is a REVERSAL, signed off by the owner. It used to read "an
+ * ambiguous name resolves to the SAME entity every time", and the suite proved
+ * it: a total `ORDER BY` under a `LIMIT 1` does make the answer reproducible.
+ * It just made it reproducibly SILENT — `block lookup button` answered with
+ * Launchpad's Button on every machine, because `apps_launchpad…` sorts before
+ * `global…`, and nothing in the payload said the global one existed. The arity
+ * is unchanged and deliberately so; what the old assertions took for the whole
+ * property, determinism, was only half of it.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  AMBIGUOUS_TTL,
+  BLOCK_PREFIXES,
+  BLOCK_TTL,
+} from "../../testing/fixtures/blockGraph.js";
+import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
+import type { PragmaRuntime } from "../runtime/types.js";
+import { compilePack } from "./compile.js";
+import { lookupFormatters, lookupOptions } from "./renderPack.js";
+import type { LookupOutput } from "./resolveEntity.js";
+import type { PackDefinition, PackLookup } from "./types.js";
+import { distributionSource } from "./types.js";
+import { verbKey } from "./uniqueness.js";
+
+const DS = "https://ds.canonical.com/";
+
+/** A graphql-sourced pack — the shape `block` and `modifier` declare. */
+const GQL: PackDefinition = {
+  noun: "gblock",
+  lookup: {
+    source: "graphql",
+    by: "ds:name",
+    types: ["ds:Component", "ds:Pattern", "ds:Subcomponent"],
+    graphqlType: "UIBlock",
+    fields: [{ name: "summary", property: "ds:summary" }],
+  },
+};
+
+/** A sparql-sourced pack — the shape `tier`, `token` and `standard` declare. */
+const SPQ: PackDefinition = {
+  noun: "sblock",
+  lookup: {
+    source: "sparql",
+    by: "ds:name",
+    type: "ds:Component",
+    fields: [{ name: "summary", property: "ds:summary" }],
+  },
+};
+
+describe("pack lookup addressing (PROTECTED)", () => {
+  let rt: PragmaRuntime;
+
+  beforeAll(async () => {
+    ({ rt } = await buildFixtureRuntime({
+      ttl: BLOCK_TTL + AMBIGUOUS_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "detailed",
+    }));
+  });
+
+  afterAll(async () => {
+    (await rt.store.get()).store.dispose();
+  });
+
+  const lookupVia = (
+    definition: PackDefinition,
+    ...name: string[]
+  ): Promise<LookupOutput> => {
+    const verb = compilePack(
+      definition,
+      distributionSource("t"),
+      BLOCK_PREFIXES,
+    ).find((v) => verbKey(v.path) === `${definition.noun} lookup`);
+    if (!verb) throw new Error("no lookup verb");
+    return verb.run({ name }, rt) as Promise<LookupOutput>;
+  };
+
+  const lookupNoticeVia = (
+    definition: PackDefinition,
+    out: LookupOutput,
+  ): string | undefined =>
+    lookupFormatters(definition.lookup as PackLookup, BLOCK_PREFIXES).notice?.(
+      out,
+    );
+
+  const uris = (out: LookupOutput): string[] =>
+    out.results.map((entity) => String(entity.uri));
+
+  describe("an IRI addresses an entity on EVERY pack, not just sparql ones", () => {
+    it("resolves a prefixed name on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, "ds:button");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}button`]);
+    });
+
+    it("resolves an absolute IRI on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, `${DS}modal`);
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("still resolves a plain name on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, "Modal");
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("reports an IRI that names nothing as a clean miss", async () => {
+      await expect(lookupVia(GQL, "ds:nosuchblock")).rejects.toMatchObject({
+        code: "ENTITY_NOT_FOUND",
+      });
+    });
+  });
+
+  describe("an IRI addresses an entity that carries no `by` value", () => {
+    it("resolves it on the sparql path", async () => {
+      const out = await lookupVia(SPQ, "ds:nameless.widget");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}nameless.widget`]);
+      expect(out.results.at(0)?.summary).toBe(
+        "Carries no ds:name; addressable only by IRI.",
+      );
+    });
+
+    it("resolves it on the graphql path", async () => {
+      const out = await lookupVia(GQL, "ds:nameless.widget");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}nameless.widget`]);
+    });
+
+    it("titles it with the prefixed IRI it was addressed by", () => {
+      const options = lookupOptions(SPQ.lookup as PackLookup, BLOCK_PREFIXES);
+      expect(options.title({ uri: `${DS}nameless.widget` })).toBe(
+        "ds:nameless.widget",
+      );
+    });
+  });
+
+  describe("a glob expands over the population its own shape addresses", () => {
+    it("expands an IRI-shaped glob on a sparql-sourced pack", async () => {
+      const out = await lookupVia(SPQ, "ds:*.chip");
+      expect(out.errors).toEqual([]);
+      expect(uris(out).sort()).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("expands an IRI-shaped glob on a graphql-sourced pack", async () => {
+      const out = await lookupVia(GQL, "ds:button*");
+      expect(out.errors).toEqual([]);
+      expect(uris(out).sort()).toEqual([`${DS}button`, `${DS}button.icon`]);
+    });
+
+    it("reaches an entity with no `by` value through an IRI glob", async () => {
+      const out = await lookupVia(SPQ, "ds:nameless.*");
+      expect(uris(out)).toEqual([`${DS}nameless.widget`]);
+    });
+
+    it("still expands a name-shaped glob over names", async () => {
+      const out = await lookupVia(SPQ, "Mod*");
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("expands an ABSOLUTE-IRI glob, not only the compact spelling", async () => {
+      // An entity under a registered prefix has two legal spellings, and a
+      // literal lookup honours both — so a glob that generalises one of them
+      // must too. Expanding over the compact form alone made
+      // `https://ds.canonical.com/but*` an EMPTY_RESULTS while the exact IRI
+      // it generalises resolved fine.
+      const out = await lookupVia(GQL, `${DS}button*`);
+      expect(out.errors).toEqual([]);
+      expect(uris(out).sort()).toEqual([`${DS}button`, `${DS}button.icon`]);
+    });
+
+    it("yields an entity ONCE when both its spellings match", async () => {
+      // Reachable, not defensive: a glob counts as IRI-shaped if it contains
+      // a colon, so `*:*chip` matches BOTH `ds:alpha.chip` and its absolute
+      // twin. That is why the population is a spelling→entity map rather than
+      // a flat list of both forms — a match under either spelling must render
+      // one row, not two.
+      const out = await lookupVia(SPQ, "*:*chip");
+      expect(uris(out).sort()).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("reports an IRI-shaped glob that matches nothing", async () => {
+      await expect(lookupVia(SPQ, "ds:nosuch*")).rejects.toMatchObject({
+        code: "EMPTY_RESULTS",
+      });
+    });
+  });
+
+  describe("an ambiguous name answers with EVERY entity it reaches", () => {
+    // `ds:zeta.chip` is declared BEFORE `ds:alpha.chip` in the fixture, so the
+    // store enumerates it first while IRI order puts `alpha` first. Neither of
+    // these stories declares a ranking, so the order is the total `STR(?uri)`
+    // it always was — what changed is that BOTH chips come back. Both paths,
+    // because the resolve is generated SPARQL either way and only the field
+    // fetch differs.
+    it("answers with both, best first, on the sparql path", async () => {
+      const out = await lookupVia(SPQ, "Chip");
+      expect(uris(out)).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("answers with both, best first, on the graphql path", async () => {
+      const out = await lookupVia(GQL, "Chip");
+      expect(uris(out)).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("agrees with itself across repeated resolves", async () => {
+      // Determinism was never the property in question — `LIMIT 1` over a total
+      // order was already deterministic. It is pinned because the order now
+      // carries the ranking's judgement, and an order that varied by store
+      // would make the first result mean nothing.
+      const runs = await Promise.all([
+        lookupVia(SPQ, "Chip"),
+        lookupVia(SPQ, "chip"),
+        lookupVia(GQL, "CHIP"),
+      ]);
+      expect(runs.map(uris)).toEqual([
+        [`${DS}alpha.chip`, `${DS}zeta.chip`],
+        [`${DS}alpha.chip`, `${DS}zeta.chip`],
+        [`${DS}alpha.chip`, `${DS}zeta.chip`],
+      ]);
+    });
+
+    it("answers with ONE entity for an unambiguous name", async () => {
+      // The plural case costs the singular one nothing: a unique name still
+      // returns an array of one, which is the payload it always had.
+      const out = await lookupVia(GQL, "Modal");
+      expect(uris(out)).toEqual([`${DS}modal`]);
+    });
+
+    it("answers with ONE entity for an IRI, even a shared name's IRI", async () => {
+      // An IRI is one entity by construction, so the IRI form keeps its
+      // `LIMIT 1`: there is nothing to rank and nothing else to reach.
+      const out = await lookupVia(SPQ, "ds:zeta.chip");
+      expect(uris(out)).toEqual([`${DS}zeta.chip`]);
+    });
+
+    it("reaches both entities when a GLOB expands onto the shared name", async () => {
+      // The glob population is DISTINCT names, so "Chip" expands to ONE
+      // candidate — a glob was never the escape a shared name needs. Live,
+      // `block lookup 'Butt*'` listed Launchpad's Button and ButtonLink while
+      // the global Button appeared nowhere. Now the shared name reaches both
+      // through the glob for the same reason it does through a plain name.
+      const out = await lookupVia(SPQ, "Chi*");
+      expect(uris(out)).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("adds no notice — the payload IS the address", async () => {
+      // An earlier draft kept the arity and named the outranked IRIs in a
+      // notice. With every entity returned there is nothing set aside to name,
+      // and a sentence restating what the payload already carries is noise.
+      // The zero-record notice is untouched; only the ambiguity one is gone.
+      expect(
+        lookupNoticeVia(SPQ, await lookupVia(SPQ, "Chip")),
+      ).toBeUndefined();
+      expect(
+        lookupNoticeVia(SPQ, await lookupVia(SPQ, "Modal")),
+      ).toBeUndefined();
+    });
+  });
+});