@canonical/pragma-cli 0.33.0 → 0.34.0

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

@@ -39,6 +39,7 @@ import {
   MANIFEST_FILE,
   type Manifest,
   SCHEMA_FILE,
+  STORIES_FILE,
 } from "./types.js";
 
 /** One RDF source to build into a pack. */
@@ -53,10 +54,17 @@ export interface BuildPackInput {
 export interface BuildPackOptions {
   readonly name: string;
   readonly version: string;
-  /** The config `packages` ref (verbatim) or a label. */
+  /** The config `packs` ref (verbatim) or a label. */
   readonly sourceRef: string;
   /** Prefixes the store (and every query) is built with. */
   readonly prefixes?: Readonly<Record<string, string>>;
+  /**
+   * The `stories/*.json` files the resolved packages ship, as raw text. Hash
+   * inputs like any other source — a story-only edit is a new pack, and a set
+   * of packages shipping none keeps the hash it had before stories existed, so
+   * no cached pack is invalidated by rehashing.
+   */
+  readonly stories?: readonly BuildPackInput[];
 }
 
 /** The outcome of a pack build (or cache hit). */
@@ -72,7 +80,8 @@ export interface BuildPackResult {
  * Build (or reuse) the pack for a set of source inputs.
  *
  * @param inputs - The RDF sources (path + content).
- * @param options - Provenance and the prefixes to build with.
+ * @param options - Provenance, the prefixes to build with, and the packages'
+ *   carried read stories.
  * @returns The pack directory, its content hash, and whether it was reused.
  * @note Impure — creates a store, compiles the schema, writes the pack.
  */
@@ -80,8 +89,12 @@ export async function buildPack(
   inputs: readonly BuildPackInput[],
   options: BuildPackOptions,
 ): Promise<BuildPackResult> {
+  const stories = options.stories ?? [];
   const hash = await contentHash(
-    inputs.map((input) => ({ path: input.path, content: input.content })),
+    [...inputs, ...stories].map((input) => ({
+      path: input.path,
+      content: input.content,
+    })),
   );
   const dir = packDir(hash);
 
@@ -121,6 +134,19 @@ export async function buildPack(
       const index = await buildIndex(store, store.prefixes, hash);
       writeFileSync(join(temp, INDEX_FILE), JSON.stringify(index));
 
+      // Written UNCONDITIONALLY (`[]` when the packages ship none): the artifact
+      // set is FIVE AND ONLY FIVE, and `packIsComplete` gates on it, so a pack
+      // whose hash covers stories always holds them.
+      writeFileSync(
+        join(temp, STORIES_FILE),
+        JSON.stringify(
+          stories.map((story) => ({
+            source: story.path,
+            content: story.content,
+          })),
+        ),
+      );
+
       const tripleCount = await countTriples(store);
       // Distinct abox subjects — the same figure `entityTotal` reports (A10),
       // so `sources status` reads it from the manifest without parsing the

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

@@ -6,6 +6,7 @@ import {
   OWL_EXPORT_TTL,
 } from "../../../testing/fixtures/graph/owlExport.js";
 import { entityTotal } from "../../completion/entitySource.js";
+import { VOCABULARY } from "../../vocabulary.js";
 import { buildIndex } from "./buildIndex.js";
 import type { PackIndex } from "./types.js";
 
@@ -101,3 +102,48 @@ describe("buildIndex — real-data counters/classifiers (backlog A)", () => {
     );
   });
 });
+
+/**
+ * The alternative-name property is DECLARED by the distribution, so a pack whose
+ * prefix map does not bind its prefix is an ordinary case — a third-party pack
+ * outside that namespace — not an error. Resolving the term strictly would throw
+ * there and take the whole pack build down with it.
+ */
+describe("buildIndex — the declared alternative-name property", () => {
+  let store: Store;
+
+  beforeAll(async () => {
+    store = await createStore({
+      sources: [{ content: OWL_EXPORT_TTL, path: "owl-export.ttl" }],
+      prefixes: OWL_EXPORT_PREFIXES,
+    });
+  });
+
+  afterAll(() => {
+    store.dispose();
+  });
+
+  it("projects it into altNames when the pack binds its prefix", async () => {
+    const index = await buildIndex(store, OWL_EXPORT_PREFIXES, "bound");
+    const named = index.entities.filter((entity) => entity.altNames);
+    expect(named.length).toBeGreaterThan(0);
+    expect(named.at(0)?.altNames?.length).toBeGreaterThan(0);
+  });
+
+  it("still builds, carrying no altNames, when the pack binds no such prefix", async () => {
+    // Unbind the prefix the DECLARATION uses, whatever it is — the subject here
+    // is the declared property, so naming a prefix would couple this case to
+    // today's values and quietly stop testing anything if they moved.
+    const declared = VOCABULARY.altName.slice(
+      0,
+      VOCABULARY.altName.indexOf(":"),
+    );
+    const { [declared]: _unbound, ...withoutDomain } = OWL_EXPORT_PREFIXES;
+    const index = await buildIndex(store, withoutDomain, "unbound");
+    // The graph is unchanged, so every entity is still indexed…
+    expect(index.entities.length).toBeGreaterThan(0);
+    // …they simply carry no alternative names, exactly as a pack that never
+    // authored the property would.
+    expect(index.entities.filter((entity) => entity.altNames)).toEqual([]);
+  });
+});

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

@@ -1,11 +1,16 @@
 /**
  * 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-node subjects are reachable via `graph query` but never listed). Each
- * entity carries the FROZEN `{ name, type }` minimum plus the enrichment fields
+ * 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.
@@ -25,6 +30,7 @@
  */
 
 import { compactUri } from "../../render/compactUri.js";
+import { VOCABULARY } from "../../vocabulary.js";
 import type { PackIndex, PackIndexEntity } from "./types.js";
 
 type Store = import("@canonical/ke").Store;
@@ -75,14 +81,6 @@ 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));
 
@@ -141,6 +139,37 @@ function classify(fullTypes: readonly string[]): Facet[] {
 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;
@@ -230,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(
@@ -241,9 +271,11 @@ 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[]>();
@@ -273,7 +305,10 @@ 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) {