@knighted/module 1.0.0-beta.4 → 1.0.0-rc.0

package/README.md

@@ -133,6 +133,7 @@ Behavior notes (defaults in parentheses)
 - `requireSource` (`builtin`): whether `require` comes from Node or `createRequire`.
 - `cjsDefault` (`auto`): bundler-style default interop vs direct `module.exports`.
 - `out`/`inPlace`: write the transformed code to a file; otherwise the function returns the transformed string only.
+- CommonJS → ESM lowering will throw on `with` statements and unshadowed `eval` calls to avoid unsound rewrites.
 
 See [docs/esm-to-cjs.md](docs/esm-to-cjs.md) for deeper notes on live bindings, interop helpers, top-level await behavior, and `import.meta.main` handling. For CommonJS to ESM lowering details, read [docs/cjs-to-esm.md](docs/cjs-to-esm.md).
 
@@ -141,3 +142,4 @@ See [docs/esm-to-cjs.md](docs/esm-to-cjs.md) for deeper notes on live bindings,
 - Remove `@knighted/specifier` and avoid double parsing.
 - Emit source maps and clearer diagnostics for transform choices.
 - Broaden fixtures covering live-binding and top-level await edge cases across Node versions.
+- Benchmark scope analysis choices: compare `periscopic`, `scope-analyzer`, and `eslint-scope` on fixtures and pick the final adapter.

package/dist/assignmentExpression.d.cts

@@ -0,0 +1,12 @@
+import MagicString from 'magic-string';
+import type { Node, AssignmentExpression } from 'oxc-parser';
+import type { FormatterOptions, ExportsMeta } from '../types.cjs';
+type AssignmentExpressionArg = {
+    node: AssignmentExpression;
+    parent: Node | null;
+    code: MagicString;
+    opts: FormatterOptions;
+    meta: ExportsMeta;
+};
+export declare const assignmentExpression: ({ node, parent: _parent, code: _code, opts, meta: _meta, }: AssignmentExpressionArg) => Promise<void>;
+export {};

package/dist/cjs/format.cjs

@@ -382,6 +382,12 @@ const format = async (src, ast, opts) => {
           }
         }
       }
