@canonical/pragma-cli 0.38.0 → 0.40.0

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

@@ -85,7 +85,7 @@
  */
 
 import { PragmaError } from "../../error/index.js";
-import { RESERVED_VARIABLE_PREFIX } from "../types.js";
+import { type PackRow, RESERVED_VARIABLE_PREFIX } from "../types.js";
 import { readAuthorQuery } from "./authorQuery.js";
 import { escapeSparqlString, formatTerm } from "./escape.js";
 
@@ -93,13 +93,20 @@ import { escapeSparqlString, formatTerm } from "./escape.js";
 export interface ListPredicate {
   /** SELECT variable the filter constrains (without `?`). */
   readonly variable: string;
-  /** Whole-cell comparison, or membership of a whitespace-separated set. */
-  readonly match: "exact" | "set";
+  /**
+   * Whole-cell comparison, membership of a whitespace-separated set, or — for
+   * `"iri"` — identity with one of the entity IRIs in {@link terms}.
+   */
+  readonly match: "exact" | "set" | "iri";
   /**
    * The admitted values, in the graph's own display spelling. Several are a
    * union (the row matches any of them); several FILTERS are a conjunction.
+   * For `"iri"` they are absolute IRIs the store itself returned, and none
+   * at all matches no row.
    */
   readonly terms: readonly string[];
+  /** `"iri"` only: the path from the variable to the entity {@link terms} name. */
+  readonly via?: string;
 }
 
 /** A declared search, with the term a caller actually supplied. */
