@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/kernel/packs/resolveEntity.ts

@@ -36,14 +36,16 @@ import {
   buildLookupNamesQuery,
   buildLookupQuery,
   buildNameResolveQuery,
+  SCOPE_TIER_VARIABLE,
 } from "./sparql/buildLookupQuery.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type {
-  PackChildRow,
-  PackEntity,
-  PackLookup,
-  PackRow,
-  StorySource,
+import {
+  expandIsSparql,
+  type PackChildRow,
+  type PackEntity,
+  type PackLookup,
+  type PackRow,
+  type StorySource,
 } from "./types.js";
 
 /** A structured per-query lookup failure (never rejects the whole batch). */
@@ -54,6 +56,32 @@ export interface LookupError {
   readonly suggestions?: readonly string[];
 }
 
+/**
+ * The tier scope a name resolve answers under, as the resolver needs it.
+ *
+ * Built by the run body from the noun's declaration and the caller's arguments
+ * ({@link ../tierScope}); the resolver only has to know which tiers count and
+ * how to say so.
+ */
+export interface LookupScope {
+  /** The entity → tier edge, a validated pack term. */
+  readonly via: string;
+  /** The in-scope tier IRIs. */
+  readonly tiers: readonly string[];
+  /** The scope in the words a reader can type back (`global, apps`). */
+  readonly label: string;
+}
+
+/** A name whose only matches were outside the tier scope. */
+export interface OutOfScopeAnswer {
+  /** The name (or IRI, or glob expansion) that was looked up. */
+  readonly query: string;
+  /** The tiers the answers actually came from, as local names. */
+  readonly tiers: readonly string[];
+  /** The scope that held none of them, in the words `--tier` accepts. */
+  readonly scope: string;
+}
+
 /**
  * The result of a (possibly multi-name) lookup.
  *
@@ -62,10 +90,23 @@ export interface LookupError {
  * naming the ones not answered with, because there are none — an earlier draft
  * kept the single-entity arity and carried the rest as IRIs in a notice, which
  * is a sentence about an address where the payload is the address.
+ *
+ * The tier scope narrows that: for a SCOPED noun the in-scope matches are the
+ * answer, and the out-of-scope ones are not returned — `block lookup button`
+ * answers with the global Button alone. A name whose matches are ALL out of
+ * scope is answered anyway, from the tiers it does live in, and says so through
+ * {@link outOfScope}: refusing it would be answering "no such block" about a
+ * block that exists, which is the one thing a lookup must never do.
  */
 export interface LookupOutput {
   readonly results: PackEntity[];
   readonly errors: LookupError[];
+  /**
+   * The names answered from OUTSIDE the tier scope, because the scope held
+   * nothing they reached. Absent when every answer was in scope — the ordinary
+   * case, and the case the payload speaks for itself in.
+   */
+  readonly outOfScope?: OutOfScopeAnswer[];
 }
 
 /** What the resolver needs from the runtime: the store + the query facade. */
