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

package/src/mcp/resources/buildResourceList.ts

@@ -0,0 +1,176 @@
+import extractLocalName from "../../domains/shared/extractLocalName.js";
+import {
+  ABOX_PER_CLASS_LIMIT,
+  ABOX_TOTAL_LIMIT,
+  CLASS_PRIORITY,
+  INDIVIDUAL_PRIORITY,
+  NAME_SEPARATOR,
+  PROPERTY_PRIORITY,
+  RESOURCE_META_KEYS,
+} from "./constants.js";
+import type {
+  GraphEntity,
+  GraphIndex,
+  ListedResource,
+  ResourceListing,
+} from "./types.js";
+
+/** Longest description surfaced in a listing entry before truncation. */
+const DESCRIPTION_MAX = 120;
+
+/** Human-facing display name for an entity: its label, else its local name. */
+function toDisplayName(entity: GraphEntity): string {
+  return entity.label ?? extractLocalName(entity.uri);
+}
+
+/** Truncate a description to a listing-friendly length. */
+function toShortDescription(text: string): string {
+  return text.length > DESCRIPTION_MAX
+    ? `${text.slice(0, DESCRIPTION_MAX - 3)}...`
+    : text;
+}
+
+/** Sort entities by display name for stable, legible ordering. */
+function byDisplayName(a: GraphEntity, b: GraphEntity): number {
+  return toDisplayName(a).localeCompare(toDisplayName(b));
+}
+
+/** Build the listing entry for a TBox class, carrying its individual counts. */
+function toClassResource(
+  entity: GraphEntity,
+  instanceCount: number,
+  instancesShown: number,
+): ListedResource {
+  const truncated = instancesShown < instanceCount;
+  const description = truncated
+    ? `Schema class · showing ${instancesShown} of ${instanceCount} individuals; use autocomplete or graph_query for the rest`
+    : `Schema class · ${instanceCount} individual${instanceCount === 1 ? "" : "s"}`;
+  return {
+    uri: entity.prefixed,
+    name: `Class${NAME_SEPARATOR}${toDisplayName(entity)}`,
+    description,
+    mimeType: "application/json",
+    annotations: { audience: ["assistant"], priority: CLASS_PRIORITY },
+    _meta: {
+      [RESOURCE_META_KEYS.box]: "tbox",
+      [RESOURCE_META_KEYS.category]: "class",
+      [RESOURCE_META_KEYS.instanceCount]: instanceCount,
+      [RESOURCE_META_KEYS.instancesShown]: instancesShown,
+      [RESOURCE_META_KEYS.truncated]: truncated,
+    },
+  };
+}
+
+/** Build the listing entry for a TBox property. */
+function toPropertyResource(entity: GraphEntity): ListedResource {
+  const construct = entity.types.find((t) => t.endsWith("Property"));
+  const description = construct
+    ? `Schema property · ${construct}`
+    : "Schema property";
+  return {
+    uri: entity.prefixed,
+    name: `Property${NAME_SEPARATOR}${toDisplayName(entity)}`,
+    description,
+    mimeType: "application/json",
+    annotations: { audience: ["assistant"], priority: PROPERTY_PRIORITY },
+    _meta: {
+      [RESOURCE_META_KEYS.box]: "tbox",
+      [RESOURCE_META_KEYS.category]: "property",
+    },
+  };
+}
+
+/** Build the listing entry for an ABox individual, grouped under its class. */
+function toIndividualResource(entity: GraphEntity): ListedResource {
+  const group = entity.primaryTypeLabel ?? "Individual";
+  const summary = entity.description
+    ? toShortDescription(entity.description)
+    : null;
+  const description = summary ? `${group}${NAME_SEPARATOR}${summary}` : group;
+  return {
+    uri: entity.prefixed,
+    name: `${group}${NAME_SEPARATOR}${toDisplayName(entity)}`,
+    description,
+    mimeType: "application/json",
+    annotations: { audience: ["assistant"], priority: INDIVIDUAL_PRIORITY },
+    _meta: {
+      [RESOURCE_META_KEYS.box]: "abox",
+      [RESOURCE_META_KEYS.category]: "individual",
+      [RESOURCE_META_KEYS.type]: entity.primaryType ?? null,
+    },
+  };
+}
+
+/**
+ * Build the ordered, categorized, capped MCP resource listing from the index.
+ *
+ * TBox schema comes first and in full (classes, then properties) so a consumer
+ * sees the schema without scrolling past every instance. ABox individuals
+ * follow, grouped by class and sorted, capped per class ({@link
+ * ABOX_PER_CLASS_LIMIT}) and overall ({@link ABOX_TOTAL_LIMIT}). Dropped
+ * individuals are reported in the returned {@link ResourceListing.truncation}
+ * and reflected in each class entry's count metadata — never silently lost.
+ *
+ * @param index - The graph index of classified subjects.
+ * @returns The resource entries and a summary of any capping.
+ */
+export default function buildResourceList(index: GraphIndex): ResourceListing {
+  const classes = index.entities
+    .filter((e) => e.category === "class")
+    .sort(byDisplayName);
+  const properties = index.entities
+    .filter((e) => e.category === "property")
+    .sort(byDisplayName);
+  const individuals = index.entities.filter((e) => e.category === "individual");
+
+  const groups = new Map<string, GraphEntity[]>();
+  for (const individual of individuals) {
+    const key = individual.primaryType ?? "";
+    const bucket = groups.get(key) ?? [];
+    bucket.push(individual);
+    groups.set(key, bucket);
+  }
+
+  const orderedKeys = [...groups.keys()].sort((a, b) => a.localeCompare(b));
+  const shownByType = new Map<string, number>();
+  const droppedByType = new Map<string, number>();
+  const individualResources: ListedResource[] = [];
+  let totalShown = 0;
+
+  for (const key of orderedKeys) {
+    const bucket = (groups.get(key) ?? []).sort(byDisplayName);
+    let groupShown = 0;
+    for (const individual of bucket) {
+      const atGlobalCap = totalShown >= ABOX_TOTAL_LIMIT;
+      const atClassCap = groupShown >= ABOX_PER_CLASS_LIMIT;
+      if (atGlobalCap || atClassCap) {
+        droppedByType.set(key, (droppedByType.get(key) ?? 0) + 1);
+        continue;
+      }
+      individualResources.push(toIndividualResource(individual));
+      groupShown += 1;
+      totalShown += 1;
+    }
+    shownByType.set(key, groupShown);
+  }
+
+  const classResources = classes.map((entity) =>
+    toClassResource(
+      entity,
+      (shownByType.get(entity.prefixed) ?? 0) +
+        (droppedByType.get(entity.prefixed) ?? 0),
+      shownByType.get(entity.prefixed) ?? 0,
+    ),
+  );
+
+  const totalDropped = [...droppedByType.values()].reduce((a, b) => a + b, 0);
+
+  return {
+    resources: [
+      ...classResources,
+      ...properties.map(toPropertyResource),
+      ...individualResources,
+    ],
+    truncation: { totalDropped, droppedByType },
+  };
+}

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

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import classifyEntity from "./classifyEntity.js";
+
+const OWL_CLASS = "http://www.w3.org/2002/07/owl#Class";
+const OWL_OBJECT_PROPERTY = "http://www.w3.org/2002/07/owl#ObjectProperty";
+const DS_COMPONENT = "https://ds.canonical.com/Component";
+
+describe("classifyEntity", () => {
+  it("classifies owl:Class as tbox/class", () => {
+    expect(classifyEntity([OWL_CLASS])).toEqual({
+      box: "tbox",
+      category: "class",
+    });
+  });
+
+  it("classifies a property construct as tbox/property", () => {
+    expect(classifyEntity([OWL_OBJECT_PROPERTY])).toEqual({
+      box: "tbox",
+      category: "property",
+    });
+  });
+
+  it("classifies a domain-typed subject as abox/individual", () => {
+    expect(classifyEntity([DS_COMPONENT])).toEqual({
+      box: "abox",
+      category: "individual",
+    });
+  });
+
+  it("prefers schema when a subject is punned as both class and instance", () => {
+    expect(classifyEntity([DS_COMPONENT, OWL_CLASS])).toEqual({
+      box: "tbox",
+      category: "class",
+    });
+  });
+
+  it("returns null for an untyped subject", () => {
+    expect(classifyEntity([])).toBeNull();
+  });
+});

