refactor(core): load generators by import specifier

[avivkeller]

Generators are no longer resolved through a static registry.

Now, they're now loaded dynamically by import specifier. --target accepts either a built-in shorthand (web, legacy-html, …) or any import specifier that resolves to a generator module (e.g. some-package/generator, ./my-generator.mjs). A generator's dependsOn field is likewise now a full import specifier.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Aug 1, 2026 10:37am

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

❌ Patch coverage is 94.12916% with 30 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.94%. Comparing base (2f9defe) to head (630eee0).

Files with missing lines	Patch %	Lines
packages/core/src/generators/loader.mjs	75.00%	23 Missing and 1 partial ⚠️
packages/core/bin/commands/generate.mjs	0.00%	5 Missing ⚠️
packages/core/src/generators.mjs	97.22%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #958      +/-   ##
==========================================
+ Coverage   86.63%   88.94%   +2.31%     
==========================================
  Files         195      197       +2     
  Lines       17938    18106     +168     
  Branches     1632     1664      +32     
==========================================
+ Hits        15540    16105     +565     
+ Misses       2392     1994     -398     
- Partials        6        7       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

PR Summary

Medium Risk
Touches core orchestration, worker loading, and config default merging—behavior should stay equivalent for built-in targets, but custom specifiers and resolved target arrays (e.g. web showSearchBox) are new surface area.

Overview
Replaces the static generator registry with dynamic import() loading, so --target and config target accept built-in shorthands (web, legacy-html, …) or any resolvable module (package subpaths like @node-core/doc-kit/metadata, local ./my-generator.mjs). A new loader.mjs resolves aliases, loads the dependency closure, and validates default exports.

Built-in generators are plain metadata objects (no createLazyGenerator); generators/index.mjs is only a name→specifier map. dependsOn values are full import specifiers, and the pipeline cache / Piscina workers key and load generators by resolved specifier. @node-core/doc-kit gains subpath exports for each built-in generator.

Configuration resolves targets and loads only the requested generators (plus deps) before merging defaults. Docs and tests follow the new registration model; signature parsing helpers move to utils/signature for shared use.

^{Reviewed by Cursor Bugbot for commit 630eee0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

api-links Generator

Performance estimate _{(single CI run)}

• Generation time: 32.0% slower (1.03 s → 1.36 s)
• Peak memory: 0.0% lower (365.91 MB → 365.79 MB)

legacy-json Generator

Performance estimate _{(single CI run)}

• Generation time: 11.0% slower (9.10 s → 10.10 s)
• Peak memory: 4.0% higher (1.67 GB → 1.74 GB)

llms-txt Generator

Performance estimate _{(single CI run)}

• Generation time: 2.3% faster (8.13 s → 7.94 s)
• Peak memory: 4.0% higher (1.69 GB → 1.75 GB)

orama-db Generator

Output size: 1 file changed · net +1.20 KB

File size details

File	Main	PR	Change
orama-db.json	8.89 MB	8.89 MB	+1.20 KB (+0.0%)

Performance estimate _{(single CI run)}

• Generation time: 16.4% slower (9.01 s → 10.49 s)
• Peak memory: 1.9% lower (1.81 GB → 1.78 GB)

web Generator

Output size: 2 files changed · net 0 B

File size details

File	Main	PR	Change
assets/all-C8_ahR43.js	22.13 MB	—	-22.13 MB (-100.0%)
assets/all-CavH_T_o.js	—	22.13 MB	+22.13 MB

Performance estimate _{(single CI run)}

• Generation time: 2.0% slower (73.65 s → 75.13 s)
• Peak memory: 0.1% higher (5.29 GB → 5.29 GB)

[ovflowd]

Lots of changes, hard to review so rubber stamp SGTM

[AugustinMauroy]

lgmt !

[Copilot]

Pull request overview

Copilot reviewed 46 out of 52 changed files in this pull request and generated no new comments.

Suppressed comments (1)

packages/core/src/generators/loader.mjs:21

• resolveGeneratorSpecifier() uses the in operator to check for shorthand targets. Because in also matches inherited keys (e.g. __proto__, toString), a crafted --target value can resolve to a non-string and cause import() to throw a confusing TypeError (and can open prototype-pollution style footguns). Use an own-property check instead.

export const resolveGeneratorSpecifier = target => {
  if (target in allGenerators) {
    return allGenerators[target];
  }