gramson 0.1.0__tar.gz

gramson-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kim Bäckström
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gramson-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md Makefile requirements-dev.txt requirements-release.txt
+recursive-include spec *.yaml *.yml *.md
+recursive-include schema *.schema.yaml
+recursive-include tools *.py
+recursive-include tests *.py *.json *.md LICENSE
+recursive-include examples *.json *.yaml *.yml *.md
+recursive-include docs *.md *.yaml *.html
+exclude docs/RELEASING.md
+global-exclude __pycache__ *.py[cod]

gramson-0.1.0/Makefile

@@ -0,0 +1,65 @@
+.DEFAULT_GOAL := help
+
+PYTHON ?= python3
+VENV ?= .venv
+VENV_PYTHON := $(VENV)/bin/python
+HOST ?= 127.0.0.1
+PORT ?= 8765
+
+.PHONY: help setup setup-release generate example example-bitwise example-external lint lint-python lint-openapi test check build check-dist serve
+
+help: ## Show available targets
+	@awk 'BEGIN {FS = ":.*## "} /^[a-z-]+:.*## / {printf "  %-16s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+$(VENV_PYTHON):
+	$(PYTHON) -m venv "$(VENV)"
+
+setup: $(VENV_PYTHON) ## Create the virtual environment and install the CLI and development dependencies
+	"$(VENV_PYTHON)" -m pip install -r requirements-dev.txt
+	"$(VENV_PYTHON)" -m pip install -e .
+
+setup-release: setup ## Install development and release tooling
+	"$(VENV_PYTHON)" -m pip install -r requirements-release.txt
+
+generate: ## Generate JSON Schemas from the operator specification
+	"$(VENV_PYTHON)" tools/generate_schema.py
+
+example: ## Generate and validate the ready-to-run core extension example
+	"$(VENV_PYTHON)" -m gramson generate --manifest examples/extension/language.yaml --output-directory build/examples/extension
+	"$(VENV_PYTHON)" -m gramson validate examples/extension/expressions/nested.yaml --schema build/examples/extension/expression.schema.yaml
+	"$(VENV_PYTHON)" -m gramson validate examples/extension/expressions/nested.json --schema build/examples/extension/expression.schema.yaml
+
+example-bitwise: ## Generate and validate the bitwise extension example
+	"$(VENV_PYTHON)" -m gramson generate --manifest examples/bitwise/language.yaml --output-directory build/examples/bitwise
+	"$(VENV_PYTHON)" -m gramson validate examples/bitwise/expressions/nested.yaml --schema build/examples/bitwise/expression.schema.yaml
+	"$(VENV_PYTHON)" -m gramson validate examples/bitwise/expressions/nested.json --schema build/examples/bitwise/expression.schema.yaml
+	"$(VENV_PYTHON)" -m gramson validate examples/bitwise/expressions/conversions.yaml --schema build/examples/bitwise/expression.schema.yaml
+	"$(VENV_PYTHON)" -m gramson validate examples/bitwise/expressions/conversions.json --schema build/examples/bitwise/expression.schema.yaml
+
+example-external: ## Generate and validate an external namespace include
+	"$(VENV_PYTHON)" -m gramson generate --manifest examples/external/language.yaml --spec-path examples/external/vendor --output-directory build/examples/external
+	"$(VENV_PYTHON)" -m gramson validate examples/external/expressions/nested.yaml --schema build/examples/external/expression.schema.yaml
+	"$(VENV_PYTHON)" -m gramson validate examples/external/expressions/nested.json --schema build/examples/external/expression.schema.yaml
+
+lint: lint-python lint-openapi ## Run Python and OpenAPI linting
+
+lint-python: ## Lint Python code and import ordering with Ruff
+	"$(VENV_PYTHON)" -m ruff check .
+
+lint-openapi: ## Validate the OpenAPI document and its external references
+	"$(VENV_PYTHON)" -m openapi_spec_validator docs/openapi.yaml
+
+test: ## Run all tests, including generated-schema freshness checks
+	"$(VENV_PYTHON)" -m unittest discover -s tests -v
+
+check: lint test ## Run lint and tests without regenerating files
+
+build: ## Build a source distribution and a wheel from that source distribution
+	"$(VENV_PYTHON)" -m build
+
+check-dist: build ## Check package metadata, bundled schemas, and installed CLI
+	"$(VENV_PYTHON)" tools/check_distribution.py dist
+
+serve: generate ## Generate schemas and serve the Swagger viewer locally
+	@printf 'Swagger viewer: http://%s:%s/docs/\n' "$(HOST)" "$(PORT)"
+	"$(VENV_PYTHON)" -m http.server "$(PORT)" --bind "$(HOST)"

