feat(view): config-aware remediation when argus-results.json is missing

When ``argus view`` couldn't find ``argus-results.json`` it just
reported "file not found." The most common root cause is that the
project's ``argus.yml`` doesn't list ``json`` in ``reporting.formats``,
so the previous ``argus scan`` wrote terminal/markdown/SARIF but
never the JSON file the viewers consume. Users had to guess.

The error now identifies that root cause when it's the cause, and
gives both a config fix and a CLI fix in the same output, so users
don't need a second round-trip to figure out what to do.

What changed
- New ``argus.viewers.diagnose`` module (UI-free) with one public
  entry point ``diagnose_missing_results(path)`` returning a
  multi-line, remediation-rich error string. Walks up from cwd
  looking for argus.yml/yaml variants; if found and
  ``reporting.formats`` omits ``json``, emits a *targeted* hint
  ("Detected argus.yml at <path>, but reporting.formats is
  ['terminal', 'sarif'] — 'json' isn't included…"). Otherwise emits
  a *generic* hint with the same two fix paths.
- ``argus/viewers/terminal/loader.py``: ``locate_results`` now
  raises ``FileNotFoundError`` with the diagnoser's output. Both
  viewers surface this verbatim, so the terminal interface and the
  browser interface get identical guidance.
- ``argus/viewers/browser/app.py``: ``_resolve_scan`` "no results
  inside this dir" branch defers to the same diagnoser instead of
  its previous one-line error.
- ``argus/cli.py``: new ``--check`` flag on ``argus view``. When
  set, runs the resolver, prints ``OK: <path> is readable.`` on
  success or the diagnoser remediation on failure, and exits
  without launching the viewer. Useful in CI and pre-flight checks.

What deliberately didn't change
- Successful view flows: untouched. Loader still returns the
  resolved path; the diagnoser only fires on the FileNotFoundError
  branch.
- Auto-fallback to latest results: the loader already resolves the
  ``latest`` symlink convention; no change needed.

Defensive paths covered
- argus.yml that doesn't parse → falls back to generic hint (no
  traceback, no exception leakage from the error path).
- argus.yml without a ``reporting`` key → generic hint.
- ``reporting.formats`` not a list → generic hint.
- Empty / "." path → retry hint shows ``argus view <results-dir>``
  placeholder rather than a useless ``argus view .``.

Tests (+22)
- ``argus/tests/viewers/test_diagnose.py`` (15 cases): targeted /
  generic / config-with-json branches; unparseable YAML; alternate
  config filenames (.argus.yml, .argus.yaml, argus.yaml); walk-up
  behavior; retry-arg parent extraction; placeholder fallback.
- ``argus/tests/viewers/terminal/test_loader.py`` (2 cases):
  regression that ``locate_results`` routes through the diagnoser
  in both branches (config-omits-json AND no-config).
- ``argus/tests/test_cli.py`` (5 cases): ``--check`` flag default
  is False; flag parses to True; success exit path; failure exit
  path emits the diagnoser to stderr and returns EXIT_ERROR;
  ``view --help`` includes the new flag.

Validation
- Full SDK suite: 1420 passed (+22 from this change), 8 skipped.
- Manual smoke test: ``argus view --check`` in cwd without results
  prints the full remediation; ``argus view --check /tmp/has-json``
  prints ``OK: …``.

Author: eFAILution

argus/cli.py

@@ -230,6 +230,13 @@ def _build_view_parser(subparsers: argparse._SubParsersAction) -> None:
              "stdout is a TTY; CI and other non-interactive contexts already "
              "skip auto-open without this flag.",
     )
+    view_parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Validate that the resolved scan directory contains "
+             "argus-results.json and print actionable remediation if not. "
+             "Doesn't launch the viewer — useful in CI and pre-flight checks.",
+    )
 
 
 def _resolve_view_args(args: argparse.Namespace) -> tuple[str, str | None] | None:
@@ -290,6 +297,15 @@ def cmd_view(args: argparse.Namespace) -> int:
     if resolved is None:
         return EXIT_ERROR
     interface, path = resolved
+
+    # --check short-circuits before launching the viewer: validate that
+    # argus-results.json is reachable from the supplied path and print
+    # remediation guidance if not. Useful in CI and as a pre-flight
+    # check before a maintainer hands off "open this scan in argus
+    # view" to a less-technical stakeholder.
+    if getattr(args, "check", False):
+        return _check_view_artifact(path)
+
     return _launch_view(
         interface,
         path=path,
@@ -298,6 +314,25 @@ def cmd_view(args: argparse.Namespace) -> int:
     )
 
 
