@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/kernel/packs/renderPack.ts

@@ -9,7 +9,6 @@
  * them (disclosure gates the fetch), never HOW it is laid out.
  */
 
-import { BIN_NAME, RECOVERY_CLI_PREFIX } from "../../constants.js";
 import type {
   ColumnDef,
   LookupField,
@@ -25,18 +24,25 @@ import {
   renderLookupLlm,
   renderLookupPlain,
 } from "../render/renderers.js";
-import type { Formatters } from "../spec/index.js";
-import { kebabCase } from "../spec/index.js";
+import {
+  BUILD_STORE_CALL,
+  quoteArgument,
+  renderNextStep,
+} from "../spec/call.js";
+import type { Formatters, Surface } from "../spec/index.js";
 import type { LookupOutput } from "./resolveEntity.js";
 import {
   EVERY_TIER,
   type PackAppliedFilter,
   type PackChildRow,
+  type PackEmptyRecovery,
   type PackEntity,
   type PackList,
   type PackLookup,
   type PackPage,
   type PackRow,
+  TIER_PARAM,
+  UNTIERED_KEY,
 } from "./types.js";
 
 /** Sample output: the drawn exemplars, the population size, and agent follow-ups. */
@@ -59,7 +65,15 @@ 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 = `Either nothing matched — try a wider filter — or the store has nothing in it yet: build it with \`${BIN_NAME} sources update\`.`;
+export const DEFAULT_EMPTY_RECOVERY: PackEmptyRecovery = {
+  message:
+    "Either nothing matched — try a wider filter — or the store has nothing in it yet and needs building.",
+  call: BUILD_STORE_CALL,
+};
+
+/** What a filtered empty page says first: the store is fine, the filter missed. */
+const FILTERED_EMPTY_HINT =
+  "The store answered and nothing carries that — drop the argument, or loosen it, to widen the read.";
 
 /**
  * Build the list formatters for a list-shaped verb (list or an extra verb).
@@ -93,42 +107,67 @@ export function listFormatters(
   // Zero results is a calm success, not an error (see runBodies.makeListRun):
   // render a non-blank message, exit 0, JSON stays []. A pack's authored
   // `emptyRecovery` becomes the hint; otherwise the generic build/broaden hint.
-  const emptyHint = shape.emptyRecovery
-    ? `${shape.emptyRecovery.message}${
-        shape.emptyRecovery.cli
-          ? ` Run \`${RECOVERY_CLI_PREFIX}${shape.emptyRecovery.cli}\`.`
-          : ""
-      }`
-    : DEFAULT_EMPTY_HINT;
-  const options: RenderListOptions<PackRow> = {
+  // Built per call, not once: the hint ends in the next call to make, spelled
+  // for the surface that is about to print it.
+  const { message, call } = shape.emptyRecovery ?? DEFAULT_EMPTY_RECOVERY;
+  const hintFor = (surface: Surface): string =>
+    call ? `${message} ${renderNextStep(call, surface)}` : message;
+  // A FILTERED empty page is a miss, not an empty store: it says how to widen,
+  // keeps the story's own account of the emptiness, and drops the rebuild call
+  // (any other next step a story declares — listing the values — still helps).
+  const declared = shape.emptyRecovery;
+  const filteredHintFor = (surface: Surface): string =>
+    [
+      FILTERED_EMPTY_HINT,
+      declared?.message,
+      declared?.call && declared.call.verb !== BUILD_STORE_CALL.verb
+        ? renderNextStep(declared.call, surface)
+        : undefined,
+    ]
+      .filter(Boolean)
+      .join(" ");
+  const optionsFor = (surface: Surface): RenderListOptions<PackRow> => ({
     heading: meta.heading,
     columns,
     prefixes: meta.prefixes,
     emptyMessage: `No ${meta.noun} entries found.`,
-    emptyHint,
-  };
+    emptyHint: hintFor(surface),
+  });
   return {
-    plain: (page, context) => renderListPlain(page.rows, options, context),
+    plain: (page, context) =>
+      renderListPlain(page.rows, optionsFor("cli"), context),
     llm: (page) => {
-      const body = renderListLlm(page.rows, emptyCopy(page, meta, options), {
-        more: page.nextAfter !== undefined,
-        ...(scopeText(page) === undefined
-          ? {}
-          : { scope: scopeText(page) as string }),
-      });
-      const notice = listNotice(page, meta);
+      const body = renderListLlm(
+        page.rows,
+        emptyCopy(page, meta, optionsFor("cli"), "cli", filteredHintFor("cli")),
+        {
+          more: page.nextAfter !== undefined,
+          ...(scopeText(page) === undefined
+            ? {}
+            : { scope: scopeText(page) as string }),
+        },
+      );
+      const notice = listNotice(page, meta, "cli");
       return notice ? `${body}\n\n${notice}` : body;
     },
     json: (page) => JSON.stringify(page.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: (page) =>
+    notice: (page, surface = "cli") =>
       page.rows.length === 0
         ? joinNotices([
-            renderListEmptyNotice(emptyCopy(page, meta, options)),
-            scopeNotice(page),
+            renderListEmptyNotice(
+              emptyCopy(
+                page,
+                meta,
+                optionsFor(surface),
+                surface,
+                filteredHintFor(surface),
+              ),
+            ),
+            scopeNotice(page, surface),
           ])
-        : listNotice(page, meta),
+        : listNotice(page, meta, surface),
     // The scope rides the envelope as DATA as well as prose: an agent deciding
     // whether to widen the read should not have to parse a sentence to learn
     // which tiers it got.
@@ -136,9 +175,22 @@ export function listFormatters(
   };
 }
 
-/** The tier scope in the words `--tier` accepts, or nothing when unscoped. */
+/**
+ * The tier scope in the words `--tier` accepts, each tier with its share of
+ * the whole filtered answer; an EMPTY page also names the tiers outside the
+ * scope that hold a match. Nothing when unscoped.
+ */
 function scopeText(page: PackPage): string | undefined {
-  return page.scope ? page.scope.tiers.join(", ") : undefined;
+  if (!page.scope) return undefined;
+  const { tiers, counts } = page.scope;
+  if (!counts) return tiers.join(", ");
+  const held = (tier: string): string => `${tier} ${counts[tier] ?? 0}`;
+  const inside = [...tiers, ...(UNTIERED_KEY in counts ? [UNTIERED_KEY] : [])];
+  const outside = Object.keys(counts).filter((tier) => !inside.includes(tier));
+  const text = inside.map(held).join(", ");
+  return page.rows.length > 0 || outside.length === 0
+    ? text
+    : `${text}; other tiers: ${outside.map(held).join(", ")}`;
 }
 
 /**
@@ -150,18 +202,25 @@ function scopeText(page: PackPage): string | undefined {
  * the scope — and the notice seam is where this package already puts what the
  * data cannot say about itself.
  */
-function scopeNotice(page: PackPage): string | undefined {
+function scopeNotice(page: PackPage, surface: Surface): string | undefined {
   const scope = scopeText(page);
   if (scope === undefined) return undefined;
   return (
     `Tier scope: ${scope}. ` +
-    `Pass \`--tier <name>\` for one tier and its ancestors, or \`--tier ${EVERY_TIER}\` for every tier.`
+    `Pass ${quoteArgument(TIER_PARAM, "<name>", surface)} for one tier and its ancestors, or ${quoteArgument(TIER_PARAM, EVERY_TIER, surface)} for every tier.`
   );
 }
 
 /** The page's notices, in the order a reader needs them: scope, then paging. */
-function listNotice(page: PackPage, meta: RenderMeta): string | undefined {
-  return joinNotices([scopeNotice(page), pageNotice(page, meta)]);
+function listNotice(
+  page: PackPage,
+  meta: RenderMeta,
+  surface: Surface,
+): string | undefined {
+  return joinNotices([
+    scopeNotice(page, surface),
+    pageNotice(page, meta, surface),
+  ]);
 }
 
 /** Join what a page has to say into one notice, dropping what it has not. */
@@ -175,46 +234,40 @@ function joinNotices(
 /**
  * The empty-state copy this page deserves.
  *
- * Two facts can empty a list and zero rows cannot tell them apart: nothing was
- * there, or a filter missed what was. Both are worth saying and they are not
- * exclusive, so a filtered empty page says both — the kernel's own sentence
- * names the arguments the caller typed, and the story's `emptyRecovery` follows
- * it on the next line, exactly as it does on an unfiltered page.
- *
- * It did not, briefly: a filtered empty page reported only the narrowing,
- * because the recoveries of the day asserted an empty store ("No token symbols
- * in the store … run `pragma sources update`") and so told a reader with 745
- * symbols in it to rebuild for nothing. That is a WORDING defect, and it is
- * fixed where it lives — a story's recovery is now written to hold whether the
- * population is empty or a filter missed a populated one, or the story declares
- * none. Suppressing it here cost more than it saved: `token consumers --symbol
- * color.text` narrows a table that records no bindings at all, and "No token
- * matches `--symbol color.text`." on its own read as a mistyped symbol while
- * withholding the one account of the emptiness that verb has.
+ * Two facts can empty a list: nothing was there, or a filter missed what was.
+ * An unfiltered empty page gets the story's `emptyRecovery` whole. A filtered
+ * one names the arguments the caller typed and takes `filteredHint` instead —
+ * see {@link listFormatters} for what that keeps and drops.
  *
  * @param page - The rendered page (its rows and the filters that cut them).
  * @param meta - The noun, for the sentence.
  * @param base - The story's own empty copy.
- * @returns `base` unchanged, or `base` with the filter-shaped message — the
- *   story's own hint is kept either way.
+ * @param filteredHint - The hint a filtered empty page carries.
+ * @returns `base` unchanged, or `base` with the filter-shaped message and hint.
  */
 function emptyCopy(
   page: PackPage,
   meta: RenderMeta,
   base: RenderListOptions<PackRow>,
+  surface: Surface,
+  filteredHint: string,
 ): RenderListOptions<PackRow> {
   const applied = page.filters ?? [];
   if (page.rows.length > 0 || applied.length === 0) return base;
   return {
     ...base,
-    emptyMessage: `No ${meta.noun} matches ${listFilters(applied)}.`,
+    emptyMessage: `No ${meta.noun} matches ${listFilters(applied, surface)}.`,
+    emptyHint: filteredHint,
   };
 }
 
 /** The filters in force, as flags a reader can edit: `\`--kind input\`` … */
-function listFilters(applied: readonly PackAppliedFilter[]): string {
-  const flags = applied.map(
-    (filter) => `\`--${kebabCase(filter.param)} ${filter.value}\``,
+function listFilters(
+  applied: readonly PackAppliedFilter[],
+  surface: Surface,
+): string {
+  const flags = applied.map((filter) =>
+    quoteArgument(filter.param, filter.value, surface),
   );
   const last = flags.at(-1) as string;
   return flags.length === 1
@@ -231,12 +284,16 @@ function listFilters(applied: readonly PackAppliedFilter[]): string {
  * that carry this are read by agents — so the sentence contains the flag, the
  * value, and the tool parameter, ready to copy.
  */
-function pageNotice(page: PackPage, meta: RenderMeta): string | undefined {
+function pageNotice(
+  page: PackPage,
+  meta: RenderMeta,
+  surface: Surface,
+): string | undefined {
   if (page.nextAfter === undefined) return undefined;
   return (
     `Showing ${page.rows.length} ${meta.noun} entries, and more exist. ` +
-    `For the next page pass \`--after ${page.nextAfter}\` ` +
-    `(\`after\` over MCP), or raise \`--limit\` (currently ${page.limit}).`
+    `For the next page pass ${quoteArgument("after", page.nextAfter, surface)}, ` +
+    `or raise ${surface === "mcp" ? "`limit`" : "`--limit`"} (currently ${page.limit}).`
   );
 }
 
@@ -292,9 +349,29 @@ export function lookupFormatters(
     llm: (output) =>
       renderOutput(output, (entity) => renderLookupLlm(entity, options), "llm"),
     json: (output) => JSON.stringify(output, null, 2),
+    notice: (output, surface = "cli") => truncationNotice(output, surface),
   };
 }
 
+/** What a capped pattern says for itself, on the notice seam and in the llm body. */
+function truncationNotice(
+  output: LookupOutput,
+  surface: Surface,
+): string | undefined {
+  if (!output.truncated) return undefined;
+  const advice =
+    output.detail === "summary"
+      ? ""
+      : `, or pass ${quoteArgument("detail", "summary", surface)} for smaller entries`;
+  const elsewhere = output.elsewhere
+    ? `, and ${output.elsewhere} more in other tiers: pass ${quoteArgument(TIER_PARAM, EVERY_TIER, surface)}`
+    : "";
+  return (
+    `${output.results.length} of ${output.total} matches shown${elsewhere}. ` +
+    `Narrow the pattern to reach the rest${advice}.`
+  );
+}
+
 /** Build the sample formatters (renders each exemplar, then the follow-ups). */
 export function sampleFormatters(
   lookup: PackLookup,
@@ -366,6 +443,9 @@ function renderOutput(
       `${mode === "llm" ? "### Not found" : "Not found:"}\n${lines.join("\n")}`,
     );
   }
+  const truncation =
+    mode === "llm" ? truncationNotice(output, "cli") : undefined;
+  if (truncation) bodies.push(truncation);
   return bodies.join("\n\n").trimEnd();
 }
 

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

@@ -32,7 +32,7 @@ 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 { GLOB_EXPANSION_CAP, type LookupOutput } from "./resolveEntity.js";
 import type { PackDefinition, PackLookup } from "./types.js";
 import { distributionSource } from "./types.js";
 import { verbKey } from "./uniqueness.js";
@@ -259,6 +259,70 @@ describe("pack lookup addressing (PROTECTED)", () => {
     });
   });
 
+  describe("a glob with no prefix reads names AND IRI local names", () => {
+    it("reaches an entity through its local name", async () => {
+      // The recorded case: `*.component.meter` is a pattern over what every
+      // list prints, and it matched nothing while names were the only thing a
+      // prefix-less glob was tried against.
+      const out = await lookupVia(SPQ, "*.timeline");
+      expect(out.errors).toEqual([]);
+      expect(uris(out)).toEqual([`${DS}padded.timeline`]);
+    });
+
+    it("reaches an entity that carries no name at all", async () => {
+      expect(uris(await lookupVia(SPQ, "nameless.*"))).toEqual([
+        `${DS}nameless.widget`,
+      ]);
+    });
+
+    it("answers ONCE for an entity both its name and its local name match", async () => {
+      // `*chip` fits the name "Chip" and the local names `alpha.chip` and
+      // `zeta.chip`. The name match already reaches both, so neither is looked
+      // up a second time by IRI.
+      const out = await lookupVia(SPQ, "*chip");
+      expect(uris(out).sort()).toEqual([`${DS}alpha.chip`, `${DS}zeta.chip`]);
+    });
+
+    it("does not make a bare local name an address", async () => {
+      await expect(lookupVia(SPQ, "alpha.chip")).rejects.toMatchObject({
+        code: "ENTITY_NOT_FOUND",
+      });
+    });
+  });
+
+  describe("a miss suggests the real thing", () => {
+    const suggestionsFor = async (query: string): Promise<string[]> => {
+      const reason = await lookupVia(SPQ, query).catch(
+        (error: unknown) => error,
+      );
+      expect(reason).toMatchObject({ code: "ENTITY_NOT_FOUND" });
+      return (reason as { suggestions: string[] }).suggestions;
+    };
+
+    it("answers a pasted local name with its prefixed IRI, then the name inside it", async () => {
+      expect((await suggestionsFor("alpha.chip")).slice(0, 2)).toEqual([
+        "ds:alpha.chip",
+        "Chip",
+      ]);
+    });
+
+    it("answers a mistyped local name with the prefixed IRI it was near", async () => {
+      expect(await suggestionsFor("nameless.widgit")).toContain(
+        "ds:nameless.widget",
+      );
+    });
+
+    it("every suggestion it prints resolves", async () => {
+      const suggestions = await suggestionsFor("alpha.chip");
+      const out = await lookupVia(SPQ, ...suggestions);
+      expect(out.errors).toEqual([]);
+    });
+
+    it("keeps the five-suggestion cap", async () => {
+      expect((await suggestionsFor("a")).length).toBeLessThanOrEqual(5);
+    });
+  });
+
   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
@@ -331,3 +395,108 @@ describe("pack lookup addressing (PROTECTED)", () => {
     });
   });
 });
+
+describe("a glob says what it did", () => {
+  /** More same-family entities than one lookup's patterns may expand to. */
+  const FAMILY = GLOB_EXPANSION_CAP + 12;
+  const pad = (index: number): string => String(index).padStart(3, "0");
+  const FAMILY_TTL = Array.from(
+    { length: FAMILY },
+    (_, index) =>
+      `ds:swatch.${pad(index)} a ds:Component ; ds:name "swatch.${pad(index)}" .`,
+  ).join("\n");
+
+  let rt: PragmaRuntime;
+  beforeAll(async () => {
+    ({ rt } = await buildFixtureRuntime({
+      ttl: BLOCK_TTL + AMBIGUOUS_TTL + FAMILY_TTL,
+      prefixes: BLOCK_PREFIXES,
+      detail: "detailed",
+    }));
+  });
+  afterAll(async () => {
+    (await rt.store.get()).store.dispose();
+  });
+
+  const lookup = (...name: string[]): Promise<LookupOutput> => {
+    const verb = compilePack(SPQ, distributionSource("t"), BLOCK_PREFIXES).find(
+      (v) => verbKey(v.path) === "sblock lookup",
+    );
+    if (!verb) throw new Error("no lookup verb");
+    return verb.run({ name }, rt) as Promise<LookupOutput>;
+  };
+  const formatters = lookupFormatters(SPQ.lookup as PackLookup, BLOCK_PREFIXES);
+
+  it("cuts a wide pattern at the cap and reports the true total", async () => {
+    const out = await lookup("swatch.*");
+    expect(out.results).toHaveLength(GLOB_EXPANSION_CAP);
+    expect(out).toMatchObject({ truncated: true, total: FAMILY });
+  });
+
+  it("says so in each surface's own spelling, and in the condensed body", async () => {
+    const out = await lookup("swatch.*");
+    const counted = `${GLOB_EXPANSION_CAP} of ${FAMILY} matches shown.`;
+    expect(formatters.notice?.(out, "cli")).toContain(counted);
+    expect(formatters.notice?.(out, "cli")).toContain("`--detail summary`");
+    expect(formatters.notice?.(out, "mcp")).toContain('`detail: "summary"`');
+    expect(formatters.llm(out).split("\n").at(-1)).toContain(counted);
+    expect(JSON.parse(formatters.json(out)).total).toBe(FAMILY);
+  });
+
+  it("does not advise summary to a caller already there", () => {
+    const out: LookupOutput = {
+      results: [],
+      errors: [],
+      truncated: true,
+      total: FAMILY,
+      detail: "summary",
+    };
+    expect(formatters.notice?.(out, "mcp")).toBe(
+      `0 of ${FAMILY} matches shown. Narrow the pattern to reach the rest.`,
+    );
+  });
+
+  it("counts ENTITIES: a name route and an IRI route to the same ones are one total", async () => {
+    const out = await lookup("swatch.*", "ds:swatch.*");
+    expect(out.total).toBe(FAMILY);
+    expect(out.results).toHaveLength(GLOB_EXPANSION_CAP);
+  });
+
+  it("cuts the same fifty every time, in name order", async () => {
+    const names = (await lookup("swatch.*")).results.map((e) => e.name);
+    expect(names).toEqual(
+      Array.from({ length: GLOB_EXPANSION_CAP }, (_, i) => `swatch.${pad(i)}`),
+    );
+    expect(
+      (await lookup("*.0*", "swatch.*")).results.map((e) => e.name),
+    ).toEqual(names);
+  });
+
+  it("says nothing about a pattern answered in full", async () => {
+    const out = await lookup("swatch.00*");
+    expect(out.results).toHaveLength(10);
+    expect(out.truncated).toBeUndefined();
+    expect(formatters.notice?.(out, "cli")).toBeUndefined();
+  });
+
+  it("counts an entry ONCE across overlapping patterns", async () => {
+    // Twenty-seven matches over twenty-five entries: `swatch.001` and
+    // `swatch.011` are each matched twice and answered once.
+    const out = await lookup("swatch.00*", "swatch.0*1", "swatch.01*");
+    expect(out.truncated).toBeUndefined();
+    expect(out.results.map((entity) => entity.name)).toHaveLength(25);
+    expect(new Set(out.results.map((entity) => entity.uri)).size).toBe(25);
+  });
+
+  it("answers once for an entity a name pattern and an IRI pattern both reach", async () => {
+    const out = await lookup("swatch.001", "ds:swatch.001", "ds:swatch.00*");
+    expect(out.results).toHaveLength(10);
+  });
+
+  it("never cuts a literal — not even one a cut pattern also matched", async () => {
+    const last = `swatch.${pad(FAMILY - 1)}`;
+    const out = await lookup("swatch.*", last);
+    expect(out.results.map((entity) => entity.name)).toContain(last);
+    expect(out.results).toHaveLength(GLOB_EXPANSION_CAP + 1);
+  });
+});