@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,57 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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

@@ -1,154 +0,0 @@
-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

@@ -1,23 +0,0 @@
-/**
- * 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,
-];

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

@@ -1,164 +0,0 @@
-/**
- * Bundled transitional `standard` pack.
- *
- * Replaces the hand-written `standard` domain (~1,300 LOC of command/
- * operation/formatter/orchestration/MCP wiring) with a declarative pack
- * definition. `standard list|lookup|categories|sample` and the
- * `standard_list|_lookup|_categories|_sample` MCP tools compile from this
- * definition through the same kernel as every other pack, so the CLI core
- * stops carrying standard-specific TypeScript.
- *
- * @remarks transitional — this ships inside pragma today; in P4 it moves
- * into the `@canonical/code-standards` package as `stories/standard.json`
- * alongside that package's prefix declaration, at which point the core
- * carries no standard at all.
- *
- * Scope notes (semantic parity, not byte parity — see standardParity.test):
- * - Rows/entities are the uniform pack shapes: the list SELECT binds the
- *   standard IRI to `uri` and renames `categoryName` → `category`, so JSON
- *   carries the same keys as the old summary items.
- * - The old domain's `--digest`/`--detailed` LIST enrichment is not
- *   reproduced (pack lists have a single level); the same data is reachable
- *   through `standard lookup --detail …` and `standard sample`.
- * - Lookup disclosure keeps three levels. The old digest's bespoke
- *   "first do-example truncated to 120 chars" rendering is not expressible
- *   generically; here `digest` gates the full `dos` expand (richer than the
- *   old digest) and `detailed` adds `donts`.
- * - `extends` stays the raw IRI in JSON (renderers compact it at display
- *   time); the old domain compacted it in resolved data.
- */
-
-import type { StoryPackDefinition } from "../types.js";
-
-/**
- * The `standard` read stories as data.
- *
- * The list SELECT mirrors the query the old `listStandards` operation sent
- * the store — `cs:name` and the category path stay OPTIONAL so a standard
- * without a display name or category still appears — while `ORDER BY ?name`
- * sorts by the human-facing name. The BIND reproduces the old
- * `deriveStandardName` fallback declaratively: a standard without `cs:name`
- * displays its IRI fragment with dots rendered as slashes
- * (`…#react.component.props` → `react/component/props`). Category filtering
- * is value-free (the category set lives in the graph) and search covers
- * name + description; both are post-query row predicates, so user input
- * never touches this query text.
- */
-export const standardPack: StoryPackDefinition = {
-  noun: "standard",
-  description: "List all code standards",
-  toolDescription:
-    "List code standards. Optionally filter by category or search term.",
-  list: {
-    query: [
-      "SELECT ?uri ?name ?category ?description",
-      "WHERE {",
-      "  ?uri a cs:CodeStandard ;",
-      "       cs:description ?description .",
-      "  OPTIONAL { ?uri cs:name ?n . }",
-      '  BIND(COALESCE(?n, REPLACE(STRAFTER(STR(?uri), "#"), "\\\\.", "/")) AS ?name)',
-      "  OPTIONAL {",
-      "    ?uri cs:hasCategory ?cat .",
-      "    ?cat cs:slug ?category .",
-      "  }",
-      "}",
-      "ORDER BY ?name",
-    ].join("\n"),
-    columns: [
-      { field: "uri", label: "IRI" },
-      { field: "name", label: "Name" },
-      { field: "category", label: "Category" },
-      { field: "description", label: "Description" },
-    ],
-    filters: [
-      {
-        param: "category",
-        variable: "category",
-        description: "Filter by category name",
-      },
-    ],
-    search: {
-      variables: ["name", "description"],
-      description: "Search in name and description",
-    },
-  },
-  verbs: [
-    {
-      verb: "categories",
-      description: "List all standard categories with counts",
-      toolDescription: "List all code standard categories.",
-      // OPTIONAL keeps zero-count categories in the result (a category with
-      // no standards still lists, with count 0), mirroring the old
-      // listCategories operation.
-      query: [
-        "SELECT ?name (COUNT(?standard) AS ?count)",
-        "WHERE {",
-        "  ?cat a cs:Category ;",
-        "       cs:slug ?name .",
-        "  OPTIONAL {",
-        "    ?standard a cs:CodeStandard ;",
-        "              cs:hasCategory ?cat .",
-        "  }",
-        "}",
-        "GROUP BY ?name",
-        "ORDER BY ?name",
-      ].join("\n"),
-      columns: [
-        { field: "name", label: "Category" },
-        { field: "count", label: "Standards" },
-      ],
-    },
-  ],
-  lookup: {
-    by: "cs:name",
-    type: "cs:CodeStandard",
-    description:
-      "Look up detailed information for a standard by name, IRI, or glob",
-    toolDescription:
-      "Get detailed information about one or more code standards including dos and donts with code examples. Address standards by name, prefixed name (cs:…), absolute IRI, or glob pattern (react/component/*).",
-    fields: [
-      {
-        name: "category",
-        property: "cs:hasCategory/cs:slug",
-        label: "Category",
-      },
-      {
-        name: "description",
-        property: "cs:description",
-        label: "Description",
-      },
-      { name: "extends", property: "cs:extends", label: "Extends" },
-    ],
-    expand: [
-      {
-        name: "dos",
-        heading: "Do",
-        relation: "cs:do",
-        select: [
-          { name: "caption", property: "cs:description" },
-          { name: "language", property: "cs:language" },
-          { name: "code", property: "cs:code" },
-        ],
-        level: "digest",
-      },
-      {
-        name: "donts",
-        heading: "Don't",
-        relation: "cs:dont",
-        select: [
-          { name: "caption", property: "cs:description" },
-          { name: "language", property: "cs:language" },
-          { name: "code", property: "cs:code" },
-        ],
-        level: "detailed",
-      },
-    ],
-    disclosure: { levels: ["summary", "digest", "detailed"] },
-    sample: {
-      description:
-        "Return randomly selected complete standard instances as exemplars for shape discovery",
-      toolDescription:
-        "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
-    },
-  },
-};

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

