@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -1,396 +0,0 @@
-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 } from "../../../pipeline/formatTerminal.js";
-import type { Formatters } from "../../shared/formatters.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.
- *
- * 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<OntologyShowInput> = {
-  plain({ ontology, showProperties }) {
-    if (ontology.focus) return renderFocusPlain(ontology.focus);
-
-    const lines: string[] = [];
-    lines.push(
-      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 (ontology.classes.length > 0) {
-      lines.push("");
-      for (const root of buildClassTree(ontology.classes)) {
-        renderTreePlain(root, "", "", showProperties, lines);
-      }
-    }
-
-    const looseRelations = unattachedToShow(ontology, showProperties);
-    if (looseRelations.length > 0) {
-      lines.push("");
-      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({ ontology, showProperties }) {
-    if (ontology.focus) return renderFocusLlm(ontology.focus);
-
-    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");
-      lines.push("```");
-      for (const root of buildClassTree(ontology.classes)) {
-        renderTreeLlm(root, 0, showProperties, lines);
-      }
-      lines.push("```");
-    }
-
-    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({ 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

@@ -1,89 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-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

@@ -1,79 +0,0 @@
-/**
- * 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) } : {}),
-  };
-}

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

@@ -1,23 +0,0 @@
-/**
- * Finds the namespace prefix for a given URI by matching against registered
- * prefix entries. When multiple prefixes match, selects the longest
- * (most specific) namespace.
- *
- * @param uri - The full URI to look up.
- * @param prefixEntries - Array of `[prefix, namespace]` tuples from the store.
- * @returns The matching `{ prefix, namespace }` or `undefined` if no prefix matches.
- */
-export default function findNamespace(
-  uri: string,
-  prefixEntries: [string, string][],
-): { prefix: string; namespace: string } | undefined {
-  let best: { prefix: string; namespace: string } | undefined;
-  for (const [prefix, namespace] of prefixEntries) {
-    if (uri.startsWith(namespace)) {
-      if (!best || namespace.length > best.namespace.length) {
-        best = { prefix, namespace };
-      }
-    }
-  }
-  return best;
-}

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

@@ -1,21 +0,0 @@
-/** @module Barrel for ontology helpers. */
-
-export { default as extractLocalName } from "../../shared/extractLocalName.js";
-export type { ClassTreeNode } from "./buildClassTree.js";
-export {
-  default as buildClassTree,
-  flattenClassTree,
-} from "./buildClassTree.js";
-export { default as expandOntologyIris } from "./expandOntologyIris.js";
-export { default as findNamespace } from "./findNamespace.js";
-export type { RawOntologyClass } from "./queryClasses.js";
-export { default as queryClasses } from "./queryClasses.js";
-export type { RawOntologyProperty } from "./queryProperties.js";
-export { default as queryProperties } from "./queryProperties.js";
-export {
-  queryConstraints,
-  queryInstanceCounts,
-  queryOntologyMeta,
-  querySampleInstances,
-} from "./queryTboxFacts.js";
-export { default as resolvePrefix } from "./resolvePrefix.js";