test: more coverage and fixtures. (#21)

knightedcodemonkey · web-flow · commit 911adf76baf6 · 2025-12-27T15:59:48.000-06:00
diff --git a/docs/release-1.0.0.md b/docs/release-1.0.0.md
@@ -0,0 +1,52 @@
+# @knighted/module 1.0.0 release notes
+
+## Status
+
+- Current candidate: 1.0.0-rc.0 (tag `latest` until final 1.0.0).
+- Stability: API surface locked for 1.0.x; only bug fixes expected before GA.
+
+## Requirements
+
+- Node >= 22.21.1 (tested primarily on 22.x). Older LTS are not guaranteed; add matrix coverage if support is desired.
+
+## Highlights
+
+- Symmetric ESM↔CJS transforms with optioned behaviors:
+  - `topLevelAwait`: `error` (default), `wrap`, `preserve` for CJS targets.
+  - `importMetaMain`: `shim` (default), `warn`, `error` with Node version gate.
+  - `liveBindings`: `strict` (default), `loose`, `off` for ESM→CJS.
+  - `cjsDefault`: `auto` (default), `module-exports`, `none` for default import interop.
+  - `rewriteSpecifier`: extension or callback-based specifier rewriting for both directions.
+  - `requireSource`: `builtin` (default) or `create-require` fallback.
+- Defensive handling: reject `with` / unshadowed `eval` when raising to ESM; reject shadowed `module`/`exports` in CJS lowering.
+- Runtime coverage: fixtures and integration tests for **filename/**dirname/import.meta globals, `require.main` rewrites, TLA wrapping, namespace/default interop, export hoisting, and project-level conversions.
+
+## Behavior guarantees
+
+- Live bindings are strict by default for ESM→CJS; CJS→ESM rewrites avoid unsound cases by throwing on unsupported constructs.
+- `import.meta` properties shimmed when targeting CJS; `import.meta.main` guarded by version-aware warnings/errors.
+- Top-level await in CJS targets defaults to `error`; wrapping/preserve are opt-in and keep exports intact.
+
+## Packaging and metadata
+
+- Confirm `package.json` exports/fields (`main`, `exports`, `types`) match the build outputs.
+- Dependencies: `oxc-parser`, `@babel/parser/traverse`, `magic-string`, `@knighted/specifier`, `@knighted/walk`, `node-module-type`.
+- Consider source maps (not emitted today); document absence if deferring.
+
+## Testing
+
+- Lint: `npm run lint` (oxlint) — clean.
+- Tests: `npm test` — ~98% statements, ~93% branches; format.ts 100% line coverage, remaining branches are defensive/unreachable.
+- Add Node matrix if supporting additional runtimes before GA.
+
+## Release steps to GA
+
+1. Publish 1.0.0-rc.0 as `latest` (per plan); keep `next` if needed for future prereleases.
+2. Monitor for regressions; if none, tag 1.0.0 with the same artifacts.
+3. Update README and docs links to reference this release note; remove any “remaining gaps” language now that coverage is closed.
+4. Add changelog entry summarizing changes since 1.0.0-alpha.8/1.0.0-beta.5.
+
+## Open questions
+
+- Do we want official support for Node 20/18? If yes, run matrix and adjust shims accordingly.
+- CLI packaging: still library-only; document intentionally if not providing a CLI.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@knighted/module",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-rc.0",
   "description": "Transforms differences between ES modules and CommonJS.",
   "type": "module",
   "main": "dist/module.js",
diff --git a/test/fixtures/arrayValue.cjs b/test/fixtures/arrayValue.cjs
@@ -0,0 +1 @@
+module.exports = [1, 2, 3]
diff --git a/test/fixtures/bareModuleExports.cjs b/test/fixtures/bareModuleExports.cjs
@@ -0,0 +1,2 @@
+module.exports
+exports.foo = 1
diff --git a/test/fixtures/cjsDefaultModuleExports.mjs b/test/fixtures/cjsDefaultModuleExports.mjs
@@ -0,0 +1,3 @@
+import foo from './values.cjs'
+
+export const value = foo.foo
diff --git a/test/fixtures/evalOnly.cjs b/test/fixtures/evalOnly.cjs
@@ -0,0 +1 @@
+eval('exports.ok = true')
diff --git a/test/fixtures/exportDefaultAnon.mjs b/test/fixtures/exportDefaultAnon.mjs
@@ -0,0 +1,3 @@
+export default function () {
+  return 'anon'
+}
diff --git a/test/fixtures/exportDefaultAnonTla.mjs b/test/fixtures/exportDefaultAnonTla.mjs
@@ -0,0 +1,5 @@
+await Promise.resolve('tla')
+
+export default function () {
+  return 'tla-anon'
+}
diff --git a/test/fixtures/exportDefaultNamed.mjs b/test/fixtures/exportDefaultNamed.mjs
@@ -0,0 +1,3 @@
+export default function namedNoTla() {
+  return 'named-no-tla'
+}
diff --git a/test/fixtures/exportDefaultTlaNamed.mjs b/test/fixtures/exportDefaultTlaNamed.mjs
@@ -0,0 +1,4 @@
+await Promise.resolve()
+export default function named() {
+  return 'tla-named'
+}
diff --git a/test/fixtures/exportNamedFunction.mjs b/test/fixtures/exportNamedFunction.mjs
@@ -0,0 +1,7 @@
+export function greet() {
+  return 'greet'
+}
+
+export class Box {
+  value = 1
+}
diff --git a/test/fixtures/exportNamespaceAll.mjs b/test/fixtures/exportNamespaceAll.mjs
@@ -0,0 +1 @@
+export * as bag from './values.mjs'
diff --git a/test/fixtures/exportNamespaceSpecifier.mjs b/test/fixtures/exportNamespaceSpecifier.mjs
@@ -0,0 +1 @@
+export * as ns from './exportDefaultAnon.mjs'
diff --git a/test/fixtures/exportReexportDefault.mjs b/test/fixtures/exportReexportDefault.mjs
@@ -0,0 +1,4 @@
+export { default as anon } from './exportDefaultAnon.mjs'
+export { default as named } from './exportDefaultNamed.mjs'
+
+export const label = 'reexport'
diff --git a/test/fixtures/importSideEffect.mjs b/test/fixtures/importSideEffect.mjs
@@ -0,0 +1,3 @@
+import './values.cjs'
+
+export const loaded = true
diff --git a/test/fixtures/liveBindingsOff.mjs b/test/fixtures/liveBindingsOff.mjs
@@ -0,0 +1,4 @@
+export const foo = 1
+export function inc(x) {
+  return x + 1
+}
diff --git a/test/fixtures/projects/cjs-app/index.cjs b/test/fixtures/projects/cjs-app/index.cjs
@@ -0,0 +1,15 @@
+const { basename, bump, value } = require('./lib.cjs')
+const { join } = require('node:path')
+
+const here = __dirname
+
+module.exports.main = () => ({
+  name: basename(__filename),
+  bumped: bump(2),
+  value,
+  path: join(here, 'lib.cjs'),
+})
+
+if (require.main === module) {
+  console.log(JSON.stringify(module.exports.main()))
+}
diff --git a/test/fixtures/projects/cjs-app/lib.cjs b/test/fixtures/projects/cjs-app/lib.cjs
@@ -0,0 +1,10 @@
+const path = require('node:path')
+
+exports.value = 1
+exports.basename = file => path.basename(file)
+exports.bump = v => v + exports.value
+exports.dynamicLoad = id => require(id).value
+
+if (require.main === module) {
+  console.log(exports.bump(2))
+}
diff --git a/test/fixtures/projects/esm-app/index.mjs b/test/fixtures/projects/esm-app/index.mjs
@@ -0,0 +1,13 @@
+import { add, inc } from './lib.mjs'
+
+const boot = await Promise.resolve(2)
+
+export const ready = boot
+export const run = async () => {
+  const next = inc()
+  return { sum: add(boot, 0), after: next, main: import.meta.main ?? false }
+}
+
+if (import.meta.main) {
+  run().then(res => console.log(JSON.stringify(res)))
+}
diff --git a/test/fixtures/projects/esm-app/lib.mjs b/test/fixtures/projects/esm-app/lib.mjs
@@ -0,0 +1,6 @@
+export const add = (a, b) => a + b
+export let counter = 0
+export const inc = () => {
+  counter += 1
+  return counter
+}
diff --git a/test/fixtures/requireArray.cjs b/test/fixtures/requireArray.cjs
@@ -0,0 +1,6 @@
+const [first] = require('./arrayValue.cjs')
+const path = './arrayValue.cjs'
+require(path)
+
+// keep a runtime observable side effect
+globalThis.__requireArrayFirst = first
diff --git a/test/fixtures/requireMainNotEq.cjs b/test/fixtures/requireMainNotEq.cjs
@@ -0,0 +1,5 @@
+if (require.main !== module) {
+  module.exports = { main: false }
+} else {
+  module.exports = { main: true }
+}
diff --git a/test/fixtures/requireMainReversed.cjs b/test/fixtures/requireMainReversed.cjs
@@ -0,0 +1,5 @@
+if (module === require.main) {
+  module.exports = { main: true }
+} else {
+  module.exports = { main: false }
+}
diff --git a/test/fixtures/tlaError.mjs b/test/fixtures/tlaError.mjs
@@ -0,0 +1,2 @@
+await Promise.resolve(1)
+export const foo = 1
diff --git a/test/fixtures/weirdExport.cjs b/test/fixtures/weirdExport.cjs
@@ -0,0 +1,3 @@
+exports['foo-bar'] = 1
+module.exports['baz+qux'] = 2
+exports['123num'] = 3
diff --git a/test/module.ts b/test/module.ts
diff --git a/test/utils.ts b/test/utils.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@knighted/module",`
`3`		`- "version": "1.0.0-beta.5",`
	`3`	`+ "version": "1.0.0-rc.0",`
`4`	`4`	`"description": "Transforms differences between ES modules and CommonJS.",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "dist/module.js",`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import foo from './values.cjs'`
	`2`	`+`
	`3`	`+export const value = foo.foo`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export default function () {`
	`2`	`+ return 'anon'`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export default function namedNoTla() {`
	`2`	`+ return 'named-no-tla'`
	`3`	`+}`