package/src/mcp/resources/classifyEntity.ts

@@ -0,0 +1,27 @@
+import { CLASS_TYPE_URIS, PROPERTY_TYPE_URIS } from "./constants.js";
+import type { EntityBox, EntityCategory } from "./types.js";
+
+/**
+ * Classify a subject into its box and category from its `rdf:type` values.
+ *
+ * Schema constructs win over instance-hood: a subject typed as both a class
+ * and something else is a class, so the schema is never buried among
+ * individuals. A subject with any non-schema type is an individual; a subject
+ * with no type at all returns `null` (the caller decides how to surface it).
+ *
+ * @param typeUris - Full `rdf:type` object URIs asserted for the subject.
+ * @returns The box and category, or `null` when the subject has no type.
+ */
+export default function classifyEntity(
+  typeUris: readonly string[],
+): { box: EntityBox; category: EntityCategory } | null {
+  const hasClassType = typeUris.some((t) => CLASS_TYPE_URIS.includes(t));
+  if (hasClassType) return { box: "tbox", category: "class" };
+
+  const hasPropertyType = typeUris.some((t) => PROPERTY_TYPE_URIS.includes(t));
+  if (hasPropertyType) return { box: "tbox", category: "property" };
+
+  if (typeUris.length > 0) return { box: "abox", category: "individual" };
+
+  return null;
+}

