feat: add typespec schemas for modules

[xynydev]

We should create TypeSpec schemas for each module based on the examples I set below. When all that is completed and verified as working, just change all the references to the dev branch to main and merge.

[xynydev]

Everything added up-until now is just type defs, we could also utilize patterns for certain modules. Need to also add docstrings for all the parameters.

[xynydev]

~done: move the module.yml docs to the README (as it's not user-facing) and update it with info about typespec.~

[xynydev]

I added some docstrings for the files module, and I'd like to test them in the editor before proceeding with adding the rest of them. Unfortunately there's a blocking upstream bug regarding some modules, which we could hack together a fix for, or remove those modules for now, but I'll wait and see for how quick the response is.

[xynydev]

The upstream bug was already fixed, I just had to update https://github.com/blue-build/schema to use a dev version of TypeSpec.

Additionally, the docstrings work perfectly in the way that I expected. I'll resume working on remaining issues and add docstrings in the schemas.

[xynydev]

@fiftydinar This PR is pretty much ready, I suggest you take a look at the .tsp syntax and start getting used to it. You can also try how editing recipe.yml with this feels by adding the following snippet at the top: # yaml-language-server: $schema=https://schema.blue-build.org/recipe-v1.json. Note that this requires an editor using the YAML LSP such as VSCode with the YAML extension from Red Hat.

In many cases, the example: section in module.yml is used in a very similar manner to how this is used. With https://github.com/blue-build/website/issues/55 that'll be basically useless, since the documentation will already be automatically generated from the schemas. A full-blown reference document for the module was never the full intention of the example: section, but that conflicted with the lack of other places for such documentation. After this PR and the one I just linked are merged we should work on refactoring every module example to serve as an actual good example one could just copy into their recipe without modifications.

[xynydev]

(before merge, the modules.json needs to still be updated)

[xynydev]

https://github.com/blue-build/website/pull/58 is now pretty much done, but we need to actually streamline the existing documentation and examples before merging it, because for example the brew page having to "configuration options" -sections makes no sense. https://55-feat-use-documented-jsons.website-18h.pages.dev/reference/modules/brew/#configuration-options

[fiftydinar]

@fiftydinar This PR is pretty much ready, I suggest you take a look at the .tsp syntax and start getting used to it. You can also try how editing recipe.yml with this feels by adding the following snippet at the top: # yaml-language-server: $schema=https://schema.blue-build.org/recipe-v1.json. Note that this requires an editor using the YAML LSP such as VSCode with the YAML extension from Red Hat.

I currently use just Gnome Text Editor & nothing else when editing bash scripts.

I will try to see which setup would suit me the best when editing .tsp files. It will take me time to get used to.

All this TypeScript-schema thing is new to me.

[xynydev]

I currently use just Gnome Text Editor & nothing else when editing bash scripts.

And that presumably applies to other languages as well?

I will try to see which setup would suit me the best when editing .tsp files. It will take me time to get used to.

All this TypeScript-schema thing is new to me.

The editor integration isn't that good anywhere yet. My workflow is basically copying the file from some other module and modifying the necessary details. I can write some instructions for making TypeSpec schemas for modules in the README before this is merged.

I'm hopeful and pretty confident that this method will be the easiest way to achieve good editor integration and build-time validation for the recipes.

[fiftydinar]

And that presumably applies to other languages as well?

Yeah

I can write some instructions for making TypeSpec schemas for modules in the README before this is merged.

That would be great!

[xynydev]

@fiftydinar take a look https://github.com/blue-build/modules/blob/113-feat-create-json-schemas-for-module-configuration/README.md#typespec-schema

[fiftydinar]

@fiftydinar take a look 113-feat-create-json-schemas-for-module-configuration/README.md#typespec-schema

Looks pretty good

[fiftydinar]

@xynydev there is a typo "inlude" instead of "include" in typespec section

[xynydev]

I'll write a quick schema for justfiles, but I think this PR is basically ready then. There's still a few things I've got to figure out in the schema repo before any user can start using schemas, but new modules and contributors should start adopting it.