@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,318 +0,0 @@
-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/index.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).toContain("### Anatomy (DSL)");
-    expect(text).not.toContain("### Anatomy\n");
-  });
-});
-
-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();
-  });
-});

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

@@ -1,149 +0,0 @@
-import type { RenderLookupOptions } from "../../shared/contracts.js";
-import type { Formatters } from "../../shared/formatters.js";
-import { renderLookupLlm, renderLookupPlain } from "../../shared/renderers.js";
-import type { BlockDetailed } from "../../shared/types/index.js";
-import { blockConfig } from "../blockConfig.js";
-import type { AspectFlags } from "../types.js";
-import type { BlockLookupInput } from "./types.js";
-
-/** Three-mode formatter for `pragma block lookup` output. */
-const formatters: Formatters<BlockLookupInput> = {
-  plain: ({ block, detailed, aspects }) =>
-    renderLookupPlain(block, createLookupOptions(detailed, aspects)),
-
-  llm: ({ block, detailed, aspects }) =>
-    renderLookupLlm(block, createLookupOptions(detailed, aspects)),
-
-  json({ block: component, detailed, aspects }) {
-    if (!detailed) {
-      return JSON.stringify(
-        {
-          uri: component.uri,
-          name: component.name,
-          summary: component.summary,
-          tier: component.tier,
-          modifiers: component.modifiers,
-          implementations: component.implementations,
-          nodeCount: component.nodeCount,
-          tokenCount: component.tokenCount,
-        },
-        null,
-        2,
-      );
-    }
-
-    const result: Record<string, unknown> = { ...component };
-
-    if (!aspects.modifiers) {
-      delete result.modifierValues;
-      delete result.modifierFamilies;
-    }
-    if (!aspects.implementations) {
-      delete result.implementationPaths;
-    }
-    if (!aspects.tokens) {
-      delete result.tokens;
-    }
-    if (!aspects.anatomy) {
-      delete result.anatomy;
-      delete result.anatomyDsl;
-      delete result.anatomyClassic;
-    }
-
-    return JSON.stringify(result, null, 2);
-  },
-};
-
-export default formatters;
-
-export function createLookupOptions(
-  detailed: boolean,
-  aspects: AspectFlags,
-): RenderLookupOptions<BlockDetailed> {
-  return {
-    title: (block) => block.name,
-    fields: [
-      { label: "IRI", value: (block) => block.uri },
-      { label: "Type", value: (block) => block.type },
-      { label: "Tier", value: (block) => block.tier },
-      ...(detailed
-        ? []
-        : ([
-            {
-              label: "Summary",
-              value: (block: BlockDetailed) => block.summary,
-            },
-          ] as const)),
-      { label: "Modifiers", value: (block) => block.modifiers },
-      {
-        label: "Implementations",
-        value: (block) =>
-          block.implementations
-            .filter((implementation) => implementation.available)
-            .map((implementation) => implementation.framework),
-      },
-      { label: "Anatomy nodes", value: (block) => block.nodeCount || null },
-      { label: "Tokens", value: (block) => block.tokenCount || null },
-    ],
-    sections: selectLookupSections(detailed, aspects),
-    sectionOverrides: {
-      modifierFamilies: {
-        plain: (block) =>
-          block.modifierValues.length > 0
-            ? block.modifierValues
-                .map(
-                  (modifier) =>
-                    `  ${modifier.family}: ${modifier.values.join(", ")}`,
-                )
-                .join("\n")
-            : null,
-        llm: (block) =>
-          block.modifierValues.length > 0
-            ? block.modifierValues
-                .map(
-                  (modifier) =>
-                    `- **${modifier.family}**: ${modifier.values.join(", ")}`,
-                )
-                .join("\n")
-            : null,
-      },
-    },
-    codeLanguage: (_section, value) =>
-      typeof value === "string" && value.includes("@prefix") ? "ttl" : "yaml",
-  };
-}
-
-function selectLookupSections(
-  detailed: boolean,
-  aspects: AspectFlags,
-): typeof blockConfig.lookupSections {
-  const sections = detailed
-    ? blockConfig.lookupSections
-    : blockConfig.lookupSections.filter(
-        (section) =>
-          section.key === "subcomponents" || section.key === "anatomyDsl",
-      );
-
-  return sections.filter((section) => {
-    if (
-      !aspects.anatomy &&
-      ["anatomy", "anatomyClassic"].includes(section.key)
-    ) {
-      return false;
-    }
-
-    if (!aspects.modifiers && section.key === "modifierFamilies") {
-      return false;
-    }
-
-    if (!aspects.implementations && section.key === "implementationPaths") {
-      return false;
-    }
-
-    if (!aspects.tokens && section.key === "tokens") {
-      return false;
-    }
-
-    return true;
-  });
-}

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

