ucn 5.2.1 → 5.3.0

package/languages/javascript.js

@@ -463,6 +463,55 @@ function returnsReceiverSelf(node) {
     return sawSelf;
 }
 
+/**
+ * Exact call expression returned by an expression-bodied arrow. This is a
+ * syntax proof, not return-type inference: query-time flow resolves the call
+ * through its ordinary import/receiver ownership rails. Block bodies,
+ * conditionals, and other expressions deliberately stay unmarked.
+ */
+function returnedArrowCallSpan(node) {
+    if (node.type !== 'arrow_function') return null;
+    let body = node.childForFieldName('body');
+    while (body?.type === 'parenthesized_expression' && body.namedChildCount === 1) {
+        body = body.namedChild(0);
+    }
+    if (body?.type !== 'call_expression') return null;
+    return { start: body.startIndex, end: body.endIndex };
+}
+
+/**
+ * Exact `this.field...` value returned by a one-statement method body. The
+ * deliberately narrow shape proves both that the member path is returned and
+ * that no fallthrough/alternate return widens the compiler-inferred type.
+ */
+function returnedReceiverFieldPath(node) {
+    const body = node.childForFieldName('body');
+    if (!body || body.type !== 'statement_block' || body.namedChildCount !== 1) {
+        return null;
+    }
+    const statement = body.namedChild(0);
+    if (statement?.type !== 'return_statement' || statement.namedChildCount !== 1) {
+        return null;
+    }
+    let value = statement.namedChild(0);
+    while (value?.type === 'parenthesized_expression' && value.namedChildCount === 1) {
+        value = value.namedChild(0);
+    }
+    const fields = [];
+    while (value?.type === 'member_expression') {
+        const property = value.childForFieldName('property');
+        const object = value.childForFieldName('object');
+        if (!property || !object ||
+            !['property_identifier', 'private_property_identifier', 'identifier']
+                .includes(property.type)) {
+            return null;
+        }
+        fields.unshift(property.text);
+        value = object;
+    }
+    return value?.type === 'this' && fields.length > 0 ? fields : null;
+}
+
 /**
  * Process a node for function extraction (single-pass helper)
  * Returns true if node was matched, false otherwise
@@ -634,6 +683,7 @@ function _processFunction(node, functions, processedRanges, lines) {
                         // declaration text, so we double-check the value node directly.
                         const valueIsAsync = valueNode.text.trimStart().startsWith('async ');
                         const isAsync = valueIsAsync || modifiers.includes('async');
+                        const returnedCall = returnedArrowCallSpan(valueNode);
 
                         functions.push({
                             name: nameNode.text,
@@ -648,6 +698,10 @@ function _processFunction(node, functions, processedRanges, lines) {
                             modifiers,
                             ...lexicalOwnerRange(node),
                             ...typeAnno,
+                            ...(returnedCall && {
+                                returnedCallStart: returnedCall.start,
+                                returnedCallEnd: returnedCall.end,
+                            }),
                             ...(generics && { generics }),
                             ...(docstring && { docstring })
                         });
@@ -1301,6 +1355,8 @@ function extractClassMembers(classNode, codeOrLines) {
                 const isAsync = text.match(/^\s*(?:(?:public|private|protected)\s+)?(?:static\s+)?(?:override\s+)?async\s/) !== null;
                 const returnType = extractReturnType(child) ||
                     (returnsReceiverSelf(child) ? 'this' : null);
+                const returnedReceiverPath = !returnType
+                    ? returnedReceiverFieldPath(child) : null;
                 const docstring = extractJSDocstring(code, startLine);
                 const paramsStructured = parseStructuredParams(paramsNode, 'javascript');
                 const typeAnno = buildTypeAnnotations(paramsStructured, returnType, code, startLine, true);
@@ -1329,6 +1385,7 @@ function extractClassMembers(classNode, codeOrLines) {
                     // (fix #230) — pickBestDefinition prefers the implementation.
                     ...(child.type === 'method_signature' && { isSignature: true }),
                     ...typeAnno,
+                    ...(returnedReceiverPath && { returnedReceiverPath }),
                     ...(docstring && { docstring }),
                     ...(decorators.length > 0 && { decorators }),
                     ...(decoratorsWithArgs.length > 0 && { decoratorsWithArgs })
@@ -1467,6 +1524,14 @@ function extractClassMembers(classNode, codeOrLines) {
                     const fieldTypeNode = child.childForFieldName('type');
                     const fieldType = fieldTypeNode
                         ? fieldTypeNode.text.replace(/^:\s*/, '').trim() : undefined;
