pi-dev-team 0.2.0

package/scripts/coverage_delta_steering.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python3
+"""coverage_delta_steering.py — turn per-Story coverage deltas into a live
+Phase-5 steering signal (issue #1790).
+
+Why this exists. `/coverage-delta` already records one snapshot per Story into
+`coverage-history.json`, but nothing read that history *during* the phase: a
+Pass-1 run kept closing Stories and reporting mutation-kill progress while
+line coverage stayed flat at 74.2%, and nobody saw it until the final report —
+by which point the phase's whole budget had gone into the wrong layer. This
+script is the mid-phase check: after each Story's delta lands, it measures the
+movement of the trailing Stories and fails (exit 3) once several consecutive
+Stories have moved line coverage by less than the minimum expected per-Story
+delta, so `/test-improve` can prompt for a Phase-1 targeting re-check before
+spending the next Story.
+
+Movement, per Story snapshot, is the change in `line_pct` since the previous
+Story snapshot — or, for the first Story, since the run's
+`baseline_line_pct`. A **negative** movement counts as flat: a Story that made
+coverage worse is certainly not progress. A snapshot with no comparable
+predecessor (no previous Story and no recorded baseline) has movement `None`
+and **breaks** the streak rather than extending it — absence of measurement is
+not evidence of flatness.
+
+Branch movement is reported alongside but does **not** drive the verdict:
+branch coverage is not natively available on every stack (Go), so keying the
+gate on it would make the check silently mode-dependent.
+
+Statuses (and exit codes):
+
+- `flat_streak` (3) — `--consecutive` or more trailing Stories each moved less
+  than `--min-line-delta`. The caller prompts; this script does not decide
+  policy.
+- `flat_streak_forming` (0) — the trailing Story moved less than the minimum
+  but the streak is still shorter than `--consecutive`. A distinct status
+  rather than `ok`, because "not yet a streak" is not "coverage is moving".
+- `insufficient_history` (0) — fewer measurable Stories than `--consecutive`,
+  or a trailing Story whose movement could not be measured at all, so no
+  streak verdict is possible yet.
+- `ok` (0) — the trailing Story moved coverage by at least the minimum.
+- exit `2` — the history file is missing, unreadable, not JSON, not a JSON
+  array, or carries a non-snapshot element; also an out-of-range
+  `--consecutive`/`--min-line-delta`. Never reported as an all-clear.
+
+Stdlib-only (ADR 0014/0015), Python 3.10+ floor (ADR 0031).
+
+Usage:
+    python3 coverage_delta_steering.py \\
+      --history .dev-team-reports/test-improve/<slug>/data/coverage-history.json
+    python3 coverage_delta_steering.py --history <path> \\
+      --min-line-delta 0.25 --consecutive 3 --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+DEFAULT_MIN_LINE_DELTA = 0.1
+DEFAULT_CONSECUTIVE = 3
+
+STATUS_FLAT = "flat_streak"
+STATUS_FORMING = "flat_streak_forming"
+STATUS_OK = "ok"
+STATUS_INSUFFICIENT = "insufficient_history"
+
+# Movements are rounded only to kill binary-float artifacts (72.4 - 72.0 =
+# 0.40000000000000568), NOT to two decimals: rounding to 2dp before the
+# threshold comparison would let a true 0.096-point move clear a 0.1 minimum,
+# making a display concern decide the gate.
+_MOVEMENT_PRECISION = 10
+
+
+class HistoryError(ValueError):
+    """The coverage history could not be read or is not a snapshot array."""
+
+
+def load_history(path: Path) -> list[dict]:
+    """Read `coverage-history.json`, raising HistoryError on anything that is
+    not a readable JSON array of snapshot objects."""
+    if not path.is_file():
+        raise HistoryError(f"coverage history not found: {path}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HistoryError(f"{path}: unreadable coverage history ({exc})") from exc
+    if not isinstance(payload, list):
+        raise HistoryError(
+            f"{path}: coverage history must be a JSON array of snapshots, "
+            f"got {type(payload).__name__}"
+        )
+    # A non-dict element means the file is corrupt or half-rewritten. Dropping
+    # it silently would leave a corrupt history indistinguishable from a phase
+    # that simply hasn't closed enough Stories yet — a clean verdict from
+    # unusable evidence, which is the one thing this gate must never produce.
+    for index, entry in enumerate(payload):
+        if not isinstance(entry, dict):
+            raise HistoryError(
+                f"{path}: coverage history entry at index {index} is a "
+                f"{type(entry).__name__}, not a snapshot object"
+            )
+    return list(payload)
+
+
+def story_snapshots(history: list[dict]) -> list[dict]:
+    """Keep only Story-attributed snapshots — the per-Story Phase-5 deltas.
+    Phase-less snapshots (`/quality-targets-converge`'s whole-suite call
+    passes no `--story`) are not Stories and must not enter the streak."""
+    return [entry for entry in history if entry.get("story")]
+
+
+def _movement(current: object, previous: object) -> float | None:
+    if isinstance(current, bool) or isinstance(previous, bool):
+        return None
+    if not isinstance(current, (int, float)) or not isinstance(previous, (int, float)):
+        return None
+    return round(float(current) - float(previous), _MOVEMENT_PRECISION)
+
+
+def _story_rows(snapshots: list[dict]) -> list[dict]:
+    rows = []
+    for index, snapshot in enumerate(snapshots):
+        if index == 0:
+            prev_line = snapshot.get("baseline_line_pct")
+            prev_branch = snapshot.get("baseline_branch_pct")
+        else:
+            prev_line = snapshots[index - 1].get("line_pct")
+            prev_branch = snapshots[index - 1].get("branch_pct")
+        rows.append(
+            {
+                "story": snapshot.get("story"),
+                "captured_at": snapshot.get("captured_at"),
+                "line_pct": snapshot.get("line_pct"),
+                "branch_pct": snapshot.get("branch_pct"),
+                "line_movement": _movement(snapshot.get("line_pct"), prev_line),
+                "branch_movement": _movement(snapshot.get("branch_pct"), prev_branch),
+            }
+        )
+    return rows
+
+
+def _trailing_flat_streak(rows: list[dict], min_line_delta: float) -> list[dict]:
+    """The trailing run of Stories whose measured line movement is below the
+    minimum. Stops at the first Story that moved enough OR whose movement is
+    unmeasurable."""
+    streak: list[dict] = []
+    for row in reversed(rows):
+        movement = row["line_movement"]
+        if movement is None or movement >= min_line_delta:
+            break
+        streak.append(row)
+    streak.reverse()
+    return streak
+
+
+def evaluate(
+    snapshots: list[dict],
+    min_line_delta: float = DEFAULT_MIN_LINE_DELTA,
+    consecutive: int = DEFAULT_CONSECUTIVE,
+) -> dict:
+    """Evaluate Story-attributed `snapshots` for a flat-coverage streak."""
+    rows = _story_rows(snapshots)
+    measured = [r for r in rows if r["line_movement"] is not None]
+    streak = _trailing_flat_streak(rows, min_line_delta)
+
+    if len(streak) >= consecutive:
+        status = STATUS_FLAT
+        message = (
+            f"{len(streak)} consecutive Stories moved line coverage by less than "
+            f"{min_line_delta} points ("
+            + ", ".join(f"{r['story']}: {r['line_movement']:+}" for r in streak)
+            + "). Re-check Phase-1 targeting against "
+            "coverage-gap-ranking.json before spending the next Story — "
+            "mutation-kill progress on an already-covered layer cannot move "
+            "these numbers."
+        )
+    elif len(measured) < consecutive:
+        status = STATUS_INSUFFICIENT
+        message = (
+            f"{len(measured)} Story delta(s) measured; {consecutive} are needed "
+            "before a flat-coverage streak can be judged."
+        )
+    elif rows[-1]["line_movement"] is None:
+        # The trailing Story has no comparable predecessor (a null/absent
+        # line_pct in the appended snapshot), so its movement could not be
+        # measured. Neither `ok` nor `flat_streak` is honest here.
+        status = STATUS_INSUFFICIENT
+        message = (
+            f"The latest Story ({rows[-1]['story']}) could not be measured — "
+            "its snapshot carries no comparable line_pct, so no coverage "
+            "movement verdict is possible for it."
+        )
+    elif streak:
+        # Below the streak threshold but still not moving: reporting this as
+        # `ok` would claim "targeting is producing coverage movement" about a
+        # Story that moved less than the minimum — the false all-clear this
+        # gate exists to prevent. Exit code stays 0; only the wording and
+        # status carry the warning.
+        status = STATUS_FORMING
+        message = (
+            f"The latest {len(streak)} Story/Stories moved line coverage by less "
+            f"than {min_line_delta} points ({len(streak)} of {consecutive} "
+            "needed for a flat-coverage streak). Watch the next Story's delta "
+            "before spending more of the phase on this layer."
+        )
+    else:
+        status = STATUS_OK
+        message = (
+            f"Latest Story moved line coverage by "
+            f"{rows[-1]['line_movement']:+} points — targeting is producing "
+            "coverage movement."
+        )
+
+    average = (
+        round(sum(r["line_movement"] for r in measured) / len(measured), 2)
+        if measured
+        else None
+    )
+    return {
+        "status": status,
+        "stories_evaluated": len(rows),
+        "stories_measured": len(measured),
+        "min_line_delta": min_line_delta,
+        "consecutive_threshold": consecutive,
+        "streak": len(streak),
+        "flat_stories": streak,
+        "running_average_line_movement": average,
+        "stories": rows,
+        "message": message,
+    }
+
+
+def render_text(result: dict) -> str:
+    lines = [
+        f"Coverage-delta steering: {result['status']}",
+        result["message"],
+        "",
+        f"{'story':<24}  {'line %':>8}  {'Δ line':>8}  {'Δ branch':>9}",
+    ]
+    for row in result["stories"]:
+        line_move = row["line_movement"]
+        branch_move = row["branch_movement"]
+        lines.append(
+            f"{row['story']!s:<24}  "
+            f"{row['line_pct'] if row['line_pct'] is not None else '-':>8}  "
+            f"{line_move if line_move is not None else '-':>8}  "
+            f"{branch_move if branch_move is not None else '-':>9}"
+        )
+    lines.append("")
+    lines.append(
+        f"running average line movement: {result['running_average_line_movement']}"
+    )
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="coverage_delta_steering.py",
+        description=(
+            "Flag several consecutive Stories whose coverage delta is "
+            "near zero, so Phase-1 targeting can be re-checked mid-phase."
+        ),
+    )
+    parser.add_argument(
+        "--history",
+        type=Path,
+        required=True,
+        help="Path to coverage-history.json.",
+    )
+    parser.add_argument(
+        "--min-line-delta",
+        type=float,
+        default=DEFAULT_MIN_LINE_DELTA,
+        help=(
+            "Minimum expected per-Story line-coverage movement in percentage "
+            f"points (default: {DEFAULT_MIN_LINE_DELTA})."
+        ),
+    )
+    parser.add_argument(
+        "--consecutive",
+        type=int,
+        default=DEFAULT_CONSECUTIVE,
+        help=(
+            "How many consecutive below-minimum Stories constitute a flat "
+            f"streak (default: {DEFAULT_CONSECUTIVE})."
+        ),
+    )
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    # An out-of-range threshold must fail loudly rather than produce a nonsense
+    # verdict: `--consecutive 0` makes `len(streak) >= consecutive` trivially
+    # true for any history (including an empty one), and a negative
+    # `--min-line-delta` makes every movement — regressions included — count
+    # as progress.
+    if args.consecutive < 1:
+        parser.error("--consecutive must be >= 1")
+    if args.min_line_delta < 0:
+        parser.error("--min-line-delta must be >= 0")
+
+    try:
+        history = load_history(args.history)
+    except HistoryError as exc:
+        if args.json:
+            print(json.dumps({"error": str(exc)}, indent=2))
+        else:
+            print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    result = evaluate(
+        story_snapshots(history),
+        min_line_delta=args.min_line_delta,
+        consecutive=args.consecutive,
+    )
+    print(json.dumps(result, indent=2) if args.json else render_text(result))
+    return 3 if result["status"] == STATUS_FLAT else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    # render_text()'s "Δ line"/"Δ branch" headers crash with
+    # UnicodeEncodeError on a non-UTF-8 console (e.g. Windows' default
+    # cp1252) before any output reaches the caller. Forcing UTF-8 here only
+    # affects real script invocation (this guard never runs for an in-process
+    # `import coverage_delta_steering; coverage_delta_steering.main(...)`
+    # caller, e.g. a test using capsys), matching every other script's
+    # console-encoding independence.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.exit(main())

package/scripts/coverage_discovery_dotnet.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""coverage_discovery_dotnet.py — discover and classify every project in a
+.NET solution for multi-project coverage discovery (issue #1759, Slice 2).
+
+Enumerates every project via `dotnet sln <solution> list` and classifies
+each `.csproj` using `coverage_config.TestClassification`, checking in
+order:
+
+1. An inline `Microsoft.NET.Test.Sdk` `PackageReference` in the `.csproj`
+   itself (matched on `Include="Microsoft.NET.Test.Sdk"`, case-insensitively
+   per NuGet package ID convention, regardless of attribute order or
+   whether a `Version` attribute is present — this also covers Central
+   Package Management's version-less inline form) -> `TEST`.
+2. If absent inline, walk every `Directory.Build.props` from the project's
+   directory up to the solution root (inclusive). An **unconditioned** match
+   (no `Condition` attribute on the `PackageReference` itself or its
+   enclosing `ItemGroup`) -> `TEST`. A match that exists only inside a
+   `Condition` -> `AMBIGUOUS` (this script deliberately never evaluates
+   MSBuild conditions, matching this repo's stdlib-only,
+   no-runner-execution convention already established by
+   `coverage_readiness.py`).
+3. No match anywhere -> `NOT_TEST`.
+
+**Known, documented limitation.** A `GlobalPackageReference` declared in
+`Directory.Packages.props` (MSBuild Central Package Management's other,
+zero-inline-reference mechanism, distinct from the `Directory.Build.props`
+ancestor walk above) is not walked. A project relying solely on it
+classifies `NOT_TEST` — see the plan's Risks section.
+
+**Security hardening.** Every resolved project path is verified to stay
+within the resolved repository root before it is read or classified — a
+`.sln` entry containing `..` or an absolute path can never cause this
+module to read or XML-parse a file outside the repository. Separator
+normalization (see `_parse_sln_list_output`, issue #1828) happens before
+that check, so a backslash-separated `..\\outside\\Evil.csproj` is refused
+like its forward-slash form instead of slipping past as one opaque
+filename. Every `.csproj`
+and `Directory.Build.props` file is also screened for `<!DOCTYPE`/
+`<!ENTITY` declarations before being parsed (entity-expansion hardening) —
+neither file legitimately carries either.
+
+The `dotnet` subprocess boundary (`shutil.which("dotnet")` and
+`subprocess.run([...])`) is mocked/stubbed in this module's unit tests — no
+real .NET SDK is required to run them, keeping this module inside the
+required `ci-local.sh`/pre-push pytest gate.
+
+Stdlib-only (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+import coverage_config
+from coverage_config import TestClassification
+
+_TEST_SDK_PACKAGE = "Microsoft.NET.Test.Sdk"
+
+# `dotnet sln ... list` per-run wall-clock timeout, matching this repo's
+# convention in sibling scripts (e.g. codebase_recon.py).
+_SLN_LIST_TIMEOUT_SECONDS = 120
+
+# The disallowed-XML-marker tuple is shared: coverage_config.UNSAFE_XML_MARKERS.
+
+
+def discover_dotnet_projects(repo_root):
+    """Discover and classify every project in `repo_root`'s `.sln`.
+
+    Returns a list of `{"path": <repo-relative project path as returned by
+    "dotnet sln list">, "classification": TestClassification}` entries on
+    success, `coverage_config.DISCOVERY_NOT_APPLICABLE` when no `.sln` is
+    present, or `coverage_config.discovery_error(...)` for any
+    tooling/parsing failure.
+    """
+    root = Path(repo_root).resolve()
+
+    sln_files = sorted(root.glob("*.sln"))
+    if not sln_files:
+        return coverage_config.DISCOVERY_NOT_APPLICABLE
+    if len(sln_files) > 1:
+        names = ", ".join(f.name for f in sln_files)
+        return coverage_config.discovery_error(
+            f"Multiple .sln files found at repository root: {names}. "
+            "Multi-solution repositories are not supported for discovery; "
+            "leave exactly one .sln at the repository root."
+        )
+    sln_path = sln_files[0]
+
+    dotnet_path = shutil.which("dotnet")
+    if dotnet_path is None:
+        return coverage_config.discovery_error(
+            "The `dotnet` CLI is not on PATH; install the .NET SDK to "
+            "enable solution discovery."
+        )
+
+    try:
+        result = subprocess.run(  # noqa: PLW1510 — returncode is checked explicitly below to return a discovery_error rather than raise
+            [dotnet_path, "sln", str(sln_path.resolve()), "list"],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            env={**os.environ, "DOTNET_CLI_UI_LANGUAGE": "en"},
+            timeout=_SLN_LIST_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired:
+        return coverage_config.discovery_error(
+            f"`dotnet sln {sln_path.name} list` timed out after "
+            f"{_SLN_LIST_TIMEOUT_SECONDS}s."
+        )
+    except OSError as exc:
+        return coverage_config.discovery_error(
+            f"Failed to run `dotnet sln {sln_path.name} list`: {exc}"
+        )
+
+    if result.returncode != 0:
+        return coverage_config.discovery_error(
+            f"`dotnet sln {sln_path.name} list` failed: {result.stderr.strip()}"
+        )
+
+    project_rel_paths = _parse_sln_list_output(result.stdout)
+
+    projects = []
+    for rel_path in project_rel_paths:
+        absolute_problem = _absolute_entry_problem(rel_path)
+        if absolute_problem is not None:
+            return coverage_config.discovery_error(
+                f"Solution '{sln_path.name}' references project "
+                f"'{rel_path}', which {absolute_problem}. Only "
+                "solution-relative project paths are supported; refusing to "
+                "read or classify it."
+            )
+        csproj_path = (root / rel_path).resolve()
+        if not coverage_config.is_within(csproj_path, root):
+            return coverage_config.discovery_error(
+                f"Solution '{sln_path.name}' references project "
+                f"'{rel_path}', which resolves outside the repository "
+                f"root ('{root}'); refusing to read or classify it."
+            )
+        if not csproj_path.is_file():
+            return coverage_config.discovery_error(
+                f"Solution '{sln_path.name}' references project "
+                f"'{rel_path}' but the file does not exist on disk."
+            )
+        classification = _classify_project(csproj_path, root)
+        if isinstance(classification, dict):
+            return classification  # a discovery_error propagated up
+        projects.append({"path": rel_path, "classification": classification})
+
+    return projects
+
+
+def _absolute_entry_problem(rel_path: str) -> str | None:
+    """Return a reason when a (already separator-normalized) `.sln` entry is an
+    absolute path rather than a solution-relative one, else `None`.
+
+    Checked explicitly rather than left to `PurePosixPath.is_absolute()`,
+    which is platform-divergent for exactly the shapes a Windows-authored
+    solution produces: a drive-letter path like `C:/Projects/App.csproj` is
+    NOT absolute on POSIX, so it would silently become a nonsense subpath of
+    the repo root and fail with a misleading "does not exist on disk" instead
+    of naming the real problem. A UNC path normalizes to a leading `//`, which
+    IS absolute on POSIX — so without this check the same input produces two
+    different diagnostics depending on the runner's OS."""
+    if len(rel_path) >= 2 and rel_path[1] == ":" and rel_path[0].isalpha():
+        return "is an absolute Windows path (drive letter)"
+    if rel_path.startswith("//"):
+        return "is an absolute UNC network path"
+    if rel_path.startswith("/"):
+        return "is an absolute path"
+    return None
+
+
+def _parse_sln_list_output(stdout: str) -> list:
+    """Parse `dotnet sln list`'s stdout into a list of repo-relative project
+    paths in POSIX form, skipping the `Project(s)` header and its underline.
+
+    **Separator normalization (issue #1828).** `dotnet sln list` echoes the
+    separators the `.sln` was authored with, and a Windows-authored solution
+    emits backslashes. On POSIX `pathlib` treats `src\\App\\App.csproj` as a
+    single opaque filename — `PurePath(...).name` returns the whole string —
+    so the `.csproj` is never found and every project in the solution fails
+    the "does not exist on disk" check even though the file is present. Since
+    most enterprise .NET solutions are Windows-authored and their CI is
+    commonly Linux, that made .NET discovery non-functional for them.
+
+    Backslashes are therefore normalized to `/` here, once, at parse time.
+    This is deliberately unconditional rather than POSIX-only: it keeps the
+    recorded path identity — the string every caller compares against
+    `included`/`excluded` entries — byte-identical across platforms, so a
+    `coverage-config.json` written on Windows still reconciles on Linux.
+    Normalizing before the caller's containment check also keeps the `..`
+    traversal guard effective on backslash-separated escapes, which
+    previously slipped past it as opaque filenames.
+
+    Accepted limitation: a genuine POSIX filename containing a literal
+    backslash would be rewritten. MSBuild solution files always use `\\` as a
+    separator, so such a path does not occur in `.sln` output."""
+    projects = []
+    for raw_line in stdout.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line == "Project(s)":
+            continue
+        if set(line) == {"-"}:
+            continue
+        projects.append(line.replace("\\", "/"))
+    return projects
+
+
+# The entity-expansion screen this module introduced now lives in
+# `coverage_config` so every discovery stack that parses repository-supplied
+# XML shares ONE implementation — the Java stack (#1765) originally shipped
+# without a screen at all, which is exactly the drift a shared helper
+# prevents. Call sites below use `coverage_config.read_and_screen_xml`
+# directly: private re-export aliases would give one shared symbol two names
+# depending on which file you are reading.
+
+
+def _classify_project(csproj_path: Path, solution_root: Path):
+    """Classify a single project's `.csproj`, walking ancestor
+    `Directory.Build.props` files (never climbing above `solution_root`)
+    when no inline marker is found. Each `Directory.Build.props` found is
+    resolved and containment-checked against `solution_root` before being
+    read or parsed — mirroring the JS module's symlinked-manifest handling
+    (`coverage_discovery_js._classify_package`) — so a symlinked
+    `Directory.Build.props` pointing outside the solution root is refused
+    rather than read. Returns a `TestClassification` value, or
+    `coverage_config.discovery_error(...)` if the `.csproj` (or an ancestor
+    `Directory.Build.props`) is not well-formed XML, is unreadable, escapes
+    `solution_root`, or fails the entity-expansion safety check."""
+    data, unsafe = coverage_config.read_and_screen_xml(csproj_path)
+    if unsafe is not None:
+        return unsafe
+    try:
+        csproj_root = ET.fromstring(data)
+    except ET.ParseError as exc:
+        return coverage_config.discovery_error(
+            f"Could not parse '{csproj_path}' as XML: {exc}"
+        )
+
+    if _test_sdk_reference_kind(csproj_root) is not None:
+        return TestClassification.TEST
+
+    found_conditioned = False
+    current_dir = csproj_path.parent
+    while coverage_config.is_within(current_dir, solution_root):
+        props_path = current_dir / "Directory.Build.props"
+        if props_path.is_file():
+            try:
+                resolved_props_path = props_path.resolve()
+            except OSError as exc:
+                return coverage_config.discovery_error(
+                    f"Could not resolve '{props_path}': {exc}"
+                )
+            if not coverage_config.is_within(resolved_props_path, solution_root):
+                return coverage_config.discovery_error(
+                    f"'{props_path}' resolves to '{resolved_props_path}', "
+                    f"which is outside the solution root "
+                    f"('{solution_root}'); refusing to read or parse it."
+                )
+            props_data, unsafe = coverage_config.read_and_screen_xml(resolved_props_path)
+            if unsafe is not None:
+                return unsafe
+            try:
+                props_root = ET.fromstring(props_data)
+            except ET.ParseError as exc:
+                return coverage_config.discovery_error(
+                    f"Could not parse '{props_path}' as XML: {exc}"
+                )
+            kind = _test_sdk_reference_kind(props_root)
+            if kind == "unconditioned":
+                return TestClassification.TEST
+            if kind == "conditioned":
+                found_conditioned = True
+        if current_dir == solution_root:
+            break
+        current_dir = current_dir.parent
+
+    if found_conditioned:
+        return TestClassification.AMBIGUOUS
+    return TestClassification.NOT_TEST
+
+
+def _test_sdk_reference_kind(root) -> str | None:
+    """Return `"unconditioned"`, `"conditioned"`, or `None` for whether
+    `root` contains a `Microsoft.NET.Test.Sdk` `PackageReference` (matched
+    case-insensitively, per NuGet package ID convention), and whether it (or
+    its enclosing `ItemGroup`) carries an MSBuild `Condition` attribute.
+    This script deliberately never evaluates the condition's truth value —
+    presence alone drives the distinction."""
+    found_conditioned = False
+    for item_group in root.iter():
+        if coverage_config.local_name(item_group.tag) != "ItemGroup":
+            continue
+        group_conditioned = "Condition" in item_group.attrib
+        for child in item_group:
+            if coverage_config.local_name(child.tag) != "PackageReference":
+                continue
+            include = (child.get("Include") or "").strip().casefold()
+            if include != _TEST_SDK_PACKAGE.casefold():
+                continue
+            if group_conditioned or "Condition" in child.attrib:
+                found_conditioned = True
+            else:
+                return "unconditioned"
+    return "conditioned" if found_conditioned else None