gramson-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: gramson
+Version: 0.1.0
+Summary: Define JSON expression languages declaratively
+Author: Kim Bäckström
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kbck/gramson
+Project-URL: Documentation, https://github.com/kbck/gramson#readme
+Project-URL: Repository, https://github.com/kbck/gramson
+Project-URL: Issues, https://github.com/kbck/gramson/issues
+Keywords: json-logic,json-schema,expressions,validation,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: tests/vendor/jsonlogic/LICENSE
+Requires-Dist: jsonschema<5,>=4.18
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: referencing<1,>=0.28
+Dynamic: license-file
+
+# Gramson
+
+**Define JSON expression languages declaratively.**
+
+Gramson compiles composable YAML operator definitions into recursive JSON Schema
+grammars. Its CLI generates languages and validates JSON or YAML expressions,
+with readable error locations and no network requests during validation.
+
+## Install and validate
+
+Requires Python 3.10 or newer. Install in a virtual environment:
+
+```sh
+python -m pip install gramson
+gramson validate expression.json
+gramson validate expression.yaml
+```
+
+For example, `expression.yaml` can contain:
+
+```yaml
+if:
+  - '>':
+      - var: age
+      - 18
+  - adult
+  - minor
+```
+
+Read one expression from stdin:
+
+```sh
+printf '%s\n' '{"var":"price"}' | gramson validate -
+printf '%s\n' 'var: price' | gramson validate --format yaml -
+```
+
+Files ending in `.yaml` or `.yml` are read as YAML; other files and stdin default
+to JSON. Use `--format json` or `--format yaml` to override detection. Each input
+contains one expression, without an API request envelope. YAML values must be
+representable as JSON: duplicate or non-string keys, non-finite numbers,
+timestamps, and cyclic aliases are rejected. Quote dates to use them as strings.
+
+Exit codes are `0` for valid syntax, `1` for an invalid expression, and `2` for
+input, schema, or command usage errors. `python -m gramson validate ...` is also supported.
+
+## Generate and extend a language
+
+The [ready-to-run extension example](https://github.com/kbck/gramson/tree/main/examples/extension)
+contains manifests, a custom operator, JSON/YAML expressions, and instructions.
+It is also included in the source distribution; run `make setup` and `make example`
+from its repository or source-distribution root.
+The [bitwise extension](https://github.com/kbck/gramson/tree/main/examples/bitwise)
+adds `&`, `|`, `^`, `~`, `<<`, `>>`, `hexToInt`, and `intToHex`;
+run it with `make example-bitwise`.
+Its reusable declarations are bundled in Gramson and can be selected directly:
+
+```yaml
+include:
+  - gramson:core
+  - gramson:bitwise
+```
+
+No declaration copying is needed. Add `operatorDirectories` for local groups,
+or include only `gramson:bitwise` to select it without core. Duplicate includes,
+unknown names, and operator, definition-name, or output-path collisions are errors.
+
+User-owned libraries can use their own namespaces:
+
+```yaml
+include:
+  - gramson:core
+  - mystuff:myops
+```
+
+```sh
+gramson generate --manifest language.yaml --spec-path ./vendor --output-directory generated
+```
+
+This reads operator declarations from `vendor/mystuff/myops/` recursively.
+Repeat `--spec-path` for multiple libraries; paths are relative to the command's
+working directory. `gramson:` is reserved for bundled definitions. Unknown or
+ambiguous includes fail, and namespace labels do not prefix operator keys.
+Generated schemas remain self-contained and validate without the source library.
+See the [external library example](https://github.com/kbck/gramson/tree/main/examples/external),
+also runnable with `make example-external` from the source distribution.
+
+`gramson generate --output-directory generated` writes the bundled core grammar
+as a self-contained directory. For a custom language, create a manifest:
+
+```yaml
+# my-language/language.yaml
+include:
+  - gramson:core
+operatorDirectories:
+  - custom
+```
+
+Add declarations in `my-language/custom/wrapping.yaml`:
+
+```yaml
+wrap:
+  schemaName: wrapper
+  title: Wrapper
+  summary: Wrap one expression.
+  argumentKind: expression
+  minArgs: 1
+  maxArgs: 1
+```
+
+```sh
+gramson generate --manifest my-language/language.yaml --output-directory generated
+gramson validate expression.yaml --schema generated/expression.schema.yaml
+```
+
+Generated output includes core and custom schemas, shared definitions, and one
+expression entry point; operators can nest across groups. Keep the output
+directory together when moving it. Validation against `--schema` uses those
+files offline and does not depend on the installed core language.
+
+Without `include`, a manifest selects only local directories.
+`include: [gramson:core]` alone selects just core. Include order does not give
+precedence: duplicate operator keys, definition names, or output paths fail the
+whole generation. Pin the Gramson version for reproducible bundled declarations.
+Custom declarations define syntax; they do not implement evaluation.
+
+## Compatibility and contents
+
+The included JSON Logic syntax profile covers all 34 documented operators plus
+the `?:` alias. All 278 expressions in the pinned upstream corpus pass syntax
+validation. Gramson applies stricter argument counts and object-shape rules than
+the reference interpreter and validates every branch. There is no evaluator;
+runtime equivalence is not tested.
+
+The wheel includes the generated schemas under `gramson.schemas`, preserving
+relative references for offline use. They can be accessed with
+`importlib.resources.files("gramson.schemas")`. Core and optional extension declarations are bundled
+under `gramson.specs`, and the generator is included in the installed package.
+The source distribution also contains tests and user documentation.
+
+See the [repository and development guide](https://github.com/kbck/gramson#readme),
+[operator specification](https://github.com/kbck/gramson/blob/main/spec/README.md),
+and [issue tracker](https://github.com/kbck/gramson/issues).
+
+## License and acknowledgements
+
+Gramson is licensed under MIT. Its included expression language builds on
+[JSON Logic](https://jsonlogic.com/), created by Jeremy Wadhams. The vendored
+upstream tests retain their original MIT license and attribution; see the
+[third-party notices](https://github.com/kbck/gramson/blob/main/THIRD_PARTY_NOTICES.md).

gramson-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Gramson
+
+**Define operators once. Generate the grammar that validates your JSON expressions.**
+
+Adding operators to a JSON expression language means keeping its syntax rules
+and validation in sync. Gramson compiles YAML operator declarations into a
+recursive JSON Schema grammar, so adding an operator or changing its arguments
+doesn't require hand-editing the validation schema.
+
+## Why Gramson?
+
+JSON Schema can already validate recursive expressions. Gramson generates the
+operator objects, argument-count constraints, shorthand forms, and references
+from your declarations. JSON Logic supplies the bundled starting profile;
+you can extend it or define an independent language.
+
+**Operator libraries become composable grammar modules.** Include groups from
+different libraries, and their operators can nest inside one another. The
+combined grammar is generated from the selected definitions and works with
+standard Draft 2020-12 JSON Schema validators.
+
+Gramson is a Python library and CLI. It defines and validates syntax; it does
+not evaluate expressions.
+
+## Example
+
+Declare an operator that takes exactly one expression:
+
+```yaml
+wrap:
+  argumentKind: expression
+  minArgs: 1
+  maxArgs: 1
+```
+
+Combine it with the bundled core language, and the generated schema accepts:
+
+```json
+{"wrap": [{"+": [1, 2]}]}
+```
+
+It rejects `{"wrap": [1, 2]}` because `wrap` takes one argument. Recursive
+references let your operators nest inside core operators, and vice versa.
+
+## Try it
+
+Requires Python 3.10 or newer. From a checkout:
+
+```sh
+make setup
+make example
+```
+
+This installs the CLI, generates a language with `wrap`, and validates the
+included JSON and YAML expressions. The [complete example](examples/extension/README.md)
+contains the manifest, declarations, and expressions ready to edit.
+
+For your own files, the workflow is:
+
+```sh
+. .venv/bin/activate
+gramson generate --manifest language.yaml --output-directory generated
+gramson validate expression.yaml --schema generated/expression.schema.yaml
+```
+
+Generated output is self-contained and validates offline. Without `--schema`,
+validation uses the bundled core grammar. See the [usage guide](docs/USAGE.md)
+for input formats, stdin, exit codes, and custom languages.
+
+## Compose a language
+
+Select bundled groups and local declarations in a manifest:
+
+```yaml
+include:
+  - gramson:core
+  - gramson:bitwise
+operatorDirectories:
+  - custom
+```
+
+- **Core:** a JSON Logic syntax profile covering 34 documented operators plus
+  `?:`. All 278 expressions in the pinned upstream corpus pass syntax validation.
+  Structural rules are stricter than the reference interpreter; runtime
+  equivalence is untested.
+- **Bitwise:** six bitwise operators plus `hexToInt` and `intToHex` conversion
+  forms. Try `make example-bitwise`.
+- **Your libraries:** include names such as `mystuff:myops` with explicit
+  `--spec-path` search roots. Try `make example-external`.
+
+Include order gives no precedence: duplicate operator keys, definition names,
+or output paths fail generation. The [specification guide](spec/README.md)
+explains declarations and include resolution.
+
+## Documentation
+
+- [Usage and CLI](docs/USAGE.md)
+- [Operator specification and manifest format](spec/README.md)
+- [Scope, compatibility boundaries, and open questions](docs/DESIGN.md)
+- [Development commands and repository layout](docs/DEVELOPMENT.md)
+- [Swagger schema viewer](docs/README.md)
+
+To work on Gramson, run `make check` for Ruff, OpenAPI validation, and tests.
+Run `make help` for all targets.
+
+## License and acknowledgements
+
+[MIT](LICENSE). The included JSON Logic profile builds on
+[JSON Logic](https://jsonlogic.com/), created by Jeremy Wadhams. Its shared test
+corpus is vendored with the original MIT license and attribution; see
+[third-party notices](THIRD_PARTY_NOTICES.md).

gramson-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+## JSON Logic shared tests
+
+The files `tests/vendor/jsonlogic/tests.json` and
+`tests/vendor/jsonlogic/LICENSE` are copied verbatim from the upstream JSON Logic
+project maintained by Jeremy Wadhams.
+
+Copyright (c) 2015 Jeremy Wadhams. Licensed under the MIT License; the complete
+copyright, permission, and warranty notice is included in
+[tests/vendor/jsonlogic/LICENSE](tests/vendor/jsonlogic/LICENSE).
+
+The [snapshot metadata](tests/vendor/jsonlogic/snapshot.json) identifies the
+immutable upstream revisions, source URLs, and SHA-256 checksums. See the
+[vendoring guide](tests/vendor/jsonlogic/README.md) for usage and update rules.

gramson-0.1.0/docs/DESIGN.md

@@ -0,0 +1,55 @@
+# Scope and design decisions
+
+## Scope and decisions
+
+
+- Accept JSON scalar literals and recursive arrays of expressions.
+- Represent each operation as a closed object with exactly one registered key.
+- Support data access, conditionals, Boolean logic, comparisons, arithmetic,
+  collections, strings, and logging syntax.
+- Accept variable defaults, numeric and computed keys, unary shorthand, and
+  the documented arity profile.
+- Reject unknown operators and arbitrary object literals throughout expressions,
+  including inside arrays, defaults, and unselected branches.
+
+This specifies structural acceptance. It does not implement evaluation or
+semantic typing. For example, `{"+": [true, "2", null]}` and
+`{"map": [true, "body"]}` pass syntax validation without promising meaningful
+evaluation. The profile constrains arities rather than accepting every malformed
+call that a permissive interpreter might process.
+
+`if` and its `?:` alias accept condition/result pairs with an optional final fallback. The agreed
+runtime result is `null` when no condition matches and no fallback is supplied;
+there is no evaluator yet to execute that rule.
+Empty argument lists are accepted and yield `null` in JSON Logic. A single
+argument is a fallback expression; non-array shorthand is also accepted.
+
+Results are data rather than expressions. The hand-written
+[JSON-value schema](json-value.schema.yaml) accepts scalars, recursive
+arrays, and arbitrary objects. It reuses `scalarLiteral` from the generated shared schema
+but defines its own recursive containers so result objects are never treated as
+operator calls.
+
+## Open design questions
+
+
+- **Semantic typing:** Should a separate phase check operand and result types?
+  How would it learn variable types and handle null or missing values?
+- **Explicit conversions:** This remains the preferred direction. Unary `+` and
+  `!!` are accepted syntax, but conversion failures and implicit coercions
+  remain undecided.
+- **Named constants:** Are they needed, and how should they be represented,
+  scoped, and distinguished from external data?
+- **Custom operator extensions:** The registry describes build-time syntax.
+  Runtime operator registration, scoping, and versioning remain unspecified.
+- **Evaluation and compatibility:** Lookup, truthiness, arithmetic, equality,
+  collection scope, short-circuiting, and errors require decisions. The
+  no-fallback `if` result is settled as `null`.
+
+## Next steps
+
+
+Settle semantic typing, conversions, and runtime compatibility before building
+an evaluator. For each syntax change, update the relevant operator file, regenerate the
+schemas, and add accepted and rejected examples.
+

gramson-0.1.0/docs/DEVELOPMENT.md

@@ -0,0 +1,111 @@
+# Developing Gramson
+
+## Files
+
+
+- `spec/language.yaml`: selects the operator directories included in the language.
+- `spec/core/*.yaml`: operator syntax, arities, names, titles, and summaries,
+  grouped into data, logic, comparison, arithmetic, collection, string, and debugging.
+  Longer descriptions are optional.
+- `spec/extensions/*.yaml`: reusable optional extensions, selected explicitly by
+  manifests through `include` (currently `gramson:bitwise`).
+- `gramson/generation.py`: loads and composes specifications and generates schemas.
+- `tools/generate_schema.py`: repository generation entry point used by `make generate`.
+- `gramson/cli.py`: generates grammars and validates JSON or YAML expressions.
+- `pyproject.toml`: package metadata, runtime dependencies, and the `gramson` command.
+- `schema/expression.schema.yaml`: generated language entry point.
+- `schema/core/*.schema.yaml`: generated named operator definitions, mirroring
+  the source directories and file base names.
+- `schema/shared.schema.yaml`: generated shared definitions such as `scalarLiteral`.
+- `docs/json-value.schema.yaml`: hand-written result-data grammar.
+- `examples/valid.json` and `examples/invalid.json`: accepted and rejected
+  expressions; only each entry's `expression` is validated.
+- `tests/test_validation.py`: metaschema and example validation.
+- `tests/test_jsonlogic.py`: offline syntax compatibility checks against the
+  pinned upstream [JSON Logic test corpus](../tests/vendor/jsonlogic/README.md),
+  with its MIT license, provenance, checksums, and compatibility expectations.
+- `tests/test_generation.py`: generation freshness, operator coverage, arities,
+  shorthand, documentation, and registry validation.
+- `tests/test_language.py`: directory selection, deterministic composition,
+  collision diagnostics, mirrored output, and cross-group recursion.
+- `tests/test_openapi.py`: external references, request validation, and result
+  validation against the hand-written API contract.
+- `docs/openapi.yaml`: hand-written placeholder `POST /evaluate` specification;
+  its only schema components reference `expression` and `jsonValue`.
+- `docs/index.html`: Swagger viewer; see [viewing instructions](README.md).
+- `requirements-dev.txt`: generation, validation, YAML-reading, and Ruff linting dependencies.
+
+## Layout and composition
+
+
+```text
+spec/                         schema/
+  language.yaml                 expression.schema.yaml
+                                shared.schema.yaml
+  core/                         core/
+    arithmetic.yaml               arithmetic.schema.yaml
+    logic.yaml                    logic.schema.yaml
+    ...                           ...
+```
+
+The repository manifest currently enables only its local `core`. Additional directories can be
+enabled explicitly; operator sources are scanned recursively and sorted.
+Duplicate operator keys or `schemaName` values are errors with both source
+paths reported. Each group references the root expression grammar, allowing
+nested expressions from every enabled group. See the specification guide for
+manifest rules and custom output locations.
+
+## Generate and validate
+
+
+Requires Python 3.10 or newer. From the repository root:
+
+```sh
+make setup
+make generate
+make check
+```
+
+Run `make` or `make help` to list targets:
+
+| Target | Purpose |
+| --- | --- |
+| `setup` | Create `.venv` and install the CLI and development dependencies. |
+| `generate` | Generate the expression, shared, and operator JSON Schemas. |
+| `example` | Generate and validate the included core extension example. |
+| `example-bitwise` | Generate and validate the bitwise extension example. |
+| `example-external` | Generate and validate a user-owned namespace include. |
+| `lint` | Run Python and OpenAPI linting. |
+| `lint-python` | Check Python code and import ordering with Ruff. |
+| `lint-openapi` | Validate the hand-written OpenAPI document and external references with [openapi-spec-validator](https://openapi-spec-validator.readthedocs.io/en/stable/cli.html). |
+| `test` | Run all tests, including schema validation and generation freshness. |
+| `check` | Run lint and tests without rewriting generated files. |
+| `setup-release` | Install development and release tooling. |
+| `build` | Build a source archive and a wheel from that source archive. |
+| `check-dist` | Build and check metadata, bundled schemas, and the installed CLI. |
+| `serve` | Regenerate schemas and serve the Swagger viewer at `http://127.0.0.1:8765/docs/`. |
+
+Override `PYTHON` or `VENV` for setup, or `HOST` and `PORT` for the viewer,
+for example `make serve PORT=8000`. Run `make setup` before other targets.
+The OpenAPI wrapper and JSON-value schema remain hand-written; `make generate`
+only rebuilds the expression grammar. `make check` fails when generated schemas
+are stale, so regenerate and commit them after changing operator sources.
+
+[GitHub Actions](../.github/workflows/check.yml) runs `make check` on every push and
+pull request with Python 3.10 and 3.14. CI checks the committed schemas without
+regenerating them.
+It also builds and verifies the wheel and source distribution. The
+[release guide](RELEASING.md) documents local checks and the PyPI Trusted
+Publishing setup. Publishing a matching GitHub release triggers the separate
+publication workflow; routine pushes and pull requests only build and check.
+
+Python linting uses Ruff, configured in `pyproject.toml` for Python 3.10 with
+error, unused-code, and import-order checks. `make lint-python` checks without
+rewriting files. To apply safe fixes locally, run `.venv/bin/python -m ruff check . --fix`.
+Ruff is a development dependency; the installed CLI does not require it.
+
+Generation uses PyYAML to read and write YAML. Tests use local schemas and bundled
+metaschema support, with no remote schema fetches. The expression, shared, and grouped operator schemas are
+generated; edit the OpenAPI and JSON-value schemas directly when their contracts
+change. Tests assert syntax and data shape, not evaluation results.
+