@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/kernel/render/renderers.ts

@@ -15,6 +15,7 @@ import type {
   SectionDef,
 } from "./contracts.js";
 import { DEFAULT_PREFIX_MAP } from "./prefixes.js";
+import { defaultStyle, type RenderStyle, styleFor } from "./style.js";
 
 type RenderMode = "plain" | "llm";
 
@@ -104,27 +105,40 @@ export function renderListLlm<T>(
   return lines.join("\n");
 }
 
+/**
+ * Render an entity lookup as plain text.
+ *
+ * @param entity - The looked-up entity.
+ * @param options - The lookup layout (title, fields, sections).
+ * @param style - TTY styling; defaults to the process style. On a color-capable
+ *   terminal the title is bold, its `═` rule dim, and field labels cyan; off a
+ *   TTY the styler is inert, so the output is byte-identical to the plain form.
+ * @returns The formatted lookup block.
+ */
 export function renderLookupPlain<T>(
   entity: T,
   options: RenderLookupOptions<T>,
+  style: RenderStyle = defaultStyle(),
 ): string {
-  return renderLookup(entity, options, "plain");
+  return renderLookup(entity, options, "plain", style);
 }
 
 export function renderLookupLlm<T>(
   entity: T,
   options: RenderLookupOptions<T>,
 ): string {
-  return renderLookup(entity, options, "llm");
+  // The condensed form is a byte-frozen agent contract — never styled.
+  return renderLookup(entity, options, "llm", styleFor(false));
 }
 
 function renderLookup<T>(
   entity: T,
   options: RenderLookupOptions<T>,
   mode: RenderMode,
+  style: RenderStyle,
 ): string {
   const title = options.title(entity);
-  const fields = renderLookupFields(entity, options, mode);
+  const fields = renderLookupFields(entity, options, mode, style);
   const sections = renderLookupSections(entity, options, mode);
 
   if (mode === "llm") {
@@ -132,13 +146,17 @@ function renderLookup<T>(
   }
 
   const headingRule = "═".repeat(Math.max(title.length, 24));
-  return [title, headingRule, "", ...fields, ...sections].join("\n").trimEnd();
+  const head = style.enabled
+    ? [style.bold(title), style.dim(headingRule)]
+    : [title, headingRule];
+  return [...head, "", ...fields, ...sections].join("\n").trimEnd();
 }
 
 function renderLookupFields<T>(
   entity: T,
   options: RenderLookupOptions<T>,
   mode: RenderMode,
+  style: RenderStyle,
 ): string[] {
   const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
   return options.fields.flatMap((field) => {
@@ -148,9 +166,9 @@ function renderLookupFields<T>(
     }
 
     const formatted = formatInlineValue(value, prefixes);
-    return mode === "llm"
-      ? [`- ${field.label}: ${formatted}`]
-      : [`  ${field.label}: ${formatted}`];
+    if (mode === "llm") return [`- ${field.label}: ${formatted}`];
+    const label = style.enabled ? style.cyan(field.label) : field.label;
+    return [`  ${label}: ${formatted}`];
   });
 }
 

package/src/kernel/render/style.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { defaultStyle, styleFor } from "./style.js";
+
+describe("styleFor", () => {
+  it("passes every color through unchanged when disabled", () => {
+    const style = styleFor(false);
+    expect(style.enabled).toBe(false);
+    expect(style.bold("x")).toBe("x");
+    expect(style.dim("x")).toBe("x");
+    expect(style.cyan("x")).toBe("x");
+    expect(style.green("x")).toBe("x");
+    expect(style.yellow("x")).toBe("x");
+  });
+
+  it("reports enabled and drives chalk when enabled", () => {
+    const style = styleFor(true);
+    expect(style.enabled).toBe(true);
+    // A non-TTY test process leaves chalk at level 0, so the text survives
+    // verbatim; what the beautified renderers gate on is `enabled`.
+    expect(style.cyan("x")).toContain("x");
+  });
+});
+
+describe("defaultStyle", () => {
+  it("is disabled when stdout is not a TTY (keeps piped output byte-stable)", () => {
+    // The vitest runner's stdout is never a TTY, so the beautify seam is inert
+    // here — the guarantee that piped / agent output is unstyled and stable.
+    expect(process.stdout.isTTY).not.toBe(true);
+    expect(defaultStyle().enabled).toBe(false);
+  });
+});

package/src/kernel/render/style.ts

@@ -0,0 +1,74 @@
+/**
+ * Terminal-styling seam for the human (TTY) output path.
+ *
+ * The condensed/agent (`llm`) and JSON paths are byte-frozen contracts; only an
+ * interactive terminal earns color and alignment. A {@link RenderStyle} carries
+ * that decision as data so a pure renderer can consult it without reading the
+ * process itself: {@link defaultStyle} probes chalk's own TTY/env detection (the
+ * same signal the help system leans on), so piped / redirected / MCP output —
+ * where `enabled` is false — renders byte-for-byte as before, while an attended
+ * terminal renders with `enabled: true`. Passing an explicit style keeps the
+ * beautified renderers deterministically testable in both modes.
+ */
+
+import chalk from "chalk";
+
+/** The palette + gate a renderer consults to beautify the human path. */
+export interface RenderStyle {
+  /** Whether to align + colorize — true only on a color-capable TTY. */
+  readonly enabled: boolean;
+  /** Emphasize a heading or primary label. */
+  bold(text: string): string;
+  /** De-emphasize secondary text (rules, markers, paths, punctuation). */
+  dim(text: string): string;
+  /** Highlight a value or identifier. */
+  cyan(text: string): string;
+  /** Tint a healthy / up-to-date status. */
+  green(text: string): string;
+  /** Tint a status that wants attention. */
+  yellow(text: string): string;
+}
+
+/** The identity styler — every function returns its input unchanged. */
+const PLAIN_STYLE: RenderStyle = {
+  enabled: false,
+  bold: (text) => text,
+  dim: (text) => text,
+  cyan: (text) => text,
+  green: (text) => text,
+  yellow: (text) => text,
+};
+
+/**
+ * Build a {@link RenderStyle} for a known color decision.
+ *
+ * @param enabled - True to colorize + align via chalk; false for the identity
+ *   styler (byte-identical to the pre-beautify plain output).
+ * @returns A style whose functions color, or pass through, accordingly.
+ */
+export function styleFor(enabled: boolean): RenderStyle {
+  if (!enabled) return PLAIN_STYLE;
+  return {
+    enabled: true,
+    bold: (text) => chalk.bold(text),
+    dim: (text) => chalk.dim(text),
+    cyan: (text) => chalk.cyan(text),
+    green: (text) => chalk.green(text),
+    yellow: (text) => chalk.yellow(text),
+  };
+}
+
+/**
+ * The active style for this process's stdout.
+ *
+ * Gated on BOTH signals: stdout must be an attended TTY, so piped / redirected /
+ * MCP output stays byte-stable even where `supports-color` fires off a TTY (CI
+ * sets `GITHUB_ACTIONS`, which chalk honors); AND chalk must report a usable
+ * color level, so `NO_COLOR` on a real terminal still yields the plain form.
+ *
+ * @returns A colorizing style on a color-capable TTY, else the identity styler.
+ * @note Impure — reads `process.stdout.isTTY` and chalk's color level.
+ */
+export function defaultStyle(): RenderStyle {
+  return styleFor(process.stdout.isTTY === true && chalk.level > 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,29 @@ 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
+      // whole index.json. Keep this in sync with `entityTotal` in entitySource.
+      const entityCount = new Set(
+        index.entities
+          .filter((entity) => entity.box === "abox")
+          .map((entity) => entity.uri ?? entity.name),
+      ).size;
+
       const manifest: Manifest = {
         name: options.name,
         version: options.version,
@@ -128,6 +164,8 @@ export async function buildPack(
         contentHash: hash,
         prefixes: { ...store.prefixes },
         createdAt: new Date().toISOString(),
+        tripleCount,
+        entityCount,
       };
       // Written LAST — the completeness marker for the directory.
       writeFileSync(join(temp, MANIFEST_FILE), JSON.stringify(manifest));
@@ -146,3 +184,19 @@ export async function buildPack(
     if (existsSync(temp)) rmSync(temp, { recursive: true, force: true });
   }
 }
+
+/**
+ * Count a store's triples (a cheap aggregate over the union graph).
+ *
+ * @param store - The booted store.
+ * @returns The number of triples.
+ * @note Impure — runs a COUNT query against the store.
+ */
+async function countTriples(
+  store: Awaited<ReturnType<typeof createStore>>,
+): Promise<number> {
+  const result = (await store.query(
+    "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" as never,
+  )) as import("@canonical/ke").SelectResult;
+  return Number(result.bindings.at(0)?.n ?? 0);
+}

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

@@ -0,0 +1,149 @@
+import { createStore } from "@canonical/ke";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  OWL_EXPORT_ABOX_SUBJECTS,
+  OWL_EXPORT_PREFIXES,
+  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";
+
+type Store = import("@canonical/ke").Store;
+
+/**
+ * The counters/classifiers `buildIndex` builds are masked by the embedded
+ * single-typed toy graph; the multi-typed OWL-export fixture is where the
+ * backlog-A bugs bite. Each `it` fails on the pre-fix code and passes after.
+ */
+describe("buildIndex — real-data counters/classifiers (backlog A)", () => {
+  let store: Store;
+  let index: PackIndex;
+
+  beforeAll(async () => {
+    store = await createStore({
+      sources: [{ content: OWL_EXPORT_TTL, path: "owl-export.ttl" }],
+      prefixes: OWL_EXPORT_PREFIXES,
+    });
+    index = await buildIndex(store, OWL_EXPORT_PREFIXES, "test-hash");
+  });
+
+  afterAll(() => {
+    store.dispose();
+  });
+
+  const byName = (name: string): PackIndex["entities"][number][] =>
+    index.entities.filter((entity) => entity.name === name);
+
+  it("A1: entityTotal counts DISTINCT abox subjects, not the raw multiset", () => {
+    // Every individual once — despite Protégé's `owl:NamedIndividual` dual-typing.
+    expect(entityTotal(index)).toBe(OWL_EXPORT_ABOX_SUBJECTS.length);
+
+    // The raw multiset the old code summed is strictly larger: each individual
+    // double-counts under `owl:NamedIndividual`, plus the class/property
+    // meta-buckets pile on top.
+    const rawSum = Object.values(index.instanceCountByType).reduce(
+      (sum, n) => sum + n,
+      0,
+    );
+    expect(rawSum).toBeGreaterThan(entityTotal(index));
+
+    // The abox names match the oracle exactly.
+    const aboxNames = index.entities
+      .filter((entity) => entity.box === "abox")
+      .map((entity) => entity.name);
+    expect([...new Set(aboxNames)].sort()).toEqual([
+      ...OWL_EXPORT_ABOX_SUBJECTS,
+    ]);
+  });
+
+  it("A3: a multi-domain individual gets a deterministic (lexical) primary type", () => {
+    // ex:toggle is both ex:Interactive and ex:FormControl; the smaller wins,
+    // every build/engine — never whichever type the store returned first.
+    const toggle = byName("ex:toggle").at(0);
+    expect(toggle?.type).toBe("ex:FormControl");
+    expect(toggle?.box).toBe("abox");
+  });
+
+  it("A6: a blank-node rdf:type is ignored, never a garbage primary type", () => {
+    // ex:field is typed by an anonymous class too; the blank node must not win.
+    expect(byName("ex:field").at(0)?.type).toBe("ex:FormControl");
+    // No entity type, no listed type, and no instance-count bucket is a blank node.
+    for (const entity of index.entities) {
+      expect(entity.type.startsWith("_:")).toBe(false);
+      for (const type of entity.types ?? []) {
+        expect(type.startsWith("_:")).toBe(false);
+      }
+    }
+    for (const key of Object.keys(index.instanceCountByType)) {
+      expect(key.startsWith("_:")).toBe(false);
+    }
+  });
+
+  it("A7: a multilingual label resolves to @en, deterministically", () => {
+    // "Button"@en / "Bouton"@fr → Button; the @lang no longer flips the pick.
+    expect(byName("ds:button").at(0)?.label).toBe("Button");
+    expect(byName("ex:toggle").at(0)?.label).toBe("Toggle");
+    expect(byName("ds:datePicker").at(0)?.label).toBe("Date Picker");
+  });
+
+  it("A8: an OWL-punned subject emits BOTH its tbox and abox facet", () => {
+    // ex:Slider is a class (tbox) AND an ex:Category individual (abox) — both
+    // must survive, so its abox membership stays completable.
+    const facets = byName("ex:Slider");
+    expect(facets).toHaveLength(2);
+    expect(facets.map((facet) => facet.box).sort()).toEqual(["abox", "tbox"]);
+    expect(facets.find((facet) => facet.box === "tbox")?.type).toBe(
+      "owl:Class",
+    );
+    expect(facets.find((facet) => facet.box === "abox")?.type).toBe(
+      "ex:Category",
+    );
+  });
+});
+
+/**
+ * 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([]);
+  });
+});