From 8f7947f0665e636b863e92df9bf04ee0982dfc37 Mon Sep 17 00:00:00 2001 From: Vivswan Shah <58091053+Vivswan@users.noreply.github.com> Date: Tue, 6 Oct 2026 06:47:01 -0400 Subject: [PATCH] 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. The docs README, the input declarations' comments, and the auto-fix workflow comment now name the generated region instead of action-docs. test/docs/inputs.test.ts goes: it restated the generator's rendering, its ASCII pin duplicates the typography gate, and its "|" and "<" checks duplicate the generator's refusals. --- .github/scripts/gen-inputs-table.ts | 169 ++++++++++++-------------- .github/scripts/generated.ts | 5 +- .github/workflows/auto-fix.yml | 3 +- bun.lock | 41 +------ docs/README.md | 2 +- docs/reference/inputs.md | 6 +- package.json | 1 - src/flows/inputs.ts | 11 +- test/docs/inputs.test.ts | 38 ------ test/scripts/gen-inputs-table.test.ts | 112 +++++++---------- test/scripts/generated.test.ts | 11 +- 11 files changed, 145 insertions(+), 254 deletions(-) delete mode 100644 test/docs/inputs.test.ts diff --git a/.github/scripts/gen-inputs-table.ts b/.github/scripts/gen-inputs-table.ts index 0736bc7f6..0a7d8e17b 100644 --- a/.github/scripts/gen-inputs-table.ts +++ b/.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 = ''; +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>>; -/** 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 { + 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}\``, `

${decl.description}

