@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/kernel/runtime/graphpack/buildIndex.ts

@@ -1,17 +1,36 @@
 /**
  * Build the storeless entity index (`index.json`) from a populated store.
  *
- * A lean port of the v1 `buildGraphIndex` (#856): three bulk SPARQL queries —
- * types, labels, and instance counts — joined in memory, rather than a query
- * per subject. Only typed named-node subjects are indexed (untyped subjects and
- * blank nodes are reachable via `graph query` but never listed). Each entity
+ * A lean port of the v1 `buildGraphIndex` (#856): a few bulk SPARQL queries —
+ * types (which also yield the instance counts), labels, descriptions and
+ * alternative names — joined in memory, rather than a query per subject. Only
+ * the last names a DOMAIN property, and it is read from the distribution's
+ * declaration rather than spelled out here; see {@link resolveAltNamePredicate} for
+ * the pack that binds no such prefix.
+ *
+ * Only typed named-node subjects are indexed (untyped subjects and blank-node
+ * subjects are reachable via `graph query` but never listed). Each entity
  * carries the FROZEN `{ name, type }` minimum plus the enrichment fields
  * (`uri`, `prefixed`, `types`, `label`, `box`) the completion tier and reads
  * use. The output is pure JSON — no store handle survives — so the completion
  * tier reads it without ever booting oxigraph.
+ *
+ * Real-data correctness (things a single-typed toy graph never exercises):
+ * - Blank-node `rdf:type` objects (SHACL shapes, RDF lists) are ignored — a
+ *   `_:b0` is never a domain class and must not become a `type:"_:b0"` key.
+ * - The abox primary type is the LEXICALLY-SMALLEST domain class, a
+ *   deterministic tie-break: SPARQL returns a subject's types in unspecified
+ *   order, so a multi-domain individual would otherwise get an arbitrary
+ *   completion key that flips across builds/engines.
+ * - Multilingual labels prefer untagged / `@en`, then the lexically smallest —
+ *   never the store's arbitrary first row.
+ * - An OWL-punned subject (a class/property IRI ALSO asserted as a domain
+ *   individual) emits BOTH its tbox and abox facet, so its abox membership
+ *   stays completable instead of vanishing behind the tbox facet.
  */
 
 import { compactUri } from "../../render/compactUri.js";
+import { VOCABULARY } from "../../vocabulary.js";
 import type { PackIndex, PackIndexEntity } from "./types.js";
 
 type Store = import("@canonical/ke").Store;
@@ -62,62 +81,143 @@ const DESCRIPTION_PREDICATES = [
   "http://schema.org/description",
 ];
 
-/**
- * Alternative-name predicates: `ds:name`, the property `tier lookup` (and other
- * `ds:name`-addressed families) match on. Projected into `altNames` so the
- * storeless name-completion sources can offer those tokens exactly, without a
- * store boot. Distinct from the display `label` — a subject may carry both.
- */
-const ALT_NAME_PREDICATES = ["https://ds.canonical.com/name"];
-
 const isStdVocab = (uri: string): boolean =>
   STD_VOCAB_PREFIXES.some((ns) => uri.startsWith(ns));
 
