@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -12,6 +12,7 @@
  */
 
 import chalk from "chalk";
+import { stdoutIsCaptured } from "../interactivity.js";
 
 /** The palette + gate a renderer consults to beautify the human path. */
 export interface RenderStyle {
@@ -27,6 +28,8 @@ export interface RenderStyle {
   green(text: string): string;
   /** Tint a status that wants attention. */
   yellow(text: string): string;
+  /** Tint a real fault — a failed check or a failed row, nothing milder. */
+  red(text: string): string;
 }
 
 /** The identity styler — every function returns its input unchanged. */
@@ -37,6 +40,7 @@ const PLAIN_STYLE: RenderStyle = {
   cyan: (text) => text,
   green: (text) => text,
   yellow: (text) => text,
+  red: (text) => text,
 };
 
 /**
@@ -55,20 +59,69 @@ export function styleFor(enabled: boolean): RenderStyle {
     cyan: (text) => chalk.cyan(text),
     green: (text) => chalk.green(text),
     yellow: (text) => chalk.yellow(text),
+    red: (text) => chalk.red(text),
   };
 }
 
+/**
+ * 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 three modules reach for `chalk` directly rather
+// than through `RenderStyle` — help formatting, 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;
+
+/**
+ * Whether stdout may carry color: an attended terminal AND a usable chalk
+ * level (zeroed by the module-load check above under `NO_COLOR`).
+ *
+ * The third question of the interactivity vocabulary (`kernel/interactivity.ts`
+ * holds the other two, and its docblock says why this one lives here: it needs
+ * `chalk`, and that module is on the flag-parsing fast path). Both signals are
+ * required — `supports-color` enables color off a TTY in CI, which would paint
+ * escapes into a redirected stream every byte-comparison then has to strip.
+ *
+ * @returns True on a color-capable terminal.
+ * @note Impure — reads stdout's capture state and chalk's color level.
+ */
+export function canColor(): boolean {
+  return !stdoutIsCaptured() && 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.
+ * Both signals, asked as one named question ({@link canColor}): 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, 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.
+ * @note Impure — {@link canColor} reads stdout's capture state and chalk's
+ *   color level.
  */
 export function defaultStyle(): RenderStyle {
-  return styleFor(process.stdout.isTTY === true && chalk.level > 0);
+  return styleFor(canColor());
 }

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();
+}