fix(compile): fall back to compiled JS emit for TS namespace/export= declaration merges

changelog.d/10673-namespace-export-equals-fallback.md

@@ -0,0 +1,17 @@
+Fixed `axios` (and any `perry.compilePackages` target with a similar shape)
+throwing `TypeError: Class extends value is not a constructor` at
+module-init time. The blocker was in the `https-proxy-agent` -> `agent-base`
+dependency chain: `agent-base`'s TypeScript source merges `namespace
+createAgent { export class Agent extends EventEmitter { ... } }` onto a
+same-named `function createAgent()` and exports it with `export =` —
+Perry's HIR doesn't correctly attach the namespace's exported members to
+the same runtime value `export =` ends up exporting, so
+`require("agent-base").Agent` read back as `undefined` and the downstream
+`class HttpsProxyAgent extends agent_base_1.Agent` threw. Perry's
+`compilePackages` module resolution now detects this TS
+namespace/function-merge + `export =` shape and falls back to the
+package's compiled JS emit instead of its raw `.ts` source — the same file
+Node itself runs, since `--experimental-strip-types` can't execute raw
+`namespace`/`export =` syntax either. Extends the existing #6586
+ESM+CJS-epilogue fallback in `is_hybrid_cjs_emit_input` with a second,
+narrowly-scoped trigger; not keyed on the `agent-base` package name.

crates/perry/src/commands/compile/cjs_wrap/detect.rs

@@ -458,6 +458,58 @@ pub(in crate::commands::compile) fn has_top_level_module_exports_assignment(sour
     false
 }
 
+/// Returns true if `source` (expected to already be comment/string-stripped
+/// via [`strip_comments_and_strings`]) contains a top-level TypeScript
+/// `namespace X { … }` / legacy `module X { … }` declaration with a REAL
+/// (non-ambient) body — i.e. NOT `declare namespace X { … }`, which is
+/// type-only and never emits runtime code, so it can't be the cause of a
+/// namespace/function declaration-merge going missing at runtime.
+///
+/// Line-anchored rather than depth-tracked, unlike [`has_top_level_esm`]: a
+/// `namespace`/`module` block is hand-authored (or `tsc`-emitted) TypeScript
+/// source, never a minified bundle, so it is always written starting its own
+/// line. Requiring the `{` to follow the (possibly dotted) namespace name on
+/// the SAME statement, with only whitespace/dots in between, keeps this from
+/// matching ordinary CommonJS `module.exports = { … }` — there `module` is
+/// followed immediately by `.`, never by whitespace then an identifier.
+///
+/// Used together with [`has_top_level_export_equals`] (#10662): a package
+/// like `agent-base` merges `namespace createAgent { export class Agent
+/// extends EventEmitter { … } }` onto a same-named `function createAgent()`
+/// and exports the merged value via `export = createAgent`. Perry's HIR
+/// lowers the namespace's exported members as static-field-set init
+/// statements against a synthetic class entity that does not end up being
+/// the SAME runtime object `export =` exports — so a downstream `class X
+/// extends pkg.Agent` sees `pkg.Agent` as `undefined` and throws "Class
+/// extends value is not a constructor" (axios's `https-proxy-agent` →
+/// `agent-base` dependency chain). Node can't run this non-erasable TS
+/// syntax directly either (`--experimental-strip-types` rejects `namespace`/
+/// `export =`), so a package built this way is NEVER executed from its raw
+/// `.ts` source in practice — only via its compiled emit. Detecting the
+/// shape and falling back to that emit (see `is_hybrid_cjs_emit_input` in
+/// `resolve.rs`) matches what Node actually runs, instead of attempting to
+/// correctly implement namespace/function declaration merging.
+pub(in crate::commands::compile) fn has_top_level_namespace_or_module_block(source: &str) -> bool {
+    let re = perry_perex::tooling::Regex::new(
+        r"(?m)^[ \t]*(declare\s+)?(?:export\s+)?(?:namespace|module)\s+[A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*\s*\{",
+    )
+    .expect("valid namespace/module regex");
+    re.captures_iter(source).any(|cap| cap.get(1).is_none())
+}
+
+/// Returns true if `source` (comment/string-stripped) contains a top-level
+/// TypeScript `export = <expr>;` statement — the CJS-interop export form a
+/// namespace-merged package like `agent-base` uses instead of `module.exports
+/// = …` (see [`has_top_level_namespace_or_module_block`], #10662). The
+/// trailing character class excludes `export ==`/`export =>`; neither is
+/// valid syntax here, but the exclusion costs nothing and avoids relying on
+/// lookahead, which the `regex` crate doesn't support.
+pub(in crate::commands::compile) fn has_top_level_export_equals(source: &str) -> bool {
+    let re = perry_perex::tooling::Regex::new(r"(?m)^[ \t]*export\s*=[\s\w$(\[{]")
+        .expect("valid export= regex");
+    re.is_match(source)
+}
+
 /// Returns true if `line` starts with `keyword` followed by a character
 /// that can legally begin an `import`/`export` statement's continuation:
 /// space, `{`, `*` (export only), `"`, `'`, or `(` (dynamic import). We

crates/perry/src/commands/compile/cjs_wrap/issue_10662_tests.rs

@@ -0,0 +1,101 @@
+//! Regression tests for #10662: `agent-base`'s TypeScript `namespace
+//! createAgent { export class Agent extends EventEmitter { … } } export =
+//! createAgent;` — a `function createAgent()` merged with a namespace of the
+//! same name, exported via TS's `export =` form. Perry's HIR lowers the
+//! namespace's exported `Agent` class as a static-field-set against a
+//! synthetic class entity distinct from the runtime function value
+//! `export =` actually exports, so a downstream `https-proxy-agent extends
+//! agent_base_1.Agent` (an `axios` transitive dependency) sees `.Agent` as
+//! `undefined` and throws "Class extends value is not a constructor".
+//!
+//! `has_top_level_namespace_or_module_block` /
+//! `has_top_level_export_equals` detect this shape so
+//! `is_hybrid_cjs_emit_input` (`resolve.rs`) can fall back to the package's
+//! compiled JS emit — the same emit Node itself runs, since
+//! `--experimental-strip-types` can't execute raw `namespace`/`export =`
+//! syntax either.
+
+use super::detect::{
+    has_top_level_export_equals, has_top_level_namespace_or_module_block,
+    strip_comments_and_strings,
+};
+
+#[test]
+fn namespace_block_detects_the_agent_base_shape() {
+    let src = strip_comments_and_strings(
+        "function createAgent(opts) {\n  return new createAgent.Agent(opts);\n}\n\nnamespace createAgent {\n  export class Agent extends EventEmitter {}\n}\n\nexport = createAgent;\n",
+    );
+    assert!(has_top_level_namespace_or_module_block(&src));
+    assert!(has_top_level_export_equals(&src));
+}
+
+#[test]
+fn namespace_block_accepts_legacy_module_keyword_and_dotted_names() {
+    let src = strip_comments_and_strings("module Foo.Bar {\n  export const x = 1;\n}\n");
+    assert!(has_top_level_namespace_or_module_block(&src));
+}
+
+#[test]
+fn ambient_declare_namespace_is_not_flagged() {
+    // `declare namespace X { … }` is type-only — it never emits runtime
+    // code, so it cannot be the cause of a namespace/function merge going
+    // missing at runtime, and must not trigger the JS-emit fallback.
+    let src = strip_comments_and_strings(
+        "declare namespace createAgent {\n  export class Agent {}\n}\nexport = createAgent;\n",
+    );
+    assert!(!has_top_level_namespace_or_module_block(&src));
+}
+
+#[test]
+fn ordinary_cjs_module_exports_object_literal_is_not_flagged() {
+    // `module.exports = { … }` is the single most common CommonJS shape —
+    // `module` is followed by `.`, never by whitespace then an identifier,
+    // so it must never be mistaken for a `namespace`/`module X {` block.
+    let src = strip_comments_and_strings(
+        "function build() { return 1; }\nmodule.exports = { build: build, value: 42 };\n",
+    );
+    assert!(!has_top_level_namespace_or_module_block(&src));
+}
+
+#[test]
+fn export_equals_matches_the_export_equals_form_only() {
+    assert!(has_top_level_export_equals(&strip_comments_and_strings(
+        "export = createAgent;\n"
+    )));
+    assert!(has_top_level_export_equals(&strip_comments_and_strings(
+        "export=createAgent;\n"
+    )));
+
+    // Ordinary ESM export forms must not match — none of these are the
+    // CJS-interop `export =` shape.
+    assert!(!has_top_level_export_equals(&strip_comments_and_strings(
+        "export const x = 1;\n"
+    )));
+    assert!(!has_top_level_export_equals(&strip_comments_and_strings(
+        "export class Foo {}\n"
+    )));
+    assert!(!has_top_level_export_equals(&strip_comments_and_strings(
+        "export default Foo;\n"
+    )));
+    assert!(!has_top_level_export_equals(&strip_comments_and_strings(
+        "export { Foo };\n"
+    )));
+}
+
+#[test]
+fn plain_esm_or_cjs_source_without_the_merge_shape_is_unaffected() {
+    // A normal ESM file with a class extending an imported native builtin —
+    // the overwhelmingly common case — must not be flagged: no namespace
+    // block, no `export =`.
+    let esm = strip_comments_and_strings(
+        "import { EventEmitter } from 'events';\nexport class Agent extends EventEmitter {}\n",
+    );
+    assert!(!has_top_level_namespace_or_module_block(&esm));
+    assert!(!has_top_level_export_equals(&esm));
+
+    // A normal CJS file.
+    let cjs =
+        strip_comments_and_strings("'use strict';\nclass Agent {}\nmodule.exports = { Agent };\n");
+    assert!(!has_top_level_namespace_or_module_block(&cjs));
+    assert!(!has_top_level_export_equals(&cjs));
+}

crates/perry/src/commands/compile/cjs_wrap/mod.rs

@@ -43,6 +43,8 @@ mod extract_requires;
 mod hoist_classes;
 mod wrap;
 
+#[cfg(test)]
+mod issue_10662_tests;
 #[cfg(test)]
 mod issue_6585_tests;
 #[cfg(test)]

crates/perry/src/commands/compile/resolve.rs

@@ -767,13 +767,29 @@ fn original_source_via_map(entry: &Path) -> Option<PathBuf> {
     original_source_from_map_file(&append_map_extension(entry))
 }
 
-/// A published CommonJS package can ship the TypeScript input to its CJS emit.
-/// Some such inputs are intentionally hybrid: normal ESM declarations for
-/// TypeScript plus a top-level `module.exports = ...` interop epilogue. The
-/// source is not a directly executable module in Perry: ESM classification
-/// leaves `module` unbound, while CJS wrapping would move its `export`
-/// declarations inside an IIFE. Node loads the emitted JS entry, so keep that
-/// entry instead of following its source map for this narrow shape (#6586).
+/// A published CommonJS package can ship a TypeScript input that is not
+/// directly executable as a Perry module, in which case Perry should keep
+/// the package on its compiled JS emit instead of the raw source (matching
+/// what Node actually runs) rather than following a source map / `src/`
+/// convention to that source. Two known shapes trigger this, both narrow and
+/// evidence-driven rather than a general "prefer JS" default:
+///
+/// - **ESM-plus-CJS-epilogue hybrid** (#6586): normal ESM declarations for
+///   TypeScript plus a top-level `module.exports = ...` interop epilogue.
+///   ESM classification leaves `module` unbound, while CJS wrapping would
+///   move its `export` declarations inside an IIFE — neither executes.
+/// - **Namespace/function declaration merging via `export =`** (#10662):
+///   `namespace X { export class Y extends Z {} }` merged onto a same-named
+///   `function X() {}` and exported with `export = X` — the shape
+///   `agent-base` (an `axios` → `https-proxy-agent` transitive dependency)
+///   uses. Perry's HIR lowers the namespace's exported members as static
+///   fields against a synthetic class entity that is not the SAME runtime
+///   value `export =` ends up exporting, so e.g. `pkg.Agent` reads back as
+///   `undefined` and a downstream `class X extends pkg.Agent` throws "Class
+///   extends value is not a constructor". Node can't run this non-erasable
+///   TS syntax directly either (`--experimental-strip-types` rejects
+///   `namespace`/`export =`), so such a package is never executed from its
+///   raw `.ts` source in practice — only via its compiled emit.
 fn is_hybrid_cjs_emit_input(path: &Path) -> bool {
     static CACHE: OnceLock<Mutex<HashMap<PathBuf, bool>>> = OnceLock::new();
 
@@ -789,8 +805,10 @@ fn is_hybrid_cjs_emit_input(path: &Path) -> bool {
         return false;
     };
     let stripped = super::cjs_wrap::detect::strip_comments_and_strings(&source);
-    let hybrid = super::cjs_wrap::detect::has_top_level_esm(&stripped)
-        && super::cjs_wrap::detect::has_top_level_module_exports_assignment(&stripped);
+    let hybrid = (super::cjs_wrap::detect::has_top_level_esm(&stripped)
+        && super::cjs_wrap::detect::has_top_level_module_exports_assignment(&stripped))
+        || (super::cjs_wrap::detect::has_top_level_namespace_or_module_block(&stripped)
+            && super::cjs_wrap::detect::has_top_level_export_equals(&stripped));
     cache
         .lock()
         .expect("hybrid source cache")