-/** Classify a subject's full types into a box and a primary (filter) type. */
-function classify(
-  fullTypes: readonly string[],
-): { box: "tbox" | "abox"; primary: string } | null {
-  if (fullTypes.length === 0) return null;
+/** One classification facet: which box a subject occupies + its primary type. */
+interface Facet {
+  readonly box: "tbox" | "abox";
+  readonly primary: string;
+}
+
+/**
+ * Classify a subject's full types into its facets — one per box it occupies.
+ *
+ * A plain individual or a plain class yields ONE facet. An OWL-punned subject
+ * (a class/property IRI ALSO asserted as a domain individual) yields BOTH its
+ * tbox and abox facet (A8), so its abox membership stays completable rather than
+ * disappearing behind the tbox one. The abox primary is the lexically-smallest
+ * domain class — a deterministic tie-break (A3), not the store's first row.
+ *
+ * @param fullTypes - The subject's asserted `rdf:type` values (blank nodes
+ *   already dropped), in store order.
+ * @returns The subject's facets (empty when it has no usable type).
+ */
+function classify(fullTypes: readonly string[]): Facet[] {
+  if (fullTypes.length === 0) return [];
+  const facets: Facet[] = [];
   const classMeta = fullTypes.find((t) => CLASS_METATYPES.has(t));
-  if (classMeta) return { box: "tbox", primary: classMeta };
   const propMeta = fullTypes.find((t) => PROPERTY_METATYPES.has(t));
-  if (propMeta) return { box: "tbox", primary: propMeta };
-  // An individual: its filter key is the most specific domain class.
-  const domain =
-    fullTypes.find((t) => t !== NAMED_INDIVIDUAL && !isStdVocab(t)) ??
-    fullTypes.find((t) => t !== NAMED_INDIVIDUAL) ??
-    fullTypes[0];
-  return { box: "abox", primary: domain as string };
+  if (classMeta !== undefined) facets.push({ box: "tbox", primary: classMeta });
+  else if (propMeta !== undefined)
+    facets.push({ box: "tbox", primary: propMeta });
+
+  // A subject's domain classes: its own types minus the structural std vocab
+  // and the `owl:NamedIndividual` typing artifact. Sorted, so the abox primary
+  // (the smallest) is stable across builds/engines regardless of store order.
+  const domainClasses = fullTypes
+    .filter((t) => t !== NAMED_INDIVIDUAL && !isStdVocab(t))
+    .sort();
+  const primaryDomain = domainClasses.at(0);
+  if (primaryDomain !== undefined) {
+    facets.push({ box: "abox", primary: primaryDomain });
+  } else if (facets.length === 0) {
+    // No schema facet and no domain class — a bare individual (only
+    // `owl:NamedIndividual`, or only std-vocab types). Keep it indexed under a
+    // deterministic primary rather than dropping it silently.
+    const fallback =
+      fullTypes
+        .filter((t) => t !== NAMED_INDIVIDUAL)
+        .sort()
+        .at(0) ?? [...fullTypes].sort().at(0);
+    if (fallback !== undefined) facets.push({ box: "abox", primary: fallback });
+  }
+  return facets;
 }
 
 /** A `VALUES ?p { … }` body from a predicate list. */
 const valuesList = (uris: readonly string[]): string =>
   uris.map((uri) => `<${uri}>`).join(" ");
 
+/**
+ * Expand the declared alternative-name property against a pack's prefix map.
+ *
+ * That property is what a family is addressed by, so the storeless completion
+ * sources can offer those tokens exactly and a bespoke lookup can match them,
+ * without a store boot. Distinct from the display `label`: a subject may carry
+ * both.
+ *
+ * The distribution DECLARES it as a prefixed name; this resolves it against the
+ * PACK's own prefixes, which are not the distribution's. A pack that binds no
+ * such prefix simply carries no alternative names — the normal case for a
+ * third-party pack outside the distribution's namespace. Expanding through
+ * `packs/iri.ts` instead would THROW on exactly that pack and take its whole
+ * build down, so this degrades and the caller skips the query.
+ *
+ * The split needs no guard: `kernel/vocabulary.ts` has already held the term to
+ * `prefix:local`, so the colon is there and both sides are non-empty.
+ *
+ * @param prefixes - The store's merged prefix map.
+ * @returns The full IRI to collect, or `undefined` when the prefix is unbound.
+ */
+function resolveAltNamePredicate(
+  prefixes: Readonly<Record<string, string>>,
+): string | undefined {
+  const colon = VOCABULARY.altName.indexOf(":");
+  const namespace = prefixes[VOCABULARY.altName.slice(0, colon)];
+  return namespace === undefined
+    ? undefined
+    : `${namespace}${VOCABULARY.altName.slice(colon + 1)}`;
+}
+
+/** Language rank for label selection: untagged (0) < `@en` (1) < any other (2). */
+function rankLanguage(language: string): number {
+  if (language === "") return 0;
+  const lower = language.toLowerCase();
+  return lower === "en" || lower.startsWith("en-") ? 1 : 2;
+}
+
 /**
  * Per subject, keep the object whose predicate ranks HIGHEST (lowest index) in
  * `preference`. The `?p` binding is projected so the winner is chosen by declared
  * preference order: SPARQL returns solutions in an unspecified order, so keeping
  * the first row per subject would be store-order-dependent (an entity carrying
  * both `rdfs:label` and `skos:prefLabel` could index either), not ranked.
+ *
+ * Ties within a predicate (a subject with several `rdfs:label` values — the
+ * multilingual case) are broken deterministically: untagged / `@en` first, then
+ * the lexically smallest value. So `"Button"@en`/`"Bouton"@fr` always resolves
+ * to `Button`, never whichever row the store happened to return first (A7).
  */
 function preferredBySubject(
   result: import("@canonical/ke").SelectResult,
   valueVar: string,
   preference: readonly string[],
 ): Map<string, string> {
-  const best = new Map<string, { value: string; rank: number }>();
+  const best = new Map<
+    string,
+    { value: string; rank: number; langRank: number }
+  >();
   for (const term of result.termBindings) {
     if (term.s?.termType !== "NamedNode") continue;
-    const value = term[valueVar]?.value;
+    const valueTerm = term[valueVar];
     const predicate = term.p?.value;
-    if (!value || predicate === undefined) continue;
+    if (valueTerm === undefined || predicate === undefined) continue;
+    const value = valueTerm.value;
+    if (!value) continue;
     const rank = preference.indexOf(predicate);
     if (rank === -1) continue;
+    const language =
+      valueTerm.termType === "Literal" ? (valueTerm.language ?? "") : "";
+    const langRank = rankLanguage(language);
     const current = best.get(term.s.value);
-    if (current === undefined || rank < current.rank) {
-      best.set(term.s.value, { value, rank });
-    }
+    const better =
+      current === undefined ||
+      rank < current.rank ||
+      (rank === current.rank &&
+        (langRank < current.langRank ||
+          (langRank === current.langRank && value < current.value)));
+    if (better) best.set(term.s.value, { value, rank, langRank });
   }
   const picked = new Map<string, string>();
   for (const [subject, entry] of best) picked.set(subject, entry.value);
@@ -159,6 +259,7 @@ export async function buildIndex(
   prefixes: Readonly<Record<string, string>>,
   contentHash: string,
 ): Promise<PackIndex> {
+  const altNameUri = resolveAltNamePredicate(prefixes);
   const [typesResult, labelResult, descResult, altNameResult] =
     await Promise.all([
       store.query(
@@ -170,17 +271,24 @@ export async function buildIndex(
       store.query(
         `SELECT ?s ?p ?desc WHERE { ?s ?p ?desc . VALUES ?p { ${valuesList(DESCRIPTION_PREDICATES)} } }` as never,
       ) as Promise<import("@canonical/ke").SelectResult>,
-      store.query(
-        `SELECT ?s ?p ?alt WHERE { ?s ?p ?alt . VALUES ?p { ${valuesList(ALT_NAME_PREDICATES)} } }` as never,
-      ) as Promise<import("@canonical/ke").SelectResult>,
+      altNameUri === undefined
+        ? undefined
+        : (store.query(
+            `SELECT ?s ?p ?alt WHERE { ?s ?p ?alt . VALUES ?p { <${altNameUri}> } }` as never,
+          ) as Promise<import("@canonical/ke").SelectResult>),
     ]);
 
   const typesBySubject = new Map<string, string[]>();
   const instanceCountByType: Record<string, number> = {};
   for (const term of typesResult.termBindings) {
     if (term.s?.termType !== "NamedNode") continue;
+    const typeTerm = term.type;
+    // Ignore blank-node `rdf:type` objects (SHACL shapes / RDF lists): a `_:b0`
+    // is never a domain class, so it must not become a garbage primary type or
+    // inflate the per-type instance counts (A6).
+    if (typeTerm === undefined || typeTerm.termType === "BlankNode") continue;
     const subject = term.s.value;
-    const typeUri = term.type?.value ?? "";
+    const typeUri = typeTerm.value;
     const bucket = typesBySubject.get(subject) ?? [];
     bucket.push(typeUri);
     typesBySubject.set(subject, bucket);
@@ -197,27 +305,42 @@ export async function buildIndex(
     "desc",
     DESCRIPTION_PREDICATES,
   );
-  const altNamesBySubject = allBySubject(altNameResult, "alt");
+  const altNamesBySubject =
+    altNameResult === undefined
+      ? new Map<string, string[]>()
+      : allBySubject(altNameResult, "alt");
 
   const entities: PackIndexEntity[] = [];
   for (const [subject, fullTypes] of typesBySubject) {
-    const classification = classify(fullTypes);
-    if (classification === null) continue;
+    const facets = classify(fullTypes);
+    if (facets.length === 0) continue;
     const prefixed = compactUri(subject, prefixes);
     const altNames = altNamesBySubject.get(subject);
-    entities.push({
-      name: prefixed,
-      type: compactUri(classification.primary, prefixes),
-      uri: subject,
-      prefixed,
-      types: fullTypes.map((t) => compactUri(t, prefixes)),
-      label: labelBySubject.get(subject) ?? null,
-      ...(altNames && altNames.length > 0 ? { altNames } : {}),
-      box: classification.box,
-      description: descBySubject.get(subject) ?? null,
-    });
+    const typesCompact = fullTypes.map((t) => compactUri(t, prefixes));
+    const label = labelBySubject.get(subject) ?? null;
+    const description = descBySubject.get(subject) ?? null;
+    // A punned subject emits one entity per facet (tbox class + abox individual).
+    for (const facet of facets) {
+      entities.push({
+        name: prefixed,
+        type: compactUri(facet.primary, prefixes),
+        uri: subject,
+        prefixed,
+        types: typesCompact,
+        label,
+        ...(altNames && altNames.length > 0 ? { altNames } : {}),
+        box: facet.box,
+        description,
+      });
+    }
   }
-  entities.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  // Sort by name, then a deterministic tie-break (box, then type) so a punned
+  // subject's two facets keep a stable order across builds.
+  entities.sort((a, b) => {
+    if (a.name !== b.name) return a.name < b.name ? -1 : 1;
+    if (a.box !== b.box) return a.box === "tbox" ? -1 : 1;
+    return a.type < b.type ? -1 : a.type > b.type ? 1 : 0;
+  });
 
   return {
     version: 2,