Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 79 additions & 90 deletions .github/scripts/gen-inputs-table.ts
Original file line number Diff line number Diff line change
@@ -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);
}
5 changes: 2 additions & 3 deletions .github/scripts/generated.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
}

Expand All @@ -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" },
Expand Down
3 changes: 1 addition & 2 deletions .github/workflows/auto-fix.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# The commit-back fixes a same-repo PR can need, pushed to its branch; an already-clean tree gets no commit. A PR
# with unrelated type errors fails the build job by design: the graduation script refuses to half-fix a red build.
# README, action.yml, docs/ regions -> build:docs, build:action-docs, build:inputs-table (action-docs renders
# the inputs table from action.yml)
# README, action.yml, docs/ regions -> build:docs, build:action-docs, build:inputs-table
# src/upstream-gaps/ -> graduate-upstream-gaps.ts retires the gap files @octokit/types caught up with;
# gen-gaps-index.ts re-renders index.ts
# lib/ -> never: main carries no bundle, library, or schema
Expand Down
Loading
Loading