@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,95 +0,0 @@
-import type { URI } from "@canonical/ke";
-import { describe, expect, it } from "vitest";
-import type { StandardDetailed } from "../../shared/types/index.js";
-import formatters from "./lookup.js";
-
-const DETAILED: StandardDetailed = {
-  uri: "http://example.com/s1" as URI,
-  name: "react/component/folder-structure",
-  category: "react",
-  description: "Components must follow the standard folder layout",
-  dos: [
-    { language: "typescript", code: "Place files in src/lib/" },
-    { language: "typescript", code: "Include index.ts barrel" },
-  ],
-  donts: [{ language: "typescript", code: "Use flat directory" }],
-};
-
-describe("formatters.plain", () => {
-  it("renders summary without dos/donts by default", () => {
-    const text = formatters.plain({ standard: DETAILED, detailed: false });
-    expect(text).toContain("react/component/folder-structure");
-    expect(text).toContain("URI: http://example.com/s1");
-    expect(text).toContain("Category: react");
-    expect(text).toContain("Description:");
-    expect(text).not.toContain("Do:");
-    expect(text).not.toContain("Don't:");
-  });
-
-  it("renders dos and donts when detailed", () => {
-    const text = formatters.plain({ standard: DETAILED, detailed: true });
-    expect(text).toContain("Do:");
-    expect(text).toContain("  Place files in src/lib/");
-    expect(text).toContain("Don't:");
-    expect(text).toContain("  Use flat directory");
-  });
-
-  it("renders dash for empty category", () => {
-    const text = formatters.plain({
-      standard: { ...DETAILED, category: "" },
-      detailed: false,
-    });
-    expect(text).toContain("Category: —");
-  });
-
-  it("renders extends when present", () => {
-    const text = formatters.plain({
-      standard: { ...DETAILED, extends: "react/component/base" },
-      detailed: false,
-    });
-    expect(text).toContain("Extends: react/component/base");
-  });
-});
-
-describe("formatters.llm", () => {
-  it("renders markdown heading", () => {
-    const text = formatters.llm({ standard: DETAILED, detailed: false });
-    expect(text).toContain("## react/component/folder-structure");
-    expect(text).toContain("URI: http://example.com/s1");
-    expect(text).not.toContain("### Do");
-  });
-
-  it("renders extends in llm output when present", () => {
-    const text = formatters.llm({
-      standard: { ...DETAILED, extends: "cs:react_base" },
-      detailed: false,
-    });
-    expect(text).toContain("Extends: cs:react_base");
-  });
-
-  it("renders do/dont sections when detailed", () => {
-    const text = formatters.llm({ standard: DETAILED, detailed: true });
-    expect(text).toContain("### Do");
-    expect(text).toContain("### Don't");
-    expect(text).toContain("- Place files in src/lib/");
-  });
-});
-
-describe("formatters.json", () => {
-  it("includes dos/donts when detailed", () => {
-    const parsed = JSON.parse(
-      formatters.json({ standard: DETAILED, detailed: true }),
-    );
-    expect(parsed.dos).toHaveLength(2);
-    expect(parsed.donts).toHaveLength(1);
-  });
-
-  it("omits dos/donts when not detailed", () => {
-    const parsed = JSON.parse(
-      formatters.json({ standard: DETAILED, detailed: false }),
-    );
-    expect(parsed.dos).toBeUndefined();
-    expect(parsed.donts).toBeUndefined();
-    expect(parsed.name).toBe("react/component/folder-structure");
-  });
-});

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