package/src/mcp/resources/constants.ts

@@ -0,0 +1,105 @@
+/**
+ * Constants for the MCP resource surface.
+ *
+ * Collects the RDF/RDFS/OWL term URIs, the label/description fallback
+ * chains that let foreign ontologies (no `PROPERTY_MAP` entry) still
+ * resolve human names, the listing/completion caps, and the client-facing
+ * annotation priorities and `_meta` keys used to distinguish TBox schema
+ * from ABox individuals.
+ */
+
+import { PREFIX_MAP } from "../../domains/shared/prefixes.js";
+
+const RDF_NS = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+const DCTERMS_NS = "http://purl.org/dc/terms/";
+const SCHEMA_NS = "http://schema.org/";
+
+/** `rdf:type` predicate URI. */
+export const RDF_TYPE = `${RDF_NS}type`;
+/** `rdfs:subClassOf` predicate URI. */
+export const RDFS_SUBCLASS_OF = `${PREFIX_MAP.rdfs}subClassOf`;
+/** `rdfs:domain` predicate URI. */
+export const RDFS_DOMAIN = `${PREFIX_MAP.rdfs}domain`;
+/** `rdfs:range` predicate URI. */
+export const RDFS_RANGE = `${PREFIX_MAP.rdfs}range`;
+
+/** Class-declaring `rdf:type` objects (TBox class constructs). */
+export const CLASS_TYPE_URIS: readonly string[] = [
+  `${PREFIX_MAP.owl}Class`,
+  `${PREFIX_MAP.rdfs}Class`,
+];
+
+/** Property-declaring `rdf:type` objects (TBox property constructs). */
+export const PROPERTY_TYPE_URIS: readonly string[] = [
+  `${PREFIX_MAP.owl}ObjectProperty`,
+  `${PREFIX_MAP.owl}DatatypeProperty`,
+  `${PREFIX_MAP.owl}AnnotationProperty`,
+  `${RDF_NS}Property`,
+];
+
+/**
+ * `rdf:type` objects that never make a meaningful grouping or `instanceOf`
+ * pointer for an individual: the schema-construct meta-types plus the
+ * top/individual meta-types (`owl:NamedIndividual`, `owl:Thing`,
+ * `rdfs:Resource`). An individual typed `[ds:Component, owl:NamedIndividual]`
+ * must group under `ds:Component`, so these are filtered out before a
+ * primary type is chosen.
+ */
+export const NON_GROUPING_TYPE_URIS: readonly string[] = [
+  ...CLASS_TYPE_URIS,
+  ...PROPERTY_TYPE_URIS,
+  `${PREFIX_MAP.owl}NamedIndividual`,
+  `${PREFIX_MAP.owl}Thing`,
+  `${PREFIX_MAP.rdfs}Resource`,
+];
+
+/**
+ * Generic label predicates tried after a namespace's `PROPERTY_MAP` label,
+ * in priority order. Lets foreign ontologies resolve a name.
+ */
+export const LABEL_FALLBACK_URIS: readonly string[] = [
+  `${PREFIX_MAP.rdfs}label`,
+  `${PREFIX_MAP.skos}prefLabel`,
+  `${DCTERMS_NS}title`,
+  `${SCHEMA_NS}name`,
+];
+
+/**
+ * Generic description predicates tried after a namespace's `PROPERTY_MAP`
+ * description, in priority order.
+ */
+export const DESCRIPTION_FALLBACK_URIS: readonly string[] = [
+  `${PREFIX_MAP.rdfs}comment`,
+  `${DCTERMS_NS}description`,
+  `${SCHEMA_NS}description`,
+  `${PREFIX_MAP.skos}definition`,
+];
+
+/** Maximum individuals listed per class before the remainder is capped. */
+export const ABOX_PER_CLASS_LIMIT = 25;
+
+/** Hard ceiling on total individuals across all classes in one listing. */
+export const ABOX_TOTAL_LIMIT = 300;
+
+/** Maximum ranked suggestions returned from URI autocomplete. */
+export const COMPLETION_LIMIT = 50;
+
+/** Annotation `priority` for TBox classes (highest — schema first). */
+export const CLASS_PRIORITY = 1;
+/** Annotation `priority` for TBox properties. */
+export const PROPERTY_PRIORITY = 0.9;
+/** Annotation `priority` for ABox individuals (lowest). */
+export const INDIVIDUAL_PRIORITY = 0.5;
+
+/** Separator between the category tag and the entity label in resource names. */
+export const NAME_SEPARATOR = " · ";
+
+/** Namespaced `_meta` keys carrying structured box/category metadata. */
+export const RESOURCE_META_KEYS = {
+  box: "pragma/box",
+  category: "pragma/category",
+  type: "pragma/type",
+  instanceCount: "pragma/instanceCount",
+  instancesShown: "pragma/instancesShown",
+  truncated: "pragma/truncated",
+} as const;