`, "`false`", defaultSpan(decl.default)]; + }); +} -/** A row action-docs renders: | `name` |

description

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

") && cell.endsWith("

"), - (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>$/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 { + 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({ + 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); } diff --git a/.github/scripts/generated.ts b/.github/scripts/generated.ts index 2730b01e0..80ea30abe 100644 --- a/.github/scripts/generated.ts +++ b/.github/scripts/generated.ts @@ -16,7 +16,7 @@ export interface GeneratedOutput { readonly path: string; /** The package.json script that writes it; `bun run ` 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" }, diff --git a/.github/workflows/auto-fix.yml b/.github/workflows/auto-fix.yml index 451fe8fd1..265eeacb3 100644 --- a/.github/workflows/auto-fix.yml +++ b/.github/workflows/auto-fix.yml @@ -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 diff --git a/bun.lock b/bun.lock index 69930c4bd..a532aa9f9 100644 --- a/bun.lock +++ b/bun.lock @@ -36,7 +36,6 @@ "@types/bun": "1.4.2", "@types/node": "26.6.4", "@types/picomatch": "4.0.3", - "action-docs": "2.5.1", "ajv": "8.20.0", "ajv-formats": "3.0.1", "entities": "8.1.0", @@ -424,8 +423,6 @@ "abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="], - "action-docs": ["action-docs@2.5.1", "", { "dependencies": { "chalk": "^5.3.0", "figlet": "^1.7.0", "replace-in-file": "^7.1.0", "showdown": "^2.1.0", "yaml": "^2.3.4", "yargs": "^17.7.2" }, "bin": { "action-docs": "lib/cli.js" } }, "sha512-kACC20UOsuVifAEYZAAMsm+Lpq14nWXM3FDbIUqUiu7s3KtlGSfRG5btboYIGNomZQ5coTc/UR1F5H9yRqTAEw=="], - "age-encryption": ["age-encryption@0.3.1", "", { "dependencies": { "@noble/ciphers": "^2.1.1", "@noble/curves": "^2.0.1", "@noble/hashes": "^2.0.1", "@noble/post-quantum": "^0.5.3", "@scure/base": "^2.0.0" } }, "sha512-bYgd7lxM7tEANmb9bXf7xTFB3Qpq+JGKinVSdFh5MV+t2fJJZSTdKhWkvXTFJQGysZd+K9Dt3F+n+4DKazXlnQ=="], "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="], @@ -498,7 +495,7 @@ "cli-table3": ["cli-table3@0.6.5", "", { "dependencies": { "string-width": "^4.2.0" }, "optionalDependencies": { "@colors/colors": "1.5.0" } }, "sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ=="], - "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="], + "cliui": ["cliui@7.0.4", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.0", "wrap-ansi": "^7.0.0" } }, "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ=="], "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="], @@ -570,19 +567,15 @@ "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="], - "figlet": ["figlet@1.11.4", "", { "dependencies": { "commander": "^14.0.0" }, "bin": { "figlet": "bin/index.js" } }, "sha512-ZU41480OncL+NVLQrT0GVnbO0COL24sLSrzksioDgunmdJNYEUxhJJZ4Y3x1csN8XXqN5OcCZTLG8lKdquNyfQ=="], - "foreground-child": ["foreground-child@3.3.1", "", { "dependencies": { "cross-spawn": "^7.0.6", "signal-exit": "^4.0.1" } }, "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw=="], "formatly": ["formatly@0.7.0", "", { "dependencies": { "fd-package-json": "^2.0.0", "package-manager-detector": "^1.8.0" }, "bin": { "formatly": "bin/index.mjs" } }, "sha512-7CXJtIIA0zy/u12StsYk25qVKxvdLA2ep2sTNxK3ov0mGNIIDqIvAXDSgTnAfDJFsPfWjuz0WjfYSdpvnLA5Tg=="], - "fs.realpath": ["fs.realpath@1.0.0", "", {}, "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw=="], - "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="], "get-tsconfig": ["get-tsconfig@4.14.3", "", { "dependencies": { "resolve-pkg-maps": "^1.0.0" } }, "sha512-++QEw4DIY7WGoukz+/+A/8dGYPT9l9yIadnmSgZ8Rjr3YVSVDipQSO9CdnJo9ePqFqUUqh+wk9uIaoiAwsiPkA=="], - "glob": ["glob@8.1.0", "", { "dependencies": { "fs.realpath": "^1.0.0", "inflight": "^1.0.4", "inherits": "2", "minimatch": "^5.0.1", "once": "^1.3.0" } }, "sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ=="], + "glob": ["glob@10.5.0", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg=="], "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="], @@ -604,8 +597,6 @@ "import-without-cache": ["import-without-cache@0.4.0", "", {}, "sha512-NkJQA7oZ4YHQhd2+H3BoRFKF3d/XNsiKpHZCQEMH9pDX27hQQLsTyOocyRgaIVtf8gHX3Nt3LPkR4e5EdtPAGQ=="], - "inflight": ["inflight@1.0.6", "", { "dependencies": { "once": "^1.3.0", "wrappy": "1" } }, "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA=="], - "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="], "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="], @@ -750,8 +741,6 @@ "obug": ["obug@2.2.1", "", {}, "sha512-XrsrhT5sybtKI6wakr2SPOlGZWWYbUXZ7a0jT8/QOeAPau+1X/bSegNe5YR75oJmEZQbKningirmGOEJCIk61Q=="], - "once": ["once@1.4.0", "", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="], - "oxc-parser": ["oxc-parser@0.152.0", "", { "dependencies": { "@oxc-project/types": "^0.152.0" }, "optionalDependencies": { "@oxc-parser/binding-android-arm-eabi": "0.152.0", "@oxc-parser/binding-android-arm64": "0.152.0", "@oxc-parser/binding-darwin-arm64": "0.152.0", "@oxc-parser/binding-darwin-x64": "0.152.0", "@oxc-parser/binding-freebsd-x64": "0.152.0", "@oxc-parser/binding-linux-arm-gnueabihf": "0.152.0", "@oxc-parser/binding-linux-arm-musleabihf": "0.152.0", "@oxc-parser/binding-linux-arm64-gnu": "0.152.0", "@oxc-parser/binding-linux-arm64-musl": "0.152.0", "@oxc-parser/binding-linux-ppc64-gnu": "0.152.0", "@oxc-parser/binding-linux-riscv64-gnu": "0.152.0", "@oxc-parser/binding-linux-riscv64-musl": "0.152.0", "@oxc-parser/binding-linux-s390x-gnu": "0.152.0", "@oxc-parser/binding-linux-x64-gnu": "0.152.0", "@oxc-parser/binding-linux-x64-musl": "0.152.0", "@oxc-parser/binding-openharmony-arm64": "0.152.0", "@oxc-parser/binding-win32-arm64-msvc": "0.152.0", "@oxc-parser/binding-win32-ia32-msvc": "0.152.0", "@oxc-parser/binding-win32-x64-msvc": "0.152.0" } }, "sha512-ZztsZgaCWmPeKYMdoTT5e0oV/oxD1NeLWNR3kAtr/G707cUPYaaozRlVDHLCGnszHJRszN9mJwmPNpqgwloC0A=="], "oxc-resolver": ["oxc-resolver@11.24.2", "", { "optionalDependencies": { "@oxc-resolver/binding-android-arm-eabi": "11.24.2", "@oxc-resolver/binding-android-arm64": "11.24.2", "@oxc-resolver/binding-darwin-arm64": "11.24.2", "@oxc-resolver/binding-darwin-x64": "11.24.2", "@oxc-resolver/binding-freebsd-x64": "11.24.2", "@oxc-resolver/binding-linux-arm-gnueabihf": "11.24.2", "@oxc-resolver/binding-linux-arm-musleabihf": "11.24.2", "@oxc-resolver/binding-linux-arm64-gnu": "11.24.2", "@oxc-resolver/binding-linux-arm64-musl": "11.24.2", "@oxc-resolver/binding-linux-ppc64-gnu": "11.24.2", "@oxc-resolver/binding-linux-riscv64-gnu": "11.24.2", "@oxc-resolver/binding-linux-riscv64-musl": "11.24.2", "@oxc-resolver/binding-linux-s390x-gnu": "11.24.2", "@oxc-resolver/binding-linux-x64-gnu": "11.24.2", "@oxc-resolver/binding-linux-x64-musl": "11.24.2", "@oxc-resolver/binding-openharmony-arm64": "11.24.2", "@oxc-resolver/binding-wasm32-wasi": "11.24.2", "@oxc-resolver/binding-win32-arm64-msvc": "11.24.2", "@oxc-resolver/binding-win32-x64-msvc": "11.24.2" } }, "sha512-FY91FiDBj7ls5MsFS9jN3tjz2o0/zsdSsymlakySaBwVJZorHhkWyICLZMKxlu1R9vYo+sd3z1jwb4J8x7bNDw=="], @@ -786,8 +775,6 @@ "readdir-glob": ["readdir-glob@1.1.3", "", { "dependencies": { "minimatch": "^5.1.0" } }, "sha512-v05I2k7xN8zXvPD9N+z/uhXPaj0sUFCe2rcWZIpBsqxfP7xXFQ0tipAd/wjj1YxWyWtUS5IDJpOG82JKt2EAVA=="], - "replace-in-file": ["replace-in-file@7.2.0", "", { "dependencies": { "chalk": "^4.1.2", "glob": "^8.1.0", "yargs": "^17.7.2" }, "bin": { "replace-in-file": "bin/cli.js" } }, "sha512-CiLXVop3o8/h2Kd1PwKPPimmS9wUV0Ki6Fl8+1ITD35nB3Gl/PrW5IONpTE0AXk0z4v8WYcpEpdeZqMXvSnWpg=="], - "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="], "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="], @@ -808,8 +795,6 @@ "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="], - "showdown": ["showdown@2.1.0", "", { "dependencies": { "commander": "^9.0.0" }, "bin": { "showdown": "bin/showdown.js" } }, "sha512-/6NVYu4U819R2pUIk79n67SYgJHWCce0a5xTP979WbNp0FL9MN1I1QK662IDU1b6JzKTvmhgI7T7JYIxBi3kMQ=="], - "signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="], "skin-tone": ["skin-tone@2.0.0", "", { "dependencies": { "unicode-emoji-modifier-base": "^1.0.0" } }, "sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA=="], @@ -898,17 +883,15 @@ "wrap-ansi-cjs": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="], - "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="], - "xml-naming": ["xml-naming@0.3.0", "", {}, "sha512-ghig2TBE/H11aOVgmahA3MhimvkBr6JIYknH/Dhdk10nXwdbIqBJsbfMxpvFPG8bAw77gN29aQWvKpmVoPlvPQ=="], "y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="], "yaml": ["yaml@2.9.1", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw=="], - "yargs": ["yargs@17.7.3", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g=="], + "yargs": ["yargs@16.2.2", "", { "dependencies": { "cliui": "^7.0.2", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.0", "y18n": "^5.0.5", "yargs-parser": "^20.2.2" } }, "sha512-Nt9ZJjXTv5R8MHbqby/wXQ6Gi0Bb3TcYZkR1bzuL4yB2OxWPkXknz513gEF0GoA6tn00UpbPvERW8rzCuWCA6w=="], - "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="], + "yargs-parser": ["yargs-parser@20.2.9", "", {}, "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w=="], "yuku-ast": ["yuku-ast@0.9.5", "", { "dependencies": { "@yuku-toolchain/types": "^0.9.5" } }, "sha512-Q8qW8WwQnN5Cm0ZZivdRIfv0sRLTjUq0YumXJkw8CYN1aCdICH9rk4C47/4n6kA5EqDtlj+F608twoTSV2MwdQ=="], @@ -952,13 +935,7 @@ "@protobuf-ts/plugin/typescript": ["typescript@3.9.10", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-w6fIxVE/H1PkLKcCPsFqKE7Kv7QUwhU8qQY2MueZXWx5cPZdwFupLgKK3vntcK98BtNHZtAF4LA/yl2a7k8R6Q=="], - "action-docs/chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="], - - "archiver-utils/glob": ["glob@10.5.0", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg=="], - - "cli-highlight/yargs": ["yargs@16.2.2", "", { "dependencies": { "cliui": "^7.0.2", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.0", "y18n": "^5.0.5", "yargs-parser": "^20.2.2" } }, "sha512-Nt9ZJjXTv5R8MHbqby/wXQ6Gi0Bb3TcYZkR1bzuL4yB2OxWPkXknz513gEF0GoA6tn00UpbPvERW8rzCuWCA6w=="], - - "figlet/commander": ["commander@14.0.3", "", {}, "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw=="], + "glob/minimatch": ["minimatch@9.0.9", "", { "dependencies": { "brace-expansion": "^2.0.2" } }, "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg=="], "knip/oxc-parser": ["oxc-parser@0.150.0", "", { "dependencies": { "@oxc-project/types": "^0.150.0" }, "optionalDependencies": { "@oxc-parser/binding-android-arm-eabi": "0.150.0", "@oxc-parser/binding-android-arm64": "0.150.0", "@oxc-parser/binding-darwin-arm64": "0.150.0", "@oxc-parser/binding-darwin-x64": "0.150.0", "@oxc-parser/binding-freebsd-x64": "0.150.0", "@oxc-parser/binding-linux-arm-gnueabihf": "0.150.0", "@oxc-parser/binding-linux-arm-musleabihf": "0.150.0", "@oxc-parser/binding-linux-arm64-gnu": "0.150.0", "@oxc-parser/binding-linux-arm64-musl": "0.150.0", "@oxc-parser/binding-linux-ppc64-gnu": "0.150.0", "@oxc-parser/binding-linux-riscv64-gnu": "0.150.0", "@oxc-parser/binding-linux-riscv64-musl": "0.150.0", "@oxc-parser/binding-linux-s390x-gnu": "0.150.0", "@oxc-parser/binding-linux-x64-gnu": "0.150.0", "@oxc-parser/binding-linux-x64-musl": "0.150.0", "@oxc-parser/binding-openharmony-arm64": "0.150.0", "@oxc-parser/binding-win32-arm64-msvc": "0.150.0", "@oxc-parser/binding-win32-ia32-msvc": "0.150.0", "@oxc-parser/binding-win32-x64-msvc": "0.150.0" } }, "sha512-zwajKw1GUa57IOdafIS7/yOObGF2NihwIfZfs5yJTRprMSkiwhWOc/k+n8bwnUPbHr2/XsjfBO8KyTPaW3VpWg=="], @@ -974,8 +951,6 @@ "rolldown-plugin-dts/get-tsconfig": ["get-tsconfig@5.0.0-beta.6", "", { "dependencies": { "resolve-pkg-maps": "^1.0.0" } }, "sha512-X6fBC0pmImC70gvX2zm56go9hx0MyoGVdG0tUCkg/D+Xnh5TJsOZ7iDbOdI3PvmtrDxnu1YdDufpK2QJX1Meqw=="], - "showdown/commander": ["commander@9.5.0", "", {}, "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ=="], - "strip-ansi/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], "strip-ansi-cjs/ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="], @@ -992,12 +967,6 @@ "@octokit/plugin-throttling/@octokit/types/@octokit/openapi-types": ["@octokit/openapi-types@28.0.0", "", {}, "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ=="], - "archiver-utils/glob/minimatch": ["minimatch@9.0.9", "", { "dependencies": { "brace-expansion": "^2.0.2" } }, "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg=="], - - "cli-highlight/yargs/cliui": ["cliui@7.0.4", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.0", "wrap-ansi": "^7.0.0" } }, "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ=="], - - "cli-highlight/yargs/yargs-parser": ["yargs-parser@20.2.9", "", {}, "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w=="], - "knip/oxc-parser/@oxc-parser/binding-android-arm-eabi": ["@oxc-parser/binding-android-arm-eabi@0.150.0", "", { "os": "android", "cpu": "arm" }, "sha512-oQef2Zu4Prz1KLKznz3HqZzU9uVoA5PMoDZuuLmqms7hKmKSAPzlaMnLllJq3t+rgKmfJJ2siPrpZfFrW06btw=="], "knip/oxc-parser/@oxc-parser/binding-android-arm64": ["@oxc-parser/binding-android-arm64@0.150.0", "", { "os": "android", "cpu": "arm64" }, "sha512-B6ofpoFiAUwIZ0MJ2IgHPvZK8FAtL4qzSZRwOkAKIfxEobE1mQC8nDdiFZj7pUaJiVUVCsfkMsBJKedzO8rZvA=="], diff --git a/docs/README.md b/docs/README.md index dab086724..541a5cb03 100644 --- a/docs/README.md +++ b/docs/README.md @@ -72,7 +72,7 @@ The [playbooks](playbooks/README.md) compose the pieces above into end-to-end se Generated regions carry the load-bearing facts. Each is rendered from its declarations or generator data by `bun run build:docs`, `bun run build:action-docs`, and `bun run build:inputs-table`, and `build:check` fails when a committed page drifts: - the [Sections](reference/sections.md) table and the `result` values on the inputs page; -- the [Inputs](reference/inputs.md) table, which [action-docs](https://github.com/npalm/action-docs) renders from `action.yml`; +- the [Inputs](reference/inputs.md) table, rendered from the input declarations in `src/flows/inputs.ts`; - the [Coverage](reference/coverage.md) tables and notes, the per-section detail behind the Sections table; - the defaults table and count in [undeclared policy](reference/undeclared-policy.md); - the grant sentence and gated-read bullets in [permissions](reference/permissions.md) and [check mode](operate/check-mode.md); diff --git a/docs/reference/inputs.md b/docs/reference/inputs.md index 4d8403b6a..e0ca45a22 100644 --- a/docs/reference/inputs.md +++ b/docs/reference/inputs.md @@ -8,12 +8,12 @@ Every `with:` input the action accepts, and the outputs it sets for the steps af A list input (`sections`, `required-sections`, `repos`, `exclude`, `topics`, `affiliation`, and `settings-file` in `mode: render`) takes newline- or comma-separated values. `settings-file` is split the same way in every mode, so no settings file path can contain a comma. - +

- ## Inputs + | name | description | required | default | | --- | --- | --- | --- | | `token` |

The token for the API calls: a fine-grained PAT, since the default GITHUB_TOKEN can never hold the Administration grant most sections need.

| `false` | `${{ github.token }}` | @@ -41,7 +41,7 @@ A list input (`sections`, `required-sections`, `repos`, `exclude`, `topics`, `af | `exclude` |