@@ -1,21 +0,0 @@
-/**
- * Sample formatter for the block domain.
- *
- * Delegates to the shared factory, rendering each item via the
- * existing block lookup formatter with all aspects enabled.
- */
-
-import createSampleFormatters from "../../shared/sampleFormatters.js";
-import type { BlockDetailed } from "../../shared/types/index.js";
-import lookupFormatters from "./lookup.js";
-
-const ALL_ASPECTS = {
-  anatomy: true,
-  modifiers: true,
-  tokens: true,
-  implementations: true,
-} as const;
-
-export default createSampleFormatters<BlockDetailed>("blocks", (block, mode) =>
-  lookupFormatters[mode]({ block, detailed: true, aspects: ALL_ASPECTS }),
-);

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

@@ -1,16 +0,0 @@
-/**
- * Formatter input types for block commands.
- *
- * Composite types that bundle the data with display options,
- * so formatters conform to the `Formatters<T>` contract.
- */
-
-import type { BlockDetailed } from "../../shared/types/index.js";
-import type { AspectFlags } from "../types.js";
-
-/** Input payload for the block-lookup formatter, pairing data with display flags. */
-export interface BlockLookupInput {
-  readonly block: BlockDetailed;
-  readonly detailed: boolean;
-  readonly aspects: AspectFlags;
-}

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

@@ -1,4 +0,0 @@
-/** @module Re-exports block helpers (`extractLocalName`, `resolveAspects`). */
-
-export { default as extractLocalName } from "../../shared/extractLocalName.js";
-export { default as resolveAspects } from "./resolveAspects.js";

package/src/domains/block/helpers/resolveAspects.test.ts

@@ -1,64 +0,0 @@
-import { describe, expect, it } from "vitest";
-import resolveAspects from "./resolveAspects.js";
-
-describe("resolveAspects", () => {
-  it("returns all aspects when none are set", () => {
-    const result = resolveAspects({});
-    expect(result).toEqual({
-      anatomy: true,
-      modifiers: true,
-      tokens: true,
-      implementations: true,
-    });
-  });
-
-  it("returns all aspects when all are explicitly false", () => {
-    const result = resolveAspects({
-      anatomy: false,
-      modifiers: false,
-      tokens: false,
-      implementations: false,
-    });
-    expect(result).toEqual({
-      anatomy: true,
-      modifiers: true,
-      tokens: true,
-      implementations: true,
-    });
-  });
-
-  it("returns only selected aspects when one is set", () => {
-    const result = resolveAspects({ modifiers: true });
-    expect(result).toEqual({
-      anatomy: false,
-      modifiers: true,
-      tokens: false,
-      implementations: false,
-    });
-  });
-
-  it("returns multiple selected aspects", () => {
-    const result = resolveAspects({ modifiers: true, tokens: true });
-    expect(result).toEqual({
-      anatomy: false,
-      modifiers: true,
-      tokens: true,
-      implementations: false,
-    });
-  });
-
-  it("returns all selected when all are true", () => {
-    const result = resolveAspects({
-      anatomy: true,
-      modifiers: true,
-      tokens: true,
-      implementations: true,
-    });
-    expect(result).toEqual({
-      anatomy: true,
-      modifiers: true,
-      tokens: true,
-      implementations: true,
-    });
-  });
-});

package/src/domains/block/helpers/resolveAspects.ts

@@ -1,35 +0,0 @@
-/**
- * Resolves partial aspect flags into a complete {@link AspectFlags} object.
- *
- * When no individual aspect is selected, all aspects default to `true` so
- * the full detail view is shown. When at least one aspect is explicitly
- * selected, only the selected aspects are enabled.
- *
- * @param flags - partial aspect selection from CLI flags
- * @returns fully resolved aspect flags
- */
-
-import type { AspectFlags } from "../types.js";
-
-const ALL_ASPECTS: AspectFlags = {
-  anatomy: true,
-  modifiers: true,
-  tokens: true,
-  implementations: true,
-};
-
-export default function resolveAspects(
-  flags: Partial<AspectFlags>,
-): AspectFlags {
-  const anySet =
-    flags.anatomy || flags.modifiers || flags.tokens || flags.implementations;
-
-  if (!anySet) return ALL_ASPECTS;
-
-  return {
-    anatomy: flags.anatomy ?? false,
-    modifiers: flags.modifiers ?? false,
-    tokens: flags.tokens ?? false,
-    implementations: flags.implementations ?? false,
-  };
-}

package/src/domains/block/index.ts

@@ -1,25 +0,0 @@
-/**
- * @module Block domain — CLI commands and operations.
- *
- * Commands: `pragma block list`, `pragma block lookup <name>`.
- * Operations: {@link lookupBlock}, {@link listBlocks}.
- */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../shared/context.js";
-import { listCommand, lookupCommand, sampleCommand } from "./commands/index.js";
-
-export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [listCommand(ctx), lookupCommand(ctx), sampleCommand(ctx)];
-}
-
-export { blockConfig } from "./blockConfig.js";
-export { specs as mcpSpecs } from "./mcp/index.js";
-export { listBlocks, lookupBlock, sampleBlocks } from "./operations/index.js";
-export {
-  blockEmptyError,
-  buildBlockFilters,
-  enrichBlocks,
-  resolveBlockList,
-  resolveBlockLookup,
-} from "./orchestration/index.js";

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

@@ -1,2 +0,0 @@
-/** @module Block domain MCP barrel — block_list, block_lookup. */
-export { default as specs } from "./specs.js";