@canonical/pragma-cli 0.29.0 → 0.31.0

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/mcp/specs.ts

@@ -1,93 +1,16 @@
 /**
- * MCP tool specs for the ontology domain.
+ * MCP tool specs for the ontology domain — ontology_list and
+ * ontology_show, compiled from the ontology read stories in
+ * `../stories.ts` so both surfaces share formatters and resolution.
  */
 
+import { compileReadTool } from "../../shared/stories/index.js";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { listOntologies, showOntology } from "../operations/index.js";
+import { ontologyListStory, ontologyShowStory } from "../stories.js";
 
 const specs: readonly ToolSpec[] = [
-  {
-    name: "ontology_list",
-    description:
-      "List all ontologies loaded in the knowledge graph with class and property counts.",
-    params: {
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { condensed }) {
-      const result = await listOntologies(rt.store);
-
-      if (condensed) {
-        const lines = ["## Ontologies", ""];
-        for (const o of result) {
-          lines.push(
-            `- **${o.prefix}:** (${o.namespace}) | classes: ${o.classCount} | properties: ${o.propertyCount}`,
-          );
-        }
-        const text = lines.join("\n");
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result, meta: { count: result.length } };
-    },
-  },
-  {
-    name: "ontology_show",
-    description:
-      "Show detailed schema for an ontology including classes and properties.",
-    params: {
-      prefix: {
-        type: "string",
-        description: "Ontology prefix (e.g. 'ds', 'cs')",
-        optional: false,
-      },
-      condensed: {
-        type: "boolean",
-        description: "Token-optimized output",
-        optional: true,
-      },
-    },
-    readOnly: true,
-    async execute(rt, { prefix, condensed }) {
-      const result = await showOntology(rt.store, prefix as string);
-
-      if (condensed) {
-        const lines = [`## ${result.prefix}: (${result.namespace})`, ""];
-        if (result.classes.length > 0) {
-          lines.push("### Classes");
-          for (const c of result.classes) {
-            const sup = c.superclass ? ` extends ${c.superclass}` : "";
-            lines.push(`- **${c.label}**${sup}`);
-          }
-          lines.push("");
-        }
-        if (result.properties.length > 0) {
-          lines.push("### Properties");
-          for (const p of result.properties) {
-            const domain = p.domain ? ` domain: ${p.domain}` : "";
-            const range = p.range ? ` range: ${p.range}` : "";
-            lines.push(`- **${p.label}** (${p.type})${domain}${range}`);
-          }
-        }
-        const text = lines.join("\n");
-        return {
-          condensed: true,
-          text,
-          tokens: `~${Math.ceil(text.length / 4)}`,
-        };
-      }
-
-      return { data: result };
-    },
-  },
+  compileReadTool(ontologyListStory),
+  compileReadTool(ontologyShowStory),
 ];
 
 export default specs;

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);