@owenlamont/ryl-linux-x64-musl 0.9.1 → 0.9.2

package/README.md

@@ -1,16 +1,27 @@
 # ryl
 
-ryl - the Rust Yaml Linter is intended to ultimately be a drop in replacement for
-[yamllint](https://github.com/adrienverge/yamllint). It is usable today, but
-parity and edge-case behavior are still maturing.
+ryl - the Rust YAML linter - is intended to ultimately be a drop-in
+replacement for [yamllint](https://github.com/adrienverge/yamllint). It is
+usable today, but parity and edge-case behaviour are still maturing.
 
-Compatibility note:
+Full documentation lives at <https://ryl-docs.pages.dev/>.
 
-- `ryl` aims to match `yamllint` behavior and includes many parity tests.
-- `ryl` uses the `saphyr` parser stack, while `yamllint` uses the `PyYAML` parser stack.
+## Compatibility note
+
+- `ryl` aims to match `yamllint` behaviour and includes many parity tests.
+- `ryl` uses the `saphyr` parser stack, while `yamllint` uses the `PyYAML`
+  parser stack.
 - `saphyr` and `PyYAML` do not always agree on which files are valid YAML.
+- **`ryl` targets YAML 1.2 strictly.** `yamllint` defaults to YAML 1.1
+  semantics, so bareword booleans like `yes` / `no` / `on` / `off` (and
+  case variants) are plain strings in `ryl` and booleans in `yamllint`.
+  Leading-zero integers like `0755` are decimal in `ryl` and octal in
+  `yamllint`. The same 1.2 semantics also apply when `ryl` parses
+  `.yamllint` configuration files inherited from `yamllint`. See the
+  [YAML version compatibility](https://ryl-docs.pages.dev/yaml-version/)
+  page for the practical implications.
 
-## Quick Start
+## Quick start
 
 ```bash
 # Using uv (Python)
@@ -25,262 +36,72 @@ For `prek` / `pre-commit` integration, see
 
 ## Installation
 
-### uv
-
 ```bash
-uv tool install ryl
-```
-
-### NPM
-
-```bash
-npm install -g @owenlamont/ryl
-```
-
-### pip
-
-```bash
-pip install ryl
-```
-
-### Cargo
-
-```bash
-cargo install ryl
-```
-
-## Usage
-
-ryl accepts one or more paths: files and/or directories.
-
-Basic:
-
-```text
-ryl <PATH_OR_FILE> [PATH_OR_FILE...]
-```
-
-Behavior:
-
-- Files: parsed as YAML even if the extension is not `.yml`/`.yaml`.
-- Directories: recursively lints `.yml` and `.yaml` files.
-  - Respects `.gitignore`, global git ignores, and git excludes.
-  - Does not follow symlinks.
-
-Exit codes:
-
-- `0` when all parsed files are valid (or no files found).
-- `1` when any invalid YAML is found.
-- `2` for CLI usage errors (for example, no paths provided).
-
-Examples:
-
-```text
-# Single file
-ryl myfile.yml
-
-# Multiple inputs (mix files and directories)
-ryl config/ another.yml
-
-# Multiple directories
-ryl dir1 dir2
-
-# Explicit non-YAML extension (parsed as YAML)
-ryl notes.txt
-```
-
-Help and version:
-
-```text
-Fast YAML linter written in Rust
-
-Usage: ryl [OPTIONS] [PATH_OR_FILE]...
-
-Arguments:
-  [PATH_OR_FILE]...  One or more paths: files and/or directories
-
-Options:
-  -c, --config-file <FILE>           Path to configuration file (YAML or TOML)
-  -d, --config-data <YAML>           Inline configuration data (yaml)
-  -f, --format <FORMAT>              Output format (auto, standard, colored, github,
-                                     parsable) [default: auto]
-                                     [possible values: auto, standard, colored,
-                                     github, parsable]
-      --print-toml-config-schema     Print the JSON Schema for ryl TOML config
-                                     and exit
-      --print-yaml-config-schema     Print the JSON Schema for yamllint-compatible
-                                     YAML config and exit
-      --fix                          Apply safe fixes in place before reporting
-                                     remaining diagnostics
-      --migrate-configs              Convert discovered legacy YAML config files
-                                     into .ryl.toml files
-      --list-files                   List files that would be linted (reserved)
-  -s, --strict                       Strict mode (reserved)
-      --no-warnings                  Suppress warnings (reserved)
-      --migrate-root <DIR>           Root path to search for legacy YAML config
-                                     files (default: .)
-      --migrate-write                Write migrated .ryl.toml files (otherwise
-                                     preview only)
-      --migrate-stdout               Print generated TOML to stdout during migration
-      --migrate-rename-old <SUFFIX>  Rename source YAML configs by appending
-                                     this suffix after migration
-      --migrate-delete-old           Delete source YAML configs after migration
-  -h, --help                         Print help
-  -V, --version                      Print version
-```
-
-## Performance benchmarking
-
-This repo includes a standalone benchmark script that compares PyPI `ryl` and
-`yamllint` using synthetic YAML corpora and `hyperfine`.
-
-Prerequisites:
-
-- `uv`
-- `hyperfine`
-
-Run a quick sample:
-
-```text
-uv run scripts/benchmark_perf_vs_yamllint.py --file-counts 25,100 --file-sizes-kib 1,8 --runs 5 --warmup 1
-```
-
-Run a fuller matrix (explicit lists):
-
-```text
-uv run scripts/benchmark_perf_vs_yamllint.py --file-counts 25,100,400,1000 --file-sizes-kib 1,8,32,128 --runs 10 --warmup 2
-```
-
-Run a fuller matrix (ranges with increments):
-
-```text
-uv run scripts/benchmark_perf_vs_yamllint.py --file-count-start 100 --file-count-end 1000 --file-count-step 100 --file-size-start-kib 4 --file-size-end-kib 64 --file-size-step-kib 4 --runs 10 --warmup 2
-```
-
-The script uses Typer; use `--help` for all options.
-
-Artifacts are written under `manual_outputs/benchmarks/<UTC_TIMESTAMP>/`:
-
-- `benchmark.png` and `benchmark.svg`: side-by-side facet plot with shared Y axis.
-- `summary.csv`: aggregated timing table.
-- `meta.json`: tool versions and run parameters.
-- `hyperfine-json/`: raw results from `hyperfine`.
-
-Example benchmark figure (5x5 matrix, 5 runs per point):
-
-![Benchmark: ryl vs yamllint scaling (5x5 matrix, 5 runs per point)](https://raw.githubusercontent.com/owenlamont/ryl/v0.3.4/img/benchmark-5x5-5runs.svg)
-
-## Configuration
-
-- Flags:
-  - `-c, --config-file <FILE>`: path to a YAML or TOML config file.
-  - `-d, --config-data <YAML>`: inline YAML config (highest precedence).
-  - `--print-toml-config-schema`: print the JSON Schema for `.ryl.toml` / `ryl.toml` / `[tool.ryl]`.
-  - `--print-yaml-config-schema`: print the JSON Schema for yamllint-compatible
-    YAML config files such as `.yamllint` / `.yamllint.yml` / `.yamllint.yaml`.
-  - `--fix`: apply safe fixes in place before reporting remaining diagnostics.
-  - `--list-files`: print files that would be linted after applying ignores and exit.
-  - `--migrate-configs`: discover legacy YAML configs and plan TOML migration.
-  - `--migrate-root <DIR>`: root to search for legacy YAML configs (default `.`).
-  - `--migrate-write`: write migrated `.ryl.toml` files (without this it is preview-only).
-  - `--migrate-stdout`: print generated TOML in migration mode.
-  - `--migrate-rename-old <SUFFIX>`: rename discovered legacy YAML config files after writing.
-  - `--migrate-delete-old`: delete discovered legacy YAML config files after writing.
-  - `-f, --format`, `-s, --strict`, `--no-warnings`: reserved for compatibility.
-- Discovery precedence:
-  inline `--config-data` > `--config-file` > env `YAMLLINT_CONFIG_FILE`
-  (global) > nearest project config up the tree:
-  TOML (`.ryl.toml`, `ryl.toml`, `pyproject.toml` with `[tool.ryl]`) then
-  YAML fallback (`.yamllint`, `.yamllint.yml`, `.yamllint.yaml`)
-  > user-global (`$XDG_CONFIG_HOME/yamllint/config` or
-  `~/.config/yamllint/config`) > built-in defaults.
-- **Rules Documentation**: see [docs/rules.md](https://github.com/owenlamont/ryl/blob/main/docs/rules.md)
-  for a full list of supported rules and their fixable status.
-- TOML and YAML are not merged during discovery. If a TOML project config is
-  found, YAML project config discovery is skipped (and `ryl` prints a warning).
-- Native fix policy and per-file ignores are TOML-only. YAML config remains
-  yamllint-compatible and does not support ryl-native settings.
-- Per-file behavior: unless a global config is set via `--config-data`,
-  `--config-file`, or `YAMLLINT_CONFIG_FILE`, each file discovers its nearest
-  project config. Ignores apply to directory scans and explicit files (parity).
-- Presets and extends: supports yamllint’s built-in `default`, `relaxed`, and
-  `empty` via `extends`. Rule maps are deep-merged; scalars/sequences overwrite.
-- TOML preset examples: see
-  [docs/config-presets.md](https://github.com/owenlamont/ryl/blob/main/docs/config-presets.md)
-  for `default`/`relaxed` equivalents.
-- Canonical schema artifacts are checked into this repo as:
-  - `ryl.toml.schema.json` for `.ryl.toml` / `ryl.toml` / `[tool.ryl]`
-  - `ryl.yaml.schema.json` for yamllint-compatible YAML config files such as
-    `.yamllint` / `.yamllint.yml` / `.yamllint.yaml`
-- SchemaStore sync only targets the native TOML config and publishes a draft-07
-  projection for `ryl.toml` / `.ryl.toml`. SchemaStore cannot target the
-  `[tool.ryl]` table inside `pyproject.toml`, so that remains covered by the
-  broader `pyproject.toml` schema association.
-- Release-time SchemaStore sync updates `owenlamont/schemastore:ryl-schema-update`
-  after a release succeeds and prints the manual upstream PR details in the
-  workflow summary.
-- Regenerate them with:
-  - `cargo run --quiet --bin ryl -- --print-toml-config-schema > ryl.toml.schema.json`
-  - `cargo run --quiet --bin ryl -- --print-yaml-config-schema > ryl.yaml.schema.json`
-- Print the SchemaStore projection locally with:
-  - `uv run scripts/print_ryl_schemastore_schema.py > /tmp/ryl.schemastore.json`
-
-Example TOML config (`.ryl.toml`):
-
-```toml
-yaml-files = ["*.yaml", "*.yml"]
-ignore = ["vendor/**", "generated/**"]
-locale = "en_US.UTF-8"
-
-[per-file-ignores]
-"**/values.yaml" = ["document-start"]
-"**/kustomization.yaml" = ["document-start"]
-# `!` negates the pattern, so this ignores truthy outside Kubernetes manifests.
-"!k8s/**.yaml" = ["truthy"]
-
-[rules]
-document-start = "disable"
-
-[rules.line-length]
-max = 120
-
-[rules.truthy]
-allowed-values = ["true", "false"]
-
-[fix]
-fixable = ["ALL"]
-unfixable = []
+uv tool install ryl                 # uv
+npm install -g @owenlamont/ryl      # npm
+pip install ryl                     # pip
+cargo install ryl                   # cargo
 ```
 
-For a fully expanded TOML example that names every built-in rule explicitly, see
-[`/.ryl.toml.example`](https://github.com/owenlamont/ryl/blob/main/.ryl.toml.example).
-
-Migration example:
-
-```text
-# Preview migration actions
-ryl --migrate-configs --migrate-root .
-
-# Write .ryl.toml files and keep old files with a suffix
-ryl --migrate-configs --migrate-root . --migrate-write --migrate-rename-old .bak
-```
+## Status and scope
+
+- All 23 yamllint rules are implemented. The current rule reference and
+  per-rule pages are at
+  <https://ryl-docs.pages.dev/rules/>.
+- Auto-fixing (`--fix`) is supported for `braces`, `brackets`, `commas`,
+  `comments`, `comments-indentation`, `new-line-at-end-of-file`,
+  `new-lines`, and `quoted-strings`. The set of rules that may apply
+  fixes is configurable via the TOML `[fix]` table.
+- TOML is the recommended configuration format and supports ryl-only
+  features that have no upstream equivalent: the `[fix]` table,
+  `[per-file-ignores]`, and rule options such as
+  `allow-double-quotes-for-escaping`.
+- yamllint-style YAML configuration is also accepted (`.yamllint`,
+  `.yamllint.yml`, `.yamllint.yaml`) for drop-in compatibility, including
+  the built-in `default`, `relaxed`, and `empty` presets via `extends`.
+  An existing yamllint configuration can be converted with
+  `ryl --migrate-configs --migrate-write`.
+- `--list-files` prints the files ryl would lint (after ignores and
+  config discovery) and exits, without running rules. `--no-warnings`
+  suppresses warning-level diagnostics in the output. `--strict` turns a
+  warning-only run into exit code `2`.
+- Run `ryl --help` for the authoritative CLI reference.
+
+For installation walkthroughs, configuration presets, and per-rule
+documentation, see the docs site.
+
+## Performance
+
+`ryl` is significantly faster than `yamllint` on large trees. The figure
+below is from a 5x5 file-count × file-size matrix with 5 runs per point:
+
+![Benchmark: ryl vs yamllint scaling (5x5 matrix, 5 runs per point)](https://raw.githubusercontent.com/owenlamont/ryl/main/img/benchmark-5x5-5runs.svg)
+
+The benchmark script is in `scripts/benchmark_perf_vs_yamllint.py`; run
+it with `--help` for the full option set.
 
 ## Acknowledgements
 
-This project exists thanks to the tooling and ecosystems around YAML linting and
-developer automation, especially:
-
-- [yamllint](https://github.com/adrienverge/yamllint) - for giving me the shoulders to
-  stand on and the source of many of the automated tests that ryl uses now to check for
-  behaviour parity. Copying the behaviour of an existing tool is infinitely easier than
-  building one from scratch - there'd be no ryl without yamllint.
-- [ruff](https://github.com/astral-sh/ruff) - for showing the power of Rust tooling for
-  Python development and inspiring the config and API for ryl.
-- [rumdl](https://github.com/rvben/rumdl) - for giving me another template to follow for
-  Rust tooling and showing me almost the only dev tool I was still using after this that
-  wasn't written in Rust was yamllint (which inspired me to tackle this project)
-- [saphyr](https://github.com/saphyr-rs/saphyr) - ryl is built on saphyr and saphyr's
-  developers were very patient in showing some of the nuance and complexity of parsing
-  YAML which I was embarrassingly ignorant of when start ryl.
+This project exists thanks to the tooling and ecosystems around YAML
+linting and developer automation, especially:
+
+- [yamllint](https://github.com/adrienverge/yamllint) - for giving me the
+  shoulders to stand on and the source of many of the automated tests
+  that ryl uses now to check for behaviour parity. Copying the behaviour
+  of an existing tool is infinitely easier than building one from
+  scratch - there'd be no ryl without yamllint.
+- [ruff](https://github.com/astral-sh/ruff) - for showing the power of
+  Rust tooling for Python development and inspiring the config and API
+  for ryl.
+- [rumdl](https://github.com/rvben/rumdl) - for giving me another
+  template to follow for Rust tooling and showing me almost the only dev
+  tool I was still using after this that wasn't written in Rust was
+  yamllint (which inspired me to tackle this project).
+- [saphyr](https://github.com/saphyr-rs/saphyr) - ryl is built on saphyr
+  and saphyr's developers were very patient in showing some of the
+  nuance and complexity of parsing YAML which I was embarrassingly
+  ignorant of when starting ryl.
 - [esbuild](https://github.com/evanw/esbuild) and
-  [biome](https://github.com/biomejs/biome) - for providing the "binary wrapper"
-  blueprint for distributing high-performance native tools via NPM.
+  [biome](https://github.com/biomejs/biome) - for providing the "binary
+  wrapper" blueprint for distributing high-performance native tools via
+  NPM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owenlamont/ryl-linux-x64-musl",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Fast YAML linter inspired by yamllint",
   "author": "Owen Lamont",
   "license": "MIT",