release: v2.1.4 - fail clearly on Node without require(esm)

[cldmv-bot]

@cldmv/fix-headers v2.1.4 Changelog

Release Date: October 2026
Release Type: Patch
Branch: release/2.1.4

---

Overview

Version 2.1.4 stops fix-headers from damaging files it cannot safely stamp, and fixes two CLI and discovery problems found while rolling it out across the CLDMV repositories:

• Files whose format has no usable comment syntax are never given a header. Strict JSON (package.json included) used to get a JavaScript /** … */ block that made it invalid, and Markdown named with --input got one that rendered as visible text, including in release notes built from changelog files. Markdown now gets a header only when the new markdown detector is explicitly forced, and then as an HTML comment.
• --input can be repeated, and every value is processed. Before, only the last one was.
• Dependency folders (node_modules and friends) are never walked, at any depth, whatever the ignore files say. In a project without a .gitignore, a default run used to stamp headers into installed packages.
• require("@cldmv/fix-headers") fails with a clear, actionable error on a Node.js version that cannot require() an ES module, instead of Node's bare ERR_REQUIRE_ESM.

The header format, the date logic and the fixHeaders result for files that do get a header are unchanged. See the upgrade notes for the few behaviour changes that could affect an existing setup.

---

🐛 Bug Fixes

