feat: hoisting and tdz.

Author: knightedcodemonkey

docs/hoisting-tdz.md

@@ -0,0 +1,21 @@
+# Hoisting and TDZ in identifier tracking
+
+## Purpose
+
+This library tracks module-scope identifiers so CJS↔ESM lowering can avoid collisions and emit correct exports/imports. We model only hoisting behaviors that affect module-scope resolution and skip cases that either error at runtime or are handled by the module loader.
+
+## What we treat as hoisted
+
+- `function` declarations at module scope: reads before the declaration are counted.
+- `var` declarations at module scope: reads before the declaration are counted (value is `undefined`).
+
+## What we do not hoist
+
+- `let` / `const` / `class`: reads in the temporal dead zone are ignored for hoist accounting (they are runtime errors). See fixtures/tests under `test/fixtures/identifiers/hoisting/tdz.js`.
+- `import` bindings: import hoisting is handled by the module system; we exclude imports from module-scope hoist tracking. See `test/fixtures/identifiers/hoisting/importHoist.js`.
+- Function declarations inside blocks (strict mode): they stay block-scoped and are not treated as module-scope hoists. See `test/fixtures/identifiers/hoisting/functionInBlock.js`.
+
+## Why this scope
+
+- Our goal is collision-free lowering, not simulating all JS runtime hoisting/TDZ behavior.
+- Excluding TDZ and import hoists keeps the identifier table focused on cases that meaningfully affect CJS↔ESM transforms.

src/utils.ts

@@ -276,6 +276,14 @@ const collectModuleIdentifiers = async (ast: Node, hoisting: boolean = true) =>
           const isVarDeclarationInGlobalScope =
             identifier.isVarDeclarationInGlobalScope(ancestors)
 