+def _check_view_artifact(path: str | None) -> int:
+    """Resolve ``path`` to an argus-results.json without launching the viewer.
+
+    Reuses the terminal loader's resolver so the success / failure
+    message matches what a real ``argus view`` would surface. On
+    success, prints the resolved path; on failure, prints the
+    diagnoser's remediation output (config-aware hint identifying the
+    likely root cause) to stderr.
+    """
+    from argus.viewers.terminal.loader import locate_results
+    try:
+        resolved = locate_results(path)
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_ERROR
+    print(f"OK: {resolved} is readable.")
+    return EXIT_SUCCESS
+
+
 def _should_open_browser(args: argparse.Namespace) -> bool:
     """Default to auto-opening the browser when stdout is a TTY.
 

argus/tests/test_cli.py

@@ -849,6 +849,41 @@ def test_view_default_args(self):
         assert args.interface_or_path is None
         assert args.interface_flag is None
         assert args.path_arg is None
+        assert args.check is False
+
+    def test_view_check_flag_parses(self):
+        parser = build_parser()
+        args = parser.parse_args(["view", "--check"])
+        assert args.check is True
+
+    def test_view_check_succeeds_when_results_present(self, tmp_path, capsys):
+        """--check resolves the path, finds argus-results.json, prints OK,
+        and exits 0 without launching the viewer."""
+        from argus.cli import _check_view_artifact, EXIT_SUCCESS
+        (tmp_path / "argus-results.json").write_text("{}")
+
+        rc = _check_view_artifact(str(tmp_path))
+        assert rc == EXIT_SUCCESS
+        out = capsys.readouterr().out
+        assert "OK:" in out
+        assert "argus-results.json" in out
+
+    def test_view_check_emits_diagnoser_when_results_missing(self, tmp_path, capsys, monkeypatch):
+        """--check fails clean with the diagnoser's remediation message —
+        no traceback, no launching viewer, EXIT_ERROR for CI gating."""
+        from argus.cli import _check_view_artifact, EXIT_ERROR
+        # No argus-results.json in tmp_path; no argus.yml either, so we
+        # exercise the generic-hint branch.
+        monkeypatch.chdir(tmp_path)
+
+        rc = _check_view_artifact(str(tmp_path))
+        assert rc == EXIT_ERROR
+        err = capsys.readouterr().err
+        # Original missing-file diagnostic is preserved...
+        assert "argus-results.json not found" in err
+        # ...and accompanied by both fix paths.
+        assert "argus scan --format json" in err
+        assert "reporting.formats" in err
 
     def test_view_positional_terminal(self):
         parser = build_parser()

argus/tests/viewers/terminal/test_loader.py

@@ -109,3 +109,35 @@ def test_reannotates_missing_scanner_from_enclosing_result(self):
         summary = ScanSummary(results=[ScanResult(scanner="osv", findings=[f])])
         out = flatten_findings(summary)
         assert out[0].scanner == "osv"
+
+
+class TestMissingResultsRoutesThroughDiagnoser:
+    """Regression: locate_results' FileNotFoundError must include the
+    config-aware remediation hint, not just the bare "file not found"
+    message. Both viewers surface this exception verbatim."""
+
+    def test_error_includes_diagnoser_remediation(self, tmp_path, monkeypatch):
+        # No argus.yml anywhere → generic-hint branch of the diagnoser.
+        monkeypatch.chdir(tmp_path)
+        with pytest.raises(FileNotFoundError) as excinfo:
+            locate_results(str(tmp_path))
+        msg = str(excinfo.value)
+        # File is identified.
+        assert RESULTS_FILENAME in msg
+        # Both fix paths are surfaced.
+        assert "argus scan --format json" in msg
+        assert "reporting.formats" in msg
+
+    def test_error_calls_out_config_root_cause_when_json_omitted(self, tmp_path, monkeypatch):
+        """Targeted hint when argus.yml is present but missing 'json'."""
+        (tmp_path / "argus.yml").write_text(
+            "reporting:\n  formats:\n    - terminal\n    - sarif\n"
+        )
+        monkeypatch.chdir(tmp_path)
+        with pytest.raises(FileNotFoundError) as excinfo:
+            locate_results(str(tmp_path))
+        msg = str(excinfo.value)
+        # Targeted-branch markers.
+        assert "Detected" in msg
+        assert "argus.yml" in msg
+        assert "'terminal'" in msg and "'sarif'" in msg

argus/tests/viewers/test_diagnose.py

@@ -0,0 +1,189 @@
+"""Tests for argus.viewers.diagnose — missing-results-JSON remediation hints.
+
+Three branches matter:
+- argus.yml exists and `reporting.formats` omits `json` → targeted hint
+  identifying the config root cause.
+- argus.yml exists and lists `json` → fall back to the generic hint
+  (config isn't the cause).
+- no argus.yml found anywhere up the tree → generic hint.
+
+Plus defensive paths: malformed YAML, missing reporting key, etc., all
+fall back to the generic hint without raising.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from argus.viewers.diagnose import (
+    _find_nearby_argus_config,
+    _read_reporting_formats,
+    diagnose_missing_results,
+)
+
+
+# ───────────────────────────────────────────────
+# diagnose_missing_results — public surface
+# ───────────────────────────────────────────────
+
+
+class TestDiagnoseMissingResults:
+    def test_targeted_hint_when_config_omits_json(self, tmp_path, monkeypatch):
+        """argus.yml present, json NOT in reporting.formats → message names
+        the file, the actual formats value, and offers a one-shot CLI fix
+        plus the config-edit fix."""
+        config = tmp_path / "argus.yml"
+        config.write_text(
+            "reporting:\n  formats:\n    - terminal\n    - sarif\n"
+        )
+        monkeypatch.chdir(tmp_path)
+
+        msg = diagnose_missing_results(tmp_path / "argus-results.json")
+
+        # Required: identifies the file.
+        assert "argus-results.json" in msg
+        # Required: message names config root cause.
+        assert "argus.yml" in msg
+        assert "reporting.formats" in msg
+        assert "'terminal'" in msg and "'sarif'" in msg
+        # Required: at least one config fix and one CLI fix.
+        assert "Add 'json' to reporting.formats" in msg
+        assert "argus scan --format json" in msg
+        # Required: retry instruction echoes the searched path.
+        assert "argus view" in msg
+
+    def test_generic_hint_when_no_argus_yml(self, tmp_path, monkeypatch):
+        """No argus.yml anywhere up the tree → generic hint, no false claim
+        about config being the cause."""
+        # Use an isolated tmp dir as cwd; walk-up shouldn't find any
+        # config because tmp dirs are well outside the repo root.
+        sub = tmp_path / "isolated"
+        sub.mkdir()
+        monkeypatch.chdir(sub)
+
+        msg = diagnose_missing_results(sub / "argus-results.json")
+
+        # Still identifies the file + still gives both fix paths.
+        assert "argus-results.json" in msg
+        assert "Add 'json' to reporting.formats in argus.yml" in msg
+        assert "argus scan --format json" in msg
+        # Doesn't make a confident claim about a config we never found.
+        assert "Detected" not in msg
+
+    def test_generic_hint_when_config_includes_json(self, tmp_path, monkeypatch):
+        """Config has json — bug is somewhere else (wrong path, scan never
+        ran, output dir mismatch). Don't blame the config."""
+        config = tmp_path / "argus.yml"
+        config.write_text(
+            "reporting:\n  formats:\n    - terminal\n    - json\n"
+        )
+        monkeypatch.chdir(tmp_path)
+
+        msg = diagnose_missing_results(tmp_path / "argus-results.json")
+
+        # Generic hint path — not the targeted one.
+        assert "Detected" not in msg
+        # Both fixes still listed (user might still need to run the scan).
+        assert "argus scan --format json" in msg
+
+    def test_unparseable_argus_yml_falls_back_to_generic(self, tmp_path, monkeypatch):
+        """Broken YAML must NOT mask the original missing-file diagnostic
+        with a parse-error traceback. Falls back to the generic hint."""
+        config = tmp_path / "argus.yml"
+        config.write_text("reporting:\n  formats: [terminal,, : :")
+        monkeypatch.chdir(tmp_path)
+
+        msg = diagnose_missing_results(tmp_path / "argus-results.json")
+
+        # No traceback / exception leakage.
+        assert "Traceback" not in msg
+        assert "yaml" not in msg.lower()
+        # Falls back to generic path.
+        assert "Detected" not in msg
+        assert "argus-results.json" in msg
+
+    def test_argus_yml_without_reporting_key_falls_back(self, tmp_path, monkeypatch):
+        """Config exists but doesn't define reporting.formats → can't make
+        a confident 'json missing from formats' claim, generic hint fires."""
+        config = tmp_path / "argus.yml"
+        config.write_text("scanners:\n  bandit:\n    enabled: true\n")
+        monkeypatch.chdir(tmp_path)
+
+        msg = diagnose_missing_results(tmp_path / "argus-results.json")
+        assert "Detected" not in msg
+
+    def test_retry_arg_uses_parent_for_results_filename(self, tmp_path, monkeypatch):
+        """When the searched path ends in argus-results.json, the retry
+        hint should point at its parent dir (what argus view actually
+        accepts), not the JSON file itself."""
+        config = tmp_path / "argus.yml"
+        config.write_text("reporting:\n  formats: [terminal]\n")
+        monkeypatch.chdir(tmp_path)
+
+        run_dir = tmp_path / "argus-results" / "2026-05-05T10-00-00Z"
+        msg = diagnose_missing_results(run_dir / "argus-results.json")
+
+        assert f"argus view {run_dir}" in msg
+
+    def test_retry_arg_falls_back_to_placeholder_for_empty_path(self, tmp_path, monkeypatch):
+        """A relative '.' or empty path renders as a literal placeholder
+        rather than a useless 'argus view .' line."""
+        monkeypatch.chdir(tmp_path)
+        msg = diagnose_missing_results(Path("."))
+        assert "argus view <results-dir>" in msg
+
+
+# ───────────────────────────────────────────────
+# Helpers exercised separately for confidence at boundaries
+# ───────────────────────────────────────────────
+
+
+class TestFindNearbyArgusConfig:
+    def test_finds_in_starting_dir(self, tmp_path):
+        config = tmp_path / "argus.yml"
+        config.write_text("# empty\n")
+        assert _find_nearby_argus_config(tmp_path) == config
+
+    def test_walks_up_to_find_config(self, tmp_path):
+        nested = tmp_path / "a" / "b" / "c"
+        nested.mkdir(parents=True)
+        config = tmp_path / "argus.yml"
+        config.write_text("# empty\n")
+        assert _find_nearby_argus_config(nested) == config
+
+    def test_returns_none_when_no_config_in_tree(self, tmp_path):
+        # tmp_path's tree is well-isolated from any repo with argus.yml.
+        assert _find_nearby_argus_config(tmp_path) is None
+
+    def test_recognises_alternate_config_names(self, tmp_path):
+        # argus.yaml and the dotted variants are all valid filenames.
+        for name in ("argus.yaml", ".argus.yml", ".argus.yaml"):
+            sub = tmp_path / name.replace(".", "_")
+            sub.mkdir()
+            config = sub / name
+            config.write_text("# empty\n")
+            assert _find_nearby_argus_config(sub) == config
+
+
+class TestReadReportingFormats:
+    def test_reads_formats_list(self, tmp_path):
+        config = tmp_path / "argus.yml"
+        config.write_text(
+            "reporting:\n  formats:\n    - terminal\n    - json\n"
+        )
+        assert _read_reporting_formats(config) == ["terminal", "json"]
+
+    def test_returns_none_for_missing_reporting_key(self, tmp_path):
+        config = tmp_path / "argus.yml"
+        config.write_text("scanners:\n  bandit:\n    enabled: true\n")
+        assert _read_reporting_formats(config) is None
+
+    def test_returns_none_for_unparseable_yaml(self, tmp_path):
+        config = tmp_path / "argus.yml"
+        config.write_text("reporting: [{")
+        assert _read_reporting_formats(config) is None
+
+    def test_returns_none_when_formats_isnt_a_list(self, tmp_path):
+        config = tmp_path / "argus.yml"
+        config.write_text("reporting:\n  formats: terminal\n")
+        assert _read_reporting_formats(config) is None

argus/viewers/browser/app.py

@@ -145,10 +145,13 @@ def _resolve_scan(
                 f"Use the picker to choose a specific run."
             )
 
-        return None, (
-            f"No {RESULTS_FILENAME} inside {target}. "
-            "Pick a results directory or pass a specific JSON path via ?scan=..."
-        )
+        # No results anywhere under the target. Defer to the shared
+        # diagnoser so the message identifies the likely root cause —
+        # most often the user's argus.yml lists 'reporting.formats'
+        # without 'json', so the previous scan never wrote the file
+        # the viewers consume.
+        from argus.viewers.diagnose import diagnose_missing_results
+        return None, diagnose_missing_results(direct)
 
     return None, f"Unsupported path kind: {target}"