@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/shared/stories/pack/applyPackFilters.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import applyPackFilters from "./applyPackFilters.js";
+import type { StoryPackFilter } from "./types.js";
+
+const ROWS = [
+  { name: "Gazpacho", category: "soup" },
+  { name: "Pancakes", category: "breakfast" },
+];
+const FILTERS: StoryPackFilter[] = [
+  { param: "category", variable: "category", values: ["breakfast", "soup"] },
+];
+
+describe("applyPackFilters", () => {
+  it("returns rows unchanged when no filter value is provided", () => {
+    expect(applyPackFilters(ROWS, FILTERS, {})).toEqual(ROWS);
+  });
+
+  it("returns rows unchanged when no filters are declared", () => {
+    expect(applyPackFilters(ROWS, undefined, { category: "soup" })).toEqual(
+      ROWS,
+    );
+  });
+
+  it("keeps only rows matching the provided value", () => {
+    const rows = applyPackFilters(ROWS, FILTERS, { category: "soup" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("rejects values outside the declared set", () => {
+    expect(() =>
+      applyPackFilters(ROWS, FILTERS, { category: "dinner" }),
+    ).toThrowError(PragmaError);
+    try {
+      applyPackFilters(ROWS, FILTERS, { category: "dinner" });
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+      expect((error as PragmaError).recovery?.message).toContain("breakfast");
+    }
+  });
+
+  it("rejects non-string values and suggests the declared set", () => {
+    expect(() => applyPackFilters(ROWS, FILTERS, { category: 3 })).toThrowError(
+      PragmaError,
+    );
+    try {
+      applyPackFilters(ROWS, FILTERS, { category: ["soup"] });
+    } catch (error) {
+      expect((error as PragmaError).validOptions).toEqual([
+        "breakfast",
+        "soup",
+      ]);
+    }
+  });
+
+  it("canonicalizes case-insensitive input to the declared value", () => {
+    const rows = applyPackFilters(ROWS, FILTERS, { category: "SOUP" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("trims surrounding whitespace from the provided value", () => {
+    const rows = applyPackFilters(ROWS, FILTERS, { category: "  soup " });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("matches unicode values across NFC/NFD normalization forms", () => {
+    const filters: StoryPackFilter[] = [
+      { param: "kind", variable: "kind", values: ["entr\u00e9e"] },
+    ];
+    const rows = [{ name: "Salad", kind: "entre\u0301e" }];
+    expect(
+      applyPackFilters(rows, filters, { kind: "entre\u0301e" }),
+    ).toHaveLength(1);
+  });
+
+  it("never matches rows without a binding for the variable", () => {
+    const rows = [{ name: "Mystery" }, ...ROWS];
+    const filtered = applyPackFilters(rows, FILTERS, { category: "soup" });
+    expect(filtered.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("carries the declared values as valid options on rejection", () => {
+    try {
+      applyPackFilters(ROWS, FILTERS, { category: "sopu" });
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+      expect((error as PragmaError).validOptions).toContain("soup");
+    }
+  });
+
+  it("applies several filters conjunctively", () => {
+    const filters: StoryPackFilter[] = [
+      ...FILTERS,
+      { param: "name", variable: "name", values: ["Gazpacho", "Pancakes"] },
+    ];
+    const rows = applyPackFilters(ROWS, filters, {
+      category: "soup",
+      name: "Pancakes",
+    });
+    expect(rows).toEqual([]);
+  });
+});
+
+// Value-free filters (pack v1): no declared value set, case-insensitive
+// equality against the variable — the valid values live in the data.
+describe("applyPackFilters — value-free filters", () => {
+  const FREE_FILTERS: StoryPackFilter[] = [
+    { param: "category", variable: "category" },
+  ];
+
+  it("matches on case-insensitive equality with the variable", () => {
+    const rows = applyPackFilters(ROWS, FREE_FILTERS, { category: "SOUP" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("trims surrounding whitespace from the provided value", () => {
+    const rows = applyPackFilters(ROWS, FREE_FILTERS, { category: " soup " });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("returns no rows for an unknown value instead of rejecting", () => {
+    expect(
+      applyPackFilters(ROWS, FREE_FILTERS, { category: "dinner" }),
+    ).toEqual([]);
+  });
+
+  it("matches unicode values across NFC/NFD normalization forms", () => {
+    const rows = [{ name: "Salad", kind: "entr\u00e9e" }];
+    const filters: StoryPackFilter[] = [{ param: "kind", variable: "kind" }];
+    expect(
+      applyPackFilters(rows, filters, { kind: "entre\u0301e" }),
+    ).toHaveLength(1);
+  });
+
+  it("never matches rows without a binding for the variable", () => {
+    const rows = [{ name: "Mystery" }, ...ROWS];
+    const filtered = applyPackFilters(rows, FREE_FILTERS, { category: "soup" });
+    expect(filtered.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("rejects non-string values with INVALID_INPUT", () => {
+    expect(() =>
+      applyPackFilters(ROWS, FREE_FILTERS, { category: 3 }),
+    ).toThrowError(PragmaError);
+    try {
+      applyPackFilters(ROWS, FREE_FILTERS, { category: ["soup"] });
+    } catch (error) {
+      expect((error as PragmaError).code).toBe("INVALID_INPUT");
+    }
+  });
+});

package/src/domains/shared/stories/pack/applyPackFilters.ts

@@ -0,0 +1,111 @@
+import { PragmaError } from "#error";
+import type { StoryPackFilter } from "./types.js";
+
+/**
+ * Apply declared pack filters to resolved list rows.
+ *
+ * Filters are row predicates on projected SELECT variables — the author
+ * query is never modified, so user input cannot inject SPARQL and the
+ * query's ordering is preserved.
+ *
+ * Matching semantics:
+ * - With declared `values`: input is trimmed, unicode-normalized (NFC),
+ *   and matched against the declared values case-insensitively; the
+ *   DECLARED value is canonical and rows are compared against it exactly
+ *   (NFC on both sides).
+ * - Without `values` (value-free filter): the input itself is the term —
+ *   trimmed, NFC-normalized — and rows match on case-insensitive equality
+ *   with the variable's value. Nothing is rejected up front because the
+ *   valid set lives in the data.
+ * - ke bindings carry lexical forms — language tags and datatypes are
+ *   already stripped — so plain string comparison is sound.
+ * - A row without a binding for the variable (e.g. from OPTIONAL) never
+ *   matches an active filter.
+ * - Several provided filters combine conjunctively.
+ *
+ * @param rows - Rows produced by the pack's list query.
+ * @param filters - Declared filters (absent means no filtering).
+ * @param params - Story parameters as provided by the surface.
+ * @returns Rows matching every provided filter.
+ * @throws PragmaError with code `INVALID_INPUT` (carrying the declared
+ *         values as valid options) when a provided value is not in the
+ *         filter's declared set, or when a value-free filter receives a
+ *         non-string value.
+ */
+export default function applyPackFilters(
+  rows: Record<string, string>[],
+  filters: readonly StoryPackFilter[] | undefined,
+  params: Record<string, unknown>,
+): Record<string, string>[] {
+  // Start from the caller's array; each active filter's `.filter()` yields a
+  // fresh array, so with no active filter the rows pass through unmodified —
+  // no defensive clone (the caller owns the query result).
+  let result = rows;
+  for (const filter of filters ?? []) {
+    const provided = params[filter.param];
+    if (provided === undefined) continue;
+    const values = filter.values;
+    if (values === undefined) {
+      // Value-free filter: case-insensitive equality against the variable.
+      const term = requireStringValue(provided, filter).toLowerCase();
+      result = result.filter(
+        (row) => row[filter.variable]?.normalize("NFC").toLowerCase() === term,
+      );
+      continue;
+    }
+    const canonical = canonicalizeFilterValue(provided, filter, values);
+    result = result.filter(
+      (row) => row[filter.variable]?.normalize("NFC") === canonical,
+    );
+  }
+  return result;
+}
+
+/**
+ * Require a value-free filter's input to be a trimmed, NFC-normalized
+ * string.
+ *
+ * @throws PragmaError with code `INVALID_INPUT` when it is not a string.
+ */
+function requireStringValue(
+  provided: unknown,
+  filter: StoryPackFilter,
+): string {
+  if (typeof provided !== "string") {
+    throw PragmaError.invalidInput(filter.param, String(provided), {
+      recovery: {
+        message: `Provide a string value for --${filter.param}.`,
+      },
+    });
+  }
+  return provided.trim().normalize("NFC");
+}
+
+/**
+ * Resolve a provided filter value to its declared canonical form.
+ *
+ * @throws PragmaError with code `INVALID_INPUT` when the value is not a
+ *         string or not in the declared set.
+ */
+function canonicalizeFilterValue(
+  provided: unknown,
+  filter: StoryPackFilter,
+  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: `Allowed values for --${filter.param}: ${values.join(", ")}.`,
+    },
+  });
+}

package/src/domains/shared/stories/pack/applyPackSearch.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import applyPackSearch from "./applyPackSearch.js";
+import type { StoryPackSearch } from "./types.js";
+
+const ROWS = [
+  { name: "Gazpacho", description: "A cold soup" },
+  { name: "Pancakes", description: "Fried batter" },
+  { name: "Mystery" },
+];
+const SEARCH: StoryPackSearch = { variables: ["name", "description"] };
+
+describe("applyPackSearch", () => {
+  it("returns rows unchanged when no search is declared", () => {
+    expect(applyPackSearch(ROWS, undefined, { search: "soup" })).toEqual(ROWS);
+  });
+
+  it("returns rows unchanged when no term is provided", () => {
+    expect(applyPackSearch(ROWS, SEARCH, {})).toEqual(ROWS);
+  });
+
+  it("returns rows unchanged for an empty or whitespace term", () => {
+    expect(applyPackSearch(ROWS, SEARCH, { search: "   " })).toEqual(ROWS);
+  });
+
+  it("keeps rows where any searched variable contains the term", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "soup" });
+    expect(rows.map((row) => row.name)).toEqual(["Gazpacho"]);
+  });
+
+  it("matches case-insensitively", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "PANCAKE" });
+    expect(rows.map((row) => row.name)).toEqual(["Pancakes"]);
+  });
+
+  it("matches substrings mid-value", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "batter" });
+    expect(rows.map((row) => row.name)).toEqual(["Pancakes"]);
+  });
+
+  it("never matches rows without a binding for a searched variable", () => {
+    const rows = applyPackSearch(ROWS, SEARCH, { search: "myst" });
+    expect(rows.map((row) => row.name)).toEqual(["Mystery"]);
+    expect(applyPackSearch(ROWS, SEARCH, { search: "absent" })).toEqual([]);
+  });
+
+  it("matches unicode terms across NFC/NFD normalization forms", () => {
+    const rows = [{ name: "Entr\u00e9e" }];
+    const search: StoryPackSearch = { variables: ["name"] };
+    expect(
+      applyPackSearch(rows, search, { search: "entre\u0301e" }),
+    ).toHaveLength(1);
+  });
+
+  it("ignores non-string search values", () => {
+    expect(applyPackSearch(ROWS, SEARCH, { search: 3 })).toEqual(ROWS);
+  });
+});

package/src/domains/shared/stories/pack/applyPackSearch.ts

@@ -0,0 +1,41 @@
+import type { StoryPackSearch } from "./types.js";
+
+/**
+ * Apply a pack list's free-text search to resolved rows.
+ *
+ * Search is a row predicate on projected SELECT variables — like filters,
+ * it runs AFTER the author query, so user input never touches the query
+ * text (injection-safe by construction) and the author's ORDER BY is
+ * preserved.
+ *
+ * Matching semantics:
+ * - The term is NFC-normalized and matched case-insensitively.
+ * - A row passes when ANY declared variable's value contains the term as
+ *   a substring; unbound variables (e.g. from OPTIONAL) never match.
+ * - A non-string or empty term is a no-op — search is a refinement, not a
+ *   validated enum, so there is nothing to reject against.
+ *
+ * @param rows - Rows produced by the pack's list query (post-filter).
+ * @param search - The declared search (absent means no searching).
+ * @param params - Story parameters as provided by the surface.
+ * @returns Rows containing the term in at least one searched variable.
+ */
+export default function applyPackSearch(
+  rows: Record<string, string>[],
+  search: StoryPackSearch | undefined,
+  params: Record<string, unknown>,
+): Record<string, string>[] {
+  const provided = params.search;
+  if (search === undefined || typeof provided !== "string") {
+    return rows;
+  }
+  const term = provided.trim().normalize("NFC").toLowerCase();
+  if (term === "") {
+    return rows;
+  }
+  return rows.filter((row) =>
+    search.variables.some((variable) =>
+      row[variable]?.normalize("NFC").toLowerCase().includes(term),
+    ),
+  );
+}

package/src/domains/shared/stories/pack/buildLookupQuery.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import buildLookupQuery, {
+  buildLookupByIriQuery,
+  buildLookupNamesQuery,
+  escapeSparqlString,
+  formatTerm,
+} from "./buildLookupQuery.js";
+
+describe("escapeSparqlString", () => {
+  it("escapes quotes, backslashes, and newlines", () => {
+    expect(escapeSparqlString('a"b\\c\nd')).toBe('a\\"b\\\\c\\nd');
+  });
+});
+
+describe("formatTerm", () => {
+  it("keeps prefixed names and wraps absolute IRIs", () => {
+    expect(formatTerm("ex:Recipe")).toBe("ex:Recipe");
+    expect(formatTerm("http://example.org/x")).toBe("<http://example.org/x>");
+  });
+});
+
+describe("buildLookupQuery", () => {
+  it("generates a typed, escaped, case-insensitive match", () => {
+    const query = buildLookupQuery(
+      {
+        by: "ex:name",
+        type: "ex:Recipe",
+        fields: [{ name: "category", property: "ex:category" }],
+      },
+      'Pan"cakes',
+    );
+    expect(query).toContain("?uri ex:name ?name .");
+    expect(query).toContain("?uri a ex:Recipe .");
+    expect(query).toContain("OPTIONAL { ?uri ex:category ?category . }");
+    expect(query).toContain('LCASE("Pan\\"cakes")');
+    expect(query).toContain("LIMIT 1");
+  });
+
+  it("omits the type constraint when absent", () => {
+    const query = buildLookupQuery({ by: "ex:name" }, "x");
+    expect(query).not.toContain("?uri a ");
+  });
+});
+
+describe("buildLookupByIriQuery", () => {
+  it("binds the resolved IRI instead of filtering on the name", () => {
+    const query = buildLookupByIriQuery(
+      {
+        by: "ex:name",
+        type: "ex:Recipe",
+        fields: [{ name: "category", property: "ex:category" }],
+      },
+      "http://example.org/recipes/pancakes",
+    );
+    expect(query).toContain(
+      "BIND(<http://example.org/recipes/pancakes> AS ?uri)",
+    );
+    expect(query).toContain("?uri ex:name ?name .");
+    expect(query).toContain("?uri a ex:Recipe .");
+    expect(query).toContain("OPTIONAL { ?uri ex:category ?category . }");
+    expect(query).not.toContain("FILTER");
+    expect(query).toContain("LIMIT 1");
+  });
+
+  it("omits the type constraint when absent", () => {
+    const query = buildLookupByIriQuery(
+      { by: "ex:name" },
+      "http://example.org/x",
+    );
+    expect(query).not.toContain("?uri a ");
+  });
+});
+
+describe("buildLookupNamesQuery", () => {
+  it("selects all names for the by property", () => {
+    const query = buildLookupNamesQuery({ by: "ex:name", type: "ex:Recipe" });
+    expect(query).toContain("SELECT ?name WHERE {");
+    expect(query).toContain("?uri ex:name ?name .");
+    expect(query).toContain("?uri a ex:Recipe .");
+  });
+});

package/src/domains/shared/stories/pack/buildLookupQuery.ts

@@ -0,0 +1,154 @@
+import type { StoryPackExpand, StoryPackLookup } from "./types.js";
+
+/**
+ * Build the generated, injection-safe lookup queries for a pack story.
+ *
+ * Pack authors declare *what* names an entity (`by`, optional `type`) and
+ * which properties to read; the query text is generated here so
+ * user-supplied names are always escaped SPARQL string literals — a pack
+ * definition never interpolates user input itself. Matching is exact and
+ * case-insensitive on the `by` property's string value.
+ */
+
+/** Escape a user-supplied value as a SPARQL string literal body. */
+export function escapeSparqlString(value: string): string {
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r");
+}
+
+/** Render a validated term (prefixed name or absolute IRI) as a query token. */
+export function formatTerm(term: string): string {
+  return term.includes("://") ? `<${term}>` : term;
+}
+
+/**
+ * Build the SELECT retrieving one named entity with its declared fields.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param name - User-supplied entity name (escaped here).
+ * @returns SPARQL SELECT text.
+ */
+export default function buildLookupQuery(
+  lookup: StoryPackLookup,
+  name: string,
+): string {
+  const fields = [...(lookup.fields ?? []), ...(lookup.sections ?? [])];
+  const vars = fields.map((field) => `?${field.name}`).join(" ");
+  const optionals = fields
+    .map(
+      (field) =>
+        `  OPTIONAL { ?uri ${formatTerm(field.property)} ?${field.name} . }`,
+    )
+    .join("\n");
+  const typeConstraint = lookup.type
+    ? `  ?uri a ${formatTerm(lookup.type)} .\n`
+    : "";
+
+  return [
+    `SELECT ?uri ?name${vars.length > 0 ? ` ${vars}` : ""} WHERE {`,
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    typeConstraint + optionals,
+    `  FILTER (LCASE(STR(?name)) = LCASE("${escapeSparqlString(name)}"))`,
+    "}",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the SELECT retrieving one entity addressed directly by IRI.
+ *
+ * Mirrors {@link buildLookupQuery} but binds the already-resolved IRI to
+ * `?uri` instead of filtering on the `by` property's value, so absolute
+ * IRIs and prefixed names address an entity exactly. Injection-safe by
+ * construction: the caller resolves and validates `iri` against the
+ * embeddable-IRI shape (no whitespace or `<>"` characters) BEFORE it is
+ * interpolated here — raw user input never reaches this function.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @param iri - A resolved, validated absolute IRI.
+ * @returns SPARQL SELECT text.
+ */
+export function buildLookupByIriQuery(
+  lookup: StoryPackLookup,
+  iri: string,
+): string {
+  const fields = [...(lookup.fields ?? []), ...(lookup.sections ?? [])];
+  const vars = fields.map((field) => `?${field.name}`).join(" ");
+  const optionals = fields
+    .map(
+      (field) =>
+        `  OPTIONAL { ?uri ${formatTerm(field.property)} ?${field.name} . }`,
+    )
+    .join("\n");
+  const typeConstraint = lookup.type
+    ? `  ?uri a ${formatTerm(lookup.type)} .\n`
+    : "";
+
+  return [
+    `SELECT ?uri ?name${vars.length > 0 ? ` ${vars}` : ""} WHERE {`,
+    `  BIND(<${iri}> AS ?uri)`,
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    typeConstraint + optionals,
+    "}",
+    "LIMIT 1",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}
+
+/**
+ * Build the sub-SELECT retrieving one expand's child rows for a resolved
+ * entity.
+ *
+ * Injection-safe by construction: the only interpolated value is
+ * `entityUri`, which is the IRI the base lookup already resolved from the
+ * store (never user input), and the relation/properties are validated pack
+ * terms. Returns one row per child node, each carrying the declared fields.
+ *
+ * @param expand - The expand declaration.
+ * @param entityUri - The resolved entity IRI (from the base lookup's `?uri`).
+ * @returns SPARQL SELECT text yielding one row per child node.
+ */
+export function buildExpandQuery(
+  expand: StoryPackExpand,
+  entityUri: string,
+): string {
+  const vars = expand.select.map((field) => `?${field.name}`).join(" ");
+  const optionals = expand.select
+    .map(
+      (field) =>
+        `  OPTIONAL { ?child ${formatTerm(field.property)} ?${field.name} . }`,
+    )
+    .join("\n");
+  return [
+    `SELECT ${vars} WHERE {`,
+    `  <${entityUri}> ${formatTerm(expand.relation)} ?child .`,
+    optionals,
+    "}",
+  ].join("\n");
+}
+
+/**
+ * Build the SELECT listing all entity names — lookup-miss suggestions.
+ *
+ * @param lookup - The pack's lookup declaration.
+ * @returns SPARQL SELECT text yielding a `?name` per entity.
+ */
+export function buildLookupNamesQuery(lookup: StoryPackLookup): string {
+  const typeConstraint = lookup.type
+    ? `  ?uri a ${formatTerm(lookup.type)} .\n`
+    : "";
+  return [
+    "SELECT ?name WHERE {",
+    `  ?uri ${formatTerm(lookup.by)} ?name .`,
+    typeConstraint.trimEnd(),
+    "}",
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+}

package/src/domains/shared/stories/pack/bundled/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Bundled transitional story packs.
+ *
+ * These are declarative replacements for design-system domains that used to be
+ * hand-written TypeScript in the CLI core. They ship inside pragma during the
+ * strangler migration (ADR C.07) and are the **lowest-precedence** pack
+ * source: a `pragma.config.json` `stories` entry or a semantic package's
+ * `stories/*.json` for the same noun overrides the bundled one, so a package
+ * can take ownership of its noun (the P4 end state) without a code change here.
+ *
+ * As each leaf domain is cut over, its built-in command is deleted (freeing the
+ * noun from the reserved set) and its pack is added to this list.
+ */
+
+import type { StoryPackDefinition } from "../types.js";
+import { standardPack } from "./standardPack.js";
+import { tierPack } from "./tierPack.js";
+
+/** Every pack pragma ships by default, lowest precedence. */
+export const BUNDLED_PACKS: readonly StoryPackDefinition[] = [
+  tierPack,
+  standardPack,
+];