+          const parent = ancestors[ancestors.length - 2]
+          const grandParent = ancestors[ancestors.length - 3]
+          const hoistSafe =
+            parent.type === 'FunctionDeclaration' ||
+            (parent.type === 'VariableDeclarator' &&
+              grandParent?.type === 'VariableDeclaration' &&
+              grandParent.kind === 'var')
+
           if (
             isModuleScope ||
             isClassOrFuncDeclaration ||
@@ -284,7 +292,7 @@ const collectModuleIdentifiers = async (ast: Node, hoisting: boolean = true) =>
             meta.declare.push(node)
 
             // Check for hoisted reads
-            if (hoisting && globalReads.has(name)) {
+            if (hoisting && hoistSafe && globalReads.has(name)) {
               const reads = globalReads.get(name)
 
               if (reads) {

src/utils/identifiers.ts

@@ -155,6 +155,14 @@ const collectModuleIdentifiers = async (ast: Node, hoisting: boolean = true) =>
           const isVarDeclarationInGlobalScope =
             identifier.isVarDeclarationInGlobalScope(ancestors)
 
+          const parent = ancestors[ancestors.length - 2]
+          const grandParent = ancestors[ancestors.length - 3]
+          const hoistSafe =
+            parent.type === 'FunctionDeclaration' ||
+            (parent.type === 'VariableDeclarator' &&
+              grandParent?.type === 'VariableDeclaration' &&
+              grandParent.kind === 'var')
+
           if (
             isModuleScope ||
             isClassOrFuncDeclaration ||
@@ -163,7 +171,7 @@ const collectModuleIdentifiers = async (ast: Node, hoisting: boolean = true) =>
             meta.declare.push(node)
 
             // Check for hoisted reads
-            if (hoisting && globalReads.has(name)) {
+            if (hoisting && hoistSafe && globalReads.has(name)) {
               const reads = globalReads.get(name)
 
               if (reads) {

test/fixtures/identifiers/hoisting/functionInBlock.js

@@ -0,0 +1,11 @@
+// In strict mode, function declarations inside blocks are block-scoped and not hoisted
+// to the outer scope. Ensure we don't count reads before the declaration as hoisted.
+
+{
+  func()
+  function func() {
+    return 'block-func'
+  }
+}
+
+export {}

test/fixtures/identifiers/hoisting/importHoist.js

@@ -0,0 +1,9 @@
+// Imports are hoisted by the module system, but we do not treat them as part of
+// the module-scope identifier hoisting for collision/reads accounting.
+
+import { x } from './importHoistDep.js'
+
+const a = x
+const b = (() => x)()
+
+export { a, b }

test/fixtures/identifiers/hoisting/importHoistDep.js

@@ -0,0 +1 @@
+export const x = 'import-hoist'

test/fixtures/identifiers/hoisting/tdz.js

@@ -0,0 +1,46 @@
+// These TDZ reads would throw at runtime; we should not count them as safe hoists.
+// Access before declaration (let/const/class) remains in the TDZ.
+
+// let
+const a = (() => {
+  try {
+    return foo
+  } catch {
+    return 'tdz'
+  }
+})()
+let foo = 'foo'
+
+// const
+const b = (() => {
+  try {
+    return bar
+  } catch {
+    return 'tdz'
+  }
+})()
+const bar = 'bar'
+
+// class
+const c = (() => {
+  try {
+    return Baz
+  } catch {
+    return 'tdz'
+  }
+})()
+class Baz {}
+
+// nested block TDZ
+{
+  const d = (() => {
+    try {
+      return inner
+    } catch {
+      return 'tdz'
+    }
+  })()
+  const inner = 'inner'
+}
+
+export { a, b, c }

test/utils.ts

@@ -138,4 +138,56 @@ describe('collectModuleIdentifiers', () => {
     assert.deepEqual(innerBlockVarReads, [427])
     assert.deepEqual(catchVarReads, [536])
   })
+
+  it('does not treat TDZ reads (let/const/class) as hoists', async () => {
+    const fixturePath = join(fixtures, 'identifiers', 'hoisting', 'tdz.js')
+    const code = await readFile(fixturePath)
+    const ast = parse('file.ts', code.toString())
+    const idents = await collectModuleIdentifiers(ast.program, true)
+    const { status } = spawnSync('node', [fixturePath], { stdio: 'inherit' })
+
+    // Test for valid syntax
+    assert.equal(status, 0)
+
+    // TDZ reads should not be recorded as safe hoists; they should be absent or zero reads.
+    assert.equal(idents.get('foo')?.read.length ?? 0, 0)
+    assert.equal(idents.get('bar')?.read.length ?? 0, 0)
+    assert.equal(idents.get('Baz')?.read.length ?? 0, 0)
+    assert.equal(idents.get('inner')?.read.length ?? 0, 0)
+  })
+
+  it('ignores import hoisting for identifier tracking', async () => {
+    const fixturePath = join(fixtures, 'identifiers', 'hoisting', 'importHoist.js')
+    const code = await readFile(fixturePath)
+    const ast = parse('file.ts', code.toString())
+    const idents = await collectModuleIdentifiers(ast.program, true)
+    const { status } = spawnSync('node', [fixturePath], { stdio: 'inherit' })
+
+    // Test for valid syntax
+    assert.equal(status, 0)
+
+    // Imported names should not be counted as module-scope hoists
+    assert.equal(idents.has('x'), false)
+
+    // Local reads of imported value still exist via binding 'x' inside the module
+    // but they should not appear in module hoist tracking because x is not declared locally.
+  })
+
+  it('does not hoist function declarations inside blocks to module scope', async () => {
+    const fixturePath = join(fixtures, 'identifiers', 'hoisting', 'functionInBlock.js')
+    const code = await readFile(fixturePath)
+    const ast = parse('file.ts', code.toString())
+    const idents = await collectModuleIdentifiers(ast.program, true)
+    const funcReads: number[] = []
+    const { status } = spawnSync('node', [fixturePath], { stdio: 'inherit' })
+
+    // Test for valid syntax
+    assert.equal(status, 0)
+
+    const funcMeta = idents.get('func')
+    assert.equal(funcMeta, undefined)
+
+    // Ensure no reads got captured as module-scope hoists
+    assert.deepEqual(funcReads, [])
+  })
 })