@canonical/pragma-cli 0.38.0 → 0.42.0

package/src/kernel/packs/runBodies.ts

@@ -10,7 +10,7 @@
  * (lazy), so these factories carry no heavy static import.
  */
 
-import { cliRecovery, PragmaError } from "../error/index.js";
+import { PragmaError } from "../error/index.js";
 import type { PragmaRuntime } from "../runtime/index.js";
 import { encodeCursor, pageFingerprint, readCursor } from "./cursor.js";
 import { resolvePackDetail } from "./disclosure.js";
@@ -20,10 +20,17 @@ import {
   type LookupOutput,
   type LookupScope,
   listEntityNames,
+  listRecovery,
+  resolveEntityIris,
   resolveLookup,
 } from "./resolveEntity.js";
 import { parseSampleCount, pickRandom } from "./sample.js";
-import { buildListQuery } from "./sparql/buildListQuery.js";
+import {
+  buildListQuery,
+  buildTierCountQuery,
+  type ListPredicate,
+  type ListTierScope,
+} from "./sparql/buildListQuery.js";
 import {
   type FilterVocabularies,
   resolveFilterPredicates,
@@ -31,6 +38,7 @@ import {
 import { runSelect } from "./sparql/runSelect.js";
 import { readSearchTerm } from "./sparql/searchTerm.js";
 import {
+  localName,
   resolveReadScope,
   scopeIris,
   scopeLabel,
@@ -38,34 +46,21 @@ import {
 } from "./tierScope.js";
 import {
   ENTITY_VARIABLE,
+  type NounLookups,
   type PackAppliedFilter,
   type PackFilter,
   type PackList,
   type PackLookup,
   type PackPage,
   type PackTierScope,
+  type PageTierScope,
   type StorySource,
+  UNTIERED_KEY,
 } from "./types.js";
 
 /** The highest canonical level — sample fetches everything for shape discovery. */
 const HIGHEST_LEVEL = "detailed";
 
-/**
- * The recovery every lookup-shaped miss carries: browse the noun's list.
- *
- * `mcp.params` is populated rather than left off. A bare tool NAME is only half
- * an instruction to an agent — it still has to guess an argument bag, and a
- * guess that misses returns `-32602 Invalid arguments`, which reads like the
- * recovery itself was wrong. `{}` is the concrete, valid call: every compiled
- * list verb's params are optional, so the recovery is now copy-pasteable.
- */
-function listRecovery(noun: string) {
-  return cliRecovery(`${noun} list`, `List available ${noun} entries.`, {
-    tool: `${noun}_list`,
-    params: {},
-  });
-}
-
 /** Facts a list-shaped run body needs beyond its `shape`. */
 export interface ListRunMeta {
   readonly source: StorySource;
@@ -75,6 +70,10 @@ export interface ListRunMeta {
    * are. Absent leaves the read exactly as it was.
    */
   readonly tierScope?: PackTierScope;
+  /** The prefix map a prefixed IRI handed to a noun filter expands against. */
+  readonly prefixes: Readonly<Record<string, string>>;
+  /** The other stories' lookups, for a filter that names a noun. */
+  readonly nouns?: NounLookups;
 }
 
 /**
@@ -104,12 +103,20 @@ export function makeListRun(
       params,
       meta.source,
     );
-    const predicates = resolveFilterPredicates(
-      shape.filters,
-      params,
-      vocabularies,
-      meta.source.label,
-    );
+    const predicates = [
+      ...resolveFilterPredicates(
+        shape.filters?.filter((filter) => filter.noun === undefined),
+        params,
+        vocabularies,
+        meta.source.label,
+      ),
+      ...(await resolveNounPredicates(rt, shape.filters, params, meta)),
+    ];
+    // Left out of the rows: over the shipped pack the IRIs a noun filter
+    // constrains took the largest list past its payload budget (108 KB).
+    const omit = (shape.filters ?? [])
+      .flatMap((filter) => (filter.entity ? [filter.entity] : []))
+      .filter((name) => !shape.columns.some((column) => column.field === name));
     const search = readSearchTerm(shape.search, params);
     const scope = await resolveReadScope(
       rt,
@@ -142,18 +149,31 @@ export function makeListRun(
       ...(listScope ? [JSON.stringify(tiers)] : []),
     ]);
     const offset = readCursor(params.after, fingerprint);
+    const read = {
+      query: shape.query,
+      predicates,
+      ...(search ? { search } : {}),
+      label: meta.source.label,
+    };
     const rows = await runSelect(
       rt,
       buildListQuery({
-        query: shape.query,
-        predicates,
-        ...(search ? { search } : {}),
+        ...read,
         ...(listScope ? { scope: listScope } : {}),
+        omit,
         window: { limit: limit + 1, offset },
-        label: meta.source.label,
       }),
       meta.source,
     );
+    // First page only, and never the reason a list fails.
+    const counts =
+      scope?.kind === "tiers" && listScope && params.after === undefined
+        ? await readTierCounts(
+            rt,
+            { ...read, scope: listScope },
+            meta.source,
+          ).catch(() => undefined)
+        : undefined;
     const hasMore = rows.length > limit;
     const applied = appliedFilters(shape, params, search?.term, scope);
     return {
@@ -163,13 +183,45 @@ export function makeListRun(
         : {}),
       ...(applied.length > 0 ? { filters: applied } : {}),
       ...(scope?.kind === "tiers"
-        ? { scope: { tiers: scope.tiers.map((tier) => tier.local) } }
+        ? {
+            scope: {
+              tiers: scope.tiers.map((tier) => tier.local),
+              ...(counts ? { counts } : {}),
+            },
+          }
         : {}),
       limit,
     };
   };
 }
 
+/**
+ * Count the whole filtered answer's rows per tier: every in-scope tier (0 when
+ * it holds none), then the out-of-scope tiers that hold some, then
+ * {@link UNTIERED_KEY} when any row's entity is in no tier.
+ */
+async function readTierCounts(
+  rt: PragmaRuntime,
+  read: Parameters<typeof buildTierCountQuery>[0] & { scope: ListTierScope },
+  source: StorySource,
+): Promise<NonNullable<PageTierScope["counts"]>> {
+  const query = buildTierCountQuery(read);
+  const byIri = query.read(await runSelect(rt, query.text, source));
+  const inScope = read.scope.tiers.map(
+    (iri) => [localName(iri), byIri.get(iri) ?? 0] as const,
+  );
+  const outside = [...byIri]
+    .filter(([iri]) => iri !== "" && !read.scope.tiers.includes(iri))
+    .map(([iri, count]) => [localName(iri), count] as const)
+    .sort(([a], [b]) => a.localeCompare(b));
+  const untiered = byIri.get("");
+  return Object.fromEntries([
+    ...inScope,
+    ...outside,
+    ...(untiered ? [[UNTIERED_KEY, untiered] as const] : []),
+  ]);
+}
+
 /**
  * The filters this read was narrowed by, in the spelling the caller used.
  *
@@ -259,6 +311,52 @@ async function readFilterVocabularies(
   return resolved;
 }
 
+/**
+ * Turn the values a caller supplied for each NOUN filter into a constraint on
+ * the entities they name.
+ *
+ * @returns One `"iri"` predicate per noun filter the caller used, over the
+ *   IRIs its values reached. Against a store holding none of that noun's
+ *   entities the predicate names no IRI and the list answers empty.
+ * @throws PragmaError INVALID_INPUT when a value reaches no entity of the noun;
+ *   CONFIG_ERROR when no story known to this one declares a lookup for it.
+ */
+async function resolveNounPredicates(
+  rt: PragmaRuntime,
+  filters: readonly PackFilter[] | undefined,
+  params: Record<string, unknown>,
+  meta: ListRunMeta,
+): Promise<ListPredicate[]> {
+  const predicates: ListPredicate[] = [];
+  for (const filter of filters ?? []) {
+    const provided = params[filter.param];
+    if (!filter.noun || !filter.entity || provided === undefined) continue;
+    const occurrences = Array.isArray(provided) ? provided : [provided];
+    if (occurrences.length === 0) continue;
+    const lookup = meta.nouns?.(filter.noun);
+    if (!lookup) {
+      throw PragmaError.configError(
+        `Filter "--${filter.param}" in ${meta.source.label} names the noun "${filter.noun}", and no story declares a lookup for it.`,
+      );
+    }
+    const terms = await resolveEntityIris(
+      rt,
+      lookup,
+      filter.noun,
+      occurrences.map((value) => String(value).trim().normalize("NFC")),
+      meta.source,
+      meta.prefixes,
+    );
+    predicates.push({
+      variable: filter.entity,
+      match: "iri",
+      terms,
+      ...(filter.via ? { via: filter.via } : {}),
+    });
+  }
+  return predicates;
+}
+
 /**
  * Build the run body for a lookup verb (variadic names → resolved entities).
  *
@@ -274,6 +372,7 @@ export function makeLookupRun(
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  hasList: boolean,
   tierScope?: PackTierScope,
 ): (
   params: Record<string, unknown>,
@@ -291,6 +390,7 @@ export function makeLookupRun(
       source,
       prefixes,
       level,
+      hasList,
       lookupScope(tierScope, scope),
     );
     // A total miss (single or all-miss) exits non-zero; a partial batch renders
@@ -302,7 +402,7 @@ export function makeLookupRun(
           code: first.code as PragmaError["code"],
           message: first.message,
           suggestions: first.suggestions ? [...first.suggestions] : undefined,
-          recovery: listRecovery(noun),
+          recovery: listRecovery(noun, hasList),
         });
       }
     }
@@ -346,6 +446,7 @@ export function makeSampleRun(
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   defaultCount: number,
+  hasList: boolean,
 ): (
   params: Record<string, unknown>,
   rt: PragmaRuntime,
@@ -358,7 +459,7 @@ export function makeSampleRun(
     if (names.length === 0) {
       throw PragmaError.emptyResults(noun, {
         message: `No ${noun} entries to sample.`,
-        recovery: listRecovery(noun),
+        recovery: listRecovery(noun, hasList),
       });
     }
     const selected = pickRandom(names, count);
@@ -370,6 +471,7 @@ export function makeSampleRun(
       source,
       prefixes,
       HIGHEST_LEVEL,
+      hasList,
     );
     return {
       samples: output.results,

package/src/kernel/packs/schema.ts

@@ -25,7 +25,7 @@
  */
 
 import { z } from "zod";
-import { DETAIL_LEVELS, RECOVERY_CLI_PREFIX } from "../../constants.js";
+import { DETAIL_LEVELS } from "../../constants.js";
 import { PragmaError } from "../error/index.js";
 import { listShapeIssues, tierScopeIssues } from "./storyRules.js";
 import {
@@ -33,6 +33,7 @@ import {
   type PackList,
   type PackTierScope,
   RESERVED_STORY_PARAMS,
+  VERB_PATH_PATTERN,
 } from "./types.js";
 
 const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -96,8 +97,14 @@ const term = z.string().regex(TERM_PATTERN, "must be a prefixed name or IRI");
 const graphqlName = z.string().regex(GRAPHQL_NAME_PATTERN);
 const fieldName = z.string().regex(FIELD_PATTERN);
 
+const nounName = z.string().regex(NOUN_PATTERN, NOUN_MESSAGE);
+
 const columnSchema = z
-  .object({ field: fieldName, label: z.string().optional() })
+  .object({
+    field: fieldName,
+    label: z.string().optional(),
+    noun: nounName.optional(),
+  })
   .strict();
 
 const vocabularySchema = z
@@ -114,12 +121,22 @@ const filterSchema = z
     values: z.array(z.string()).min(1).optional(),
     match: z.enum(["exact", "set"]).optional(),
     vocabulary: vocabularySchema.optional(),
+    noun: nounName.optional(),
+    entity: fieldName.optional(),
+    via: term.optional(),
     description: z.string().optional(),
   })
   .strict()
   .refine((f) => !RESERVED_PARAMS.has(f.param), {
     message: "filter param is a reserved name",
   })
+  .refine((f) => !(f.noun && (f.values || f.vocabulary || f.match)), {
+    message:
+      '"noun" is mutually exclusive with "values", "vocabulary" and "match" — the named noun admits the values and the rows are matched by IRI',
+  })
+  .refine((f) => f.noun !== undefined || !(f.entity || f.via), {
+    message: '"entity" and "via" belong to a filter that names a "noun"',
+  })
   // A declared `values` set IS the vocabulary — the filter projects it as an
   // enum and canonicalizes against it. A second, graph-read one alongside would
   // be a silent no-op at best and a disagreement at worst.
@@ -144,25 +161,44 @@ const searchSchema = z
   })
   .strict();
 
+// A call names a VERB PATH (`sources update`) and a param bag — never a command
+// line. A story is portable only if it names no binary and spells no flags: the
+// consuming distribution's renderer does both, for the surface it prints on.
+const callSchema = z
+  .object({
+    verb: z
+      .string()
+      .regex(
+        VERB_PATH_PATTERN,
+        'a call names a verb path — write "sources update", not a command line',
+      ),
+    params: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
 const emptyRecoverySchema = z
   .object({
     message: z.string().min(1),
-    // The command WITHOUT a binary name — the renderer prepends the CONSUMING
-    // distribution's. A story is portable only if it does not name a binary, so
-    // the old prefixed form is rejected rather than accepted and doubled. Named
-    // loudly, in the `packages` → `packs` tradition, because a third-party pack
-    // written against the old grammar is data, not a typo.
+    call: callSchema.optional(),
+    // The retired spelling, named loudly in the `packages` → `packs` tradition:
+    // a third-party pack written against the old grammar is data, not a typo.
     cli: z
-      .string()
-      .min(1)
+      .unknown()
       .refine(
-        (value) => !value.startsWith(RECOVERY_CLI_PREFIX),
-        `emptyRecovery.cli is now the command WITHOUT the binary name — write "sources update", not "${RECOVERY_CLI_PREFIX}sources update"`,
+        (value) => value === undefined,
+        'emptyRecovery.cli is now emptyRecovery.call — write call: { verb: "sources update" }, not cli: "sources update"',
       )
       .optional(),
   })
   .strict();
 
+// What a story half tells a caller choosing between tools. Optional: the schema
+// is strict and third-party packs predate these.
+const guidanceShape = {
+  useWhen: z.string().min(1).optional(),
+  example: z.record(z.string(), z.unknown()).optional(),
+};
+
 const listShape = {
   query: z.string().min(1),
   columns: z.array(columnSchema).min(1),
@@ -178,6 +214,7 @@ const verbSchema = z
     verb: z.string().regex(NOUN_PATTERN, NOUN_MESSAGE),
     description: z.string().optional(),
     toolDescription: z.string().optional(),
+    ...guidanceShape,
   })
   .strict();
 
@@ -188,6 +225,7 @@ const fieldSchema = z
     label: z.string().optional(),
     graphqlField: graphqlName.optional(),
     level: z.string().optional(),
+    noun: nounName.optional(),
   })
   .strict();
 
