Skip to content

Commit a4cd425

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

23 files changed

+2255
-100
lines changed

‎package-lock.json

Lines changed: 210 additions & 99 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
@@ -55,6 +55,8 @@
5555
"reading-time": "^1.5.0",
5656
"recma-jsx": "^1.0.0",
5757
"rehype-recma": "^1.0.0",
58+
"json-schema-to-typescript": "^15.0.4",
59+
"jsonc-parser": "^3.3.1",
5860
"rehype-stringify": "^10.0.1",
5961
"remark-gfm": "^4.0.1",
6062
"remark-parse": "^11.0.0",

‎src/generators/index.mjs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ import legacyJsonAll from './legacy-json-all/index.mjs';
1212
import llmsTxt from './llms-txt/index.mjs';
1313
import manPage from './man-page/index.mjs';
1414
import oramaDb from './orama-db/index.mjs';
15+
import json from './json/index.mjs';
16+
import jsonAll from './json-all/index.mjs';
1517

1618
export const publicGenerators = {
1719
'json-simple': jsonSimple,
@@ -25,6 +27,8 @@ export const publicGenerators = {
2527
'orama-db': oramaDb,
2628
'llms-txt': llmsTxt,
2729
'jsx-ast': jsxAst,
30+
json,
31+
'json-all': jsonAll,
2832
};
2933

3034
export const allGenerators = {

‎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: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
'use strict';

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

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

0 commit comments

Comments
 (0)