Comma- or newline-separated glob patterns removing repositories from repos: "*" discovery, compared case-insensitively against owner/name when the pattern has a "/" and against the name alone otherwise. A star matches any run of characters, "?" one character, "[abc]" one of a set, "[!abc]" or "[^abc]" one outside it, and one leading "!" negates the pattern. Beyond those a pattern holds only letters, digits, ".", "-", and "_", with at most one "/", nothing empty around it, and no side that is just "." or ".."; anything else (a leading "./", a run of stars, a regex token such as "(a)+") fails the run naming the fix.

| `false` | `""` | | `topics` |

Comma- or newline-separated topics, of which repos: "*" discovery keeps the repositories carrying at least one.

| `false` | `""` | | `affiliation` |

Comma- or newline-separated affiliations for repos: "*" discovery: owner (default), collaborator, or organization_member.

| `false` | `""` | - +
diff --git a/package.json b/package.json index 0672da171..f600835f7 100644 --- a/package.json +++ b/package.json @@ -92,7 +92,6 @@ "@types/bun": "1.4.2", "@types/node": "26.6.4", "@types/picomatch": "4.0.3", - "action-docs": "2.5.1", "ajv": "8.20.0", "ajv-formats": "3.0.1", "entities": "8.1.0", diff --git a/src/flows/inputs.ts b/src/flows/inputs.ts index 72607acca..708bc57fb 100644 --- a/src/flows/inputs.ts +++ b/src/flows/inputs.ts @@ -27,9 +27,8 @@ export const DEFAULT_LAYERING = "deep" satisfies Layering; */ export interface InputDecl { /** - * The action.yml description; the generator folds it to width. Plain prose: action-docs runs it through a - * markdown renderer for the docs table, so a paired "*" or "_" would italicize, "..." would become an - * ellipsis, a "|" would split the cell, and a "<" would open a tag (test/docs/inputs.test.ts pins the rendering). + * The action.yml description; the generator folds it to width. Plain prose: the inputs table renders it inside + * an HTML cell, so a "|" would split the row and a "<" would open a tag; gen-inputs-table.ts refuses both. */ readonly description: string; /** The action.yml default, verbatim (an empty string means "unset"). */ @@ -43,9 +42,9 @@ export interface InputDecl { } /** - * The single source action.yml is generated from (bun run build:action-docs), in its listing order; the inputs - * reference page's table is action-docs's rendering of that action.yml (bun run build:inputs-table). Adding an - * input here is the whole declaration. A new mode's inputs go beside their mode's. + * The single source action.yml (bun run build:action-docs) and the inputs reference page's table (bun run + * build:inputs-table) are generated from, in its listing order. Adding an input here is the whole declaration. A + * new mode's inputs go beside their mode's. */ export const INPUT_DECLS = { token: { diff --git a/test/docs/inputs.test.ts b/test/docs/inputs.test.ts deleted file mode 100644 index c0513ba3c..000000000 --- a/test/docs/inputs.test.ts +++ /dev/null @@ -1,38 +0,0 @@ -import { expect, test } from "bun:test"; -import { readFileSync } from "node:fs"; -import { join } from "node:path"; -import { INPUTS_PAGE_PATH, MARKER } from "../../.github/scripts/gen-inputs-table.js"; -import { INPUT_DECLS } from "../../src/flows/inputs.js"; -import { ROOT } from "../root.js"; - -/** - * action-docs runs each description through a markdown renderer before it reaches the table cell, so prose action.yml - * and the CLI help show verbatim can come out italicized (a paired "*" or "_"), as an ellipsis character ("..."), or - * swallowed as an HTML tag (""); nothing else on the page would notice. The region is pinned whole (the - * heading, one row per declaration verbatim and in order, nothing else), the same shape gen-inputs-table.ts refuses - * to regenerate over. A "|" and a "<" are the two characters the row comparison cannot catch: the renderer passes - * both through, so the expected row carries the split cell or the raw tag too. - */ -test("the inputs table region is exactly action-docs's ASCII rendering of every declaration", () => { - const page = readFileSync(join(ROOT, INPUTS_PAGE_PATH), "utf8"); - const parts = page.split(MARKER); - expect(parts).toHaveLength(3); - const region = parts[1] ?? ""; - const rows = Object.entries(INPUT_DECLS).map( - ([name, decl]) => - `| \`${name}\` |

${decl.description}

| \`false\` | \`${decl.default === "" ? '""' : decl.default}\` |`, - ); - expect(region.split("\n")).toEqual([ - "", - "## Inputs", - "", - "| name | description | required | default |", - "| --- | --- | --- | --- |", - ...rows, - "", - ]); - expect(region).toMatch(/^[\x20-\x7e\n]*$/); - for (const [name, decl] of Object.entries(INPUT_DECLS)) { - expect(decl.description, `the "${name}" description holds a "|" or a "<"`).not.toMatch(/[|<]/); - } -}); diff --git a/test/scripts/gen-inputs-table.test.ts b/test/scripts/gen-inputs-table.test.ts index 799d3c3b8..ab1a5d92c 100644 --- a/test/scripts/gen-inputs-table.test.ts +++ b/test/scripts/gen-inputs-table.test.ts @@ -1,78 +1,56 @@ -import { expect, test } from "bun:test"; +import { describe, expect, test } from "bun:test"; import { readFileSync } from "node:fs"; import { join } from "node:path"; -import { INPUTS_PAGE_PATH, MARKER, regionProblem } from "../../.github/scripts/gen-inputs-table.js"; +import { + INPUTS_PAGE_PATH, + INPUTS_PAGES, + renderInputsTable, +} from "../../.github/scripts/gen-inputs-table.js"; +import { regionBounds } from "../../.github/scripts/lib/generated-regions.js"; +import { regenerateFile } from "../../.github/scripts/lib/region-driver.js"; import { ROOT } from "../root.js"; const page = readFileSync(join(ROOT, INPUTS_PAGE_PATH), "utf8"); -const [intro, region, tail] = page.split(MARKER) as [string, string, string]; -const pageLine = (text: string, needle: string): number => - text.slice(0, text.indexOf(needle)).split("\n").length; -const refusal = (line: number): RegExp => +const { begin, end } = regionBounds(page, "inputs-table", "html"); +const [intro, body, tail] = [ + page.slice(0, begin[1]), + page.slice(begin[1], end[0]), + page.slice(end[0]), +]; +const regenerate = (text: string): string => regenerateFile(INPUTS_PAGES, INPUTS_PAGE_PATH, text); +/** The seal's refusal of the inputs-table region, naming the line below the BEGIN marker. */ +const refusal = (lineBelowBegin: number): RegExp => new RegExp( - `^line ${line} of docs/reference/inputs.md .*not a line of a rendered inputs table; move the markers back`, + `^the inputs-table region in docs/reference/inputs.md encloses content .*\\(line ${lineBelowBegin} `, ); -/** action-docs itself accepts every one of these pages and rewrites the region; only the guard tells them apart. */ -test("the committed page and a fresh marker pair pass; a marker moved over prose is refused naming the line, a lone marker naming the count", () => { - expect(regionProblem(page)).toBeNull(); - expect(regionProblem(`${intro}${MARKER}\n${MARKER}${tail}`)).toBeNull(); - const paragraphEnd = tail.indexOf("\n\n## "); - const swallowing = `${intro}${MARKER}${region}${tail.slice(0, paragraphEnd)}\n${MARKER}${tail.slice(paragraphEnd)}`; - // The first swallowed line is the first blank after the rows: a rendering's only blank there is the line before the - // closing marker, and the moved marker leaves the page's own blank lines and its closing div in the region. - expect(regionProblem(swallowing)).toMatch(refusal(pageLine(swallowing, "\n\n"))); - expect(regionProblem(`${intro}${MARKER}${region}${tail}`)).toMatch( - /exactly two .* markers, found 1/, - ); - expect(regionProblem(`${intro}${MARKER}${region}${MARKER}${MARKER}${tail}`)).toMatch(/found 3/); - // action-docs replaces only the opening marker of an adjacent pair, leaving three on the page. - expect(regionProblem(`${intro}${MARKER}${MARKER}${tail}`)).toMatch( - new RegExp( - `^the closing .* marker on line ${pageLine(intro, "
") + 2} of .* must start its own line`, - ), - ); -}); +describe("the inputs table region", () => { + test("the committed page regenerates to itself and a fresh marker pair renders the table", () => { + expect(regenerate(page)).toBe(page); + expect(regenerate(`${intro}\n${tail}`)).toBe(page); + }); -/** A guard that checked only the `| ` prefix let action-docs erase the first two, and one that counted cells the - * third: an authored line that looks like a row, an authored table of another width, and an authored four-cell row - * with bare cells. Each is placed where a moved marker would swallow it. */ -test.each([ - ["| authored prose", "a one-cell line"], - ["| a | b |\n| --- | --- |\n| 1 | 2 |", "a two-column table"], - [ - "| Keep this warning | It is authored prose | do not erase | note |", - "a four-cell row with bare cells", - ], -])("%p between the markers is refused naming its line (%s)", (authored) => { - const swallowing = `${intro}${MARKER}${region}${authored}\n${MARKER}${tail}`; - expect(regionProblem(swallowing)).toMatch(refusal(pageLine(swallowing, authored))); - const replacing = `${intro}${MARKER}\n${authored}\n${MARKER}${tail}`; - expect(regionProblem(replacing)).toMatch(refusal(pageLine(replacing, authored))); -}); + /** A parse that checked only the cell count let an authored four-cell row through; each shape is placed where a moved marker would swallow it. */ + test.each([ + ["| authored prose", "a one-cell line"], + ["| a | b |\n| --- | --- |\n| 1 | 2 |", "a two-column table"], + [ + "| Keep this warning | It is authored prose | do not erase | note |", + "a four-cell row with bare cells", + ], + ])("%p between the markers is refused naming its line (%s)", (authored) => { + const rows = body.split("\n").length - 2; + expect(() => regenerate(`${intro}${body}${authored}\n${tail}`)).toThrow(refusal(rows + 1)); + expect(() => regenerate(`${intro}\n${authored}\n${tail}`)).toThrow(refusal(1)); + }); -/** The check is one split per line, so a row of thousands of cells costs what its length costs; the four-cell regex - * this replaced backtracked exponentially on exactly this row (CodeQL's inefficient-regular-expression alert). */ -test("a 30-row table whose last row is malformed is refused naming that row, in linear time", () => { - const rows = Array.from( - { length: 29 }, - (_, i) => `| \`in${i}\` |

text

| \`false\` | \`""\` |`, - ); - const malformed = `| \`_\` | ${" | `true` | `true` | `` | `_` |".repeat(5000)}`; - const table = [ - "", - "## Inputs", - "", - "| name | description | required | default |", - "| --- | --- | --- | --- |", - ...rows, - malformed, - "", - ]; - const swallowing = `${intro}${MARKER}${table.join("\n")}${MARKER}${tail}`; - const started = performance.now(); - const problem = regionProblem(swallowing); - const elapsed = performance.now() - started; - expect(problem).toMatch(refusal(pageLine(swallowing, malformed))); - expect(elapsed).toBeLessThan(2000); + test('a description holding "<" is refused on both sides, since the cell would read it as a tag', () => { + // The page's renderer swallows an HTML tag inside the cell; nothing else on the page would notice. + expect(() => + renderInputsTable({ repos: { description: "the /name", default: "" } }), + ).toThrow('gen-inputs-table: the "repos" description holds a "<"'); + const tagged = body.replace("

The token", "

The "); + expect(tagged).not.toBe(body); + expect(() => regenerate(`${intro}${tagged}${tail}`)).toThrow(refusal(3)); + }); }); diff --git a/test/scripts/generated.test.ts b/test/scripts/generated.test.ts index 7dbea95fc..58036c2af 100644 --- a/test/scripts/generated.test.ts +++ b/test/scripts/generated.test.ts @@ -18,8 +18,6 @@ import { withTempDir } from "../temp-dir.js"; /** Only a file type with a marker syntax carries a region; a marker string anywhere else is test or script text. */ const regionFile = (path: string): boolean => extname(path) in SYNTAX_BY_EXTENSION; -/** action-docs's own region markers, the one grammar lib/generated-regions.ts does not read. */ -const ACTION_DOCS_MARKER = /