Skip to content

Commit d711fee

Browse files
flakey5flakey5
committed
feat: json, json-all generators
Closes #214 Signed-off-by: flakey5 <[email protected]>
1 parent a7f0f57 commit d711fee

25 files changed

+3533
-703
lines changed

‎package-lock.json‎

Lines changed: 1096 additions & 702 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,8 @@
6767
"recma-jsx": "^1.0.1",
6868
"rehype-raw": "^7.0.0",
6969
"rehype-recma": "^1.0.0",
70+
"json-schema-to-typescript": "^15.0.4",
71+
"jsonc-parser": "^3.3.1",
7072
"rehype-stringify": "^10.0.1",
7173
"remark-gfm": "^4.0.1",
7274
"remark-parse": "^11.0.0",

‎src/generators/index.mjs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ import manPage from './man-page/index.mjs';
1414
import metadata from './metadata/index.mjs';
1515
import oramaDb from './orama-db/index.mjs';
1616
import web from './web/index.mjs';
17+
import json from './json/index.mjs';
18+
import jsonAll from './json-all/index.mjs';
1719

1820
export const publicGenerators = {
1921
'json-simple': jsonSimple,
@@ -27,6 +29,10 @@ export const publicGenerators = {
2729
'orama-db': oramaDb,
2830
'llms-txt': llmsTxt,
2931
web,
32+
'jsx-ast': jsxAst,
33+
metadata,
34+
json,
35+
'json-all': jsonAll,
3036
};
3137

3238
// These ones are special since they don't produce standard output,

‎src/generators/json-all/index.mjs‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
// @ts-check
2+
'use strict';
3+
4+
import { writeFile } from 'node:fs/promises';
5+
import { join } from 'node:path';
6+
import { DOC_NODE_VERSION } from '../../constants.mjs';
7+
import { generateJsonSchema } from './util/generateJsonSchema.mjs';
8+
9+
// TODO add test w/ https://www.npmjs.com/package/jsonschema
10+
11+
/**
12+
* TODO docs
13+
*
14+
* @typedef {Array<ApiDocMetadataEntry>} Input
15+
*
16+
* @type {GeneratorMetadata<Input, object>}
17+
*/
18+
export default {
19+
name: 'json-all',
20+
21+
// This should be kept in sync with the JSON schema version for this
22+
// generator AND the `json` generator
23+
version: '2.0.0',
24+
25+
description: 'TODO',
26+
27+
dependsOn: 'json',
28+
29+
/**
30+
* Generates a JSON file.
31+
*
32+
* @param {Input} input
33+
* @param {Partial<GeneratorOptions>} param1
34+
* @returns {Promise<object>}
35+
*/
36+
async generate(input, { output }) {
37+
const generatedValue = {
38+
$schema: `https://nodejs.org/docs/${DOC_NODE_VERSION}/api/node-doc-all-schema.jsonc`,
39+
modules: [],
40+
text: [],
41+
};
42+
43+
const propertiesToIgnore = ['$schema', 'source'];
44+
45+
input.forEach(section => {
46+
const copiedSection = {};
47+
48+
Object.keys(section).forEach(key => {
49+
if (!propertiesToIgnore.includes(key)) {
50+
copiedSection[key] = section[key];
51+
}
52+
});
53+
54+
switch (section.type) {
55+
case 'module':
56+
generatedValue.modules.push(copiedSection);
57+
break;
58+
case 'text':
59+
generatedValue.text.push(copiedSection);
60+
break;
61+
default:
62+
throw new TypeError(`unsupported root section type ${section.type}`);
63+
}
64+
});
65+
66+
if (output) {
67+
const schema = generateJsonSchema();
68+
69+
// Write the parsed JSON schema to the output directory
70+
await writeFile(
71+
join(output, 'node-doc-schema.json'),
72+
JSON.stringify(schema)
73+
);
74+
}
75+
76+
return generatedValue;
77+
},
78+
};

‎src/generators/json-all/util/generateJsonSchema.mjs‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// @ts-check
2+
'use strict';
3+
4+
import { DOC_NODE_VERSION } from '../../../constants.mjs';
5+
6+
const JSON_SCHEMA_URL = `https://nodejs.org/docs/${DOC_NODE_VERSION}/api/node-doc-schema.json`;
7+
8+
export const generateJsonSchema = () => ({
9+
$schema: 'http://json-schema.org/draft-07/schema#',
10+
// This should be kept in sync with the generator version for this generator
11+
// AND the `json` generator and schema
12+
$id: '[email protected]', // This should be kept in sync with the generator version.
13+
title: 'Node.js API Documentation Schema (All)',
14+
readOnly: true,
15+
16+
properties: {
17+
modules: {
18+
type: 'array',
19+
items: { $ref: `${JSON_SCHEMA_URL}/#/definitions/Module` },
20+
},
21+
text: {
22+
type: 'array',
23+
items: { $ref: `${JSON_SCHEMA_URL}/#/definitions/Text` },
24+
},
25+
},
26+
});

‎src/generators/json/constants.mjs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
'use strict';
2+
3+
// Grabs the default value if present
4+
export const DEFAULT_EXPRESSION = /^(D|d)efault(s|):$/;
5+
6+
// Grabs the type and description of one of the formats for event types
7+
export const EVENT_TYPE_DESCRIPTION_EXTRACTOR = /{(.*)}(.*)/;

‎src/generators/json/generated.d.ts‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
/* eslint-disable */
2+
/**
3+
* This file was automatically generated by json-schema-to-typescript.
4+
* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
5+
* and run json-schema-to-typescript to regenerate this file.
6+
*/
7+
8+
export type NodeJsAPIDocumentationSchema = DocumentRoot & (Module | Text);
9+
/**
10+
* A JavaScript module.
11+
*/
12+
export type Module = SectionBase & {
13+
type: 'module';
14+
/**
15+
* https://jsdoc.app/tags-module
16+
*/
17+
'@module': string;
18+
/**
19+
* Classes exported from this module.
20+
*/
21+
classes?: Class[];
22+
/**
23+
* Methods exported from this module.
24+
*/
25+
methods?: Method[];
26+
/**
27+
* APIs that are available globally.
28+
*/
29+
globals?: (Class | Method)[];
30+
properties?: Property[];
31+
events?: Event[];
32+
[k: string]: unknown;
33+
};
34+
export type Text = SectionBase;
35+
/**
36+
* Node.js version number
37+
*/
38+
export type NodeCoreVersion = string;
39+
export type Class = SectionBase & {
40+
type: 'class';
41+
'@constructor': MethodSignature[];
42+
methods: Method[];
43+
staticMethods: Method[];
44+
properties: Property[];
45+
events?: Event[];
46+
[k: string]: unknown;
47+
};
48+
/**
49+
* A JavaScript function.
50+
*/
51+
export type Method = SectionBase & {
52+
type: 'method';
53+
signatures: MethodSignature[];
54+
[k: string]: unknown;
55+
};
56+
/**
57+
* A property on a JavaScript object or class.
58+
*/
59+
export type Property = SectionBase & {
60+
type: 'property';
61+
/**
62+
* JavaScript type of the property.
63+
*/
64+
'@type'?: string | [string, ...string[]];
65+
/**
66+
* Is this property modifiable by user code?
67+
*/
68+
mutable?: boolean;
69+
[k: string]: unknown;
70+
};
71+
/**
72+
* An event that can be emitted by the parent object or class.
73+
*/
74+
export type Event = SectionBase & {
75+
type: 'event';
76+
parameters: MethodParameter[];
77+
[k: string]: unknown;
78+
};
79+
80+
/**
81+
* Common properties found at the root of each document.
82+
*/
83+
export interface DocumentRoot {
84+
/**
85+
* The path to the Markdown source used to generate this document. It is relative to the Node.js repository root.
86+
*/
87+
source: string;
88+
[k: string]: unknown;
89+
}
90+
/**
91+
* Common properties found in each section of a document.
92+
*/
93+
export interface SectionBase {
94+
/**
95+
* Type of the section
96+
*/
97+
type: 'module' | 'class' | 'method' | 'property' | 'event' | 'text';
98+
/**
99+
* https://jsdoc.app/tags-name
100+
*/
101+
'@name': string;
102+
/**
103+
* Description of the section.
104+
*/
105+
description?: string;
106+
/**
107+
* https://jsdoc.app/tags-see
108+
*/
109+
'@see'?: string;
110+
/**
111+
* Sections that just hold further text on this section.
112+
*/
113+
text?: Text[];
114+
/**
115+
* https://jsdoc.app/tags-example
116+
*/
117+
'@example'?: string | string[];
118+
/**
119+
* https://jsdoc.app/tags-deprecated
120+
*/
121+
'@deprecated'?: NodeCoreVersion[];
122+
stability?: Stability;
123+
/**
124+
* The changes this API has underwent.
125+
*/
126+
changes?: Change[];
127+
/**
128+
* https://jsdoc.app/tags-since
129+
*/
130+
'@since'?: NodeCoreVersion[];
131+
napiVersion?: number[];
132+
/**
133+
* Versions that this was removed in.
134+
*/
135+
removedIn?: NodeCoreVersion[];
136+
[k: string]: unknown;
137+
}
138+
/**
139+
* Describes the stability of an object.
140+
*/
141+
export interface Stability {
142+
/**
143+
* The stability value.
144+
*/
145+
value: number;
146+
/**
147+
* Textual representation of the stability.
148+
*/
149+
text: string;
150+
[k: string]: unknown;
151+
}
152+
export interface Change {
153+
version: NodeCoreVersion[];
154+
/**
155+
* URL to the PR that introduced this change.
156+
*/
157+
prUrl?: string;
158+
/**
159+
* Description of the change.
160+
*/
161+
description: string;
162+
[k: string]: unknown;
163+
}
164+
export interface MethodSignature {
165+
parameters?: MethodParameter[];
166+
/**
167+
* The method signature's return type.
168+
*/
169+
'@returns'?: string | [string, ...string[]];
170+
[k: string]: unknown;
171+
}
172+
export interface MethodParameter {
173+
/**
174+
* Name of the parameter.
175+
*/
176+
'@name': string;
177+
/**
178+
* Type of the parameter
179+
*/
180+
'@type': string | [string, ...string[]];
181+
description?: string;
182+
/**
183+
* The parameter's default value
184+
*/
185+
'@default'?: string;
186+
[k: string]: unknown;
187+
}

0 commit comments

Comments
 (0)