package/src/mcp/resources/displayPredicates.ts

@@ -0,0 +1,62 @@
+/**
+ * Label and description predicate chains for display-value resolution.
+ *
+ * Two concerns share this file because they are one policy: how a subject's
+ * human name and blurb are found. `resolve*` builds the per-subject priority
+ * order (namespace-specific `PROPERTY_MAP` predicate first, then the generic
+ * fallback chain); `collect*` builds the flat union used to bulk-query every
+ * candidate predicate at once. Keeping them together keeps the fallback
+ * ordering and the bulk query in lockstep.
+ */
+
+import { PROPERTY_MAP } from "../../constants.js";
+import { DESCRIPTION_FALLBACK_URIS, LABEL_FALLBACK_URIS } from "./constants.js";
+
+/** Narrow away `undefined` while preserving the string type. */
+function isPresent(value: string | undefined): value is string {
+  return value !== undefined;
+}
+
+/**
+ * Ordered label predicates for a subject: its namespace's `PROPERTY_MAP`
+ * label first, then the generic chain so foreign namespaces still resolve.
+ *
+ * @param prefix - The subject's namespace prefix, or `undefined` if foreign.
+ */
+export function resolveLabelPredicates(prefix: string | undefined): string[] {
+  const specific = prefix ? PROPERTY_MAP[prefix]?.label : undefined;
+  return [...new Set([specific, ...LABEL_FALLBACK_URIS].filter(isPresent))];
+}
+
+/**
+ * Ordered description predicates for a subject: its namespace's `PROPERTY_MAP`
+ * description then definition, then the generic chain.
+ *
+ * @param prefix - The subject's namespace prefix, or `undefined` if foreign.
+ */
+export function resolveDescriptionPredicates(
+  prefix: string | undefined,
+): string[] {
+  const map = prefix ? PROPERTY_MAP[prefix] : undefined;
+  return [
+    ...new Set(
+      [map?.description, map?.definition, ...DESCRIPTION_FALLBACK_URIS].filter(
+        isPresent,
+      ),
+    ),
+  ];
+}
+
+/** Every label predicate any namespace might use, for one bulk query. */
+export function collectLabelPredicates(): string[] {
+  const fromMap = Object.values(PROPERTY_MAP).map((m) => m.label);
+  return [...new Set([...fromMap, ...LABEL_FALLBACK_URIS])];
+}
+
+/** Every description predicate any namespace might use, for one bulk query. */
+export function collectDescriptionPredicates(): string[] {
+  const fromMap = Object.values(PROPERTY_MAP).flatMap((m) =>
+    [m.description, m.definition].filter(isPresent),
+  );
+  return [...new Set([...fromMap, ...DESCRIPTION_FALLBACK_URIS])];
+}

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import pickFirstValue from "./pickFirstValue.js";
+
+describe("pickFirstValue", () => {
+  it("returns the value of the first predicate present in priority order", () => {
+    const values = new Map([
+      ["p2", ["second"]],
+      ["p3", ["third"]],
+    ]);
+    expect(pickFirstValue(values, ["p1", "p2", "p3"])).toBe("second");
+  });
+
+  it("skips empty values", () => {
+    const values = new Map([
+      ["p1", [""]],
+      ["p2", ["real"]],
+    ]);
+    expect(pickFirstValue(values, ["p1", "p2"])).toBe("real");
+  });
+
+  it("returns null when no predicate matches", () => {
+    const values = new Map([["other", ["x"]]]);
+    expect(pickFirstValue(values, ["p1", "p2"])).toBeNull();
+  });
+
+  it("returns null for an empty map", () => {
+    expect(pickFirstValue(new Map(), ["p1"])).toBeNull();
+  });
+});

