@canonical/pragma-cli 0.30.0 → 0.31.0

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

@@ -1,7 +1,21 @@
 /** @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";

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

@@ -2,49 +2,65 @@ import type { Store } from "@canonical/ke";
 import { buildQuery } from "../../shared/buildQuery.js";
 import extractLocalName from "../../shared/extractLocalName.js";
 import { P } from "../../shared/prefixes.js";
-import type { OntologyClass } from "../../shared/types/index.js";
+
+/** A class row as stored — full URIs, all superclass edges preserved. */
+export interface RawOntologyClass {
+  readonly uri: string;
+  readonly label: string;
+  readonly comment?: string;
+  readonly subClassOf: readonly string[];
+}
 
 /**
- * Queries all `owl:Class` definitions within a namespace.
- *
- * Deduplicates by class URI -- when a class has multiple `rdfs:subClassOf`
- * values, only the first superclass encountered is kept.
+ * Queries all `owl:Class` definitions within a namespace, including their
+ * `rdfs:comment` and **every** `rdfs:subClassOf` edge (multiple inheritance
+ * is preserved; downstream renderers decide tree placement).
  *
  * @note Queries ke store
  *
  * @param store - The ke store to query.
  * @param namespace - The namespace URI to filter classes by.
- * @returns An array of {@link OntologyClass} entries.
+ * @returns An array of {@link RawOntologyClass} entries, one per class.
  */
 export default async function queryClasses(
   store: Store,
   namespace: string,
-): Promise<OntologyClass[]> {
+): Promise<RawOntologyClass[]> {
   const result = await store.query(
     buildQuery(`
-      SELECT ?class ?label ?superclass
+      SELECT ?class ?label ?comment ?superclass
       WHERE {
         ?class a ${P.owl}Class .
         FILTER(STRSTARTS(STR(?class), "${namespace}"))
         OPTIONAL { ?class ${P.rdfs}label ?label }
+        OPTIONAL { ?class ${P.rdfs}comment ?comment }
         OPTIONAL { ?class ${P.rdfs}subClassOf ?superclass }
       }
-      ORDER BY ?class
+      ORDER BY ?class ?superclass
     `),
   );
 
   if (result.type !== "select") return [];
 
-  const seen = new Map<string, OntologyClass>();
+  const seen = new Map<
+    string,
+    { label: string; comment?: string; supers: Set<string> }
+  >();
   for (const b of result.bindings) {
     const uri = b.class ?? "";
-    if (seen.has(uri)) continue;
-    seen.set(uri, {
-      uri,
+    const entry = seen.get(uri) ?? {
       label: b.label ?? extractLocalName(uri),
-      ...(b.superclass ? { superclass: b.superclass } : {}),
-    });
+      ...(b.comment ? { comment: b.comment } : {}),
+      supers: new Set<string>(),
+    };
+    if (b.superclass) entry.supers.add(b.superclass);
+    seen.set(uri, entry);
   }
 
-  return [...seen.values()];
+  return [...seen.entries()].map(([uri, entry]) => ({
+    uri,
+    label: entry.label,
+    ...(entry.comment ? { comment: entry.comment } : {}),
+    subClassOf: [...entry.supers].sort(),
+  }));
 }

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

@@ -2,11 +2,20 @@ import type { Store } from "@canonical/ke";
 import { buildQuery } from "../../shared/buildQuery.js";
 import extractLocalName from "../../shared/extractLocalName.js";
 import { P } from "../../shared/prefixes.js";
-import type { OntologyProperty } from "../../shared/types/index.js";
+
+/** A property row as stored — full URIs. */
+export interface RawOntologyProperty {
+  readonly uri: string;
+  readonly label: string;
+  readonly kind: "object" | "datatype";
+  readonly domain?: string;
+  readonly range?: string;
+  readonly functional: boolean;
+}
 
 /**
  * Queries all `owl:ObjectProperty` and `owl:DatatypeProperty` definitions
- * within a namespace.
+ * within a namespace, marking those also typed `owl:FunctionalProperty`.
  *
  * Deduplicates by property URI -- when a property has multiple `rdfs:domain`
  * or `rdfs:range` values, only the first encountered is kept.
@@ -15,12 +24,12 @@ import type { OntologyProperty } from "../../shared/types/index.js";
  *
  * @param store - The ke store to query.
  * @param namespace - The namespace URI to filter properties by.
- * @returns An array of {@link OntologyProperty} entries.
+ * @returns An array of {@link RawOntologyProperty} entries.
  */
 export default async function queryProperties(
   store: Store,
   namespace: string,
-): Promise<OntologyProperty[]> {
+): Promise<RawOntologyProperty[]> {
   const result = await store.query(
     buildQuery(`
       SELECT ?prop ?label ?domain ?range ?propType
@@ -38,7 +47,9 @@ export default async function queryProperties(
 
   if (result.type !== "select") return [];
 
-  const seen = new Map<string, OntologyProperty>();
+  const functional = await queryFunctionalProperties(store, namespace);
+
+  const seen = new Map<string, RawOntologyProperty>();
   for (const b of result.bindings) {
     const uri = b.prop ?? "";
     if (seen.has(uri)) continue;
@@ -47,11 +58,33 @@ export default async function queryProperties(
       label: b.label ?? extractLocalName(uri),
       ...(b.domain ? { domain: b.domain } : {}),
       ...(b.range ? { range: b.range } : {}),
-      type: b.propType?.includes("ObjectProperty")
+      kind: b.propType?.includes("ObjectProperty")
         ? ("object" as const)
         : ("datatype" as const),
+      functional: functional.has(uri),
     });
   }
 
   return [...seen.values()];
 }
+
+/** URIs within the namespace typed `owl:FunctionalProperty`. */
+async function queryFunctionalProperties(
+  store: Store,
+  namespace: string,
+): Promise<Set<string>> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?prop
+      WHERE {
+        ?prop a ${P.owl}FunctionalProperty .
+        FILTER(STRSTARTS(STR(?prop), "${namespace}"))
+      }
+    `),
+  );
+
+  if (result.type !== "select") return new Set();
+  return new Set(
+    result.bindings.map((b) => b.prop).filter((p): p is string => Boolean(p)),
+  );
+}

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

