docs: update.

Author: knightedcodemonkey

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.

docs/cjs-to-esm.md

@@ -5,6 +5,7 @@
 - Rewrites CommonJS modules to ESM when `target: 'module'` with `transformSyntax` enabled.
 - Assumes Node 22.21+ runtime with native ESM.
 - Skips lowering when `module` or `exports` are shadowed at module scope to avoid mis-compilation.
+- Throws when encountering `with` statements or unshadowed `eval` to avoid unsound rewrites.
 - Deprecated CJS features (`require.extensions`, `module.parent`, legacy folder-as-module resolution) are left as-is.
 
 ## Imports

docs/esm-to-cjs.md

@@ -3,7 +3,7 @@
 ## Scope
 
 - Translates ESM syntax to CommonJS when `target: 'commonjs'` with `transformSyntax` enabled.
-- Assumes Node 20.11+ runtime with `__filename`/`__dirname` shims supplied by the host.
+- Assumes Node 22.21+ runtime with `__filename`/`__dirname` shims supplied by the host (matches package engines).
 - Keeps optional live-binding behavior via `liveBindings` (strict/loose/off).
 - Top-level await (TLA) handling is controlled by `topLevelAwait: 'error' | 'wrap' | 'preserve'` when lowering to CommonJS.
 - Optional import.meta.main gating via `importMetaMain: 'shim' | 'warn' | 'error'`.