Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/workflows/schema-drift.yml
Original file line number Diff line number Diff line change
@@ -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"
17 changes: 17 additions & 0 deletions docs/docs/reference/congregation/comline-toml.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
231 changes: 231 additions & 0 deletions docs/docs/schemas/comline-toml/0.x.json
Original file line number Diff line number Diff line change
@@ -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`<out>/<language>/`. 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"
}
54 changes: 54 additions & 0 deletions scripts/sync-comline-toml-schema.py
Original file line number Diff line number Diff line change
@@ -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 <sha>

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())
Loading