@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/llm/operations/collectContext.test.ts

@@ -0,0 +1,64 @@
+import type { Store } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestStore, DS_ALL_TTL } from "#testing";
+import type { FilterConfig } from "../../shared/types/index.js";
+import { TOKEN_READ_SURFACE_ENABLED } from "../../token/featureFlag.js";
+import { renderLlmOrientation } from "../formatters/index.js";
+import type { LlmData } from "../types.js";
+import collectContext from "./collectContext.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());
+
+const config: FilterConfig = { tier: undefined, channel: "prerelease" };
+
+/** Extract the `## Context` data lines from a rendered orientation doc. */
+function contextBlock(rendered: string): string {
+  const lines = rendered.split("\n");
+  const start = lines.indexOf("## Context");
+  const block: string[] = [];
+  for (let i = start + 1; i < lines.length && lines[i] !== ""; i++) {
+    block.push(lines[i] ?? "");
+  }
+  return block.join("\n");
+}
+
+describe("collectContext", () => {
+  it("assembles counts and namespaces from the store", async () => {
+    const ctx = await collectContext(store, config);
+
+    expect(ctx.tier).toBeUndefined();
+    expect(ctx.channel).toBe("prerelease");
+    expect(ctx.counts.blocks).toBeGreaterThan(0);
+    expect(ctx.counts.standards).toBeGreaterThan(0);
+    expect(ctx.counts.modifierFamilies).toBeGreaterThan(0);
+    expect(ctx.counts.tokens).toBeGreaterThan(0);
+    expect(ctx.namespaces.length).toBeGreaterThan(0);
+  });
+
+  it("renders a stable `## Context` block", async () => {
+    const data: LlmData = {
+      context: await collectContext(store, config),
+      decisionTrees: [],
+      commandReference: [],
+    };
+
+    // The token count only renders while the token read surface is enabled.
+    const tokenSegment = TOKEN_READ_SURFACE_ENABLED ? ", 2 tokens" : "";
+    expect(contextBlock(renderLlmOrientation(data))).toBe(
+      [
+        "tier: (none) | channel: prerelease",
+        `data: 5 blocks, 3 standards, 2 modifier families${tokenSegment}`,
+        "namespaces: cs, ds",
+      ].join("\n"),
+    );
+  });
+});

package/src/domains/llm/operations/collectContext.ts

@@ -1,18 +1,16 @@
 import type { Store } from "@canonical/ke";
-import { listBlocks } from "../../block/operations/index.js";
-import { listModifiers } from "../../modifier/operations/index.js";
+import { collectEntityCounts } from "../../info/operations/index.js";
 import { listOntologies } from "../../ontology/operations/index.js";
 import { resolveTierChain } from "../../shared/filters/buildTierFilter.js";
 import type { FilterConfig } from "../../shared/types/index.js";
