Skip to content

Commit 1bcf93d

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

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+5739
-466
lines changed

.c8rc.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"**/fixtures",
66
"src/generators/legacy-html/assets",
77
"src/generators/web/ui",
8-
"**/*.d.ts"
8+
"**/*.d.ts",
9+
"tools/"
910
]
1011
}

npm-shrinkwrap.json

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

package.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@
3434
"eslint-plugin-import-x": "^4.16.1",
3535
"eslint-plugin-jsdoc": "^61.1.12",
3636
"husky": "^9.1.7",
37+
"json-schema-to-typescript": "^15.0.4",
38+
"jsonschema": "^1.5.0",
3739
"lint-staged": "^16.2.6",
3840
"prettier": "3.6.2"
3941
},
@@ -58,6 +60,7 @@
5860
"globals": "^16.4.0",
5961
"hast-util-to-string": "^3.0.1",
6062
"hastscript": "^9.0.1",
63+
"jsonc-parser": "^3.3.1",
6164
"lightningcss": "^1.30.1",
6265
"mdast-util-slice-markdown": "^2.0.1",
6366
"preact": "^10.27.2",

src/generators/index.mjs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
import addonVerify from './addon-verify/index.mjs';
44
import apiLinks from './api-links/index.mjs';
55
import astJs from './ast-js/index.mjs';
6+
import json from './json/index.mjs';
7+
import jsonAll from './json-all/index.mjs';
68
import jsonSimple from './json-simple/index.mjs';
79
import jsxAst from './jsx-ast/index.mjs';
810
import legacyHtml from './legacy-html/index.mjs';
@@ -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,
Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
import assert from 'node:assert';
2+
import { join } from 'node:path';
3+
import { test } from 'node:test';
4+
5+
import { Validator } from 'jsonschema';
6+
import { SemVer } from 'semver';
7+
8+
import createGenerator from '../../../generators.mjs';
9+
import createMarkdownLoader from '../../../loaders/markdown.mjs';
10+
import createMarkdownParser from '../../../parsers/markdown.mjs';
11+
import { generateJsonSchema } from '../util/generateJsonSchema.mjs';
12+
13+
const FIXTURES_DIR = join(
14+
import.meta.dirname,
15+
'..',
16+
'json',
17+
'__tests__',
18+
'fixtures'
19+
);
20+
21+
const loader = createMarkdownLoader();
22+
const parser = createMarkdownParser();
23+
24+
test('generator output complies with json schema', async () => {
25+
const validator = new Validator();
26+
27+
const version = 'v1.2.3';
28+
29+
/**
30+
* @type {object}
31+
*/
32+
const schema = generateJsonSchema(version);
33+
34+
const input = [
35+
join(FIXTURES_DIR, 'text-doc.md'),
36+
join(FIXTURES_DIR, 'module.md'),
37+
];
38+
const files = await loader.loadFiles(input);
39+
const docs = await parser.parseApiDocs(files);
40+
41+
const { runGenerators } = createGenerator(docs);
42+
43+
const result = await runGenerators({
44+
generators: ['json-all'],
45+
input,
46+
output: undefined,
47+
version: new SemVer('v1.2.3'),
48+
releases: [],
49+
gitRef: 'a'.repeat(40),
50+
threads: 1,
51+
typeMap: {},
52+
});
53+
54+
assert.ok(validator.validate(result, schema).valid);
55+
});

