Skip to content

Commit 2b5d2ff

Browse files
authored
build(scripts): emit action.yml scalars with the yaml package and fold the table-cell helpers into one (#443)
1 parent b6d2f0a commit 2b5d2ff

6 files changed

Lines changed: 318 additions & 149 deletions

File tree

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

Lines changed: 156 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,16 @@
11
import { readFileSync, writeFileSync } from "node:fs";
22
import { join } from "node:path";
3+
import {
4+
Document,
5+
type DocumentOptions,
6+
type ParseOptions,
7+
parseDocument,
8+
Scalar,
9+
type SchemaOptions,
10+
type ToStringOptions,
11+
YAMLMap,
12+
} from "yaml";
13+
import { z } from "zod";
314
import { OUTPUT_DECLS } from "../../src/action/io.js";
415
import type { InputDecl } from "../../src/flows/inputs.js";
516
import { INPUT_DECLS } from "../../src/flows/inputs.js";
@@ -21,85 +32,113 @@ import { SECTIONS } from "../../src/sections/registry.js";
2132
import { agree } from "../../src/text.js";
2233
import { countWord } from "./lib/count-word.js";
2334
import { type GeneratedRegion, regenerateRegions } from "./lib/generated-regions.js";
35+
import { tableCell } from "./lib/markdown-table.js";
2436

2537
const ROOT = join(import.meta.dir, "..", "..");
2638

27-
/** Column budget for a folded description line, indent included. */
28-
const YAML_WIDTH = 78;
29-
30-
function wrap(text: string, width: number): string[] {
31-
const lines: string[] = [];
32-
let current = "";
33-
for (const word of text.split(" ")) {
34-
if (current !== "" && current.length + 1 + word.length > width) {
35-
lines.push(current);
36-
current = word;
37-
} else {
38-
current = current === "" ? word : `${current} ${word}`;
39+
/** The schema the scalars are rendered and read back under: a key YAML 1.1 would re-type (on, y, null, ...) comes out
40+
* quoted, for the 1.1 readers of action.yml still in the wild. Its merge tag is removed: it claims the string "<<"
41+
* itself, whatever style the scalar asks for, and action.yml carries no merges. */
42+
const YAML_DOCUMENT: DocumentOptions & SchemaOptions & ParseOptions = {
43+
version: "1.1",
44+
merge: false,
45+
customTags: (tags) =>
46+
tags.filter((tag) =>
47+
typeof tag === "string" ? tag !== "merge" : tag.tag !== "tag:yaml.org,2002:merge",
48+
),
49+
};
50+
51+
/** Column budget for a folded description line, indent included; the library takes it as a soft limit (a line one
52+
* column over stays whole). Quoted scalars are JSON strings: one line however long, with JSON's escapes. */
53+
const YAML_STYLE: ToStringOptions = { lineWidth: 78, singleQuote: false, doubleQuotedAsJSON: true };
54+
55+
const PLAIN_NAME = /^[a-z][a-z0-9-]*$/;
56+
57+
/** One line not starting with whitespace: any other description would fold into a form action.yml does not carry (a
58+
* blank line, an indentation indicator, a kept newline), so the generator refuses it instead of writing it. */
59+
const DESCRIPTION = z
60+
.string()
61+
.regex(/^\S[^\r\n]*$/, "one line of text, not starting with whitespace");
62+
63+
const INPUT_ENTRY = z.strictObject({
64+
description: DESCRIPTION,
65+
required: z.literal(false),
66+
default: z.string(),
67+
});
68+
const OUTPUT_ENTRY = z.strictObject({ description: DESCRIPTION });
69+
70+
const DESCRIBED = z.object({ description: DESCRIPTION });
71+
72+
/** Each declaration parsed with `schema`, every own name kept (a record schema would drop `__proto__`, a name the
73+
* emitter writes), or the first miss as "name.path: message". */
74+
function declarations<T>(
75+
schema: z.ZodType<T>,
76+
decls: Readonly<Record<string, unknown>>,
77+
): Record<string, T> | string {
78+
const parsed: Array<[string, T]> = [];
79+
for (const [name, decl] of Object.entries(decls)) {
80+
const result = schema.safeParse(decl);
81+
if (!result.success) {
82+
const issue = result.error.issues[0];
83+
return `${[name, ...(issue?.path ?? [])].map(String).join(".")}: ${issue?.message ?? "invalid"}`;
3984
}
85+
parsed.push([name, result.data]);
4086
}
41-
return current === "" ? lines : [...lines, current];
87+
return Object.fromEntries(parsed);
4288
}
4389

44-
/** Folding turns each line break back into one space, so only single-spaced prose without edge spaces parses back to
45-
* the declaration verbatim; anything else is rejected. */
46-
function foldedDescription(text: string, indent: number): string {
47-
if (text === "" || /^ | $|[^ \S]| {2}/.test(text)) {
48-
throw new Error(`a description must be single-spaced prose to fold losslessly: ${text}`);
49-
}
50-
const pad = " ".repeat(indent);
51-
return [
52-
`${pad}description: >-`,
53-
...wrap(text, YAML_WIDTH - indent - 2).map((line) => `${pad} ${line}`),
54-
].join("\n");
90+
function scalar(value: string, type: Scalar.Type): Scalar<string> {
91+
const node = new Scalar(value);
92+
node.type = type;
93+
return node;
5594
}
5695

57-
/** Words a YAML 1.1 parser would re-type if left as a plain key. */
58-
const YAML_WORDS = new Set(["null", "true", "false", "yes", "no", "on", "off", "y", "n"]);
96+
/** A plain-shaped name stays plain unless the schema would re-type it; any other name is quoted outright. */
97+
function yamlKey(name: string): Scalar<string> {
98+
return scalar(name, PLAIN_NAME.test(name) ? Scalar.PLAIN : Scalar.QUOTE_DOUBLE);
99+
}
59100

60-
function yamlKey(name: string): string {
61-
return /^[a-z][a-z0-9-]*$/.test(name) && !YAML_WORDS.has(name) ? name : JSON.stringify(name);
101+
/** The entries of the top-level `key` mapping, rendered under that key so they carry the file's own nesting; the
102+
* key line itself is the file's, outside the region. */
103+
function yamlEntries<T extends { readonly description: string }>(
104+
key: string,
105+
decls: Readonly<Record<string, T>>,
106+
entry: (decl: T) => object,
107+
): string {
108+
const described = declarations(DESCRIBED, decls);
109+
if (typeof described === "string") {
110+
throw new Error(`the ${key} declarations: ${described}`);
111+
}
112+
const doc = new Document({}, YAML_DOCUMENT);
113+
const map = new YAMLMap<Scalar<string>, object>(doc.schema);
114+
for (const [name, decl] of Object.entries(decls)) {
115+
map.set(yamlKey(name), entry(decl));
116+
}
117+
// An empty mapping serializes as `{}` on the key's own line; the region then holds nothing.
118+
if (map.items.length === 0) {
119+
return "";
120+
}
121+
doc.set(key, map);
122+
return doc.toString(YAML_STYLE).slice(`${key}:\n`.length, -1);
62123
}
63124

64125
export function renderActionInputs(
65126
decls: Readonly<Record<string, Pick<InputDecl, "description" | "default">>>,
66127
): string {
67-
return Object.entries(decls)
68-
.map(([name, decl]) =>
69-
[
70-
` ${yamlKey(name)}:`,
71-
foldedDescription(decl.description, 4),
72-
" required: false",
73-
// Always double-quoted: a bare default could re-type itself (2022-11-28 is a YAML timestamp, "" needs its quotes to exist).
74-
` default: ${JSON.stringify(decl.default)}`,
75-
].join("\n"),
76-
)
77-
.join("\n");
128+
return yamlEntries("inputs", decls, (decl) => ({
129+
description: scalar(decl.description, Scalar.BLOCK_FOLDED),
130+
required: false,
131+
// Every default double-quoted: one form for the region shape to name, and the string type visible at a glance.
132+
default: scalar(decl.default, Scalar.QUOTE_DOUBLE),
133+
}));
78134
}
79135

80136
export function renderActionOutputs(
81137
decls: Readonly<Record<string, { readonly description: string }>>,
82138
): string {
83-
return Object.entries(decls)
84-
.map(([name, decl]) =>
85-
[` ${yamlKey(name)}:`, foldedDescription(decl.description, 4)].join("\n"),
86-
)
87-
.join("\n");
88-
}
89-
90-
/** A markdown table cell: an unescaped pipe gets its backslash; a line break is rejected (it would end the row). */
91-
function cell(text: string): string {
92-
if (/[\r\n]/.test(text)) {
93-
throw new Error(`a table cell cannot contain a line break: ${text}`);
94-
}
95-
// A pipe behind an odd run of backslashes is already escaped.
96-
return text.replace(/(\\*)\|/g, (match, slashes: string) =>
97-
slashes.length % 2 === 0 ? `${slashes}\\|` : match,
98-
);
99-
}
100-
101-
function row(cells: readonly string[]): string {
102-
return `| ${cells.map(cell).join(" | ")} |`;
139+
return yamlEntries("outputs", decls, (decl) => ({
140+
description: scalar(decl.description, Scalar.BLOCK_FOLDED),
141+
}));
103142
}
104143

105144
function proseList(items: readonly string[]): string {
@@ -148,11 +187,15 @@ export function renderPolicyDefaultsTable(
148187
}
149188
const caveat = text.caveat === undefined ? "" : ` (${text.caveat})`;
150189
const opposite = section.undeclaredDefault === "delete" ? "keep" : "delete";
151-
return row([
190+
const cells = [
152191
`\`${section.key}\``,
153-
`${section.undeclaredDefault}${caveat}`,
154-
`\`${opposite}\`: ${text.override}`,
155-
]);
192+
tableCell(`${section.undeclaredDefault}${caveat}`, `the ${section.key} Default cell`),
193+
tableCell(
194+
`\`${opposite}\`: ${text.override}`,
195+
`the ${section.key} "The override buys you" cell`,
196+
),
197+
];
198+
return `| ${cells.join(" | ")} |`;
156199
});
157200
return [DEFAULTS_TABLE_HEADER, ...rows].join("\n");
158201
}
@@ -308,18 +351,52 @@ function tableShape(header: string, cells: string): RegExp {
308351
return blockShape(String.raw`${RegExp.escape(header)}\n(?:\| ${cells} \|\n)*`);
309352
}
310353

311-
/** A JSON string literal as JSON.stringify() emits it: its own escapes only, bare quotes never. */
312-
const JSON_STRING = String.raw`"(?:[^"\\\u0000-\u001f]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*"`;
313-
314-
/** The key forms yamlKey() writes: a plain name that is no YAML word, or a JSON string holding a YAML word or a name that is not plain-shaped. */
315-
const YAML_WORD = [...YAML_WORDS].join("|");
316-
const PLAIN_KEY = `(?!(?:${YAML_WORD}):)[a-z][a-z0-9-]*`;
317-
const QUOTED_KEY = `(?:"(?:${YAML_WORD})"|(?!"[a-z][a-z0-9-]*")${JSON_STRING})`;
318-
319-
/** An action.yml mapping key line at two spaces, as yamlKey() renders it. */
320-
const YAML_ENTRY_KEY = String.raw` (?:${PLAIN_KEY}|${QUOTED_KEY}):\n`;
321-
322-
const YAML_DESCRIPTION = String.raw` description: >-\n(?: \S[^\n]*\n)+`;
354+
/** The emitter is its own grammar: a body is admitted when re-rendering the declarations it parses to reproduces it
355+
* byte for byte, so no spelling the emitter does not write gets through. A freshly placed region holds "\n" and
356+
* renders next. */
357+
function roundTrip<T extends { readonly description: string }>(
358+
key: string,
359+
entry: z.ZodType<T>,
360+
render: (decls: Readonly<Record<string, T>>) => string,
361+
): (body: string) => string | undefined {
362+
return (body) => {
363+
if (body === "\n") {
364+
return undefined;
365+
}
366+
const doc = parseDocument(`${key}:${body}`, YAML_DOCUMENT);
367+
const error = doc.errors[0];
368+
if (error !== undefined) {
369+
return `it does not parse as YAML (${error.message.split("\n")[0]})`;
370+
}
371+
let root: unknown;
372+
try {
373+
root = doc.toJS();
374+
} catch (failure) {
375+
// An alias without its anchor parses but does not convert; to the guard that is a refusal.
376+
return `it does not convert from YAML (${failure instanceof Error ? failure.message : String(failure)})`;
377+
}
378+
const mapping =
379+
typeof root === "object" && root !== null
380+
? ((root as Record<string, unknown>)[key] ?? {})
381+
: root;
382+
if (typeof mapping !== "object" || mapping === null || Array.isArray(mapping)) {
383+
return `it is not a mapping of ${key} declarations`;
384+
}
385+
const declared = declarations(entry, mapping as Record<string, unknown>);
386+
if (typeof declared === "string") {
387+
return `it is not a set of ${key} declarations (${declared})`;
388+
}
389+
const rendered = `\n${render(declared)}\n`;
390+
if (rendered === body) {
391+
return undefined;
392+
}
393+
const authored = body.split("\n");
394+
const expected = rendered.split("\n");
395+
const differing = authored.findIndex((line, i) => line !== expected[i]);
396+
const at = differing === -1 ? authored.length : differing;
397+
return `line ${at} reads ${JSON.stringify(authored[at] ?? "")} where the generator writes ${JSON.stringify(expected[at] ?? "")}`;
398+
};
399+
}
323400

324401
const GATED_READ_BULLET =
325402
String.raw`- GitHub gates (?:even )?the [^\n]+ reads at write, so \x60[a-z_]+\x60 needs ` +
@@ -337,15 +414,13 @@ export const GENERATED_REGIONS: Readonly<Record<string, readonly GeneratedRegion
337414
{
338415
name: "action-inputs",
339416
placement: { kind: "under-key", key: "inputs" },
340-
body: blockShape(
341-
String.raw`(?:${YAML_ENTRY_KEY}${YAML_DESCRIPTION} required: false\n default: ${JSON_STRING}\n)+`,
342-
),
417+
body: roundTrip("inputs", INPUT_ENTRY, renderActionInputs),
343418
render: block(() => renderActionInputs(INPUT_DECLS)),
344419
},
345420
{
346421
name: "action-outputs",
347422
placement: { kind: "under-key", key: "outputs" },
348-
body: blockShape(`(?:${YAML_ENTRY_KEY}${YAML_DESCRIPTION})+`),
423+
body: roundTrip("outputs", OUTPUT_ENTRY, renderActionOutputs),
349424
render: block(() => renderActionOutputs(OUTPUT_DECLS)),
350425
},
351426
],
@@ -359,9 +434,10 @@ export const GENERATED_REGIONS: Readonly<Record<string, readonly GeneratedRegion
359434
{
360435
name: "policy-defaults-table",
361436
placement: { kind: "under-heading", heading: "## Defaults per section" },
437+
// A cell holds no pipe and no line break: tableCell() refuses both, so a row carrying one is authored, not stale output.
362438
body: tableShape(
363439
DEFAULTS_TABLE_HEADER,
364-
String.raw`\x60[a-z_]+\x60 \| (?:delete|keep)(?: \([^\n]+\))? \| \x60(?:delete|keep)\x60: [^\n]+`,
440+
String.raw`\x60[a-z_]+\x60 \| (?:delete|keep)(?: \([^\r\n|]+\))? \| \x60(?:delete|keep)\x60: [^\r\n|]+`,
365441
),
366442
render: block(() => renderPolicyDefaultsTable(knobbedSections(), POLICY_ROW_PROSE)),
367443
},

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

Lines changed: 10 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import { readArchitecture, renderArchitectureMermaid } from "./arch-lint.js";
1616
import { COVERAGE_DATA, type CoverageData } from "./coverage-data.js";
1717
import { ENDPOINT_ANCHORS, type EndpointAnchors } from "./endpoint-docs.js";
1818
import { type GeneratedRegion, regenerateRegions, regionBounds } from "./lib/generated-regions.js";
19+
import { tableCell } from "./lib/markdown-table.js";
1920

2021
const ROOT = join(import.meta.dir, "..", "..");
2122
export const COVERAGE_PATH = "docs/reference/coverage.md";
@@ -85,16 +86,6 @@ export function renderPatCell(grant: string): string {
8586
return `${cell}; ${rendered}`;
8687
}
8788

88-
/** A markdown table cell; a pipe or a line break would split the row, so both are refused. */
89-
function cell(text: string, where: string): string {
90-
if (text.trim() === "" || /[|\r\n]/.test(text)) {
91-
throw new Error(
92-
`gen-docs: ${where} is blank or contains "|" or a line break, which would break its table row: "${text}"`,
93-
);
94-
}
95-
return text;
96-
}
97-
9889
const TABLE_HEADER =
9990
"| Section | Endpoints | PAT permission | Undeclared default | Notes |\n|---|---|---|---|---|";
10091

@@ -109,10 +100,10 @@ export function renderSectionsTable(
109100
}
110101
return [
111102
`\`${section.key}\``,
112-
cell(doc.sections_table.endpoints, `the ${section.key} Endpoints cell`),
113-
cell(renderPatCell(sectionGrant(section)), `the ${section.key} PAT permission cell`),
103+
tableCell(doc.sections_table.endpoints, `the ${section.key} Endpoints cell`),
104+
tableCell(renderPatCell(sectionGrant(section)), `the ${section.key} PAT permission cell`),
114105
UNDECLARED_DEFAULT_DISPLAY[section.undeclaredDefault],
115-
cell(doc.sections_table.notes, `the ${section.key} Notes cell`),
106+
tableCell(doc.sections_table.notes, `the ${section.key} Notes cell`),
116107
];
117108
});
118109
return [TABLE_HEADER, ...rows.map((cells) => `| ${cells.join(" | ")} |`)].join("\n");
@@ -125,7 +116,7 @@ function codeSpan(text: string, where: string): string {
125116
`gen-docs: ${where} contains a backtick, which would close its code span: ${text}`,
126117
);
127118
}
128-
return cell(text, where);
119+
return tableCell(text, where);
129120
}
130121

