diff --git a/SPEC.md b/SPEC.md index c88b978..7ad37bf 100644 --- a/SPEC.md +++ b/SPEC.md @@ -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. --- diff --git a/src/fiona/__main__.py b/src/fiona/__main__.py index 1089763..2f7aabc 100644 --- a/src/fiona/__main__.py +++ b/src/fiona/__main__.py @@ -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() diff --git a/src/run_sanity.py b/src/run_sanity.py index fd4cb07..9268786 100644 --- a/src/run_sanity.py +++ b/src/run_sanity.py @@ -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) diff --git a/src/tests/test_fiona_main.py b/src/tests/test_fiona_main.py index c14bc15..7afaf01 100644 --- a/src/tests/test_fiona_main.py +++ b/src/tests/test_fiona_main.py @@ -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']), \ diff --git a/src/tests/test_run_sanity.py b/src/tests/test_run_sanity.py index 72c6342..40e763a 100644 --- a/src/tests/test_run_sanity.py +++ b/src/tests/test_run_sanity.py @@ -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: diff --git a/src/tests/test_sanity_manager.py b/src/tests/test_sanity_manager.py index ed5e38e..0dee4f2 100644 --- a/src/tests/test_sanity_manager.py +++ b/src/tests/test_sanity_manager.py @@ -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 diff --git a/src/wiki/sanity_manager.py b/src/wiki/sanity_manager.py index 7e59902..e9758fa 100644 --- a/src/wiki/sanity_manager.py +++ b/src/wiki/sanity_manager.py @@ -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