Introduce a Linter / Validation System

[ovflowd]

This is another feature we want to tackle and have within the API docs tooling. The idea is similar to ESlint: We have a system that reports on irregularities when running the API docs tooling against files.

Assume you have a missing version on one of the YAML metadata (i.e.: version: REPLACEME), or some of the YAML is missing (like each module may have an "introduced_in" on the first node/section), or you have some invalid type within the API docs (ie: {SomethingThatDoesNotExist} or a typo {Obrect} instead of {Object}

• The system would print on the console with the error level (info, warn, error) and tell in which line and position it would be such an issue on the source Markdown file.
• The system could be a singleton that collects all issues during runtime and then displays them at the end of the run.
• The system could be disabled/ignored with a CLI flag --skip-validation; The system must know the almost exact position of something, possibly within the AST tree, which gives you a position object for each item so you can narrow it to a close position.
• Some methods might need to be updated (if they don't use a node (ApiMetadataEntry or Parent/Node) to pass such information or the position object; Or maybe some abstraction so that the queries.mjs, generators.mjs and all utils know what is the current context being handled. (Note that since parsing and processing is async, we cannot set a static context within a Singleton) The system should not use try/catch or exceptions since the code should be evergreen and failproof to actual errors within the markdown.
• All the message templates should be defined within the constants.mjs
• When there's at least one Error level, the process will exit with a non-success status code.

Possible items for the system:

• Warning: missing version on a YAML metadata entry (changes or updates properties)
• Warning: invalid version on a YAML metadata entry (changes or updates properties) (ie: REPLACEME)
• Warning: invalid type reference {type}
• Info: missing "introduced_in" on top of the document
• More?

[flakey5]

I can try to take a swing at this once I'm done with the legacy json generator, do we know when we'd want this by?

[ovflowd]

I can try to take a swing at this once I'm done with the legacy json generator, do we know when we'd want this by?

No ETA, priorities on parity with current generation.

[flakey5]

Assuming this is also gonna be ran in ci, wdyt of having it report errors inline similiar to https://www.npmjs.com/package/@reporters/github?

[ovflowd]

Why not