+                    // A direct identifier initializer on a static field keeps
+                    // the lexical callable identity available to the IR:
+                    // `static create = createSchema`. Resolution remains
+                    // same-file and overload-disciplined in createFileIR;
+                    // expressions, member accesses, and instance fields do
+                    // not receive this proof marker.
+                    const callableTarget = isStatic && valueNode?.type === 'identifier'
+                        ? valueNode.text : undefined;
                     members.push({
                         name,
                         startLine,
@@ -1474,6 +1539,7 @@ function extractClassMembers(classNode, codeOrLines) {
                         memberType: name.startsWith('#') ? 'private field' : 'field',
                         ...(isStatic && { modifiers: ['static'] }),
                         ...(fieldType && { fieldType }),
+                        ...(callableTarget && { callableTarget }),
                         ...(fieldDecorators.length > 0 && { decorators: fieldDecorators })
                         // Not a method - regular field
                     });
@@ -1920,13 +1986,120 @@ function findCallsInCode(code, parser) {
     const tree = parseTree(parser, code);
     const calls = [];
     const assignedMembers = new Set();
+    const mutatedObjectRoots = new Set();
+    const moduleCompositions = new Map();
+    const unsafeModuleCompositions = new Set();
+    const namespaceAliases = new Set();
+    const accessRoot = (node) => {
+        let current = node;
+        while (current && (current.type === 'member_expression' ||
+            current.type === 'subscript_expression')) {
+            current = current.childForFieldName('object');
+        }
+        return current?.type === 'identifier' ? current.text : undefined;
+    };
     traverseTreeCached(tree.rootNode, node => {
-        if (node.type !== 'assignment_expression' &&
-            node.type !== 'augmented_assignment_expression') return true;
-        const left = node.childForFieldName('left');
-        if (left?.type === 'member_expression') assignedMembers.add(left.text);
+        if (node.type === 'namespace_import') {
+            const identifier = node.namedChild(0);
+            if (identifier?.type === 'identifier') namespaceAliases.add(identifier.text);
+        }
+        if (node.type === 'variable_declarator') {
+            const declaration = node.parent;
+            const nameNode = node.childForFieldName('name');
+            const valueNode = node.childForFieldName('value');
+            if (nameNode?.type === 'identifier' && valueNode?.type === 'object' &&
+                declaration?.type === 'lexical_declaration' &&
+                declaration.child(0)?.text === 'const' && isModuleScope(declaration)) {
+                const layers = [];
+                let spreadCandidates = 0;
+                for (let i = 0; i < valueNode.namedChildCount; i++) {
+                    const item = valueNode.namedChild(i);
+                    if (item.type === 'spread_element') {
+                        const value = item.namedChild(0);
+                        if (value?.type === 'identifier') {
+                            // Namespace imports may legally appear later in
+                            // the module. Resolve candidates after this pass
+                            // has seen the complete import surface.
+                            layers.push({ kind: 'spread-candidate', receiver: value.text });
+                            spreadCandidates++;
+                        } else {
+                            layers.push({ kind: 'unknown' });
+                        }
+                        continue;
+                    }
+                    if (item.type === 'pair') {
+                        const key = item.childForFieldName('key');
+                        const staticKey = key && ['property_identifier', 'identifier', 'string']
+                            .includes(key.type)
+                            ? key.text.replace(/^['"]|['"]$/g, '') : null;
+                        layers.push(staticKey
+                            ? { kind: 'property', name: staticKey }
+                            : { kind: 'unknown' });
+                        continue;
+                    }
+                    if (item.type === 'shorthand_property_identifier' ||
+                        item.type === 'method_definition') {
+                        const name = item.type === 'method_definition'
+                            ? item.childForFieldName('name')?.text : item.text;
+                        layers.push(name
+                            ? { kind: 'property', name }
+                            : { kind: 'unknown' });
+                        continue;
+                    }
+                    layers.push({ kind: 'unknown' });
+                }
+                if (spreadCandidates > 0) moduleCompositions.set(nameNode.text, layers);
+            }
+        }
+        if (node.type === 'assignment_expression' ||
+            node.type === 'augmented_assignment_expression') {
+            const left = node.childForFieldName('left');
+            if (left?.type === 'member_expression') assignedMembers.add(left.text);
+            const root = accessRoot(left);
+            if (root) mutatedObjectRoots.add(root);
+        }
+        // A namespace-spread composite is exact only while the ordinary
+        // object remains private and unmodified. Any use of the object value
+        // itself (export, alias, return, argument, spread, etc.) can expose a
+        // mutation; property reads/calls are the sole accepted uses.
+        if (node.type !== 'identifier' || !moduleCompositions.has(node.text)) return true;
+        const parent = node.parent;
+        if (parent?.type === 'variable_declarator' &&
+            parent.childForFieldName('name')?.id === node.id) return true;
+        if ((parent?.type === 'member_expression' ||
+            parent?.type === 'subscript_expression') &&
+            parent.childForFieldName('object')?.id === node.id) {
+            let access = parent;
+            while ((access.parent?.type === 'member_expression' ||
+                access.parent?.type === 'subscript_expression') &&
+                access.parent.childForFieldName('object')?.id === access.id) {
+                access = access.parent;
+            }
+            const container = access.parent;
+            const assigned = (container?.type === 'assignment_expression' ||
+                container?.type === 'augmented_assignment_expression') &&
+                container.childForFieldName('left')?.id === access.id;
+            const updated = container?.type === 'update_expression';
+            const deleted = container?.type === 'unary_expression' &&
+                container.child(0)?.text === 'delete';
+            if (!assigned && !updated && !deleted) return true;
+        }
+        unsafeModuleCompositions.add(node.text);
         return true;
     });
+    for (const [name, layers] of moduleCompositions) {
+        const normalized = layers.map(layer => layer.kind === 'spread-candidate'
+            ? (namespaceAliases.has(layer.receiver)
+                ? { kind: 'spread', receiver: layer.receiver }
+                : { kind: 'unknown' })
+            : layer);
+        if (normalized.some(layer => layer.kind === 'spread')) {
+            moduleCompositions.set(name, normalized);
+        } else {
+            moduleCompositions.delete(name);
+        }
+    }
+    for (const name of mutatedObjectRoots) unsafeModuleCompositions.add(name);
     const functionStack = [];  // Stack of { name, startLine, endLine }
     // Local aliases with lexical ownership. A flat aliasName→target map leaks
     // block locals into the rest of a module (`let effect = batchedEffect`
@@ -2162,6 +2335,16 @@ function findCallsInCode(code, parser) {
 
     const _patternDeclaresName = (pattern, name) => {
         if (!pattern) return false;
+        // TypeScript parameter wrappers contain both the runtime binding
+        // pattern and a type annotation. Only the pattern declares names:
+        // `metadata: registries.GlobalMeta` must not make the namespace
+        // identifier `registries` look like a shadowing parameter.
+        if (pattern.type === 'required_parameter' ||
+            pattern.type === 'optional_parameter') {
+            return _patternDeclaresName(
+                pattern.childForFieldName('pattern') ||
+                pattern.childForFieldName('name'), name);
+        }
         if ((pattern.type === 'identifier' ||
             pattern.type === 'shorthand_property_identifier_pattern') &&
             pattern.text === name) return true;
@@ -2188,6 +2371,94 @@ function findCallsInCode(code, parser) {
         }
         return false;
     };
+    // fix #337: a declarator initialized from require()/import() is an
+    // IMPORT binding — the module's own name reaching this scope — not a
+    // local shadow. `function build() { const { Foo } = require('./lib');
+    // new Foo() }` resolves through import ownership exactly like the
+    // top-level require the walk already exempts as the module binding
+    // itself. Unwraps `await import()`, parens, and `require('./x').Foo`.
+    const _isImportBindingInitializer = (value) => {
+        let v = value;
+        for (;;) {
+            if (!v) return false;
+            if (v.type === 'await_expression' || v.type === 'parenthesized_expression') {
+                v = v.namedChild(0);
+                continue;
+            }
+            if (v.type === 'member_expression' || v.type === 'subscript_expression') {
+                v = v.childForFieldName('object');
+                continue;
+            }
+            break;
+        }
+        if (v.type !== 'call_expression') return false;
+        const fn = v.childForFieldName('function');
+        return !!fn && (fn.type === 'import' || (fn.type === 'identifier' && fn.text === 'require'));
+    };
+    const _declaresLocalShadow = (declNode, name) => {
+        for (let i = 0; i < declNode.namedChildCount; i++) {
+            const d = declNode.namedChild(i);
+            if (d.type !== 'variable_declarator') continue;
+            if (!_patternDeclaresName(d.childForFieldName('name'), name)) continue;
+            if (_isImportBindingInitializer(d.childForFieldName('value'))) continue;
+            return true;
+        }
+        return false;
+    };
+
+    // Bare callback references need to distinguish a module-owned VALUE from
+    // an unbound name. File-level import reachability cannot prove the value's
+    // identity: `const app = express(); use(app)` may live in a file that also
+    // imports the pinned target, but `app` is the factory result rather than a
+    // direct lexical reference to that target. Keep the parser evidence exact
+    // and cheap by collecting only declarations whose lexical owner is the
+    // program/module root (export wrappers included).
+    const moduleValueBindings = new Set();
+    const collectPatternNames = (pattern) => {
+        if (!pattern) return;
+        if (pattern.type === 'identifier' ||
+            pattern.type === 'shorthand_property_identifier_pattern') {
+            moduleValueBindings.add(pattern.text);
+            return;
+        }
+        if (pattern.type === 'pair_pattern' || pattern.type === 'pair') {
+            collectPatternNames(pattern.childForFieldName('value'));
+            return;
+        }
+        if (pattern.type === 'assignment_pattern') {
+            collectPatternNames(
+                pattern.childForFieldName('left') || pattern.childForFieldName('pattern'));
+            return;
+        }
+        for (let i = 0; i < pattern.namedChildCount; i++) {
+            collectPatternNames(pattern.namedChild(i));
+        }
+    };
+    const collectModuleDeclaration = (statement) => {
+        let declaration = statement;
+        if (statement.type === 'export_statement') {
+            declaration = null;
+            for (let i = 0; i < statement.namedChildCount; i++) {
+                const child = statement.namedChild(i);
+                if (child.type === 'lexical_declaration' || child.type === 'variable_declaration') {
+                    declaration = child;
+                    break;
+                }
+            }
+        }
+        if (!declaration ||
+            (declaration.type !== 'lexical_declaration' &&
+                declaration.type !== 'variable_declaration')) return;
+        for (let i = 0; i < declaration.namedChildCount; i++) {
+            const declarator = declaration.namedChild(i);
+            if (declarator.type === 'variable_declarator') {
+                collectPatternNames(declarator.childForFieldName('name'));
+            }
+        }
+    };
+    for (let i = 0; i < tree.rootNode.namedChildCount; i++) {
+        collectModuleDeclaration(tree.rootNode.namedChild(i));
+    }
 
     // fix #203: is a bare-identifier function REFERENCE shadowed by a
     // let/const/var local, for/catch binding, or inner-arrow param in an
@@ -2210,7 +2481,7 @@ function findCallsInCode(code, parser) {
                         stmt.childForFieldName('name')?.text === name) return true;
                     if (stmt.startIndex >= refNode.startIndex) continue; // declaration-before-use
                     if ((stmt.type === 'lexical_declaration' || stmt.type === 'variable_declaration') &&
-                        _declaresName(stmt, name)) return true;
+                        _declaresLocalShadow(stmt, name)) return true;
                 }
             } else if (p.type === 'for_statement') {
                 const init = p.childForFieldName('initializer');
@@ -2241,6 +2512,11 @@ function findCallsInCode(code, parser) {
         return false;
     };
 
+    const bareReferenceBindingFields = (refNode) => ({
+        ...(isShadowedByLocal(refNode, refNode.text) && { localShadow: true }),
+        ...(moduleValueBindings.has(refNode.text) && { moduleLocalBinding: true }),
+    });
+
     const isConditionalReassignment = node => {
         for (let p = node.parent; p && !isFunctionNode(p); p = p.parent) {
             if (p.type === 'if_statement') {
@@ -2429,7 +2705,7 @@ function findCallsInCode(code, parser) {
                     isMethod: false,
                     isFunctionReference: true,
                     isPotentialCallback: true,
-                    ...(isShadowedByLocal(right, right.text) && { localShadow: true }),
+                    ...bareReferenceBindingFields(right),
                     enclosingFunction: getCurrentEnclosingFunction(),
                 });
             }
@@ -2696,6 +2972,9 @@ function findCallsInCode(code, parser) {
                         const receiverIsModule = !!receiverModuleSpecifier ||
                             (!!receiver && moduleAliases.has(receiver) &&
                                 !localVarTypes.has(receiver));
+                        const receiverModuleComposition = receiver &&
+                            !unsafeModuleCompositions.has(receiver)
+                            ? moduleCompositions.get(receiver) : undefined;
                         const firstArg = getFirstStringArg(node);
                         const argCount = getArgCount(node);
                         let assignedTo = jsAssignmentTargetOf(node);
@@ -2730,6 +3009,9 @@ function findCallsInCode(code, parser) {
                             }),
                             ...(receiverIsModule && { receiverIsModule: true }),
                             ...(receiverModuleSpecifier && { receiverModuleSpecifier }),
+                            ...(receiverModuleComposition && {
+                                receiverModuleComposition,
+                            }),
                             ...(receiver && assignedMembers.has(`${receiver}.${propName}`) && {
                                 receiverMemberAssigned: true,
                             }),
@@ -2787,7 +3069,7 @@ function findCallsInCode(code, parser) {
                                     line: arg.startPosition.row + 1,
                                     isMethod: false,
                                     isFunctionReference: true,
-                                    ...(isShadowedByLocal(arg, arg.text) && { localShadow: true }),
+                                    ...bareReferenceBindingFields(arg),
                                     enclosingFunction
                                 });
                             } else if (arg.type === 'member_expression') {
@@ -2832,7 +3114,7 @@ function findCallsInCode(code, parser) {
                                 isMethod: false,
                                 isFunctionReference: true,
                                 isPotentialCallback: true,
-                                ...(isShadowedByLocal(arg, arg.text) && { localShadow: true }),
+                                ...bareReferenceBindingFields(arg),
                                 enclosingFunction
                             });
                         }
@@ -2873,7 +3155,7 @@ function findCallsInCode(code, parser) {
                                             isMethod: false,
                                             isFunctionReference: true,
                                             isPotentialCallback: true,
-                                            ...(isShadowedByLocal(val, val.text) && { localShadow: true }),
+                                            ...bareReferenceBindingFields(val),
                                             enclosingFunction
                                         });
                                     }