@@ -0,0 +1,160 @@
+/**
+ * Supplementary TBox queries for `ontology show` — instance counts, SHACL
+ * shape summaries, the owl:Ontology header, and per-class sample instances.
+ *
+ * Kept together because each is a single small SELECT feeding the one
+ * {@link OntologyDetailed} structure the show operation assembles.
+ *
+ * @note Every function queries the ke store.
+ */
+
+import type { Store } from "@canonical/ke";
+import { buildQuery } from "../../shared/buildQuery.js";
+import { P } from "../../shared/prefixes.js";
+
+const SH = "http://www.w3.org/ns/shacl#";
+
+/**
+ * Count instances per class within a namespace.
+ *
+ * One `GROUP BY ?type` query for the whole namespace — never per class.
+ *
+ * @returns Map from full class URI to instance count.
+ */
+export async function queryInstanceCounts(
+  store: Store,
+  namespace: string,
+): Promise<ReadonlyMap<string, number>> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?type (COUNT(?s) AS ?n)
+      WHERE {
+        ?s a ?type .
+        FILTER(STRSTARTS(STR(?type), "${namespace}"))
+      }
+      GROUP BY ?type
+    `),
+  );
+
+  if (result.type !== "select") return new Map();
+
+  const counts = new Map<string, number>();
+  for (const b of result.bindings) {
+    if (b.type && b.n) counts.set(b.type, Number(b.n));
+  }
+  return counts;
+}
+
+/** A SHACL node-shape summary row — full URIs. */
+export interface RawConstraint {
+  readonly shape: string;
+  readonly targetClass?: string;
+  readonly propertyCount: number;
+}
+
+/**
+ * Summarize `sh:NodeShape`s whose shape or target class lives in the
+ * namespace: target class and number of property constraints.
+ */
+export async function queryConstraints(
+  store: Store,
+  namespace: string,
+): Promise<RawConstraint[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?shape ?target (COUNT(?p) AS ?n)
+      WHERE {
+        ?shape a <${SH}NodeShape> .
+        OPTIONAL { ?shape <${SH}targetClass> ?target }
+        OPTIONAL { ?shape <${SH}property> ?p }
+        FILTER(
+          STRSTARTS(STR(?shape), "${namespace}") ||
+          STRSTARTS(STR(?target), "${namespace}")
+        )
+      }
+      GROUP BY ?shape ?target
+      ORDER BY ?shape
+    `),
+  );
+
+  if (result.type !== "select") return [];
+
+  return result.bindings
+    .filter((b) => Boolean(b.shape))
+    .map((b) => ({
+      shape: b.shape as string,
+      ...(b.target ? { targetClass: b.target } : {}),
+      propertyCount: Number(b.n ?? 0),
+    }));
+}
+
+/** owl:Ontology header row — full URIs. */
+export interface RawOntologyMeta {
+  readonly title?: string;
+  readonly version?: string;
+  readonly imports: readonly string[];
+}
+
+/**
+ * Read the `owl:Ontology` header declared in a namespace, when present:
+ * title (rdfs:label), version (owl:versionInfo), and owl:imports.
+ */
+export async function queryOntologyMeta(
+  store: Store,
+  namespace: string,
+): Promise<RawOntologyMeta | undefined> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?ont ?title ?version ?import
+      WHERE {
+        ?ont a ${P.owl}Ontology .
+        FILTER(STRSTARTS(STR(?ont), "${namespace}"))
+        OPTIONAL { ?ont ${P.rdfs}label ?title }
+        OPTIONAL { ?ont ${P.owl}versionInfo ?version }
+        OPTIONAL { ?ont ${P.owl}imports ?import }
+      }
+      ORDER BY ?ont
+    `),
+  );
+
+  if (result.type !== "select" || result.bindings.length === 0) {
+    return undefined;
+  }
+
+  const first = result.bindings[0] as (typeof result.bindings)[number];
+  const imports = [
+    ...new Set(
+      result.bindings
+        .map((b) => b.import)
+        .filter((i): i is string => Boolean(i)),
+    ),
+  ].sort();
+
+  return {
+    ...(first.title ? { title: first.title } : {}),
+    ...(first.version ? { version: first.version } : {}),
+    imports,
+  };
+}
+
+/**
+ * Fetch up to `limit` instance URIs of a class, as concrete entry points
+ * for `graph inspect` and domain lookups.
+ */
+export async function querySampleInstances(
+  store: Store,
+  classUri: string,
+  limit = 3,
+): Promise<string[]> {
+  const result = await store.query(
+    buildQuery(`
+      SELECT ?s
+      WHERE { ?s a <${classUri}> }
+      ORDER BY ?s
+      LIMIT ${limit}
+    `),
+  );
+
+  if (result.type !== "select") return [];
+  return result.bindings.map((b) => b.s).filter((s): s is string => Boolean(s));
+}

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

@@ -1,7 +1,7 @@
 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 { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import listOntologies from "./listOntologies.js";
 
 let store: Store;
@@ -22,12 +22,36 @@ describe("listOntologies", () => {
 
     const ds = result.find((o) => o.prefix === "ds");
     expect(ds).toBeDefined();
-    expect(ds?.namespace).toBe(PREFIX_MAP.ds);
+    expect(ds?.namespace).toBe(DEFAULT_PREFIX_MAP.ds);
     expect(ds?.classCount).toBeGreaterThan(0);
-    expect(ds?.propertyCount).toBeGreaterThan(0);
+    expect(ds?.relationCount).toBeGreaterThan(0);
+    expect(ds?.attributeCount).toBeGreaterThan(0);
     expect(ds?.anatomyCount).toBeGreaterThan(0);
   });
 
+  it("splits relations from attributes", async () => {
+    const result = await listOntologies(store);
+    const ds = result.find((o) => o.prefix === "ds");
+    // ds:tier is an object property; ds:name is a datatype property.
+    expect(ds?.relationCount).toBeGreaterThan(0);
+    expect(ds?.attributeCount).toBeGreaterThan(0);
+  });
+
+  it("carries the owl:Ontology header and SHACL shape count", async () => {
+    const result = await listOntologies(store);
+    const ds = result.find((o) => o.prefix === "ds");
+    expect(ds?.title).toBe("Design System Ontology");
+    expect(ds?.version).toBe("0.1.0-test");
+    expect(ds?.shapeCount).toBeGreaterThan(0);
+  });
+
+  it("omits header fields for namespaces without an owl:Ontology node", async () => {
+    const result = await listOntologies(store);
+    const cs = result.find((o) => o.prefix === "cs");
+    expect(cs?.title).toBeUndefined();
+    expect(cs?.version).toBeUndefined();
+  });
+
   it("includes cs namespace", async () => {
     const result = await listOntologies(store);
     const cs = result.find((o) => o.prefix === "cs");
@@ -36,6 +60,59 @@ describe("listOntologies", () => {
     expect(cs?.anatomyCount).toBe(0);
   });
 
+  it("lists namespaces without a registered prefix", async () => {
+    const scoped = await createTestStore({
+      ttl: `@prefix owl: <http://www.w3.org/2002/07/owl#> .
+<http://unprefixed.example.org/ontology#Widget> a owl:Class .
+<http://unprefixed.example.org/ontology#partOf> a owl:ObjectProperty .`,
+    });
+    try {
+      const result = await listOntologies(scoped.store);
+      const anon = result.find(
+        (o) => o.namespace === "http://unprefixed.example.org/ontology#",
+      );
+      expect(anon).toBeDefined();
+      expect(anon?.prefix).toBe("");
+      expect(anon?.classCount).toBe(1);
+      expect(anon?.relationCount).toBe(1);
+    } finally {
+      scoped.cleanup();
+    }
+  });
+
+  it("derives namespaces from short path-only URIs", async () => {
+    const scoped = await createTestStore({
+      ttl: `@prefix owl: <http://www.w3.org/2002/07/owl#> .
+<http://a/b> a owl:Class .`,
+    });
+    try {
+      const result = await listOntologies(scoped.store);
+      expect(result.find((o) => o.namespace === "http://a/")?.classCount).toBe(
+        1,
+      );
+    } finally {
+      scoped.cleanup();
+    }
+  });
+
+  it("lists a namespace that only contributes SHACL shapes", async () => {
+    const scoped = await createTestStore({
+      ttl: `@prefix sh: <http://www.w3.org/ns/shacl#> .
+<http://shapes.example.org/ontology#OnlyShape> a sh:NodeShape .`,
+    });
+    try {
+      const result = await listOntologies(scoped.store);
+      const shapeOnly = result.find(
+        (o) => o.namespace === "http://shapes.example.org/ontology#",
+      );
+      expect(shapeOnly).toBeDefined();
+      expect(shapeOnly?.shapeCount).toBe(1);
+      expect(shapeOnly?.classCount).toBe(0);
+    } finally {
+      scoped.cleanup();
+    }
+  });
+
   it("returns sorted by prefix", async () => {
     const result = await listOntologies(store);
     const prefixes = result.map((o) => o.prefix);

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),
+  );
 }