feat(json): add JSON generators - #1079
Open
avivkeller wants to merge 2 commits into
Open
avivkeller wants to merge 2 commits into
avivkeller wants to merge 2 commits into
Conversation
Co-Authored-By: flakey5 <73616808+flakey5@users.noreply.github.com> Signed-off-by: avivkeller <me@aviv.sh>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #1079 +/- ##
==========================================
- Coverage 90.57% 89.74% -0.83%
==========================================
Files 217 245 +28
Lines 20755 22791 +2036
Branches 1969 2160 +191
==========================================
+ Hits 18799 20454 +1655
- Misses 1949 2328 +379
- Partials 7 9 +2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Contributor
|
| File | Main | PR | Change |
|---|---|---|---|
orama-db.json |
9.26 MB | 9.26 MB | -1.00 B (-0.0%) |
Performance estimate (single CI run)
- Generation time: 18.0% faster (6.85 s → 5.62 s)
- Peak memory: 2.4% higher (1.84 GB → 1.88 GB)
web Generator
Output size: 61 files changed · net +106.00 B
File size details
| File | Main | PR | Change |
|---|---|---|---|
assets/SearchBox-Wv1oNrZ4.js |
84.77 KB | — | -84.77 KB (-100.0%) |
assets/SearchBox-BL8dXwTL.js |
— | 84.77 KB | +84.77 KB |
assets/dist-ClZxiFIR.js |
30.43 KB | — | -30.43 KB (-100.0%) |
assets/dist-CzAzC9z0.js |
— | 30.43 KB | +30.43 KB |
assets/SideBar-BxtRyUC0.js |
25.62 KB | — | -25.62 KB (-100.0%) |
assets/SideBar-C7cAmuh_.js |
— | 25.62 KB | +25.62 KB |
assets/client-BnRwar35.js |
21.61 KB | — | -21.61 KB (-100.0%) |
assets/client-BxHMcFum.js |
— | 21.61 KB | +21.61 KB |
assets/config-B5W8Tt3j.js |
18.12 KB | — | -18.12 KB (-100.0%) |
assets/config-IkLyzSmT.js |
— | 18.12 KB | +18.12 KB |
assets/Combination-BoaLz8yJ.js |
16.13 KB | — | -16.13 KB (-100.0%) |
assets/Combination-Zb_wbksL.js |
— | 16.13 KB | +16.13 KB |
assets/ThemeToggle-C9uyg7p4.js |
13.63 KB | — | -13.63 KB (-100.0%) |
assets/ThemeToggle-HeB5GDg3.js |
— | 13.63 KB | +13.63 KB |
assets/dist-B8D6tfAu.js |
10.20 KB | — | -10.20 KB (-100.0%) |
assets/dist-BTd5CAIn.js |
— | 10.20 KB | +10.20 KB |
assets/Layout-Bnj5_xHZ.js |
10.13 KB | — | -10.13 KB (-100.0%) |
assets/Layout-CQlDKFf0.js |
— | 10.13 KB | +10.13 KB |
assets/compat-Cs2UD7dR.js |
10.12 KB | — | -10.12 KB (-100.0%) |
assets/compat-Cad6KQmt.js |
— | 10.12 KB | +10.12 KB |
assets/Tooltip-CBOa1hvu.js |
7.93 KB | — | -7.93 KB (-100.0%) |
assets/Tooltip-Cv_49yBV.js |
— | 7.93 KB | +7.93 KB |
assets/dist-BdgOfsvK.js |
6.99 KB | — | -6.99 KB (-100.0%) |
assets/dist-DehGet4Y.js |
— | 6.99 KB | +6.99 KB |
assets/jsx-runtime-CQg_ZAC-.js |
5.67 KB | — | -5.67 KB (-100.0%) |
assets/jsx-runtime-DvG5qREu.js |
— | 5.67 KB | +5.67 KB |
assets/dist-BL39aKkE.js |
3.94 KB | — | -3.94 KB (-100.0%) |
assets/dist-Bgf0Jnzs.js |
— | 3.94 KB | +3.94 KB |
assets/CodeTabs-61XaHhAc.js |
3.88 KB | — | -3.88 KB (-100.0%) |
assets/CodeTabs-DYc8I65q.js |
— | 3.88 KB | +3.88 KB |
assets/CodeBox-QEyvaIRE.js |
3.44 KB | — | -3.44 KB (-100.0%) |
assets/CodeBox-DOtdsEwP.js |
— | 3.44 KB | +3.44 KB |
assets/hooks.module-B1PJ03KC.js |
3.37 KB | — | -3.37 KB (-100.0%) |
assets/hooks.module-CYyVbMul.js |
— | 3.37 KB | +3.37 KB |
assets/FunctionSignature-D5ExS4CH.js |
2.28 KB | — | -2.28 KB (-100.0%) |
assets/FunctionSignature-C1lpWimx.js |
— | 2.28 KB | +2.28 KB |
assets/Banner-BKhErV47.js |
2.19 KB | — | -2.19 KB (-100.0%) |
assets/Banner-BK3FKvcZ.js |
— | 2.19 KB | +2.19 KB |
assets/ChangeHistory-DBGsX4Ax.js |
1.75 KB | — | -1.75 KB (-100.0%) |
assets/ChangeHistory-AUxDHeXU.js |
— | 1.75 KB | +1.75 KB |
assets/DataTag-Ddiwy3uh.js |
844.00 B | — | -844.00 B (-100.0%) |
assets/DataTag-DuDOJ4sg.js |
— | 844.00 B | +844.00 B |
assets/DocumentationIndex-Da_NytUD.js |
833.00 B | — | -833.00 B (-100.0%) |
assets/DocumentationIndex-CorDpbbO.js |
— | 833.00 B | +833.00 B |
assets/ArrowUpRightIcon-CtDpVK61.js |
618.00 B | — | -618.00 B (-100.0%) |
assets/ArrowUpRightIcon-BsMpTR54.js |
— | 618.00 B | +618.00 B |
assets/Badge-31CvtEtL.js |
607.00 B | — | -607.00 B (-100.0%) |
assets/Badge-CgKXSSuQ.js |
— | 607.00 B | +607.00 B |
assets/AlertBox-C46fHV9T.js |
591.00 B | — | -591.00 B (-100.0%) |
assets/AlertBox-CLWqAN63.js |
— | 591.00 B | +591.00 B |
assets/CodeBracketIcon-DvMuvH1Z.js |
512.00 B | — | -512.00 B (-100.0%) |
assets/CodeBracketIcon-27W66IwF.js |
— | 512.00 B | +512.00 B |
assets/dist-DIQNjpog.js |
477.00 B | — | -477.00 B (-100.0%) |
assets/dist-DQ-NNaqQ.js |
— | 477.00 B | +477.00 B |
assets/ChevronDownIcon-B4BCs7rb.js |
468.00 B | — | -468.00 B (-100.0%) |
assets/ChevronDownIcon-A4vTqgoN.js |
— | 468.00 B | +468.00 B |
assets/Blockquote-DOJx39qt.js |
167.00 B | — | -167.00 B (-100.0%) |
assets/Blockquote-BR5wxS3q.js |
— | 167.00 B | +167.00 B |
all.html |
32.21 MB | 32.22 MB | +106.00 B (+0.0%) |
assets/withIsland-ETxmTyke.js |
105.00 B | — | -105.00 B (-100.0%) |
assets/withIsland-JV_aVfKY.js |
— | 105.00 B | +105.00 B |
Performance estimate (single CI run)
- Generation time: 19.7% slower (69.00 s → 82.56 s)
- Peak memory: 14.9% lower (6.11 GB → 5.20 GB)
🚀 Deploying Preview to Cloudflare 🚀Preview Deployments by commit
|
|
|
||
| // Where a version of the bundle's schema is published. | ||
| export const SCHEMA_URL = | ||
| 'https://doc-kit.nodejs.org/schemas/api-doc-all/{schemaVersion}.json'; |
Member
There was a problem hiding this comment.
IMO we should generate that and give it with the generated artifact so a built can be served independently
Member
Author
There was a problem hiding this comment.
They are welcome to export the artifact from the source code and host it independently, we also, by default, host our schema
Member
Author
|
Bump @nodejs/web for reviews |
Member
There was a problem hiding this comment.
can we have an other fixtures thats look like deprecation.
I use this script that read json so I would like to see output of such as file https://github.com/brunocroh/node-deprecations-pretty
Member
There was a problem hiding this comment.
we should include the ts file link
Member
|
@avivkeller reviews on this will take a bit of time, this PR touchjes 68 files, it is... expected for this to... be complex to review 🙇 |
Member
Author
|
Bump! |
ovflowd
reviewed
Sep 19, 2026
| import { readFile } from 'node:fs/promises'; | ||
| import { describe, it } from 'node:test'; | ||
|
|
||
| import Ajv from 'ajv'; |
Member
There was a problem hiding this comment.
I assume this is a test-only (dev) dependency, right?
ovflowd
reviewed
Sep 19, 2026
| /** | ||
| * A heading that documents no API entry: prose, a deprecation, a command-line option. | ||
| */ | ||
| export type SectionNode = Entry & |
Member
There was a problem hiding this comment.
Can you use interface in these scenarios (SectionNode, ClassNode, ConstructionNode...), so we do use extends?
Member
There was a problem hiding this comment.
(I know this is generated, but wondering why a generated schema lives on git hmmm)
ovflowd
reviewed
Sep 19, 2026
| // with no shallower heading before it) is treated as a child of it | ||
| const roots = buildHierarchy(entries); | ||
| const root = roots.find(node => node.entry === head) ?? roots[0]; | ||
| const children = [ |
Member
There was a problem hiding this comment.
nit: assign const for each one of these things instead of several assignment + spreads
ovflowd
reviewed
Sep 19, 2026
| introducedIn: | ||
| head.introduced_in == null ? null : String(head.introduced_in), | ||
| sourceLink: head.source_link | ||
| ? { |
Member
There was a problem hiding this comment.
nit: fn just for generating this sourceLink property
ovflowd
reviewed
Sep 19, 2026
| body: body.toSpliced( | ||
| index, | ||
| 1, | ||
| ...(rest.length ? [{ ...list, children: rest }] : []) |
ovflowd
reviewed
Sep 19, 2026
|
|
||
| if ( | ||
| kind === 'class' && | ||
| !items.some(item => extractListItem(item).prefix === 'Extends') |
Member
There was a problem hiding this comment.
How many items can be in this Array? .some is not that performant...
ovflowd
reviewed
Sep 19, 2026
| * @param {Array<import('mdast').ListItem>} items The entry's typed list items | ||
| * @returns {{ properties: object, description?: string }} | ||
| */ | ||
| const kindProperties = (kind, entry, items) => { |
Member
There was a problem hiding this comment.
I wonder if instead of a switch we could use a factory, might be overkill, but better specified and controled/standardized.
ovflowd
reviewed
Sep 19, 2026
| removed, | ||
| napiVersion, | ||
| changes, | ||
| ...properties, |
Member
There was a problem hiding this comment.
Why the spread happens before a speciifc item? It'd be good to know what could be accidentally overridden here and that it is fragile that it needs to be in a speciific position.
ovflowd
reviewed
Sep 19, 2026
| const [item] = items.map(extractListItem); | ||
|
|
||
| return item | ||
| ? { |
Member
There was a problem hiding this comment.
I know it might not sound practical, but could you remove the ternary and make it like below (easier to read)
if (item) {
return { ... }
}
return { type: null, ... }
ovflowd
reviewed
Sep 19, 2026
| * @returns {import('../types').Type | null} | ||
| */ | ||
| export const toType = node => | ||
| node |
Member
There was a problem hiding this comment.
same here... this is the sort of situation I'd rather NOT use a ternary
ovflowd
reviewed
Sep 19, 2026
| export const DISPLAY_NAME = /displayName="([^"]*)"/; | ||
|
|
||
| // A rest parameter's marker | ||
| export const REST_MARKER = /^\.\.\./; |
Member
There was a problem hiding this comment.
Are these RegEx's available elsewhere? Are these duplication of already existing RegEx's?
ovflowd
reviewed
Sep 19, 2026
| export const SECTION_KIND = 'section'; | ||
|
|
||
| // The kinds whose leading typed list is lifted out of the body as data | ||
| export const KINDS_WITH_TYPED_LIST = new Set([ |
Member
There was a problem hiding this comment.
Also wondering if this is already defined elsewhere
ovflowd
reviewed
Sep 19, 2026
| const match = QUERIES.stabilityIndex.exec(text); | ||
| const start = match ? text.length - match[2].length : 0; | ||
|
|
||
| return slice(node, start, undefined, { |
Member
There was a problem hiding this comment.
nit: instead .node -> const { node } =
ovflowd
reviewed
Sep 19, 2026
|
|
||
| return compile(schema, 'Document', { | ||
| bannerComment: | ||
| '/* eslint-disable */\n' + |
ovflowd
reviewed
Sep 19, 2026
| "eslint-plugin-react-x": "5.18.1", | ||
| "globals": "~17.7.0", | ||
| "husky": "9.1.7", | ||
| "json-schema-to-typescript": "^16.0.0", |
Member
There was a problem hiding this comment.
yet another package... At least it is a dev one, so Node.js consuming doc-kit won't use it right?
ovflowd
reviewed
Sep 19, 2026
ovflowd
left a comment
ovflowd
left a comment
Member
There was a problem hiding this comment.
Looking really good. Left a few comments, I left out more specific nits, to let this move forward. If you could address my current comments I believe I'm good with a ✔️
Member
|
Can you also rebase, @avivkeller? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is meant to supersede #287 and fix #214.
The majority of the added lines are test fixtures and schemas, so do not be alarmed by the size of this PR.
This new generator writes one JSON document per source file. Each document
is a tree of the file's headings, in document order, with the metadata,
signature or type, Markdown body, and code examples of every one of them.
The output is described by a JSON schema, published at the URL every document
carries in
$schema, and shipped with the package as@doc-kit/core/generators/json/schema.json.An output looks roughly like:
{ "$schema": "https://doc-kit.nodejs.org/schemas/api-doc/1.0.0.json", "id": "fs", "path": "/fs", "type": "module", "module": "fs", "title": "File system", "introducedIn": "v0.10.0", "sourceLink": { "path": "lib/fs.js", "url": "https://github.com/nodejs/node/blob/HEAD/lib/fs.js" }, "stability": { "index": "2","description": "Stable" }, "added": [], "deprecated": [], "removed": [], "napiVersion": [], "changes": [], "description": "The `node:fs` module enables interacting with the file system in a\nway modeled on standard POSIX functions.\n\n…", "summary": "The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions.", "examples": [], "children": [] }