fix(engine): surface scanner exceptions as failure rows in canonical results

Both ``_run_sequential`` and ``_run_parallel`` previously caught
exceptions raised from ``scanner.scan()`` and silently dropped the
scanner from the result list. Other scanners that failed via the
``_run_in_container`` path produced an ``execution_failed`` ScanResult
row visible in argus-results.json; scanners with custom ``scan()``
implementations that raise (FileNotFoundError when a binary is missing,
RuntimeError, TimeoutExpired, etc.) disappeared entirely.

Concretely: ``lint-dockerfile`` (HadolintLinter) calls
``subprocess.run(['hadolint', ...])`` directly. When hadolint is not
installed locally and the container backend is unavailable, the
FileNotFoundError propagates up through scan() — the engine logged
the exception and moved on, leaving no trace in canonical results.
The user looking at argus-results.json had no signal that
lint-dockerfile was even attempted, much less why it didn't run.

Per ADR-016: silent failures are the anti-pattern. The fix:

* New ``_failure_result(scanner_name, exc, duration_ms=None)`` helper at
  the top of ``argus/core/engine.py`` builds a ScanResult with the
  same ``execution_failed`` and ``execution_failure_reason`` metadata
  shape ``_run_in_container`` already emits for output-less docker
  runs.
* ``_run_sequential`` (line 304) appends the failure row before the
  fail-fast check, so even with --fail-fast the scanner that broke
  the loop is visible in results.
* ``_run_parallel`` (line 389) does the same when collecting futures.

Tests updated:

* ``test_run_handles_scanner_exception``,
  ``test_local_backend_fails_if_unavailable``,
  ``test_docker_backend_no_image_raises``,
  ``test_timeout_raises_on_slow_scanner``,
  ``test_version_mismatch_raises_by_default``,
  ``test_auto_backend_local_fallback_checks_version``,
  ``test_run_skips_unavailable_scanners`` (renamed),
  ``test_fail_fast_aborts_after_failure``,
  ``test_without_fail_fast_continues_after_failure`` — all updated
  from ``len(results) == 0`` (silent drop) to asserting the
  ``execution_failed`` failure row.
* New ``test_parallel_failure_surfaces_as_failure_row`` —
  regression test for the lint-dockerfile bug specifically: scanner
  raises FileNotFoundError in parallel mode, failure row appears in
  canonical results with the exception type captured.

1517 SDK tests pass.

Author: eFAILution

argus/core/engine.py

@@ -25,6 +25,31 @@
 }
 
 
+def _failure_result(
+    scanner_name: str,
+    exc: BaseException,
+    duration_ms: int | None = None,
+) -> ScanResult:
+    """Build a ScanResult representing a scanner that raised during execution.
+
+    Mirrors the ``execution_failed`` metadata that ``_run_in_container``
+    produces for output-less docker runs, so the canonical results
+    contract is uniform regardless of which path produced the failure.
+    A user reviewing argus-results.json sees the scanner with its
+    error reason; without this, scanners whose ``scan()`` raises (e.g.
+    a missing local binary that subprocess.run can't find) silently
+    disappear from the results — exactly the silent-failure pattern
+    ADR-016 was written to prevent.
+    """
+    metadata: dict = {
+        "execution_failed": True,
+        "execution_failure_reason": f"{type(exc).__name__}: {exc}",
+    }
+    if duration_ms is not None:
+        metadata["duration_ms"] = duration_ms
+    return ScanResult(scanner=scanner_name, metadata=metadata)
+
+
 class ArgusEngine:
     """Orchestrates registered scanners and aggregates their results."""
 
@@ -312,11 +337,18 @@ def _run_sequential(
                     scanner.name, elapsed, result.total_count,
                 )
                 results.append(result)
-            except Exception:
+            except Exception as exc:
                 elapsed = int((time.monotonic() - start) * 1000)
                 logger.exception(
                     "Scanner '%s' failed after %dms", scanner.name, elapsed,
                 )
+                # Append a failure-row ScanResult so the user sees the
+                # scanner in the canonical results — silently dropping
+                # it makes a hard failure look identical to "ran clean
+                # with zero findings". Mirrors the execution_failed
+                # metadata that ``_run_in_container`` produces for
+                # output-less docker runs.
+                results.append(_failure_result(scanner.name, exc, elapsed))
                 if fail_fast:
                     logger.error(
                         "Aborting scan — --fail-fast is set and '%s' failed",
@@ -386,8 +418,12 @@ def _timed_run(scanner, scan_path, config_dict, patterns):
                         result.total_count,
                     )
                     results.append(result)
-                except Exception:
+                except Exception as exc:
                     logger.exception("Scanner '%s' failed", name)