Never write a comment into a file that cannot carry one; Markdown headers only when forced (#124, fixes #120 and #122)

A file now gets a header only when an enabled detector handles its extension. Every other file was previously given a JavaScript /** … */ block, whatever its format, and is now skipped and left byte-for-byte unchanged, even when named with --input or added through includeExtensions:

• Strict JSON (.json). JSON has no comment syntax, so the old header made the file invalid; on package.json every npm command in the folder then failed with ERR_INVALID_PACKAGE_CONFIG. JSONC, JSON5 and JSONV still get headers.
• Markdown (.md, .markdown). A repo-wide run already skipped Markdown, but naming a file with --input stamped it with a JS comment that showed up as text, and in a per-version changelog it would have ended up in the release notes. Markdown is now handled by a new markdown detector that never runs unless forced with --force-detector markdown (forcedDetectors: ["markdown"] in the API or a config file). A forced header is an HTML comment (<!-- … -->), placed below any YAML front matter and updated in place on later runs. Naming a file with --input, or listing markdown in --enable-detector, does not force it.
• Files with no extension, or an extension no enabled detector handles (.txt, .toml, a disabled detector's extensions). These used to get a guessed JS comment, which in an extensionless script could land above the shebang.

Skipped files are reported: the API result gains filesSkipped and skipped: [{ file, reason }] (skipped files no longer count in filesScanned), and the CLI summary adds skipped=<n> plus one skipped: <file> (<reason>) line per file. The README gains a Supported file types table that matches the detectors.

Repeated --input processes every value (#125, fixes #119)

--input a.mjs --input b.mjs used to process only b.mjs and report scanned=1, silently skipping the rest. --input is now repeatable and the input option accepts a string or an array: every file and folder given is processed, each file once, in the order given. A path that does not exist throws an error naming it.

Dependency folders are never walked, at any depth (#126, fixes #123)

The discovery walker only ever skipped .git by name and relied on the project's ignore files for everything else. In a project with no .gitignore, or for a sub-package's own node_modules, a default run processed installed packages. node_modules, bower_components, jspm_packages, .pnpm-store and .yarn are now skipped at any depth regardless of the ignore files or gitignore: false; vendor is skipped only when Composer (autoload.php) or Go (modules.txt) created it, since the name is often used for a project's own code. A path inside one of these folders named explicitly with --include-folder or --input is still processed. This reverses part of #71 (v2.0.0), which had stopped skipping node_modules by name; build output (dist, build, coverage) is still processed unless something excludes it.

require() fails clearly on Node.js without require(esm) (#117)

Since v2.0.0, dist/index.cjs is a small wrapper that loads dist/index.mjs through Node's synchronous require(esm) and returns its default export. On a Node.js version without that feature (before 20.19 on the 20.x line, or before 22.12), the require() call inside the wrapper threw a generic ERR_REQUIRE_ESM that pointed at the package's own internals and gave no hint of what to do.

The wrapper now checks process.features.require_module before loading the ES module build. When it is missing, it throws an error with the same ERR_REQUIRE_ESM code and a message that names the package, the required Node.js versions and the running version, and points at import():

@cldmv/fix-headers: require() needs Node.js ^20.19.0 or >=22.12.0 (this is v20.18.0). On older Node.js, load the package with import() instead.

Code that catches ERR_REQUIRE_ESM by code keeps working. On supported Node.js versions the check passes and require() returns the fixHeaders function as before.

🧪 Tests

• New suites for each fix, written to fail before it: non-JS formats and forced Markdown (tests/non-js-formats.test.vitest.mjs), repeated --input (tests/repeatable-input.test.vitest.mjs) and dependency folders (tests/file-discovery-dependency-folders.test.vitest.mjs). Coverage stays at 100%.
• New tests/cjs/entry.test.cjs, run with node --test by a new test:cjs script after a fresh npm run build. It checks that require() of the built package returns the same default export as import, and that the version check throws the new error when require(esm) is unavailable.
• npm test and npm run coverage (and so ci:coverage) now run test:cjs after the Vitest suite, so CI exercises the published CommonJS entry point, not only the source.

📚 Documentation

• NEW: docs/changelog/v2/v2.1.4.md: this changelog.
• NEW: changelog files for every earlier release that shipped without one: v1.0.0 to v1.3.12 in docs/changelog/v1/, plus v2.1.1 and v2.1.2.
• README restructured to the CLDMV layout: badges, What's New, Key Features, Installation with Node.js requirements, Quick Start, then the existing usage, API and configuration reference.

🔧 Dependencies

No dependency updates. ignore, the only runtime dependency, is unchanged.

---

Upgrade notes

No changes are needed for the usual setup (source files plus a config). The behaviour changes that could affect an existing setup:

• Files that used to get a JS comment are now skipped: strict .json, Markdown named with --input, files with no extension, and extensions no enabled detector handles (for example a .txt added through includeExtensions). If you relied on that, the header was being written in the wrong comment syntax; for Markdown, use --force-detector markdown.
• Dependency folders are no longer processed, even with gitignore: false. To stamp something inside one on purpose, name it with --include-folder or --input.
• filesScanned no longer counts skipped files; read filesSkipped and skipped for those.
• On Node.js versions without require(esm), require() fails with a clearer message and the same ERR_REQUIRE_ESM code.

👥 Contributors

• @Shinrai

---

Metric	Coverage
Statements	100.0%
Branches	100.0%
Functions	100.0%
Lines	100.0%

Avg: 100.0% · 9587a3a · Node lts/*

Co-authored-by: Shinrai Shinrai@users.noreply.github.com

[cldmv-bot]

🔒 Dependency Review

• ✅ 0 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ✅ 0 package(s) with unknown licenses
• ✅ 0 denied package(s)
• ✅ 0 package(s) with OpenSSF Scorecard score < 3

Full job summary

[cldmv-bot]

⚠️ Bundle size increased

File	Raw	Δ Raw	Gzipped	Δ Gzipped
bin/fix-headers.mjs	51.4 kB	+2.1 kB (+4.2%) ⚠️	17.3 kB	+850 B
dist/index.cjs	1.6 kB	+468 B (+40.3%) ⚠️	940 B	+248 B
dist/index.mjs	42.2 kB	+1.6 kB (+4.0%) ⚠️	14.4 kB	+708 B
Total	95.2 kB	+4.2 kB	32.6 kB	+1.8 kB

_{📊 Generated by bundle-size. Brotli sizes also measured but omitted from the table for brevity.}