131122
/** The longest paragraph or bullet the page carries; a fact past it is two facts. */
@@ -249,9 +240,9 @@ function renderSection(
249240
const where = `a ${section.key} coverage row`;
250241
const keys = row.keys === undefined ? "" : ` (\`${codeSpan(row.keys, `${where}'s keys`)}\`)`;
251242
const cells = [
252-
cell(row.area, `${where}'s Area cell`),
243+
tableCell(row.area, `${where}'s Area cell`),
253244
`[\`${section.key}\`](${SECTIONS_PAGE})${keys}`,
254-
cell(renderCalls(section, row, claimed, carrier, anchors), `${where}'s Endpoints cell`),
245+
tableCell(renderCalls(section, row, claimed, carrier, anchors), `${where}'s Endpoints cell`),
255246
];
256247
return `| ${cells.join(" | ")} |`;
257248
});
@@ -315,9 +306,9 @@ export function renderCoverage(
315306
...data.gaps.rows.map((row) => {
316307
const where = `the "${row.area}" gap row`;
317308
const cells = [
318-
cell(row.area, `${where}'s Area cell`),
319-
cell(row.endpoints.join(", "), `${where}'s Endpoints cell`),
320-
cell(row.why, `${where}'s Why cell`),
309+
tableCell(row.area, `${where}'s Area cell`),
310+
tableCell(row.endpoints.join(", "), `${where}'s Endpoints cell`),
311+
tableCell(row.why, `${where}'s Why cell`),
321312
];
322313
return `| ${cells.join(" | ")} |`;
323314
}),

0 commit comments

Comments
 (0)