refactor(scripts): render the inputs table as a generated region

The inputs table on docs/reference/inputs.md was rendered by the action-docs package from action.yml between action-docs's own markers, after a hand-written guard checked that the region held only a rendering. It is now one more GeneratedRegion: the data is INPUT_DECLS, the same source action.yml's inputs region is generated from; the render is a four-cell table through renderTable; the parse reads each row back through tableBody; and the round-trip seal refuses a moved marker, an authored row, or a description holding "<" naming the line.

Every table line is byte-identical to the previous rendering, the paragraph wrapper and the empty-default spelling included. Only the marker lines changed, and the "## Inputs" heading moved above the BEGIN marker so the region sits under it like every other table region. action-docs leaves the devDependencies: the region needs a synchronous render and a parse, which the async, file-writing package cannot give.

Author: Vivswan

.github/scripts/gen-inputs-table.ts

@@ -1,112 +1,101 @@
-/** Renders the inputs table on docs/reference/inputs.md with action-docs, after refusing a marker region holding anything
- * but the lines of a rendering in the renderer's order: action-docs rewrites the region blind, and auto-fix.yml pushes
- * regenerations unreviewed, so an authored line that merely looks like a table row would be erased and committed. */
+/**
+ * The inputs table of docs/reference/inputs.md: one row per input declaration, rendered as a generated region so a
+ * marker moved over authored text is refused instead of regenerated over. The page's outputs list is gen-docs.ts's
+ * region, so two generators write into the page.
+ */
 
-import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { generateActionMarkdownDocs } from "action-docs";
+import { err, ok, type Result } from "neverthrow";
+import { INPUT_DECLS, type InputDecl } from "../../src/flows/inputs.js";
+import { renderTable, tableBody, tableFault } from "../../src/report/markdown.js";
+import { block, GeneratedRegion } from "./lib/generated-regions.js";
+import { type GeneratedFiles, regenerateFiles } from "./lib/region-driver.js";
 
 const ROOT = join(import.meta.dir, "..", "..");
 
-/** The page action-docs renders the inputs table into, from the action.yml build:action-docs writes just before. */
 export const INPUTS_PAGE_PATH = "docs/reference/inputs.md";
 
-export const MARKER = '<!-- action-docs-inputs source="action.yml" -->';
+const INPUTS_TABLE_HEADER =
+  "| name | description | required | default |\n| --- | --- | --- | --- |";
 
-/** The header row action-docs emits; test/docs/inputs.test.ts pins the same cells on the committed page. */
-const HEADER_CELLS = ["name", "description", "required", "default"];
+/** The declarations the table renders from, by input name. */
+type Inputs = Readonly<Record<string, Pick<InputDecl, "description" | "default">>>;
 
-/** The trimmed cells of a table line `| a | b |`, or null for any other line. One split per line and no regex: the
- * earlier four-cell regex backtracked exponentially on a long row of repeated cells. */
-const cells = (line: string): string[] | null =>
-  line.startsWith("| ") && line.endsWith(" |")
-    ? line
-        .slice(1, -1)
-        .split("|")
-        .map((cell) => cell.trim())
-    : null;
-
-type CellCheck = (cell: string) => boolean;
+/** Why a description cannot sit in its cell: the cell is HTML, so a tag would be swallowed by the page's renderer. */
+function descriptionFault(text: string): string | undefined {
+  return text.includes("<") ? 'holds a "<", which the cell would read as an HTML tag' : undefined;
+}
 
-const lineOf =
-  (checks: CellCheck[]) =>
-  (line: string): boolean => {
-    const found = cells(line);
-    return (
-      found !== null &&
-      found.length === checks.length &&
-      checks.every((ok, i) => ok(found[i] ?? ""))
-    );
-  };
+/** The default as the table shows it: in a code span, the empty string as `""`. */
+function defaultSpan(value: string): string {
+  return `\`${value === "" ? '""' : value}\``;
+}
 
-const backticked: CellCheck = (cell) =>
-  cell.length > 2 && cell.startsWith("`") && cell.endsWith("`");
+function inputsCells(inputs: Inputs): ReadonlyArray<readonly string[]> {
+  return Object.entries(inputs).map(([name, decl]) => {
+    const fault = descriptionFault(decl.description);
+    if (fault !== undefined) {
+      throw new Error(`gen-inputs-table: the "${name}" description ${fault}`);
+    }
+    return [`\`${name}\``, `<p>${decl.description}</p>`, "`false`", defaultSpan(decl.default)];
+  });
+}
 
-/** A row action-docs renders: | `name` | <p>description</p> | `false` | `default` |. An authored four-cell row
- * with bare cells is refused on these, since a cell count alone let one through. */
-const row = lineOf([
-  backticked,
-  (cell) => cell.startsWith("<p>") && cell.endsWith("</p>"),
-  (cell) => cell === "`true`" || cell === "`false`",
-  backticked,
-]);
+/** The table rule is the author's to meet, so a description that would break its row stops the build naming it. */
+export function renderInputsTable(inputs: Inputs): string {
+  const cells = inputsCells(inputs);
+  const fault = tableFault(INPUTS_TABLE_HEADER, cells, "cells");
+  if (fault !== undefined) {
+    throw new Error(`gen-inputs-table: ${fault}`);
+  }
+  return renderTable(INPUTS_TABLE_HEADER, cells);
+}
 
