Skip to content

Commit a65fcda

Browse files
committed
refactor(scripts): drive every generated region through one registry
gen-docs.ts and gen-action-docs.ts each drove their generated regions by hand: a lookup in a path-to-regions record, a throw for an unregistered path, a call to regenerateRegions, a read/write loop in main, and a log line. lib/region-driver.ts is now the one driver both call. A registry maps each path to its regions and the two whole-file rules no region's placement can carry: a shape rule judged on the file as read, before any region, and a rendered rule judged over the regenerated text. gen-docs's two page rules become registry data: the coverage page's title-and-tail rule is its shape, and the token-form label rule is every other page's rendered rule. The coverage page joins the docs registry, so generated.ts derives the docs rows from one Object.keys(). The four wrappers renderPage, renderCoverageFile, regenerateText, and regenerateAll go; tests call the driver with the registry. Every generated page regenerates byte-identically. The one message change is the unregistered-path refusal, which no longer carries a "gen-docs: " prefix; no user reaches it, since paths come from the registry keys.
1 parent e6a9867 commit a65fcda

6 files changed

Lines changed: 190 additions & 169 deletions

File tree

‎.github/scripts/gen-action-docs.ts‎

Lines changed: 72 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import { readFileSync, writeFileSync } from "node:fs";
21
import { join } from "node:path";
32
import { err, ok, Result } from "neverthrow";
43
import {
@@ -34,13 +33,8 @@ import { SECTIONS } from "../../src/sections/registry.js";
3433
import { agree } from "../../src/text.js";
3534
import type { UndeclaredPolicy } from "../../src/types.js";
3635
import { COUNT_WORD_MAX, countWord } from "./lib/count-word.js";
37-
import {
38-
block,
39-
blockLine,
40-
blockLines,
41-
GeneratedRegion,
42-
regenerateRegions,
43-
} from "./lib/generated-regions.js";
36+
import { block, blockLine, blockLines, GeneratedRegion } from "./lib/generated-regions.js";
37+
import { type GeneratedFiles, regenerateFiles } from "./lib/region-driver.js";
4438

4539
const ROOT = join(import.meta.dir, "..", "..");
4640

@@ -665,96 +659,77 @@ function yamlDeclarations<T>(
665659
* Each region reads its body back and re-renders it, so a marker moved elsewhere fails instead of regenerating
666660
* in the wrong place or erasing authored text.
667661
*/
668-
export const GENERATED_REGIONS: Readonly<Record<string, readonly GeneratedRegion[]>> = {
669-
"action.yml": [
670-
GeneratedRegion.of<Readonly<Record<string, Pick<InputDecl, "description" | "default">>>>({
671-
name: "action-inputs",
672-
placement: { kind: "under-key", key: "inputs" },
673-
data: () => INPUT_DECLS,
674-
render: block(renderActionInputs),
675-
parse: yamlDeclarations("inputs", INPUT_ENTRY),
676-
}),
677-
GeneratedRegion.of<Readonly<Record<string, { readonly description: string }>>>({
678-
name: "action-outputs",
679-
placement: { kind: "under-key", key: "outputs" },
680-
data: () => OUTPUT_DECLS,
681-
render: block(renderActionOutputs),
682-
parse: yamlDeclarations("outputs", OUTPUT_ENTRY),
683-
}),
684-
],
685-
"docs/reference/undeclared-policy.md": [
686-
GeneratedRegion.of<readonly string[]>({
687-
name: "policy-count-sentence",
688-
placement: { kind: "under-heading", heading: "# The undeclared policy" },
689-
data: () => countSentenceKeys(knobbedSections()),
690-
render: block(countSentence),
691-
parse: parseCountSentence,
692-
}),
693-
GeneratedRegion.of<readonly PolicyRow[]>({
694-
name: "policy-defaults-table",
695-
placement: { kind: "under-heading", heading: "## Defaults per section" },
696-
data: () => policyRows(knobbedSections(), POLICY_ROW_PROSE),
697-
render: block(renderPolicyRows),
698-
parse: tableBody(DEFAULTS_TABLE_HEADER, "keyed", policyRow),
699-
}),
700-
],
701-
"docs/reference/permissions.md": [
702-
GeneratedRegion.of({
703-
name: "permissions-grant-sentence",
704-
placement: { kind: "under-heading", heading: "## What to grant" },
705-
data: () => grantLabels(SECTIONS),
706-
render: block(grantSentence),
707-
parse: parseGrantSentence,
708-
}),
709-
GeneratedRegion.of<readonly GatedRead[]>({
710-
name: "permissions-gated-reads",
711-
placement: { kind: "under-heading", heading: "## How a denial surfaces" },
712-
data: () => gatedReads(SECTIONS),
713-
render: block(gatedBullets),
714-
parse: (body) => blockLines(body).andThen((lines) => parseGatedBullets(lines, 1)),
715-
}),
716-
],
717-
"docs/operate/check-mode.md": [
718-
GeneratedRegion.of<readonly GatedRead[]>({
719-
name: "check-mode-gated-reads",
720-
placement: {
721-
kind: "under-heading",
722-
heading: "## Checking settings changes on pull requests",
723-
},
724-
data: () => gatedReads(SECTIONS),
725-
render: block(checkModeGatedReads),
726-
parse: parseCheckModeGatedReads,
727-
}),
728-
],
662+
export const FILES: GeneratedFiles = {
663+
"action.yml": {
664+
regions: [
665+
GeneratedRegion.of<Readonly<Record<string, Pick<InputDecl, "description" | "default">>>>({
666+
name: "action-inputs",
667+
placement: { kind: "under-key", key: "inputs" },
668+
data: () => INPUT_DECLS,
669+
render: block(renderActionInputs),
670+
parse: yamlDeclarations("inputs", INPUT_ENTRY),
671+
}),
672+
GeneratedRegion.of<Readonly<Record<string, { readonly description: string }>>>({
673+
name: "action-outputs",
674+
placement: { kind: "under-key", key: "outputs" },
675+
data: () => OUTPUT_DECLS,
676+
render: block(renderActionOutputs),
677+
parse: yamlDeclarations("outputs", OUTPUT_ENTRY),
678+
}),
679+
],
680+
},
681+
"docs/reference/undeclared-policy.md": {
682+
regions: [
683+
GeneratedRegion.of<readonly string[]>({
684+
name: "policy-count-sentence",
685+
placement: { kind: "under-heading", heading: "# The undeclared policy" },
686+
data: () => countSentenceKeys(knobbedSections()),
687+
render: block(countSentence),
688+
parse: parseCountSentence,
689+
}),
690+
GeneratedRegion.of<readonly PolicyRow[]>({
691+
name: "policy-defaults-table",
692+
placement: { kind: "under-heading", heading: "## Defaults per section" },
693+
data: () => policyRows(knobbedSections(), POLICY_ROW_PROSE),
694+
render: block(renderPolicyRows),
695+
parse: tableBody(DEFAULTS_TABLE_HEADER, "keyed", policyRow),
696+
}),
697+
],
698+
},
699+
"docs/reference/permissions.md": {
700+
regions: [
701+
GeneratedRegion.of({
702+
name: "permissions-grant-sentence",
703+
placement: { kind: "under-heading", heading: "## What to grant" },
704+
data: () => grantLabels(SECTIONS),
705+
render: block(grantSentence),
706+
parse: parseGrantSentence,
707+
}),
708+
GeneratedRegion.of<readonly GatedRead[]>({
709+
name: "permissions-gated-reads",
710+
placement: { kind: "under-heading", heading: "## How a denial surfaces" },
711+
data: () => gatedReads(SECTIONS),
712+
render: block(gatedBullets),
713+
parse: (body) => blockLines(body).andThen((lines) => parseGatedBullets(lines, 1)),
714+
}),
715+
],
716+
},
717+
"docs/operate/check-mode.md": {
718+
regions: [
719+
GeneratedRegion.of<readonly GatedRead[]>({
720+
name: "check-mode-gated-reads",
721+
placement: {
722+
kind: "under-heading",
723+
heading: "## Checking settings changes on pull requests",
724+
},
725+
data: () => gatedReads(SECTIONS),
726+
render: block(checkModeGatedReads),
727+
parse: parseCheckModeGatedReads,
728+
}),
729+
],
730+
},
729731
};
730732

731-
export function regenerateText(path: string, text: string): string {
732-
const regions = GENERATED_REGIONS[path];
733-
if (regions === undefined) {
734-
throw new Error(`no generated regions are registered for ${path}`);
735-
}
736-
return regenerateRegions(text, regions, path);
737-
}
738-
739-
export function regenerateAll(): string[] {
740-
const changed: string[] = [];
741-
for (const path of Object.keys(GENERATED_REGIONS)) {
742-
const file = join(ROOT, path);
743-
const before = readFileSync(file, "utf8");
744-
const after = regenerateText(path, before);
745-
if (after !== before) {
746-
writeFileSync(file, after);
747-
changed.push(path);
748-
}
749-
}
750-
return changed;
751-
}
752-
753733
if (import.meta.main) {
754-
const changed = regenerateAll();
755-
console.log(
756-
changed.length === 0
757-
? "generated regions already up to date"
758-
: `regenerated ${changed.join(", ")}`,
759-
);
734+
regenerateFiles("gen-action-docs", FILES, ROOT);
760735
}

‎.github/scripts/gen-docs.ts‎

Lines changed: 40 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
import { readFileSync, writeFileSync } from "node:fs";
21
import { join } from "node:path";
32
import { err, ok, Result, safeTry } from "neverthrow";
43
import { RUN_RESULTS } from "../../src/engine/outcome.js";
@@ -28,12 +27,11 @@ import {
2827
blockLine,
2928
blockLines,
3029
GeneratedRegion,
31-
regenerateRegions,
3230
regionBounds,
3331
} from "./lib/generated-regions.js";
32+
import { type GeneratedFile, type GeneratedFiles, regenerateFiles } from "./lib/region-driver.js";
3433

3534
const ROOT = join(import.meta.dir, "..", "..");
36-
export const COVERAGE_PATH = "docs/reference/coverage.md";
3735

3836
/** The repository these pages document; the token form's name and description derive from it. */
3937
const REPO_SLUG = "Vivswan/github-settings-as-code";
@@ -816,79 +814,68 @@ function architectureMapRegion(name: string, heading: string): GeneratedRegion {
816814
});
817815
}
818816

819-
export const PAGE_REGIONS: Readonly<Record<string, readonly GeneratedRegion[]>> = {
820-
"README.md": [patUrlRegion("readme-pat-url")],
821-
"docs/start/getting-started.md": [patUrlRegion("pat-url")],
822-
"docs/reference/sections.md": [sectionsTableRegion("sections-table", "# Sections")],
823-
"docs/reference/inputs.md": [outputsListRegion("outputs-list", "## Outputs")],
824-
"docs/reference/architecture.md": [
825-
architectureMapRegion("architecture-map", "## The module map"),
826-
],
827-
};
828-
829-
// The result must reference the token-form label exactly as often as it defines it, at most once: a renamed
817+
// A rendered page must reference the token-form label exactly as often as it defines it, at most once: a renamed
830818
// reference, a second one, or a stale definition ahead of the generated one (it wins) would leave the page wrong
831819
// while regeneration stays a no-op.
832-
export function renderPage(path: string, text: string): string {
833-
const regions = PAGE_REGIONS[path];
834-
if (regions === undefined) {
835-
throw new Error(`gen-docs: no generated regions are registered for ${path}`);
836-
}
837-
const out = regenerateRegions(text, regions, path);
820+
function patFormFault(page: string, path: string): string | undefined {
838821
// CommonMark trims and case-folds labels and lets the first definition win, so every spelling counts: a mention
839822
// opening a line and ending in ":" is a definition, any other bracketed mention is a reference.
840-
const mentions = [...out.matchAll(/^ {0,3}\[([^\]]+)\]:|\[([^\]]+)\]/gm)].filter(
823+
const mentions = [...page.matchAll(/^ {0,3}\[([^\]]+)\]:|\[([^\]]+)\]/gm)].filter(
841824
(match) => (match[1] ?? match[2] ?? "").trim().toLowerCase() === PAT_FORM_LABEL,
842825
);
843826
const definitions = mentions.filter((match) => match[1] !== undefined).length;
844827
const references = mentions.length - definitions;
845828
if (references !== definitions || definitions > 1) {
846-
throw new Error(
847-
`gen-docs: ${path} must reference [${PAT_FORM_LABEL}] exactly as often as it defines it, at most once; found ${references} and ${definitions}`,
829+
return (
830+
`gen-docs: ${path} must reference [${PAT_FORM_LABEL}] exactly as often as it defines it, ` +
831+
`at most once; found ${references} and ${definitions}`
848832
);
849833
}
850-
return out;
834+
return undefined;
851835
}
852836

