@canonical/pragma-cli 0.18.0

package/src/domains/block/formatters/index.ts

@@ -0,0 +1,4 @@
+/** @module Re-exports block formatters (`lookupFormatters`, `listFormatters`). */
+
+export { default as listFormatters } from "./list.js";
+export { default as lookupFormatters } from "./lookup.js";

package/src/domains/block/formatters/list.test.ts

@@ -0,0 +1,107 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import type { BlockSummary } from "../../shared/types.js";
+import formatters from "./list.js";
+
+const BUTTON: BlockSummary = {
+  uri: `${PREFIX_MAP.ds}button` as URI,
+  name: "Button",
+  tier: "global",
+  modifiers: ["importance", "density"],
+  implementations: [
+    { framework: "react", available: true },
+    { framework: "svelte", available: false },
+  ],
+  nodeCount: 3,
+  tokenCount: 1,
+};
+
+const CARD: BlockSummary = {
+  uri: `${PREFIX_MAP.ds}card` as URI,
+  name: "Card",
+  tier: "global",
+  modifiers: [],
+  implementations: [],
+  nodeCount: 0,
+  tokenCount: 0,
+};
+
+const components = [BUTTON, CARD];
+
+describe("formatters.plain", () => {
+  it("includes block names", () => {
+    const text = formatters.plain(components);
+    expect(text).toContain("Button");
+    expect(text).toContain("Card");
+  });
+
+  it("includes tier info", () => {
+    const text = formatters.plain(components);
+    expect(text).toContain("global");
+  });
+
+  it("includes modifiers for Button", () => {
+    const text = formatters.plain(components);
+    expect(text).toContain("importance");
+    expect(text).toContain("density");
+  });
+
+  it("includes available implementations", () => {
+    const text = formatters.plain(components);
+    expect(text).toContain("react");
+    // svelte is not available
+    expect(text).not.toContain("svelte");
+  });
+
+  it("returns empty string for empty list", () => {
+    expect(formatters.plain([])).toBe("");
+  });
+});
+
+describe("formatters.llm", () => {
+  it("starts with heading", () => {
+    const text = formatters.llm(components);
+    expect(text).toContain("## Blocks");
+  });
+
+  it("bolds block names", () => {
+    const text = formatters.llm(components);
+    expect(text).toContain("**Button**");
+    expect(text).toContain("**Card**");
+  });
+
+  it("includes tier and modifier info", () => {
+    const text = formatters.llm(components);
+    expect(text).toContain("tier: global");
+    expect(text).toContain("modifiers: importance, density");
+  });
+
+  it("includes node and token counts when non-zero", () => {
+    const text = formatters.llm(components);
+    expect(text).toContain("nodes: 3");
+    expect(text).toContain("tokens: 1");
+  });
+});
+
+describe("formatters.json", () => {
+  it("returns valid JSON array", () => {
+    const text = formatters.json(components);
+    const parsed = JSON.parse(text);
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed).toHaveLength(2);
+  });
+
+  it("preserves block structure", () => {
+    const text = formatters.json(components);
+    const parsed = JSON.parse(text);
+    expect(parsed[0].name).toBe("Button");
+    expect(parsed[0].tier).toBe("global");
+    expect(parsed[0].modifiers).toEqual(["importance", "density"]);
+  });
+
+  it("returns empty array for empty list", () => {
+    const text = formatters.json([]);
+    expect(JSON.parse(text)).toEqual([]);
+  });
+});

package/src/domains/block/formatters/list.ts

