@canonical/pragma-cli 0.30.0 → 0.31.0

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

@@ -2,104 +2,395 @@ import chalk from "chalk";
 // Deep import, not #pipeline: the barrel re-exports collectCommands, which
 // imports every domain barrel — including this one — so #pipeline here forms
 // a module cycle that evaluates this domain's stories as undefined at load.
-import {
-  formatHeading,
-  formatSection,
-} from "../../../pipeline/formatTerminal.js";
-import compactUri from "../../shared/compactUri.js";
+import { formatHeading } from "../../../pipeline/formatTerminal.js";
 import type { Formatters } from "../../shared/formatters.js";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
-import type { OntologyDetailed } from "../../shared/types/index.js";
+import type {
+  OntologyClassFocus,
+  OntologyDetailed,
+  OntologyProperty,
+} from "../../shared/types/index.js";
+import type { ClassTreeNode } from "../helpers/buildClassTree.js";
+import buildClassTree from "../helpers/buildClassTree.js";
+
+/**
+ * Formatter input for `ontology show`: the one complete structure plus the
+ * projection controls resolved from the story params. `--full-uris` is
+ * already applied to `ontology` by the story's `toOutput`, so the renderers
+ * below never re-encode IRIs.
+ */
+export interface OntologyShowInput {
+  readonly ontology: OntologyDetailed;
+  /** Include datatype properties (attributes); default renders relations only. */
+  readonly showProperties: boolean;
+}
 
 /**
  * Formatters for `pragma ontology show` output.
  *
- * - **plain**: chalk-styled heading with Classes and Properties sections.
- * - **llm**: condensed Markdown with `### Classes` and `### Properties` sub-headings.
- * - **json**: serialized {@link OntologyDetailed} as indented JSON.
+ * All three modes are projections of the same {@link OntologyDetailed}
+ * structure — they may style differently, but every fact they print comes
+ * from that one shape, and the hierarchy is derived through the single
+ * shared {@link buildClassTree} helper so it can never diverge between
+ * output modes.
+ *
+ * - **plain**: chalk-styled header (name, metadata, counts), class
+ *   hierarchy tree with instance counts and inline relations, constraints,
+ *   and a next-command footer. Attributes render only with `--properties`.
+ *   Renders the class deep dive when `focus` is present.
+ * - **llm**: the same content as condensed Markdown.
+ * - **json**: the complete {@link OntologyDetailed} structure itself
+ *   (always everything — display flags never subset the canonical data).
  */