-/** The first entry is the rest of the opening marker's own line. A "|" in a description would split its rendered row
- * past `row`'s four cells and refuse it as authored, so test/docs/inputs.test.ts pins every description free of one. */
-const LEADING: ((line: string) => boolean)[] = [
-  (line) => line === "",
-  (line) => line === "## Inputs",
-  (line) => line === "",
-  lineOf(HEADER_CELLS.map((name) => (cell: string) => cell === name)),
-  lineOf(HEADER_CELLS.map(() => (cell: string) => cell === "---")),
-];
+const NAME_SPAN = /^`([a-z][a-z0-9-]*)`$/;
+// The dotAll flag is for the two Unicode line separators cellFault() admits inside a cell.
+const DESCRIPTION_CELL = /^<p>(.*)<\/p>$/s;
+const DEFAULT_SPAN = /^`(.*)`$/s;
 
-/** Why `page` cannot be handed to action-docs, or null when its region holds only a rendering's lines in order. */
-export function regionProblem(page: string): string | null {
-  const parts = page.split(MARKER);
-  if (parts.length !== 3) {
-    return `${INPUTS_PAGE_PATH} must carry exactly two "${MARKER}" markers, found ${parts.length - 1}`;
+/** A row read back to the declaration it renders from; every input is optional, so the required cell is fixed. */
+function inputRow(cells: readonly string[]): Result<readonly [string, Inputs[string]], string> {
+  const name = NAME_SPAN.exec(cells[0] ?? "")?.[1];
+  const description = DESCRIPTION_CELL.exec(cells[1] ?? "")?.[1];
+  const value = DEFAULT_SPAN.exec(cells[3] ?? "")?.[1];
+  if (name === undefined) {
+    return err("does not open with an input name in a code span");
   }
-  const [intro, region] = parts as [string, string, string];
-  const openingLine = intro.split("\n").length;
-  const lines = region.split("\n");
-  const last = lines.length - 1;
-  if (last === 0) {
-    // action-docs then replaces the opening marker alone and leaves three on the page.
-    return `the closing "${MARKER}" marker on line ${openingLine} of ${INPUTS_PAGE_PATH} must start its own line`;
+  if (description === undefined) {
+    return err("has no paragraph-wrapped description in its second cell");
   }
-  if (lines.every((line) => line === "")) {
-    return null;
+  const fault = descriptionFault(description);
+  if (fault !== undefined) {
+    return err(`${fault}, which the renderer refuses`);
   }
-  const authored = lines.findIndex((line, index) => {
-    const leading = LEADING[index];
-    if (leading !== undefined) {
-      return !leading(line);
-    }
-    return index === last ? line !== "" : !row(line);
-  });
-  if (authored !== -1) {
-    return (
-      `line ${openingLine + authored} of ${INPUTS_PAGE_PATH} sits between the two "${MARKER}" markers ` +
-      "but is not a line of a rendered inputs table; move the markers back around the table before " +
-      "regenerating, or action-docs erases what sits between them"
-    );
+  if (cells[2] !== "`false`") {
+    return err("does not show `false` in its required cell");
   }
-  return null;
+  if (value === undefined) {
+    return err("has no default in a code span in its fourth cell");
+  }
+  return ok([name, { description, default: value === '""' ? "" : value }]);
 }
 
+const parseInputsTable = tableBody(INPUTS_TABLE_HEADER, "cells", inputRow);
+
+export const INPUTS_PAGES: GeneratedFiles = {
+  [INPUTS_PAGE_PATH]: {
+    regions: [
+      GeneratedRegion.of<Inputs>({
+        name: "inputs-table",
+        placement: { kind: "under-heading", heading: "## Inputs" },
+        data: () => INPUT_DECLS,
+        render: block(renderInputsTable),
+        parse: (body) => parseInputsTable(body).map((rows) => Object.fromEntries(rows)),
+      }),
+    ],
+  },
+};
+
 if (import.meta.main) {
-  // action-docs resolves both files from the working directory and matches the marker on the literal source name.
-  process.chdir(ROOT);
-  const problem = regionProblem(readFileSync(INPUTS_PAGE_PATH, "utf8"));
-  if (problem !== null) {
-    console.error(`gen-inputs-table: ${problem}`);
-    process.exit(1);
-  }
-  await generateActionMarkdownDocs({
-    sourceFile: "action.yml",
-    updateReadme: true,
-    readmeFile: INPUTS_PAGE_PATH,
-  });
-  console.log(`gen-inputs-table: rendered ${INPUTS_PAGE_PATH} from action.yml`);
+  regenerateFiles("gen-inputs-table", INPUTS_PAGES, ROOT);
 }

.github/scripts/generated.ts

@@ -16,7 +16,7 @@ export interface GeneratedOutput {
   readonly path: string;
   /** The package.json script that writes it; `bun run <generator>` regenerates it in place. */
   readonly generator: string;
-  /** Marker-delimited regions inside an authored file (lib/generated-regions.ts, or action-docs's own markers), or the whole file. */
+  /** Marker-delimited regions inside an authored file (lib/generated-regions.ts), or the whole file. */
   readonly kind: "regions" | "file";
 }
 
@@ -26,9 +26,8 @@ function regions(generator: string, paths: readonly string[]): GeneratedOutput[]
 
 /**
  * A page two generators write into (docs/reference/inputs.md) has one row per generator. Rows stay in dependency
- * order, each artifact before its readers, or a new gap file or a bump would leave a run stale.
+ * order, each artifact before its readers, or a new gap file would leave a run stale.
  *   the gaps index -> imported through src/ by the docs and action.yml generators
- *   action.yml     -> feeds the inputs table
  */
 export const GENERATED_OUTPUTS: readonly GeneratedOutput[] = [
   { path: INDEX_PATH, generator: "build:gaps-index", kind: "file" },