11import { expect , test } from 'vitest' ;
22import fs from 'node:fs' ;
33import path from 'node:path' ;
4- import { parseSync } from 'oxc-parser' ;
4+ import {
5+ eagerClosureOf ,
6+ eagerlyEvaluatedModules ,
7+ } from './eager-import-closure.fixtures' ;
58
69/**
710 * Every CLI invocation eagerly evaluates the static import closure of
@@ -17,179 +20,12 @@ import { parseSync } from 'oxc-parser';
1720 * static import of the Maestro engine (and the YAML parser behind it) put a 131 kB chunk and
1821 * ~28ms on every warm command, for a format most invocations never touch (#1802). The replay
1922 * script-source builder loads it on demand, only once an entry actually resolves to a flow.
20- *
21- * "On demand" is a claim about SCOPE, not about syntax, which is why this reads
22- * the AST rather than matching import forms. Two shapes evaluate the module
23- * during module evaluation while looking lazy or looking like nothing at all:
24- * a bare side-effect `import 'node:http'` (binds no names, still evaluates),
25- * and a dynamic `import('node:http')` sitting at module top level rather than
26- * inside a function -- including `.then(...)` and an immediately-invoked
27- * top-level function. A dynamic import is lazy only when its nearest enclosing
28- * function scope is not the module itself. Type-only imports and re-exports are
29- * erased at build and stay allowed.
30- *
31- * Known limitation: a top-level function that is invoked indirectly at load
32- * time (stored, then called by another top-level statement) reads as lazy here.
33- * Direct top-level invocation -- `(() => { ... })()` -- is detected.
3423 */
3524
3625const srcRoot = path . resolve ( import . meta. dirname , '..' ) ;
3726const LAZY_HTTP_MODULES = new Set ( [ 'node:http' , 'node:https' ] ) ;
3827/** Engines heavy enough that evaluating them on startup is a measurable regression. */
3928const LAZY_ENGINE_MODULES = new Set ( [ '@agent-device/maestro' ] ) ;
40- const FUNCTION_NODES = new Set ( [
41- 'FunctionDeclaration' ,
42- 'FunctionExpression' ,
43- 'ArrowFunctionExpression' ,
44- ] ) ;
45- const WORKSPACE_SPECIFIER = / ^ ( @ a g e n t - d e v i c e \/ [ ^ / ] + ) ( \/ .* ) ? $ / ;
46-
47- type AstNode = { type ?: string ; [ key : string ] : unknown } ;
48-
49- type ParsedModuleRecord = ReturnType < typeof parseSync > [ 'module' ] ;
50-
51- /** Static specifiers this file causes to be EVALUATED (not type-only). */
52- function staticEvaluatedRefs ( module : ParsedModuleRecord ) : string [ ] {
53- const refs : string [ ] = [ ] ;
54- for ( const staticImport of module . staticImports ) {
55- // No entries at all is a side-effect import (`import 'x'`), which always
56- // evaluates. Otherwise it evaluates unless every binding is type-only.
57- const evaluates =
58- staticImport . entries . length === 0 || staticImport . entries . some ( ( entry ) => ! entry . isType ) ;
59- if ( evaluates ) refs . push ( staticImport . moduleRequest . value ) ;
60- }
61- for ( const staticExport of module . staticExports ) {
62- for ( const entry of staticExport . entries ) {
63- if ( entry . moduleRequest && ! entry . isType ) refs . push ( entry . moduleRequest . value ) ;
64- }
65- }
66- return refs ;
67- }
68-
69- function unwrapParentheses ( node : unknown ) : AstNode | null {
70- let current = node as AstNode | null ;
71- while ( current ?. type === 'ParenthesizedExpression' )
72- current = current . expression as AstNode | null ;
73- return current ;
74- }
75-
76- /** The body of a function invoked right where it is defined, if this is that call. */
77- function immediatelyInvokedBody ( node : AstNode ) : unknown {
78- if ( node . type !== 'CallExpression' ) return null ;
79- const callee = unwrapParentheses ( node . callee ) ;
80- return callee && FUNCTION_NODES . has ( String ( callee . type ) ) ? callee . body : null ;
81- }
82-
83- function dynamicImportSpecifier ( node : AstNode ) : string | null {
84- if ( node . type !== 'ImportExpression' ) return null ;
85- const source = node . source as { type ?: string ; value ?: unknown } | undefined ;
86- return source ?. type === 'Literal' && typeof source . value === 'string' ? source . value : null ;
87- }
88-
89- function recordDynamicImport ( record : AstNode , eager : boolean , found : string [ ] ) : void {
90- if ( ! eager ) return ;
91- const specifier = dynamicImportSpecifier ( record ) ;
92- if ( specifier !== null ) found . push ( specifier ) ;
93- }
94-
95- /** Descends into a node's children, dropping `eager` on the way into a function body. */
96- function visitChildren ( record : AstNode , eager : boolean , found : string [ ] ) : void {
97- const childEager = eager && ! FUNCTION_NODES . has ( String ( record . type ) ) ;
98- for ( const [ key , value ] of Object . entries ( record ) ) {
99- if ( key !== 'type' ) collectEagerDynamicImports ( value , childEager , found ) ;
100- }
101- }
102-
103- /** Walks the AST, collecting only `import()` calls reached without entering a function. */
104- function collectEagerDynamicImports ( node : unknown , eager : boolean , found : string [ ] ) : void {
105- if ( Array . isArray ( node ) ) {
106- for ( const child of node ) collectEagerDynamicImports ( child , eager , found ) ;
107- return ;
108- }
109- if ( ! node || typeof node !== 'object' ) return ;
110- const record = node as AstNode ;
111- recordDynamicImport ( record , eager , found ) ;
112- // An immediately-invoked function runs now, so its body inherits `eager`.
113- const invokedBody = immediatelyInvokedBody ( record ) ;
114- if ( invokedBody ) collectEagerDynamicImports ( invokedBody , eager , found ) ;
115- visitChildren ( record , eager , found ) ;
116- }
117-
118- /** Every specifier this file evaluates at load time, static or dynamic. */
119- function eagerlyEvaluatedModules ( fileName : string , source : string ) : string [ ] {
120- const parsed = parseSync ( fileName , source ) ;
121- const dynamic : string [ ] = [ ] ;
122- collectEagerDynamicImports ( parsed . program , true , dynamic ) ;
123- return [ ...new Set ( [ ...staticEvaluatedRefs ( parsed . module ) , ...dynamic ] ) ] ;
124- }
125-
126- function resolveRelative ( fromFile : string , specifier : string ) : string | null {
127- const candidate = path . resolve ( path . dirname ( fromFile ) , specifier ) ;
128- if ( fs . existsSync ( candidate ) && fs . statSync ( candidate ) . isFile ( ) ) return candidate ;
129- for ( const suffix of [ '.ts' , '.tsx' , '/index.ts' ] ) {
130- if ( fs . existsSync ( `${ candidate } ${ suffix } ` ) ) return `${ candidate } ${ suffix } ` ;
131- }
132- return null ;
133- }
134-
135- /** `@agent-device/<pkg>` -> that package's directory, keyed by its declared name. */
136- function readWorkspacePackageDirs ( ) : Map < string , string > {
137- const packagesRoot = path . resolve ( srcRoot , '..' , 'packages' ) ;
138- const dirs = new Map < string , string > ( ) ;
139- for ( const entry of fs . readdirSync ( packagesRoot ) ) {
140- const manifestPath = path . join ( packagesRoot , entry , 'package.json' ) ;
141- if ( ! fs . existsSync ( manifestPath ) ) continue ;
142- const manifest = JSON . parse ( fs . readFileSync ( manifestPath , 'utf8' ) ) as { name ?: string } ;
143- if ( manifest . name ) dirs . set ( manifest . name , path . join ( packagesRoot , entry ) ) ;
144- }
145- return dirs ;
146- }
147-
148- type ExportTarget = { default ?: string ; types ?: string } | string ;
149-
150- function readExportTarget ( packageDir : string , subpath : string ) : string | undefined {
151- const manifest = JSON . parse ( fs . readFileSync ( path . join ( packageDir , 'package.json' ) , 'utf8' ) ) as {
152- exports ?: Record < string , ExportTarget > ;
153- } ;
154- const target = manifest . exports ?. [ subpath ] ;
155- if ( typeof target === 'string' ) return target ;
156- return target ?. default ?? target ?. types ;
157- }
158-
159- /**
160- * Workspace subpath imports are followed too: a package the CLI evaluates can
161- * pull `node:http` in just as effectively as a file under src/, and stopping the
162- * walk at the package boundary would be the same blind spot in a new place.
163- */
164- function resolveWorkspace ( specifier : string , packageDirs : Map < string , string > ) : string | null {
165- const match = WORKSPACE_SPECIFIER . exec ( specifier ) ;
166- const packageName = match ?. [ 1 ] ;
167- const packageDir = packageName ? packageDirs . get ( packageName ) : undefined ;
168- if ( ! packageDir ) return null ;
169- const target = readExportTarget ( packageDir , `.${ match ?. [ 2 ] ?? '' } ` ) ;
170- if ( ! target ) return null ;
171- const resolved = path . resolve ( packageDir , target ) ;
172- return fs . existsSync ( resolved ) ? resolved : null ;
173- }
174-
175- /** Every repo file evaluated as a consequence of importing `src/cli.ts`. */
176- function eagerClosureOfCli ( ) : string [ ] {
177- const packageDirs = readWorkspacePackageDirs ( ) ;
178- const queue = [ path . join ( srcRoot , 'cli.ts' ) ] ;
179- const visited = new Set < string > ( ) ;
180- while ( queue . length > 0 ) {
181- const current = queue . pop ( ) ;
182- if ( ! current || visited . has ( current ) ) continue ;
183- visited . add ( current ) ;
184- for ( const specifier of eagerlyEvaluatedModules ( current , fs . readFileSync ( current , 'utf8' ) ) ) {
185- const resolved = specifier . startsWith ( '.' )
186- ? resolveRelative ( current , specifier )
187- : resolveWorkspace ( specifier , packageDirs ) ;
188- if ( resolved ) queue . push ( resolved ) ;
189- }
190- }
191- return [ ...visited ] ;
192- }
19329
19430test . for ( [
19531 // --- static forms ---
@@ -252,7 +88,7 @@ test.for([
25288
25389test ( 'the CLI startup import closure never evaluates node:http or node:https' , ( ) => {
25490 const offenders : string [ ] = [ ] ;
255- for ( const file of eagerClosureOfCli ( ) ) {
91+ for ( const file of eagerClosureOf ( path . join ( srcRoot , 'cli.ts' ) ) ) {
25692 for ( const specifier of eagerlyEvaluatedModules ( file , fs . readFileSync ( file , 'utf8' ) ) ) {
25793 if ( LAZY_HTTP_MODULES . has ( specifier ) ) {
25894 offenders . push ( `${ path . relative ( srcRoot , file ) } -> ${ specifier } ` ) ;
@@ -269,7 +105,7 @@ test('the CLI startup import closure never evaluates node:http or node:https', (
269105
270106test ( 'the CLI startup import closure never evaluates the Maestro engine' , ( ) => {
271107 const offenders : string [ ] = [ ] ;
272- for ( const file of eagerClosureOfCli ( ) ) {
108+ for ( const file of eagerClosureOf ( path . join ( srcRoot , 'cli.ts' ) ) ) {
273109 for ( const specifier of eagerlyEvaluatedModules ( file , fs . readFileSync ( file , 'utf8' ) ) ) {
274110 if ( LAZY_ENGINE_MODULES . has ( specifier ) ) {
275111 offenders . push ( `${ path . relative ( srcRoot , file ) } -> ${ specifier } ` ) ;
@@ -289,7 +125,7 @@ test('the CLI startup import closure is reachable and crosses the package bounda
289125 // Guards the test above from silently passing because the walk found nothing:
290126 // a resolver that returned null for everything would leave both the src side
291127 // and the workspace side of the closure empty while the guard stayed green.
292- const closure = eagerClosureOfCli ( ) ;
128+ const closure = eagerClosureOf ( path . join ( srcRoot , 'cli.ts' ) ) ;
293129 expect ( closure . length ) . toBeGreaterThan ( 50 ) ;
294130 expect (
295131 closure . filter ( ( file ) => file . includes ( `${ path . sep } packages${ path . sep } ` ) ) . length ,
0 commit comments