@canonical/pragma-cli 0.36.0 → 0.38.0

package/dist/src/kernel/packs/sparql/authorQuery.js

@@ -0,0 +1,227 @@
+/**
+ * Read a list story's author query as the three parts a page has to keep apart:
+ * the PROLOGUE it declares, the VARIABLES it projects, and the BODY a wrapping
+ * select can hold.
+ *
+ * Every list answer is one page now, and a page is a wrapping select over the
+ * story's own query ({@link ./buildListQuery.buildListQuery}). Three properties
+ * of the author's text decide whether that wrap is legal, and none of them can
+ * be asked of the store:
+ *
+ * - **The prologue cannot be wrapped.** `PREFIX` and `BASE` belong to a QUERY;
+ *   a group graph pattern admits only patterns, so splicing author text that
+ *   opens with `PREFIX` inside one is a parse error (`expected OPTIONAL`). The
+ *   declarations are lifted to the wrapper's own prologue instead, in order, and
+ *   the body from the `SELECT` keyword on is what gets wrapped.
+ * - **The projection has to be reproduced.** `SELECT *` in the wrapper hands
+ *   back alphabetised binding keys, so `block list`'s rows would go from
+ *   `{uri,name,type,tier}` to `{name,tier,type,uri}` and every `--format json`
+ *   answer would change shape for no reason a caller asked for. The store cannot
+ *   answer this either: `SelectResult.variables` is derived from the rows that
+ *   came back, not from the query's header — over the shipped pack `block list`
+ *   reports four of its five, because the fifth is unbound on the first row. So
+ *   the projection is read from the query TEXT, which is the only place that
+ *   states it. An author who wrote `SELECT *` is wrapped with `SELECT *`, which
+ *   preserves their key order because it is the same alphabetisation twice.
+ * - **A dataset clause cannot be wrapped either.** `FROM` sits between the
+ *   select clause and the where clause, and `SubSelect` has no place for it. It
+ *   is REFUSED rather than lifted, because lifting it would mean cutting a span
+ *   out of the middle of the author's text — the prologue is a prefix, which is
+ *   why lifting that one is a split and not an edit.
+ *
+ * This is a lexer for the two clauses that precede the where clause, not a
+ * SPARQL parser. It covers the whole grammar of both — `Prologue ::= (BaseDecl
+ * | PrefixDecl)*` and `SelectClause ::= 'SELECT' ('DISTINCT'|'REDUCED')?
+ * ((Var | '(' Expression 'AS' Var ')')+ | '*')` — and it skips comments and
+ * string literals everywhere it scans, so a `#` inside a prefix IRI, a `# select
+ * the blocks` heading, and a `WHERE {` inside a `REPLACE` literal are all read
+ * as what they are. What it cannot read it says it cannot read, naming the
+ * shape it found: a refusal that misdiagnoses sends the author to the wrong
+ * file.
+ */
+/** A SPARQL variable as this reader recognises it (`?name`, `$name`). */
+const VARIABLE = /^[?$]([A-Za-z_][A-Za-z0-9_]*)/;
+/** The `AS ?var` binding that names a projection expression's result. */
+const ALIAS = /\bAS\s+[?$]([A-Za-z_][A-Za-z0-9_]*)\s*$/i;
+/** Whitespace and `#` comments, which may sit between any two tokens. */
+const IGNORABLE = /^(?:\s+|#[^\n\r]*)+/;
+/** `PNAME_NS ::= PN_PREFIX? ':'` — the name a `PREFIX` declaration binds. */
+const PREFIX_NAME = /^[A-Za-z][\w.-]*:|^:/;
+/**
+ * Split an author query into its prologue, its projection and its body.
+ *
+ * @param text - The author's SPARQL SELECT text.
+ * @returns The three parts, or the reason the text cannot be wrapped — a
+ *   sentence fragment naming what the reader FOUND, for a caller to quote.
+ */
+export function readAuthorQuery(text) {
+    const prologue = readPrologue(text);
+    const start = skipIgnorable(text, prologue.end);
+    if (!/^SELECT\b/i.test(text.slice(start))) {
+        return { ok: false, reason: "its text declares no SPARQL SELECT" };
+    }
+    const clause = readSelectClause(text, start + "SELECT".length);
+    if (!clause.ok)
+        return clause;
+    return {
+        ok: true,
+        query: {
+            prologue: text.slice(prologue.start, prologue.end),
+            projection: clause.projection,
+            body: text.slice(start),
+        },
+    };
+}
+/** Where the prologue's declarations begin and end (equal when there are none). */
+function readPrologue(text) {
+    const start = skipIgnorable(text, 0);
+    let end = start;
+    let at = start;
+    for (;;) {
+        const declaration = readDeclaration(text, at);
+        if (declaration === undefined)
+            return { start, end };
+        end = declaration;
+        at = skipIgnorable(text, declaration);
+    }
+}
+/**
+ * The index just past one `PREFIX`/`BASE` declaration, or `undefined` when the
+ * text at {@link at} is not one.
+ *
+ * The IRI is scanned to its closing `>`, which is exact: `IRIREF` excludes `>`
+ * from its character class, so the first one closes it — and it does NOT
+ * exclude `#`, which is why a comment-aware scan has to read the IRI as an IRI
+ * rather than skip to end of line.
+ */
+function readDeclaration(text, at) {
+    const keyword = text.slice(at).match(/^(BASE|PREFIX)\b/i);
+    if (!keyword?.[1])
+        return undefined;
+    let index = skipIgnorable(text, at + keyword[0].length);
+    if (keyword[1].toUpperCase() === "PREFIX") {
+        const name = text.slice(index).match(PREFIX_NAME);
+        if (!name)
+            return undefined;
+        index = skipIgnorable(text, index + name[0].length);
+    }
+    if (text[index] !== "<")
+        return undefined;
+    const close = text.indexOf(">", index + 1);
+    return close === -1 ? undefined : close + 1;
+}
+/** Read the select clause that starts just past the `SELECT` keyword. */
+function readSelectClause(text, from) {
+    const projected = [];
+    let star = false;
+    let at = from;
+    while (at < text.length) {
+        at = skipIgnorable(text, at);
+        const rest = text.slice(at);
+        // The clause ends at the WHERE keyword or at the group graph pattern's
+        // brace, whichever the author wrote (`WHERE` is optional in SPARQL).
+        if (rest === "" || /^(?:WHERE\b|\{)/i.test(rest))
+            break;
+        if (/^FROM\b/i.test(rest)) {
+            return {
+                ok: false,
+                reason: "it carries a FROM dataset clause, and a sub-select cannot carry one",
+            };
+        }
+        // DISTINCT/REDUCED sit between the keyword and the projection.
+        const modifier = rest.match(/^(?:DISTINCT|REDUCED)\b/i);
+        if (modifier && projected.length === 0 && !star) {
+            at += modifier[0].length;
+            continue;
+        }
+        if (rest.startsWith("*")) {
+            star = true;
+            at += 1;
+            continue;
+        }
+        const variable = rest.match(VARIABLE);
+        if (variable?.[1]) {
+            projected.push(variable[1]);
+            at += variable[0].length;
+            continue;
+        }
+        if (rest.startsWith("(")) {
+            const end = matchingParen(text, at);
+            const alias = end === -1 ? null : text.slice(at + 1, end).match(ALIAS);
+            if (!alias?.[1]) {
+                return {
+                    ok: false,
+                    reason: "its SELECT clause carries a parenthesised expression that names no result variable (`(… AS ?name)`)",
+                };
+            }
+            projected.push(alias[1]);
+            at = end + 1;
+            continue;
+        }
+        return {
+            ok: false,
+            reason: `its SELECT clause carries ${quoted(rest)}, which is neither a variable nor an \`(expression AS ?variable)\``,
+        };
+    }
+    if (star) {
+        return projected.length === 0
+            ? { ok: true, projection: undefined }
+            : {
+                ok: false,
+                reason: "its SELECT clause mixes `*` with named variables",
+            };
+    }
+    return projected.length > 0
+        ? { ok: true, projection: projected }
+        : { ok: false, reason: "its SELECT clause projects nothing" };
+}
+/** The first token of {@link rest}, quoted short enough to read in a message. */
+function quoted(rest) {
+    const token = rest.match(/^\S{1,24}/)?.[0] ?? rest.slice(0, 24);
+    return `"${token}"`;
+}
+/** Whitespace and comments consumed: the next index that is neither. */
+function skipIgnorable(text, at) {
+    const skip = text.slice(at).match(IGNORABLE);
+    return skip ? at + skip[0].length : at;
+}
+/**
+ * The index of the `)` closing the `(` at {@link open}, or -1 when unbalanced.
+ *
+ * Depth-counted rather than regex-matched: a projection expression nests
+ * (`(COALESCE(IF(…), 0) AS ?rank)`), and the first `)` is rarely the right one.
+ * Quoted strings are skipped so a `)` inside a literal cannot close the
+ * expression.
+ */
+function matchingParen(text, open) {
+    let depth = 0;
+    for (let index = open; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '"' || char === "'") {
+            index = skipLiteral(text, index);
+            continue;
+        }
+        if (char === "(")
+            depth += 1;
+        if (char === ")") {
+            depth -= 1;
+            if (depth === 0)
+                return index;
+        }
+    }
+    return -1;
+}
+/** The index of the quote closing the literal opened at {@link open}. */
+function skipLiteral(text, open) {
+    const quote = text[open];
+    for (let index = open + 1; index < text.length; index += 1) {
+        if (text[index] === "\\") {
+            index += 1;
+            continue;
+        }
+        if (text[index] === quote)
+            return index;
+    }
+    return text.length;
+}
+//# sourceMappingURL=authorQuery.js.map

package/dist/src/kernel/packs/sparql/authorQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorQuery.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/authorQuery.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/packs/sparql/buildListQuery.js

@@ -0,0 +1,251 @@
+/**
+ * Compile a list story's declared filters, its search term, its tier scope and
+ * one page's bounds into the SPARQL the store actually runs.
+ *
+ * WHY IN THE QUERY. Filters used to be predicates over the rows a query had
+ * already returned. That was injection-safe and order-preserving — the two
+ * properties this module has to keep — but it put filtering on the wrong side
+ * of any cap: a `LIMIT` in a story's own text truncates BEFORE the filter runs,
+ * so `--category testing` over a capped population answers from whatever
+ * happened to be inside the window. Nothing was being truncated yet, because no
+ * story declared a cap and the kernel had none to declare; the moment one
+ * exists, every declared filter starts deciding over a truncated population.
+ * Pagination is that cap, so the two move together and they move inward.
+ *
+ * The TIER SCOPE is here for that reason and not by analogy: it narrows the
+ * 252-row `block list` under a 300-row page today, so a page that started
+ * truncating would decide the default scope by where the window fell. It is the
+ * one clause that constrains the ENTITY rather than a projected cell — see
+ * {@link ListTierScope}.
+ *
+ * ONE SHAPE, ALWAYS. The author query becomes a sub-select inside a wrapping
+ * SELECT that carries the predicates and the page bounds — whether or not there
+ * is anything to filter. It has to be a wrap rather than an appended `HAVING`
+ * when there IS something: a `match: "set"` filter reads a cell the author's own
+ * `GROUP BY` computed (`standard list`'s `GROUP_CONCAT`), so the predicate can
+ * only run after aggregation, and the cap only after the predicate.
+ *
+ * It is a wrap when there is NOTHING to filter, too, and that is a correction.
+ * Appending `LIMIT n` to the author's own text is a syntax error for every
+ * story whose text already ends in a solution modifier or a trailing `VALUES`
+ * block — `LIMIT` after `LIMIT`, after `OFFSET`, after `VALUES` — and because
+ * the page has a DEFAULT, that error fired on every call rather than only on
+ * paged ones. The shortcut existed to keep the store running, character for
+ * character, the query it ran before. Measured over all nine shipped bodies
+ * (median of 15 warm store queries per body, both texts, 2026-09-10) the wrap
+ * ran between 2.7 ms FASTER and 0.5 ms slower, deltas straddling zero and the
+ * one clear win being `block list`, the 252-row body; every body's rows came
+ * back byte-identical through the wrap, key order included. So the shortcut
+ * bought nothing measurable and cost a whole class of author query. Keeping it
+ * would have meant a guard recognising every trailing-modifier shape the
+ * grammar admits — more parsing than the wrap itself needs, to reach the
+ * answer the wrap already gives.
+ *
+ * THE AUTHOR'S TEXT IS SPLIT, NEVER EDITED. Two parts of a query cannot live
+ * inside a group graph pattern, and {@link ./authorQuery.readAuthorQuery} is
+ * what tells them apart:
+ *
+ * - The PROLOGUE (`PREFIX`, `BASE`) is lifted to the wrapper's own prologue, in
+ *   the author's order. That is a split at the `SELECT` keyword, not a rewrite:
+ *   the body is a suffix of the author's text, byte for byte. A COLLIDING
+ *   prefix resolves the way it always did — the store prepends the pack's own
+ *   prefix map ahead of whatever it is handed, the author's declaration is
+ *   emitted after it, and SPARQL's last declaration wins, so an author who
+ *   redeclares `ds:` shadows the pack's `ds:` exactly as they did before any
+ *   wrap existed (verified both shapes against the pinned oxigraph). The
+ *   wrapper declares nothing and names no prefixed term, so it brings no
+ *   prefix of its own for an author to collide with.
+ * - A DATASET clause (`FROM`, `FROM NAMED`) is refused, at declaration and
+ *   again here. It sits in the MIDDLE of the author's text rather than at its
+ *   front, so lifting it would mean cutting a span out — an edit, not a split.
+ *
+ * The wrapper projects the author's own variables, in the author's own order
+ * ({@link ./authorQuery}) — `SELECT *` in the wrapper would hand back
+ * alphabetised binding keys and change every JSON answer's shape. An author who
+ * wrote `SELECT *` themselves gets `SELECT *`, which is the same alphabetisation
+ * twice and so preserves their key order; a FILTERABLE story that writes it is
+ * refused, because a projection of `*` names nothing to constrain.
+ *
+ * USER INPUT IS BOUND, NOT SPLICED. Every value a caller supplies reaches the
+ * query as a row of a `VALUES` block — the closest thing the store's text-only
+ * interface has to a bound parameter — escaped by
+ * {@link ./escape.escapeSparqlString}, and the predicate compares against that
+ * variable rather than against interpolated text. The `VALUES` block sits
+ * inside `FILTER EXISTS` deliberately: joined into the outer group it would
+ * MULTIPLY rows, and a repeated flag over a `set` cell carrying two of the
+ * requested members would return that row twice.
+ *
+ * The comparison itself is the row predicate's, transposed:
+ * case-insensitively equal for `exact`, membership of a whitespace-separated
+ * set for `set`, substring for search, and a cell that is unbound or empty
+ * never matches. One divergence is worth naming: the row predicate NFC-
+ * normalised both sides, and SPARQL has no normaliser, so the graph's own
+ * spelling is compared as it is stored (the caller's side is still normalised,
+ * in {@link ./filterValues}).
+ */
+import { PragmaError } from "../../error/index.js";
+import { RESERVED_VARIABLE_PREFIX } from "../types.js";
+import { readAuthorQuery } from "./authorQuery.js";
+import { escapeSparqlString, formatTerm } from "./escape.js";
+/**
+ * Build the SELECT one page of a list story runs.
+ *
+ * @param input - The author query, the supplied filters/search, and the page.
+ * @returns SPARQL SELECT text composed only from author terms, escaped values
+ *   and the page's own integers.
+ * @throws PragmaError CONFIG_ERROR when the author query cannot be wrapped in a
+ *   page, when a filterable story's projection cannot be reproduced, or when
+ *   its query already uses the generated variable prefix. Each names what it
+ *   found: the same refusal for three different reasons would send an author to
+ *   the wrong part of their own file.
+ */
+export function buildListQuery(input) {
+    const { query, predicates, search, scope, window, label } = input;
+    const clauses = [
+        ...predicates.map((predicate, index) => filterClause(predicate, `${RESERVED_VARIABLE_PREFIX}Filter${index}`)),
+        ...(search
+            ? [searchClause(search, `${RESERVED_VARIABLE_PREFIX}Search`)]
+            : []),
+        ...(scope && scope.tiers.length > 0
+            ? [scopeClause(scope, `${RESERVED_VARIABLE_PREFIX}Tier`)]
+            : []),
+    ];
+    if (clauses.length > 0 && 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.");
+    }
+    const read = readAuthorQuery(query);
+    if (!read.ok) {
+        throw PragmaError.configError(`Story query in ${label} cannot be paged: ${read.reason}. Every list ` +
+            "answer is one page, and a page is a wrapping SELECT over the story's own query.");
+    }
+    const { prologue, projection, body } = read.query;
+    // The SCOPE clause is deliberately not counted here: it constrains the entity
+    // through a graph edge, not a projected cell, and a sub-select's `SELECT *`
+    // still makes the entity variable visible to the wrapper. A FILTER is the
+    // case that cannot be checked — it names a variable, and `*` names none.
+    if ((predicates.length > 0 || search !== undefined) &&
+        projection === undefined) {
+        throw PragmaError.configError(`Story query in ${label} declares filters or a search, so its SELECT must ` +
+            "project its variables by name — the page projects the same names in the " +
+            "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");
+}
+/** The page as SPARQL solution modifiers (`OFFSET 0` omitted as the no-op it is). */
+function modifier(window) {
+    return window.offset > 0
+        ? `LIMIT ${window.limit} OFFSET ${window.offset}`
+        : `LIMIT ${window.limit}`;
+}
+/**
+ * One filter as a row predicate that cannot duplicate a row.
+ *
+ * `FILTER EXISTS` makes the `VALUES` block a per-row existence test: joining it
+ * into the group instead would pair each row with every requested value, and a
+ * `set` cell carrying two of them would be returned twice.
+ */
+function filterClause(predicate, bound) {
+    const values = predicate.terms
+        .map((term) => `"${escapeSparqlString(term)}"`)
+        .join(" ");
+    const cell = `?${predicate.variable}`;
+    const comparison = predicate.match === "set"
+        ? setMembership(cell, bound)
+        : `STR(${cell}) != "" && LCASE(STR(${cell})) = LCASE(?${bound})`;
+    return `FILTER EXISTS { VALUES ?${bound} { ${values} } FILTER(${comparison}) }`;
+}
+/**
+ * Membership of a whitespace-separated set, spelled as a padded substring.
+ *
+ * The cell is a `GROUP_CONCAT` of every value a row belongs to at once — a
+ * category and each of its ancestors. Padding both sides with a space is what
+ * keeps it a WHOLE-member comparison, so `testing` does not match
+ * `testing-unit`; collapsing runs of whitespace first reproduces the row
+ * predicate's own `\s+` split, whatever separator the author's aggregate used.
+ *
+ * TWO WAYS IT IS WIDER THAN THE SPLIT IT REPLACED, both out of reach of every
+ * vocabulary the distribution declares and both worth knowing before a
+ * vocabulary is widened:
+ *
+ * - A value that CONTAINS whitespace matches a contiguous RUN of members: cell
+ *   `"foo bar baz"`, value `"bar baz"` answers true here where
+ *   `split(/\s+/).includes(value)` answered false. Unreachable today because no
+ *   admissible value carries whitespace (all 21 `cs:slug` values are clean), and
+ *   reachable the moment a filter declares `values: ["a b"]` or a graph
+ *   vocabulary grows a multi-word term.
+ * - An EMPTY value matches an EMPTY cell, because `CONTAINS(" ", " ")` is true.
+ *   The row predicate answered false on an empty cell, and the `exact` branch
+ *   above still does via its explicit `STR(?c) != ""` guard, which this branch
+ *   has no equivalent of. Unreachable today because `readFilterVocabularies`
+ *   drops empty strings from a vocabulary and `rejectUnknownValue` then refuses
+ *   `""` as unadmitted — i.e. it is the ADMISSION step that closes this, not the
+ *   predicate.
+ */
+function setMembership(cell, bound) {
+    const members = `CONCAT(" ", REPLACE(LCASE(STR(${cell})), "\\\\s+", " "), " ")`;
+    return `CONTAINS(${members}, CONCAT(" ", LCASE(?${bound}), " "))`;
+}
+/**
+ * The tier scope as a row predicate: the entity is in an in-scope tier, or in
+ * no tier at all.
+ *
+ * `EXISTS` with the tiers in a `VALUES` block, for both reasons the filter
+ * clauses use that shape. It cannot MULTIPLY a row (an entity in two in-scope
+ * tiers is still one entity — the design system asserts one `ds:tier` per block
+ * today, and a second one tomorrow must not double the row), and the tier IRIs
+ * ride a bound variable rather than being spliced into a pattern.
+ *
+ * The IRIs are the store's own, read back from the tier hierarchy by
+ * {@link ../tierScope.readTierHierarchy} — a caller supplies a tier NAME, which
+ * is resolved to a tier before it ever reaches here, so the only thing
+ * interpolated is a term the graph itself published.
+ *
+ * THE UNTIERED HALF IS NOT A COURTESY. `ds:button.icon` is a subcomponent with
+ * no `ds:tier`, and a required tier join is exactly what used to hide it: the
+ * hand-written block list inner-joined the tier and surfaced it only under
+ * `--all-tiers`, which is the defect the declared query's OPTIONAL join closed
+ * and `block.parity.test.ts` holds it to. A membership test alone would reopen
+ * it — an entity the scope cannot PLACE would become an entity the default
+ * scope cannot SHOW. So the predicate is "in scope, or in no tier", which is
+ * the same rule the lookup resolver applies to the same rows
+ * ({@link ../resolveEntity.applyScope}).
+ *
+ * `IN` would read closer to the rule as stated, and this is the same predicate:
+ * membership of a set, tested per row. A `VALUES` block is how every other
+ * generated clause in this module spells a set, so the scope spells it that way
+ * too rather than introducing a second idiom for one clause.
+ */
+function scopeClause(scope, bound) {
+    const values = scope.tiers.map((iri) => `<${iri}>`).join(" ");
+    const entity = `?${scope.entity}`;
+    const via = formatTerm(scope.via);
+    return (`FILTER(EXISTS { VALUES ?${bound} { ${values} } ${entity} ${via} ?${bound} } ` +
+        `|| NOT EXISTS { ${entity} ${via} ?${bound}Any })`);
+}
+/**
+ * Search as a substring test over every declared variable.
+ *
+ * `COALESCE(…, false)` per variable rather than one bare disjunction: an
+ * unbound cell makes `CONTAINS` raise, and an error inside `||` is not reliably
+ * false. The row predicate treated a missing cell as "does not contain", and so
+ * does this.
+ */
+function searchClause(search, bound) {
+    const tests = search.variables
+        .map((variable) => `COALESCE(CONTAINS(LCASE(STR(?${variable})), LCASE(?${bound})), false)`)
+        .join(" || ");
+    return (`FILTER EXISTS { VALUES ?${bound} { "${escapeSparqlString(search.term)}" } ` +
+        `FILTER(${tests}) }`);
+}
+//# sourceMappingURL=buildListQuery.js.map

package/dist/src/kernel/packs/sparql/buildListQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildListQuery.js","sourceRoot":"","sources":["../../../../../src/kernel/packs/sparql/buildListQuery.ts"],"names":[],"mappings":"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"}