@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/ontology/operations/listOntologies.ts

@@ -4,17 +4,51 @@ import { P } from "../../shared/prefixes.js";
 import type { OntologySummary } from "../../shared/types/index.js";
 import findNamespace from "../helpers/findNamespace.js";
 
+const SH = "http://www.w3.org/ns/shacl#";
+
 /** Check whether a URI belongs to the anatomy namespace. */
 function isAnatomyTerm(uri: string): boolean {
   return uri.toLowerCase().includes("anatomy");
 }
 
+/** Per-namespace URI accumulator. */
+function add(
+  map: Map<string, Set<string>>,
+  namespace: string,
+  uri: string,
+): void {
+  const set = map.get(namespace) ?? new Set();
+  set.add(uri);
+  map.set(namespace, set);
+}
+
+/**
+ * Derive a namespace from a URI when no registered prefix matches: cut
+ * after the last `#`, else after the last `/`. Keeps ontologies loaded
+ * without a declared prefix (e.g. a package that has not yet published
+ * its `pragma.prefixes`) visible in the listing instead of silently
+ * dropping their whole TBox.
+ */
+function deriveNamespace(uri: string): string | undefined {
+  const hash = uri.lastIndexOf("#");
+  if (hash > 0) return uri.slice(0, hash + 1);
+  // Scheme-agnostic: any slash after the `scheme://` authority separator
+  // marks a path segment; a URI with no path (http://host) has none.
+  const authority = uri.indexOf("://");
+  if (authority < 0) return undefined;
+  const slash = uri.lastIndexOf("/");
+  return slash > authority + 2 ? uri.slice(0, slash + 1) : undefined;
+}
+
 /**
- * List all loaded ontology namespaces with their class, property, and anatomy counts.
+ * List all loaded ontology namespaces with their header metadata (title,
+ * version) and counts: classes, relations (object properties), attributes
+ * (datatype properties), SHACL shapes, and anatomy terms.
  *
  * Discovers namespaces by querying for `owl:Class` and
  * `owl:ObjectProperty`/`owl:DatatypeProperty` definitions, then maps
- * namespace URIs back to prefixes via `store.prefixes`.
+ * namespace URIs back to prefixes via `store.prefixes`. Four whole-store
+ * queries regardless of how many namespaces are loaded.
  *
  * @param store - The ke store to query.
  * @returns An array of {@link OntologySummary} sorted alphabetically by prefix.
@@ -41,25 +75,47 @@ export default async function listOntologies(
     `),
   );
 
+  const shapeResult = await store.query(
+    buildQuery(`
+      SELECT ?shape ?target
+      WHERE {
+        ?shape a <${SH}NodeShape> .
+        OPTIONAL { ?shape <${SH}targetClass> ?target }
+      }
+    `),
+  );
+
+  const metaResult = await store.query(
+    buildQuery(`
+      SELECT ?ont ?title ?version
+      WHERE {
+        ?ont a ${P.owl}Ontology .
+        OPTIONAL { ?ont ${P.rdfs}label ?title }
+        OPTIONAL { ?ont ${P.owl}versionInfo ?version }
+      }
+      ORDER BY ?ont
+    `),
+  );
+
   const prefixEntries = Object.entries(store.prefixes);
+  // Everything below is keyed by namespace URI so ontologies without a
+  // registered prefix still surface in the listing.
+  const nsOf = (uri: string): string | undefined =>
+    findNamespace(uri, prefixEntries)?.namespace ?? deriveNamespace(uri);
   const classCounts = new Map<string, Set<string>>();
-  const propCounts = new Map<string, Set<string>>();
+  const relationCounts = new Map<string, Set<string>>();
+  const attributeCounts = new Map<string, Set<string>>();
+  const shapeCounts = new Map<string, Set<string>>();
   const anatomyCounts = new Map<string, Set<string>>();
+  const meta = new Map<string, { title?: string; version?: string }>();
 
   if (classResult.type === "select") {
     for (const b of classResult.bindings) {
       const uri = b.class ?? "";
-      const ns = findNamespace(uri, prefixEntries);
+      const ns = nsOf(uri);
       if (ns) {
-        const set = classCounts.get(ns.prefix) ?? new Set();
-        set.add(uri);
-        classCounts.set(ns.prefix, set);
-
-        if (isAnatomyTerm(uri)) {
-          const anatomySet = anatomyCounts.get(ns.prefix) ?? new Set();
-          anatomySet.add(uri);
-          anatomyCounts.set(ns.prefix, anatomySet);
-        }
+        add(classCounts, ns, uri);
+        if (isAnatomyTerm(uri)) add(anatomyCounts, ns, uri);
       }
     }
   }
@@ -67,35 +123,75 @@ export default async function listOntologies(
   if (propResult.type === "select") {
     for (const b of propResult.bindings) {
       const uri = b.prop ?? "";
-      const ns = findNamespace(uri, prefixEntries);
+      const ns = nsOf(uri);
       if (ns) {
-        const set = propCounts.get(ns.prefix) ?? new Set();
-        set.add(uri);
-        propCounts.set(ns.prefix, set);
-
-        if (isAnatomyTerm(uri)) {
-          const anatomySet = anatomyCounts.get(ns.prefix) ?? new Set();
-          anatomySet.add(uri);
-          anatomyCounts.set(ns.prefix, anatomySet);
-        }
+        const kind = b.propType?.includes("ObjectProperty")
+          ? relationCounts
+          : attributeCounts;
+        add(kind, ns, uri);
+        if (isAnatomyTerm(uri)) add(anatomyCounts, ns, uri);
+      }
+    }
+  }
+
+  if (shapeResult.type === "select") {
+    for (const b of shapeResult.bindings) {
+      // Same attribution as `ontology show`: a shape counts for the
+      // namespace of the shape itself or of its target class.
+      const ns = b.shape ? nsOf(b.shape) : undefined;
+      const targetNs = b.target ? nsOf(b.target) : undefined;
+      const owner = ns ?? targetNs;
+      if (owner && b.shape) add(shapeCounts, owner, b.shape);
+    }
+  }
+
+  if (metaResult.type === "select") {
+    for (const b of metaResult.bindings) {
+      const ns = b.ont ? nsOf(b.ont) : undefined;
+      if (ns && !meta.has(ns)) {
+        meta.set(ns, {
+          ...(b.title ? { title: b.title } : {}),
+          ...(b.version ? { version: b.version } : {}),
+        });
       }
     }
   }
 
-  const allPrefixes = new Set([
+  // A namespace that only contributes SHACL shapes still surfaces; one
+  // that only declares an owl:Ontology header (no terms at all) does not —
+  // an empty TBox is not a listable ontology.
+  const allNamespaces = new Set([
     ...classCounts.keys(),
-    ...propCounts.keys(),
+    ...relationCounts.keys(),
+    ...attributeCounts.keys(),
     ...anatomyCounts.keys(),
+    ...shapeCounts.keys(),
   ]);
 
-  return [...allPrefixes].sort().map((prefix) => {
-    const namespace = prefixEntries.find(([p]) => p === prefix)?.[1] ?? "";
+  const summaries = [...allNamespaces].map((namespace) => {
+    const prefix = prefixEntries.find(([, ns]) => ns === namespace)?.[0] ?? "";
+    const header = meta.get(namespace);
     return {
       prefix,
       namespace,
-      classCount: classCounts.get(prefix)?.size ?? 0,
-      propertyCount: propCounts.get(prefix)?.size ?? 0,
-      anatomyCount: anatomyCounts.get(prefix)?.size ?? 0,
+      ...(header?.title ? { title: header.title } : {}),
+      ...(header?.version ? { version: header.version } : {}),
+      classCount: classCounts.get(namespace)?.size ?? 0,
+      relationCount: relationCounts.get(namespace)?.size ?? 0,
+      attributeCount: attributeCounts.get(namespace)?.size ?? 0,
+      shapeCount: shapeCounts.get(namespace)?.size ?? 0,
+      anatomyCount: anatomyCounts.get(namespace)?.size ?? 0,
     };
   });
+
+  // Prefixed namespaces first (alphabetical), unprefixed after by URI.
+  return summaries.sort((a, b) =>
+    a.prefix && b.prefix
+      ? a.prefix.localeCompare(b.prefix)
+      : a.prefix
+        ? -1
+        : b.prefix
+          ? 1
+          : a.namespace.localeCompare(b.namespace),
+  );
 }

package/src/domains/ontology/operations/showOntology.test.ts

@@ -2,7 +2,7 @@ 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 { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import showOntology from "./showOntology.js";
 
 let store: Store;
@@ -17,31 +17,85 @@ beforeAll(async () => {
 afterAll(() => cleanup());
 
 describe("showOntology", () => {
-  it("returns classes and properties for a prefix", async () => {
+  it("returns classes with attached properties for a prefix", async () => {
     const result = await showOntology(store, "ds");
     expect(result.prefix).toBe("ds");
-    expect(result.namespace).toBe(PREFIX_MAP.ds);
+    expect(result.namespace).toBe(DEFAULT_PREFIX_MAP.ds);
     expect(result.classes.length).toBeGreaterThan(0);
-    expect(result.properties.length).toBeGreaterThan(0);
+
+    const uiBlock = result.classes.find((c) => c.iri === "ds:UIBlock");
+    expect(uiBlock).toBeDefined();
+    expect(uiBlock?.properties.map((p) => p.label)).toContain("name");
   });
 
-  it("includes class labels and superclass relationships", async () => {
+  it("preserves all subClassOf edges as compact IRIs", async () => {
     const result = await showOntology(store, "ds");
     const component = result.classes.find((c) => c.label === "Component");
     expect(component).toBeDefined();
-    expect(component?.superclass).toContain("UIBlock");
+    expect(component?.subClassOf).toContain("ds:UIBlock");
+  });
+
+  it("orders classes topologically (parents before children)", async () => {
+    const result = await showOntology(store, "ds");
+    const order = result.classes.map((c) => c.iri);
+    expect(order.indexOf("ds:UIBlock")).toBeLessThan(
+      order.indexOf("ds:Component"),
+    );
+  });
+
+  it("includes rdfs:comment when declared", async () => {
+    const result = await showOntology(store, "ds");
+    const component = result.classes.find((c) => c.iri === "ds:Component");
+    expect(component?.comment).toBe("A reusable UI building block.");
+  });
+
+  it("counts instances per class", async () => {
+    const result = await showOntology(store, "ds");
+    const component = result.classes.find((c) => c.iri === "ds:Component");
+    expect(component?.instances).toBeGreaterThan(0);
+  });
+
+  it("marks functional properties", async () => {
+    const result = await showOntology(store, "ds");
+    const uiBlock = result.classes.find((c) => c.iri === "ds:UIBlock");
+    const tier = uiBlock?.properties.find((p) => p.iri === "ds:tier");
+    expect(tier?.functional).toBe(true);
   });
 
-  it("includes property domain and range", async () => {
+  it("attaches property domain and range as compact IRIs", async () => {
     const result = await showOntology(store, "ds");
-    const nameProp = result.properties.find((p) => p.uri.endsWith("name"));
+    const uiBlock = result.classes.find((c) => c.iri === "ds:UIBlock");
+    const nameProp = uiBlock?.properties.find((p) => p.iri === "ds:name");
     expect(nameProp).toBeDefined();
-    expect(nameProp?.domain).toContain("UIBlock");
-    expect(nameProp?.type).toBe("datatype");
+    expect(nameProp?.domain).toBe("ds:UIBlock");
+    expect(nameProp?.kind).toBe("datatype");
+    expect(nameProp?.range).toBe("xsd:string");
+  });
+
+  it("emits a prefixes map covering the compact IRIs used", async () => {
+    const result = await showOntology(store, "ds");
+    expect(result.prefixes.ds).toBe(DEFAULT_PREFIX_MAP.ds);
+    expect(result.prefixes.xsd).toBeDefined();
+  });
+
+  it("surfaces the owl:Ontology header", async () => {
+    const result = await showOntology(store, "ds");
+    expect(result.meta?.title).toBe("Design System Ontology");
+    expect(result.meta?.version).toBe("0.1.0-test");
+  });
+
+  it("summarizes SHACL node shapes", async () => {
+    const result = await showOntology(store, "ds");
+    const shape = result.constraints?.find(
+      (c) => c.shape === "ds:ComponentShape",
+    );
+    expect(shape).toBeDefined();
+    expect(shape?.targetClass).toBe("ds:Component");
+    expect(shape?.propertyCount).toBe(2);
   });
 
   it("resolves full namespace URI", async () => {
-    const result = await showOntology(store, PREFIX_MAP.ds);
+    const result = await showOntology(store, DEFAULT_PREFIX_MAP.ds);
     expect(result.prefix).toBe("ds");
     expect(result.classes.length).toBeGreaterThan(0);
   });
@@ -59,7 +113,72 @@ describe("showOntology", () => {
   it("returns cs ontology with standard classes", async () => {
     const result = await showOntology(store, "cs");
     expect(result.prefix).toBe("cs");
-    const standard = result.classes.find((c) => c.uri.includes("CodeStandard"));
+    const standard = result.classes.find((c) => c.iri.includes("CodeStandard"));
     expect(standard).toBeDefined();
   });
 });
+
+describe("showOntology — class focus", () => {
+  it("deep-dives into a class by label", async () => {
+    const result = await showOntology(store, "ds", { class: "Component" });
+    const focus = result.focus;
+    expect(focus).toBeDefined();
+    expect(focus?.iri).toBe("ds:Component");
+    expect(focus?.superChain).toEqual(["ds:UIBlock"]);
+    expect(focus?.instances).toBeGreaterThan(0);
+  });
+
+  it("separates direct and inherited properties", async () => {
+    const result = await showOntology(store, "ds", { class: "Component" });
+    const inherited = result.focus?.inheritedProperties.map((p) => p.iri);
+    expect(inherited).toContain("ds:name");
+  });
+
+  it("finds reverse references (properties ranging over the class)", async () => {
+    const result = await showOntology(store, "ds", { class: "UIBlock" });
+    const refs = result.focus?.referencedBy.map((p) => p.iri);
+    expect(refs).toContain("ds:implementsBlock");
+  });
+
+  it("returns sample instance IRIs", async () => {
+    const result = await showOntology(store, "ds", { class: "Component" });
+    expect(result.focus?.sampleInstances.length).toBeGreaterThan(0);
+  });
+
+  it("emits runnable follow-up queries with compact IRIs", async () => {
+    const result = await showOntology(store, "ds", { class: "Component" });
+    const queries = result.focus?.queries ?? [];
+    expect(queries.length).toBeGreaterThan(0);
+    expect(queries[0]?.sparql).toBe(
+      "SELECT ?instance WHERE { ?instance a ds:Component } LIMIT 20",
+    );
+    // A sample-instance inspection query is included when instances exist.
+    expect(queries.some((q) => q.sparql.includes("?predicate ?object"))).toBe(
+      true,
+    );
+  });
+
+  it("accepts a compact IRI and a local name", async () => {
+    const byIri = await showOntology(store, "ds", { class: "ds:Component" });
+    expect(byIri.focus?.iri).toBe("ds:Component");
+
+    const byLocal = await showOntology(store, "ds", { class: "component" });
+    expect(byLocal.focus?.iri).toBe("ds:Component");
+  });
+
+  it("throws not-found with suggestions for an unknown class", async () => {
+    try {
+      await showOntology(store, "ds", { class: "Comp" });
+      expect.unreachable("should have thrown");
+    } catch (e) {
+      expect((e as PragmaError).code).toBe("ENTITY_NOT_FOUND");
+      expect((e as PragmaError).suggestions).toContain("Component");
+    }
+  });
+
+  it("still returns the full namespace structure alongside the focus", async () => {
+    const result = await showOntology(store, "ds", { class: "Component" });
+    expect(result.classes.length).toBeGreaterThan(0);
+    expect(result.focus).toBeDefined();
+  });
+});