-import { listStandards } from "../../standard/operations/index.js";
-import { listTokens } from "../../token/operations/index.js";
 import type { LlmContext } from "../types.js";
 
 /**
  * Collects dynamic context for the `pragma llm` orientation output.
  *
- * Queries the store in parallel for block, standard, modifier, token, and
- * ontology counts, and combines them with tier/channel config state.
+ * Queries the store in parallel for entity counts (via
+ * {@link collectEntityCounts}) and ontology namespaces, and combines them
+ * with tier/channel config state.
  *
  * @note Queries ke store
  *
@@ -24,11 +22,8 @@ export default async function collectContext(
   store: Store,
   config: FilterConfig,
 ): Promise<LlmContext> {
-  const [blocks, standards, modifiers, tokens, ontologies] = await Promise.all([
-    listBlocks(store, config),
-    listStandards(store),
-    listModifiers(store),
-    listTokens(store),
+  const [counts, ontologies] = await Promise.all([
+    collectEntityCounts(store, config),
     listOntologies(store),
   ]);
 
@@ -36,12 +31,7 @@ export default async function collectContext(
     tier: config.tier,
     tierChain: resolveTierChain(config.tier),
     channel: config.channel,
-    counts: {
-      blocks: blocks.length,
-      standards: standards.length,
-      modifierFamilies: modifiers.length,
-      tokens: tokens.length,
-    },
+    counts,
     namespaces: ontologies.map((o) => o.prefix),
   };
 }

package/src/domains/modifier/commands/sample.ts

@@ -11,6 +11,7 @@ import {
 } from "@canonical/cli-core";
 import type { PragmaContext } from "../../shared/context.js";
 import { selectFormatter } from "../../shared/formatters.js";
+import parseSampleCount from "../../shared/parseSampleCount.js";
 import type { ModifierFamily, SampleOutput } from "../../shared/types/index.js";
 import { sampleFormatters } from "../formatters/index.js";
 import { sampleModifiers } from "../operations/index.js";
@@ -37,7 +38,7 @@ export default function sampleCommand(ctx: PragmaContext): CommandDefinition {
       examples: ["pragma modifier sample", "pragma modifier sample --count 3"],
     },
     async execute(params) {
-      const count = Number(params.count ?? 2);
+      const count = parseSampleCount(params.count);
       const result = await sampleModifiers(ctx.store, count);
 
       const output: SampleOutput<ModifierFamily> = {

package/src/domains/modifier/operations/lookup.ts

@@ -28,7 +28,7 @@ export default async function lookupModifier(
 
   const result = await store.query(
     buildQuery(`
-      SELECT ?family (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
+      SELECT ?family ?familyName (GROUP_CONCAT(DISTINCT ?valueName; separator="|") AS ?values)
       WHERE {
         ?family a ${P.ds}ModifierFamily ;
                 ${P.ds}name ?familyName .
@@ -39,7 +39,7 @@ export default async function lookupModifier(
                ${P.ds}name ?valueName .
         }
       }
-      GROUP BY ?family
+      GROUP BY ?family ?familyName
     `),
   );
 
@@ -61,7 +61,9 @@ export default async function lookupModifier(
   const b = result.bindings[0] as (typeof result.bindings)[number];
   return {
     uri: (b.family ?? "") as URI,
-    name,
+    // Return the canonical stored name, not the raw user query (which may
+    // differ in casing).
+    name: b.familyName ?? name,
     values: b.values ? b.values.split("|").filter(Boolean) : [],
   };
 }

package/src/domains/modifier/stories.ts

@@ -7,6 +7,7 @@
  */
 
 import { createListView, createLookupView } from "#tui";
+import { PragmaError } from "../../error/index.js";
 import type { LookupStory, ReadStory } from "../shared/stories/index.js";
 import type { ModifierFamily } from "../shared/types/index.js";
 import {
@@ -67,6 +68,14 @@ export const modifierLookupStory: LookupStory<ModifierFamily, ModifierFamily> =
     },
     toFmtInput: (family) => family,
     formatters: lookupFormatters,
