`dashboard`

The green dashboard. It runs every quality gate in its own subprocess, prints one verdict, and exits non-zero when any gate is red. Run it with python scripts/dashboard.py.

Run every quality gate and report one green or red dashboard.

The dashboard is the single signal that every commit must keep green. It runs each gate in its own subprocess, records the outcome, and prints a table. Its exit status is 0 only when every gate is green, so the same command serves as a local habit, a pre-commit check, and a CI step.

Command-line usage:

python scripts/dashboard.py                        # table on the terminal
python scripts/dashboard.py --markdown             # Markdown, for CI step summaries
python scripts/dashboard.py --json runtime/dashboard.json

The seed gates generate a project and run its dashboard. They run only in a repository that contains the project generator, scripts/new_project.py.

class dashboard.Gate(name: str, command: tuple[str, ...], purpose: str)[source]

Bases: object

A quality gate: a named command that must exit with status 0.

name

Short identifier shown on the dashboard.

Type:: str

command

Argument vector, run from the repository root.

Type:: tuple of str

purpose

One sentence that says what the gate protects.

Type:: str

class dashboard.GateResult(name: str, status: Literal['green', 'red'], returncode: int, seconds: float, tail: str)[source]

Bases: object

The outcome of running one gate.

name

The gate’s name.

Type:: str

status

"green" when the command exited with status 0, and "red" otherwise.

Type:: {“green”, “red”}

returncode

The command’s exit status.

Type:: int

seconds

Wall-clock seconds the command took, rounded to two decimals.

Type:: float

tail

The last lines of combined output, kept so that a red gate can be investigated.

Type:: str

dashboard.default_gates(root: Path, python: str = '/opt/hostedtoolcache/Python/3.12.16/x64/bin/python') → tuple[Gate, ...][source]

Build the gates that apply to a repository.

Parameters:

root (Path) – Repository root. Whether scripts/new_project.py exists there decides whether the seed gates are included.
python (str, optional) – Interpreter for every command. The default is the interpreter that runs the dashboard.

Returns:

tuple of Gate – The lint, format, type, test, validator, and docs gates, followed by the seed gates when the project generator is present.

dashboard.run_gate(gate: Gate, cwd: Path) → GateResult[source]

Run one gate in a subprocess and record its outcome.

Parameters:

gate (Gate) – The gate to run.
cwd (Path) – Directory to run the command in, normally the repository root.

Returns:

GateResult – The status, exit code, duration, and output tail of the run.

dashboard.run_gates(gates: Sequence[Gate], cwd: Path) → list[GateResult][source]

Run every gate in order and collect the results.

Parameters:

gates (sequence of Gate) – The gates to run, in the order they should appear.
cwd (Path) – Directory to run every command in.

Returns:

list of GateResult – One result per gate, in the same order as gates.

dashboard.overall_status(results: Sequence[GateResult]) → Literal['green', 'red'][source]

Summarize a dashboard as one status.

Parameters:: results (sequence of GateResult) – The results to summarize.
Returns:: {“green”, “red”} – "green" only when there is at least one result and every result is green. An empty dashboard is red, because nothing was checked.

dashboard.render_text(results: Sequence[GateResult]) → str[source]

Render the dashboard as a plain-text table.

Parameters:: results (sequence of GateResult) – The results to render.
Returns:: str – A table with one row per gate, an overall verdict, and the output tail of each red gate.

dashboard.render_markdown(results: Sequence[GateResult]) → str[source]

Render the dashboard as a Markdown table, for a CI step summary.

Parameters:: results (sequence of GateResult) – The results to render.
Returns:: str – A heading with the overall verdict, and a table with one row per gate.

dashboard.record(results: Sequence[GateResult]) → dict[str, object][source]

Build the machine-readable record of a dashboard run.

Parameters:: results (sequence of GateResult) – The results to record.
Returns:: dict of str to object – The overall status and one entry per gate, ready for json.dumps.

dashboard.main(argv: Sequence[str] | None = None, *, gates: Sequence[Gate] | None = None, root: Path = PosixPath('/home/runner/work/fresh-fvsbc/fresh-fvsbc')) → int[source]

Run the dashboard from the command line.

Parameters:

argv (sequence of str or None, optional) – Arguments to parse. None reads sys.argv.
gates (sequence of Gate or None, optional) – Gates to run instead of the defaults. Tests use this to avoid running the full suite from inside itself.
root (Path, optional) – Repository root in which the commands run.

Returns:

int – 0 when every gate is green, and 1 otherwise.

dashboard

`dashboard`