@@ -1,50 +0,0 @@
-/**
- * Bundled transitional `tier` pack.
- *
- * Replaces the hand-written `tier` domain (~179 LOC of command/operation/
- * formatter/MCP wiring) with a declarative list story. `tier list` and the
- * `tier_list` MCP tool are compiled from this definition through the same
- * kernel as every other pack, so the CLI core stops carrying tier-specific
- * TypeScript.
- *
- * @remarks transitional — this ships inside pragma today; in P4 it moves into
- * the `@canonical/design-system` package as `stories/tier.json` alongside that
- * package's prefix declaration, at which point the core carries no tier at all.
- *
- * Scope note: the old domain's `TierEntry.depth`/`parent` fields were always
- * `0`/absent — tier hierarchy is encoded in the slash-separated *path string*
- * (`apps/lxd`), not in graph edges, and the ordered-inheritance logic lives in
- * `buildTierFilter`/`resolveTierChain` (a filter primitive other domains use).
- * `tier list` is therefore a flat, name-ordered list, which this pack
- * reproduces faithfully; there is no graph tree to project.
- */
-
-import type { StoryPackDefinition } from "../types.js";
-
-/**
- * The `tier` list story as data.
- *
- * The SELECT binds the tier IRI to `uri` and its `ds:name` to `name` (the
- * honest mapping of the `ds:name` property), so `--format json` is the uniform
- * `{uri, name}` pack shape and the generic renderer emits `- ` + "`ds:apps`" +
- * ` — **Apps**` in llm mode. The store injects PREFIX declarations, so `ds:`
- * resolves against the merged prefix map. The old domain's always-zero
- * `depth` field is intentionally dropped.
- */
-export const tierPack: StoryPackDefinition = {
-  noun: "tier",
-  description: "List all tiers in the design system ontology",
-  toolDescription: "List all tiers in the design-system ontology.",
-  list: {
-    query: [
-      "SELECT ?uri ?name WHERE {",
-      "  ?uri a ds:Tier ;",
-      "       ds:name ?name .",
-      "} ORDER BY ?name",
-    ].join("\n"),
-    columns: [
-      { field: "uri", label: "IRI" },
-      { field: "name", label: "Name" },
-    ],
-  },
-};