package/src/mcp/resources/pickFirstValue.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolve the first available value from a predicate priority chain.
+ *
+ * Walks `orderedPredicates` in order and returns the first non-empty value
+ * present in `valuesByPredicate`. This drives the label/description fallback:
+ * a namespace's `PROPERTY_MAP` predicate is tried first, then the generic
+ * chain (`rdfs:label`, `skos:prefLabel`, …), so foreign ontologies still
+ * resolve a name.
+ *
+ * @param valuesByPredicate - Full predicate URI → asserted lexical values.
+ * @param orderedPredicates - Predicate URIs in descending priority.
+ * @returns The first non-empty value, or `null` when none match.
+ */
+export default function pickFirstValue(
+  valuesByPredicate: ReadonlyMap<string, readonly string[]>,
+  orderedPredicates: readonly string[],
+): string | null {
+  for (const predicate of orderedPredicates) {
+    const values = valuesByPredicate.get(predicate);
+    if (values === undefined) continue;
+    for (const value of values) {
+      if (value.length > 0) return value;
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { PREFIX_MAP } from "../../domains/shared/prefixes.js";
+import pickPrimaryType from "./pickPrimaryType.js";
+
+const COMPONENT = `${PREFIX_MAP.ds}Component`;
+const BLOCK = `${PREFIX_MAP.ds}Block`;
+const NAMED_INDIVIDUAL = `${PREFIX_MAP.owl}NamedIndividual`;
+const OWL_THING = `${PREFIX_MAP.owl}Thing`;
+
+describe("pickPrimaryType", () => {
+  it("returns null for no types", () => {
+    expect(pickPrimaryType([])).toBeNull();
+  });
+
+  it("picks the domain type over a meta-type that sorts first", () => {
+    // owl: is http://… and ds: is https://…, so the meta-type sorts first;
+    // the meaningful domain type must still win.
+    expect([...[NAMED_INDIVIDUAL, COMPONENT]].sort().at(0)).toBe(
+      NAMED_INDIVIDUAL,
+    );
+    expect(pickPrimaryType([NAMED_INDIVIDUAL, COMPONENT])).toBe(COMPONENT);
+  });
+
+  it("ignores owl:Thing and owl:NamedIndividual together", () => {
+    expect(pickPrimaryType([OWL_THING, NAMED_INDIVIDUAL, COMPONENT])).toBe(
+      COMPONENT,
+    );
+  });
+
+  it("is deterministic among several domain types (lexicographic first)", () => {
+    expect(pickPrimaryType([COMPONENT, BLOCK])).toBe(BLOCK);
+    expect(pickPrimaryType([BLOCK, COMPONENT])).toBe(BLOCK);
+  });
+
+  it("falls back to the full set when only meta-types are present", () => {
+    // Both share the owl# namespace, so "NamedIndividual" < "Thing".
+    expect(pickPrimaryType([NAMED_INDIVIDUAL, OWL_THING])).toBe(
+      NAMED_INDIVIDUAL,
+    );
+  });
+});

package/src/mcp/resources/pickPrimaryType.ts

@@ -0,0 +1,26 @@
+import { NON_GROUPING_TYPE_URIS } from "./constants.js";
+
+/**
+ * Choose an individual's primary type — its grouping key and `instanceOf`
+ * pointer — from its full `rdf:type` object URIs.
+ *
+ * Schema and top/individual meta-types (`owl:Class`, `owl:NamedIndividual`,
+ * `owl:Thing`, `rdf:Property`, …) are filtered out first, so a subject typed
+ * `[ds:Component, owl:NamedIndividual]` resolves to `ds:Component` rather than
+ * the meta-type that happens to sort first. Among the remaining meaningful
+ * types the lexicographically-first is chosen for determinism. When an entity
+ * has nothing but meta-types, the full set is the fallback pool so a type is
+ * still returned.
+ *
+ * @param fullTypes - The subject's full `rdf:type` object URIs.
+ * @returns The chosen full type URI, or `null` when there are no types.
+ */
+export default function pickPrimaryType(
+  fullTypes: readonly string[],
+): string | null {
+  const meaningful = fullTypes.filter(
+    (type) => !NON_GROUPING_TYPE_URIS.includes(type),
+  );
+  const pool = meaningful.length > 0 ? meaningful : fullTypes;
+  return [...pool].sort((a, b) => a.localeCompare(b)).at(0) ?? null;
+}

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

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import rankUriCompletions from "./rankUriCompletions.js";
+import type { UriCompletionCandidate } from "./types.js";
+
+const candidates: UriCompletionCandidate[] = [
+  { prefixed: "ds:Component", label: "Component" },
+  { prefixed: "ds:global.component.button", label: "Button" },
+  { prefixed: "ds:global.component.card", label: "Card" },
+  { prefixed: "cs:code_purity", label: "code/function/purity" },
+];
+
+describe("rankUriCompletions", () => {
+  it("matches a URI substring case-insensitively", () => {
+    expect(rankUriCompletions(candidates, "BUTTON", 10)).toContain(
+      "ds:global.component.button",
+    );
+  });
+
+  it("matches a human label fragment", () => {
+    expect(rankUriCompletions(candidates, "card", 10)).toContain(
+      "ds:global.component.card",
+    );
+  });
+
+  it("ranks an exact match above a substring match", () => {
+    const ranked = rankUriCompletions(candidates, "component", 10);
+    expect(ranked.indexOf("ds:Component")).toBeLessThan(
+      ranked.indexOf("ds:global.component.button"),
+    );
+  });
+
+  it("ranks a prefix match above a substring match", () => {
+    const ranked = rankUriCompletions(candidates, "comp", 10);
+    expect(ranked.indexOf("ds:Component")).toBeLessThan(
+      ranked.indexOf("ds:global.component.button"),
+    );
+  });
+
+  it("returns the compacted URI even when matched by label", () => {
+    expect(rankUriCompletions(candidates, "purity", 10)).toEqual([
+      "cs:code_purity",
+    ]);
+  });
+
+  it("caps the result count", () => {
+    expect(rankUriCompletions(candidates, "", 2)).toHaveLength(2);
+  });
+
+  it("excludes non-matches", () => {
+    expect(rankUriCompletions(candidates, "zzz", 10)).toEqual([]);
+  });
+});

package/src/mcp/resources/rankUriCompletions.ts

@@ -0,0 +1,64 @@
+import type { UriCompletionCandidate } from "./types.js";
+
+/** Match strength of a query against one field, higher is better. */
+const NO_MATCH = 0;
+const SUBSTRING_MATCH = 1;
+const PREFIX_MATCH = 2;
+const EXACT_MATCH = 3;
+
+/** Score a single lowercased field against a lowercased query. */
+function scoreField(field: string, query: string): number {
+  if (field === query) return EXACT_MATCH;
+  if (field.startsWith(query)) return PREFIX_MATCH;
+  if (field.includes(query)) return SUBSTRING_MATCH;
+  return NO_MATCH;
+}
+
+/**
+ * Rank URI autocomplete candidates for a partial query.
+ *
+ * Matches case-insensitively against BOTH the compacted URI and the human
+ * label, so `button` completes `ds:global.component.button` and a label
+ * fragment works too. Ranks exact > prefix > substring (taking the stronger
+ * of the two fields), breaks ties by compacted URI for determinism, and caps
+ * the result at `limit`. Returns compacted URIs — the values a client reads.
+ *
+ * @param candidates - Listable subjects with their compacted URI and label.
+ * @param query - The partial text typed by the client.
+ * @param limit - Maximum suggestions to return.
+ * @returns Ranked, deduped, capped compacted URIs.
+ */
+export default function rankUriCompletions(
+  candidates: readonly UriCompletionCandidate[],
+  query: string,
+  limit: number,
+): string[] {
+  const needle = query.toLowerCase();
+
+  const scored: { prefixed: string; score: number }[] = [];
+  for (const candidate of candidates) {
+    const uriScore = scoreField(candidate.prefixed.toLowerCase(), needle);
+    const labelScore =
+      candidate.label === null
+        ? NO_MATCH
+        : scoreField(candidate.label.toLowerCase(), needle);
+    const score = Math.max(uriScore, labelScore);
+    if (score > NO_MATCH) scored.push({ prefixed: candidate.prefixed, score });
+  }
+
+  scored.sort((a, b) =>
+    b.score !== a.score
+      ? b.score - a.score
+      : a.prefixed.localeCompare(b.prefixed),
+  );
+
+  const seen = new Set<string>();
+  const ranked: string[] = [];
+  for (const { prefixed } of scored) {
+    if (seen.has(prefixed)) continue;
+    seen.add(prefixed);
+    ranked.push(prefixed);
+    if (ranked.length >= limit) break;
+  }
+  return ranked;
+}