feat: add progress display and --non-interactive to wiki sanity

wiki sanity now reuses run_sanity's ProgressDisplay: one bar line
per check on a terminal, labeled progress dots on an interval when
piped or with --non-interactive; --json runs skip the display.
Non-interactive mode prints one dot per interval (Running Sanity /
Running Wiki Sanity) for both runners instead of status blocks.
SPEC 3.1.3, 4.9.5, 4.9.6 updated to match.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-09-28 09:46:32 +02:00
parent 4843ca5a9a
commit 417c1cf665
7 changed files with 283 additions and 46 deletions
+22 -9
View File
@@ -299,6 +299,11 @@ Implementation notes:
files there cannot be fixed. Links pointing into these zones are
still resolved.
- Markdown lint uses the wiki's own `fiona-settings.json`.
- Human-readable runs draw the same live per-check progress as
run_sanity (4.9.6), reusing its `ProgressDisplay`: one bar line
per check on a terminal, `Running Wiki Sanity ....` progress dots
on an interval when piped or with `--non-interactive`. JSON runs
skip the display so their output stays parseable.
- Checks live in `SANITY_CHECKS`, a (name, runner) registry in
`src/wiki/sanity_manager.py`; add new checks (e.g. shellcheck once
4.4 ships) by implementing a runner and appending it. Current
@@ -1031,8 +1036,8 @@ Requirements:
and a `heartbeat(remaining_names)` callable invoked roughly every
0.5s while checks are still running. The check lifecycle (start and
completion with duration) is logged at INFO through the logging
module. run_sanity passes its progress display as these callbacks
(see 4.9.6); wiki sanity passes none and its output is unchanged.
module. run_sanity and wiki sanity (3.1.3) pass their progress
display as these callbacks (see 4.9.6).
- Runner-specific presentation (which reports print and with which
headers) stays with each runner.
@@ -1041,7 +1046,8 @@ Acceptance criteria:
- run_sanity and wiki sanity produce their reports through
SanityRunner; the engine and format code are not duplicated.
- The check reports are byte-identical to the pre-refactor runners;
run_sanity's in-run progress output follows 4.9.6.
run_sanity's and wiki sanity's in-run progress output follows
4.9.6.
---
@@ -1051,7 +1057,8 @@ Acceptance criteria:
>
> Covers: `src/run_sanity.py` (`ProgressDisplay`,
> `format_progress_bar`, `load_progress_settings`, `parse_args`) and
> the `--non-interactive` CLI argument.
> the `--non-interactive` CLI argument of both `run_sanity` and
> `wiki sanity` (3.1.3), which reuses the same display.
Live per-check progress while the sanity checks run, replacing the
`[DONE]`/`[WAITING]` heartbeat.
@@ -1070,22 +1077,28 @@ Requirements:
- The final block stays visible above the reports (nothing is
erased), so the terminal keeps a record of the run's progress.
- `--non-interactive` — also automatic when stdout is not a terminal —
prints the same status lines as fresh plain-text lines without
ANSI codes, every `interval` seconds (default 3) while checks run.
prints the label once (`Running Sanity` for run_sanity,
`Running Wiki Sanity` for wiki sanity), then one progress dot
every `interval` seconds (default 3) while checks run, e.g.
`Running Sanity ....`; the line ends with a newline before the
reports. Runs shorter than the interval print no progress output.
- Settings (`settings_dev.json`, `progress` section): `interval`
(non-interactive print cadence) and `expected-seconds` (bar
scale); each falls back to its default when the section or key is
absent.
- The shared SanityRunner engine (4.9.5) is unchanged; the display
plugs in as the engine's `progress` and `heartbeat` callbacks.
- `wiki sanity` (3.1.3) plugs the same display into its checks: the
bars carry the `SANITY_CHECKS` registry names and scale against the
same settings; `--json` runs skip the display so the JSON output
stays parseable.
Acceptance criteria:
- On a terminal each check gets its own live bar line; on a pipe or
with `--non-interactive` the output contains no ANSI escape codes
and a full status block prints every `interval` seconds.
- A check that finishes between prints reports `100% done (MM:SS)`
in the next block.
and one progress dot appears per `interval` seconds after the
label.
---
+8 -1
View File
@@ -155,6 +155,12 @@ def main():
action="store_true",
help="Output results in JSON format"
)
wiki_sanity_parser.add_argument(
"--non-interactive",
action="store_true",
help="print one progress dot on an interval instead of live "
"progress bars (also automatic when stdout is not a terminal)"
)
args = parser.parse_args()
setup_logging()
@@ -221,7 +227,8 @@ def main():
elif args.wiki_subcommand == "sanity":
sys.exit(sanity_main(
directory=args.directory,
json_output=args.json
json_output=args.json,
non_interactive=args.non_interactive
))
else:
wiki_parser.print_help()
+25 -15
View File
@@ -125,39 +125,47 @@ class ProgressDisplay:
Interactive mode (a terminal without --non-interactive) draws one
bar line per check and redraws the block in place as the engine
polls; non-interactive mode prints the same status lines every
`interval_seconds` so piped or logged output stays readable. Bars
fill against `expected_seconds`; a finished check shows a full bar
with its measured duration.
polls; non-interactive mode prints the label once, then one
progress dot every `interval_seconds` (`Running Sanity ....`) so
piped or logged output stays readable. Bars fill against
`expected_seconds`; a finished check shows a full bar with its
measured duration.
"""
DEFAULT_LABEL = "Running Sanity"
def __init__(self, check_names: Sequence[str], interactive: bool,
stream=None,
interval_seconds: float = DEFAULT_PROGRESS_INTERVAL_SECONDS,
expected_seconds: float = DEFAULT_EXPECTED_SECONDS,
clock: Callable[[], float] = time.perf_counter):
clock: Callable[[], float] = time.perf_counter,
label: str = DEFAULT_LABEL):
"""Initialize the display state for one sanity run.
Args:
check_names: Registry-ordered names of the checks to draw.
interactive: True draws in-place bars (ANSI), False prints
status lines on an interval.
one progress dot per interval after the label.
stream: Output stream; defaults to sys.stdout.
interval_seconds: Non-interactive print cadence.
expected_seconds: Duration the bars treat as 100%.
clock: Zero-arg callable returning the current monotonic
time; injectable for tests.
label: Text printed once before the first progress dot
(non-interactive mode only).
"""
self.check_names = list(check_names)
self.interactive = interactive
self.stream = stream if stream is not None else sys.stdout
self.interval_seconds = interval_seconds
self.expected_seconds = expected_seconds
self.label = label
self._clock = clock
self._start = clock()
self._durations: dict[str, float | None] = {}
self._lines_drawn = 0
self._last_print = self._start
self._dots_printed = False
self._name_width = max((len(name) for name in self.check_names), default=0)
def progress(self, check_name: str, check_result: dict) -> None:
@@ -183,11 +191,11 @@ class ProgressDisplay:
now = self._clock()
if now - self._last_print >= self.interval_seconds:
self._last_print = now
self._print_status(now)
self._print_dot()
def finish(self) -> None:
"""Separate the progress block from the reports that follow."""
if self.interactive:
"""Separate the progress output from the reports that follow."""
if self.interactive or self._dots_printed:
self.stream.write("\n")
self.stream.flush()
@@ -224,10 +232,12 @@ class ProgressDisplay:
self.stream.flush()
self._lines_drawn = len(self.check_names)
def _print_status(self, now: float) -> None:
"""Print the status block as fresh lines (non-interactive)."""
for line in self._status_lines(now):
self.stream.write(f"{line}\n")
def _print_dot(self) -> None:
"""Print one progress dot, prefixed by the label on the first."""
if not self._dots_printed:
self.stream.write(f"{self.label} ")
self._dots_printed = True
self.stream.write(".")
self.stream.flush()
def run_pytests():
@@ -509,8 +519,8 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
parser.add_argument(
"--non-interactive",
action="store_true",
help="print status lines on an interval instead of live progress "
"bars (also automatic when stdout is not a terminal)",
help="print one progress dot on an interval instead of live "
"progress bars (also automatic when stdout is not a terminal)",
)
return parser.parse_args(argv)
+25
View File
@@ -204,6 +204,31 @@ class TestFionaMain:
assert re.search(r"mdlinter:\s+FAIL", captured.out)
assert "Sanity Failed" in captured.out
def test_main_wiki_sanity_non_interactive_flag(self, capsys, minimal_wiki):
"""Test main() wiki sanity accepts --non-interactive and exits 0."""
argv = ['fiona-assistant', 'wiki', 'sanity',
'--non-interactive', str(minimal_wiki)]
with patch('sys.argv', argv), \
pytest.raises(SystemExit) as exc_info:
main()
assert exc_info.value.code == 0
captured = capsys.readouterr()
assert "SANITY PASSED" in captured.out
# Non-interactive output carries no ANSI cursor codes (SPEC 4.9.6)
assert "\x1b[" not in captured.out
def test_main_wiki_sanity_passes_non_interactive(self, minimal_wiki):
"""Test main() forwards the --non-interactive flag to sanity_main."""
argv = ['fiona-assistant', 'wiki', 'sanity',
'--non-interactive', str(minimal_wiki)]
with patch('fiona.__main__.sanity_main', return_value=0) as mock_main, \
patch('sys.argv', argv), \
pytest.raises(SystemExit):
main()
assert mock_main.call_args.kwargs["non_interactive"] is True
def test_main_wiki_without_subcommand_shows_help(self, capsys):
"""Test main() with wiki command and no subcommand shows help."""
with patch('sys.argv', ['fiona-assistant', 'wiki']), \
+37 -15
View File
@@ -1147,7 +1147,7 @@ class TestLoadProgressSettings:
class TestProgressDisplayNonInteractive:
"""Tests for the interval status prints (non-interactive mode)."""
"""Tests for the interval progress dots (non-interactive mode)."""
def test_no_print_before_interval_elapses(self):
stream = io.StringIO()
@@ -1162,39 +1162,40 @@ class TestProgressDisplayNonInteractive:
assert stream.getvalue() == ""
def test_prints_status_block_every_interval(self):
def test_prints_label_then_one_dot_per_interval(self):
stream = io.StringIO()
clock = _fake_clock([0.0, 0.5, 3.2, 4.0])
clock = _fake_clock([0.0, 3.2, 6.5, 7.0])
display = run_sanity.ProgressDisplay(
["lint1", "lint2"], interactive=False, stream=stream,
interval_seconds=3.0, expected_seconds=30.0, clock=clock,
)
display.heartbeat(["lint1", "lint2"])
assert stream.getvalue() == ""
assert stream.getvalue() == "Running Sanity ."
display.heartbeat(["lint1", "lint2"])
first_output = stream.getvalue()
assert first_output != ""
assert stream.getvalue() == "Running Sanity .."
# Below the interval again: no extra dot
display.heartbeat(["lint1", "lint2"])
assert stream.getvalue() == first_output
assert stream.getvalue() == "Running Sanity .."
def test_status_line_format(self):
def test_custom_label_prefixes_the_dots(self):
stream = io.StringIO()
clock = _fake_clock([0.0, 6.0])
clock = _fake_clock([0.0, 3.2])
display = run_sanity.ProgressDisplay(
["lint1"], interactive=False, stream=stream,
interval_seconds=3.0, expected_seconds=30.0, clock=clock,
label="Running Wiki Sanity",
)
display.heartbeat(["lint1"])
assert stream.getvalue() == "lint1 [###------------] 20% 6.0s\n"
assert stream.getvalue() == "Running Wiki Sanity ."
def test_done_check_shows_full_bar_and_duration(self):
def test_finished_check_prints_nothing(self):
stream = io.StringIO()
clock = _fake_clock([0.0, 3.5])
clock = _fake_clock([0.0, 3.2])
display = run_sanity.ProgressDisplay(
["lint1", "lint2"], interactive=False, stream=stream,
interval_seconds=3.0, expected_seconds=30.0, clock=clock,
@@ -1203,9 +1204,30 @@ class TestProgressDisplayNonInteractive:
display.progress("lint1", {"result": 0, "duration_seconds": 7.5})
display.heartbeat(["lint2"])
out = stream.getvalue()
assert "lint1 [###############] 100% done (00:07)\n" in out
assert "lint2" in out
# The dot comes from the interval tick, not from the finished
# check; no status lines or ANSI codes appear
assert stream.getvalue() == "Running Sanity ."
def test_finish_prints_newline_only_after_dots(self):
stream = io.StringIO()
clock = _fake_clock([0.0])
silent_display = run_sanity.ProgressDisplay(
["lint1"], interactive=False, stream=stream,
interval_seconds=3.0, expected_seconds=30.0, clock=clock,
)
silent_display.finish()
assert stream.getvalue() == ""
ticking_clock = _fake_clock([0.0, 3.2])
ticking_display = run_sanity.ProgressDisplay(
["lint1"], interactive=False, stream=stream,
interval_seconds=3.0, expected_seconds=30.0, clock=ticking_clock,
)
ticking_display.heartbeat(["lint1"])
ticking_display.finish()
assert stream.getvalue() == "Running Sanity .\n"
class TestProgressDisplayInteractive:
+110
View File
@@ -12,6 +12,8 @@ import re
import pytest
import run_sanity
from wiki import sanity_manager
from wiki.sanity_manager import (
SANITY_CHECKS,
format_sanity_report,
@@ -115,6 +117,26 @@ class TestRunWikiChecks:
with pytest.raises(NotADirectoryError):
run_wiki_checks(str(empty))
def test_progress_callback_reports_every_check(self, minimal_wiki):
completed = []
run_wiki_checks(
str(minimal_wiki),
progress=lambda name, _result: completed.append(name),
)
assert set(completed) == {name for name, _check in SANITY_CHECKS}
def test_heartbeat_callback_forwarded(self, minimal_wiki):
heartbeats = []
run_wiki_checks(
str(minimal_wiki), heartbeat=lambda remaining: heartbeats.append(list(remaining))
)
# The engine polls at least once while checks run; every poll
# carries the names of the still-running checks
for remaining in heartbeats:
assert set(remaining) <= {name for name, _check in SANITY_CHECKS}
# =============================================================================
# Report Format Tests (run_sanity structure, SPEC 4.9.3/4.9.4)
@@ -263,3 +285,91 @@ class TestSanityMain:
assert result == 1
assert "Error" in capsys.readouterr().err
def test_forwards_non_interactive_to_wiki_sanity(self, minimal_wiki, monkeypatch):
received = {}
def fake_wiki_sanity(directory=".", json_output=False, non_interactive=False):
received["non_interactive"] = non_interactive
return 0
monkeypatch.setattr(sanity_manager, "wiki_sanity", fake_wiki_sanity)
result = sanity_main(directory=str(minimal_wiki), non_interactive=True)
assert result == 0
assert received["non_interactive"] is True
# =============================================================================
# Progress Display Tests (SPEC 4.9.6)
# =============================================================================
class TestWikiSanityProgress:
"""Tests for the in-run progress display wiring (SPEC 4.9.6)."""
@pytest.fixture
def fake_display_class(self, monkeypatch):
"""Replace run_sanity's ProgressDisplay with a recording stub."""
instances = []
class _StubDisplay:
def __init__(self, check_names, interactive, stream=None,
interval_seconds=3.0, expected_seconds=30.0,
clock=None, label="Running Sanity"):
self.check_names = list(check_names)
self.interactive = interactive
self.label = label
self.progress_calls = []
self.heartbeat_calls = []
self.finished = False
instances.append(self)
def progress(self, check_name, check_result):
self.progress_calls.append(check_name)
def heartbeat(self, remaining):
self.heartbeat_calls.append(list(remaining))
def finish(self):
self.finished = True
monkeypatch.setattr(run_sanity, "ProgressDisplay", _StubDisplay)
return instances
def test_display_covers_registered_checks(self, minimal_wiki, fake_display_class):
exit_code = wiki_sanity(str(minimal_wiki))
assert exit_code == 0
assert len(fake_display_class) == 1
display = fake_display_class[0]
assert display.check_names == [name for name, _check in SANITY_CHECKS]
assert set(display.progress_calls) == {name for name, _check in SANITY_CHECKS}
assert display.finished is True
def test_non_interactive_flag_drives_display_mode(
self, minimal_wiki, fake_display_class, monkeypatch
):
decisions = []
monkeypatch.setattr(
run_sanity, "should_use_interactive",
lambda flag, stream: decisions.append(flag) or flag,
)
wiki_sanity(str(minimal_wiki), non_interactive=True)
assert decisions == [True]
assert fake_display_class[0].interactive is True
def test_display_label_names_the_wiki_run(self, minimal_wiki, fake_display_class):
wiki_sanity(str(minimal_wiki))
assert fake_display_class[0].label == "Running Wiki Sanity"
def test_json_output_skips_display(self, minimal_wiki, fake_display_class, capsys):
exit_code = wiki_sanity(str(minimal_wiki), json_output=True)
assert exit_code == 0
assert fake_display_class == []
# The JSON stream stays pure: no progress noise around it
assert json.loads(capsys.readouterr().out)["passed"] is True
+56 -6
View File
@@ -23,6 +23,7 @@ import time
from collections.abc import Callable
from pathlib import Path
import run_sanity
import sanity_runner
from customlinter.base import LintViolation
from customlinter.fmlint import FrontmatterLinter
@@ -155,7 +156,11 @@ SANITY_CHECKS: tuple[tuple[str, Callable[[Path], dict]], ...] = (
# Aggregated Sanity
# =============================================================================
def run_wiki_checks(directory: str | Path) -> dict:
def run_wiki_checks(
directory: str | Path,
progress: Callable[[str, dict], None] | None = None,
heartbeat: Callable[[list[str]], None] | None = None,
) -> dict:
"""Run all sanity checks over an llm-wiki directory.
Checks run concurrently (one thread each, mirroring run_sanity);
@@ -165,6 +170,11 @@ def run_wiki_checks(directory: str | Path) -> dict:
Args:
directory: The wiki directory to check.
progress: Optional engine completion callback, invoked as
`progress(name, check_result)` per finished check.
heartbeat: Optional engine polling callback, invoked as
`heartbeat(remaining_names)` roughly every 0.5s while
checks are still running.
Returns:
dict: Aggregated results: `target`, `checks` (one entry per
@@ -195,7 +205,7 @@ def run_wiki_checks(directory: str | Path) -> dict:
]
)
total_start = time.perf_counter()
checks = runner.run_all()
checks = runner.run_all(progress=progress, heartbeat=heartbeat)
total_duration_seconds = time.perf_counter() - total_start
total_violations = sum(check["violation_count"] for check in checks.values())
@@ -259,13 +269,25 @@ def format_sanity_report(results: dict) -> str:
# CLI Entry Points
# =============================================================================
def wiki_sanity(directory: str | Path = ".", json_output: bool = False) -> int:
def wiki_sanity(
directory: str | Path = ".",
json_output: bool = False,
non_interactive: bool = False,
) -> int:
"""Run all sanity checks and print the aggregated report.
Human-readable runs draw the same live per-check progress as
run_sanity (SPEC 4.9.6) through the shared ProgressDisplay: one
bar line per check on a terminal, `Running Wiki Sanity ....`
progress dots on an interval when piped or when `non_interactive`
is set. JSON runs skip the display so their output stays parseable.
Args:
directory: The wiki directory to check. Defaults to the current
directory.
json_output: If True, print the results as JSON.
non_interactive: If True, print status lines on an interval
instead of live progress bars.
Returns:
int: 0 when the wiki is clean, 1 on any violation.
@@ -274,7 +296,24 @@ def wiki_sanity(directory: str | Path = ".", json_output: bool = False) -> int:
FileNotFoundError: If the wiki directory does not exist.
NotADirectoryError: If the directory is not an llm-wiki directory.
"""
results = run_wiki_checks(directory)
display = None
if not json_output:
display = run_sanity.ProgressDisplay(
[name for name, _check in SANITY_CHECKS],
interactive=run_sanity.should_use_interactive(
non_interactive, sys.stdout
),
label="Running Wiki Sanity",
**run_sanity.load_progress_settings(),
)
results = run_wiki_checks(
directory,
progress=display.progress if display else None,
heartbeat=display.heartbeat if display else None,
)
if display:
display.finish()
if json_output:
print(json.dumps({
@@ -302,18 +341,29 @@ def wiki_sanity(directory: str | Path = ".", json_output: bool = False) -> int:
return 0 if results["passed"] else 1
def sanity_main(directory: str = ".", json_output: bool = False) -> int:
def sanity_main(
directory: str = ".",
json_output: bool = False,
non_interactive: bool = False,
) -> int:
"""Main function for the 'wiki sanity' CLI command.
Args:
directory: Wiki directory to check (default: current directory).
json_output: If True, output results in JSON format.
non_interactive: If True, print progress status lines on an
interval instead of live progress bars (also automatic
when stdout is not a terminal).
Returns:
int: Exit code (0 clean, 1 any violation or error).
"""
try:
return wiki_sanity(directory, json_output=json_output)
return wiki_sanity(
directory,
json_output=json_output,
non_interactive=non_interactive,
)
except (FileNotFoundError, NotADirectoryError) as error:
print(f"Error: {error}", file=sys.stderr)
return 1