feat: add the -validate mode to interpres-decode

Assisted-by: GLM 5.3 Flash

docs/CLI.md

@@ -1,26 +1,45 @@
 # Command line
 
-The reference below is taken from the program itself. `interpres-decode` is the
-toml-test harness adapter, not a general-purpose tool: it takes no flags and no
-arguments, reads one TOML document from stdin, and writes the toml-test
-tagged-JSON form to stdout.
+The reference below is taken from the program itself. `interpres-decode` is
+the toml-test harness adapter, and it also validates documents. Install it
+with Go itself, no release assets involved:
+
+```sh
+go install sourcedock.dev/petrbalvin/interpres/cmd/interpres-decode@latest
+```
 
 ## Synopsis
 
 ```sh
-interpres-decode < document.toml
+interpres-decode [flags]
+interpres-decode -validate [file ...]
 ```
 
-Build it with `just build`, which compiles it into `bin/interpres-decode`, or
-run it straight from the module directory with `just run`.
+Without `-validate` the program is the toml-test adapter: it takes no
+arguments, reads one TOML document from stdin, and writes the toml-test
+tagged-JSON form to stdout. Build it locally with `just build`, which
+compiles it into `bin/interpres-decode`, or run it straight from the module
+directory with `just run`.
+
+With `-validate` the program parses each named file instead, or stdin when no
+file is named, and prints one line per invalid document to stderr. It is
+quiet on valid documents, which is the shape a CI step wants. The `-` name
+means stdin.
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `-validate` | validate the documents instead of emitting tagged JSON |
+| `-h` | print the usage |
 
 ## Exit codes
 
 | Code | Meaning |
 |---|---|
-| `0` | the document parsed, tagged JSON written to stdout |
-| `1` | parse error, the document is malformed; the message goes to stderr |
-| `2` | reading stdin failed, or a value has no tagged representation |
+| `0` | adapter: the document parsed and the tagged JSON was written; validate: every document parsed |
+| `1` | adapter: parse error; validate: at least one document is invalid |
+| `2` | a usage error, a read failure, or a value with no tagged representation |
 
 ## Wire format
 
@@ -59,8 +78,23 @@ port = 9090
 ' | ./bin/interpres-decode
 ```
 
-The output is the equivalent value tree as one JSON object. Run the official
-compliance suite against the binary:
+The output is the equivalent value tree as one JSON object. Validate the
+TOML files of another repository in CI:
+
+```sh
+interpres-decode -validate config.toml deploy/example.toml
+```
+
+An invalid document reports the file and the library's line number:
+
+```sh
+$ interpres-decode -validate bad.toml
+bad.toml: interpres: line 1: expected a value
+$ echo $?
+1
+```
+
+Run the official compliance suite against the adapter:
 
 ```sh
 just toml-test