Upgrade to unified 11 / remark 11 and publish as ESM

[josemarluedke]

Closes the long-standing blocker in #93, unblocks #116, and answers #150.

Why this is possible now

Docfy has been stuck on unified 9 because the remark/rehype ecosystem moved to ESM and a CommonJS broccoli addon couldn't load ESM-only packages. That constraint is gone: Node supports require() of ES modules, unflagged since 20.19 / 22.12. So @docfy/ember-cli can require an ESM-only @docfy/core, and a CommonJS .docfy-config.js can require ESM-only plugins. No dual builds, no await import() plumbing, and no forcing users onto .mjs.

What changed

@docfy/core and @docfy/plugin-with-prose are now ES modules on unified 11 / remark 11 / rehype 11. Going ESM also deletes the export default X; module.exports = X; interop hack that no ESM loader can execute.

• remark-slug (deprecated) replaced by a ~20-line internal transform. It stays at the mdast stage because the toc plugin reads node.data.id while the tree is still markdown. Generated ids are byte-identical.
• mdast-util-toc removed — declared but never imported.
• Nine hand-written .d.ts shims deleted; every one of those packages ships its own types now.
• @docfy/ember-cli now loads .docfy-config.js, .mjs and .cjs, all synchronously, and raises an explicit error for the one case it can't handle (top-level await).

The one non-obvious problem

Highlighting has to move from remark to rehype, and that exposed an ordering bug. remark-hbs escapes {{ in code blocks on the mdast tree; rehype highlighters inject <span>s afterwards, reintroducing bare {{, so Ember's template compiler chokes:

Parse error on line 23:
...tuation mustache">{{<span class="hljs-cl
-----------------------^

Escaping now happens at the hast stage via a new escape-curlies-in-code plugin — runWithHast runs after all rehype plugins. With that in place highlight.js 11 works, so highlightjs-glimmer works (#116). Verified hljs-template-variable in test-app-classic's built output.

Jest → vitest

Jest 29 cannot require() ESM regardless of Node's support — it throws on trough/index.js. @docfy/core and @docfy/plugin-with-prose move to vitest, matching @docfy/ember-vite. No test bodies changed beyond __dirname → import.meta.dirname, named imports, and .js extensions.

Vitest keys snapshots differently, so the .snap files were rewritten. I diffed old against new key-by-key before accepting:

• heading extraction, URL generation (auto + manual), internal-link rewriting — byte-identical
• plugin-with-prose — identical HTML, only jest's Array [ serialization differs
• integration-remark-plugins — differs only from the plugin swaps: rehype-autolink-headings orders attributes differently, remark-math 6 renders bare math as <code class="language-math">, katex dropped a wrapper span

Verification

@docfy/core	52/57 pass — the 5 failures are pre-existing
@docfy/plugin-with-prose	2/2
@docfy/ember-vite	60/60
pnpm -r compile	clean
test-app-classic	ember build succeeds, with a CommonJS config requiring ESM-only plugins
test-app-vite	vite build succeeds
frontile site/	client + ssr + prerender build, 21/21 node tests — config-only changes, no source changes

The 5 core failures are repo-info (4) and generating-edit-url (1). They fail on main too: they were run from a git worktree, so git-repo-info reports a root containing .claude/worktrees/.... The snapshot diff shows that path prefix is the only delta.

Breaking changes

Documented in docs/ember/upgrade-guide.md:

• Node ^20.19.0 || >=22.12.0. This is what makes require(esm) work.
• Plain require('@docfy/core') returns the module namespace, so it needs .default. ESM and TypeScript esModuleInterop consumers are unaffected — frontile and both test apps needed no code change.
• Deep imports from ESM need an extension: @docfy/core/lib/plugin.js.
• remark-highlight.js and @mapbox/rehype-prism no longer work → rehype-highlight or rehype-prism-plus.
• Docfy now owns remarkHbsOptions.escapeCurliesCode / escapeCurliesInlineCode; remove them from your config.
• Don't bump a direct highlight.js dependency. rehype-highlight brings its own via lowlight. Doing both at once broke language registration in frontile's SSR bundle.

Deliberately left out

• escape-curlies-in-code is duplicated across ember-cli and ember-vite, matching how those two already duplicate their other Docfy plugins. Deduplicating is its own change.
• The @types/unist v2 pin stays, with the comment rewritten to explain why. The Ember integrations' plugins are written against v2's loose Node (index signature, so node.value / node.depth type-check on a bare node) and intentionally build synthetic nodes and reassign node.type — which strict mdast Root/RootContent cannot express. It's types-only; runtime is unaffected. I prototyped the strict version and it needs those plugins redesigned, not retyped.
• remark-hbs still works but is from 2021 on unist-util-visit@2. A 0.5 on current deps would drop the last stale link. Its inline-component limitation (the The easy way to support Unified and Remark ESM (latest) #150 caveat) is unchanged — I confirmed identical behaviour on unified 9 and 11, so not a regression.
• hosted-git-info stays at v3; v4+ replaced browsetemplate with .edit(), an unrelated repo-info.ts refactor.

Pre-existing lint failures untouched by this PR: packages/ember lint:hbs (nested splattributes), test-app-classic lint:types (@glint/core isn't a dependency), test-app-vite lint:types.

Not verified either way: test-app-vite's testem run fails with ReferenceError: define is not defined in @embroider/virtual/test-support.js. It isn't in CI and I couldn't get a clean baseline install to compare against.

🤖 Generated with Claude Code