853-
// The one region closes the file and holds everything below the title (or an empty body between fresh markers), so
854-
// a marker moved over authored prose fails instead of erasing it.
855-
const COVERAGE_REGIONS: readonly GeneratedRegion[] = [
856-
GeneratedRegion.of({
857-
name: "coverage",
858-
placement: { kind: "tail" },
859-
data: () => coveragePage(SECTIONS, DOCS, COVERAGE_DATA, ENDPOINT_ANCHORS),
860-
render: block(renderCoveragePage),
861-
parse: parseCoveragePage,
862-
}),
863-
];
837+
/** A page with regions, held to the token-form rule once rendered. */
838+
function page(...regions: GeneratedRegion[]): GeneratedFile {
839+
return { regions, rendered: patFormFault };
840+
}
864841

865842
/** The page's frontmatter and title; the sidebar reads `order`, and 115 sits the page right after the Sections table (110). */
866843
const COVERAGE_TITLE = "---\norder: 115\n---\n\n# Coverage\n\n";
867844

868845
// Beyond the shared placement checks, the page must be exactly the title, the region, and one final newline, or
869846
// prose left outside could drift from the generator's.
870-
export function renderCoverageFile(coverage: string): string {
847+
function coverageShapeFault(coverage: string, path: string): string | undefined {
871848
const { begin, end } = regionBounds(coverage, "coverage", "html");
872849
if (coverage.slice(0, begin[0]) !== COVERAGE_TITLE || coverage.slice(end[1]) !== "\n") {
873-
throw new Error(
874-
`gen-docs: ${COVERAGE_PATH} must be the frontmatter, the "# Coverage" title, the coverage region, and one final newline`,
875-
);
850+
return `gen-docs: ${path} must be the frontmatter, the "# Coverage" title, the coverage region, and one final newline`;
876851
}
877-
return regenerateRegions(coverage, COVERAGE_REGIONS, COVERAGE_PATH);
852+
return undefined;
878853
}
879854

855+
export const PAGES: GeneratedFiles = {
856+
"docs/reference/coverage.md": {
857+
// The one region closes the file and holds everything below the title (or an empty body between fresh
858+
// markers), so a marker moved over authored prose fails instead of erasing it.
859+
regions: [
860+
GeneratedRegion.of({
861+
name: "coverage",
862+
placement: { kind: "tail" },
863+
data: () => coveragePage(SECTIONS, DOCS, COVERAGE_DATA, ENDPOINT_ANCHORS),
864+
render: block(renderCoveragePage),
865+
parse: parseCoveragePage,
866+
}),
867+
],
868+
shape: coverageShapeFault,
869+
},
870+
"README.md": page(patUrlRegion("readme-pat-url")),
871+
"docs/start/getting-started.md": page(patUrlRegion("pat-url")),
872+
"docs/reference/sections.md": page(sectionsTableRegion("sections-table", "# Sections")),
873+
"docs/reference/inputs.md": page(outputsListRegion("outputs-list", "## Outputs")),
874+
"docs/reference/architecture.md": page(
875+
architectureMapRegion("architecture-map", "## The module map"),
876+
),
877+
};
878+
880879
if (import.meta.main) {
881-
const pages: ReadonlyArray<readonly [string, (text: string) => string]> = [
882-
[COVERAGE_PATH, renderCoverageFile],
883-
...Object.keys(PAGE_REGIONS).map(
884-
(path) => [path, (text: string) => renderPage(path, text)] as const,
885-
),
886-
];
887-
for (const [file, render] of pages) {
888-
const path = join(ROOT, file);
889-
const before = readFileSync(path, "utf8");
890-
const after = render(before);
891-
writeFileSync(path, after);
892-
console.log(`gen-docs: wrote ${path}${after === before ? " (unchanged)" : ""}`);
893-
}
880+
regenerateFiles("gen-docs", PAGES, ROOT);
894881
}

‎.github/scripts/generated.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
*/
55

66
import { join } from "node:path";
7-
import { GENERATED_REGIONS } from "./gen-action-docs.js";
8-
import { COVERAGE_PATH, PAGE_REGIONS } from "./gen-docs.js";
7+
import { FILES } from "./gen-action-docs.js";
8+
import { PAGES } from "./gen-docs.js";
99
import { INDEX_PATH } from "./gen-gaps-index.js";
1010
import { INPUTS_PAGE_PATH } from "./gen-inputs-table.js";
1111

@@ -32,8 +32,8 @@ function regions(generator: string, paths: readonly string[]): GeneratedOutput[]
3232
*/
3333
export const GENERATED_OUTPUTS: readonly GeneratedOutput[] = [
3434
{ path: INDEX_PATH, generator: "build:gaps-index", kind: "file" },
35-
...regions("build:docs", [COVERAGE_PATH, ...Object.keys(PAGE_REGIONS)]),
36-
...regions("build:action-docs", Object.keys(GENERATED_REGIONS)),
35+
...regions("build:docs", Object.keys(PAGES)),
36+
...regions("build:action-docs", Object.keys(FILES)),
3737
{ path: INPUTS_PAGE_PATH, generator: "build:inputs-table", kind: "regions" },
3838
];
3939

0 commit comments

Comments
 (0)