@@ -1,101 +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 { StandardDetailed } from "../../shared/types/index.js";
-import { standardConfig } from "../standardConfig.js";
-import type { StandardLookupInput } from "./types.js";
-
-/** Three-mode formatter for `pragma standard lookup` output. */
-const formatters: Formatters<StandardLookupInput> = {
-  plain: ({ standard, detailed }) =>
-    renderLookupPlain(standard, {
-      title: (entry) => entry.name,
-      fields: [
-        { label: "URI", value: (entry) => entry.uri },
-        { label: "Category", value: (entry) => entry.category || "—" },
-        { label: "Description", value: (entry) => entry.description },
-        { label: "Extends", value: (entry) => entry.extends },
-      ],
-      sections: detailed
-        ? standardConfig.lookupSections.filter(
-            (section) => section.key === "dos" || section.key === "donts",
-          )
-        : [],
-      sectionOverrides: standardSectionOverrides,
-    }),
-
-  llm: ({ standard, detailed }) =>
-    renderLookupLlm(standard, {
-      title: (entry) => entry.name,
-      fields: [
-        { label: "URI", value: (entry) => entry.uri },
-        { label: "Category", value: (entry) => entry.category || "—" },
-        { label: "Description", value: (entry) => entry.description },
-        { label: "Extends", value: (entry) => entry.extends },
-      ],
-      sections: detailed
-        ? standardConfig.lookupSections.filter(
-            (section) => section.key === "dos" || section.key === "donts",
-          )
-        : [],
-      sectionOverrides: standardSectionOverrides,
-    }),
-
-  json({ standard, detailed }) {
-    if (detailed) {
-      return JSON.stringify(standard, null, 2);
-    }
-    const { dos: _dos, donts: _donts, ...summary } = standard;
-    return JSON.stringify(summary, null, 2);
-  },
-};
-
-export default formatters;
-
-/**
- * Build lookup rendering options for the Ink TUI view.
- *
- * @param detailed - whether to include dos/donts sections
- * @returns Options compatible with the LookupView component.
- */
-export function createInkLookupOptions(
-  detailed: boolean,
-): RenderLookupOptions<StandardDetailed> {
-  return {
-    title: (entry) => entry.name,
-    fields: [
-      { label: "URI", value: (entry) => entry.uri },
-      { label: "Category", value: (entry) => entry.category || "—" },
-      { label: "Description", value: (entry) => entry.description },
-      { label: "Extends", value: (entry) => entry.extends },
-    ],
-    sections: detailed
-      ? standardConfig.lookupSections.filter(
-          (section) => section.key === "dos" || section.key === "donts",
-        )
-      : [],
-  };
-}
-
-const standardSectionOverrides = {
-  dos: {
-    plain: (entry: StandardLookupInput["standard"]) =>
-      entry.dos.length > 0
-        ? entry.dos.map((item) => `  ${item.code}`).join("\n")
-        : null,
-    llm: (entry: StandardLookupInput["standard"]) =>
-      entry.dos.length > 0
-        ? entry.dos.map((item) => `- ${item.code}`).join("\n")
-        : null,
-  },
-  donts: {
-    plain: (entry: StandardLookupInput["standard"]) =>
-      entry.donts.length > 0
-        ? entry.donts.map((item) => `  ${item.code}`).join("\n")
-        : null,
-    llm: (entry: StandardLookupInput["standard"]) =>
-      entry.donts.length > 0
-        ? entry.donts.map((item) => `- ${item.code}`).join("\n")
-        : null,
-  },
-};

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

@@ -1,15 +0,0 @@
-/**
- * Sample formatter for the standard domain.
- *
- * Delegates to the shared factory, rendering each item via the
- * existing standard lookup formatter.
- */
-
-import createSampleFormatters from "../../shared/sampleFormatters.js";
-import type { StandardDetailed } from "../../shared/types/index.js";
-import lookupFormatters from "./lookup.js";
-
-export default createSampleFormatters<StandardDetailed>(
-  "standards",
-  (standard, mode) => lookupFormatters[mode]({ standard, detailed: true }),
-);

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

@@ -1,31 +0,0 @@
-/**
- * Formatter input types for standard commands.
- *
- * Composite types that bundle the data with display options,
- * so formatters conform to the `Formatters<T>` contract.
- */
-
-import type {
-  Disclosure,
-  StandardDetailed,
-  StandardSummary,
-} from "../../shared/types/index.js";
-
-/** Input payload for the standard-lookup formatter, pairing data with a detail flag. */
-export interface StandardLookupInput {
-  readonly standard: StandardDetailed;
-  readonly detailed: boolean;
-}
-
-/**
- * Input for the list formatter with progressive disclosure.
- *
- * - summary: items only (name + category + description)
- * - digest: items enriched with first do example
- * - detailed: items enriched with full dos/donts
- */
-export interface StandardListOutput {
-  readonly items: readonly StandardSummary[];
-  readonly details?: readonly (StandardDetailed | null)[];
-  readonly disclosure: Disclosure;
-}

