fix(legacy-json): preserve source subdirectories in output paths

[shivxmsharma]

Description

Right now legacy-json writes every file straight into the output root and names it after the generated api slug, so a doc like path/to/file.md ends up as path-to-file.json instead of path/to/file.json. The folder structure of the source docs gets flattened.

There were two reasons for this in src/generators/legacy-json/generate.mjs:

1. The output filename was built from section.api. That value is a slug (created in metadata/utils/parse.mjs) that deliberately turns path separators into dashes, which is exactly why the subfolders disappear. The real relative path is already available on the head node as head.path ( the same field legacy-html uses ) so I now build a small api → path lookup from the head nodes and use that for the filename.

2. The file was written with writeFile from node:fs/promises, which doesn't create missing folders, so writing into a subfolder would fail even with the right path. I switched to the project's own writeFile from utils/file.mjs, which creates the parent directories first (again, the helper legacy-html already uses).

The change is contained to the write path: processChunk and the yielded sections are untouched, so nothing downstream (like legacy-json-all) is affected.

Validation

Running the generator on a few docs that live in subfolders:

node bin/cli.mjs generate -i "docs/**/*.md" -t legacy-json -o out -v 18.0.0

Before:

out/alpha.json
out/sub-beta.json
out/sub-deepgamma.json

After:

out/alpha.json
out/sub/beta.json
out/sub/deep/gamma.json

The subfolders are preserved and created automatically, and the generated JSON is unchanged otherwise.

If you're reviewing, the thing to check is that the output path now comes from path (via withExt(path, 'json')) instead of section.api, and that writeFile is imported from utils/file.mjs.

node --run test passes for me. The only suites that fail (api-links, jsx-ast, web) fail the exact same way on a clean main, so they're unrelated to this change. node --run lint and node --run format are clean.

One related thing I noticed but left out on purpose: buildSection.mjs builds its source field as doc/api/${head.api}.md (you can see it in the output above as doc/api/sub-deepgamma.md), which has the same slug-vs-path problem for files in subfolders. I kept this PR focused on the output path since that's what the issue is about. Happy to fix source here too or in a follow-up, whichever you'd prefer.

Related Issues

Fixes #838

Check List

• I have read the [Contributing Guidelines](https://github.com/nodejs/doc-kit/blob/main/CONTRIBUTING.md) and made commit messages that follow the guideline.
• I have run node --run test and all tests passed.
• I have check code formatting with node --run format & node --run lint.
• I've covered new added functionality with unit tests if necessary.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 16, 2026 9:07am

[cursor]

PR Summary

Low Risk
Scoped to legacy-json file output paths only; no auth, data, or API contract changes beyond where files land on disk.

Overview
legacy-json now writes each section under the same relative path as its source doc (e.g. sub/deep/gamma.json) instead of flattening everything to slug-named files in the output root.

Output paths are built from each head node’s path via a api → path map and withExt(..., 'json'), replacing filenames derived from section.api (slugs with / turned into dashes). Writes use the shared writeFile from utils/file.mjs, which creates parent directories before writing—matching the approach already used elsewhere (e.g. legacy-html for mkdir behavior, though HTML still names files by api).

processChunk and yielded section shape are unchanged, so downstream consumers like legacy-json-all are unaffected.

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

[codecov]

Codecov Report

❌ Patch coverage is 0% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.56%. Comparing base (3fbb9fb) to head (1c64086).

Files with missing lines	Patch %	Lines
src/generators/legacy-json/generate.mjs	0.00%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #841      +/-   ##
==========================================
- Coverage   84.60%   84.56%   -0.04%     
==========================================
  Files         176      176              
  Lines       15802    15809       +7     
  Branches     1411     1411              
==========================================
  Hits        13369    13369              
- Misses       2423     2430       +7     
  Partials       10       10              

☔ 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.