[david-Darkcollective]

Part of #17. Design: docs/design.md §3, §4. One commit per issue.

Report commands (#11)

• Every command that reads Relix goes through one loop, ScriptRunner. It takes each script through its session, the catalog, the -i inputs and analysis, then hands it to the command's view. run's rows are one view, now ResultRows; each report command is another.
• check: nothing on stdout, diagnostics on stderr, exit 0 or 3, so find … | xargs relix check is a lint pass. --json writes every script's diagnostics as one document on stdout instead.
• explain: each query's physical plan. A script with several queries heads each plan with -- query NAME. --json writes one {"script", "query", "plan"} object per line.
• optimize: the script with each query statement replaced by query { <rewritten> };. Every other statement and comment is kept as written, so relix optimize slow.relix > fast.relix works. --report prints the rules and the before/after trees instead.
• trace: each query's event feed, rows pulled and discarded. Each query's feed ends with a ROWS event.
• bundle: the playground JSON bundle, still produced for a script that doesn't analyse (with its diagnostics, exit 3).
• ir: the IR report of the whole script.
• provenance: annotated rows with --semiring (default counting) and --weight. A [prov] table on a terminal, JSON in a pipe, or chosen with -o table|json.
• run --trace[=FILE] writes the event feed to stderr, or FILE, while the rows go to stdout. A file is named only with =: Main gives a bare --trace an empty value, so relix --trace q.relix traces q.relix rather than writing over it.
• explain, trace and provenance take --query=NAME.

Engine bug found: Relation.render() writes an optimised CLOSURE with its pushed-down seed in ⟨…⟩, which the parser can't read back (the closure query in introspection.relix). optimize checks that each rewrite parses. One that doesn't is left as written, with a warning, so the output always runs. Filed as DarkCollective/relix-core#100.

fmt (#12)

• relix fmt [SCRIPT...] prints with ScriptPrinter. -w rewrites the files that change. --check changes nothing, names the files that would change, and exits 1 if any would. --glyphs (the default) or --keywords picks the operator spelling; the keyword spelling comes from the reference's language/spellings.md.
• The printer drops comments and can only write glyphs. As S8: relix fmt — canonical script printing #12 asks, that's raised on the engine: Keep comments, and offer the ASCII spelling, when printing a script relix-core#99. Until it lands, fmt keeps comments itself:
  • a comment between statements stays where it was;
  • a statement with a comment inside it is left exactly as written;
  • blank lines collapse to one.
• ScriptText finds statement ends and comments. It follows the two lexers: -- and /* */ outside strings, and inside an inline table only at the start of a line, because a cell or the |---| rule can hold --. Inline tables' columns are aligned.
• A script that doesn't parse is reported as FILE:LINE:COL, left alone, and exits 3.

Management commands (#13)

• drivers ls / drivers install NAME and connectors ls [--available] / connectors install TYPE. They replace the run-time download flags; --allow-download stays for fetching during a run. Listings print through the S2 renderers. Messages go to stderr, and a failed download exits 5.
• doc [TOPIC]: a page found by glyph, keyword or name, rendered and paged through $PAGER (default less with LESS=FRX) on a terminal. --markdown prints the source, --no-pager skips the pager, and --function searches functions only. With no topic, it lists the pages as rows.
  • The index (DocIndex) is built here, over relix-docs' language pages and the installed functions, with the language keyword winning a shared name (fix).
  • It moves to relix-docs with Move the reference lookup into relix-docs: functions and front-end pages in one index relix-core#95.
  • It holds every key of relix-console's index except the REPL's page about itself (repl, relix-repl).
• help [COMMAND] is picocli's HelpCommand. version prints the same line as --version.
• completion bash|zsh|fish|powershell comes from the command model. bash's is picocli's AutoComplete, which runs under zsh through bashcompinit. The fish and PowerShell scripts are generated here.
• CI installs zsh and fish on Linux, so each script is syntax-checked by its own shell there. The runners already have bash and pwsh.

Tests

• src/test/resources/examples: three real scripts from the earlier command (comments, inline tables, views, several queries each). All are offline, and a test keeps them that way. .gitattributes keeps .relix files LF.
• ReportCommandsTest:
  • every report command over every example;
  • a script that doesn't analyse, and -e/stdin sources;
  • check over several files as xargs runs it, and --json;
  • optimize output returns the same rows as the original, for every example;
  • run --trace: rows on stdout and events on stderr in one run, --trace=FILE, and a bare --trace before a script.
• FmtTest, over every example:
  • fmt is idempotent;
  • it parses back to the same statements in both spellings;
  • it keeps every comment in order;
  • the layout rules hold;
  • -w, --check and parse-failure exit codes.
• ManagementCommandsTest, DocIndexTest and PagerTest:
  • doc --markdown resolves every key of every language page;
  • every documented function resolves;
  • the shell syntax checks, which run where the shell is installed.
• Nothing downloads: only the install paths that need no network are run.

./gradlew clean build passes locally (macOS) at each commit.

Fixes #11
Fixes #12
Fixes #13