chore: drop node 20, refactor. (#19)

Author: knightedcodemonkey

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
 

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.
 

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/`.

package-lock.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": {

package.json

@@ -5,8 +5,8 @@ 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'
+import { scopeNodes } from './utils/scopeNodes.js'
 
 type UpdateSrcLang = Parameters<Specifier['updateSrc']>[1]
 const getLangFromExt = (filename: string): UpdateSrcLang => {

src/utils.ts

@@ -2,8 +2,8 @@ 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'
+import { scopeNodes } from './scopeNodes.js'
 
 const collectScopeIdentifiers = (node: Node, scopes: Scope[]) => {
   const { type } = node

src/utils/identifiers.ts

@@ -1,6 +1,4 @@
-import type { Node } from 'oxc-parser'
-
-const scopes = [
+const scopeNodes = [
   'BlockStatement',
   'FunctionDeclaration',
   'FunctionExpression',
@@ -11,10 +9,4 @@ const scopes = [
   'StaticBlock',
 ]
 
-const scope = {
-  isScope(node: Node) {
-    return scopes.includes(node.type)
-  },
-}
-
-export { scopes, scope }
+export { scopeNodes }