package/src/domains/standard/index.ts

@@ -1,40 +0,0 @@
-/**
- * @module Standard domain — CLI commands and operations.
- *
- * Commands: `pragma standard list`, `pragma standard lookup <name>`,
- *           `pragma standard categories`.
- * Operations: {@link lookupStandard}, {@link listStandards}, {@link listCategories}.
- */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../shared/context.js";
-import {
-  categoriesCommand,
-  listCommand,
-  lookupCommand,
-  sampleCommand,
-} from "./commands/index.js";
-
-export function commands(ctx: PragmaContext): CommandDefinition[] {
-  return [
-    listCommand(ctx),
-    lookupCommand(ctx),
-    categoriesCommand(ctx),
-    sampleCommand(ctx),
-  ];
-}
-
-export { specs as mcpSpecs } from "./mcp/index.js";
-export {
-  listCategories,
-  listStandards,
-  lookupStandard,
-  sampleStandards,
-} from "./operations/index.js";
-export {
-  buildStandardFilters,
-  resolveStandardList,
-  resolveStandardLookup,
-  standardEmptyError,
-} from "./orchestration/index.js";
-export { standardConfig } from "./standardConfig.js";

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

@@ -1,2 +0,0 @@
-/** @module Standard domain MCP barrel — standard_list, standard_lookup, standard_categories. */
-export { default as specs } from "./specs.js";

package/src/domains/standard/mcp/specs.ts

@@ -1,89 +0,0 @@
-/**
- * MCP tool specs for the standard domain — standard_list, standard_lookup,
- * standard_categories, standard_sample.
- *
- * The list and lookup tools are compiled from the standard read stories in
- * `../stories.ts`; categories and sample are spec'd by hand. The adapter
- * layer converts these into registered MCP tools via `registerFromSpec()`.
- */
-
-import {
-  compileLookupTool,
-  compileReadTool,
-  condense,
-} from "../../shared/stories/index.js";
-import type { ToolSpec } from "../../shared/ToolSpec.js";
-import {
-  categoriesFormatters as standardCatFmt,
-  sampleFormatters as standardSampleFmt,
-} from "../formatters/index.js";
-import { listCategories, sampleStandards } from "../operations/index.js";
-import { standardListStory, standardLookupStory } from "../stories.js";
-
-const specs: readonly ToolSpec[] = [
-  compileReadTool(standardListStory),
-  compileLookupTool(standardLookupStory),
-  {
-    name: "standard_categories",
-    description: "List all code standard categories.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const result = await listCategories(rt.store);
-
-      if (condensed) {
-        return condense(standardCatFmt.llm(result));
-      }
-
-      return { data: result, meta: { count: result.length } };
-    },
-  },
-  {
-    name: "standard_sample",
-    description:
-      "Return 1–5 randomly selected complete code standard instances as exemplars. Use BEFORE writing queries to see actual data shapes, property names, and value formats. Each call returns different instances.",
-    params: {
-      count: {
-        type: "string",
-        description: "Number of samples (1–5, default 2)",
-        optional: true,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { count, condensed }) {
-      const n = Number(count ?? 2);
-      const result = await sampleStandards(rt.store, n);
-      const nextSteps = [
-        `These are ${result.samples.length} of ${result.totalCount} total standards.`,
-        "Use standard_lookup to inspect specific standards by name.",
-        "Use standard_list with category param to filter by category.",
-      ];
-
-      if (condensed) {
-        return condense(standardSampleFmt.llm({ ...result, nextSteps }));
-      }
-
-      return {
-        data: {
-          samples: result.samples,
-          totalCount: result.totalCount,
-          nextSteps,
-        },
-        meta: { count: result.samples.length },
-      };
-    },
-  },
-] as const;
-
-export default specs;

package/src/domains/standard/operations/categories.test.ts

