From 3cb45ad646617588cc9a7b7da1221dc3127bda9f Mon Sep 17 00:00:00 2001 From: KCM Date: Sat, 27 Dec 2025 13:52:09 -0600 Subject: [PATCH 1/3] chore: drop node 20. --- README.md | 2 +- docs/cjs-to-esm.md | 2 +- package-lock.json | 6 +++--- package.json | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 27eb93f..9b6b11f 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ By default `@knighted/module` transforms the one-to-one [differences between ES ## Requirements -- Node >= 20.11.0 +- Node >= 22.21.1 ## Install diff --git a/docs/cjs-to-esm.md b/docs/cjs-to-esm.md index b2a63d7..71270d3 100644 --- a/docs/cjs-to-esm.md +++ b/docs/cjs-to-esm.md @@ -3,7 +3,7 @@ ## Scope - Rewrites CommonJS modules to ESM when `target: 'module'` with `transformSyntax` enabled. -- Assumes Node 20.11+ runtime with native ESM. +- Assumes Node 22.21+ runtime with native ESM. - Skips lowering when `module` or `exports` are shadowed at module scope to avoid mis-compilation. - Deprecated CJS features (`require.extensions`, `module.parent`, legacy folder-as-module resolution) are left as-is. diff --git a/package-lock.json b/package-lock.json index 37437a0..acb703e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@knighted/module", - "version": "1.0.0-beta.3", + "version": "1.0.0-beta.4", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@knighted/module", - "version": "1.0.0-beta.3", + "version": "1.0.0-beta.4", "license": "MIT", "dependencies": { "@knighted/specifier": "^2.0.9", @@ -28,7 +28,7 @@ "typescript": "^5.9.3" }, "engines": { - "node": ">=20.11.0" + "node": ">=22.21.1" } }, "node_modules/@babel/code-frame": { diff --git a/package.json b/package.json index 8b0e221..d333d60 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@knighted/module", - "version": "1.0.0-beta.3", + "version": "1.0.0-beta.4", "description": "Transforms differences between ES modules and CommonJS.", "type": "module", "main": "dist/module.js", @@ -27,7 +27,7 @@ "#formatters/*.js": "./src/formatters/*.js" }, "engines": { - "node": ">=20.11.0" + "node": ">=22.21.1" }, "engineStrict": true, "scripts": { From 131c66326e1ebc5373bc8970ae0f92b58ad5953d Mon Sep 17 00:00:00 2001 From: KCM Date: Sat, 27 Dec 2025 14:10:47 -0600 Subject: [PATCH 2/3] refactor: remove scope helper. --- docs/helpers-vs-utils.md | 22 ++++++++++++++++++++++ src/helpers/scope.ts | 20 -------------------- src/utils.ts | 12 +++++++++++- src/utils/identifiers.ts | 12 +++++++++++- 4 files changed, 44 insertions(+), 22 deletions(-) create mode 100644 docs/helpers-vs-utils.md delete mode 100644 src/helpers/scope.ts diff --git a/docs/helpers-vs-utils.md b/docs/helpers-vs-utils.md new file mode 100644 index 0000000..b68e2cf --- /dev/null +++ b/docs/helpers-vs-utils.md @@ -0,0 +1,22 @@ +# Helpers vs utils + +## Intent + +- `helpers/`: small, pure AST-shape predicates/utilities. They inspect nodes but do not mutate `MagicString`, maintain state, or depend on transformation options. Safe to import anywhere (including formatters) without side effects. +- `utils/`: transformation plumbing and shared state. They may build/consume metadata, track identifiers/exports, or mutate `MagicString`/strings. Formatters and the main `format` pass call into these. + +## Conventions + +- `helpers/` should not import from `utils/` to keep them dependency-light. `utils/` may import `helpers/`. +- Keep `helpers/` functions small and specific (e.g., identifier/name guards, skip checks). If it holds cross-pass state or writes code, it belongs in `utils/`. +- When adding a new helper, check if it needs options or shared tables; if so, place it in `utils/` instead. + +## Current layout (Dec 2025) + +- `helpers/`: identifier/name helpers. +- `utils/`: exports collection, identifier tracking, language/specifier helpers, misc transformation utilities. + +## Maintenance tips + +- Periodically run a quick grep to remove unused helpers. +- If a helper starts mutating code or carrying state, move it into `utils/`. diff --git a/src/helpers/scope.ts b/src/helpers/scope.ts deleted file mode 100644 index 013008e..0000000 --- a/src/helpers/scope.ts +++ /dev/null @@ -1,20 +0,0 @@ -import type { Node } from 'oxc-parser' - -const scopes = [ - 'BlockStatement', - 'FunctionDeclaration', - 'FunctionExpression', - 'ArrowFunctionExpression', - 'ClassDeclaration', - 'ClassExpression', - 'ClassBody', - 'StaticBlock', -] - -const scope = { - isScope(node: Node) { - return scopes.includes(node.type) - }, -} - -export { scopes, scope } diff --git a/src/utils.ts b/src/utils.ts index 78ec425..4976c81 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -5,9 +5,19 @@ import type { Node } from 'oxc-parser' import type { Specifier } from '@knighted/specifier' import type { IdentMeta, SpannedNode, Scope, CjsExport } from './types.js' -import { scopes as scopeNodes } from './helpers/scope.js' import { identifier } from './helpers/identifier.js' +const scopeNodes = [ + 'BlockStatement', + 'FunctionDeclaration', + 'FunctionExpression', + 'ArrowFunctionExpression', + 'ClassDeclaration', + 'ClassExpression', + 'ClassBody', + 'StaticBlock', +] + type UpdateSrcLang = Parameters[1] const getLangFromExt = (filename: string): UpdateSrcLang => { const ext = extname(filename) diff --git a/src/utils/identifiers.ts b/src/utils/identifiers.ts index 523c8d0..ec683f8 100644 --- a/src/utils/identifiers.ts +++ b/src/utils/identifiers.ts @@ -2,9 +2,19 @@ import type { Node } from 'oxc-parser' import type { IdentMeta, SpannedNode, Scope } from '../types.js' import { ancestorWalk } from '#walk' -import { scopes as scopeNodes } from '#helpers/scope.js' import { identifier } from '#helpers/identifier.js' +const scopeNodes = [ + 'BlockStatement', + 'FunctionDeclaration', + 'FunctionExpression', + 'ArrowFunctionExpression', + 'ClassDeclaration', + 'ClassExpression', + 'ClassBody', + 'StaticBlock', +] + const collectScopeIdentifiers = (node: Node, scopes: Scope[]) => { const { type } = node From f0173b18f078927505008e00e0e31d5fd6e15a11 Mon Sep 17 00:00:00 2001 From: KCM Date: Sat, 27 Dec 2025 14:16:40 -0600 Subject: [PATCH 3/3] refactor: scope nodes. --- src/utils.ts | 12 +----------- src/utils/identifiers.ts | 12 +----------- src/utils/scopeNodes.ts | 12 ++++++++++++ 3 files changed, 14 insertions(+), 22 deletions(-) create mode 100644 src/utils/scopeNodes.ts diff --git a/src/utils.ts b/src/utils.ts index 4976c81..9c7b1ab 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -6,17 +6,7 @@ import type { Specifier } from '@knighted/specifier' import type { IdentMeta, SpannedNode, Scope, CjsExport } from './types.js' import { identifier } from './helpers/identifier.js' - -const scopeNodes = [ - 'BlockStatement', - 'FunctionDeclaration', - 'FunctionExpression', - 'ArrowFunctionExpression', - 'ClassDeclaration', - 'ClassExpression', - 'ClassBody', - 'StaticBlock', -] +import { scopeNodes } from './utils/scopeNodes.js' type UpdateSrcLang = Parameters[1] const getLangFromExt = (filename: string): UpdateSrcLang => { diff --git a/src/utils/identifiers.ts b/src/utils/identifiers.ts index ec683f8..4b344dc 100644 --- a/src/utils/identifiers.ts +++ b/src/utils/identifiers.ts @@ -3,17 +3,7 @@ import type { Node } from 'oxc-parser' import type { IdentMeta, SpannedNode, Scope } from '../types.js' import { ancestorWalk } from '#walk' import { identifier } from '#helpers/identifier.js' - -const scopeNodes = [ - 'BlockStatement', - 'FunctionDeclaration', - 'FunctionExpression', - 'ArrowFunctionExpression', - 'ClassDeclaration', - 'ClassExpression', - 'ClassBody', - 'StaticBlock', -] +import { scopeNodes } from './scopeNodes.js' const collectScopeIdentifiers = (node: Node, scopes: Scope[]) => { const { type } = node diff --git a/src/utils/scopeNodes.ts b/src/utils/scopeNodes.ts new file mode 100644 index 0000000..28dcc20 --- /dev/null +++ b/src/utils/scopeNodes.ts @@ -0,0 +1,12 @@ +const scopeNodes = [ + 'BlockStatement', + 'FunctionDeclaration', + 'FunctionExpression', + 'ArrowFunctionExpression', + 'ClassDeclaration', + 'ClassExpression', + 'ClassBody', + 'StaticBlock', +] + +export { scopeNodes }