@@ -152,6 +159,8 @@ export interface ListQueryInput {
   readonly search?: ListSearch;
   /** The tier scope this read answers under, absent when it answers from all. */
   readonly scope?: ListTierScope;
+  /** Projected variables the page leaves out of its rows. */
+  readonly omit?: readonly string[];
   /** The page to return. */
   readonly window: ListWindow;
   /** The story's label, for a configuration diagnosis. */
@@ -171,7 +180,79 @@ export interface ListQueryInput {
  *   the wrong part of their own file.
  */
 export function buildListQuery(input: ListQueryInput): string {
-  const { query, predicates, search, scope, window, label } = input;
+  const { prologue, projection, body, clauses } = readWrapped(input);
+  const shown = projection?.filter((name) => !input.omit?.includes(name));
+  return [
+    ...(prologue === "" ? [] : [prologue]),
+    `SELECT ${shown ? shown.map((variable) => `?${variable}`).join(" ") : "*"}`,
+    "WHERE {",
+    "  {",
+    body,
+    "  }",
+    ...clauses.map((clause) => `  ${clause}`),
+    "}",
+    modifier(input.window),
+  ].join("\n");
+}
+
+/**
+ * Build the SELECT counting a scoped list's whole filtered answer per tier —
+ * the page's wrap without the page and without the scope clause — and the
+ * reader of its rows.
+ *
+ * @param input - The author query, the supplied filters/search, and the scope
+ *   whose `entity` and `via` say how a row reaches its tier.
+ * @returns The query text, and `read`: its rows as tier IRI → row count, with
+ *   `""` for rows whose entity is in no tier. An entity in two tiers counts
+ *   under each.
+ * @throws PragmaError CONFIG_ERROR for the reasons {@link buildListQuery} does.
+ */
+export function buildTierCountQuery(
+  input: Omit<ListQueryInput, "window"> & { readonly scope: ListTierScope },
+): { text: string; read: (rows: readonly PackRow[]) => Map<string, number> } {
+  const { scope } = input;
+  const tier = `${RESERVED_VARIABLE_PREFIX}TierOf`;
+  const count = `${RESERVED_VARIABLE_PREFIX}TierRows`;
+  const { prologue, body, clauses } = readWrapped({
+    ...input,
+    scope: { ...scope, tiers: [] },
+    reserved: true,
+  });
+  const text = [
+    ...(prologue === "" ? [] : [prologue]),
+    `SELECT ?${tier} (COUNT(*) AS ?${count})`,
+    "WHERE {",
+    "  {",
+    body,
+    "  }",
+    ...clauses.map((clause) => `  ${clause}`),
+    `  OPTIONAL { ?${scope.entity} ${formatTerm(scope.via)} ?${tier} }`,
+    "}",
+    `GROUP BY ?${tier}`,
+  ].join("\n");
+  return {
+    text,
+    read: (rows) =>
+      new Map(rows.map((row) => [row[tier] ?? "", Number(row[count])])),
+  };
+}
+
+/**
+ * Split the author query and compile the clauses that go around it — the part
+ * the page and the tier count share.
+ *
+ * @param input - As {@link buildListQuery}; `reserved` says the caller binds a
+ *   generated variable of its own even when no clause does.
+ */
+function readWrapped(
+  input: Omit<ListQueryInput, "window"> & { readonly reserved?: boolean },
+): {
+  prologue: string;
+  projection: readonly string[] | undefined;
+  body: string;
+  clauses: string[];
+} {
+  const { query, predicates, search, scope, label } = input;
   const clauses = [
     ...predicates.map((predicate, index) =>
       filterClause(predicate, `${RESERVED_VARIABLE_PREFIX}Filter${index}`),
@@ -183,7 +264,10 @@ export function buildListQuery(input: ListQueryInput): string {
       ? [scopeClause(scope, `${RESERVED_VARIABLE_PREFIX}Tier`)]
       : []),
   ];
-  if (clauses.length > 0 && query.includes(RESERVED_VARIABLE_PREFIX)) {
+  if (
+    (clauses.length > 0 || input.reserved === true) &&
+    query.includes(RESERVED_VARIABLE_PREFIX)
+  ) {
     throw PragmaError.configError(
       `Story query in ${label} uses the reserved variable prefix "?${RESERVED_VARIABLE_PREFIX}", ` +
         "which the generated filter clauses bind a caller's values to. Rename it.",
@@ -211,17 +295,7 @@ export function buildListQuery(input: ListQueryInput): string {
         "same order, which `SELECT *` cannot promise.",
     );
   }
-  return [
-    ...(prologue === "" ? [] : [prologue]),
-    `SELECT ${projection ? projection.map((variable) => `?${variable}`).join(" ") : "*"}`,
-    "WHERE {",
-    "  {",
-    body,
-    "  }",
-    ...clauses.map((clause) => `  ${clause}`),
-    "}",
-    modifier(window),
-  ].join("\n");
+  return { prologue, projection, body, clauses };
 }
 
 /** The page as SPARQL solution modifiers (`OFFSET 0` omitted as the no-op it is). */
@@ -239,6 +313,7 @@ function modifier(window: ListWindow): string {
  * `set` cell carrying two of them would be returned twice.
  */
 function filterClause(predicate: ListPredicate, bound: string): string {
+  if (predicate.match === "iri") return entityClause(predicate, bound);
   const values = predicate.terms
     .map((term) => `"${escapeSparqlString(term)}"`)
     .join(" ");
@@ -250,6 +325,21 @@ function filterClause(predicate: ListPredicate, bound: string): string {
   return `FILTER EXISTS { VALUES ?${bound} { ${values} } FILTER(${comparison}) }`;
 }
 
+/**
+ * A row's entity is one of the named ones, or reaches one along `via`.
+ *
+ * The IRIs are the store's own, returned by the named noun's resolve — a
+ * caller's text never reaches this clause.
+ */
+function entityClause(predicate: ListPredicate, bound: string): string {
+  const values = predicate.terms.map((iri) => `<${iri}>`).join(" ");
+  const entity = `?${predicate.variable}`;
+  const test = predicate.via
+    ? `${entity} ${formatTerm(predicate.via)} ?${bound}`
+    : `FILTER(${entity} = ?${bound})`;
+  return `FILTER EXISTS { VALUES ?${bound} { ${values} } ${test} }`;
+}
+
 /**
  * Membership of a whitespace-separated set, spelled as a padded substring.
  *

package/src/kernel/packs/sparql/buildLookupQuery.ts

@@ -540,17 +540,19 @@ export function buildIriResolveQuery(lookup: PackLookup, iri: string): string {
     .join("\n");
 }
 
-/** Build the SELECT listing every entity IRI a lookup can address (IRI globs). */
-export function buildLookupIrisQuery(lookup: PackLookup): string {
-  const constraint = buildTypeConstraint(lookup).trimEnd();
+/**
+ * Build the SELECT listing every entity IRI a lookup can address, with the name
+ * it carries when it carries one and, for a scoped lookup, its tier.
+ */
+export function buildLookupIrisQuery(lookup: PackLookup, via?: string): string {
+  const tier = scopeTierProjection(via);
   return [
-    "SELECT DISTINCT ?uri WHERE {",
-    // A pack that constrains by class is asking about its class; one that does
-    // not has only the `by` triple to bound the scan, so it keeps that bound
-    // (and, like the name population, addresses only entities that carry one).
-    constraint !== "" ? constraint : `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    `SELECT DISTINCT ?uri ?name${tier.variable} WHERE {`,
+    buildTypeConstraint(lookup).trimEnd(),
+    // OPTIONAL under a class, required without one — the only bound there is.
+    iriNameBinding(lookup),
+    tier.optional,
     "}",
-    "ORDER BY STR(?uri)",
   ]
     .filter((line) => line !== "")
     .join("\n");
@@ -568,28 +570,51 @@ export function buildLookupIrisQuery(lookup: PackLookup): string {
  * `lookup` is read for ONE thing — the entity's own identity property, which a
  * `blankWhenSelf` field compares its value against. A lookup declaring no such
  * field never binds it.
+ *
+ * A `many` field is aggregated to one space-separated cell, and the rows are
+ * then grouped by child — so it adds values to a row and never rows. A grouped
+ * expand's rows come back in one order on every run.
  */
 export function buildExpandQuery(
   expand: PackExpand,
   entityUri: string,
   lookup?: Pick<PackLookup, "by">,
 ): string {
-  const vars = expand.select.map((field) => `?${field.name}`).join(" ");
+  const fields = expand.select.filter((field) => "property" in field);
+  const single = fields.filter((field) => !field.many);
+  const vars = fields
+    .map((field) =>
+      field.many
+        ? `(GROUP_CONCAT(DISTINCT ?${eachOf(field)}; SEPARATOR=" ") AS ?${field.name})`
+        : `?${field.name}`,
+    )
+    .join(" ");
+  const grouped = single.length < fields.length;
+  const group = grouped
+    ? `GROUP BY ?child${single.map((field) => ` ?${field.name}`).join("")}`
+    : "";
   const optionals = expand.select
     .map((field) =>
       "property" in field ? expandFieldClause(field, entityUri, lookup) : "",
     )
     .filter((line) => line !== "")
     .join("\n");
+  // Grouping discards the store's scan order, so a grouped expand orders by
+  // every single-valued field: the declared names first, the rest as tiebreaks.
+  const declared = expand.orderBy ?? [];
+  const keys = grouped
+    ? [...new Set([...declared, ...single.map((field) => field.name)])]
+    : declared;
   const order =
-    expand.orderBy && expand.orderBy.length > 0
-      ? `ORDER BY ${expand.orderBy.map((name) => `?${name}`).join(" ")}`
+    keys.length > 0
+      ? `ORDER BY ${keys.map((name) => `?${name}`).join(" ")}`
       : "";
   return [
     `SELECT ${vars} WHERE {`,
     `  <${entityUri}> ${formatTerm(expand.relation)} ?child .`,
     optionals,
     "}",
+    group,
     order,
   ]
     .filter((line) => line !== "")
@@ -611,7 +636,8 @@ function expandFieldClause(
   entityUri: string,
   lookup?: Pick<PackLookup, "by">,
 ): string {
-  const read = `?child ${formatTerm(field.property)} ?${field.name} .`;
+  const variable = field.many ? eachOf(field) : field.name;
+  const read = `?child ${formatTerm(field.property)} ?${variable} .`;
   if (!field.blankWhenSelf || !lookup) return `  OPTIONAL { ${read} }`;
   const self = `?${RESERVED_VARIABLE_PREFIX}Self`;
   return [
@@ -623,6 +649,11 @@ function expandFieldClause(
   ].join("\n");
 }
 
+/** The variable one value of a `many` field is bound to before aggregation. */
+function eachOf(field: PackExpandField): string {
+  return `${RESERVED_VARIABLE_PREFIX}Each_${field.name}`;
+}
+
 /** Build the SELECT listing all entity names — lookup-miss suggestions. */
 export function buildLookupNamesQuery(lookup: PackLookup): string {
   return [

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

@@ -30,7 +30,7 @@ const SET_FILTER: PackFilter = {
 /** The error a filter raises for a value it does not admit. */
 function rejection(
   filter: PackFilter,
-  value: string,
+  value: string | readonly string[],
   vocabulary?: readonly string[],
 ): PragmaError {
   try {
@@ -58,8 +58,8 @@ describe("a refused filter value names its vocabulary once", () => {
     expect(occurrences(plain, "color.text.0,")).toBe(1);
     expect(plain).toContain("Valid options (745), first 40:");
     // The recovery says what to do, and names the flag — without the list.
-    expect(plain).toContain("Pick one of the 745 values --symbol accepts.");
-    expect(renderErrorLlm(error)).toContain("Pick one of the 745 values");
+    expect(plain).toContain("Every value must be one of the 745 accepted.");
+    expect(renderErrorLlm(error)).toContain("must be one of the 745");
     expect(occurrences(renderErrorLlm(error), "color.text.0,")).toBe(1);
   });
 
@@ -75,7 +75,7 @@ describe("a refused filter value names its vocabulary once", () => {
 
     expect(occurrences(plain, "dimension")).toBe(1);
     expect(plain).toContain("Valid options: color, dimension, duration");
-    expect(plain).toContain("Pick one of the 3 values --type accepts.");
+    expect(plain).toContain("Every value must be one of the 3 accepted.");
   });
 
   it("a short vocabulary stays cheap to read", () => {
@@ -84,3 +84,35 @@ describe("a refused filter value names its vocabulary once", () => {
     expect(plain.length).toBeLessThan(200);
   });
 });
+
+describe("a filter handed several values", () => {
+  it("admits them as one union predicate", () => {
+    const predicates = resolveFilterPredicates(
+      [SET_FILTER],
+      { type: ["Color", "duration"] },
+      undefined,
+      "test:story",
+    );
+
+    expect(predicates).toEqual([
+      { variable: "type", match: "exact", terms: ["color", "duration"] },
+    ]);
+  });
+
+  it("names EVERY refused value, not just the first", () => {
+    const error = rejection(
+      FREE_FILTER,
+      ["color.text.1", "nope", "color.text.2", "neither"],
+      VOCABULARY,
+    );
+
+    expect(error.message).toBe('Invalid symbol "nope", "neither".');
+  });
+
+  it("names every refused value of a declared set", () => {
+    const error = rejection(SET_FILTER, ["color", "nope", "neither"]);
+
+    expect(error.message).toBe('Invalid type "nope", "neither".');
+    expect(error.validOptions).toEqual(["color", "dimension", "duration"]);
+  });
+});

package/src/kernel/packs/sparql/filterValues.ts

@@ -59,17 +59,18 @@ export function resolveFilterPredicates(
   for (const filter of filters ?? []) {
     const provided = params[filter.param];
     if (provided === undefined) continue;
-    // A repeated CLI flag accumulates into an array; MCP args stay scalar.
-    // Several values for ONE filter are a union (a row matches any of them);
+    // A repeated CLI flag accumulates into an array, and the MCP schema hands
+    // over the same array (one bare value coerced into it). Several values for ONE filter are a union (a row matches any of them);
     // several filters still combine conjunctively.
     const occurrences = Array.isArray(provided) ? provided : [provided];
     if (occurrences.length === 0) continue;
     const values = filter.values;
-    const terms = occurrences.map((occurrence) =>
+    const terms =
       values === undefined
-        ? requireStringValue(occurrence, filter)
-        : canonicalizeFilterValue(occurrence, filter, values),
-    );
+        ? occurrences.map((occurrence) =>
+            requireStringValue(occurrence, filter),
+          )
+        : canonicalizeFilterValues(occurrences, filter, values);
     if (values === undefined) {
       rejectUnknownValue(
         requireVocabulary(filter, vocabularies, label),
@@ -135,18 +136,38 @@ function rejectUnknownValue(
     if (!admissible.has(key)) admissible.set(key, value.normalize("NFC"));
   }
   if (admissible.size === 0) return;
-  const index = terms.findIndex((term) => !admissible.has(term.toLowerCase()));
-  if (index === -1) return;
-  const validOptions = [...admissible.values()].sort();
+  const refused = occurrences.filter(
+    (_, index) => !admissible.has((terms.at(index) ?? "").toLowerCase()),
+  );
+  if (refused.length === 0) return;
   // The VALUES ride `validOptions`, which every renderer already prints (and
   // truncates, and counts). Repeating them in the recovery printed the same
   // 40-name, 1.4KB list twice on one error — see `error/validOptions.ts`.
-  throw PragmaError.invalidInput(filter.param, String(occurrences[index]), {
-    validOptions,
-    recovery: {
-      message: `Pick one of the ${validOptions.length} values --${filter.param} accepts.`,
+  throw refuseValues(filter, refused, [...admissible.values()].sort());
+}
+
+/**
+ * The refusal for values a filter does not admit — EVERY one of them.
+ *
+ * A filter takes several values, so a caller who sent twenty and mistyped three
+ * is told about all three at once: naming only the first would cost a round
+ * trip per typo, which is the cost taking several values exists to remove.
+ */
+function refuseValues(
+  filter: PackFilter,
+  refused: readonly unknown[],
+  validOptions: string[],
+): PragmaError {
+  return PragmaError.invalidInput(
+    filter.param,
+    refused.map(String).join('", "'),
+    {
+      validOptions,
+      recovery: {
+        message: `Every value must be one of the ${validOptions.length} accepted.`,
+      },
     },
-  });
+  );
 }
 
 /** @throws PragmaError INVALID_INPUT when a value-free filter value is not a string. */
@@ -159,24 +180,22 @@ function requireStringValue(provided: unknown, filter: PackFilter): string {
   return provided.trim().normalize("NFC");
 }
 
-/** @throws PragmaError INVALID_INPUT when the value is not in the declared set. */
-function canonicalizeFilterValue(
-  provided: unknown,
+/** @throws PragmaError INVALID_INPUT when a value is not in the declared set. */
+function canonicalizeFilterValues(
+  provided: readonly unknown[],
   filter: PackFilter,
   values: readonly string[],
-): string {
-  if (typeof provided === "string") {
-    const normalized = provided.trim().normalize("NFC");
-    const match = values.find(
-      (value) =>
-        value.normalize("NFC").toLowerCase() === normalized.toLowerCase(),
-    );
-    if (match !== undefined) return match.normalize("NFC");
-  }
-  throw PragmaError.invalidInput(filter.param, String(provided), {
-    validOptions: [...values],
-    recovery: {
-      message: `Pick one of the ${values.length} values --${filter.param} accepts.`,
-    },
+): string[] {
+  const matches = provided.map((occurrence) => {
+    if (typeof occurrence !== "string") return undefined;
+    const normalized = occurrence.trim().normalize("NFC").toLowerCase();
+    return values
+      .find((value) => value.normalize("NFC").toLowerCase() === normalized)
+      ?.normalize("NFC");
   });
+  const refused = provided.filter(
+    (_, index) => matches.at(index) === undefined,
+  );
+  if (refused.length > 0) throw refuseValues(filter, refused, [...values]);
+  return matches.filter((match): match is string => match !== undefined);
 }

package/src/kernel/packs/sparql/runSelect.ts

@@ -10,8 +10,9 @@
  * (`graph query`) goes through the facade directly and stays INVALID_INPUT.
  */
 
-import { cliRecovery, PragmaError } from "../../error/index.js";
+import { callRecovery, PragmaError } from "../../error/index.js";
 import type { PragmaRuntime } from "../../runtime/index.js";
+import { BUILD_STORE_CALL } from "../../spec/call.js";
 import type { PackRow, StorySource } from "../types.js";
 
 /**
@@ -63,12 +64,9 @@ function unboundPrefixError(source: StorySource): PragmaError {
   return PragmaError.storeUnavailable(
     "The local store was not built from a pack that defines every term this read uses.",
     {
-      recovery: cliRecovery(
-        "sources update",
+      recovery: callRecovery(
+        BUILD_STORE_CALL,
         "Build the local store from the configured packs.",
-        // An agent recovers by calling the tool, then retrying (PR9 C1 cold-
-        // store retry makes the post-update retry succeed).
-        { tool: "sources_update" },
       ),
     },
   );

package/src/kernel/packs/storyRules.ts

@@ -32,9 +32,9 @@ import {
   TIER_PARAM,
 } from "./types.js";
 
-/** The message a filter declaring neither `values` nor a `vocabulary` gets. */
+/** The message a filter declaring nothing to admit a value against gets. */
 const FILTER_VOCABULARY_MESSAGE =
-  'a filter must declare "values" or a "vocabulary" query — a value-free filter with neither has nothing to check a caller\'s value against';
+  'a filter must declare "values", a "vocabulary" query or a "noun" — a value-free filter with none has nothing to check a caller\'s value against';
 
 /** One reason a declaration cannot be compiled, and where in it to look. */
 export interface StoryIssue {
@@ -61,15 +61,28 @@ export function listShapeIssues(
 ): StoryIssue[] {
   const issues: StoryIssue[] = [];
   for (const [index, filter] of (shape.filters ?? []).entries()) {
-    if (filter.values === undefined && filter.vocabulary === undefined) {
+    if (
+      filter.values === undefined &&
+      filter.vocabulary === undefined &&
+      filter.noun === undefined
+    ) {
       issues.push({
         path: [...path, "filters", index],
         message: FILTER_VOCABULARY_MESSAGE,
       });
     }
+    if (filter.noun !== undefined && filter.entity === undefined) {
+      issues.push({
+        path: [...path, "filters", index],
+        message:
+          'a filter naming a "noun" must declare the "entity" variable its IRIs constrain',
+      });
+    }
   }
   const constrained = [
-    ...(shape.filters ?? []).map((filter) => filter.variable),
+    ...(shape.filters ?? []).flatMap((filter) =>
+      filter.entity ? [filter.variable, filter.entity] : [filter.variable],
+    ),
     ...(shape.search?.variables ?? []),
   ];
   const read = readAuthorQuery(shape.query);
@@ -107,6 +120,26 @@ export function listShapeIssues(
   return issues;
 }
 
+/**
+ * Every noun a story's cells and filters name, once each.
+ *
+ * @param definition - The story to read.
+ * @returns The named nouns, in declaration order.
+ */
+export function nounsNamed(definition: PackDefinition): string[] {
+  const lookup = definition.lookup;
+  const named = [
+    ...[
+      ...(definition.list ? [definition.list] : []),
+      ...(definition.verbs ?? []),
+    ].flatMap((shape) => [...shape.columns, ...(shape.filters ?? [])]),
+    ...(lookup?.fields ?? []),
+    ...(lookup?.sections ?? []),
+    ...(lookup?.expand ?? []).flatMap((expand) => expand.select),
+  ].flatMap((cell) => ("noun" in cell && cell.noun ? [cell.noun] : []));
+  return [...new Set(named)];
+}
+
 /**
  * Every compilability rule a whole definition breaks, `list` and extra verbs
  * alike.