@@ -2977,7 +3259,7 @@ function findCallsInCode(code, parser) {
                         isMethod: false,
                         isFunctionReference: true,
                         isPotentialCallback: true,
-                        ...(isShadowedByLocal(child, child.text) && { localShadow: true }),
+                        ...bareReferenceBindingFields(child),
                         enclosingFunction
                     });
                 } else if (child.type === 'member_expression') {
@@ -3190,6 +3472,144 @@ function findImportsInCode(code, parser) {
     const imports = [];
     let importAliases = null;  // {original, local}[] — tracks renamed imports
 
+    // fix #338: classify edges that do not execute during module
+    // initialization so dependency-cycle reporting can separate an eager
+    // import-time loop from a deliberate lazy one. `require()`/`import()`
+    // nested in any function body (incl. `() => require('./x')` thunks) runs
+    // only when that function is called; TS `import type` / `export type`
+    // re-exports and all-`type` specifier lists are erased at compile time.
+    const FUNCTION_LIKE = new Set(['function_declaration', 'function_expression', 'arrow_function',
+        'method_definition', 'generator_function_declaration', 'generator_function', 'function']);
+    const importDeferral = (node) => {
+        for (let p = node.parent; p; p = p.parent) {
+            if (FUNCTION_LIKE.has(p.type)) return 'function-local';
+        }
+        return null;
+    };
+    // Static path folding is positive identity evidence. A method merely
+    // named join/resolve need not be Node's path utility. Keep an ambiguous
+    // or shadowed binding dynamic rather than inventing a module edge.
+    let pathBindings = null;
+    const isPathModuleCall = node => {
+        if (node?.type !== 'call_expression') return false;
+        const fn = node.childForFieldName('function');
+        const args = node.childForFieldName('arguments');
+        const arg = args?.namedChild(0);
+        return fn?.type === 'identifier' && fn.text === 'require' &&
+            args.namedChildCount === 1 && arg?.type === 'string' &&
+            ['path', 'node:path'].includes(arg.text.slice(1, -1));
+    };
+    const collectPathBindings = () => {
+        if (pathBindings) return;
+        pathBindings = new Map();
+        const add = (pattern, value) => {
+            if (!pattern) return;
+            traverseTree(pattern, id => {
+                if (id.type === 'identifier' || id.type === 'shorthand_property_identifier_pattern') {
+                    const entries = pathBindings.get(id.text) || [];
+                    entries.push({ pattern, value });
+                    pathBindings.set(id.text, entries);
+                }
+                return true;
+            });
+        };
+        // File-wide ambiguity is deliberately conservative, including writes
+        // and parameters in unrelated scopes. This rare syntax needs proof,
+        // while ordinary literal require specifiers keep their existing path.
+        traverseTree(tree.rootNode, n => {
+            if (n.type === 'variable_declarator') add(n.childForFieldName('name'), n.childForFieldName('value'));
+            else if (n.type === 'formal_parameters' || n.type === 'import_clause') add(n, null);
+            else if (n.type === 'assignment_expression' || n.type === 'augmented_assignment_expression') add(n.childForFieldName('left'), null);
+            else if (n.type === 'update_expression') add(n.childForFieldName('argument'), null);
+            else if (n.type === 'class_declaration' || n.type === 'class') add(n.childForFieldName('name'), null);
+            else if (n.type === 'catch_clause') add(n.childForFieldName('parameter'), null);
+            else if (FUNCTION_LIKE.has(n.type)) {
+                add(n.childForFieldName('name'), null);
+                add(n.childForFieldName('parameter'), null); // unparenthesized arrow
+            }
+            return true;
+        });
+    };
+    const isPathUtility = fn => {
+        if (pathBindings.has('require')) return false;
+        if (fn?.type !== 'member_expression' ||
+            !['join', 'resolve'].includes(fn.childForFieldName('property')?.text)) return false;
+        const object = fn.childForFieldName('object');
+        if (isPathModuleCall(object)) return true;
+        if (object?.type !== 'identifier') return false;
+        const bindings = pathBindings.get(object.text) || [];
+        return bindings.length === 1 && bindings[0].pattern.type === 'identifier' &&
+            isPathModuleCall(bindings[0].value);
+    };
+    // Static composition of `__dirname`-rooted require paths (fix #337b).
+    // Returns a relative specifier ('./x' / '../x') or null when any piece is
+    // not a string literal.
+    const unquote = (n) => (n.type === 'string' &&
+        !n.namedChildren.some(child => child.type === 'escape_sequence') ? n.text.slice(1, -1) : null);
+    const staticDirnamePath = (arg) => {
+        collectPathBindings();
+        if (pathBindings.has('__dirname') || pathBindings.has('require')) return null;
+        let parts = null;
+        if (arg.type === 'call_expression') {
+            const fn = arg.childForFieldName('function');
+            if (!isPathUtility(fn)) return null;
+            const args = arg.childForFieldName('arguments');
+            if (!args || args.namedChildCount < 2) return null;
+            if (args.namedChild(0).type !== 'identifier' || args.namedChild(0).text !== '__dirname') return null;
+            parts = [];
+            for (let i = 1; i < args.namedChildCount; i++) {
+                const piece = unquote(args.namedChild(i));
+                if (piece == null || piece.startsWith('/')) return null;
+                parts.push(piece);
+            }
+        } else if (arg.type === 'binary_expression') {
+            const operands = [];
+            const flatten = (n) => {
+                if (n.type === 'binary_expression' && n.childForFieldName('operator')?.text === '+') {
+                    flatten(n.childForFieldName('left'));
+                    flatten(n.childForFieldName('right'));
+                } else operands.push(n);
+            };
+            flatten(arg);
+            if (operands.length < 2 || operands[0].type !== 'identifier' || operands[0].text !== '__dirname') return null;
+            let tail = '';
+            for (let i = 1; i < operands.length; i++) {
+                const piece = unquote(operands[i]);
+                if (piece == null) return null;
+                tail += piece;
+            }
+            if (!tail.startsWith('/')) return null;
+            parts = [tail.slice(1)];
+        } else if (arg.type === 'template_string') {
+            let tail = '';
+            let sawDirname = false;
+            for (let i = 0; i < arg.childCount; i++) {
+                const c = arg.child(i);
+                if (c.type === 'template_substitution') {
+                    if (sawDirname || c.namedChildCount !== 1 || c.namedChild(0).text !== '__dirname') return null;
+                    sawDirname = true;
+                } else if (c.type === 'string_fragment') {
+                    if (!sawDirname) return null;
+                    tail += c.text;
+                } else if (c.type !== '`') return null;
+            }
+            if (!sawDirname || !tail.startsWith('/')) return null;
+            parts = [tail.slice(1)];
+        }
+        if (!parts || parts.length === 0) return null;
+        const joined = parts.join('/').replace(/\\/g, '/');
+        if (!joined || joined.includes('${')) return null;
+        const normalized = require('path').posix.normalize(joined);
+        if (normalized.startsWith('/') || normalized === '.') return null;
+        return normalized.startsWith('.') ? normalized : `./${normalized}`;
+    };
+    const hasTypeKeyword = (node) => {
+        for (let i = 0; i < node.childCount; i++) {
+            if (node.child(i).type === 'type') return true;
+        }
+        return false;
+    };
+
     traverseTreeCached(tree.rootNode, (node) => {
         // ES6 import statements
         if (node.type === 'import_statement') {
@@ -3198,6 +3618,10 @@ function findImportsInCode(code, parser) {
             const names = [];
             const esmRenames = [];
             let importType = 'named';
+            let typeOnly = hasTypeKeyword(node);
+            let specifierCount = 0;
+            let typeSpecifierCount = 0;
+            let hasValueBinding = false;
 
             // Find the module path (string node)
             for (let i = 0; i < node.namedChildCount; i++) {
@@ -3218,7 +3642,8 @@ function findImportsInCode(code, parser) {
                         if (c.type === 'string') src = c.text.slice(1, -1);
                     }
                     if (src) {
-                        imports.push({ module: src, names: alias ? [alias] : [], type: 'require', line });
+                        imports.push({ module: src, names: alias ? [alias] : [], type: 'require', line,
+                            ...(typeOnly && { deferred: true, deferredReason: 'type-only' }) });
                     }
                     return true;
                 }
@@ -3230,6 +3655,7 @@ function findImportsInCode(code, parser) {
                             // Default import: import foo from 'x'
                             names.push(clauseChild.text);
                             importType = 'default';
+                            hasValueBinding = true;
                         } else if (clauseChild.type === 'named_imports') {
                             // Named imports: import { a, b } from 'x'
                             for (let k = 0; k < clauseChild.namedChildCount; k++) {
@@ -3237,6 +3663,8 @@ function findImportsInCode(code, parser) {
                                 if (specifier.type === 'import_specifier') {
                                     const nameNode = specifier.namedChild(0);
                                     const aliasNode = specifier.namedChild(1);
+                                    specifierCount++;
+                                    if (hasTypeKeyword(specifier)) typeSpecifierCount++;
                                     if (nameNode) names.push(nameNode.text);
                                     // Track renamed imports: import { X as Y }
                                     if (nameNode && aliasNode && aliasNode.text !== nameNode.text) {
@@ -3253,6 +3681,7 @@ function findImportsInCode(code, parser) {
                                           clauseChild.namedChild(0);
                             if (nsName) names.push(nsName.text);
                             importType = 'namespace';
+                            hasValueBinding = true;
                         }
                     }
                 }
@@ -3263,8 +3692,13 @@ function findImportsInCode(code, parser) {
                     // Side-effect import: import 'x'
                     importType = 'side-effect';
                 }
+                if (!typeOnly && specifierCount > 0 && typeSpecifierCount === specifierCount &&
+                    importType === 'named' && !hasValueBinding) {
+                    typeOnly = true;
+                }
                 imports.push({ module: modulePath, names, type: importType, line,
-                    ...(esmRenames.length > 0 && { renames: esmRenames }) });
+                    ...(esmRenames.length > 0 && { renames: esmRenames }),
+                    ...(typeOnly && { deferred: true, deferredReason: 'type-only' }) });
             }
             return true;
         }
@@ -3274,6 +3708,8 @@ function findImportsInCode(code, parser) {
         if (node.type === 'export_statement') {
             let source = null;
             const names = [];
+            let specifierCount = 0;
+            let typeSpecifierCount = 0;
 
             // Find the source module (string node with 'from')
             for (let i = 0; i < node.namedChildCount; i++) {
@@ -3285,6 +3721,8 @@ function findImportsInCode(code, parser) {
                     for (let j = 0; j < child.namedChildCount; j++) {
                         const specifier = child.namedChild(j);
                         if (specifier.type === 'export_specifier') {
+                            specifierCount++;
+                            if (hasTypeKeyword(specifier)) typeSpecifierCount++;
                             const nameNode = specifier.namedChild(0);
                             if (nameNode) names.push(nameNode.text);
                         }
@@ -3296,7 +3734,9 @@ function findImportsInCode(code, parser) {
                 const line = node.startPosition.row + 1;
                 const isStarReExport = node.text.includes('export *');
                 const importType = isStarReExport ? 'namespace' : 'named';
-                imports.push({ module: source, names, type: importType, line, isReExport: true });
+                imports.push({ module: source, names, type: importType, line, isReExport: true,
+                    ...((hasTypeKeyword(node) || (specifierCount > 0 && specifierCount === typeSpecifierCount)) &&
+                        { deferred: true, deferredReason: 'type-only' }) });
             }
             return true;
         }
@@ -3314,8 +3754,17 @@ function findImportsInCode(code, parser) {
                     let modulePath;
                     let dynamic = false;
 
+                    const composedPath = firstArg && firstArg.type !== 'string' ? staticDirnamePath(firstArg) : null;
                     if (firstArg && firstArg.type === 'string') {
                         modulePath = firstArg.text.slice(1, -1);
+                    } else if (composedPath) {
+                        // fix #337b: `require(path.join(__dirname, '..', 'x'))`,
+                        // `require(__dirname + '/x')`, `require(\`${__dirname}/x\`)`
+                        // compose to an exact relative specifier — the CJS
+                        // test-suite idiom that used to be an unresolvable
+                        // dynamic module (excluding every constructor call it
+                        // bound as other-definition-import).
+                        modulePath = composedPath;
                     } else {
                         dynamic = true;
                         modulePath = firstArg ? firstArg.text : null;
@@ -3357,7 +3806,9 @@ function findImportsInCode(code, parser) {
                     }
 
                     if (modulePath) {
+                        const deferral = importDeferral(node);
                         imports.push({ module: modulePath, names, type: 'require', line, dynamic,
+                            ...(deferral && { deferred: true, deferredReason: deferral }),
                             ...(defaultLike && { defaultLike: true }),
                             // Per-import rename pairing (fix #269): the flat
                             // importAliases list loses WHICH module a renamed
@@ -3375,11 +3826,15 @@ function findImportsInCode(code, parser) {
                 if (argsNode && argsNode.namedChildCount > 0) {
                     const firstArg = argsNode.namedChild(0);
                     const line = node.startPosition.row + 1;
+                    const deferral = importDeferral(node);
+                    const deferredFields = deferral ? { deferred: true, deferredReason: deferral } : {};
                     if (firstArg && firstArg.type === 'string') {
                         const modulePath = firstArg.text.slice(1, -1);
-                        imports.push({ module: modulePath, names: [], type: 'dynamic', line, dynamic: false });
+                        imports.push({ module: modulePath, names: [], type: 'dynamic', line, dynamic: false,
+                            ...deferredFields });
                     } else if (firstArg) {
-                        imports.push({ module: firstArg.text, names: [], type: 'dynamic', line, dynamic: true });
+                        imports.push({ module: firstArg.text, names: [], type: 'dynamic', line, dynamic: true,
+                            ...deferredFields });
                     }
                 }
             }