@@ -84,6 +125,7 @@ export async function resolveLookup(
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
+  scope?: LookupScope,
 ): Promise<LookupOutput> {
   if (queries.length === 0) {
     throw PragmaError.invalidInput("names", "(empty)", {
@@ -106,16 +148,18 @@ export async function resolveLookup(
   );
   const results: PackEntity[] = [];
   const errors: LookupError[] = [...expanded.globErrors];
+  const outOfScope: OutOfScopeAnswer[] = [];
   const settled = await Promise.allSettled(
     expanded.names.map((query) =>
-      lookupOne(rt, lookup, noun, query, source, prefixes, level),
+      lookupOne(rt, lookup, noun, query, source, prefixes, level, scope),
     ),
   );
   for (const [index, outcome] of settled.entries()) {
     const query = expanded.names[index];
     if (query === undefined) continue;
     if (outcome.status === "fulfilled") {
-      results.push(...outcome.value);
+      results.push(...outcome.value.entities);
+      if (outcome.value.outOfScope) outOfScope.push(outcome.value.outOfScope);
       continue;
     }
     const error = outcome.reason;
@@ -136,7 +180,11 @@ export async function resolveLookup(
       });
     }
   }
-  return { results, errors };
+  return {
+    results,
+    errors,
+    ...(outOfScope.length > 0 ? { outOfScope } : {}),
+  };
 }
 
 /**
@@ -235,15 +283,16 @@ async function lookupOne(
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
-): Promise<PackEntity[]> {
+  scope?: LookupScope,
+): Promise<{ entities: PackEntity[]; outOfScope?: OutOfScopeAnswer }> {
   const graphqlSourced = lookup.source === "graphql";
   const rows = await runSelect(
     rt,
-    buildResolveQuery(lookup, query, prefixes, level),
+    buildResolveQuery(lookup, query, prefixes, level, scope),
     source,
   );
-  const bases = firstRowPerEntity(rows);
-  if (bases.length === 0) {
+  const resolved = firstRowPerEntity(rows);
+  if (resolved.length === 0) {
     const candidates = await listEntityNames(rt, lookup, source);
     throw PragmaError.notFound(noun, query, {
       suggestions: suggestNames(query, candidates),
@@ -256,8 +305,12 @@ async function lookupOne(
     });
   }
 
+  const chosen = applyScope(resolved, query, scope);
+  const bases = chosen.rows.map(withoutScopeVariable);
+  const fallback = chosen.outOfScope ? { outOfScope: chosen.outOfScope } : {};
+
   if (graphqlSourced) {
-    return Promise.all(
+    const fetched = await Promise.all(
       bases.map((base) =>
         fetchGraphqlLookup(
           rt,
@@ -273,21 +326,123 @@ async function lookupOne(
         ),
       ),
     );
+    // A graphql lookup may still declare SPARQL-lane expands (see
+    // `PackExpand.source`), and they are fetched HERE rather than inside the
+    // GraphQL lane: one entity, two lanes, merged on the way out. The document
+    // generator skips exactly what this loop claims, so no expand is fetched
+    // twice and none is dropped.
+    const entities = await Promise.all(
+      fetched.map(async (entity) =>
+        addSparqlExpands(rt, lookup, entity, source, level),
+      ),
+    );
+    return { entities, ...fallback };
   }
 
   const entities: PackEntity[] = [];
   for (const base of bases) {
-    const entity: PackEntity = { ...base };
-    for (const expand of activeExpands(lookup, level)) {
-      entity[expand.name] = (await runSelect(
-        rt,
-        buildExpandQuery(expand, String(base.uri)),
-        source,
-      )) as readonly PackChildRow[];
-    }
-    entities.push(entity);
+    entities.push(
+      await addSparqlExpands(rt, lookup, { ...base }, source, level),
+    );
+  }
+  return { entities, ...fallback };
+}
+
+/**
+ * Narrow a resolve to the tier scope — or, when the scope holds none of what
+ * the name reached, answer from outside it and say so.
+ *
+ * THE FALLBACK IS THE POINT, and it is why the scope is not a `FILTER` in the
+ * resolve query. A scoped filter would turn `block lookup back-link` — an LXD
+ * component, out of the default scope — into ENTITY_NOT_FOUND with suggestions,
+ * i.e. into "no such block" about a block the store holds and `block list
+ * --tier apps_lxd` prints. A name a reader typed is evidence they mean
+ * something; the scope decides WHICH of several it means, never whether it
+ * exists.
+ *
+ * An entity with no tier at all is treated as IN scope. It cannot be placed, so
+ * it cannot be placed outside — and being unplaceable is not grounds for being
+ * unfindable.
+ */
+function applyScope(
+  rows: readonly PackRow[],
+  query: string,
+  scope: LookupScope | undefined,
+): { rows: readonly PackRow[]; outOfScope?: OutOfScopeAnswer } {
+  if (!scope) return { rows };
+  const inScope = new Set(scope.tiers);
+  const kept = rows.filter((row) => {
+    const tier = row[SCOPE_TIER_VARIABLE];
+    return tier === undefined || tier === "" || inScope.has(tier);
+  });
+  if (kept.length > 0) return { rows: kept };
+  const tiers = [
+    ...new Set(
+      rows
+        .map((row) => row[SCOPE_TIER_VARIABLE] ?? "")
+        .filter((tier) => tier !== "")
+        .map(scopeTierName),
+    ),
+  ];
+  return { rows, outOfScope: { query, tiers, scope: scope.label } };
+}
+
+/** A tier IRI as the scope reports it: the local name `--tier` accepts. */
+function scopeTierName(iri: string): string {
+  return iri.replace(/^.*[#/]/, "");
+}
+
+/**
+ * Drop the kernel's scope variable from a resolved row.
+ *
+ * The sparql-sourced lane spreads its resolve row straight into the entity it
+ * answers with, so a variable the kernel added for its own decision would land
+ * in `--format json` as a field the story never declared.
+ */
+function withoutScopeVariable(row: PackRow): PackRow {
+  if (!(SCOPE_TIER_VARIABLE in row)) return row;
+  const { [SCOPE_TIER_VARIABLE]: _tier, ...rest } = row;
+  return rest;
+}
+
+/**
+ * Fetch every SPARQL-lane expand active at this level onto one entity.
+ *
+ * The lane test is the expand's, not the lookup's, so this serves both callers:
+ * on a sparql lookup every expand is one of these, and on a graphql lookup only
+ * those that opted out of the document.
+ *
+ * @param rt - The runtime (store + query facade).
+ * @param lookup - The validated lookup declaration.
+ * @param entity - The entity to add child arrays to (mutated and returned).
+ * @param source - Pack source, for error attribution.
+ * @param level - Active canonical disclosure level.
+ * @returns The same entity, with one array per fetched expand.
+ * @note Impure — queries the store, once per expand.
+ */
+async function addSparqlExpands(
+  rt: LookupRuntime,
+  lookup: PackLookup,
+  entity: PackEntity,
+  source: StorySource,
+  level: string | undefined,
+): Promise<PackEntity> {
+  for (const expand of activeExpands(lookup, level)) {
+    if (!expandIsSparql(lookup, expand)) continue;
+    entity[expand.name] = (await runSelect(
+      rt,
+      buildExpandQuery(expand, String(entity.uri), lookup),
+      source,
+      // A section whose vocabulary this store does not bind renders EMPTY
+      // rather than taking the whole entity down with it — see
+      // `RunSelectOptions.degradeOnUnboundPrefix`. The block lookup's tokens
+      // read the anatomy DSL's style key and state, which a store built
+      // without that pack does not bind, and every other section of that
+      // block is still perfectly answerable.
+      { degradeOnUnboundPrefix: true },
+    )) as readonly PackChildRow[];
   }
-  return entities;
+  return entity;
 }
 
 /** Collapse a ranked resolve to one row per entity, keeping the best-ranked. */
@@ -316,13 +471,18 @@ function buildResolveQuery(
   query: string,
   prefixes: Readonly<Record<string, string>>,
   level: string | undefined,
+  scope?: LookupScope,
 ): string {
   const graphqlSourced = lookup.source === "graphql";
   if (!looksLikeIri(query)) {
     return graphqlSourced
-      ? buildNameResolveQuery(lookup, query)
-      : buildLookupQuery(lookup, query, level);
+      ? buildNameResolveQuery(lookup, query, scope?.via)
+      : buildLookupQuery(lookup, query, level, scope?.via);
   }
+  // An IRI-ADDRESSED form is never scoped, and that is not an omission. An IRI
+  // reaches exactly one entity, so there is nothing for a scope to choose
+  // between — the whole job the scope does. A caller who pastes
+  // `ds:apps_lxd.component.back_link` has already said which tier they mean.
   const resolved = resolveUri(query, prefixes);
   if (!isEmbeddableIri(resolved)) {
     throw PragmaError.invalidInput("name", query, {

package/src/kernel/packs/runBodies.ts

@@ -2,35 +2,49 @@
  * The shared run bodies a compiled pack verb closes over.
  *
  * Each factory returns a `VerbSpec.run` closure. Reads are plain async: the list
- * body runs the pack's SELECT then applies post-query filters/search; the lookup
- * body resolves names → IRIs and fetches per the declared source, gated by the
- * resolved disclosure level; the sample body draws N random entities at the
- * highest level. All store access is through the runtime facade (lazy), so these
- * factories carry no heavy static import.
+ * body admits the caller's filter values against the graph's vocabulary, then
+ * runs ONE generated SELECT that carries the filters, the search and the page's
+ * bounds; the lookup body resolves names → IRIs and fetches per the declared
+ * source, gated by the resolved disclosure level; the sample body draws N random
+ * entities at the highest level. All store access is through the runtime facade
+ * (lazy), so these factories carry no heavy static import.
  */
 
 import { cliRecovery, PragmaError } from "../error/index.js";
 import type { PragmaRuntime } from "../runtime/index.js";
+import { encodeCursor, pageFingerprint, readCursor } from "./cursor.js";
 import { resolvePackDetail } from "./disclosure.js";
+import { readLimit } from "./paging.js";
 import type { SampleOutput } from "./renderPack.js";
 import {
   type LookupOutput,
+  type LookupScope,
   listEntityNames,
   resolveLookup,
 } from "./resolveEntity.js";
 import { parseSampleCount, pickRandom } from "./sample.js";
+import { buildListQuery } from "./sparql/buildListQuery.js";
 import {
-  applyPackFilters,
   type FilterVocabularies,
-} from "./sparql/applyFilters.js";
-import { applyPackSearch } from "./sparql/applySearch.js";
+  resolveFilterPredicates,
+} from "./sparql/filterValues.js";
 import { runSelect } from "./sparql/runSelect.js";
-import type {
-  PackFilter,
-  PackList,
-  PackLookup,
-  PackRow,
-  StorySource,
+import { readSearchTerm } from "./sparql/searchTerm.js";
+import {
+  resolveReadScope,
+  scopeIris,
+  scopeLabel,
+  type TierScope,
+} from "./tierScope.js";
+import {
+  ENTITY_VARIABLE,
+  type PackAppliedFilter,
+  type PackFilter,
+  type PackList,
+  type PackLookup,
+  type PackPage,
+  type PackTierScope,
+  type StorySource,
 } from "./types.js";
 
 /** The highest canonical level — sample fetches everything for shape discovery. */
@@ -55,37 +69,152 @@ function listRecovery(noun: string) {
 /** Facts a list-shaped run body needs beyond its `shape`. */
 export interface ListRunMeta {
   readonly source: StorySource;
+  /**
+   * The noun's declared tier hierarchy, when its entities are tiered: the list
+   * is then narrowed to a tier scope, compiled into the same query the filters
+   * are. Absent leaves the read exactly as it was.
+   */
+  readonly tierScope?: PackTierScope;
 }
 
 /**
  * Build the run body for a list-shaped verb (`list` or an extra verb).
  *
- * Zero rows is a plain empty list — a SUCCESS, not an error. It returns `[]`
- * (JSON stays `[]`, exit 0); the formatter turns the emptiness into a non-blank
- * message (a pack's `emptyRecovery` becomes that message's hint). Routing zero
- * results through EMPTY_RESULTS would map to exit 1 and break the uniform
- * `ok:true` list contract, so the run body never throws on emptiness.
+ * Zero rows is a plain empty list — a SUCCESS, not an error. It returns an
+ * empty page (JSON stays `[]`, exit 0); the formatter turns the emptiness into
+ * a non-blank message (a pack's `emptyRecovery` becomes that message's hint).
+ * Routing zero results through EMPTY_RESULTS would map to exit 1 and break the
+ * uniform `ok:true` list contract, so the run body never throws on emptiness.
+ * An empty PAGE is the same calm answer: a caller who walked past the last row
+ * asked a legitimate question and got a legitimate nothing.
+ *
+ * `limit + 1` rows are asked for and at most `limit` returned. That extra row
+ * is the whole "are there more" answer — a `COUNT` over the filtered
+ * population would be a second full evaluation of the same query to learn one
+ * boolean.
  */
 export function makeListRun(
   shape: PackList,
   meta: ListRunMeta,
-): (params: Record<string, unknown>, rt: PragmaRuntime) => Promise<PackRow[]> {
+): (params: Record<string, unknown>, rt: PragmaRuntime) => Promise<PackPage> {
   return async (params, rt) => {
-    const rows = await runSelect(rt, shape.query, meta.source);
     const vocabularies = await readFilterVocabularies(
       rt,
       shape.filters,
       params,
       meta.source,
     );
-    return applyPackSearch(
-      applyPackFilters(rows, shape.filters, params, vocabularies),
-      shape.search,
+    const predicates = resolveFilterPredicates(
+      shape.filters,
       params,
+      vocabularies,
+      meta.source.label,
+    );
+    const search = readSearchTerm(shape.search, params);
+    const scope = await resolveReadScope(
+      rt,
+      meta.tierScope,
+      params.tier,
+      meta.source,
+    );
+    // The scope as the query builder takes it, or nothing: a story with no
+    // declared hierarchy, and a read that asked for every tier, both compile
+    // the query they always did.
+    const tiers = scope ? scopeIris(scope) : [];
+    const listScope =
+      meta.tierScope && tiers.length > 0
+        ? { entity: ENTITY_VARIABLE, via: meta.tierScope.via, tiers }
+        : undefined;
+    const limit = readLimit(params.limit);
+    // The cursor is spendable only on the read that issued it, and the read IS
+    // the author query plus the admitted arguments — the tier scope among them.
+    // A cursor minted under one scope and spent under another would page
+    // through a population it was not cut from, which is the same defect the
+    // fingerprint exists to prevent for filters.
+    const fingerprint = pageFingerprint([
+      shape.query,
+      JSON.stringify(predicates),
+      JSON.stringify(search ?? null),
+      // Only when there IS a scope: the fingerprint names the read, and an
+      // unscoped read has no scope to name. Adding an empty one unconditionally
+      // would re-hash every cursor every unscoped story has ever issued, for a
+      // component that says nothing about them.
+      ...(listScope ? [JSON.stringify(tiers)] : []),
+    ]);
+    const offset = readCursor(params.after, fingerprint);
+    const rows = await runSelect(
+      rt,
+      buildListQuery({
+        query: shape.query,
+        predicates,
+        ...(search ? { search } : {}),
+        ...(listScope ? { scope: listScope } : {}),
+        window: { limit: limit + 1, offset },
+        label: meta.source.label,
+      }),
+      meta.source,
     );
+    const hasMore = rows.length > limit;
+    const applied = appliedFilters(shape, params, search?.term, scope);
+    return {
+      rows: hasMore ? rows.slice(0, limit) : rows,
+      ...(hasMore
+        ? { nextAfter: encodeCursor(offset + limit, fingerprint) }
+        : {}),
+      ...(applied.length > 0 ? { filters: applied } : {}),
+      ...(scope?.kind === "tiers"
+        ? { scope: { tiers: scope.tiers.map((tier) => tier.local) } }
+        : {}),
+      limit,
+    };
   };
 }
 
+/**
+ * The filters this read was narrowed by, in the spelling the caller used.
+ *
+ * Read off the DECLARED filters and the search term rather than off the
+ * compiled predicates: what an empty answer has to name is the argument a
+ * reader typed (`--search zzzznotreal`), not the query variable it bound to.
+ * A repeated flag accumulates into an array; it is joined here so the renderer
+ * never has to know that.
+ *
+ * A per-call `--tier` counts as one of them, and a CONFIGURED or default scope
+ * does not. The distinction is the one this list exists to draw: these are the
+ * arguments a reader TYPED, so an empty answer can hand them back as flags to
+ * edit. A scope nobody asked for is reported by the page's own `scope` instead,
+ * which every format states in its own register.
+ *
+ * @param shape - The story's list shape (its declared filters).
+ * @param params - The arguments this invocation supplied.
+ * @param search - The normalised search term, when the caller supplied one.
+ * @param scope - The tier scope in force, when the noun is tiered.
+ * @returns One entry per filter in force, in declared order, search last.
+ */
+function appliedFilters(
+  shape: PackList,
+  params: Record<string, unknown>,
+  search: string | undefined,
+  scope: TierScope | undefined,
+): PackAppliedFilter[] {
+  const applied: PackAppliedFilter[] = [];
+  for (const filter of shape.filters ?? []) {
+    const provided = params[filter.param];
+    if (provided === undefined) continue;
+    const value = Array.isArray(provided)
+      ? provided.map(String).join(", ")
+      : String(provided);
+    if (value === "") continue;
+    applied.push({ param: filter.param, value });
+  }
+  if (search !== undefined) applied.push({ param: "search", value: search });
+  if (scope !== undefined && typeof params.tier === "string") {
+    const value = params.tier.trim();
+    if (value !== "") applied.push({ param: "tier", value });
+  }
+  return applied;
+}
+
 /**
  * Read the declared vocabulary of each value-free filter the caller actually
  * used.
@@ -130,12 +259,22 @@ async function readFilterVocabularies(
   return resolved;
 }
 
-/** Build the run body for a lookup verb (variadic names → resolved entities). */
+/**
+ * Build the run body for a lookup verb (variadic names → resolved entities).
+ *
+ * A TIERED noun's lookup carries the scope too, and it is the same scope its
+ * list carries — one rule, so `block list` and `block lookup` cannot disagree
+ * about which Button a reader means. What differs is what the scope DOES: a
+ * list omits what is out of scope, a lookup prefers what is in it and falls
+ * back rather than answering "no such block" about a block that exists
+ * ({@link ./resolveEntity.applyScope}).
+ */
 export function makeLookupRun(
   lookup: PackLookup,
   noun: string,
   source: StorySource,
   prefixes: Readonly<Record<string, string>>,
+  tierScope?: PackTierScope,
 ): (
   params: Record<string, unknown>,
   rt: PragmaRuntime,
@@ -143,6 +282,7 @@ export function makeLookupRun(
   return async (params, rt) => {
     const names = readNames(params);
     const level = await resolvePackDetail(rt, lookup.disclosure);
+    const scope = await resolveReadScope(rt, tierScope, params.tier, source);
     const output = await resolveLookup(
       rt,
       lookup,
@@ -151,6 +291,7 @@ export function makeLookupRun(
       source,
       prefixes,
       level,
+      lookupScope(tierScope, scope),
     );
     // A total miss (single or all-miss) exits non-zero; a partial batch renders
     // the results it found and notes the misses.
@@ -169,7 +310,36 @@ export function makeLookupRun(
   };
 }
 
-/** Build the run body for a sample verb (N random entities at the highest level). */
+/**
+ * The resolver's view of a scope, or `undefined` when there is nothing to
+ * narrow by.
+ *
+ * `all` collapses to `undefined` rather than to an empty tier set: a resolver
+ * handed an empty set would treat every match as out of scope and report a
+ * fallback for a read that asked for every tier.
+ */
+function lookupScope(
+  declaration: PackTierScope | undefined,
+  scope: TierScope | undefined,
+): LookupScope | undefined {
+  if (!declaration || scope === undefined || scope.kind === "all") {
+    return undefined;
+  }
+  const label = scopeLabel(scope);
+  if (label === undefined) return undefined;
+  return { via: declaration.via, tiers: scopeIris(scope), label };
+}
+
+/**
+ * Build the run body for a sample verb (N random entities at the highest level).
+ *
+ * UNSCOPED, deliberately, and it is the one read of a tiered noun that is. A
+ * sample is a shape probe — "show me what a block record looks like" — drawn at
+ * the highest disclosure level for exactly that reason, and the tier a specimen
+ * happens to belong to is not part of the shape. Narrowing it would also make
+ * the draw pool depend on a setting, so two agents reading the same store would
+ * see different exemplars for reasons neither asked about.
+ */
 export function makeSampleRun(
   lookup: PackLookup,
   noun: string,