@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -1,406 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { PragmaConfig } from "#config";
-import { PragmaError } from "#error";
-import { RECIPE_STORY } from "#testing";
-import type { SemanticPackage } from "../../semanticPackage.js";
-import { BUNDLED_PACKS } from "./bundled/index.js";
-import realCollectPackStories from "./collectPackStories.js";
-import {
-  buildReservedVerbs,
-  deriveReservedVerbs,
-  isReserved,
-  type ReservedVerbs,
-} from "./reservedVerbs.js";
-
-/**
- * Test wrapper that isolates the always-present bundled packs: unit tests
- * asserting exact entries pass `[]` so the default bundled `tier` pack does not
- * pollute their expectations. Bundled behavior is covered separately below.
- */
-function collectPackStories(
-  config: PragmaConfig,
-  packages: readonly SemanticPackage[],
-  reserved: ReservedVerbs,
-): ReturnType<typeof realCollectPackStories> {
-  return realCollectPackStories(config, packages, reserved, []);
-}
-
-function makePackage(stories: SemanticPackage["stories"]): SemanticPackage {
-  return {
-    name: "@canonical/example",
-    version: "1.0.0",
-    source: "local",
-    graphs: [],
-    skills: [],
-    stories,
-  };
-}
-
-const CONFIG = { tier: undefined, channel: "normal" as const };
-
-// A representative slice of the real built-in surface: leaf read nouns that
-// own `list`/`lookup`, plus operational nouns (graph, config, create, graphql,
-// setup, tokens) that own neither and so must be reserved wholesale.
-const BUILTIN_PAIRS: readonly (readonly [string, string | undefined])[] = [
-  ["standard", "list"],
-  ["standard", "lookup"],
-  ["standard", "categories"],
-  ["standard", "sample"],
-  ["block", "list"],
-  ["block", "lookup"],
-  ["token", "list"],
-  ["token", "lookup"],
-  ["tier", "list"],
-  ["config", "show"],
-  ["config", "tier"],
-  ["config", "channel"],
-  ["graph", "query"],
-  ["graph", "inspect"],
-  ["create", "component"],
-  ["create", "package"],
-  ["graphql", "build"],
-  ["graphql", "check"],
-  ["graphql", "serve"],
-  ["setup", "all"],
-  ["setup", "lsp"],
-  ["tokens", "add-config"],
-  ["info", undefined],
-];
-
-/** Run a thunk and return the error it throws (or `undefined`). */
-function caught(run: () => unknown): unknown {
-  try {
-    run();
-  } catch (error) {
-    return error;
-  }
-  return undefined;
-}
-
-describe("collectPackStories", () => {
-  let warn: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    warn = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
-  });
-
-  afterEach(() => {
-    warn.mockRestore();
-  });
-
-  it("collects config stories and validated package stories", () => {
-    const entries = collectPackStories(
-      { ...CONFIG, stories: [RECIPE_STORY] },
-      [
-        makePackage([
-          {
-            path: "/pkg/stories/other.json",
-            definition: { ...RECIPE_STORY, noun: "other" },
-          },
-        ]),
-      ],
-      buildReservedVerbs([["block", undefined]]),
-    );
-    expect(entries.map((entry) => entry.definition.noun)).toEqual([
-      "recipe",
-      "other",
-    ]);
-    expect(entries.at(0)?.source).toBe("config");
-    expect(entries.at(1)?.source).toBe("/pkg/stories/other.json");
-  });
-
-  it("lets config stories win noun collisions against packages", () => {
-    const entries = collectPackStories(
-      { ...CONFIG, stories: [RECIPE_STORY] },
-      [
-        makePackage([
-          { path: "/pkg/stories/recipe.json", definition: RECIPE_STORY },
-        ]),
-      ],
-      buildReservedVerbs([]),
-    );
-    expect(entries).toHaveLength(1);
-    expect(entries.at(0)?.source).toBe("config");
-    expect(warn).toHaveBeenCalledWith(
-      expect.stringContaining("already provided"),
-    );
-  });
-
-  it("skips invalid package stories with a warning", () => {
-    const entries = collectPackStories(
-      CONFIG,
-      [
-        makePackage([
-          { path: "/pkg/stories/broken.json", definition: { nope: true } },
-        ]),
-      ],
-      buildReservedVerbs([]),
-    );
-    expect(entries).toHaveLength(0);
-    expect(warn).toHaveBeenCalledWith(
-      expect.stringContaining("skipping story"),
-    );
-  });
-
-  it("throws when a config story shadows a built-in noun", () => {
-    expect(() =>
-      collectPackStories(
-        { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "block" }] },
-        [],
-        buildReservedVerbs([["block", undefined]]),
-      ),
-    ).toThrow(PragmaError);
-  });
-
-  it("skips package stories that shadow built-in nouns", () => {
-    const entries = collectPackStories(
-      CONFIG,
-      [
-        makePackage([
-          {
-            path: "/pkg/stories/block.json",
-            definition: { ...RECIPE_STORY, noun: "block" },
-          },
-        ]),
-      ],
-      buildReservedVerbs([["block", undefined]]),
-    );
-    expect(entries).toHaveLength(0);
-  });
-
-  it("admits a pack once its noun's verbs leave the reserved map", () => {
-    // Post-migration simulation: `standard`'s list/lookup wrappers are gone,
-    // so only categories/sample remain reserved — a `standard` pack (which
-    // emits list + lookup) is now admissible. `info` is a bare (whole-noun)
-    // built-in, so an `info` pack stays blocked. This is the keystone: the
-    // per-verb guard makes the leaf cutover incremental.
-    const reserved = buildReservedVerbs([
-      ["standard", "categories"],
-      ["standard", "sample"],
-      ["info", undefined],
-    ]);
-
-    const entries = collectPackStories(
-      CONFIG,
-      [
-        makePackage([
-          {
-            path: "/pkg/stories/standard.json",
-            definition: { ...RECIPE_STORY, noun: "standard" },
-          },
-          {
-            path: "/pkg/stories/info.json",
-            definition: { ...RECIPE_STORY, noun: "info" },
-          },
-        ]),
-      ],
-      reserved,
-    );
-
-    expect(entries.map((entry) => entry.definition.noun)).toEqual(["standard"]);
-    expect(warn).toHaveBeenCalledWith(
-      expect.stringContaining("shadows built-in command"),
-    );
-  });
-
-  // Regression restoration (FIX 1): operational nouns own no list/lookup, so
-  // deriveReservedVerbs promotes them to a whole-noun reservation. Since a
-  // pack always emits `list`, a pack targeting an operational namespace must
-  // stay BLOCKED — this is the load-bearing proof that the per-verb flip did
-  // not silently open pragma's core operational namespaces to packs.
-  describe("operational nouns stay reserved wholesale", () => {
-    const reserved = deriveReservedVerbs(BUILTIN_PAIRS);
-
-    it("promotes every operational noun to a whole-noun reservation", () => {
-      for (const noun of ["config", "graph", "create", "graphql", "setup"]) {
-        expect(isReserved(reserved, noun, "list")).toBe(true);
-      }
-      // `tokens` (the plural add-config noun) owns only `add-config`.
-      expect(isReserved(reserved, "tokens", "list")).toBe(true);
-    });
-
-    it("throws a config error when a config story shadows an operational noun", () => {
-      const error = caught(() =>
-        collectPackStories(
-          { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "graph" }] },
-          [],
-          reserved,
-        ),
-      );
-      expect(error).toBeInstanceOf(PragmaError);
-      expect((error as PragmaError).code).toBe("CONFIG_ERROR");
-    });
-
-    it("skips a package story that shadows an operational noun", () => {
-      const entries = collectPackStories(
-        CONFIG,
-        [
-          makePackage([
-            {
-              path: "/pkg/stories/graph.json",
-              definition: { ...RECIPE_STORY, noun: "graph" },
-            },
-          ]),
-        ],
-        reserved,
-      );
-      expect(entries).toHaveLength(0);
-      expect(warn).toHaveBeenCalledWith(
-        expect.stringContaining("shadows built-in command"),
-      );
-    });
-  });
-
-  // Keystone incremental window (FIX 3): `standard`'s `list` wrapper is
-  // deleted but `lookup` is still built-in (alongside categories/sample).
-  describe("incremental leaf cutover window", () => {
-    const reserved = deriveReservedVerbs([
-      ["standard", "lookup"],
-      ["standard", "categories"],
-      ["standard", "sample"],
-      ["info", undefined],
-    ]);
-
-    it("keeps `standard` per-verb because it still owns lookup (not promoted)", () => {
-      // Disjointness check: the noun retains a read verb, so it must NOT be
-      // wholesale-promoted — otherwise `list` could never be freed.
-      expect(isReserved(reserved, "standard", "list")).toBe(false);
-      expect(isReserved(reserved, "standard", "lookup")).toBe(true);
-    });
-
-    it("admits a standard pack that declares only list", () => {
-      const listOnly = { ...RECIPE_STORY, noun: "standard", lookup: undefined };
-      const entries = collectPackStories(
-        CONFIG,
-        [
-          makePackage([
-            { path: "/pkg/stories/standard.json", definition: listOnly },
-          ]),
-        ],
-        reserved,
-      );
-      expect(entries.map((entry) => entry.definition.noun)).toEqual([
-        "standard",
-      ]);
-    });
-
-    it("rejects a standard pack that also declares lookup (config throws)", () => {
-      const error = caught(() =>
-        collectPackStories(
-          { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: "standard" }] },
-          [],
-          reserved,
-        ),
-      );
-      expect(error).toBeInstanceOf(PragmaError);
-      expect((error as PragmaError).code).toBe("CONFIG_ERROR");
-    });
-
-    it("rejects a standard pack that also declares lookup (package skips)", () => {
-      const entries = collectPackStories(
-        CONFIG,
-        [
-          makePackage([
-            {
-              path: "/pkg/stories/standard.json",
-              definition: { ...RECIPE_STORY, noun: "standard" },
-            },
-          ]),
-        ],
-        reserved,
-      );
-      expect(entries).toHaveLength(0);
-      expect(warn).toHaveBeenCalledWith(
-        expect.stringContaining("shadows built-in command"),
-      );
-    });
-
-    it("rejects a list-only standard pack whose extra verb is still built-in", () => {
-      // Pack v1 emissions beyond list/lookup are guarded too: `categories`
-      // here collides with the still-registered built-in wrapper.
-      const withCategories = {
-        ...RECIPE_STORY,
-        noun: "standard",
-        lookup: undefined,
-        verbs: [
-          {
-            verb: "categories",
-            query: RECIPE_STORY.list.query,
-            columns: RECIPE_STORY.list.columns,
-          },
-        ],
-      };
-      const error = caught(() =>
-        collectPackStories(
-          { ...CONFIG, stories: [withCategories] },
-          [],
-          reserved,
-        ),
-      );
-      expect(error).toBeInstanceOf(PragmaError);
-      expect((error as PragmaError).message).toContain("standard categories");
-    });
-
-    it("rejects a pack whose sample capability is still built-in", () => {
-      const withSample = {
-        ...RECIPE_STORY,
-        noun: "standard",
-        lookup: {
-          // biome-ignore lint/style/noNonNullAssertion: fixture always declares lookup
-          ...RECIPE_STORY.lookup!,
-          sample: true as const,
-        },
-      };
-      const error = caught(() =>
-        collectPackStories({ ...CONFIG, stories: [withSample] }, [], reserved),
-      );
-      expect(error).toBeInstanceOf(PragmaError);
-      expect((error as PragmaError).message).toContain("standard sample");
-    });
-  });
-
-  // Bundled transitional packs use the REAL collect (not the isolating wrapper).
-  describe("bundled packs", () => {
-    it("includes bundled packs by default, lowest precedence", () => {
-      const entries = realCollectPackStories(
-        CONFIG,
-        [],
-        buildReservedVerbs([]),
-      );
-      const nouns = entries.map((entry) => entry.definition.noun);
-      // Every bundled pack is present, tagged with a `bundled:` source.
-      for (const pack of BUNDLED_PACKS) {
-        expect(nouns).toContain(pack.noun);
-        const entry = entries.find((e) => e.definition.noun === pack.noun);
-        expect(entry?.source).toBe(`bundled:${pack.noun}`);
-      }
-    });
-
-    it("lets a config story override a bundled noun (config wins)", () => {
-      const bundledNoun = BUNDLED_PACKS[0]?.noun ?? "tier";
-      const entries = realCollectPackStories(
-        { ...CONFIG, stories: [{ ...RECIPE_STORY, noun: bundledNoun }] },
-        [],
-        buildReservedVerbs([]),
-      );
-      const entry = entries.find((e) => e.definition.noun === bundledNoun);
-      // The config-declared story wins; the bundled one yields silently.
-      expect(entry?.source).toBe("config");
-      expect(
-        entries.filter((e) => e.definition.noun === bundledNoun),
-      ).toHaveLength(1);
-    });
-
-    it("yields a bundled noun to a still-reserved built-in", () => {
-      // If a bundled noun is still a built-in (not yet cut over), the bundled
-      // pack must not shadow it.
-      const bundledNoun = BUNDLED_PACKS[0]?.noun ?? "tier";
-      const entries = realCollectPackStories(
-        CONFIG,
-        [],
-        buildReservedVerbs([[bundledNoun, undefined]]),
-      );
-      expect(entries.map((e) => e.definition.noun)).not.toContain(bundledNoun);
-    });
-  });
-});

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

