Skip to content

Repository navigation

presentation.md

Latest commit

 

History

History
205 lines (185 loc) · 11.8 KB

presentation.md

File metadata and controls

205 lines (185 loc) · 11.8 KB
Raw

CLI presentation and completion

← CLI contract index

CLI presentation and completion (#164, #186)

The wright command model is defined once with clap. The same model drives argv parsing, generated help, and shell completion:

# Pure completion generation (stdout)
wright completion bash
wright completion zsh
wright completion fish
wright completion powershell

# Automatic or explicit user-local completion installation
wright completion install
wright completion install zsh
wright completion install --dir <DIR>
wright completion install --dry-run
wright completion install --all

Shell completion lifecycle (#186)

Wright manages its completion lifecycle directly so installations and updates provide working completions without duplicating shell filesystem logic or mutating shell startup configuration:

  • wright completion <shell>: generates pure static completion scripts for Bash, Zsh, Fish, or PowerShell (pwsh) directly to stdout for manual setup or package-manager packaging.
  • wright completion install [SHELL]: detects the current shell (or takes an explicit shell/--shell override) and installs generated completion into the standard conventional user-local directories without modifying .zshrc, .bashrc, or user startup scripts.
    • --dir <DIR> overrides the target directory.
    • --dry-run prints planned installation paths without writing files.
    • --all installs/refreshes completions for all supported shells.
    • --force forces re-writing existing completion files.
  • Shell detection: resolves $WRIGHT_SHELL first, then inspects $SHELL path/filename, followed by shell environment variables (ZSH_VERSION, BASH_VERSION, FISH_VERSION, PSModulePath), falling back to PowerShell on Windows.
  • Conventional installation locations:
    • Fish: ~/.config/fish/completions/wright.fish (or ~/.local/share/fish/vendor_completions.d/wright.fish), automatically loaded by Fish.
    • Bash: ~/.local/share/bash-completion/completions/wright (or ~/.bash_completion.d/wright), loaded automatically when bash-completion is active.
    • Zsh: $ZSH_CUSTOM/completions/_wright (if $ZSH_CUSTOM set), ~/.oh-my-zsh/custom/completions/_wright (if Oh My Zsh exists), ~/.zfunc/_wright, ~/.zsh/completions/_wright, or ~/.local/share/zsh/site-functions/_wright.
    • PowerShell: ~/Documents/PowerShell/Scripts/_wright.ps1 (Windows) or ~/.config/powershell/completions/_wright.ps1 (Unix).
  • Install and Update integration:
    • install.sh invokes wright completion install post-installation and reports non-fatal guidance if automatic completion installation cannot run.
    • wright update refreshes existing Wright completion files in conventional locations upon replacing the binaries so completions stay aligned with the installed command model.
  • Package-manager boundaries: Homebrew, Scoop, and WinGet packaging consume wright completion <shell> generation using native package conventions rather than maintaining hand-written completion scripts.

Workflow commands accept these CLI-only presentation options:

  • --format text|json selects human or machine output (-f remains an alias).
  • --renderer auto|terminal|plain|github-actions selects the presentation environment. auto selects GitHub Actions when GITHUB_ACTIONS is truthy, plain output for generic CI or a non-TTY, and terminal output otherwise.
  • --color auto|always|never controls ANSI color. Explicit options take precedence over environment detection; GitHub Actions keeps workflow command lines free of ANSI even when color is explicitly requested.

check, analyze, lint, and inspect cost also accept the finding-selection options --severity, --rule-id, --file, and --max (#430), applied by the driver to reported diagnostics and lint findings. Selection is a rendering concern only: it runs after the verdict and exit code are fixed on the complete set, so it can never turn a failing command into exit 0 or a WARN verdict into PASS. Consecutive lint findings sharing a rule id and message render as one entry listing all locations; when --max withholds findings, text output states the withheld count and the JSON envelope carries selection.total/selection.withheld beside the filtered array.

JSON output is one wright-result/v1 envelope on stdout with no ANSI, progress, or workflow commands. The convert source artifact and the compile -o - program remain the only stdout payloads in text mode, including when GitHub Actions presentation is selected; every other compile report is a verdict, the written path, and the output SHA-256. GitHub Actions diagnostics and findings are emitted as escaped workflow annotations; grouping is sent to the workflow command stream and a concise PASS/WARN/ERROR line is appended to GITHUB_STEP_SUMMARY when the runner provides that file. The summary uses the highest structured severity: errors produce ERROR, warnings produce WARN, and info/notice-only results produce PASS.

Interactive terminal mode is TUI-lite by design. For text workflows selected as terminal, Wright prints immediate activity feedback and then renders truthful session phases such as input resolution, parsing, semantic analysis, linting, emission, or conversion. A lightweight spinner starts only after a short anti-flicker threshold; phase output is transient and is fully cleared before the final verdict, diagnostics, report, or source artifact is rendered. Completed check, lint, analyze, inspect, and the inspect query subcommands (symbols, refs, cfg, callgraph, cost) print a command-specific PASS/WARN/ERROR verdict and compact summary before details; diagnostics and findings include a one-line source context when the reported provenance path is readable. The driver exposes typed progress events through ProgressObserver; no terminal strings, spinner frames, ANSI sequence, or source context enters the driver envelope or JSON. Plain output, redirected/piped output, TERM=dumb, CI, GitHub Actions, and explicit JSON rendering remain static and deterministic.

On the terminal renderer only, a report with independent multi-line items is drawn on one continuous rail (#703, #718). The verdict line opens it with ╭─, every section heading, count, and child line continues it with │, each item (envelope diagnostic, lint finding or fix entry, analyze risk item, inspect cfg block, inspect rules --content entry) branches off with ├─, and the footer closes it with ╰─, even when a trailing detail hint follows it in the flat layout; a report without a footer ends on a bare ╰─. A blank rail line separates independent blocks, except between a one-line section heading and its first item. Content sits on one column, so locations, source frames, and secondary notes align under the item text. Rail glyphs draw dim when color is on, so severity labels and messages keep prominence. A report with no multi-line item, such as a clean check (two undecorated lines), stays flat. The rail is a terminal detail: lines keep the stdout/stderr stream they use elsewhere, plain, GitHub Actions, CI, and JSON keep their existing undecorated layout byte-for-byte, and the reported findings, verdicts, exit codes, caps, and --all expansion are identical across renderers.

The check report follows a human-first hierarchy (#443) on the terminal/plain text surface only: the verdict line leads with the blocking error count before the non-blocking severities, diagnostics render in action order (errors before warnings and info notes, stable within a severity), and a mapped diagnostic carries its --> location plus a one-line source frame on the diagnostic stream. Spans whose path is not a readable source file, such as <stdin>, <provider-artifact>, or a dangling <file N>, are never dressed up as file locations; the reported position and the pipeline stage trail each diagnostic as secondary metadata instead. A diagnostic whose code carries an unknown- kind (a rejected Workshop or OverPy name) is followed by a one-line hint: run 'wright lookup' ... pointer on check and compile (#529, ADR-0021); an OPY-origin diagnostic names its vocabulary: wright lookup --language opy (#692). The hint is text presentation only and never enters the envelope. A compact footer closes the report with the count of affected source files and, on an interactive terminal, the elapsed workflow time; plain output omits wall-clock values so it stays deterministic. Severity ordering, secondary metadata, the lookup hint, and the footer are presentation-layer concerns: the wright-result/v1 envelope keeps the driver's diagnostic set and production order, and the GitHub Actions renderer is unchanged.

The lint report applies the same hierarchy to findings: the verdict leads with finding counts by severity, findings render in action order, and a finding entry leads with severity, rule id, and message before its --> location and one-line source frame. Evidence class and boundedness trail dimmed as secondary metadata; pseudo-path spans degrade to position notes. Repeated findings keep the shared collapse, one entry naming its finding count and using the selected locations, and interactive elapsed time stays presentation-only. The wright-result/v1 envelope uses the same selected finding set, and the GitHub Actions renderer is unchanged.

The inspect queries follow the same human-first hierarchy (#446) on the terminal/plain text surface. Bare wright inspect prints the program inventory of file, rule, variable, subroutine, and finding counts, followed by a bounded rule-name preview and the detail commands, so the first screen answers "what is this" and routes deeper questions to the owning query. Each subcommand leads with its subject and summary before its detail:

  • inspect symbols groups entries under their kind and prints each symbol's name beside its primary path:line:col location.
  • inspect refs prints the queried symbol's identity and usage counts in the verdict metadata, then the reference list where each entry carries its location, kind, and rule/action index.
  • inspect cfg prints the queried rule's name, the graph shape (block, edge, loop-header, wait, and call-site counts; entry and exit blocks), then the block/edge listing.
  • inspect callgraph prints the edge shape first, then notable fan-in and fan-out, that is, subroutines with more than one caller and rules calling more than one subroutine, then the edge list.
  • inspect cost prints exact generated-resource totals, the canonical element count against the client element budget with each rule's share ranked by count and located in source (path:line:col), then static findings ordered by severity with consecutive identical findings collapsed into one counted entry that lists every occurrence's location (#722). With --rule, inspect cost instead prints that rule's identity and location, its Costliest statements ranked by recursive count, and the By node name own-cost shares that reconcile to the rule's total (#724).

Text and compact JSON present the same selected items. Detail lists default to at most 20 items, with their total and an expansion hint when truncated; --all lifts the default cap. The analyze report keeps its ranked top-five hotspots, risks and variables and top-three condition trees, with the same explicit expansion metadata. JSON is the structured form for programmatic processing. Verdicts still describe the full set. When a query fails, its verdict and diagnostics render without result metadata, so a default result cannot masquerade as an answer.

This document is the normative contract for the compiler driver and CLI. It defines the shared driver model, the command surface, exit codes, stdout/stderr ownership, and the wright-result/v1 envelope that CI and agents consume.