@@ -12,23 +12,36 @@ import { parseSync } from 'oxc-parser';
1212 * socket). The HTTP daemon transport, remote-artifact upload and download all
1313 * load these modules on demand instead.
1414 *
15- * Classification comes from oxc-parser's ES module record rather than a regex,
16- * because the forms that matter are exactly the ones a regex tuned to
17- * `import ... from` misses: a bare side-effect `import 'node:http'` binds
18- * nothing yet still evaluates the module, so it reintroduces the whole cost
19- * while looking like nothing at all. Type-only imports are erased at build and
20- * stay allowed; dynamic `import()` is the fix and is deliberately not followed.
15+ * "On demand" is a claim about SCOPE, not about syntax, which is why this reads
16+ * the AST rather than matching import forms. Two shapes evaluate the module
17+ * during module evaluation while looking lazy or looking like nothing at all:
18+ * a bare side-effect `import 'node:http'` (binds no names, still evaluates),
19+ * and a dynamic `import('node:http')` sitting at module top level rather than
20+ * inside a function -- including `.then(...)` and an immediately-invoked
21+ * top-level function. A dynamic import is lazy only when its nearest enclosing
22+ * function scope is not the module itself. Type-only imports and re-exports are
23+ * erased at build and stay allowed.
24+ *
25+ * Known limitation: a top-level function that is invoked indirectly at load
26+ * time (stored, then called by another top-level statement) reads as lazy here.
27+ * Direct top-level invocation -- `(() => { ... })()` -- is detected.
2128 */
2229
2330const srcRoot = path . resolve ( import . meta. dirname , '..' ) ;
2431const LAZY_HTTP_MODULES = new Set ( [ 'node:http' , 'node:https' ] ) ;
32+ const FUNCTION_NODES = new Set ( [
33+ 'FunctionDeclaration' ,
34+ 'FunctionExpression' ,
35+ 'ArrowFunctionExpression' ,
36+ ] ) ;
37+ const WORKSPACE_SPECIFIER = / ^ ( @ a g e n t - d e v i c e \/ [ ^ / ] + ) ( \/ .* ) ? $ / ;
2538
26- /**
27- * Specifiers whose module this file causes to be EVALUATED at load time.
28- * Excludes type-only imports/re-exports (erased) and dynamic imports (lazy).
29- */
30- function evaluatedModuleRefs ( fileName : string , source : string ) : string [ ] {
31- const { module } = parseSync ( fileName , source ) ;
39+ type AstNode = { type ?: string ; [ key : string ] : unknown } ;
40+
41+ type ParsedModuleRecord = ReturnType < typeof parseSync > [ 'module' ] ;
42+
43+ /** Static specifiers this file causes to be EVALUATED (not type-only). */
44+ function staticEvaluatedRefs ( module : ParsedModuleRecord ) : string [ ] {
3245 const refs : string [ ] = [ ] ;
3346 for ( const staticImport of module . staticImports ) {
3447 // No entries at all is a side-effect import (`import 'x'`), which always
@@ -45,6 +58,63 @@ function evaluatedModuleRefs(fileName: string, source: string): string[] {
4558 return refs ;
4659}
4760
61+ function unwrapParentheses ( node : unknown ) : AstNode | null {
62+ let current = node as AstNode | null ;
63+ while ( current ?. type === 'ParenthesizedExpression' )
64+ current = current . expression as AstNode | null ;
65+ return current ;
66+ }
67+
68+ /** The body of a function invoked right where it is defined, if this is that call. */
69+ function immediatelyInvokedBody ( node : AstNode ) : unknown {
70+ if ( node . type !== 'CallExpression' ) return null ;
71+ const callee = unwrapParentheses ( node . callee ) ;
72+ return callee && FUNCTION_NODES . has ( String ( callee . type ) ) ? callee . body : null ;
73+ }
74+
75+ function dynamicImportSpecifier ( node : AstNode ) : string | null {
76+ if ( node . type !== 'ImportExpression' ) return null ;
77+ const source = node . source as { type ?: string ; value ?: unknown } | undefined ;
78+ return source ?. type === 'Literal' && typeof source . value === 'string' ? source . value : null ;
79+ }
80+
81+ function recordDynamicImport ( record : AstNode , eager : boolean , found : string [ ] ) : void {
82+ if ( ! eager ) return ;
83+ const specifier = dynamicImportSpecifier ( record ) ;
84+ if ( specifier !== null ) found . push ( specifier ) ;
85+ }
86+
87+ /** Descends into a node's children, dropping `eager` on the way into a function body. */
88+ function visitChildren ( record : AstNode , eager : boolean , found : string [ ] ) : void {
89+ const childEager = eager && ! FUNCTION_NODES . has ( String ( record . type ) ) ;
90+ for ( const [ key , value ] of Object . entries ( record ) ) {
91+ if ( key !== 'type' ) collectEagerDynamicImports ( value , childEager , found ) ;
92+ }
93+ }
94+
95+ /** Walks the AST, collecting only `import()` calls reached without entering a function. */
96+ function collectEagerDynamicImports ( node : unknown , eager : boolean , found : string [ ] ) : void {
97+ if ( Array . isArray ( node ) ) {
98+ for ( const child of node ) collectEagerDynamicImports ( child , eager , found ) ;
99+ return ;
100+ }
101+ if ( ! node || typeof node !== 'object' ) return ;
102+ const record = node as AstNode ;
103+ recordDynamicImport ( record , eager , found ) ;
104+ // An immediately-invoked function runs now, so its body inherits `eager`.
105+ const invokedBody = immediatelyInvokedBody ( record ) ;
106+ if ( invokedBody ) collectEagerDynamicImports ( invokedBody , eager , found ) ;
107+ visitChildren ( record , eager , found ) ;
108+ }
109+
110+ /** Every specifier this file evaluates at load time, static or dynamic. */
111+ function eagerlyEvaluatedModules ( fileName : string , source : string ) : string [ ] {
112+ const parsed = parseSync ( fileName , source ) ;
113+ const dynamic : string [ ] = [ ] ;
114+ collectEagerDynamicImports ( parsed . program , true , dynamic ) ;
115+ return [ ...new Set ( [ ...staticEvaluatedRefs ( parsed . module ) , ...dynamic ] ) ] ;
116+ }
117+
48118function resolveRelative ( fromFile : string , specifier : string ) : string | null {
49119 const candidate = path . resolve ( path . dirname ( fromFile ) , specifier ) ;
50120 if ( fs . existsSync ( candidate ) && fs . statSync ( candidate ) . isFile ( ) ) return candidate ;
@@ -67,22 +137,30 @@ function readWorkspacePackageDirs(): Map<string, string> {
67137 return dirs ;
68138}
69139
140+ type ExportTarget = { default ?: string ; types ?: string } | string ;
141+
142+ function readExportTarget ( packageDir : string , subpath : string ) : string | undefined {
143+ const manifest = JSON . parse ( fs . readFileSync ( path . join ( packageDir , 'package.json' ) , 'utf8' ) ) as {
144+ exports ?: Record < string , ExportTarget > ;
145+ } ;
146+ const target = manifest . exports ?. [ subpath ] ;
147+ if ( typeof target === 'string' ) return target ;
148+ return target ?. default ?? target ?. types ;
149+ }
150+
70151/**
71152 * Workspace subpath imports are followed too: a package the CLI evaluates can
72153 * pull `node:http` in just as effectively as a file under src/, and stopping the
73154 * walk at the package boundary would be the same blind spot in a new place.
74155 */
75156function resolveWorkspace ( specifier : string , packageDirs : Map < string , string > ) : string | null {
76- const match = / ^ ( @ a g e n t - d e v i c e \/ [ ^ / ] + ) ( \/ .* ) ? $ / . exec ( specifier ) ;
77- const packageDir = match ?. [ 1 ] ? packageDirs . get ( match [ 1 ] ) : undefined ;
157+ const match = WORKSPACE_SPECIFIER . exec ( specifier ) ;
158+ const packageName = match ?. [ 1 ] ;
159+ const packageDir = packageName ? packageDirs . get ( packageName ) : undefined ;
78160 if ( ! packageDir ) return null ;
79- const manifest = JSON . parse ( fs . readFileSync ( path . join ( packageDir , 'package.json' ) , 'utf8' ) ) as {
80- exports ?: Record < string , { default ?: string ; types ?: string } | string > ;
81- } ;
82- const target = manifest . exports ?. [ `.${ match ?. [ 2 ] ?? '' } ` ] ;
83- const relativeTarget = typeof target === 'string' ? target : ( target ?. default ?? target ?. types ) ;
84- if ( ! relativeTarget ) return null ;
85- const resolved = path . resolve ( packageDir , relativeTarget ) ;
161+ const target = readExportTarget ( packageDir , `.${ match ?. [ 2 ] ?? '' } ` ) ;
162+ if ( ! target ) return null ;
163+ const resolved = path . resolve ( packageDir , target ) ;
86164 return fs . existsSync ( resolved ) ? resolved : null ;
87165}
88166
@@ -95,7 +173,7 @@ function eagerClosureOfCli(): string[] {
95173 const current = queue . pop ( ) ;
96174 if ( ! current || visited . has ( current ) ) continue ;
97175 visited . add ( current ) ;
98- for ( const specifier of evaluatedModuleRefs ( current , fs . readFileSync ( current , 'utf8' ) ) ) {
176+ for ( const specifier of eagerlyEvaluatedModules ( current , fs . readFileSync ( current , 'utf8' ) ) ) {
99177 const resolved = specifier . startsWith ( '.' )
100178 ? resolveRelative ( current , specifier )
101179 : resolveWorkspace ( specifier , packageDirs ) ;
@@ -106,41 +184,68 @@ function eagerClosureOfCli(): string[] {
106184}
107185
108186test . for ( [
109- { form : 'side-effect import' , code : `import 'node:http';` , evaluates : true } ,
110- { form : 'default value import' , code : `import http from 'node:http';` , evaluates : true } ,
111- { form : 'namespace import' , code : `import * as http from 'node:http';` , evaluates : true } ,
112- { form : 'named value import' , code : `import { request } from 'node:http';` , evaluates : true } ,
113- { form : 'value re-export' , code : `export { request } from 'node:http';` , evaluates : true } ,
114- { form : 'star re-export' , code : `export * from 'node:http';` , evaluates : true } ,
187+ // --- static forms ---
188+ { form : 'side-effect import' , code : `import 'node:http';` , eager : true } ,
189+ { form : 'default value import' , code : `import http from 'node:http';` , eager : true } ,
190+ { form : 'namespace import' , code : `import * as http from 'node:http';` , eager : true } ,
191+ { form : 'named value import' , code : `import { request } from 'node:http';` , eager : true } ,
192+ { form : 'value re-export' , code : `export { request } from 'node:http';` , eager : true } ,
193+ { form : 'star re-export' , code : `export * from 'node:http';` , eager : true } ,
115194 {
116195 form : 'mixed value + type import' ,
117196 code : `import http, { type IncomingMessage } from 'node:http';` ,
118- evaluates : true ,
119- } ,
120- {
121- form : 'type-only default import' ,
122- code : `import type http from 'node:http';` ,
123- evaluates : false ,
197+ eager : true ,
124198 } ,
199+ { form : 'type-only default import' , code : `import type http from 'node:http';` , eager : false } ,
125200 {
126201 form : 'type-only named import' ,
127202 code : `import { type IncomingMessage } from 'node:http';` ,
128- evaluates : false ,
203+ eager : false ,
129204 } ,
130205 {
131206 form : 'type-only re-export' ,
132207 code : `export type { IncomingMessage } from 'node:http';` ,
133- evaluates : false ,
208+ eager : false ,
209+ } ,
210+ // --- dynamic import: scope decides, not syntax ---
211+ { form : 'top-level await import' , code : `const m = await import('node:http');` , eager : true } ,
212+ { form : 'top-level import().then' , code : `import('node:http').then((m) => m);` , eager : true } ,
213+ {
214+ form : 'top-level immediately-invoked arrow' ,
215+ code : `(async () => { await import('node:http'); })();` ,
216+ eager : true ,
217+ } ,
218+ {
219+ form : 'function-declaration-local import' ,
220+ code : `async function load() { return await import('node:http'); }` ,
221+ eager : false ,
222+ } ,
223+ {
224+ form : 'arrow-local import' ,
225+ code : `const load = async () => await import('node:http');` ,
226+ eager : false ,
227+ } ,
228+ {
229+ form : 'method-local import' ,
230+ code : `class K { async load() { await import('node:http'); } }` ,
231+ eager : false ,
232+ } ,
233+ {
234+ form : 'ternary inside a function (the shipped lazy-load shape)' ,
235+ code : `async function load(s: boolean) {
236+ return s ? (await import('node:https')).default : (await import('node:http')).default;
237+ }` ,
238+ eager : false ,
134239 } ,
135- { form : 'dynamic import ', code : `const m = await import('node:http');` , evaluates : false } ,
136- ] ) ( '$form is classified as evaluates=$evaluates' , ( { code , evaluates } ) => {
137- expect ( evaluatedModuleRefs ( 'fixture.ts' , code ) ) . toEqual ( evaluates ? [ 'node:http' ] : [ ] ) ;
240+ ] ) ( '$ form is eager=$eager ', ( { code, eager } ) => {
241+ const refs = eagerlyEvaluatedModules ( 'fixture.ts' , code ) ;
242+ expect ( refs . includes ( 'node:http' ) || refs . includes ( 'node:https' ) ) . toBe ( eager ) ;
138243} ) ;
139244
140245test ( 'the CLI startup import closure never evaluates node:http or node:https' , ( ) => {
141246 const offenders : string [ ] = [ ] ;
142247 for ( const file of eagerClosureOfCli ( ) ) {
143- for ( const specifier of evaluatedModuleRefs ( file , fs . readFileSync ( file , 'utf8' ) ) ) {
248+ for ( const specifier of eagerlyEvaluatedModules ( file , fs . readFileSync ( file , 'utf8' ) ) ) {
144249 if ( LAZY_HTTP_MODULES . has ( specifier ) ) {
145250 offenders . push ( `${ path . relative ( srcRoot , file ) } -> ${ specifier } ` ) ;
146251 }
@@ -156,7 +261,7 @@ test('the CLI startup import closure never evaluates node:http or node:https', (
156261
157262test ( 'the CLI startup import closure is reachable and crosses the package boundary' , ( ) => {
158263 // Guards the test above from silently passing because the walk found nothing:
159- // a resolver that returns null for everything would leave both the src side
264+ // a resolver that returned null for everything would leave both the src side
160265 // and the workspace side of the closure empty while the guard stayed green.
161266 const closure = eagerClosureOfCli ( ) ;
162267 expect ( closure . length ) . toBeGreaterThan ( 50 ) ;
0 commit comments