diff --git a/.github/workflows/schema-drift.yml b/.github/workflows/schema-drift.yml new file mode 100644 index 0000000..4a5a605 --- /dev/null +++ b/.github/workflows/schema-drift.yml @@ -0,0 +1,53 @@ +name: Schema drift + +# `docs/docs/schemas/comline-toml/0.x.json` is served on the site as the +# `comline.toml` JSON Schema, which `comline new` points a `#:schema` line at. +# It is a copy: generation derives it from `comline_codegen::config`. This +# checks the copy still equals generation's file. +# +# Separate from the Docs workflow for the same reason as the other drift +# checks: a fetch against another repo has no business blocking a deploy. + +on: + schedule: + # A schema change lands in `generation` and never touches this repo, so a + # push-triggered run would not see it. Weekly catches that side. + - cron: '45 7 * * 1' + pull_request: + paths: + - 'docs/docs/schemas/**' + - 'scripts/sync-comline-toml-schema.py' + - '.github/workflows/schema-drift.yml' + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: schema-drift-${{ github.ref }} + cancel-in-progress: true + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-python@v7 + with: + python-version: "3.14" + + - name: Compare with generation's schema + shell: bash + run: | + if ! python3 scripts/sync-comline-toml-schema.py | tee drift.txt; then + { + echo '### Schema drift' + echo + echo '```' + cat drift.txt + echo '```' + } >> "$GITHUB_STEP_SUMMARY" + exit 1 + fi + cat drift.txt >> "$GITHUB_STEP_SUMMARY" diff --git a/docs/docs/reference/congregation/comline-toml.md b/docs/docs/reference/congregation/comline-toml.md index 7a5742a..ea14be2 100644 --- a/docs/docs/reference/congregation/comline-toml.md +++ b/docs/docs/reference/congregation/comline-toml.md @@ -255,6 +255,23 @@ built-in defaults → [generate] → [[generate.target]] → COMLINE_GENERATE_* - `--out` / `--layout` / `--mode` — apply to **one** target and need `--target` when more than one is configured. +## Editor support + +`comline.toml` has a JSON Schema, served at +`https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json`. With it an +editor completes keys, checks values, and shows each key's description on hover. +`comline new` writes the pointer as the first line of the file: + +```toml +#:schema https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json +``` + +Any TOML language server that reads the `#:schema` directive picks it up: [Even +Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) +in VS Code, or [Taplo](https://taplo.tamasfe.dev/) in other editors. The +[VS Code extension](https://github.com/ComlineProject/comline-vscode) also associates the schema with +`comline.toml` files, so an older file without the line is covered too. + ## Forward-looking ```toml diff --git a/docs/docs/schemas/comline-toml/0.x.json b/docs/docs/schemas/comline-toml/0.x.json new file mode 100644 index 0000000..bfc630c --- /dev/null +++ b/docs/docs/schemas/comline-toml/0.x.json @@ -0,0 +1,231 @@ +{ + "$id": "https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json", + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "definitions": { + "EncodingEntry": { + "anyOf": [ + { + "description": "The type implementing the encoding, e.g. `\"acme::LinesFraming\"`.", + "type": "string" + }, + { + "allOf": [ + { + "$ref": "#/definitions/EncodingTable" + } + ], + "description": "The type and the package it comes from, e.g.\n`{ type = \"LinesFraming\", package = \"acme-encodings\", version = \"^0.2\" }`." + } + ], + "description": "One entry of `encodings`: the type alone, or with its package." + }, + "EncodingTable": { + "additionalProperties": false, + "description": "The table form of an `encodings` entry.", + "properties": { + "package": { + "description": "The package the type comes from.", + "type": "string" + }, + "type": { + "description": "The type implementing the encoding, as the generated code names it.", + "type": "string" + }, + "version": { + "description": "The version requirement on that package.", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "Generate": { + "additionalProperties": false, + "description": "The `[generate]` table.", + "properties": { + "async": { + "default": false, + "description": "`true`: protocols on a connection get async handlers and senders\n(Rust's `AsyncConnection`), shared by every target unless overridden.\nA generator whose output is async anyway ignores it. Default `false`.", + "type": "boolean" + }, + "encodings": { + "additionalProperties": { + "$ref": "#/definitions/EncodingEntry" + }, + "description": "Which type implements each encoding (format, framing, handshake) in\nthe generated code, by encoding name:\n`encodings = { \"com.acme.lines@1\" = \"acme::LinesFraming\" }`, or with\nthe package it comes from, `{ type = \"...\", package = \"...\", version\n= \"...\" }`. Overrides the declaring package's suggested mapping, and\nmaps an encoding that has none. A target's own `encodings` override\nthese, name by name.", + "type": "object" + }, + "external_std": { + "description": "`true`: reference `comline_std` as its own package instead of inlining\nit, shared by every target unless overridden. Only a generator that\nknows how (today, Rust's) acts on it. Defaults on in `lib` mode, off in\n`code` mode.", + "type": "boolean" + }, + "layout": { + "default": "{{language}}/{{namespace}}.{{ext}}", + "description": "Where each file lands under the output root, as a template over\n`{{language}}`, `{{namespace}}`, `{{ext}}`, `{{lang_version}}`,\n`{{spec_version}}` and `{{package_version}}`. Shared by every target\nunless overridden. Has no effect in `lib` mode.", + "type": "string" + }, + "mode": { + "default": "code", + "description": "Emit form shared by every target unless overridden: `code` (loose\nsource files, the default) or `lib` (a buildable package).", + "enum": [ + "code", + "lib" + ], + "type": "string" + }, + "only": { + "default": [], + "description": "Narrow generation to these languages, out of the ones `config.idp`\ndeclares. Empty (the default) means every declared language.\n\nThe consumer's half of the split: `config.idp` says which languages\nthe *package* is for, and this says which of them *this checkout*\nwants built. A name the congregation doesn't declare is an error\nrather than a silent no-op, so a typo here can't quietly stop\ngenerating something.", + "items": { + "type": "string" + }, + "type": "array" + }, + "out": { + "default": "generated", + "description": "Output root, relative to `comline.toml`, shared by every target unless\noverridden. Default `generated`.", + "type": "string" + }, + "package_versions": { + "allOf": [ + { + "$ref": "#/definitions/VersionSpec" + } + ], + "description": "Version selection shared by every target unless overridden." + }, + "target": { + "description": "`[[generate.target]]` blocks.", + "items": { + "$ref": "#/definitions/Target" + }, + "type": "array" + }, + "validate_on_decode": { + "default": "off", + "description": "Whether decoding a value runs its `@validators` checks: `off` (the\ndefault), `collect` (fail with every failure) or `first` (fail with\nthe first). Shared by every target unless overridden.", + "enum": [ + "off", + "collect", + "first" + ], + "type": "string" + } + }, + "type": "object" + }, + "Target": { + "additionalProperties": false, + "description": "One `[[generate.target]]` block: the settings for one language the\npackage declares. It does not decide which languages are generated, and\nnaming one `config.idp` doesn't declare is an error.", + "properties": { + "async": { + "description": "Whether this target's protocols on a connection get async handlers and\nsenders. Overrides `[generate] async`.", + "type": "boolean" + }, + "encodings": { + "additionalProperties": { + "$ref": "#/definitions/EncodingEntry" + }, + "description": "Which type implements each encoding, by encoding name, for this\ntarget. Overrides `[generate] encodings`, name by name.", + "type": "object" + }, + "external_std": { + "description": "Whether this target references `comline_std` as its own package.\nOverrides `[generate] external_std`.", + "type": "boolean" + }, + "flatten": { + "default": false, + "description": "`lib` mode only: write the crate straight into `out` instead of\n`//`. Target-only (no `[generate]` default, no flag/env)\n— a shared `out` across several `lib` targets needs the per-language\nsplit to avoid two crates colliding in one directory, so flattening\nonly makes sense once a target already has `out` to itself.", + "type": "boolean" + }, + "generator": { + "description": "A generator outside this binary: a path to a `.wasm` (run sandboxed\nunder wasmtime) or to an executable, relative to `comline.toml`'s\ndirectory. Unset, the built-in generator for `language` is used.", + "type": "string" + }, + "lang_version": { + "description": "Language/toolchain version selecting the generator (e.g. `1.88.0`).\nFalls back to the version the congregation declared for this language,\nand may raise it but never lower it.", + "type": "string" + }, + "language": { + "description": "The language this block configures. Must match a language the\npackage declares under `code_generation.languages` in `config.idp`.\nWith `generator`, it also picks among the languages that generator\noffers, and may be left out when it offers one.", + "type": "string" + }, + "layout": { + "description": "This target's layout template. Overrides `[generate] layout`.", + "type": "string" + }, + "mode": { + "description": "This target's emit form: `code` or `lib`. Overrides `[generate] mode`.", + "enum": [ + "code", + "lib" + ], + "type": "string" + }, + "out": { + "description": "This target's output root, relative to `comline.toml`. Overrides\n`[generate] out`.", + "type": "string" + }, + "package_versions": { + "allOf": [ + { + "$ref": "#/definitions/VersionSpec" + } + ], + "description": "This target's version selection. Overrides\n`[generate] package_versions`." + }, + "timeout": { + "description": "The wall-time limit for each call to `generator`, in seconds.\nDefault 60.", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "validate_on_decode": { + "description": "Whether this target's decoding runs `@validators` checks: `off`,\n`collect` or `first`. Overrides `[generate] validate_on_decode`.", + "enum": [ + "off", + "collect", + "first" + ], + "type": "string" + } + }, + "type": "object" + }, + "VersionSpec": { + "anyOf": [ + { + "examples": [ + "latest", + "all", + "0.3.0" + ], + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "Which package versions to generate bindings for: `latest` (the working tree, the default), `all` (every committed version), or one version or a list of them, each a version string or commit hash." + } + }, + "description": "`comline.toml`: where `comline generate` writes code, and how. Which\nlanguages are generated comes from `config.idp`'s\n`code_generation.languages`; this file says where each one lands.", + "properties": { + "generate": { + "allOf": [ + { + "$ref": "#/definitions/Generate" + } + ], + "description": "Code-generation settings: defaults shared by every target, and\n`[[generate.target]]` blocks configuring one language each." + } + }, + "title": "comline.toml", + "type": "object" +} diff --git a/scripts/sync-comline-toml-schema.py b/scripts/sync-comline-toml-schema.py new file mode 100644 index 0000000..1c041d6 --- /dev/null +++ b/scripts/sync-comline-toml-schema.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +"""Keep the served `comline.toml` JSON Schema equal to generation's. + +`comline_codegen::config` is the source of truth: generation derives +`schemas/comline-toml.json` from it and drift-checks that file there. This repo +only serves a copy, at `/schemas/comline-toml/0.x.json`, because `comline new` +writes that URL into a fresh `comline.toml` as a `#:schema` line. + + python3 scripts/sync-comline-toml-schema.py # check; exit 1 on drift + python3 scripts/sync-comline-toml-schema.py --write # refresh the copy + python3 scripts/sync-comline-toml-schema.py --rev + +The schema is fetched from generation's default branch (`HEAD`) unless pinned. +""" + +from __future__ import annotations + +import argparse +import sys +import urllib.request +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +COPY = ROOT / "docs/docs/schemas/comline-toml/0.x.json" +RAW = "https://raw.githubusercontent.com/ComlineProject/generation/{rev}/schemas/comline-toml.json" + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__.split("\n")[0]) + ap.add_argument("--write", action="store_true", help="overwrite the committed copy") + ap.add_argument("--rev", default="HEAD", help="generation ref to read (default: HEAD)") + args = ap.parse_args() + + url = RAW.format(rev=args.rev) + with urllib.request.urlopen(url, timeout=30) as r: + upstream = r.read() + + if args.write: + COPY.write_bytes(upstream) + print(f"wrote {COPY.relative_to(ROOT)} from {url}") + return 0 + + if COPY.read_bytes() == upstream: + print("comline.toml schema: up to date") + return 0 + + print(f"{COPY.relative_to(ROOT)} differs from generation's schemas/comline-toml.json") + print("Refresh it with:") + print(" python3 scripts/sync-comline-toml-schema.py --write") + return 1 + + +if __name__ == "__main__": + sys.exit(main())