@@ -223,8 +261,14 @@ const expandFieldSchema = z
     label: z.string().optional(),
     graphqlField: graphqlName.optional(),
     blankWhenSelf: z.literal(true).optional(),
+    many: z.literal(true).optional(),
+    noun: nounName.optional(),
   })
-  .strict();
+  .strict()
+  .refine((f) => !(f.many && f.blankWhenSelf), {
+    message:
+      '"many" and "blankWhenSelf" are mutually exclusive — a set of values has no single one to compare with the entity\'s own',
+  });
 
 const expandSchema = z
   .object({
@@ -276,6 +320,7 @@ const sampleSchema = z.union([
       fixedCount: z.boolean().optional(),
       description: z.string().optional(),
       toolDescription: z.string().optional(),
+      ...guidanceShape,
     })
     .strict(),
 ]);
@@ -328,6 +373,7 @@ const lookupSchema = z
     type: term.optional(),
     description: z.string().optional(),
     toolDescription: z.string().optional(),
+    ...guidanceShape,
     types: z.array(term).min(1).optional(),
     weights: z.record(term, z.number().min(0).max(1)).optional(),
     scopeWeight: scopeWeightSchema.optional(),
@@ -346,6 +392,7 @@ const definitionSchema = z
     noun: z.string().regex(NOUN_PATTERN, NOUN_MESSAGE),
     description: z.string().optional(),
     toolDescription: z.string().optional(),