+      if (shouldRaiseEsm && node.type === 'WithStatement') {
+        throw new Error('Cannot transform to ESM: with statements are not supported.');
+      }
+      if (shouldRaiseEsm && node.type === 'CallExpression' && node.callee.type === 'Identifier' && node.callee.name === 'eval' && !shadowedBindings.has('eval')) {
+        throw new Error('Cannot transform to ESM: eval is not supported.');
+      }
       if (shouldRaiseEsm && node.type === 'CallExpression' && isRequireCall(node, shadowedBindings)) {
         const isStatic = isStaticRequire(node, shadowedBindings);
         const parent = ancestors[ancestors.length - 2] ?? null;

package/dist/cjs/helpers/scope.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.scopes = exports.scope = void 0;
+const scopes = exports.scopes = ['BlockStatement', 'FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression', 'ClassDeclaration', 'ClassExpression', 'ClassBody', 'StaticBlock'];
+const scope = exports.scope = {
+  isScope(node) {
+    return scopes.includes(node.type);
+  }
+};

package/dist/cjs/scope.d.cts

@@ -0,0 +1,6 @@
+import type { Node } from 'oxc-parser';
+declare const scopes: string[];
+declare const scope: {
+    isScope(node: Node): boolean;
+};
+export { scopes, scope };

package/dist/cjs/utils/identifiers.cjs

@@ -152,11 +152,14 @@ const collectModuleIdentifiers = async (ast, hoisting = true) => {
           const isModuleScope = _identifier.identifier.isModuleScope(ancestors);
           const isClassOrFuncDeclaration = _identifier.identifier.isClassOrFuncDeclarationId(ancestors);
           const isVarDeclarationInGlobalScope = _identifier.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 || isVarDeclarationInGlobalScope) {
             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) {
                 reads.forEach(read => {

package/dist/cjs/utils/lang.cjs

@@ -8,11 +8,11 @@ var _nodePath = require("node:path");
 // Determine language from filename extension for specifier rewrite.
 
 const getLangFromExt = filename => {
-  const ext = (0, _nodePath.extname)(filename);
-  if (ext.endsWith('.js')) {
+  const ext = (0, _nodePath.extname)(filename).toLowerCase();
+  if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
     return 'js';
   }
-  if (ext.endsWith('.ts')) {
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
     return 'ts';
   }
   if (ext === '.tsx') {

package/dist/cjs/utils.cjs

@@ -9,11 +9,11 @@ var _walk = require("./walk.cjs");
 var _identifier = require("./helpers/identifier.cjs");
 var _scopeNodes = require("./utils/scopeNodes.cjs");
 const getLangFromExt = filename => {
-  const ext = (0, _nodePath.extname)(filename);
-  if (ext.endsWith('.js')) {
+  const ext = (0, _nodePath.extname)(filename).toLowerCase();
+  if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
     return 'js';
   }
-  if (ext.endsWith('.ts')) {
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
     return 'ts';
   }
   if (ext === '.tsx') {
@@ -250,11 +250,14 @@ const collectModuleIdentifiers = async (ast, hoisting = true) => {
           const isModuleScope = _identifier.identifier.isModuleScope(ancestors);
           const isClassOrFuncDeclaration = _identifier.identifier.isClassOrFuncDeclarationId(ancestors);
           const isVarDeclarationInGlobalScope = _identifier.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 || isVarDeclarationInGlobalScope) {
             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) {
                 reads.forEach(read => {

package/dist/exports.d.cts

@@ -0,0 +1,6 @@
+import type { Node } from 'oxc-parser';
+import type { CjsExport } from '../types.cjs';
+declare const exportsRename = "__exports";
+declare const requireMainRgx: RegExp;
+declare const collectCjsExports: (ast: Node) => Promise<Map<string, CjsExport>>;
+export { exportsRename, requireMainRgx, collectCjsExports };

package/dist/expressionStatement.d.cts

@@ -0,0 +1,4 @@
+import MagicString from 'magic-string';
+import type { Node, ExpressionStatement } from 'oxc-parser';
+import type { FormatterOptions } from '../types.cjs';
+export declare const expressionStatement: (node: ExpressionStatement, parent: Node | null, src: MagicString, options: FormatterOptions) => void;

package/dist/format.d.cts

@@ -0,0 +1,9 @@
+import type { ParseResult } from 'oxc-parser';
+import type { FormatterOptions } from './types.cjs';
+/**
+ * Node added support for import.meta.main.
+ * Added in: v24.2.0, v22.18.0
+ * @see https://nodejs.org/api/esm.html#importmetamain
+ */
+declare const format: (src: string, ast: ParseResult, opts: FormatterOptions) => Promise<string>;
+export { format };

package/dist/format.js

@@ -375,6 +375,12 @@ const format = async (src, ast, opts) => {
           }
         }
       }
+      if (shouldRaiseEsm && node.type === 'WithStatement') {
+        throw new Error('Cannot transform to ESM: with statements are not supported.');
+      }
+      if (shouldRaiseEsm && node.type === 'CallExpression' && node.callee.type === 'Identifier' && node.callee.name === 'eval' && !shadowedBindings.has('eval')) {
+        throw new Error('Cannot transform to ESM: eval is not supported.');
+      }
       if (shouldRaiseEsm && node.type === 'CallExpression' && isRequireCall(node, shadowedBindings)) {
         const isStatic = isStaticRequire(node, shadowedBindings);
         const parent = ancestors[ancestors.length - 2] ?? null;

package/dist/formatters/assignmentExpression.d.ts

@@ -0,0 +1,12 @@
+import MagicString from 'magic-string';
+import type { Node, AssignmentExpression } from 'oxc-parser';
+import type { FormatterOptions, ExportsMeta } from '../types.js';
+type AssignmentExpressionArg = {
+    node: AssignmentExpression;
+    parent: Node | null;
+    code: MagicString;
+    opts: FormatterOptions;
+    meta: ExportsMeta;
+};
+export declare const assignmentExpression: ({ node, parent: _parent, code: _code, opts, meta: _meta, }: AssignmentExpressionArg) => Promise<void>;
+export {};

package/dist/formatters/expressionStatement.d.ts

@@ -0,0 +1,4 @@
+import MagicString from 'magic-string';
+import type { Node, ExpressionStatement } from 'oxc-parser';
+import type { FormatterOptions } from '../types.js';
+export declare const expressionStatement: (node: ExpressionStatement, parent: Node | null, src: MagicString, options: FormatterOptions) => void;

package/dist/formatters/identifier.d.ts

@@ -0,0 +1,12 @@
+import MagicString from 'magic-string';
+import type { Node, IdentifierName } from 'oxc-parser';
+import type { FormatterOptions, ExportsMeta } from '../types.js';
+type IdentifierArg = {
+    node: IdentifierName;
+    ancestors: Node[];
+    code: MagicString;
+    opts: FormatterOptions;
+    meta: ExportsMeta;
+};
+export declare const identifier: ({ node, ancestors, code, opts, meta }: IdentifierArg) => void;
+export {};

package/dist/formatters/memberExpression.d.ts

@@ -0,0 +1,4 @@
+import MagicString from 'magic-string';
+import type { MemberExpression, Node } from 'oxc-parser';
+import type { FormatterOptions } from '../types.js';
+export declare const memberExpression: (node: MemberExpression, parent: Node | null, src: MagicString, options: FormatterOptions) => void;

package/dist/formatters/metaProperty.d.ts

@@ -0,0 +1,4 @@
+import MagicString from 'magic-string';
+import type { Node, MetaProperty } from 'oxc-parser';
+import type { FormatterOptions } from '../types.js';
+export declare const metaProperty: (node: MetaProperty, parent: Node | null, src: MagicString, options: FormatterOptions) => void;

package/dist/helpers/identifier.d.ts

@@ -0,0 +1,31 @@
+import type { Node, IdentifierName } from 'oxc-parser';
+/**
+ * Focus exclusively on IdentifierName type as it has the name property,
+ * which is what the identifer utilities are interested in.
+ *
+ * Explicitly ignore the TSThisParameter type as it is not a valid identifier name.
+ */
+declare const isIdentifierName: (node: Node) => node is IdentifierName;
+/**
+ * All methods receive the full set of ancestors, which
+ * specifically includes the node itself as the last element.
+ * The second to last element is the parent node, and so on.
+ * The first element is the root node.
+ */
+declare const identifier: {
+    isNamed: (node: Node) => node is IdentifierName;
+    isMetaProperty(ancestors: Node[]): boolean;
+    isModuleScope(ancestors: Node[], includeImports?: boolean): boolean;
+    isMemberExpressionRoot(ancestors: Node[]): boolean;
+    isDeclaration(ancestors: Node[]): boolean;
+    isClassOrFuncDeclarationId(ancestors: Node[]): boolean;
+    isVarDeclarationInGlobalScope(ancestors: Node[]): boolean;
+    isIife(ancestors: Node[]): boolean;
+    isFunctionExpressionId(ancestors: Node[]): boolean;
+    isExportSpecifierAlias(ancestors: Node[]): boolean;
+    isClassPropertyKey(ancestors: Node[]): boolean;
+    isMethodDefinitionKey(ancestors: Node[]): boolean;
+    isMemberKey(ancestors: Node[]): boolean;
+    isPropertyKey(ancestors: Node[]): boolean;
+};
+export { identifier, isIdentifierName };

package/dist/helpers/scope.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from 'oxc-parser';
+declare const scopes: string[];
+declare const scope: {
+    isScope(node: Node): boolean;
+};
+export { scopes, scope };

package/dist/helpers/scope.js

@@ -0,0 +1,7 @@
+const scopes = ['BlockStatement', 'FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression', 'ClassDeclaration', 'ClassExpression', 'ClassBody', 'StaticBlock'];
+const scope = {
+  isScope(node) {
+    return scopes.includes(node.type);
+  }
+};
+export { scopes, scope };

package/dist/identifier.d.cts

@@ -0,0 +1,31 @@
+import type { Node, IdentifierName } from 'oxc-parser';
+/**
+ * Focus exclusively on IdentifierName type as it has the name property,
+ * which is what the identifer utilities are interested in.
+ *
+ * Explicitly ignore the TSThisParameter type as it is not a valid identifier name.
+ */
+declare const isIdentifierName: (node: Node) => node is IdentifierName;
+/**
+ * All methods receive the full set of ancestors, which
+ * specifically includes the node itself as the last element.
+ * The second to last element is the parent node, and so on.
+ * The first element is the root node.
+ */
+declare const identifier: {
+    isNamed: (node: Node) => node is IdentifierName;
+    isMetaProperty(ancestors: Node[]): boolean;
+    isModuleScope(ancestors: Node[], includeImports?: boolean): boolean;
+    isMemberExpressionRoot(ancestors: Node[]): boolean;
+    isDeclaration(ancestors: Node[]): boolean;
+    isClassOrFuncDeclarationId(ancestors: Node[]): boolean;
+    isVarDeclarationInGlobalScope(ancestors: Node[]): boolean;
+    isIife(ancestors: Node[]): boolean;
+    isFunctionExpressionId(ancestors: Node[]): boolean;
+    isExportSpecifierAlias(ancestors: Node[]): boolean;
+    isClassPropertyKey(ancestors: Node[]): boolean;
+    isMethodDefinitionKey(ancestors: Node[]): boolean;
+    isMemberKey(ancestors: Node[]): boolean;
+    isPropertyKey(ancestors: Node[]): boolean;
+};
+export { identifier, isIdentifierName };

package/dist/identifiers.d.cts

@@ -0,0 +1,19 @@
+import type { Node } from 'oxc-parser';
+import type { IdentMeta, Scope } from '../types.cjs';
+declare const collectScopeIdentifiers: (node: Node, scopes: Scope[]) => void;
+/**
+ * Collects all module scope identifiers in the AST.
+ *
+ * Ignores identifiers that are in functions or classes.
+ * Ignores new scopes for StaticBlock nodes (can only reference static class members).
+ *
+ * Special case handling for these which create their own scopes,
+ * but are also valid module scope identifiers:
+ * - ClassDeclaration
+ * - FunctionDeclaration
+ *
+ * Special case handling for var inside BlockStatement
+ * which are also valid module scope identifiers.
+ */
+declare const collectModuleIdentifiers: (ast: Node, hoisting?: boolean) => Promise<Map<string, IdentMeta>>;
+export { collectScopeIdentifiers, collectModuleIdentifiers };

package/dist/lang.d.cts

@@ -0,0 +1,4 @@
+import type { Specifier } from '@knighted/specifier';
+type UpdateSrcLang = Parameters<Specifier['updateSrc']>[1];
+declare const getLangFromExt: (filename: string) => UpdateSrcLang;
+export { getLangFromExt };

package/dist/memberExpression.d.cts

@@ -0,0 +1,4 @@
+import MagicString from 'magic-string';
+import type { MemberExpression, Node } from 'oxc-parser';
+import type { FormatterOptions } from '../types.cjs';
+export declare const memberExpression: (node: MemberExpression, parent: Node | null, src: MagicString, options: FormatterOptions, shadowed?: Set<string>) => void;

package/dist/metaProperty.d.cts

@@ -0,0 +1,4 @@
+import MagicString from 'magic-string';
+import type { Node, MetaProperty } from 'oxc-parser';
+import type { FormatterOptions } from '../types.cjs';
+export declare const metaProperty: (node: MetaProperty, parent: Node | null, src: MagicString, options: FormatterOptions) => void;

package/dist/module.d.cts

@@ -0,0 +1,3 @@
+import type { ModuleOptions } from './types.cjs';
+declare const transform: (filename: string, options?: ModuleOptions) => Promise<string>;
+export { transform };

package/dist/parse.d.cts

@@ -0,0 +1,2 @@
+declare const parse: (filename: string, code: string) => import("oxc-parser").ParseResult;
+export { parse };

package/dist/scope.d.cts

@@ -0,0 +1,6 @@
+import type { Node } from 'oxc-parser';
+declare const scopes: string[];
+declare const scope: {
+    isScope(node: Node): boolean;
+};
+export { scopes, scope };

package/dist/scope.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from 'oxc-parser';
+declare const scopes: string[];
+declare const scope: {
+    isScope(node: Node): boolean;
+};
+export { scopes, scope };

package/dist/scopeNodes.d.cts

@@ -0,0 +1,2 @@
+declare const scopeNodes: string[];
+export { scopeNodes };

package/dist/src/helpers/scope.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from 'oxc-parser';
+declare const scopes: string[];
+declare const scope: {
+    isScope(node: Node): boolean;
+};
+export { scopes, scope };

package/dist/types.d.cts

@@ -0,0 +1,44 @@
+import type { Node, Span, IdentifierName, IdentifierReference, BindingIdentifier, LabelIdentifier, TSIndexSignatureName } from 'oxc-parser';
+export type RewriteSpecifier = '.js' | '.mjs' | '.cjs' | '.ts' | '.mts' | '.cts' | ((value: string) => string | null | undefined);
+export type ModuleOptions = {
+    target: 'module' | 'commonjs';
+    sourceType?: 'auto' | 'module' | 'commonjs';
+    transformSyntax?: boolean;
+    liveBindings?: 'strict' | 'loose' | 'off';
+    rewriteSpecifier?: RewriteSpecifier;
+    dirFilename?: 'inject' | 'preserve' | 'error';
+    importMeta?: 'preserve' | 'shim' | 'error';
+    importMetaMain?: 'shim' | 'warn' | 'error';
+    requireSource?: 'builtin' | 'create-require';
+    cjsDefault?: 'module-exports' | 'auto' | 'none';
+    topLevelAwait?: 'error' | 'wrap' | 'preserve';
+    out?: string;
+    inPlace?: boolean;
+};
+export type SpannedNode = Node & Span;
+export type ExportsMeta = {
+    hasExportsBeenReassigned: boolean;
+    hasDefaultExportBeenReassigned: boolean;
+    hasDefaultExportBeenAssigned: boolean;
+    defaultExportValue: unknown;
+};
+export type CjsExport = {
+    key: string;
+    writes: SpannedNode[];
+    fromIdentifier?: string;
+    via: Set<'exports' | 'module.exports'>;
+    reassignments: SpannedNode[];
+    hasGetter?: boolean;
+};
+export type IdentMeta = {
+    declare: SpannedNode[];
+    read: SpannedNode[];
+};
+export type Scope = {
+    type: string;
+    name: string;
+    node: Node;
+    idents: Set<string>;
+};
+export type FormatterOptions = Omit<ModuleOptions, 'out' | 'inPlace'>;
+export type Identifier = IdentifierName | IdentifierReference | BindingIdentifier | LabelIdentifier | TSIndexSignatureName;

package/dist/url.d.cts

@@ -0,0 +1,2 @@
+declare const isValidUrl: (url: string) => boolean;
+export { isValidUrl };

package/dist/utils/identifiers.js

@@ -145,11 +145,14 @@ const collectModuleIdentifiers = async (ast, hoisting = true) => {
           const isModuleScope = identifier.isModuleScope(ancestors);
           const isClassOrFuncDeclaration = identifier.isClassOrFuncDeclarationId(ancestors);
           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 || isVarDeclarationInGlobalScope) {
             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) {
                 reads.forEach(read => {

package/dist/utils/lang.js

@@ -3,11 +3,11 @@ import { extname } from 'node:path';
 // Determine language from filename extension for specifier rewrite.
 
 const getLangFromExt = filename => {
-  const ext = extname(filename);
-  if (ext.endsWith('.js')) {
+  const ext = extname(filename).toLowerCase();
+  if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
     return 'js';
   }
-  if (ext.endsWith('.ts')) {
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
     return 'ts';
   }
   if (ext === '.tsx') {

package/dist/utils.d.cts

@@ -0,0 +1,26 @@
+import type { Node } from 'oxc-parser';
+import type { Specifier } from '@knighted/specifier';
+import type { IdentMeta, Scope, CjsExport } from './types.cjs';
+type UpdateSrcLang = Parameters<Specifier['updateSrc']>[1];
+declare const getLangFromExt: (filename: string) => UpdateSrcLang;
+declare const isValidUrl: (url: string) => boolean;
+declare const exportsRename = "__exports";
+declare const requireMainRgx: RegExp;
+declare const collectCjsExports: (ast: Node) => Promise<Map<string, CjsExport>>;
+declare const collectScopeIdentifiers: (node: Node, scopes: Scope[]) => void;
+/**
+ * Collects all module scope identifiers in the AST.
+ *
+ * Ignores identifiers that are in functions or classes.
+ * Ignores new scopes for StaticBlock nodes (can only reference static class members).
+ *
+ * Special case handling for these which create their own scopes,
+ * but are also valid module scope identifiers:
+ * - ClassDeclaration
+ * - FunctionDeclaration
+ *
+ * Special case handling for var inside BlockStatement
+ * which are also valid module scope identifiers.
+ */
+declare const collectModuleIdentifiers: (ast: Node, hoisting?: boolean) => Promise<Map<string, IdentMeta>>;
+export { getLangFromExt, isValidUrl, collectScopeIdentifiers, collectModuleIdentifiers, collectCjsExports, exportsRename, requireMainRgx, };

package/dist/utils.js

@@ -3,11 +3,11 @@ import { ancestorWalk } from './walk.js';
 import { identifier } from './helpers/identifier.js';
 import { scopeNodes } from './utils/scopeNodes.js';
 const getLangFromExt = filename => {
-  const ext = extname(filename);
-  if (ext.endsWith('.js')) {
+  const ext = extname(filename).toLowerCase();
+  if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
     return 'js';
   }
-  if (ext.endsWith('.ts')) {
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
     return 'ts';
   }
   if (ext === '.tsx') {
@@ -240,11 +240,14 @@ const collectModuleIdentifiers = async (ast, hoisting = true) => {
           const isModuleScope = identifier.isModuleScope(ancestors);
           const isClassOrFuncDeclaration = identifier.isClassOrFuncDeclarationId(ancestors);
           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 || isVarDeclarationInGlobalScope) {
             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) {
                 reads.forEach(read => {

package/dist/walk.d.cts

@@ -0,0 +1,20 @@
+import type { Node } from 'oxc-parser';
+/**
+ * Using visitorKeys instead of oxc Visitor to keep
+ * an ancestor-aware enter/leave API with this.skip()
+ * without per-node method boilerplate.
+ */
+type AncestorContext = {
+    skip: () => void;
+};
+type AncestorVisitor = {
+    enter?: (this: AncestorContext, node: Node, ancestors: Node[]) => void | Promise<void>;
+    leave?: (this: AncestorContext, node: Node, ancestors: Node[]) => void | Promise<void>;
+};
+type WalkVisitor = {
+    enter?: (this: AncestorContext, node: Node, parent: Node | null) => void | Promise<void>;
+    leave?: (this: AncestorContext, node: Node, parent: Node | null) => void | Promise<void>;
+};
+declare const ancestorWalk: (node: Node, visitors: AncestorVisitor) => Promise<void>;
+declare const walk: (node: Node, visitors: WalkVisitor) => Promise<void>;
+export { ancestorWalk, walk };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/module",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-rc.0",
   "description": "Transforms differences between ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",