src/generators/json-all/index.mjs

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
// @ts-check
2+
'use strict';
3+
4+
import { writeFile } from 'node:fs/promises';
5+
import { join } from 'node:path';
6+
7+
import { DOC_NODE_VERSION } from '../../constants.mjs';
8+
import { generateJsonSchema } from './util/generateJsonSchema.mjs';
9+
10+
/**
11+
* This generator is responsible for collecting the JSON output generated by
12+
* the `json` generator into a single JSON file.
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:
26+
'This generator is responsible for collecting the JSON output generated by the `json` generator into a single JSON file.',
27+
28+
dependsOn: 'json',
29+
30+
/**
31+
* Generates a JSON file.
32+
*
33+
* @param {Input} input
34+
* @param {Partial<GeneratorOptions>} param1
35+
* @returns {Promise<object>}
36+
*/
37+
async generate(input, { version, output }) {
38+
const generatedValue = {
39+
$schema: `https://nodejs.org/docs/${DOC_NODE_VERSION}/api/node-doc-all-schema.jsonc`,
40+
modules: [],
41+
text: [],
42+
};
43+
44+
const propertiesToIgnore = ['$schema', 'source'];
45+
46+
input.forEach(section => {
47+
const copiedSection = {};
48+
49+
Object.keys(section).forEach(key => {
50+
if (!propertiesToIgnore.includes(key)) {
51+
copiedSection[key] = section[key];
52+
}
53+
});
54+
55+
switch (section.type) {
56+
case 'module':
57+
generatedValue.modules.push(copiedSection);
58+
break;
59+
case 'text':
60+
generatedValue.text.push(copiedSection);
61+
break;
62+
default:
63+
throw new TypeError(`unsupported root section type ${section.type}`);
64+
}
65+
});
66+
67+
if (output) {
68+
const schema = generateJsonSchema(version);
69+
70+
// Write the parsed JSON schema to the output directory
71+
await writeFile(
72+
join(output, 'node-doc-schema.json'),
73+
JSON.stringify(schema)
74+
);
75+
}
76+
77+
return generatedValue;
78+
},
79+
};
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
'use strict';
2+
3+
import jsonAll from '../index.mjs';
4+
5+
/**
6+
* @param {string} version
7+
*/
8+
export function generateJsonSchema(version) {
9+
const jsonSchemaUrl = `https://nodejs.org/docs/${version}/api/node-doc-schema.json`;
10+
11+
return {
12+
$schema: 'http://json-schema.org/draft-07/schema#',
13+
$id: `nodejs-api-doc-all@v${jsonAll.version}`,
14+
title: 'Node.js API Documentation Schema (All)',
15+
readOnly: true,
16+
17+
properties: {
18+
modules: {
19+
type: 'array',
20+
items: { $ref: `${jsonSchemaUrl}/#/definitions/Module` },
21+
},
22+
text: {
23+
type: 'array',
24+
items: { $ref: `${jsonSchemaUrl}/#/definitions/Text` },
25+
},
26+
},
27+
};
28+
}
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Module
2+
3+
<!-- introduced_in=v20.0.0 -->
4+
<!-- source_link=lib/module.js -->
5+
6+
> Stability: 2 - Stable
7+
8+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
9+
10+
Nulla sagittis pulvinar lacus et venenatis. Morbi eget varius sem, a rutrum velit. Vestibulum placerat vehicula felis. Proin et porttitor augue. Sed feugiat urna sit amet euismod posuere. Phasellus quis pretium velit. Integer porta ut velit ac consectetur. Pellentesque venenatis leo et volutpat dapibus. Nam consectetur quam venenatis feugiat tempus. Curabitur semper fringilla felis.
11+
12+
Donec sed est at nulla lacinia suscipit id id neque. Cras quis risus a risus mattis consectetur ut ut ex. Cras non metus a orci facilisis laoreet. Sed eu nisi sit amet mauris iaculis placerat. Nullam interdum, lectus sed convallis tristique, nibh nibh ullamcorper leo, non vehicula metus elit a nisl. Donec eros felis, ornare eget tempor nec, egestas mattis elit. Integer semper purus at risus pretium, in tristique ipsum tristique.
13+
14+
```mjs
15+
import { something } from 'node:something';
16+
```
17+
18+
## text section
19+
20+
<!-- YAML
21+
changes:
22+
- version: v3.0.0
23+
pr-url: https://github.com/nodejs/node/pull/1234
24+
description: asdf
25+
-->
26+
27+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
28+
29+
Nulla sagittis pulvinar lacus et venenatis. Morbi eget varius sem, a rutrum velit. Vestibulum placerat vehicula felis. Proin et porttitor augue. Sed feugiat urna sit amet euismod posuere. Phasellus quis pretium velit. Integer porta ut velit ac consectetur. Pellentesque venenatis leo et volutpat dapibus. Nam consectetur quam venenatis feugiat tempus. Curabitur semper fringilla felis.
30+
31+
Donec sed est at nulla lacinia suscipit id id neque. Cras quis risus a risus mattis consectetur ut ut ex. Cras non metus a orci facilisis laoreet. Sed eu nisi sit amet mauris iaculis placerat. Nullam interdum, lectus sed convallis tristique, nibh nibh ullamcorper leo, non vehicula metus elit a nisl. Donec eros felis, ornare eget tempor nec, egestas mattis elit. Integer semper purus at risus pretium, in tristique ipsum tristique.
32+
33+
## Class: `Something`
34+
35+
<!-- YAML
36+
added:
37+
- v15.7.0
38+
- v14.18.0
39+
changes:
40+
- version:
41+
- v18.0.0
42+
- v16.17.0
43+
pr-url: https://github.com/nodejs/node/pull/1234
44+
description: No longer experimental.
45+
-->
46+
47+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
48+
49+
### `new something.Something([sources[, options]])`
50+
51+
- `sources` {string\[]|object} something something bla bla bla
52+
- `options` {object} something something bla bla bla
53+
- `optionA` {boolean} asdf
54+
- `bla` qwerty
55+
56+
### `something.doThing()`
57+
58+
- Returns: {Promise}
59+
60+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
61+
62+
### Static method: `something.doStaticThing()`
63+
64+
- Returns: {Promise}
65+
66+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
67+
68+
### Event: `somethingHappened`
69+
70+
- `thing` {string} thing that happened
71+
- `how` {string|object} bla
72+
73+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Hello world
2+
3+
<!-- type=misc -->
4+
5+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
6+
7+
## abc123
8+
9+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
10+
11+
Nulla sagittis pulvinar lacus et venenatis. Morbi eget varius sem, a rutrum velit. Vestibulum placerat vehicula felis. Proin et porttitor augue. Sed feugiat urna sit amet euismod posuere. Phasellus quis pretium velit. Integer porta ut velit ac consectetur. Pellentesque venenatis leo et volutpat dapibus. Nam consectetur quam venenatis feugiat tempus. Curabitur semper fringilla felis.
12+
13+
Donec sed est at nulla lacinia suscipit id id neque. Cras quis risus a risus mattis consectetur ut ut ex. Cras non metus a orci facilisis laoreet. Sed eu nisi sit amet mauris iaculis placerat. Nullam interdum, lectus sed convallis tristique, nibh nibh ullamcorper leo, non vehicula metus elit a nisl. Donec eros felis, ornare eget tempor nec, egestas mattis elit. Integer semper purus at risus pretium, in tristique ipsum tristique.
14+
15+
Nulla ultrices venenatis ex, vitae ullamcorper dui pulvinar non. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vivamus fermentum, metus in blandit hendrerit, lorem urna interdum lacus, nec pretium turpis justo eget est. Cras tincidunt urna vel massa ultrices ultrices. Vivamus ullamcorper leo at nulla semper, ac vehicula nisl fringilla. Curabitur viverra vulputate tristique. Donec lorem erat, ornare sit amet faucibus id, mattis vel diam. Ut posuere sem laoreet augue tristique, eget volutpat leo malesuada. Nullam non velit mattis, pulvinar sem eu, vehicula purus. Proin placerat accumsan porttitor. Duis pharetra facilisis aliquet. Suspendisse blandit a nulla eget gravida. Etiam molestie porttitor sodales. Donec lobortis pretium sollicitudin. [asd](https://github.com/nodejs/node)
16+
17+
### asd
18+
19+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
20+
21+
Nulla sagittis pulvinar lacus et venenatis. Morbi eget varius sem, a rutrum velit. Vestibulum placerat vehicula felis. Proin et porttitor augue. Sed feugiat urna sit amet euismod posuere. Phasellus quis pretium velit. Integer porta ut velit ac consectetur. Pellentesque venenatis leo et volutpat dapibus. Nam consectetur quam venenatis feugiat tempus. Curabitur semper fringilla felis.
22+
23+
- lorem
24+
- ipsum
25+
26+
```c++
27+
int main() {
28+
std::cout << "blahaj\n";
29+
return 0;
30+
}
31+
```
32+
33+
## lorem
34+
35+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla aliquet est sit amet nisi iaculis ornare. Donec eu orci condimentum, semper quam ut, luctus nisl. Aliquam vel erat efficitur, egestas justo a, accumsan mauris. Quisque scelerisque enim rhoncus ornare iaculis. Sed commodo, sem ac accumsan posuere, sapien magna eleifend massa, sit amet rhoncus sem diam quis nulla. Donec feugiat elit a tellus hendrerit congue quis bibendum urna. Pellentesque mollis tincidunt tortor, in lobortis ex fringilla a.
36+
37+
Nulla sagittis pulvinar lacus et venenatis. Morbi eget varius sem, a rutrum velit. Vestibulum placerat vehicula felis. Proin et porttitor augue. Sed feugiat urna sit amet euismod posuere. Phasellus quis pretium velit. Integer porta ut velit ac consectetur. Pellentesque venenatis leo et volutpat dapibus. Nam consectetur quam venenatis feugiat tempus. Curabitur semper fringilla felis.
38+
39+
Donec sed est at nulla lacinia suscipit id id neque. Cras quis risus a risus mattis consectetur ut ut ex. Cras non metus a orci facilisis laoreet. Sed eu nisi sit amet mauris iaculis placerat. Nullam interdum, lectus sed convallis tristique, nibh nibh ullamcorper leo, non vehicula metus elit a nisl. Donec eros felis, ornare eget tempor nec, egestas mattis elit. Integer semper purus at risus pretium, in tristique ipsum tristique.
40+
41+
Fusce pretium tincidunt dolor sit amet dignissim. Aliquam egestas purus sed lorem feugiat faucibus. Aenean eget augue non velit maximus tempor cursus eget augue. Suspendisse id laoreet felis. Integer consectetur scelerisque turpis, eu dapibus diam. Etiam ut tempus massa, vel euismod ipsum. Suspendisse quis nisl sapien. Etiam sed euismod dui. Nulla fermentum fringilla dignissim. In mauris ex, iaculis at arcu et, gravida sodales erat.
42+
43+
Nulla ultrices venenatis ex, vitae ullamcorper dui pulvinar non. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vivamus fermentum, metus in blandit hendrerit, lorem urna interdum lacus, nec pretium turpis justo eget est. Cras tincidunt urna vel massa ultrices ultrices. Vivamus ullamcorper leo at nulla semper, ac vehicula nisl fringilla. Curabitur viverra vulputate tristique. Donec lorem erat, ornare sit amet faucibus id, mattis vel diam. Ut posuere sem laoreet augue tristique, eget volutpat leo malesuada. Nullam non velit mattis, pulvinar sem eu, vehicula purus. Proin placerat accumsan porttitor. Duis pharetra facilisis aliquet. Suspendisse blandit a nulla eget gravida. Etiam molestie porttitor sodales. Donec lobortis pretium sollicitudin.
Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
import assert from 'node:assert';
2+
import { join } from 'node:path';
3+
import { describe, test, before } from 'node:test';
4+
5+
import { Validator } from 'jsonschema';
6+
import { parse as jsoncParse } from 'jsonc-parser';
7+
import { SemVer } from 'semver';
8+
9+
import createGenerator from '../../../generators.mjs';
10+
import createMarkdownLoader from '../../../loaders/markdown.mjs';
11+
import createMarkdownParser from '../../../parsers/markdown.mjs';
12+
import { parseSchema } from '../utils/parseSchema.mjs';
13+
import { readFile } from 'node:fs/promises';
14+
import json from '../index.mjs';
15+
16+
const FIXTURES_DIR = join(import.meta.dirname, 'fixtures');
17+
18+
const loader = createMarkdownLoader();
19+
const parser = createMarkdownParser();
20+
21+
describe('generator output complies with json schema', () => {
22+
const validator = new Validator();
23+
24+
/**
25+
* @type {object}
26+
*/
27+
let schema;
28+
29+
before(async () => {
30+
schema = await parseSchema();
31+
});
32+
33+
for (const fixture of ['text-doc', 'module']) {
34+
const input = join(FIXTURES_DIR, `${fixture}.md`);
35+
36+
test(`${fixture}.md`, async () => {
37+
const files = await loader.loadFiles([input]);
38+
const docs = await parser.parseApiDocs(files);
39+
40+
const { runGenerators } = createGenerator(docs);
41+
42+
const result = await runGenerators({
43+
generators: ['json'],
44+
input,
45+
output: undefined,
46+
version: new SemVer('v1.2.3'),
47+
releases: [],
48+
gitRef: 'a'.repeat(40),
49+
threads: 1,
50+
typeMap: {},
51+
});
52+
53+
assert.ok(validator.validate(result[0], schema).valid);
54+
});
55+
}
56+
});
57+
58+
test('schema version matches generator version', async () => {
59+
const schemaString = await readFile(
60+
join(import.meta.dirname, '..', 'schema.jsonc'),
61+
'utf8'
62+
);
63+
const schema = await jsoncParse(schemaString);
64+
65+
assert.strictEqual(schema.$id, `nodejs-api-doc@v${json.version}`);
66+
});

0 commit comments

Comments
 (0)