@@ -0,0 +1,64 @@
+/**
+ * Three-mode formatter for `pragma block list` output.
+ *
+ * - **plain** — styled terminal output with chalk; one line per block
+ *   showing name, tier, modifiers, and available implementations.
+ * - **llm** — condensed Markdown consumed by LLM agents and reused
+ *   by the MCP adapter when `condensed: true`.
+ * - **json** — structured JSON array for programmatic consumption.
+ */
+
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { BlockSummary } from "../../shared/types.js";
+
+const formatters: Formatters<readonly BlockSummary[]> = {
+  plain(components) {
+    const lines: string[] = [];
+
+    for (const c of components) {
+      const tier = chalk.dim(`[${c.tier}]`);
+      const mods =
+        c.modifiers.length > 0 ? chalk.dim(` (${c.modifiers.join(", ")})`) : "";
+      const impl = c.implementations
+        .filter((i) => i.available)
+        .map((i) => i.framework);
+      const implStr = impl.length > 0 ? chalk.dim(` → ${impl.join(", ")}`) : "";
+
+      lines.push(`${chalk.bold(c.name)} ${tier}${mods}${implStr}`);
+    }
+
+    return lines.join("\n");
+  },
+
+  llm(components) {
+    const lines: string[] = [];
+
+    lines.push("## Blocks");
+    lines.push("");
+
+    for (const c of components) {
+      const parts = [`**${c.name}**`, `tier: ${c.tier}`];
+      if (c.modifiers.length > 0) {
+        parts.push(`modifiers: ${c.modifiers.join(", ")}`);
+      }
+      const impl = c.implementations
+        .filter((i) => i.available)
+        .map((i) => i.framework);
+      if (impl.length > 0) {
+        parts.push(`implementations: ${impl.join(", ")}`);
+      }
+      if (c.nodeCount > 0) parts.push(`nodes: ${c.nodeCount}`);
+      if (c.tokenCount > 0) parts.push(`tokens: ${c.tokenCount}`);
+      lines.push(`- ${parts.join(" | ")}`);
+    }
+
+    return lines.join("\n");
+  },
+
+  json(components) {
+    return JSON.stringify(components, null, 2);
+  },
+};
+
+export default formatters;

package/src/domains/block/formatters/lookup.test.ts

