1313// Both are read here, so adding either kind of rule immediately widens the universe and the
1414// manifest fails until a representative path exercises it. That is the "something enumerates N"
1515// discipline the umbrella asks for, applied to the selector rather than to a second list.
16+ //
17+ // Anything else fails closed. A category this reader cannot see would bypass the derived
18+ // universe and therefore the representative-sample and reachability checks too, so a rule that
19+ // is not a string literal is an error naming its line — never a silent skip. The two shapes
20+ // that legitimately forward an already-collected rule are exempted by PROOF, not by pattern:
21+ // see reasonFactorySpan and ownershipIterationBindings.
1622
1723import {
1824 calleeName ,
@@ -31,63 +37,160 @@ import {
3137const REASON_FACTORY = 'reason' ;
3238const RULE_ARGUMENT_INDEX = 2 ;
3339
40+ type Span = { start : number ; end : number } ;
41+
42+ function spanOf ( node : Node ) : Span | null {
43+ const { start, end } = node as { start ?: unknown ; end ?: unknown } ;
44+ return typeof start === 'number' && typeof end === 'number' ? { start, end } : null ;
45+ }
46+
47+ function within ( span : Span | null , node : Node ) : boolean {
48+ const inner = spanOf ( node ) ;
49+ return span !== null && inner !== null && inner . start >= span . start && inner . end <= span . end ;
50+ }
51+
52+ function identifierName ( node : unknown ) : string | null {
53+ return isNode ( node ) && node . type === 'Identifier' && typeof node [ 'name' ] === 'string'
54+ ? node [ 'name' ]
55+ : null ;
56+ }
57+
58+ function isMemberAccess ( node : Node ) : boolean {
59+ return node . type === 'MemberExpression' || node . type === 'StaticMemberExpression' ;
60+ }
61+
62+ /** Walks `a.b().c` down to its root identifier, or null when the root is not one. */
63+ function rootIdentifier ( node : unknown ) : string | null {
64+ let current : unknown = node ;
65+ for ( let depth = 0 ; isNode ( current ) && depth < 32 ; depth ++ ) {
66+ const name = identifierName ( current ) ;
67+ if ( name !== null ) return name ;
68+ if ( isMemberAccess ( current ) ) current = current [ 'object' ] ;
69+ else if ( current . type === 'CallExpression' ) current = current [ 'callee' ] ;
70+ else return null ;
71+ }
72+ return null ;
73+ }
74+
3475/**
35- * The `rule:` of a build-ownership table entry, or null for any other object .
76+ * The body of the `reason(check, file, rule, detail)` factory itself .
3677 *
37- * The selector uses `rule:` for two unrelated things. `BUILD_OWNERSHIP` entries pair it with a
38- * `check:`, and those are real path categories. `FailOpenReason` literals pair it with a
39- * `path:` instead (`workflow-tooling`, `unknown-path`, …) — those are not categories at all:
40- * failing open runs the whole check set, so there is no owning job whose triggers could
41- * exclude them. Requiring a sibling `check:` separates the two by shape rather than by a
42- * hand-maintained exclusion list, which is the thing this module exists to avoid.
78+ * Its `return { check, path: file, rule, detail }` pairs a `check` with a `rule`, so it looks
79+ * exactly like a build-ownership entry — but it declares no category: it forwards its own
80+ * parameters, and the literal lives at each call site, which this reader visits separately.
81+ * Excluding it by the factory's source span is provable; excluding "any shorthand `rule`"
82+ * would also swallow a real table entry someone wrote with shorthand variables.
4383 */
84+ function reasonFactorySpan ( program : Node ) : Span | null {
85+ let span : Span | null = null ;
86+ collect ( program , ( node ) => {
87+ if ( span !== null ) return ;
88+ const isFactory =
89+ ( node . type === 'FunctionDeclaration' || node . type === 'FunctionExpression' ) &&
90+ identifierName ( node [ 'id' ] ) === REASON_FACTORY ;
91+ if ( isFactory ) span = spanOf ( node ) ;
92+ } ) ;
93+ return span ;
94+ }
95+
96+ /** Variables initialized to an array literal containing at least one `{ check, rule }` entry. */
97+ function ownershipTableNames ( program : Node , factory : Span | null ) : Set < string > {
98+ const names = new Set < string > ( ) ;
99+ collect ( program , ( node ) => {
100+ if ( node . type !== 'VariableDeclarator' ) return ;
101+ const name = identifierName ( node [ 'id' ] ) ;
102+ const init = node [ 'init' ] ;
103+ if ( name === null || ! isNode ( init ) || init . type !== 'ArrayExpression' ) return ;
104+ const holdsOwnershipEntry = children ( init ) . some ( ( element ) => {
105+ if ( element . type !== 'ObjectExpression' || within ( factory , element ) ) return false ;
106+ const properties = children ( element ) ;
107+ return (
108+ properties . some ( ( property ) => propertyKey ( property ) === 'check' ) &&
109+ properties . some ( ( property ) => propertyKey ( property ) === 'rule' )
110+ ) ;
111+ } ) ;
112+ if ( holdsOwnershipEntry ) names . add ( name ) ;
113+ } ) ;
114+ return names ;
115+ }
116+
117+ /**
118+ * Callback parameter names bound while iterating a collected ownership table — the `entry` in
119+ * `BUILD_OWNERSHIP.filter((entry) => …).map((entry) => reason(…, entry.rule, …))`.
120+ *
121+ * This is what makes the forwarding exemption a proof rather than a pattern. Accepting any
122+ * member access named `.rule` would silently skip `reason(check, file, config.rule, …)`, whose
123+ * literal this reader never sees — a live category slipping past the derived universe while
124+ * the gate stays green. Only a binding whose origin is an ownership-table iteration qualifies,
125+ * because only then is the literal guaranteed to have been collected from the table already.
126+ */
127+ function iteratesOwnershipTable ( node : Node , tables : ReadonlySet < string > ) : boolean {
128+ if ( node . type !== 'CallExpression' ) return false ;
129+ const callee = node [ 'callee' ] ;
130+ if ( ! isNode ( callee ) || ! isMemberAccess ( callee ) ) return false ;
131+ const root = rootIdentifier ( callee [ 'object' ] ) ;
132+ return root !== null && tables . has ( root ) ;
133+ }
134+
135+ /** The first parameter name of each function argument — `entry` in `.map((entry) => …)`. */
136+ function callbackParameterNames ( node : Node ) : string [ ] {
137+ const args = node [ 'arguments' ] ;
138+ if ( ! Array . isArray ( args ) ) return [ ] ;
139+ return args . flatMap ( ( argument ) : string [ ] => {
140+ if ( ! isNode ( argument ) ) return [ ] ;
141+ const isCallback =
142+ argument . type === 'ArrowFunctionExpression' || argument . type === 'FunctionExpression' ;
143+ if ( ! isCallback ) return [ ] ;
144+ const params = argument [ 'params' ] ;
145+ const name = identifierName ( Array . isArray ( params ) ? params [ 0 ] : undefined ) ;
146+ return name === null ? [ ] : [ name ] ;
147+ } ) ;
148+ }
149+
150+ function ownershipIterationBindings ( program : Node , tables : ReadonlySet < string > ) : Set < string > {
151+ const bindings = new Set < string > ( ) ;
152+ collect ( program , ( node ) => {
153+ if ( ! iteratesOwnershipTable ( node , tables ) ) return ;
154+ for ( const name of callbackParameterNames ( node ) ) bindings . add ( name ) ;
155+ } ) ;
156+ return bindings ;
157+ }
158+
159+ /** `entry.rule` where `entry` is proven to iterate a collected ownership table. */
160+ function forwardsACollectedRule ( argument : unknown , bindings : ReadonlySet < string > ) : boolean {
161+ if ( ! isNode ( argument ) || ! isMemberAccess ( argument ) ) return false ;
162+ if ( identifierName ( argument [ 'property' ] ) !== 'rule' ) return false ;
163+ const object = identifierName ( argument [ 'object' ] ) ;
164+ return object !== null && bindings . has ( object ) ;
165+ }
166+
167+ /** The `rule:` of a build-ownership entry, or `declared: false` for any other object. */
44168function buildOwnershipRule ( node : Node ) : { rule : string | null ; declared : boolean } {
45169 if ( node . type !== 'ObjectExpression' ) return { rule : null , declared : false } ;
46170 const properties = children ( node ) ;
171+ // A `rule:` paired with `path:` rather than `check:` is a FailOpenReason literal
172+ // (`workflow-tooling`, `unknown-path`, …), not a category: failing open runs the whole check
173+ // set, so no owning job's triggers could exclude it. Separating the two by shape avoids a
174+ // hand-maintained exclusion list, which is the thing this module exists to avoid.
47175 if ( ! properties . some ( ( property ) => propertyKey ( property ) === 'check' ) ) {
48176 return { rule : null , declared : false } ;
49177 }
50178 const rule = properties . find ( ( property ) => propertyKey ( property ) === 'rule' ) ;
51179 if ( ! rule ) return { rule : null , declared : false } ;
52- // `{ check, path: file, rule, detail }` — the `reason` factory forwarding its own parameter.
53- // A shorthand property cannot name a category; the literal is at the call site, which this
54- // reader visits separately. Declaring it "not declared" keeps it out of the fail-closed set
55- // without weakening the rule for a genuinely dynamic value.
56- if ( rule [ 'shorthand' ] === true ) return { rule : null , declared : false } ;
57180 return { rule : stringValue ( rule ) , declared : true } ;
58181}
59182
60183/**
61- * Whether a `reason(...)` rule argument merely forwards a rule already read from elsewhere.
62- *
63- * `reason(entry.check, file, entry.rule, entry.detail)` in the build-ownership loop is the one
64- * live case: the literal lives in the BUILD_OWNERSHIP table, which this reader already
65- * collects, so the forwarding call adds no category. Anything else non-literal — a template
66- * string, a variable, a call — could name a category this reader would never see, and must
67- * fail closed.
68- */
69- function forwardsAKnownRule ( argument : unknown ) : boolean {
70- if ( ! isNode ( argument ) ) return false ;
71- const isMemberAccess =
72- argument . type === 'MemberExpression' || argument . type === 'StaticMemberExpression' ;
73- if ( ! isMemberAccess ) return false ;
74- const property = argument [ 'property' ] ;
75- return isNode ( property ) && property [ 'name' ] === 'rule' ;
76- }
77-
78- /**
79- * Every category id `scripts/check-affected/model.ts` can attach to a selection. Throws when it
80- * finds none: an empty universe would silently mean "nothing to represent", which is the same
81- * class of quiet pass this gate exists to prevent.
184+ * Every category id `scripts/check-affected/model.ts` can attach to a selection. Throws when a
185+ * rule is not statically readable, and when it finds none at all — an empty universe would
186+ * silently mean "nothing to represent", the same class of quiet pass this gate exists to stop.
82187 */
83188export function selectorRuleIds ( file : string , source : string ) : string [ ] {
84189 const program = parseProgram ( file , source ) ;
85- const rules = new Set < string > ( ) ;
190+ const factory = reasonFactorySpan ( program ) ;
191+ const bindings = ownershipIterationBindings ( program , ownershipTableNames ( program , factory ) ) ;
86192
87- // Shapes this reader cannot turn into a category id. Silently skipping them would let a
88- // future live category slip past the derived universe — and therefore past the
89- // representative-sample and reachability checks — which is the whole hole this module
90- // closes. So they fail closed, pointing at the line to fix.
193+ const rules = new Set < string > ( ) ;
91194 const unsupported : string [ ] = [ ] ;
92195
93196 collect ( program , ( node ) => {
@@ -99,14 +202,15 @@ export function selectorRuleIds(file: string, source: string): string[] {
99202 rules . add ( literal ) ;
100203 return ;
101204 }
102- if ( forwardsAKnownRule ( argument ) ) return ;
205+ if ( forwardsACollectedRule ( argument , bindings ) ) return ;
103206 unsupported . push (
104207 `line ${ lineOf ( source , isNode ( argument ) ? argument : node ) } : \`${ REASON_FACTORY } (...)\` ` +
105208 `rule argument is not a string literal` ,
106209 ) ;
107210 return ;
108211 }
109212 // The build-ownership table states its rule as a property instead of a call argument.
213+ if ( within ( factory , node ) ) return ;
110214 const owned = buildOwnershipRule ( node ) ;
111215 if ( ! owned . declared ) return ;
112216 if ( owned . rule !== null ) {
0 commit comments