@@ -1,61 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
-import listCategories from "./categories.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-describe("listCategories", () => {
-  it("returns categories with standard counts", async () => {
-    const result = await listCategories(store);
-    expect(result.length).toBe(2);
-
-    const react = result.find((c) => c.name === "react");
-    expect(react?.standardCount).toBe(2);
-
-    const code = result.find((c) => c.name === "code");
-    expect(code?.standardCount).toBe(1);
-  });
-
-  it("returns sorted by name", async () => {
-    const result = await listCategories(store);
-    const names = result.map((c) => c.name);
-    const sorted = [...names].sort();
-    expect(names).toEqual(sorted);
-  });
-
-  it("includes categories with zero standards", async () => {
-    const ttlWithEmptyCategory = `
-      @prefix cs: <${PREFIX_MAP.cs}> .
-      cs:empty_cat a cs:Category ; cs:slug "empty" .
-      cs:filled_cat a cs:Category ; cs:slug "filled" .
-      cs:s1 a cs:CodeStandard ;
-        cs:name "filled/one" ;
-        cs:hasCategory cs:filled_cat ;
-        cs:description "A standard" .
-    `;
-    const { store: testStore, cleanup: testCleanup } = await createTestStore({
-      ttl: ttlWithEmptyCategory,
-    });
-    try {
-      const result = await listCategories(testStore);
-      const empty = result.find((c) => c.name === "empty");
-      expect(empty).toBeDefined();
-      expect(empty?.standardCount).toBe(0);
-      const filled = result.find((c) => c.name === "filled");
-      expect(filled?.standardCount).toBe(1);
-    } finally {
-      testCleanup();
-    }
-  });
-});

package/src/domains/standard/operations/categories.ts

@@ -1,38 +0,0 @@
-/**
- * Lists all standard categories with the number of standards in each.
- *
- * @param store - ke store to query
- * @returns array of category summaries ordered by name, empty when none exist
- * @note Queries ke store
- */
-
-import type { Store } from "@canonical/ke";
-import { buildQuery } from "../../shared/buildQuery.js";
-import { P } from "../../shared/prefixes.js";
-import type { CategorySummary } from "../../shared/types/index.js";
-
-export default async function listCategories(
-  store: Store,
-): Promise<CategorySummary[]> {
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?categoryName (COUNT(?standard) AS ?count)
-      WHERE {
-        ?cat a ${P.cs}Category ;
-             ${P.cs}slug ?categoryName .
-        OPTIONAL {
-          ?standard a ${P.cs}CodeStandard ;
-                    ${P.cs}hasCategory ?cat .
-        }
-      }
-      GROUP BY ?categoryName
-      ORDER BY ?categoryName
-    `),
-  );
-
-  if (result.type !== "select") return [];
-  return result.bindings.map((b) => ({
-    name: b.categoryName ?? "",
-    standardCount: Number.parseInt(b.count ?? "0", 10) || 0,
-  }));
-}

package/src/domains/standard/operations/index.ts

@@ -1,6 +0,0 @@
-/** @module Re-exports standard operations (`listCategories`, `listStandards`, `lookupStandard`, `sampleStandards`). */
-
-export { default as listCategories } from "./categories.js";
-export { default as listStandards } from "./list.js";
-export { default as lookupStandard } from "./lookup.js";
-export { default as sampleStandards } from "./sample.js";

package/src/domains/standard/operations/list.test.ts

@@ -1,75 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import listStandards from "./list.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-describe("listStandards", () => {
-  it("returns all standards", async () => {
-    const result = await listStandards(store);
-    expect(result.length).toBe(3);
-    const names = result.map((s) => s.name);
-    expect(names).toContain("react/component/folder-structure");
-    expect(names).toContain("react/component/props");
-    expect(names).toContain("code/function/purity");
-  });
-
-  it("includes category names", async () => {
-    const result = await listStandards(store);
-    const folder = result.find(
-      (s) => s.name === "react/component/folder-structure",
-    );
-    expect(folder?.category).toBe("react");
-  });
-
-  it("returns sorted by name", async () => {
-    const result = await listStandards(store);
-    const names = result.map((s) => s.name);
-    const sorted = [...names].sort();
-    expect(names).toEqual(sorted);
-  });
-
-  it("filters by category", async () => {
-    const result = await listStandards(store, { category: "react" });
-    expect(result.length).toBe(2);
-    for (const s of result) {
-      expect(s.category).toBe("react");
-    }
-  });
-
-  it("filters by search term in name", async () => {
-    const result = await listStandards(store, { search: "folder" });
-    expect(result.length).toBe(1);
-    expect(result[0]?.name).toBe("react/component/folder-structure");
-  });
-
-  it("filters by search term in description", async () => {
-    const result = await listStandards(store, { search: "pure" });
-    expect(result.length).toBe(1);
-    expect(result[0]?.name).toBe("code/function/purity");
-  });
-
-  it("returns empty for non-matching category", async () => {
-    const result = await listStandards(store, { category: "nonexistent" });
-    expect(result.length).toBe(0);
-  });
-
-  it("combines category and search filters", async () => {
-    const result = await listStandards(store, {
-      category: "react",
-      search: "props",
-    });
-    expect(result.length).toBe(1);
-    expect(result[0]?.name).toBe("react/component/props");
-  });
-});

package/src/domains/standard/operations/list.ts

@@ -1,64 +0,0 @@
-/**
- * Lists all code standards, optionally filtered by category or search term.
- *
- * @param store - ke store to query
- * @param filters - optional category and/or search text filters
- * @returns array of standard summaries ordered by name, empty when none match
- * @note Queries ke store
- */
-
-import type { Store, URI } from "@canonical/ke";
-import { escapeSparqlValue } from "@canonical/ke";
-import { buildQuery } from "../../shared/buildQuery.js";
-import { P } from "../../shared/prefixes.js";
-import type {
-  StandardListFilters,
-  StandardSummary,
-} from "../../shared/types/index.js";
-
-export default async function listStandards(
-  store: Store,
-  filters?: StandardListFilters,
-): Promise<StandardSummary[]> {
-  const filterClauses: string[] = [];
-
-  if (filters?.category) {
-    const escaped = escapeSparqlValue(filters.category.toLowerCase());
-    filterClauses.push(
-      `?standard ${P.cs}hasCategory ?filterCat . ?filterCat ${P.cs}slug ?catSlug . FILTER(?catSlug = ${escaped})`,
-    );
-  }
-
-  if (filters?.search) {
-    const escaped = escapeSparqlValue(filters.search.toLowerCase());
-    filterClauses.push(
-      `FILTER(CONTAINS(LCASE(?name), ${escaped}) || CONTAINS(LCASE(?description), ${escaped}))`,
-    );
-  }
-
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?standard ?name ?categoryName ?description
-      WHERE {
-        ?standard a ${P.cs}CodeStandard ;
-                  ${P.cs}name ?name ;
-                  ${P.cs}description ?description .
-        OPTIONAL {
-          ?standard ${P.cs}hasCategory ?cat .
-          ?cat ${P.cs}slug ?categoryName .
-        }
-        ${filterClauses.join("\n        ")}
-      }
-      ORDER BY ?name
-    `),
-  );
-
-  if (result.type !== "select") return [];
-
-  return result.bindings.map((b) => ({
-    uri: (b.standard ?? "") as URI,
-    name: b.name ?? "",
-    category: b.categoryName ?? "",
-    description: b.description ?? "",
-  }));
-}

