11import { readFileSync , writeFileSync } from "node:fs" ;
22import { 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" ;
314import { OUTPUT_DECLS } from "../../src/action/io.js" ;
415import type { InputDecl } from "../../src/flows/inputs.js" ;
516import { INPUT_DECLS } from "../../src/flows/inputs.js" ;
@@ -21,85 +32,113 @@ import { SECTIONS } from "../../src/sections/registry.js";
2132import { agree } from "../../src/text.js" ;
2233import { countWord } from "./lib/count-word.js" ;
2334import { type GeneratedRegion , regenerateRegions } from "./lib/generated-regions.js" ;
35+ import { tableCell } from "./lib/markdown-table.js" ;
2436
2537const 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 - z 0 - 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 - z 0 - 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
64125export 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
80136export 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
105144function 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
324401const 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 } ,
0 commit comments