@@ -0,0 +1,317 @@
+import type { URI } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import { PREFIX_MAP } from "../../shared/prefixes.js";
+import type { BlockDetailed } from "../../shared/types.js";
+import type { AspectFlags } from "../types.js";
+import formatters from "./lookup.js";
+
+const BUTTON_DETAILED: BlockDetailed = {
+  uri: `${PREFIX_MAP.ds}global.component.button` as URI,
+  name: "Button",
+  type: "component",
+  tier: "global",
+  modifiers: ["importance", "density"],
+  summary: "Primary action trigger with optional icon and label.",
+  implementations: [
+    { framework: "react", available: true },
+    { framework: "svelte", available: false },
+  ],
+  nodeCount: 3,
+  tokenCount: 1,
+  whenToUse: "Use for high-priority actions in forms and flows.",
+  whenNotToUse: "Avoid for low-emphasis tertiary actions.",
+  guidelines: "Keep labels concise and pair icons with text when possible.",
+  anatomyDsl: "root: button; children: label, icon",
+  anatomyClassic: "button > label + icon",
+  figmaLink: "https://figma.com/design/example/Button",
+  anatomy: {
+    root: {
+      name: "button",
+      type: "named",
+      children: [
+        { name: "label", type: "named", children: [] },
+        { name: "icon", type: "anonymous", children: [], slot: "start" },
+      ],
+    },
+  },
+  modifierValues: [
+    { family: "importance", values: ["default", "primary", "secondary"] },
+    { family: "density", values: ["default", "compact"] },
+  ],
+  modifierFamilies: [
+    {
+      uri: `${PREFIX_MAP.ds}modifier_family.importance` as URI,
+      name: "importance",
+      values: ["default", "primary", "secondary"],
+    },
+  ],
+  properties: [
+    {
+      name: "disabled",
+      propertyType: "boolean",
+      optional: true,
+      defaultValue: "false",
+      constraints: "Disables click and keyboard activation.",
+    },
+  ],
+  subcomponents: [
+    {
+      uri: `${PREFIX_MAP.ds}global.subcomponent.button.icon` as URI,
+      name: "Button Icon",
+    },
+  ],
+  implementationPaths: [
+    { framework: "react", path: "src/lib/Button/Button.tsx" },
+  ],
+  tokens: [
+    {
+      uri: `${PREFIX_MAP.ds}token.color.primary` as URI,
+      name: "color.primary",
+    },
+  ],
+  standards: [],
+};
+
+const ALL_ASPECTS: AspectFlags = {
+  anatomy: true,
+  modifiers: true,
+  tokens: true,
+  implementations: true,
+};
+
+describe("formatters.plain (summary)", () => {
+  it("includes block name and tier", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("Button");
+    expect(text).toContain("global");
+  });
+
+  it("includes summary when present", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain(
+      "Primary action trigger with optional icon and label.",
+    );
+  });
+
+  it("includes modifier names", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("importance, density");
+  });
+
+  it("includes available implementations", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("react");
+  });
+
+  it("includes node and token counts", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("3");
+    expect(text).toContain("1");
+  });
+});
+
+describe("formatters.plain (detailed)", () => {
+  it("includes summary counts in detailed view", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("3");
+    expect(text).toContain("1");
+  });
+
+  it("shows modifiers section with values", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("Modifiers");
+    expect(text).toContain("importance");
+    expect(text).toContain("primary");
+    expect(text).toContain("secondary");
+  });
+
+  it("shows implementations section", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("Implementations");
+    expect(text).toContain("react");
+    expect(text).toContain("Button.tsx");
+  });
+
+  it("shows tokens section", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("Tokens");
+    expect(text).toContain("color.primary");
+  });
+
+  it("shows anatomy section", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("Anatomy");
+    expect(text).toContain("button");
+    expect(text).toContain("label");
+    expect(text).toContain("icon");
+  });
+
+  it("shows guidance, properties, and subcomponents", () => {
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("When to use");
+    expect(text).toContain("Guidelines");
+    expect(text).toContain("Properties");
+    expect(text).toContain("disabled");
+    expect(text).toContain("Subcomponents");
+    expect(text).toContain("Button Icon");
+  });
+
+  it("respects aspect filter — modifiers only", () => {
+    const aspects: AspectFlags = {
+      anatomy: false,
+      modifiers: true,
+      tokens: false,
+      implementations: false,
+    };
+    const text = formatters.plain({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects,
+    });
+    expect(text).toContain("Modifiers");
+    // Summary field "Tokens: 1" is always shown, but the Tokens section should not appear
+    expect(text).not.toContain("color.primary");
+    expect(text).not.toContain("Anatomy\n");
+    expect(text).not.toContain("Button.tsx");
+  });
+});
+
+describe("formatters.llm", () => {
+  it("formats summary as markdown", () => {
+    const text = formatters.llm({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("## Button");
+    expect(text).toContain("- Tier: global");
+    expect(text).toContain(
+      "- Summary: Primary action trigger with optional icon and label.",
+    );
+    expect(text).not.toContain("### Modifiers");
+  });
+
+  it("formats detailed with all sections", () => {
+    const text = formatters.llm({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    expect(text).toContain("### Modifiers");
+    expect(text).toContain("### Implementations");
+    expect(text).toContain("### Tokens");
+    expect(text).toContain("### Anatomy");
+    expect(text).toContain("### Properties");
+    expect(text).toContain("### Subcomponents");
+  });
+
+  it("formats detailed with aspect filter", () => {
+    const aspects: AspectFlags = {
+      anatomy: false,
+      modifiers: true,
+      tokens: true,
+      implementations: false,
+    };
+    const text = formatters.llm({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects,
+    });
+    expect(text).toContain("### Modifiers");
+    expect(text).toContain("### Tokens");
+    expect(text).not.toContain("### Anatomy");
+  });
+});
+
+describe("formatters.json", () => {
+  it("returns valid JSON for summary", () => {
+    const text = formatters.json({
+      block: BUTTON_DETAILED,
+      detailed: false,
+      aspects: ALL_ASPECTS,
+    });
+    const parsed = JSON.parse(text);
+    expect(parsed.name).toBe("Button");
+    expect(parsed.tier).toBe("global");
+    expect(parsed.modifierValues).toBeUndefined();
+  });
+
+  it("returns valid JSON for detailed with all aspects", () => {
+    const text = formatters.json({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects: ALL_ASPECTS,
+    });
+    const parsed = JSON.parse(text);
+    expect(parsed.name).toBe("Button");
+    expect(parsed.nodeCount).toBe(3);
+    expect(parsed.tokenCount).toBe(1);
+    expect(parsed.modifiers).toBeDefined();
+    expect(parsed.implementations).toBeDefined();
+    expect(parsed.modifierValues).toBeDefined();
+    expect(parsed.tokens).toBeDefined();
+    expect(parsed.anatomy).toBeDefined();
+  });
+
+  it("returns JSON with filtered aspects", () => {
+    const aspects: AspectFlags = {
+      anatomy: false,
+      modifiers: true,
+      tokens: false,
+      implementations: false,
+    };
+    const text = formatters.json({
+      block: BUTTON_DETAILED,
+      detailed: true,
+      aspects,
+    });
+    const parsed = JSON.parse(text);
+    expect(parsed.modifierValues).toBeDefined();
+    expect(parsed.tokens).toBeUndefined();
+    expect(parsed.anatomy).toBeUndefined();
+  });
+});