+                    # See _run_sequential for rationale — failure rows
+                    # surface in canonical results instead of silently
+                    # dropping the scanner.
+                    results.append(_failure_result(name, exc))
                     if fail_fast:
                         logger.error(
                             "Aborting scan — --fail-fast and '%s' failed",

argus/tests/test_engine.py

@@ -100,14 +100,19 @@ def test_run_skips_disabled_scanners(self):
         assert len(summary.results) == 1
         assert summary.results[0].scanner == "bandit"
 
-    def test_run_skips_unavailable_scanners(self):
+    def test_run_surfaces_unavailable_scanner_as_failure_row(self):
+        """A scanner the user enabled in config but that isn't installed
+        locally surfaces as a failure row, not a silent skip — the user
+        explicitly asked for it, so they should see why it didn't run.
+        """
         engine = self._make_engine(
             scanners_config={"bandit": {"enabled": True}}
         )
         engine.register_scanner(MockScanner("bandit", available=False))
 
         summary = engine.run()
-        assert len(summary.results) == 0
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
 
     def test_run_skips_unregistered_scanners(self):
         engine = self._make_engine()
@@ -177,7 +182,11 @@ def install_command(self):
 
         engine.register_scanner(FailingScanner())
         summary = engine.run()
-        assert len(summary.results) == 0
+        # Failure row surfaces in canonical results (ADR-016) — silent
+        # drops were the bug behind ``lint-dockerfile`` going missing.
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
+        assert summary.results[0].total_count == 0
 
 
 class TestDockerExecutionBackend:
@@ -207,9 +216,11 @@ def test_local_backend_fails_if_unavailable(self):
         scanner = MockScanner("bandit", available=False)
         engine.register_scanner(scanner)
 
-        # Engine catches exceptions and logs them
+        # Engine surfaces the failure as a row with execution_failed
+        # metadata (ADR-016 — no silent drops).
         summary = engine.run(scanner_names=["bandit"])
-        assert len(summary.results) == 0
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
 
     def test_resolve_image_no_registry(self):
         engine = self._make_engine(registry="")
@@ -238,7 +249,8 @@ def test_docker_backend_no_image_raises(self):
         engine.register_scanner(scanner)
 
         summary = engine.run(scanner_names=["bandit"])
-        assert len(summary.results) == 0
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
 
     def test_auto_backend_prefers_container(self, monkeypatch):
         """auto backend uses containers first when Docker is available."""
@@ -325,8 +337,13 @@ def install_command(self):
         engine.register_scanner(good)
 
         summary = engine.run(fail_fast=True, parallel=False)
-        # Scanner "a" fails, "b" should never run (sequential mode)
-        assert len(summary.results) == 0
+        # Scanner "a" produces a failure row (recorded for visibility)
+        # then the loop breaks before running "b". No silent drop.
+        assert len(summary.results) == 1
+        failed = summary.results[0]
+        assert failed.scanner == "a"
+        assert failed.metadata.get("execution_failed") is True
+        assert "boom" in failed.metadata.get("execution_failure_reason", "")
         assert good.scan_called_with is None
 
     def test_without_fail_fast_continues_after_failure(self):
@@ -348,9 +365,13 @@ def install_command(self):
         engine.register_scanner(good)
 
         summary = engine.run(fail_fast=False)
-        # Scanner "a" fails, "b" still runs
-        assert len(summary.results) == 1
+        # Both scanners present in canonical results: "a" as a
+        # failure row, "b" as a normal success row.
+        assert len(summary.results) == 2
         assert good.scan_called_with is not None
+        by_name = {r.scanner: r for r in summary.results}
+        assert by_name["a"].metadata.get("execution_failed") is True
+        assert by_name["b"].metadata.get("execution_failed") is None
 
 
 class TestParallelExecution:
@@ -371,6 +392,40 @@ def test_parallel_runs_all_scanners(self):
         summary = engine.run(parallel=True)
         assert len(summary.results) == 3
 
+    def test_parallel_failure_surfaces_as_failure_row(self):
+        """Regression for ADR-016: a scanner that raises in parallel mode
+        produces a ScanResult with execution_failed metadata, not a
+        silent drop. This is the bug behind ``lint-dockerfile`` going
+        missing from results when hadolint isn't installed locally —
+        custom scan() implementations that raise FileNotFoundError used
+        to disappear from canonical results entirely.
+        """
+        engine = self._make_engine(2)  # config has scanners s0, s1
+
+        class FailingScanner:
+            name = "s0"
+            def scan(self, path, config=None):
+                raise FileNotFoundError(2, "No such file", "broken-tool")
+            def is_available(self):
+                return True
+            def install_command(self):
+                return None
+
+        good = MockScanner("s1", findings=[
+            Finding(id="1", severity=Severity.LOW, title="f"),
+        ])
+        engine.register_scanner(FailingScanner())
+        engine.register_scanner(good)
+
+        summary = engine.run(parallel=True)
+        assert len(summary.results) == 2
+        by_name = {r.scanner: r for r in summary.results}
+        assert by_name["s0"].metadata.get("execution_failed") is True
+        assert "FileNotFoundError" in by_name["s0"].metadata.get(
+            "execution_failure_reason", "",
+        )
+        assert by_name["s1"].metadata.get("execution_failed") is None
+
     def test_parallel_faster_than_sequential(self):
         """Parallel should be faster when scanners have I/O wait."""
         import time as time_mod
@@ -463,8 +518,9 @@ def install_command(self):
 
         engine.register_scanner(SlowScanner())
         summary = engine.run(timeout=1)
-        # Scanner should time out and produce no results
-        assert len(summary.results) == 0
+        # Timeout surfaces as a failure row, not a silent drop.
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
 
     def test_no_timeout_allows_completion(self):
         engine = self._make_engine()
@@ -1399,9 +1455,11 @@ def test_version_mismatch_raises_by_default(self, monkeypatch):
             lambda name: "1.0.0",
         )
 
-        # Engine catches exceptions — scanner produces no results
+        # Version mismatch surfaces as a failure row instead of a
+        # silent drop.
         summary = engine.run(scanner_names=["bandit"])
-        assert len(summary.results) == 0
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
 
     def test_version_mismatch_allowed_with_flag(self, monkeypatch):
         """With allow_local_versions=True, mismatch logs warning but proceeds."""
@@ -1477,8 +1535,9 @@ def test_auto_backend_local_fallback_checks_version(self, monkeypatch):
         )
 
         summary = engine.run(scanner_names=["bandit"])
-        # Version mismatch should cause failure
-        assert len(summary.results) == 0
+        # Version mismatch surfaces as a failure row.
+        assert len(summary.results) == 1
+        assert summary.results[0].metadata.get("execution_failed") is True
 
     def test_tool_version_recorded_in_metadata(self, monkeypatch):
         """Tool version should be recorded in result metadata."""