@@ -1,158 +0,0 @@
-import type { PragmaConfig } from "#config";
-import { PragmaError } from "#error";
-import type { SemanticPackage } from "../../semanticPackage.js";
-import { BUNDLED_PACKS } from "./bundled/index.js";
-import { isReserved, type ReservedVerbs } from "./reservedVerbs.js";
-import type { StoryPackDefinition } from "./types.js";
-import validateStoryPackDefinition from "./validateStoryPackDefinition.js";
-
-/** A validated story definition paired with where it was declared. */
-export interface PackStoryEntry {
-  readonly definition: StoryPackDefinition;
-  readonly source: string;
-}
-
-/**
- * The verbs a pack definition compiles to — mirrors `compilePackStories`,
- * which always emits `list`, adds any declared extra verbs, and adds
- * `lookup`/`sample` only when declared. The reserved-verb guard sees the
- * FULL emission so a pack cannot shadow any built-in verb.
- */
-function emittedVerbs(definition: StoryPackDefinition): string[] {
-  return [
-    "list",
-    ...(definition.verbs ?? []).map((verb) => verb.verb),
-    ...(definition.lookup ? ["lookup"] : []),
-    ...(definition.lookup?.sample ? ["sample"] : []),
-  ];
-}
-
-/**
- * Name the built-in `(noun, verb)` command(s) a pack collides with, for
- * actionable diagnostics — e.g. `built-in command "standard lookup"`.
- * Since the guard is per-verb, reporting the noun alone is misleading.
- */
-function describeShadow(noun: string, verbs: readonly string[]): string {
-  const pairs = verbs.map((verb) => `"${noun} ${verb}"`).join(", ");
-  return `built-in command${verbs.length > 1 ? "s" : ""} ${pairs}`;
-}
-
-/**
- * Gather the story-pack definitions active for a runtime.
- *
- * Config-declared stories come first (already validated by the config
- * parser) and win noun collisions against package-shipped ones — the
- * config is the user's override layer. Package story files are validated
- * here; an invalid or colliding package story is skipped with a warning
- * so one bad file cannot break boot. A config story colliding with a
- * reserved (built-in) noun is a hard config error. Bundled transitional
- * packs come last (lowest precedence), so config or a package can override
- * a bundled noun.
- *
- * @param config - The effective merged configuration.
- * @param packages - Resolved semantic packages (may ship `stories/*.json`).
- * @param reserved - Built-in `(noun, verb)` reservations packs must not
- *   shadow; a pack collides only when it emits a reserved verb.
- * @param bundled - Transitional packs pragma ships by default (lowest
- *   precedence). Defaults to {@link BUNDLED_PACKS}; tests pass `[]` to isolate.
- * @returns Validated, collision-free story entries.
- * @throws PragmaError with code `CONFIG_ERROR` when a config story shadows
- *   a reserved built-in verb.
- * @note Impure — warns on stderr for skipped package stories.
- */
-export default function collectPackStories(
-  config: PragmaConfig,
-  packages: readonly SemanticPackage[],
-  reserved: ReservedVerbs,
-  bundled: readonly StoryPackDefinition[] = BUNDLED_PACKS,
-): PackStoryEntry[] {
-  const entries: PackStoryEntry[] = [];
-  const taken = new Set<string>();
-
-  for (const definition of config.stories ?? []) {
-    const shadowed = emittedVerbs(definition).filter((verb) =>
-      isReserved(reserved, definition.noun, verb),
-    );
-    if (shadowed.length > 0) {
-      throw PragmaError.configError(
-        `Story noun "${definition.noun}" shadows ${describeShadow(
-          definition.noun,
-          shadowed,
-        )}.`,
-      );
-    }
-    if (taken.has(definition.noun)) {
-      throw PragmaError.configError(
-        `Duplicate story noun "${definition.noun}" in config.`,
-      );
-    }
-    taken.add(definition.noun);
-    entries.push({ definition, source: "config" });
-  }
-
-  for (const pkg of packages) {
-    for (const file of pkg.stories) {
-      let definition: StoryPackDefinition;
-      try {
-        definition = validateStoryPackDefinition(file.definition, file.path);
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        process.stderr.write(`Warning: skipping story — ${reason}\n`);
-        continue;
-      }
-      const shadowed = emittedVerbs(definition).filter((verb) =>
-        isReserved(reserved, definition.noun, verb),
-      );
-      if (shadowed.length > 0) {
-        process.stderr.write(
-          `Warning: skipping story "${definition.noun}" from ${file.path} — it shadows ${describeShadow(
-            definition.noun,
-            shadowed,
-          )}.\n`,
-        );
-        continue;
-      }
-      if (taken.has(definition.noun)) {
-        process.stderr.write(
-          `Warning: skipping story "${definition.noun}" from ${file.path} — the noun is already provided by a higher-precedence source.\n`,
-        );
-        continue;
-      }
-      taken.add(definition.noun);
-      entries.push({ definition, source: file.path });
-    }
-  }
-
-  // Bundled transitional packs — lowest precedence, so a config- or
-  // package-declared story for the same noun overrides them (the P4 handoff).
-  // Authored in-repo but still validated: only a validation failure (an
-  // authoring slip) is skipped with a warning (consistent with package
-  // stories — one bad pack cannot break boot), and the pack's own parity tests
-  // catch a bundled pack that fails to load. When a still-reserved built-in or
-  // a higher-precedence source already owns the noun, the bundled pack yields
-  // silently (no warning) — the shadow/duplicate check below, matching the
-  // precedence order rather than flagging an error.
-  for (const raw of bundled) {
-    const source = `bundled:${raw.noun}`;
-    let definition: StoryPackDefinition;
-    try {
-      definition = validateStoryPackDefinition(raw, source);
-    } catch (error) {
-      const reason = error instanceof Error ? error.message : String(error);
-      process.stderr.write(`Warning: skipping bundled story — ${reason}\n`);
-      continue;
-    }
-    const shadowed = emittedVerbs(definition).filter((verb) =>
-      isReserved(reserved, definition.noun, verb),
-    );
-    if (shadowed.length > 0 || taken.has(definition.noun)) {
-      // A still-registered built-in (not yet cut over) or a higher-precedence
-      // source already owns this noun — the bundled pack yields to it silently.
-      continue;
-    }
-    taken.add(definition.noun);
-    entries.push({ definition, source });
-  }
-
-  return entries;
-}

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