+    ...guidanceShape,
     list: listSchema.optional(),
     verbs: z.array(verbSchema).min(1).optional(),
     lookup: lookupSchema.optional(),
@@ -599,6 +646,24 @@ function refineLookup(
           path: ["lookup"],
         });
       }
+      if ("many" in entry && entry.many && expandSource !== "sparql") {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `expand "${expand.name}" field "${entry.name}" sets "many", which only the SPARQL lane can express — set the expand's "source" to "sparql".`,
+          path: ["lookup"],
+        });
+      }
+      if (
+        "many" in entry &&
+        entry.many &&
+        expand.orderBy?.includes(entry.name)
+      ) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `expand "${expand.name}" orders by "${entry.name}", a "many" field — a set of values has no order to sort on.`,
+          path: ["lookup"],
+        });
+      }
     }
     if (expand.orderBy !== undefined) {
       if (expandSource !== "sparql") {

package/src/kernel/packs/sparql/buildListQuery.test.ts

@@ -12,7 +12,7 @@
 
 import { describe, expect, it } from "vitest";
 import { PragmaError } from "../../error/index.js";
-import { buildListQuery } from "./buildListQuery.js";
+import { buildListQuery, buildTierCountQuery } from "./buildListQuery.js";
 
 /** The author query every case below wraps: aggregate, grouped, ordered. */
 const AUTHORED = [
@@ -342,3 +342,80 @@ describe("buildListQuery — a story it cannot serve", () => {
     );
   });
 });
