@canonical/pragma-cli 0.34.0 → 0.35.0

package/src/kernel/render/renderers.ts

@@ -10,6 +10,7 @@
 import { compactUri } from "./compactUri.js";
 import type {
   ColumnDef,
+  RenderContext,
   RenderListOptions,
   RenderLookupOptions,
   SectionDef,
@@ -19,6 +20,56 @@ import { defaultStyle, type RenderStyle, styleFor } from "./style.js";
 
 type RenderMode = "plain" | "llm";
 
+/**
+ * The widest a plain-table cell renders. Cells are records, not documents: a
+ * pack can ship arbitrary prose in a column (one shipped an 834-character
+ * multi-line description), and a single cell that wraps destroys the
+ * one-row-one-record model every field-splitting consumer relies on. Longer
+ * values are truncated with an ellipsis; the detail escape hatch is `lookup`.
+ */
+export const MAX_PLAIN_CELL_WIDTH = 80;
+
+/**
+ * The placeholder for an empty cell in a populated column. The grid stays
+ * rectangular: a value's absence must not shift its neighbours left, or
+ * `awk '{print $4}'` reads a different field on every row.
+ */
+const EMPTY_CELL = "-";
+
+/** The context assumed when a caller passes none: interactive, headers on. */
+const DEFAULT_CONTEXT: RenderContext = { headers: true, stdoutIsTty: true };
+
+/**
+ * The markdown heading level `renderLookupSections` gives a section in llm mode
+ * — the lookup title is `##`, so a section is `###`. Read, not re-typed, by
+ * {@link nestHeadings}: the renderer is the only party that knows its own
+ * nesting depth, and it must stay the only party that encodes it.
+ */
+const SECTION_HEADING_LEVEL = 3;
+
+/** Markdown's deepest heading. Demotion clamps here rather than overflowing. */
+const MAX_HEADING_LEVEL = 6;
+
+/**
+ * An ATX heading: up to three spaces of indent, 1–6 `#`, whitespace, text.
+ *
+ * The indent is CommonMark's — four spaces would make the line an indented
+ * code block, three or fewer leave it a heading. Missing it left
+ * `  ### Accessibility` un-nested while its unindented twin was demoted, so
+ * one body could come out with two conflicting hierarchies. The indent is
+ * captured so a rewrite preserves it.
+ */
+const ATX_HEADING = /^( {0,3})(#{1,6})(\s+\S.*)$/;
+
+/**
+ * A fenced code-block delimiter: up to three spaces of indent, then the run of
+ * markers, then whatever follows on the line (the info string).
+ *
+ * The RUN LENGTH and the info string both matter for closing, which is why
+ * they are captured rather than just recognised — see {@link nestHeadings}.
+ */
+const CODE_FENCE = /^ {0,3}((`{3,})|(~{3,}))([^`]*)$/;
+
 /**
  * The empty-state body — the message plus its optional hint on a second line,
  * or "" when the caller declared no message (bare-empty behavior preserved).
@@ -30,37 +81,112 @@ function emptyBody<T>(options: RenderListOptions<T>): string {
     : options.emptyMessage;
 }
 
+/**
+ * The empty-list notice a dispatcher routes to STDERR (exit 0): zero rows is
+ * a calm success, and stdout — the data stream — must not carry a human
+ * sentence a pipe would read as a record. Exported for the formatter seam's
+ * `emptyNotice`; the plain renderer itself no longer prints it.
+ */
+export function renderListEmptyNotice<T>(
+  options: RenderListOptions<T>,
+): string {
+  return emptyBody(options);
+}
+
+/**
+ * One plain-table cell: single-line (embedded newlines collapse to a space)
+ * and at most {@link MAX_PLAIN_CELL_WIDTH} characters, truncated with an
+ * ellipsis — see the constant's rationale.
+ */
+function disciplineCell(value: string): string {
+  const singleLine = value.replace(/\s*\n\s*/g, " ").trim();
+  if (singleLine.length <= MAX_PLAIN_CELL_WIDTH) return singleLine;
+  return `${singleLine.slice(0, MAX_PLAIN_CELL_WIDTH - 1).trimEnd()}…`;
+}
+
+/**
+ * Render a list as a plain table: a bold UPPERCASE header row (from
+ * `column.label`), then one padded row per item over a RECTANGULAR grid — a
+ * column is included when any row (or `showWhenEmpty`) populates it, and an
+ * empty cell in an included column renders `-` so fields never shift. An
+ * empty list renders nothing on a terminal (the notice is stderr's, see
+ * {@link renderListEmptyNotice}) and just the header row on a pipe, so a
+ * zero-record table stays well-formed for field-splitting consumers.
+ *
+ * @param items - The rows.
+ * @param options - Columns and empty-state copy.
+ * @param context - Header/TTY presentation facts (defaults to a terminal
+ *   with headers on).
+ * @param style - TTY styling; off a TTY the styler is inert, so piped bytes
+ *   carry no escape sequences.
+ * @returns The formatted table.
+ */
 export function renderListPlain<T>(
   items: readonly T[],
   options: RenderListOptions<T>,
+  context: RenderContext = DEFAULT_CONTEXT,
+  style: RenderStyle = defaultStyle(),
 ): string {
-  if (items.length === 0) return emptyBody(options);
+  if (items.length === 0) {
+    // A piped zero-record table keeps its schema; a terminal needs nothing.
+    return context.headers && !context.stdoutIsTty
+      ? renderHeaderRow(options.columns, style)
+      : "";
+  }
 
   const prefixes = options.prefixes ?? DEFAULT_PREFIX_MAP;
-  const rows = items.map((item) =>
-    options.columns
-      .map((column) => ({
-        column,
-        value: formatColumnValue(item, column, prefixes),
-      }))
-      .filter(({ column, value }) => shouldRenderColumn(column, value))
-      .map(({ value }) => value),
+  const cells = items.map((item) =>
+    options.columns.map((column) =>
+      disciplineCell(formatColumnValue(item, column, prefixes)),
+    ),
+  );
+  const included = options.columns
+    .map((column, index) => ({ column, index }))
+    .filter(
+      ({ column, index }) =>
+        column.showWhenEmpty === true ||
+        cells.some((row) => (row[index] ?? "").length > 0),
+    );
+
+  const header = included.map(({ column }) => column.label.toUpperCase());
+  const rows = cells.map((row) =>
+    included.map(({ index }) => {
+      const value = row[index] ?? "";
+      return value.length > 0 ? value : EMPTY_CELL;
+    }),
   );
 
-  const widths = rows.reduce<number[]>(
+  const layoutRows = context.headers ? [header, ...rows] : rows;
+  const widths = layoutRows.reduce<number[]>(
     (acc, row) =>
       row.map((value, index) => Math.max(acc[index] ?? 0, value.length)),
     [],
   );
+  const padded = layoutRows.map((row) =>
+    row
+      .map((value, index) => value.padEnd(widths[index] ?? value.length))
+      .join("  ")
+      .trimEnd(),
+  );
 
-  return rows
-    .map((row) =>
-      row
-        .map((value, index) => value.padEnd(widths[index] ?? value.length))
-        .join("  ")
-        .trimEnd(),
-    )
-    .join("\n");
+  if (!context.headers) return padded.join("\n");
+  const [headerLine, ...bodyLines] = padded;
+  const styledHeader = style.enabled
+    ? style.bold(headerLine ?? "")
+    : (headerLine ?? "");
+  return [styledHeader, ...bodyLines].join("\n");
+}
+
+/** The zero-record header row (every declared column, uppercase labels). */
+function renderHeaderRow<T>(
+  columns: readonly ColumnDef<T>[],
+  style: RenderStyle,
+): string {
+  const line = columns
+    .map((column) => column.label.toUpperCase())
+    .join("  ")
+    .trimEnd();
+  return style.enabled ? style.bold(line) : line;
 }
 
 export function renderListLlm<T>(
@@ -196,7 +322,9 @@ function renderLookupSections<T>(
 
     sections.push("");
     sections.push(
-      mode === "llm" ? `### ${section.heading}` : `${section.heading}:`,
+      mode === "llm"
+        ? `${"#".repeat(SECTION_HEADING_LEVEL)} ${section.heading}`
+        : `${section.heading}:`,
     );
     sections.push(body);
   }
@@ -238,7 +366,81 @@ function renderFieldValue(
   }
 
   const text = formatScalarValue(value, prefixes);
-  return mode === "llm" ? text : indentBlock(text);
+  // Plain mode is not markdown — a `###` there is literal text, and rewriting
+  // it would corrupt the value. Only the llm mode's markdown has a hierarchy to
+  // collide with, so only it nests.
+  return mode === "llm"
+    ? nestHeadings(text, SECTION_HEADING_LEVEL)
+    : indentBlock(text);
+}
+
+/**
+ * Demote a section body's own ATX headings so they nest UNDER the heading the
+ * renderer gave the section.
+ *
+ * Authored markdown cannot know what level it will be rendered at; the renderer
+ * can, and so the renderer is the side that moves. A block whose shallowest
+ * heading is at or above `parentLevel` is shifted down as a whole — `###
+ * Accessibility` inside a `### Guidelines` section becomes `#### Accessibility`
+ * — which fixes the collision (a section heading immediately followed by a
+ * same-level heading reads as an empty section) while preserving the content's
+ * internal hierarchy exactly. Content already nested deeper is left alone.
+ *
+ * Headings inside a fenced code block are content, not structure — a `# ` in a
+ * shell sample is a comment — so fenced regions pass through untouched.
+ *
+ * @param text - The section body as authored.
+ * @param parentLevel - The heading level the section itself was rendered at.
+ * @returns The body with its headings nested below `parentLevel`.
+ */
+function nestHeadings(text: string, parentLevel: number): string {
+  const lines = text.split("\n");
+  const headings = new Map<number, number>();
+  // A fence CLOSES only on the same marker character, a run at least as long
+  // as the opener's, and no info string — CommonMark's rule, and the reason
+  // the opener's length is remembered rather than just its character. Toggling
+  // on any same-character run let a ``` sample inside a ```` block read as the
+  // close, after which every `#` line in that code block was rewritten as a
+  // heading: the renderer editing someone's sample code.
+  let fence: { marker: string; length: number } | undefined;
+  for (const [index, line] of lines.entries()) {
+    const delimiter = CODE_FENCE.exec(line);
+    const run = delimiter?.[1];
+    if (run !== undefined) {
+      const marker = run.charAt(0);
+      const info = (delimiter?.[4] ?? "").trim();
+      if (fence === undefined) {
+        fence = { marker, length: run.length };
+        continue;
+      }
+      if (
+        marker === fence.marker &&
+        run.length >= fence.length &&
+        info === ""
+      ) {
+        fence = undefined;
+      }
+      continue;
+    }
+    if (fence !== undefined) continue;
+    const level = ATX_HEADING.exec(line)?.[2]?.length;
+    if (level !== undefined) headings.set(index, level);
+  }
+
+  if (headings.size === 0) return text;
+  const shift = parentLevel + 1 - Math.min(...headings.values());
+  if (shift <= 0) return text;
+
+  return lines
+    .map((line, index) => {
+      const level = headings.get(index);
+      if (level === undefined) return line;
+      const hashes = "#".repeat(Math.min(level + shift, MAX_HEADING_LEVEL));
+      // `$1` keeps the line's own indent: rewriting it away would turn a
+      // legally indented heading into an unindented one.
+      return line.replace(ATX_HEADING, `$1${hashes}$3`);
+    })
+    .join("\n");
 }
 
 function renderCodeValue<T>(

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

@@ -1,31 +1,82 @@
-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");
+/**
+ * The color gate.
+ *
+ * `forbidsColor` is tested directly because it encodes a convention with two
+ * counter-intuitive edges — an empty assignment does NOT disable, and any
+ * non-empty value DOES, including `0`. The zero-escape guarantee is asserted
+ * against the shared chalk instance, which is what the four modules that bypass
+ * `RenderStyle` actually reach for.
+ */
+
+import chalk from "chalk";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { forbidsColor, styleFor } from "./style.js";
+
+/** The ANSI escape introducer, written as an escape so no control byte
+ * sits in the source. Assertions read "does not contain this". */
+const ANSI_ESCAPE = "\u001B[";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("forbidsColor", () => {
+  it("disables for any non-empty value, whatever it says", () => {
+    expect(forbidsColor({ NO_COLOR: "1" })).toBe(true);
+    // Counter-intuitive and deliberate: the value is never parsed.
+    expect(forbidsColor({ NO_COLOR: "0" })).toBe(true);
+    expect(forbidsColor({ NO_COLOR: "false" })).toBe(true);
   });
 
-  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");
+  it("does NOT disable for an absent or empty variable", () => {
+    expect(forbidsColor({})).toBe(false);
+    expect(forbidsColor({ NO_COLOR: "" })).toBe(false);
   });
 });
 
-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);
+describe("the plain style emits no escapes (PROTECTED)", () => {
+  it("returns its input untouched for every role", () => {
+    const plain = styleFor(false);
+    // `enabled` rides alongside the roles, so select the callables rather than
+    // assuming the shape — a role added later is then covered automatically.
+    const roles = Object.values(plain).filter(
+      (value): value is (text: string) => string => typeof value === "function",
+    );
+    expect(roles.length).toBeGreaterThan(0);
+    for (const role of roles) {
+      expect(role("text")).toBe("text");
+      expect(role("text")).not.toContain(ANSI_ESCAPE);
+    }
+  });
+});
+
+describe("NO_COLOR reaches the shared chalk instance (PROTECTED)", () => {
+  // The defect this pins: the gate delegated to chalk, and the vendored
+  // `supports-color` it ships has no NO_COLOR branch at all — so the flag did
+  // nothing while the code asserted it worked. Re-importing under a stubbed env
+  // exercises the module-load check that now zeroes the level.
+  it("zeroes chalk's level, so even direct chalk callers go plain", async () => {
+    const level = chalk.level;
+    try {
+      // FORCE a color-capable level first. Under vitest there is no TTY, so
+      // chalk already reports 0 and the assertion below would hold whether or
+      // not the module does anything — the test would pass with the fix
+      // deleted, which is no test at all. Starting from 3 makes the zeroing the
+      // only thing that can satisfy it.
+      chalk.level = 3;
+      expect(chalk.cyan("text")).toContain(ANSI_ESCAPE);
+
+      vi.stubEnv("NO_COLOR", "1");
+      vi.resetModules();
+      await import("./style.js");
+
+      expect(chalk.level).toBe(0);
+      // The four modules that bypass RenderStyle call chalk exactly like this.
+      expect(chalk.cyan("text")).toBe("text");
+      expect(chalk.bold("text")).not.toContain(ANSI_ESCAPE);
+    } finally {
+      chalk.level = level;
+      vi.resetModules();
+    }
   });
 });

package/src/kernel/render/style.ts

@@ -58,13 +58,43 @@ export function styleFor(enabled: boolean): RenderStyle {
   };
 }
 
+/**
+ * Whether the environment forbids color outright.
+ *
+ * `NO_COLOR` is honored when PRESENT AND NON-EMPTY, whatever its value — an
+ * empty assignment is explicitly not a request to disable (no-color.org). The
+ * value is never parsed: `NO_COLOR=0` still disables, which surprises people
+ * and is nonetheless what the convention says.
+ *
+ * @param env - The environment to read.
+ * @returns True when color must not be emitted.
+ */
+export function forbidsColor(env: NodeJS.ProcessEnv): boolean {
+  const value = env.NO_COLOR;
+  return value !== undefined && value !== "";
+}
+
+// Applied to the SHARED chalk instance at module load, not inside
+// `defaultStyle()`, because four modules reach for `chalk` directly rather than
+// through `RenderStyle` — help formatting, doctor, upgrade and the colophon's
+// Markdown renderer. Gating only the style seam would leave every one of them
+// still emitting escapes. Zeroing the level once covers them by construction,
+// including any site added later.
+//
+// This used to be delegated to chalk, and the delegation was silent: the
+// vendored `supports-color` this version ships handles `FORCE_COLOR` and has no
+// `NO_COLOR` branch at all, so the flag did nothing while the code asserted it
+// worked.
+if (forbidsColor(process.env)) chalk.level = 0;
+
 /**
  * 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.
+ * color level, which the module-load check above forces to zero under
+ * `NO_COLOR`.
  *
  * @returns A colorizing style on a color-capable TTY, else the identity styler.
  * @note Impure — reads `process.stdout.isTTY` and chalk's color level.

package/src/kernel/render/turtle.ts

@@ -0,0 +1,222 @@
+/**
+ * Serialize an entity's neighbourhood as Turtle — the dense form of the read.
+ *
+ * The JSON projection is faithful but expensive: one named node costs about 95
+ * bytes of wrapper to convey thirteen characters, and that overhead is paid per
+ * term. Measured on one button, structure alone was ~6.1 KB of a 15.8 KB read.
+ * Turtle spends the prefixes ONCE and then writes each term as itself.
+ *
+ * It is not merely shorter — it is the shape this data already has:
+ *
+ * - IRI versus literal is SYNTAX (`ds:Foo` against `"Foo"`), which is the whole
+ *   thing the typed-term projection had to carry a `termType` field to say.
+ * - A blank node is `[ … ]` inline, which is exactly the record the reader
+ *   assembles by hand for the JSON form.
+ * - Datatypes and language tags are native (`"x"@en`, `"2026-02-20"^^xsd:date`).
+ * - An inbound edge is just a triple written the other way round. The whole
+ *   `InboundGroup` structure exists only because JSON cannot point an arrow
+ *   backwards.
+ *
+ * Counts, samples and truncations ride as `#` comments. That is not a fallback:
+ * a comment is the one place a serialization can say something ABOUT the data
+ * without asserting it as data, and a reader — human or model — takes it the
+ * same way.
+ *
+ * Pure: it reads only the projection it is handed, so the same neighbourhood
+ * always renders the same bytes.
+ */
+
+import type {
+  InboundGroup,
+  InspectResult,
+  NestedRecord,
+  ReadTerm,
+} from "../runtime/readEntity.js";
+
+/** Characters that must be escaped inside a single-line Turtle literal. */
+const ESCAPES: Readonly<Record<string, string>> = {
+  "\\": "\\\\",
+  '"': '\\"',
+  "\n": "\\n",
+  "\r": "\\r",
+  "\t": "\\t",
+};
+
+/** Whether a literal is better served by a triple-quoted long string. */
+function isMultiline(value: string): boolean {
+  return value.includes("\n");
+}
+
+/** Escape a literal for the single-line `"…"` form. */
+function escapeShort(value: string): string {
+  return value.replace(/[\\"\n\r\t]/g, (char) => ESCAPES[char] ?? char);
+}
+
+/**
+ * Escape a literal for the `"""…"""` form.
+ *
+ * Only backslashes and a trailing/tripled quote need attention there — newlines
+ * are the entire point of the form and must survive untouched, which is what
+ * keeps an embedded YAML or Markdown body readable rather than turning it into
+ * one `\n`-riddled line.
+ */
+function escapeLong(value: string): string {
+  return (
+    value
+      .replace(/\\/g, "\\\\")
+      .replace(/"""/g, '\\"\\"\\"')
+      // A value ENDING in a quote would run straight into the closing delimiter
+      // and produce four quotes, which no parser reads as intended. Truncation
+      // makes this reachable on ordinary prose, not just on hostile input.
+      .replace(/"$/, '\\"')
+  );
+}
+
+/**
+ * Write a name that may or may not have compacted.
+ *
+ * `compactUri` returns its input UNCHANGED when no namespace matches, so a
+ * datatype or predicate outside the prefix map arrived here as a bare absolute
+ * IRI and was emitted raw — producing `"x"^^http://example.com/type`, which no
+ * parser accepts. A prefixed name goes through as-is; anything else is wrapped.
+ */
+function asName(value: string): string {
+  return /^[A-Za-z][\w.-]*:[^/]/.test(value) && !value.includes("://")
+    ? value
+    : `<${value}>`;
+}
+
+/** Render one term in Turtle: a prefixed name, an `<iri>`, or a literal. */
+function renderTerm(term: ReadTerm): string {
+  if (term.termType === "NamedNode") {
+    return term.prefixed ?? `<${term.value}>`;
+  }
+  if (term.termType === "BlankNode") {
+    // A bare `[]` — the label is store-local and re-minted on every load, so
+    // writing it would publish an identifier that means nothing on the next read.
+    return "[]";
+  }
+  const body = isMultiline(term.value)
+    ? `"""${escapeLong(term.value)}"""`
+    : `"${escapeShort(term.value)}"`;
+  // Direction is RDF 1.2's `@lang--dir`; it only ever accompanies a language.
+  if (term.language) {
+    return `${body}@${term.language}${term.direction ? `--${term.direction}` : ""}`;
+  }
+  if (term.datatype) return `${body}^^${asName(term.datatype)}`;
+  return body;
+}
+
+/**
+ * `# ds:guidelines — 5,814 chars, showing 400` — states a preview as a preview.
+ *
+ * On its OWN line ABOVE the triple, never trailing it: a Turtle comment runs to
+ * end of line, so a note placed after the object swallows the `;` or `.` that
+ * terminates the statement and silently breaks the document.
+ */
+function truncationNote(predicate: string, term: ReadTerm): string | undefined {
+  if (!term.truncated || term.length === undefined) return undefined;
+  const total = term.length.toLocaleString("en-US");
+  return `  # ${predicate} — ${total} chars, showing ${term.value.length}`;
+}
+
+/** Render one inlined blank node as a Turtle `[ … ]` record. */
+function renderNested(record: NestedRecord): string {
+  const fields = Object.entries(record).map(([field, value]) => {
+    // `type` was hoisted out of the record body on the way in; `a` is Turtle's
+    // own shorthand for it, so it goes back exactly where it came from.
+    const predicate = field === "type" ? "a" : asName(field);
+    return `${predicate} ${renderTerm(value)}`;
+  });
+  return `[ ${fields.join(" ; ")} ]`;
+}
+
+/** The prefixes a rendering actually uses, so the header declares no more. */
+function usedPrefixes(
+  text: string,
+  prefixes: Readonly<Record<string, string>>,
+): string[] {
+  return Object.entries(prefixes)
+    .filter(([prefix]) => new RegExp(`\\b${prefix}:`).test(text))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([prefix, namespace]) => `@prefix ${prefix}: <${namespace}> .`);
+}
+
+/** `# rdf:type — 330 total, sample of 5` and the triples under it. */
+function renderInbound(subject: string, group: InboundGroup): string[] {
+  const predicate = renderTerm(group.predicate);
+  const total = group.count.toLocaleString("en-US");
+  // An empty `subjects` means two different things, and conflating them told a
+  // lie: at `summary` EVERY group is empty because the level exhibits none, so
+  // claiming "none individually addressable" there libelled perfectly nameable
+  // subjects. Only a level that WOULD have shown exemplars can conclude that
+  // none exist.
+  const exhibits = group.exhibits ?? 0;
+  const note =
+    exhibits > 0 && group.subjects.length === 0 && group.count > 0
+      ? `# ${predicate} — ${total} total, none individually addressable; use the noun's list verb`
+      : group.sampled
+        ? `# ${predicate} — ${total} total, sample of ${group.subjects.length}; use the noun's list verb for the full set`
+        : group.truncated
+          ? `# ${predicate} — ${total} total, showing ${group.subjects.length}`
+          : `# ${predicate} — ${total}`;
+  return [
+    note,
+    ...group.subjects.map((s) => `${renderTerm(s)} ${predicate} ${subject} .`),
+  ];
+}
+
+/**
+ * Render an entity's neighbourhood as a Turtle document.
+ *
+ * @param result - The neighbourhood projection to serialize.
+ * @param prefixes - The store's merged prefix map, for the `@prefix` header.
+ * @returns A Turtle document: header, the subject's own triples, its inlined
+ *   blank nodes, then the edges pointing at it.
+ */
+export function toTurtle(
+  result: InspectResult,
+  prefixes: Readonly<Record<string, string>>,
+): string {
+  const subject = result.prefixed ?? `<${result.uri}>`;
+  const body: string[] = [];
+
+  // The subject's own triples, one predicate per line.
+  const predicates: string[] = [];
+  for (const group of result.groups) {
+    const predicate = renderTerm(group.predicate);
+    // Blank objects are written as their inlined records instead, so they are
+    // skipped here — emitting both would assert the same edge twice.
+    const objects = group.objects.filter((o) => o.termType !== "BlankNode");
+    if (objects.length === 0) continue;
+    const keyword = predicate === "rdf:type" ? "a" : predicate;
+    // Notes are folded INTO the element, above its statement, so the `;` the
+    // join appends always lands on the statement line. Pushed as siblings they
+    // would each take a separator of their own — into a comment, which runs to
+    // end of line and eats it.
+    const notes = objects
+      .map((o) => truncationNote(keyword, o))
+      .filter((n): n is string => n !== undefined);
+    const rendered = objects.map(renderTerm).join(", ");
+    predicates.push([...notes, `  ${keyword} ${rendered}`].join("\n"));
+  }
+  for (const [via, records] of Object.entries(result.nested)) {
+    predicates.push(
+      `  ${via}\n    ${records.map(renderNested).join(",\n    ")}`,
+    );
+  }
+  if (predicates.length > 0) {
+    body.push(`${subject}\n${predicates.join(" ;\n")} .`);
+  }
+
+  if (result.inbound.length > 0) {
+    body.push("", "# ── referenced by ──");
+    for (const group of result.inbound) {
+      body.push(...renderInbound(subject, group));
+    }
+  }
+
+  const text = body.join("\n");
+  const header = usedPrefixes(text, prefixes);
+  return [...header, "", text].join("\n").trimEnd();
+}

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

@@ -29,7 +29,7 @@
  *   stays completable instead of vanishing behind the tbox facet.
  */
 
-import { compactUri } from "../../render/compactUri.js";
+import { compactUri } from "../../render/index.js";
 import { VOCABULARY } from "../../vocabulary.js";
 import type { PackIndex, PackIndexEntity } from "./types.js";