@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -6,9 +6,16 @@ import {
   renderErrorLlm,
   renderErrorPlain,
 } from "../error/renderError.js";
-import type { ColumnDef, LookupField, SectionDef } from "./contracts.js";
+import type {
+  ColumnDef,
+  LookupField,
+  RenderContext,
+  SectionDef,
+} from "./contracts.js";
 import { resolveDetail } from "./disclosure.js";
 import {
+  MAX_PLAIN_CELL_WIDTH,
+  renderListEmptyNotice,
   renderListLlm,
   renderListPlain,
   renderLookupLlm,
@@ -16,6 +23,11 @@ import {
 } from "./renderers.js";
 import { type RenderStyle, styleFor } from "./style.js";
 
+/** An interactive stdout with headers on — the default terminal shape. */
+const TTY_CONTEXT: RenderContext = { headers: true, stdoutIsTty: true };
+/** A piped stdout with headers on — the field-splitting consumer shape. */
+const PIPE_CONTEXT: RenderContext = { headers: true, stdoutIsTty: false };
+
 interface Widget {
   readonly uri: string;
   readonly name: string;
@@ -111,18 +123,21 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
     expect(matrix).toMatchSnapshot();
   });
 
-  it("renders an empty-state message (+ hint) when items are empty", () => {
+  it("separates the empty notice (stderr's text) from the stdout rendering", () => {
     const options = {
       heading: "Widgets",
       columns: columnsFor("summary"),
       emptyMessage: "No widget entries found.",
       emptyHint: "Run `pragma sources update`.",
     };
-    // Plain: message then hint on the next line — a non-blank exit-0 body.
-    expect(renderListPlain([], options)).toBe(
+    // The notice is its own render — the dispatcher routes it to stderr so a
+    // pipe never receives a human sentence as data.
+    expect(renderListEmptyNotice(options)).toBe(
       "No widget entries found.\nRun `pragma sources update`.",
     );
-    // Llm: the `(0)` heading, then the same message + hint.
+    // Plain stdout for an empty list on a TTY: nothing (the notice suffices).
+    expect(renderListPlain([], options, TTY_CONTEXT)).toBe("");
+    // Llm keeps its byte-frozen shape: the `(0)` heading, then message + hint.
     expect(renderListLlm([], options)).toBe(
       "## Widgets (0)\n\nNo widget entries found.\nRun `pragma sources update`.",
     );
@@ -130,7 +145,8 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
 
   it("keeps the bare-empty behavior when no emptyMessage is declared", () => {
     const options = { heading: "Widgets", columns: columnsFor("summary") };
-    expect(renderListPlain([], options)).toBe("");
+    expect(renderListEmptyNotice(options)).toBe("");
+    expect(renderListPlain([], options, TTY_CONTEXT)).toBe("");
     expect(renderListLlm([], options)).toBe("## Widgets (0)\n");
   });
 
@@ -145,6 +161,101 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
   });
 });
 
+describe("plain list table contract (headers, rectangular grid, cell discipline)", () => {
+  const columns: ColumnDef<Widget>[] = [
+    { key: "name", label: "Name" },
+    { key: "kind", label: "Kind" },
+    { key: "note", label: "Note" },
+  ];
+  const options = { heading: "Widgets", columns };
+
+  it("emits a bold-eligible UPPERCASE header row built from the column labels", () => {
+    const lines = renderListPlain(widgets, options, TTY_CONTEXT).split("\n");
+    expect(lines[0]).toMatch(/^NAME\s+KIND\s+NOTE$/);
+    expect(lines).toHaveLength(1 + widgets.length);
+  });
+
+  it("suppresses the header row when the context disables headers", () => {
+    const lines = renderListPlain(widgets, options, {
+      headers: false,
+      stdoutIsTty: true,
+    }).split("\n");
+    expect(lines[0]).not.toMatch(/^NAME/);
+    expect(lines).toHaveLength(widgets.length);
+  });
+
+  it("keeps the grid rectangular — an empty cell renders as -", () => {
+    // Card's note is "": the NOTE column is populated on another row, so the
+    // grid keeps the column and marks the hole instead of shifting fields.
+    const lines = renderListPlain(widgets, options, TTY_CONTEXT).split("\n");
+    const cardRow = lines.find((line) => line.startsWith("Card"));
+    expect(cardRow?.trim().split(/\s{2,}/)).toEqual(["Card", "pattern", "-"]);
+  });
+
+  it("drops a column no row populates (unless it opts into showWhenEmpty)", () => {
+    const noteless = widgets.map((w) => ({ ...w, note: "" }));
+    const lines = renderListPlain(noteless, options, TTY_CONTEXT).split("\n");
+    expect(lines[0]).toMatch(/^NAME\s+KIND$/);
+  });
+
+  it("collapses newlines and truncates a long cell with an ellipsis", () => {
+    const prose = [
+      {
+        ...widgets[0],
+        note: `first line\nsecond line ${"x".repeat(2 * MAX_PLAIN_CELL_WIDTH)}`,
+      },
+    ] as Widget[];
+    const lines = renderListPlain(prose, options, TTY_CONTEXT).split("\n");
+    const row = lines[1] as string;
+    expect(row).not.toContain("\n");
+    expect(row).toContain("first line second line");
+    const noteCell = row
+      .trim()
+      .split(/\s{2,}/)
+      .at(-1) as string;
+    expect(noteCell.length).toBeLessThanOrEqual(MAX_PLAIN_CELL_WIDTH);
+    expect(noteCell.endsWith("…")).toBe(true);
+  });
+
+  it("renders only the header row for an empty list on a piped stdout", () => {
+    // An explicit `--format plain` down a pipe gets a well-formed zero-record
+    // table: every declared column, no rows — so `awk` sees a schema.
+    expect(renderListPlain([], options, PIPE_CONTEXT)).toMatch(
+      /^NAME\s+KIND\s+NOTE$/,
+    );
+    // With headers off there is nothing to print at all.
+    expect(
+      renderListPlain([], options, { headers: false, stdoutIsTty: false }),
+    ).toBe("");
+  });
+
+  it("bolds the header row on a color-capable TTY, leaving cells unstyled", () => {
+    const tagged: RenderStyle = {
+      enabled: true,
+      bold: (t) => `B(${t})`,
+      dim: (t) => t,
+      cyan: (t) => t,
+      green: (t) => t,
+      yellow: (t) => t,
+    };
+    const lines = renderListPlain(widgets, options, TTY_CONTEXT, tagged).split(
+      "\n",
+    );
+    expect(lines[0]).toMatch(/^B\(NAME\s+KIND\s+NOTE\)$/);
+    expect(lines[1]).not.toContain("B(");
+  });
+
+  it("is byte-identical plain text when the styler is disabled", () => {
+    const lines = renderListPlain(
+      widgets,
+      options,
+      TTY_CONTEXT,
+      styleFor(false),
+    ).split("\n");
+    expect(lines[0]).toMatch(/^NAME\s+KIND\s+NOTE$/);
+  });
+});
+
 describe("lookup beautify (TTY style seam)", () => {
   const lookupOpts = {
     title: (w: Widget) => w.name,
@@ -182,7 +293,7 @@ describe("error render matrix (× plain/llm/json)", () => {
   it("renders each error across the three formats", () => {
     const notFound = PragmaError.notFound("block", "Buton", {
       suggestions: ["Button"],
-      recovery: cliRecovery("pragma block list", "List available blocks."),
+      recovery: cliRecovery("block list", "List available blocks."),
     });
     const empty = PragmaError.emptyResults("token", {
       filters: { channel: "stable", tier: "core" },
@@ -203,3 +314,129 @@ describe("error render matrix (× plain/llm/json)", () => {
     }).toMatchSnapshot();
   });
 });
+
+describe("section-body headings nest under the heading the renderer gives them", () => {
+  interface Doc {
+    readonly guidelines: string;
+  }
+
+  const render = (guidelines: string): string =>
+    renderLookupLlm<Doc>(
+      { guidelines },
+      {
+        title: () => "Button",
+        fields: [],
+        sections: [{ key: "guidelines", heading: "Guidelines", kind: "field" }],
+      },
+    );
+
+  it("demotes authored headings that collide with the section heading", () => {
+    const out = render(
+      "### Accessibility\n\n- Label the button.\n\n### Content\n\n- Verb first.",
+    );
+    expect(out).toContain("### Guidelines");
+    expect(out).toContain("#### Accessibility");
+    expect(out).toContain("#### Content");
+    expect(out).not.toMatch(/^### Accessibility$/m);
+  });
+
+  it("preserves the content's own hierarchy while shifting it as a block", () => {
+    const out = render("## Overview\n\ntext\n\n### Detail\n\nmore");
+    expect(out).toContain("#### Overview");
+    expect(out).toContain("##### Detail");
+  });
+
+  it("leaves content already nested below the section alone", () => {
+    const out = render("#### Already nested\n\ntext");
+    expect(out).toContain("#### Already nested");
+    expect(out).not.toContain("##### Already nested");
+  });
+
+  it("never emits a heading deeper than markdown's floor", () => {
+    const out = render("###### Deep\n\ntext");
+    expect(out).toContain("###### Deep");
+  });
+
+  it("leaves `#` inside a fenced code block exactly as authored", () => {
+    const out = render("### Setup\n\n```sh\n# not a heading\nbun install\n```");
+    expect(out).toContain("#### Setup");
+    expect(out).toContain("# not a heading");
+    expect(out).not.toContain("## not a heading");
+  });
+
+  it("leaves a body with no headings untouched", () => {
+    const out = render("Plain prose with a # hash mid-line.");
+    expect(out).toContain("Plain prose with a # hash mid-line.");
+  });
+
+  it("does not rewrite the plain body, where `###` is literal text", () => {
+    const out = renderLookupPlain<Doc>(
+      { guidelines: "### Accessibility" },
+      {
+        title: () => "Button",
+        fields: [],
+        sections: [{ key: "guidelines", heading: "Guidelines", kind: "field" }],
+      },
+    );
+    expect(out).toContain("Guidelines:");
+    expect(out).toContain("  ### Accessibility");
+  });
+});
+
+describe("section-body nesting follows CommonMark, not a near-enough reading", () => {
+  interface Doc {
+    readonly guidelines: string;
+  }
+
+  const render = (guidelines: string): string =>
+    renderLookupLlm<Doc>(
+      { guidelines },
+      {
+        title: () => "Button",
+        fields: [],
+        sections: [{ key: "guidelines", heading: "Guidelines", kind: "field" }],
+      },
+    );
+
+  it("nests a heading indented up to three spaces, keeping its indent", () => {
+    // Four spaces would make the line an indented code block; three or fewer
+    // leave it a heading. Missing that left an indented heading at the
+    // section's own level while its unindented twin was demoted — one body
+    // rendered with two conflicting hierarchies.
+    expect(render("  ### Accessibility\n\ntext")).toMatch(
+      /^ {2}#### Accessibility$/m,
+    );
+  });
+
+  it("does not close a four-backtick fence on a three-backtick sample", () => {
+    // A closing fence must be AT LEAST as long as the opener. Toggling on any
+    // same-character run let the inner sample read as the close, after which
+    // every `#` line in that code block was rewritten — the renderer silently
+    // editing the user's sample code.
+    const out = render(
+      [
+        "````md",
+        "```",
+        "### Sample text, not a heading",
+        "```",
+        "````",
+        "",
+        "### A real heading",
+      ].join("\n"),
+    );
+    // Anchored: `#### x` CONTAINS `### x`, so a substring check would pass
+    // against the very rewrite this pins against.
+    expect(out).toMatch(/^### Sample text, not a heading$/m);
+    expect(out).toMatch(/^#### A real heading$/m);
+  });
+
+  it("does not close a fence on a run that carries an info string", () => {
+    // An opener may carry an info string; a CLOSER may not. A ```js line
+    // inside a block opens nothing and closes nothing.
+    const out = render(
+      ["```", "### inside", "```js", "### also inside", "```"].join("\n"),
+    );
+    expect(out).toMatch(/^### inside$/m);
+    expect(out).toMatch(/^### also inside$/m);
+  });
+});

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>(