+
+describe("buildTierCountQuery — the whole filtered answer, per tier", () => {
+  const scope = {
+    entity: "uri",
+    via: "ds:tier",
+    tiers: ["https://ds.canonical.com/global"],
+  };
+  const build = (query = AUTHORED) =>
+    buildTierCountQuery({
+      query,
+      predicates: [{ variable: "category", match: "exact", terms: ["react"] }],
+      search: { variables: ["name"], term: "props" },
+      scope,
+      label,
+    }).text;
+
+  it("wraps the author query under the page's own filter and search clauses", () => {
+    const page = buildListQuery({
+      query: AUTHORED,
+      predicates: [{ variable: "category", match: "exact", terms: ["react"] }],
+      search: { variables: ["name"], term: "props" },
+      window,
+      label,
+    });
+    const clauses = page
+      .split("\n")
+      .filter((line) => line.startsWith("  FILTER EXISTS"));
+    expect(clauses).toHaveLength(2);
+    for (const clause of clauses) expect(build()).toContain(clause);
+    // The author's text is inside it verbatim, as it is inside the page.
+    expect(build()).toContain(AUTHORED);
+  });
+
+  it("groups by the row's tier, which is OPTIONAL so an untiered row counts", () => {
+    expect(build()).toMatch(
+      /SELECT \?(\w+) \(COUNT\(\*\) AS \?\w+\)[\s\S]*OPTIONAL \{ \?uri ds:tier \?\1 \}\n\}\nGROUP BY \?\1$/,
+    );
+  });
+
+  it("reads its rows as tier → row count, the unbound tier as the empty key", () => {
+    const query = buildTierCountQuery({
+      query: AUTHORED,
+      predicates: [],
+      scope,
+      label,
+    });
+    const [, tier, count] =
+      /SELECT \?(\w+) \(COUNT\(\*\) AS \?(\w+)\)/.exec(query.text) ?? [];
+    const rows = [
+      {
+        [tier as string]: "https://ds.canonical.com/apps",
+        [count as string]: "3",
+      },
+      { [count as string]: "1" },
+    ];
+    expect([...query.read(rows)]).toEqual([
+      ["https://ds.canonical.com/apps", 3],
+      ["", 1],
+    ]);
+  });
+
+  it("carries neither the page nor the scope it is the breakdown OF", () => {
+    expect(build()).not.toMatch(/\bLIMIT\b|\bOFFSET\b/);
+    expect(build()).not.toContain("https://ds.canonical.com/global");
+  });
+
+  it("refuses an author query already using the generated prefix, filtered or not", () => {
+    expect(() =>
+      buildTierCountQuery({
+        query: "SELECT ?uri ?__pragmaX WHERE { ?uri a ds:Thing }",
+        predicates: [],
+        scope,
+        label,
+      }),
+    ).toThrow(PragmaError);
+  });
+});