"""Subordinate-resolution guard.

Hard CI invariant preventing the next recurrence of the "departed report
still counts as a current report" bug class. The same root cause —
a hand-rolled ``IdentityPerson.manager_person_id`` BFS that forgets (or
diverges on) the ``employment_status`` leaver filter — was patched seven
times across separate surfaces (dashboard headcount, me_universe team
footprint / cloud, GlobalSearch, RelationshipGraph, mobile aggregate,
asset team, provisioning billing). PR1 collapsed all of them into the
single canonical resolver :func:`app.core.person_scope.subordinate_person_ids`.

This guard stops a NEW surface from re-introducing an inline manager-tree
BFS. It rejects any ``IdentityPerson.manager_person_id.in_(...)`` outside
the canonical module — that frontier-expansion signature is the tell-tale
of a transitive subordinate walk and is exactly what must go through
``person_scope`` instead.

Legitimate non-BFS uses (a single ``manager_person_id == viewer_id``
direct-report check, or a deliberately distinct skip-level subquery) are
allowed by adding ``# person-scope-exempt: <reason>`` on the matched line
or one of the two lines above it. The marker forces a human to justify the
exception rather than silently re-growing the bug surface.

Runs without a database connection — pure text scan. Exits 0 on success,
1 with a human-readable diagnostic on failure.
"""

from __future__ import annotations

import re
import sys
from pathlib import Path

# The frontier-expansion signature of a transitive manager-tree BFS.
_BFS_SIGNATURE = re.compile(r"\bmanager_person_id\.in_\(")

_EXEMPT_MARKER = "person-scope-exempt:"

# The canonical module is the ONE place this pattern is allowed — it *is*
# the shared BFS every other surface must call.
_ALLOWED_FILES = {
    "app/core/person_scope.py",
}


def _app_dir() -> Path:
    return Path(__file__).resolve().parent.parent / "app"


def _rel(path: Path, root: Path) -> str:
    return str(path.relative_to(root.parent)).replace("\\", "/")


def scan_lines(lines: list[str]) -> list[int]:
    """Return 1-based line numbers carrying an un-exempted BFS signature.

    Exposed for unit testing. An exemption marker may sit on the matched
    line or either of the two lines above it (so a long ORM clause can
    carry the marker as a preceding comment without tripping line-length
    lint).
    """
    hits: list[int] = []
    for idx, line in enumerate(lines):
        if not _BFS_SIGNATURE.search(line):
            continue
        window = lines[max(0, idx - 2): idx + 1]
        if any(_EXEMPT_MARKER in w for w in window):
            continue
        hits.append(idx + 1)
    return hits


def main() -> int:
    app_dir = _app_dir()
    if not app_dir.is_dir():
        print(f"[subordinate-guard] app dir not found: {app_dir}")
        return 1

    offenders: list[str] = []
    for path in sorted(app_dir.rglob("*.py")):
        rel = _rel(path, app_dir)
        if rel in _ALLOWED_FILES:
            continue
        lines = path.read_text(encoding="utf-8").splitlines()
        for line_no in scan_lines(lines):
            offenders.append(f"  {rel}:{line_no}: {lines[line_no - 1].strip()}")

    if offenders:
        print(
            "[subordinate-guard] FAIL — inline manager_person_id BFS found. "
            "Resolve subordinates through "
            "app.core.person_scope.subordinate_person_ids(scope=...) instead of "
            "hand-rolling the manager-tree walk (this is the leaver-display bug "
            "class PR1 collapsed). If the use is a deliberate non-BFS exception, "
            "add '# person-scope-exempt: <reason>' on or just above the line.\n"
            + "\n".join(offenders)
        )
        return 1

    print(
        "[subordinate-guard] OK — no inline manager-tree BFS outside person_scope."
    )
    return 0


if __name__ == "__main__":
    sys.exit(main())