feat: add schema for feature manifest files

[AprilSylph]

Description

I keep getting annoyed at how juvenile docs/Chapter 4.1 - Feature metadata.md seems. Better documentation would look more like the pages on Google's Chrome extension developer docs, with its own type definitions and better clarity about what can and cannot overlap.

Well, that sounds awfully like a schema to me. I think that maybe creating a schema could be a great starting point for writing better documentation, since it forces accurate recording of definitions without the additional effort of explaining too much of anything in English.

As a bonus, we get basic IntelliSense descriptions for properties in feature.json files.

I have to admit—I had fun doing this.

Screenshots

N/A, dev changes only

Testing steps

1. Pull this branch locally
2. Validate our feature.json files against the new schema:

   npx ajv-cli validate --spec=draft2020 -s schemas/feature.json -d 'src/features/*/feature.json'
   

[AprilSylph]

Possible point of contention: should the "json.schemas" VS Code config property be committed, or should we add a "$schema" property to every feature manifest? The former is obviously a lot less lift, but only works with one editor; the latter is more complete but would be more LoC total.

...I think I'm leaning towards the latter, now that I spell it out like that.

[marcustyphoon]

Possible point of contention: should the "json.schemas" VS Code config property be committed, or should we add a "$schema" property to every feature manifest? The former is obviously a lot less lift, but only works with one editor; the latter is more complete but would be more LoC total.

...I think I'm leaning towards the latter, now that I spell it out like that.

Hm, I think either works well. Agreed with your lean, I think.

[AprilSylph]

In implementing the "$schema" properties I realised something about it which is making me lean a little harder in the other direction: it's essentially polluting the final package. 36 added LoC that do absolutely nothing.

If folks want to use other editors to contribute, and stick around long enough to crave dev QoL things like schema validation (which is already an unrealistic circumstance, if the project's history is anything to go on), then we can revisit this decision or commit another editor config file.

---

^{Attachments: diff.patch}

[marcustyphoon]

Hm, I guess I'm just used to $schema properties at this point, as if they were part of the filetype.

[marcustyphoon]

Aside: I do find the true-json-schema approach interesting to compare to authoring types in typescript (and validating with e.g. typia, which was what I chose for https://github.com/discretize/discretize-gear-optimizer) or authoring in zod. Both seem quite a bit more succinct to author in and read. Things like "minProperties": 1, aren't expressable in typescript, to my knowledge; I have to imagine they are in zod (which I should probably use at some point just to get familiar with it, since it seems pretty ubiquitous).

To my knowledge, you can't get intellisense in a json file using either directly without a hacky VS Code plugin; using either without that would presumably either requiring running a script to convert the source of truth into a schema file wheneve it's changed (meh) or changing the metadata files to be js/ts default exports (also meh, besides that you get jsonc features for free; no-trailing-commas requirements should be banned by some kind of international treaty).

So, not practical, really, but interesting.