+    emptyNamesError: () =>
+      PragmaError.invalidInput("names", "(empty)", {
+        recovery: {
+          message: "List available modifier families.",
+          cli: "pragma modifier list",
+          mcp: { tool: "modifier_list" },
+        },
+      }),
     renderInk: (result) =>
       createLookupView({
         results: result.results,

package/src/domains/ontology/commands/list.test.ts

@@ -52,8 +52,10 @@ describe("ontology list command", () => {
     const { text } = await executeOutput(cmd, {}, ctx);
 
     expect(text).toContain("ds");
-    expect(text).toContain("classes:");
-    expect(text).toContain("anatomy:");
+    expect(text).toContain("classes");
+    expect(text).toContain("relations");
+    expect(text).toContain("attributes");
+    expect(text).toContain("Next: pragma ontology show <prefix>");
   });
 
   it("renders llm output", async () => {
@@ -65,7 +67,7 @@ describe("ontology list command", () => {
 
     expect(text).toContain("## Ontologies");
     expect(text).toContain("**ds:**");
-    expect(text).toContain("anatomy:");
+    expect(text).toContain("relations");
   });
 
   it("renders json output", async () => {

package/src/domains/ontology/commands/show.test.ts

@@ -3,7 +3,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import createTestRuntime from "../../../testing/helpers/createTestRuntime.js";
 import type { PragmaContext } from "../../shared/context.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
-import type { OntologyDetailed } from "../../shared/types/index.js";
+import type { OntologyShowInput } from "../formatters/index.js";
 import buildShowCommand from "./show.js";
 
 let runtime: PragmaRuntime;
@@ -41,10 +41,69 @@ describe("ontology show command", () => {
     const cmd = buildShowCommand(ctx);
     const { value } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    const result = value as OntologyDetailed;
-    expect(result.prefix).toBe("ds");
-    expect(result.classes.length).toBeGreaterThan(0);
-    expect(result.properties.length).toBeGreaterThan(0);
+    const { ontology } = value as OntologyShowInput;
+    expect(ontology.prefix).toBe("ds");
+    expect(ontology.classes.length).toBeGreaterThan(0);
+    const propertyCount =
+      ontology.classes.reduce((n, c) => n + c.properties.length, 0) +
+      ontology.unattached.length;
+    expect(propertyCount).toBeGreaterThan(0);
+  });
+
+  it("deep-dives into a class via the class param", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const { value, text } = await executeOutput(
+      cmd,
+      { prefix: "ds", class: "Component" },
+      ctx,
+    );
+
+    const { ontology } = value as OntologyShowInput;
+    expect(ontology.focus?.iri).toBe("ds:Component");
+    expect(text).toContain("Component");
+    expect(text).toContain("extends:");
+    // Follow-up querying: the deep dive hands over runnable SPARQL.
+    expect(text).toContain(
+      "SELECT ?instance WHERE { ?instance a ds:Component }",
+    );
+  });
+
+  it("hides attributes by default and shows them with --properties", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+
+    const bare = await executeOutput(cmd, { prefix: "ds" }, ctx);
+    // Attributes render as `label: range` — absent by default.
+    expect(bare.text).not.toContain(": xsd:");
+    // hasModifierFamily is an object property (relation) — always shown.
+    expect(bare.text).toContain("hasModifierFamily");
+
+    const withProps = await executeOutput(
+      cmd,
+      { prefix: "ds", properties: true },
+      ctx,
+    );
+    expect(withProps.text).toContain(": xsd:");
+  });
+
+  it("expands IRIs with --full-uris", async () => {
+    const ctx = makeCtx({
+      globalFlags: { llm: true, format: "text" as const, verbose: false },
+    });
+    const cmd = buildShowCommand(ctx);
+    const { value, text } = await executeOutput(
+      cmd,
+      { prefix: "ds", fullUris: true },
+      ctx,
+    );
+
+    const { ontology } = value as OntologyShowInput;
+    const component = ontology.classes.find((c) => c.label === "Component");
+    expect(component?.iri).toBe("https://ds.canonical.com/Component");
+    expect(text).toContain("https://ds.canonical.com/Component");
+    // The seeded footer query must stay valid SPARQL: full URIs need <...>.
+    expect(text).toMatch(/\?s a <https:\/\/ds\.canonical\.com\//);
   });
 
   it("completes ontology prefixes", async () => {
@@ -57,13 +116,30 @@ describe("ontology show command", () => {
     expect(matches).toContain("ds");
   });
 
+  it("completes class names for --class", async () => {
+    const ctx = makeCtx();
+    const cmd = buildShowCommand(ctx);
+    const classParam = cmd.parameters.find((p) => p.name === "class");
+    const complete = classParam?.complete;
+
+    expect(complete).toBeTypeOf("function");
+    const matches = await complete?.("comp", ctx);
+    expect(matches).toContain("Component");
+    // Case-insensitive prefix match, sorted, no non-matches.
+    expect(matches?.every((m) => m.toLowerCase().startsWith("comp"))).toBe(
+      true,
+    );
+  });
+
   it("renders plain output", async () => {
     const ctx = makeCtx();
     const cmd = buildShowCommand(ctx);
     const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    expect(text).toContain("Classes");
-    expect(text).toContain("Properties");
+    expect(text).toContain("Ontology ds:");
+    expect(text).toContain("classes");
+    // Hierarchy: children render beneath their parent with tree branches.
+    expect(text).toContain("└─");
   });
 
   it("renders llm output", async () => {
@@ -73,7 +149,7 @@ describe("ontology show command", () => {
     const cmd = buildShowCommand(ctx);
     const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    expect(text).toContain("## ds:");
+    expect(text).toContain("## Ontology ds:");
     expect(text).toContain("### Classes");
   });
 
@@ -84,7 +160,7 @@ describe("ontology show command", () => {
     const cmd = buildShowCommand(ctx);
     const { text } = await executeOutput(cmd, { prefix: "ds" }, ctx);
 
-    const parsed = JSON.parse(text) as OntologyDetailed;
+    const parsed = JSON.parse(text) as { prefix: string };
     expect(parsed.prefix).toBe("ds");
   });
 

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

@@ -1,4 +1,5 @@
 /** @module Barrel for ontology formatters. */
 
 export { default as listFormatters } from "./list.js";
+export type { OntologyShowInput } from "./show.js";
 export { default as showFormatters } from "./show.js";

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

@@ -1,33 +1,39 @@
 import chalk from "chalk";
-import compactUri from "../../shared/compactUri.js";
 import type { Formatters } from "../../shared/formatters.js";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
 import type { OntologySummary } from "../../shared/types/index.js";
 
 /**
  * Formatters for `pragma ontology list` output.
  *
- * - **plain**: one line per ontology with chalk-styled prefix, namespace, and counts.
- * - **llm**: condensed Markdown bullet list under an `## Ontologies` heading.
- * - **json**: serialized ontology summary array as indented JSON.
+ * One line per namespace mirroring the `ontology show` summary line —
+ * name, metadata, and split counts — plus a next-command footer, so the
+ * list is the entry point of the same drill-down path
+ * (`list → show <prefix> → show <prefix> --class <Class>`).
+ *
+ * - **plain**: chalk-styled lines with counts and a dimmed footer.
+ * - **llm**: the same content as condensed Markdown bullets.
+ * - **json**: the {@link OntologySummary} array itself.
  */
 const formatters: Formatters<readonly OntologySummary[]> = {
   plain(ontologies) {
-    return ontologies
-      .map(
-        (o) =>
-          `${chalk.bold(`${o.prefix}:`)} ${compactUri(o.namespace, PREFIX_MAP)} classes: ${o.classCount} properties: ${o.propertyCount} anatomy: ${o.anatomyCount}`,
-      )
-      .join("\n");
+    const lines = ontologies.map(
+      (o) =>
+        `${chalk.bold(prefixLabel(o))} ${o.namespace} ${chalk.dim(`— ${summaryLine(o)}`)}`,
+    );
+    lines.push("");
+    lines.push(chalk.dim("Next: pragma ontology show <prefix>"));
+    return lines.join("\n");
   },
 
   llm(ontologies) {
     const lines = ["## Ontologies", ""];
     for (const o of ontologies) {
       lines.push(
-        `- **${o.prefix}:** \`${compactUri(o.namespace, PREFIX_MAP)}\` | classes: ${o.classCount} | properties: ${o.propertyCount} | anatomy: ${o.anatomyCount}`,
+        `- **${prefixLabel(o)}** \`${o.namespace}\` — ${summaryLine(o)}`,
       );
     }
+    lines.push("");
+    lines.push("Next: `ontology show <prefix>` for the class hierarchy.");
     return lines.join("\n");
   },
 
@@ -37,3 +43,22 @@ const formatters: Formatters<readonly OntologySummary[]> = {
 };
 
 export default formatters;
+
+/** `ds:` for prefixed namespaces, a placeholder for unprefixed ones. */
+function prefixLabel(o: OntologySummary): string {
+  return o.prefix ? `${o.prefix}:` : "(no prefix)";
+}
+
+/** The same counts-and-metadata line `ontology show` leads with. */
+function summaryLine(o: OntologySummary): string {
+  const parts = [
+    `${o.classCount} classes`,
+    `${o.relationCount} relations`,
+    `${o.attributeCount} attributes`,
+  ];
+  if (o.shapeCount > 0) parts.push(`${o.shapeCount} shapes`);
+  if (o.anatomyCount > 0) parts.push(`${o.anatomyCount} anatomies`);
+  if (o.version) parts.push(`v${o.version}`);
+  if (o.title) parts.push(o.title);
+  return parts.join(" · ");
+}