fix: Report the CLI's own reason when a parse yields no verdict

`astro dev parse` states why it refused — a project configured for standalone
dev mode, a venv without pytest — but parse_check folded every non-completing
run into rc 2 and verify.sh reported the catch-all "produced no recognizable
result". Diagnosing that required digging the raw log out of a CI run.

Capture the CLI's message as "cli_error" and prefer it in the fallback note.
The rc contract is unchanged: these are all still "no verdict, degrade", and
the image-build failure keeps rc 4 because BUILD_MARKER is matched first even
though it wears the same wrapper. A timeout keeps its own wording, since a kill
leaves no explanation behind.

Author: kaxil

scripts/parse_check.py

@@ -18,8 +18,9 @@
      the repo's committed .astro/test_dag_integrity_default.py (generated by
      an older astro CLI) calls DagBag with an argument the target Airflow
      removed, so the harness itself is incompatible with the target.
-  2  output not recognized as an `astro dev parse` run (infra; caller treats
-     like an env failure, never like a code verdict)
+  2  no verdict: the run never completed, or the CLI refused to start it. When
+     the CLI said why, "cli_error" carries its reason verbatim so the caller can
+     show it instead of a catch-all (infra; never a code verdict)
 """
 
 from __future__ import annotations
@@ -47,6 +48,14 @@
 _EXC_HEAD = re.compile(r"^E\s+Exception: (?P<path>\S+) failed to import with message")
 _EXC_CLASS = re.compile(r"^([A-Za-z_][A-Za-z0-9_.]*(?:Error|Exception|Warning))\b")
 _CLEAN = "No errors detected in your DAGs"
+# The CLI's own reason for not producing a result, e.g. a project configured for
+# standalone dev mode ("no virtual environment found — run 'astro dev start'
+# first") or a venv without pytest. Kept out of the rc contract: these are all
+# "no verdict, degrade" (rc 2), and the value only enriches the message. The
+# image-build failure wears the same wrapper, which is why BUILD_MARKER is
+# matched first — a build failure is a real verdict (rc 4), not a missing one.
+_CLI_ERROR = re.compile(
+    r"^Error: something went wrong while parsing your DAGs: (?P<cause>.+)$", re.MULTILINE)
 
 
 def parse_output(text: str) -> tuple[int, dict]:
@@ -103,7 +112,11 @@ def parse_output(text: str) -> tuple[int, dict]:
     # items" alone is what a timeout kill leaves behind.
     completed = _CLEAN in text or _SUMMARY.search(text) is not None
     if not completed:
-        return 2, {"checked": 0, "failures": []}
+        result: dict = {"checked": 0, "failures": []}
+        m = _CLI_ERROR.search(text)
+        if m:
+            result["cli_error"] = m.group("cause").strip()
+        return 2, result
     return (3 if failures else 0), {"checked": checked, "failures": sorted(
         failures.values(), key=lambda f: f["path"])}
 

scripts/verify.sh

@@ -238,7 +238,18 @@ verify_parse_level() {
     return 1
   elif [[ "$target_rc" -eq 2 ]]; then
     local reason="produced no recognizable result"
-    [[ "$target_run_rc" -eq 124 ]] && reason="timed out before completing"
+    local cli_error
+    if [[ "$target_run_rc" -eq 124 ]]; then
+      # A timeout kill leaves no explanation of its own, so keep ours.
+      reason="timed out before completing"
+    else
+      # The CLI usually states exactly why it refused (a project configured for
+      # standalone dev mode, a venv without pytest, …). Its words beat the
+      # catch-all: "produced no recognizable result" is what made a field case
+      # take a full log dig to explain.
+      cli_error=$(jq -r '.cli_error // empty' "$WORKDIR/import-failures.json" 2>/dev/null || true)
+      [[ -n "$cli_error" ]] && reason="failed: ${cli_error}"
+    fi
     fallback_note="ℹ️ Image-level verification could not run (\`astro dev parse\` ${reason}). Results below come from the import-level fallback."
     echo "::warning::verify-level parse: astro dev parse ${reason}; falling back to import-level verification."
     return 1

tests/test_parse_check.py

@@ -114,6 +114,57 @@ def test_collection_error_detected_with_cause(tmp_path):
 def test_unrecognized_output_is_infra(tmp_path):
     rc, result, *_ = _run(tmp_path, "docker daemon not running\n")
     assert rc == 2
+    # Nothing to quote: the caller falls back to its own catch-all wording.
+    assert "cli_error" not in result
+
+
+STANDALONE_NO_VENV_RUN = """\
+Checking your DAGs for errors…
+Error: something went wrong while parsing your DAGs: no virtual environment found \
+— run 'astro dev start' first
+"""
+
+STANDALONE_NO_PYTEST_RUN = """\
+Checking your DAGs for errors…
+Error: something went wrong while parsing your DAGs: exec: "pytest": \
+executable file not found in $PATH
+"""
+
+
+def test_cli_refusal_carries_its_own_reason(tmp_path):
+    # A project committing `dev.mode: standalone` sends the CLI to a gitignored
+    # local .venv no CI checkout has. Still no verdict (rc 2), but the reason
+    # must reach the caller — reporting only "produced no recognizable result"
+    # is what made this take a log dig to diagnose in the field.
+    rc, result, *_ = _run(tmp_path, STANDALONE_NO_VENV_RUN)
+    assert rc == 2
+    assert result["cli_error"] == "no virtual environment found — run 'astro dev start' first"
+
+
+def test_cli_refusal_half_provisioned_venv(tmp_path):
+    # The nastier standalone shape: the venv exists (so the CLI's own venv check
+    # passes) but nothing installed pytest into it.
+    rc, result, *_ = _run(tmp_path, STANDALONE_NO_PYTEST_RUN)
+    assert rc == 2
+    assert result["cli_error"] == 'exec: "pytest": executable file not found in $PATH'
+
+
+def test_build_failure_wrapper_is_not_demoted_to_cli_error(tmp_path):
+    # The image-build failure wears the same "something went wrong while parsing
+    # your DAGs" wrapper. It is a real verdict (rc 4) and must not be reclassified
+    # as a missing one just because the wrapper matches.
+    rc, result, *_ = _run(tmp_path, BUILD_FAILURE_RUN)
+    assert rc == 4
+    assert "cli_error" not in result
+
+
+def test_completed_run_never_gains_a_cli_error(tmp_path):
+    # Defensive: a finished run is a verdict. Even if the wrapper somehow appears
+    # alongside a closing summary, the summary wins.
+    text = FAILING_RUN + "Error: something went wrong while parsing your DAGs: noise\n"
+    rc, result, *_ = _run(tmp_path, text)
+    assert rc == 3
+    assert "cli_error" not in result
 
 
 def test_long_run_summary_with_hms_suffix_is_recognized(tmp_path):