chore(docs): render the inputs table with action-docs and run the generators by their package.json scripts

[Vivswan]

Before

docs/reference/inputs.md, rendered by .github/scripts/gen-action-docs.ts from a summary and shownDefault per input:

| Input | Default | Meaning |
|---|---|---|
| `token` | `github.token` | Token for the API calls (see [Token permissions](permissions.md)) |
| `visibility` | `all` | Discovery-only: keep `public`, `private`, or `internal` repositories |

After

docs/reference/inputs.md, rendered by action-docs from action.yml between its own markers (bun run build:inputs-table):

| name | description | required | default |
| --- | --- | --- | --- |
| `token` | <p>Token used for the API calls. Most sections need a fine-grained PAT with Administration read/write on the repository - the default GITHUB_TOKEN can never hold that permission.</p> | `false` | `${{ github.token }}` |
| `visibility` | <p>Keeps only repositories of this visibility in repos: "*" discovery. One of all (default), public, private, or internal; internal is matched client-side (Enterprise only). Fails if set outside that discovery.</p> | `false` | `""` |

$ bun run build:check          # after editing one description in src/flows/inputs.ts
regenerated action.yml
gen-inputs-table: rendered docs/reference/inputs.md from action.yml
 action.yml               | 2 +-
 docs/reference/inputs.md | 2 +-
build:check: the generated output listed above drifted from the committed tree; run bun run build and commit it

$ bun run build:inputs-table   # with a prose line moved between the markers
gen-inputs-table: line 41 of docs/reference/inputs.md sits between the two "<!-- action-docs-inputs source="action.yml" -->" 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

$ bun run build:inputs-table   # with `| authored prose` on the line after the last row
gen-inputs-table: line 41 of docs/reference/inputs.md sits between the two "<!-- action-docs-inputs source="action.yml" -->" 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

How

• One text per input. The summary and shownDefault fields leave InputDecl; the action.yml description is what the page, the manifest, and the CLI help all show.
• action-docs owns the region. build:inputs-table runs .github/scripts/gen-inputs-table.ts, which calls generateActionMarkdownDocs on action.yml with the page as its target.
• The region is checked before it is overwritten. The lines between the two markers must be, in order, the ## Inputs heading, a blank, the header row, its | --- | separator, one row per input in the renderer's cell shape (backticked name, <p> description, `true`/`false`, backticked default), and a closing blank. The first line off that shape is refused by its page line number: action-docs rewrites the region blind and auto-fix.yml pushes regenerations unreviewed.
• The guard is one split per line, no regex. Each table line is split on | and its cell count compared, so a row of thousands of cells costs its length and nothing more; the four-cell regex an earlier revision used backtracked exponentially on such a row (CodeQL alert 104).
• Descriptions stay verbatim through the markdown renderer. Ten descriptions drop a paired asterisk, an ellipsis, or an angle-bracket placeholder, and test/docs/inputs.test.ts pins the whole region to the declarations, ASCII only and with no pipe or angle bracket in any description (the two characters the renderer passes through, so a verbatim comparison alone would not notice).
• The site renders the region literally. The page wraps the markers in a <div v-pre>, the same device the secrets page uses, so the site's Vue renderer leaves the token default's workflow expression alone.
• Generators run by their package.json scripts. The drift runner in .github/scripts/generated.ts (build, then git diff --exit-code --stat plus an untracked-file check) already exists on main; this change keys its table by script name (bun run <generator>), reworded its failure, and adds two rows: build:gaps-index first (the bundle, the library, and the later generators import the index through src/) and build:inputs-table last, so build, build:check, and auto-fix.yml run the one list.
• The gaps index renders first. build:bundle, build:lib, and the schema, docs, and action.yml generators import src/upstream-gaps/index.ts through src/, so build:gaps-index opens the build chain, the generated-output table, and auto-fix.yml's rebuild step; test/scripts/generated.test.ts pins it ahead of the bundle and the library.

Proof

