@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/testing/perf/globalSetup.ts

@@ -1,24 +1,139 @@
 /**
  * Vitest global setup: build the compiled `dist/pragma` once, before the suite,
- * if it is missing.
+ * if it is missing OR older than the sources it was built from.
  *
  * Shared by both configs, because two suites spawn the binary: the perf budgets
  * (src/testing/perf/**, `test:perf`) and the storeless-guarantee guards in
  * src/kernel/completion/safety.test.ts (the main `test:vitest` pass). Wiring it
  * into both means `bun run test` on a clean checkout provisions the binary with
  * no manual build step — neither suite may assume it is pre-built.
+ *
+ * STALENESS, not mere existence. `existsSync` alone meant every spawned-binary
+ * guard ran against whatever binary happened to be on disk: a mutation to
+ * `bin.ts` making the storeless `__complete` path write to `$HOME` and boot the
+ * store — precisely what `safety.test.ts` is PROTECTED to forbid — was live
+ * when run from source and invisible through the gate. The guard whose own
+ * docblock warns that an unreachable bundle "would leave the whole suite green"
+ * was itself green against a binary that predated the change under test.
+ *
+ * STALENESS INCLUDES THE EMBEDDED WORKSPACE DEPS. The binary bundles every
+ * `@canonical/*` workspace package it (transitively) imports — task, summon-*,
+ * ke, … — so an edit to `packages/runtime/task` is a change to what
+ * `dist/pragma` runs, yet this package's own `src` never moves. The gate
+ * therefore also watches each workspace-linked dependency (found by following
+ * the `node_modules/<name>` symlinks, transitively) — its `src` (the authored
+ * source), `dist` (what the bundler actually embeds, per the dep's export map)
+ * and `package.json`. Registry deps resolve into a `node_modules` store path
+ * and are skipped: their content only changes with a lockfile change, which
+ * `bun install` surfaces as a fresh symlink mtime anyway. Content hashing of
+ * the build inputs was considered and DECLINED (PR7 ruling R5): an mtime
+ * comparison is a handful of stats, needs no state file to compare against,
+ * and the failure mode of a false "stale" is one redundant 10 s build — while
+ * hashing every input on every suite start costs more than the rebuild it
+ * avoids. CI is fresh-checkout either way; this gate exists for developer
+ * boxes that have built before.
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Everything the compiled binary is built FROM, relative to the package root. */
+const INPUTS = ["src", "scripts", "pragma.conf.ts", "package.json"];
+
+/**
+ * What feeds the binary inside one workspace dependency: its authored source,
+ * the compiled output the bundler embeds, and its manifest. Deliberately NOT
+ * the whole package dir — that would watch `coverage/` and `node_modules/`,
+ * whose mtimes move on every test run and would force a rebuild loop.
+ */
+const DEP_INPUTS = ["src", "dist", "package.json"];
+
+/**
+ * The newest modification time under `path`, or 0 when it does not exist.
+ * A nested `node_modules` is never descended into (a dep's own deps are
+ * enumerated as roots of their own by {@link workspaceDepRoots}).
+ *
+ * @param path - A file or directory.
+ * @returns Epoch milliseconds of the newest entry beneath it.
+ * @note Impure — stats the source tree.
+ */
+function newestMtime(path: string): number {
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(path);
+  } catch {
+    return 0;
+  }
+  if (!stats.isDirectory()) return stats.mtimeMs;
+  let newest = stats.mtimeMs;
+  for (const entry of readdirSync(path)) {
+    if (entry === "node_modules") continue;
+    newest = Math.max(newest, newestMtime(join(path, entry)));
+  }
+  return newest;
+}
+
+/**
+ * Every workspace package the binary can embed, transitively: follow each
+ * `node_modules/<name>` symlink whose target lives OUTSIDE any `node_modules`
+ * store (that is what distinguishes a workspace link from a registry install),
+ * then repeat from the target's own `node_modules`. Cycles are cut by the
+ * visited set.
+ *
+ * @param pkgRoot - This package's root directory.
+ * @returns Absolute real paths of the linked workspace dependency roots.
+ * @note Impure — reads `node_modules` link farms.
+ */
+function workspaceDepRoots(pkgRoot: string): string[] {
+  const visited = new Set<string>([realpathSync(pkgRoot)]);
+  const queue = [realpathSync(pkgRoot)];
+  while (queue.length > 0) {
+    const dir = queue.pop() as string;
+    const nm = join(dir, "node_modules");
+    let entries: string[];
+    try {
+      entries = readdirSync(nm);
+    } catch {
+      continue;
+    }
+    const links = entries.flatMap((entry) => {
+      if (!entry.startsWith("@")) return [join(nm, entry)];
+      try {
+        return readdirSync(join(nm, entry)).map((e) => join(nm, entry, e));
+      } catch {
+        return [];
+      }
+    });
+    for (const link of links) {
+      let real: string;
+      try {
+        if (!lstatSync(link).isSymbolicLink()) continue;
+        real = realpathSync(link);
+      } catch {
+        continue;
+      }
+      if (real.split(sep).includes("node_modules")) continue;
+      if (visited.has(real)) continue;
+      visited.add(real);
+      queue.push(real);
+    }
+  }
+  const root = realpathSync(pkgRoot);
+  return [...visited].filter((dir) => dir !== root);
+}
+
 export default function setup(): void {
   const root = fileURLToPath(new URL("../../../", import.meta.url));
-  const binary = fileURLToPath(
-    new URL("../../../dist/pragma", import.meta.url),
-  );
-  if (existsSync(binary)) return;
+  const built = newestMtime(join(root, "dist", "pragma"));
+  const fresh =
+    built > 0 &&
+    INPUTS.every((input) => newestMtime(join(root, input)) < built) &&
+    workspaceDepRoots(root).every((dep) =>
+      DEP_INPUTS.every((input) => newestMtime(join(dep, input)) < built),
+    );
+  if (fresh) return;
 
   const result = spawnSync("bun", ["run", "scripts/build.ts"], {
     cwd: root,

package/src/types.ts

@@ -12,8 +12,8 @@ export type { DetailLevel, OutputFormat } from "./constants.js";
 // — Config authoring ————————————————————————————————————————————————————————
 export type {
   Channel,
-  PackageDeclaration,
-  PackageEntry,
+  PackDeclaration,
+  PackSource,
   PragmaConfig,
 } from "./kernel/config/types.js";
 // — Error model —————————————————————————————————————————————————————————————

package/src/capabilities/block/blockList.verb.ts

@@ -1,150 +0,0 @@
-/**
- * `block list` — the ONE hand-written read (Risk5).
- *
- * A block list is config-filtered in ways packs cannot express declaratively:
- * the tier CHAIN (a tier makes its whole parent chain visible), the channel
- * (release-level visibility), and the `--all-tiers` escape. Everything else in
- * PR3 is a declarative pack; this verb ports that behaviour directly. It reads
- * the effective tier/channel from config and runs one generated SELECT (no user
- * input in the query — the tier is config, the channel a closed enum).
- */
-
-import { runSelect } from "../../kernel/packs/sparql/runSelect.js";
-import type {
-  ColumnDef,
-  RenderListOptions,
-} from "../../kernel/render/contracts.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import {
-  renderListLlm,
-  renderListPlain,
-} from "../../kernel/render/renderers.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { Formatters, VerbSpec } from "../../kernel/spec/types.js";
-import { buildChannelFilter, buildTierFilter } from "./tierChain.js";
-
-/** One block summary row. */
-export interface BlockRow {
-  readonly uri: string;
-  readonly name: string;
-  readonly type: string;
-  readonly tier: string;
-  readonly modifiers: string;
-}
-
-/** Local name of an IRI (`…/global` → `global`; `…#Thing` → `Thing`). */
-function localName(uri: string): string {
-  const hash = uri.lastIndexOf("#");
-  if (hash !== -1) return uri.slice(hash + 1);
-  const slash = uri.lastIndexOf("/");
-  return slash !== -1 ? uri.slice(slash + 1) : uri;
-}
-
-/** Normalize a block's rdf:type to one of the four block kinds. */
-function normalizeType(typeUri: string | undefined): BlockRow["type"] {
-  const local = localName(typeUri ?? "").toLowerCase();
-  return local === "pattern" || local === "layout" || local === "subcomponent"
-    ? local
-    : "component";
-}
-
-const listColumns: ColumnDef<BlockRow>[] = [
-  { key: "name", label: "Name" },
-  { key: "type", label: "Type" },
-  { key: "tier", label: "Tier" },
-  { key: "modifiers", label: "Modifiers", showWhenEmpty: false },
-  { key: "uri", label: "IRI" },
-];
-
-const listOptions: RenderListOptions<BlockRow> = {
-  heading: "Blocks",
-  columns: listColumns,
-  prefixes: DEFAULT_PREFIX_MAP,
-  // Zero blocks is a calm success (exit 0), not an error — the list is scoped by
-  // the active tier chain and channel, so the message names that scope and the
-  // hint offers the escape hatches (a cold store fails earlier with
-  // STORE_UNAVAILABLE, so reaching here means the store is built).
-  emptyMessage: "No blocks found under the current tier and channel.",
-  emptyHint:
-    "Use --all-tiers to ignore the tier filter, or run `pragma sources update` if the store is empty.",
-};
-
-const listFormatters: Formatters<BlockRow[]> = {
-  plain: (rows) => renderListPlain(rows, listOptions),
-  llm: (rows) => renderListLlm(rows, listOptions),
-  json: (rows) => JSON.stringify(rows, null, 2),
-};
-
-/** Build the config-filtered block SELECT for the resolved tier/channel. */
-function buildQuery(
-  tier: string | undefined,
-  channel: import("../../kernel/config/types.js").Channel,
-  allTiers: boolean,
-): string {
-  const tierFilter = allTiers ? "" : buildTierFilter(tier);
-  const channelFilter = buildChannelFilter(channel);
-  return [
-    "SELECT ?component ?type ?name ?tier",
-    '       (GROUP_CONCAT(DISTINCT ?modName; separator=", ") AS ?modifiers)',
-    "WHERE {",
-    "  VALUES ?type { ds:Component ds:Pattern ds:Layout ds:Subcomponent }",
-    "  ?component a ?type ;",
-    "             ds:name ?name ;",
-    "             ds:tier ?tier .",
-    tierFilter ? `  ${tierFilter}` : "",
-    `  ${channelFilter}`,
-    "  OPTIONAL { ?component ds:hasModifierFamily ?mod . ?mod ds:name ?modName }",
-    "}",
-    "GROUP BY ?component ?type ?name ?tier",
-    "ORDER BY ?name",
-  ]
-    .filter((line) => line !== "")
-    .join("\n");
-}
-
-const listVerb: VerbSpec<Record<string, unknown>, BlockRow[]> = {
-  path: ["block", "list"],
-  summary: "List blocks visible under the current tier and channel.",
-  doc: "List design system blocks visible under the active tier chain and channel. Optionally list across every tier, ignoring the tier filter.",
-  params: [
-    {
-      kind: "boolean",
-      name: "allTiers",
-      doc: "Show blocks from all tiers, ignoring the tier filter.",
-    },
-  ],
-  output: { formatters: listFormatters },
-  examples: [
-    { cmd: "pragma block list" },
-    { cmd: "pragma block list --all-tiers" },
-    { cmd: "pragma block list --llm" },
-  ],
-  capability: {
-    needsStore: true,
-    mutates: false,
-    mcp: {
-      expose: true,
-      annotations: { readOnlyHint: true, openWorldHint: false },
-    },
-  },
-  run: async (params: Record<string, unknown>, rt: PragmaRuntime) => {
-    const layers = await rt.loadConfig();
-    const query = buildQuery(
-      layers.config.tier,
-      layers.config.channel,
-      params.allTiers === true,
-    );
-    const rows = await runSelect(rt, query, "block");
-    return rows.map((row) => ({
-      uri: row.component ?? "",
-      name: row.name ?? "",
-      type: normalizeType(row.type),
-      tier: localName(row.tier ?? ""),
-      modifiers: row.modifiers ?? "",
-    }));
-  },
-};
-
-/** The hand-written `block list` verb. */
-export const blockListVerb = asVerb(listVerb);

package/src/capabilities/block/index.ts

@@ -1,25 +0,0 @@
-/**
- * The `block` capability module — a COMPOSITE: the hand-written `block list`
- * (tier chain + channel + --all-tiers) plus the bundled pack's GraphQL `lookup`.
- *
- * This is the one noun where a declarative pack and a hand-written verb share a
- * module; the pack ships lookup-only, so there is no `(noun, verb)` collision.
- */
-
-import { compilePack } from "../../kernel/packs/compile.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
-import { blockListVerb } from "./blockList.verb.js";
-import { blockPack } from "./pack.js";
-
-/** The `block` capability module (`list` hand-written, `lookup` from the pack). */
-export const blockModule: CapabilityModule = {
-  name: "block",
-  verbs: [
-    blockListVerb,
-    ...compilePack(blockPack, "bundled:block", DEFAULT_PREFIX_MAP),
-  ],
-  // The bundled design-system domain colophon (authored on the flagship UI-block
-  // noun), surfaced by `pragma colophon` after pragma's own.
-  colophon: blockPack.colophon,
-};

package/src/capabilities/block/pack.ts

@@ -1,155 +0,0 @@
-/**
- * The bundled `block` pack — the lookup verb only.
- *
- * `block lookup` is served over the GraphQL fetch path (ONE generated document
- * over the `UIBlock` interface covering Component/Pattern/Layout/Subcomponent);
- * `block list` deliberately stays HAND-WRITTEN (tier-chain inheritance + channel
- * + `--all-tiers` — see ./blockList.verb). Base level mirrors the old summary
- * view (name/tier/summary); the default is `detailed`, matching the old CLI
- * which rendered anatomy and modifiers without a flag. A derived name that maps
- * onto no schema field is omitted (OPTIONAL parity), so a graph lacking
- * whenToUse/whenNotToUse degrades gracefully.
- */
-
-import type { PackDefinition } from "../../kernel/packs/types.js";
-
-/**
- * The bundled design-system domain colophon — the ontology + graph story,
- * surfaced by `pragma colophon` after pragma's own. Authored on the flagship
- * UI-block noun because `block` most embodies the design system; it narrates the
- * DOMAIN (what the graph models), not the toolchain (pragma's built-in section).
- */
-const DESIGN_SYSTEM_COLOPHON = `The Canonical design system is a **knowledge graph**, not a component library.
-Every block, token, modifier, standard, and tier is a node in an RDF store,
-described by the \`ds:\` ontology and queried the same way whether you reach it
-over GraphQL or raw SPARQL.
-
-## What the graph models
-
-- **Blocks** — components, patterns, layouts, and subcomponents (the \`ds:UIBlock\`
-  family). A block carries its anatomy, guidelines, and \`when to use\` / \`when
-  not to use\` narrative as graph properties, not prose in a wiki.
-- **Modifiers** — families of variant values (\`ds:hasModifierFamily\` →
-  \`ds:hasModifier\`) a block composes, so a variant is a relationship, not a
-  string.
-- **Tokens** — the themeable design values, resolved per theme.
-- **Standards** — the do / don't coding guidance, categorized and linked to the
-  blocks they govern.
-
-## How it fits together
-
-- **Tiers** are a hierarchy (\`global\` > \`apps\` > \`apps/lxd\`): a lower tier
-  inherits and overrides the blocks of its ancestors, so scoping a query to a
-  tier walks that chain.
-- **Channels** (\`normal\`, \`experimental\`, \`prerelease\`) gate visibility, so an
-  in-progress block never leaks into a stable answer.
-
-## Why RDF
-
-One graph makes every relationship first-class and queryable: \`block lookup\`
-follows edges to modifiers and subcomponents, \`graph query\` runs arbitrary
-SPARQL, and \`ontology show\` reads the schema itself. The store is built once
-by \`sources update\` and addressed by content hash, so the domain you query is
-exactly the domain that was published.`;
-
-export const blockPack: PackDefinition = {
-  noun: "block",
-  description: "Look up design system blocks.",
-  colophon: DESIGN_SYSTEM_COLOPHON,
-  lookup: {
-    source: "graphql",
-    toolDescription:
-      'Get detailed information about one or more design system blocks including anatomy, modifiers, and properties. Use when you need the full spec of specific blocks by name — detail: "summary" trims to the base view. Example: block_lookup { names: ["Button"] }.',
-    by: "ds:name",
-    types: ["ds:Component", "ds:Pattern", "ds:Layout", "ds:Subcomponent"],
-    graphqlType: "UIBlock",
-    fields: [
-      { name: "tier", property: "ds:tier", label: "Tier" },
-      {
-        name: "figmaLink",
-        property: "ds:figmaLink",
-        label: "Figma",
-        level: "detailed",
-      },
-    ],
-    sections: [
-      { name: "summary", property: "ds:summary", label: "Summary" },
-      {
-        name: "whenToUse",
-        property: "ds:whenToUse",
-        label: "When to use",
-        level: "detailed",
-      },
-      {
-        name: "whenNotToUse",
-        property: "ds:whenNotToUse",
-        label: "When not to use",
-        level: "detailed",
-      },
-      {
-        name: "guidelines",
-        property: "ds:guidelines",
-        label: "Guidelines",
-        level: "detailed",
-      },
-      {
-        name: "anatomyDsl",
-        property: "ds:anatomyDsl",
-        label: "Anatomy (DSL)",
-        kind: "code",
-        level: "detailed",
-      },
-      {
-        name: "anatomyClassic",
-        property: "ds:anatomyClassic",
-        label: "Anatomy (classic)",
-        kind: "code",
-        level: "detailed",
-      },
-    ],
-    expand: [
-      {
-        name: "modifierFamilies",
-        heading: "Modifier Families",
-        relation: "ds:hasModifierFamily",
-        level: "detailed",
-        select: [
-          { name: "name", property: "ds:name" },
-          {
-            name: "values",
-            relation: "ds:hasModifier",
-            select: [{ name: "name", property: "ds:name" }],
-          },
-        ],
-      },
-      {
-        name: "properties",
-        heading: "Properties",
-        relation: "ds:hasProperty",
-        kind: "table",
-        level: "detailed",
-        select: [
-          { name: "name", property: "ds:name" },
-          { name: "type", property: "ds:propertyType" },
-          { name: "optional", property: "ds:optional" },
-        ],
-      },
-      {
-        name: "subcomponents",
-        heading: "Subcomponents",
-        relation: "ds:hasSubcomponent",
-        level: "detailed",
-        select: [
-          { name: "name", property: "ds:name" },
-          { name: "uri", property: "ds:name", graphqlField: "uri" },
-        ],
-      },
-    ],
-    disclosure: { levels: ["summary", "detailed"], default: "detailed" },
-    sample: {
-      fixedCount: true,
-      toolDescription:
-        "Return randomly selected complete design-system blocks as exemplars. Use BEFORE writing queries to see actual data shapes, anatomy, and property names.",
-    },
-  },
-};

package/src/capabilities/block/parity.test.ts

@@ -1,180 +0,0 @@
-/**
- * Block content-parity (PROTECTED) — on a FIXTURE graph, not the live one.
- *
- * The hand-written block lookup is gone; parity is asserted against the fixture
- * graph directly: Button and Modal resolve through the GraphQL `block lookup`
- * with the same content a direct SPARQL oracle returns (summary, guidance,
- * anatomy, tier, modifier families with values, properties, subcomponents). The
- * fixture DECLARES whenToUse/whenNotToUse (which the live graph superseded with
- * ds:usage), so those sections are exercised here. The hand-written `block list`
- * is checked for its tier/channel filtering and --all-tiers.
- */
-
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import type { LookupOutput } from "../../kernel/packs/resolveEntity.js";
-import { verbKey } from "../../kernel/packs/uniqueness.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
-import {
-  BLOCK_PREFIXES,
-  BLOCK_TTL,
-} from "../../testing/fixtures/blockGraph.js";
-import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
-import type { BlockRow } from "./blockList.verb.js";
-import { blockModule } from "./index.js";
-
-const DS = "https://ds.canonical.com/";
-
-const listVerb = blockModule.verbs.find(
-  (v) => verbKey(v.path) === "block list",
-) as VerbSpec;
-const lookupVerb = blockModule.verbs.find(
-  (v) => verbKey(v.path) === "block lookup",
-) as VerbSpec;
-
-let rt: PragmaRuntime;
-
-beforeAll(async () => {
-  ({ rt } = await buildFixtureRuntime({
-    ttl: BLOCK_TTL,
-    prefixes: BLOCK_PREFIXES,
-    detail: "detailed",
-  }));
-});
-
-afterAll(async () => {
-  (await rt.store.get()).store.dispose();
-});
-
-async function lookup(name: string): Promise<Record<string, unknown>> {
-  const out = (await lookupVerb.run({ name: [name] }, rt)) as LookupOutput;
-  expect(out.errors).toEqual([]);
-  return out.results.at(0) as Record<string, unknown>;
-}
-
-/** Oracle: a single scalar from the graph, queried directly. */
-async function oracle(subject: string, predicate: string): Promise<string> {
-  const result = await rt.query.sparql(
-    `SELECT ?v WHERE { <${subject}> ${predicate} ?v }`,
-  );
-  return result.type === "select" ? (result.bindings[0]?.v ?? "") : "";
-}
-
-describe("block lookup — Button content parity (GraphQL, detailed)", () => {
-  it("resolves the full Button spec with content matching the SPARQL oracle", async () => {
-    const button = await lookup("Button");
-    expect(button.uri).toBe(`${DS}button`);
-    expect(button.name).toBe("Button");
-    expect(button.tier).toBe(`${DS}global`);
-
-    // Guidance + anatomy sections — each cross-checked against the graph.
-    expect(button.summary).toBe(await oracle(`${DS}button`, "ds:summary"));
-    expect(button.whenToUse).toBe(await oracle(`${DS}button`, "ds:whenToUse"));
-    expect(button.whenNotToUse).toBe(
-      await oracle(`${DS}button`, "ds:whenNotToUse"),
-    );
-    expect(button.guidelines).toBe(
-      await oracle(`${DS}button`, "ds:guidelines"),
-    );
-    expect(button.anatomyDsl).toBe(
-      await oracle(`${DS}button`, "ds:anatomyDsl"),
-    );
-    expect(button.figmaLink).toBe(await oracle(`${DS}button`, "ds:figmaLink"));
-  });
-
-  it("resolves the nested modifier families with values (inverse union)", async () => {
-    const button = await lookup("Button");
-    const families = button.modifierFamilies as {
-      name: string;
-      values?: string[];
-    }[];
-    expect(families.map((f) => f.name).sort()).toEqual([
-      "density",
-      "importance",
-    ]);
-    const importance = families.find((f) => f.name === "importance");
-    expect(importance?.values?.sort()).toEqual(["primary", "secondary"]);
-  });
-
-  it("resolves properties and the subtype-scoped subcomponents identity field", async () => {
-    const button = await lookup("Button");
-    expect(button.properties).toEqual([
-      { name: "disabled", type: "boolean", optional: "true" },
-    ]);
-    expect(button.subcomponents).toEqual([
-      { name: "Button Icon", uri: `${DS}button.icon` },
-    ]);
-  });
-
-  it("renders every declared section in the llm output", async () => {
-    const out = (await lookupVerb.run(
-      { name: ["Button"] },
-      rt,
-    )) as LookupOutput;
-    const llm = lookupVerb.output.formatters.llm(out);
-    expect(llm).toContain("## Button");
-    expect(llm).toContain("### When to use");
-    expect(llm).toContain("### Anatomy (DSL)");
-    expect(llm).toContain("### Modifier Families");
-    expect(llm).toContain("primary");
-  });
-});
-
-describe("block lookup — Modal content parity (GraphQL, detailed)", () => {
-  it("resolves the full Modal spec (a different block, same document engine)", async () => {
-    const modal = await lookup("Modal");
-    expect(modal.uri).toBe(`${DS}modal`);
-    expect(modal.name).toBe("Modal");
-    expect(modal.summary).toBe(await oracle(`${DS}modal`, "ds:summary"));
-    expect(modal.whenToUse).toBe(await oracle(`${DS}modal`, "ds:whenToUse"));
-    const families = modal.modifierFamilies as {
-      name: string;
-      values?: string[];
-    }[];
-    expect(families.map((f) => f.name)).toEqual(["size"]);
-    expect(families[0]?.values?.sort()).toEqual(["large", "small"]);
-    expect(modal.properties).toEqual([
-      { name: "open", type: "boolean", optional: "false" },
-    ]);
-    // Modal has no subcomponents — the subtype-scoped selection is simply absent.
-    expect(modal.subcomponents).toEqual([]);
-  });
-});
-
-describe("block lookup — disclosure trims to the base view at summary", () => {
-  it("summary keeps name/tier/summary and drops the detailed sections/expands", async () => {
-    const out = (await lookupVerb.run(
-      { name: ["Button"] },
-      { ...rt, globalFlags: { ...rt.globalFlags, detail: "summary" } },
-    )) as LookupOutput;
-    const button = out.results.at(0) as Record<string, unknown>;
-    expect(button.name).toBe("Button");
-    expect(button.summary).toBeDefined();
-    expect(button.whenToUse).toBeUndefined();
-    expect(button.anatomyDsl).toBeUndefined();
-    expect(button.modifierFamilies).toBeUndefined();
-    expect(button.figmaLink).toBeUndefined();
-  });
-});
-
-describe("block list — hand-written tier/channel filtering", () => {
-  it("lists visible blocks with the summary row shape", async () => {
-    const rows = (await listVerb.run({}, rt)) as BlockRow[];
-    const byName = new Map(rows.map((r) => [r.name, r]));
-    expect([...byName.keys()].sort()).toEqual(["Button", "Modal"]);
-    const button = byName.get("Button");
-    expect(button?.type).toBe("component");
-    expect(button?.tier).toBe("global");
-    expect(button?.uri).toBe(`${DS}button`);
-    // GROUP_CONCAT of the family names (order-independent).
-    expect(button?.modifiers.split(", ").sort()).toEqual([
-      "density",
-      "importance",
-    ]);
-  });
-
-  it("--all-tiers returns the same global blocks (no tier configured)", async () => {
-    const rows = (await listVerb.run({ allTiers: true }, rt)) as BlockRow[];
-    expect(rows.map((r) => r.name).sort()).toEqual(["Button", "Modal"]);
-  });
-});