@@ -1,50 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../context.js";
-import { resolvePrefixes } from "../../prefixes.js";
-import compileLookupCommand from "../compileLookupCommand.js";
-import compileReadCommand from "../compileReadCommand.js";
-import collectPackStories from "./collectPackStories.js";
-import compilePackStories from "./compilePackStories.js";
-import type { ReservedVerbs } from "./reservedVerbs.js";
-
-/**
- * Compile every active story pack into CLI command definitions.
- *
- * Story packs come from the merged config (`stories`) and from resolved
- * semantic packages (`stories/*.json`); each yields `<noun> list` and,
- * when declared, `<noun> lookup`, extra list verbs, and `<noun> sample` —
- * projected through the same kernel as the built-in read stories, so
- * completions and help come for free.
- *
- * @param ctx - Pragma context carrying config, packages, and the store.
- * @param reserved - Built-in `(noun, verb)` reservations packs must not shadow.
- * @returns Command definitions for every pack story.
- */
-export default function compilePackCommands(
-  ctx: PragmaContext,
-  reserved: ReservedVerbs,
-): CommandDefinition[] {
-  const prefixes = resolvePrefixes(ctx.packages ?? [], ctx.config.prefixes);
-  const entries = collectPackStories(ctx.config, ctx.packages ?? [], reserved);
-
-  return entries.flatMap((entry) => {
-    const compiled = compilePackStories(
-      entry.definition,
-      entry.source,
-      prefixes,
-    );
-    // Surface order mirrors the built-in leaf domains: list, lookup,
-    // extra verbs, sample.
-    const commands = [compileReadCommand(ctx, compiled.list)];
-    if (compiled.lookup) {
-      commands.push(compileLookupCommand(ctx, compiled.lookup));
-    }
-    for (const verb of compiled.verbs) {
-      commands.push(compileReadCommand(ctx, verb));
-    }
-    if (compiled.sample) {
-      commands.push(compileReadCommand(ctx, compiled.sample));
-    }
-    return commands;
-  });
-}