package/src/domains/standard/operations/lookup.test.ts

@@ -1,58 +0,0 @@
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import lookupStandard from "./lookup.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-describe("lookupStandard", () => {
-  it("returns detailed data with dos and donts", async () => {
-    const result = await lookupStandard(
-      store,
-      "react/component/folder-structure",
-    );
-    expect(result.name).toBe("react/component/folder-structure");
-    expect(result.category).toBe("react");
-    expect(result.dos.length).toBeGreaterThan(0);
-    expect(result.donts.length).toBeGreaterThan(0);
-  });
-
-  it("throws PragmaError.notFound for unknown standard", async () => {
-    await expect(lookupStandard(store, "nonexistent")).rejects.toThrow(
-      PragmaError,
-    );
-
-    try {
-      await lookupStandard(store, "nonexistent");
-    } catch (e) {
-      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
-    }
-  });
-
-  it("resolves prefixed IRIs and compacts extends", async () => {
-    const result = await lookupStandard(store, "cs:react_props");
-    expect(result.name).toBe("react/component/props");
-    expect(result.extends).toBe("cs:react_folder");
-  });
-
-  it("resolves full IRIs", async () => {
-    const result = await lookupStandard(
-      store,
-      "http://pragma.canonical.com/codestandards#react_props",
-    );
-    expect(result.name).toBe("react/component/props");
-    expect(result.uri).toBe(
-      "http://pragma.canonical.com/codestandards#react_props",
-    );
-  });
-});