@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/mcp/registerResources.ts

@@ -1,303 +1,9 @@
-import type { Store } from "@canonical/ke";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { PragmaError } from "#error";
-import { PROPERTY_MAP } from "../constants.js";
-import resolveUri from "../domains/graph/helpers/resolveUri.js";
-import { buildQuery } from "../domains/shared/buildQuery.js";
-import compactUri from "../domains/shared/compactUri.js";
-import type { PragmaRuntime } from "../domains/shared/runtime.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-interface PropertyValueLiteral {
-  readonly type: "literal";
-  readonly value: string;
-  readonly datatype?: string;
-}
-
-interface PropertyValueUri {
-  readonly type: "uri";
-  readonly uri: string;
-  readonly prefixed: string;
-  readonly label: string | null;
-}
-
-type PropertyValue = PropertyValueLiteral | PropertyValueUri;
-
-interface PropertyGroup {
-  readonly predicate: string;
-  readonly values: PropertyValue[];
-}
-
-interface ResourceEntity {
-  readonly uri: string;
-  readonly prefixed: string;
-  readonly types: string[];
-  readonly label: string | null;
-  readonly description: string | null;
-  readonly properties: PropertyGroup[];
-}
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-const RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
-
-/**
- * Determine the namespace prefix for a full URI.
- */
-function findPrefix(
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-): string | null {
-  for (const [prefix, namespace] of Object.entries(prefixes)) {
-    if (fullUri.startsWith(namespace)) return prefix;
-  }
-  return null;
-}
-
-/**
- * Fetch a single property value for a URI using the PROPERTY_MAP.
- */
-async function fetchProperty(
-  store: Store,
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-  field: "label" | "description",
-): Promise<string | null> {
-  const prefix = findPrefix(fullUri, prefixes);
-  if (!prefix) return null;
-
-  const propUri = PROPERTY_MAP[prefix]?.[field];
-  if (!propUri) return null;
-
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?val
-      WHERE { <${fullUri}> <${propUri}> ?val }
-      LIMIT 1
-    `),
-  );
-
-  if (result.type === "select" && result.bindings.length > 0) {
-    return result.bindings[0]?.val ?? null;
-  }
-  return null;
-}
-
-/**
- * Fetch the human-readable label for a URI using the PROPERTY_MAP.
- */
-async function fetchLabel(
-  store: Store,
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-): Promise<string | null> {
-  return fetchProperty(store, fullUri, prefixes, "label");
-}
-
-/**
- * Fetch the human-readable description for a URI using the PROPERTY_MAP.
- */
-async function fetchDescription(
-  store: Store,
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-): Promise<string | null> {
-  return fetchProperty(store, fullUri, prefixes, "description");
-}
-
 /**
- * Detect whether a SPARQL binding value is a URI or a literal.
- * URIs start with http:// or https:// or are prefixed; literals are everything else.
- */
-function isUri(value: string): boolean {
-  return (
-    value.startsWith("http://") ||
-    value.startsWith("https://") ||
-    value.startsWith("urn:")
-  );
-}
-
-/**
- * Enumerate all distinct subject URIs in the graph.
- */
-async function listAllSubjects(store: Store): Promise<string[]> {
-  const result = await store.query(
-    buildQuery("SELECT DISTINCT ?s WHERE { ?s ?p ?o } ORDER BY ?s"),
-  );
-
-  if (result.type !== "select") return [];
-  return result.bindings.map((b) => b.s ?? "").filter((s) => isUri(s));
-}
-
-/**
- * Read a single entity: all its triples with level-1 object summaries.
- */
-async function readEntity(
-  store: Store,
-  fullUri: string,
-  prefixes: Readonly<Record<string, string>>,
-): Promise<ResourceEntity> {
-  const result = await store.query(
-    buildQuery(`
-      SELECT ?p ?o
-      WHERE { <${fullUri}> ?p ?o }
-      ORDER BY ?p ?o
-    `),
-  );
-
-  if (result.type !== "select" || result.bindings.length === 0) {
-    throw PragmaError.notFound("entity", compactUri(fullUri, prefixes), {
-      recovery: {
-        message:
-          "Check the URI is correct and run a SPARQL query to find valid URIs.",
-        cli: "pragma graph query 'SELECT ?s WHERE { ?s ?p ?o } LIMIT 10'",
-        mcp: { tool: "graph_query" },
-      },
-    });
-  }
-
-  const types: string[] = [];
-  const groupMap = new Map<string, PropertyValue[]>();
-
-  for (const b of result.bindings) {
-    const predicate = b.p ?? "";
-    const object = b.o ?? "";
-
-    if (predicate === RDF_TYPE) {
-      types.push(compactUri(object, prefixes));
-      continue;
-    }
-
-    const compactPred = compactUri(predicate, prefixes);
-    const existing = groupMap.get(compactPred) ?? [];
-
-    if (isUri(object)) {
-      const label = await fetchLabel(store, object, prefixes);
-      existing.push({
-        type: "uri",
-        uri: object,
-        prefixed: compactUri(object, prefixes),
-        label,
-      });
-    } else {
-      existing.push({ type: "literal", value: object });
-    }
-
-    groupMap.set(compactPred, existing);
-  }
-
-  const [label, description] = await Promise.all([
-    fetchLabel(store, fullUri, prefixes),
-    fetchDescription(store, fullUri, prefixes),
-  ]);
-
-  const properties: PropertyGroup[] = [...groupMap.entries()].map(
-    ([predicate, values]) => ({ predicate, values }),
-  );
-
-  return {
-    uri: fullUri,
-    prefixed: compactUri(fullUri, prefixes),
-    types,
-    label,
-    description,
-    properties,
-  };
-}
-
-// =============================================================================
-// Registration
-// =============================================================================
-
-/**
- * Register graph-driven MCP resources on the server.
+ * Entry point for the MCP resource surface.
  *
- * Every subject URI in the ke graph becomes a discoverable MCP resource.
- * Reading a resource returns the entity's properties with level-1 object
- * relations resolved to summaries (label and description from PROPERTY_MAP).
- *
- * @param server - The MCP server to register resources on.
- * @param runtime - The pragma runtime providing the ke store and prefixes.
- *
- * @note Impure
+ * The implementation lives in `./resources/`, split across focused modules
+ * (index build, listing, autocomplete, reads). This file re-exports the
+ * registrar so existing importers keep a stable path.
  */
-export default function registerResources(
-  server: McpServer,
-  runtime: PragmaRuntime,
-): void {
-  const { store } = runtime;
-  const prefixes = store.prefixes;
-
-  const template = new ResourceTemplate("pragma:{+uri}", {
-    list: async () => {
-      const subjects = await listAllSubjects(store);
-      const resources = await Promise.all(
-        subjects.map(async (fullUri) => {
-          const prefixed = compactUri(fullUri, prefixes);
-          const label = await fetchLabel(store, fullUri, prefixes);
-          return {
-            uri: `pragma:${prefixed}`,
-            name: label ?? prefixed,
-            mimeType: "application/json" as const,
-          };
-        }),
-      );
-      return { resources };
-    },
-    complete: {
-      uri: async (value) => {
-        const subjects = await listAllSubjects(store);
-        const compacted = subjects.map((s) => compactUri(s, prefixes));
-        return compacted.filter((p) =>
-          p.toLowerCase().startsWith(value.toLowerCase()),
-        );
-      },
-    },
-  });
 
-  server.registerResource(
-    "graph-entity",
-    template,
-    {
-      description:
-        "An entity in the pragma knowledge graph. Returns all properties with level-1 relation summaries.",
-      mimeType: "application/json",
-    },
-    async (url, variables) => {
-      try {
-        const prefixedUri = variables.uri as string;
-        const fullUri = resolveUri(prefixedUri, prefixes);
-        const entity = await readEntity(store, fullUri, prefixes);
-        return {
-          contents: [
-            {
-              uri: url.href,
-              mimeType: "application/json",
-              text: JSON.stringify(entity, null, 2),
-            },
-          ],
-        };
-      } catch (error) {
-        const message =
-          error instanceof PragmaError
-            ? JSON.stringify({ code: error.code, message: error.message })
-            : String(error);
-        return {
-          contents: [
-            {
-              uri: url.href,
-              mimeType: "text/plain",
-              text: message,
-            },
-          ],
-        };
-      }
-    },
-  );
-}
+export { default } from "./resources/registerResources.js";

package/src/mcp/resources/buildGraphIndex.ts

@@ -0,0 +1,167 @@
+import type { Store } from "@canonical/ke";
+import findNamespace from "../../domains/ontology/helpers/findNamespace.js";
+import { buildQuery } from "../../domains/shared/buildQuery.js";
+import compactUri from "../../domains/shared/compactUri.js";
+import extractLocalName from "../../domains/shared/extractLocalName.js";
+import classifyEntity from "./classifyEntity.js";
+import { RDF_TYPE } from "./constants.js";
+import {
+  collectDescriptionPredicates,
+  collectLabelPredicates,
+  resolveDescriptionPredicates,
+  resolveLabelPredicates,
+} from "./displayPredicates.js";
+import pickFirstValue from "./pickFirstValue.js";
+import pickPrimaryType from "./pickPrimaryType.js";
+import type { GraphEntity, GraphIndex } from "./types.js";
+
+/** A per-subject map of predicate URI → asserted lexical values. */
+type ValuesBySubject = Map<string, Map<string, string[]>>;
+
+/** Wrap full URIs as a SPARQL `VALUES` list body. */
+function toValuesList(uris: readonly string[]): string {
+  return [...new Set(uris)].map((uri) => `<${uri}>`).join(" ");
+}
+
+/**
+ * Run one `?s ?p ?v` bulk query restricted to the given predicates and
+ * collect values per named-node subject. Blank-node subjects are skipped —
+ * they are never listed as resources.
+ *
+ * @note Queries ke store
+ */
+async function fetchValuesBySubject(
+  store: Store,
+  predicates: readonly string[],
+): Promise<ValuesBySubject> {
+  const bySubject: ValuesBySubject = new Map();
+  if (predicates.length === 0) return bySubject;
+
+  const result = await store.query(
+    buildQuery(
+      `SELECT ?s ?p ?v WHERE { ?s ?p ?v . VALUES ?p { ${toValuesList(predicates)} } }`,
+    ),
+  );
+  if (result.type !== "select") return bySubject;
+
+  for (const term of result.termBindings) {
+    if (term.s?.termType !== "NamedNode") continue;
+    const subject = term.s.value;
+    const predicate = term.p?.value ?? "";
+    const value = term.v?.value ?? "";
+    const byPredicate = bySubject.get(subject) ?? new Map<string, string[]>();
+    const values = byPredicate.get(predicate) ?? [];
+    values.push(value);
+    byPredicate.set(predicate, values);
+    bySubject.set(subject, byPredicate);
+  }
+  return bySubject;
+}
+
+/**
+ * Build the in-memory graph index used by listing, autocomplete, and reads.
+ *
+ * Replaces the former per-subject label/type/description queries with three
+ * bulk queries — one for types, one for labels, one for descriptions — joined
+ * in memory. Only typed named-node subjects are indexed; untyped subjects and
+ * blank nodes are reachable via `graph_query` but are not listed as resources.
+ *
+ * @param store - The ke store to query.
+ * @param prefixes - The store's merged prefix map.
+ * @returns The classified entities plus label and instance-count lookups.
+ *
+ * @note Queries ke store
+ */
+export default async function buildGraphIndex(
+  store: Store,
+  prefixes: Readonly<Record<string, string>>,
+): Promise<GraphIndex> {
+  const prefixEntries = Object.entries(prefixes);
+
+  const [typesResult, labelValues, descriptionValues] = await Promise.all([
+    store.query(buildQuery(`SELECT ?s ?type WHERE { ?s <${RDF_TYPE}> ?type }`)),
+    fetchValuesBySubject(store, collectLabelPredicates()),
+    fetchValuesBySubject(store, collectDescriptionPredicates()),
+  ]);
+
+  const typesBySubject = new Map<string, string[]>();
+  const instanceCountByType = new Map<string, number>();
+  if (typesResult.type === "select") {
+    for (const term of typesResult.termBindings) {
+      if (term.s?.termType !== "NamedNode") continue;
+      const subject = term.s.value;
+      const typeUri = term.type?.value ?? "";
+      const types = typesBySubject.get(subject) ?? [];
+      types.push(typeUri);
+      typesBySubject.set(subject, types);
+      instanceCountByType.set(
+        typeUri,
+        (instanceCountByType.get(typeUri) ?? 0) + 1,
+      );
+    }
+  }
+
+  // Phase 1: resolve every subject's label and description so that a class
+  // label is available before any individual that references it is built.
+  interface ResolvedSubject {
+    readonly subject: string;
+    readonly fullTypes: string[];
+    readonly box: GraphEntity["box"];
+    readonly category: GraphEntity["category"];
+    readonly label: string | null;
+    readonly description: string | null;
+  }
+
+  const labelByUri = new Map<string, string>();
+  const resolved: ResolvedSubject[] = [];
+
+  for (const [subject, fullTypes] of typesBySubject) {
+    const classification = classifyEntity(fullTypes);
+    if (classification === null) continue;
+
+    const prefix = findNamespace(subject, prefixEntries)?.prefix;
+    const label = pickFirstValue(
+      labelValues.get(subject) ?? new Map(),
+      resolveLabelPredicates(prefix),
+    );
+    const description = pickFirstValue(
+      descriptionValues.get(subject) ?? new Map(),
+      resolveDescriptionPredicates(prefix),
+    );
+    if (label !== null) labelByUri.set(subject, label);
+
+    resolved.push({
+      subject,
+      fullTypes,
+      box: classification.box,
+      category: classification.category,
+      label,
+      description,
+    });
+  }
+
+  // Phase 2: build entities, resolving each individual's grouping label from
+  // the now-complete label lookup.
+  const entities: GraphEntity[] = resolved.map((r) => {
+    const primaryTypeFull =
+      r.category === "individual" ? pickPrimaryType(r.fullTypes) : null;
+    return {
+      uri: r.subject,
+      prefixed: compactUri(r.subject, prefixes),
+      box: r.box,
+      category: r.category,
+      types: r.fullTypes.map((t) => compactUri(t, prefixes)),
+      primaryType:
+        primaryTypeFull === null ? null : compactUri(primaryTypeFull, prefixes),
+      primaryTypeLabel:
+        primaryTypeFull === null
+          ? null
+          : (labelByUri.get(primaryTypeFull) ??
+            extractLocalName(primaryTypeFull)),
+      label: r.label,
+      description: r.description,
+    };
+  });
+
+  return { entities, labelByUri, instanceCountByType };
+}

package/src/mcp/resources/buildResourceList.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import buildResourceList from "./buildResourceList.js";
+import { ABOX_PER_CLASS_LIMIT } from "./constants.js";
+import type { GraphEntity, GraphIndex } from "./types.js";
+
+const gadgetClass: GraphEntity = {
+  uri: "https://ds.canonical.com/Gadget",
+  prefixed: "ds:Gadget",
+  box: "tbox",
+  category: "class",
+  types: ["owl:Class"],
+  primaryType: null,
+  primaryTypeLabel: null,
+  label: "Gadget",
+  description: null,
+};
+
+const nameProperty: GraphEntity = {
+  uri: "https://ds.canonical.com/name",
+  prefixed: "ds:name",
+  box: "tbox",
+  category: "property",
+  types: ["owl:DatatypeProperty"],
+  primaryType: null,
+  primaryTypeLabel: null,
+  label: null,
+  description: null,
+};
+
+function makeIndividual(n: number): GraphEntity {
+  return {
+    uri: `https://ds.canonical.com/w${n}`,
+    prefixed: `ds:w${n}`,
+    box: "abox",
+    category: "individual",
+    types: ["ds:Gadget"],
+    primaryType: "ds:Gadget",
+    primaryTypeLabel: "Gadget",
+    label: `Widget ${n}`,
+    description: null,
+  };
+}
+
+function makeIndex(entities: GraphEntity[]): GraphIndex {
+  return { entities, labelByUri: new Map(), instanceCountByType: new Map() };
+}
+
+function boxOf(resource: { _meta: Record<string, unknown> }): unknown {
+  return resource._meta["pragma/box"];
+}
+
+describe("buildResourceList", () => {
+  it("orders all TBox schema before any ABox individual", () => {
+    const index = makeIndex([makeIndividual(0), nameProperty, gadgetClass]);
+    const boxes = buildResourceList(index).resources.map(boxOf);
+    expect(boxes.slice(0, 2)).toEqual(["tbox", "tbox"]);
+    expect(boxes.at(-1)).toBe("abox");
+  });
+
+  it("caps individuals per class and records the dropped remainder", () => {
+    const overflow = ABOX_PER_CLASS_LIMIT + 7;
+    const individuals = Array.from({ length: overflow }, (_, i) =>
+      makeIndividual(i),
+    );
+    const { resources, truncation } = buildResourceList(
+      makeIndex([gadgetClass, ...individuals]),
+    );
+
+    const shown = resources.filter((r) => boxOf(r) === "abox");
+    expect(shown).toHaveLength(ABOX_PER_CLASS_LIMIT);
+    expect(truncation.totalDropped).toBe(7);
+    expect(truncation.droppedByType.get("ds:Gadget")).toBe(7);
+
+    const cls = resources.find((r) => r.uri === "ds:Gadget");
+    expect(cls?._meta["pragma/instanceCount"]).toBe(overflow);
+    expect(cls?._meta["pragma/instancesShown"]).toBe(ABOX_PER_CLASS_LIMIT);
+    expect(cls?._meta["pragma/truncated"]).toBe(true);
+  });
+
+  it("reports no truncation when under the cap", () => {
+    const { truncation } = buildResourceList(
+      makeIndex([gadgetClass, makeIndividual(0)]),
+    );
+    expect(truncation.totalDropped).toBe(0);
+  });
+
+  it("assigns higher annotation priority to classes than individuals", () => {
+    const { resources } = buildResourceList(
+      makeIndex([gadgetClass, makeIndividual(0)]),
+    );
+    const cls = resources.find((r) => r.uri === "ds:Gadget");
+    const individual = resources.find((r) => r.uri === "ds:w0");
+    expect(cls?.annotations.priority).toBeGreaterThan(
+      individual?.annotations.priority ?? 1,
+    );
+  });
+});