feat: legacy json generator

[RedYetiDev]

Closes #57
Closes #141
Closes #92

---

This is an extension of #92. This is a seperate PR due to a rebase that caused merge conflicts.

Description

See #92 for a description

Validation

# Variables
FILENAME="$1"
NODE="path/to/node/repo"
API_DOCS_TOOLING="path/to/api-docs/tooling/repo"
DOC="$NODE/doc/api/$FILENAME.md"
OUTPUT_DIR="output"
NEW_DIR="$OUTPUT_DIR/new"
OLD_DIR="$OUTPUT_DIR/old"
SORT_JSON=$(cat <<EOF
def sorted_walk(f):
  . as \$in
  | if type == "object" then
      reduce keys[] as \$key
        ( {}; . + { (\$key):  (\$in[\$key] | sorted_walk(f)) } ) | f
  elif type == "array" then map( sorted_walk(f) ) | f
  else f
  end;

def normalize: sorted_walk(if type == "array" then sort else . end);

normalize
EOF
)

# Functions
initialize_output() {
  rm -rf "$OUTPUT_DIR" && mkdir -p "$NEW_DIR" "$OLD_DIR"
}

generate_new() {
  node "$API_DOCS_TOOLING/bin/cli.mjs" -i "$DOC" -t legacy-json -o "$NEW_DIR"
}

generate_old() {
  node "$NODE/tools/doc/generate.mjs" "$DOC" --output-directory="$OLD_DIR"
}

compare_outputs() {
  git diff --no-index <(jq --sort-keys -f <(echo $SORT_JSON) "$OLD_DIR/$FILENAME.json") <(jq --sort-keys -f <(echo $SORT_JSON) "$NEW_DIR/$FILENAME.json")
}

# Main logic
initialize_output
generate_new
generate_old
compare_outputs

Validate with bash ./file.sh addons, bash ./file.sh fs, etc.

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I've covered new added functionality with unit tests if necessary.

[RedYetiDev]

@flakey5 PTAL

[RedYetiDev]

Currently, this PR is 1:1 with the original JSON (AFAIK), except for the following differences, which probably don't need to be fixed:

1. Highlighting is done by Shiki instead of Highlight.js
2. The old parser had issues parsing optional parameters in some cases (IIUC)
3. The old parser mistook return-ed Objects for additional parameters
4. The old parser pre-parsed the source_code YAML comments, ours does not.
5. The old parser would use the filename as the displayName for the root node, this one uses the actual display name. (E.X. fs (old) vs File System (new))

[ovflowd]

So, is it correct to assume that this is PR supersedes @flakey5's PR? Was this communicated with @flakey5? Are they fine with the continuation on this PR?

Note that you could also have pushed your work on their PR if they were fine :) -- or at least you can once you join the team on GitHub I believe.

I will review this once I get time 🙏

[RedYetiDev]

I would wait until we get the go-ahead from the other PR. My plan was to open this PR into that branch, but there was merge conflicts. If we don't get the go ahead, I suggest that @flakey5 use git apply to semi-manually apply some of these changes.

(I obviously don't want to take away from the other PR / cut off @flakey5's amazing work, and if we'd rather keep the discussion there, I am fine with that)

[ovflowd]

BTW @RedYetiDev CodeQL complained about your code, that it might have a security vuln; Mind giving an eye? 👀

[RedYetiDev]

BTW @RedYetiDev CodeQL complained about your code, that it might have a security vuln; Mind giving an eye? 👀

#142 (comment)

[flakey5]

I was either traveling or getting over jet lag this weekend so I wasn't able to respond much to the comments made on #92, I would've appreciated a little more time to respond to the comments made but it's water under the bridge.

Imo it makes sense to continue with this one since the commits are already here and it's pretty much done, still need to make sure the unresolved comments in #92 are addressed here however

[RedYetiDev]

I would've appreciated a little more time to respond to the comments made but it's water under the bridge.

Sorry!! Thank you for understanding. Again, I'm happy to instead have this merged into your PR, I really don't want to take over your amazing work

[ovflowd]

Wouldn't it be better to simply extract the nodes that are listed and ignore others? Also, we already have helpers for stability index, I don't think any of this needs to be done. Afaik the metadata of the node should already have everything about stability. Meaning we don't need any of this code (IMO)

See: https://github.com/nodejs/api-docs-tooling/blob/main/src/metadata.mjs#L152

[RedYetiDev]

We need to delete the stability node from the nodes, so this matches the node, unless we can delete it elsewhere?

[ovflowd]

This should be a Factory (even a different file) that allows you to handle the signature types for other types.

So that we have tiny methods (that implement an interface) instead of non-ending signatures

[RedYetiDev]

What do you mean? Can you give a tiny example (sorry, it's not clicking in my head for me)

[ovflowd]

Ill keep reviewing this later on, but so far I left a few comments already :D

[flakey5]

Lgtm other than a few nits and the comments from other reviewers

Copilot reviewed 8 out of 20 changed files in this pull request and generated 2 suggestions.

Files not reviewed (12)

• src/generators/legacy-html/assets/api.js: Evaluated as low risk
• src/parser.mjs: Evaluated as low risk
• src/test/metadata.test.mjs: Evaluated as low risk
• README.md: Evaluated as low risk
• src/generators/index.mjs: Evaluated as low risk
• src/metadata.mjs: Evaluated as low risk
• src/utils/parser.mjs: Evaluated as low risk
• shiki.config.mjs: Evaluated as low risk
• src/queries.mjs: Evaluated as low risk
• src/generators/legacy-json/utils/buildSection.mjs: Evaluated as low risk
• src/test/queries.test.mjs: Evaluated as low risk
• src/constants.mjs: Evaluated as low risk

[RedYetiDev]

src/generators/legacy-json/utils/buildSection.mjs: Evaluated as low risk

😆 It didn't even review the most important file