refactor(node): extract @doc-kittens/node package by avivkeller · Pull Request #961 · nodejs/doc-kit

avivkeller · 2026-07-30T21:30:32Z

And finally, the remaining Node.js-specific generators are now in @doc-kittens/node

vercel · 2026-07-30T21:30:33Z

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 3:27pm

Copilot

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

codecov · 2026-07-30T21:31:40Z

Codecov Report

❌ Patch coverage is 62.50000% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.27%. Comparing base (d75c211) to head (59787df).

Files with missing lines	Patch %	Lines
packages/node/src/man-page/generate.mjs	0.00%	5 Missing ⚠️
packages/node/src/addon-verify/generate.mjs	0.00%	2 Missing ⚠️
packages/node/src/api-links/index.mjs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@                    Coverage Diff                     @@
##           refactor/legacy-kitten     #961      +/-   ##
==========================================================
- Coverage                   84.54%   78.27%   -6.27%     
==========================================================
  Files                         215      215              
  Lines                       19148    19151       +3     
  Branches                     1670     1564     -106     
==========================================================
- Hits                        16188    14990    -1198     
- Misses                       2953     4153    +1200     
- Partials                        7        8       +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 · 2026-07-30T21:34:48Z

PR Summary

Medium Risk
Breaking for anyone importing api-links, addon-verify, or man-page from @node-core/doc-kit; CLI shorthand behavior is preserved but workspace wiring must include the new package.

Overview
Node-specific generators api-links, addon-verify, and man-page are moved out of @node-core/doc-kit into a new @doc-kittens/node workspace package. The core generator registry still exposes the same CLI/config shorthand names (man-page, addon-verify, api-links), but they now resolve to import specifiers like @doc-kittens/node/man-page.

@node-core/doc-kit drops the ./addon-verify, ./api-links, and ./man-page package exports and sheds estree-util-visit (now a dependency of @doc-kittens/node). Moved code imports shared utilities and types from @node-core/doc-kit (e.g. configuration, file helpers, metadata types). addon-verify’s generated test.js wrapper now requires @node-core/doc-kit/generators/common instead of a relative ../../common path.

Docs examples for the redesigned site use -t html instead of -t web (aligned with the html generator name). The changeset flags a major release for @doc-kittens/node and a minor for @node-core/doc-kit because consumers that imported those generators directly from doc-kit must switch packages.

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

