@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

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

@@ -0,0 +1,253 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import type {
+  ColumnDef,
+  LookupField,
+  RenderListOptions,
+  RenderLookupOptions,
+  SectionDef,
+} from "../../contracts.js";
+import type { Formatters } from "../../formatters.js";
+import lookupMany from "../../lookupMany.js";
+import {
+  renderListLlm,
+  renderListPlain,
+  renderLookupLlm,
+  renderLookupPlain,
+} from "../../renderers.js";
+import { suggestNames } from "../../suggestions/index.js";
+import requirePragmaContext from "../requirePragmaContext.js";
+import type { LookupStory, ReadStory, StoryParam } from "../types.js";
+import applyPackFilters from "./applyPackFilters.js";
+import buildLookupQuery, { buildLookupNamesQuery } from "./buildLookupQuery.js";
+import runSelectQuery from "./runSelectQuery.js";
+import type {
+  StoryPackDefinition,
+  StoryPackFilter,
+  StoryPackLookup,
+} from "./types.js";
+
+/** A pack entity/row: SELECT variable name → string value. */
+type PackRow = Record<string, string>;
+
+/** The read stories a pack definition compiles to. */
+export interface CompiledPackStories {
+  readonly list: ReadStory<PackRow[], PackRow[]>;
+  readonly lookup?: LookupStory<PackRow, PackRow>;
+}
+
+/**
+ * Compile one validated story-pack definition into kernel read stories.
+ *
+ * The list story runs the pack's preferred SELECT verbatim; the lookup
+ * story runs the generated, injection-safe per-name query. Both render
+ * through the shared generic renderers with the runtime's merged prefix
+ * map, so foreign namespaces display compacted.
+ *
+ * @param definition - A validated pack definition.
+ * @param source - Where the definition came from, for diagnostics.
+ * @param prefixes - The merged prefix map used for display.
+ * @returns The compiled list story and, when declared, the lookup story.
+ */
+export default function compilePackStories(
+  definition: StoryPackDefinition,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): CompiledPackStories {
+  const { noun } = definition;
+  const heading = capitalize(noun);
+  const description = definition.description ?? `List ${noun} entries`;
+
+  const listColumns: ColumnDef<PackRow>[] = definition.list.columns.map(
+    (column) => ({
+      key: column.field,
+      label: column.label ?? column.field,
+    }),
+  );
+  const listOptions: RenderListOptions<PackRow> = {
+    heading,
+    columns: listColumns,
+    prefixes,
+  };
+  const listFormatters: Formatters<PackRow[]> = {
+    plain: (rows) => renderListPlain(rows, listOptions),
+    llm: (rows) => renderListLlm(rows, listOptions),
+    json: (rows) => JSON.stringify(rows, null, 2),
+  };
+
+  const filters = definition.list.filters;
+  const filterExample = filters?.at(0);
+  const list: ReadStory<PackRow[], PackRow[]> = {
+    noun,
+    verb: "list",
+    description,
+    toolDescription:
+      definition.toolDescription ?? `${description} (story pack: ${source}).`,
+    params: projectFilterParams(filters),
+    examples: [
+      `pragma ${noun} list`,
+      ...(filterExample
+        ? [
+            `pragma ${noun} list --${filterExample.param} ${quoteExampleValue(filterExample.values.at(0) ?? "")}`,
+          ]
+        : []),
+      `pragma ${noun} list --llm`,
+    ],
+    resolve: async (rt, params) =>
+      applyPackFilters(
+        await runSelectQuery(rt.store, definition.list.query, source),
+        filters,
+        params,
+      ),
+    toOutput: (rows) => rows,
+    formatters: listFormatters,
+    toEnvelope: (rows) => ({ data: rows, meta: { count: rows.length } }),
+  };
+
+  const lookup = definition.lookup
+    ? compileLookup(definition.lookup, noun, source, prefixes)
+    : undefined;
+
+  return { list, ...(lookup ? { lookup } : {}) };
+}
+
+function compileLookup(
+  lookup: StoryPackLookup,
+  noun: string,
+  source: string,
+  prefixes: Readonly<Record<string, string>>,
+): LookupStory<PackRow, PackRow> {
+  const fields: LookupField<PackRow>[] = (lookup.fields ?? []).map((field) => ({
+    label: field.label ?? field.name,
+    value: (entity) => entity[field.name],
+  }));
+  const sections: SectionDef<PackRow>[] = (lookup.sections ?? []).map(
+    (section) => ({
+      key: section.name,
+      heading: section.label ?? section.name,
+      kind: section.kind ?? "field",
+    }),
+  );
+  const lookupOptions: RenderLookupOptions<PackRow> = {
+    title: (entity) => entity.name ?? entity.uri ?? "(unnamed)",
+    fields,
+    sections,
+    prefixes,
+  };
+  const lookupFormatters: Formatters<PackRow> = {
+    plain: (entity) => renderLookupPlain(entity, lookupOptions),
+    llm: (entity) => renderLookupLlm(entity, lookupOptions),
+    json: (entity) => JSON.stringify(entity, null, 2),
+  };
+
+  return {
+    noun,
+    description: `Look up ${noun} details by name`,
+    toolDescription: `Get details for one or more ${noun} entries by name (story pack: ${source}).`,
+    namesDescription: `${capitalize(noun)} names`,
+    complete: async (partial, cmdCtx) => {
+      const ctx = requirePragmaContext(cmdCtx);
+      const names = await listEntityNames(ctx.store, lookup, source);
+      return names.filter((name) =>
+        name.toLowerCase().startsWith(partial.toLowerCase()),
+      );
+    },
+    examples: [`pragma ${noun} lookup <name>`],
+    resolve: (rt, names) =>
+      lookupMany(names, (query) =>
+        lookupPackEntity(rt.store, lookup, noun, query, source),
+      ),
+    toFmtInput: (entity) => entity,
+    formatters: lookupFormatters,
+    emptyNamesError: () =>
+      PragmaError.invalidInput("names", "(empty)", {
+        recovery: {
+          message: `List available ${noun} entries.`,
+          cli: `pragma ${noun} list`,
+          mcp: { tool: `${noun}_list` },
+        },
+      }),
+  };
+}
+
+/**
+ * Look up one pack entity by name via the generated query.
+ *
+ * @throws PragmaError with code `ENTITY_NOT_FOUND` and ranked suggestions
+ *   when no entity matches.
+ * @note Impure — queries the ke store.
+ */
+async function lookupPackEntity(
+  store: Store,
+  lookup: StoryPackLookup,
+  noun: string,
+  query: string,
+  source: string,
+): Promise<PackRow> {
+  const rows = await runSelectQuery(
+    store,
+    buildLookupQuery(lookup, query),
+    source,
+  );
+  const entity = rows.at(0);
+  if (entity) {
+    return entity;
+  }
+
+  const candidates = await listEntityNames(store, lookup, source);
+  throw PragmaError.notFound(noun, query, {
+    suggestions: suggestNames(query, candidates),
+    recovery: {
+      message: `List available ${noun} entries.`,
+      cli: `pragma ${noun} list`,
+      mcp: { tool: `${noun}_list` },
+    },
+  });
+}
+
+async function listEntityNames(
+  store: Store,
+  lookup: StoryPackLookup,
+  source: string,
+): Promise<string[]> {
+  const rows = await runSelectQuery(
+    store,
+    buildLookupNamesQuery(lookup),
+    source,
+  );
+  return rows.map((row) => row.name ?? "").filter((name) => name !== "");
+}
+
+/**
+ * Quote a filter value for a shell help example when it is not a bare word.
+ *
+ * Values with whitespace or shell-sensitive characters are double-quoted
+ * so the generated `pragma … list --flag value` example stays valid to
+ * copy-paste; simple tokens render unquoted.
+ */
+function quoteExampleValue(value: string): string {
+  return /^[\w.-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
+/**
+ * Project declared pack filters onto kernel story parameters.
+ *
+ * The declared value set becomes the parameter's enum, which the kernel
+ * projects to CLI select choices and an MCP enum schema.
+ */
+function projectFilterParams(
+  filters: readonly StoryPackFilter[] | undefined,
+): StoryParam[] {
+  return (filters ?? []).map((filter) => ({
+    name: filter.param,
+    type: "string",
+    description:
+      filter.description ??
+      `Filter by ${filter.variable} (${filter.values.join(", ")})`,
+    enum: filter.values,
+  }));
+}
+
+function capitalize(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}

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

@@ -0,0 +1,43 @@
+import { PREFIX_MAP } from "../../prefixes.js";
+import type { ToolSpec } from "../../ToolSpec.js";
+import type { PragmaRuntime } from "../../types/index.js";
+import compileLookupTool from "../compileLookupTool.js";
+import compileReadTool from "../compileReadTool.js";
+import collectPackStories from "./collectPackStories.js";
+import compilePackStories from "./compilePackStories.js";
+
+/**
+ * Compile every active story pack into MCP tool specs.
+ *
+ * Mirrors `compilePackCommands` on the MCP surface: each pack yields
+ * `<noun>_list` and, when declared, `<noun>_lookup`, registered alongside
+ * the built-in tools.
+ *
+ * @param runtime - Pragma runtime carrying config, packages, and the store.
+ * @param reservedNouns - Built-in nouns packs must not shadow.
+ * @returns Tool specs for every pack story.
+ */
+export default function compilePackToolSpecs(
+  runtime: PragmaRuntime,
+  reservedNouns: ReadonlySet<string>,
+): ToolSpec[] {
+  const prefixes = { ...PREFIX_MAP, ...runtime.config.prefixes };
+  const entries = collectPackStories(
+    runtime.config,
+    runtime.packages,
+    reservedNouns,
+  );
+
+  return entries.flatMap((entry) => {
+    const compiled = compilePackStories(
+      entry.definition,
+      entry.source,
+      prefixes,
+    );
+    const specs = [compileReadTool(compiled.list)];
+    if (compiled.lookup) {
+      specs.push(compileLookupTool(compiled.lookup));
+    }
+    return specs;
+  });
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Story packs — declarative read stories compiled through the kernel.
+ * @module
+ */
+
+export {
+  buildLookupNamesQuery,
+  default as buildLookupQuery,
+  escapeSparqlString,
+  formatTerm,
+} from "./buildLookupQuery.js";
+export type { PackStoryEntry } from "./collectPackStories.js";
+export { default as collectPackStories } from "./collectPackStories.js";
+export { default as compilePackCommands } from "./compilePackCommands.js";
+export type { CompiledPackStories } from "./compilePackStories.js";
+export { default as compilePackStories } from "./compilePackStories.js";
+export { default as compilePackToolSpecs } from "./compilePackToolSpecs.js";
+export { default as runSelectQuery } from "./runSelectQuery.js";
+export type {
+  StoryPackColumn,
+  StoryPackDefinition,
+  StoryPackField,
+  StoryPackList,
+  StoryPackLookup,
+  StoryPackSection,
+  StoryPackSource,
+} from "./types.js";
+export { default as validateStoryPackDefinition } from "./validateStoryPackDefinition.js";

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

@@ -0,0 +1,31 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import { buildQuery } from "../../buildQuery.js";
+
+/**
+ * Run a pack story's SELECT and return its binding rows.
+ *
+ * The store rejects non-read queries at the engine level; this guards the
+ * result shape so a pack whose query is not a SELECT fails with a
+ * recoverable config error instead of a shape mismatch downstream.
+ *
+ * @param store - The ke store to query.
+ * @param query - SPARQL SELECT text (the store injects PREFIX declarations).
+ * @param source - The pack source, for error attribution.
+ * @returns One record per row, keyed by SELECT variable name.
+ * @throws PragmaError with code `CONFIG_ERROR` when the query is not a SELECT.
+ * @note Impure — queries the ke store.
+ */
+export default async function runSelectQuery(
+  store: Store,
+  query: string,
+  source: string,
+): Promise<Record<string, string>[]> {
+  const result = await store.query(buildQuery(query));
+  if (result.type !== "select") {
+    throw PragmaError.configError(
+      `Story query in ${source} must be a SELECT (got ${result.type}).`,
+    );
+  }
+  return result.bindings;
+}

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

@@ -0,0 +1,308 @@
+/**
+ * Standard-noun parity pilot — the built-in `standard` read stories vs
+ * the declarative pack definition in `standardParityFixtures.ts`.
+ *
+ * Both paths run against the real @canonical/code-standards graphs,
+ * resolved from node_modules through the production loader chain — no
+ * fixture TTL. Assertions demand byte parity wherever the v0 pack
+ * format reaches; every remaining divergence is pinned exactly and
+ * must be named in PARITY_GAPS. Nothing is cut over: the built-in
+ * stories stay untouched and the pack is compiled directly.
+ */
+
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { PARITY_GAPS, STANDARD_PACK_STORY } from "#testing";
+import { parsePackageEntry } from "../../../refs/operations/parseRef.js";
+import type { StandardListOutput } from "../../../standard/formatters/index.js";
+import {
+  standardListStory,
+  standardLookupStory,
+} from "../../../standard/stories.js";
+import { bootStore } from "../../bootStore.js";
+import compactUri from "../../compactUri.js";
+import { PREFIX_MAP } from "../../prefixes.js";
+import type { PragmaRuntime, StandardDetailed } from "../../types/index.js";
+import type { LookupStoryView } from "../types.js";
+import compilePackStories, {
+  type CompiledPackStories,
+} from "./compilePackStories.js";
+import validateStoryPackDefinition from "./validateStoryPackDefinition.js";
+
+const PACK_SOURCE = "standardParityFixtures";
+
+/** The built-in CLI default view: summary lookup, no extra params. */
+const SUMMARY_VIEW: LookupStoryView = {
+  surface: "cli",
+  detailed: false,
+  params: {},
+};
+
+/** Real standard names without cs:extends — full byte parity expected. */
+const PARITY_LOOKUP_NAMES = [
+  "code/function/purity",
+  "react/component/props",
+] as const;
+
+/** A real standard with cs:extends — pins the JSON compaction gap. */
+const EXTENDS_LOOKUP_NAME = "react/component/structure/context";
+
+/** A near-miss query — both paths must produce identical suggestions. */
+const NEAR_MISS_NAME = "code/function/puriti";
+
+let store: Store;
+let rt: PragmaRuntime;
+let packList: CompiledPackStories["list"];
+let packLookup: NonNullable<CompiledPackStories["lookup"]>;
+
+beforeAll(async () => {
+  const boot = await bootStore({
+    refs: [parsePackageEntry("@canonical/code-standards")],
+  });
+  store = boot.store;
+  rt = { store } as PragmaRuntime;
+
+  const compiled = compilePackStories(STANDARD_PACK_STORY, PACK_SOURCE, {
+    ...PREFIX_MAP,
+  });
+  packList = compiled.list;
+  const lookup = compiled.lookup;
+  if (!lookup) {
+    throw new Error("STANDARD_PACK_STORY must declare a lookup story");
+  }
+  packLookup = lookup;
+});
+
+afterAll(() => store?.dispose());
+
+/** Resolve one name through the built-in lookup story. */
+async function lookupBuiltin(name: string): Promise<StandardDetailed> {
+  const result = await standardLookupStory.resolve(rt, [name], {});
+  expect(result.errors).toEqual([]);
+  const entity = result.results.at(0);
+  if (entity === undefined) {
+    throw new Error(`built-in lookup found no result for "${name}"`);
+  }
+  return entity;
+}
+
+/** Resolve one name through the compiled pack lookup story. */
+async function lookupPack(name: string): Promise<Record<string, string>> {
+  const result = await packLookup.resolve(rt, [name], {});
+  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;
+}
+
+/**
+ * Remove the built-in's URI field line — the one v0 lookup rendering
+ * gap (see PARITY_GAPS: "lookup uri field"). Asserts the line occurs
+ * exactly once so the transformation cannot mask other divergence.
+ */
+function dropUriField(text: string, marker: "  URI: " | "- URI: "): string {
+  const lines = text.split("\n");
+  const remaining = lines.filter((line) => !line.startsWith(marker));
+  expect(lines.length - remaining.length).toBe(1);
+  return remaining.join("\n");
+}
+
+/** Assert every name appears in the text, in order. */
+function expectNamesInOrder(text: string, names: readonly string[]): void {
+  let cursor = 0;
+  for (const name of names) {
+    const index = text.indexOf(name, cursor);
+    expect(
+      index,
+      `expected "${name}" after position ${cursor}`,
+    ).toBeGreaterThanOrEqual(0);
+    cursor = index + name.length;
+  }
+}
+
+describe("standard pack definition", () => {
+  it("round-trips as declarative JSON and validates as a v0 pack", () => {
+    const raw: unknown = JSON.parse(JSON.stringify(STANDARD_PACK_STORY));
+    expect(validateStoryPackDefinition(raw, PACK_SOURCE)).toEqual(
+      STANDARD_PACK_STORY,
+    );
+  });
+
+  it("records every known gap as a distinct capability 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 builtinResolution: Awaited<ReturnType<typeof standardListStory.resolve>>;
+  let builtinOutput: StandardListOutput;
+  let packRows: Record<string, string>[];
+
+  beforeAll(async () => {
+    builtinResolution = await standardListStory.resolve(rt, {});
+    builtinOutput = standardListStory.toOutput(builtinResolution, {});
+    packRows = await packList.resolve(rt, {});
+  });
+
+  it("resolves the same rows as the built-in resolver", () => {
+    expect(packRows.length).toBeGreaterThan(0);
+    expect(packRows).toEqual(builtinOutput.items);
+  });
+
+  it("json output is byte-identical", () => {
+    const builtinJson = standardListStory.formatters.json(builtinOutput);
+    const packJson = packList.formatters.json(packList.toOutput(packRows, {}));
+    expect(packJson).toBe(builtinJson);
+  });
+
+  it("MCP envelope matches the built-in summary envelope", () => {
+    expect(packList.toEnvelope(packRows)).toEqual(
+      standardListStory.toEnvelope(builtinResolution),
+    );
+  });
+
+  it("plain output carries every standard in order — layout is a recorded gap", () => {
+    const names = builtinOutput.items.map((item) => item.name);
+    const builtinPlain = standardListStory.formatters.plain(builtinOutput);
+    const packPlain = packList.formatters.plain(
+      packList.toOutput(packRows, {}),
+    );
+    expectNamesInOrder(builtinPlain, names);
+    expectNamesInOrder(packPlain, names);
+    // Layout divergence pinned — see PARITY_GAPS "list plain template".
+    expect(packPlain).not.toBe(builtinPlain);
+  });
+
+  it("llm output carries every standard in order — templates are a recorded gap", () => {
+    const names = builtinOutput.items.map((item) => item.name);
+    const builtinLlm = standardListStory.formatters.llm(builtinOutput);
+    const packLlm = packList.formatters.llm(packList.toOutput(packRows, {}));
+    expectNamesInOrder(builtinLlm, names);
+    expectNamesInOrder(packLlm, names);
+    // Heading divergence pinned — see PARITY_GAPS "list llm template".
+    expect(builtinLlm.startsWith("## Standards\n")).toBe(true);
+    expect(packLlm.startsWith(`## Standard (${packRows.length})\n`)).toBe(true);
+    expect(packLlm).not.toBe(builtinLlm);
+  });
+});
+
+describe("standard lookup parity (summary view)", () => {
+  for (const name of PARITY_LOOKUP_NAMES) {
+    it(`plain output for "${name}" matches modulo the URI field gap`, async () => {
+      const builtinPlain = standardLookupStory.formatters.plain(
+        standardLookupStory.toFmtInput(await lookupBuiltin(name), SUMMARY_VIEW),
+      );
+      const packPlain = packLookup.formatters.plain(
+        packLookup.toFmtInput(await lookupPack(name), SUMMARY_VIEW),
+      );
+      expect(packPlain).toBe(dropUriField(builtinPlain, "  URI: "));
+    });
+
+    it(`llm output for "${name}" matches modulo the URI field gap`, async () => {
+      const builtinLlm = standardLookupStory.formatters.llm(
+        standardLookupStory.toFmtInput(await lookupBuiltin(name), SUMMARY_VIEW),
+      );
+      const packLlm = packLookup.formatters.llm(
+        packLookup.toFmtInput(await lookupPack(name), SUMMARY_VIEW),
+      );
+      expect(packLlm).toBe(dropUriField(builtinLlm, "- URI: "));
+    });
+
+    it(`json output for "${name}" is byte-identical`, async () => {
+      const builtinJson = standardLookupStory.formatters.json(
+        standardLookupStory.toFmtInput(await lookupBuiltin(name), SUMMARY_VIEW),
+      );
+      const packJson = packLookup.formatters.json(
+        packLookup.toFmtInput(await lookupPack(name), SUMMARY_VIEW),
+      );
+      expect(packJson).toBe(builtinJson);
+    });
+  }
+});
+
+describe("standard lookup parity — cs:extends divergence", () => {
+  it("plain and llm stay byte-identical modulo the URI field", async () => {
+    const builtinInput = standardLookupStory.toFmtInput(
+      await lookupBuiltin(EXTENDS_LOOKUP_NAME),
+      SUMMARY_VIEW,
+    );
+    const packInput = packLookup.toFmtInput(
+      await lookupPack(EXTENDS_LOOKUP_NAME),
+      SUMMARY_VIEW,
+    );
+    expect(packLookup.formatters.plain(packInput)).toBe(
+      dropUriField(
+        standardLookupStory.formatters.plain(builtinInput),
+        "  URI: ",
+      ),
+    );
+    expect(packLookup.formatters.llm(packInput)).toBe(
+      dropUriField(standardLookupStory.formatters.llm(builtinInput), "- URI: "),
+    );
+  });
+
+  it("json diverges only on extends compaction — a recorded gap", async () => {
+    const builtinJson = standardLookupStory.formatters.json(
+      standardLookupStory.toFmtInput(
+        await lookupBuiltin(EXTENDS_LOOKUP_NAME),
+        SUMMARY_VIEW,
+      ),
+    );
+    const packJson = packLookup.formatters.json(
+      packLookup.toFmtInput(
+        await lookupPack(EXTENDS_LOOKUP_NAME),
+        SUMMARY_VIEW,
+      ),
+    );
+    // Divergence pinned — see PARITY_GAPS "lookup data compaction".
+    expect(packJson).not.toBe(builtinJson);
+
+    const builtinParsed = JSON.parse(builtinJson) as Record<string, string>;
+    const packParsed = JSON.parse(packJson) as Record<string, string>;
+    const packExtends = packParsed.extends;
+    if (packExtends === undefined) {
+      throw new Error(`expected cs:extends on "${EXTENDS_LOOKUP_NAME}"`);
+    }
+    // The built-in compacts extends in resolved data; the pack keeps the
+    // raw IRI. Compacting the pack value restores byte-level agreement.
+    expect({
+      ...packParsed,
+      extends: compactUri(packExtends, PREFIX_MAP),
+    }).toEqual(builtinParsed);
+    expect(
+      JSON.stringify(
+        { ...packParsed, extends: compactUri(packExtends, PREFIX_MAP) },
+        null,
+        2,
+      ),
+    ).toBe(builtinJson);
+  });
+});
+
+describe("standard lookup miss parity", () => {
+  it("collects identical not-found entries with ranked suggestions", async () => {
+    const builtinResult = await standardLookupStory.resolve(
+      rt,
+      [NEAR_MISS_NAME],
+      {},
+    );
+    const packResult = await packLookup.resolve(rt, [NEAR_MISS_NAME], {});
+    expect(builtinResult.results).toEqual([]);
+    expect(packResult.results).toEqual([]);
+
+    const builtinError = builtinResult.errors.at(0);
+    const packError = packResult.errors.at(0);
+    if (builtinError === undefined || packError === undefined) {
+      throw new Error("both paths must report a not-found error");
+    }
+    expect(packError).toEqual(builtinError);
+    expect(builtinError.code).toBe("ENTITY_NOT_FOUND");
+    expect(builtinError.suggestions).toContain("code/function/purity");
+  });
+});