Blog post about output

Author: fileformat

docs/_posts/2025-04-13-output.md

@@ -0,0 +1,29 @@
+---
+title: Output from namelint
+h1: Output
+---
+
+We are designing what running namelint should produce.  Criteria:
+
+* Guaranteed UTF-8: no invalid Unicode UTF-8 byte sequences
+* Nothing unsafe: looking at the output shouldn't mess up your terminal
+* Separate results (ex: lint errors) from tooling messages (ex: errors loading rules)
+* Distinct: filenames should be as close to actual as possible, but still show what is going on behind the scenes
+* Nice output for humans looking at a tty
+* Nice output when running in CI
+
+## What goes where
+
+* Stdout: Progress updates (controlled by a `--progress` option)
+* Stdout: human-readable lint results
+* Stderr: tooling messages (controlled by a `--loglevel` option)
+* File: machine-readable (=JSON) lint results (controlled by a `--output` option)
+
+## Details
+
+Progress is one of `none`, `dots` or `bar`.  If stdout is a tty, the default is `bar`.  Otherwise the default is `dots`.
+
+The JSON output has:
+* the `filename` if the filename is UTF-8 and has no null bytes.  All non-ASCII characters will use the escaped form (`\uXXXX`), so the file should be 7-bit ASCII safe.
+* a `bytes` version of the filename if there are any non-Posix characters.
+* a `display` version of the filename, with non-Posix characters replaced by `?`