Skip to content

Commit 3f37a11

Browse files
committed
fix(gate-manifest): prove the forwarded-rule exemption instead of matching .rule
Addresses the remaining P2 from the re-review at d1a5085. forwardsAKnownRule accepted any member access whose property was named `rule`, so a future `reason(check, file, config.rule, ...)` would have been skipped in silence while the other literal categories kept the derived-universe gate green — the exact class of hole the fail-closed repair existed to shut. The exemption is now a proof. ownershipTableNames finds variables initialized to an array literal holding at least one `{ check, rule }` entry; ownershipIterationBindings records the callback parameter names bound while iterating one of those — the `entry` in `BUILD_OWNERSHIP.filter(...).map(...)`. Only `<binding>.rule` for such a binding is exempt, because only then is the literal guaranteed to have been collected from the table already. `config.rule`, `entry.rule` with no table behind it, and iteration of a non-ownership array all fail closed now. The `reason` factory's own `return { check, path: file, rule, detail }` is excluded by the factory's source span rather than by "any shorthand `rule`". The shorthand heuristic was the same shape of over-match: it would also have swallowed a real ownership entry someone wrote with shorthand variables. Tests 40 → 43: an arbitrary-member negative case (three shapes), the legitimate BUILD_OWNERSHIP forwarding case asserting no category is lost, and the factory return object. Planted red against the live selector — swapping one real `reason(...)` rule for `config.rule` fails with its line number. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01SkS4S8XXrfkJ8TD1VBKkvJ
1 parent d1a5085 commit 3f37a11

2 files changed

Lines changed: 193 additions & 39 deletions

File tree

‎scripts/gate-manifest/selector-rules.test.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,56 @@ test('a fail-open literal is not a category, because it pairs rule: with path:',
2727
assert.deepEqual(selectorRuleIds('m.ts', source), ['gate:lint']);
2828
});
2929

30+
test('an arbitrary .rule member access is NOT an exempt forwarding shape', () => {
31+
// The exemption exists only for a binding proven to iterate the collected ownership table.
32+
// Accepting any member named `.rule` would silently skip a category this reader never sees,
33+
// while the other literal categories keep the derived-universe gate green.
34+
assert.throws(
35+
() => selectorRuleIds('m.ts', "const a = reason('lint', file, config.rule, 'd');"),
36+
/rule argument is not a string literal/,
37+
);
38+
// Same shape, but iterating an array that is not an ownership table: still not proven.
39+
assert.throws(
40+
() =>
41+
selectorRuleIds(
42+
'm.ts',
43+
`const OTHER = [{ id: 'x', rule: 'not-a-category' }];
44+
const a = OTHER.map((entry) => reason('lint', file, entry.rule, 'd'));`,
45+
),
46+
/rule argument is not a string literal/,
47+
);
48+
// And a binding named `entry` that never came from a table does not inherit the exemption.
49+
assert.throws(
50+
() => selectorRuleIds('m.ts', "const a = reason('lint', file, entry.rule, 'd');"),
51+
/rule argument is not a string literal/,
52+
);
53+
});
54+
55+
test('forwarding from the real ownership-table iteration is exempt and loses no category', () => {
56+
const source = `
57+
const BUILD_OWNERSHIP = [
58+
{ check: 'swift-runner', rule: 'own:swift', detail: 'd', owns: () => true },
59+
{ check: 'macos-helper', rule: 'own:macos-helper', detail: 'd', owns: () => true },
60+
];
61+
const a = reason('lint', file, 'gate:lint', 'd');
62+
const b = BUILD_OWNERSHIP.filter((entry) => entry.owns(file)).map((entry) =>
63+
reason(entry.check, file, entry.rule, entry.detail),
64+
);
65+
`;
66+
assert.deepEqual(selectorRuleIds('m.ts', source), ['gate:lint', 'own:macos-helper', 'own:swift']);
67+
});
68+
69+
test("the reason factory's own return object declares no category", () => {
70+
// `return { check, path: file, rule, detail }` pairs check with rule and would otherwise read
71+
// as a build-ownership entry whose rule is not a literal. It is excluded by the factory's
72+
// source span, not by "any shorthand rule" — which would also swallow a real table entry.
73+
const source = `
74+
function reason(check, file, rule, detail) { return { check, path: file, rule, detail }; }
75+
const a = reason('lint', file, 'gate:lint', 'd');
76+
`;
77+
assert.deepEqual(selectorRuleIds('m.ts', source), ['gate:lint']);
78+
});
79+
3080
test('a computed rule argument fails closed rather than being skipped', () => {
3181
// A category this reader cannot see would bypass the representative-sample and reachability
3282
// checks entirely — the exact hole the derived universe exists to close.

‎scripts/gate-manifest/selector-rules.ts‎

Lines changed: 143 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@
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

1723
import {
1824
calleeName,
@@ -31,63 +37,160 @@ import {
3137
const REASON_FACTORY = 'reason';
3238
const 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. */
44168
function 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
*/
83188
export 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

Comments
 (0)