@@ -9,12 +9,36 @@ import {
99 ALIAS_REGISTRY_FILE ,
1010 aliasResolverLocalName ,
1111 BIN_FILE ,
12+ countLocalBindings ,
13+ helpTargetBindingName ,
1214 importsAliasResolver ,
1315 localAliasLiterals ,
1416 registryAliasTokens ,
15- usageTextCallsResolver ,
17+ usageTextDelegationFailure ,
1618} from './bin-alias-fast-path.ts' ;
1719
20+ /**
21+ * The shape of bin.ts's real `--help` fast path, minus everything R12 does not read. Fixtures
22+ * below vary one thing against this baseline, so a test's subject is the line it changed.
23+ */
24+ function binFixture ( fastPathBody : string , prelude = '' ) : string {
25+ return `
26+ import { normalizeCliCommandAlias } from './commands/cli-command-aliases.ts';
27+ ${ prelude }
28+ function runHelpFastPath(argv) {
29+ const helpTarget = resolveSimpleHelpTarget(argv);
30+ if (helpTarget === undefined) return false;
31+ ${ fastPathBody }
32+ return true;
33+ }
34+ ` ;
35+ }
36+
37+ /** `usageTextDelegationFailure` for a fixture, resolving the local name the way check.ts does. */
38+ function delegationFailure ( source : string ) : string | null {
39+ return usageTextDelegationFailure ( source , aliasResolverLocalName ( source ) ! ) ;
40+ }
41+
1842const REGISTRY_FIXTURE = `
1943import type { CliFlags } from '@agent-device/contracts/command';
2044const CLI_COMMAND_ALIASES = [
@@ -110,57 +134,138 @@ test('aliasResolverLocalName is null when there is no matching value import', ()
110134 ) ;
111135} ) ;
112136
113- test ( 'usageTextCallsResolver is true for the real composition, by local name ' , ( ) => {
137+ test ( 'helpTargetBindingName reads the binding resolveSimpleHelpTarget produces ' , ( ) => {
114138 assert . equal (
115- usageTextCallsResolver (
116- 'const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(helpTarget));\n' ,
117- 'normalizeCliCommandAlias' ,
118- ) ,
119- true ,
139+ helpTargetBindingName ( binFixture ( ' buildCommandUsageText(normalizeCliCommandAlias(x));' ) ) ,
140+ 'helpTarget' ,
120141 ) ;
121- // Binds by whatever LOCAL name the caller passes — an aliased import's local name must still
122- // be found at the call site, since that is the only name available to call it by.
142+ // Renaming the local re-points the guard rather than disarming it — the name is never assumed.
143+ const renamed = `
144+ function runHelpFastPath(argv) {
145+ const target = resolveSimpleHelpTarget(argv);
146+ }
147+ ` ;
148+ assert . equal ( helpTargetBindingName ( renamed ) , 'target' ) ;
149+ } ) ;
150+
151+ test ( 'helpTargetBindingName is null when the fast path no longer produces one' , ( ) => {
152+ assert . equal ( helpTargetBindingName ( 'const helpTarget = argv[0];\n' ) , null ) ;
153+ } ) ;
154+
155+ test ( 'countLocalBindings counts value declarations only, not the import or type positions' , ( ) => {
156+ const source = `
157+ import { normalizeCliCommandAlias } from './commands/cli-command-aliases.ts';
158+ function f(helpTarget: normalizeCliCommandAlias) { const other = 1; }
159+ ` ;
160+ // The import itself is not a shadow, and a type annotation naming the resolver binds nothing.
161+ assert . equal ( countLocalBindings ( source , 'normalizeCliCommandAlias' ) , 0 ) ;
162+ assert . equal ( countLocalBindings ( source , 'helpTarget' ) , 1 ) ;
163+ assert . equal ( countLocalBindings ( 'const x = 1;\nfunction x() {}\n' , 'x' ) , 2 ) ;
164+ } ) ;
165+
166+ test ( 'usageTextDelegationFailure accepts the real composition, by local name' , ( ) => {
123167 assert . equal (
124- usageTextCallsResolver (
125- 'const commandHelp = buildCommandUsageText(resolveAlias(helpTarget));\n' ,
126- 'resolveAlias' ,
168+ delegationFailure (
169+ binFixture (
170+ ' const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(helpTarget));' ,
171+ ) ,
127172 ) ,
128- true ,
173+ null ,
129174 ) ;
175+ // Binds by whatever LOCAL name the import resolved to — an aliased import's local name must
176+ // still be found at the call site, since that is the only name available to call it by.
177+ const aliased = `
178+ import { normalizeCliCommandAlias as resolveAlias } from './commands/cli-command-aliases.ts';
179+ function runHelpFastPath(argv) {
180+ const helpTarget = resolveSimpleHelpTarget(argv);
181+ const commandHelp = buildCommandUsageText(resolveAlias(helpTarget));
182+ }
183+ ` ;
184+ assert . equal ( delegationFailure ( aliased ) , null ) ;
130185} ) ;
131186
132- test ( 'usageTextCallsResolver is false for a raw call, with no wrapping resolver call' , ( ) => {
133- assert . equal (
134- usageTextCallsResolver (
135- 'const commandHelp = buildCommandUsageText(helpTarget);\n' ,
136- 'normalizeCliCommandAlias' ,
137- ) ,
138- false ,
187+ test ( 'usageTextDelegationFailure rejects a raw call, with no wrapping resolver call' , ( ) => {
188+ const failure = delegationFailure (
189+ binFixture ( ' const commandHelp = buildCommandUsageText(helpTarget);' ) ,
139190 ) ;
191+ assert . match ( failure ?? '' , / b u i l d C o m m a n d U s a g e T e x t \( h e l p T a r g e t \) / ) ;
140192} ) ;
141193
142- // #P2 (maintainer review of the original R12): import presence and literal absence both still
143- // pass a bin.ts that imports the resolver and never calls it, or calls it on something unrelated,
144- // while buildCommandUsageText runs on the raw, unresolved helpTarget. These two fixtures are
145- // exactly that regression — the import is real and even "used", but never as the argument
146- // buildCommandUsageText receives — and usageTextCallsResolver must reject both.
147- test ( 'usageTextCallsResolver rejects a present-but-unused import' , ( ) => {
148- const source = `
149- import { normalizeCliCommandAlias } from './commands/cli-command-aliases.ts';
150- const commandHelp = buildCommandUsageText(helpTarget);
151- ` ;
194+ // #P2 (first maintainer review of R12): import presence and literal absence both still pass a
195+ // bin.ts that imports the resolver and never calls it, or calls it on something unrelated, while
196+ // buildCommandUsageText runs on the raw, unresolved helpTarget.
197+ test ( 'usageTextDelegationFailure rejects a present-but-unused import' , ( ) => {
198+ const source = binFixture ( ' const commandHelp = buildCommandUsageText(helpTarget);' ) ;
152199 assert . equal ( importsAliasResolver ( source ) , true ) ;
153- assert . equal ( usageTextCallsResolver ( source , aliasResolverLocalName ( source ) ! ) , false ) ;
200+ assert . notEqual ( delegationFailure ( source ) , null ) ;
154201} ) ;
155202
156- test ( 'usageTextCallsResolver rejects an import used only unrelated to buildCommandUsageText' , ( ) => {
157- const source = `
203+ test ( 'usageTextDelegationFailure rejects an import used only unrelated to buildCommandUsageText' , ( ) => {
204+ const source = binFixture (
205+ ' const commandHelp = buildCommandUsageText(helpTarget);' ,
206+ 'void normalizeCliCommandAlias;' ,
207+ ) ;
208+ assert . equal ( importsAliasResolver ( source ) , true ) ;
209+ assert . notEqual ( delegationFailure ( source ) , null ) ;
210+ } ) ;
211+
212+ // #P2 (second maintainer review of R12): the fixture below is the reviewer's own, verbatim in
213+ // shape. An EXISTENTIAL fact 3 — "some buildCommandUsageText call somewhere wraps the resolver" —
214+ // accepts it, because the decoy on the first line satisfies the quantifier while the line that
215+ // actually ships resolves nothing. This is the regression that motivated making fact 3 universal
216+ // and value-bound, and it must be rejected for BOTH reasons independently.
217+ test ( 'usageTextDelegationFailure rejects a decoy wrapped call beside a raw shipped call' , ( ) => {
218+ const source = binFixture (
219+ ` void buildCommandUsageText(normalizeCliCommandAlias('open'));
220+ const commandHelp = buildCommandUsageText(helpTarget);` ,
221+ ) ;
222+ assert . equal ( importsAliasResolver ( source ) , true ) ;
223+ const failure = delegationFailure ( source ) ;
224+ assert . match ( failure ?? '' , / e v e r y b u i l d C o m m a n d U s a g e T e x t c a l l m u s t r e c e i v e / ) ;
225+ } ) ;
226+
227+ test ( 'usageTextDelegationFailure rejects the resolver applied to anything but the help target' , ( ) => {
228+ // The decoy alone, with no raw call at all: the only usage-text call in the file wraps the
229+ // resolver, so a universal-but-not-value-bound fact 3 would still pass it.
230+ const source = binFixture (
231+ " const commandHelp = buildCommandUsageText(normalizeCliCommandAlias('open'));" ,
232+ ) ;
233+ assert . match ( delegationFailure ( source ) ?? '' , / n o r m a l i z e C l i C o m m a n d A l i a s \( " o p e n " \) / ) ;
234+ } ) ;
235+
236+ test ( 'usageTextDelegationFailure rejects a local shadow of the imported resolver' , ( ) => {
237+ // Fact 3 binds by NAME, so a same-named local would otherwise let the composition read as
238+ // delegation while calling something that resolves nothing.
239+ const source = binFixture (
240+ ' const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(helpTarget));' ,
241+ 'const normalizeCliCommandAlias = (command) => command;' ,
242+ ) ;
243+ assert . match ( delegationFailure ( source ) ?? '' , / s h a d o w i n g t h e i m p o r t e d r e s o l v e r / ) ;
244+ } ) ;
245+
246+ test ( 'usageTextDelegationFailure rejects an ambiguous second help-target binding' , ( ) => {
247+ const source = binFixture (
248+ ` const helpTarget = 'open';
249+ const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(helpTarget));` ,
250+ ) ;
251+ assert . match ( delegationFailure ( source ) ?? '' , / d e c l a r e s h e l p T a r g e t m o r e t h a n o n c e / ) ;
252+ } ) ;
253+
254+ test ( 'usageTextDelegationFailure reports a fast path that no longer builds usage text at all' , ( ) => {
255+ const gone = `
256+ import { normalizeCliCommandAlias } from './commands/cli-command-aliases.ts';
257+ function runHelpFastPath(argv) {
258+ const helpTarget = resolveSimpleHelpTarget(argv);
259+ void normalizeCliCommandAlias(helpTarget);
260+ }
261+ ` ;
262+ assert . match ( delegationFailure ( gone ) ?? '' , / n e v e r c a l l s b u i l d C o m m a n d U s a g e T e x t / ) ;
263+ // …and one whose help-target producer is gone, so the guard says so instead of passing blind.
264+ const untraceable = `
158265import { normalizeCliCommandAlias } from './commands/cli-command-aliases.ts';
159- void normalizeCliCommandAlias;
160- const commandHelp = buildCommandUsageText(helpTarget);
266+ const commandHelp = buildCommandUsageText(normalizeCliCommandAlias(argv[1]));
161267` ;
162- assert . equal ( importsAliasResolver ( source ) , true ) ;
163- assert . equal ( usageTextCallsResolver ( source , aliasResolverLocalName ( source ) ! ) , false ) ;
268+ assert . match ( delegationFailure ( untraceable ) ?? '' , / h a s n o v a r i a b l e i n i t i a l i z e d b y / ) ;
164269} ) ;
165270
166271test ( 'localAliasLiterals reports every requested token present as a string literal' , ( ) => {
@@ -203,6 +308,7 @@ test('the real tree imports the resolver, calls it into buildCommandUsageText, h
203308 assert . deepEqual ( tokens , [ 'launch' , 'long-press' , 'metrics' , 'relaunch' , 'tap' ] ) ;
204309 const localName = aliasResolverLocalName ( binSource ) ;
205310 assert . equal ( localName , 'normalizeCliCommandAlias' ) ;
206- assert . equal ( usageTextCallsResolver ( binSource , localName ! ) , true ) ;
311+ assert . equal ( helpTargetBindingName ( binSource ) , 'helpTarget' ) ;
312+ assert . equal ( usageTextDelegationFailure ( binSource , localName ! ) , null ) ;
207313 assert . deepEqual ( localAliasLiterals ( binSource , tokens ) , [ ] ) ;
208314} ) ;
0 commit comments