@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -1,381 +0,0 @@
-/**
- * Standard-noun cutover parity — the bundled `standard` pack against the
- * real @canonical/code-standards graphs, resolved from node_modules
- * through the production loader chain (no fixture TTL).
- *
- * The hand-written standard domain is gone, so parity is SEMANTIC and
- * asserted directly against the graph: every standard the store carries
- * is reachable through the pack's list/lookup/categories/sample stories
- * with the same names and values (category, description, extends,
- * dos/donts code examples), by name, prefixed name, absolute IRI, and
- * glob. The accepted divergences from the deleted built-in are pinned in
- * PARITY_GAPS (`#testing`), not silently absorbed here.
- */
-
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, PARITY_GAPS } from "#testing";
-import { parsePackageEntry } from "../../../refs/operations/parseRef.js";
-import { bootStore } from "../../bootStore.js";
-import compactUri from "../../compactUri.js";
-import {
-  DEFAULT_PREFIX_MAP,
-  TRANSITIONAL_DS_PREFIX_MAP,
-} from "../../prefixes.js";
-import { listDomainNames } from "../../suggestions/index.js";
-import type { PragmaRuntime } from "../../types/index.js";
-import { standardPack } from "./bundled/standardPack.js";
-import compilePackStories, {
-  type CompiledPackStories,
-} from "./compilePackStories.js";
-import runSelectQuery from "./runSelectQuery.js";
-import validateStoryPackDefinition from "./validateStoryPackDefinition.js";
-
-const PACK_SOURCE = "bundled:standard";
-
-/** A real standard whose dos AND donts are non-empty on the live package. */
-const LOOKUP_NAME = "react/component/props";
-
-/** A real standard with cs:extends — pins the raw-IRI JSON contract. */
-const EXTENDS_LOOKUP_NAME = "react/component/structure/context";
-
-/** A near-miss query — must produce ranked suggestions. */
-const NEAR_MISS_NAME = "code/function/puriti";
-
-let store: Store;
-let rt: PragmaRuntime;
-let compiled: CompiledPackStories;
-
-beforeAll(async () => {
-  const boot = await bootStore({
-    refs: [parsePackageEntry("@canonical/code-standards")],
-  });
-  store = boot.store;
-  rt = { store } as PragmaRuntime;
-  compiled = compilePackStories(standardPack, PACK_SOURCE, {
-    ...DEFAULT_PREFIX_MAP,
-  });
-});
-
-afterAll(() => store?.dispose());
-
-/** The dos/donts row shape the pack projects for each code example. */
-type ExampleRow = { caption?: string; language?: string; code?: string };
-
-/** Resolve one lookup query at an optional detail level. */
-async function lookupPack(
-  name: string,
-  params: Record<string, unknown> = {},
-): Promise<Record<string, string | readonly ExampleRow[]>> {
-  const lookup = compiled.lookup;
-  if (!lookup) throw new Error("standard pack must declare a lookup story");
-  const result = await lookup.resolve(rt, [name], params);
-  expect(result.errors).toEqual([]);
-  const entity = result.results.at(0);
-  if (entity === undefined) {
-    throw new Error(`pack lookup found no result for "${name}"`);
-  }
-  return entity as Record<string, string | readonly ExampleRow[]>;
-}
-
-describe("standard pack definition", () => {
-  it("round-trips as declarative JSON and validates as a v1 pack", () => {
-    const raw: unknown = JSON.parse(JSON.stringify(standardPack));
-    expect(validateStoryPackDefinition(raw, PACK_SOURCE)).toEqual(standardPack);
-  });
-
-  it("records every accepted divergence as a distinct entry", () => {
-    expect(PARITY_GAPS.length).toBeGreaterThan(0);
-    expect(new Set(PARITY_GAPS).size).toBe(PARITY_GAPS.length);
-    for (const gap of PARITY_GAPS) {
-      expect(gap.trim().length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("standard list parity", () => {
-  let rows: Record<string, string>[];
-
-  beforeAll(async () => {
-    rows = await compiled.list.resolve(rt, {});
-  });
-
-  it("lists every named standard in the graph, with the uniform row shape", async () => {
-    // The shared suggestions name query is the independent oracle for
-    // which standards exist (same store, different query path).
-    const allNames = await listDomainNames(store, "standard");
-    expect(allNames.length).toBeGreaterThan(0);
-    const listed = new Set(rows.map((row) => row.name));
-    for (const name of allNames) {
-      expect(listed.has(name), `"${name}" missing from standard list`).toBe(
-        true,
-      );
-    }
-    for (const row of rows) {
-      expect(row.uri).toBeTruthy();
-      expect(row.description).toBeTruthy();
-    }
-  });
-
-  it("filters by category (value-free, case-insensitive)", async () => {
-    const filtered = await compiled.list.resolve(rt, { category: "REACT" });
-    expect(filtered.length).toBeGreaterThan(0);
-    expect(filtered).toEqual(rows.filter((row) => row.category === "react"));
-  });
-
-  it("returns zero rows (not an error) for an unknown category", async () => {
-    // Pinned gap: the old list raised EMPTY_RESULTS here.
-    await expect(
-      compiled.list.resolve(rt, { category: "nonexistent" }),
-    ).resolves.toEqual([]);
-  });
-
-  it("searches name and description case-insensitively", async () => {
-    const found = await compiled.list.resolve(rt, { search: "folder" });
-    expect(found.length).toBeGreaterThan(0);
-    expect(found).toEqual(
-      rows.filter(
-        (row) =>
-          row.name?.toLowerCase().includes("folder") ||
-          row.description?.toLowerCase().includes("folder"),
-      ),
-    );
-  });
-
-  it("combines category and search conjunctively", async () => {
-    const found = await compiled.list.resolve(rt, {
-      category: "react",
-      search: "folder",
-    });
-    expect(found.length).toBeGreaterThan(0);
-    for (const row of found) {
-      expect(row.category).toBe("react");
-    }
-  });
-});
-
-describe("standard lookup parity", () => {
-  it("resolves base fields by name at the default (summary) level", async () => {
-    const entity = await lookupPack(LOOKUP_NAME);
-    expect(entity.name).toBe(LOOKUP_NAME);
-    expect(entity.uri).toBeTruthy();
-    expect(entity.category).toBe("react");
-    expect(typeof entity.description).toBe("string");
-    // Summary fetches no expands.
-    expect(entity.dos).toBeUndefined();
-    expect(entity.donts).toBeUndefined();
-  });
-
-  it("fetches full dos (code examples) at --detail digest", async () => {
-    const entity = await lookupPack(LOOKUP_NAME, { detail: "digest" });
-    const dos = entity.dos as readonly ExampleRow[];
-    expect(Array.isArray(dos)).toBe(true);
-    expect(dos.length).toBeGreaterThan(0);
-    for (const example of dos) {
-      expect(example.code).toBeTruthy();
-      expect(example.language).toBeTruthy();
-    }
-    expect(entity.donts).toBeUndefined();
-  });
-
-  it("fetches dos AND donts at --detail detailed", async () => {
-    const entity = await lookupPack(LOOKUP_NAME, { detail: "detailed" });
-    expect((entity.dos as readonly ExampleRow[]).length).toBeGreaterThan(0);
-    expect((entity.donts as readonly ExampleRow[]).length).toBeGreaterThan(0);
-  });
-
-  it("carries each example's cs:description as its caption", async () => {
-    const entity = await lookupPack(LOOKUP_NAME, { detail: "detailed" });
-    const uri = entity.uri as string;
-    const dos = entity.dos as readonly ExampleRow[];
-    const donts = entity.donts as readonly ExampleRow[];
-    expect(dos.at(0)?.caption).toBeTruthy();
-    expect(donts.at(0)?.caption).toBeTruthy();
-    // Oracle: the same store queried directly for the examples' captions.
-    const doCaptions = await runSelectQuery(
-      store,
-      `SELECT ?caption WHERE { <${uri}> cs:do ?ex . ?ex cs:description ?caption }`,
-      "test:oracle",
-    );
-    expect(doCaptions.map((row) => row.caption)).toContain(dos.at(0)?.caption);
-    const dontCaptions = await runSelectQuery(
-      store,
-      `SELECT ?caption WHERE { <${uri}> cs:dont ?ex . ?ex cs:description ?caption }`,
-      "test:oracle",
-    );
-    expect(dontCaptions.map((row) => row.caption)).toContain(
-      donts.at(0)?.caption,
-    );
-  });
-
-  it("honors the legacy --detailed alias flag", async () => {
-    const aliased = await lookupPack(LOOKUP_NAME, { detailed: true });
-    const explicit = await lookupPack(LOOKUP_NAME, { detail: "detailed" });
-    expect(aliased).toEqual(explicit);
-  });
-
-  it("keeps cs:extends as the raw IRI in data — a pinned gap", async () => {
-    const entity = await lookupPack(EXTENDS_LOOKUP_NAME);
-    const extendsIri = entity.extends as string;
-    expect(extendsIri).toMatch(/^https?:\/\//);
-    // Display-time compaction still yields the prefixed form.
-    expect(compactUri(extendsIri, DEFAULT_PREFIX_MAP)).toMatch(/^cs:/);
-  });
-
-  it("resolves the same entity by absolute IRI and prefixed name", async () => {
-    const byName = await lookupPack(LOOKUP_NAME);
-    const uri = byName.uri as string;
-
-    const byIri = await lookupPack(uri);
-    expect(byIri.name).toBe(LOOKUP_NAME);
-
-    const prefixed = compactUri(uri, DEFAULT_PREFIX_MAP);
-    expect(prefixed).toMatch(/^cs:/);
-    const byPrefixed = await lookupPack(prefixed);
-    expect(byPrefixed.name).toBe(LOOKUP_NAME);
-  });
-
-  it("expands glob queries against the standard names", async () => {
-    const lookup = compiled.lookup;
-    if (!lookup) throw new Error("expected lookup story");
-    const result = await lookup.resolve(rt, ["react/component/*"], {});
-    expect(result.errors).toEqual([]);
-    expect(result.results.length).toBeGreaterThan(1);
-    for (const entity of result.results) {
-      expect(String(entity.name)).toMatch(/^react\/component\//);
-    }
-  });
-
-  it("reports misses with ranked suggestions", async () => {
-    const lookup = compiled.lookup;
-    if (!lookup) throw new Error("expected lookup story");
-    const result = await lookup.resolve(rt, [NEAR_MISS_NAME], {});
-    expect(result.results).toEqual([]);
-    const error = result.errors.at(0);
-    expect(error?.code).toBe("ENTITY_NOT_FOUND");
-    expect(error?.suggestions).toContain("code/function/purity");
-  });
-});
-
-describe("standard categories parity", () => {
-  it("lists every category with its standard count (zero-counts kept)", async () => {
-    const categories = compiled.verbs.find(
-      (story) => story.verb === "categories",
-    );
-    if (!categories) throw new Error("expected a categories verb");
-    const rows = await categories.resolve(rt, {});
-    expect(rows.length).toBeGreaterThan(0);
-
-    // Independent oracle: recount per category from the list story.
-    const listRows = await compiled.list.resolve(rt, {});
-    const expected = new Map<string, number>();
-    for (const row of listRows) {
-      if (row.category) {
-        expected.set(row.category, (expected.get(row.category) ?? 0) + 1);
-      }
-    }
-    for (const [category, count] of expected) {
-      const row = rows.find((entry) => entry.name === category);
-      expect(row, `category "${category}" missing`).toBeDefined();
-      expect(Number(row?.count)).toBe(count);
-    }
-    // Categories beyond the expected map are zero-count declarations.
-    for (const row of rows) {
-      if (!expected.has(row.name ?? "")) {
-        expect(Number(row.count)).toBe(0);
-      }
-    }
-  });
-});
-
-// Synthetic fixture: the pinned @canonical/code-standards release names every
-// standard, so the real-graph suites above cannot observe the list query's
-// COALESCE/STRAFTER derived-name fallback or the name-addressable/list-row
-// population split. This tiny store has one NAMED and one UNNAMED standard.
-describe("standard pack on a synthetic graph (derived-name fallback)", () => {
-  const CS = TRANSITIONAL_DS_PREFIX_MAP.cs;
-  const SYNTHETIC_TTL = `
-@prefix cs: <${CS}> .
-
-cs:code.named a cs:CodeStandard ;
-  cs:name "code/named" ;
-  cs:description "A standard with an explicit cs:name." .
-
-<${CS}react.component.unnamed> a cs:CodeStandard ;
-  cs:description "A standard without cs:name." .
-`;
-
-  let syntheticStore: Store;
-  let syntheticCleanup: () => void;
-  let syntheticRt: PragmaRuntime;
-  let synthetic: CompiledPackStories;
-
-  beforeAll(async () => {
-    const result = await createTestStore({ ttl: SYNTHETIC_TTL });
-    syntheticStore = result.store;
-    syntheticCleanup = result.cleanup;
-    syntheticRt = { store: syntheticStore } as PragmaRuntime;
-    synthetic = compilePackStories(standardPack, "test:synthetic", {
-      ...DEFAULT_PREFIX_MAP,
-    });
-  });
-
-  afterAll(() => syntheticCleanup());
-
-  it("lists the unnamed standard under its IRI-derived slash-name", async () => {
-    const rows = await synthetic.list.resolve(syntheticRt, {});
-    expect(rows.map((row) => row.name).sort()).toEqual([
-      "code/named",
-      "react/component/unnamed",
-    ]);
-    const derived = rows.find((row) => row.name === "react/component/unnamed");
-    expect(derived?.uri).toBe(`${CS}react.component.unnamed`);
-    expect(derived?.description).toBe("A standard without cs:name.");
-  });
-
-  it("counts only the NAMED standard in the sample population", async () => {
-    const sample = synthetic.sample;
-    if (!sample) throw new Error("expected a sample story");
-    const data = await sample.resolve(syntheticRt, { count: "1" });
-    // 2 list rows, but only 1 name-addressable standard (PARITY_GAPS).
-    expect(data.totalCount).toBe(1);
-    expect(data.samples.map((entity) => entity.name)).toEqual(["code/named"]);
-  });
-
-  it("cannot address the unnamed standard's derived name via lookup", async () => {
-    const lookup = synthetic.lookup;
-    if (!lookup) throw new Error("expected a lookup story");
-    const result = await lookup.resolve(
-      syntheticRt,
-      ["react/component/unnamed"],
-      {},
-    );
-    expect(result.results).toEqual([]);
-    expect(result.errors.at(0)?.code).toBe("ENTITY_NOT_FOUND");
-  });
-});
-
-describe("standard sample parity", () => {
-  it("returns N full exemplars (highest disclosure) with the population size", async () => {
-    const sample = compiled.sample;
-    if (!sample) throw new Error("expected a sample story");
-    const data = await sample.resolve(rt, { count: "2" });
-    expect(data.samples).toHaveLength(2);
-    // PARITY_GAPS: totalCount counts NAME-ADDRESSABLE standards (the set
-    // the sampler can resolve), while the list also carries rows whose
-    // name is COALESCE-derived from the IRI — so the list length is only
-    // an upper bound. The independent oracle is the shared suggestions
-    // name query (cs:name only, different query path, same store).
-    const nameAddressable = await listDomainNames(store, "standard");
-    expect(nameAddressable.length).toBeGreaterThan(0);
-    expect(data.totalCount).toBe(nameAddressable.length);
-    const listRows = await compiled.list.resolve(rt, {});
-    expect(data.totalCount).toBeLessThanOrEqual(listRows.length);
-    for (const entity of data.samples) {
-      expect(entity.name).toBeTruthy();
-      // Highest level: expands are fetched (arrays, possibly empty).
-      expect(Array.isArray(entity.dos)).toBe(true);
-      expect(Array.isArray(entity.donts)).toBe(true);
-    }
-  });
-});

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

@@ -1,224 +0,0 @@
-/**
- * Declarative story-pack definitions — read stories as data.
- *
- * A story pack maps a noun to preferred queries: a SPARQL SELECT for the
- * list story and a generated, injection-safe lookup. Definitions are
- * declared in `pragma.config.json` (`stories`) or shipped by semantic
- * packages (`stories/*.json`) and compiled through the read-story kernel
- * into CLI commands and MCP tools at boot.
- *
- * @experimental The story-pack format (v0) is experimental: field names,
- * lookup generation, and rendering semantics may change while GraphQL
- * document queries and SHACL-derived defaults are designed.
- */
-
-/** A list column: a SELECT variable to display. */
-export interface StoryPackColumn {
-  /** SELECT variable name (without `?`). */
-  readonly field: string;
-  /** Column heading (defaults to the field name). */
-  readonly label?: string;
-}
-
-/** A looked-up value: an output name bound to a property of the entity. */
-export interface StoryPackField {
-  /** Output field name on the looked-up entity. */
-  readonly name: string;
-  /** Property to read — a prefixed name (`ex:category`) or absolute IRI. */
-  readonly property: string;
-  /** Display label (defaults to the field name). */
-  readonly label?: string;
-}
-
-/** A long-form lookup section. */
-export interface StoryPackSection extends StoryPackField {
-  /** Rendering kind (v0 supports inline fields and code blocks). */
-  readonly kind?: "field" | "code";
-}
-
-/** A field read from each child node of an {@link StoryPackExpand}. */
-export interface StoryPackExpandField {
-  /** Output field name on the child record. */
-  readonly name: string;
-  /** Property to read on the child node — prefixed name, IRI, or path. */
-  readonly property: string;
-  /** Display label (defaults to the field name). */
-  readonly label?: string;
-}
-
-/**
- * A multi-valued nested projection: `entity → relation → child nodes`, each
- * child projected to a small record. This is pack v1's structured-section
- * primitive — the one thing v0 could not express (dos/donts, token scales,
- * modifier values). Resolved with a generated, injection-safe sub-SELECT bound
- * to the already-resolved entity IRI (never user input), so it needs no
- * GraphQL. Rendered through the shared `list`/`table` render-kinds.
- */
-export interface StoryPackExpand {
-  /** Output field holding the child array on the looked-up entity. */
-  readonly name: string;
-  /** Section heading (defaults to the field name). */
-  readonly heading?: string;
-  /** Render kind for the array (v1: `list` or `table`; defaults to `list`). */
-  readonly kind?: "list" | "table";
-  /** Relation from the entity to each child node — prefixed name, IRI, or path. */
-  readonly relation: string;
-  /** Fields to read from each child node. */
-  readonly select: readonly StoryPackExpandField[];
-  /** Render the section even when the array is empty (default: false). */
-  readonly showWhenEmpty?: boolean;
-  /**
-   * Minimum disclosure level at which this expand is fetched and rendered — a
-   * name from {@link StoryPackDisclosure.levels}. Omitted means the base level
-   * (always included). Below its level the sub-SELECT never runs, so gating is
-   * both a cost and a rendering control.
-   */
-  readonly level?: string;
-}
-
-/**
- * Progressive-disclosure capability for a lookup.
- *
- * Declares an **ordered** list of named levels (the first is the base/default,
- * always shown). Fields/expands tag themselves with the minimum level at which
- * they appear. The compiler derives from this one declaration: a `--detail
- * <level>` CLI flag, a `detail` MCP parameter (enumerated from the levels), and
- * the JSON/plain/llm projection for the selected level. Levels are additive and
- * optional — a lookup with no disclosure exposes no detail flag.
- */
-export interface StoryPackDisclosure {
-  /** Ordered level names, lowest → highest. The first is the base/default. */
-  readonly levels: readonly string[];
-  /** Default level when none is requested (must be one of `levels`). */
-  readonly default?: string;
-}
-
-/**
- * A declarative list filter: a CLI/MCP parameter constraining one SELECT
- * variable.
- *
- * Filters are row predicates applied AFTER the author query runs — the
- * query text is never modified, so filter input cannot inject SPARQL,
- * and the author's ORDER BY is preserved.
- */
-export interface StoryPackFilter {
-  /**
-   * Parameter name — a single lowercase word, exposed as `--param` on the
-   * CLI and as the parameter key on the MCP tool.
-   */
-  readonly param: string;
-  /** SELECT variable the filter constrains (without `?`). */
-  readonly variable: string;
-  /**
-   * Allowed values; anything else is rejected with INVALID_INPUT and the
-   * set projects to CLI select choices and an MCP enum. Omitted when the
-   * value set is data-driven (e.g. categories that live in the graph): the
-   * parameter is then a free string matched case-insensitively against the
-   * variable — still a post-query row predicate, never query text.
-   */
-  readonly values?: readonly string[];
-  /** Help text (defaults to a generated description). */
-  readonly description?: string;
-}
-
-/**
- * Free-text search over list rows: a `--search` string parameter that
- * keeps a row when ANY named SELECT variable's value contains the term
- * (case-insensitive substring). Like filters, search is applied after the
- * author query runs — user input never touches the query text.
- */
-export interface StoryPackSearch {
-  /** SELECT variables searched (without `?`). */
-  readonly variables: readonly string[];
-  /** Help text (defaults to a generated description). */
-  readonly description?: string;
-}
-
-/** The list half of a story pack. */
-export interface StoryPackList {
-  /** SPARQL SELECT producing one row per item. */
-  readonly query: string;
-  /** Columns to render, referencing SELECT variables. */
-  readonly columns: readonly StoryPackColumn[];
-  /** Declarative filters projected to CLI flags and MCP parameters. */
-  readonly filters?: readonly StoryPackFilter[];
-  /** Free-text search projected to a `--search` flag / `search` parameter. */
-  readonly search?: StoryPackSearch;
-}
-
-/**
- * An additional list-shaped verb: `<noun> <verb>` and `<noun>_<verb>`
- * compiled through the SAME machinery as `list` (query, columns, filters,
- * search) — e.g. standard's `categories`. The verb may not collide with
- * the compiled `list`/`lookup`/`sample` verbs.
- */
-export interface StoryPackVerb extends StoryPackList {
-  /** Verb name (kebab-case), e.g. `"categories"`. */
-  readonly verb: string;
-  /** CLI description for the command. */
-  readonly description?: string;
-  /** MCP tool description (defaults to the CLI description). */
-  readonly toolDescription?: string;
-}
-
-/**
- * The sample capability: `<noun> sample [count]` and `<noun>_sample`
- * return 1–5 randomly selected complete entities (resolved through the
- * lookup path at the HIGHEST disclosure level) so agents can learn the
- * data shape before querying.
- */
-export interface StoryPackSample {
-  /** Default sample count when none is requested (1–5; default 2). */
-  readonly count?: number;
-  /** CLI description for the command. */
-  readonly description?: string;
-  /** MCP tool description (defaults to the CLI description). */
-  readonly toolDescription?: string;
-}
-
-/**
- * The lookup half of a story pack. The query is generated from `type` and
- * `by` — user-supplied names are escaped by the generator, never
- * interpolated by the author.
- */
-export interface StoryPackLookup {
-  /** Property whose value names the entity — prefixed name or IRI. */
-  readonly by: string;
-  /** Optional class constraint — prefixed name or IRI. */
-  readonly type?: string;
-  /** CLI description for the lookup command (defaults to a generated one). */
-  readonly description?: string;
-  /** MCP tool description (defaults to a generated one). */
-  readonly toolDescription?: string;
-  /** Inline fields shown under the entity title. */
-  readonly fields?: readonly StoryPackField[];
-  /** Long-form sections shown after the fields. */
-  readonly sections?: readonly StoryPackSection[];
-  /** Multi-valued nested projections (pack v1 structured sections). */
-  readonly expand?: readonly StoryPackExpand[];
-  /** Progressive-disclosure levels; enables the derived `--detail` flag. */
-  readonly disclosure?: StoryPackDisclosure;
-  /** Sample capability: `true` for defaults, or a configured sample. */
-  readonly sample?: true | StoryPackSample;
-}
-
-/** One declarative read story: a noun with its preferred queries. */
-export interface StoryPackDefinition {
-  /** Command noun (kebab-case), e.g. `"recipe"` → `pragma recipe list`. */
-  readonly noun: string;
-  /** CLI description for the list command. */
-  readonly description?: string;
-  /** MCP tool description (defaults to the CLI description). */
-  readonly toolDescription?: string;
-  readonly list: StoryPackList;
-  /** Additional list-shaped verbs beyond `list` (e.g. `categories`). */
-  readonly verbs?: readonly StoryPackVerb[];
-  readonly lookup?: StoryPackLookup;
-}
-
-/** A story definition with the source it came from, for diagnostics. */
-export interface StoryPackSource {
-  /** Where the definition was declared (config path or package file). */
-  readonly source: string;
-  readonly definition: StoryPackDefinition;
-}