feat(json): add JSON generators

Co-Authored-By: flakey5 <73616808+flakey5@users.noreply.github.com>
Signed-off-by: avivkeller <me@aviv.sh>

Author: avivkeller

.changeset/json-generator.md

@@ -0,0 +1,7 @@
+---
+'@doc-kit/core': minor
+'@doc-kit/generator-react': patch
+'@node-core/doc-kit-legacy': patch
+---
+
+feat: the `json` and `json-all` generators

.github/workflows/generate.yml

@@ -94,6 +94,10 @@ jobs:
           - target: json-simple
             input: './node/doc/api/*.md'
 
+          - target: json
+            input: './node/doc/api/*.md'
+            compare: object-assertion
+
           - target: legacy-json
             input: './node/doc/api/*.md'
             compare: object-assertion

.prettierignore

@@ -16,6 +16,7 @@ www/out/
 
 # Generated Files
 packages/core/src/generators/metadata/maps/mdn.json
+packages/core/src/generators/json/generated/
 
 # The specification uses things that prettier would not
 # approve of, such as bullets with `*`

README.md

@@ -69,10 +69,11 @@ Options:
   --config-file <path>         Config file
   -i, --input <patterns...>    Input file patterns (glob)
   -t, --target <generator...>  Target generator(s): a built-in name
-                               (json-simple, legacy-html, legacy-html-all,
-                               man-page, legacy-json, legacy-json-all,
-                               addon-verify, api-links, orama-db, llms-txt,
-                               sitemap, html) or an import specifier for a
+                               (json, json-all, json-simple, legacy-html,
+                               legacy-html-all, man-page, legacy-json,
+                               legacy-json-all, addon-verify, api-links,
+                               orama-db, llms-txt, sitemap, html,
+                               section-pages) or an import specifier for a
                                custom generator
   --ignore <patterns...>       Ignore file patterns (glob)
   -o, --output <directory>     The output directory

docs/generators.md

@@ -20,9 +20,11 @@ npx @doc-kit/cli generate -t html -t orama-db -t sitemap -i "docs/**/*.md" -o ou
 
 ### JSON ([`@doc-kit/core`](./packages/core.md))
 
-| Target                                       | Output                                                   |
-| -------------------------------------------- | -------------------------------------------------------- |
-| [`json-simple`](./generators/json-simple.md) | A simplified JSON rendering of the parsed documentation. |
+| Target                                       | Output                                                             |
+| -------------------------------------------- | ------------------------------------------------------------------ |
+| [`json`](./generators/json.md)               | One schema-described JSON document per source file.                |
+| [`json-all`](./generators/json-all.md)       | Those documents bundled into a single `all.json`.                  |
+| [`json-simple`](./generators/json-simple.md) | A dump of the parsed metadata entries, for debugging the pipeline. |
 
 ### Legacy ([`@node-core/doc-kit-legacy`](./packages/node-legacy.md))
 

package.json

@@ -44,6 +44,7 @@
     "eslint-plugin-react-x": "5.18.6",
     "globals": "~17.7.0",
     "husky": "9.1.7",
+    "json-schema-to-typescript": "^16.0.0",
     "lint-staged": "17.4.1",
     "prettier": "3.9.6"
   }

packages/core/README.md

@@ -10,7 +10,8 @@ The command-line interface lives in the companion
 ## Generators
 
 Output formats are provided by generators. This package ships the shared
-pipeline stages and `json-simple`; the rest come from companion packages:
+pipeline stages and the JSON generators (`json`, `json-all`, and the
+debugging-only `json-simple`); the rest come from companion packages:
 
 | Package                                                                                | Generators                                                                            |
 | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |

packages/core/package.json

@@ -20,6 +20,8 @@
     ".": "./src/generators.mjs",
     "./ast": "./src/generators/ast/index.mjs",
     "./ast-js": "./src/generators/ast-js/index.mjs",
+    "./json": "./src/generators/json/index.mjs",
+    "./json-all": "./src/generators/json-all/index.mjs",
     "./json-simple": "./src/generators/json-simple/index.mjs",
     "./metadata": "./src/generators/metadata/index.mjs",
     "./package.json": "./package.json",
@@ -59,6 +61,8 @@
     "github-slugger": "^2.0.0",
     "glob-parent": "^6.0.2",
     "hastscript": "^9.0.1",
+    "mdast-util-slice-markdown": "^2.0.1",
+    "mdast-util-to-string": "^4.0.0",
     "piscina": "^5.3.1",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
@@ -79,13 +83,14 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
     "hast-util-to-html": "^9.0.5",
     "hast-util-to-string": "^3.0.1"
   },
   "peerDependencies": {
+    "@doc-kit/generator-react": "workspace:>=0.1.0",
     "@node-core/doc-kit": "workspace:>=2.0.0",
-    "@node-core/doc-kit-legacy": "workspace:>=1.0.0",
-    "@doc-kit/generator-react": "workspace:>=0.1.0"
+    "@node-core/doc-kit-legacy": "workspace:>=1.0.0"
   },
   "peerDependenciesMeta": {
     "@node-core/doc-kit": {

packages/core/src/generators/index.mjs

@@ -10,6 +10,8 @@
  * which is how third-party generator packages are loaded.
  */
 export const publicGenerators = {
+  json: '@doc-kit/core/json',
+  'json-all': '@doc-kit/core/json-all',
   'json-simple': '@doc-kit/core/json-simple',
   'legacy-html': '@node-core/doc-kit-legacy/legacy-html',
   'legacy-html-all': '@node-core/doc-kit-legacy/legacy-html-all',

packages/core/src/generators/json-all/README.md

@@ -0,0 +1,31 @@
+# `json-all` Generator
+
+The `json-all` generator bundles the documents of the [`json`](./json.md)
+generator into a single `all.json` file.
+
+```sh
+npx @doc-kit/cli generate -t json-all -i "doc/api/*.md" -o out --index doc/api/index.md
+```
+
+```json
+{
+  "$schema": "https://doc-kit.nodejs.org/schemas/api-doc-all/1.0.0.json",
+  "documents": []
+}
+```
+
+`documents` holds every document in the order of the configured `index`,
+then the rest by `id`. The bundle's schema, shipped as
+`@doc-kit/core/generators/json-all/schema.json`, refers to the `json`
+generator's schema for the documents.
+
+## Configuring
+
+- `output` {string} The directory where `all.json` will be written.
+- `minify` {boolean} Whether to minify the output. Inherited from `global`.
+  **Default:** `true`.
+- `index` {Array} The `{ api }` objects defining the document order. Inherited
+  from `global`.
+- `schemaURL` {string} Where the bundle's schema is published.
+  `{schemaVersion}` is filled in. **Default:**
+  `'https://doc-kit.nodejs.org/schemas/api-doc-all/{schemaVersion}.json'`.