-const formatters: Formatters<OntologyDetailed> = {
-  plain(data) {
-    const lines: string[] = [];
+const formatters: Formatters<OntologyShowInput> = {
+  plain({ ontology, showProperties }) {
+    if (ontology.focus) return renderFocusPlain(ontology.focus);
 
+    const lines: string[] = [];
     lines.push(
-      formatHeading(
-        `${data.prefix}: ${compactUri(data.namespace, PREFIX_MAP)}`,
-      ),
+      formatHeading(`Ontology ${ontology.prefix}: — ${ontology.namespace}`),
     );
+    lines.push(chalk.dim(summaryLine(ontology)));
+    if (ontology.meta?.imports?.length) {
+      lines.push(chalk.dim(`imports: ${ontology.meta.imports.join(", ")}`));
+    }
 
-    if (data.classes.length > 0) {
-      const classLines = data.classes
-        .map((c) => {
-          const sup = c.superclass
-            ? chalk.dim(` extends ${compactUri(c.superclass, PREFIX_MAP)}`)
-            : "";
-          return `  ${chalk.bold(c.label)} ${chalk.dim(`(${compactUri(c.uri, PREFIX_MAP)})`)}${sup}`;
-        })
-        .join("\n");
+    if (ontology.classes.length > 0) {
       lines.push("");
-      lines.push(formatSection("Classes", classLines));
+      for (const root of buildClassTree(ontology.classes)) {
+        renderTreePlain(root, "", "", showProperties, lines);
+      }
     }
 
-    if (data.properties.length > 0) {
-      const propLines = data.properties
-        .map((p) => {
-          const domain = p.domain
-            ? chalk.dim(` domain: ${compactUri(p.domain, PREFIX_MAP)}`)
-            : "";
-          const range = p.range
-            ? chalk.dim(` range: ${compactUri(p.range, PREFIX_MAP)}`)
-            : "";
-          return `  ${chalk.bold(p.label)} ${chalk.dim(`(${compactUri(p.uri, PREFIX_MAP)})`)} (${p.type})${domain}${range}`;
-        })
-        .join("\n");
+    const looseRelations = unattachedToShow(ontology, showProperties);
+    if (looseRelations.length > 0) {
       lines.push("");
-      lines.push(formatSection("Properties", propLines));
+      lines.push(
+        `${chalk.bold("Unattached:")} ${looseRelations
+          .map((p) => propLine(p, showProperties))
+          .join(", ")}`,
+      );
     }
 
+    if (ontology.constraints && ontology.constraints.length > 0) {
+      lines.push("");
+      lines.push(chalk.bold("Constraints:"));
+      for (const c of ontology.constraints) {
+        const target = c.targetClass ? ` on ${c.targetClass}` : "";
+        lines.push(
+          `  ${c.shape}${target} ${chalk.dim(
+            `(${c.propertyCount} property constraints)`,
+          )}`,
+        );
+      }
+    }
+
+    lines.push("");
+    lines.push(chalk.dim(footer(ontology)));
+
     return lines.join("\n");
   },
 
-  llm(data) {
-    const lines = [
-      `## ${data.prefix}: ${compactUri(data.namespace, PREFIX_MAP)}`,
-      "",
-    ];
+  llm({ ontology, showProperties }) {
+    if (ontology.focus) return renderFocusLlm(ontology.focus);
 
-    if (data.classes.length > 0) {
+    const lines: string[] = [];
+    lines.push(`## Ontology ${ontology.prefix}: — ${ontology.namespace}`);
+    lines.push(summaryLine(ontology));
+    if (ontology.meta?.imports?.length) {
+      lines.push(`imports: ${ontology.meta.imports.join(", ")}`);
+    }
+    lines.push("");
+
+    if (ontology.classes.length > 0) {
       lines.push("### Classes");
-      for (const c of data.classes) {
-        const sup = c.superclass
-          ? ` extends ${compactUri(c.superclass, PREFIX_MAP)}`
-          : "";
-        lines.push(
-          `- \`${compactUri(c.uri, PREFIX_MAP)}\` — **${c.label}**${sup}`,
-        );
+      lines.push("```");
+      for (const root of buildClassTree(ontology.classes)) {
+        renderTreeLlm(root, 0, showProperties, lines);
       }
-      lines.push("");
+      lines.push("```");
     }
 
-    if (data.properties.length > 0) {
-      lines.push("### Properties");
-      for (const p of data.properties) {
-        const domain = p.domain
-          ? ` domain: ${compactUri(p.domain, PREFIX_MAP)}`
-          : "";
-        const range = p.range
-          ? ` range: ${compactUri(p.range, PREFIX_MAP)}`
-          : "";
-        lines.push(
-          `- \`${compactUri(p.uri, PREFIX_MAP)}\` — **${p.label}** (${p.type})${domain}${range}`,
-        );
+    const looseRelations = unattachedToShow(ontology, showProperties);
+    if (looseRelations.length > 0) {
+      lines.push(
+        `Unattached: ${looseRelations
+          .map((p) => propLine(p, showProperties))
+          .join(", ")}`,
+      );
+    }
+
+    if (ontology.constraints && ontology.constraints.length > 0) {
+      lines.push("### Constraints");
+      for (const c of ontology.constraints) {
+        const target = c.targetClass ? ` targets ${c.targetClass}` : "";
+        lines.push(`- ${c.shape}${target} (${c.propertyCount} constraints)`);
       }
     }
 
+    lines.push("");
+    lines.push(footer(ontology));
+
     return lines.join("\n");
   },
 
-  json(data) {
-    return JSON.stringify(data, null, 2);
+  json({ ontology }) {
+    return JSON.stringify(ontology, null, 2);
   },
 };
 
 export default formatters;
+
+// ---------------------------------------------------------------------------
+// Shared fragments
+// ---------------------------------------------------------------------------
+
+function allProperties(ontology: OntologyDetailed): OntologyProperty[] {
+  return [
+    ...ontology.classes.flatMap((c) => c.properties),
+    ...ontology.unattached,
+  ];
+}
+
+function summaryLine(ontology: OntologyDetailed): string {
+  const props = allProperties(ontology);
+  const relations = props.filter((p) => p.kind === "object").length;
+  const attributes = props.length - relations;
+  const parts = [
+    `${ontology.classes.length} classes`,
+    `${relations} relations`,
+    `${attributes} attributes`,
+  ];
+  if (ontology.constraints?.length) {
+    parts.push(`${ontology.constraints.length} shapes`);
+  }
+  if (ontology.meta?.version) parts.push(`v${ontology.meta.version}`);
+  if (ontology.meta?.title) parts.push(ontology.meta.title);
+  return parts.join(" · ");
+}
+
+/**
+ * The next-step footer: the class deep dive, plus a runnable query seeded
+ * with a real class from this namespace so follow-up querying starts from
+ * copy-paste, not from reading SPARQL docs.
+ */
+function footer(ontology: OntologyDetailed): string {
+  const seed =
+    ontology.classes.find((c) => (c.instances ?? 0) > 0) ?? ontology.classes[0];
+  const query = seed
+    ? ` · pragma graph query "SELECT ?s WHERE { ?s a ${sparqlTerm(seed.iri)} } LIMIT 10"`
+    : "";
+  return `Next: pragma ontology show ${ontology.prefix} --class <Class>${query}`;
+}
+
+/**
+ * Render an IRI as a valid SPARQL term: full URIs (present under
+ * `--full-uris`) need `<...>`; compact prefixed IRIs are usable as-is.
+ */
+function sparqlTerm(iri: string): string {
+  return iri.startsWith("http://") || iri.startsWith("https://")
+    ? `<${iri}>`
+    : iri;
+}
+
+/** Properties a class renders inline: relations always, attributes on demand. */
+function inlineProperties(
+  props: readonly OntologyProperty[],
+  showProperties: boolean,
+): readonly OntologyProperty[] {
+  return showProperties ? props : props.filter((p) => p.kind === "object");
+}
+
+/** Unattached entries to display under the current verbosity. */
+function unattachedToShow(
+  ontology: OntologyDetailed,
+  showProperties: boolean,
+): readonly OntologyProperty[] {
+  return inlineProperties(ontology.unattached, showProperties);
+}
+
+/** One class's inline property summary: `tier →ds:Tier, …(+2 more)`. */
+function inlineProps(
+  props: readonly OntologyProperty[],
+  showProperties: boolean,
+  max = 4,
+): string {
+  const shown = inlineProperties(props, showProperties);
+  if (shown.length === 0) return "";
+  const rendered = shown.slice(0, max).map((p) => propLine(p, showProperties));
+  const extra = shown.length - max;
+  return ` — ${rendered.join(", ")}${extra > 0 ? `, …(+${extra} more)` : ""}`;
+}
+
+function propLine(p: OntologyProperty, showProperties: boolean): string {
+  const range =
+    p.kind === "object" && p.range
+      ? ` →${p.range}`
+      : showProperties && p.range
+        ? `: ${p.range}`
+        : "";
+  return `${p.label}${range}`;
+}
+
+function classSuffix(node: ClassTreeNode): string {
+  const count = node.cls.instances ? ` (${node.cls.instances})` : "";
+  const also =
+    node.alsoExtends.length > 0
+      ? ` [also extends ${node.alsoExtends.join(", ")}]`
+      : "";
+  return `${count}${also}`;
+}
+
+// ---------------------------------------------------------------------------
+// Tree renderers (both derive from the same buildClassTree forest)
+// ---------------------------------------------------------------------------
+
+function renderTreePlain(
+  node: ClassTreeNode,
+  prefix: string,
+  childIndent: string,
+  showProperties: boolean,
+  lines: string[],
+): void {
+  const suffix = chalk.dim(
+    `${classSuffix(node)}${inlineProps(node.cls.properties, showProperties)}`,
+  );
+  lines.push(`${prefix}${chalk.bold(node.cls.label)}${suffix}`);
+
+  node.children.forEach((child, i) => {
+    const last = i === node.children.length - 1;
+    renderTreePlain(
+      child,
+      `${childIndent}${last ? "└─ " : "├─ "}`,
+      `${childIndent}${last ? "   " : "│  "}`,
+      showProperties,
+      lines,
+    );
+  });
+}
+
+function renderTreeLlm(
+  node: ClassTreeNode,
+  depth: number,
+  showProperties: boolean,
+  lines: string[],
+): void {
+  const pad = "  ".repeat(depth);
+  lines.push(
+    `${pad}${node.cls.iri}${classSuffix(node)}${inlineProps(node.cls.properties, showProperties)}`,
+  );
+  for (const child of node.children) {
+    renderTreeLlm(child, depth + 1, showProperties, lines);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Focus (per-class deep dive) renderers — always full detail
+// ---------------------------------------------------------------------------
+
+function renderFocusPlain(f: OntologyClassFocus): string {
+  const lines: string[] = [];
+
+  lines.push(formatHeading(`${f.label} — ${f.iri}`));
+  if (f.comment) lines.push(f.comment);
+  const chain =
+    f.superChain.length > 0 ? f.superChain.join(" < ") : "(root class)";
+  lines.push(chalk.dim(`extends: ${chain} · instances: ${f.instances}`));
+
+  pushPropSection(lines, "Relations", relationsOf(f.directProperties));
+  pushPropSection(lines, "Attributes", attributesOf(f.directProperties));
+  pushPropSection(lines, "Inherited", f.inheritedProperties);
+  pushPropSection(lines, "Referenced by", f.referencedBy);
+
+  if (f.subclasses.length > 0) {
+    lines.push("");
+    lines.push(`${chalk.bold("Subclasses:")} ${f.subclasses.join(", ")}`);
+  }
+
+  if (f.sampleInstances.length > 0) {
+    lines.push("");
+    lines.push(`${chalk.bold("Instances:")} ${f.sampleInstances.join(", ")}`);
+  }
+
+  if (f.queries.length > 0) {
+    lines.push("");
+    lines.push(chalk.bold("Queries:"));
+    for (const q of f.queries) {
+      lines.push(chalk.dim(`  # ${q.label}`));
+      lines.push(`  pragma graph query "${q.sparql}"`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderFocusLlm(f: OntologyClassFocus): string {
+  const lines: string[] = [];
+
+  lines.push(`## ${f.iri} — ${f.label}`);
+  if (f.comment) lines.push(f.comment);
+  const chain =
+    f.superChain.length > 0 ? f.superChain.join(" < ") : "(root class)";
+  lines.push(`- extends: ${chain}`);
+  lines.push(`- instances: ${f.instances}`);
+  if (f.subclasses.length > 0) {
+    lines.push(`- subclasses: ${f.subclasses.join(", ")}`);
+  }
+
+  const section = (title: string, props: readonly OntologyProperty[]) => {
+    if (props.length === 0) return;
+    lines.push(`### ${title}`);
+    for (const p of props) {
+      lines.push(`- ${fullPropLine(p)}`);
+    }
+  };
+  section("Relations", relationsOf(f.directProperties));
+  section("Attributes", attributesOf(f.directProperties));
+  section("Inherited", f.inheritedProperties);
+  section("Referenced by", f.referencedBy);
+
+  if (f.sampleInstances.length > 0) {
+    lines.push("### Instances");
+    for (const iri of f.sampleInstances) lines.push(`- ${iri}`);
+  }
+
+  if (f.queries.length > 0) {
+    lines.push("### Queries");
+    for (const q of f.queries) {
+      lines.push(`- ${q.label}: \`${q.sparql}\``);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function relationsOf(
+  props: readonly OntologyProperty[],
+): readonly OntologyProperty[] {
+  return props.filter((p) => p.kind === "object");
+}
+
+function attributesOf(
+  props: readonly OntologyProperty[],
+): readonly OntologyProperty[] {
+  return props.filter((p) => p.kind === "datatype");
+}
+
+function pushPropSection(
+  lines: string[],
+  title: string,
+  props: readonly OntologyProperty[],
+): void {
+  if (props.length === 0) return;
+  lines.push("");
+  lines.push(chalk.bold(`${title}:`));
+  for (const p of props) {
+    lines.push(`  ${fullPropLine(p)}`);
+  }
+}
+
+function fullPropLine(p: OntologyProperty): string {
+  const range = p.range ? ` → ${p.range}` : "";
+  const from = p.domain ? ` (on ${p.domain})` : "";
+  const functional = p.functional ? " [functional]" : "";
+  return `${p.iri} (${p.kind})${range}${from}${functional}`;
+}

package/src/domains/ontology/helpers/buildClassTree.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure class-hierarchy builder shared by every `ontology show` projection.
+ *
+ * The {@link OntologyDetailed} data shape keeps classes as a flat,
+ * topologically ordered array with `subClassOf` edges (canonical for JSON
+ * and MCP consumers); the plain and llm renderers both derive their tree
+ * from this single implementation so the hierarchy can never diverge
+ * between output modes.
+ */
+
+import type { OntologyClass } from "../../shared/types/index.js";
+
+/** A class positioned in the rendered hierarchy. */
+export interface ClassTreeNode {
+  readonly cls: OntologyClass;
+  readonly children: readonly ClassTreeNode[];
+  /**
+   * Superclasses beyond the one used for tree placement (multiple
+   * inheritance) — renderers annotate these as "also extends".
+   */
+  readonly alsoExtends: readonly string[];
+}
+
+/**
+ * Arrange classes into a forest.
+ *
+ * Roots are classes with no in-set parent; children sort alphabetically by
+ * label. A class with several in-set parents is placed under its first
+ * (alphabetically sorted) parent and carries the rest in `alsoExtends`.
+ * Cycle-safe: an edge that would revisit a placed class is ignored, so a
+ * cyclic ontology degrades to a flat listing rather than recursing.
+ *
+ * @param classes - Flat class array (any order; `subClassOf` holds compact
+ *   or full IRIs — matching whatever `iri` uses).
+ * @returns Root nodes in alphabetical label order.
+ */
+export default function buildClassTree(
+  classes: readonly OntologyClass[],
+): ClassTreeNode[] {
+  const byIri = new Map(classes.map((c) => [c.iri, c]));
+  const placed = new Set<string>();
+
+  const inSetParents = (cls: OntologyClass): string[] =>
+    cls.subClassOf.filter((parent) => byIri.has(parent));
+
+  const childrenOf = (parentIri: string): OntologyClass[] =>
+    classes
+      .filter((c) => inSetParents(c)[0] === parentIri)
+      .sort((a, b) => a.label.localeCompare(b.label));
+
+  const build = (cls: OntologyClass): ClassTreeNode => {
+    placed.add(cls.iri);
+    const parents = inSetParents(cls);
+    return {
+      cls,
+      alsoExtends: parents.slice(1),
+      children: childrenOf(cls.iri)
+        .filter((child) => !placed.has(child.iri))
+        .map(build),
+    };
+  };
+
+  const roots = classes
+    .filter((c) => inSetParents(c).length === 0)
+    .sort((a, b) => a.label.localeCompare(b.label))
+    .map(build);
+
+  // Cycle fallback: anything unreachable from a root (e.g. mutually
+  // extending classes) is appended as an additional root.
+  const leftovers = classes
+    .filter((c) => !placed.has(c.iri))
+    .sort((a, b) => a.label.localeCompare(b.label))
+    .map(build);
+
+  return [...roots, ...leftovers];
+}
+
+/** Flatten a forest to pre-order (the shape's canonical class ordering). */
+export function flattenClassTree(
+  nodes: readonly ClassTreeNode[],
+): OntologyClass[] {
+  const out: OntologyClass[] = [];
+  const walk = (node: ClassTreeNode): void => {
+    out.push(node.cls);
+    for (const child of node.children) walk(child);
+  };
+  for (const node of nodes) walk(node);
+  return out;
+}

package/src/domains/ontology/helpers/completeClassNames.ts

@@ -0,0 +1,43 @@
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import extractLocalName from "../../shared/extractLocalName.js";
+import { P } from "../../shared/prefixes.js";
+
+/**
+ * Tab-completion candidates for the `--class` parameter of
+ * `ontology show`: the local names of every `owl:Class` in the store,
+ * filtered by the typed partial (case-insensitive prefix match).
+ *
+ * Completion runs before the prefix positional is resolvable from the
+ * completion context, so candidates span all namespaces — the operation
+ * scopes the actual lookup to the requested namespace. Results are capped
+ * at `limit` so a huge graph cannot flood the shell; an empty partial
+ * still completes (class sets are small and the query is one indexed
+ * type-scan).
+ *
+ * @note Queries ke store
+ */
+export default async function completeClassNames(
+  store: Store,
+  partial: string,
+  limit = 50,
+): Promise<string[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?class
+      WHERE { ?class a ${P.owl}Class }
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  const needle = partial.toLowerCase();
+  const names = new Set<string>();
+  for (const b of result.bindings) {
+    if (!b.class) continue;
+    const local = extractLocalName(b.class);
+    if (local.toLowerCase().startsWith(needle)) names.add(local);
+  }
+
+  return [...names].sort().slice(0, limit);
+}

package/src/domains/ontology/helpers/expandOntologyIris.ts

@@ -0,0 +1,79 @@
+/**
+ * Expand every compact IRI in an {@link OntologyDetailed} structure back to
+ * its full URI using the structure's own `prefixes` map.
+ *
+ * The data shape keeps compact IRIs as its canonical encoding; `--full-uris`
+ * applies this pure transform once in the story's `toOutput`, so every
+ * projection (plain, llm, json, MCP condensed) inherits the expansion from
+ * the same place. Query hints are left untouched: their compact IRIs are
+ * resolvable by `pragma graph query` regardless of the display encoding.
+ */
+
+import type {
+  OntologyClass,
+  OntologyClassFocus,
+  OntologyDetailed,
+  OntologyProperty,
+} from "../../shared/types/index.js";
+
+export default function expandOntologyIris(
+  ontology: OntologyDetailed,
+): OntologyDetailed {
+  const expand = (iri: string): string => {
+    const colon = iri.indexOf(":");
+    if (colon <= 0) return iri;
+    const namespace = ontology.prefixes[iri.slice(0, colon)];
+    return namespace === undefined
+      ? iri
+      : `${namespace}${iri.slice(colon + 1)}`;
+  };
+
+  const expandProperty = (p: OntologyProperty): OntologyProperty => ({
+    ...p,
+    iri: expand(p.iri),
+    ...(p.domain ? { domain: expand(p.domain) } : {}),
+    ...(p.range ? { range: expand(p.range) } : {}),
+  });
+
+  const expandClass = (c: OntologyClass): OntologyClass => ({
+    ...c,
+    iri: expand(c.iri),
+    subClassOf: c.subClassOf.map(expand),
+    properties: c.properties.map(expandProperty),
+  });
+
+  const expandFocus = (f: OntologyClassFocus): OntologyClassFocus => ({
+    ...f,
+    iri: expand(f.iri),
+    superChain: f.superChain.map(expand),
+    subclasses: f.subclasses.map(expand),
+    directProperties: f.directProperties.map(expandProperty),
+    inheritedProperties: f.inheritedProperties.map(expandProperty),
+    referencedBy: f.referencedBy.map(expandProperty),
+    sampleInstances: f.sampleInstances.map(expand),
+  });
+
+  return {
+    ...ontology,
+    ...(ontology.meta?.imports
+      ? {
+          meta: {
+            ...ontology.meta,
+            imports: ontology.meta.imports.map(expand),
+          },
+        }
+      : {}),
+    classes: ontology.classes.map(expandClass),
+    unattached: ontology.unattached.map(expandProperty),
+    ...(ontology.constraints
+      ? {
+          constraints: ontology.constraints.map((c) => ({
+            ...c,
+            shape: expand(c.shape),
+            ...(c.targetClass ? { targetClass: expand(c.targetClass) } : {}),
+          })),
+        }
+      : {}),
+    ...(ontology.focus ? { focus: expandFocus(ontology.focus) } : {}),
+  };
+}