• Tests: bun test test/scripts/gen-inputs-table.test.ts test/scripts/generated.test.ts test/scripts/auto-fix-allowlist.test.ts test/docs/inputs.test.ts: 21 pass, 0 fail (2 new files); CI runs the suite.
• Gates: typecheck, knip, lint, bun run build:inputs-table with an unchanged page, and bun run build:check green on a clean tree.
• RED: a description edited at its source fails build:check naming both action.yml and docs/reference/inputs.md (block above); a stale byte staged in the rendered table fails it naming docs/reference/inputs.md; a prose line moved between the markers fails build:inputs-table naming its line (block above); reverting each restores green.
• RED, the guard's shape: against the previous prefix-only guard, | authored prose and a two-column | a | b | table between the markers return null (three new cases fail on it: Received value must be a string: null); on this guard each is refused naming its line, whether it follows the rows or replaces the table. A four-cell row of bare cells (| Keep this warning | It is authored prose | do not erase | note |) passes a count-only check and is refused here. Two markers on one line are refused naming the line, since action-docs replaces only the opening one of an adjacent pair and leaves three on the page. A 30-row table whose last row is one 5000-cell malformed line is refused naming that row; the check is linear (one split per line) and the test bounds it at 2 s.
• Build order: the order test fails on the previous build chain (bundle and library before the gaps index) and passes on this one.
• Site build: a throwaway VitePress build of the page without the v-pre div fails with the same TypeError the docs-check job printed; with it, the build completes and the HTML carries the expression and the Inputs heading anchor.
• Standalone script: importing gen-inputs-table.ts pulls in every generator through generated.ts when the page path comes from there, and imports only action-docs when the path is declared in the script itself; the script now owns it.
• action-docs output is ASCII: the region test rejects any byte outside printable ASCII.

Line accounting by kind

A library replacement that nets positive lines: the tests gain more than the scripts lose, since two new files pin the region and the guard, the guard checks the table's structure and cell shape rather than a line prefix, action-docs brings its lockfile entries, and the rendered table carries full descriptions where the old one carried one-line summaries.