cursor · 2026-07-30T21:36:43Z

  return dedent`
    'use strict';
-    const common = require('../../common');
+    const common = require('@node-core/doc-kit/generators/common');


Wrong require in generated tests

High Severity

updateJsRequirePaths now embeds require('@node-core/doc-kit/generators/common') into generated addon test.js files. Those files run under Node.js's test/addons tree and need the relative ../../common helper for common.buildType, so addon verification will fail to resolve the module.

^{Reviewed by Cursor Bugbot for commit 1043c7e. Configure here.}

🤦 Find + Replace always has quirks

AugustinMauroy · 2026-07-31T08:39:00Z

why doc-kittens instead of doc-kit?

avivkeller · 2026-07-31T13:34:21Z

why doc-kittens instead of doc-kit?

doc-kit is taken, and we can't claim it since we don't own a trademark for the term

bmuenzenmeyer · 2026-07-31T14:26:36Z

why doc-kittens instead of doc-kit?

doc-kit is taken, and we can't claim it since we don't own a trademark for the term

Is the goal to move away from @node-core scope to communicate its general availability? Cause I don't know if that's worth it. I don't recall if all of this was discussed earlier, or if consensus was reached. Apologies for missing it

edit: #343 was the voted name. I understand the dynamics of the scope and ownership...

edit:

I'd prefer

- `@node-core/doc-kit-legacy` (`legacy-*`)
- `@node-core/doc-kit-react` (`orama-db`, `web` TBR `react-html`, `jsx-ast`)
- `@node-core/doc-kit-web` (`sitemap`, `llms-txt`)
- `@node-core/doc-kit-internal` (`ast-*`, `metadata`)
- `@node-core/doc-kit-extras` (Everything else)

Is this open for revisiting.

avivkeller · 2026-07-31T15:19:55Z

Is the goal to move away from @node-core scope to communicate its general availability

The goal is to put generators in their own scope to avoid cluttering the core scope.

bmuenzenmeyer · 2026-07-31T16:01:47Z

is there such a thing as cluttering? you cannot really see all packages in a scope - i can see them at https://npmx.dev/org/node-core but couldnt figure out an npmjs way to do this. adding a new scope increases our support footprint...

what about @nodejs per nodejs/TSC#1178 and https://github.com/nodejs/admin/blob/main/package-namespace-migration.md

avivkeller · 2026-07-31T16:06:14Z

is there such a thing as cluttering? you cannot really see all packages in a scope - i can see them at npmx.dev/org/node-core but couldnt figure out an npmjs way to do this. adding a new scope increases our support footprint...

https://www.npmjs.com/org/node-core

what about @nodejs per nodejs/TSC#1178 and nodejs/admin@main/package-namespace-migration.md

Sounds good to me, just need to name the packages something like doc-kit-web, etc

ovflowd · 2026-08-01T10:38:54Z

And finally, the remaining Node.js-specific generators are now in @doc-kittens/node

I wonder if people could mistake this as being @doc-kittens repackage FOR nodejs, instead of specific TO nodejs. I feel these should be actually under @node-core/doc-kittens or something @node-core as it is Node.js's specific and not for outer world usage, wdyt?

Copilot

🟡 Not ready to approve

There are multiple concrete breakages/inconsistencies (missing @doc-kittens/node package manifest/exports, a runtime-invalid require() target, and an extractExports logic bug) that must be addressed before this can safely ship.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (3)

packages/node/src/addon-verify/utils/generateFileList.mjs:12

@node-core/doc-kit/generators/common does not exist in this repo's @node-core/doc-kit package exports (there is no packages/core/src/generators/common), so generated test.js files will fail at runtime when required. Revert to the original relative Node.js test harness import (or introduce and export a real replacement module).
README.md:101
The redesigned docs example now uses -t html, but the preceding sentence still says to use the web generator; this is confusing given the new html target name (with web being an alias). Update the text to match the command shown.

  -t html \

.changeset/node-kitten-package.md:3

This changeset marks @node-core/doc-kit as a minor bump, but this PR removes previously exported subpaths like @node-core/doc-kit/man-page, @node-core/doc-kit/api-links, and @node-core/doc-kit/addon-verify from packages/core/package.json, which is a breaking change for consumers. Either keep compatibility exports/re-exports, or bump @node-core/doc-kit to a major release.

'@doc-kittens/node': major
'@node-core/doc-kit': minor
---

Files reviewed: 13/40 changed files
Comments generated: 1
Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

+  'man-page': '@doc-kittens/node/man-page',
  'legacy-json': '@doc-kittens/legacy/legacy-json',
  'legacy-json-all': '@doc-kittens/legacy/legacy-json-all',
-  'addon-verify': '@node-core/doc-kit/addon-verify',
-  'api-links': '@node-core/doc-kit/api-links',
+  'addon-verify': '@doc-kittens/node/addon-verify',
+  'api-links': '@doc-kittens/node/api-links',


cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 59787df. Configure here.}

cursor · 2026-08-01T15:28:19Z

      'www/out',
      'out/',
-      'packages/core/src/generators/api-links/__tests__/fixtures/',
+      'packages/node/src/api-links/__tests__/fixtures/',


Stale Prettier ignore path

Medium Severity

The ESLint ignore for api-links fixtures was updated to packages/node/..., but .prettierignore still points at packages/core/src/generators/api-links/__tests__/fixtures/. Those fixtures are intentionally non-Prettier-shaped, so format:check in CI can fail now that they are no longer ignored.

^{Reviewed by Cursor Bugbot for commit 59787df. Configure here.}

Copilot AI review requested due to automatic review settings July 30, 2026 21:30

Copilot AI reviewed Jul 30, 2026

vercel Bot deployed to Preview – api-docs-tooling July 30, 2026 21:31 View deployment

avivkeller marked this pull request as ready for review July 30, 2026 21:34

avivkeller requested a review from a team as a code owner July 30, 2026 21:34

cursor Bot reviewed Jul 30, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 1, 2026 10:36

ovflowd force-pushed the refactor/node-kitten branch from 1043c7e to b654f0d Compare August 1, 2026 10:36

Copilot started reviewing on behalf of ovflowd August 1, 2026 10:36 View session

vercel Bot deployed to Preview – api-docs-tooling August 1, 2026 10:37 View deployment

ovflowd approved these changes Aug 1, 2026

View reviewed changes

Copilot AI reviewed Aug 1, 2026

View reviewed changes

refactor(node): extract @doc-kittens/node package

59787df

avivkeller force-pushed the refactor/node-kitten branch from b654f0d to 59787df Compare August 1, 2026 15:26

vercel Bot deployed to Preview – api-docs-tooling August 1, 2026 15:27 View deployment

cursor Bot reviewed Aug 1, 2026

View reviewed changes

Uh oh!

Conversation

avivkeller commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cursor Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

cursor Bot Jul 30, 2026

Choose a reason for hiding this comment

Wrong require in generated tests

Uh oh!

avivkeller Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AugustinMauroy commented Jul 31, 2026

Uh oh!

avivkeller commented Jul 31, 2026

Uh oh!

bmuenzenmeyer commented Jul 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avivkeller commented Jul 31, 2026

Uh oh!

bmuenzenmeyer commented Jul 31, 2026

Uh oh!

avivkeller commented Jul 31, 2026

Uh oh!

ovflowd commented Aug 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Not ready to approve

Suppressed comments (3)

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Aug 1, 2026

Choose a reason for hiding this comment

Stale Prettier ignore path

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

avivkeller commented Jul 30, 2026 •

edited

Loading

vercel Bot commented Jul 30, 2026 •

edited

Loading

codecov Bot commented Jul 30, 2026 •

edited

Loading

cursor Bot commented Jul 30, 2026 •

edited

Loading

bmuenzenmeyer commented Jul 31, 2026 •

edited

Loading