@canonical/pragma-cli 0.36.0 → 0.38.0

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

@@ -86,21 +86,54 @@ async function queryOrRemap(
   rt: Pick<PragmaRuntime, "query">,
   query: string,
   source: StorySource,
+  degradeOnUnboundPrefix: boolean,
 ) {
   try {
     return await rt.query.sparql(query);
   } catch (error) {
     if (error instanceof PragmaError) throw error;
-    if (isUnseededStoreError(error)) throw unboundPrefixError(source);
+    if (isUnseededStoreError(error)) {
+      if (degradeOnUnboundPrefix) return undefined;
+      throw unboundPrefixError(source);
+    }
     throw error;
   }
 }
 
+/** How one generated read wants an unbound prefix handled. */
+export interface RunSelectOptions {
+  /**
+   * Answer NO ROWS, rather than raising, when the store binds none of the
+   * vocabulary this query names.
+   *
+   * For the read that IS the answer — a list, a name resolve, a lookup's own
+   * fields — raising is right: the caller asked for something this store
+   * cannot speak about, and a silent empty result is the "empty ≠ silence"
+   * defect. For ONE SECTION of a lookup it is not. A section's vocabulary can
+   * come from a different pack than the entity's: a block is `ds:`, and the
+   * style key and state of the tokens it consumes are the anatomy DSL's. A
+   * store built without that pack answers every OTHER section correctly, and
+   * taking the whole entity down over one absent section would make
+   * `block lookup` fail outright on a graph it can very nearly fully describe.
+   *
+   * Degrading is what the lookup's other lane already does with the same
+   * condition — a GraphQL document omits a name the compiled schema has no
+   * field for, the way an OPTIONAL omits an unbound variable — so this keeps
+   * one contract across both lanes rather than two.
+   *
+   * It cannot hide an unbuilt store: by the time a section is read, the base
+   * resolve has already answered from this store, so an unbound prefix here
+   * can only mean this pack's vocabulary is narrower than the story's.
+   */
+  readonly degradeOnUnboundPrefix?: true;
+}
+
 /**
  * @param rt - The runtime (its query facade over the lazy store).
  * @param query - SPARQL SELECT text (prefixes auto-applied by the store).
  * @param source - The story's provenance: its label for attribution, and the
  *   layer that declared it, which decides how an unbound prefix is diagnosed.
+ * @param options - See {@link RunSelectOptions}; defaults to raising.
  * @returns One record per row, keyed by SELECT variable name.
  * @throws PragmaError CONFIG_ERROR when the query is not a SELECT, or when a
  *   config/package story names a prefix the graph does not bind;
@@ -111,8 +144,15 @@ export async function runSelect(
   rt: Pick<PragmaRuntime, "query">,
   query: string,
   source: StorySource,
+  options: RunSelectOptions = {},
 ): Promise<PackRow[]> {
-  const result = await queryOrRemap(rt, query, source);
+  const result = await queryOrRemap(
+    rt,
+    query,
+    source,
+    options.degradeOnUnboundPrefix === true,
+  );
+  if (result === undefined) return [];
   if (result.type !== "select") {
     throw PragmaError.configError(
       `Story query in ${source.label} must be a SELECT (got ${result.type}).`,

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

@@ -0,0 +1,29 @@
+/**
+ * Read a list story's free-text search argument.
+ *
+ * The comparison itself compiles into the query
+ * ({@link ./buildListQuery.buildListQuery}); what stays here is the reading of
+ * the argument — NFC-normalised and trimmed, with a non-string or empty term a
+ * no-op rather than a predicate that matches everything. Normalising on this
+ * side is the whole of it: the store has no normaliser, so the graph's own
+ * spelling is compared as it is stored.
+ */
+
+import type { PackSearch } from "../types.js";
+import type { ListSearch } from "./buildListQuery.js";
+
+/**
+ * @param search - The declared search (absent means the story has none).
+ * @param params - Story parameters as provided by the surface.
+ * @returns The search to compile, or `undefined` when there is nothing to search for.
+ */
+export function readSearchTerm(
+  search: PackSearch | undefined,
+  params: Record<string, unknown>,
+): ListSearch | undefined {
+  const provided = params.search;
+  if (search === undefined || typeof provided !== "string") return undefined;
+  const term = provided.trim().normalize("NFC");
+  if (term === "") return undefined;
+  return { variables: search.variables, term };
+}

