feat(dynamic-import): resolve variable/computed specifiers via type-narrowing + directory glob

[proggeramlug]

Summary

A dynamic import() whose specifier is a runtime variable or computed value — import(path) where path is a function parameter or non-const local — is a hard compile error today. Because Perry is AOT and closed-world (the full module universe is known at collect_modules time), we can resolve a finite candidate set in many cases instead of erroring.

Real-world drivers are tooling-side: config-file loading (await import(resolvedConfigPath) — Vite, ESLint flat config, Jest, Drizzle Kit, tsx) and plugin/adapter-by-name from user config (await import(userConfig.adapter), import(`@scope/${name}`) — Vite/Rollup/PostCSS/unplugin). Lower priority than the literal bare-specifier / node:-builtin tier, but needed to run modern tooling natively.

Background

crates/perry-hir/src/dynamic_import.rs:560 (resolve_import_path_with_consts) currently resolves: string literals, ternaries, template literals over const interpolations, and module-level const locals. Anything else returns Resolution::Unresolved, which the driver turns into a compile error. The downstream multi-target dispatch (dyn_extern_i18n.rs) already consumes a Vec<String> and emits an N-way js_string_equals chain, so widening the resolver requires no new runtime or codegen for the type-narrowing path.

Proposed approach (two sub-parts, can ship independently)

A. Type/flow narrowing. Resolve a finite candidate set from static info already available:

• String-literal union types: path: './a.ts' | './b.ts' → enumerate the union.
• Finite reaching-definitions: a non-const local assigned only literals across the function → union those. (scan_mutations_expr, dynamic_import.rs:517, already tracks which locals are mutated; invert it to collect assigned values.)

B. Glob / context-module scoping (Vite import.meta.glob style). When a template literal has a non-const interpolation but fixed prefix/suffix, treat ${var} as a wildcard and glob <prefix>*<suffix> against the discovered module universe at collect_modules time. The existing DYNAMIC_IMPORT_PATH_CAP (64) bounds the candidate set.

Cross-cutting concerns

• Path canonicalization. Once candidates come from globbing or runtime variables, the runtime arg string must match a compile-time key exactly. Apply one normalization function to both the keys (build time) and the runtime arg (dispatch): extension resolution (./foo → ./foo.ts), index resolution, ./ vs absolute. This is the most likely source of "compiled fine but silently rejects" bugs.
• Miss semantics. No-match → rejected promise (current fallthrough), which matches Node. Optionally offer a compile-time exhaustiveness mode for provably-covered union-typed args that skips the reject branch.
• Retention. Every candidate module must survive dead-stripping (cf. #[used] / auto-optimize interaction). The is_dynamic edge handles graph inclusion; verify the namespace global isn't stripped when its only reference is a runtime string compare.

Acceptance criteria

• let p = cond ? './a.ts' : './b.ts'; await import(p) (non-const local) resolves both targets — type/flow narrowing.
• await import(`./plugins/${name}.ts`) with non-const name resolves to all matching files under ./plugins/ — glob.
• Unresolvable-and-unbounded specifiers still produce a clear compile error (no silent whole-program retention).
• Canonicalization covered by tests for ./foo vs ./foo.ts vs absolute.

Files

• crates/perry-hir/src/dynamic_import.rs:560 (resolver)
• crates/perry/src/commands/compile/collect_modules.rs:465-548 (glob cross-ref against module universe; cap enforcement)

Part of the dynamic-import Node.js-compatibility series (variable/computed-specifier tier — lower priority than the literal tier).

[proggeramlug]

Dynamic-import Node.js-compatibility series:

• feat(dynamic-import): resolve literal bare-specifier import('pkg') via compilePackages #1672 — literal bare npm specifier via compilePackages (Tier 1)
• feat(dynamic-import): resolve literal node: builtin import('node:crypto') to native namespace #1673 — literal node: builtin → native namespace (Tier 1)
• feat(dynamic-import): resolve variable/computed specifiers via type-narrowing + directory glob #1674 — variable/computed specifiers via type-narrowing + glob (Tier 3)

Recommended order: #1672 and #1673 first (highest Node-compat leverage, literal specifiers — the head of real-world usage), then #1674 (tooling-side tail).

[andrewtdiz]

Taking a focused first implementation slice for this dynamic-import tracker.

Planned PR scope: resolve dynamic import(specifier) when specifier is a non-const local whose initializer already reduces to a finite literal candidate set, for example let p = cond ? "./a.ts" : "./b.ts"; await import(p). This uses the existing multi-candidate dynamic import dispatch path rather than adding new runtime/codegen machinery.

Non-goals for this cut: template-glob/context-module expansion, function-parameter type narrowing, reaching-definition analysis across later assignments, and broader path canonicalization beyond the current dynamic import resolver behavior.

[andrewtdiz]

Opened draft PR #4281 for the focused local-candidate coverage slice: #4281

Current main already has resolver support for this #1674 subcase, so this PR adds end-to-end parity coverage rather than changing compiler code.

Scope covered:

• let specifier = flag ? "./a" : "./b"; await import(specifier) inside a function
• transitive template-literal local candidates (let name = flag ? "a" : "b"; let specifier = ./dynamic-${name}.ts``)
• both dispatch branches exercised through tiny fixture target modules

Validation passed:

• Node 26 oracle for the new fixture
• release build for perry, perry-runtime, and perry-stdlib with single-job build to fit current disk/memory constraints
• direct Perry run of the new fixture matching Node output
• focused module parity filter dynamic-import-local-candidates (1/1 pass)
• adjacent module parity filter dynamic-import (2/2 pass)
• cargo fmt --all -- --check
• git diff --check
• ./scripts/check_file_size.sh

Still out of scope for this PR: glob/context-module wildcard expansion, function-parameter type narrowing, and reaching-definition analysis across later assignments.

[andrewtdiz]

Taking the follow-up #1674 glob/context-module coverage slice.

Planned scope: add an end-to-end parity fixture for a runtime variable inside a fixed relative template specifier, e.g. await import(./fixtures/dynamic-glob/${name}.ts), where Perry should enumerate matching files in that directory and dispatch to the requested module at runtime.

Non-goals: compiler/runtime refactors unless the fixture exposes a failure, package/bare-specifier wildcard imports, unbounded project-wide globs, and type-narrowing for function parameters outside the existing directory-scoped glob behavior.