Kind	Added	Deleted	Net
Scripts and source (.github/scripts/*.ts, src/flows/inputs.ts)	175	145	+30
Tests (test/)	213	98	+115
Generated output (action.yml, docs/reference/inputs.md)	65	58	+7
Docs prose (docs/README.md)	3	2	+1
Config and lockfile (package.json, bun.lock, auto-fix.yml)	49	11	+38
Total	505	314	+191

Reviewer note

• Information the table lost. The one-line Meaning gist per input is gone; the cell now carries the full description. The effective-default column is gone: "" means unset, and the description names the effective default the same way for every discovery filter (all (default), skip (default, include (default), owner (default)), which test/action/action-yml.test.ts pins. The two links the Meaning cells carried (permissions, undeclared policy) moved into the page's intro paragraph.
• Information that moved into action.yml descriptions. Ten descriptions are reworded for the markdown renderer: <owner>/<name>.yml becomes owner/name.yml, ... becomes and so on, the quoted age1... becomes a public key starting with age1, "*" matches becomes An asterisk matches, and the six discovery filters end with Fails if set outside that discovery instead of a second repos: "*". The sections description now says an omitted input processes every declared section (the old (all declared) cell), and affiliation marks owner (default) like the other filters.
• What stayed hand-rolled and why. action.yml itself, the outputs region, and the permissions grant sentences in gen-action-docs.ts stay in-house: action-docs renders markdown from action.yml, it does not write action.yml or derive grants from the sections' declared reads and writes. The region guard in gen-inputs-table.ts stays because action-docs offers no check of what it is about to overwrite; it checks the table's structure by position (heading, header row, separator, rows in the renderer's cell shape), and what a description may hold inside its <p> stays the renderer's own grammar. The render is its own build:inputs-table script rather than part of build:docs, because build:docs runs before build:action-docs writes the action.yml it reads.
• A blank line among the rows is refused too. The check is positional, so an extra blank or a second heading between rows is named as the offending line even though it holds nothing to lose; action-docs never writes one, and the fix is the same move of the markers back around the table. The prose case in the test names the first blank after the rows for this reason.
• A truncated rendering passes. A region holding only the first lines of a rendering (the heading alone, or the header row and separator with no rows) is accepted: none of those lines is authored, so nothing can be lost, and action-docs writes the full table over them. Requiring the whole shape would add a code path and a message for a state with no harm.
• A guard deliberately not carried over. The in-house marker grammar refuses a marker sitting inside a fenced code block; action-docs's markers get no such check, so a marker pair wrapped in raw HTML such as <pre> is now accepted where the in-house grammar refused it. The region test pins the table whole and the guard pins its table shape, and a fence around the markers is not a drift anyone has produced, so it is recorded here rather than built.
• generated.ts stays. knip keeps it: the tests read its table and the drift runner is its main.
• A hand-forged renderer row is not caught. An authored line written in the renderer's exact cell shape (| \note` |

  Keep this

  | `false` | `""` |`) passes the check and is overwritten. The next rung, requiring the name cell to be an input declared in action.yml, is recorded here rather than built: nothing produces such a line, and the region test pins the table whole.

BEGIN_COMMIT_OVERRIDE
chore(docs): render the inputs table with action-docs and run the generators by their package.json scripts

The inputs table on docs/reference/inputs.md is now action-docs's rendering of action.yml between its own markers, written by the build:inputs-table script.
The in-house table renderer, its link rebasing, and the summary and shownDefault fields of every input declaration go; action.yml's description is the one text the page, the manifest, and the CLI help share.
Ten descriptions are reworded so the markdown renderer inside action-docs leaves them verbatim: at most one asterisk per text, no ellipsis, no angle-bracket placeholders.
The sections description says what an omitted input means and the affiliation description marks its default like the other discovery filters, since the table no longer has an effective-default column.
The page wraps the region in a v-pre div, since the site's Vue renderer would otherwise evaluate the token default's workflow expression and fail the build.
build:inputs-table runs .github/scripts/gen-inputs-table.ts, which refuses a marker region holding anything but a rendering's lines in order, naming the first other line: action-docs rewrites the region blind and auto-fix pushes it unreviewed.
The region check is structural and regex-free, one split per line: the heading, the header row and its separator, then rows carrying the renderer's cell quoting, so an authored pipe-led line, a table of another width, or a row of bare cells is refused too.
test/docs/inputs.test.ts pins the whole region between the markers to the declarations, verbatim and ASCII with no pipe or angle bracket in any description, so a cell the markdown renderer mangled fails CI.
The generated-output table in .github/scripts/generated.ts names each generator by its package.json script, so build:check, bun run build, and auto-fix.yml run the one list.
The gaps index gets build:gaps-index and runs first in that list, since the bundle, the library, and the later generators import it through src/ and would otherwise build over a stale index when a gap file is added.
END_COMMIT_OVERRIDE

[github-actions]

File size check

0 over a hard cap (fails), 32 warning(s).

File	Size	Tier	Cap
.github/scripts/gen-inputs-table.ts:54	11 comment lines	warn	10
.github/scripts/generated.ts:28	200 chars	warn	150
.github/scripts/release-pipeline.ts:6	156 chars	warn	150
.github/scripts/release-pipeline.ts:453	151 chars	warn	150
.github/scripts/release-pipeline.ts:1247	153 chars	warn	150
.github/scripts/release-pipeline.ts:1	34 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:449	14 comment lines	warn	10
.github/workflows/post-green.yml:29	153 chars	warn	150
.github/workflows/update-release-pr.yml:109	14 comment lines	warn	10
docs/upgrading/v2-to-v3.md	1276 lines	warn	1040
src/engine/layers.ts:217	157 chars	warn	150
src/flows/settings-write.ts:142	159 chars	warn	150
src/flows/settings-write.ts:30	11 comment lines	warn	10
src/flows/snapshot.ts:189	13 comment lines	warn	10
src/github/secret-scan.ts:42	11 comment lines	warn	10
src/schema.ts:186	153 chars	warn	150
src/schema.ts:197	176 chars	warn	150
src/sections/contract/errors.ts:14	14 comment lines	warn	10
src/sections/contract/module.ts:963	185 chars	warn	150
src/sections/contract/module.ts:627	12 comment lines	warn	10
src/sections/contract/module.ts:897	12 comment lines	warn	10
src/sections/secret_scanning_custom_patterns/compilable-form.ts:382	161 chars	warn	150
src/sections/shared/roles.ts:43	13 comment lines	warn	10
src/types.ts:16	156 chars	warn	150
test/docs/guides.test.ts:451	155 chars	warn	150
test/e2e/generators.ts	2633 lines	warn	2560
test/e2e/generators.ts:1703	166 chars	warn	150
test/e2e/generators.ts:1857	161 chars	warn	150
test/e2e/generators.ts:1666	12 comment lines	warn	10
test/engine/execute.test.ts:617	152 chars	warn	150
test/flows/merge-parity.test.ts:63	164 chars	warn	150
test/scripts/auto-fix-allowlist.test.ts:12	12 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

[Copilot]

Copilot review overview

🟡 Changes recommended

The action-docs lockfile specifier disagrees with package.json, breaking frozen dependency installation.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: None

What changed in this PR

Replaces the custom inputs reference renderer with action-docs and unifies generated-output checking.

Changes:

• Generates the inputs table from action.yml with overwrite guards.
• Runs registered generators through package scripts and checks drift with Git.
• Adds coverage for rendering, generated files, and auto-fix behavior.

File	Description
.github/​scripts/​gen-action-docs.ts	Removes the custom inputs-table renderer.
.github/​scripts/​gen-inputs-table.ts	Adds guarded action-docs generation.
.github/​scripts/​generated.ts	Registers and runs generator scripts.
.github/​workflows/​auto-fix.yml	Regenerates the inputs table and gaps index.
action.yml	Updates generated input descriptions.
bun.lock	Adds action-docs dependencies.
docs/​README.md	Documents the new generator.
docs/​reference/​inputs.md	Contains the generated inputs table.
package.json	Adds dependency and build scripts.
src/​flows/​inputs.ts	Consolidates input documentation.
test/​action/​action-yml.test.ts	Updates effective-default assertions.
test/​docs/​inputs.test.ts	Verifies exact ASCII table rendering.
test/​scripts/​auto-fix-allowlist.test.ts	Verifies generator workflow alignment.
test/​scripts/​gen-action-docs.test.ts	Removes obsolete renderer tests.
test/​scripts/​gen-inputs-table.test.ts	Tests marker-region protection.
test/​scripts/​generated.test.ts	Tests script registration and drift detection.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Vivswan]

Fixed in the amended commit: bun.lock now pins action-docs 2.5.1 exactly as package.json does.

[Copilot]

Copilot review overview

🟡 Changes recommended

The rendering contract test does not reject angle-bracket placeholders that action-docs treats as HTML.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Test should reject angle-bracket placeholders in descriptions · New

[Copilot]

Copilot review overview

🟡 Changes recommended

The build runs library generation before regenerating the upstream-gaps index, preventing new gaps from bootstrapping successfully.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Generate gaps index before building library · New

Resolved since last review (1)

• Test should reject angle-bracket placeholders in descriptions

[Copilot]

Copilot review overview

🔵 Needs a closer look

The build order can generate npm declarations from a stale upstream-gaps index.

Review effort: Balanced
Findings: 1

Open (1)

• Generate gaps index before building library

[Copilot]

Copilot review overview

🟡 Changes recommended

The inputs-table guard accepts arbitrary pipe-prefixed content that action-docs can erase.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Require full four-cell row shape before moving markers · New

Resolved since last review (1)

• Generate gaps index before building library

[Copilot]

Copilot review overview

🟢 Approval recommended

The generation pipeline, guarded replacement region, artifacts, workflow integration, and regression coverage are consistent.

Review effort: Balanced
Findings: 1

Open (1)

• Require full four-cell row shape before moving markers

Resolved since last review (1)

• Generate gaps index before building library

[Copilot]

Copilot review overview

🟡 Changes recommended

The webhook-events generator is referenced but absent and unregistered, breaking its script and generated-output census.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Missing build:events entry point causes module-not-found failure · New
• Require full four-cell row shape before moving markers

[Copilot]

Copilot review overview

🟢 Approval recommended

The generation pipeline, ordering constraints, overwrite guard, and rendered output are coherently implemented and comprehensively tested.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Missing build:events entry point causes module-not-found failure
• Require full four-cell row shape before moving markers

[Copilot]

Copilot review overview

🟢 Approval recommended

The generation pipeline, overwrite safeguards, ordering constraints, and drift behavior are coherently implemented and thoroughly tested.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Missing build:events entry point causes module-not-found failure
• Require full four-cell row shape before moving markers

[Copilot]

Copilot review overview

🔵 Needs a closer look

It changes a dependency-backed documentation pipeline and an unreviewed auto-fix workflow across multiple generated artifacts.

Review effort: Balanced
Findings: None

[Copilot]

Copilot review overview

🟢 Approval recommended

The generation order, overwrite safeguards, workflow integration, and rendered output are comprehensively covered.

Review effort: Balanced
Findings: None

[Copilot]

Copilot review overview

🟢 Approval recommended

The new generation path, ordering constraints, overwrite guard, and drift behavior are comprehensively tested.

Review effort: Balanced
Findings: None