package/src/kernel/packs/storyRules.ts

@@ -0,0 +1,180 @@
+/**
+ * The declaration rules a list story must satisfy to be COMPILABLE, checked
+ * without zod so that every story is held to them — including the
+ * distribution's own.
+ *
+ * WHY NOT IN THE GRAMMAR. `schema.ts` is the zod gate, and it runs for config-
+ * and package-declared stories only: `capabilities/distribution.ts` compiles
+ * `pragma.conf.ts` statically and never revalidates it, deliberately, because
+ * zod on the `--help`/`__complete` fast path is latency every invocation pays.
+ * The consequence was that three rules whose violation is a CONFIG_ERROR — a
+ * query a page cannot wrap, a filtered variable the query does not project, a
+ * filter with nothing to admit a value against — were declaration-time refusals
+ * for a third-party author and FIRST-CALL failures for the distribution. The
+ * same rule reaching one tier and missing the other is the shape this domain
+ * keeps closing (see `compileStoryModule`), so the rules live here, in pure
+ * string work the fast path can afford, and the grammar delegates to them
+ * rather than restating them.
+ *
+ * These are the COMPILABILITY rules only. Everything about a definition's
+ * SHAPE — required fields, enums, mutual exclusions, reserved param names —
+ * stays in the zod schema, which is where a shape is best expressed and which
+ * a statically typed `pragma.conf.ts` already satisfies by construction.
+ */
+
+import { readAuthorQuery } from "./sparql/authorQuery.js";
+import {
+  ENTITY_VARIABLE,
+  type PackDefinition,
+  type PackList,
+  type PackTierScope,
+  RESERVED_VARIABLE_PREFIX,
+  TIER_PARAM,
+} from "./types.js";
+
+/** The message a filter declaring neither `values` nor a `vocabulary` 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';
+
+/** One reason a declaration cannot be compiled, and where in it to look. */
+export interface StoryIssue {
+  /** The path into the definition, in the grammar's own field names. */
+  readonly path: readonly (string | number)[];
+  /** What is wrong, in the author's terms. */
+  readonly message: string;
+}
+
+/**
+ * Every compilability rule one list-shaped body breaks.
+ *
+ * @param shape - A `list` or an extra list-shaped verb.
+ * @param path - Where that body sits in the definition, for the issue paths.
+ * @returns The issues: each filter's own rule first, at its own `filters.N`
+ *   path, then the query's. A caller reporting only the first (zod, and
+ *   `compileStoryModule`) therefore names the most local fault it can, and the
+ *   query rules stop at the first one that makes the rest unjudgeable — a
+ *   projection cannot be checked against a query the reader could not read.
+ */
+export function listShapeIssues(
+  shape: PackList,
+  path: readonly (string | number)[],
+): StoryIssue[] {
+  const issues: StoryIssue[] = [];
+  for (const [index, filter] of (shape.filters ?? []).entries()) {
+    if (filter.values === undefined && filter.vocabulary === undefined) {
+      issues.push({
+        path: [...path, "filters", index],
+        message: FILTER_VOCABULARY_MESSAGE,
+      });
+    }
+  }
+  const constrained = [
+    ...(shape.filters ?? []).map((filter) => filter.variable),
+    ...(shape.search?.variables ?? []),
+  ];
+  const read = readAuthorQuery(shape.query);
+  if (!read.ok) {
+    issues.push({
+      path: [...path, "query"],
+      message: `a list query must be wrappable in a page, and ${read.reason} — every list answer is one page, and a page is a wrapping SELECT over the story's own query.`,
+    });
+    return issues;
+  }
+  if (constrained.length === 0) return issues;
+  if (shape.query.includes(RESERVED_VARIABLE_PREFIX)) {
+    issues.push({
+      path: [...path, "query"],
+      message: `a filtered or searched list query may not use the reserved variable prefix "?${RESERVED_VARIABLE_PREFIX}", which the generated filter clauses bind a caller's values to. Rename it.`,
+    });
+  }
+  const projection = read.query.projection;
+  if (!projection) {
+    issues.push({
+      path: [...path, "query"],
+      message:
+        "a list declaring filters or a search must project its SELECT variables by name — the page projects the same names in the same order, which `SELECT *` cannot promise.",
+    });
+    return issues;
+  }
+  for (const variable of constrained) {
+    if (!projection.includes(variable)) {
+      issues.push({
+        path: [...path, "query"],
+        message: `"${variable}" is filtered or searched but not projected by the query (it selects ${projection.join(", ")}).`,
+      });
+    }
+  }
+  return issues;
+}
+
+/**
+ * Every compilability rule a whole definition breaks, `list` and extra verbs
+ * alike.
+ *
+ * @param definition - The definition about to be compiled.
+ * @returns The issues, empty when it compiles.
+ */
+export function storyIssues(definition: PackDefinition): StoryIssue[] {
+  const issues: StoryIssue[] = [];
+  if (definition.list) {
+    issues.push(...listShapeIssues(definition.list, ["list"]));
+    issues.push(
+      ...tierScopeIssues(definition.tierScope, definition.list, ["list"]),
+    );
+  }
+  for (const [index, verb] of (definition.verbs ?? []).entries()) {
+    issues.push(...listShapeIssues(verb, ["verbs", index]));
+    issues.push(
+      ...tierScopeIssues(definition.tierScope, verb, ["verbs", index]),
+    );
+  }
+  return issues;
+}
+
+/**
+ * The two rules a TIER-SCOPED noun's list-shaped body must satisfy.
+ *
+ * Both are the same kind of fault — a declaration that would compile and then
+ * scope nothing, silently:
+ *
+ * - It must PROJECT its entity variable. The scope clause constrains that
+ *   variable through the noun's declared `via` edge, so a body that publishes
+ *   rows without it (`standard categories` projects a name and a count) is a
+ *   body the scope cannot narrow. Refusing it here is the difference between a
+ *   declaration error an author reads once and a list that quietly answers
+ *   from every tier while its heading claims a scope.
+ * - Its own filters may not claim the `tier` param, which the kernel puts on
+ *   every tiered noun's reads. A story filter of that name would collide with
+ *   the flag Commander has already registered — the failure mode
+ *   {@link RESERVED_STORY_PARAMS} exists to prevent, conditional here because
+ *   an UNSCOPED noun's `tier` filter is legitimate (`variable list --tier`
+ *   filters the token graph's own `dt:tier`, which this scope does not touch).
+ */
+export function tierScopeIssues(
+  tierScope: PackTierScope | undefined,
+  shape: PackList,
+  path: readonly (string | number)[],
+): StoryIssue[] {
+  if (!tierScope) return [];
+  const issues: StoryIssue[] = [];
+  for (const [index, filter] of (shape.filters ?? []).entries()) {
+    if (filter.param === TIER_PARAM) {
+      issues.push({
+        path: [...path, "filters", index],
+        message: `a tier-scoped story may not declare a "${TIER_PARAM}" filter — the kernel puts that parameter on every tiered noun's reads, and the two would collide`,
+      });
+    }
+  }
+  const read = readAuthorQuery(shape.query);
+  // An unreadable query is already reported by `listShapeIssues`, and the
+  // projection cannot be judged against a query nobody could read.
+  if (!read.ok) return issues;
+  const projection = read.query.projection;
+  if (projection !== undefined && !projection.includes(ENTITY_VARIABLE)) {
+    issues.push({
+      path: [...path, "query"],
+      message: `a tier-scoped story must project ?${ENTITY_VARIABLE} — the tier scope is compiled in as a constraint on that variable (it selects ${projection.join(", ")}).`,
+    });
+  }
+  return issues;
+}