# `actions.json` schema

`.assess/actions.json` is the durable, machine-readable Top 3 Actions contract. `assess_finalize.py` writes it from the LLM-authored `actions` array in `finalize-input.json`. Unlike the report's markdown table, it is meant to be parsed: an executor agent - often a smaller, cheaper model than the one that ran the assessment - reads it to know what to do, how to verify it, where to stop, and whether the work is still open.

## Top-level shape

```json
{
  "schema": 2,
  "run_id": "20260707T101500Z-ab12cd",
  "actions": [ /* one entry per action, sorted by rank */ ]
}
```

| Field | Type | Meaning |
|-------|------|---------|
| `schema` | int | Schema version. Currently `2`. |
| `run_id` | string \| null | The run that produced this contract, copied from `run-context.json`. `null` when the run carried no id (legacy). Ties the actions back to the assessment that raised them. |
| `actions` | array | The Top 3 Actions, one object per row, sorted ascending by `rank`. |

## Per-action fields

```json
{
  "rank": 1,
  "action": "Investigate the src/foo.go <-> src/bar.go seam",
  "done_when": "The coupling is documented in a contract, or the shared state is extracted",
  "scope_fence": "Only src/foo.go and src/bar.go; do not touch callers",
  "status": "pending",
  "claimed_by": null,
  "completed_sha": null,
  "mode": "characterize_first",
  "finding": "hidden_coupling"
}
```

### Required (written every time)

| Field | Type | Meaning |
|-------|------|---------|
| `rank` | int | Priority order (1 = do first). |
| `action` | string | The directive. Also the **stable identity** used to carry status across re-runs (rank reshuffles between runs; the directive text does not). |
| `done_when` | string | The exit criterion. Without it a weak executor doesn't know when to stop. |
| `scope_fence` | string | What NOT to touch. Without it a weak executor over-extends. |
| `status` | enum | Lifecycle: `pending` \| `claimed` \| `done` \| `reopened`. See below. |
| `claimed_by` | string \| null | Identifier of the executor that claimed the action; `null` while unclaimed. |
| `completed_sha` | string \| null | The commit SHA that satisfied `done_when`; `null` until done. |
| `mode` | enum | Deterministic execution posture, derived from `finding`: `characterize_first` \| `verify_then_retire` \| `refactor_safe`. See below. |

### Recommended (passed through when the LLM supplies them)

`layer`, `effort`, `files`, `first_step`, and `finding` are carried through verbatim if present. `finding` is the finding type the action addresses; it drives `mode` derivation and is worth supplying for that reason.

## `status` lifecycle

| Status | Meaning |
|--------|---------|
| `pending` | Open, unclaimed. The initial state of every newly written action. |
| `claimed` | An executor has taken the action but not finished it. |
| `done` | Completed; `completed_sha` records the commit that satisfied `done_when`. |
| `reopened` | A later run re-flagged work a prior run had marked done. |

**Carry-forward across runs.** Each `/assess` run recomputes `rank`, `mode`, `done_when`, and `scope_fence` from the freshest findings, but preserves `status`, `claimed_by`, and `completed_sha` for any action whose `action` directive matches an entry in the existing `actions.json`. A done action therefore stays done, with its completed SHA and claimant intact, when the assessment is re-run. An action that no longer appears in the new Top 3 simply drops out of the contract.

## `mode` derivation

`mode` is derived deterministically by the finalize step from the action's `finding` type (via `FINDING_MODES` in `lib/keyhole_signals.py`) - it is never guessed by the LLM. Each mode traces to one of the write-side tendencies the toolkit guards against:

| Mode | Posture | Finding types |
|------|---------|---------------|
| `characterize_first` | Understand/contract the code before changing it - the risk is acting blind on an unpinned seam or complexity. | `hidden_coupling`, `unexplained_complexity`, `untrusted_hotspot`, `orphaned_understanding`, `override_contradicts_signals` |
| `verify_then_retire` | A self-description that may be lying - verify whether it is still true, then delete / ticket / escalate. Never trust it as-is. | `lying_map`, `self_referential_tests`, `unactioned_intent`, `candidate_dead_weight` |
| `refactor_safe` | A bounded island safe to restructure in isolation. | `refactor_boundary`, `accretion_ratchet` |

An action whose `finding` is absent or unrecognised defaults to `characterize_first` - the conservative "understand before you touch it" posture.

## Versioning

- **v1** (`schema: 1`): `{schema, actions:[{rank, action, done_when, scope_fence, ...}]}`. No lifecycle fields, no `mode`, no top-level `run_id`.
- **v2** (`schema: 2`): adds per-action `status` / `claimed_by` / `completed_sha` / `mode` and top-level `run_id`.

The finalize step reads a v1 `actions.json` for carry-forward without error: a v1 entry contributes no lifecycle fields, so a re-run over a v1 contract initialises every action to `pending`.

# Consent lifecycle: decline markers, three phases, non-interactive contract

Reference for `/assess`'s consent flow. SKILL.md Steps 2a/2b/2d and the assess-pr skill point here. Two concerns: how a permanent decline is recorded (decline markers with provenance), and how the offers are grouped so a user is never asked 8-10 serial questions (three phases) and a headless run never blocks (the non-interactive contract).

## Decline markers carry provenance

A user can permanently decline any optional tool (`scc`, a dead-code linter, the mutation pass) by writing `$REPO_ROOT/.assess/.no-<tool>`. A decline is a durable, silencing choice, so the marker records **who** declined **what**, **when**, and under **which plugin version** - not a provenance-free empty file. Always write markers with this helper so the disclosure and re-offer logic downstream has the data it needs:

```bash
# Resolve the plugin version for provenance stamping (degrades to "unknown").
# The deterministic core records the running version in run-context.json.
assess_plugin_version() {
  if [ -f "$REPO_ROOT/.assess/run-context.json" ]; then
    jq -r '.plugin_version // "unknown"' "$REPO_ROOT/.assess/run-context.json" 2>/dev/null || echo unknown
  else
    echo unknown
  fi
}

# Write a JSON decline marker with provenance. $1 = tool; $2 = optional reason.
write_decline_marker() {
  local tool="$1" reason="${2:-}"
  mkdir -p "$REPO_ROOT/.assess"
  local who when ver
  who="$(git -C "$REPO_ROOT" config user.name 2>/dev/null || echo "${USER:-unknown}")"
  when="$(date +%Y-%m-%d)"
  ver="$(assess_plugin_version)"
  jq -n --arg by "$who" --arg at "$when" --arg ver "$ver" --arg reason "$reason" \
    '{declined_by: $by, declined_at: $at, plugin_version: $ver}
       + (if $reason == "" then {} else {reason: $reason} end)' \
    > "$REPO_ROOT/.assess/.no-$tool"
}
```

The marker JSON shape: `{declined_by, declined_at, plugin_version, reason?}` (`reason` optional). The deterministic core reads every `.no-<tool>` back into `run-context.json` as `decline_markers` (with a `decline_disclosures` line per marker and a `reoffer_mutation` flag). Two downstream effects, both automatic once you write markers this way:

- **Disclosure.** The report surfaces each active marker verbatim from `decline_disclosures`, e.g. _"Mutation testing permanently declined by ben on 2026-07-07"_ - a silenced capability is never invisible.
- **Re-offer once per major.** When a mutation marker was written under an older *major* plugin version, the core sets `reoffer_mutation: true`; Step 2d re-asks once. Declining again permanently restamps the marker at the current version, so its major now matches and the re-offer does not repeat within the same major.

**Pre-versioning markers** (empty or non-JSON files from before this convention) are still honoured as a decline; they read as "declined by an unknown user on an unknown date" and are never auto-re-offered (no major to compare). The `[ -f ... ]` presence checks in SKILL.md work identically for JSON and legacy markers.

## Three phases

`/assess` asks for consent at several points. Left un-batched, that is 8-10 serial questions - a tax the user pays one modal at a time. The flow is grouped into **three phases**, each a single decision surface:

- **Phase 1 - tool installs** (SKILL.md Steps 2a + 2b): **one** batched AskUserQuestion covering every optional analysis tool (`scc` plus each per-language dead-code linter). These are read-only system installs; batching them is safe because none modifies the repo.
- **Phase 3 - mutation pass** (SKILL.md Step 2d): kept **separate** and asked on its own. Unlike Phase 1, the mutation pass *modifies source and runs code*, so it carries a different risk class and must not be bundled into an install question where a user might wave it through. Frame it explicitly as code modification.
- **Phase 2 - write-back** (assess-pr Steps 5-7): **one** batched AskUserQuestion covering the four write-back offers (open a PR, track findings, freeze a CI gate, file feedback).

The phases are numbered by their risk grouping, not their run order: Phase 1 and 3 happen during Step 2; Phase 2 happens at the end.

## Non-interactive contract (headless / CI)

When no human can answer - a headless run, a CI job, any non-tty stdin - **every offer is treated as declined**. The run must complete with **zero interactive prompts**; never emit an AskUserQuestion that would block a pipeline forever. This holds in every phase.

Two enforcement surfaces, because the phases straddle the core run (Step 2c, which writes `run-context.json`):

- **Phase 1 (Steps 2a/2b) precedes the core** - `run-context.json` does not exist yet. Here the contract is **orchestration**: if this is a headless/CI run (no human to answer), make no Phase 1 AskUserQuestion calls, install nothing, write no markers. You determine this from your own runtime context.
- **Phases 3 and 2 (Steps 2d and the assess-pr write-back) follow the core**, so they read the authoritative `interactive` flag from `run-context.json`. That flag is set from the **explicit signal you pass the core**, not a stdin probe: pass `--non-interactive` to `assess_core.py` (or set `ASSESS_NON_INTERACTIVE=1` / `CI`) **only** on the same headless/CI run for which you skipped Phase 1. `sys.stdin.isatty()` is never consulted - the core runs as a subprocess with no controlling terminal, so it would misread a normal interactive `/assess` as headless and silently suppress every offer. With no flag and no CI env, the run is interactive by default.

  ```bash
  jq '{interactive, offers}' "$REPO_ROOT/.assess/run-context.json"
  ```

  When `interactive` is `false`, **make no AskUserQuestion calls** - every offer (`tool_install`, `mutation`, `pr`, `issue_tracking`, `ci_gate`, `feedback`, `uninstall`) is already recorded as `{type, status: "skipped", reason: "non-interactive"}` in `offers`, the run's audit trail. When `true`, `offers` is empty and you drive the phases live.

Passing the same signal to Phase 1 (orchestration) and to the core (the `--non-interactive` flag) keeps all three phases reading one decision, not two. The core cannot make AskUserQuestion calls for you, so *you* enforce "no prompts when non-interactive"; the `offers` array is the record that you did.

# Monorepo scoping: `/assess <path>`

When the user runs `/assess <path>` (a directory under the repo root), scope the
whole assessment to that subtree. The metrics, score, badge, wiki, and gate are
all computed for - and labelled with - the scope, and every artifact lands under
`.assess/<scope-slug>/` instead of `.assess/`. A root-level run (no path) is
unchanged.

This exists because a monorepo holds several services in one git repo. A
whole-repo score averages them into a number that describes none of them; a
scoped run answers "how ready is *this* service" with no signal bleeding in from
a sibling directory.

## Deriving the scope

`$SCOPE` is the path argument, resolved to a directory under `$REPO_ROOT`. If it
does not exist or is not under the repo root, the scripts exit non-zero with an
`error:` message - report that to the user rather than pressing on.

```bash
# $SCOPE is repo-relative, e.g. services/api
SCOPE_SLUG=$(printf '%s' "$SCOPE" | tr '/\\' '-')   # services/api -> services-api
ASSESS_DIR="$REPO_ROOT/.assess/$SCOPE_SLUG"
mkdir -p "$ASSESS_DIR"
```

Every `.assess/...` path in the orchestrator's Step 1-7.5 becomes
`$ASSESS_DIR/...` for a scoped run (the run-context, the SVGs, the stats
sidecars, the wiki, the badge, `finalize-input.json`). A whole-repo run keeps
`ASSESS_DIR="$REPO_ROOT/.assess"` so its output is byte-identical to before.

## Threading the scope into the scans

Each deterministic step takes the scope so it scores only the subtree while still
rooting at the repo (so `.assess/config.toml` excludes and the git churn window
are resolved once, repo-wide, and stay comparable across scopes):

<!-- chat-skip:start -->
```bash
# <assess-skill-dir> is the directory SKILL.md's own `uv run` lines name. Do not
# assume a reference file gets the harness's path substitution.
# Heatmap - scores only files under the scope; title + default SVG name carry it
uv run "<assess-skill-dir>/scripts/complexity-treemap.py" "$REPO_ROOT" \
  --scope "$SCOPE" -o "$ASSESS_DIR/complexity-heatmap.svg" \
  --stats "$ASSESS_DIR/complexity-stats.json"

# Deterministic core - reads the scoped stats sidecar it just wrote, confines the
# doc graph, doc staleness, dead-code, promissory-marker and change-coupling
# scans to the subtree, routes every artifact under .assess/<slug>/, and records
# `scope` / `scope_slug` in run-context.json for the report and badge.
uv run "<assess-skill-dir>/scripts/assess_core.py" "$REPO_ROOT" --scope "$SCOPE"
```
<!-- chat-skip:end -->

The deterministic core confines the doc graph, doc staleness, dead-code,
promissory-marker and change-coupling scans to the subtree, routes every
artifact under `.assess/<slug>/`, and records `scope` / `scope_slug` in
`run-context.json` for the report and badge.

The doc-graph SVG has no `--scope` flag of its own; render it for the subtree by
pointing it at the scope directory as its root
(`doc-graph-svg.py "$REPO_ROOT/$SCOPE" -o "$ASSESS_DIR/doc-graph.svg"`), or skip
it for a code-only service.

The opt-in mutation re-run must be given the same scope so it finds the scoped
run-context: `assess_core.py "$REPO_ROOT" --opt-in-mutation --scope "$SCOPE"`.

## What "scoped" means per signal

- **Complexity / hotspots** - only files under the scope are scored; the
  dominance warning is per-scope.
- **Doc graph + staleness** - only docs (and `.base` hubs) under the scope.
- **Git churn** - the treemap saturation axis and the behaviour co-change pairs
  count only commits that touched the subtree.
- **Dead code, promissory markers, change coupling** - candidates/markers/pairs
  outside the scope are dropped, so a sibling's TODO or unused function never
  appears.
- **Observability** stays repo-level - telemetry is a whole-repo property, not a
  per-subtree one.

## Labelling

The badge label reads `AI-readiness (services/api)` and the wiki `index.md`
carries a `_Scope: \`services/api\`_` line, so a committed artifact is never
mistaken for a whole-repo score. The report should name the scope in its
heading too. `run-context.json` carries `scope` (repo-relative) and `scope_slug`
for any consumer; both are `null` on a whole-repo run.

# Uninstall `/assess` from a repo

Everything `/assess` leaves in a **target** repo, and how to remove it cleanly. Offered at the end of a run (see the assess-pr end-of-run offers); also runnable on demand. `/assess` writes only inside the target repo - it installs no global state - so removal is a bounded set of files plus a few in-file edits. Nothing here touches the `ai-native-toolkit` plugin itself; this removes the *artifacts a run produced*, not the tool.

Work from the target repo root (`$REPO_ROOT`). Do each step only if that artifact exists - a repo that never opted into the CI gate has no workflow to delete, and so on. None of these is destructive beyond the assessment: no source file, test, or history is touched.

## 1. Delete the `.assess/` directory

The assessment wiki and all transient artifacts live here: `assess-report.md`, `complexity-heatmap.svg`, `doc-graph.svg`, `run-context.json`, `complexity-stats.json` (+ `.prior.json`), `badge.json`, `actions.json`, `index.md`, `log.md`, `hotspots/`, `config.toml`, the `.cache/` scratch dir, and any decline markers (see step 4).

```bash
rm -rf "$REPO_ROOT/.assess"
```

If `.assess/` was committed, stage the deletion (`git rm -r --cached .assess` then commit) so it leaves the tree.

## 2. Remove the badge line from the README

The PR offer may have added a shields.io AI-readiness badge that points at `.assess/badge.json`. With `.assess/` gone the badge would 404, so remove the embed line. It looks like:

```markdown
![AI-readiness](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2F<owner>%2F<repo>%2F<default-branch>%2F.assess%2Fbadge.json)
```

Find and delete it (check `README.md`, and any other README the repo uses):

```bash
grep -rn "assess%2Fbadge.json\|.assess/badge.json" "$REPO_ROOT"/README* 2>/dev/null
```

Delete the matching line(s) with an editor - do not blind-`sed` a README, since surrounding prose may reference the badge.

## 3. Delete the CI gate workflow

If the freeze-into-CI offer was accepted, a gating workflow was written:

```bash
rm -f "$REPO_ROOT/.github/workflows/assess-gate.yml"
```

That is the only workflow `/assess` emits. Removing it stops the gate from running on future PRs. No other CI file is touched.

## 4. Remove decline markers

Permanent-decline markers (`.assess/.no-mutmut`, `.assess/.no-scc`, `.assess/.no-<tool>`) live inside `.assess/`, so step 1 already removed them. Only if the user chose to keep `.assess/` (e.g. to preserve the report) remove the markers explicitly so a future re-install starts from a clean slate:

```bash
rm -f "$REPO_ROOT"/.assess/.no-*
```

## 5. Remove archetype override markers from instruction files

`/assess` never writes these - a user adds an `assess-archetype: <value>` marker by hand to force the knowledge-base or software archetype. If one was added for `/assess`, remove it from the instruction file so it does not linger as a dangling directive. Scan the known instruction files:

```bash
grep -rn "assess-archetype" \
  "$REPO_ROOT/CLAUDE.md" "$REPO_ROOT/AGENTS.md" "$REPO_ROOT/GEMINI.md" \
  "$REPO_ROOT/.cursorrules" "$REPO_ROOT/.github/copilot-instructions.md" 2>/dev/null
```

Delete any matching line (typically `<!-- assess-archetype: knowledge-base -->`). Leave the rest of the instruction file untouched.

## 6. Optional: `.gitignore` hint and tracked findings

- If the PR offer's gitignore hint was followed, a `.gitignore` line was added for `.assess/complexity-stats.prior.json`. With `.assess/` gone it is inert; remove the line only if you want a spotless `.gitignore`.
- **Tracked findings are not removed.** Issues created by the "track the Top 3 Actions" offer (labelled `assess-finding`) are real work items in the user's tracker. Uninstalling the tool does not close them - the close decision is the user's. Mention any open `assess-finding` items so the user can triage them separately:

  ```bash
  gh issue list --label assess-finding --state open 2>/dev/null
  ```

## Verify

After the steps above, no assessment artifact should remain:

```bash
ls "$REPO_ROOT/.assess" 2>/dev/null            # should be absent
grep -rn "assess%2Fbadge.json" "$REPO_ROOT"/README* 2>/dev/null   # no output
ls "$REPO_ROOT/.github/workflows/assess-gate.yml" 2>/dev/null     # should be absent
```

All three silent means the repo is back to its pre-`/assess` state (bar any `assess-finding` tracker items the user chose to keep).

"""Orchestrator for the deterministic core of /assess.

Reads:
    {repo_root}/.assess/complexity-stats.json       (current run)
    {repo_root}/.assess/complexity-stats.prior.json (if it exists)
    {repo_root}/CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md (any that exist)

Writes:
    {repo_root}/.assess/run-context.json   (everything the LLM needs)
    {repo_root}/.assess/index.md           (regenerated each run)
    {repo_root}/.assess/log.md             (appended each run)
    {repo_root}/.assess/hotspots/*.md      (one per top hotspot)

Run:
    uv run assess_core.py <repo_root>

The LLM still writes assess-report.md (the prose-heavy summary).
The LLM reads run-context.json to ground that prose in deterministic data.
"""
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "networkx",
#     "grimp",
# ]
# ///
from __future__ import annotations

import argparse
import json
import re
import sys
import uuid
from datetime import datetime
from pathlib import Path
from typing import Any

# Make sibling lib package importable when run as a script
sys.path.insert(0, str(Path(__file__).resolve().parent))

from lib.accretion_ratchet import scan_accretion_ratchet
from lib.agent_instructions_grader import (
    detect_alias,
    detect_skills_dir,
    grade_instructions,
    scan_sensitive_content,
)
from lib.agent_ops import scan_agent_ops
from lib.anomaly_detector import detect_anomalies
from lib.archetype import analyze_archetype
from lib.badge import (
    concern_count_from_findings,
    fallback_badge,
    write_badge,
)
from lib.assess_config import (
    is_user_excluded, load_excludes, load_structure_config, load_working_notes_config,
)
from lib.change_coupling import build_rename_map
from lib.config_drift import scan_config_drift
from lib.coverage_report import detect_coverage_report, load_coverage_data
from lib.decline_markers import build_decline_block
from lib.gate_cost import estimate_gate_cost
from lib.instruction_claims import scan_instruction_claims
from lib.interactivity import build_offers_block
from lib.doc_graph import build_doc_graph, is_repo_file
from lib.gap_actions import build_gap_actions
from lib.doc_staleness import analyze_doc_staleness, content_clock
from lib.generated_files import matches_generated_name
from lib.git_churn import ContentClock, git_commit_info, tracked_files
from lib.keyhole_signals import integrate as integrate_keyhole_signals
from lib.liveness_scan import scan_liveness
from lib.promissory_markers import scan_promissory_markers
from lib.review_reality import scan_review_reality
from lib.structure_graph import analyze_structure
from lib.stats_diff import StatsDiff, diff_stats, hotspot_commits, load_stats
from lib.structure_drift import (
    SEAM_ALLOWLIST,
    detect_path_existence_drift,
)
from lib.sibling_tests import TestIndex, build_test_index, has_sibling_test, shared_name_keys
from lib.test_focus import compute_test_focus, mutation_scope
from lib.test_pressure import scan_test_pressure
from lib.wiki_writer import (
    UNFINALIZED_ACTIONS_POINTER,
    HotspotEntry,
    LogEntry,
    append_log_entry,
    last_log_entry_is_unfinalized_run,
    prune_orphan_hotspots,
    retire_excluded_hotspots,
    supersede_unfinalized_log_entry,
    verify_log_chain,
    write_hotspot_page,
    write_index,
)


# Artifact schema version, stamped on every artifact the run produces
# (run-context.json, the badge, the wiki pages, complexity-stats). Distinct from
# the stats-layout `schema_version` (from #244) that versions the sidecar shape
# for diff comparability: this one versions the run_id provenance envelope.
# Bumped when the cross-artifact provenance schema changes shape in a way a
# consumer must adapt to.
# 1.1.0: run-context.json doc_graph gains link_only_orphan_rate /
# link_only_reachability_pct, and its orphan_rate / reachability_pct now count
# reference edges (#353). complexity-stats.json is unchanged, so its layout
# STATS_SCHEMA_VERSION stays put and the cross-run diff stays armed.
ARTIFACT_SCHEMA_VERSION = "1.1.0"


def _new_run_id() -> str:
    """A unique id for this run: a sortable wall-clock stamp plus random suffix.

    ``YYYYMMDDHHMMSS-<8 hex>`` - the timestamp orders runs, the uuid suffix makes
    two runs in the same second still distinct. Stamped on every artifact so
    finalize can prove the finalize-input and run-context came from one run.
    """
    return f"{datetime.now().strftime('%Y%m%d%H%M%S')}-{uuid.uuid4().hex[:8]}"


# Known agent instruction file locations (relative to repo root).
# The same heuristic grader applies to all of them.
INSTRUCTION_FILE_PATHS = [
    # Canonical repo-root locations
    "CLAUDE.md",
    "AGENTS.md",
    "GEMINI.md",
    ".cursorrules",
    # Tool-specific locations under .github/
    ".github/copilot-instructions.md",
    ".github/claude-instructions.md",
    ".github/claude-review-instructions.md",
    # docs/ subdirectory variants used by some projects
    "docs/CLAUDE.md",
    "docs/AGENTS.md",
]

# Grade ranking (best -> worst) for picking a top-level grade across multiple files.
GRADE_RANK = {"A": 7, "A-": 6, "B+": 5, "B": 4, "C": 3, "D": 2, "F": 1}


def _file_freshness_days(file_path: Path, clock: ContentClock) -> int:
    """Days since file_path's last content change in git. 0 if not in git.

    Same clock as `.doc_staleness` (author time, bulk mechanical commits
    skipped - issue #333), so a licence-header sweep cannot make a stale
    instruction file read as fresh.
    """
    days = clock.days(file_path)
    return days if days is not None else 0


def _grade_instruction_files(
    repo_root: Path,
) -> tuple[dict[str, dict], str | None, list[str], list[dict], dict, dict]:
    """Scan all known instruction file locations and grade each one found.

    Returns: (files_dict, best_grade, untracked, dangling_refs, skills_info, sensitive)
        files_dict: keyed by filename, e.g. {"CLAUDE.md": {grade, score, ...}}.
        best_grade: best letter grade across all *tracked, present* files; None
            if none found. None is distinct from "F": None means no committed
            file exists ("create the file"), "F" means one exists but scored
            poorly ("fix the file").
        untracked: instruction files that exist on disk but aren't part of the
            repo (untracked / git-ignored / symlinked from outside). Surfaced as
            a finding so a personal CLAUDE.md isn't silently credited *or*
            silently ignored - the agent should note it isn't committed.
        dangling_refs: instruction files that are dangling symlinks (committed
            `.cursorrules -> missing-target`) - an advertised-but-broken
            instruction surface.
        sensitive: per-path list of REDACTED sensitive-content findings (IPs,
            SSH/host details, credentials, home-dir/PII paths) for any candidate
            on disk - tracked or untracked. Surfaced so the remediation warns
            before recommending a file be committed, especially to a public repo
            (issue #56).
    """
    repo_root = repo_root.resolve()
    tracked = tracked_files(repo_root)
    # Detect skills directories once, before grading any file. A repo that
    # factors guidance into on-demand skills uses progressive disclosure, so a
    # large instruction file is not penalized as bloat (see compute_bloat_penalty).
    skills_info = detect_skills_dir(repo_root)
    skills_present = skills_info["skills_dirs_present"]
    clock = content_clock(repo_root)  # one build for every candidate
    found: dict[str, dict] = {}
    untracked: list[str] = []
    dangling_refs: list[dict] = []
    sensitive: dict[str, list] = {}
    for rel_path in INSTRUCTION_FILE_PATHS:
        candidate = repo_root / rel_path
        # A dangling symlink (an instruction file pointing at a missing target)
        # exists() == False but is_symlink() == True - an advertised, broken
        # instruction reference, not "no file".
        if candidate.is_symlink() and not candidate.exists():
            dangling_refs.append({"path": rel_path, "reason": "symlink target missing"})
            continue
        if not candidate.exists():
            continue
        # Scan every candidate on disk for content unsafe to publish - tracked
        # OR untracked. An untracked file is exactly the one the remediation
        # might tell the user to commit, so it must be scanned before that.
        try:
            disk_text = candidate.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            disk_text = ""
        flags = scan_sensitive_content(disk_text) if disk_text else []
        if flags:
            sensitive[rel_path] = flags
        # Only grade genuine repo files. An on-disk-but-untracked instruction
        # file (a contributor's personal CLAUDE.md, or one symlinked in from
        # outside) is recorded as a finding rather than credited to the score.
        if not is_repo_file(candidate, repo_root, tracked):
            untracked.append(rel_path)
            continue
        text = disk_text
        freshness = _file_freshness_days(candidate, clock)
        grade = grade_instructions(
            text, freshness_days=freshness, skills_present=skills_present
        )
        entry = {
            "grade": grade.grade,
            "score": grade.score,
            "subscores": grade.subscores,
            "freshness_days": freshness,
            "line_count": len(text.splitlines()),
            "present": True,
        }
        # Alias detection (issue #57): a committed AGENTS.md/GEMINI.md that is a
        # symlink to - or a thin stub pointing at - a canonical instruction file
        # is the desired single-source-of-truth shape, not a low-scoring bespoke
        # doc. Record the target so the second pass can inherit its grade.
        alias_target = _alias_target(candidate, text, repo_root)
        if alias_target:
            entry["alias_target_basename"] = alias_target
        found[rel_path] = entry

    _resolve_alias_grades(found)

    best = (max(found.values(), key=lambda v: GRADE_RANK.get(v["grade"], 0))["grade"]
            if found else None)
    return found, best, untracked, dangling_refs, skills_info, sensitive


# Basenames (lowercased) of the known instruction files, for cross-referencing
# broken doc links against the instruction surface.
_INSTRUCTION_BASENAMES = {Path(p).name.lower() for p in INSTRUCTION_FILE_PATHS}

# Canonical files an alias would point at (a single source of truth).
_CANONICAL_ALIAS_TARGETS = {"claude.md", "agents.md", "gemini.md"}


def _alias_target(candidate: Path, text: str, repo_root: Path) -> str | None:
    """Return the canonical basename this file aliases, or None.

    Two shapes count as an alias (issue #57):
      * a symlink whose target is a canonical instruction file, or
      * a thin stub whose only real content references a canonical file.
    The alias's own basename is excluded, so CLAUDE.md never aliases itself.
    """
    self_name = candidate.name.lower()
    # Symlink alias - the target is whatever the link resolves to.
    if candidate.is_symlink():
        try:
            target_name = candidate.resolve().name.lower()
        except OSError:
            target_name = ""
        if target_name in _CANONICAL_ALIAS_TARGETS and target_name != self_name:
            return candidate.resolve().name
    # Thin-stub alias - short file that just points at a canonical doc.
    alias = detect_alias(text)
    if alias["is_alias"] and alias["alias_target"]:
        if alias["alias_target"].lower() != self_name:
            return alias["alias_target"]
    return None


def _resolve_alias_grades(found: dict[str, dict]) -> None:
    """Let an alias inherit the grade of the canonical file it points at.

    A thin alias/symlink should grade as the single-source-of-truth it routes
    to, not as a low-scoring standalone doc that the remediation would tell the
    user to rewrite. Mutates ``found`` in place: marks ``is_alias`` and copies
    the target's grade/score when the target is itself graded.
    """
    by_basename = {Path(rel).name.lower(): meta for rel, meta in found.items()}
    for meta in found.values():
        target = meta.pop("alias_target_basename", None)
        if not target:
            continue
        target_meta = by_basename.get(target.lower())
        meta["is_alias"] = True
        meta["alias_target"] = target
        if target_meta is not None and target_meta is not meta:
            # Inherit the canonical grade - the alias is as good as what it
            # points at, and carries no maintenance burden of its own.
            meta["grade"] = target_meta["grade"]
            meta["score"] = target_meta["score"]


def detect_ancestor_instructions(repo_root: Path) -> list[str]:
    """Detect committed-elsewhere instruction files that cascade into this repo.

    Claude Code composes ``CLAUDE.md`` from every ancestor directory plus the
    global ``~/.claude/CLAUDE.md``. So "no instruction file at the repo root" is
    not the same as "no instructions anywhere" - a clone gets none of the
    ancestor cascade, but the maintainer working in-tree does (issue #57).

    Returns REDACTED, repo-relative / ``~``-relative descriptors (never absolute
    paths - those would leak a home directory into the committed wiki). Best
    effort: any filesystem error yields an empty list.
    """
    found: list[str] = []
    try:
        repo_root = repo_root.resolve()
        # Walk parent directories above the repo root (bounded depth).
        parent = repo_root.parent
        depth = 1
        while parent != parent.parent and depth <= 6:
            for name in ("CLAUDE.md", "AGENTS.md", "GEMINI.md"):
                if (parent / name).is_file():
                    found.append(f"{name} ({depth} level(s) above repo root)")
            parent = parent.parent
            depth += 1
        # The global user instructions, if present.
        for rel in (".claude/CLAUDE.md", ".codex/AGENTS.md", ".gemini/GEMINI.md"):
            if (Path.home() / rel).is_file():
                found.append(f"~/{rel} (global user instructions)")
    except OSError:
        return []
    return found


def _broken_instruction_refs(doc_graph: dict, dangling_refs: list[dict]) -> list[dict]:
    """Combine dangling-symlink instruction files with broken doc links whose
    target is an instruction file (an entry doc linking a missing CLAUDE.md).
    These are advertised-but-broken instruction references."""
    refs = list(dangling_refs)
    if doc_graph.get("available"):
        for bl in doc_graph.get("broken_links", []):
            target = bl.get("target", "")
            if Path(target).name.lower() in _INSTRUCTION_BASENAMES:
                refs.append({
                    "from": bl.get("from"), "target": target,
                    "reason": "link to missing instruction file",
                })
    return refs


def _read_plugin_version() -> str:
    """Read the plugin version from .claude-plugin/plugin.json.

    The plugin.json lives three directories up from this script:
        scripts/assess_core.py -> scripts/ -> skills/assess/ -> skills/ -> repo root
    """
    plugin_json = Path(__file__).resolve().parents[3] / ".claude-plugin" / "plugin.json"
    try:
        data = json.loads(plugin_json.read_text(encoding="utf-8"))
        return str(data.get("version", "unknown"))
    except (FileNotFoundError, json.JSONDecodeError):
        return "unknown"


def _parse_semver(value: str | None) -> tuple[int, int, int] | None:
    """Parse ``MAJOR.MINOR.PATCH`` (leading ``v`` and a pre-release/build
    suffix tolerated) into an int triple, or ``None`` when it isn't a semver.

    A small local parse rather than a ``packaging`` dependency: the deterministic
    core is stdlib-only by convention (its only deps are the graph libs), and the
    only comparison the diff needs is the major component and equality.
    """
    if not isinstance(value, str):
        return None
    m = re.match(r"^\s*v?(\d+)\.(\d+)\.(\d+)", value)
    if not m:
        return None
    return int(m.group(1)), int(m.group(2)), int(m.group(3))


def _diff_is_reliable(
    prior_version: str | None,
    current_version: str | None,
    prior_schema: object | None,
    current_schema: object | None,
) -> tuple[bool, str | None]:
    """Decide whether a cross-run diff can be trusted, and why not if not.

    A diff is only trustworthy when both snapshots came from a comparable
    toolchain. This gates the plugin-version and stats-schema halves of that
    (tool-backend version changes are handled by the caller, which owns the
    per-tool notes). Ordering matches the failure severity:

    - prior snapshot never stamped a version -> unreliable (can't establish
      comparability at all);
    - either version unparseable -> unreliable (can't reason about the delta);
    - stats schema changed -> unreliable (the sidecar shape the diff reads moved);
    - MAJOR version changed -> unreliable AND a trend reset (breaking change to
      the deterministic core; prior history is not comparable);
    - only MINOR/PATCH moved -> reliable, trend and gate stay armed.

    Returns ``(reliable, note)``; ``note`` is ``None`` exactly when reliable.
    """
    if not prior_version:
        return False, "version not stamped in prior snapshot"
    pv = _parse_semver(prior_version)
    cv = _parse_semver(current_version)
    if pv is None or cv is None:
        return False, (
            f"unparseable plugin version (prior {prior_version!r}, "
            f"current {current_version!r})"
        )
    if prior_schema != current_schema:
        return False, f"schema version changed {prior_schema}->{current_schema}"
    if pv[0] != cv[0]:
        return False, f"major version changed {prior_version}->{current_version}"
    return True, None


_NON_TOOL_VERSION_KEYS = frozenset(
    {"schema_version", "artifact_schema_version", "plugin_version"})


def _stats_tool_versions(stats: dict | None) -> dict[str, str]:
    """Extract the ``{tool: version}`` map a stats sidecar stamped.

    Reads every flat ``<tool>_version`` key the treemap writes (``lizard_version``,
    ``scc_version``, and any per-function backend added later), skipping the
    layout and plugin stamps. A tool absent from a pre-stamping snapshot is
    simply omitted - it can't be compared, so it never forces a false reset."""
    if not isinstance(stats, dict):
        return {}
    out: dict[str, str] = {}
    for key, v in stats.items():
        if (key.endswith("_version") and key not in _NON_TOOL_VERSION_KEYS
                and isinstance(v, str) and v):
            out[key[: -len("_version")]] = v
    return out


def _compute_diff_reliability(
    prior_exists: bool, prior: dict | None, current: dict,
) -> tuple[bool, str | None, bool]:
    """Decide whether the cross-run diff is trustworthy, returning
    ``(diff_reliable, diff_version_note, diff_trend_reset)``.

    Layers the plugin/schema check (``_diff_is_reliable``) over the tool-backend
    check (``_tool_version_change_note``): a MINOR/PATCH plugin bump keeps the
    diff armed unless a complexity backend also moved. A first run (no prior) is
    trivially reliable - there is nothing to compare, so nothing to distrust.
    """
    if not prior_exists:
        return True, None, False
    reliable, note = _diff_is_reliable(
        (prior or {}).get("plugin_version"),
        current.get("plugin_version"),
        (prior or {}).get("schema_version"),
        current.get("schema_version"),
    )
    if not reliable:
        # A MAJOR plugin bump is a breaking change to the core: the prior trend
        # history is not comparable, so the report discloses a reset.
        trend_reset = bool(note and note.startswith("major version changed"))
        return False, note, trend_reset
    # Plugin/schema are comparable; a backend version change still voids the diff
    # (and names which tool moved) so the numbers aren't read as a regression.
    tool_note = _tool_version_change_note(
        _stats_tool_versions(prior), _stats_tool_versions(current),
    )
    if tool_note is not None:
        return False, tool_note, False
    return True, None, False


def _tool_version_change_note(
    prior_tools: dict[str, str], current_tools: dict[str, str]
) -> str | None:
    """Return a note naming the first complexity backend whose version changed
    between the two snapshots, or ``None`` when every shared tool matches.

    Only a tool recorded in BOTH snapshots can be compared; a tool missing from
    the prior snapshot (older, pre-stamping) is skipped rather than treated as a
    change - that case is already caught by the plugin/schema reliability check.
    A backend version change (e.g. a lizard release) can shift cyclomatic scores
    with no change in the tree, so the diff against the prior snapshot is voided.
    """
    for tool in sorted(current_tools):
        pv = prior_tools.get(tool)
        cv = current_tools.get(tool)
        if pv is not None and cv is not None and pv != cv:
            return (
                f"{tool} version changed {pv}->{cv}; complexity scores may shift, "
                "so the diff against the prior snapshot is not comparable"
            )
    return None


def _has_sibling_test(
    repo_root: Path, rel_path: str, shared_names: frozenset[str] = frozenset(),
    index: TestIndex | None = None,
) -> bool | None:
    """Best-effort: does this file have a test file?

    Delegates to ``lib.sibling_tests.has_sibling_test``, the one resolver the
    ``test_focus`` signal also reads, so the hotspot page's ``Has test file`` row
    and the focus table agree. ``True``/``False`` from a filesystem check of the
    naming idioms (``foo.ts`` next to ``foo.test.ts``, ``FooTest.java``, an
    adjacent ``__tests__/``, a mirrored ``tests/`` tree, ...); ``None`` only when
    the file isn't on disk (a since-deleted path in a stats snapshot).
    """
    return has_sibling_test(repo_root, rel_path, shared_names, index)


def _load_first_flagged(assess_dir: Path) -> dict[str, str]:
    """Load the first-flagged date map from .assess/first-flagged.json.

    Returns an empty dict if the file does not exist yet (first run).
    """
    state_file = assess_dir / "first-flagged.json"
    if not state_file.exists():
        return {}
    return json.loads(state_file.read_text(encoding="utf-8"))


def _rekey_first_flagged(
    first_flagged: dict[str, str], rename_map: dict[str, str],
) -> dict[str, str]:
    """Move each first-flagged entry for a renamed path onto its current path.

    The date travels with the file. When the current path already has an entry,
    the earlier known date wins, so a rename never makes a file look newer.
    """
    rekeyed = {k: v for k, v in first_flagged.items() if k not in rename_map}
    for old, date in first_flagged.items():
        new = rename_map.get(old)
        if new is None:
            continue
        known = sorted(d for d in (date, rekeyed.get(new)) if d and d != "unknown")
        rekeyed[new] = known[0] if known else "unknown"
    return rekeyed


def _same_measurement_prior_run(
    assess_dir: Path, *, run_date: str, measured_commit: dict
) -> dict | None:
    """The previous run's context when this run supersedes it, else None.

    A run supersedes the previous one when both share ``run_date`` and the
    measured commit. The previous run-context.json is still on disk here (this
    run writes its own later), so it names the entry's run id and commit. The
    wiki writer only removes that run's log entry if it is the log's last and
    still carries placeholders; a finalized entry is history and stays (#355).

    A target with no git (``available`` false on both runs) has no commit to
    key on, so the date and the prior run id are the whole identity: two such
    runs on one day count as the same measurement.
    """
    try:
        prior = json.loads((assess_dir / "run-context.json").read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return None
    if not isinstance(prior, dict) or not prior.get("run_id"):
        return None
    if prior.get("run_date") != run_date:
        return None
    prior_commit = prior.get("measured_commit")
    if not isinstance(prior_commit, dict):
        return None
    head_sha = measured_commit.get("head_sha")
    if head_sha:
        same = prior_commit.get("head_sha") == head_sha
    else:
        same = (
            measured_commit.get("available") is False
            and prior_commit.get("available") is False
        )
    return prior if same else None


def _inherited_provisional_paths(
    assess_dir: Path, superseded: dict | None, first_flagged_map: dict[str, str],
) -> set[str]:
    """Paths first flagged only by the superseded, never-finalized run (#356).

    Empty unless the superseded run's log entry is still unfinalized. Each run
    records ``provisional_first_flagged``: the paths it first flagged plus those
    it inherited this way, so a chain of unfinalized same-day runs carries a
    file forward after it stops being "new". A run-context written before the
    key existed yields nothing: its ``diff_detail.new`` cannot tell a file first
    flagged there from one first flagged by a finalized run earlier that day
    that graduated and returned, and retiring the latter would delete a
    finalized date. Only paths whose first-flagged date is still that run's
    date qualify.
    """
    if superseded is None or not last_log_entry_is_unfinalized_run(
        assess_dir, superseded["run_id"],
    ):
        return set()
    paths = superseded.get("provisional_first_flagged")
    if not isinstance(paths, list):
        return set()
    return {
        p for p in paths
        if isinstance(p, str) and first_flagged_map.get(p) == superseded.get("run_date")
    }


def _excluded_after_unfinalized_run(
    assess_dir: Path, *, superseded: dict | None, first_flagged_map: dict[str, str],
    current: dict, diff: StatsDiff, excludes: tuple[set[str], list[str]],
) -> tuple[set[str], list[str]]:
    """Split out the files excluded after a never-finalized run (#356).

    Returns ``(provisional, excluded)``. ``provisional`` is what this run records
    as ``provisional_first_flagged``: the inherited paths plus the ones this run
    flags for the first time, minus ``excluded``. ``excluded`` is the sorted
    inherited paths now matched by a config exclude and no longer a top hotspot;
    they are removed from ``diff.graduated`` here so the rotated prior stats do
    not carry them into index.md. Must run before the hotspot loop stamps new
    first-flagged dates.
    """
    inherited = _inherited_provisional_paths(assess_dir, superseded, first_flagged_map)
    current_hot = {h["path"] for h in current.get("top_hotspots", [])}
    excluded = sorted(
        p for p in inherited - current_hot if is_user_excluded(Path(p), *excludes)
    )
    diff.graduated = [h for h in diff.graduated if h.path not in excluded]
    fresh = {h.path for h in diff.new if h.path not in first_flagged_map}
    return (inherited | fresh) - set(excluded), excluded


def _retire_excluded_unfinalized(
    assess_dir: Path, excluded: list[str], first_flagged_map: dict[str, str],
) -> tuple[list[str], list[str]]:
    """Retire the pages of ``excluded`` and drop their first-flagged entries.

    Returns ``(retired, dropped)``. A path whose page exists but has no status
    token to stamp keeps its entry, so a page that still reads live never loses
    its first-flagged date.
    """
    retired, unstamped = retire_excluded_hotspots(assess_dir, excluded)
    dropped = [p for p in excluded if p not in unstamped and p in first_flagged_map]
    for path in dropped:
        del first_flagged_map[path]
    return retired, dropped


def _drop_superseded_log_entry(assess_dir: Path, superseded: dict | None) -> None:
    """Remove the superseded run's log entry when it is still unfinalized."""
    if superseded is not None:
        supersede_unfinalized_log_entry(assess_dir, superseded["run_id"])


def _save_first_flagged(assess_dir: Path, first_flagged: dict[str, str]) -> None:
    """Persist the first-flagged date map to .assess/first-flagged.json."""
    (assess_dir / "first-flagged.json").write_text(
        json.dumps(first_flagged, indent=2), encoding="utf-8"
    )


def _write_badge(
    assess_dir: Path, promissory: Any, derived_findings: list[dict],
    run_id: str | None = None, scope: str | None = None,
) -> None:
    """Write the deterministic default badge, always.

    The shipped ``badge.json`` is the deterministic findings-count form: a pure
    function of measured run data, never an LLM-authored score. It is written on
    every run and is no longer overwritten by ``assess_finalize`` - the
    LLM-derived grade lives in ``assess-report.md``, and the badge's ``link``
    funnels a badge-clicker there. ``run_id`` stamps the badge with the run that
    produced it. ``scope`` (the repo-relative subtree) labels the badge for a
    ``/assess <path>`` monorepo run.
    """
    stale = (
        promissory.get("total_stale", 0)
        if isinstance(promissory, dict) and promissory.get("available")
        else 0
    )
    badge = fallback_badge(
        concern_count_from_findings(derived_findings), stale, run_id=run_id,
        scope=scope,
    )
    badge["link"] = "./assess-report.md"
    write_badge(assess_dir, badge)


# Cap on accretion files carried into run-context.json. The scanner measures
# every file; the run-context list keeps only the worst few that also score in
# the top complexity/size band, so a growing-but-simple file never earns a line.
MAX_ACCRETION_FILES = 12


def _excluded_generated(complexity_stats: dict) -> list[dict[str, str]]:
    """The stats file's ``excluded_generated`` list, keeping well-formed rows.

    Each row is ``{"path", "reason"}`` with non-empty strings; anything else
    (an older stats file without the key, a malformed row) is dropped, so the
    run-context key is always a list.
    """
    rows = complexity_stats.get("excluded_generated")
    if not isinstance(rows, list):
        return []
    return [
        {"path": r["path"], "reason": r["reason"]}
        for r in rows
        if isinstance(r, dict)
        and isinstance(r.get("path"), str) and r["path"]
        and isinstance(r.get("reason"), str) and r["reason"]
    ]


def _top_band_paths(complexity_stats: dict) -> set[str]:
    """Paths already in the top complexity/size band of this run's stats.

    Union of the three ranked top-N lists (``top_hotspots``/``top_complex``/
    ``top_large``). Accretion is only surfaced for a file already in this set:
    a growing file that scores low on complexity *and* size isn't a hotspot, so
    flagging its growth would be noise. Mirrors lib.keyhole_signals._paths_from_stats.
    """
    paths: set[str] = set()
    for key in ("top_hotspots", "top_complex", "top_large"):
        for entry in complexity_stats.get(key) or []:
            path = entry.get("path")
            if path:
                paths.add(path)
    return paths


def _accretion_block(scan: Any, complexity_stats: dict) -> dict[str, Any]:
    """Serialize an AccretionScan into the run-context ``accretion_ratchet`` block.

    On an unavailable scan, emits the same shape with an empty file list and the
    scan's reason (graceful degradation - a failed scan is never read as "no
    accretion"). On success, the flagged files are filtered to those already in
    the top complexity/size band (the noise budget), sorted by net additions
    descending with a path tie-break for a total, deterministic order, and capped
    at MAX_ACCRETION_FILES.
    """
    block: dict[str, Any] = {
        "available": scan.available,
        "reason": scan.reason,
        "reliable": scan.reliable,
        "deletion_fraction_threshold": scan.deletion_fraction_threshold,
        "files": [],
    }
    if not scan.available:
        return block

    band = _top_band_paths(complexity_stats)
    in_band = [f for f in scan.files if f.path in band]
    # The scan already sorts by (-net_additions, path); re-sort defensively so
    # the serialized order is a total, clone-independent order regardless of the
    # filtered subset's incoming order.
    in_band.sort(key=lambda f: (-f.net_additions, f.path))
    block["total_in_band"] = len(in_band)
    block["files"] = [f.to_dict() for f in in_band[:MAX_ACCRETION_FILES]]
    return block


def _accretion_lookup(scan: Any) -> dict[str, dict]:
    """O(1) ``{path: accretion_info}`` for the hotspot pages, from one scan.

    Each entry is the serialized AccretionFile plus the scan-wide ``reliable``
    flag, so a hotspot page can name a file's growth profile and disclaim it on
    degenerate history without re-deriving anything. Returns ``{}`` when the
    scan was unavailable - the hotspot loop then writes pages with no growth
    line (graceful degradation; the scan never gates page generation).
    """
    if not scan.available:
        return {}
    lookup: dict[str, dict] = {}
    for af in scan.files:
        entry = af.to_dict()
        entry["reliable"] = scan.reliable
        lookup[af.path] = entry
    return lookup


# The six Tier 1 grouping-disagreement counts, in a fixed order so the
# run-context tier_1 sub-block is deterministic regardless of dict iteration.
_TIER1_DISAGREEMENT_KEYS = (
    "human_grouped_static_splits",
    "human_split_static_fuses",
    "human_grouped_never_cochange",
    "human_split_but_cochange",
    "human_static_agree",
    "human_cochange_agree",
)


def _structure_drift_block(
    repo_root: Path, tier_1: dict,
) -> dict | None:
    """Build the run-context ``structure_drift`` block (Tier 0 + Tier 1).

    Tier 0 (``detect_path_existence_drift``) is the zero-threshold cut: declared
    ownership patterns matching no tracked file. It runs whenever an ownership
    map exists; when none does it degrades to ``available: False`` and the whole
    block is omitted (the caller drops a ``None``), keeping non-owned repos'
    run-context byte-stable.

    ``tier_1`` is the grouping-disagreement result ``keyhole_signals.integrate``
    already computed from the behaviour block's co-change pairs (no second
    ``git log`` parse, no double computation) - either the six disagreement
    counts or an ``available: False`` marker when the static import graph was
    unavailable or no ownership map existed. The seam allowlist was applied
    inside the detector, so the counts here are already post-allowlist.

    Returns ``None`` when Tier 0 is unavailable (no ownership map) - a graceful,
    half-block-free omission. Otherwise returns a JSON-serialisable block whose
    ``tier_0`` always carries data and whose ``tier_1`` is either the six
    disagreement counts or ``{"available": False}``.
    """
    tier_0 = detect_path_existence_drift(repo_root)
    if not tier_0.get("available"):
        return None  # no ownership map - omit the block entirely

    block: dict[str, Any] = {
        "tier_0": {
            "available": True,
            "empty_ownership_patterns": tier_0["empty_ownership_patterns"],
            "total_patterns": tier_0["total_patterns"],
            "matched_patterns": tier_0["matched_patterns"],
        },
    }

    if not tier_1.get("available"):
        block["tier_1"] = {"available": False}
        return block

    tier_1_block: dict[str, Any] = {"available": True}
    for key in _TIER1_DISAGREEMENT_KEYS:
        tier_1_block[f"{key}_count"] = tier_1.get(f"{key}_count", 0)
    tier_1_block["seam_allowlist_applied"] = True
    tier_1_block["allowlist_pairs_count"] = len(SEAM_ALLOWLIST)
    block["tier_1"] = tier_1_block
    return block


def _attach_structure_drift(
    ctx: dict[str, Any], repo_root: Path, tier_1: dict,
) -> None:
    """Attach the structure_drift block to ctx, or omit it on a graceful degrade.

    Builds the block via :func:`_structure_drift_block` (Tier 0 + the supplied
    Tier 1 result) under :func:`_safe`. Attaches only a real block (one carrying
    a ``tier_0``): the no-ownership-map path returns ``None`` and a scan failure
    returns ``_safe``'s degrade dict (no ``tier_0``); both omit the block rather
    than emit a half-block, keeping the contract that absence means "nothing to
    drift against / not assessed", never "no drift".
    """
    block = _safe(
        "structure_drift",
        lambda: _structure_drift_block(repo_root, tier_1),
    )
    if isinstance(block, dict) and "tier_0" in block:
        ctx["structure_drift"] = block


def _marker_debt_sentence(debt: dict | None) -> str:
    """One briefing sentence accusing a hotspot of its own stale promises."""
    if not debt:
        return ""
    families = ", ".join(debt["families"])
    return (
        f"Carries {debt['count']} stale promissory marker(s) "
        f"({families}; oldest survived {debt['max_survived']} edits to this file). "
    )


def _safe(label: str, fn):
    """Run a read-side scan, degrading to an unavailable marker on any failure.

    Read-side signals are additive context for the LLM, never gates - a broken
    scan must never block the assessment (PRD: "never block").
    """
    try:
        return fn()
    except Exception as e:  # noqa: BLE001 - intentional catch-all; degrade, don't crash
        return {"available": False, "reason": f"{label} scan failed: {e}"}


def _normalize_test_pressure(test_pressure: Any) -> dict:
    """Normalize a ``scan_test_pressure`` result into the run-context block shape.

    A failed (or malformed) scan must not read as "no mutation setup": that
    would mis-score Layer 1 just as a failed liveness scan would mis-score
    observability. On a bad result, carry an explicit unavailable marker with a
    null ``mutation_config_present`` and empty heuristic buckets so the LLM sees
    "not assessed", never a false negative. Keys mirror the real block's
    ``cheap_heuristics`` schema (assertion_on_internal / untested_boundaries /
    duplicate_truth) so the consumer's shape doesn't change on the failure path.

    Shared by the default read-only scan (``build_run_context``) and the opt-in
    mutation re-run (``run_opt_in_mutation``) so both write an identical shape.
    """
    tp_ok = (isinstance(test_pressure, dict)
             and "mutation_config_present" in test_pressure
             and "cheap_heuristics" in test_pressure)
    if tp_ok:
        return test_pressure
    return {
        "available": False,
        "reason": (test_pressure.get("reason")
                   if isinstance(test_pressure, dict)
                   else "test_pressure scan unavailable"),
        "mutation_config_present": None,
        "cheap_heuristics": {
            "assertion_on_internal": [],
            "untested_boundaries": [],
            "duplicate_truth": [],
        },
    }


# The annotation the LLM must attach to Layer 6 when mutation testing never
# ran. Layer 6 (truth pressure) asks whether the suite *proves* behaviour, not
# merely visits it - a claim only a mutation run can substantiate. Absent that
# run, the strongest honest verdict is Partial; a Present claim would be an
# unproven self-description, exactly the guardrail-erosion failure /assess
# exists to catch. assess_finalize enforces the cap deterministically.
MUTATION_NOT_RUN_ANNOTATION = "truth-pressure unproven (mutation not run)"


def _mutation_not_run_cap(test_pressure_block: dict) -> dict:
    """The Layer 6 cap the LLM reads: does mutation evidence exist this run?

    ``mutation_run`` is True only when the (opt-in, code-executing) bounded
    mutation pass actually ran - coverage-config detection alone leaves it
    False. When it is False, Layer 6 cannot be scored above Partial and the
    ``annotation`` must be attached; assess_finalize rejects a finalize-input
    that violates this.

    The flag alone is not trusted: a block that claims ``mutation_run`` but
    carries no parsed mutant record in ``per_file`` is evidence-free, so the cap
    stays applied (#317).
    """
    per_file = (
        test_pressure_block.get("per_file")
        if isinstance(test_pressure_block, dict) else None
    )
    mutation_run = bool(
        isinstance(test_pressure_block, dict)
        and test_pressure_block.get("mutation_run", False)
        and isinstance(per_file, list)
        and any(isinstance(rec, dict) for rec in per_file)
    )
    return {
        "applies": not mutation_run,
        "mutation_run": mutation_run,
        "max_layer6_band": "Present" if mutation_run else "Partial",
        "annotation": None if mutation_run else MUTATION_NOT_RUN_ANNOTATION,
    }


def _build_stale_hubs(doc_graph: dict, doc_staleness: dict) -> list[dict]:
    """Centrality x staleness - the priority Layer 0 signal.

    A stale *hub* (high PageRank) is the most dangerous lying map: everything
    routes through it. We join the doc graph's central docs with their
    staleness ratio so a stale hub surfaces as a top finding.

    Each hub carries the underlying `subject_method` + a `confidence` flag.
    `subject_method == "repo-baseline"` means the ratio is computed against
    repo-wide churn (no derivable subject), so the priority composite shares
    a denominator across every baseline entry - confidence on those is "low".
    The sort halves the priority of low-confidence entries so a precise-subject
    hub at half the raw priority of a baseline one still outranks it.
    """
    if not doc_graph.get("available") or not doc_staleness.get("available"):
        return []
    staleness_by_path = {d["path"]: d for d in doc_staleness.get("docs", [])}
    hubs: list[dict] = []
    for hub in doc_graph.get("hubs", []):
        s = staleness_by_path.get(hub["path"])
        if s is None:
            continue
        priority = round(hub["pagerank"] * s["ratio"], 3)
        confidence = s.get("confidence", "high")
        hubs.append({
            "path": hub["path"],
            "pagerank": hub["pagerank"],
            "last_commit_days": s["last_commit_days"],
            "code_churn_in_window": s["code_churn_in_window"],
            "ratio": s["ratio"],
            "subject_method": s.get("subject_method"),
            "confidence": confidence,
            "priority": priority,
        })
    return sorted(
        hubs,
        key=lambda h: -(h["priority"] * (0.5 if h["confidence"] == "low" else 1.0)),
    )


def resolve_scope(
    repo_root: Path, scope: Path | None
) -> tuple[Path | None, str | None, str]:
    """Resolve a ``--scope`` argument into (absolute path, repo-relative, slug).

    A whole-repo run (``scope`` is None) returns ``(None, None, "")`` so the
    caller keeps ``repo_root/.assess`` and every output is byte-identical to a
    pre-scope run. A scoped run validates the path exists and is under
    ``repo_root``; the slug replaces path separators with hyphens so artifacts
    land under ``.assess/<slug>/``. Raises ``ValueError`` on a missing or
    outside-repo path so the CLI can report it cleanly (a non-zero exit).
    """
    if scope is None:
        return None, None, ""
    scope_abs = (scope if scope.is_absolute() else repo_root / scope).resolve()
    if not scope_abs.exists():
        raise ValueError(f"scope path does not exist: {scope_abs}")
    if not scope_abs.is_relative_to(repo_root):
        raise ValueError(f"scope path is not under repo root {repo_root}: {scope_abs}")
    rel = scope_abs.relative_to(repo_root)
    slug = str(rel).replace("/", "-").replace("\\", "-")
    return scope_abs, str(rel), slug


def build_run_context(
    *, repo_root: Path, run_date: str, non_interactive: bool = False,
    scope: Path | None = None,
) -> dict:
    """Run the deterministic pipeline and return the structured context dict.

    ``non_interactive`` is the orchestrator's explicit headless/CI signal; it
    (together with the ``CI`` / ``ASSESS_NON_INTERACTIVE`` env vars) decides the
    ``interactive`` flag and the pre-recorded ``offers``. It is never inferred
    from ``sys.stdin.isatty()`` - the core always runs as a subprocess with no
    controlling terminal, so an interactive /assess would misread as headless.

    ``scope`` restricts the assessment to a subtree (``/assess <path>`` monorepo
    scoping): artifacts land under ``.assess/<slug>/`` and the file-enumerating
    scans (complexity stats read from the scoped sidecar, doc graph, doc
    staleness) see only the subtree, so the score/badge/wiki carry no signal
    from a sibling directory. None (the default) is a whole-repo run, unchanged.

    Side effects: writes index.md, log.md, hotspots/*.md, run-context.json.
    """
    scope_abs, scope_rel, scope_slug = resolve_scope(repo_root, scope)
    assess_dir = repo_root / ".assess" / scope_slug if scope_slug else repo_root / ".assess"
    assess_dir.mkdir(parents=True, exist_ok=True)
    # Unique id minted once at the top of the run and stamped on every artifact
    # this build produces, so finalize can prove the finalize-input it later
    # consumes was authored against *this* run-context and not a stale one.
    run_id = _new_run_id()
    current = load_stats(assess_dir / "complexity-stats.json") or {
        "files_scored": 0, "top_hotspots": [], "top_complex": [], "top_large": [],
        "loc": {}, "ccn": {},
    }
    prior = load_stats(assess_dir / "complexity-stats.prior.json")
    prior_exists = prior is not None

    # A diff is only trustworthy when both snapshots came from a comparable
    # toolchain. Three things can void it, in descending severity, all schema-
    # and version-aware (not a blunt exact-string equality):
    #   1. the plugin's stats schema or MAJOR version changed - the sidecar shape
    #      or the deterministic core moved (major also resets the trend);
    #   2. a complexity backend (lizard/scc) version changed - scores can shift
    #      with no change in the tree, so the note names the tool;
    #   3. the prior snapshot never stamped a version - comparability can't be
    #      established, so "graduated" entries may be phantom filter transitions.
    # A mere MINOR/PATCH plugin bump keeps the diff reliable and the gate armed.
    prior_version = prior.get("plugin_version") if prior else None
    current_schema = current.get("schema_version")
    prior_schema = prior.get("schema_version") if prior else None
    current_tools = _stats_tool_versions(current)
    prior_tools = _stats_tool_versions(prior)
    diff_reliable, diff_version_note, diff_trend_reset = _compute_diff_reliability(
        prior_exists, prior, current,
    )

    diff = diff_stats(prior=prior, current=current)
    # A hotspot that left the ranking because this run excluded it as generated
    # did not graduate: the filter changed, not the file. Drop it from the
    # graduated list so the append-only log and index never record it as one.
    # Content excludes are named in excluded_generated; the generated-name
    # globs are silent, so they are matched here directly.
    generated_paths = {r["path"] for r in _excluded_generated(current)}
    diff.graduated = [
        h for h in diff.graduated
        if h.path not in generated_paths and not matches_generated_name(h.path)
    ]
    instruction_files, instructions_grade, untracked_instr, dangling_instr, skills_info, \
        sensitive_instr = _grade_instruction_files(repo_root)

    # Historical path -> current path, from git's rename detection. Built once:
    # it re-keys the first-flagged map here and folds co-change history onto
    # current paths in the keyhole integrate below.
    rename_map = build_rename_map(repo_root)

    # Load (and later update) the persistent first-flagged date map, with any
    # entry for a renamed file moved to its current path.
    first_flagged_map = _rekey_first_flagged(
        _load_first_flagged(assess_dir), rename_map.paths)

    # User-supplied excludes (`.assess/config.toml`), loaded once and threaded
    # into every read-side scan (heatmap parity, doc graph, staleness, liveness,
    # markers) so "this is reference data, not source" is a single statement.
    extra_exclude_dirs, extra_exclude_patterns = load_excludes(repo_root)

    # Excluded after an unfinalized run (#356): a file first flagged only by the
    # never-finalized run this one supersedes, and now excluded by config, was
    # never part of a finished assessment. Its page is retired, its first-flagged
    # entry dropped, and it is kept out of "graduated" so the rotated prior stats
    # do not carry it into index.md. Files first flagged by a finalized run are
    # outside the rule, as are files still in the current top hotspots.
    measured_commit = git_commit_info(repo_root)
    superseded = _same_measurement_prior_run(
        assess_dir, run_date=run_date, measured_commit=measured_commit,
    )
    provisional, excluded_unfinalized = _excluded_after_unfinalized_run(
        assess_dir, superseded=superseded, first_flagged_map=first_flagged_map,
        current=current, diff=diff,
        excludes=(extra_exclude_dirs, extra_exclude_patterns),
    )

    # Promissory markers (stale TODO/FIXME, suppressions, disabled tests),
    # scanned before the wiki pages so each hotspot page can carry its own
    # marker debt. summary() shape on success; _safe's degrade dict on failure
    # (both carry `available`).
    promissory = _safe(
        "promissory_markers",
        lambda: scan_promissory_markers(
            repo_root,
            extra_exclude_dirs=extra_exclude_dirs,
            extra_exclude_patterns=extra_exclude_patterns,
            scope=scope_abs,
        ).summary(),
    )
    marker_debt_by_file = (
        promissory.get("stale_by_file", {}) if promissory.get("available") else {}
    )

    # Accretion ratchet (files whose line count only ever grows): the first of
    # the three write-side tendencies. scan_accretion_ratchet never raises - it
    # degrades to available=False internally - and returns an AccretionScan
    # dataclass (not a dict), so it is called directly rather than through _safe
    # (whose degrade path yields a dict). The block is serialized below, after
    # the complexity band is known, so growth is reported only for files already
    # in the top complexity/size band.
    accretion_scan = scan_accretion_ratchet(repo_root)
    # O(1) per-file lookup for the hotspot pages, built from the same scan the
    # run-context block serializes (no re-scan). Empty when the scan was
    # unavailable - graceful degradation: those files just get no growth line.
    accretion_by_file = _accretion_lookup(accretion_scan)

    # Build status map: which paths are graduated, new, regressed, persistent
    status_map: dict[str, str] = {}
    for h in diff.graduated:
        status_map[h.path] = "graduated"
    for h in diff.new:
        status_map[h.path] = "new"
    for h in diff.regressed:
        status_map[h.path] = "regressed"
    for h in diff.persistent:
        status_map[h.path] = "persistent"

    # Wiki: hotspot pages for current top hotspots
    hotspot_entries: list[HotspotEntry] = []
    # Same flat-tree disambiguation the test_focus block applies to these files.
    hot_shared_names = shared_name_keys(
        h["path"] for h in current.get("top_hotspots", []))
    # One repository index for every hot file's parallel-tree (basename) probe.
    hot_test_index = build_test_index(repo_root) if current.get("top_hotspots") else None
    for h in current.get("top_hotspots", []):
        path = h["path"]
        # Preserve the original first_flagged date across runs. A path missing
        # from the map is either genuinely new this run (stamp today) or it was
        # present in the prior snapshot but we have no recorded date - e.g. the
        # prior stats were seeded without first-flagged.json. In the latter case
        # it predates this run, so an honest "unknown" beats a wrong today.
        if path not in first_flagged_map:
            first_flagged_map[path] = (
                run_date if status_map.get(path) == "new" else "unknown"
            )
        first_flagged = first_flagged_map[path]
        status = status_map.get(path, "active")
        commits = hotspot_commits(h)
        loc = h.get("loc", 0)
        ccn = h.get("ccn", 0)
        hotspot_entries.append(HotspotEntry(
            path=path,
            first_flagged=first_flagged,
            last_seen=run_date,
            status=status,
            ccn=ccn,
            loc=loc,
        ))
        write_hotspot_page(
            assess_dir,
            path=path,
            first_flagged=first_flagged,
            last_seen=run_date,
            status=status,
            loc=loc,
            ccn=ccn,
            commits=commits,
            has_tests=_has_sibling_test(repo_root, path, hot_shared_names,
                                        hot_test_index),
            history_rows=f"| {run_date} | {loc} | {ccn} | {commits} | {status} |",
            briefing=(
                f"Hotspot ({status}). "
                f"{loc} LOC, "
                f"max cyclomatic complexity {ccn}, "
                f"{commits} commits in churn window. "
                + _marker_debt_sentence(marker_debt_by_file.get(path))
                + "(Briefing refined by LLM via assess_finalize - see Suggested actions below.)"
            ),
            actions=UNFINALIZED_ACTIONS_POINTER,
            accretion_data=accretion_by_file.get(path),
            run_id=run_id,
            schema_version=ARTIFACT_SCHEMA_VERSION,
        )

    # Prune orphan hotspot pages: any page from a prior run whose source file no
    # longer exists on disk is stamped retired (history preserved) so no active
    # page keeps describing a deleted file. Runs after the current top hotspots
    # are (re)written, so a file that is still a live hotspot has just had its
    # page refreshed and won't be touched.
    pruned_hotspots = prune_orphan_hotspots(assess_dir, repo_root)
    retired_excluded, dropped_first_flagged = _retire_excluded_unfinalized(
        assess_dir, excluded_unfinalized, first_flagged_map,
    )

    # Also surface graduated hotspots in the index. Carry the file's actual
    # current metrics across the three top-N lists in `current` - graduating
    # off `top_hotspots[:10]` means the file fell out of the composite
    # ranking, NOT that its LOC or CCN dropped to zero. A graduated file
    # almost always still appears in `top_complex` (top 10 by raw CCN) or
    # `top_large` (top 10 by raw LOC) since those are wider views, so we
    # can recover real numbers in the common case. Merge metrics per-path
    # because top_complex entries carry only `ccn` and top_large entries
    # carry only `loc` - only top_hotspots carries both. When a metric
    # genuinely isn't present in any list, leave it as None - the wiki
    # renders None as "-" rather than misleading zeros (issue #52 Bug 1).
    current_locs: dict[str, int] = {}
    current_ccns: dict[str, int] = {}
    for src_key in ("top_hotspots", "top_complex", "top_large"):
        for entry in current.get(src_key, []):
            path = entry.get("path")
            if not path:
                continue
            loc = entry.get("loc")
            ccn = entry.get("ccn")
            if loc is not None and path not in current_locs:
                current_locs[path] = int(loc)
            if ccn is not None and path not in current_ccns:
                current_ccns[path] = int(ccn)

    for h in diff.graduated:
        hotspot_entries.append(HotspotEntry(
            path=h.path,
            # Graduated means it was a prior hotspot; if we have no recorded
            # first-flagged date, it predates this run - "unknown", not today.
            first_flagged=first_flagged_map.get(h.path, "unknown"),
            last_seen=run_date,
            status="graduated",
            ccn=current_ccns.get(h.path),
            loc=current_locs.get(h.path),
        ))

    # Persist the updated first-flagged map for future runs
    _save_first_flagged(assess_dir, first_flagged_map)

    write_index(
        assess_dir, hotspot_entries, last_updated=run_date,
        run_id=run_id, schema_version=ARTIFACT_SCHEMA_VERSION,
        scope=scope_rel,
    )

    top_action = "Deterministic ranker not yet wired (LLM picks Top 3)"
    log_entry = LogEntry(
        run_date=run_date,
        files_scored=current.get("files_scored", 0),
        readiness_score=0.0,  # LLM produces the layered score
        maturity_label="(LLM fills in)",
        instructions_grade=instructions_grade,
        graduated_count=len(diff.graduated),
        regressed_count=len(diff.regressed),
        new_count=len(diff.new),
        persistent_count=len(diff.persistent),
        top_action=top_action,
        plugin_version=_read_plugin_version(),
        run_id=run_id,
        schema_version=ARTIFACT_SCHEMA_VERSION,
    )
    _drop_superseded_log_entry(assess_dir, superseded)
    append_log_entry(assess_dir, log_entry)

    # log.md integrity: verify the chained checksums after the append. A break
    # (an earlier entry edited after the fact) is disclosed in log.md itself and
    # surfaced here so the report/gate can render it - a lying history is exactly
    # the self-description-under-no-pressure failure the toolkit guards against.
    log_valid, log_broken_at = verify_log_chain(assess_dir)

    # Heterogeneous run-context bus: values are dicts, lists, scalars, or the
    # degrade-gracefully bool/str/None fallbacks. Typed as dict[str, Any] so the
    # block accessors below (ctx["dead_code"] etc.) stay assignable to the
    # signal functions that consume them.
    ctx: dict[str, Any] = {
        # Run provenance: the unique id every artifact of this run carries, and
        # the artifact schema version a consumer checks before reading. finalize
        # refuses to reconcile a finalize-input whose run_id disagrees (a torn
        # write). `artifact_schema_version` is distinct from the stats-layout
        # `schema_version` set further below (from #244).
        "run_id": run_id,
        "artifact_schema_version": ARTIFACT_SCHEMA_VERSION,
        "run_date": run_date,
        # Monorepo scope (`/assess <path>`): the repo-relative subtree this run
        # covers, and its artifact-directory slug (.assess/<slug>/). Both null /
        # "" for a whole-repo run, so a consumer that ignores them sees the
        # pre-scope shape. The report, badge, and wiki label the run with these.
        "scope": scope_rel,
        "scope_slug": scope_slug or None,
        # The commit the scan measured. Absolute LOC/CCN figures are a snapshot
        # of this commit; the report pins the SHA and warns when HEAD is dirty
        # or behind its upstream so the numbers aren't read as current (#59).
        "measured_commit": measured_commit,
        "prior_stats_exists": prior_exists,
        "stats_summary": {
            "files_scored": current.get("files_scored", 0),
            "loc": current.get("loc", {}),
            # Estimated tokens (the keyhole size unit) + the budget rollup: repo
            # total and how many files / top-level subtrees exceed one
            # context-window keyhole. The most on-thesis snapshot signal - the
            # literal "does the relevant slice fit?" measure. Empty {} on a
            # pre-token stats snapshot (back-compat).
            "est_tokens": current.get("est_tokens", {}),
            "ccn": current.get("ccn", {}),
            "top_hotspots": current.get("top_hotspots", []),
        },
        "instruction_files": instruction_files,
        "instructions_grade": instructions_grade,
        "diff": diff.summary(),
        "diff_reliable": diff_reliable,
        "diff_version_note": diff_version_note,
        # True only when a 

"""Emit the frozen-harness CI workflow for /assess (the third end-of-run offer).

Thin CLI over ``lib.ci_workflow.emit_ci_workflow``. The orchestrator (SKILL.md
Step 6.5) runs this after the user accepts the "freeze this into a repeatable
check?" offer. It writes ``.github/workflows/assess-gate.yml`` into the target
repo, pinning a published toolkit release and baking in the toolchain it found.

Defaults are derived so the common case is a single argument:
- ``--version`` defaults to the running plugin's version (``plugin.json`` beside
  this script), never the target's ``.assess/run-context.json``, which can be
  months old. The pin is checked upstream: ``git ls-remote --tags`` lists the
  published tags and ``gh api .../contents/action.yml?ref=<tag>`` confirms the
  tag ships the action. ``gh`` checks the running tag first; only when it is
  absent or ships no ``action.yml`` are the tags listed and the newest published
  tag that does is pinned instead, with the choice printed. With neither ``gh`` nor ``git`` reaching GitHub, the running
  version is emitted with an "unverified" warning. An explicit ``--version`` is
  emitted as given, unchecked. When the running version is unknown or known
  unpublished and no published tag qualifies, nothing is written and the exit
  code is 1.
- ``--branch`` defaults to the repo's detected default branch (``main`` if it
  can't be detected).
- ``--tools`` defaults to auto-detecting ``scc`` on PATH plus ``lizard`` (the
  always-present complexity backend); pass a comma list to override.
- ``--paths <glob>`` / ``--paths-ignore <glob>`` (each repeatable, order kept)
  become ``paths:`` / ``paths-ignore:`` under ``on.pull_request``. GitHub rejects
  both on one event, so passing both is a usage error. With neither, when an
  existing workflow under ``.github/workflows/`` filters pull requests by path (a
  ``paths:`` or ``paths-ignore:`` key on a ``pull_request`` trigger, or
  ``dorny/paths-filter``), the gate gets
  ``paths-ignore: ['**/*.md', '.assess/**']`` and a line saying so is printed.

Run:
    uv run assess_emit_workflow.py <repo_root> [--version V] [--branch B] [--tools a,b]
        [--paths GLOB ... | --paths-ignore GLOB ...]
"""
# /// script
# requires-python = ">=3.11"
# ///
from __future__ import annotations

import json
import re
import shutil
import subprocess
import sys
from pathlib import Path

from lib.ci_workflow import DEFAULT_PATHS_IGNORE, emit_ci_workflow, find_path_filtered_workflow


_REPO = "bjcoombs/ai-native-toolkit"
_REMOTE = f"https://github.com/{_REPO}.git"
# action.yml first shipped in v1.42.0; no earlier tag can back a ``uses:`` line.
_FIRST_ACTION_RELEASE = (1, 42, 0)
# Upper bound on per-tag action.yml lookups while walking down the tag list.
_MAX_TAG_PROBES = 10
_SEMVER_TAG = re.compile(r"^v(\d+)\.(\d+)\.(\d+)$")


def _running_version() -> str | None:
    """The running plugin's version from ``.claude-plugin/plugin.json``.

    scripts/assess_emit_workflow.py -> scripts/ -> skills/assess/ -> skills/ -> repo root.
    Same lookup as ``assess_core._read_plugin_version``; not imported from there
    because that module pulls the whole analysis stack and its dependencies.
    """
    plugin_json = Path(__file__).resolve().parents[3] / ".claude-plugin" / "plugin.json"
    try:
        version = json.loads(plugin_json.read_text(encoding="utf-8")).get("version")
    except (OSError, json.JSONDecodeError):
        return None
    return str(version) if version else None


def _run(cmd: list[str]) -> tuple[int, str, str]:
    """Run ``cmd``; ``(returncode, stdout, stderr)``, with 127 when it can't start.

    The only door to the network (tests stub it), via ``gh`` / ``git`` on PATH.
    """
    try:
        out = subprocess.run(cmd, capture_output=True, text=True, timeout=20, check=False)
    except (OSError, subprocess.SubprocessError) as exc:
        return 127, "", str(exc)
    return out.returncode, out.stdout, out.stderr


def _semver(tag: str) -> tuple[int, int, int] | None:
    m = _SEMVER_TAG.match(tag)
    return (int(m[1]), int(m[2]), int(m[3])) if m else None


def _published_tags() -> list[str] | None:
    """Release tags (``vX.Y.Z``) on the upstream, newest first; None if unreachable."""
    rc, out, _ = _run(["git", "ls-remote", "--tags", "--refs", _REMOTE])
    if rc != 0:
        return None
    tags = [line.rsplit("refs/tags/", 1)[-1] for line in out.splitlines() if "refs/tags/" in line]
    return sorted((t for t in tags if _semver(t)), key=lambda t: _semver(t) or (0, 0, 0), reverse=True)


def _action_status(tag: str) -> str:
    """``ok`` if ``tag`` ships action.yml, ``absent`` on a definite HTTP 404,
    ``unknown`` when gh can't answer (missing, unauthenticated, offline)."""
    rc, out, err = _run(["gh", "api", f"repos/{_REPO}/contents/action.yml?ref={tag}"])
    if rc == 0:
        return "ok"
    return "absent" if "HTTP 404" in f"{out}\n{err}" else "unknown"


def _released_with_action(tag: str) -> bool:
    return (_semver(tag) or (0, 0, 0)) >= _FIRST_ACTION_RELEASE


def _unverified(version: str, why: str) -> tuple[str, str]:
    return version, (
        f"WARNING: pin v{version} is unverified - {why}. "
        "Check the tag exists and ships action.yml before committing the workflow."
    )


def _resolve_version(running: str | None) -> tuple[str | None, str]:
    """Pick the version to pin and a one-line note saying which and why.

    ``None`` means nothing safe can be pinned; the note says why."""
    status = _action_status(f"v{running}") if running else "absent"
    if running and status == "ok":
        return running, f"Pinned v{running}: the running version's tag ships action.yml."
    tags = _published_tags()
    if running and status == "unknown":
        if tags is None:
            return _unverified(running, "neither gh nor git ls-remote reached GitHub")
        if f"v{running}" in tags and _released_with_action(f"v{running}"):
            return running, f"Pinned v{running}: the tag is published (gh could not confirm action.yml)."
    why = f"v{running} is not published or ships no action.yml" if running else "the running version is unknown"
    for tag in [t for t in tags or [] if _released_with_action(t)][:_MAX_TAG_PROBES]:
        # gh unavailable before or during the walk: a release at or after the
        # first action.yml release stands in. Only a definite 404 rules a tag out.
        probe = status if status == "unknown" else _action_status(tag)
        if probe == "ok":
            return tag[1:], f"Pinned {tag}, the newest published tag that ships action.yml: {why}."
        if probe == "unknown":
            return tag[1:], f"Pinned {tag}, the newest published release after action.yml shipped (gh could not confirm it): {why}."
    # Every path here has a definite negative (gh's 404, or a tag list without
    # the running tag), so pinning the running version would write a dead ref.
    return None, (
        f"ERROR: no workflow written - {why}, and no published tag shipping action.yml was "
        "found. Pass --version <X.Y.Z> naming a published release."
    )


def _default_branch(repo_root: Path) -> str:
    """Best-effort detect the repo's default branch; fall back to 'main'."""
    try:
        out = subprocess.run(
            ["git", "-C", str(repo_root), "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
            capture_output=True, text=True, timeout=5, check=False,
        )
        ref = out.stdout.strip()
        if ref:
            return ref.rsplit("/", 1)[-1]
    except (OSError, subprocess.SubprocessError):
        pass
    return "main"


def _detect_tools() -> list[str]:
    """Discovered external tools we can install in CI; lizard is always present."""
    tools = ["lizard"]
    if shutil.which("scc"):
        tools.append("scc")
    return tools


def _opt(args: list[str], name: str) -> str | None:
    if name in args:
        idx = args.index(name)
        if idx + 1 < len(args):
            return args[idx + 1]
    return None


def _opt_all(args: list[str], name: str) -> list[str]:
    """Every value of a repeatable flag, in the order given."""
    return [args[i + 1] for i, arg in enumerate(args[:-1]) if arg == name]


def _path_filters(repo_root: Path, paths: list[str], paths_ignore: list[str]) -> tuple[list[str], list[str]]:
    """The explicit filters, or the docs-only default when the repo already filters by path."""
    if paths or paths_ignore:
        return paths, paths_ignore
    source = find_path_filtered_workflow(repo_root)
    if source is None:
        return [], []
    globs = ", ".join(DEFAULT_PATHS_IGNORE)
    print(
        f"Applied the default paths-ignore ({globs}): {source.relative_to(repo_root)} "
        "already filters pull requests by path, so docs-only and .assess/-only PRs skip "
        "the gate, and doc-truth findings (lying_map, orphaned_understanding) no longer "
        "gate them. A skipped PR reports no gate check at all, so a required status check "
        "on the gate would stay pending on it. Pass --paths or --paths-ignore to override.",
        file=sys.stderr,
    )
    return [], list(DEFAULT_PATHS_IGNORE)


_USAGE = (
    "Usage: assess_emit_workflow.py <repo_root> [--version V] [--branch B] [--tools a,b] "
    "[--paths GLOB ... | --paths-ignore GLOB ...]"
)


def main(argv: list[str] | None = None) -> int:
    args = list(sys.argv[1:] if argv is None else argv)
    flags = {"--version", "--branch", "--tools", "--paths", "--paths-ignore"}
    positional: list[str] = []
    i = 0
    while i < len(args):
        if args[i] in flags:
            if i + 1 >= len(args) or args[i + 1] in flags:
                print(f"{args[i]} needs a value.", file=sys.stderr)
                print(_USAGE, file=sys.stderr)
                return 2
            if args[i] in {"--paths", "--paths-ignore"} and not args[i + 1].strip():
                print(f"{args[i]} needs a non-empty value.", file=sys.stderr)
                print(_USAGE, file=sys.stderr)
                return 2
            i += 2
            continue
        if args[i].startswith("-"):
            print(f"Unknown option {args[i]}: pass a flag and its value as two arguments.", file=sys.stderr)
            print(_USAGE, file=sys.stderr)
            return 2
        positional.append(args[i])
        i += 1
    if len(positional) != 1:
        if len(positional) > 1:
            print(
                f"Unexpected arguments {positional[1:]}: quote globs so the shell does not expand them.",
                file=sys.stderr,
            )
        print(_USAGE, file=sys.stderr)
        return 2
    paths, paths_ignore = _opt_all(args, "--paths"), _opt_all(args, "--paths-ignore")
    if paths and paths_ignore:
        print("GitHub rejects --paths and --paths-ignore on the same event; pass one.", file=sys.stderr)
        print(_USAGE, file=sys.stderr)
        return 2
    repo_root = Path(positional[0]).resolve()
    version = _opt(args, "--version")
    if version is None:
        version, note = _resolve_version(_running_version())
        print(note, file=sys.stderr)
        if version is None:
            return 1
    branch = _opt(args, "--branch") or _default_branch(repo_root)
    tools_arg = _opt(args, "--tools")
    tools = (
        [t.strip() for t in tools_arg.split(",") if t.strip()]
        if tools_arg is not None
        else _detect_tools()
    )
    paths, paths_ignore = _path_filters(repo_root, paths, paths_ignore)
    path = emit_ci_workflow(
        repo_root, tools, version, default_branch=branch, paths=paths, paths_ignore=paths_ignore,
    )
    print(str(path))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

"""LLM write-back for /assess: fill placeholders left by the deterministic core.

The deterministic core writes log.md and hotspots/*.md with placeholders for
LLM-derived content (score, maturity label, top action, per-hotspot actions).
After the LLM writes assess-report.md, it also writes finalize-input.json with
its derived values and invokes this script to update the wiki files in place.

Reads (in order; first hit wins):
    {repo_root}/.assess/.cache/finalize-input.json  (preferred - transient cache)
    {repo_root}/.assess/finalize-input.json         (legacy - written to working tree)

The input file is **consumed and deleted** on success. It carries no future
utility past the run that produced it, and leaving it in the working tree
caused noisy diffs when users committed `.assess/` (issue #39).

Updates:
    {repo_root}/.assess/log.md           (this run's entry, by assess:run_id,
                                          then the chain re-computed)
    {repo_root}/.assess/hotspots/*.md    (Suggested actions sections)

Writes (when the input carries an ``actions`` array):
    {repo_root}/.assess/actions.json     (durable machine-readable Top 3
                                          action contract for executor agents;
                                          v2 - carries per-action status/mode and
                                          preserves done state across re-runs)

Run:
    uv run assess_finalize.py <repo_root>
    uv run assess_finalize.py <repo_root> --drop-entry <run_id>
        (replaces a never-finalized log entry that blocks finalize with a
        one-line tombstone and re-chains the log; finalized entries are refused)
"""
# /// script
# requires-python = ">=3.11"
# ///
from __future__ import annotations

import json
import re
import sys
from pathlib import Path


# Make sibling lib package importable when run as a script
sys.path.insert(0, str(Path(__file__).resolve().parent))

from lib.badge import maturity_band
from lib.evidence_check import check_evidence, describe
from lib.keyhole_signals import mode_for_finding
from lib.wiki_writer import (
    find_log_entry,
    log_entry_date,
    log_entry_is_unfinalized,
    log_entry_owns_span,
    log_entry_run_id,
    read_log_entries,
    rewrite_log_entry,
    slug_for_path,
)


class FinalizeValidationError(Exception):
    """Raised when finalize-input.json violates a run-context invariant.

    finalize is fail-closed: on any violation it raises *before writing
    anything*, so a torn, mismatched, or fabricated input can never reach the
    wiki, the badge, or the actions contract. ``main()`` catches it and exits
    non-zero with the specific violation named.

    The invariants this guards (see ``_validate_finalize_input``) are the
    contract that lets a downstream reader trust the finalised wiki: the score
    fits its denominator, the maturity label matches the score band, every
    hotspot action names a real hotspot, the input came from *this* run (run_id),
    Layer 6 never claims proof (Present) the run never gathered (no mutation),
    and no layer verdict rests only on evidence that fails its re-check.
    """


# Canonical maturity tier keywords, used to pull the tier the LLM claimed out of
# a free-text ``maturity_label`` (which may be decorated, e.g.
# "Knowledge Base · Solid (3 applicable layers)"). No pair is a substring of
# another, so a single containment test per keyword is unambiguous.
_MATURITY_KEYWORDS = ("AI-Native", "Not Ready", "Solid", "Basic")

# The annotation the LLM must attach to Layer 6 when mutation testing never ran.
# Mirrors ``assess_core.MUTATION_NOT_RUN_ANNOTATION`` (the two scripts share no
# import, so the literal is duplicated); the finalize error names it so a caller
# knows the required remediation.
MUTATION_NOT_RUN_ANNOTATION = "truth-pressure unproven (mutation not run)"


def _log_target(assess_dir: Path, run_id: str | None) -> int | None:
    """Index of the log entry finalize fills, or None when there is none.

    The entry stamped with this run's ``assess:run_id`` wins. A legacy log
    (no entry carries a run id stamp) or a context with no run id falls back to
    the last entry still carrying placeholders, the pre-#355 behaviour. In a
    stamped log a missing entry refuses: falling back there would write this
    run's score into another run's entry and re-sign it.
    """
    entries = read_log_entries(assess_dir)
    if run_id:
        idx = find_log_entry(assess_dir, run_id)
        if idx is not None:
            return idx
        if any(log_entry_run_id(e) for e in entries):
            raise FinalizeValidationError(
                f"log.md has no entry stamped run_id={run_id}; refusing to fill "
                "another run's entry. Re-run the core to write this run's entry."
            )
    for i in range(len(entries) - 1, -1, -1):
        if log_entry_is_unfinalized(entries[i]):
            return i
    return None


def _validate_no_earlier_same_date_placeholders(assess_dir: Path, target: int | None) -> None:
    """Refuse when an earlier entry for the target's date is still unfinalized.

    Two unfinalized entries on one date mean a run was superseded without its
    entry being replaced (a different commit, or a stale run-context): filling
    only the later one would leave a same-day placeholder entry that reads as a
    finished run. The error names the earlier entry so the operator can find it.
    """
    if target is None:
        return
    entries = read_log_entries(assess_dir)
    day = log_entry_date(entries[target])
    if day is None:
        return
    for content in entries[:target]:
        stale_id = log_entry_run_id(content)
        # An entry written before run-id stamps existed cannot be addressed by
        # --drop-entry, so refusing on it would block finalize for good; such an
        # entry keeps the pre-#355 treatment (left in place as history).
        if stale_id is None:
            continue
        if log_entry_date(content) == day and log_entry_is_unfinalized(content):
            heading = next(
                (ln for ln in content.splitlines() if ln.startswith("## ")), "?"
            )
            raise FinalizeValidationError(
                f"log.md entry run_id={stale_id} ({heading}) for {day} still "
                "carries unfilled placeholders; an earlier same-date run was "
                "never finalized. Its run-context is gone, so drop it with: "
                f"assess_finalize.py <repo_root> --drop-entry {stale_id}, then "
                "re-run finalize. Deleting it by hand breaks the log chain."
            )


def _finalize_log(
    assess_dir: Path,
    *,
    target: int | None,
    score: float,
    maturity_label: str,
    top_action: str,
    denominator: int = 8,
) -> None:
    """Fill the placeholders of log entry ``target`` and re-chain the log.

    Only that entry is updated; other entries are immutable historical records.
    The rewrite recomputes the chain marker of the filled entry and every later
    one, so ``verify_log_chain`` stays valid after finalize (#355).
    ``denominator`` is 8 for a software repo and the applicable-layer count for
    a knowledge base (#224), so the finalised line reads ``2.5 / 3`` rather
    than ``2.5 / 8``.
    """
    if target is None:
        return
    text = read_log_entries(assess_dir)[target]
    # The placeholder the core writes is always "/ 8"; the finalised
    # denominator may differ for a knowledge base, so the replacement carries it.
    text = _replace_last(
        text,
        pattern=r"\*\*AI Readiness:\*\* [\d.]+ / 8 \(\(LLM fills in\)\)",
        replacement=f"**AI Readiness:** {score} / {denominator} ({maturity_label})",
    )
    text = _replace_last(
        text,
        pattern=r"\*\*Top action:\*\* Deterministic ranker not yet wired \(LLM picks Top 3\)",
        replacement=f"**Top action:** {top_action}",
    )
    rewrite_log_entry(assess_dir, target, text)


def _replace_last(text: str, *, pattern: str, replacement: str) -> str:
    """Replace the LAST occurrence of pattern in text with replacement (literal).

    Uses slicing rather than re.sub so the replacement is a literal string,
    not subject to backreference interpretation.
    """
    matches = list(re.finditer(pattern, text))
    if not matches:
        return text
    last = matches[-1]
    return text[:last.start()] + replacement + text[last.end():]


def _finalize_hotspot_actions(assess_dir: Path, *, hotspot_actions: dict[str, list[str]]) -> None:
    """Rewrite the 'Suggested actions' section of each hotspot page.

    Pages whose paths are absent from hotspot_actions are left as-is. Paths in
    hotspot_actions whose pages don't exist are silently skipped (lifecycle:
    a hotspot might have graduated between LLM read and finalize).
    """
    hotspots_dir = assess_dir / "hotspots"
    if not hotspots_dir.exists():
        return

    for path, actions in hotspot_actions.items():
        slug = slug_for_path(path)
        page_path = hotspots_dir / f"{slug}.md"
        if not page_path.exists():
            continue

        page_text = page_path.read_text(encoding="utf-8")
        actions_block = "\n".join(f"- {a}" for a in actions) if actions else "- (no actions)"
        # Replace the section content between "## Suggested actions" and end-of-file (or next ## heading)
        new_text = re.sub(
            r"(## Suggested actions\s*\n\s*\n).*?(\n##\s|$)",
            lambda m: m.group(1) + actions_block + "\n" + m.group(2),
            page_text,
            count=1,
            flags=re.DOTALL,
        )
        page_path.write_text(new_text, encoding="utf-8")


# Keys every action contract entry must carry. The executor-critical pair is
# done_when (the exit criterion - without it a weak model doesn't know when to
# stop) and scope_fence (what NOT to touch - without it a weak model
# over-extends). Entries missing required keys are dropped with a warning
# rather than failing the run: a partial contract beats none, but a malformed
# entry must not reach an executor as if it were complete.
ACTION_REQUIRED_KEYS = {"rank", "action", "done_when", "scope_fence"}

# actions.json schema version. v2 adds executor-lifecycle fields (status /
# claimed_by / completed_sha) plus a deterministic execution ``mode`` per action
# and a top-level ``run_id`` stamp. v1 (schema:1, no lifecycle fields) is still
# read for status carry-forward - see _read_prior_action_status.
ACTIONS_SCHEMA_VERSION = 2

# The executor lifecycle. A fresh action is ``pending``; an executor ``claimed``
# it; ``done`` records the ``completed_sha`` that satisfied ``done_when``;
# ``reopened`` means a later run re-flagged work a prior run marked done.
ACTION_STATUS_VALUES = frozenset({"pending", "claimed", "done", "reopened"})

# Lifecycle fields carried forward from a prior actions.json so a done action
# stays done (with its completed_sha and claimant) across re-runs. Everything
# else - rank, mode, done_when, scope_fence - is recomputed each run from the
# freshest findings.
_ACTION_CARRY_FIELDS = ("status", "claimed_by", "completed_sha")


def _read_prior_action_status(assess_dir: Path) -> dict[str, dict]:
    """Prior actions keyed by their ``action`` text, for status carry-forward.

    The action directive is the stable identity across runs: rank reshuffles as
    findings re-prioritise, but "investigate the src/foo.go seam" is the same
    piece of work whether it ranks 1 or 3 this time. Reads v1 and v2 contracts
    alike - a v1 entry simply carries no lifecycle fields, so a re-run over a v1
    actions.json initialises every action to pending (backward compatible). A
    missing or unreadable prior contract yields no carry-forward, not an error.
    """
    path = assess_dir / "actions.json"
    if not path.exists():
        return {}
    try:
        prior = json.loads(path.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError):
        return {}
    out: dict[str, dict] = {}
    for a in prior.get("actions", []) if isinstance(prior, dict) else []:
        if isinstance(a, dict) and isinstance(a.get("action"), str):
            out[a["action"]] = a
    return out


def _carry_status_fields(prior_entry: dict) -> dict:
    """The lifecycle fields to inherit from a matching prior action.

    An unrecognised prior status resets to ``pending`` (a corrupted or
    hand-edited contract must not smuggle an out-of-vocabulary status forward).
    A v1 prior entry has none of these fields, so the executor sees a fresh
    pending action with a null claimant and no completed_sha.
    """
    status = prior_entry.get("status")
    return {
        "status": status if status in ACTION_STATUS_VALUES else "pending",
        "claimed_by": prior_entry.get("claimed_by"),
        "completed_sha": prior_entry.get("completed_sha"),
    }


def _write_actions_contract(
    assess_dir: Path, actions: list[dict], *, run_id: str | None = None
) -> None:
    """Write the durable machine-readable Top 3 contract to actions.json (v2).

    Unlike finalize-input.json (consumed and deleted - transient by design),
    actions.json persists: it is the artifact an executing agent reads to know
    what to do, how to verify it, where to stop, and - v2 - whether the work is
    still open. Status/claimed_by/completed_sha are carried forward from any
    existing contract so a done action stays done across re-runs; ``mode`` is
    derived deterministically from each action's ``finding`` type.
    """
    prior = _read_prior_action_status(assess_dir)
    valid = []
    for a in actions:
        if not isinstance(a, dict) or not ACTION_REQUIRED_KEYS <= set(a):
            missing = ACTION_REQUIRED_KEYS - set(a) if isinstance(a, dict) else ACTION_REQUIRED_KEYS
            print(
                f"actions.json: dropping malformed entry (missing {sorted(missing)})",
                file=sys.stderr,
            )
            continue
        valid.append(a)
    if not valid:
        return
    entries = []
    for a in sorted(valid, key=lambda a: a["rank"]):
        # Keep whatever the LLM supplied (rank/action/done_when/scope_fence plus
        # any recommended files/first_step/layer/effort/finding), then stamp the
        # v2 lifecycle + derived mode over it so those fields are authoritative.
        entry = {
            **a,
            **_carry_status_fields(prior.get(a["action"], {})),
            "mode": mode_for_finding(a.get("finding")),
        }
        entries.append(entry)
    payload = {
        "schema": ACTIONS_SCHEMA_VERSION,
        "run_id": run_id,
        "actions": entries,
    }
    (assess_dir / "actions.json").write_text(
        json.dumps(payload, indent=2) + "\n", encoding="utf-8"
    )


def _locate_input(assess_dir: Path) -> Path:
    """Find finalize-input.json. Prefer the transient cache location; fall back
    to the legacy in-tree path for backwards compatibility.
    """
    cache_path = assess_dir / ".cache" / "finalize-input.json"
    if cache_path.exists():
        return cache_path
    legacy = assess_dir / "finalize-input.json"
    if legacy.exists():
        return legacy
    raise FileNotFoundError(
        f"finalize-input.json not found at {cache_path} or {legacy}"
    )


def _load_run_context(assess_dir: Path) -> dict:
    """Load run-context.json, the ground truth finalize reconciles against.

    Its absence is a hard failure, not a skip: finalize *reconciles* the
    LLM-authored input against the deterministic core's output, so with no
    run-context there is nothing to reconcile against and the invariants can't be
    enforced - the fail-closed choice is to refuse.
    """
    path = assess_dir / "run-context.json"
    if not path.exists():
        raise FinalizeValidationError(
            f"run-context.json missing at {path} - finalize cannot reconcile the "
            "LLM input against the deterministic core's output; refusing to write"
        )
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as e:
        raise FinalizeValidationError(
            f"run-context.json at {path} is not valid JSON: {e}"
        ) from e


def _claimed_maturity_tier(label: str) -> str | None:
    """The canonical maturity tier named inside a (possibly decorated) label.

    Returns None when no single recognised tier is present - a custom label with
    zero or ambiguously many keywords carries too little structure to reconcile,
    so that specific check is skipped rather than false-rejected.
    """
    low = label.lower()
    hits = [k for k in _MATURITY_KEYWORDS if k.lower() in low]
    return hits[0] if len(hits) == 1 else None


def _layer_score(data: dict, layer: int) -> float | None:
    """The LLM-supplied numeric score for one layer, or None if not carried.

    ``layer_scores`` maps a layer id to its 0.0/0.5/1.0 band (Missing/Partial/
    Present). JSON object keys are strings, but an int key is tolerated too. A
    legacy input with no ``layer_scores`` returns None so the layer-cap check is
    skipped rather than firing on absent data.
    """
    scores = data.get("layer_scores")
    if not isinstance(scores, dict):
        return None
    for key in (str(layer), layer):
        if key in scores:
            try:
                return float(scores[key])
            except (TypeError, ValueError):
                return None
    return None


def _validate_run_id_match(data: dict, ctx: dict) -> None:
    """Both artifacts must be from the same run (torn-write detection).

    Only enforced when *both* carry a run_id: a legacy artifact missing the
    stamp still finalises (backward compat). A disagreement means the
    finalize-input was authored against a different run-context than the one on
    disk - a torn write finalize must refuse.
    """
    in_id = data.get("run_id")
    ctx_id = ctx.get("run_id")
    if in_id and ctx_id and in_id != ctx_id:
        raise FinalizeValidationError(
            f"run_id mismatch (torn write): finalize-input run_id {in_id!r} != "
            f"run-context run_id {ctx_id!r}; refusing to reconcile artifacts from "
            "different runs"
        )


def _validate_denominator(denominator: int, ctx: dict) -> None:
    """The finalize-input denominator must match the archetype's.

    Skipped when the archetype scan degraded (no available block / no
    denominator) - honest-degrade beats false-rejecting a run whose archetype
    couldn't be determined.
    """
    archetype = ctx.get("archetype")
    if not isinstance(archetype, dict) or not archetype.get("available"):
        return
    ctx_denominator = archetype.get("denominator")
    if ctx_denominator is None:
        return
    if int(ctx_denominator) != denominator:
        raise FinalizeValidationError(
            f"denominator mismatch: finalize-input denominator {denominator} != "
            f"run-context archetype.denominator {ctx_denominator}"
        )


def _validate_score(score: float, denominator: int) -> None:
    """A layered score can never exceed its denominator (the display ceiling)."""
    if score > denominator:
        raise FinalizeValidationError(
            f"score {score} exceeds denominator {denominator}"
        )


def _validate_maturity(score: float, denominator: int, label: str) -> None:
    """The maturity label must name the tier the score actually earns.

    Bands come from ``lib.badge.maturity_band`` (the single source of truth,
    co-located with the badge colour ratios). A label that claims a different
    tier than the score/denominator fraction earns is rejected - the guardrail
    against a run that quietly overstates (or understates) its own readiness.
    """
    claimed = _claimed_maturity_tier(label)
    if claimed is None:
        return
    expected = maturity_band(score, denominator)
    if claimed != expected:
        ratio = (score / denominator) if denominator else 0.0
        raise FinalizeValidationError(
            f"maturity_label {label!r} claims tier {claimed!r} but score "
            f"{score}/{denominator} (ratio {ratio:.3f}) is tier {expected!r}"
        )


def _validate_hotspot_actions(data: dict, ctx: dict) -> None:
    """Every hotspot_actions key must be a real top hotspot from run-context.

    A path the LLM invented (not in ``stats_summary.top_hotspots``) is a
    fabricated map: the error names the offending path so the cause is obvious.
    """
    hotspot_actions = data.get("hotspot_actions", {})
    if not isinstance(hotspot_actions, dict):
        return
    stats_summary = ctx.get("stats_summary")
    top = stats_summary.get("top_hotspots", []) if isinstance(stats_summary, dict) else []
    known = {h.get("path") for h in top if isinstance(h, dict) and h.get("path")}
    for path in hotspot_actions:
        if path not in known:
            raise FinalizeValidationError(
                f"hotspot_actions references {path!r}, which is not a top hotspot "
                f"in run-context.json (stats_summary.top_hotspots). "
                f"Known hotspots: {sorted(known)}"
            )


def _validate_layer6_cap(data: dict, ctx: dict) -> None:
    """Layer 6 cannot exceed Partial when mutation testing never ran.

    ``mutation_not_run_cap.mutation_run`` (or, for a run-context that predates
    the block, ``test_pressure.mutation_run``) is True only when the bounded
    mutation pass actually executed. Without it, a Present verdict (score > 0.5)
    for Layer 6 is an unproven self-description - the guardrail-erosion failure
    /assess exists to catch - so finalize refuses it. A legacy input carrying no
    ``layer_scores`` is exempt (nothing to check).
    """
    cap = ctx.get("mutation_not_run_cap")
    if isinstance(cap, dict):
        mutation_ran = bool(cap.get("mutation_run", False))
    else:
        tp = ctx.get("test_pressure")
        mutation_ran = bool(isinstance(tp, dict) and tp.get("mutation_run", False))
    if mutation_ran:
        return
    layer6 = _layer_score(data, 6)
    if layer6 is None:
        return
    if layer6 > 0.5:
        raise FinalizeValidationError(
            "Layer 6 cannot exceed Partial when mutation testing was not run "
            f"(scored {layer6}). Annotation required: "
            f"'{MUTATION_NOT_RUN_ANNOTATION}'"
        )


def _evidence_layer(entry: object) -> int | None:
    """The layer an evidence entry cites, or None when it names no layer 0-8."""
    if not isinstance(entry, dict):
        return None
    layer = entry.get("layer")
    if isinstance(layer, bool) or not isinstance(layer, int) or not 0 <= layer <= 8:
        return None
    return layer


def _validate_evidence(data: dict, repo_root: Path) -> list[dict]:
    """Re-check the input's ``evidence`` list against the repository (#362).

    The scorer is a model, and the facts it cites ("docs/guide.md is absent",
    "no workflow calls scripts/check-x.sh") are checked again here with the
    deterministic ``lib.evidence_check``, each ``path`` resolved against
    ``repo_root`` (the parent of ``.assess/``). Grouped by ``layer``:

    - every entry of a layer rejected: the verdict rests on nothing true, so
      finalize refuses, naming each rejected entry by kind, path and needle;
    - some entries of a layer rejected (a mixed layer): the verdict still rests
      on a verified fact, so finalize proceeds, and the rejected entries are
      returned for the caller to print as warnings.

    An input with no ``evidence`` key is accepted unchecked, as an input with
    no ``layer_scores`` skips the Layer 6 cap. A malformed list (not a list, or
    an entry naming no layer 0-8) cannot be attributed to a verdict, so it
    fails closed. An entry that names its layer but is otherwise malformed
    (unknown kind, missing path or needle) is one the library rejects, so it
    counts as a rejected entry of that layer under the rule above.
    """
    if "evidence" not in data:
        return []
    entries = data["evidence"]
    if not isinstance(entries, list):
        raise FinalizeValidationError(
            "evidence must be a list of entries "
            f"({{layer, kind, path[, needle]}}), got {type(entries).__name__}"
        )
    for entry in entries:
        if not isinstance(entry, dict):
            raise FinalizeValidationError(f"evidence entry {entry!r} is not an object")
        if _evidence_layer(entry) is None:
            raise FinalizeValidationError(
                f"evidence entry {describe(entry)} names no layer 0-8 "
                f"(layer={entry.get('layer')!r})"
            )
    result = check_evidence(repo_root, entries)
    verified_layers = {_evidence_layer(e) for e in result["evidence"]}
    unsupported = [e for e in result["evidence_rejected"] if e["layer"] not in verified_layers]
    if unsupported:
        named = "; ".join(
            f"layer {e['layer']}: {describe(e)} ({e['reason']})" for e in unsupported
        )
        raise FinalizeValidationError(
            f"a layer verdict rests only on rejected evidence: {named}. "
            "Correct the verdict or its evidence, then re-run finalize."
        )
    return result["evidence_rejected"]


def _validate_finalize_input(
    data: dict, ctx: dict, *, denominator: int, repo_root: Path
) -> list[dict]:
    """Run every finalize invariant. Raises FinalizeValidationError on the first
    violation, before any write - so a bad input reaches nothing.

    Returns the rejected evidence entries of mixed layers, which do not block
    finalize but are reported as warnings.
    """
    _validate_run_id_match(data, ctx)
    _validate_denominator(denominator, ctx)
    _validate_score(float(data["score"]), denominator)
    _validate_maturity(float(data["score"]), denominator, data["maturity_label"])
    _validate_hotspot_actions(data, ctx)
    _validate_layer6_cap(data, ctx)
    return _validate_evidence(data, repo_root)


def finalize_run(*, assess_dir: Path) -> None:
    """Read finalize-input.json, validate it against run-context.json, apply it
    to log.md and hotspot pages, then delete the input file.

    Fail-closed: run-context.json is read and every invariant checked *before*
    any write, including the re-check of any ``evidence`` list against the
    repository root (the parent of ``assess_dir``). Any violation raises
    ``FinalizeValidationError`` and nothing is written.
    """
    input_path = _locate_input(assess_dir)
    data = json.loads(input_path.read_text(encoding="utf-8"))
    ctx = _load_run_context(assess_dir)
    # Denominator: 8 for a software repo (the display ceiling), or the count of
    # applicable layers for a knowledge base (issue #224). Defaults to 8 so a
    # pre-archetype finalize-input.json finalises exactly as before.
    denominator = int(data.get("denominator", 8))
    tolerated = _validate_finalize_input(
        data, ctx, denominator=denominator, repo_root=assess_dir.parent
    )
    target = _log_target(assess_dir, ctx.get("run_id") or data.get("run_id"))
    _validate_no_earlier_same_date_placeholders(assess_dir, target)
    _finalize_log(
        assess_dir,
        target=target,
        score=data["score"],
        maturity_label=data["maturity_label"],
        top_action=data["top_action"],
        denominator=denominator,
    )
    _finalize_hotspot_actions(assess_dir, hotspot_actions=data.get("hotspot_actions", {}))
    actions = data.get("actions")
    if isinstance(actions, list) and actions:
        _write_actions_contract(assess_dir, actions, run_id=ctx.get("run_id"))
    for e in tolerated:
        print(
            f"finalize: warning: layer {e['layer']} evidence rejected, verdict kept on "
            f"its verified entries: {describe(e)} ({e['reason']})",
            file=sys.stderr,
        )
    # The shipped badge stays deterministic: assess_core wrote the findings-count
    # badge.json (linking to this report). Finalize deliberately does NOT
    # overwrite it with the LLM-derived score - that grade appears inside
    # assess-report.md instead, so the badge never claims a number a
    # deterministic run cannot reproduce.
    # Clean up: the input file is consumed - delete from both the cache and
    # the legacy in-tree location so a stale copy can't leak into a commit.
    try:
        input_path.unlink()
    except OSError:
        pass
    legacy = assess_dir / "finalize-input.json"
    if legacy != input_path and legacy.exists():
        try:
            legacy.unlink()
        except OSError:
            pass


def drop_unfinalized_entry(*, assess_dir: Path, run_id: str) -> None:
    """Replace the never-finalized log entry stamped ``run_id`` with a tombstone.

    The supported way out of the earlier-same-date refusal: the entry's own
    run-context has been overwritten, so it can never be finalized, and deleting
    it by hand breaks the chain for every later entry. The entry becomes a
    one-line chained note (no heading, no stamp, no placeholders) so the log
    still records that the run existed; the chain is recomputed from there. A
    finalized entry is history and is refused.
    """
    idx = find_log_entry(assess_dir, run_id)
    if idx is None:
        raise FinalizeValidationError(f"log.md has no entry stamped run_id={run_id}")
    content = read_log_entries(assess_dir)[idx]
    if not log_entry_owns_span(content, run_id):
        raise FinalizeValidationError(
            f"log.md entry run_id={run_id} shares its span with log history written "
            "before the integrity chain existed; dropping it would drop that history "
            "too. Leave it in place."
        )
    if not log_entry_is_unfinalized(content):
        raise FinalizeValidationError(
            f"log.md entry run_id={run_id} is finalized; finalized entries are history "
            "and are not removed"
        )
    day = log_entry_date(content) or "unknown date"
    tombstone = (
        f"> Dropped run {run_id} ({day}): never finalized, its run-context was "
        "superseded; removed with assess_finalize.py --drop-entry.\n\n---\n"
    )
    rewrite_log_entry(assess_dir, idx, tombstone)


def main() -> int:
    args = sys.argv[1:]
    usage = "Usage: assess_finalize.py <repo_root> [--drop-entry <run_id>]"
    if len(args) not in (1, 3) or (len(args) == 3 and args[1] != "--drop-entry"):
        print(usage, file=sys.stderr)
        return 2
    repo_root = Path(args[0]).resolve()
    assess_dir = repo_root / ".assess"
    try:
        if len(args) == 3:
            drop_unfinalized_entry(assess_dir=assess_dir, run_id=args[2])
        else:
            finalize_run(assess_dir=assess_dir)
    except FinalizeValidationError as e:
        # Fail-closed: a violated invariant means finalize wrote nothing. Name
        # the specific violation and exit non-zero so the run surfaces it.
        print(f"finalize refused: {e}", file=sys.stderr)
        return 1
    return 0


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

"""CI gate for /assess - the enforcement half of the frozen harness.

Reads ``.assess/run-context.json`` (written by ``assess_core.py``) and the
``[gate]`` section of ``.assess/config.toml``, then decides whether the current
snapshot should fail a pull request. Two kinds of check, both strictly opt-in:

- **Readiness floors** (absolute, evaluated on the current snapshot): a finding
  in ``fail_on`` is present, p95 complexity exceeds ``ccn_p95_max``, or the
  safe-zone containment ratio drops below ``containment_min``.
- **Regression** (cross-run): with ``fail_on_regression = true``, fail when the
  diff ``assess_core`` computed against the prior committed snapshot reports
  hotspots whose complexity/churn increased. This needs a prior snapshot and a
  reliable diff; on a first run or an unreliable diff it is skipped, never
  fired - a freshly-cloned repo never trips a regression gate on its first PR.

The defaults are warn-only: with no config, every finding is reported but
nothing fails, so adopting the emitted workflow never blocks a pipeline by
surprise.

Exit codes:
    0  pass (nothing failing, the gate is disabled / warn-only, OR an
       infrastructure failure - missing/corrupt run-context - was skipped: an
       infra failure is never a red check on an unrelated PR)
    1  fail (a floor was breached, or an opted-in regression fired)
    2  usage error (no repo_root argument)

Run:
    uv run assess_gate.py <repo_root> [--config <path>]
"""
# /// script
# requires-python = ">=3.11"
# ///
from __future__ import annotations

import json
import sys
from pathlib import Path
from typing import Any

# scripts/ is on sys.path (pyproject pythonpath); lib is a package under it.
from lib.assess_config import load_gate_config, load_gate_config_file


def _findings_by_name(ctx: dict) -> dict[str, dict]:
    """Index ``derived_findings`` by finding name for O(1) lookup."""
    return {
        f["name"]: f
        for f in ctx.get("derived_findings", [])
        if isinstance(f, dict) and "name" in f
    }


def check_finding_regressions(
    ctx: dict, gate: dict
) -> tuple[list[dict], list[dict]]:
    """Split flagged findings into (failures, warnings) per the gate config.

    A finding "fires" when it has a non-empty ``paths`` list - that is the
    deterministic core's own signal that the concern is present in this repo.
    ``fail_on`` takes precedence over ``warn_on`` so a finding named in both is
    only ever counted once, as a failure.
    """
    findings = _findings_by_name(ctx)
    fail_on = gate.get("fail_on", [])
    failures: list[dict] = []
    warnings: list[dict] = []

    def _fired(name: str) -> dict | None:
        f = findings.get(name)
        if f and f.get("paths"):
            return {"finding": name, "count": len(f["paths"]), "paths": f["paths"][:5]}
        return None

    for name in fail_on:
        hit = _fired(name)
        if hit is not None:
            failures.append(hit)
    for name in gate.get("warn_on", []):
        if name in fail_on:
            continue
        hit = _fired(name)
        if hit is not None:
            warnings.append(hit)
    return failures, warnings


def check_complexity_threshold(ctx: dict, gate: dict) -> list[dict]:
    """Return a one-element list when p95 file CCN exceeds ``ccn_p95_max``."""
    threshold = gate.get("ccn_p95_max")
    if threshold is None:
        return []
    current = ctx.get("stats_summary", {}).get("ccn", {}).get("p95")
    if isinstance(current, (int, float)) and current > threshold:
        return [{"metric": "ccn_p95", "value": current, "threshold": threshold}]
    return []


def _containment_ratio(ctx: dict) -> float | None:
    """Safe zones / (safe zones + total concerns) from the keyhole summary.

    The deterministic core already rolls the findings into a keyhole summary
    with a safe-zone count and a total-concern count. The ratio is the share of
    examined units that are clean refactor boundaries; ``None`` when there is
    nothing to score (no units flagged either way).
    """
    summary = ctx.get("keyhole_summary") or {}
    safe = summary.get("safe_zones")
    concerns = summary.get("total_concerns")
    if not isinstance(safe, int) or not isinstance(concerns, int):
        return None
    denom = safe + concerns
    if denom <= 0:
        return None
    return safe / denom


def check_containment_threshold(ctx: dict, gate: dict) -> list[dict]:
    """Return a one-element list when the containment ratio drops below the floor."""
    floor = gate.get("containment_min")
    if floor is None:
        return []
    ratio = _containment_ratio(ctx)
    if ratio is not None and ratio < floor:
        return [{"metric": "containment", "value": round(ratio, 3), "threshold": floor}]
    return []


def check_diff_regression(ctx: dict, gate: dict) -> list[dict]:
    """Return a regression breach when the cross-run diff reports a worsening.

    Only fires when ``fail_on_regression`` is set AND there is a reliable diff
    against a prior committed snapshot. ``assess_core`` already computed the diff
    (graduated / new / regressed) into the run-context; "regressed" is its term
    for hotspots whose complexity or churn increased since the prior run. On a
    first run (no prior) or an unreliable diff (version-mismatched filter), it
    returns nothing - a freshly-adopted repo can't trip a regression gate.
    """
    if not gate.get("fail_on_regression"):
        return []
    if not ctx.get("prior_stats_exists") or not ctx.get("diff_reliable", True):
        return []
    regressed = ctx.get("diff_detail", {}).get("regressed", [])
    if not regressed:
        return []
    return [{
        "metric": "regressed_hotspots",
        "count": len(regressed),
        "paths": [r.get("path", "?") for r in regressed[:5]],
    }]


def evaluate(ctx: dict, gate: dict) -> dict:
    """Run every check and return a structured verdict.

    ``failed`` is the gate decision; ``warnings`` are reported but never fail.
    A disabled gate collects the same diagnostics (so the log is honest) but
    always reports ``failed = False``.
    """
    failures, warnings = check_finding_regressions(ctx, gate)
    threshold_breaches = (
        check_complexity_threshold(ctx, gate)
        + check_containment_threshold(ctx, gate)
        + check_diff_regression(ctx, gate)
    )
    blocking = bool(failures or threshold_breaches)
    return {
        "enabled": gate.get("enabled", True),
        "failed": blocking and gate.get("enabled", True),
        "failures": failures,
        "warnings": warnings,
        "threshold_breaches": threshold_breaches,
        # Carried through so the verdict log can disclose findings the config
        # excludes suppressed - the gate must never read clean when a real
        # finding was filtered out by an exclude.
        "excluded_by_config": ctx.get("excluded_by_config"),
        # Files the treemap dropped as generated, so the log names the reasons.
        "excluded_generated": ctx.get("excluded_generated"),
    }


def format_verdict(verdict: dict) -> str:
    """Render a human-readable summary for the CI log."""
    lines: list[str] = ["/assess gate"]
    if not verdict["enabled"]:
        lines.append("  gate disabled in config - reporting only, never failing")
    for breach in verdict["threshold_breaches"]:
        if breach["metric"] == "regressed_hotspots":
            sample = ", ".join(breach["paths"])
            lines.append(
                f"  FAIL regression: {breach['count']} hotspot(s) worsened since "
                f"the prior snapshot ({sample})"
            )
        else:
            lines.append(
                f"  FAIL threshold: {breach['metric']} = {breach['value']} "
                f"(max/min {breach['threshold']})"
            )
    for f in verdict["failures"]:
        sample = ", ".join(f["paths"])
        lines.append(f"  FAIL finding: {f['finding']} x{f['count']} ({sample})")
    for w in verdict["warnings"]:
        sample = ", ".join(w["paths"])
        lines.append(f"  warn finding: {w['finding']} x{w['count']} ({sample})")
    if not verdict["failures"] and not verdict["threshold_breaches"] and not verdict["warnings"]:
        lines.append("  no findings fired - clean snapshot")
    disclosure = _format_exclusion_disclosure(verdict.get("excluded_by_config"))
    if disclosure:
        lines.append(disclosure)
    generated = _format_generated_disclosure(verdict.get("excluded_generated"))
    if generated:
        lines.append(generated)
    lines.append("  RESULT: " + ("FAIL" if verdict["failed"] else "PASS"))
    return "\n".join(lines)


def _format_exclusion_disclosure(excluded_by_config: dict | None) -> str:
    """One indented line disclosing findings the config excludes suppressed.

    Returns ``""`` when nothing was suppressed, so a clean run's log is
    unchanged. When a path that would have been a finding was filtered out by a
    config exclude, the suppression is stated with the excluding dirs/patterns so
    a reader never mistakes a filtered PASS for a genuinely clean one.
    """
    block = excluded_by_config or {}
    count = block.get("count", 0)
    if not isinstance(count, int) or count <= 0:
        return ""
    dirs = ", ".join(block.get("dirs", [])) or "none"
    patterns = ", ".join(block.get("patterns", [])) or "none"
    noun = "finding" if count == 1 else "findings"
    return (
        f"  {count} {noun} suppressed by config excludes "
        f"(dirs: {dirs}; patterns: {patterns})"
    )


# Per-file lines the gate log lists before summarising the rest as "+N more".
GENERATED_DISCLOSURE_MAX_PATHS = 10


def _format_generated_disclosure(excluded_generated: list | None) -> str:
    """A summary line naming each distinct reason files were excluded as
    generated, then one indented ``path (reason)`` line per file (capped at
    ``GENERATED_DISCLOSURE_MAX_PATHS``), or ``""`` when none were, so a clean
    run's log is unchanged."""
    rows = [
        r for r in (excluded_generated or [])
        if isinstance(r, dict) and r.get("path") and r.get("reason")
    ]
    if not rows:
        return ""
    reasons = sorted({r["reason"] for r in rows})
    noun = "file" if len(rows) == 1 else "files"
    lines = [
        f"  {len(rows)} {noun} excluded from scoring as generated "
        f"(reasons: {', '.join(reasons)})"
    ]
    shown = rows[:GENERATED_DISCLOSURE_MAX_PATHS]
    lines.extend(f"    {r['path']} ({r['reason']})" for r in shown)
    if len(rows) > len(shown):
        lines.append(f"    +{len(rows) - len(shown)} more")
    return "\n".join(lines)


def load_context(repo_root: Path) -> dict[str, Any]:
    """Load ``.assess/run-context.json`` from a repo root."""
    ctx_path = repo_root / ".assess" / "run-context.json"
    return json.loads(ctx_path.read_text(encoding="utf-8"))


def main(argv: list[str] | None = None) -> int:
    args = list(sys.argv[1:] if argv is None else argv)
    # --config points the gate at a config file outside the conventional
    # .assess/config.toml. Consume both the flag and its value so the value
    # isn't mistaken for the positional repo root.
    config_path: str | None = None
    positional: list[str] = []
    i = 0
    while i < len(args):
        arg = args[i]
        if arg == "--config":
            if i + 1 < len(args):
                config_path = args[i + 1]
            i += 2
            continue
        if arg.startswith("-"):
            i += 1
            continue
        positional.append(arg)
        i += 1
    if not positional:
        print("Usage: assess_gate.py <repo_root> [--config <path>]", file=sys.stderr)
        return 2
    repo_root = Path(positional[0]).resolve()
    try:
        ctx = load_context(repo_root)
    except (OSError, json.JSONDecodeError) as e:
        # The run-context is missing or corrupt because the deterministic core
        # failed to produce it - an infrastructure failure, not an AI-readiness
        # finding. Skip with a clear notice and exit 0 so a broken render never
        # fails a PR that has nothing to do with the breakage. The gate runs
        # again on the next push, when the core has a clean run-context.
        print(
            f"/assess gate skipped: infrastructure failure "
            f"({type(e).__name__}: {e}).\n"
            "This is an infra issue, not a finding. The gate will run on the "
            "next push.",
            file=sys.stderr,
        )
        return 0
    gate = (
        load_gate_config_file(Path(config_path))
        if config_path is not None
        else load_gate_config(repo_root)
    )
    verdict = evaluate(ctx, gate)
    print(format_verdict(verdict))
    return 1 if verdict["failed"] else 0


if __name__ == "__main__":
    raise SystemExit(main())

"""Deterministic report renderer for /assess.

Reads ``.assess/run-context.json`` and renders a Markdown report from a stdlib
``string.Template``. This is the *frozen harness*: it runs with zero model
tokens and produces the same report for the same context, on every PR forever.

It renders:
- a metrics dashboard (complexity profile, churn window, total LOC),
- the top-hotspots table,
- the keyhole-readiness summary + the six cross-layer findings, and
- the regression deltas (graduated / new / regressed / persistent).

It deliberately does NOT reproduce (these require LLM judgement and are written
elsewhere by the orchestrator, see SKILL.md):
- the 0-8 layered readiness score,
- the per-layer present/partial/missing prose, or
- the Top 3 Actions priority narrative.

The findings section, the keyhole summary, and the prescribed actions are
already serialised into ``run-context.json`` by the deterministic core
(``assess_core.build_run_context`` -> ``keyhole_signals``). This renderer
*consumes* those products verbatim; it does not re-derive them.

Run:
    uv run assess_report.py <repo_root>            # writes .assess/deterministic-report.md
    uv run assess_report.py <repo_root> --stdout   # prints the report to stdout
"""
# /// script
# requires-python = ">=3.11"
# ///
from __future__ import annotations

import json
import sys
from pathlib import Path
from string import Template
from typing import Any

# Caps on rows rendered so a pathological repo can't bloat the frozen report.
# The structured arrays in run-context.json keep the full lists.
MAX_HOTSPOT_ROWS = 10
MAX_DIFF_ROWS = 10

# Diff categories rendered in order, with the gloss shown beside each count.
DIFF_CATEGORIES = [
    ("graduated", "Graduated", "left the hotspot list"),
    ("new", "New", "entered the hotspot list"),
    ("regressed", "Regressed", "complexity or churn increased"),
    ("persistent", "Persistent", "still in the hotspot list"),
]

# Caps on listed empty-ownership patterns so a pathologically broken ownership
# map can't bloat the frozen report. The full list stays in run-context.json.
MAX_EMPTY_PATTERNS_RENDERED = 20

# Tier 1 grouping-disagreement metrics, in render order. Each row is the
# run-context key stem (the ``_count`` suffix is added at read time), a
# human label, and the one-line interpretation - the disagreement (or
# agreement) the metric measures between the declared boundary, the static
# import graph, and the co-change history. The objective count is rendered
# first, the interpretation second (SKILL.md deterministic-findings rule).
TIER1_METRICS = [
    ("human_grouped_static_splits",
     "declared together, import graph splits them",
     "a boundary the dependency structure no longer backs"),
    ("human_split_static_fuses",
     "import graph fuses them, no declared boundary does",
     "cohesion the ownership map misses"),
    ("human_grouped_never_cochange",
     "declared together, commit log never couples them",
     "a boundary history does not exercise as a unit"),
    ("human_split_but_cochange",
     "keep co-changing, no declared boundary groups them",
     "a hidden seam the map omits (folded into hidden_coupling above)"),
    ("human_static_agree",
     "declared and dependency lenses agree",
     "boundary backed by the import graph"),
    ("human_cochange_agree",
     "declared and historical lenses agree",
     "boundary exercised as a unit by history"),
]

REPORT_TEMPLATE = Template("""# Deterministic Assessment Snapshot: $repo_name

_Generated $run_date by `/assess` v$plugin_version.${commit_note}_

## Metrics Dashboard

- **Files scored:** $files_scored
- **Total LOC:** $loc_total
- **Complexity profile:** p95 LOC $loc_p95 (max $loc_max$loc_split), p95 CCN $ccn_p95 (max $ccn_max)
- **Churn window:** $churn_window

### Top Hotspots

$hotspots_table

## Keyhole Readiness

$keyhole_summary

$findings_section
$structure_drift_section
## Changes Since Last Run

$diff_section

---

_Deterministic portion of the assessment: metrics, hotspots, and cross-layer findings. The 0-8 layer scores, the per-layer prose, and the Top 3 Actions priority narrative require LLM judgement and are written separately._
""")


def _fmt(value: Any) -> str:
    """Format a metric for display: ints as ints, whole floats without a
    trailing ``.0``, fractional floats to one decimal, ``None`` as ``?``."""
    if value is None:
        return "?"
    if isinstance(value, bool):
        return str(value)
    if isinstance(value, float):
        return str(int(value)) if value.is_integer() else f"{value:.1f}"
    return str(value)


def render_hotspots_table(ctx: dict) -> str:
    """Render the top hotspots as a Markdown table (capped at MAX_HOTSPOT_ROWS)."""
    hotspots = ctx.get("stats_summary", {}).get("top_hotspots", [])
    if not hotspots:
        return "_No hotspots identified._"
    lines = ["| Path | LOC | CCN | Commits |", "|------|-----|-----|---------|"]
    for h in hotspots[:MAX_HOTSPOT_ROWS]:
        lines.append(
            f"| `{h.get('path', '?')}` | {_fmt(h.get('loc'))} | "
            f"{_fmt(h.get('ccn'))} | {_fmt(h.get('commits'))} |"
        )
    return "\n".join(lines)


def render_keyhole_summary(ctx: dict) -> str:
    """Return the pre-built keyhole-readiness summary line (consumed verbatim)."""
    summary = ctx.get("keyhole_summary") or {}
    text = summary.get("summary_text")
    return text if text else "_Keyhole readiness summary unavailable._"


def render_exclusion_disclosure(ctx: dict) -> str:
    """Lines disclosing config-excluded findings and archive paths, or ``""``.

    Config excludes silently drop paths from every scan; when at least one path
    that would have been a finding is filtered out, this makes the suppression
    visible - a reader must never mistake a filtered report for a clean one.
    Returns ``""`` when nothing was suppressed, so a clean run's report is byte
    identical to before this disclosure existed. A second line names the paths
    kept out of the attention list because they sit under an ``archive/``,
    ``archived/`` or ``attic/`` directory (``excluded_as_archive``), and a
    third the git-history paths pruned because they no longer exist
    (``pruned_finding_paths``), and a last one says when ``attention_low_signal``
    cut the prescribed actions to rank 1.
    """
    lines: list[str] = []
    block = ctx.get("excluded_by_config") or {}
    count = block.get("count", 0)
    if isinstance(count, int) and count > 0:
        dirs = ", ".join(block.get("dirs", [])) or "none"
        patterns = ", ".join(block.get("patterns", [])) or "none"
        noun = "finding" if count == 1 else "findings"
        lines.append(
            f"_{count} {noun} suppressed by config excludes "
            f"(dirs: {dirs}; patterns: {patterns})._"
        )
    archived = ctx.get("excluded_as_archive") or {}
    a_count = archived.get("count", 0)
    if isinstance(a_count, int) and a_count > 0:
        # Name at most five, as assess_gate does; the full list stays in
        # run-context.json.
        named = list(archived.get("affected_finding_paths", []))
        paths = ", ".join(named[:5])
        if len(named) > 5:
            paths += f" +{len(named) - 5} more"
        noun = "path" if a_count == 1 else "paths"
        lines.append(
            f"_{a_count} archived {noun} left out of the attention list: {paths}._"
        )
    pruned = ctx.get("pruned_finding_paths") or {}
    p_count = pruned.get("count", 0)
    if isinstance(p_count, int) and p_count > 0:
        named = list(pruned.get("paths", []))
        paths = ", ".join(named[:5])
        if len(named) > 5:
            paths += f" +{len(named) - 5} more"
        verbs = "path no longer exists and was" if p_count == 1 else (
            "paths no longer exist and were")
        lines.append(
            f"_{p_count} git-history {verbs} left out of the findings: {paths}._"
        )
    if pruned.get("rename_map_complete") is False:
        lines.append(
            "_Renames could not be read from git history: findings may name "
            "pre-rename paths, and none were pruned._"
        )
    if ctx.get("attention_low_signal") is True:
        lines.append(
            "_Attention ranking is low signal (no attention row lands in more than one "
            "finding): only rank 1 is prescribed._"
        )
    return "\n\n".join(lines)


# Generated-file rows shown on the report surface before the rest are folded.
GENERATED_DISCLOSURE_VISIBLE = 10


def render_generated_disclosure(ctx: dict) -> str:
    """Name each file the treemap excluded as generated, with its reason.

    One line per file (``- `path` (reason)``) under a count line, or ``""`` when
    ``excluded_generated`` is empty or absent, so a run with nothing excluded
    renders exactly as before. The first ``GENERATED_DISCLOSURE_VISIBLE`` rows
    sit on the report surface; the rest go in a ``<details>`` fold, so every
    path stays named without hundreds of bullets displacing the findings.
    """
    rows = [
        r for r in (ctx.get("excluded_generated") or [])
        if isinstance(r, dict) and r.get("path") and r.get("reason")
    ]
    if not rows:
        return ""
    noun = "file" if len(rows) == 1 else "files"
    lines = [f"_{len(rows)} {noun} excluded from scoring as generated:_", ""]
    visible = rows[:GENERATED_DISCLOSURE_VISIBLE]
    rest = rows[GENERATED_DISCLOSURE_VISIBLE:]
    lines.extend(f"- `{r['path']}` ({r['reason']})" for r in visible)
    if rest:
        lines += ["", f"<details><summary>{len(rest)} more</summary>", ""]
        lines.extend(f"- `{r['path']}` ({r['reason']})" for r in rest)
        lines += ["", "</details>"]
    return "\n".join(lines)


def render_findings_section(ctx: dict) -> str:
    """Return the pre-rendered cross-layer findings section, verbatim.

    The deterministic core already renders the six findings + attention list
    into ``findings_markdown``; this renderer copies it so the section appears
    whether or not an LLM is in the loop.
    """
    markdown = ctx.get("findings_markdown")
    if not markdown or not markdown.strip():
        return "_No cross-layer findings recorded._"
    return markdown.strip()


def _render_tier0_drift(tier_0: dict) -> list[str]:
    """Tier 0 ownership-map drift: declared globs matching zero tracked files.

    Each empty pattern is a slice of the tree the ownership map *claims* to
    cover but no file satisfies, so any edit there silently skips the declared
    owner's review. Lists the pattern, where it was declared, and the owners it
    would have routed to. Returns ``[]`` (caller omits the section) when Tier 0
    is unavailable or no pattern is empty - absence reads as "nothing stale",
    never a broken half-section.
    """
    if not tier_0.get("available"):
        return []
    patterns = tier_0.get("empty_ownership_patterns") or []
    if not patterns:
        return []
    ordered = sorted(
        patterns,
        key=lambda p: (p.get("pattern", ""), p.get("declared_in", "")),
    )
    lines = [
        "### Tier 0 - Ownership Map Drift",
        "",
        (f"{len(patterns)} declared ownership pattern"
         f"{'' if len(patterns) == 1 else 's'} match zero tracked files. "
         "Stale ownership silently drops review coverage: an edit under one of "
         "these patterns routes to no declared owner."),
        "",
    ]
    for p in ordered[:MAX_EMPTY_PATTERNS_RENDERED]:
        owners = p.get("owners") or []
        owners_text = ", ".join(owners) if owners else "_no owners declared_"
        lines.append(
            f"- `{p.get('pattern', '?')}` "
            f"(declared in {p.get('declared_in', '?')}; owners: {owners_text})"
        )
    overflow = len(ordered) - MAX_EMPTY_PATTERNS_RENDERED
    if overflow > 0:
        lines.append(f"- ...and {overflow} more")
    lines.append("")
    return lines


def _render_tier1_disagreement(tier_1: dict, repo_name: str) -> list[str]:
    """Tier 1 grouping disagreement: six set-algebra counts over the declared,
    static-import, and co-change groupings, plus the seam-allowlist note.

    The objective counts lead; the interpretation follows each (SKILL.md
    deterministic-findings rule). The hidden-seam direction
    (``human_split_but_cochange``) already folds into the ``hidden_coupling``
    finding above, so this block surfaces the explicit magnitudes and the
    allowlist transparency line rather than re-rendering that finding. Returns
    ``[]`` (caller omits) when the static lens was unavailable.
    """
    if not tier_1.get("available"):
        return []
    lines = [
        "### Tier 1 - Grouping Disagreement",
        "",
        ("Set-algebra over three groupings - the declared boundary, the static "
         "import graph, and the co-change history - counting the file pairs each "
         "lens pair agrees or disagrees on:"),
        "",
    ]
    for key, label, interpretation in TIER1_METRICS:
        count = tier_1.get(f"{key}_count", 0)
        lines.append(f"- **{count}** `{key}` - {label}: {interpretation}")
    lines.append("")
    if tier_1.get("seam_allowlist_applied"):
        n = tier_1.get("allowlist_pairs_count", 0)
        note = (
            f"Seam allowlist applied: {n} owned seam pair"
            f"{'' if n == 1 else 's'} excluded from the disagreement counts "
            "before they were reported."
        )
        if _is_self_assessment(repo_name):
            note += " See `lib/README.md` for the owned seams."
        lines.append(note)
        lines.append("")
    return lines


def _is_self_assessment(repo_name: str) -> bool:
    """True when /assess is assessing its own repo - the only case where the
    ``lib/README.md`` owned-seams footnote points at a file that exists."""
    return repo_name == "ai-native-toolkit"


def format_structure_drift_findings(
    structure_drift: dict | None, repo_name: str = "",
) -> str:
    """Render the run-context ``structure_drift`` block as a Markdown section.

    Two tiers, each independently omitted when it has nothing to say:
    - **Tier 0** lists declared ownership patterns matching no tracked file.
    - **Tier 1** surfaces the six grouping-disagreement counts and the
      seam-allowlist transparency line.

    Counts lead, interpretation follows; the harness never auto-prescribes
    regenerating the ownership map - that is a human decision, stated here only
    so the human can make it. Returns ``""`` (caller omits the heading) when the
    block is absent or both tiers are empty - graceful degrade, no broken
    markdown.
    """
    if not structure_drift:
        return ""
    body: list[str] = []
    body += _render_tier0_drift(structure_drift.get("tier_0") or {})
    body += _render_tier1_disagreement(
        structure_drift.get("tier_1") or {}, repo_name,
    )
    if not body:
        return ""
    return "## Structure Drift\n\n" + "\n".join(body).rstrip() + "\n"


def _format_transition(category: str, entry: dict) -> str:
    """Render one hotspot transition as a bullet, with deltas for regressions."""
    path = entry.get("path", "?")
    if category != "regressed":
        return f"  - `{path}`"
    bits = []
    ccn_delta = entry.get("ccn_delta", 0)
    loc_delta = entry.get("loc_delta", 0)
    if ccn_delta:
        bits.append(f"CCN {ccn_delta:+d}")
    if loc_delta:
        bits.append(f"LOC {loc_delta:+d}")
    suffix = f" ({', '.join(bits)})" if bits else ""
    return f"  - `{path}`{suffix}"


def render_diff_section(ctx: dict) -> str:
    """Render the regression deltas, honouring the first-run and reliability flags.

    No prior snapshot -> say so. An unreliable diff (plugin-version mismatch in
    the file filter) is suppressed with its note rather than shown, mirroring the
    SKILL.md rule that phantom transitions must not read as real improvement.
    """
    if not ctx.get("prior_stats_exists"):
        return "_No prior run to compare against - this is the first recorded snapshot._"
    if not ctx.get("diff_reliable", True):
        note = ctx.get("diff_version_note") or "prior and current snapshots are not comparable"
        if ctx.get("diff_trend_reset"):
            # A MAJOR version bump broke comparability: state the reset explicitly
            # so a suppressed diff isn't misread as a clean, unchanged run.
            return (
                f"_Trend baseline reset: {note}. Prior hotspot history is not "
                "comparable across a major version; the trend restarts from this "
                "snapshot._"
            )
        return f"_Diff suppressed: {note}._"

    summary = ctx.get("diff", {})
    detail = ctx.get("diff_detail", {})
    lines: list[str] = []
    for key, label, gloss in DIFF_CATEGORIES:
        entries = detail.get(key, [])
        count = summary.get(key, len(entries))
        lines.append(f"- **{label}** ({gloss}): {count}")
        for entry in entries[:MAX_DIFF_ROWS]:
            lines.append(_format_transition(key, entry))
        overflow = len(entries) - MAX_DIFF_ROWS
        if overflow > 0:
            lines.append(f"  - ...and {overflow} more")
    return "\n".join(lines)


def _render_commit_note(ctx: dict) -> str:
    """Render the measured-commit provenance suffix for the generated-by line.

    Pins the SHA the absolute LOC/CCN numbers were measured at and warns when
    HEAD is dirty or behind upstream, so the figures aren't read as current
    when they describe an uncommitted or stale tree. Returns a leading-space
    string (it follows ``v<version>.``) or ``""`` when provenance is unknown.
    """
    commit = ctx.get("measured_commit") or {}
    if not commit.get("available"):
        return ""
    short = commit.get("head_short") or str(commit.get("head_sha", ""))[:7]
    note = f" Measured at `{short}`"
    subject = commit.get("subject")
    if subject:
        note += f' ("{subject}")'
    warnings = []
    if commit.get("dirty"):
        warnings.append("working tree dirty")
    behind = commit.get("behind")
    if isinstance(behind, int) and behind > 0:
        warnings.append(f"{behind} commit(s) behind upstream")
    if warnings:
        note += f" - {', '.join(warnings)}"
    return note + "."


def _render_churn_window(ctx: dict) -> str:
    """Surface the churn-window label the treemap/doc-staleness pass settled on.

    When the history is degenerate (every file ~1 commit - a snapshot with no
    usable history), the label carries a caveat so the churn axis, the saturation
    treemap channel, and any churn-derived finding are read as inactive rather
    than as a live signal (issue #172).
    """
    doc_staleness = ctx.get("doc_staleness") or {}
    window = doc_staleness.get("churn_window")
    label = window if window else "unavailable"
    if ctx.get("churn_degenerate"):
        return f"{label} - snapshot / no usable history, churn signal flat"
    return label


def _render_loc_split(loc: dict) -> str:
    """The code and data LOC maxima (scc language split in the stats file), as
    ``; code N, data M`` after the overall max, so a large JSON fixture is not
    read as the largest source file. Empty on a snapshot written before the
    split, which leaves the line in its older shape."""
    if "max_code" not in loc or "max_data" not in loc:
        return ""
    return f"; code {_fmt(loc['max_code'])}, data {_fmt(loc['max_data'])}"


def render_report(ctx: dict, repo_name: str) -> str:
    """Render the full deterministic Markdown report from a run-context dict.

    Pure: takes the loaded context and the repo name, returns the report string.
    ``Template.substitute`` is strict - a missing key raises, which surfaces a
    template/data drift at the seam rather than silently emitting ``$placeholder``.
    """
    stats = ctx.get("stats_summary", {})
    loc = stats.get("loc", {})
    ccn = stats.get("ccn", {})
    # The keyhole summary line, with two disclosures appended when they apply:
    # findings suppressed by config excludes, and files excluded from scoring as
    # generated (each empty otherwise, so a clean run renders exactly as before).
    keyhole_summary = render_keyhole_summary(ctx)
    disclosure = render_exclusion_disclosure(ctx)
    if disclosure:
        keyhole_summary = f"{keyhole_summary}\n\n{disclosure}"
    generated = render_generated_disclosure(ctx)
    if generated:
        keyhole_summary = f"{keyhole_summary}\n\n{generated}"
    report = REPORT_TEMPLATE.substitute(
        repo_name=repo_name,
        run_date=ctx.get("run_date", "unknown"),
        plugin_version=ctx.get("plugin_version", "unknown"),
        commit_note=_render_commit_note(ctx),
        files_scored=stats.get("files_scored", 0),
        loc_total=_fmt(loc.get("total")),
        loc_p95=_fmt(loc.get("p95")),
        loc_max=_fmt(loc.get("max")),
        loc_split=_render_loc_split(loc),
        ccn_p95=_fmt(ccn.get("p95")),
        ccn_max=_fmt(ccn.get("max")),
        churn_window=_render_churn_window(ctx),
        hotspots_table=render_hotspots_table(ctx),
        keyhole_summary=keyhole_summary,
        findings_section=render_findings_section(ctx),
        structure_drift_section=_structure_drift_section(ctx, repo_name),
        diff_section=render_diff_section(ctx),
    )
    return report.rstrip() + "\n"


def _structure_drift_section(ctx: dict, repo_name: str) -> str:
    """Template-ready structure-drift block: the rendered section followed by a
    blank line, or ``""`` when there's nothing to render (the surrounding blank
    line in the template then collapses on the final ``rstrip``)."""
    section = format_structure_drift_findings(ctx.get("structure_drift"), repo_name)
    return f"\n{section.rstrip()}\n" if section else ""


def load_context(repo_root: Path) -> dict:
    """Load ``.assess/run-context.json`` from a repo root."""
    ctx_path = repo_root / ".assess" / "run-context.json"
    return json.loads(ctx_path.read_text(encoding="utf-8"))


def main(argv: list[str] | None = None) -> int:
    args = list(sys.argv[1:] if argv is None else argv)
    to_stdout = "--stdout" in args
    positional = [a for a in args if not a.startswith("-")]
    if not positional:
        print("Usage: assess_report.py <repo_root> [--stdout]", file=sys.stderr)
        return 2
    repo_root = Path(positional[0]).resolve()
    try:
        ctx = load_context(repo_root)
    except (OSError, json.JSONDecodeError) as e:
        # Infrastructure failure (the core never wrote run-context.json, or it is
        # corrupt), not a finding. Emit a skip notice and succeed so a broken
        # snapshot never renders a red check on an unrelated PR - the assessment
        # runs again on the next push.
        print(
            f"/assess report skipped: infrastructure failure "
            f"({type(e).__name__}: {e}).\n"
            "This is an infra issue, not a finding. The report will render on "
            "the next push.",
            file=sys.stderr,
        )
        return 0
    report = render_report(ctx, repo_root.name)
    if to_stdout:
        sys.stdout.write(report)
    else:
        out_path = repo_root / ".assess" / "deterministic-report.md"
        out_path.write_text(report, encoding="utf-8")
        print(str(out_path))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     # Pinned to an EXACT version. lizard produces the per-function cyclomatic
#     # complexity that drives the treemap hue and the regression baseline; a
#     # floating version could shift complexity-stats.json between runs and move
#     # the regression gate with no change in the assessed tree (the same risk
#     # ci_workflow.py pins scc against). The captured version is stamped into
#     # complexity-stats.json (`lizard_version`) so a diff can detect a change.
#     "lizard==1.23.0",
#     "squarify",
#     "matplotlib",
#     "numpy",
# ]
# ///
"""
complexity-treemap.py - Codecov-style hotspot treemap for any folder.

Each rectangle is one file, grouped by folder. The combined view encodes
three signals on one canvas (Adam Tornhill "hotspot" pattern, CodeScene-
style saturation):

  - Size        -> estimated tokens (~chars/4; the keyhole size unit. LOC is
                   kept in the hover tooltip). LOC undercounts dense/wide files
                   and overcounts sparse code; tokens track context burden.
  - Hue         -> cyclomatic complexity (dark red = complex, pale = simple;
                   colour-blind-safe OrRd ramp, no red-green)
  - Saturation  -> recent git churn (vivid = active, grey = stable)

Vivid red = complex AND actively changing = highest migration risk.
Faded grey = code that hasn't moved lately, regardless of complexity.

Scoring tiers (size + complexity):
  1. lizard    -> real per-function cyclomatic complexity (Java, Python, JS,
                  TS, Go, C/C++, C#, Scala, Kotlin, Ruby, Swift, Rust, PHP).
  2. scc       -> keyword-heuristic complexity, covers 200+ languages.
                  Skipped for files lizard already scored. Optional.
     Dart files scc scored also get an approximate per-function breakdown
     from lib/dart_complexity.py (the `dart-scanner` backend), since lizard
     has no Dart reader.

Churn window auto-widens (12mo -> 24mo -> 5y -> all-time) until at least
10% of files have any activity. If the path isn't inside a git repo, the
saturation signal is dropped and files render fully vivid.

The hue and saturation gradients are independently capped at the 95th
percentile when the distribution has wild outliers (max > 5x p95);
otherwise the full max-of-data range is used so small/well-behaved data
sees the full gradient.

Output is a single self-contained SVG with hover tooltips on every block
(file path, estimated tokens, LOC, complexity, recent commit count). Pass
--labels to also annotate large blocks with text.

Build artifacts (main.dart.js, *.min.js, *.bundle.js, *.map, files under
node_modules/dist/build/.next/.nuxt/etc.) and generated code (*.pb.go,
*.connect.go, *_pb.ts, wire_gen.go, zz_generated_*.go, *.freezed.dart,
*.designer.cs, etc.), and generated test reports (Playwright html-report/,
Lighthouse, ZAP, *.jsonl under a nested fixtures/) are filtered by default
so compiled bundles and protoc-emitted bindings don't dominate the "most
complex" lists with code nobody wrote by hand. If a single remaining file
still holds >30% of total LOC, a warning prints to stderr suggesting it
might be a build artifact that needs .gitignore; if the 5 largest files are
all scc-scored data files with complexity 0, a hint names
.assess/config.toml as the place to exclude them. Pass --include-artifacts
to disable the filter entirely.

Usage:
    uv run skills/assess/scripts/complexity-treemap.py <path> [-o out.svg] [--labels] [--include-artifacts]
"""
from __future__ import annotations

import argparse
import fnmatch
import json
import math
import shutil
import subprocess
import sys
import uuid
from datetime import datetime
from pathlib import Path

import lizard
import matplotlib.pyplot as plt
import numpy as np

# Shared layout/SVG primitives and churn machinery live in lib/ so the code
# heatmap, the docs heatmap, and the Layer 0 staleness metric reuse one
# implementation. Only the colour mapping differs per heatmap and stays local.
sys.path.insert(0, str(Path(__file__).resolve().parent))
from lib.assess_config import resolve_excludes  # noqa: E402
from lib.dart_complexity import (  # noqa: E402
    BACKEND_NAME as DART_BACKEND,
    dart_function_scores,
)
from lib.git_churn import (  # noqa: E402
    churn_is_degenerate,
    git_churn_scores,
    pick_churn_window,
)
from lib.generated_files import (  # noqa: E402
    GENERATED_NAME_PATTERNS,
    generated_reason,
)
from lib.treemap_render import (  # noqa: E402
    adaptive_cap,
    blend_to_grey,
    build_tree,
    layout,
    write_svg,
)


EXCLUDE_DIRS = {".git", "node_modules", "dist", "build", "target", "vendor",
                ".venv", "venv", "__pycache__", ".gradle", ".idea", ".mvn",
                "worktree", ".understand-anything", ".obsidian",
                ".taskmaster", ".claude",
                # /assess's own output directory. Without this the prior
                # run's run-context.json (often 2,000+ LOC) gets picked up
                # as a top-large file on every re-run - circular pollution.
                ".assess",
                # modern web framework build outputs
                ".next", ".nuxt", ".output", ".svelte-kit", ".astro",
                "out", "coverage", "htmlcov",
                # iOS/Xcode
                "Pods", "DerivedData",
                # Flutter web build output (lives under web/ or public/)
                "flutter_assets",
                # Playwright HTML test reports: a few lines holding a base64
                # bundle, committed under web/public/tests/... they took the
                # largest treemap blocks on a real repo (issue #336)
                "html-report", "playwright-report"}

# Filenames that match these glob patterns are treated as build artifacts
# or generated code and excluded from scoring. Two motivations:
#   - Compiled bundles (main.dart.js etc.) eat 78% of LOC and skew
#     every percentile (see PR #12).
#   - Generated bindings (.pb.go, *_pb.ts etc.) dominate "most complex"
#     lists with machine-emitted switch statements and getters that
#     nobody wrote by hand (see meridian PR #2212 - 8/10 most-complex
#     files were protobuf bindings).
# Files that match no glob but declare themselves generated (a header marker)
# or carry payload-length lines are caught by content in `collect`, via
# lib.generated_files, and listed in the stats file's `excluded_generated`.
# Pass --include-artifacts to disable.
EXCLUDE_FILE_PATTERNS = [
    # --- build artifacts ---
    # Minified / bundled JS-CSS
    "*.min.js", "*.min.mjs", "*.min.css",
    "*.bundle.js", "*.bundle.mjs", "*.bundle.css",
    "*.chunk.js", "*.chunk.mjs",
    "*-bundle.js", "*-min.js",
    # Sourcemaps and build metadata
    "*.map", "*.tsbuildinfo",
    # Flutter web outputs. `--web-renderer canvaskit` always emits the
    # canvaskit/skwasm runtime bundles (framework code, churn=1, not source);
    # basename globs catch them wherever the build nests them
    # (e.g. canvaskit/chromium/canvaskit.js).
    "main.dart.js", "flutter_service_worker.js", "flutter.js",
    "canvaskit.js", "skwasm*.js",
    # PWA / service worker stubs
    "service-worker.js", "sw.js", "workbox-*.js",

    # --- generated code ---
    # Go protobuf / gRPC / grpc-gateway / Connect
    "*.pb.go", "*_grpc.pb.go", "*.pb.gw.go", "*.connect.go",
    # JS/TS protobuf / Connect (buf, ts-proto, protoc-gen-grpc-web)
    "*_pb.ts", "*_pb.d.ts", "*_pb.js",
    "*_connect.ts", "*_connect.d.ts", "*_connect.js",
    # Python protobuf
    "*_pb2.py", "*_pb2_grpc.py",
    # C++ protobuf
    "*.pb.cc", "*.pb.h",
    # Go generators (wire, controller-gen, mockgen, bindata)
    "*.gen.go", "*.generated.go",
    # Any-language generator naming, and Supabase/GraphQL codegen outputs
    # (`supabase gen types` writes database.types.ts).
    *GENERATED_NAME_PATTERNS,
    "wire_gen.go",
    "zz_generated_*.go",
    "bindata.go", "bindata_assetfs.go",
    # .NET designer / source generators
    "*.designer.cs", "*.g.cs", "*.g.i.cs",
    # Dart/Flutter codegen (freezed, json_serializable, riverpod, get_it)
    "*.freezed.dart", "*.g.dart", "*.gr.dart", "*.config.dart",

    # --- generated test-tool reports ---
    # Lighthouse and OWASP ZAP output committed beside the tests (issue #336).
    # `zap-report.*` is ZAP's default report name in every output format; the
    # underscore spelling is pinned to report formats so a hand-written
    # `zap_report.py` that runs the scan stays scored.
    "lighthouse-report.html", "lighthouse-results.json",
    "zap-report.*",
    "zap_report.html", "zap_report.json", "zap_report.xml", "zap_report.md",
]

# Path-aware defaults: (directory name, basename glob). A file matches when the
# glob fits its basename and the directory name is one of its parent
# directories below the repo root. A same-named directory at the top level
# does not count: a bare top-level `fixtures/` often holds hand-kept reference
# data, while a nested `fixtures/` (`test/fixtures/`, `mcp/test/fixtures/`)
# holds recorded tool output. Path-aware like `EXCLUDE_PATH_SEQUENCES` in
# lib/doc_graph.py, but broader: any `fixtures` component below the top level
# matches, whatever its parent, since recorded JSONL sits under `mcp/test/`,
# `src/` or `e2e/` as often as under `tests/`.
EXCLUDE_NESTED_PATH_PATTERNS: tuple[tuple[str, str], ...] = (
    # Recorded JSONL fixtures (API captures, event logs), issue #336.
    ("fixtures", "*.jsonl"),
)


def _is_build_artifact(rel: Path) -> bool:
    """True if repo-relative ``rel`` matches an EXCLUDE_FILE_PATTERNS glob
    (basename match) or an EXCLUDE_NESTED_PATH_PATTERNS rule."""
    name = rel.name
    if any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_FILE_PATTERNS):
        return True
    nested_dirs = rel.parts[1:-1]
    return any(
        d in nested_dirs and fnmatch.fnmatch(name, pat)
        for d, pat in EXCLUDE_NESTED_PATH_PATTERNS
    )


def _is_user_excluded(rel: Path, extra_dirs: set[str],
                      extra_patterns: list[str]) -> bool:
    """True if `rel` matches a user-supplied exclude (CLI `--exclude` or
    `.assess/config.toml`).

    `extra_dirs` is matched exactly against any path component (mirrors how
    `EXCLUDE_DIRS` works). `extra_patterns` is matched as a basename glob
    (mirrors `EXCLUDE_FILE_PATTERNS`).
    """
    if extra_dirs and any(part in extra_dirs for part in rel.parts):
        return True
    if extra_patterns and any(
        fnmatch.fnmatch(rel.name, pat) for pat in extra_patterns
    ):
        return True
    return False


def lizard_scores(
    root: Path, include_artifacts: bool = False,
    extra_exclude_dirs: set[str] | None = None,
    extra_exclude_patterns: list[str] | None = None,
    fn_names: dict[Path, str] | None = None,
) -> dict[Path, tuple[int, float, list[float]]]:
    """Return ``{abs_path: (loc, ccn_sum, fn_ccns)}`` for scoreable files.

    ``fn_names``, when a dict, receives the name of each file's worst function
    (the first with the highest ccn) for every file with at least one function.

    Two distinct complexity signals come out of lizard, and conflating them is
    exactly the failure mode issue #58 reported:

    - ``ccn_sum`` - the **file-level aggregate** (sum of every function's
      cyclomatic complexity). This is the treemap's hue and the composite
      hotspot score's complexity axis. It is NOT comparable to a per-function
      linter threshold like ``cyclop: 15``; a file of twelve simple functions
      can sum past 100 without any single function violating anything.
    - ``fn_ccns`` - the **per-function** values. ``max(fn_ccns)`` is the worst
      single function and is what a per-function linter threshold actually
      gates. ``write_stats`` carries both so the report can say "ccn 136
      aggregate; worst function 13, under the 15 threshold" instead of
      mislabelling the aggregate as a per-function violation.
    """
    extra_dirs = extra_exclude_dirs or set()
    extra_pats = extra_exclude_patterns or []
    scores: dict[Path, tuple[int, float, list[float]]] = {}
    for f in lizard.analyze(paths=[str(root)], exclude_pattern=[]):
        path = Path(f.filename).resolve()
        try:
            rel = path.relative_to(root)
        except ValueError:
            continue
        if any(part in EXCLUDE_DIRS for part in rel.parts):
            continue
        if not include_artifacts and _is_build_artifact(rel):
            continue
        if _is_user_excluded(rel, extra_dirs, extra_pats):
            continue
        fn_ccns = [float(fn.cyclomatic_complexity) for fn in f.function_list]
        ccn_sum = sum(fn_ccns) or 1.0
        scores[path] = (f.nloc, float(ccn_sum), fn_ccns)
        if fn_names is not None and fn_ccns:
            fn_names[path] = f.function_list[fn_ccns.index(max(fn_ccns))].name
    return scores


def scc_scores(
    root: Path, include_artifacts: bool = False,
    extra_exclude_dirs: set[str] | None = None,
    extra_exclude_patterns: list[str] | None = None,
    languages: dict[Path, str] | None = None,
) -> dict[Path, tuple[int, float]]:
    """Return ``{abs_path: (loc, complexity)}`` for the files scc scores.

    ``languages``, when a dict, receives scc's per-language ``Name`` (``JSON``,
    ``YAML``, ``Python``) for every returned path.
    """
    if shutil.which("scc") is None:
        return {}
    extra_dirs = extra_exclude_dirs or set()
    extra_pats = extra_exclude_patterns or []
    # scc's --exclude-dir wants a comma-separated list. Merge defaults with
    # user-supplied dirs so scc skips them at scan time (cheaper than
    # filtering in Python after the fact).
    excludes = ",".join(sorted(EXCLUDE_DIRS | extra_dirs))
    try:
        raw = subprocess.run(
            ["scc", "--by-file", "--format", "json",
             f"--exclude-dir={excludes}", str(root)],
            capture_output=True, text=True, check=True,
        ).stdout
    except (subprocess.CalledProcessError, FileNotFoundError) as e:
        print(f"warning: scc failed ({e}); continuing without scc scores",
              file=sys.stderr)
        return {}
    try:
        payload = json.loads(raw)
    except json.JSONDecodeError:
        print("warning: scc returned invalid JSON; continuing without scc scores",
              file=sys.stderr)
        return {}
    scores: dict[Path, tuple[int, float]] = {}
    for lang_block in payload:
        for f in lang_block.get("Files", []):
            path = Path(f["Location"]).resolve()
            try:
                rel = path.relative_to(root)
            except ValueError:
                continue
            if not include_artifacts and _is_build_artifact(rel):
                continue
            # scc honoured extra_dirs at the --exclude-dir level, but
            # exclude_patterns are basename-only so we filter them here.
            if _is_user_excluded(rel, set(), extra_pats):
                continue
            scores[path] = (int(f["Code"]), float(f["Complexity"]))
            if languages is not None:
                languages[path] = str(lang_block.get("Name", ""))
    return scores


def _git_not_found_warning(root: Path) -> None:
    print(
        f"warning: no git history found for {root}\n"
        "         (path may not be a git repo, or the repo is "
        "empty / has a broken HEAD).\n"
        "         Rendering pure complexity (no saturation signal). "
        "If your code lives in a subdirectory\n"
        "         that IS a git repo (e.g. a -main subfolder), point "
        "the path at that.",
        file=sys.stderr,
    )


def _add_dart_scores(files: list[tuple[Path, int, float, str]],
                     fn_ccn_by_path: dict[Path, list[float]],
                     fn_names: dict[Path, str] | None,
                     fn_backends: dict[Path, str] | None) -> None:
    """Give scc-scored ``.dart`` files the approximate per-function breakdown.

    lizard has no Dart reader, so scc scores Dart at file level only; the
    ``dart-scanner`` backend (lib/dart_complexity.py) fills ``fn_ccn_by_path``,
    the worst function's name and the backend name for each such file.
    """
    for path, _loc, _metric, src in files:
        if src != "scc" or path.suffix != ".dart":
            continue
        fn_ccns, worst = dart_function_scores(path)
        if not fn_ccns:
            # No function found: the file stays scc-only, so a Dart file with
            # decision points and no breakdown keeps backend_by_language null.
            continue
        fn_ccn_by_path[path] = fn_ccns
        if fn_names is not None and worst is not None:
            fn_names[path] = worst
        if fn_backends is not None:
            fn_backends[path] = DART_BACKEND


def collect(root: Path, by: str = "complexity",
            include_artifacts: bool = False,
            extra_exclude_dirs: set[str] | None = None,
            extra_exclude_patterns: list[str] | None = None,
            scope: Path | None = None,
            excluded_generated: list[dict] | None = None,
            scc_languages: dict[Path, str] | None = None,
            fn_names: dict[Path, str] | None = None,
            fn_backends: dict[Path, str] | None = None,
            ) -> tuple[list[tuple[Path, int, float, str]], str,
                       dict[Path, int] | None, str | None,
                       dict[Path, list[float]]]:
    """Returns (files, effective_by, aux_data, aux_label, fn_ccn_by_path).

    - files: [(path, loc, metric, source)] - metric depends on mode
    - effective_by: may differ from `by` if we fell back (e.g. no git)
    - aux_data: secondary per-file signal (hotspot mode only); None otherwise
    - aux_label: human label for aux signal in tooltips
    - fn_ccn_by_path: per-function cyclomatic-complexity lists for the files a
      per-function backend scored: lizard, and the approximate Dart scanner for
      scc-scored ``.dart`` files (scc reports file-level complexity with no
      function breakdown, so its other paths are absent here). Threaded to `write_stats` so the report can
      separate per-function violations from file-level aggregates (issue #58).

    `scope` (an absolute path under `root`) restricts scoring to a subtree for
    `/assess <path>` monorepo scoping. The scan still roots at `root` so the
    config/exclude resolution and churn windowing are unchanged; the scored file
    list, dominance check, and churn axis then see only the subtree - so a scoped
    treemap carries no complexity or churn signal from a sibling directory. Omit
    it (the default) for a whole-repo run.

    `excluded_generated`, when a list, receives one ``{"path", "reason"}`` entry
    (repo-relative path) per file the content checks in lib.generated_files
    dropped: a generator header in the first lines (``generated-header``) or a
    payload-length average line (``long-lines``). ``include_artifacts`` skips
    those checks as it skips the filename globs.

    `scc_languages`, when a dict, receives scc's language name per scc-scored
    path (see `scc_scores`); `write_stats` uses it to split code from data.

    `fn_names`, when a dict, receives the worst function's name per path a
    per-function backend scored (see `lizard_scores`); `write_stats` writes it
    as each row's `max_fn_name`.

    `fn_backends`, when a dict, receives the backend name of every path scored
    by a backend other than lizard (`write_stats` defaults the rest to lizard).
    """
    lz = lizard_scores(
        root, include_artifacts=include_artifacts,
        extra_exclude_dirs=extra_exclude_dirs,
        extra_exclude_patterns=extra_exclude_patterns,
        fn_names=fn_names,
    )
    sc = scc_scores(
        root, include_artifacts=include_artifacts,
        extra_exclude_dirs=extra_exclude_dirs,
        extra_exclude_patterns=extra_exclude_patterns,
        languages=scc_languages,
    )
    files: list[tuple[Path, int, float, str]] = []
    fn_ccn_by_path: dict[Path, list[float]] = {}
    for path, (loc, ccn, fn_ccns) in lz.items():
        files.append((path, loc, ccn, "lizard"))
        fn_ccn_by_path[path] = fn_ccns
    for path, (loc, cx) in sc.items():
        if path not in lz:
            files.append((path, loc, cx, "scc"))
    files = [f for f in files if f[1] > 0]
    if scope is not None:
        scope_abs = scope.resolve()
        files = [f for f in files if f[0].resolve().is_relative_to(scope_abs)]
        fn_ccn_by_path = {
            p: v for p, v in fn_ccn_by_path.items()
            if p.resolve().is_relative_to(scope_abs)
        }
    if not include_artifacts:
        kept: list[tuple[Path, int, float, str]] = []
        for f in files:
            reason = generated_reason(f[0])
            if reason is None:
                kept.append(f)
                continue
            fn_ccn_by_path.pop(f[0], None)
            if excluded_generated is not None:
                try:
                    rel = f[0].relative_to(root).as_posix()
                except ValueError:
                    rel = f[0].as_posix()
                excluded_generated.append({"path": rel, "reason": reason})
        files = kept
        if excluded_generated is not None:
            excluded_generated.sort(key=lambda e: e["path"])

    # After the scope and generated-file filters, so it reads only kept files.
    _add_dart_scores(files, fn_ccn_by_path, fn_names, fn_backends)

    effective_by = by
    aux_data: dict[Path, int] | None = None
    aux_label: str | None = None

    if by == "churn":
        churn = git_churn_scores(root, scope=scope)
        if not churn:
            _git_not_found_warning(root)
            effective_by = "complexity"
        else:
            files = [(p, loc, float(churn.get(p, 0)), src)
                     for p, loc, _m, src in files]
    elif by == "hotspot":
        aux_data, aux_label = pick_churn_window(root, [f[0] for f in files])
        if aux_data is None:
            _git_not_found_warning(root)
            effective_by = "complexity"

    return files, effective_by, aux_data, aux_label, fn_ccn_by_path


DOMINANCE_WARN_THRESHOLD = 0.30  # one file >30% of total LOC = suspicious


def _warn_if_dominated_by_one_file(
    files: list[tuple[Path, int, float, str]],
) -> None:
    """If a single file is >30% of total LOC, flag it as likely-build-artifact.

    Compiled bundles (main.dart.js, *.min.js) that slip past the filter
    skew every percentile and dominate the treemap. The size signal alone
    is enough to flag suspects - human-written codebases rarely have one
    file holding a third of the LOC.
    """
    if len(files) < 2:
        return
    total_loc = sum(f[1] for f in files)
    if total_loc == 0:
        return
    biggest = max(files, key=lambda f: f[1])
    share = biggest[1] / total_loc
    if share < DOMINANCE_WARN_THRESHOLD:
        return
    print(
        f"warning: one file holds {share:.0%} of scoreable LOC "
        f"({biggest[1]:,} of {total_loc:,}).\n"
        f"         {biggest[0].name} - looks like a build artifact or "
        f"generated file.\n"
        f"         If so, add it to .gitignore and re-run. To score it "
        f"anyway, pass --include-artifacts.",
        file=sys.stderr,
    )


SCC_ONLY_HINT_TOP_N = 5  # the largest blocks a reader sees first


def _hint_if_largest_files_scc_only(
    files: list[tuple[Path, int, float, str]],
    tokens: dict[Path, int],
    languages: dict[Path, str],
    n: int = SCC_ONLY_HINT_TOP_N,
) -> None:
    """Hint at config excludes when the ``n`` largest files by estimated tokens
    are all scc-scored data files (``DATA_LANGUAGES``) with complexity 0.

    No single file need pass the dominance threshold for the treemap's biggest
    blocks to be data an agent never edits (issue #336). Scoped to data
    languages because scc also reports complexity 0 for Markdown, HTML and CSS:
    on a docs-first repository those blocks are the deliverable, and advising
    to exclude them would be wrong. Silent below ``n`` files and when any of
    the ``n`` is lizard-scored, carries complexity, or is not a data language.
    """
    if len(files) < n:
        return
    largest = sorted(files, key=lambda f: -tokens.get(f[0], f[1]))[:n]
    if any(f[3] != "scc" or f[2] > 0
           or languages.get(f[0]) not in DATA_LANGUAGES for f in largest):
        return
    names = ", ".join(f[0].name for f in largest)
    print(
        f"hint: the {n} largest files by estimated tokens are all data files "
        f"(JSON / YAML / JSONL)\n"
        f"      scored by scc with complexity 0: {names}.\n"
        f"      If agents never edit them, add their directories or globs to "
        f".assess/config.toml\n"
        f"      (`exclude_dirs` / `exclude_patterns`) and re-run.",
        file=sys.stderr,
    )


# Survivor-density overlay thresholds. A file whose mutation survivor density
# (survivors / mutants, from the test_pressure block) clears these stops
# rendering as safe green: >30% gets a diagonal hatch, >50% a cross-hatch.
SURVIVOR_DIAG_THRESHOLD = 0.30
SURVIVOR_CROSS_THRESHOLD = 0.50


def _hatch_for_density(density: float | None) -> str:
    """Map a survivor density to a hatch level. "" when below threshold or
    unknown - so absent/empty data silently renders no overlay."""
    if density is None:
        return ""
    if density > SURVIVOR_CROSS_THRESHOLD:
        return "cross"
    if density > SURVIVOR_DIAG_THRESHOLD:
        return "diag"
    return ""


def _survivor_overrides(
    files: list[tuple[Path, int, float, str]],
    survivor_density: dict[Path, float] | None,
) -> dict[Path, dict]:
    """Build the per-file Node overrides (``{path: {"hatch": ...}}``) for the
    survivor-density overlay. Keys in ``survivor_density`` are matched against
    each file's resolved path (``files[i][0]``). Returns an empty dict when no
    data is supplied or nothing clears the threshold - the caller treats that
    as "no overlay"."""
    if not survivor_density:
        return {}
    overrides: dict[Path, dict] = {}
    for f in files:
        hatch = _hatch_for_density(survivor_density.get(f[0]))
        if hatch:
            overrides[f[0]] = {"hatch": hatch}
    return overrides


def render(files: list[tuple[Path, int, float, str]],
           root: Path, out_path: Path, title: str,
           show_labels: bool = False,
           by: str = "complexity",
           aux_data: dict[Path, int] | None = None,
           aux_label: str | None = None,
           survivor_density: dict[Path, float] | None = None,
           tokens_by_path: dict[Path, int] | None = None,
           churn_degenerate: bool = False) -> None:
    metric_label = "commits" if by == "churn" else "ccn"
    metrics = [f[2] for f in files]
    cap, cap_kind = adaptive_cap(metrics)
    # OrRd (ColorBrewer): colour-blind-safe sequential ramp, pale = simple ->
    # dark red = complex. Avoids the red-green of RdYlGn (the most common CVD).
    cmap = plt.get_cmap("OrRd")

    # Degenerate churn = a flat saturation axis (every file ~1 commit), which
    # would render as uniform full-saturation and read as a live signal. Drop it:
    # the blocks render fully vivid (pure complexity), matching the no-git path,
    # and the one-line summary below states the axis is inactive rather than
    # legending a meaningless gradient.
    if churn_degenerate:
        aux_data = None

    aux_cap = 1.0
    aux_cap_kind = ""
    if aux_data is not None:
        aux_values = [float(aux_data.get(f[0], 0)) for f in files]
        aux_cap, aux_cap_kind = adaptive_cap(aux_values)

    files_colored = []
    for f in files:
        # Floor the ramp at 0.12 so the calm (low-complexity) end is a visible
        # pale orange, not near-white that washes out against the white canvas.
        base = cmap(0.12 + 0.88 * min(f[2] / cap, 1.0))
        if aux_data is not None:
            aux_val = float(aux_data.get(f[0], 0))
            color = blend_to_grey(base, aux_val / aux_cap)
        else:
            color = base
        files_colored.append((f[0], f[1], f[2], f[3], color))

    # Block area is estimated tokens (the keyhole size unit), not LOC: size_by
    # overrides the layout area per file while each leaf keeps its real LOC for
    # the tooltip. Falls back to LOC area when no token map is supplied.
    tokens = (tokens_by_path if tokens_by_path is not None
              else est_tokens_by_path(files))
    overrides = _survivor_overrides(files, survivor_density)
    tree = build_tree(files_colored, root, aux_data, aux_label or "",
                      node_overrides=overrides or None, size_by=tokens)
    W, H = 1600.0, 1000.0
    rects: list = []
    layout(tree, 0, 0, W, H, rects)

    write_svg(rects, root, W, H, out_path, show_labels, metric_label,
              show_survivor_legend=bool(overrides))

    print(f"wrote {out_path}  ({len(files)} files, "
          f"{sum(1 for f in files if f[3] == 'lizard')} lizard, "
          f"{sum(1 for f in files if f[3] == 'scc')} scc)")
    mx = float(max(metrics)) if metrics else 0.0
    print(f"hue: {metric_label}; range 0-{mx:.0f}; "
          f"cap {cap:.0f} ({cap_kind})")
    if churn_degenerate:
        print("saturation: churn signal flat (degenerate history - every file "
              "~1 commit); axis inactive, rendering pure complexity.")
    elif aux_data is not None:
        aux_max = max((float(aux_data.get(f[0], 0)) for f in files),
                       default=0.0)
        print(f"saturation: {aux_label}; range 0-{aux_max:.0f}; "
              f"cap {aux_cap:.0f} ({aux_cap_kind})")

    biggest = sorted(files, key=lambda f: -tokens.get(f[0], 0))[:5]
    if biggest:
        print("biggest files (estimated tokens dominate layout):")
        for path, loc, metric, src in biggest:
            try:
                rel = path.relative_to(root)
            except ValueError:
                rel = path
            aux_str = ""
            if aux_data is not None:
                aux_str = f"  {aux_label} {aux_data.get(path, 0):>4d}"
            print(f"  {tokens.get(path, 0):>9,} est.tok  {loc:>7} loc  "
                  f"{metric_label} {metric:>5.0f}{aux_str}  [{src:6}]  {rel}")


# Artifact schema version for complexity-stats.json - the run_id provenance
# schema (distinct from STATS_SCHEMA_VERSION below, which versions the stats
# *layout* for diff comparability). Mirrors assess_core's
# ARTIFACT_SCHEMA_VERSION - the treemap runs as a separate process, so the
# constant is duplicated rather than imported (no dependency on assess_core).
ARTIFACT_SCHEMA_VERSION = "1.1.0"


def _new_run_id() -> str:
    """A unique id for this stats emission: sortable wall-clock stamp + random
    suffix (``YYYYMMDDHHMMSS-<8 hex>``), so each complexity-stats.json is
    traceable to the run that wrote it."""
    return f"{datetime.now().strftime('%Y%m%d%H%M%S')}-{uuid.uuid4().hex[:8]}"


def _read_plugin_version() -> str:
    """Read the plugin version from .claude-plugin/plugin.json.

    plugin.json lives three directories up from this script:
        scripts/complexity-treemap.py -> scripts/ -> skills/assess/ -> skills/ -> repo root
    Stamped into the stats sidecar so a later run can detect when its prior
    snapshot came from a differently-filtered plugin and suppress a misleading
    diff (filter-mismatched "graduated" ghosts). Returns "unknown" if absent.
    """
    plugin_json = Path(__file__).resolve().parents[3] / ".claude-plugin" / "plugin.json"
    try:
        data = json.loads(plugin_json.read_text(encoding="utf-8"))
        return str(data.get("version", "unknown"))
    except (FileNotFoundError, json.JSONDecodeError):
        return "unknown"


# Version of the complexity-stats.json layout the diff compares. A cross-run
# diff is only trustworthy when both snapshots share this schema; a bump here
# is a structural change to the sidecar shape (a metric added/removed/redefined)
# that voids the diff against an older snapshot until the next clean run
# re-seeds the baseline (assess_core._diff_is_reliable reads it).
STATS_SCHEMA_VERSION = 5  # 2: generated-file content excludes + excluded_generated
                          # 3: generated test-report excludes + loc/est_tokens max_code/max_data
                          # 4: fn_ccn.source list + backend_by_language, rows max_fn_name
                          # 5: dart-scanner fills max_fn_ccn for Dart rows, moving their score

# scc language names counted as data, not code, for the `max_code` / `max_data`
# split in the stats file. Data files stay in the treemap: a large hand-kept
# fixture is weight an agent may have to read.
DATA_LANGUAGES = frozenset({"JSON", "YAML", "JSONL"})

# Per-function complexity backends, by name, with whether their counts are
# approximate. `fn_ccn.source` in the stats file lists the ones that scored a
# file in the run; a path's backend defaults to lizard (see `write_stats`).
FN_BACKENDS = {"lizard": False, DART_BACKEND: True}


def _lizard_version() -> str:
    """Capture the installed lizard version at runtime.

    lizard exposes no ``__version__`` attribute, so the version comes from the
    installed-package metadata. Stamped into complexity-stats.json so a later
    run can tell that the complexity backend moved (a lizard release can shift
    cyclomatic scores) and flag the diff against the prior snapshot as not
    comparable. Returns "unknown" if the metadata can't be read.
    """
    try:
        from importlib.metadata import version
        return version("lizard")
    except Exception:
        # Defensive: a metadata quirk must never fail the scan, only the stamp.
        return "unknown"


def _scc_version() -> str | None:
    """Capture the installed scc version, or ``None`` when scc is not on PATH.

    scc prints ``scc version 3.7.0``; the trailing token is the version. Only
    stamped into the sidecar when scc actually scored files, so its absence in
    the stats is honest (scc contributed nothing) rather than a false "unknown".
    """
    if shutil.which("scc") is None:
        return None
    try:
        out = subprocess.run(
            ["scc", "--version"], capture_output=True, text=True, check=True,
        ).stdout.strip()
    except (subprocess.SubprocessError, OSError):
        return None
    if not out:
        return None
    return out.split()[-1]


def _tool_versions(files: list[tuple[Path, int, float, str]]) -> dict[str, str]:
    """Map the complexity backends that scored this run to their versions.

    Always carries ``lizard``; adds ``scc`` only when at least one file was
    scored by scc (the sidecar's own ``scoring_coverage`` is the source of that
    truth), so the version set matches the tools that actually shaped the data.
    """
    versions: dict[str, str] = {"lizard": _lizard_version()}
    if any(f[3] == "scc" for f in files):
        scc_v = _scc_version()
        if scc_v is not None:
            versions["scc"] = scc_v
    return versions


# Weight of the per-function worst case in the hotspot composite. The effective
# complexity is a weighted geometric mean of the file aggregate and the file's
# worst single function, leaning toward the per-function offender (issue #115).
PER_FUNCTION_WEIGHT = 0.7

# Token estimation. /assess measures the keyhole in tokens, not lines: LOC
# undercounts dense/wide files (long identifiers, comments, data tables, prose)
# and overcounts sparse code. A treemap and a ranking need only *relative* size,
# so the standard ~4-chars-per-token heuristic is visually and ordinally
# equivalent to a real tokenizer while staying deterministic, dependency-free,
# and model-agnostic (a tokenizer is model-specific - OpenAI != Claude - and
# adds a reproducibility caveat). Always labelled "estimated tokens": an honest
# stable estimate, never an exact count.
CHARS_PER_TOKEN = 4

# A subtree (or single file) above this many estimated tokens no longer fits one
# context-window keyhole - the literal "does the relevant slice fit?" measure.
# An estimate, labelled as such; a documented default, not a model-exact limit.
CONTEXT_WINDOW_BUDGET_TOKENS = 200_000


def est_token_count(path: Path, loc: int) -> int:
    """Estimated token count for one file: ``ceil(len(text) / 4)``.

    Reads the file text and applies the ~4-chars-per-token heuristic. On an
    unreadable file (binary, vanished, decode error) it falls back to ``loc`` -
    a conservative floor that can't inflate a benign file's rank. Always >= 1 so
    a file never has zero area.
    """
    try:
        text = path.read_text(encoding="utf-8", errors="ignore")
    except (OSError, ValueError):
        return max(1, loc)
    return max(1, math.ceil(len(text) / CHARS_PER_TOKEN))


def est_tokens_by_path(
    files: list[tuple[Path, int, float, str]],
) -> dict[Path, int]:
    """``{path: est_tokens}`` for the already-filtered scoreable files.

    Called after the artifact filter (``collect``), so a minified/generated
    bundle that never reaches the treemap never contributes to the token totals
    or the keyhole budget either.
    """
    return {f[0]: est_token_count(f[0], f[1]) for f in files}


def _keyhole_budget_rollup(
    tokens: dict[Path, int], root: Path,
    budget: int = CONTEXT_WINDOW_BUDGET_TOKENS,
) -> dict:
    """Roll per-file estimated tokens into the keyhole-budget finding.

    Reports the repo total and how many individual files / top-level subtrees
    exceed one context-window budget - the most on-thesis signal /assess emits:
    "does the relevant slice fit one keyhole?". The budget is an estimate
    (char-based tokens against a documented default), labelled as such.
    """
    total = sum(tokens.values())
    files_over = sum(1 for t in tokens.values() if t > budget)
    subtree_totals: dict[str, int] = {}
    for path, t in tokens.items():
        try:
            rel = path.relative_to(root)
        except ValueError:
            continue
        # First path component: a top-level file maps to itself, anything under
        # a directory maps to that directory.
        top = rel.parts[0] if rel.parts else rel.name
        subtree_totals[top] = subtree_totals.get(top, 0) + t
    over_subtrees = sorted(
        ({"path": name, "est_tokens": tot}
         for name, tot in subtree_totals.items() if tot > budget),
        key=lambda s: -s["est_tokens"],
    )
    return {
        "total": total,
        "budget": budget,
        "budget_basis": "estimate (~4 chars/token, documented default)",
        "chars_per_token": CHARS_PER_TOKEN,
        "files_over_budget": files_over,
        "subtrees_over_budget": len(over_subtrees),
        "over_budget_subtrees": over_subtrees[:10],
    }


def _effective_ccn(ccn: float, max_fn_ccn: float | None) -> float:
    """Complexity used to rank hotspots, re-weighted toward the worst function.

    The treemap hue and the ``ccn`` field stay file-aggregate, but the hotspot
    composite ranks on this value instead. For class-per-file languages
    (Java/Kotlin/C#) a broad coordinator class spreads complexity across many
    small methods, so its aggregate over-ranks it above a genuinely complex
    single method living in a leaner file (issue #115: an aggregate-107 / worst-
    function-14 coordinator out-ranked a ccn-28 DAO method). Blending toward
    ``max_fn_ccn`` corrects that.

    For a lizard file ``max_fn_ccn <= ccn`` by construction (it is the largest
    term of the sum). A Dart file takes ``ccn`` from scc and ``max_fn_ccn`` from
    the Dart scanner, whose counting rules differ (scc skips ``case``, ``catch``
    and the per-function +1), so ``max_fn_ccn`` is clamped to ``ccn`` and the
    effective value never exceeds the aggregate. For single-function-dominant
    files (Python/Go, where ``max_fn_ccn`` is at or near the aggregate) the blend
    collapses back to the aggregate, so their ranking is unchanged. Files with no
    function breakdown (``max_fn_ccn is None``) keep the raw aggregate.
    """
    if max_fn_ccn:
        max_fn_ccn = min(max_fn_ccn, ccn)
    if not max_fn_ccn:  # None (no breakdown) or 0 -> no usable signal
        return ccn
    w = PER_FUNCTION_WEIGHT
    return float(max_fn_ccn ** w * ccn ** (1.0 - w))


def write_stats(files: list[tuple[Path, int, float, str]],
                aux_data: dict[Path, int] | None,
                aux_label: str | None,
                root: Path, out_path: Path,
                fn_ccn_by_path: dict[Path, list[float]] | None = None,
                tokens_by_path: dict[Path, int] | None = None,
                churn_degenerate: bool = False,
                excluded_generated: list[dict] | None = None,
                languages_by_path: dict[Path, str] | None = None,
                fn_name_by_path: dict[Path, str] | None = None,
                fn_backend_by_path: dict[Path, str] | None = None) -> None:
    """Write a JSON stats sidecar summarising the treemap data.

    Consumed by the /assess skill: percentiles drive Layer 3 (linter) scoring,
    top hotspot lists become the named files in the actions table.
    Composite hotspot score = sqrt(effective_ccn) * sqrt(1 + commits) *
    sqrt(est_tokens): a sub-linear geometric mean of complexity, recent churn,
    and context-window size. All three axes are sqrt-damped, so a file high on
    *multiple* axes - big AND complex AND churning - is the worst keyhole and
    leads; a frozen-but-complex file ranks below an equally-sized active one;
    a trivially-simple-but-churny file can't top on churn alone; and a
    big-but-simple-stable file (a long config or data table) can't top on size
    alone (low ccn * low churn * big size stays moderate). ``effective_ccn``
    re-weights the file aggregate toward the worst single function (see
    ``_effective_ccn``) so a broad coordinator class can't out-rank a genuinely
    complex single method (issue #115).

    ``tokens_by_path`` carries the per-file estimated token counts (computed
    once by ``main`` post-artifact-filter). When omitted it is derived here from
    the same files, so the sidecar is self-consistent whoever calls it.

    The ``ccn`` block and every row's ``ccn`` field are **file-level aggregates**
    (sum of per-function complexity). A per-function linter threshold (cyclop 15,
    gocognit, etc.) is NOT comparable to those - so each row also carries
    ``max_fn_ccn`` (the file's worst single function, or null for scc-scored
    files with no function breakdown), and the top-level ``fn_ccn`` block reports
    the per-function distribution. Layer 3 compares the linter threshold against
    ``fn_ccn`` / ``max_fn_ccn``, never the aggregate (issue #58).

    ``excluded_generated`` (the list ``collect`` filled) is written as the
    top-level ``excluded_generated`` key, always present and empty when nothing
    was dropped, so the exclusion stays visible downstream.

    ``languages_by_path`` (scc's language name per path, from ``collect``)
    splits the ``loc`` and ``est_tokens`` maxima into ``max_code`` and
    ``max_data``: a file whose language is in ``DATA_LANGUAGES`` is data,
    everything else code. A side with no files reports 0.

    ``fn_name_by_path`` gives each row's ``max_fn_name`` (null wherever
    ``max_fn_ccn`` is null). ``fn_backend_by_path`` names the per-function
    backend of each path in ``fn_ccn_by_path`` (lizard when omitted);
    ``fn_ccn.source`` lists the backends that scored a file, as
    ``{name, approximate}`` objects from ``FN_BACKENDS``, and
    ``fn_ccn.backend_by_language`` maps each scc language to its backend, or to
    null when any of its files with decision points was scored by scc at file
    level only (so partial coverage reads as null). A language gets a key when a
    backend scored one of its files or scc counted a decision point in one;
    data and markup (JSON, YAML, Markdown), where scc counts none, get no key,
    but CSS maps to null because scc counts decision points in it.
    """
    fn_ccn_by_path = fn_ccn_by_path or {}
    fn_names = fn_name_by_path or {}
    backend_of = {p: (fn_backend_by_path or {}).get(p, "lizard")
                  for p in fn_ccn_by_path}
    tokens = tokens_by_path if tokens_by_path is not None else est_tokens_by_path(files)
    locs = [f[1] for f in files]
    token_vals = [tokens.get(f[0], est_token_count(f[0], f[1])) for f in files]
    ccns = [f[2] for f in files]
    langs = languages_by_path or {}
    is_data = [langs.get(f[0]) in DATA_LANGUAGES for f in files]

    def side_max(values: list, data: bool) -> float:
        side = [v for v, d in zip(values, is_data) if d is data]
        return float(max(side)) if side else 0.0

    churns = ([float(aux_data.get(f[0], 0)) for f in files]
              if aux_data is not None else [])
    # Per-function population, per-function backends only. Other scc paths are
    # absent from fn_ccn_by_path, so they don't contribute - the block
    # self-labels its sources so a reader knows what it omits.
    fn_population: list[float] = []
    for vals in fn_ccn_by_path.values():
        fn_population.extend(vals)

    def pct(values: list[float], q: float) -> float:
        return float(np.percentile(values, q)) if values else 0.0

    def rel(p: Path) -> str:
        # Forward slashes on every host, matching `excluded_generated` (built
        # in `collect`), so assess_core can compare the two path sets on Windows.
        try:
            return p.relative_to(root).as_posix()
        except ValueError:
            return p.as_posix()

    def max_fn(path: Path) -> float | None:
        vals = fn_ccn_by_path.get(path)
        return float(max(vals)) if vals else None

    backends_used = sorted({backend_of[f[0]] for f in files
                            if f[0] in backend_of})
    covered: dict[str, str] = {}
    uncovered: set[str] = set()
    for path, _loc, metric, _src in files:
        lang = langs.get(path)
        if not lang:
            continue
        if path in backend_of:
            covered[lang] = backend_of[path]
        elif metric > 0 and lang not in DATA_LANGUAGES:
            uncovered.add(lang)
    # A language counts as covered only when no file of it with decision points
    # fell back to scc: partial coverage reads as null, not as the backend.
    backend_by_language: dict[str, str | None] = {
        lang: (None if lang in uncovered else covered[lang])
        for lang in covered.keys() | uncovered
    }

    enriched = []
    for path, loc, ccn, src in files:
        churn = float(aux_data.get(path, 0)) if aux_data else 0.0
        est_tokens = tokens.get(path, est_token_count(path, loc))
        enriched.append({
            "path": rel(path),
            "loc": int(loc),
            # Estimated tokens (~chars/4), the size unit the treemap blocks and
            # the hotspot composite use. `loc` is kept alongside (tooltip +
            # back-compat). An estimate, not a model-exact count.
            "est_tokens": int(est_tokens),
            # File-level aggregate (sum of per-function ccn). See `max_fn_ccn`
            # for the per-function worst case the linter threshold gates.
            "ccn": float(ccn),
            "ccn_basis": "file-aggregate",
            "max_fn_ccn": max_fn(path),
            # Name of the function whose ccn is max_fn_ccn; null with it.
            "max_fn_name": (fn_names.get(path)
                            if max_fn(path) is not None else None),
            # Named `commits` to match what every consumer reads (stats_diff,
            # assess_core, the hotspot template). None when churn is unavailable
            # (no git), so a missing value is distinct from a real 0.
            "commits": int(churn) if aux_data else None,
            "source": src,
            # Ranked on the per-function-weighted effective complexity, recent
            # churn, AND context-window size - each sqrt-damped so the worst
            # keyhole (high on multiple axes) leads and no single axis can top
            # the list alone (issue #115 for the ccn re-weight; PRD 2026-06 for
            # the token axis). The `ccn`/`loc` fields above stay raw for the hue
            # and the Layer 3 comparison.
            "_score": math.sqrt(_effective_ccn(ccn, max_fn(path)))
            * math.sqrt(1.0 + churn)
            * math.sqrt(est_tokens),
        })

    def strip(rows: list[dict]) -> list[dict]:
        return [{k: v for k, v in r.items() if k != "_score"} for r in rows]

    by_score = sorted(enriched, key=lambda f: -f["_score"])
    by_ccn = sorted(enriched, key=lambda f: -f["ccn"])
    by_loc = sorted(enriched, key=lambda f: -f["loc"])

    tool_versions = _tool_versions(files)
    stats: dict = {
        # Run provenance: the artifact schema and a unique id for this emission
        # (distinct from schema_version below, which versions the stats layout).
        "artifact_schema_version": ARTIFACT_SCHEMA_VERSION,
        "run_id": _new_run_id(),
        "plugin_version": _read_plugin_version(),
        # Layout version of this sidecar. A cross-run diff is only comparable
        # when both snapshots share it (assess_core._diff_is_reliable).
        "schema_version": STATS_SCHEMA_VERSION,
        # The complexity backends and their captured versions. A backend version
        # change can shift scores, so a later run flags the diff as not
        # comparable and names the tool. lizard is always present; scc only when
        # it scored files.
        "lizard_version": tool_versions["lizard"],
        **({"scc_version": tool_versions["scc"]} if "scc" in tool_versions else {}),
        "files_scored": len(files),
        # Files dropped by content (generator header, payload-length lines):
        # [{path, reason}]. assess_core copies it into run-context.json.
        "excluded_generated": list(excluded_generated or []),
        "scoring_coverage": {
            "lizard": sum(1 for f in files if f[3] == "lizard"),
            "scc": sum(1 for f in files if f[3] == "scc"),
        },
        "churn_window": aux_label,
        # Churn-measurement reliability (lib.git_churn.churn_is_degenerate). True
        # when the history is degenerate - every file ~1 commit - so the
        # saturation axis carries no signal and the hotspot composite's churn
        # term (sqrt(1 + commits)) is near-constant. A reader (and the report)
        # treats the `commits` column and saturation axis as inactive here.
        "churn_degenerate": bool(churn_degenerate),
        "loc": {
            "p50": pct(locs, 50),
            "p95": pct(locs, 95),
            "max": float(max(locs)) if locs else 0.0,
            # The maxima split by scc language (DATA_LANGUAGES), so a large
            # JSON fixture cannot pass for the largest source file.
            "max_code": side_max(locs, False),
            "max_data": side_max(locs, True),
            "total": sum(locs),
        },
        # Estimated tokens (~chars/4) - the keyhole size unit. Sized the treemap
        # blocks and feeds the hotspot composite. `budget` rolls the per-file
        # totals into the "does the relevant slice fit one keyhole?" finding.
        "est_tokens": {
            "p50": pct(token_vals, 50),
            "p95": pct(token_vals, 95),
            "max": float(max(token_vals)) if token_vals else 0.0,
            "max_code": side_max(token_vals, False),
            "max_data": side_max(token_vals, True),
            "total": sum(token_vals),
            "budget": _keyhole_budget_rollup(tokens, root),
        },
        # File-level aggregate complexity (sum per file). Drives the treemap hue
        # and the hotspot composite - NOT comparable to a per-function linter
        # threshold. Use `fn_ccn` for that comparison.
        "ccn": {
            "basis": "file-aggregate",
            "p50": pct(ccns, 50),
            "p95": pct(ccns, 95),
            "max": float(max(ccns)) if ccns else 0.0,
        },
        # Per-function complexity distribution (the unit a linter threshold like
        # cyclop:15 actually gates). Per-function backends only; scc files
        # contribute no function breakdown. `function_count` is 0 when only scc
        # scored the repo. `backend_by_language` null = no per-function data.
        "fn_ccn": {
            "basis": "per-function",
            "source": [{"name": n, "approximate": FN_BACKENDS.get(n, False)}
                       for n in backends_used],
            "backend_by_language": dict(sorted(backend_by_language.items())),
            "function_count": len(fn_population),
            "p50": pct(fn_population, 50),
            "p95": pct(fn_population, 95),
            "max": float(max(fn_population)) if fn_population else 0.0,
        },
        "churn": ({
            "p50": pct(churns, 50),
            "p95": pct(churns, 95),
            "max": float(max(churns)) if churns else 0.0,
        } if aux_data is not None else None),
        "top_hotspots": strip(by_score[:10]),
        "top_complex": strip(by_ccn[:10]),
        "top_large": strip(by_loc[:10]),
    }

    out_path.write_text(json.dumps(stats, indent=2), encoding="utf-8")
    print(f"wrote {out_path}")


def load_survivor_density(run_context_path: Path,
                          root: Path) -> dict[Path, float]:
    """Build a ``{resolved_path: density}`` map from a run-context.json's
    ``test_pressure`` block, for the survivor-density overlay.

    Per-file density is ``survived / total`` taken from ``test_pressure.per_file``
    (the only source carrying per-file totals; ``survivor_density.by_file`` holds
    raw survivor *counts*). Entries without a total (e.g. mutmut, which lists
    only survivors) are skipped - we hatch on a real density or not at all.

    File paths reported by mutation tools are resolved against ``root`` so they
    match the treemap's resolved file paths. Degrades silently to ``{}`` on any
    error or when no ``test_pressure`` data is present - an absent or empty block
    means no overlay, no warning.
    """
    try:
        ctx = json.loads(run_context_path.read_text(encoding="utf-8"))
    except (FileNotFoundError, json.JSONDecodeError, OSError):
        return {}
    if not isinstance(ctx, dict):
        return {}
    tp = ctx.get("test_pressure")
    if not isinstance(tp, dict):
        return {}
    per_file = tp.get("per_file") or []
    density: dict[Path, float] = {}
    for entry in per_file:
        if not isinstance(entry, dict):
            continue
        total = entry.get("total")
        survived = entry.get("survived")
        file_str = entry.get("file")
        if not file_str or not total:  # None or 0 total -> no derivable density
            continue
        try:
            resolved = (root / file_str).resolve()
            density[resolved] = (survived or 0) / total
        except (TypeError, ValueError, OSError):
            continue
    return density


def main() -> int:
    ap = argparse.ArgumentParser(
        description=(
            "Render a Codecov-style hotspot treemap of any folder. "
            "Hue = cyclomatic complexity, saturation = recent git churn "
            "(auto-windowed: 12mo -> 24mo -> 5y -> all-time). "
            "Vivid red = complex AND active = highest risk."
        ))
    ap.add_argument("path", type=Path, help="Directory to analyse")
    ap.add_argument(
        "-o", "--out", type=Path,
        help=("Output SVG path. If omitted, writes "
              "./hotspot-<folder>.svg in the current working directory."),
    )
    ap.add_argument("--labels", action="store_true",
                    help=("Annotate large blocks with filename, estimated "
                          "tokens and metric"))
    ap.add_argument(
        "--stats", type=Path,
        help=("Write a JSON stats sidecar (file count, estimated-token / "
              "LOC / CCN percentiles, keyhole-budget rollup, top "
              "hotspot/complex/large files). Used by /assess to score "
              "Layer 3 and surface specific improvement actions."),
    )
    ap.add_argument(
        "--include-artifacts", action="store_true",
        help=("Score known build artifacts that are normally filtered "
              "(main.dart.js, *.min.js, *.bundle.js, *.map, etc.) and "
              "files excluded as generated by content (a generator "
              "header in the first 5 lines, or payload-length lines). "
              "Use this only when you specifically want to visualise "
              "the build output - typically you'd .gitignore these instead."),
    )
    ap.add_argument(
        "--test-pressure", type=Path, metavar="RUN_CONTEXT_JSON",
        help=("Path to a run-context.json. When its `test_pressure` block "
              "carries per-file mutation results, files with high survivor "
              "density are hatched (>30%% diagonal, >50%% cross-hatch) so "
              "covered-but-unpinned code stops rendering as safe green. "
              "Absent or empty test_pressure data -> no overlay (silent)."),
    )
    ap.add_argument(
        "--exclude", action="append", default=[], metavar="PATTERN",
        help=("Skip files / directories that match PATTERN. Repeatable. "
              "A plain string (`regulatory-raw`) is treated as a directory "
              "name; a glob (`*.csv`) is matched against the basename. "
              "Extends the built-in defaults rather than replacing them. "
              "For a durable per-repo exclude list, use "
              "`.assess/config.toml` (top-level `exclude_dirs` / "
              "`exclude_patterns`)."),
    )
    ap.add_argument(
        "--scope", type=Path, metavar="SUBDIR",
        help=("Restrict scoring to a subtree of the repo (for `/assess <path>` "
              "monorepo scoping). A path under the analysed root; the scan still "
              "roots at the repo (so excludes and churn windowing are unchanged) "
              "but only files under this subtree are scored, so the treemap "
              "carries no signal from a sibling directory. Omit for a whole-repo "
              "run."),
    )
    args = ap.parse_args()

    root = args.path.resolve()
    if not root.is_dir():
        print(f"error: {root} is not a directory", file=sys.stderr)
        return 1

    scope: Path | None = None
    if args.scope is not None:
        scope = args.scope if args.scope.is_absolute() else (root / args.scope)
        scope = scope.resolve()
        if not scope.exists():
            print(f"error: scope path {scope} does not exist", file=sys.stderr)
            return 1
        if not scope.is_relative_to(root):
            print(f"error: scope path {scope} is not under {root}",
                  file=sys.stderr)
            return 1

    # Resolve user excludes from `.assess/config.toml` first, then layer the
    # CLI `--exclude` on top. Both extend the built-in defaults; the CLI is
    # not "ad-hoc only" - it just doesn't need to be remembered between runs
    # the way the config does. A CLI pattern containing a glob char goes to
    # exclude_patterns; everything else goes to exclude_dirs (so the same
    # `--exclude regulatory-raw` shape works as a dir match without needing
    # the user to pick the right list). `resolve_excludes` is the single shared
    # resolution path - the doc-graph SVG uses it too, so every artifact
    # computes over the identical set (issue #177); the orchestrator drives the
    # read-side scans via the same config - see `assess_core.build_run_context`.
    extra_dirs, extra_patterns = resolve_excludes(root, args.exclude)

    excluded_generated: list[dict] = []
    scc_languages: dict[Path, str] = {}
    fn_names: dict[Path, str] = {}
    fn_backends: dict[Path, str] = {}
    files, effective_by, aux_data, aux_label, fn_ccn_by_path = collect(
        root, by="hotspot", include_artifacts=args.include_artifacts,
        extra_exclude_dirs=extra_dirs,
        extra_exclude_patterns=extra_patterns,
        scope=scop

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "networkx",
#     "numpy",
#     "matplotlib",
# ]
# ///
"""
doc-graph-svg.py - the unified doc map: connectivity by structure, staleness by colour.

This single graph carries both Layer 0 doc signals, with one channel each so
neither is overloaded:

  - **Structure** (position + edges) = navigability. A radial layout rings docs
    by link-distance from the entry point: the navigable core is central, and
    docs no traversal can reach are banished to the rim. Orphans float free;
    islands sit as detached clusters. The topology *is* the reachability story,
    so colour is freed for the other signal.
  - **Colour** = staleness, in the exact grammar of the docs-staleness heatmap:
    hue = days since the doc changed (red = stale), blended toward grey by the
    churn of the code it describes. Vivid red = a frozen doc beside churning
    code = a lying map; pale/grey = stable or low-churn.
  - **Size** = file length (lines).
  - The entry point carries a blue ring so the navigation root is obvious even
    though colour now means staleness.

Reuses ``lib.doc_graph`` (structure) and ``lib.doc_staleness`` (the staleness
metric) so the picture matches the Layer 0 score exactly, and folds the separate
docs-staleness treemap into this one artifact.

Usage:
    uv run skills/assess/scripts/doc-graph-svg.py <path> [-o out.svg]
        [--layout radial|web] [--size lines|centrality] [--colour staleness|status]
"""
from __future__ import annotations

import argparse
import html
import math
import sys
from pathlib import Path

import matplotlib.pyplot as plt
import networkx as nx
import numpy as np

sys.path.insert(0, str(Path(__file__).resolve().parent))
from lib.doc_graph import (  # noqa: E402
    build_doc_graph,
    classify_node,
    group_broken_links,
    radial_shells,
)
from lib.assess_config import load_working_notes_config, resolve_excludes  # noqa: E402
from lib.doc_staleness import analyze_doc_staleness  # noqa: E402
from lib.treemap_render import adaptive_cap, blend_to_grey, rgba_to_hex  # noqa: E402

# Colour-blind-safe by default. The status palette uses the Okabe-Ito set
# (distinguishable under all common colour-vision deficiencies); the staleness
# fill uses the OrRd sequential ramp (CVD-safe, varies in luminance) rather than
# red-green. Markers also carry non-colour cues (rings, dashes) so the graph
# never relies on hue alone.
STALENESS_CMAP = "OrRd"      # pale = fresh/neutral -> dark red = stale lying-map
COLOR_ENTRY = "#0072B2"      # Okabe-Ito blue
COLOR_REACHABLE = "#009E73"  # Okabe-Ito bluish-green
COLOR_ISLAND = "#E69F00"     # Okabe-Ito orange
COLOR_ORPHAN = "#D55E00"     # Okabe-Ito vermillion
EDGE_COLOR = "#9aa0a6"
# Edge kinds. A link is a markdown link; a reference is a backticked doc path
# that names a file on disk. A reference is drawn dotted: dashes already mean the
# ghost tether (4,3) and the orphan and ghost rings (3,2), so a dot pattern is
# the one line style left that collides with neither. Round caps add half the
# stroke width to each end of a dash, so a near-zero dash paints a round dot and
# the 4-unit gap keeps a visible break after the caps take their 1.6 units.
_EDGE_STYLE = {
    "link": {"stroke": EDGE_COLOR, "stroke-dasharray": None,
             "stroke-width": "1.2", "opacity": "0.6"},
    "reference": {"stroke": EDGE_COLOR, "stroke-dasharray": "0.1,4",
                  "stroke-width": "1.6", "opacity": "0.8"},
}
ENTRY_RING = "#0072B2"       # blue ring marks the entry node when colour = staleness
ORPHAN_RING = "#1a1a1a"      # dark dashed ring marks orphans when colour = staleness
# A doc with no staleness measurement: white with grey hatching, outside the
# OrRd ramp and the churn-blend grey, so it never reads as a measured value.
UNMEASURED_FILL = "url(#unmeasured)"
_UNMEASURED_PATTERN = (
    '<pattern id="unmeasured" width="5" height="5" patternUnits="userSpaceOnUse" '
    'patternTransform="rotate(45)"><rect width="5" height="5" fill="#ffffff"/>'
    '<line x1="0" y1="0" x2="0" y2="5" stroke="#8c8c8c" stroke-width="1.6"/></pattern>'
)
GHOST_COLOR = "#CC79A7"      # Okabe-Ito reddish-purple: broken-link "ghost" nodes

W, H = 1600.0, 1000.0
MARGIN = 70.0
R_MIN, R_MAX = 4.0, 24.0


_STATUS_COLOR = {
    "entry": COLOR_ENTRY, "reachable": COLOR_REACHABLE,
    "island": COLOR_ISLAND, "orphan": COLOR_ORPHAN,
}


def _fit_rect(pos: dict, nodes: list[str], rect: tuple[float, float, float, float]) -> dict:
    """Normalise spring-layout coords into a sub-rectangle (x, y, w, h)."""
    rx, ry, rw, rh = rect
    xs = np.array([pos[n][0] for n in nodes])
    ys = np.array([pos[n][1] for n in nodes])
    x0, x1, y0, y1 = xs.min(), xs.max(), ys.min(), ys.max()
    sx = rw / (x1 - x0) if x1 > x0 else 0.0
    sy = rh / (y1 - y0) if y1 > y0 else 0.0
    # Centre when an axis is degenerate (single column/row).
    return {n: (rx + ((pos[n][0] - x0) * sx if sx else rw / 2),
                ry + ((pos[n][1] - y0) * sy if sy else rh / 2)) for n in nodes}


def _grid_positions(nodes: list[str], rect: tuple[float, float, float, float]) -> dict:
    """Lay nodes out in a tidy grid inside (x, y, w, h)."""
    rx, ry, rw, rh = rect
    count = len(nodes)
    if count == 0:
        return {}
    cols = max(1, round(math.sqrt(count * rw / rh)))
    rows = math.ceil(count / cols)
    cw = rw / cols
    ch = rh / max(rows, 1)
    out = {}
    for i, node in enumerate(nodes):
        c, r = i % cols, i // cols
        out[node] = (rx + cw * (c + 0.5), ry + ch * (r + 0.5))
    return out


def _doc_lines(repo_root: Path, rel: str) -> int:
    try:
        return max(1, (repo_root / rel).read_text(encoding="utf-8", errors="ignore").count("\n") + 1)
    except OSError:
        return 1


def _radial_positions(graph, entries: set[str], cx: float, cy: float, fit: float) -> dict:
    """Concentric rings by link-distance from the entry points.

    Centre = entry; ring k = docs k hops away (following links); everything
    unreachable is banished to the outer rings. The picture is the navigability
    claim made literal: the navigable core is central, the lost docs are at the
    rim. The plot is centred at (cx, cy) and scaled to radius `fit`.
    """
    # Shell assignment (the BFS/distance logic) lives in
    # lib.doc_graph.radial_shells, which is unit-tested; here we only turn the
    # shells into x/y coordinates.
    shells = radial_shells(graph, entries)
    if not shells:
        return {}

    raw = nx.shell_layout(graph, nlist=shells, rotate=0.3)
    max_r = max((math.hypot(x, y) for x, y in raw.values()), default=1.0) or 1.0
    return {n: (cx + x / max_r * fit, cy + y / max_r * fit) for n, (x, y) in raw.items()}


def _render_ghosts(broken_links: list[dict], pos: dict, radius,
                   show_labels: bool = False) -> str:
    """Draw one 'ghost' node per missing file — not per broken link. Several links
    to the same absent target (e.g. README.md and CONTRIBUTING.md both pointing at
    a missing CLAUDE.md) collapse to a single ghost they all tether to, so the map
    shows one missing file rather than a cloud of duplicates.

    Each ghost is a hollow dashed circle sitting just outside the centroid of the
    sources that reference it, joined to each by a dashed tether. The missing name
    lives in the hover tooltip; it is only drawn as a text label when
    ``show_labels`` is set, so ghosts read like every other node (clean by
    default, named on hover)."""
    if not broken_links:
        return ""
    out: list[str] = []
    for gi, group in enumerate(group_broken_links(broken_links)):
        key = group["target"]
        sources = [s for s in group["sources"] if s in pos]
        if not sources:
            continue
        # Anchor the shared ghost at the centroid of its sources, pushed radially
        # outward so it clears the cluster; fan distinct ghosts apart.
        cx = sum(pos[s][0] for s in sources) / len(sources)
        cy = sum(pos[s][1] for s in sources) / len(sources)
        ang = 0.6 + gi * 0.9
        off = max(radius(s) for s in sources) + 40
        gx, gy = cx + off * math.cos(ang), cy + off * math.sin(ang)
        for s in sources:
            sx, sy = pos[s]
            out.append(
                f'<line x1="{sx:.1f}" y1="{sy:.1f}" x2="{gx:.1f}" y2="{gy:.1f}" '
                f'stroke="{GHOST_COLOR}" stroke-width="1.2" stroke-dasharray="4,3" opacity="0.85"/>'
            )
        n = len(sources)
        srcs = ", ".join(sources)
        tip = html.escape(
            f"BROKEN LINK ({n} source{'s' if n != 1 else ''})\n"
            f"{srcs} -> {key}\nmissing file: create it or fix the links",
            quote=False)
        out.append(
            f'<circle cx="{gx:.1f}" cy="{gy:.1f}" r="7" fill="#ffffff" '
            f'stroke="{GHOST_COLOR}" stroke-width="1.6" stroke-dasharray="3,2">'
            f'<title>{tip}</title></circle>'
        )
        if show_labels:
            out.append(
                f'<text x="{gx:.1f}" y="{gy - 11:.1f}" font-size="10" fill="{GHOST_COLOR}" '
                f'text-anchor="middle">{html.escape(Path(key).name)}</text>'
            )
    return "\n".join(out)


def _normalize_edge_kind(kind: str) -> str:
    """An edge with no kind, or an unknown one, draws as a link."""
    return kind if kind in _EDGE_STYLE else "link"


def _edge_attrs(kind: str) -> str:
    """Presentation attributes for one edge kind; an unknown kind draws as a link."""
    kind = _normalize_edge_kind(kind)
    style = " ".join(f'{k}="{v}"' for k, v in _EDGE_STYLE[kind].items() if v is not None)
    cap = ' stroke-linecap="round"' if _EDGE_STYLE[kind]["stroke-dasharray"] else ""
    return f'{style}{cap}'


def _edge_legend(mid: float, y: float) -> list[str]:
    """One centred row with a sample line per edge kind, styled as the edges."""
    items = [("link", "link"), ("reference", "reference (backticked path)")]
    out: list[str] = []
    x = mid - 150
    for kind, label in items:
        out.append(f'<line data-legend-kind="{kind}" x1="{x:.0f}" y1="{y - 4:.0f}" '
                   f'x2="{x + 28:.0f}" y2="{y - 4:.0f}" {_edge_attrs(kind)}/>')
        out.append(f'<text x="{x + 34:.0f}" y="{y:.0f}" font-size="13">{label}</text>')
        x += 110
    return out


def render(result, out_path: Path, repo_root: Path, *, layout: str = "radial",  # noqa: C901  # SVG layout + colour-mode branching; ccn 18, ratchet target
           size_mode: str = "lines", colour: str = "staleness",
           staleness: dict | None = None, show_labels: bool = False) -> None:
    graph = result.graph
    nodes = list(graph.nodes())
    n = len(nodes)
    pr = result.pagerank or {x: 1.0 / max(n, 1) for x in nodes}
    in_deg = dict(graph.in_degree())
    out_deg = dict(graph.out_degree())

    entries = set(result.entry_points)
    unreachable = set(result.unreachable)
    orphans = set(result.orphans)

    # Node size metric: file length (lines) or link-graph centrality.
    if size_mode == "lines":
        sizes = {x: _doc_lines(repo_root, x) for x in nodes}
        size_label = "file length (lines)"
    else:
        sizes = {x: pr.get(x, 0.0) for x in nodes}
        size_label = "link-graph centrality"
    size_max = max(sizes.values(), default=1.0) or 1.0

    # Fill colour. Default "staleness" reuses the docs-staleness heatmap grammar
    # (hue = days stale, blended toward grey by the churn of the code the doc
    # describes) so the two doc views speak one colour language. "status" is the
    # older navigability-by-colour mode, kept as an option.
    staleness = staleness or {}
    cmap = plt.get_cmap(STALENESS_CMAP)
    days = {x: float(staleness.get(x, {}).get("last_commit_days") or 0) for x in nodes}
    churn = {x: float(staleness.get(x, {}).get("code_churn_in_window") or 0) for x in nodes}
    # A node the staleness scan never measured (a `.claude/` doc a reference
    # brought in) is hatched, not painted as if a 0d / zero-churn value were known.
    unmeasured = {x: UNMEASURED_FILL for x in nodes if staleness and x not in staleness}
    day_cap, _ = adaptive_cap([days[x] for x in nodes if x not in unmeasured])
    churn_cap, _ = adaptive_cap([churn[x] for x in nodes if x not in unmeasured])

    def fill(node: str) -> str:
        if colour == "status":
            return _STATUS_COLOR[classify_node(node, entries, unreachable, orphans)]
        base = cmap(min(days[node] / day_cap, 1.0) if day_cap else 0.0)
        sat = (churn[node] / churn_cap) if churn_cap else 0.0
        return unmeasured.get(node) or rgba_to_hex(blend_to_grey(base, sat))

    # Canvas: square-ish for the radial layout (it's circular, so a wide canvas
    # wastes the sides); wide for the web two-panel. Header = centred title;
    # footer = centred legend (radial only).
    if layout == "radial":
        cw, ch, header, footer = 1180.0, 1230.0, 92.0, 104.0
    else:
        cw, ch, header, footer = 1600.0, 1000.0, 110.0, 0.0

    pos: dict = {}
    has_isolated = False
    if layout == "radial":
        cx, cy = cw / 2, header + (ch - header - footer) / 2
        fit = min(cw, ch - header - footer) / 2 - R_MAX - 10
        pos = _radial_positions(graph, entries, cx, cy, fit)
    else:
        # Two-panel: linked web (force) + isolated-docs grid.
        linked = [x for x in nodes if in_deg.get(x, 0) + out_deg.get(x, 0) > 0]
        isolated = [x for x in nodes if x not in set(linked)]
        has_isolated = bool(isolated)
        web_right = (0.60 * cw) if has_isolated else (cw - MARGIN)
        web_rect = (MARGIN, 110, web_right - MARGIN, ch - 110 - MARGIN)
        if linked:
            sub = graph.subgraph(linked).to_undirected()
            raw = nx.spring_layout(sub, k=1.2, iterations=250, seed=np.random.RandomState(42))
            pos.update(_fit_rect(raw, linked, web_rect))
        if has_isolated:
            orphan_rect = (web_right + 40, 140, (cw - MARGIN) - (web_right + 40), ch - 140 - MARGIN)
            pos.update(_grid_positions(sorted(isolated), orphan_rect))

    def radius(node: str) -> float:
        return R_MIN + (R_MAX - R_MIN) * math.sqrt(sizes.get(node, 0.0) / size_max)

    parts: list[str] = [
        '<?xml version="1.0" encoding="UTF-8" standalone="no"?>',
        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {cw:.0f} {ch:.0f}" '
        f'width="{cw:.0f}" height="{ch:.0f}" preserveAspectRatio="xMidYMid meet" '
        'role="img">',
        # A11y: <title>/<desc> as the first children of the root <svg> give the
        # image an accessible name and description (SVG accessibility contract).
        '<title>Documentation Navigability Graph</title>',
        '<desc>Graph showing documentation structure, reachability from entry '
        'point, and staleness indicators</desc>',
        '<style>',
        '  text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; fill: #1a1a1a; }',
        '  circle:hover { stroke: #000; stroke-width: 2; }',
        '</style>',
        f'<rect x="0" y="0" width="{cw:.0f}" height="{ch:.0f}" fill="#ffffff"/>',
        '<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" '
        'markerWidth="6" markerHeight="6" orient="auto-start-reverse">'
        f'<path d="M0,0 L10,5 L0,10 z" fill="{EDGE_COLOR}"/></marker></defs>',
    ]

    # Panels: a labelled bin for the isolated docs, separated from the web.
    if has_isolated:
        ox = web_right + 16
        parts.append(
            f'<rect x="{ox:.0f}" y="104" width="{(cw - MARGIN) - ox:.0f}" '
            f'height="{ch - 104 - MARGIN + 16:.0f}" rx="10" fill="#fcf0f0" stroke="#f1c0c0"/>'
        )
        parts.append(
            f'<text x="{ox + 16:.0f}" y="130" font-size="15" font-weight="600" fill="#86181d">'
            f'{len(isolated)} isolated docs — no link in or out</text>'
        )

    # Edges (drawn first, under the nodes). Pull the arrow back to the target rim.
    for u, v, kind in graph.edges(data="kind", default="link"):
        if u not in pos or v not in pos:
            continue
        x1, y1 = pos[u]
        x2, y2 = pos[v]
        dx, dy = x2 - x1, y2 - y1
        dist = math.hypot(dx, dy) or 1.0
        rt = radius(v) + 3
        ex, ey = x2 - dx / dist * rt, y2 - dy / dist * rt
        parts.append(
            f'<line data-edge-kind="{_normalize_edge_kind(kind)}" '
            f'x1="{x1:.1f}" y1="{y1:.1f}" x2="{ex:.1f}" y2="{ey:.1f}" '
            f'{_edge_attrs(kind)} marker-end="url(#arrow)"/>'
        )

    def size_text(node: str) -> str:
        return (f"{sizes.get(node, 0):.0f} lines" if size_mode == "lines"
                else f"centrality {sizes.get(node, 0):.3f}")

    # Nodes. The title (path + stats) lives in a hover tooltip; no inline text.
    label_nodes: list[tuple[float, float, float, str]] = []
    for node in nodes:
        x, y = pos[node]
        r = radius(node)
        status = classify_node(node, entries, unreachable, orphans)
        is_entry = status == "entry"
        # Staleness mode frees colour for staleness, so the entry root and
        # orphans are called out by stroke (a non-colour cue), not fill. A faint
        # grey base stroke keeps pale (fresh) nodes visible on the white canvas.
        dash = ""
        if is_entry:
            stroke, sw = ENTRY_RING, 3.5
        elif colour == "staleness" and status == "orphan":
            stroke, sw, dash = ORPHAN_RING, 1.8, ' stroke-dasharray="3,2"'
        else:
            stroke, sw = "#b8b8b8", 1.0
        days_txt = "" if colour != "staleness" else (
            "staleness not measured" if node in unmeasured
            else f"{days[node]:.0f}d stale, subject churn {churn[node]:.0f}")
        tip = html.escape(
            f"{node}\n{size_text(node)} · in {in_deg.get(node, 0)} · "
            f"out {out_deg.get(node, 0)} · {status}"
            + (f" · {days_txt}" if days_txt else ""),
            quote=False)
        parts.append(
            f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{r:.1f}" fill="{fill(node)}" '
            f'stroke="{stroke}" stroke-width="{sw}"{dash}><title>{tip}</title></circle>'
        )
        # Inline labels are opt-in only (--labels); default is hover-only.
        if show_labels and (is_entry or in_deg.get(node, 0) + out_deg.get(node, 0) > 0):
            label_nodes.append((x, y, r, Path(node).name))

    for x, y, r, name in label_nodes:
        parts.append(
            f'<text x="{x:.1f}" y="{y - r - 3:.1f}" font-size="11" '
            f'text-anchor="middle">{html.escape(name)}</text>'
        )

    parts.append(_render_ghosts(result.broken_links, pos, radius, show_labels))
    parts.append(_title(result, n, cw))
    parts.append(_legend(size_label, layout, colour, cw, ch, footer))
    parts.append('</svg>')
    out_path.write_text("\n".join(parts), encoding="utf-8")

    print(f"wrote {out_path}  ({n} docs, {graph.number_of_edges()} edges, "
          f"{result.island_count} islands)")
    print(f"orphan-rate {result.orphan_rate:.0%}  reachable-from-entry "
          f"{result.reachability_pct:.0%}  entries={sorted(entries)}")


def _title(result, n: int, cw: float) -> str:
    """Two centred lines at the top: headline + one-line stats."""
    mid = cw / 2
    links = len(result.broken_links)
    ghosts = len(group_broken_links(result.broken_links))
    if not links:
        broken_clause = ""
    elif ghosts < links:
        # Several links point at the same absent file; show the link total and
        # the smaller count of distinct missing files they collapse to.
        broken_clause = f' · {links} broken links to {ghosts} missing files'
    else:
        broken_clause = f' · {links} broken links'
    return "\n".join([
        f'<text x="{mid:.0f}" y="40" font-size="24" font-weight="600" '
        f'text-anchor="middle">Doc map — {n} docs, {result.graph.number_of_edges()} '
        f'edges, {result.island_count} islands</text>',
        f'<text x="{mid:.0f}" y="66" font-size="14" fill="#555" text-anchor="middle">'
        f'{result.orphan_rate:.0%} orphaned · {result.reachability_pct:.0%} '
        f'reachable from the entry point'
        + broken_clause
        + '</text>',
    ])


def _legend(size_label: str, layout: str, colour: str, cw: float, ch: float,
            footer: float) -> str:
    """Centred key. For the radial layout it sits in the bottom footer band; for
    the web layout it falls back to a top-left strip."""
    mid = cw / 2
    y = (ch - footer / 2) if footer else 86
    out: list[str] = []
    if colour == "staleness":
        struct = ("rings = link-distance from entry · rim = unreachable"
                  if layout == "radial" else "loose dots = orphans")
        out.append(
            '<defs><linearGradient id="stalegrad" x1="0" y1="0" x2="1" y2="0">'
            '<stop offset="0" stop-color="#fff7ec"/><stop offset="0.5" stop-color="#fc8d59"/>'
            '<stop offset="1" stop-color="#7f0000"/></linearGradient>'
            + _UNMEASURED_PATTERN + '</defs>'
        )
        # Row 1, centred: gradient (flanked by plain words, no arrow glyph that
        # some SVG renderers tofu) + entry + orphan markers.
        gx = mid - 330
        out.append(f'<text x="{gx - 6:.0f}" y="{y - 16:.0f}" font-size="12" fill="#555" '
                   'text-anchor="end">stable</text>')
        out.append(f'<rect x="{gx:.0f}" y="{y - 27:.0f}" width="110" height="12" rx="3" fill="url(#stalegrad)"/>')
        out.append(f'<text x="{gx + 116:.0f}" y="{y - 16:.0f}" font-size="12" fill="#555">lying map</text>')
        ux = mid - 125
        out.append(f'<circle cx="{ux:.0f}" cy="{y - 20:.0f}" r="8" fill="{UNMEASURED_FILL}" '
                   'stroke="#b8b8b8" stroke-width="1"/>')
        out.append(f'<text x="{ux + 14:.0f}" y="{y - 16:.0f}" font-size="13">not measured</text>')
        ex = mid + 10
        out.append(f'<circle cx="{ex:.0f}" cy="{y - 20:.0f}" r="8" fill="#dddddd" stroke="{ENTRY_RING}" stroke-width="3"/>')
        out.append(f'<text x="{ex + 14:.0f}" y="{y - 16:.0f}" font-size="13">entry</text>')
        ox = mid + 105
        out.append(f'<circle cx="{ox:.0f}" cy="{y - 20:.0f}" r="8" fill="#dddddd" stroke="{ORPHAN_RING}" '
                   'stroke-width="2" stroke-dasharray="3,2"/>')
        out.append(f'<text x="{ox + 14:.0f}" y="{y - 16:.0f}" font-size="13">orphan</text>')
        gh = mid + 205
        out.append(f'<circle cx="{gh:.0f}" cy="{y - 20:.0f}" r="8" fill="#ffffff" stroke="{GHOST_COLOR}" '
                   'stroke-width="1.8" stroke-dasharray="3,2"/>')
        out.append(f'<text x="{gh + 14:.0f}" y="{y - 16:.0f}" font-size="13">ghost (broken link)</text>')
        out.extend(_edge_legend(mid, y + 3))
        out.append(f'<text x="{mid:.0f}" y="{y + 20:.0f}" font-size="12" fill="#555" '
                   f'text-anchor="middle">colour = staleness · size = {size_label} · {struct}</text>')
        return "\n".join(out)
    # Status mode: discrete swatches, centred.
    swatches = [(COLOR_ENTRY, "entry"), (COLOR_REACHABLE, "reachable"),
                (COLOR_ISLAND, "island"), (COLOR_ORPHAN, "orphan")]
    total = sum(34 + len(lbl) * 7.2 for _, lbl in swatches)
    x = mid - total / 2
    for color, label in swatches:
        out.append(f'<circle cx="{x + 6:.0f}" cy="{y - 4:.0f}" r="7" fill="{color}"/>')
        out.append(f'<text x="{x + 20:.0f}" y="{y:.0f}" font-size="13">{label}</text>')
        x += 34 + len(label) * 7.2
    out.extend(_edge_legend(mid, y + 24))
    return "\n".join(out)


def main() -> int:
    ap = argparse.ArgumentParser(
        description="Render the doc link-graph as a navigability node diagram.")
    ap.add_argument("path", type=Path, help="Directory to analyse")
    ap.add_argument("-o", "--out", type=Path,
                    help="Output SVG path (default ./doc-graph-<folder>.svg)")
    ap.add_argument("--layout", choices=["radial", "web"], default="radial",
                    help="radial: concentric rings by link-distance from entry "
                         "(rim = unreachable). web: force-directed cluster + "
                         "isolated-docs bin.")
    ap.add_argument("--size", choices=["lines", "centrality"], default="lines",
                    help="Node size metric (default file length in lines).")
    ap.add_argument("--colour", "--color", choices=["staleness", "status"],
                    default="staleness", dest="colour",
                    help="staleness: docs-staleness heatmap grammar (default). "
                         "status: navigability colours (entry/reachable/island/orphan).")
    ap.add_argument("--labels", action="store_true",
                    help="Add inline filename labels (default hover-only).")
    ap.add_argument(
        "--exclude", action="append", default=[], metavar="PATTERN",
        help=("Skip files / directories that match PATTERN. Repeatable. "
              "A plain string (`regulatory-raw`) is treated as a directory "
              "name; a glob (`*.csv`) is matched against the basename. "
              "Extends the built-in defaults. For a durable per-repo list use "
              "`.assess/config.toml` (`exclude_dirs` / `exclude_patterns`); "
              "those are always honoured so the SVG and the scorer compute over "
              "the identical doc set (issue #177)."),
    )
    args = ap.parse_args()

    root = args.path.resolve()
    if not root.is_dir():
        print(f"error: {root} is not a directory", file=sys.stderr)
        return 1

    # Honour the same excludes the scorer applies (`.assess/config.toml` plus
    # any `--exclude`) so the SVG and `lib.doc_graph` compute over the identical
    # doc set rather than reporting different doc counts for one run (issue #177).
    extra_dirs, extra_patterns = resolve_excludes(root, args.exclude)
    working_notes = load_working_notes_config(root)

    result = build_doc_graph(
        root,
        extra_exclude_dirs=extra_dirs,
        extra_exclude_patterns=extra_patterns,
        working_notes_dirs=working_notes.dirs,
        working_notes_ignore=working_notes.ignore,
    )
    if not result.available:
        print(f"error: doc graph unavailable - {result.reason}", file=sys.stderr)
        return 1
    if result.doc_count == 0 or result.graph is None:
        print("error: no docs to graph", file=sys.stderr)
        return 1

    # Staleness data for colour (reuses the same metric as the heatmap).
    staleness_block = analyze_doc_staleness(
        root, doc_to_code_edges=result.doc_to_code_edges,
        extra_exclude_dirs=extra_dirs,
        extra_exclude_patterns=extra_patterns)
    staleness = {d["path"]: d for d in staleness_block.get("docs", [])}

    out = args.out or Path(f"doc-graph-{root.name}.svg")
    render(result, out, root, layout=args.layout, size_mode=args.size,
           colour=args.colour, staleness=staleness,
           show_labels=args.labels)
    return 0


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

"""Shared pytest fixtures.

Hermetic git. The fixtures below build throwaway git repos and assert on
commit *metadata* (authorship, dates, coupling), never on signatures. A git
subprocess inherits the ambient global/system config, and some environments
enable commit signing there (``commit.gpgsign=true`` with an SSH/GPG signing
program, e.g. Claude Code's web sandbox). Signing then fails inside the
disposable test repos and ``git commit`` exits 128 — breaking the whole
git-backed suite in any signing environment while CI (which doesn't sign)
stays green. We neutralise ambient git config for the whole test process at
import time (before any fixture builds a repo) by pointing GIT_CONFIG_GLOBAL
/ GIT_CONFIG_SYSTEM at the null device. Each repo still sets its own local
identity, so commits resolve an author/committer with no global config.
"""
from __future__ import annotations

import datetime as _dt
import os
import subprocess
from pathlib import Path

import pytest

# Applied at import time so it is in effect before any module/session-scoped
# fixture creates a repo. See the module docstring for the why.
os.environ["GIT_CONFIG_GLOBAL"] = os.devnull
os.environ["GIT_CONFIG_SYSTEM"] = os.devnull
os.environ["GIT_CONFIG_NOSYSTEM"] = "1"


@pytest.fixture
def fixtures_dir() -> Path:
    """Path to tests/fixtures/."""
    return Path(__file__).parent / "fixtures"


@pytest.fixture
def tmp_assess_dir(tmp_path: Path) -> Path:
    """A clean .assess/ directory in a temp location."""
    assess_dir = tmp_path / ".assess"
    assess_dir.mkdir()
    (assess_dir / "hotspots").mkdir()
    return assess_dir


def _git(repo: Path, *args: str, env: dict | None = None) -> None:
    full_env = {**os.environ, **(env or {})}
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True, env=full_env)


@pytest.fixture
def git_repo(tmp_path: Path):
    """Create an initialised git repo and return (repo_path, commit_fn).

    commit_fn(message, days_ago=None, committer_days_ago=None) stages everything
    and commits; pass an integer `days_ago` to backdate both author and committer
    time, which lets a test simulate a stale doc beside churning code. Pass
    `committer_days_ago` to backdate the committer time independently of the
    author time - a rebase/cherry-pick keeps the original author time but stamps a
    fresh committer time, so this lets a test prove staleness reads from author
    time (`%at`), not committer time (`%ct`). Git's date env vars reject relative
    strings ("500 days ago"), so we convert to a strict ISO timestamp.
    """
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "test@example.com")
    _git(repo, "config", "user.name", "Test")

    def _stamp(days_ago: int) -> str:
        when = _dt.datetime.now() - _dt.timedelta(days=days_ago)
        return when.strftime("%Y-%m-%dT%H:%M:%S")

    def commit(
        message: str,
        days_ago: int | None = None,
        committer_days_ago: int | None = None,
    ) -> None:
        _git(repo, "add", "-A")
        env = {}
        if days_ago is not None:
            author_stamp = _stamp(days_ago)
            # Committer time defaults to author time; override it to simulate a
            # rebase/cherry-pick, where the commit is re-applied "now" but keeps
            # its original author date.
            committer_at = committer_days_ago if committer_days_ago is not None else days_ago
            env = {
                "GIT_AUTHOR_DATE": author_stamp,
                "GIT_COMMITTER_DATE": _stamp(committer_at),
            }
        _git(repo, "commit", "-q", "-m", message, env=env)

    return repo, commit

"""Golden-baseline normalization for /assess dogfood parity tests.

Phase 0 of the `assess-dogfooded` work captures a full `/assess` run against
this repo as a regression baseline. The decomposition work (Part 3) must prove
the decomposed pipeline reproduces the *same* deterministic output the monolith
produces today - a byte-for-byte parity test against the captured golden.

But a raw `run-context.json` / `assess-report.md` carries fields that change on
every commit and every version bump - the plugin version, the run date, the
measured commit, and the cross-run diff (which depends on whatever prior stats
sidecar happened to be on disk). Comparing those verbatim would make the parity
test fail for reasons unrelated to the decomposition.

So the golden fixtures are stored *normalized*: every volatile field is replaced
with the sentinel below. A parity test regenerates `run-context.json`, runs it
through `normalize_run_context`, and compares against the stored golden - which
was itself produced by this same function. Same transform on both sides → the
only differences that can fail the test are real divergences in the
deterministic computation, which is exactly what Part 3 must not introduce.

Keep this module dependency-free (stdlib only) so it imports cleanly in any test
environment, mirroring the deterministic-core contract.
"""
from __future__ import annotations

import copy
import json
import re
from pathlib import Path
from typing import Any

#: Replaces every volatile scalar. A string sentinel (not ``None``) so a
#: normalized field stays type-stable and visibly intentional in a diff.
SENTINEL = "<<normalized>>"

#: Top-level keys whose entire value is environment- or run-dependent and is
#: therefore replaced wholesale. ``diff`` / ``diff_detail`` depend on which
#: prior stats sidecar was on disk; the version/date keys move every release.
_VOLATILE_TOP_LEVEL = (
    "plugin_version",
    "prior_plugin_version",
    "run_date",
    # run_id is a fresh timestamp+uuid every run (schema_version is stable, so it
    # stays comparable and is NOT masked).
    "run_id",
    "diff",
    "diff_detail",
    "diff_reliable",
    "diff_version_note",
    "prior_stats_exists",
)

#: Sub-keys of ``measured_commit`` that identify the specific commit/work-tree
#: state. ``available`` is preserved (structural), the rest are normalized.
_VOLATILE_MEASURED_COMMIT = (
    "head_sha",
    "head_short",
    "committed_date",
    "subject",
    "dirty",
    "upstream",
    "behind",
)


def normalize_run_context(ctx: dict[str, Any]) -> dict[str, Any]:
    """Return a copy of a ``run-context.json`` dict with volatile fields masked.

    Pure: the input is deep-copied, never mutated. Missing keys are tolerated
    (the schema evolves), so an absent volatile key is simply skipped rather
    than synthesized - the golden then carries no entry for it either.
    """
    out = copy.deepcopy(ctx)

    for key in _VOLATILE_TOP_LEVEL:
        if key in out:
            out[key] = SENTINEL

    mc = out.get("measured_commit")
    if isinstance(mc, dict):
        for key in _VOLATILE_MEASURED_COMMIT:
            if key in mc:
                mc[key] = SENTINEL

    return out


#: The "Generated ..." provenance line at the top of a report. Captures the
#: date and plugin version, both volatile.
_REPORT_GENERATED_RE = re.compile(
    r"^_Generated .*?\._$", re.MULTILINE
)
#: The "Measured at commit" bullet pins absolute figures to a commit + date.
_REPORT_MEASURED_COMMIT_RE = re.compile(
    r"^- \*\*Measured at commit:\*\* .*$", re.MULTILINE
)


def normalize_report(text: str) -> str:
    """Return an ``assess-report.md`` string with volatile lines masked.

    Only the two provenance lines (the ``_Generated ..._`` stamp and the
    ``Measured at commit`` bullet) carry the date/version/commit; the rest of
    the report is deterministic given the deterministic core's output, so it is
    compared verbatim.
    """
    text = _REPORT_GENERATED_RE.sub(f"_Generated {SENTINEL}._", text)
    text = _REPORT_MEASURED_COMMIT_RE.sub(
        f"- **Measured at commit:** {SENTINEL}", text
    )
    return text


def load_golden_run_context() -> dict[str, Any]:
    """Load the normalized golden ``run-context`` baseline."""
    path = Path(__file__).parent / "fixtures" / "golden" / "run-context-baseline.json"
    return json.loads(path.read_text())


def load_golden_report() -> str:
    """Load the normalized golden ``assess-report`` baseline."""
    path = Path(__file__).parent / "fixtures" / "golden" / "assess-report-baseline.md"
    return path.read_text()

# skills/assess/tests

Test suites for the `/assess` deterministic engine. Tests live here, co-located with
the scripts they pin. When a source module changes, its test file is expected to change
in the same commit - this is intentional co-change, not accidental coupling.

## Test/source co-change seam

The suites below are expected to move with the engine. A reviewer seeing
`test_doc_graph.py` and `lib/doc_graph.py` in the same diff is looking at the normal
edit cycle, not a layering violation. Keep tests co-located.

The two highest-frequency co-change pairs in the git history are:

- **`test_assess_core.py` / `assess_core.py`** - the orchestrator and its end-to-end
  harness. Every time the core adds a signal or changes the `run-context.json` schema,
  both files move.
- **`test_doc_graph.py` / `lib/doc_graph.py`** - the navigability graph is the
  foundation for Layer 0 and feeds both the staleness and the understanding analysis,
  so its contract tests are touched on most doc-analysis changes.

---

## Suite / source mapping

### Orchestrator suites

| Suite | Pins |
|---|---|
| `test_assess_core.py` | `scripts/assess_core.py` - end-to-end orchestrator; drives `build_run_context` without running lizard/scc |
| `test_assess_finalize.py` | `scripts/assess_finalize.py` - LLM write-back; placeholder substitution in `log.md` and `hotspots/*.md` |
| `test_assess_gate.py` | `scripts/assess_gate.py` - CI regression gate; complexity and containment threshold checks and exit codes |
| `test_assess_report.py` | `scripts/assess_report.py` - deterministic report renderer; template substitution, section renderers, conditional fallbacks |
| `test_emit_workflow.py` | `scripts/assess_emit_workflow.py` - CLI wrapper for the frozen-harness workflow emitter; default derivation, arg parsing, path filters and the path-filter default |
| `test_decomposition_parity.py` | `scripts/assess_core.py` + `scripts/assess_report.py` - parity harness; guards that the deterministic pipeline produces byte-for-byte identical output after the Part 3 SKILL.md decomposition |
| `test_complexity_treemap.py` | `scripts/complexity-treemap.py` - build-artifact filter, plugin version stamp, and stats-sidecar enrichment (heavy deps are stubbed) |

### lib/ suites

| Suite | Pins |
|---|---|
| `test_doc_graph.py` | `lib/doc_graph.py` - doc link-graph, link parsing, orphan detection, connectivity, MOC validation, doc->code edges |
| `test_keyhole_signals.py` | `lib/keyhole_signals.py` - integration barrier; derivation of the five run-context blocks and the six named derived findings from mocked upstream signal outputs |
| `test_change_coupling.py` | `lib/change_coupling.py` - B1 change-coupling pairs, B2 containment ratio, B4 authorship; synthetic git histories built in tmp dirs |
| `test_coupling_analysis.py` | `lib/coupling_analysis.py` - B3 static-vs-historical disagreement; hidden-coupling, bleeding-module, and refactor-boundary classification with mocked inputs |
| `test_doc_complexity_join.py` | `lib/doc_complexity_join.py` - Signal C: doc_value formula, slop-doc guard, threshold behaviour; mocked complexity-stats and staleness inputs |
| `test_doc_staleness.py` | `lib/doc_staleness.py` - doc->code association (base-doc, parallel docs/, code links, repo-wide fallback) and churn-relative staleness ratios |
| `test_structure_graph.py` | `lib/structure_graph.py` - A1 footprint additivity, A2 SCCs and Q range, A3 front-door vs burrow, A4 cut-lines, graceful degradation |
| `test_understanding_analysis.py` | `lib/understanding_analysis.py` - B4 human anchor + intent source, velocity clock (D2), orphaned-understanding classification; both pure-logic (mocked) and git-integration variants |
| `test_liveness_scan.py` | `lib/liveness_scan.py` - dead-code tool output parsers, observability rungs, graceful degradation when tools are absent |
| `test_test_pressure.py` | `lib/test_pressure/` - mutation tier output parsing, cheap heuristics (test/source ratio, assertion density, gap signal) |
| `test_ci_workflow.py` | `lib/ci_workflow.py` - template substitution (version, branch, tool steps, path filters), path-filtered workflow detection, literal-dollar escaping, YAML well-formedness |
| `test_stats_diff.py` | `lib/stats_diff.py` - hotspot transition classification (graduated, regressed, new, persistent) and sidecar loading |
| `test_wiki_writer.py` | `lib/wiki_writer.py` - wiki file rendering (index, log, hotspot pages) and HotspotEntry / LogEntry dataclass behaviour |
| `test_git_commit_info.py` | `lib/git_churn.py` (`git_commit_info`) - commit snapshot with SHA/timestamp for staleness warnings |
| `test_instruction_bloat.py` | `lib/agent_instructions_grader.py` - bloat penalty, skills-delegation credit, conservative thresholds |

### Infrastructure suites

| Suite | Pins |
|---|---|
| `test_smoke.py` | `lib/__init__.py` - confirms the lib package is importable and `__version__` is set |
| `test_golden_baseline.py` | `tests/golden.py` + dogfood fixtures - guards the regression baseline scaffolding (fixture completeness, normalization idempotency, loader correctness) used by `test_decomposition_parity.py` |

---

## Running the suite

```bash
# From skills/assess/ - avoids ~7 phantom git-commit failures from global git config
GIT_CONFIG_GLOBAL=/dev/null uv run --with pytest pytest tests/ -v
```

The phantom failures are a local-only artifact of global git commit-template or hook
configuration. They do not appear in CI.

"""Comprehensive contract suite for the accretion-ratchet scanner.

Fixtures build synthetic git histories in tmp dirs; expected values are
hand-computed in each test's docstring so the contract is auditable. The
scanner's job is to flag files whose accumulated line count only ever ratchets
upward - net growth *with almost no deletion pressure* across multiple commits -
while leaving healthy churn, renames, binaries, and single-touch artifacts
alone. These tests pin that behaviour and, crucially, the determinism contract:
the author-time ordering must make the output byte-identical run to run.

Author/committer identity and dates are pinned in every fixture commit so the
``%at`` ordering and the resulting net-delta accumulation are reproducible on
CI. The ambient git config is already neutralised process-wide by the package
``conftest.py`` (GIT_CONFIG_GLOBAL/SYSTEM -> /dev/null), so commits never trip
ambient signing.
"""
from __future__ import annotations

import json
import os
import subprocess
from pathlib import Path

import lib.accretion_ratchet as ar
from lib.accretion_ratchet import (
    DELETION_FRACTION_THRESHOLD,
    MIN_COMMITS_FOR_ACCRETION,
    AccretionFile,
    _accumulate_history,
    _build_accretion_file,
    _FileHistory,
    _is_monotonic_nondecreasing,
    _repo_top,
    scan_accretion_ratchet,
)

# A fixed clock so every commit's author/committer time is deterministic. Each
# commit advances the clock by one day, which both pins the ``%at`` sort order
# and gives the time-span readout a known value.
_BASE_EPOCH = 1_700_000_000  # 2023-11-14T22:13:20Z
_DAY = 86_400


def _git(repo: Path, *args: str, env: dict | None = None) -> None:
    full_env = {**os.environ, **(env or {})}
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True, env=full_env)


def _init_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "dev@example.com")
    _git(repo, "config", "user.name", "Dev Human")
    return repo


class _Clock:
    """Monotone per-commit clock: each call returns the next day's epoch.

    Pinning author *and* committer time to the same advancing value makes the
    scanner's ``(author_time, sha)`` sort fully determined by commit order, so
    the accumulation sequence - and the flagged output - is reproducible.
    """

    def __init__(self) -> None:
        self._n = 0

    def env(self) -> dict[str, str]:
        stamp = f"{_BASE_EPOCH + self._n * _DAY} +0000"
        self._n += 1
        return {
            "GIT_AUTHOR_DATE": stamp,
            "GIT_COMMITTER_DATE": stamp,
        }


def _commit(repo: Path, rel: str, text: str, clock: _Clock,
            message: str = "change") -> None:
    """Write ``text`` to ``rel``, stage, and commit at the clock's next tick."""
    p = repo / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", message, env=clock.env())


def _lines(n: int, *, start: int = 0, width: int = 12) -> str:
    """A file body of ``n`` distinct lines (distinct so numstat counts churn).

    Each line is unique and ``width`` chars wide, so replacing the body deletes
    the old lines and adds the new ones - a real numstat delta, not a no-op.
    """
    return "".join(f"L{i + start:0{width}d}\n" for i in range(n))


def _flagged_paths(repo: Path, **kw) -> list[str]:
    return [f.path for f in scan_accretion_ratchet(repo, **kw).files]


# --- 1. Deletion-fraction discrimination -------------------------------------

def test_deletion_fraction_discriminates_refactor_from_ratchet(tmp_path: Path) -> None:
    """A healthy refactor is spared; a pure ratchet is flagged.

    Two files, three commits each (clearing the multi-commit gate):

    * ``refactor.py`` - grows then is reworked: 2000 lines added, 1500 deleted
      across its history => deletion fraction 1500 / 3500 = 0.4286, far above the
      0.15 default. Maintained by rewriting, so it is NOT flagged - regardless of
      whether its net drifts up.
    * ``ratchet.py`` - appended to only: 510 added, 10 deleted => 10 / 520 =
      0.0192, well below 0.15, and its running net never falls back. Flagged.

    Only the ratchet should surface.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # ratchet.py: append-only growth. Verified numstat per commit below.
    #   c1: write 200 lines               -> +200 / -0   (net 200)
    #   c2: keep 200, append 200          -> +200 / -0   (net 400)
    #   c3: rewrite 10 lines in place,
    #       append 110 more               -> +120 / -10  (net 510)
    # Totals: 520 added, 10 deleted => fraction 10 / 530 = 0.0189 < 0.15.
    # Running net 200 -> 400 -> 510 is monotonic. Flagged.
    _commit(repo, "ratchet.py", _lines(200), clock)
    _commit(repo, "ratchet.py", _lines(200) + _lines(200, start=200), clock)
    body = (_lines(190) + _lines(10, start=9000)
            + _lines(200, start=200) + _lines(110, start=400))
    _commit(repo, "ratchet.py", body, clock)

    # refactor.py: heavy churn. Grow big, then rewrite large swaths so deletions
    # are a large share of total churn.
    _commit(repo, "refactor.py", _lines(1000), clock)
    _commit(repo, "refactor.py", _lines(500, start=10000) + _lines(500, start=2000), clock)
    _commit(repo, "refactor.py", _lines(1000, start=20000), clock)

    scan = scan_accretion_ratchet(repo)
    flagged = {f.path for f in scan.files}

    assert "ratchet.py" in flagged
    assert "refactor.py" not in flagged
    # The ratchet's deletion fraction is well under the default threshold.
    ratchet = next(f for f in scan.files if f.path == "ratchet.py")
    assert ratchet.deletion_fraction < DELETION_FRACTION_THRESHOLD
    assert ratchet.net_additions > 0


# --- 2. Rename handling ------------------------------------------------------

def test_rename_is_not_flagged_as_accretion(tmp_path: Path) -> None:
    """A create -> rename -> add sequence is not a ratchet.

    With ``--no-renames`` (the scanner's mode) a rename reads as a full delete of
    the old path plus a full add of the new path. The old path nets to zero (and
    is filtered: net <= 0). The new path appears in only one commit (the rename
    itself) and would need ``MIN_COMMITS_FOR_ACCRETION`` (3) touches to qualify;
    the single later edit gives it two, still under the gate. So neither path is
    flagged - the rename produces no false positive.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    _commit(repo, "old_name.py", _lines(300), clock, "create")
    # Rename: git mv, content unchanged. Under --no-renames this is del old / add new.
    _git(repo, "mv", "old_name.py", "new_name.py")
    _git(repo, "commit", "-q", "-m", "rename", env=clock.env())
    # One later edit under the new name.
    _commit(repo, "new_name.py", _lines(300) + _lines(50, start=300), clock, "extend")

    flagged = _flagged_paths(repo)
    assert "old_name.py" not in flagged
    assert "new_name.py" not in flagged


# --- 3. Degenerate history ---------------------------------------------------

def test_squashed_history_is_available_but_unreliable(tmp_path: Path) -> None:
    """One commit touching many files => available True, reliable False.

    A squashed import gives every file exactly one commit, so the per-file
    commit-count distribution is flat (p95 == 1) over enough active files
    (>= MIN_ACTIVE_FILES_FOR_DEGENERACY = 5). ``churn_is_degenerate`` returns
    True, so the scan reports ``reliable=False`` while still being ``available``.
    No file clears the 3-commit gate, so nothing is flagged either.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    files = {f"mod/f{i}.py": _lines(100 + i) for i in range(8)}
    for rel, text in files.items():
        p = repo / rel
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(text, encoding="utf-8")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "squashed import", env=clock.env())

    scan = scan_accretion_ratchet(repo)
    assert scan.available is True
    assert scan.reliable is False
    assert scan.files == []


# --- 4. Binary file guard ----------------------------------------------------

def test_binary_files_are_skipped(tmp_path: Path) -> None:
    """A binary file (numstat ``-``) carries no line signal and is not flagged.

    Git emits ``-\t-\t<path>`` for binary content; the parser skips rows whose
    add/remove columns are not digits. Even committed repeatedly (clearing the
    multi-commit gate), the binary never accumulates additions, so it can never
    appear in the flagged set. A text file committed alongside it under pure
    accretion still surfaces - proving the binary is skipped, not the whole
    commit.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    def write_binary(rel: str, n: int) -> None:
        # NUL bytes force git to treat the blob as binary (numstat '-').
        (repo / rel).write_bytes(bytes([0, 1, 2, 255] * n))

    for i in range(1, 4):
        write_binary("asset.bin", 100 * i)
        # A text file that only grows, committed in the same commits.
        (repo / "grow.py").write_text(_lines(200 * i), encoding="utf-8")
        _git(repo, "add", "-A")
        _git(repo, "commit", "-q", "-m", f"c{i}", env=clock.env())

    scan = scan_accretion_ratchet(repo)
    flagged = {f.path for f in scan.files}
    assert "asset.bin" not in flagged
    # The accompanying append-only text file is flagged, so the commits were
    # scanned - the binary was filtered specifically.
    assert "grow.py" in flagged


# --- 5. Ordering reproducibility ---------------------------------------------

def test_scan_output_is_byte_identical_across_runs(tmp_path: Path) -> None:
    """Two scans of one repo serialize to byte-identical JSON.

    The scanner sorts history on ``(author_time, sha)`` rather than trusting
    git's emission order, so the net-delta accumulation - and the flagged set,
    its order, and every field - must be reproducible. This pins that contract:
    serialize the full summary twice and assert exact equality.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # A handful of files with varied histories so the flagged set is non-trivial.
    for i in range(1, 5):
        _commit(repo, "a.py", _lines(100 * i), clock)
    for i in range(1, 4):
        _commit(repo, "b.py", _lines(80 * i, start=900), clock)
    for i in range(1, 4):
        # A churny file that should be excluded - keeps the sort non-trivial.
        _commit(repo, "c.py", _lines(50, start=i * 1000), clock)

    first = json.dumps(scan_accretion_ratchet(repo).summary(), sort_keys=True)
    second = json.dumps(scan_accretion_ratchet(repo).summary(), sort_keys=True)
    assert first == second
    # And the flagged set is actually populated, so equality isn't vacuous.
    assert scan_accretion_ratchet(repo).files


# --- 6. Multi-commit gate ----------------------------------------------------

def test_single_commit_growth_is_not_flagged(tmp_path: Path) -> None:
    """A file that grows large in one commit is below the multi-commit gate.

    Accretion is a property of *repeated* growth: a file appearing in fewer than
    ``MIN_COMMITS_FOR_ACCRETION`` (3) commits is filtered, even if that single
    commit adds a thousand lines and deletes nothing (a perfect-looking ratchet
    in miniature). This guards against a one-shot generated file reading as
    accretion. Other files in the repo provide enough history that the scan is
    reliable, isolating the gate as the reason this file is spared.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # Background history so the repo isn't degenerate (>=5 active, multi-commit).
    for i in range(1, 4):
        _commit(repo, "background.py", _lines(40 * i, start=7000), clock)
    for name in ("p.py", "q.py", "r.py", "s.py"):
        for i in range(1, 4):
            _commit(repo, name, _lines(20 * i, start=8000), clock)

    # The file under test: one commit, large append-only body, zero deletions.
    _commit(repo, "oneshot.py", _lines(1000), clock, "generated in one shot")

    flagged = _flagged_paths(repo)
    assert "oneshot.py" not in flagged


def test_two_commit_growth_is_not_flagged(tmp_path: Path) -> None:
    """Exactly MIN_COMMITS_FOR_ACCRETION - 1 touches is still below the gate.

    The boundary: a monotonically growing, zero-deletion file touched in only
    two commits must not be flagged, while the same pattern at three commits is.
    This pins the gate at its exact threshold.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # Two-commit grower: must NOT be flagged.
    _commit(repo, "two.py", _lines(100), clock)
    _commit(repo, "two.py", _lines(200), clock)

    # Three-commit grower with the same shape: MUST be flagged, proving the gate
    # is the only thing keeping two.py out.
    _commit(repo, "three.py", _lines(100, start=300), clock)
    _commit(repo, "three.py", _lines(200, start=300), clock)
    _commit(repo, "three.py", _lines(300, start=300), clock)

    flagged = _flagged_paths(repo)
    assert "two.py" not in flagged
    assert "three.py" in flagged
    assert MIN_COMMITS_FOR_ACCRETION == 3


# --- Monotonicity: a late cut clears the flag --------------------------------

def test_late_refactor_clears_the_ratchet(tmp_path: Path) -> None:
    """A file that grows, then is cut back below an earlier high, is not flagged.

    Monotonicity is judged off the running net-delta sequence, not the
    endpoints. Three growth commits push net up; a fourth deletes enough to drop
    net below an earlier value. That single step down breaks the ratchet even
    though the file still has a positive net - the deletion pressure the signal
    rewards. (Deletions here also stay a small share of churn, so it is the
    monotonicity test, not the deletion-fraction filter, doing the work.)
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # Grow: net climbs 300 -> 600 -> 900.
    _commit(repo, "f.py", _lines(300), clock)
    _commit(repo, "f.py", _lines(600), clock)
    _commit(repo, "f.py", _lines(900), clock)
    # Cut: drop to 250 lines. Net falls to 250, below the first commit's 300.
    # This single backward step makes the sequence non-monotonic.
    _commit(repo, "f.py", _lines(250), clock)

    # Provide background so the scan is reliable and f.py is the only variable.
    for name in ("x.py", "y.py", "z.py", "w.py"):
        for i in range(1, 4):
            _commit(repo, name, _lines(15 * i, start=9000), clock)

    flagged = _flagged_paths(repo)
    assert "f.py" not in flagged


# --- 7. Self-test on the assess repo ----------------------------------------

def test_self_scan_on_assess_repo_is_well_formed(tmp_path: Path) -> None:
    """Scanning this repo's own history produces only well-formed flags.

    A dogfood guard run against real, human-maintained history. The repo *does*
    contain files whose net line count has only ever grown (a test suite that
    keeps gaining cases, a reference doc that keeps gaining sections) - that is
    not a false positive, it is the signal working on real data. What must hold
    is that every flagged record honestly satisfies the definition it claims:
    positive net additions, at least ``MIN_COMMITS_FOR_ACCRETION`` commits, and a
    deletion fraction strictly under the threshold the scan reports. A "false
    positive" here would be a record that is flagged while violating its own
    contract - that is what this rules out. The scanner may degrade to
    unavailable in a packaging context with no git history; that is acceptable.

    The flagged set must also be deterministically sorted (net descending, path
    ascending) - the same ordering contract the byte-identical test pins, checked
    here against real history rather than a fixture.
    """
    repo_root = Path(__file__).resolve().parents[1]  # skills/assess/
    scan = scan_accretion_ratchet(repo_root)

    if not scan.available:
        # No git history reachable (e.g. exported tree) - nothing to assert.
        return

    for f in scan.files:
        # Every flagged record must satisfy the contract it claims.
        assert f.net_additions > 0, f
        assert f.commit_count >= MIN_COMMITS_FOR_ACCRETION, f
        assert f.deletion_fraction < scan.deletion_fraction_threshold, f
        assert 0.0 <= f.deletion_fraction < 1.0, f
        assert f.time_span_months >= 0.0, f

    # Sorted by net additions descending, then path ascending - the public
    # ordering contract, holding on real history.
    keys = [(-f.net_additions, f.path) for f in scan.files]
    assert keys == sorted(keys)


# --- AccretionFile field contract --------------------------------------------

def test_accretion_file_fields_and_to_dict(tmp_path: Path) -> None:
    """A flagged file's fields and ``to_dict`` rounding match the contract.

    Five append-only commits over four days (one per clock tick) to a single
    growing file. net_additions is the final additions - deletions; commit_count
    is the touch count; deletion_fraction rounds to 4 dp in ``to_dict`` and
    time_span_months rounds to 1 dp. The span is 4 days (first to fifth commit) /
    30.44 ~= 0.13 months -> rounds to 0.1.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # Five commits, pure append, no deletions.
    for i in range(1, 6):
        _commit(repo, "grow.py", _lines(100 * i), clock)
    # Background so the scan is reliable.
    for name in ("a.py", "b.py", "c.py", "d.py"):
        for i in range(1, 4):
            _commit(repo, name, _lines(10 * i, start=5000), clock)

    scan = scan_accretion_ratchet(repo)
    grow = next((f for f in scan.files if f.path == "grow.py"), None)
    assert grow is not None
    assert isinstance(grow, AccretionFile)
    assert grow.commit_count == 5
    assert grow.net_additions == 500  # 100..500 added, nothing removed
    assert grow.deletion_fraction == 0.0

    d = grow.to_dict()
    assert d["path"] == "grow.py"
    assert d["net_additions"] == 500
    assert d["commit_count"] == 5
    assert d["deletion_fraction"] == 0.0
    # round(x, 1) on the to_dict span: keys present and numeric.
    assert isinstance(d["time_span_months"], float)


# --- Threshold sensitivity (as-merged semantics) -----------------------------

def test_caller_threshold_is_honored_end_to_end(tmp_path: Path) -> None:
    """The caller's deletion_threshold is the cut actually applied by the scan.

    Builds a file at deletion fraction ~0.20: 400 lines added, 100 deleted
    across the history (100 / 500 = 0.20), monotonic, multi-commit. At the 0.15
    default it is dropped (0.20 >= 0.15). At ``deletion_threshold=0.30`` it is
    admitted (0.20 < 0.30) - and the reported threshold on the scan matches the
    one applied. This is the end-to-end form of the task-1-fix regression: the
    caller's value is honored, not a hard-coded module constant.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()

    # c1: write 200 lines                 -> +200 / -0   (net 200)
    # c2: keep 200, append 200             -> +200 / -0   (net 400)
    # c3: keep first 300, replace last 100 -> +100 / -100 (net 400, still up)
    # Totals: 500 added, 100 deleted => fraction 100 / 600 = 0.1667, just over the
    # 0.15 default. Running net 200 -> 400 -> 400 is monotonic non-decreasing.
    _commit(repo, "g.py", _lines(200), clock)
    _commit(repo, "g.py", _lines(400), clock)
    body = _lines(300) + _lines(100, start=99000)
    _commit(repo, "g.py", body, clock)

    # Background history so the scan is reliable.
    for name in ("h.py", "i.py", "j.py", "k.py"):
        for i in range(1, 4):
            _commit(repo, name, _lines(10 * i, start=6000), clock)

    # Measure g.py's real deletion fraction (threshold 1.0 admits everything)
    # so the assertions can bracket the threshold around it.
    full = scan_accretion_ratchet(repo, deletion_threshold=1.0)
    g_full = next(f for f in full.files if f.path == "g.py")
    frac = g_full.deletion_fraction
    assert frac > DELETION_FRACTION_THRESHOLD  # excluded at the default

    # Below the file's fraction -> dropped; the reported threshold is the cut used.
    below = scan_accretion_ratchet(repo, deletion_threshold=frac - 0.01)
    assert below.deletion_fraction_threshold == frac - 0.01
    assert all(f.path != "g.py" for f in below.files)

    # Above the file's fraction -> admitted.
    above = scan_accretion_ratchet(repo, deletion_threshold=frac + 0.01)
    assert any(f.path == "g.py" for f in above.files)


# --- Availability degrade -----------------------------------------------------

def test_non_git_directory_is_unavailable(tmp_path: Path) -> None:
    """A plain directory (not a git repo) degrades to available=False, never raises."""
    plain = tmp_path / "nogit"
    plain.mkdir()
    (plain / "a.py").write_text(_lines(50), encoding="utf-8")

    scan = scan_accretion_ratchet(plain)
    assert scan.available is False
    assert scan.files == []
    assert scan.reason


def test_empty_repo_has_no_commit_history(tmp_path: Path) -> None:
    """An initialised repo with zero commits reports 'no commit history'.

    ``_accumulate_history`` returns an empty map (git log fails on a repo with no
    HEAD), which the scanner reports as unavailable rather than a clean scan.
    """
    repo = _init_repo(tmp_path)  # init + config, but no commit yet
    scan = scan_accretion_ratchet(repo)
    assert scan.available is False
    assert scan.reason == "no commit history"


def test_scan_degrades_when_accumulate_raises(tmp_path: Path, monkeypatch) -> None:
    """An unexpected error inside the pipeline degrades to available=False.

    The pipeline is wrapped so the deterministic core never crashes its caller.
    Forcing ``_accumulate_history`` to raise must surface as a degraded scan with
    the exception type in the reason, not a propagated traceback.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()
    _commit(repo, "a.py", _lines(10), clock)

    def boom(_repo_top: str) -> dict:
        raise RuntimeError("synthetic failure")

    monkeypatch.setattr(ar, "_accumulate_history", boom)
    scan = scan_accretion_ratchet(repo)
    assert scan.available is False
    assert "RuntimeError" in scan.reason
    assert "synthetic failure" in scan.reason


# --- internal helpers --------------------------------------------------------

def test_repo_top_resolves_and_rejects_non_repo(tmp_path: Path) -> None:
    """``_repo_top`` returns the toplevel inside a repo, None outside one."""
    repo = _init_repo(tmp_path)
    clock = _Clock()
    _commit(repo, "a.py", _lines(3), clock)
    # Resolves to the repo top from a subdirectory.
    sub = repo / "pkg"
    sub.mkdir()
    top = _repo_top(sub)
    assert top is not None
    assert Path(top).resolve() == repo.resolve()

    plain = tmp_path / "plain"
    plain.mkdir()
    assert _repo_top(plain) is None


def test_is_monotonic_nondecreasing_edge_cases() -> None:
    """Empty / single-point sequences are vacuously monotonic; a dip is not."""
    assert _is_monotonic_nondecreasing([]) is True
    assert _is_monotonic_nondecreasing([5]) is True
    assert _is_monotonic_nondecreasing([1, 1, 2, 3]) is True
    assert _is_monotonic_nondecreasing([1, 2, 1]) is False


def test_build_accretion_file_filters() -> None:
    """The promote-to-AccretionFile filters each reject for the documented reason."""
    # Below the multi-commit gate.
    assert _build_accretion_file(
        "f", _FileHistory(additions=100, deletions=0, commit_count=2,
                          net_sequence=[50, 100]), 0.15) is None
    # Zero total churn (no add, no del) - guarded before the division.
    assert _build_accretion_file(
        "f", _FileHistory(additions=0, deletions=0, commit_count=3,
                          net_sequence=[0, 0, 0]), 0.15) is None
    # Deletion fraction at/over threshold.
    assert _build_accretion_file(
        "f", _FileHistory(additions=80, deletions=20, commit_count=3,
                          net_sequence=[20, 40, 60]), 0.15) is None
    # Net <= 0 with a permissive threshold: a file with equal add/delete churn
    # (fraction 0.5) clears a 0.6 threshold but nets to zero, so the net<=0 guard
    # is what rejects it - distinct from the deletion-fraction filter above.
    assert _build_accretion_file(
        "f", _FileHistory(additions=10, deletions=10, commit_count=3,
                          net_sequence=[0, 0, 0]), 0.6) is None
    # Non-monotonic running net (a dip) clears the flag.
    assert _build_accretion_file(
        "f", _FileHistory(additions=300, deletions=10, commit_count=3,
                          net_sequence=[100, 50, 290]), 0.15) is None
    # A clean accretor passes and carries the right fields.
    ok = _build_accretion_file(
        "f", _FileHistory(additions=300, deletions=10, commit_count=3,
                          first_time=_BASE_EPOCH, last_time=_BASE_EPOCH + _DAY,
                          net_sequence=[100, 200, 290]), 0.15)
    assert ok is not None
    assert ok.net_additions == 290
    assert ok.commit_count == 3


def test_accumulate_history_skips_binary_and_malformed(tmp_path: Path) -> None:
    """``_accumulate_history`` skips binary rows and never indexes them.

    A repo with a binary file and a text file: the returned history map contains
    the text path with real line counts and omits the binary path entirely
    (its numstat rows are ``-``, filtered at parse time).
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()
    (repo / "data.bin").write_bytes(bytes([0, 1, 2, 255] * 50))
    (repo / "code.py").write_text(_lines(40), encoding="utf-8")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "c1", env=clock.env())

    top = _repo_top(repo)
    assert top is not None
    hist = _accumulate_history(top)
    assert "code.py" in hist
    assert hist["code.py"].additions == 40
    assert "data.bin" not in hist


def test_accumulate_history_on_non_repo_returns_empty(tmp_path: Path) -> None:
    """git log failing (not a repo path) yields an empty history map, no raise."""
    plain = tmp_path / "plain"
    plain.mkdir()
    assert _accumulate_history(str(plain)) == {}


def test_accumulate_history_skips_malformed_records(monkeypatch) -> None:
    """Malformed commit records are skipped, not allowed to corrupt the map.

    Feeds ``_accumulate_history`` a hand-built git-log payload with three records:
    a header with no SHA (one field -> skipped at the len check), a header whose
    timestamp is non-numeric (ValueError -> skipped), and one well-formed commit.
    Only the good commit's file survives, proving the two parse guards skip rather
    than crash. ``\x1e`` opens each record; rows are ``added\tremoved\tpath``.
    """
    RS = "\x1e"
    payload = (
        f"{RS}1700000000\n"               # header missing the SHA -> len(header)!=2
        "5\t0\torphan.py\n"
        f"{RS}notanumber abc123\n"         # non-numeric author time -> ValueError
        "9\t0\tbadtime.py\n"
        f"{RS}1700100000 deadbeef\n"       # well-formed
        "40\t2\tgood.py\n"
    )

    class _Result:
        stdout = payload

    monkeypatch.setattr(ar.subprocess, "run", lambda *a, **k: _Result())
    hist = _accumulate_history("/irrelevant")
    assert set(hist) == {"good.py"}
    assert hist["good.py"].additions == 40
    assert hist["good.py"].deletions == 2


# --- CLI ---------------------------------------------------------------------

def test_cli_reports_offenders_and_writes_json(tmp_path: Path, capsys, monkeypatch) -> None:
    """``main()`` scans, prints the offender readout, and writes the JSON sidecar.

    Drives the CLI entry point on a real repo with one append-only file. Exit
    code 0 on a successful scan; the JSON file matches the printed summary; the
    offender line for the flagged file appears in stdout.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()
    for i in range(1, 5):
        _commit(repo, "grow.py", _lines(100 * i), clock)

    out_json = tmp_path / "out.json"
    monkeypatch.setattr(
        "sys.argv",
        ["accretion_ratchet.py", str(repo), "--json", str(out_json)],
    )
    rc = ar.main()
    assert rc == 0

    printed = capsys.readouterr().out
    assert "accreting files:" in printed
    assert "grow.py" in printed

    data = json.loads(out_json.read_text())
    assert data["available"] is True
    assert data["total_accreting"] >= 1
    assert any(f["path"] == "grow.py" for f in data["top_offenders"])
    assert "elapsed_seconds" in data


def test_cli_returns_nonzero_when_unavailable(tmp_path: Path, capsys, monkeypatch) -> None:
    """``main()`` exits non-zero and prints the reason on an unavailable scan."""
    plain = tmp_path / "plain"
    plain.mkdir()
    monkeypatch.setattr("sys.argv", ["accretion_ratchet.py", str(plain)])
    rc = ar.main()
    assert rc == 1
    assert "unavailable" in capsys.readouterr().out


# --- Documentation files are not accretion -----------------------------------

def test_accretion_skips_documentation_append_only_markdown(tmp_path: Path) -> None:
    """A 3,000-line append-only markdown plan earns no accretion entry.

    ``notes/PLAN.md`` grows by 1,000 lines in each of three commits with no
    deletions (fraction 0.0, monotonic), the exact accretion fingerprint. A plan
    that grows by appending carries no change risk, so the scanner skips
    documentation extensions. ``src/big.py`` grows the same way and is still
    flagged, so the filter is by file type, not by growth shape.
    """
    repo = _init_repo(tmp_path)
    clock = _Clock()
    for i in range(1, 4):
        _commit(repo, "notes/PLAN.md", _lines(1000 * i), clock)
        _commit(repo, "src/big.py", _lines(100 * i, start=50000), clock)

    assert (repo / "notes" / "PLAN.md").read_text().count("\n") == 3000
    flagged = _flagged_paths(repo)
    assert "notes/PLAN.md" not in flagged
    assert "src/big.py" in flagged


def test_accretion_skips_documentation_every_doc_suffix() -> None:
    """Every documentation suffix is rejected, case-insensitively; code is not."""
    hist = _FileHistory(additions=900, deletions=0, commit_count=3,
                        first_time=0, last_time=86_400,
                        net_sequence=[300, 600, 900])
    for path in ("a.md", "b.MD", "c.markdown", "d.mdx", "e.rst", "g.adoc"):
        assert _build_accretion_file(path, hist, DELETION_FRACTION_THRESHOLD) is None
    # .txt is not documentation here: build logic and manifests accrete for real.
    for path in ("a.py", "b.dart", "c.js", "Makefile", "CMakeLists.txt",
                 "requirements.txt"):
        assert _build_accretion_file(path, hist, DELETION_FRACTION_THRESHOLD) is not None

"""Regression: the caller's --deletion-threshold is the cut actually applied.

`_build_accretion_file` once hard-coded the module constant
(DELETION_FRACTION_THRESHOLD = 0.15) for its deletion-fraction filter, while
`scan_accretion_ratchet` re-filtered on, and reported, the caller's
`deletion_threshold`. The effective cut was min(0.15, deletion_threshold), so any
caller-supplied threshold above 0.15 was silently ignored - the API contradicted
its reported `deletion_fraction_threshold`. This pins the contract: a file at
deletion fraction 0.20 is admitted under `--deletion-threshold 0.30` and dropped
under the 0.15 default.

The comprehensive suite is owned by a separate task; this is the focused
regression only, in a minimally-named module to avoid colliding with it.
"""
from __future__ import annotations

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))

from lib.accretion_ratchet import (  # noqa: E402
    _FileHistory,
    _build_accretion_file,
)


def _history_at_fraction_020() -> _FileHistory:
    """A monotonically-growing file whose deletion fraction is exactly 0.20.

    Three appending commits (multi-commit gate cleared), running net-delta never
    falls back (monotonic), 80 additions to 20 deletions => 20/100 = 0.20.
    """
    return _FileHistory(
        additions=80,
        deletions=20,
        commit_count=3,
        first_time=1_000,
        last_time=1_000 + 86_400,
        net_sequence=[20, 40, 60],
    )


def test_threshold_above_fraction_admits_file() -> None:
    """--deletion-threshold 0.30 admits a 0.20-fraction file (old code dropped it)."""
    result = _build_accretion_file("grower.py", _history_at_fraction_020(), 0.30)
    assert result is not None
    assert result.path == "grower.py"
    assert result.deletion_fraction == 0.20


def test_default_threshold_drops_same_file() -> None:
    """At the 0.15 default the same file is correctly excluded (0.20 >= 0.15)."""
    result = _build_accretion_file("grower.py", _history_at_fraction_020(), 0.15)
    assert result is None

"""Contract tests for the repo-root composite action (action.yml).

The action is the published form of the assess gate - the thing consumers pin
by version and Dependabot upgrades. These tests hold it to the same invariants
the emitted-workflow template carried before the logic moved here: pinned
supply chain, warn-only infra degrade, and the gate step as the only path to a
red check.
"""
from __future__ import annotations

import re
from pathlib import Path

import pytest

try:  # PyYAML is not a declared dependency of this suite.
    import yaml
except ImportError:  # pragma: no cover - environment-dependent
    yaml = None

_ACTION_PATH = Path(__file__).resolve().parents[3] / "action.yml"

# `working-directory: <value>` as a plain scalar, read from the text rather than
# the parse tree so the guard below still runs where PyYAML is absent - which is
# every CI run of this suite today, and the reason a module-level importorskip
# would make that guard decorative.
_WORKING_DIR_RE = re.compile(r"^\s*working-directory:[ \t]*(\S.*?)\s*$", re.MULTILINE)


def _action() -> dict:
    if yaml is None:
        pytest.skip("PyYAML is not installed; the structural assertions need a parse tree")
    return yaml.safe_load(_ACTION_PATH.read_text(encoding="utf-8"))


def _steps() -> list[dict]:
    return _action()["runs"]["steps"]


def test_action_is_composite_at_repo_root():
    action = _action()
    assert action["runs"]["using"] == "composite"
    # Root placement is what makes `uses: bjcoombs/ai-native-toolkit@v<semver>`
    # resolve (and keeps the action Marketplace-eligible).
    assert _ACTION_PATH.parent.name == "ai-native-toolkit" or (
        _ACTION_PATH.parent / ".claude-plugin"
    ).exists()


def test_action_installs_pinned_ripgrep():
    """The marker scan needs rg; ubuntu-latest does not ship it. Unpinned
    installs could move the regression baseline with no change in the tree."""
    text = _ACTION_PATH.read_text(encoding="utf-8")
    rg_lines = [ln for ln in text.splitlines() if "ripgrep/releases/download" in ln]
    assert rg_lines, "expected a pinned ripgrep download"
    assert re.search(r"/download/\d+\.\d+\.\d+/", rg_lines[0])


def test_action_installs_pinned_uv():
    text = _ACTION_PATH.read_text(encoding="utf-8")
    uv_lines = [ln for ln in text.splitlines() if "astral.sh/uv/" in ln]
    assert uv_lines, "expected a pinned uv installer"
    assert re.search(r"astral\.sh/uv/\d+\.\d+\.\d+/install\.sh", uv_lines[0]), (
        f"unpinned uv installer: {uv_lines[0].strip()}"
    )


def test_action_contains_no_floating_latest():
    assert "@latest" not in _ACTION_PATH.read_text(encoding="utf-8")


def test_action_runs_the_four_core_scripts():
    text = _ACTION_PATH.read_text(encoding="utf-8")
    for script in (
        "complexity-treemap.py",
        "assess_core.py",
        "assess_report.py",
        "assess_gate.py",
    ):
        assert script in text, f"missing core script: {script}"


def test_assessment_steps_are_guarded_on_uv():
    """Render + gate only run when uv is available; unavailable uv must skip
    with a notice (warn-only contract), never fail the consumer's check."""
    guarded = [
        s for s in _steps() if "steps.ensure-uv.outputs.ok == 'true'" in (s.get("if") or "")
    ]
    # Render, the skip-notice reporter, and the gate all require uv.
    assert len(guarded) == 3
    ensure = next(s for s in _steps() if s.get("id") == "ensure-uv")
    assert "::notice::" in ensure["run"]
    assert "ok=false" in ensure["run"]


def test_render_step_is_continue_on_error():
    """A mid-render crash is infrastructure, not a finding: the render step must
    continue-on-error so it degrades to a skip, never a red check."""
    render = next(s for s in _steps() if s.get("id") == "render")
    assert render["continue-on-error"] is True


def test_gate_runs_only_after_successful_render():
    """The gate must run meaningfully only when the snapshot rendered whole: its
    guard requires both uv and a successful render outcome."""
    gate = next(s for s in _steps() if "assess_gate.py" in s.get("run", ""))
    cond = gate.get("if") or ""
    assert "steps.ensure-uv.outputs.ok == 'true'" in cond
    assert "steps.render.outcome == 'success'" in cond


def test_failed_render_emits_skip_notice():
    """A failed render surfaces a skip notice (never a failure) so the skip is
    visible in the checks UI as infrastructure, not a finding."""
    skip = next(
        s for s in _steps()
        if "steps.render.outcome == 'failure'" in (s.get("if") or "")
    )
    assert "::notice::" in skip["run"]
    assert "not a finding" in skip["run"]


def test_infra_steps_cannot_red_the_check():
    """The ripgrep step must always exit 0 (degrade = reduced coverage); only
    the gate step's exit code may fail the consumer's PR."""
    rg_step = next(s for s in _steps() if "ripgrep" in s["name"].lower())
    assert rg_step["run"].rstrip().endswith("exit 0")
    gate_step = next(s for s in _steps() if "assess_gate.py" in s.get("run", ""))
    assert "exit 0" not in gate_step["run"]
    assert "continue-on-error" not in gate_step


def test_config_input_default():
    assert _action()["inputs"]["config"]["default"] == ".assess/config.toml"


def test_own_workflow_self_tests_the_action():
    """This repo's own gate must run `uses: ./` so every PR exercises the
    action from the branch under review, not a stale released tag."""
    wf = (
        _ACTION_PATH.parent / ".github" / "workflows" / "assess-gate.yml"
    ).read_text(encoding="utf-8")
    assert "uses: ./" in wf


def test_action_yml_is_git_tracked():
    """The repo .gitignore is an allowlist (`/*` + unignores); a root file not
    explicitly unignored is silently skipped by `git add -A`. That happened to
    action.yml on first publish - the self-test workflow failed with
    'Can't find action.yml'. Pin trackedness so the action can't ship absent."""
    import subprocess

    out = subprocess.run(
        ["git", "-C", str(_ACTION_PATH.parent), "ls-files", "--", "action.yml"],
        capture_output=True, text=True,
    )
    assert out.stdout.strip() == "action.yml"


def test_action_description_fits_marketplace_limit():
    """GitHub Marketplace rejects an action whose description is 125+ chars -
    discovered live on the v1.42.0 release page. Pin publishability."""
    desc = _action()["description"]
    assert len(desc) < 125, f"{len(desc)} chars: {desc}"


def test_working_directories_exist():
    """Every `working-directory` in action.yml must resolve on disk.

    A composite step's `working-directory` is only checked at run time, and a
    miss there surfaces as a render failure the warn-only contract swallows as
    a notice. Resolving `${{ github.action_path }}` to the checkout root here
    turns a moved directory into a red test in the PR that moves it.
    """
    action_root = _ACTION_PATH.parent
    values = _WORKING_DIR_RE.findall(_ACTION_PATH.read_text(encoding="utf-8"))
    assert values, "expected at least one working-directory in action.yml"
    for wd in values:
        resolved = Path(wd.replace("${{ github.action_path }}", str(action_root)))
        assert resolved.is_dir(), f"working-directory does not exist: {wd}"

"""Tests for heuristic agent-instructions grader.

Grades any of: CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules,
.github/copilot-instructions.md. The grader operates on text + freshness,
so it's filename-agnostic - the file selection lives in assess_core.
"""
from __future__ import annotations

from pathlib import Path

import pytest

from lib.agent_instructions_grader import (
    compute_size_metrics,
    count_positive_directives,
    count_tradeoff_phrases,
    count_path_references,
    count_verifiable_outcomes,
    detect_alias,
    detect_skills_delegation,
    grade_instructions,
    scan_sensitive_content,
)


@pytest.fixture
def good_text(fixtures_dir: Path) -> str:
    return (fixtures_dir / "good_instructions.md").read_text()


@pytest.fixture
def bad_text(fixtures_dir: Path) -> str:
    return (fixtures_dir / "bad_instructions.md").read_text()


def test_positive_directives_good_outscores_bad(good_text: str, bad_text: str) -> None:
    # Good fixture uses: Use, Prefer, Default to, Match, Add (positive)
    # Bad fixture uses mostly: Write, Follow, Be, Don't (negatives + generic verbs)
    assert count_positive_directives(good_text) >= 5
    assert count_positive_directives(bad_text) <= 2


def test_tradeoff_phrases_only_in_good(good_text: str, bad_text: str) -> None:
    # "because", "over X" are tradeoff signals
    assert count_tradeoff_phrases(good_text) >= 2
    assert count_tradeoff_phrases(bad_text) == 0


def test_path_references_only_in_good(good_text: str, bad_text: str) -> None:
    # Good fixture has src/auth/, src/payments/processor.py, etc.
    assert count_path_references(good_text) >= 4
    assert count_path_references(bad_text) == 0


def test_verifiable_outcomes_only_in_good(good_text: str, bad_text: str) -> None:
    # "Working if" is the signal phrase
    assert count_verifiable_outcomes(good_text) >= 1
    assert count_verifiable_outcomes(bad_text) == 0


# --- JVM / build-tool verifiable outcomes (issue #116) --------------------
# The detector was calibrated for JS/Python phrasing and credited zero
# verifiable outcomes to Maven/Gradle CLAUDE.md files that contain runnable
# verification (mvn/gradle/gradlew test, -Dtest=, rg recipes). Recognise
# those idioms while keeping JS/Python phrase recognition intact.

MAVEN_INSTRUCTIONS = """# Project Guidelines

## Verifying a change

- Run the focused test: `mvn test -Dtest=PaymentServiceTest#refundsAreIdempotent`.
- Run the full verification gate before opening a PR: `mvn verify`.
- Confirm no stray TODOs slipped in: `rg "TODO" src/main/java`.
"""

GRADLE_INSTRUCTIONS = """# Project Guidelines

## Verifying a change

- Run the focused test: `./gradlew test --tests com.example.PaymentServiceTest`.
- Build and check everything: `./gradlew build check`.
- Confirm logging uses the wrapper: `rg "System.out" src`.
"""


def test_maven_instructions_score_nonzero_verifiable_outcomes() -> None:
    # Success criterion for issue #116: a Maven CLAUDE.md with runnable
    # mvn/rg verification must score a NON-ZERO verifiable_outcomes.
    assert count_verifiable_outcomes(MAVEN_INSTRUCTIONS) >= 1
    grade = grade_instructions(MAVEN_INSTRUCTIONS, freshness_days=10)
    assert grade.subscores["verifiable_outcomes"] >= 1


def test_gradle_instructions_score_nonzero_verifiable_outcomes() -> None:
    assert count_verifiable_outcomes(GRADLE_INSTRUCTIONS) >= 1
    grade = grade_instructions(GRADLE_INSTRUCTIONS, freshness_days=10)
    assert grade.subscores["verifiable_outcomes"] >= 1


def test_jvm_idioms_do_not_regress_js_python_recognition(good_text: str, bad_text: str) -> None:
    # Existing phrase-based recognition stays intact: the good JS/Python
    # fixture still credits a verifiable outcome, the bad one still none.
    assert count_verifiable_outcomes(good_text) >= 1
    assert count_verifiable_outcomes(bad_text) == 0


def test_jvm_patterns_do_not_false_match_prose() -> None:
    # High precision: prose that merely mentions Maven/Gradle without a
    # runnable command must not be credited as a verifiable outcome.
    prose = (
        "# Guidelines\n\n"
        "This is a Maven project that uses Gradle elsewhere. "
        "We care about testing and verifying our work generally.\n"
    )
    assert count_verifiable_outcomes(prose) == 0


def test_rg_prose_mention_is_not_credited() -> None:
    # A bare reference to ripgrep without a runnable recipe (no flag, no
    # quoted query) must not count as a verifiable outcome.
    prose = (
        "# Guidelines\n\n"
        "You can use rg to find things, and rg or grep are both useful. "
        "The rg tool is fast.\n"
    )
    assert count_verifiable_outcomes(prose) == 0


def test_rg_recipe_with_flag_is_credited() -> None:
    # A real ripgrep recipe (flag-driven, unquoted query) is verifiable.
    text = "# Guidelines\n\nCheck for leftovers: `rg -n TODO src/main/java`.\n"
    assert count_verifiable_outcomes(text) >= 1


def test_grade_returns_letter_grade(good_text: str, bad_text: str) -> None:
    good = grade_instructions(good_text, freshness_days=10)
    bad = grade_instructions(bad_text, freshness_days=10)

    assert good.grade in {"A", "A-", "B+", "B"}
    assert bad.grade in {"D", "F"}
    assert good.score > bad.score


def test_grade_penalizes_staleness(good_text: str) -> None:
    fresh = grade_instructions(good_text, freshness_days=10)
    stale = grade_instructions(good_text, freshness_days=400)
    assert stale.score < fresh.score


def test_grade_empty_string_is_F() -> None:
    empty = grade_instructions("", freshness_days=0)
    assert empty.grade == "F"
    assert empty.score == 0


def test_subscores_in_result(good_text: str) -> None:
    result = grade_instructions(good_text, freshness_days=10)
    assert result.subscores["positive_directives"] >= 5
    assert result.subscores["path_references"] >= 4
    assert "tradeoff_phrases" in result.subscores
    assert "verifiable_outcomes" in result.subscores


def test_size_metrics_accurate() -> None:
    text = "line1\nline2\nline3"
    m = compute_size_metrics(text)
    assert m["line_count"] == 3
    assert m["word_count"] == 3
    assert m["exceeds_line_threshold"] is False
    assert m["exceeds_word_threshold"] is False


def test_skills_delegation_detection() -> None:
    text = "Load Java conventions via the `java-conventions` skill."
    d = detect_skills_delegation(text)
    assert d["delegates_to_skills"] is True
    assert d["delegation_pointers"] >= 1
    assert len(d["delegation_samples"]) >= 1


def test_skills_delegation_detection_dir_pointer() -> None:
    text = "Topic guidance lives under .claude/skills/ and loads on demand."
    d = detect_skills_delegation(text)
    assert d["delegates_to_skills"] is True


def test_no_skills_delegation_in_generic_text() -> None:
    text = "Write clean code. Follow best practices."
    d = detect_skills_delegation(text)
    assert d["delegates_to_skills"] is False
    assert d["delegation_pointers"] == 0


def test_size_subscores_in_grade(good_text: str) -> None:
    result = grade_instructions(good_text, freshness_days=10)
    assert "line_count" in result.subscores
    assert "word_count" in result.subscores
    assert "bloat_penalty" in result.subscores
    assert result.subscores["bloat_penalty"] == 0  # good_instructions is small


# --- Sensitive-content scan (issue #56) -----------------------------------

def _categories(findings: list[dict]) -> set[str]:
    return {f["category"] for f in findings}


def test_scan_flags_public_ip() -> None:
    findings = scan_sensitive_content("Demo server: 203.0.113.42 runs the stack.")
    assert "ip_address" in _categories(findings)
    # Evidence is redacted - the full IP must not survive into the finding.
    assert all("203.0.113.42" not in f["evidence"] for f in findings)


def test_scan_ignores_loopback_and_version_strings() -> None:
    assert scan_sensitive_content("bind to 127.0.0.1 for local dev") == []
    # 999 is not a valid octet -> a version-like string, not an IP.
    assert scan_sensitive_content("upgrade to release 1.2.999.4") == []


def test_scan_flags_ssh_root_login() -> None:
    findings = scan_sensitive_content("Connect with `ssh root@demo.example.com`.")
    cats = _categories(findings)
    assert "ssh_or_host" in cats
    assert all("demo.example.com" not in f["evidence"] for f in findings)


def test_scan_flags_private_key_and_cloud_key() -> None:
    pem = "-----BEGIN RSA PRIVATE KEY-----\nMIIabc\n-----END RSA PRIVATE KEY-----"
    assert "private_key" in _categories(scan_sensitive_content(pem))
    assert "cloud_key" in _categories(scan_sensitive_content("AWS: AKIAIOSFODNN7EXAMPLE"))


def test_scan_flags_real_credential_but_not_placeholder() -> None:
    real = scan_sensitive_content('password = "hunter2correcthorse"')
    assert "credential" in _categories(real)
    assert all("hunter2" not in f["evidence"] for f in real)
    # Placeholders / env refs are not flagged.
    assert scan_sensitive_content("API_KEY=your_key_here") == []
    assert scan_sensitive_content("token = ${GH_TOKEN}") == []
    assert scan_sensitive_content("password: <your-password>") == []


def test_scan_flags_home_directory_path_but_not_placeholder() -> None:
    findings = scan_sensitive_content("Config lives at /Users/ben/.config/app.yaml")
    assert "home_path" in _categories(findings)
    assert all("ben" not in f["evidence"] for f in findings)
    # Generic placeholder home dirs are not a leak.
    assert scan_sensitive_content("clone into /home/user/project") == []


def test_scan_clean_instruction_file_has_no_findings(good_text: str) -> None:
    assert scan_sensitive_content(good_text) == []


# --- Alias detection (issue #57) ------------------------------------------

def test_detect_alias_thin_stub_points_at_claude_md() -> None:
    stub = "# AGENTS.md\n\nSee [CLAUDE.md](./CLAUDE.md) for all project instructions."
    result = detect_alias(stub)
    assert result["is_alias"] is True
    assert result["alias_target"] == "CLAUDE.md"


def test_detect_alias_rejects_full_standalone_doc(good_text: str) -> None:
    # A real instruction file is not a thin alias even if it mentions CLAUDE.md.
    assert detect_alias(good_text)["is_alias"] is False


def test_detect_alias_rejects_stub_with_no_canonical_reference() -> None:
    assert detect_alias("# Notes\n\nThis project is great.")["is_alias"] is False

"""Tests for the agent-operations guardrail scan (Layer 8 evidence)."""
from __future__ import annotations

import json
from pathlib import Path

from lib.agent_ops import scan_agent_ops


def _write_settings(repo: Path, rel: str, data: object) -> Path:
    path = repo / rel
    path.parent.mkdir(parents=True, exist_ok=True)
    if isinstance(data, str):
        path.write_text(data, encoding="utf-8")
    else:
        path.write_text(json.dumps(data), encoding="utf-8")
    return path


# ── empty / degraded cases ──────────────────────────────────────────────────

def test_no_claude_dir(git_repo) -> None:
    repo, commit = git_repo
    (repo / "README.md").write_text("hi", encoding="utf-8")
    commit("init")
    block = scan_agent_ops(repo)
    assert block["available"] is True
    assert block["settings"] == []
    assert block["hooks_dir"]["present"] is False
    assert block["summary"] == {
        "permissions_encoded": False,
        "hooks_present": False,
        "routines_present": False,
    }


def test_non_git_dir_counts_nothing_as_tracked(tmp_path: Path) -> None:
    _write_settings(tmp_path, ".claude/settings.json",
                    {"permissions": {"allow": ["Bash(ls:*)"]}})
    block = scan_agent_ops(tmp_path)
    assert block["available"] is True
    assert block["settings"][0]["tracked"] is False
    assert block["settings"][0]["allow_count"] == 1
    # Untracked evidence is reported but never credited.
    assert block["summary"]["permissions_encoded"] is False


def test_malformed_settings_json_degrades(git_repo) -> None:
    repo, commit = git_repo
    _write_settings(repo, ".claude/settings.json", "{not json")
    commit("add settings")
    block = scan_agent_ops(repo)
    entry = block["settings"][0]
    assert entry["parse_ok"] is False
    assert entry["allow_count"] == 0
    assert block["summary"]["permissions_encoded"] is False


# ── tracked-only credit ─────────────────────────────────────────────────────

def test_tracked_settings_credit_summary(git_repo) -> None:
    repo, commit = git_repo
    _write_settings(repo, ".claude/settings.json", {
        "permissions": {"allow": ["Bash(ls:*)", "Read"], "deny": ["WebFetch"]},
        "hooks": {"PreToolUse": [], "PostToolUse": []},
        "sandbox": {"enabled": True},
    })
    commit("add settings")
    block = scan_agent_ops(repo)
    entry = block["settings"][0]
    assert entry["tracked"] is True
    assert entry["parse_ok"] is True
    assert entry["allow_count"] == 2
    assert entry["deny_count"] == 1
    assert entry["ask_count"] == 0
    assert entry["hook_events"] == 2
    assert entry["sandbox_configured"] is True
    assert block["summary"]["permissions_encoded"] is True
    assert block["summary"]["hooks_present"] is True


def test_untracked_settings_reported_not_credited(git_repo) -> None:
    repo, commit = git_repo
    (repo / "README.md").write_text("hi", encoding="utf-8")
    commit("init")
    # Written after the commit, never staged - the settings.local.json case.
    _write_settings(repo, ".claude/settings.local.json",
                    {"permissions": {"allow": ["Bash(ls:*)"]}})
    block = scan_agent_ops(repo)
    assert [s["path"] for s in block["settings"]] == [".claude/settings.local.json"]
    assert block["settings"][0]["tracked"] is False
    assert block["summary"]["permissions_encoded"] is False


def test_hooks_dir_scripts(git_repo) -> None:
    repo, commit = git_repo
    hook = repo / ".claude" / "hooks" / "check.sh"
    hook.parent.mkdir(parents=True)
    hook.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")
    commit("add hook")
    block = scan_agent_ops(repo)
    assert block["hooks_dir"]["present"] is True
    assert block["hooks_dir"]["file_count"] == 1
    assert block["hooks_dir"]["tracked_count"] == 1
    assert block["summary"]["hooks_present"] is True


def test_routine_dirs(git_repo) -> None:
    repo, commit = git_repo
    wf = repo / ".claude" / "workflows" / "nightly-triage.md"
    wf.parent.mkdir(parents=True)
    wf.write_text("# nightly triage\n", encoding="utf-8")
    commit("add workflow")
    block = scan_agent_ops(repo)
    workflows = next(
        d for d in block["routine_dirs"] if d["path"] == ".claude/workflows"
    )
    assert workflows["tracked_count"] == 1
    assert block["summary"]["routines_present"] is True

"""Tests for anomaly detection on /assess run output."""
from __future__ import annotations

from lib.anomaly_detector import detect_anomalies


def _ctx(**overrides) -> dict:
    """Build a healthy context, then apply overrides for the test."""
    base = {
        "prior_stats_exists": True,
        "stats_summary": {
            "files_scored": 100,
            "loc": {"p50": 30, "p95": 200, "max": 500},
            "ccn": {"p50": 3, "p95": 8, "max": 25},
            "top_hotspots": [
                {"path": "src/a.go", "loc": 400, "ccn": 25, "commits": 5},
                {"path": "src/b.go", "loc": 300, "ccn": 18, "commits": 3},
            ],
        },
        "instruction_files": {
            "CLAUDE.md": {
                "present": True, "grade": "B+", "score": 62, "line_count": 80, "subscores": {},
            },
        },
        "instructions_grade": "B+",
        "diff": {"new": 1, "graduated": 0, "regressed": 0, "persistent": 1},
    }
    for k, v in overrides.items():
        if isinstance(base.get(k), dict) and isinstance(v, dict) and v:
            base[k].update(v)
        else:
            base[k] = v
    return base


def test_no_anomalies_in_healthy_run() -> None:
    assert detect_anomalies(_ctx()) == []


def test_zero_files_scored() -> None:
    anomalies = detect_anomalies(_ctx(stats_summary={"files_scored": 0}))
    assert "ZERO_FILES_SCORED" in {a.code for a in anomalies}


def test_zero_complexity_with_files() -> None:
    anomalies = detect_anomalies(_ctx(stats_summary={
        "files_scored": 50, "ccn": {"p50": 0, "p95": 0, "max": 0},
    }))
    assert "ZERO_COMPLEXITY" in {a.code for a in anomalies}


def test_empty_hotspots_large_repo() -> None:
    anomalies = detect_anomalies(_ctx(stats_summary={
        "files_scored": 250, "top_hotspots": [],
    }))
    assert "EMPTY_HOTSPOTS" in {a.code for a in anomalies}


def test_instruction_file_grade_mismatch_long_file_low_grade() -> None:
    """An instruction file that's >200 lines but grades F is suspicious."""
    anomalies = detect_anomalies(_ctx(
        instruction_files={"CLAUDE.md": {
            "present": True, "grade": "F", "score": 10, "line_count": 350, "subscores": {},
        }},
        instructions_grade="F",
    ))
    assert "INSTRUCTION_FILE_GRADE_MISMATCH" in {a.code for a in anomalies}


def test_instruction_file_grade_mismatch_for_agents_md() -> None:
    """The check applies to any instruction filename, not just CLAUDE.md."""
    anomalies = detect_anomalies(_ctx(
        instruction_files={"AGENTS.md": {
            "present": True, "grade": "F", "score": 10, "line_count": 300, "subscores": {},
        }},
        instructions_grade="F",
    ))
    assert "INSTRUCTION_FILE_GRADE_MISMATCH" in {a.code for a in anomalies}


def test_all_hotspots_new_means_rotation_failed() -> None:
    anomalies = detect_anomalies(_ctx(
        diff={"new": 8, "graduated": 0, "regressed": 0, "persistent": 0},
        stats_summary={"files_scored": 100, "top_hotspots": [
            {"path": f"src/{i}.go", "loc": 300, "ccn": 15, "commits": 2} for i in range(8)
        ]},
    ))
    assert "ALL_NEW_HOTSPOTS" in {a.code for a in anomalies}


def test_all_new_hotspots_first_run_not_flagged() -> None:
    """On a true first run (no prior stats), ALL_NEW_HOTSPOTS must not be raised."""
    anomalies = detect_anomalies(_ctx(
        prior_stats_exists=False,
        diff={"new": 8, "graduated": 0, "regressed": 0, "persistent": 0},
        stats_summary={"files_scored": 100, "top_hotspots": [
            {"path": f"src/{i}.go", "loc": 300, "ccn": 15, "commits": 2} for i in range(8)
        ]},
    ))
    assert "ALL_NEW_HOTSPOTS" not in {a.code for a in anomalies}


def test_anomaly_detail_excludes_source_paths() -> None:
    """Every anomaly type must produce detail strings with no source file paths.

    File basenames for well-known instruction files (CLAUDE.md, AGENTS.md, etc.)
    are intentionally included - those are public knowledge and help triage.
    The exclusion is for source paths (src/foo.go, lib/bar.py, etc.).
    """
    # Trigger all 5 anomaly types
    triggers = [
        # ZERO_FILES_SCORED
        _ctx(stats_summary={"files_scored": 0}),
        # ZERO_COMPLEXITY
        _ctx(stats_summary={"files_scored": 50, "ccn": {"p50": 0, "p95": 0, "max": 0}}),
        # EMPTY_HOTSPOTS
        _ctx(stats_summary={"files_scored": 250, "top_hotspots": []}),
        # INSTRUCTION_FILE_GRADE_MISMATCH
        _ctx(
            instruction_files={"CLAUDE.md": {
                "present": True, "grade": "F", "score": 10, "line_count": 350, "subscores": {},
            }},
            instructions_grade="F",
        ),
        # ALL_NEW_HOTSPOTS
        _ctx(
            diff={"new": 8, "graduated": 0, "regressed": 0, "persistent": 0},
            stats_summary={"files_scored": 100, "top_hotspots": [
                {"path": f"src/{i}.go", "loc": 300, "ccn": 15, "commits": 2} for i in range(8)
            ]},
        ),
    ]
    for ctx in triggers:
        anomalies = detect_anomalies(ctx)
        for a in anomalies:
            # No source-path characters
            assert "/" not in a.detail, f"{a.code}: detail contains slash: {a.detail!r}"
            assert ".go" not in a.detail, f"{a.code}: detail contains .go: {a.detail!r}"
            assert ".py" not in a.detail, f"{a.code}: detail contains .py: {a.detail!r}"
            assert ".ts" not in a.detail, f"{a.code}: detail contains .ts: {a.detail!r}"


def test_anomaly_has_code_description_detail() -> None:
    anomalies = detect_anomalies(_ctx(stats_summary={"files_scored": 0}))
    assert len(anomalies) >= 1
    a = anomalies[0]
    assert a.code and a.description and a.detail


def test_no_anomalies_when_no_instruction_files() -> None:
    """A repo with no instruction files at all is a valid (if poor) state, not an anomaly.

    The grade is None (distinct from F). INSTRUCTION_FILE_GRADE_MISMATCH should not fire
    because there's no file to mismatch with.
    """
    ctx = _ctx(instruction_files={}, instructions_grade=None)
    anomalies = detect_anomalies(ctx)
    codes = {a.code for a in anomalies}
    assert "INSTRUCTION_FILE_GRADE_MISMATCH" not in codes

"""Tests for repository archetype detection (lib/archetype.py).

Covers the four acceptance criteria of issue #224:
1. A markdown KB repo is auto-detected; an override marker forces/suppresses.
2. A detected KB marks write-side layers N/A and renormalises the denominator.
3. The KB-maintenance (Karpathy LLM-wiki) workflow is detected and the gist
   is always available as the best-practice pointer.
4. A conventional software repo is unaffected (all 0-8 layers, denominator 8).
"""
from __future__ import annotations

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))

from lib.archetype import (  # noqa: E402
    KARPATHY_GIST_URL,
    KB_APPLICABLE_LAYERS,
    SOFTWARE_DENOMINATOR,
    WRITE_SIDE_LAYERS,
    analyze_archetype,
    classify_archetype,
    detect_kb_maintenance,
    read_archetype_override,
)


def _kb_maint_empty() -> dict:
    return {"documented": False, "signals_found": [], "gist_cited": False, "gist": KARPATHY_GIST_URL}


# --- classify_archetype: heuristic --------------------------------------


def test_markdown_kb_detected_by_ratio_and_no_runtime():
    block = classify_archetype(
        code_file_count=1,
        doc_file_count=80,
        other_file_count=4,
        has_runtime_surface=False,
        override=None,
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["archetype"] == "knowledge-base"
    assert block["detected_via"] == "heuristic"
    assert block["na_layers"] == WRITE_SIDE_LAYERS
    assert block["applicable_layers"] == KB_APPLICABLE_LAYERS
    assert block["denominator"] == len(KB_APPLICABLE_LAYERS) == 3
    assert "ratio" in block["reason"]


def test_software_repo_unaffected_all_layers():
    block = classify_archetype(
        code_file_count=120,
        doc_file_count=20,
        other_file_count=10,
        has_runtime_surface=True,
        override=None,
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["archetype"] == "software"
    assert block["na_layers"] == []
    assert block["applicable_layers"] == list(range(0, 9))
    assert block["denominator"] == SOFTWARE_DENOMINATOR == 8


def test_doc_heavy_app_with_runtime_surface_is_software():
    # Lots of markdown but a real build manifest -> not a KB.
    block = classify_archetype(
        code_file_count=2,
        doc_file_count=200,
        other_file_count=5,
        has_runtime_surface=True,
        override=None,
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["archetype"] == "software"
    assert block["signals"]["has_runtime_surface"] is True
    assert "runtime surface" in block["reason"]


def test_empty_or_tiny_doc_set_not_kb():
    block = classify_archetype(
        code_file_count=0,
        doc_file_count=1,
        other_file_count=0,
        has_runtime_surface=False,
        override=None,
        kb_maintenance=_kb_maint_empty(),
    )
    # Only one doc and no real base -> not enough to call it a knowledge base.
    assert block["archetype"] == "software"


# --- classify_archetype: override ---------------------------------------


def test_override_forces_knowledge_base():
    block = classify_archetype(
        code_file_count=500,  # code-heavy; heuristic would say software
        doc_file_count=3,
        other_file_count=0,
        has_runtime_surface=True,
        override="knowledge-base",
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["archetype"] == "knowledge-base"
    assert block["detected_via"] == "override"
    assert block["denominator"] == 3


def test_override_suppresses_detection():
    block = classify_archetype(
        code_file_count=0,  # heuristic would say knowledge-base
        doc_file_count=99,
        other_file_count=0,
        has_runtime_surface=False,
        override="software",
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["archetype"] == "software"
    assert block["detected_via"] == "override"
    assert block["denominator"] == 8


# --- override_contradicts_signals (issue: silent override) --------------


def test_kb_override_contradicts_high_code_ratio():
    # A knowledge-base marker on a code-heavy repo with a runtime surface: the
    # override wins the score, but the contradiction is surfaced with details.
    block = classify_archetype(
        code_file_count=500,
        doc_file_count=3,
        other_file_count=0,
        has_runtime_surface=True,
        override="knowledge-base",
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["override_contradicts_signals"] is True
    assert block["contradiction_details"]
    assert "software" in block["contradiction_details"]
    # Override still wins: the denominator uses the forced (KB) archetype.
    assert block["archetype"] == "knowledge-base"
    assert block["denominator"] == 3


def test_software_override_contradicts_pure_doc_repo():
    block = classify_archetype(
        code_file_count=0,
        doc_file_count=99,
        other_file_count=0,
        has_runtime_surface=False,
        override="software",
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["override_contradicts_signals"] is True
    assert "knowledge-base" in block["contradiction_details"]
    # Override still wins the classification.
    assert block["archetype"] == "software"
    assert block["denominator"] == 8


def test_override_matching_heuristic_no_contradiction():
    # A KB marker on a repo the heuristic would also call a KB: no contradiction.
    block = classify_archetype(
        code_file_count=1,
        doc_file_count=80,
        other_file_count=0,
        has_runtime_surface=False,
        override="knowledge-base",
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["override_contradicts_signals"] is False
    assert block["contradiction_details"] is None
    assert block["archetype"] == "knowledge-base"


def test_heuristic_path_never_contradicts():
    # No override -> no contradiction flag can fire (nothing forced anything).
    block = classify_archetype(
        code_file_count=1,
        doc_file_count=80,
        other_file_count=0,
        has_runtime_surface=False,
        override=None,
        kb_maintenance=_kb_maint_empty(),
    )
    assert block["detected_via"] == "heuristic"
    assert block["override_contradicts_signals"] is False
    assert block["contradiction_details"] is None


def test_analyze_records_override_source_on_contradiction(tmp_path: Path):
    # A software marker on a pure-doc repo: analyze_archetype records the marker
    # source file so a finding can point at it.
    repo = tmp_path / "kb"
    (repo / "notes").mkdir(parents=True)
    for i in range(12):
        (repo / "notes" / f"note-{i}.md").write_text(f"# Note {i}\n", encoding="utf-8")
    (repo / "CLAUDE.md").write_text(
        "# KB\n\n<!-- assess-archetype: software -->\n", encoding="utf-8"
    )
    _git_init(repo)

    block = analyze_archetype(repo)
    assert block["archetype"] == "software"
    assert block["override_contradicts_signals"] is True
    assert block["override_source"] == "CLAUDE.md"


# --- read_archetype_override --------------------------------------------


def test_read_override_marker_force_kb(tmp_path: Path):
    (tmp_path / "CLAUDE.md").write_text(
        "# Repo\n\n<!-- assess-archetype: knowledge-base -->\n", encoding="utf-8"
    )
    assert read_archetype_override(tmp_path) == "knowledge-base"


def test_read_override_marker_suppress(tmp_path: Path):
    (tmp_path / "AGENTS.md").write_text(
        "assess-archetype: software\n", encoding="utf-8"
    )
    assert read_archetype_override(tmp_path) == "software"


def test_read_override_alias_kb(tmp_path: Path):
    (tmp_path / "CLAUDE.md").write_text("<!-- assess-archetype: kb -->", encoding="utf-8")
    assert read_archetype_override(tmp_path) == "knowledge-base"


def test_read_override_absent_returns_none(tmp_path: Path):
    (tmp_path / "CLAUDE.md").write_text("# nothing special here\n", encoding="utf-8")
    assert read_archetype_override(tmp_path) is None


def test_read_override_unrecognised_value_ignored(tmp_path: Path):
    (tmp_path / "CLAUDE.md").write_text("<!-- assess-archetype: banana -->", encoding="utf-8")
    assert read_archetype_override(tmp_path) is None


# --- detect_kb_maintenance ----------------------------------------------


def test_kb_maintenance_documented_by_two_facets():
    text = (
        "Raw sources are immutable and append-only. "
        "A periodic consolidation pass lints the wiki and prunes stale notes."
    )
    sig = detect_kb_maintenance(text)
    assert sig["documented"] is True
    assert "immutable-sources" in sig["signals_found"]
    assert "periodic-consolidation" in sig["signals_found"]
    assert sig["gist"] == KARPATHY_GIST_URL


def test_kb_maintenance_documented_by_gist_citation():
    text = "We follow the LLM-wiki pattern: " + KARPATHY_GIST_URL
    sig = detect_kb_maintenance(text)
    assert sig["gist_cited"] is True
    assert sig["documented"] is True


def test_kb_maintenance_single_keyword_not_documented():
    text = "This project has a database schema."
    sig = detect_kb_maintenance(text)
    assert sig["documented"] is False
    # gist pointer is always present regardless
    assert sig["gist"] == KARPATHY_GIST_URL


def test_kb_maintenance_gist_always_present_when_absent():
    sig = detect_kb_maintenance("nothing relevant")
    assert sig["documented"] is False
    assert sig["signals_found"] == []
    assert sig["gist"] == KARPATHY_GIST_URL


# --- analyze_archetype (integration over a temp repo) -------------------


def _git_init(repo: Path) -> None:
    import subprocess

    subprocess.run(["git", "-C", str(repo), "init", "-q"], check=True)
    subprocess.run(["git", "-C", str(repo), "add", "-A"], check=True)
    subprocess.run(
        ["git", "-C", str(repo), "-c", "user.email=t@e.com", "-c", "user.name=t",
         "commit", "-q", "-m", "init"],
        check=True,
    )


def test_analyze_markdown_repo_is_knowledge_base(tmp_path: Path):
    repo = tmp_path / "kb"
    (repo / "notes").mkdir(parents=True)
    for i in range(12):
        (repo / "notes" / f"note-{i}.md").write_text(f"# Note {i}\n", encoding="utf-8")
    (repo / "CLAUDE.md").write_text(
        "# KB schema\nRaw sources are immutable. Periodic consolidation lints the wiki.\n",
        encoding="utf-8",
    )
    _git_init(repo)

    block = analyze_archetype(repo)
    assert block["available"] is True
    assert block["archetype"] == "knowledge-base"
    assert block["na_layers"] == WRITE_SIDE_LAYERS
    assert block["denominator"] == 3
    assert block["kb_maintenance"]["documented"] is True


def test_analyze_software_repo_is_software(tmp_path: Path):
    repo = tmp_path / "app"
    (repo / "src").mkdir(parents=True)
    for i in range(15):
        (repo / "src" / f"mod_{i}.py").write_text(f"def f{i}():\n    return {i}\n", encoding="utf-8")
    (repo / "README.md").write_text("# App\n", encoding="utf-8")
    (repo / "pyproject.toml").write_text("[project]\nname='app'\n", encoding="utf-8")
    _git_init(repo)

    block = analyze_archetype(repo)
    assert block["archetype"] == "software"
    assert block["na_layers"] == []
    assert block["denominator"] == 8
    assert block["signals"]["has_runtime_surface"] is True

"""Tests for the working-notes keys in `.assess/config.toml` (issue #367).

`working_notes_dirs` forces a directory to be classified as a working-notes
tree whatever its size or fingerprint; `working_notes_ignore` keeps a directory
counted in the headline even when the fingerprint matches. Each test runs the
key end to end: config file -> `load_working_notes_config` -> `build_doc_graph`.
"""
from __future__ import annotations

from pathlib import Path

from lib.assess_config import load_working_notes_config
from lib.doc_graph import build_doc_graph


def _write(root: Path, rel: str, text: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _config(root: Path, body: str) -> None:
    _write(root, ".assess/config.toml", body)


def _plan_notes(root: Path, directory: str = "notes") -> None:
    """50 plan notes under one backlog index: the fingerprint matches."""
    for i in range(1, 51):
        _write(root, f"{directory}/plan_{i:02d}.md", f"# plan {i:02d}\n")
    _write(root, f"{directory}/backlog.md", "".join(
        f"- [plan {i:02d}](plan_{i:02d}.md)\n" for i in range(1, 51)
    ))


_WORDS = "harbour ledger compass anchor beacon current driftwood estuary".split()


def _journal(root: Path) -> None:
    """Eight cross-linked pages with varied names: no fingerprint matches."""
    n = len(_WORDS)
    for i, w in enumerate(_WORDS):
        links = "".join(f"- [{_WORDS[(i + k) % n]}]({_WORDS[(i + k) % n]}.md)\n" for k in (1, 3))
        _write(root, f"journal/{w}.md", f"# {w}\n\n{links}")


def _graph(root: Path) -> dict:
    cfg = load_working_notes_config(root)
    return build_doc_graph(
        root, working_notes_dirs=cfg.dirs, working_notes_ignore=cfg.ignore,
    ).as_dict()


def test_working_notes_dirs_forces_classification(tmp_path: Path) -> None:
    _journal(tmp_path)
    _write(tmp_path, "README.md", "# Home\n[harbour](journal/harbour.md)\n")
    assert _graph(tmp_path)["excluded_working_notes_trees"] == []

    _config(tmp_path, 'working_notes_dirs = ["./journal/"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == [{"path": "journal", "file_count": 8}]
    assert d["working_notes_doc_count"] == 8
    assert d["doc_count"] == 1


def test_working_notes_dirs_nested_path_and_absent_dir(tmp_path: Path) -> None:
    for i in range(3):
        _write(tmp_path, f"docs/plans/p{i}.md", f"# p{i}\n")
    _write(tmp_path, "docs/guide.md", "# Guide\n")
    _config(tmp_path, 'working_notes_dirs = ["docs/plans", "does-not-exist"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == [{"path": "docs/plans", "file_count": 3}]
    assert d["doc_count"] == 1


def test_working_notes_dirs_absorbs_a_detected_tree_below_it(tmp_path: Path) -> None:
    _plan_notes(tmp_path, "work/notes")
    _write(tmp_path, "work/summary.md", "# Summary\n")
    _config(tmp_path, 'working_notes_dirs = ["work"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == [{"path": "work", "file_count": 52}]


def test_working_notes_ignore_suppresses_classification(tmp_path: Path) -> None:
    _plan_notes(tmp_path)
    _write(tmp_path, "README.md", "# Home\n[backlog](notes/backlog.md)\n")
    assert _graph(tmp_path)["excluded_working_notes_trees"] == [
        {"path": "notes", "file_count": 51}
    ]

    _config(tmp_path, 'working_notes_ignore = ["notes"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == []
    assert d["working_notes_doc_count"] == 0
    assert d["doc_count"] == 52


def test_working_notes_ignore_covers_subdirectories_and_wins_over_dirs(tmp_path: Path) -> None:
    _plan_notes(tmp_path, "notes/2026")
    _journal(tmp_path)
    _config(tmp_path, 'working_notes_dirs = ["journal"]\nworking_notes_ignore = ["notes", "journal"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == []
    assert d["doc_count"] == 51 + len(_WORDS)


def test_working_notes_config_degrades_silently(tmp_path: Path) -> None:
    assert load_working_notes_config(tmp_path) == ([], [])
    _config(tmp_path, 'working_notes_dirs = "journal"\nworking_notes_ignore = ["", "/", 7, "a/b/"]\n')
    assert load_working_notes_config(tmp_path) == ([], ["a/b"])
    _config(tmp_path, "working_notes_dirs = [\n")  # malformed TOML
    assert load_working_notes_config(tmp_path) == ([], [])


def test_working_notes_ignore_never_qualifies_a_parent(tmp_path: Path) -> None:
    # 25 plans + backlog beside 10 varied curated pages in notes/misc: notes/
    # fails the name-density leg. Ignoring notes/misc must not tip it over.
    for i in range(1, 26):
        _write(tmp_path, f"notes/plan_{i:02d}.md", f"# plan {i:02d}\n")
    _write(tmp_path, "notes/backlog.md", "".join(
        f"- [plan {i:02d}](plan_{i:02d}.md)\n" for i in range(1, 26)
    ))
    for w in "alpha bravo charlie delta echo foxtrot golf hotel india juliet".split():
        _write(tmp_path, f"notes/misc/{w}.md", f"# {w}\n")
    assert _graph(tmp_path)["excluded_working_notes_trees"] == []

    _config(tmp_path, 'working_notes_ignore = ["notes/misc"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == []
    assert d["doc_count"] == 36


def test_working_notes_ignore_leaves_no_rump_tree(tmp_path: Path) -> None:
    # A chapter series under its contents page qualifies as one tree, docs/.
    # Ignoring the series must return the contents page too, not report a
    # one-file docs tree.
    for i in range(1, 21):
        _write(tmp_path, f"docs/chapters/chapter-{i:02d}.md", f"# chapter {i}\n")
    _write(tmp_path, "docs/contents.md", "".join(
        f"- [chapter {i}](chapters/chapter-{i:02d}.md)\n" for i in range(1, 21)
    ))
    _write(tmp_path, "README.md", "# Home\n[contents](docs/contents.md)\n")
    assert _graph(tmp_path)["excluded_working_notes_trees"] == [
        {"path": "docs", "file_count": 21}
    ]

    _config(tmp_path, 'working_notes_ignore = ["docs/chapters"]\n')
    d = _graph(tmp_path)
    assert d["excluded_working_notes_trees"] == []
    assert d["doc_count"] == 22

"""End-to-end test for the assess_core orchestrator.

We don't run lizard/scc here - we drive assess_core via its public functions
to exercise the deterministic plumbing.
"""
from __future__ import annotations

import json
from pathlib import Path

import pytest

import assess_core
from assess_core import build_run_context


def _minimal_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))
    return repo


_EMPTY_STATS = json.dumps({
    "files_scored": 0, "loc": {}, "ccn": {},
    "top_hotspots": [], "top_complex": [], "top_large": [],
})


def _seed_assess(repo: Path) -> None:
    (repo / ".assess").mkdir(exist_ok=True)
    (repo / ".assess" / "complexity-stats.json").write_text(_EMPTY_STATS)


def test_untracked_instruction_file_flagged_not_graded(git_repo, fixtures_dir: Path) -> None:
    """Issue #34 Gap 1: an on-disk-but-untracked instruction file isn't credited
    to the grade, and is surfaced as a finding."""
    repo, commit = git_repo
    good = (fixtures_dir / "good_instructions.md").read_text()
    _seed_assess(repo)
    (repo / ".github").mkdir()
    (repo / ".github" / "copilot-instructions.md").write_text(good, encoding="utf-8")
    commit("committed instructions")
    (repo / "CLAUDE.md").write_text(good, encoding="utf-8")  # untracked (after commit)

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    assert ".github/copilot-instructions.md" in ctx["instruction_files"]
    assert "CLAUDE.md" not in ctx["instruction_files"]          # untracked -> not graded
    assert "CLAUDE.md" in ctx["untracked_instruction_files"]    # but flagged


def test_archetype_block_emitted_for_software_repo(git_repo) -> None:
    """Issue #224: run-context carries an archetype block; a code repo is software."""
    repo, commit = git_repo
    _seed_assess(repo)
    src = repo / "src"
    src.mkdir()
    for i in range(12):
        (src / f"mod_{i}.py").write_text(f"def f{i}():\n    return {i}\n", encoding="utf-8")
    (repo / "pyproject.toml").write_text("[project]\nname='x'\n", encoding="utf-8")
    commit("software repo")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    arch = ctx["archetype"]
    assert arch["available"] is True
    assert arch["archetype"] == "software"
    assert arch["na_layers"] == []
    assert arch["denominator"] == 8


def test_archetype_block_detects_knowledge_base(git_repo) -> None:
    """Issue #224: a markdown-only repo is detected as a knowledge base with
    write-side layers N/A and a renormalised denominator."""
    repo, commit = git_repo
    _seed_assess(repo)
    notes = repo / "notes"
    notes.mkdir()
    for i in range(15):
        (notes / f"note-{i}.md").write_text(f"# Note {i}\n\nbody\n", encoding="utf-8")
    (repo / "CLAUDE.md").write_text(
        "# KB\nRaw sources are immutable. A periodic consolidation pass lints the wiki.\n",
        encoding="utf-8",
    )
    commit("knowledge base")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    arch = ctx["archetype"]
    assert arch["archetype"] == "knowledge-base"
    assert arch["na_layers"] == [2, 3, 4, 5, 6, 7]
    assert arch["denominator"] == 3
    assert arch["kb_maintenance"]["documented"] is True


def test_archetype_override_marker_suppresses(git_repo) -> None:
    """Issue #224: an `assess-archetype: software` marker forces software even
    on a markdown-only repo."""
    repo, commit = git_repo
    _seed_assess(repo)
    notes = repo / "notes"
    notes.mkdir()
    for i in range(15):
        (notes / f"note-{i}.md").write_text(f"# Note {i}\n", encoding="utf-8")
    (repo / "CLAUDE.md").write_text(
        "# Docs repo\n\n<!-- assess-archetype: software -->\n", encoding="utf-8"
    )
    commit("override to software")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    arch = ctx["archetype"]
    assert arch["archetype"] == "software"
    assert arch["detected_via"] == "override"


def test_dangling_symlink_instruction_is_broken_ref(git_repo) -> None:
    """Issue #34 Gap 2: a committed instruction file that is a dangling symlink
    is an advertised-but-broken reference."""
    import os
    repo, commit = git_repo
    _seed_assess(repo)
    (repo / "README.md").write_text("# Repo", encoding="utf-8")
    os.symlink("missing-target.md", repo / ".cursorrules")  # dangling symlink
    commit("init with dangling .cursorrules")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    refs = ctx["broken_instruction_refs"]
    assert any(r.get("path") == ".cursorrules" and "symlink" in r["reason"] for r in refs)


def test_broken_link_to_instruction_file_is_broken_ref(git_repo) -> None:
    """Issue #34 Gap 2: an entry doc linking a missing instruction file."""
    repo, commit = git_repo
    _seed_assess(repo)
    (repo / "README.md").write_text("see the [rules](AGENTS.md)", encoding="utf-8")
    commit("init; README links a missing AGENTS.md")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    refs = ctx["broken_instruction_refs"]
    assert any(Path(r.get("target", "")).name == "AGENTS.md" for r in refs)


def test_sensitive_content_surfaced_for_committed_file(git_repo, fixtures_dir: Path) -> None:
    """Issue #56: a committed instruction file carrying an IP / home path is
    surfaced (redacted) so the remediation can warn before any further commit."""
    repo, commit = git_repo
    good = (fixtures_dir / "good_instructions.md").read_text()
    _seed_assess(repo)
    (repo / "CLAUDE.md").write_text(
        good + "\n\n## Demo\nServer 203.0.113.7, ssh root@demo.example.com\n"
        "Config at /Users/ben/.config/app.yaml\n",
        encoding="utf-8",
    )
    commit("instructions with infra detail")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    flagged = ctx["sensitive_instruction_content"]
    assert "CLAUDE.md" in flagged
    cats = {f["category"] for f in flagged["CLAUDE.md"]}
    assert {"ip_address", "ssh_or_host", "home_path"} <= cats
    # Evidence must be redacted - no raw secret survives into run-context.
    blob = json.dumps(flagged)
    assert "203.0.113.7" not in blob and "/Users/ben" not in blob


def test_sensitive_content_surfaced_for_untracked_file(git_repo, fixtures_dir: Path) -> None:
    """Issue #56: the file the remediation might tell you to commit (an
    untracked CLAUDE.md) is scanned even though it isn't graded."""
    repo, commit = git_repo
    good = (fixtures_dir / "good_instructions.md").read_text()
    _seed_assess(repo)
    (repo / "README.md").write_text("# Repo", encoding="utf-8")
    commit("init")
    (repo / "CLAUDE.md").write_text(  # untracked
        good + "\nAWS key AKIAIOSFODNN7EXAMPLE\n", encoding="utf-8"
    )

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    assert "CLAUDE.md" in ctx["untracked_instruction_files"]   # not graded
    assert "CLAUDE.md" in ctx["sensitive_instruction_content"]  # but scanned
    assert any(f["category"] == "cloud_key"
               for f in ctx["sensitive_instruction_content"]["CLAUDE.md"])


def test_agents_md_symlink_alias_inherits_claude_grade(git_repo, fixtures_dir: Path) -> None:
    """Issue #57: AGENTS.md as a symlink to CLAUDE.md is the single-source-of-
    truth shape - it inherits CLAUDE.md's grade, not a standalone score."""
    import os
    repo, commit = git_repo
    good = (fixtures_dir / "good_instructions.md").read_text()
    _seed_assess(repo)
    (repo / "CLAUDE.md").write_text(good, encoding="utf-8")
    os.symlink("CLAUDE.md", repo / "AGENTS.md")
    commit("CLAUDE.md + AGENTS.md alias")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    files = ctx["instruction_files"]
    assert files["AGENTS.md"]["is_alias"] is True
    assert files["AGENTS.md"]["alias_target"] == "CLAUDE.md"
    assert files["AGENTS.md"]["grade"] == files["CLAUDE.md"]["grade"]


def test_agents_md_thin_stub_alias_inherits_grade(git_repo, fixtures_dir: Path) -> None:
    """Issue #57: a thin AGENTS.md stub pointing at CLAUDE.md inherits its grade
    instead of scoring low as a bespoke doc the remediation would rewrite."""
    repo, commit = git_repo
    good = (fixtures_dir / "good_instructions.md").read_text()
    _seed_assess(repo)
    (repo / "CLAUDE.md").write_text(good, encoding="utf-8")
    (repo / "AGENTS.md").write_text(
        "# AGENTS.md\n\nSee [CLAUDE.md](./CLAUDE.md) for all instructions.\n",
        encoding="utf-8",
    )
    commit("CLAUDE.md + thin AGENTS.md stub")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    files = ctx["instruction_files"]
    assert files["AGENTS.md"]["is_alias"] is True
    assert files["AGENTS.md"]["alias_target"] == "CLAUDE.md"
    assert files["AGENTS.md"]["grade"] == files["CLAUDE.md"]["grade"]


def test_ancestor_instruction_files_key_present(tmp_path: Path) -> None:
    """Issue #57: the ancestor-cascade signal is always surfaced as a list."""
    repo = _minimal_repo(tmp_path)
    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    assert isinstance(ctx["ancestor_instruction_files"], list)


def test_build_run_context_first_run(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """No prior .assess/, no instruction files - 'new' diff, empty instructions."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()

    current_stats = {
        "files_scored": 50,
        "loc": {"p50": 30, "p95": 200, "max": 500},
        "ccn": {"p50": 2, "p95": 8, "max": 20},
        "top_hotspots": [
            {"path": "src/a.go", "loc": 500, "ccn": 20, "commits": 5},
        ],
        "top_complex": [{"path": "src/a.go", "ccn": 20}],
        "top_large": [{"path": "src/a.go", "loc": 500}],
    }
    (assess_dir / "complexity-stats.json").write_text(json.dumps(current_stats))

    # Clear the ambient CI signal so the default (no-flag) run is genuinely
    # interactive regardless of where the suite runs (locally or under CI).
    monkeypatch.delenv("CI", raising=False)
    monkeypatch.delenv("ASSESS_NON_INTERACTIVE", raising=False)
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")

    assert ctx["run_date"] == "2026-05-22"
    assert ctx["stats_summary"]["files_scored"] == 50
    assert ctx["instruction_files"] == {}  # nothing found
    assert ctx["instructions_grade"] is None  # no instructions = None (distinct from F)
    assert ctx["diff"]["new"] == 1
    assert ctx["diff"]["graduated"] == 0
    assert (assess_dir / "log.md").exists()
    assert (assess_dir / "index.md").exists()
    # No decline markers in a bare repo -> empty block, no re-offer.
    assert ctx["decline_markers"] == []
    assert ctx["reoffer_mutation"] is False
    assert ctx["decline_disclosures"] == []
    # Default run (no --non-interactive, no CI env): interactive, offers left
    # empty for the orchestrator to present live - NOT pre-recorded as skipped.
    assert ctx["interactive"] is True
    assert ctx["offers"] == []

    # Explicit headless signal: every offer is pre-recorded as skipped and the
    # orchestrator makes zero prompts. This is the wiring the CLI --non-interactive
    # flag drives, verified independent of the ambient environment.
    ctx_headless = build_run_context(
        repo_root=repo, run_date="2026-05-22", non_interactive=True
    )
    assert ctx_headless["interactive"] is False
    assert {o["type"] for o in ctx_headless["offers"]}  # non-empty
    assert all(o["status"] == "skipped" for o in ctx_headless["offers"])


def test_build_run_context_surfaces_decline_markers(tmp_path: Path) -> None:
    """A JSON decline marker flows into run-context with provenance + disclosure."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 1, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))
    # Marker declined under an ancient major -> re-offer eligible.
    (assess_dir / ".no-mutmut").write_text(json.dumps({
        "declined_by": "ben", "declined_at": "2025-01-01",
        "plugin_version": "0.9.0",
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")

    markers = ctx["decline_markers"]
    assert len(markers) == 1
    assert markers[0]["tool"] == "mutmut"
    assert markers[0]["declined_by"] == "ben"
    assert ctx["reoffer_mutation"] is True
    assert any("Mutation testing permanently declined by ben on 2025-01-01" in d
               for d in ctx["decline_disclosures"])


def test_unfinalized_hotspot_page_uses_neutral_pointer_not_placeholder(tmp_path: Path) -> None:
    """A hotspot page the deterministic core writes - before any LLM finalize -
    must carry the neutral out-of-Top-3 pointer, never a TODO-style placeholder.

    assess_finalize only rewrites the pages it's handed actions for (at minimum
    the Top 3), so a flagged-but-not-Top-3 page can ship un-finalized. Its default
    "Suggested actions" body must read as intentional, not as unfinished work
    (issue #165).
    """
    from lib.wiki_writer import UNFINALIZED_ACTIONS_POINTER, slug_for_path

    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 50,
        "loc": {"p50": 30, "p95": 200, "max": 500},
        "ccn": {"p50": 2, "p95": 8, "max": 20},
        "top_hotspots": [{"path": "src/a.go", "loc": 500, "ccn": 20, "commits": 5}],
        "top_complex": [{"path": "src/a.go", "ccn": 20}],
        "top_large": [{"path": "src/a.go", "loc": 500}],
    }))

    build_run_context(repo_root=repo, run_date="2026-05-22")

    page = (assess_dir / "hotspots" / f"{slug_for_path('src/a.go')}.md").read_text(encoding="utf-8")
    # The "## Suggested actions" heading the finalizer keys off must survive.
    assert "## Suggested actions" in page
    # The neutral pointer is present...
    assert UNFINALIZED_ACTIONS_POINTER in page
    # ...and no TODO/placeholder marker leaks into the committed page.
    for marker in ("Pending LLM-generated suggestions", "TODO", "placeholder", "FIXME"):
        assert marker not in page


def test_hotspot_page_carries_growth_profile_when_file_accretes(git_repo) -> None:
    """A top-hotspot file that the accretion scan flags (monotonic growth, low
    deletion across several commits) gets the growth-profile line wired into its
    generated hotspot page - tasks 4+5 end-to-end."""
    from lib.wiki_writer import slug_for_path

    repo, commit = git_repo
    src = repo / "src"
    src.mkdir()
    grower = src / "grower.go"
    # Five commits that only add lines and never delete: pure accretion.
    for i in range(1, 6):
        grower.write_text("\n".join(f"line {n}" for n in range(i * 40)) + "\n")
        commit(f"grow {i}", days_ago=(6 - i) * 20)

    assess_dir = repo / ".assess"
    assess_dir.mkdir(exist_ok=True)
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 50,
        "loc": {"p50": 30, "p95": 200, "max": 500},
        "ccn": {"p50": 2, "p95": 8, "max": 20},
        "top_hotspots": [{"path": "src/grower.go", "loc": 200, "ccn": 20, "commits": 5}],
        "top_complex": [{"path": "src/grower.go", "ccn": 20}],
        "top_large": [{"path": "src/grower.go", "loc": 200}],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-06-17")
    # Precondition: the scan actually flagged this file (else the test proves nothing).
    flagged = {f["path"] for f in ctx["accretion_ratchet"].get("files", [])}
    assert "src/grower.go" in flagged

    # The block must also reach the keyhole: a populated accretion_ratchet block
    # is wired into the derived finding (assess_core passes it to integrate), so
    # the cross-layer finding lists the path - not just the run-context block.
    finding = next(
        f for f in ctx["derived_findings"] if f["name"] == "accretion_ratchet"
    )
    assert "src/grower.go" in finding["paths"]

    page = (assess_dir / "hotspots" / f"{slug_for_path('src/grower.go')}.md").read_text(
        encoding="utf-8"
    )
    assert "Growth profile: monotonic" in page
    assert "0 net reductions over" in page


def test_hotspot_page_omits_growth_profile_when_scan_unavailable(tmp_path: Path) -> None:
    """Graceful degradation: outside a git repo the accretion scan is
    unavailable, so the hotspot page is still written - just without a growth
    line. Hotspot generation never depends on the scan succeeding."""
    from lib.wiki_writer import slug_for_path

    repo = tmp_path / "repo"  # not a git repo
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 50,
        "loc": {"p50": 30, "p95": 200, "max": 500},
        "ccn": {"p50": 2, "p95": 8, "max": 20},
        "top_hotspots": [{"path": "src/a.go", "loc": 500, "ccn": 20, "commits": 5}],
        "top_complex": [{"path": "src/a.go", "ccn": 20}],
        "top_large": [{"path": "src/a.go", "loc": 500}],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-06-17")
    assert ctx["accretion_ratchet"]["available"] is False

    page = (assess_dir / "hotspots" / f"{slug_for_path('src/a.go')}.md").read_text(
        encoding="utf-8"
    )
    # Page exists and is complete, but carries no growth profile.
    assert "## Suggested actions" in page
    assert "Growth profile" not in page


def test_unfinalized_actions_pointer_carries_no_placeholder_marker() -> None:
    """The neutral pointer text itself must be free of TODO-style markers - it is
    the default that ships when a page is never finalized."""
    from lib.wiki_writer import UNFINALIZED_ACTIONS_POINTER

    lowered = UNFINALIZED_ACTIONS_POINTER.lower()
    for marker in ("pending", "todo", "placeholder", "fixme", "tbd"):
        assert marker not in lowered


def test_build_run_context_with_claude_md(tmp_path: Path, fixtures_dir: Path) -> None:
    repo = tmp_path / "repo"
    repo.mkdir()
    (repo / "CLAUDE.md").write_text((fixtures_dir / "good_instructions.md").read_text())
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert "CLAUDE.md" in ctx["instruction_files"]
    assert ctx["instruction_files"]["CLAUDE.md"]["grade"] in {"A", "A-", "B+", "B"}
    assert ctx["instruction_files"]["CLAUDE.md"]["subscores"]["positive_directives"] >= 5
    # Top-level instructions_grade reflects the best of the present files
    assert ctx["instructions_grade"] in {"A", "A-", "B+", "B"}


def test_build_run_context_with_agents_md(tmp_path: Path, fixtures_dir: Path) -> None:
    """The grader is filename-agnostic - works for AGENTS.md too."""
    repo = tmp_path / "repo"
    repo.mkdir()
    (repo / "AGENTS.md").write_text((fixtures_dir / "good_instructions.md").read_text())
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert "AGENTS.md" in ctx["instruction_files"]
    assert ctx["instruction_files"]["AGENTS.md"]["grade"] in {"A", "A-", "B+", "B"}


def test_build_run_context_with_multiple_instruction_files(tmp_path: Path, fixtures_dir: Path) -> None:
    """A repo can have CLAUDE.md AND AGENTS.md AND GEMINI.md (all pointing at the same content)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    good = (fixtures_dir / "good_instructions.md").read_text()
    bad = (fixtures_dir / "bad_instructions.md").read_text()
    (repo / "CLAUDE.md").write_text(good)
    (repo / "AGENTS.md").write_text(good)
    (repo / "GEMINI.md").write_text(bad)
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    keys = set(ctx["instruction_files"].keys())
    assert {"CLAUDE.md", "AGENTS.md", "GEMINI.md"} <= keys
    # Top-level grade reflects the BEST of the present files
    assert ctx["instructions_grade"] in {"A", "A-", "B+", "B"}


def test_build_run_context_second_run_sees_diff(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()

    # First run state - persist prior stats
    prior_stats = {
        "files_scored": 50, "loc": {"p50": 30, "p95": 200, "max": 500},
        "ccn": {"p50": 2, "p95": 8, "max": 20},
        "top_hotspots": [
            {"path": "src/legacy.go", "loc": 500, "ccn": 20, "commits": 5},
        ],
        "top_complex": [{"path": "src/legacy.go", "ccn": 20}],
        "top_large": [{"path": "src/legacy.go", "loc": 500}],
    }
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps(prior_stats))

    current_stats = {
        "files_scored": 55, "loc": {"p50": 30, "p95": 220, "max": 550},
        "ccn": {"p50": 2, "p95": 9, "max": 22},
        "top_hotspots": [
            {"path": "src/new.go", "loc": 400, "ccn": 18, "commits": 4},
        ],
        "top_complex": [{"path": "src/new.go", "ccn": 18}],
        "top_large": [{"path": "src/new.go", "loc": 400}],
    }
    (assess_dir / "complexity-stats.json").write_text(json.dumps(current_stats))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff"]["graduated"] == 1
    assert ctx["diff"]["new"] == 1


def test_graduated_index_row_carries_current_metrics(tmp_path: Path) -> None:
    """Issue #52 Bug 1: when a file graduates off top_hotspots[:10] but is
    still present in top_complex or top_large, the index row must show its
    *current* CCN and LOC, not 0. Zero in those columns reads as "the file
    was emptied," contradicts assess-report.md, and misleads reviewers."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()

    # Prior run: src/legacy.go was a top hotspot.
    prior_stats = {
        "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [
            {"path": "src/legacy.go", "loc": 1096, "ccn": 172, "commits": 5},
        ],
        "top_complex": [{"path": "src/legacy.go", "ccn": 172}],
        "top_large": [{"path": "src/legacy.go", "loc": 1096}],
    }
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps(prior_stats))

    # Current run: src/legacy.go dropped off top_hotspots (a bigger file
    # took its slot) but still appears in top_complex and top_large at its
    # actual current metrics. This is the case CodeRabbit caught.
    current_stats = {
        "files_scored": 55, "loc": {}, "ccn": {},
        "top_hotspots": [
            {"path": "src/giant.go", "loc": 2500, "ccn": 200, "commits": 8},
        ],
        "top_complex": [
            {"path": "src/giant.go", "ccn": 200},
            {"path": "src/legacy.go", "ccn": 172},
        ],
        "top_large": [
            {"path": "src/giant.go", "loc": 2500},
            {"path": "src/legacy.go", "loc": 1096},
        ],
    }
    (assess_dir / "complexity-stats.json").write_text(json.dumps(current_stats))

    build_run_context(repo_root=repo, run_date="2026-05-29")
    index = (assess_dir / "index.md").read_text(encoding="utf-8")

    # The graduated row must reflect reality: 1,096 LOC, ccn 172. NEVER 0.
    legacy_row = next(line for line in index.splitlines() if "src/legacy.go" in line)
    assert "graduated" in legacy_row
    assert "| 172 | 1096 |" in legacy_row, (
        f"expected current ccn/loc, got: {legacy_row}"
    )
    # The active row stays intact.
    assert "src/giant.go" in index


def test_graduated_index_row_uses_dash_when_metrics_unknown(tmp_path: Path) -> None:
    """When a graduated file fell off every top-N list (no current metrics
    available anywhere), the row renders `-` rather than misleading zeros."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()

    # Prior: src/legacy.go was a hotspot.
    prior_stats = {
        "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [
            {"path": "src/legacy.go", "loc": 800, "ccn": 90, "commits": 3},
        ],
        "top_complex": [{"path": "src/legacy.go", "ccn": 90}],
        "top_large": [{"path": "src/legacy.go", "loc": 800}],
    }
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps(prior_stats))

    # Current: src/legacy.go fell off ALL top-N lists (none of them mention it).
    current_stats = {
        "files_scored": 55, "loc": {}, "ccn": {},
        "top_hotspots": [
            {"path": "src/new.go", "loc": 600, "ccn": 80, "commits": 4},
        ],
        "top_complex": [{"path": "src/new.go", "ccn": 80}],
        "top_large": [{"path": "src/new.go", "loc": 600}],
    }
    (assess_dir / "complexity-stats.json").write_text(json.dumps(current_stats))

    build_run_context(repo_root=repo, run_date="2026-05-29")
    index = (assess_dir / "index.md").read_text(encoding="utf-8")
    legacy_row = next(line for line in index.splitlines() if "src/legacy.go" in line)
    # Sentinel "-" not "0" - never lie about the size.
    assert "| - | - |" in legacy_row


def test_build_run_context_writes_hotspot_pages(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [
            {"path": "src/foo.go", "loc": 500, "ccn": 20, "commits": 5},
        ],
        "top_complex": [{"path": "src/foo.go", "ccn": 20}],
        "top_large": [{"path": "src/foo.go", "loc": 500}],
    }))

    build_run_context(repo_root=repo, run_date="2026-05-22")
    hotspots = list((assess_dir / "hotspots").iterdir())
    assert len(hotspots) == 1
    assert hotspots[0].name.startswith("src-foo-go-")
    assert hotspots[0].name.endswith(".md")


def test_build_run_context_includes_anomalies_field(tmp_path: Path) -> None:
    """Every run-context.json must have an anomalies array (possibly empty)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0,
        "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert "anomalies" in ctx
    codes = {a["code"] for a in ctx["anomalies"]}
    assert "ZERO_FILES_SCORED" in codes


def test_run_context_has_deterministic_keyhole_products(tmp_path: Path) -> None:
    """assess-dogfooded Part 1: run-context.json carries the deterministic
    report-skeleton products - the pre-rendered findings markdown, the keyhole
    readiness summary, and the prescribed Top-3 actions - plus the eight derived
    findings (six original + E1/E2 trust axis)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 1, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/a.py", "loc": 100, "ccn": 12, "commits": 3}],
        "top_complex": [{"path": "src/a.py", "ccn": 12}],
        "top_large": [{"path": "src/a.py", "loc": 100}],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")

    # Task 2: deterministic findings markdown is present and well-formed.
    assert "findings_markdown" in ctx
    assert ctx["findings_markdown"].startswith(
        "## Cross-Layer Findings (Keyhole Readiness)"
    )
    # Task 3: keyhole readiness summary reported alongside the 0-8 score.
    assert "keyhole_summary" in ctx
    assert set(ctx["keyhole_summary"]) == {
        "concerns", "safe_zones", "total_concerns", "summary_text"
    }
    # Task 4: prescribed actions array exists (possibly empty for a clean repo).
    assert "prescribed_actions" in ctx
    assert isinstance(ctx["prescribed_actions"], list)
    # The low-signal marker is always emitted as a boolean beside attention.
    assert isinstance(ctx["attention_low_signal"], bool)
    # Task 5: derived findings now carry the nine named axes in fixed order.
    names = [f["name"] for f in ctx["derived_findings"]]
    assert names == [
        "hidden_coupling", "lying_map", "unexplained_complexity",
        "untrusted_hotspot", "self_referential_tests",
        "unactioned_intent", "accretion_ratchet",
        "orphaned_understanding", "candidate_dead_weight",
        "override_contradicts_signals", "refactor_boundary",
    ]


def test_instructions_grade_is_None_when_no_files(tmp_path: Path) -> None:
    """When no instruction file exists, instructions_grade is None (not 'F').

    Distinct from F: F means a file exists but scored badly. None means there's
    no file at all - different remediation ("create the file" vs "fix the file").
    """
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0,
        "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["instructions_grade"] is None
    assert ctx["instruction_files"] == {}


def test_repo_root_not_in_ctx(tmp_path: Path) -> None:
    """ctx should not contain repo_root - it leaks the author's absolute path.

    The LLM consumer has $REPO_ROOT from its shell context; no need to serialize it.
    """
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert "repo_root" not in ctx


def test_readside_blocks_present_in_ctx(tmp_path: Path) -> None:
    """run-context.json must carry the Layer 0/1 read-side blocks."""
    repo = _minimal_repo(tmp_path)
    (repo / "README.md").write_text("# Project\nsee [code](app.py)\n")
    (repo / "app.py").write_text("x = 1\n")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-27")
    for key in ("doc_graph", "doc_staleness", "stale_hubs", "dead_code", "observability"):
        assert key in ctx, f"missing read-side block: {key}"
    assert ctx["doc_graph"]["available"] is True
    assert ctx["doc_graph"]["doc_count"] == 1
    assert ctx["doc_staleness"]["available"] is True
    assert isinstance(ctx["stale_hubs"], list)
    assert "rung" in ctx["observability"]
    assert "candidate_count" in ctx["dead_code"]


def test_keyhole_blocks_present_and_backward_compatible(git_repo) -> None:
    """Task #5 integration barrier: build_run_context emits the five new keyhole
    blocks + derived findings while leaving every existing block intact."""
    repo, commit = git_repo
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    # A small history so the change-coupling / containment / authorship signals
    # have real git data to chew on.
    (repo / "README.md").write_text("# Project\nsee [code](src/app.py)\n")
    (repo / "src").mkdir()
    (repo / "src" / "app.py").write_text("def f():\n    return 1\n")
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 1, "loc": {"p50": 2, "p95": 2, "max": 2},
        "ccn": {"p50": 1, "p95": 1, "max": 1},
        "top_hotspots": [{"path": "src/app.py", "loc": 2, "ccn": 1, "commits": 2}],
        "top_complex": [{"path": "src/app.py", "ccn": 1}],
        "top_large": [{"path": "src/app.py", "loc": 2}],
    }))
    commit("init")
    (repo / "src" / "app.py").write_text("def f():\n    return 2\n")
    commit("change")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-29")

    # (1) All five new blocks present.
    for key in ("structure", "behaviour", "documentation", "understanding", "runtime"):
        assert key in ctx, f"missing keyhole block: {key}"
    # structure carries available/reason so the report can say "grimp absent".
    assert "available" in ctx["structure"]
    assert "containment_by_dir" in ctx["behaviour"]
    assert "freshness_by_doc" in ctx["documentation"]
    assert "authorship_class_by_path" in ctx["understanding"]
    assert "static_reachability" in ctx["runtime"]

    # (2) derived_findings populated; every finding has name/paths/action.
    assert "derived_findings" in ctx
    findings = ctx["derived_findings"]
    assert findings, "derived_findings must not be empty"
    expected = {"hidden_coupling", "lying_map", "unexplained_complexity",
                "untrusted_hotspot", "self_referential_tests",
                "unactioned_intent", "accretion_ratchet",
                "orphaned_understanding", "candidate_dead_weight",
                "override_contradicts_signals", "refactor_boundary"}
    assert {f["name"] for f in findings} == expected
    for f in findings:
        assert set(f) == {"name", "paths", "action"}
        assert isinstance(f["paths"], list)
        assert isinstance(f["action"], str) and f["action"]
    assert "attention" in ctx
    assert isinstance(ctx["attention"], list)

    # (3) Existing blocks unchanged (backward-compat): the pre-existing shape
    # is all still there alongside the additions.
    for key in ("run_date", "stats_summary", "instruction_files", "diff",
                "doc_graph", "doc_staleness", "stale_hubs", "dead_code",
                "observability", "anomalies", "plugin_version"):
        assert key in ctx, f"existing block dropped: {key}"


def test_keyhole_signal_failure_degrades_not_crashes(tmp_path: Path, monkeypatch) -> None:
    """A raising keyhole signal must degrade to available:false, not crash the
    run or disturb the existing blocks (defensive-wiring constraint)."""
    repo = _minimal_repo(tmp_path)

    def boom(*_a, **_k):
        raise RuntimeError("simulated structure failure")

    monkeypatch.setattr(assess_core, "analyze_structure", boom)
    ctx = build_run_context(repo_root=repo, run_date="2026-05-29")
    assert ctx["structure"]["available"] is False
    assert "failed" in ctx["structure"]["reason"]
    # The rest of the run is intact, including the other keyhole blocks.
    assert "behaviour" in ctx
    assert "derived_findings" in ctx
    assert "observability" in ctx


def test_stale_hubs_join_centrality_and_staleness(tmp_path: Path) -> None:
    """stale_hubs ranks central docs by pagerank x staleness ratio."""
    repo = _minimal_repo(tmp_path)
    (repo / "hub.md").write_text("hub")
    for i in range(3):
        (repo / f"leaf{i}.md").write_text("see [hub](hub.md)")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-27")
    # Each stale-hub row carries both the centrality and staleness factors,
    # plus the subject_method + confidence that surface coarse-proxy entries.
    if ctx["stale_hubs"]:
        row = ctx["stale_hubs"][0]
        assert {"path", "pagerank", "ratio", "priority",
                "subject_method", "confidence"} <= set(row)
        assert row["confidence"] in {"low", "high"}


def test_stale_hubs_confidence_low_for_repo_baseline(tmp_path: Path) -> None:
    """Hubs whose subject_method is repo-baseline must surface confidence=low.

    Without a derivable subject, the staleness ratio shares a denominator with
    every other baseline entry - the priority composite looks comparable when
    it isn't. The confidence flag lets the report discount accordingly.
    """
    repo = _minimal_repo(tmp_path)
    (repo / "hub.md").write_text("hub with no association")
    for i in range(3):
        (repo / f"leaf{i}.md").write_text("see [hub](hub.md)")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-28")
    # All docs here are floating (no co-location, no parallel docs/, no explicit
    # links), so every staleness entry falls back to repo-baseline.
    assert ctx["doc_staleness"]["available"] is True
    for d in ctx["doc_staleness"]["docs"]:
        if d["subject_method"] == "repo-baseline":
            assert d["confidence"] == "low"
    for h in ctx["stale_hubs"]:
        if h["subject_method"] == "repo-baseline":
            assert h["confidence"] == "low"


def test_stale_hubs_sort_deweights_low_confidence(tmp_path: Path) -> None:
    """A precise-subject hub at half the raw priority of a baseline hub still
    outranks it. The sort multiplies low-confidence priority by 0.5.
    """
    from assess_core import _build_stale_hubs  # type: ignore[import-not-found]

    doc_graph = {
        "available": True,
        "hubs": [
            {"path": "baseline.md", "pagerank": 1.0},
            {"path": "precise.md", "pagerank": 0.6},
        ],
    }
    doc_staleness = {
        "available": True,
        "docs": [
            {"path": "baseline.md", "last_commit_days": 100,
             "code_churn_in_window": 500, "ratio": 100.0,
             "subject_method": "repo-baseline", "confidence": "low"},
            {"path": "precise.md", "last_commit_days": 100,
             "code_churn_in_window": 20, "ratio": 80.0,
             "subject_method": "nearest-ancestor", "confidence": "high"},
        ],
    }
    hubs = _build_stale_hubs(doc_graph, doc_staleness)
    # Raw priorities: baseline = 100.0 * 1.0 = 100; precise = 80.0 * 0.6 = 48.
    # After the 0.5x low-confidence multiplier in the sort: baseline -> 50,
    # precise -> 48; baseline still wins. Test the inverse case directly.
    doc_staleness_b = dict(doc_staleness)
    doc_staleness_b["docs"] = [
        {"path": "baseline.md", "last_commit_days": 100,
         "code_churn_in_window": 200, "ratio": 80.0,
         "subject_method": "repo-baseline", "confidence": "low"},
        {"path": "precise.md", "last_commit_days": 100,
         "code_churn_in_window": 20, "ratio": 70.0,
         "subject_method": "nearest-ancestor", "confidence": "high"},
    ]
    hubs = _build_stale_hubs(doc_graph, doc_staleness_b)
    # baseline raw = 80.0 -> sorted at 40; precise raw = 42.0 -> wins.
    assert hubs[0]["path"] == "precise.md"
    # Raw priority still reflects the unweighted composite (for transparency).
    assert hubs[0]["priority"] == 42.0


def test_readside_scan_failure_degrades_not_crashes(tmp_path: Path, monkeypatch) -> None:
    """A raising scan must degrade to an unavailable marker, not blow up the run."""
    repo = _minimal_repo(tmp_path)

    def boom(*_a, **_k):
        raise RuntimeError("simulated scan failure")

    monkeypatch.setattr(assess_core, "build_doc_graph", boom)
    ctx = build_run_context(repo_root=repo, run_date="2026-05-27")
    assert ctx["doc_graph"]["available"] is False
    assert "failed" in ctx["doc_graph"]["reason"]
    # downstream blocks still present
    assert "observability" in ctx
    assert ctx["stale_hubs"] == []  # can't join hubs without a graph


def test_failed_liveness_scan_is_not_scored_rung_0(tmp_path: Path, monkeypatch) -> None:
    """A failed liveness scan must read as 'not assessed' (rung null), not as a
    genuine rung 0 (no observability) - conflating them mis-scores Layer 1."""
    repo = _minimal_repo(tmp_path)

    def boom(*_a, **_k):
        raise RuntimeError("liveness blew up")

    monkeypatch.setattr(assess_core, "scan_liveness", boom)
    ctx = build_run_context(repo_root=repo, run_date="2026-05-27")
    assert ctx["observability"]["available"] is False
    assert ctx["observability"]["rung"] is None  # not 0
    assert "reason" in ctx["observability"]
    assert ctx["dead_code"]["available"] is False


def test_plugin_version_in_ctx(tmp_path: Path) -> None:
    """ctx should include plugin_version so the LLM can surface it in the report.

    Mitigates the multi-version cache footgun: if /reload-plugins lands on an old
    cached version, the report shows that version and the user can spot the drift.
    """
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert "plugin_version" in ctx
    assert isinstance(ctx["plugin_version"], str)
    assert ctx["plugin_version"].count(".") >= 1


def test_scans_github_claude_instructions(tmp_path: Path, fixtures_dir: Path) -> None:
    """The scan finds .github/claude-instructions.md - a real-world non-canonical location.

    Surfaced by the v1.4 meridian run: .github/claude-review-instructions.md was a
    legitimate 795-line breadcrumb file that the canonical-paths-only scan missed.
    """
    repo = tmp_path / "repo"
    repo.mkdir()
    github_dir = repo / ".github"
    github_dir.mkdir()
    (github_dir / "claude-instructions.md").write_text(
        (fixtures_dir / "good_instructions.md").read_text()
    )

    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ".github/claude-instructions.md" in ctx["instruction_files"]


def test_scans_github_claude_review_instructions(tmp_path: Path, fixtures_dir: Path) -> None:
    """The scan finds .github/claude-review-instructions.md (used by claude-review bots)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    github_dir = repo / ".github"
    github_dir.mkdir()
    (github_dir / "claude-review-instructions.md").write_text(
        (fixtures_dir / "good_instructions.md").read_text()
    )

    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ".github/claude-review-instructions.md" in ctx["instruction_files"]


def test_scans_docs_subdirectory(tmp_path: Path, fixtures_dir: Path) -> None:
    """The scan finds docs/CLAUDE.md (some projects keep instruction files there)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    docs_dir = repo / "docs"
    docs_dir.mkdir()
    (docs_dir / "CLAUDE.md").write_text(
        (fixtures_dir / "good_instructions.md").read_text()
    )

    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 0, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))

    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert "docs/CLAUDE.md" in ctx["instruction_files"]


def test_briefing_includes_loc_ccn_commits_and_status(tmp_path: Path) -> None:
    """The auto-generated briefing should reflect the actual stats, not be vague."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [
            {"path": "src/foo.go", "loc": 500, "ccn": 20, "commits": 15},
        ],
        "top_complex": [{"path": "src/foo.go", "ccn": 20}],
        "top_large": [{"path": "src/foo.go", "loc": 500}],
    }))
    build_run_context(repo_root=repo, run_date="2026-05-22")

    page = next((assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert "500 LOC" in content
    assert "max cyclomatic complexity 20" in content
    assert "15 commits" in content
    # has_tests should be "unknown" now, not "no"
    assert "Has test file | unknown" in content


def test_has_sibling_test_detects_colocated_and_adjacent(tmp_path: Path) -> None:
    """Co-located and adjacent-dir test files lift has_tests from unknown to
    yes/no cheaply (issue #47, observation 6)."""
    repo = tmp_path / "repo"
    (repo / "go").mkdir(parents=True)
    (repo / "go" / "foo.go").write_text("package foo")
    (repo / "go" / "foo_test.go").write_text("package foo")  # co-located
    (repo / "ts").mkdir()
    (repo / "ts" / "bar.ts").write_text("export const x = 1")
    (repo / "ts" / "bar.test.ts").write_text("test")          # co-located .test.
    (repo / "py").mkdir()
    (repo / "py" / "baz.py").write_text("x = 1")              # no test
    (repo / "svc").mkdir()
    (repo / "svc" / "api.py").write_text("x = 1")
    (repo / "svc" / "__tests__").mkdir()
    (repo / "svc" / "__tests__" / "test_api.py").write_text("t")  # adjacent dir

    assert assess_core._has_sibling_test(repo, "go/foo.go") is True
    assert assess_core._has_sibling_test(repo, "ts/bar.ts") is True
    assert assess_core._has_sibling_test(repo, "py/baz.py") is False
    assert assess_core._has_sibling_test(repo, "svc/api.py") is True
    # The file is itself a test -> counts as covered.
    assert assess_core._has_sibling_test(repo, "go/foo_test.go") is True
    # Not on disk (e.g. a since-deleted path in a stats snapshot) -> unknown.
    assert assess_core._has_sibling_test(repo, "go/gone.go") is None


def test_hotspot_page_shows_yes_when_sibling_test_exists(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    (repo / "src").mkdir(parents=True)
    (repo / "src" / "foo.go").write_text("package foo")
    (repo / "src" / "foo_test.go").write_text("package foo")
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [{"path": "src/foo.go", "loc": 500, "ccn": 20, "commits": 5}],
        "top_complex": [], "top_large": [],
    }))
    build_run_context(repo_root=repo, run_date="2026-05-22")
    content = next((assess_dir / "hotspots").iterdir()).read_text(encoding="utf-8")
    assert "Has test file | yes" in content


def test_commits_read_from_legacy_churn_field(tmp_path: Path) -> None:
    """A stats snapshot using the legacy `churn` key still shows real commits in
    the hotspot page, not 0 (issue #47, observation 5)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 10, "loc": {"p50": 10, "p95": 30, "max": 50},
        "ccn": {"p50": 1, "p95": 3, "max": 5},
        "top_hotspots": [{"path": "src/foo.go", "loc": 500, "ccn": 20, "churn": 33}],
        "top_complex": [], "top_large": [],
    }))
    build_run_context(repo_root=repo, run_date="2026-05-22")
    content = next((assess_dir / "hotspots").iterdir()).read_text(encoding="utf-8")
    assert "33 commits" in content
    assert "Commits in churn window | 33" in content


def test_diff_is_reliable_pure_matrix() -> None:
    """Direct unit coverage of the pure reliability decision, independent of the
    full pipeline."""
    from assess_core import _diff_is_reliable  # type: ignore[import-not-found]

    # Missing prior version stamp.
    assert _diff_is_reliable(None, "1.0.0", 1, 1) == (
        False, "version not stamped in prior snapshot"
    )
    # Unparseable version.
    ok, note = _diff_is_reliable("not-a-version", "1.0.0", 1, 1)
    assert ok is False and "unparseable" in note
    # Schema delta.
    assert _diff_is_reliable("1.0.0", "1.0.1", 1, 2) == (
        False, "schema version changed 1->2"
    )
    # Major delta.
    assert _diff_is_reliable("1.9.9", "2.0.0", 1, 1) == (
        False, "major version changed 1.9.9->2.0.0"
    )
    # Minor/patch only -> reliable.
    assert _diff_is_reliable("1.2.3", "1.5.0", 1, 1) == (True, None)
    assert _diff_is_reliable("1.2.3", "1.2.3", 1, 1) == (True, None)


def test_diff_unreliable_when_prior_snapshot_lacks_version_stamp(tmp_path: Path) -> None:
    """A prior snapshot that never stamped a plugin version can't establish
    comparability, so the diff is flagged unreliable to suppress phantom
    transitions (issue #47, observation 4). The note names the exact reason."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps({
        # No plugin_version: seeded by hand / written by an older plugin.
        "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/old.go", "loc": 500, "ccn": 20, "commits": 5}],
    }))
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "plugin_version": "1.12.0",
        "files_scored": 55, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/new.go", "loc": 400, "ccn": 18, "commits": 4}],
    }))
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff_reliable"] is False
    assert ctx["diff_version_note"] == "version not stamped in prior snapshot"
    assert ctx["diff_trend_reset"] is False


def test_diff_reliable_when_plugin_versions_match(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    stats = {
        "plugin_version": "1.12.0", "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/a.go", "loc": 500, "ccn": 20, "commits": 5}],
    }
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps(stats))
    (assess_dir / "complexity-stats.json").write_text(json.dumps(stats))
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff_reliable"] is True
    assert ctx["diff_version_note"] is None


def _seed_prior_current(
    tmp_path: Path, prior_extra: dict, current_extra: dict,
) -> Path:
    """Seed a repo with a prior and current stats sidecar sharing one hotspot,
    each merged with the caller's version/schema/tool stamps."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    base = {
        "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/a.go", "loc": 500, "ccn": 20, "commits": 5}],
    }
    (assess_dir / "complexity-stats.prior.json").write_text(
        json.dumps({**base, **prior_extra})
    )
    (assess_dir / "complexity-stats.json").write_text(
        json.dumps({**base, **current_extra})
    )
    return repo


def test_diff_reliable_across_patch_bump_keeps_gate_armed(tmp_path: Path) -> None:
    """A patch/minor plugin bump with an unchanged schema and toolchain keeps the
    diff reliable so the trend and regression gate stay armed."""
    stamp = {"schema_version": 1, "lizard_version": "1.23.0"}
    repo = _seed_prior_current(
        tmp_path,
        {"plugin_version": "1.54.0", **stamp},
        {"plugin_version": "1.54.1", **stamp},
    )
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff_reliable"] is True
    assert ctx["diff_version_note"] is None
    assert ctx["diff_trend_reset"] is False


def test_diff_unreliable_on_lizard_version_change_names_tool(tmp_path: Path) -> None:
    """A complexity-backend version change voids the diff and names the tool, so
    a score shift from the tool isn't read as a real regression."""
    repo = _seed_prior_current(
        tmp_path,
        {"plugin_version": "1.54.1", "schema_version": 1, "lizard_version": "1.22.0"},
        {"plugin_version": "1.54.1", "schema_version": 1, "lizard_version": "1.23.0"},
    )
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff_reliable"] is False
    assert "lizard" in ctx["diff_version_note"]
    assert "1.22.0->1.23.0" in ctx["diff_version_note"]
    assert ctx["diff_trend_reset"] is False


def test_diff_major_bump_resets_trend(tmp_path: Path) -> None:
    """A MAJOR plugin bump voids the diff and flags a trend reset, which the
    report discloses explicitly."""
    stamp = {"schema_version": 1, "lizard_version": "1.23.0"}
    repo = _seed_prior_current(
        tmp_path,
        {"plugin_version": "1.54.1", **stamp},
        {"plugin_version": "2.0.0", **stamp},
    )
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff_reliable"] is False
    assert ctx["diff_trend_reset"] is True
    assert "major version changed 1.54.1->2.0.0" in ctx["diff_version_note"]


def test_diff_unreliable_on_schema_change(tmp_path: Path) -> None:
    """A stats schema-version delta voids the diff: the sidecar shape the diff
    reads moved, so the comparison isn't trustworthy."""
    repo = _seed_prior_current(
        tmp_path,
        {"plugin_version": "1.54.1", "schema_version": 1, "lizard_version": "1.23.0"},
        {"plugin_version": "1.54.2", "schema_version": 2, "lizard_version": "1.23.0"},
    )
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["diff_reliable"] is False
    assert "schema version changed 1->2" in ctx["diff_version_note"]
    assert ctx["diff_trend_reset"] is False


def test_tool_versions_surface_in_run_context(tmp_path: Path) -> None:
    """The toolchain the snapshot was produced with is surfaced for the report
    and gate to reason about comparability."""
    repo = _seed_prior_current(
        tmp_path,
        {"plugin_version": "1.54.1", "schema_version": 1, "lizard_version": "1.23.0"},
        {"plugin_version": "1.54.1", "schema_version": 1, "lizard_version": "1.23.0",
         "scc_version": "3.7.0"},
    )
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["tool_versions"] == {"lizard": "1.23.0", "scc": "3.7.0"}
    assert ctx["prior_tool_versions"] == {"lizard": "1.23.0"}
    assert ctx["schema_version"] == 1


def test_first_flagged_unknown_when_prior_seeded_without_history(tmp_path: Path) -> None:
    """When prior stats are seeded but first-flagged.json isn't, a hotspot that
    predates this run must read 'unknown', not today's date
    (issue #47, observation 7)."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    # Same hotspot in prior and current -> persistent, predates this run.
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps({
        "plugin_version": "1.12.0", "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/old.go", "loc": 500, "ccn": 20, "commits": 5}],
    }))
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "plugin_version": "1.12.0", "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/old.go", "loc": 510, "ccn": 21, "commits": 6}],
    }))
    # No first-flagged.json on disk.
    build_run_context(repo_root=repo, run_date="2026-05-22")
    page = next((assess_dir / "hotspots").iterdir()).read_text(encoding="utf-8")
    assert "First flagged: unknown" in page
    assert "First flagged: 2026-05-22" not in page


def test_first_flagged_stamps_today_for_genuinely_new_hotspot(tmp_path: Path) -> None:
    """A hotspot absent from the prior snapshot is genuinely new -> today."""
    repo = tmp_path / "repo"
    repo.mkdir()
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.prior.json").write_text(json.dumps({
        "plugin_version": "1.12.0", "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/old.go", "loc": 500, "ccn": 20, "commits": 5}],
    }))
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "plugin_version": "1.12.0", "files_scored": 50, "loc": {}, "ccn": {},
        "top_hotspots": [{"path": "src/fresh.go", "loc": 400, "ccn": 18, "commits": 4}],
    }))
    build_run_context(repo_root=repo, run_date="2026-05-22")
    fresh_page = next(p for p in (assess_dir / "hotspots").iterdir()
                      if p.name.startswith("src-fresh-go-"))
    assert "First flagged: 2026-05-22" in fresh_page.read_text(encoding="utf-8")


def test_config_excludes_apply_to_all_scans(tmp_path: Path) -> None:
    """`.assess/config.toml` excludes are loaded once by the orchestrator
    and applied uniformly to the doc graph, doc staleness, and liveness
    scan. A `regulatory-raw/` dir vanishes from every layer's view, not
    just the treemap. This is the single load-bearing test for the
    consistent-excludes design - if it passes, the schema rename and the
    per-scan plumbing are wired correctly end-to-end."""
    repo = _minimal_repo(tmp_path)
    # Config opt-in.
    (repo / ".assess" / "config.toml").write_text(
        'exclude_dirs = ["regulatory-raw"]\n',
        encoding="utf-8",
    )
    # Two docs (one in scope, one excluded) and two code files (same).
    (repo / "README.md").write_text("see [main](./src/app.py)\n", encoding="utf-8")
    (repo / "src").mkdir()
    (repo / "src" / "app.py").write_text("def used(): pass\n", encoding="utf-8")
    (repo / "regulatory-raw").mkdir()
    (repo / "regulatory-raw" / "notes.md").write_text("ref data note\n", encoding="utf-8")
    (repo / "regulatory-raw" / "loader.py").write_text("x = 1\n", encoding="utf-8")

    ctx = build_run_context(repo_root=repo, run_date="2026-05-29")

    # Doc graph: only README.md is counted.
    assert ctx["doc_graph"]["doc_count"] == 1
    # Doc staleness: only the in-scope doc + code file are counted.
    assert ctx["doc_staleness"]["association"]["doc_count"] == 1
    assert ctx["doc_staleness"]["association"]["code_file_count"] == 1
    # Liveness: any candidate paths from the dead-code scan must not
    # mention regulatory-raw (vulture etc. would either skip the dir
    # via --exclude or get post-filtered).
    for c in ctx["dead_code"].get("candidates", []):
        assert "regulatory-raw" not in c.get("path", "")


# ════════════════════════════════════════════════════════════════════════════
# Task 4 - test_pressure wiring into build_run_context / run-context.json
# ════════════════════════════════════════════════════════════════════════════

def test_test_pressure_block_present_in_ct

"""End-to-end test for assess_finalize - the LLM write-back script."""
from __future__ import annotations

import json
from pathlib import Path

import pytest

from assess_finalize import FinalizeValidationError, finalize_run


def _seed_run_context(
    assess_dir: Path,
    *,
    denominator: int = 8,
    hotspots: tuple[str, ...] = ("src/foo.go",),
    mutation_run: bool = True,
    run_id: str | None = None,
) -> None:
    """Write a minimal valid run-context.json for finalize to reconcile against.

    finalize now reads run-context.json first and enforces invariants against it,
    so every finalize test seeds a matching context. Defaults produce a
    software-repo (denominator 8) context whose top hotspots and mutation state
    satisfy the invariants; individual tests override to exercise a violation.
    """
    ctx: dict = {
        "archetype": {"available": True, "denominator": denominator},
        "stats_summary": {
            "top_hotspots": [{"path": p} for p in hotspots],
        },
        "mutation_not_run_cap": {
            "applies": not mutation_run,
            "mutation_run": mutation_run,
            "max_layer6_band": "Present" if mutation_run else "Partial",
            "annotation": (
                None if mutation_run
                else "truth-pressure unproven (mutation not run)"
            ),
        },
    }
    if run_id is not None:
        ctx["run_id"] = run_id
    (assess_dir / "run-context.json").write_text(json.dumps(ctx), encoding="utf-8")


def _seed_log_md(assess_dir: Path) -> None:
    """Seed a log.md with one entry that has placeholders awaiting LLM fill."""
    (assess_dir / "log.md").write_text(
        "# Assess Log\n\n"
        "## 2026-05-22\n\n"
        "- **Files scored:** 100\n"
        "- **AI Readiness:** 0.0 / 8 ((LLM fills in))\n"
        "- **Instructions grade:** B+\n"
        "- **Hotspot transitions:** 1 graduated, 0 regressed, 0 new, 2 persistent\n"
        "- **Top action:** Deterministic ranker not yet wired (LLM picks Top 3)\n\n"
        "[Full report](./assess-report.md)\n\n"
        "---\n",
        encoding="utf-8",
    )


def _seed_hotspot_page(assess_dir: Path, slug: str) -> None:
    (assess_dir / "hotspots").mkdir(exist_ok=True)
    (assess_dir / "hotspots" / f"{slug}.md").write_text(
        "# Hotspot: `src/foo.go`\n\n"
        "## Suggested actions\n\n"
        "- Pending LLM-generated suggestions\n",
        encoding="utf-8",
    )


def test_finalize_updates_log_last_entry(tmp_assess_dir: Path) -> None:
    """The latest log.md entry gets its placeholders replaced with LLM-provided values."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    finalize_input = {
        "score": 6.0,
        "maturity_label": "Solid",
        "top_action": "Add cyclop rule to .golangci.yml (threshold 15)",
        "hotspot_actions": {},
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "AI Readiness:** 6.0 / 8 (Solid)" in content
    assert "Top action:** Add cyclop rule to .golangci.yml (threshold 15)" in content
    # Placeholders must be gone
    assert "((LLM fills in))" not in content
    assert "Deterministic ranker not yet wired" not in content


def test_finalize_knowledge_base_denominator(tmp_assess_dir: Path) -> None:
    """A KB run finalises the log over its applicable-layer denominator (#224).

    The score is renormalised in the log/report line; it is deliberately NOT
    written to the badge, which stays the deterministic form assess_core wrote.
    """
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, denominator=3)
    finalize_input = {
        "score": 2.5,
        "maturity_label": "Knowledge Base · Solid (3 applicable layers)",
        "denominator": 3,
        "top_action": "Document the KB maintenance workflow in CLAUDE.md",
        "hotspot_actions": {},
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "AI Readiness:** 2.5 / 3 (Knowledge Base · Solid (3 applicable layers))" in content
    assert "/ 8" not in content  # the misleading software denominator is gone
    # Finalize writes no badge - the score lives in the report line above, not
    # on the shipped (deterministic) badge.
    assert not (tmp_assess_dir / "badge.json").exists()


def test_finalize_updates_hotspot_actions(tmp_assess_dir: Path) -> None:
    """Hotspot pages get their 'Suggested actions' section rewritten with LLM input."""
    # The slug for "src/foo.go" includes a sha256[:8] hash - use the same function the script uses
    from lib.wiki_writer import slug_for_path
    slug = slug_for_path("src/foo.go")
    _seed_hotspot_page(tmp_assess_dir, slug=slug)
    finalize_input = {
        "score": 6.0,
        "maturity_label": "Solid",
        "top_action": "x",
        "hotspot_actions": {
            "src/foo.go": [
                "Split parseLine into smaller functions",
                "Add a test file at src/foo_test.go",
            ],
        },
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )
    # Need a log.md too since finalize_run does both
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)

    finalize_run(assess_dir=tmp_assess_dir)
    page = (tmp_assess_dir / "hotspots" / f"{slug}.md").read_text(encoding="utf-8")
    assert "Split parseLine" in page
    assert "Add a test file at src/foo_test.go" in page
    assert "Pending LLM-generated suggestions" not in page


def test_finalize_missing_input_raises(tmp_assess_dir: Path) -> None:
    """If finalize-input.json doesn't exist, raise a clear error."""
    with pytest.raises(FileNotFoundError):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_hotspot_without_match_is_skipped(tmp_assess_dir: Path) -> None:
    """An entry in hotspot_actions whose page doesn't exist is silently skipped.

    This is forward-compatible with the path lifecycle: a hotspot might graduate
    between when the LLM read the data and when finalize runs.
    """
    _seed_log_md(tmp_assess_dir)
    # The referenced path IS a real top hotspot in run-context (so it clears the
    # fabrication invariant); its wiki page simply doesn't exist, which is the
    # lifecycle case this test covers (graduated between LLM read and finalize).
    _seed_run_context(tmp_assess_dir, hotspots=("src/nonexistent.go",))
    finalize_input = {
        "score": 6.0,
        "maturity_label": "Solid",
        "top_action": "x",
        "hotspot_actions": {"src/nonexistent.go": ["something"]},
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    # Should not raise
    finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_log_handles_backslash_in_top_action(tmp_assess_dir: Path) -> None:
    """Top action text containing \\1 must be inserted literally, not as a regex backreference."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    finalize_input = {
        "score": 6.0,
        "maturity_label": "Solid",
        # Adversarial: contains \1 which would be a re.sub backreference if not handled
        "top_action": r"Replace `\1` capture group references in regexes",
        "hotspot_actions": {},
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert r"Replace `\1` capture group references" in content


def test_finalize_hotspot_action_handles_backslash(tmp_assess_dir: Path) -> None:
    """Hotspot action text containing \\1 must be inserted literally."""
    from lib.wiki_writer import slug_for_path
    slug = slug_for_path("src/foo.go")
    _seed_hotspot_page(tmp_assess_dir, slug=slug)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    finalize_input = {
        "score": 6.0,
        "maturity_label": "Solid",
        "top_action": "x",
        "hotspot_actions": {
            "src/foo.go": [
                r"Use \1 to denote first capture group",
                "Add tests",
            ],
        },
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)
    page = (tmp_assess_dir / "hotspots" / f"{slug}.md").read_text(encoding="utf-8")
    assert r"Use \1 to denote first capture group" in page


def test_finalize_reads_from_cache_path(tmp_assess_dir: Path) -> None:
    """The preferred input location is `.assess/.cache/finalize-input.json`."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    cache_dir = tmp_assess_dir / ".cache"
    cache_dir.mkdir()
    (cache_dir / "finalize-input.json").write_text(
        json.dumps({
            "score": 7.0, "maturity_label": "AI-Native",
            "top_action": "x", "hotspot_actions": {},
        }),
        encoding="utf-8",
    )

    finalize_run(assess_dir=tmp_assess_dir)
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "AI Readiness:** 7.0 / 8 (AI-Native)" in content


def test_finalize_deletes_input_after_success(tmp_assess_dir: Path) -> None:
    """The input file is one-off: delete it on success so it can't leak into commits."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    legacy = tmp_assess_dir / "finalize-input.json"
    legacy.write_text(
        json.dumps({
            "score": 6.0, "maturity_label": "Solid",
            "top_action": "x", "hotspot_actions": {},
        }),
        encoding="utf-8",
    )

    finalize_run(assess_dir=tmp_assess_dir)
    assert not legacy.exists()


def test_finalize_cleans_up_legacy_when_cache_present(tmp_assess_dir: Path) -> None:
    """If both cache and legacy paths exist (e.g. an older run left a stale
    legacy file), finalize prefers cache and cleans up both.
    """
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    cache_dir = tmp_assess_dir / ".cache"
    cache_dir.mkdir()
    cache_path = cache_dir / "finalize-input.json"
    cache_path.write_text(
        json.dumps({
            "score": 7.0, "maturity_label": "AI-Native",
            "top_action": "current", "hotspot_actions": {},
        }),
        encoding="utf-8",
    )
    legacy = tmp_assess_dir / "finalize-input.json"
    legacy.write_text(
        json.dumps({
            "score": 3.0, "maturity_label": "Basic",
            "top_action": "stale", "hotspot_actions": {},
        }),
        encoding="utf-8",
    )

    finalize_run(assess_dir=tmp_assess_dir)
    # Cache wins (the value the report just published).
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "AI-Native" in content
    # Both files cleaned up.
    assert not cache_path.exists()
    assert not legacy.exists()


def test_finalize_updates_last_entry_when_older_entry_unfinalized(tmp_assess_dir: Path) -> None:
    """When an older log entry still has placeholders, finalize updates the LATEST.

    Log entries are appended (newest at bottom). If we finalized the first match,
    we'd overwrite stale historical data and leave the new run unfilled.
    The older unfinalized entry stays as evidence of "this run wasn't finalized."
    """
    _seed_run_context(tmp_assess_dir)
    # Seed two entries: older (unfinalized, placeholders intact) then newer (also placeholders)
    (tmp_assess_dir / "log.md").write_text(
        "# Assess Log\n\n"
        "## 2026-05-01\n\n"
        "- **Files scored:** 80\n"
        "- **AI Readiness:** 0.0 / 8 ((LLM fills in))\n"
        "- **Top action:** Deterministic ranker not yet wired (LLM picks Top 3)\n\n"
        "---\n\n"
        "## 2026-05-22\n\n"
        "- **Files scored:** 100\n"
        "- **AI Readiness:** 0.0 / 8 ((LLM fills in))\n"
        "- **Top action:** Deterministic ranker not yet wired (LLM picks Top 3)\n\n"
        "---\n",
        encoding="utf-8",
    )
    finalize_input = {
        "score": 6.5,
        "maturity_label": "Solid",
        "top_action": "Add cyclop rule (threshold 15) to .golangci.yml",
        "hotspot_actions": {},
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")

    # The 2026-05-22 (latest) entry got filled
    latest_section = content.split("## 2026-05-22")[1]
    assert "AI Readiness:** 6.5 / 8 (Solid)" in latest_section
    assert "Top action:** Add cyclop rule (threshold 15) to .golangci.yml" in latest_section

    # The 2026-05-01 (older) entry's placeholders are PRESERVED as historical evidence
    older_section = content.split("## 2026-05-22")[0]
    assert "AI Readiness:** 0.0 / 8 ((LLM fills in))" in older_section
    assert "Deterministic ranker not yet wired" in older_section


def _base_input() -> dict:
    return {
        "score": 6.0,
        "maturity_label": "Solid",
        "top_action": "Add cyclop rule",
        "hotspot_actions": {},
    }


def _good_action(rank: int = 1) -> dict:
    return {
        "rank": rank,
        "action": "Add cyclop rule (threshold 15) to .golangci.yml",
        "layer": 3,
        "effort": "small",
        "files": [".golangci.yml"],
        "first_step": "Add cyclop under linters",
        "done_when": "golangci-lint run passes with the rule active",
        "scope_fence": "Only .golangci.yml; no source edits",
    }


def _distinct_action(rank: int, *, finding: str | None = None) -> dict:
    """A good action with a rank-unique directive (the carry-forward identity)."""
    a = {**_good_action(rank=rank), "action": f"Action number {rank}"}
    if finding is not None:
        a["finding"] = finding
    return a


def test_finalize_writes_actions_contract(tmp_assess_dir: Path) -> None:
    """An `actions` array in the input becomes the durable .assess/actions.json,
    sorted by rank, with the executor-critical fields intact (v2 schema)."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, run_id="run-abc")
    finalize_input = {
        **_base_input(),
        "actions": [_distinct_action(rank=2), _distinct_action(rank=1)],
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)

    contract = json.loads(
        (tmp_assess_dir / "actions.json").read_text(encoding="utf-8")
    )
    assert contract["schema"] == 2
    assert contract["run_id"] == "run-abc"
    assert [a["rank"] for a in contract["actions"]] == [1, 2]
    for a in contract["actions"]:
        assert a["done_when"]
        assert a["scope_fence"]
        # v2 lifecycle fields present and initialised for a first run.
        assert a["status"] == "pending"
        assert a["claimed_by"] is None
        assert a["completed_sha"] is None
        assert a["mode"] in {
            "characterize_first", "verify_then_retire", "refactor_safe",
        }


def test_finalize_derives_mode_from_finding(tmp_assess_dir: Path) -> None:
    """`mode` is derived deterministically from each action's finding type; an
    action with no finding falls back to the conservative characterize_first."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    finalize_input = {
        **_base_input(),
        "actions": [
            _distinct_action(rank=1, finding="lying_map"),
            _distinct_action(rank=2, finding="refactor_boundary"),
            _distinct_action(rank=3),  # no finding -> default
        ],
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)

    by_rank = {
        a["rank"]: a
        for a in json.loads(
            (tmp_assess_dir / "actions.json").read_text(encoding="utf-8")
        )["actions"]
    }
    assert by_rank[1]["mode"] == "verify_then_retire"
    assert by_rank[2]["mode"] == "refactor_safe"
    assert by_rank[3]["mode"] == "characterize_first"


def test_finalize_carries_status_across_runs(tmp_assess_dir: Path) -> None:
    """A done action stays done with its completed_sha on re-run - status,
    claimed_by, and completed_sha are carried forward by the action directive."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    # Run 1: writes a pending contract.
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps({**_base_input(), "actions": [_distinct_action(rank=1)]}),
        encoding="utf-8",
    )
    finalize_run(assess_dir=tmp_assess_dir)

    # An executor marks the action done out of band.
    contract_path = tmp_assess_dir / "actions.json"
    contract = json.loads(contract_path.read_text(encoding="utf-8"))
    contract["actions"][0].update(
        status="done", claimed_by="agent-7", completed_sha="deadbeef",
    )
    contract_path.write_text(json.dumps(contract), encoding="utf-8")

    # Run 2: the same action re-appears (rank changed) - it must stay done.
    # Same directive text (the carry-forward key), new rank.
    _seed_log_md(tmp_assess_dir)
    reranked = {**_distinct_action(rank=1), "rank": 3}
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps({**_base_input(), "actions": [reranked]}),
        encoding="utf-8",
    )
    finalize_run(assess_dir=tmp_assess_dir)

    after = json.loads(contract_path.read_text(encoding="utf-8"))["actions"][0]
    assert after["status"] == "done"
    assert after["claimed_by"] == "agent-7"
    assert after["completed_sha"] == "deadbeef"
    assert after["rank"] == 3  # rank is recomputed, not carried


def test_finalize_reads_v1_actions_for_carry_forward(tmp_assess_dir: Path) -> None:
    """A pre-existing v1 actions.json (no lifecycle fields) is read without
    error; the re-run upgrades it to v2 with every action initialised pending."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    # A v1-shaped contract on disk from before this schema existed.
    (tmp_assess_dir / "actions.json").write_text(
        json.dumps({
            "schema": 1,
            "actions": [{
                "rank": 1,
                "action": "Action number 1",
                "done_when": "x",
                "scope_fence": "y",
            }],
        }),
        encoding="utf-8",
    )
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps({**_base_input(), "actions": [_distinct_action(rank=1)]}),
        encoding="utf-8",
    )

    finalize_run(assess_dir=tmp_assess_dir)

    contract = json.loads(
        (tmp_assess_dir / "actions.json").read_text(encoding="utf-8")
    )
    assert contract["schema"] == 2
    entry = contract["actions"][0]
    assert entry["status"] == "pending"
    assert entry["claimed_by"] is None
    assert entry["completed_sha"] is None


def test_finalize_without_actions_writes_no_contract(tmp_assess_dir: Path) -> None:
    """Backwards compatibility: an input with no `actions` key (the pre-1.41
    shape) finalizes the wiki exactly as before and writes no actions.json."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(_base_input()), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)

    assert not (tmp_assess_dir / "actions.json").exists()
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "AI Readiness:** 6.0 / 8 (Solid)" in content


def test_finalize_drops_malformed_action_entries(tmp_assess_dir: Path) -> None:
    """An entry missing done_when/scope_fence is dropped (a malformed contract
    must not reach an executor as if complete); valid siblings still land."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    incomplete = {"rank": 2, "action": "vague intention"}  # no done_when/fence
    finalize_input = {
        **_base_input(),
        "actions": [_good_action(rank=1), incomplete],
    }
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)

    contract = json.loads(
        (tmp_assess_dir / "actions.json").read_text(encoding="utf-8")
    )
    assert len(contract["actions"]) == 1
    assert contract["actions"][0]["rank"] == 1


def test_finalize_all_actions_malformed_writes_no_contract(tmp_assess_dir: Path) -> None:
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    finalize_input = {**_base_input(), "actions": [{"rank": 1}]}
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(finalize_input), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)

    assert not (tmp_assess_dir / "actions.json").exists()


def test_finalize_leaves_deterministic_badge_untouched(tmp_assess_dir: Path) -> None:
    """Finalize does NOT overwrite the deterministic badge with the LLM score.

    The shipped badge stays the findings-count form assess_core wrote; the
    LLM-derived score lands in the report/log instead, so the badge never claims
    a grade a deterministic run cannot reproduce.
    """
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    deterministic_badge = (
        '{"schemaVersion": 1, "label": "AI-readiness", '
        '"message": "9 findings · 9 stale markers", "color": "orange", '
        '"link": "./assess-report.md"}'
    )
    (tmp_assess_dir / "badge.json").write_text(deterministic_badge, encoding="utf-8")
    (tmp_assess_dir / "finalize-input.json").write_text(
        json.dumps(_base_input()), encoding="utf-8"
    )

    finalize_run(assess_dir=tmp_assess_dir)

    badge = json.loads((tmp_assess_dir / "badge.json").read_text(encoding="utf-8"))
    # Badge unchanged: still the deterministic findings form, no LLM score.
    assert badge["message"] == "9 findings · 9 stale markers"
    assert "6.0/8" not in badge["message"]
    assert badge["link"] == "./assess-report.md"
    # The LLM score still lands where it belongs: the report/log entry.
    log = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "**AI Readiness:** 6.0 / 8 (Solid)" in log


# --- Task 1: finalize reconciles run-context invariants (fail-closed) --------


def _write_input(assess_dir: Path, data: dict) -> None:
    (assess_dir / "finalize-input.json").write_text(json.dumps(data), encoding="utf-8")


def test_finalize_missing_run_context_refuses(tmp_assess_dir: Path) -> None:
    """A present input but no run-context.json is a hard, named failure - there
    is nothing to reconcile against, so finalize refuses and writes nothing."""
    _seed_log_md(tmp_assess_dir)  # note: no _seed_run_context
    _write_input(tmp_assess_dir, _base_input())

    with pytest.raises(FinalizeValidationError, match="run-context.json missing"):
        finalize_run(assess_dir=tmp_assess_dir)

    # Nothing written: the log placeholder survives untouched.
    content = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "((LLM fills in))" in content
    assert not (tmp_assess_dir / "actions.json").exists()


def test_finalize_denominator_mismatch_refuses(tmp_assess_dir: Path) -> None:
    """The input denominator must match run-context archetype.denominator."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, denominator=3)  # KB
    _write_input(tmp_assess_dir, {**_base_input(), "denominator": 8})

    with pytest.raises(FinalizeValidationError, match="denominator mismatch"):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_score_exceeds_denominator_refuses(tmp_assess_dir: Path) -> None:
    """A score above its denominator is impossible - refuse."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(
        tmp_assess_dir,
        {**_base_input(), "score": 9.0, "maturity_label": "AI-Native"},
    )

    with pytest.raises(FinalizeValidationError, match="exceeds denominator"):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_maturity_inconsistent_with_score_refuses(tmp_assess_dir: Path) -> None:
    """A label that overstates the score band (2.0/8 called 'AI-Native') is a
    lying self-description - refuse, naming the expected tier."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(
        tmp_assess_dir,
        {**_base_input(), "score": 2.0, "maturity_label": "AI-Native"},
    )

    with pytest.raises(FinalizeValidationError, match="claims tier 'AI-Native'"):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_valid_maturity_bands_pass(tmp_assess_dir: Path) -> None:
    """The documented ladder is accepted verbatim: each score earns its label."""
    for score, label in [
        (7.0, "AI-Native"),   # 0.875
        (6.0, "Solid"),       # 0.75
        (3.0, "Basic"),       # 0.375
        (1.0, "Not Ready"),   # 0.125
    ]:
        _seed_log_md(tmp_assess_dir)
        _seed_run_context(tmp_assess_dir)
        _write_input(
            tmp_assess_dir,
            {**_base_input(), "score": score, "maturity_label": label},
        )
        finalize_run(assess_dir=tmp_assess_dir)  # must not raise


def test_finalize_fabricated_hotspot_path_refuses(tmp_assess_dir: Path) -> None:
    """A hotspot_actions key absent from run-context top_hotspots is fabricated;
    the error names the offending path."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, hotspots=("src/foo.go",))
    _write_input(
        tmp_assess_dir,
        {**_base_input(), "hotspot_actions": {"src/invented.go": ["do a thing"]}},
    )

    with pytest.raises(FinalizeValidationError, match=r"src/invented\.go"):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_writes_nothing_on_violation(tmp_assess_dir: Path) -> None:
    """A violation short-circuits before any write: no badge, no actions.json,
    log placeholders intact, and the input file is NOT consumed (so a fixed
    rerun can still find it)."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    bad = {**_base_input(), "score": 2.0, "maturity_label": "AI-Native",
           "actions": [_good_action(rank=1)]}
    _write_input(tmp_assess_dir, bad)

    with pytest.raises(FinalizeValidationError):
        finalize_run(assess_dir=tmp_assess_dir)

    assert "((LLM fills in))" in (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert not (tmp_assess_dir / "actions.json").exists()
    assert not (tmp_assess_dir / "badge.json").exists()
    assert (tmp_assess_dir / "finalize-input.json").exists()  # not consumed


# --- Task 2: run_id torn-write detection -------------------------------------


def test_finalize_run_id_mismatch_refuses(tmp_assess_dir: Path) -> None:
    """finalize-input and run-context from different runs (mismatched run_id) is
    a torn write - refuse."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, run_id="20260707120000-aaaaaaaa")
    _write_input(tmp_assess_dir, {**_base_input(), "run_id": "20260707130000-bbbbbbbb"})

    with pytest.raises(FinalizeValidationError, match="torn write"):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_run_id_match_finalizes_log(tmp_assess_dir: Path) -> None:
    """A matching run_id passes the torn-write check and finalize completes.

    (The badge is deterministic and written by assess_core, so finalize no
    longer stamps it - the run_id proves the input was authored against this
    run, which is what unblocks the write-back.)
    """
    _seed_log_md(tmp_assess_dir)
    run_id = "20260707120000-abcdef01"
    _seed_run_context(tmp_assess_dir, run_id=run_id)
    _write_input(tmp_assess_dir, {**_base_input(), "run_id": run_id})

    finalize_run(assess_dir=tmp_assess_dir)

    log = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "**AI Readiness:** 6.0 / 8 (Solid)" in log


def test_finalize_legacy_input_without_run_id_still_works(tmp_assess_dir: Path) -> None:
    """A legacy input carrying no run_id finalises even when run-context has one
    (backward compat: the torn-write check needs both stamps to fire)."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, run_id="20260707120000-abcdef01")
    _write_input(tmp_assess_dir, _base_input())  # no run_id

    finalize_run(assess_dir=tmp_assess_dir)  # must not raise
    assert "AI Readiness:** 6.0 / 8 (Solid)" in (
        tmp_assess_dir / "log.md"
    ).read_text(encoding="utf-8")


# --- Task 8: Layer 6 capped at Partial when mutation never ran ---------------


def test_finalize_layer6_present_without_mutation_refuses(tmp_assess_dir: Path) -> None:
    """Mutation never ran + LLM scores Layer 6 Present (1.0) -> finalize rejects,
    naming the required annotation."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, mutation_run=False)
    _write_input(tmp_assess_dir, {**_base_input(), "layer_scores": {"6": 1.0}})

    with pytest.raises(
        FinalizeValidationError,
        match="truth-pressure unproven",
    ):
        finalize_run(assess_dir=tmp_assess_dir)


def test_finalize_layer6_present_with_mutation_allowed(tmp_assess_dir: Path) -> None:
    """When mutation actually ran, a Present Layer 6 is allowed."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, mutation_run=True)
    _write_input(tmp_assess_dir, {**_base_input(), "layer_scores": {"6": 1.0}})

    finalize_run(assess_dir=tmp_assess_dir)  # must not raise


def test_finalize_layer6_partial_without_mutation_allowed(tmp_assess_dir: Path) -> None:
    """Partial (0.5) is the ceiling when mutation didn't run - allowed."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir, mutation_run=False)
    _write_input(tmp_assess_dir, {**_base_input(), "layer_scores": {"6": 0.5}})

    finalize_run(assess_dir=tmp_assess_dir)  # must not raise


# --- #362: finalize re-checks the evidence a layer verdict cites -------------


def _seed_evidence_repo(assess_dir: Path) -> Path:
    """The repository root around ``assess_dir``: a doc, and a script a CI
    workflow calls. Returns the root (the parent of ``.assess/``)."""
    root = assess_dir.parent
    (root / "docs").mkdir(exist_ok=True)
    (root / "docs" / "guide.md").write_text("# guide\n", encoding="utf-8")
    (root / "scripts").mkdir(exist_ok=True)
    (root / "scripts" / "check-x.sh").write_text("echo ok\n", encoding="utf-8")
    wf = root / ".github" / "workflows"
    wf.mkdir(parents=True, exist_ok=True)
    (wf / "ci.yml").write_text(
        "on: push\njobs:\n  lint:\n    runs-on: ubuntu-latest\n"
        "    steps:\n      - run: bash scripts/check-x.sh\n",
        encoding="utf-8",
    )
    return root


def _evidence_input(evidence: list | None) -> dict:
    data = {**_base_input(), "layer_scores": {"0": 1.0, "7": 1.0}}
    if evidence is not None:
        data["evidence"] = evidence
    return data


def _assert_nothing_written(assess_dir: Path) -> None:
    assert "((LLM fills in))" in (assess_dir / "log.md").read_text(encoding="utf-8")
    assert (assess_dir / "finalize-input.json").exists()  # not consumed


def test_finalize_evidence_path_absent_for_existing_file_refuses(tmp_assess_dir: Path) -> None:
    """A layer resting only on "docs/guide.md is absent", when it exists, is
    refused before any write, and the message names the entry."""
    _seed_evidence_repo(tmp_assess_dir)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, _evidence_input(
        [{"layer": 0, "kind": "path_absent", "path": "docs/guide.md"}]
    ))

    with pytest.raises(FinalizeValidationError, match=r"path_absent docs/guide\.md") as exc:
        finalize_run(assess_dir=tmp_assess_dir)
    assert "layer 0" in str(exc.value)
    _assert_nothing_written(tmp_assess_dir)


def test_finalize_evidence_not_referenced_in_called_script_refuses(tmp_assess_dir: Path) -> None:
    """"No workflow calls scripts/check-x.sh", when ci.yml calls it, is refused;
    the message names the kind, the searched path and the needle."""
    _seed_evidence_repo(tmp_assess_dir)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, _evidence_input([{
        "layer": 7, "kind": "not_referenced_in",
        "needle": "scripts/check-x.sh", "path": ".github/workflows",
    }]))

    with pytest.raises(FinalizeValidationError) as exc:
        finalize_run(assess_dir=tmp_assess_dir)
    msg = str(exc.value)
    assert "not_referenced_in" in msg
    assert ".github/workflows" in msg
    assert "scripts/check-x.sh" in msg
    _assert_nothing_written(tmp_assess_dir)


def test_finalize_evidence_all_true_finalizes(tmp_assess_dir: Path) -> None:
    """Every entry verifies: finalize writes exactly as it does without evidence."""
    _seed_evidence_repo(tmp_assess_dir)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, _evidence_input([
        {"layer": 7, "kind": "referenced_in",
         "needle": "scripts/check-x.sh", "path": ".github/workflows"},
        {"layer": 0, "kind": "path_absent", "path": "docs/missing.md"},
        {"layer": 0, "kind": "file_contains", "path": "docs/guide.md", "needle": "guide"},
    ]))

    finalize_run(assess_dir=tmp_assess_dir)

    log = (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    assert "**AI Readiness:** 6.0 / 8 (Solid)" in log
    assert "((LLM fills in))" not in log
    assert not (tmp_assess_dir / "finalize-input.json").exists()


def test_finalize_without_evidence_key_finalizes(tmp_assess_dir: Path) -> None:
    """An input with no evidence key (every input before #362) is accepted,
    as a legacy input without layer_scores is."""
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, _evidence_input(None))

    finalize_run(assess_dir=tmp_assess_dir)

    assert "**AI Readiness:** 6.0 / 8 (Solid)" in (tmp_assess_dir / "log.md").read_text(
        encoding="utf-8"
    )


def test_finalize_evidence_mixed_layer_finalizes_and_warns(
    tmp_assess_dir: Path, capsys: pytest.CaptureFixture[str]
) -> None:
    """A layer with at least one verified entry keeps its verdict: finalize
    writes, and names each rejected entry on stderr as a warning."""
    _seed_evidence_repo(tmp_assess_dir)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, _evidence_input([
        {"layer": 0, "kind": "path_exists", "path": "docs/guide.md"},
        {"layer": 0, "kind": "path_exists", "path": "docs/invented.md"},
    ]))

    finalize_run(assess_dir=tmp_assess_dir)

    assert "((LLM fills in))" not in (tmp_assess_dir / "log.md").read_text(encoding="utf-8")
    err = capsys.readouterr().err
    assert "warning" in err
    assert "path_exists docs/invented.md" in err
    assert "docs/guide.md" not in err


def test_finalize_evidence_one_layer_all_rejected_refuses_despite_other_layers(
    tmp_assess_dir: Path,
) -> None:
    """The rule is per layer: layer 7 verifying does not carry a layer 0 whose
    only entry is false."""
    _seed_evidence_repo(tmp_assess_dir)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, _evidence_input([
        {"layer": 7, "kind": "referenced_in",
         "needle": "scripts/check-x.sh", "path": ".github/workflows"},
        {"layer": 0, "kind": "path_exists", "path": "docs/invented.md"},
    ]))

    with pytest.raises(FinalizeValidationError, match=r"layer 0.*path_exists docs/invented\.md"):
        finalize_run(assess_dir=tmp_assess_dir)
    _assert_nothing_written(tmp_assess_dir)


@pytest.mark.parametrize(
    ("evidence", "match"),
    [
        ({"layer": 0}, "must be a list"),
        (["docs/guide.md"], "not an object"),
        ([{"kind": "path_exists", "path": "docs/guide.md"}], "layer"),
        ([{"layer": 9, "kind": "path_exists", "path": "docs/guide.md"}], "layer"),
        ([{"layer": True, "kind": "path_exists", "path": "docs/guide.md"}], "layer"),
    ],
)
def test_finalize_malformed_evidence_refuses(
    tmp_assess_dir: Path, evidence: object, match: str
) -> None:
    """A malformed evidence value cannot be attributed to a layer, so it fails
    closed rather than being skipped."""
    _seed_evidence_repo(tmp_assess_dir)
    _seed_log_md(tmp_assess_dir)
    _seed_run_context(tmp_assess_dir)
    _write_input(tmp_assess_dir, {**_base_input(), "evidence": evidence})

    with pytest.raises(FinalizeValidationError, match=match):
        finalize_run(assess_dir=tmp_assess_dir)
    _assert_nothing_written(tmp_assess_dir)


def test_finalize_evidence_refusal_through_core_and_cli(tmp_path: Path) -> None:
    """End to end: the log comes from the real core, and the CLI prints
    "finalize refused" naming the entry on stderr, exits 1, and writes nothing."""
    import subprocess
    import sys

    from assess_core import build_run_context

    root = tmp_path / "repo"
    (root / ".assess").mkdir(parents=True)
    _seed_evidence_repo(root / ".assess")
    ctx = build_run_context(repo_root=root, run_date="2026-09-18", non_interactive=True)
    den = int(ctx["archetype"].get("denominator") or 8)
    cache = root / ".assess" / ".cache"
    cache.mkdir(exist_ok=True)
    (cache / "finalize-input.json").write_text(json.dumps({
        "run_id": ctx["run_id"], "score": den * 0.75, "maturity_label": "Solid",
        "denominator": den, "top_action": "Add a gate",
        "layer_scores": {"0": 1.0, "7": 1.0},
        "evidence": [{"layer": 0, "kind": "path_absent", "path": "docs/guide.md"}],
    }), encoding="utf-8")

    script = Path(__file__).resolve().parents[1] / "scripts" / "assess_finalize.py"
    proc = subprocess.run(
        [sys.executable, str(script), str(root)], capture_output=True, text=True
    )

    assert proc.returncode == 1
    assert "finalize refused" in proc.stderr
    assert "path_absent docs/guide.md" in proc.stderr
    assert "((LLM fills in))" in (root / ".assess" / "log.md").read_text(encoding="utf-8")
    assert (cache / "finalize-input.json").exists()

"""Tests for the CI regression gate (assess_gate.py) and its config loader.

The gate is the enforcement half of the frozen harness: same run-context +
config in, same pass/fail out, no LLM. These tests pin the warn-only defaults,
the fail_on / warn_on precedence, the threshold checks, and the exit codes.
"""
from __future__ import annotations

import json
from pathlib import Path


from assess_gate import (
    check_complexity_threshold,
    check_containment_threshold,
    check_diff_regression,
    check_finding_regressions,
    evaluate,
    format_verdict,
    main,
)
from lib.assess_config import (
    GATE_CONCERN_FINDINGS,
    load_gate_config,
    load_gate_config_file,
)
from lib.keyhole_signals import FINDING_ORDER


def _ctx(
    findings: list[dict] | None = None,
    ccn_p95: float = 50.0,
    safe_zones: int = 1,
    total_concerns: int = 5,
) -> dict:
    """A minimal run-context with the keys the gate reads."""
    return {
        "derived_findings": findings if findings is not None else [],
        "stats_summary": {"ccn": {"p95": ccn_p95}},
        "keyhole_summary": {"safe_zones": safe_zones, "total_concerns": total_concerns},
    }


def _diff_ctx(regressed: list[dict] | None = None, prior: bool = True, reliable: bool = True) -> dict:
    """A run-context carrying the cross-run diff the regression check reads."""
    ctx = _ctx([])
    ctx["prior_stats_exists"] = prior
    ctx["diff_reliable"] = reliable
    ctx["diff_detail"] = {"regressed": regressed or []}
    return ctx


def _write_config(tmp_path: Path, body: str) -> Path:
    (tmp_path / ".assess").mkdir(parents=True, exist_ok=True)
    (tmp_path / ".assess" / "config.toml").write_text(body, encoding="utf-8")
    return tmp_path


# --- config loader --------------------------------------------------------


def test_gate_concerns_match_keyhole_signals():
    """The default warn set must stay in sync with the canonical finding order."""
    expected = [f for f in FINDING_ORDER if f != "refactor_boundary"]
    assert GATE_CONCERN_FINDINGS == expected


def test_load_gate_config_defaults_warn_only(tmp_path):
    """No config -> enabled, nothing fails, every concern warns, no thresholds."""
    gate = load_gate_config(tmp_path)
    assert gate["enabled"] is True
    assert gate["fail_on"] == []
    assert gate["warn_on"] == GATE_CONCERN_FINDINGS
    assert gate["ccn_p95_max"] is None
    assert gate["containment_min"] is None


def test_load_gate_config_reads_section(tmp_path):
    _write_config(
        tmp_path,
        '[gate]\n'
        'enabled = true\n'
        'fail_on = ["lying_map", "hidden_coupling"]\n'
        'ccn_p95_max = 80\n'
        'containment_min = 0.5\n',
    )
    gate = load_gate_config(tmp_path)
    assert gate["fail_on"] == ["lying_map", "hidden_coupling"]
    assert gate["ccn_p95_max"] == 80.0
    assert gate["containment_min"] == 0.5


def test_load_gate_config_explicit_empty_warn_on(tmp_path):
    """An explicit empty list silences warnings (distinct from missing key)."""
    _write_config(tmp_path, "[gate]\nwarn_on = []\n")
    assert load_gate_config(tmp_path)["warn_on"] == []


def test_load_gate_config_rejects_bad_threshold(tmp_path):
    """Non-positive / non-numeric / boolean thresholds degrade to None."""
    _write_config(tmp_path, "[gate]\nccn_p95_max = 0\ncontainment_min = true\n")
    gate = load_gate_config(tmp_path)
    assert gate["ccn_p95_max"] is None
    assert gate["containment_min"] is None


def test_load_gate_config_non_dict_section(tmp_path):
    """A malformed [gate] (scalar instead of table) falls back to defaults."""
    _write_config(tmp_path, 'gate = "nope"\n')
    gate = load_gate_config(tmp_path)
    assert gate["enabled"] is True
    assert gate["fail_on"] == []


# --- finding regressions --------------------------------------------------


def test_finding_fires_only_with_paths():
    ctx = _ctx([
        {"name": "lying_map", "paths": ["docs/old.md"]},
        {"name": "hidden_coupling", "paths": []},
    ])
    gate = {"fail_on": ["lying_map", "hidden_coupling"], "warn_on": []}
    failures, warnings = check_finding_regressions(ctx, gate)
    assert [f["finding"] for f in failures] == ["lying_map"]
    assert failures[0]["count"] == 1
    assert warnings == []


def test_fail_on_takes_precedence_over_warn_on():
    ctx = _ctx([{"name": "lying_map", "paths": ["a", "b"]}])
    gate = {"fail_on": ["lying_map"], "warn_on": ["lying_map"]}
    failures, warnings = check_finding_regressions(ctx, gate)
    assert len(failures) == 1
    assert warnings == []  # not double-counted


def test_warn_on_reports_without_failing():
    ctx = _ctx([{"name": "candidate_dead_weight", "paths": ["x.py"]}])
    gate = {"fail_on": [], "warn_on": ["candidate_dead_weight"]}
    failures, warnings = check_finding_regressions(ctx, gate)
    assert failures == []
    assert [w["finding"] for w in warnings] == ["candidate_dead_weight"]


def test_paths_sample_capped_at_five():
    ctx = _ctx([{"name": "hidden_coupling", "paths": [str(i) for i in range(20)]}])
    gate = {"fail_on": ["hidden_coupling"], "warn_on": []}
    failures, _ = check_finding_regressions(ctx, gate)
    assert failures[0]["count"] == 20
    assert len(failures[0]["paths"]) == 5


# --- thresholds -----------------------------------------------------------


def test_complexity_threshold_breach():
    breaches = check_complexity_threshold(_ctx(ccn_p95=120.0), {"ccn_p95_max": 100.0})
    assert breaches[0]["metric"] == "ccn_p95"
    assert breaches[0]["value"] == 120.0


def test_complexity_threshold_within_budget():
    assert check_complexity_threshold(_ctx(ccn_p95=90.0), {"ccn_p95_max": 100.0}) == []


def test_complexity_threshold_unset():
    assert check_complexity_threshold(_ctx(ccn_p95=999.0), {"ccn_p95_max": None}) == []


def test_containment_threshold_breach():
    # 1 safe / (1 + 9) = 0.1, below the 0.5 floor.
    breaches = check_containment_threshold(
        _ctx(safe_zones=1, total_concerns=9), {"containment_min": 0.5}
    )
    assert breaches[0]["metric"] == "containment"
    assert breaches[0]["value"] == 0.1


def test_containment_threshold_met():
    assert check_containment_threshold(
        _ctx(safe_zones=9, total_concerns=1), {"containment_min": 0.5}
    ) == []


def test_containment_no_units_scored():
    """Nothing flagged either way -> no ratio -> no breach."""
    assert check_containment_threshold(
        _ctx(safe_zones=0, total_concerns=0), {"containment_min": 0.5}
    ) == []


# --- cross-run regression -------------------------------------------------


def test_regression_not_opted_in():
    ctx = _diff_ctx(regressed=[{"path": "a.py"}])
    assert check_diff_regression(ctx, {"fail_on_regression": False}) == []


def test_regression_fires_when_opted_in():
    ctx = _diff_ctx(regressed=[{"path": "a.py"}, {"path": "b.py"}])
    breaches = check_diff_regression(ctx, {"fail_on_regression": True})
    assert breaches[0]["metric"] == "regressed_hotspots"
    assert breaches[0]["count"] == 2
    assert breaches[0]["paths"] == ["a.py", "b.py"]


def test_regression_skipped_on_first_run():
    """No prior snapshot -> a freshly-cloned repo can't trip the regression gate."""
    ctx = _diff_ctx(regressed=[{"path": "a.py"}], prior=False)
    assert check_diff_regression(ctx, {"fail_on_regression": True}) == []


def test_regression_skipped_when_diff_unreliable():
    ctx = _diff_ctx(regressed=[{"path": "a.py"}], reliable=False)
    assert check_diff_regression(ctx, {"fail_on_regression": True}) == []


def test_regression_clean_diff_no_breach():
    ctx = _diff_ctx(regressed=[])
    assert check_diff_regression(ctx, {"fail_on_regression": True}) == []


def test_load_gate_config_fail_on_regression_default_false(tmp_path):
    assert load_gate_config(tmp_path)["fail_on_regression"] is False


def test_load_gate_config_reads_fail_on_regression(tmp_path):
    _write_config(tmp_path, "[gate]\nfail_on_regression = true\n")
    assert load_gate_config(tmp_path)["fail_on_regression"] is True


def test_regression_breach_renders_in_verdict():
    ctx = _diff_ctx(regressed=[{"path": "hot.py"}])
    verdict = evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": [], "fail_on_regression": True})
    assert verdict["failed"] is True
    assert "FAIL regression" in format_verdict(verdict)


# --- explicit --config file -----------------------------------------------


def test_load_gate_config_file_reads_explicit_path(tmp_path):
    cfg = tmp_path / "custom.toml"
    cfg.write_text('[gate]\nfail_on = ["lying_map"]\n', encoding="utf-8")
    gate = load_gate_config_file(cfg)
    assert gate["fail_on"] == ["lying_map"]


def test_load_gate_config_file_missing_uses_defaults(tmp_path):
    gate = load_gate_config_file(tmp_path / "nope.toml")
    assert gate["fail_on"] == []
    assert gate["enabled"] is True


# --- evaluate + verdict ---------------------------------------------------


def test_evaluate_clean_passes():
    gate = load_gate_config(Path("/nonexistent"))  # warn-only defaults
    verdict = evaluate(_ctx([]), gate)
    assert verdict["failed"] is False


def test_evaluate_fails_on_fail_on_finding():
    ctx = _ctx([{"name": "lying_map", "paths": ["doc.md"]}])
    verdict = evaluate(ctx, {"enabled": True, "fail_on": ["lying_map"], "warn_on": []})
    assert verdict["failed"] is True
    assert verdict["failures"][0]["finding"] == "lying_map"


def test_disabled_gate_never_fails_but_reports():
    ctx = _ctx([{"name": "lying_map", "paths": ["doc.md"]}])
    verdict = evaluate(ctx, {"enabled": False, "fail_on": ["lying_map"], "warn_on": []})
    assert verdict["failed"] is False
    assert verdict["failures"]  # still collected for the log
    assert "disabled" in format_verdict(verdict)


def test_format_verdict_clean():
    verdict = evaluate(_ctx([]), {"enabled": True, "fail_on": [], "warn_on": []})
    out = format_verdict(verdict)
    assert "RESULT: PASS" in out
    assert "clean snapshot" in out


# --- config-exclusion disclosure ------------------------------------------


def test_verdict_discloses_config_suppressed_findings():
    ctx = _ctx([])
    ctx["excluded_by_config"] = {
        "dirs": ["vendor"],
        "patterns": ["*.gen.py"],
        "affected_finding_paths": ["vendor/x.py", "a.gen.py"],
        "count": 2,
    }
    out = format_verdict(evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": []}))
    assert "2 findings suppressed by config excludes" in out
    assert "dirs: vendor" in out
    assert "patterns: *.gen.py" in out


def test_verdict_singular_suppression_noun():
    ctx = _ctx([])
    ctx["excluded_by_config"] = {
        "dirs": ["vendor"], "patterns": [],
        "affected_finding_paths": ["vendor/x.py"], "count": 1,
    }
    out = format_verdict(evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": []}))
    assert "1 finding suppressed by config excludes" in out
    assert "patterns: none" in out


def test_verdict_no_disclosure_when_no_excludes():
    ctx = _ctx([])
    ctx["excluded_by_config"] = {
        "dirs": [], "patterns": [], "affected_finding_paths": [], "count": 0,
    }
    out = format_verdict(evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": []}))
    assert "suppressed by config excludes" not in out


def test_verdict_no_disclosure_when_block_absent():
    out = format_verdict(evaluate(_ctx([]), {"enabled": True, "fail_on": [], "warn_on": []}))
    assert "suppressed by config excludes" not in out


# --- generated-file disclosure --------------------------------------------


def test_verdict_names_each_generated_header_reason():
    ctx = _ctx([])
    ctx["excluded_generated"] = [
        {"path": "db/schema.sql", "reason": "generated-header"},
        {"path": "db/other.sql", "reason": "generated-header"},
        {"path": "assets/font.ts", "reason": "long-lines"},
    ]
    out = format_verdict(evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": []}))
    line = next(ln for ln in out.splitlines() if "generated-header" in ln)
    assert "3 files excluded from scoring as generated" in line
    assert "long-lines" in line
    assert line.count("generated-header") == 1
    assert "    db/schema.sql (generated-header)" in out
    assert "    assets/font.ts (long-lines)" in out
    assert "RESULT: PASS" in out


def test_verdict_caps_generated_header_path_lines():
    ctx = _ctx([])
    ctx["excluded_generated"] = [
        {"path": f"gen/f{i:02}.sql", "reason": "generated-header"} for i in range(13)
    ]
    out = format_verdict(evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": []}))
    assert "gen/f09.sql (generated-header)" in out
    assert "gen/f10.sql" not in out
    assert "+3 more" in out


def test_verdict_generated_header_disclosure_silent_when_empty():
    for ctx in (_ctx([]), {**_ctx([]), "excluded_generated": []}):
        out = format_verdict(evaluate(ctx, {"enabled": True, "fail_on": [], "warn_on": []}))
        assert "excluded from scoring as generated" not in out


# --- CLI ------------------------------------------------------------------


def _write_ctx(tmp_path: Path, ctx: dict) -> Path:
    (tmp_path / ".assess").mkdir(parents=True, exist_ok=True)
    (tmp_path / ".assess" / "run-context.json").write_text(json.dumps(ctx))
    return tmp_path


def test_main_passes_clean(tmp_path, capsys):
    _write_ctx(tmp_path, _ctx([]))
    assert main([str(tmp_path)]) == 0
    assert "RESULT: PASS" in capsys.readouterr().out


def test_main_fails_when_configured(tmp_path, capsys):
    _write_ctx(tmp_path, _ctx([{"name": "lying_map", "paths": ["doc.md"]}]))
    _write_config(tmp_path, '[gate]\nfail_on = ["lying_map"]\n')
    assert main([str(tmp_path)]) == 1
    assert "RESULT: FAIL" in capsys.readouterr().out


def test_main_warn_only_default_passes_with_findings(tmp_path):
    """Findings present but no fail_on config -> warn-only -> exit 0."""
    _write_ctx(tmp_path, _ctx([{"name": "lying_map", "paths": ["doc.md"]}]))
    assert main([str(tmp_path)]) == 0


def test_main_accepts_config_flag_without_consuming_repo_root(tmp_path):
    _write_ctx(tmp_path, _ctx([]))
    cfg = tmp_path / ".assess" / "config.toml"
    assert main([str(tmp_path), "--config", str(cfg)]) == 0


def test_main_honors_explicit_config_path(tmp_path):
    """--config pointing at a relocated file drives the gate, not .assess/."""
    _write_ctx(tmp_path, _ctx([{"name": "lying_map", "paths": ["doc.md"]}]))
    cfg = tmp_path / "elsewhere.toml"
    cfg.write_text('[gate]\nfail_on = ["lying_map"]\n', encoding="utf-8")
    # No .assess/config.toml exists, so this fails only if --config is honored.
    assert main([str(tmp_path), "--config", str(cfg)]) == 1


def test_main_missing_context_skips_not_fails(tmp_path, capsys):
    """A missing run-context is an infrastructure failure, not a finding: the
    gate skips with a clear notice and exits 0 so it never red-checks an
    unrelated PR (it runs again once the core produces a clean run-context)."""
    assert main([str(tmp_path)]) == 0
    err = capsys.readouterr().err
    assert "gate skipped" in err
    assert "infrastructure failure" in err
    assert "not a finding" in err
    assert "next push" in err


def test_main_corrupt_context_skips_not_fails(tmp_path, capsys):
    """A corrupt (unparseable) run-context is also infra, not a finding: skip
    with a notice and exit 0 rather than fail the PR."""
    (tmp_path / ".assess").mkdir(parents=True)
    (tmp_path / ".assess" / "run-context.json").write_text(
        "{ not valid json", encoding="utf-8"
    )
    assert main([str(tmp_path)]) == 0
    err = capsys.readouterr().err
    assert "gate skipped" in err
    assert "infrastructure failure" in err


def test_main_no_args_is_usage_error(capsys):
    assert main([]) == 2
    assert "Usage" in capsys.readouterr().err

"""Tests for the deterministic report renderer (assess_report.py).

The renderer is the frozen harness: same context in, same Markdown out, no LLM.
These tests pin its template substitution, the section renderers (hotspots,
keyhole summary, findings, diff), the conditional fallbacks, and the honest
boundary - it must NOT reproduce the LLM-only 0-8 score or Top 3 Actions.
"""
from __future__ import annotations

import json
from pathlib import Path

import pytest

from assess_report import (
    _fmt,
    _render_commit_note,
    format_structure_drift_findings,
    load_context,
    main,
    render_diff_section,
    render_exclusion_disclosure,
    render_findings_section,
    render_generated_disclosure,
    render_hotspots_table,
    render_keyhole_summary,
    render_report,
)


def _full_ctx() -> dict:
    """A realistic, non-normalised run-context with every section populated."""
    return {
        "run_date": "2026-06-01",
        "plugin_version": "1.22.0",
        "measured_commit": {
            "available": True,
            "head_short": "abc1234",
            "head_sha": "abc1234def5678",
            "subject": "feat: add the thing",
            "dirty": False,
            "behind": 0,
        },
        "prior_stats_exists": True,
        "diff_reliable": True,
        "diff_version_note": None,
        "stats_summary": {
            "files_scored": 58,
            "loc": {"max": 761.0, "p50": 132.5, "p95": 483.65, "total": 10428},
            "ccn": {"max": 169.0, "p50": 31.0, "p95": 107.35, "basis": "file-aggregate"},
            "top_hotspots": [
                {"path": "scripts/assess_core.py", "loc": 493, "ccn": 106.0, "commits": 14},
                {"path": "lib/doc_graph.py", "loc": 514, "ccn": 169.0, "commits": 7},
            ],
        },
        "diff": {"graduated": 1, "regressed": 1, "new": 1, "persistent": 1},
        "diff_detail": {
            "graduated": [{"path": "old/file.py", "ccn_delta": 0, "loc_delta": 0}],
            "new": [{"path": "new/file.py", "ccn_delta": 0, "loc_delta": 0}],
            "regressed": [{"path": "hot/file.py", "ccn_delta": 12, "loc_delta": 60}],
            "persistent": [{"path": "stable/file.py", "ccn_delta": 0, "loc_delta": 0}],
        },
        "doc_staleness": {"churn_window": "commits (last 12mo)", "available": True},
        "keyhole_summary": {
            "concerns": [{"name": "hidden_coupling", "count": 5}],
            "safe_zones": 1,
            "total_concerns": 5,
            "summary_text": "5 structural concerns (5 hidden coupling), 1 safe zone.",
        },
        "findings_markdown": (
            "## Cross-Layer Findings (Keyhole Readiness)\n\n"
            "### hidden_coupling\n\n"
            "Action: investigate the seam\n\n"
            "Paths:\n- scripts\n- scripts/tests\n"
        ),
        "prescribed_actions": [
            {"path": "scripts", "action": "investigate the seam",
             "findings": ["hidden_coupling"], "rank": 1},
        ],
        "structure_drift": _structure_drift_block(),
    }


def _structure_drift_block() -> dict:
    """A populated structure_drift block: Tier 0 empty globs + Tier 1 counts."""
    return {
        "tier_0": {
            "available": True,
            "total_patterns": 30,
            "matched_patterns": 8,
            "empty_ownership_patterns": [
                {"pattern": "../skills/marathon/SKILL.md",
                 "declared_in": "commands/README.md::Workflow",
                 "owners": []},
                {"pattern": "./assess/SKILL.md",
                 "declared_in": "skills/README.md::Portable",
                 "owners": ["@platform-team"]},
            ],
        },
        "tier_1": {
            "available": True,
            "human_grouped_static_splits_count": 6582,
            "human_split_static_fuses_count": 0,
            "human_grouped_never_cochange_count": 6636,
            "human_split_but_cochange_count": 6,
            "human_static_agree_count": 56,
            "human_cochange_agree_count": 2,
            "seam_allowlist_applied": True,
            "allowlist_pairs_count": 2,
        },
    }


def _minimal_ctx() -> dict:
    """The thinnest valid context: first run, no hotspots, no findings."""
    return {
        "run_date": "2026-06-01",
        "plugin_version": "1.22.0",
        "prior_stats_exists": False,
        "stats_summary": {"files_scored": 0, "loc": {}, "ccn": {}, "top_hotspots": []},
    }


# --------------------------------------------------------------------------
# _fmt
# --------------------------------------------------------------------------

def test_fmt_none_is_question_mark() -> None:
    assert _fmt(None) == "?"


def test_fmt_whole_float_drops_decimal() -> None:
    assert _fmt(493.0) == "493"


def test_fmt_fractional_float_one_decimal() -> None:
    out = _fmt(107.35)
    assert out.startswith("107.")
    assert len(out.split(".")[1]) == 1


def test_fmt_int_passthrough() -> None:
    assert _fmt(14) == "14"


# --------------------------------------------------------------------------
# Full render
# --------------------------------------------------------------------------

def test_full_render_has_all_sections() -> None:
    report = render_report(_full_ctx(), "ai-native-toolkit")
    assert "# Deterministic Assessment Snapshot: ai-native-toolkit" in report
    assert "## Metrics Dashboard" in report
    assert "### Top Hotspots" in report
    assert "## Keyhole Readiness" in report
    assert "## Changes Since Last Run" in report
    # No unsubstituted placeholders leaked.
    assert "$" not in report


# --------------------------------------------------------------------------
# Config-exclusion disclosure
# --------------------------------------------------------------------------


def test_exclusion_disclosure_renders_when_findings_suppressed() -> None:
    disclosure = render_exclusion_disclosure({
        "excluded_by_config": {
            "dirs": ["vendor"], "patterns": ["*.gen.py"],
            "affected_finding_paths": ["vendor/x.py", "a.gen.py"], "count": 2,
        }
    })
    assert "2 findings suppressed by config excludes" in disclosure
    assert "dirs: vendor" in disclosure
    assert "patterns: *.gen.py" in disclosure


def test_exclusion_disclosure_empty_without_excludes() -> None:
    assert render_exclusion_disclosure({}) == ""
    assert render_exclusion_disclosure(
        {"excluded_by_config": {"dirs": [], "patterns": [], "count": 0}}
    ) == ""


def test_archive_paths_excluded_disclosed_in_report() -> None:
    """Archive paths left out of attention are named under the keyhole summary."""
    disclosure = render_exclusion_disclosure({
        "excluded_as_archive": {
            "affected_finding_paths": ["docs/archive/PLAN.md"], "count": 1,
        }
    })
    assert disclosure == (
        "_1 archived path left out of the attention list: docs/archive/PLAN.md._"
    )
    both = render_exclusion_disclosure({
        "excluded_by_config": {"dirs": ["vendor"], "patterns": [], "count": 1},
        "excluded_as_archive": {"affected_finding_paths": ["a/attic/x.py", "b/archive/y.py"],
                                "count": 2},
    })
    assert both.split("\n\n") == [
        "_1 finding suppressed by config excludes (dirs: vendor; patterns: none)._",
        "_2 archived paths left out of the attention list: a/attic/x.py, b/archive/y.py._",
    ]
    assert render_exclusion_disclosure(
        {"excluded_as_archive": {"affected_finding_paths": [], "count": 0}}
    ) == ""
    many = [f"archive/f{i}.py" for i in range(7)]
    capped = render_exclusion_disclosure(
        {"excluded_as_archive": {"affected_finding_paths": many, "count": 7}}
    )
    assert capped == (
        "_7 archived paths left out of the attention list: archive/f0.py, "
        "archive/f1.py, archive/f2.py, archive/f3.py, archive/f4.py +2 more._"
    )


def test_pruned_finding_paths_disclosed_in_report() -> None:
    """Dead git-history paths dropped from the findings are named, capped at five."""
    assert render_exclusion_disclosure(
        {"pruned_finding_paths": {"paths": ["gone"], "count": 1}}
    ) == (
        "_1 git-history path no longer exists and was left out of the findings: gone._"
    )
    assert render_exclusion_disclosure(
        {"pruned_finding_paths": {"paths": [], "count": 0}}
    ) == ""
    many = [f"gone/d{i}" for i in range(6)]
    assert render_exclusion_disclosure(
        {"pruned_finding_paths": {"paths": many, "count": 6}}
    ).endswith("gone/d3, gone/d4 +1 more._")

def test_report_includes_exclusion_disclosure() -> None:
    ctx = _full_ctx()
    ctx["excluded_by_config"] = {
        "dirs": ["vendor"], "patterns": [],
        "affected_finding_paths": ["vendor/x.py"], "count": 1,
    }
    report = render_report(ctx, "demo")
    assert "1 finding suppressed by config excludes" in report
    # It sits in the Keyhole Readiness section, right after the summary line.
    assert report.index("Keyhole Readiness") < report.index("suppressed by config")


def test_report_no_disclosure_line_when_no_excludes() -> None:
    report = render_report(_full_ctx(), "demo")
    assert "suppressed by config excludes" not in report


def test_full_render_metrics_values() -> None:
    report = render_report(_full_ctx(), "demo")
    assert "**Files scored:** 58" in report
    assert "**Total LOC:** 10428" in report
    assert "p95 LOC 483" in report
    assert "max 761" in report
    assert "p95 CCN 107" in report
    assert "max 169" in report
    assert "**Churn window:** commits (last 12mo)" in report


def test_churn_window_carries_degenerate_caveat() -> None:
    """Issue #172: when the run-context flags a degenerate churn history, the
    churn-window line carries a 'snapshot / no usable history' caveat so the
    score line isn't read as backed by a live churn signal."""
    ctx = _full_ctx()
    ctx["churn_degenerate"] = True
    report = render_report(ctx, "demo")
    assert "snapshot / no usable history, churn signal flat" in report

    # Default (no flag) leaves the line clean - no regression for real histories.
    clean = render_report(_full_ctx(), "demo")
    assert "**Churn window:** commits (last 12mo)" in clean
    assert "snapshot / no usable history" not in clean


def test_full_render_substitute_is_strict() -> None:
    # render_report must not raise on a fully populated context.
    render_report(_full_ctx(), "demo")


def test_minimal_render_uses_fallbacks() -> None:
    report = render_report(_minimal_ctx(), "tiny")
    assert "_No hotspots identified._" in report
    assert "_No cross-layer findings recorded._" in report
    assert "_Keyhole readiness summary unavailable._" in report
    assert "first recorded snapshot" in report
    assert "$" not in report


# --------------------------------------------------------------------------
# Hotspots table
# --------------------------------------------------------------------------

def test_hotspots_table_empty_fallback() -> None:
    assert render_hotspots_table({"stats_summary": {"top_hotspots": []}}) == \
        "_No hotspots identified._"


def test_hotspots_table_rows_and_header() -> None:
    out = render_hotspots_table(_full_ctx())
    assert "| Path | LOC | CCN | Commits |" in out
    assert "| `scripts/assess_core.py` | 493 | 106 | 14 |" in out
    assert "| `lib/doc_graph.py` | 514 | 169 | 7 |" in out


def test_hotspots_table_missing_metric_renders_question_mark() -> None:
    ctx = {"stats_summary": {"top_hotspots": [{"path": "x.py"}]}}
    out = render_hotspots_table(ctx)
    assert "| `x.py` | ? | ? | ? |" in out


def test_hotspots_table_caps_at_ten_rows() -> None:
    hotspots = [{"path": f"f{i}.py", "loc": 1, "ccn": 1, "commits": 1} for i in range(25)]
    out = render_hotspots_table({"stats_summary": {"top_hotspots": hotspots}})
    # 2 header lines + 10 data rows.
    assert len(out.splitlines()) == 12
    assert "f9.py" in out
    assert "f10.py" not in out


# --------------------------------------------------------------------------
# Keyhole summary + findings
# --------------------------------------------------------------------------

def test_keyhole_summary_consumed_verbatim() -> None:
    out = render_keyhole_summary(_full_ctx())
    assert out == "5 structural concerns (5 hidden coupling), 1 safe zone."


def test_keyhole_summary_missing_fallback() -> None:
    assert render_keyhole_summary({}) == "_Keyhole readiness summary unavailable._"


def test_findings_section_verbatim() -> None:
    out = render_findings_section(_full_ctx())
    assert out.startswith("## Cross-Layer Findings (Keyhole Readiness)")
    assert "### hidden_coupling" in out
    assert "Action: investigate the seam" in out


def test_findings_section_empty_fallback() -> None:
    assert render_findings_section({"findings_markdown": "   "}) == \
        "_No cross-layer findings recorded._"
    assert render_findings_section({}) == "_No cross-layer findings recorded._"


# --------------------------------------------------------------------------
# Diff section
# --------------------------------------------------------------------------

def test_diff_no_prior_run() -> None:
    out = render_diff_section({"prior_stats_exists": False})
    assert "No prior run to compare against" in out


def test_diff_unreliable_is_suppressed_with_note() -> None:
    ctx = {
        "prior_stats_exists": True,
        "diff_reliable": False,
        "diff_version_note": "prior stats from plugin 1.10.0, current 1.22.0",
    }
    out = render_diff_section(ctx)
    assert out.startswith("_Diff suppressed:")
    assert "1.10.0" in out


def test_diff_unreliable_without_note_falls_back() -> None:
    out = render_diff_section({"prior_stats_exists": True, "diff_reliable": False})
    assert "not comparable" in out


def test_diff_major_bump_renders_trend_reset_disclosure() -> None:
    """A MAJOR version bump renders an explicit trend-reset line, distinct from a
    plain suppression, so a voided diff isn't misread as an unchanged run."""
    ctx = {
        "prior_stats_exists": True,
        "diff_reliable": False,
        "diff_trend_reset": True,
        "diff_version_note": "major version changed 1.54.1->2.0.0",
    }
    out = render_diff_section(ctx)
    assert out.startswith("_Trend baseline reset:")
    assert "major version changed 1.54.1->2.0.0" in out
    assert "trend restarts" in out


def test_diff_reliable_renders_all_categories() -> None:
    out = render_diff_section(_full_ctx())
    assert "- **Graduated** (left the hotspot list): 1" in out
    assert "- **New** (entered the hotspot list): 1" in out
    assert "- **Regressed** (complexity or churn increased): 1" in out
    assert "- **Persistent** (still in the hotspot list): 1" in out
    assert "- `old/file.py`" in out
    assert "- `new/file.py`" in out
    assert "- `stable/file.py`" in out


def test_diff_regressed_shows_deltas() -> None:
    out = render_diff_section(_full_ctx())
    assert "- `hot/file.py` (CCN +12, LOC +60)" in out


def test_diff_regressed_without_deltas_omits_suffix() -> None:
    ctx = {
        "prior_stats_exists": True,
        "diff_reliable": True,
        "diff": {"regressed": 1},
        "diff_detail": {"regressed": [{"path": "x.py", "ccn_delta": 0, "loc_delta": 0}]},
    }
    out = render_diff_section(ctx)
    assert "- `x.py`" in out
    assert "(CCN" not in out


def test_diff_caps_rows_and_reports_overflow() -> None:
    entries = [{"path": f"f{i}.py"} for i in range(13)]
    ctx = {
        "prior_stats_exists": True,
        "diff_reliable": True,
        "diff": {"persistent": 13},
        "diff_detail": {"persistent": entries},
    }
    out = render_diff_section(ctx)
    assert "...and 3 more" in out
    assert "f9.py" in out
    assert "f10.py" not in out


# --------------------------------------------------------------------------
# Commit note
# --------------------------------------------------------------------------

def test_commit_note_clean() -> None:
    note = _render_commit_note(_full_ctx())
    assert "Measured at `abc1234`" in note
    assert '("feat: add the thing")' in note
    assert "dirty" not in note
    assert "behind" not in note


def test_commit_note_dirty_and_behind() -> None:
    ctx = {"measured_commit": {
        "available": True, "head_short": "deadbee", "dirty": True, "behind": 3,
    }}
    note = _render_commit_note(ctx)
    assert "working tree dirty" in note
    assert "3 commit(s) behind upstream" in note


def test_commit_note_unavailable_is_empty() -> None:
    assert _render_commit_note({"measured_commit": {"available": False}}) == ""
    assert _render_commit_note({}) == ""


# --------------------------------------------------------------------------
# Structure drift (Tier 0 ownership-map drift + Tier 1 grouping disagreement)
# --------------------------------------------------------------------------

def test_structure_drift_tier0_lists_empty_patterns() -> None:
    """Tier 0 surfaces each empty ownership pattern with its declared_in source
    and owners, framed as stale ownership dropping review coverage."""
    out = format_structure_drift_findings(_structure_drift_block())
    assert "Tier 0" in out
    assert "Ownership Map Drift" in out
    assert "`../skills/marathon/SKILL.md`" in out
    assert "commands/README.md::Workflow" in out
    assert "@platform-team" in out
    # The interpretation is review-coverage loss, not a blame.
    assert "review coverage" in out


def test_structure_drift_tier0_omitted_when_no_empty_patterns() -> None:
    block = _structure_drift_block()
    block["tier_0"]["empty_ownership_patterns"] = []
    out = format_structure_drift_findings(block)
    assert "Tier 0" not in out


def test_structure_drift_tier0_omitted_when_unavailable() -> None:
    block = _structure_drift_block()
    block["tier_0"] = {"available": False}
    out = format_structure_drift_findings(block)
    assert "Tier 0" not in out


def test_structure_drift_tier1_renders_six_counts() -> None:
    """Tier 1 surfaces the six disagreement/agreement counts, objective first."""
    out = format_structure_drift_findings(_structure_drift_block())
    assert "Tier 1" in out
    assert "Grouping Disagreement" in out
    # All six magnitudes are present.
    assert "6582" in out
    assert "6636" in out
    assert "56" in out
    assert "2" in out
    # Zero counts are shown explicitly, not dropped.
    assert "human_split_static_fuses" in out
    assert "human_split_but_cochange" in out


def test_structure_drift_tier1_omitted_when_unavailable() -> None:
    block = _structure_drift_block()
    block["tier_1"] = {"available": False}
    out = format_structure_drift_findings(block)
    assert "Grouping Disagreement" not in out


def test_structure_drift_seam_allowlist_transparency() -> None:
    """When the allowlist fired, the report says so and how many pairs it cut."""
    out = format_structure_drift_findings(_structure_drift_block())
    assert "allowlist" in out
    assert "2" in out  # allowlist_pairs_count


def test_structure_drift_never_auto_recommends_regenerate_codeowners() -> None:
    """The deterministic harness states counts; regenerating the ownership map is
    a human decision, never an auto-prescribed action."""
    out = format_structure_drift_findings(_structure_drift_block()).lower()
    assert "regenerate codeowners" not in out
    assert "regenerate the ownership map" not in out


def test_structure_drift_empty_block_omitted() -> None:
    assert format_structure_drift_findings(None) == ""
    assert format_structure_drift_findings({}) == ""


def test_structure_drift_deterministic() -> None:
    block = _structure_drift_block()
    assert format_structure_drift_findings(block) == \
        format_structure_drift_findings(block)


def test_structure_drift_in_full_report() -> None:
    report = render_report(_full_ctx(), "demo")
    assert "Structure Drift" in report
    assert "Tier 0" in report
    assert "Tier 1" in report
    assert "$" not in report


def test_structure_drift_absent_block_leaves_valid_report() -> None:
    ctx = _full_ctx()
    del ctx["structure_drift"]
    report = render_report(ctx, "demo")
    assert "Structure Drift" not in report
    assert "$" not in report


# --------------------------------------------------------------------------
# Honest boundary: must NOT reproduce LLM-only content
# --------------------------------------------------------------------------

def test_report_omits_llm_only_artifacts() -> None:
    report = render_report(_full_ctx(), "demo")
    # The 0-8 layered score and the Top 3 Actions priority narrative are the
    # LLM's job; the frozen report names the boundary, it does not fake them.
    assert "## Top 3 Actions" not in report
    assert "present/partial/missing" not in report
    assert "/ 8" not in report
    assert "require LLM judgement" in report


# --------------------------------------------------------------------------
# main() + IO
# --------------------------------------------------------------------------

def _seed_run_context(repo_root: Path, ctx: dict) -> None:
    assess_dir = repo_root / ".assess"
    assess_dir.mkdir(parents=True, exist_ok=True)
    (assess_dir / "run-context.json").write_text(json.dumps(ctx), encoding="utf-8")


def test_load_context_roundtrip(tmp_path: Path) -> None:
    _seed_run_context(tmp_path, _full_ctx())
    loaded = load_context(tmp_path)
    assert loaded["run_date"] == "2026-06-01"


def test_main_writes_report_file(tmp_path: Path, capsys: pytest.CaptureFixture) -> None:
    _seed_run_context(tmp_path, _full_ctx())
    rc = main([str(tmp_path)])
    assert rc == 0
    out_path = tmp_path / ".assess" / "deterministic-report.md"
    assert out_path.exists()
    report = out_path.read_text(encoding="utf-8")
    assert "# Deterministic Assessment Snapshot:" in report
    assert str(out_path) in capsys.readouterr().out


def test_main_stdout_does_not_write_file(tmp_path: Path,
                                         capsys: pytest.CaptureFixture) -> None:
    _seed_run_context(tmp_path, _full_ctx())
    rc = main([str(tmp_path), "--stdout"])
    assert rc == 0
    assert not (tmp_path / ".assess" / "deterministic-report.md").exists()
    out = capsys.readouterr().out
    assert "# Deterministic Assessment Snapshot:" in out


def test_main_no_args_usage_error(capsys: pytest.CaptureFixture) -> None:
    rc = main([])
    assert rc == 2
    assert "Usage:" in capsys.readouterr().err


def test_main_missing_context_skips_not_fails(tmp_path: Path,
                                               capsys: pytest.CaptureFixture) -> None:
    """A missing run-context is infrastructure, not a finding: the renderer skips
    with a notice and exits 0 rather than crashing the check."""
    rc = main([str(tmp_path)])
    assert rc == 0
    err = capsys.readouterr().err
    assert "report skipped" in err
    assert "infrastructure failure" in err
    assert not (tmp_path / ".assess" / "deterministic-report.md").exists()


def test_main_corrupt_context_skips_not_fails(tmp_path: Path,
                                               capsys: pytest.CaptureFixture) -> None:
    (tmp_path / ".assess").mkdir(parents=True)
    (tmp_path / ".assess" / "run-context.json").write_text(
        "{ not valid json", encoding="utf-8"
    )
    rc = main([str(tmp_path)])
    assert rc == 0
    assert "infrastructure failure" in capsys.readouterr().err


# --------------------------------------------------------------------------
# Generated-file disclosure (excluded_generated)
# --------------------------------------------------------------------------


def test_generated_header_exclusion_named_with_reason_on_one_line() -> None:
    ctx = _full_ctx()
    ctx["excluded_generated"] = [
        {"path": "db/schema.sql", "reason": "generated-header"},
        {"path": "assets/font.ts", "reason": "long-lines"},
    ]
    report = render_report(ctx, "demo")
    lines = report.splitlines()
    assert any("db/schema.sql" in ln and "generated-header" in ln for ln in lines)
    assert any("assets/font.ts" in ln and "long-lines" in ln for ln in lines)
    assert "2 files excluded from scoring as generated" in report


def test_generated_header_disclosure_silent_when_empty() -> None:
    assert render_generated_disclosure({}) == ""
    assert render_generated_disclosure({"excluded_generated": []}) == ""
    assert "excluded from scoring as generated" not in render_report(_full_ctx(), "demo")


def test_generated_header_disclosure_folds_rows_past_the_cap() -> None:
    rows = [{"path": f"gen/f{i:02}.sql", "reason": "generated-header"} for i in range(13)]
    out = render_generated_disclosure({"excluded_generated": rows})
    head, fold = out.split("<details>")
    assert "gen/f09.sql` (generated-header)" in head
    assert "gen/f10.sql" not in head
    assert "3 more</summary>" in fold
    for i in (10, 11, 12):
        assert f"- `gen/f{i}.sql` (generated-header)" in fold
    assert fold.rstrip().endswith("</details>")


def test_pruned_finding_paths_disclosure_names_incomplete_rename_map() -> None:
    """A run whose rename map could not be built says so instead of reading
    like a run with nothing dead."""
    assert render_exclusion_disclosure({"pruned_finding_paths": {
        "paths": [], "count": 0, "rename_map_complete": False}}) == (
        "_Renames could not be read from git history: findings may name "
        "pre-rename paths, and none were pruned._"
    )
    assert render_exclusion_disclosure({"pruned_finding_paths": {
        "paths": [], "count": 0, "rename_map_complete": True}}) == ""


def test_attention_low_signal_disclosed_in_report() -> None:
    """A low-signal ranking says why only rank 1 is prescribed; false says nothing."""
    assert render_exclusion_disclosure({"attention_low_signal": True}) == (
        "_Attention ranking is low signal (no attention row lands in more than one "
        "finding): only rank 1 is prescribed._"
    )
    assert render_exclusion_disclosure({"attention_low_signal": False}) == ""


def test_report_code_data_maxima_quoted_separately() -> None:
    ctx = _full_ctx()
    ctx["stats_summary"]["loc"].update({"max_code": 761.0, "max_data": 7137.0})
    ctx["stats_summary"]["loc"]["max"] = 7137.0
    lines = [ln for ln in render_report(ctx, "repo").splitlines()
             if "**Complexity profile:**" in ln]
    assert len(lines) == 1
    line = lines[0]
    assert "code 761" in line and "data 7137" in line
    assert "(max 7137;" in line


def test_report_code_data_maxima_absent_on_older_snapshot() -> None:
    """A pre-split stats snapshot has no max_code / max_data; the line keeps
    its old shape rather than printing '?' placeholders."""
    line = next(ln for ln in render_report(_full_ctx(), "repo").splitlines()
                if "**Complexity profile:**" in ln)
    assert line == ("- **Complexity profile:** p95 LOC 483.6 (max 761), "
                    "p95 CCN 107.3 (max 169)")

"""Tests for the shields.io endpoint badge (lib/badge.py) and its producers.

The badge is a self-description, so the contract under test is honesty: colours
are pure threshold functions, the fallback only claims what was measured, and a
deterministic-only run never downgrades a finalized score badge.
"""
from __future__ import annotations

import json
from pathlib import Path

from lib.badge import (
    badge_exists,
    concern_count_from_findings,
    fallback_badge,
    maturity_band,
    score_badge,
    score_color,
    write_badge,
)


def test_score_color_bands():
    """Hand-computed band edges: first matching floor wins."""
    assert score_color(8.0) == "brightgreen"
    assert score_color(7.0) == "brightgreen"
    assert score_color(6.5) == "green"
    assert score_color(5.5) == "green"
    assert score_color(4.0) == "yellowgreen"
    assert score_color(2.5) == "yellow"
    assert score_color(1.0) == "orange"
    assert score_color(0.5) == "red"
    assert score_color(0.0) == "red"


def test_score_badge_shape():
    badge = score_badge(7.0, "AI-Native")
    assert badge == {
        "schemaVersion": 1,
        "label": "AI-readiness",
        "message": "7.0/8 · AI-Native",
        "color": "brightgreen",
    }


def test_fallback_badge_clean_repo_is_green():
    badge = fallback_badge(0, 0)
    assert badge["message"] == "0 findings · 0 stale markers"
    assert badge["color"] == "green"


def test_fallback_badge_colors_scale_with_concerns():
    assert fallback_badge(1, 3)["color"] == "yellow"
    assert fallback_badge(2, 0)["color"] == "yellow"
    assert fallback_badge(3, 0)["color"] == "orange"


def test_concern_count_ignores_refactor_boundary_and_empty():
    findings = [
        {"name": "hidden_coupling", "paths": ["a.py"], "action": "x"},
        {"name": "lying_map", "paths": [], "action": "x"},
        {"name": "unactioned_intent", "paths": ["b.py"], "action": "x"},
        {"name": "refactor_boundary", "paths": ["safe/"], "action": "x"},
    ]
    assert concern_count_from_findings(findings) == 2


def test_write_and_exists_roundtrip(tmp_path: Path):
    assert not badge_exists(tmp_path)
    write_badge(tmp_path, score_badge(5.0, "Solid"))
    assert badge_exists(tmp_path)
    data = json.loads((tmp_path / "badge.json").read_text(encoding="utf-8"))
    assert data["schemaVersion"] == 1
    assert data["message"] == "5.0/8 · Solid"


def test_score_badge_knowledge_base_denominator():
    """A KB renormalises the denominator over its applicable layers (#224)."""
    badge = score_badge(2.5, "Knowledge Base · Solid", denominator=3)
    assert badge["message"] == "2.5/3 · Knowledge Base · Solid"
    # 2.5/3 = 0.833 -> green band (>= 0.6875), not the misleading 2.5/8 yellow.
    assert badge["color"] == "green"


def test_score_color_normalises_over_denominator():
    # Full marks on a KB denominator is brightgreen, not red.
    assert score_color(3.0, 3) == "brightgreen"
    assert score_color(0.0, 3) == "red"
    # Default denominator 8 reproduces the original absolute bands.
    assert score_color(7.0) == "brightgreen"
    assert score_color(7.0, 8) == "brightgreen"


def test_maturity_band_ladder():
    """The documented ladder: >=0.875 AI-Native, >=0.625 Solid, >=0.375 Basic,
    else Not Ready. Band edges hit exactly."""
    assert maturity_band(7.0) == "AI-Native"   # 0.875
    assert maturity_band(6.9) == "Solid"       # 0.8625
    assert maturity_band(5.0) == "Solid"       # 0.625
    assert maturity_band(4.9) == "Basic"       # 0.6125
    assert maturity_band(3.0) == "Basic"       # 0.375
    assert maturity_band(2.9) == "Not Ready"   # 0.3625
    assert maturity_band(0.0) == "Not Ready"


def test_maturity_band_normalises_over_denominator():
    # A KB scoring full marks earns AI-Native, not the misleading 2.5/8 read.
    assert maturity_band(3.0, 3) == "AI-Native"
    assert maturity_band(2.5, 3) == "Solid"   # 0.833


def test_score_badge_stamps_run_id_when_supplied():
    badge = score_badge(6.0, "Solid", run_id="20260707120000-abcdef01")
    assert badge["run_id"] == "20260707120000-abcdef01"
    # Message/colour are unchanged by the extra provenance field.
    assert badge["message"] == "6.0/8 · Solid"


def test_badge_run_id_omitted_by_default():
    """No run_id -> no key, so the badge dict is byte-identical to before."""
    assert "run_id" not in score_badge(6.0, "Solid")
    assert "run_id" not in fallback_badge(1, 0)


def test_fallback_badge_stamps_run_id_when_supplied():
    badge = fallback_badge(2, 1, run_id="20260707120000-abcdef01")
    assert badge["run_id"] == "20260707120000-abcdef01"
    assert badge["message"] == "2 findings · 1 stale markers"

"""Tests for the git-log change-coupling and authorship primitives (B1/B2/B4).

Fixtures build synthetic git histories in tmp dirs. Expected values are
hand-computed in each test's docstring/comments so the contract is auditable.
"""
from __future__ import annotations

import os
import subprocess
from pathlib import Path

from lib.change_coupling import (
    RenameMap,
    authorship_analysis,
    build_rename_map,
    change_coupling_pairs,
    containment_ratio,
    find_self_referential_tests,
    fold_renames,
    parse_commit_file_sets,
)


def _git(repo: Path, *args: str, env: dict | None = None) -> None:
    full_env = {**os.environ, **(env or {})}
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True, env=full_env)


def _write(repo: Path, rel: str, text: str) -> None:
    p = repo / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _commit(
    repo: Path,
    files: dict[str, str],
    message: str = "change",
    *,
    author: tuple[str, str] | None = None,
    committer: tuple[str, str] | None = None,
    co_authors: list[str] | None = None,
) -> None:
    """Write ``files`` (rel path -> contents), stage, and commit.

    ``author``/``committer`` are (name, email) tuples; ``co_authors`` is a list
    of "Name <email>" strings folded into Co-Authored-By trailers.
    """
    for rel, text in files.items():
        _write(repo, rel, text)
    _git(repo, "add", "-A")
    body = message
    for ca in co_authors or []:
        body += f"\n\nCo-Authored-By: {ca}"
    env: dict[str, str] = {}
    if author:
        env["GIT_AUTHOR_NAME"], env["GIT_AUTHOR_EMAIL"] = author
    if committer:
        env["GIT_COMMITTER_NAME"], env["GIT_COMMITTER_EMAIL"] = committer
    _git(repo, "commit", "-q", "-m", body, env=env)


def _init_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "dev@example.com")
    _git(repo, "config", "user.name", "Dev Human")
    return repo


# --- parse_commit_file_sets --------------------------------------------------

def test_parse_commit_file_sets_one_set_per_commit(tmp_path: Path) -> None:
    repo = _init_repo(tmp_path)
    _commit(repo, {"a.py": "1", "b.py": "1"}, "c1")
    _commit(repo, {"a.py": "2"}, "c2")

    sets = parse_commit_file_sets(repo)
    # Newest first: [{a.py}, {a.py, b.py}]
    assert len(sets) == 2
    assert sets[0] == {Path("a.py")}
    assert sets[1] == {Path("a.py"), Path("b.py")}


def test_parse_commit_file_sets_no_git_returns_empty(tmp_path: Path) -> None:
    plain = tmp_path / "nogit"
    plain.mkdir()
    (plain / "a.py").write_text("x", encoding="utf-8")
    assert parse_commit_file_sets(plain) == []


def test_parse_commit_file_sets_since_window(tmp_path: Path) -> None:
    repo = _init_repo(tmp_path)
    old_date = "2020-01-01T00:00:00"
    _commit_env = {"GIT_AUTHOR_DATE": old_date, "GIT_COMMITTER_DATE": old_date}
    _write(repo, "old.py", "x")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "old", env=_commit_env)
    _commit(repo, {"new.py": "y"}, "new")  # committed "now"

    sets = parse_commit_file_sets(repo, since="1 year ago")
    flat = {p for s in sets for p in s}
    assert Path("new.py") in flat
    assert Path("old.py") not in flat


# --- change_coupling_pairs (B1) ----------------------------------------------

def test_change_coupling_detects_co_changing_trio(tmp_path: Path) -> None:
    """Three files always committed together over 4 commits -> 3 pairs, count 4."""
    repo = _init_repo(tmp_path)
    for i in range(4):
        _commit(repo, {"a.py": str(i), "b.py": str(i), "c.py": str(i)}, f"c{i}")

    sets = parse_commit_file_sets(repo)
    pairs = change_coupling_pairs(sets, min_support=3)
    # combinations of {a,b,c} = (a,b),(a,c),(b,c); each co-changed 4 times.
    assert len(pairs) == 3
    for p in pairs:
        assert p["co_change_count"] == 4
        # 4 of 4 commits -> 100% support.
        assert p["support_pct"] == 100.0
    keys = {(p["file_a"], p["file_b"]) for p in pairs}
    assert keys == {("a.py", "b.py"), ("a.py", "c.py"), ("b.py", "c.py")}


def test_change_coupling_respects_min_support(tmp_path: Path) -> None:
    """A pair co-changing only twice is dropped at the default min_support=3."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"x.py": "1", "y.py": "1"}, "c1")
    _commit(repo, {"x.py": "2", "y.py": "2"}, "c2")  # x,y co-change = 2
    _commit(repo, {"x.py": "3"}, "c3")

    sets = parse_commit_file_sets(repo)
    assert change_coupling_pairs(sets, min_support=3) == []
    # Lowering the threshold surfaces it.
    low = change_coupling_pairs(sets, min_support=2)
    assert len(low) == 1
    assert low[0]["co_change_count"] == 2
    assert (low[0]["file_a"], low[0]["file_b"]) == ("x.py", "y.py")


def test_change_coupling_single_file_commits_yield_no_pairs(tmp_path: Path) -> None:
    repo = _init_repo(tmp_path)
    for i in range(5):
        _commit(repo, {"solo.py": str(i)}, f"c{i}")
    sets = parse_commit_file_sets(repo)
    assert change_coupling_pairs(sets) == []


def test_change_coupling_empty_input() -> None:
    assert change_coupling_pairs([]) == []


# --- containment_ratio (B2) --------------------------------------------------

def test_containment_fully_contained_module(tmp_path: Path) -> None:
    """A module whose commits never reach outside it has ratio 1.0."""
    repo = _init_repo(tmp_path)
    for i in range(3):
        _commit(repo, {f"mod/f{i}.py": str(i), "mod/core.py": str(i)}, f"c{i}")
    sets = parse_commit_file_sets(repo)
    assert containment_ratio(repo, "mod", sets) == 1.0


def test_containment_bleeding_module(tmp_path: Path) -> None:
    """Module edits that routinely drag in outside files give a low ratio."""
    repo = _init_repo(tmp_path)
    # 1 self-contained commit...
    _commit(repo, {"mod/a.py": "1"}, "contained")
    # ...and 3 that also touch files outside the module.
    for i in range(3):
        _commit(repo, {"mod/a.py": f"v{i}", "other/b.py": f"v{i}"}, f"bleed{i}")
    sets = parse_commit_file_sets(repo)
    # 4 commits touch mod, only 1 touches mod-only -> 1/4 = 0.25
    assert containment_ratio(repo, "mod", sets) == 0.25


def test_containment_zero_commits_returns_one(tmp_path: Path) -> None:
    """A module no commit touches is vacuously contained (documented: 1.0)."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"other/a.py": "1"}, "c1")
    sets = parse_commit_file_sets(repo)
    assert containment_ratio(repo, "nonexistent", sets) == 1.0


def test_containment_accepts_absolute_module_path(tmp_path: Path) -> None:
    repo = _init_repo(tmp_path)
    for i in range(2):
        _commit(repo, {f"mod/f{i}.py": str(i)}, f"c{i}")
    sets = parse_commit_file_sets(repo)
    # Absolute path is normalised to repo-relative internally.
    assert containment_ratio(repo, repo / "mod", sets) == 1.0


# --- authorship_analysis (B4) ------------------------------------------------

def test_authorship_human_only(tmp_path: Path) -> None:
    repo = _init_repo(tmp_path)
    _commit(repo, {"app.py": "1"}, "c1",
            author=("Alice", "alice@example.com"),
            committer=("Alice", "alice@example.com"))
    r = authorship_analysis(repo, "app.py")
    assert r["authorship_class"] == "human"
    assert r["human_anchor"] is True
    assert r["intent_source"] is True
    assert r["contributors"][0]["email"] == "alice@example.com"
    assert r["contributors"][0]["classification"] == "human"


def test_authorship_mixed_human_author_agent_coauthor(tmp_path: Path) -> None:
    """Human author + Claude co-author = agent involvement alongside a human."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"app.py": "1"}, "feat: thing",
            author=("Bob", "bob@example.com"),
            committer=("Bob", "bob@example.com"),
            co_authors=["Claude <noreply@anthropic.com>"])
    r = authorship_analysis(repo, "app.py")
    assert r["authorship_class"] == "mixed"
    assert r["human_anchor"] is True
    assert r["intent_source"] is True


def test_authorship_pure_agent_via_bot_committer(tmp_path: Path) -> None:
    """Bot author + bot committer with no human anywhere -> 'agent'."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"dep.lock": "1"}, "chore: bump",
            author=("dependabot[bot]", "49699333+dependabot[bot]@users.noreply.github.com"),
            committer=("dependabot[bot]", "49699333+dependabot[bot]@users.noreply.github.com"))
    r = authorship_analysis(repo, "dep.lock")
    assert r["authorship_class"] == "agent"
    assert r["human_anchor"] is False
    assert r["intent_source"] is False
    assert r["contributors"][0]["classification"] == "agent"


def test_authorship_agent_authored_human_committed(tmp_path: Path) -> None:
    """Bot author + human committer: class is 'agent', but intent_source is True."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"x.py": "1"}, "apply bot patch",
            author=("renovate[bot]", "29139614+renovate[bot]@users.noreply.github.com"),
            committer=("Carol", "carol@example.com"))
    r = authorship_analysis(repo, "x.py")
    # agent author + human committer: agent involved, but no human *author*, and
    # n_unknown==0, so the class is 'agent'. The human committer still makes
    # them the intent source (a human directed/applied the change).
    assert r["authorship_class"] == "agent"
    assert r["human_anchor"] is False
    assert r["intent_source"] is True


def test_authorship_human_named_claude_not_libelled(tmp_path: Path) -> None:
    """A real human named 'Claude' with a normal e-mail must NOT be called agent."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"app.py": "1"}, "c1",
            author=("Claude Dupont", "claude.dupont@example.com"),
            committer=("Claude Dupont", "claude.dupont@example.com"))
    r = authorship_analysis(repo, "app.py")
    assert r["authorship_class"] == "human"
    assert r["human_anchor"] is True
    assert r["contributors"][0]["classification"] == "human"


def test_authorship_no_history_degrades(tmp_path: Path) -> None:
    plain = tmp_path / "nogit"
    plain.mkdir()
    r = authorship_analysis(plain, "whatever.py")
    assert r == {
        "human_anchor": False,
        "authorship_class": "unknown",
        "intent_source": False,
        "contributors": [],
    }


def test_authorship_contributor_line_stats(tmp_path: Path) -> None:
    """numstat line counts aggregate per author across commits."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"app.py": "line1\nline2\n"}, "c1",
            author=("Alice", "alice@example.com"),
            committer=("Alice", "alice@example.com"))
    _commit(repo, {"app.py": "line1\nline2\nline3\n"}, "c2",
            author=("Alice", "alice@example.com"),
            committer=("Alice", "alice@example.com"))
    r = authorship_analysis(repo, "app.py")
    alice = r["contributors"][0]
    assert alice["commits"] == 2
    # First commit adds 2 lines; second adds 1 more. 3 added total, 0 removed.
    assert alice["lines_added"] == 3
    assert alice["lines_removed"] == 0


# --- E2: find_self_referential_tests ------------------------------------------

def test_self_referential_test_same_commit_flagged(tmp_path: Path) -> None:
    """Test + code introduced in one commit -> self-referential."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"pkg/svc.go": "package pkg",
                   "pkg/svc_test.go": "package pkg"}, "feat: svc + test together")
    result = find_self_referential_tests(
        repo, {"pkg/svc_test.go": "pkg/svc.go"}
    )
    assert result == [{
        "test_file": "pkg/svc_test.go",
        "source_file": "pkg/svc.go",
        "reason": "test added in same commit as code",
    }]


def test_self_referential_test_separate_commits_not_flagged(tmp_path: Path) -> None:
    """Code first, test in a later commit -> not the same-commit signal."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"pkg/svc.go": "package pkg"}, "feat: svc")
    _commit(repo, {"pkg/svc_test.go": "package pkg"}, "test: svc")
    result = find_self_referential_tests(
        repo, {"pkg/svc_test.go": "pkg/svc.go"}
    )
    assert result == []


def test_self_referential_test_empty_map_returns_empty(tmp_path: Path) -> None:
    repo = _init_repo(tmp_path)
    _commit(repo, {"a.py": "1"}, "c1")
    assert find_self_referential_tests(repo, {}) == []


def test_self_referential_test_reuses_passed_commit_sets(tmp_path: Path) -> None:
    """commit_sets passed in (the orchestrator's single git-log parse) is used
    directly - no second git call needed."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"m.py": "1", "test_m.py": "1"}, "feat+test")
    commit_sets = parse_commit_file_sets(repo)
    result = find_self_referential_tests(
        repo, {"test_m.py": "m.py"}, commit_sets=commit_sets
    )
    assert [r["source_file"] for r in result] == ["m.py"]


# --- build_rename_map / fold_renames (renamed paths) --------------------------

def test_rename_map_folds_history_onto_current_paths(tmp_path: Path) -> None:
    """a/x.py and a/y.py co-change 3 times, then a/ -> b/ -> c/. The map
    resolves the chain to c/, and folding counts the pre-rename history under
    the current names: 3 edits + 2 rename commits = 5 co-changes."""
    repo = _init_repo(tmp_path)
    for i in range(3):
        _commit(repo, {"a/x.py": f"x = {i}\n" * 5, "a/y.py": f"y = {i}\n" * 5})
    _git(repo, "mv", "a", "b")
    _commit(repo, {}, "rename a -> b")
    _git(repo, "mv", "b", "c")
    _commit(repo, {}, "rename b -> c")

    rename_map = build_rename_map(repo)
    assert rename_map.complete
    assert rename_map.paths == {
        "a/x.py": "c/x.py", "a/y.py": "c/y.py",
        "b/x.py": "c/x.py", "b/y.py": "c/y.py",
    }
    pairs = change_coupling_pairs(
        fold_renames(parse_commit_file_sets(repo), rename_map.paths), min_support=1,
    )
    assert [(p["file_a"], p["file_b"], p["co_change_count"]) for p in pairs] == [
        ("c/x.py", "c/y.py", 5),
    ]


def test_rename_map_skips_path_reused_at_head(tmp_path: Path) -> None:
    """A name that exists again at HEAD keeps its own history, so it is left
    out of the map; outside a git repo there is no history, so the map is
    empty and complete (only a failed git read marks it incomplete)."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"old.py": "v = 1\n" * 5})
    _git(repo, "mv", "old.py", "new.py")
    _commit(repo, {}, "rename")
    _commit(repo, {"old.py": "fresh = 1\n"}, "reuse the name")

    assert build_rename_map(repo) == RenameMap({}, complete=True)
    plain = tmp_path / "plain"
    plain.mkdir()
    assert build_rename_map(plain) == RenameMap({}, complete=True)
    assert fold_renames([{Path("a.py")}], {}) == [{Path("a.py")}]


def test_rename_map_incomplete_when_git_log_times_out(tmp_path: Path, monkeypatch) -> None:
    """A git timeout yields an empty, incomplete map rather than an empty map
    that reads as "nothing was renamed"."""
    import lib.change_coupling as cc

    repo = _init_repo(tmp_path)
    _commit(repo, {"a.py": "v = 1\n"})
    top = cc.repo_top(repo)
    assert top is not None

    def boom(*args, **kwargs):
        raise subprocess.TimeoutExpired(cmd="git log", timeout=cc.GIT_TIMEOUT_SECONDS)

    monkeypatch.setattr(cc.subprocess, "run", boom)
    assert cc.build_rename_map(repo, top=top) == RenameMap({}, complete=False)


def test_rename_map_resolves_chain_through_reused_intermediate(tmp_path: Path) -> None:
    """a -> b, b -> c, then a fresh b. The chain resolves before the reused-name
    filter, so a maps to c (its real successor), and b, which exists again,
    is left out."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"a.py": "orig = 1\n" * 5})
    _git(repo, "mv", "a.py", "b.py")
    _commit(repo, {}, "a -> b")
    _git(repo, "mv", "b.py", "c.py")
    _commit(repo, {}, "b -> c")
    _commit(repo, {"b.py": "fresh = 1\n"}, "fresh b")

    assert build_rename_map(repo) == RenameMap({"a.py": "c.py"}, complete=True)


def test_rename_map_keeps_non_ascii_paths_literal(tmp_path: Path) -> None:
    """A non-ASCII path comes back as written, not octal-escaped, in both the
    rename map and the commit file sets, so it matches the file on disk."""
    repo = _init_repo(tmp_path)
    for i in range(2):
        _commit(repo, {"caf\u00e9/x.py": f"x = {i}\n" * 5})
    _git(repo, "mv", "caf\u00e9", "cr\u00e8me")
    _commit(repo, {}, "rename")

    assert build_rename_map(repo).paths == {"caf\u00e9/x.py": "cr\u00e8me/x.py"}
    files = set().union(*parse_commit_file_sets(repo))
    assert Path("cr\u00e8me/x.py") in files
    assert all((repo / f).exists() or f.parts[0] == "caf\u00e9" for f in files)


def test_rename_map_orders_chain_edges_in_time(tmp_path: Path) -> None:
    """A chain follows only renames made in later commits. b -> c frees the
    name b, and a later a -> b refills it: a maps to b, not through to c. The
    reverse order (a -> b, then b -> c) is a real chain and a maps to c."""
    (tmp_path / "freed").mkdir()
    (tmp_path / "chained").mkdir()
    freed = _init_repo(tmp_path / "freed")
    _commit(freed, {"a.py": "a = 1\n" * 5, "b.py": "b = 2\n" * 5})
    _git(freed, "mv", "b.py", "c.py")
    _commit(freed, {}, "b -> c")
    _git(freed, "mv", "a.py", "b.py")
    _commit(freed, {}, "a -> b refills the freed name")
    # b.py exists again, so it keeps its own entry out of the map.
    assert build_rename_map(freed) == RenameMap({"a.py": "b.py"}, complete=True)

    chained = _init_repo(tmp_path / "chained")
    _commit(chained, {"a.py": "a = 1\n" * 5})
    _git(chained, "mv", "a.py", "b.py")
    _commit(chained, {}, "a -> b")
    _git(chained, "mv", "b.py", "c.py")
    _commit(chained, {}, "b -> c")
    assert build_rename_map(chained) == RenameMap(
        {"a.py": "c.py", "b.py": "c.py"}, complete=True)



def test_rename_map_starts_chain_from_first_rename(tmp_path: Path) -> None:
    """a -> b, then an unrelated a is created and later renamed a -> c. The
    original a's history belongs to b, so the chain starts from a's first
    rename, the same rule the rest of the walk follows."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"a.py": "original = 1\n" * 5})
    _git(repo, "mv", "a.py", "b.py")
    _commit(repo, {}, "a -> b")
    _commit(repo, {"a.py": "unrelated = 2\n" * 5}, "a fresh a")
    _git(repo, "mv", "a.py", "c.py")
    _commit(repo, {}, "second a -> c")
    assert build_rename_map(repo) == RenameMap({"a.py": "b.py"}, complete=True)


def _sibling_rename_merge(repo: Path, into: str, other: str) -> None:
    """Branch ``refill`` frees b.py and renames a.py -> b.py; ``main`` renames
    b.py -> c.py. Merge ``other`` into ``into`` and keep both files."""
    _commit(repo, {"a.py": "a = 1\n" * 5, "b.py": "b = 2\n" * 5}, "base")
    _git(repo, "branch", "-M", "main")
    _git(repo, "checkout", "-q", "-b", "refill")
    _git(repo, "rm", "-q", "b.py")
    _commit(repo, {}, "free b")
    _git(repo, "mv", "a.py", "b.py")
    _commit(repo, {}, "a -> b")
    _git(repo, "checkout", "-q", "main")
    _git(repo, "mv", "b.py", "c.py")
    _commit(repo, {}, "b -> c")
    _git(repo, "checkout", "-q", into)
    subprocess.run(["git", "-C", str(repo), "merge", "-q", "--no-edit", other],
                   capture_output=True, text=True)
    for leftover in ("a.py",):
        if (repo / leftover).exists():
            (repo / leftover).unlink()
    _write(repo, "b.py", "a = 1\n" * 5)
    _write(repo, "c.py", "b = 2\n" * 5)
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "--allow-empty", "-m", "merge")


def test_rename_map_does_not_chain_across_sibling_branches(tmp_path: Path) -> None:
    """One branch renames b -> c while a sibling frees b and renames a -> b.
    After the merge both b and c exist; the two renames are unrelated, so a maps
    to b, never through to c. Merged both ways, so either branch can be the one
    git log lists first."""
    for into, other in (("main", "refill"), ("refill", "main")):
        (tmp_path / into).mkdir()
        repo = _init_repo(tmp_path / into)
        _sibling_rename_merge(repo, into, other)
        assert build_rename_map(repo) == RenameMap({"a.py": "b.py"}, complete=True), into

"""Tests for the frozen-harness workflow emitter (lib/ci_workflow.py).

The emitter bakes the discovered toolchain into a GitHub Action. These tests pin
the substitution (version, branch, tool steps), the literal-dollar escaping for
shell vars, the supply-chain pins (no @latest, actions on commit SHAs), the
warn-only infra degrade (a failed fetch/install skips instead of failing), and
that the result is well-formed YAML when a parser is available.
"""
from __future__ import annotations

import re

import pytest

from lib.ci_workflow import emit_ci_workflow, find_path_filtered_workflow, render_ci_workflow

# Every external tool the emitter knows how to install - renders the maximal
# workflow so the supply-chain assertions cover all recipes.
ALL_EXTERNAL_TOOLS = ["scc", "staticcheck", "ts-prune", "knip"]


def test_render_substitutes_version_and_branch():
    out = render_ci_workflow(plugin_version="1.23.0", default_branch="develop")
    assert "ai-native-toolkit v1.23.0" in out
    assert "uses: bjcoombs/ai-native-toolkit@v1.23.0" in out
    assert "branches: [develop]" in out


def test_render_leaves_no_unresolved_placeholders():
    out = render_ci_workflow(plugin_version="1.23.0")
    assert "$plugin_version" not in out
    assert "$tool_steps" not in out
    assert "$default_branch" not in out
    assert "$generated_date" not in out


def test_working_directory_uses_actions_expression_not_shell_var():
    """`working-directory:` only expands `${{ }}` expressions, not shell `${VAR}`.

    Regression: a `working-directory: ${RUNNER_TEMP}/...` cd's into a literal
    `${RUNNER_TEMP}` dir and the step dies with 'No such file or directory'. The
    runner temp dir must be referenced as the GitHub expression `${{ runner.temp }}`.
    """
    out = render_ci_workflow(plugin_version="1.23.0")
    for line in out.splitlines():
        stripped = line.strip()
        if stripped.startswith("working-directory:"):
            assert "${{ runner.temp }}" in stripped, stripped
            assert "${RUNNER_TEMP}" not in stripped, stripped


def test_render_emits_scc_install_step():
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=["lizard", "scc"])
    assert "Install scc" in out
    assert "go install github.com/boyter/scc" in out


def test_render_contains_no_floating_latest():
    """Supply-chain pin: @latest makes the frozen contract non-deterministic.

    A future scc (or other tool) release could shift complexity-stats.json and
    move the regression baseline without any change in the assessed tree.
    """
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=ALL_EXTERNAL_TOOLS)
    assert "@latest" not in out


def test_render_pins_go_and_npm_tools_to_versions():
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=ALL_EXTERNAL_TOOLS)
    for line in out.splitlines():
        if "go install" in line or "npm install" in line:
            assert re.search(r"@v?\d", line), f"unpinned install: {line.strip()}"


def test_render_pins_actions_to_commit_shas():
    """Every third-party action rides a full commit SHA with a version comment.

    Mutable tags (@v4) can be re-pointed by the action's maintainer (or an
    attacker with push access), silently changing what runs in the gate.
    """
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=ALL_EXTERNAL_TOOLS)
    uses_lines = [ln for ln in out.splitlines() if ln.strip().startswith("uses:") or " uses:" in ln]
    assert uses_lines, "expected at least one uses: step"
    for line in uses_lines:
        if "bjcoombs/ai-native-toolkit@" in line:
            # First-party exception: this repo publishes IMMUTABLE releases, so
            # the tag cannot be re-pointed - the guarantee SHA-pinning buys for
            # third-party actions. A tag pin here is what lets Dependabot
            # propose readable version bumps to consumers.
            ref = line.split("@", 1)[1].strip()
            assert re.fullmatch(r"v\d+\.\d+\.\d+", ref), f"not semver-tag-pinned: {line.strip()}"
            continue
        ref = line.split("@", 1)[1].split("#", 1)[0].strip()
        assert re.fullmatch(r"[0-9a-f]{40}", ref), f"not SHA-pinned: {line.strip()}"
        assert re.search(r"#\s*v\d", line), f"missing version comment: {line.strip()}"


def test_checkout_does_not_persist_credentials():
    """Nothing downstream pushes, so the checked-out token must not linger."""
    out = render_ci_workflow(plugin_version="1.23.0")
    assert "persist-credentials: false" in out


def test_render_delegates_to_the_action_not_a_clone():
    """The gate logic ships as a composite action; the emitted workflow is a
    thin pin. No `git clone` of the toolkit may remain - a clone inside a run:
    step is invisible to Dependabot/Renovate, which was the defect this action
    exists to fix. Infra degrade now lives inside the action itself."""
    out = render_ci_workflow(plugin_version="1.23.0")
    assert "git clone" not in out
    assert "uses: bjcoombs/ai-native-toolkit@v1.23.0" in out
    assert "config: .assess/config.toml" in out
    # The Dependabot enablement snippet ships in the header comment.
    assert "package-ecosystem: github-actions" in out


def test_tool_install_failures_do_not_red_the_check():
    """Each install step degrades to reduced coverage, not a failed check."""
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=ALL_EXTERNAL_TOOLS)
    installs = out.count("go install") + out.count("npm install")
    assert installs == len(ALL_EXTERNAL_TOOLS)
    # One continue-on-error per tool install; rg/uv degrade now lives inside
    # the composite action, not the emitted workflow.
    assert out.count("continue-on-error: true") == installs


def test_render_skips_python_dep_tools():
    """Python deps (lizard, grimp) ride uv - they never get an OS install step."""
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=["lizard", "grimp"])
    assert "Install scc" not in out
    assert "without an install recipe" not in out


def test_render_comments_unknown_tools():
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=["weirdtool"])
    assert "without an install recipe: weirdtool" in out


def test_render_dedupes_tools():
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=["scc", "scc"])
    assert out.count("Install scc") == 1


def test_render_is_valid_yaml():
    yaml = pytest.importorskip("yaml")
    out = render_ci_workflow(plugin_version="1.23.0", discovered_tools=ALL_EXTERNAL_TOOLS)
    doc = yaml.safe_load(out)
    assert doc["name"] == "Assess Gate"
    # PyYAML parses the unquoted `on:` key as boolean True (the YAML 1.1 norm).
    on = doc.get("on", doc.get(True))
    assert "pull_request" in on
    assert "assess" in doc["jobs"]


def test_emit_writes_workflow_file(tmp_path):
    path = emit_ci_workflow(tmp_path, ["scc"], "1.23.0", default_branch="main")
    assert path == tmp_path / ".github" / "workflows" / "assess-gate.yml"
    assert path.is_file()
    assert "Assess Gate" in path.read_text()


def test_emit_creates_nested_dirs(tmp_path):
    """No pre-existing .github/ - the emitter creates the full path."""
    path = emit_ci_workflow(tmp_path, [], "1.23.0")
    assert path.is_file()


def _pull_request(out: str) -> dict:
    yaml = pytest.importorskip("yaml")
    doc = yaml.safe_load(out)
    on = doc.get("on", doc.get(True))  # PyYAML reads a bare `on:` key as True
    return on["pull_request"]


def test_render_paths_ignore_flag_yields_valid_yaml():
    out = render_ci_workflow(plugin_version="1.23.0", paths_ignore=["**/*.md"])
    assert _pull_request(out) == {"branches": ["main"], "paths-ignore": ["**/*.md"]}


def test_render_paths_flag_repeatable_keeps_order():
    out = render_ci_workflow(plugin_version="1.23.0", paths=["src/**", "lib/**", "it's/**"])
    assert _pull_request(out) == {"branches": ["main"], "paths": ["src/**", "lib/**", "it's/**"]}


def test_render_rejects_paths_with_paths_ignore():
    with pytest.raises(ValueError):
        render_ci_workflow(plugin_version="1.23.0", paths=["src/**"], paths_ignore=["**/*.md"])


def test_render_without_path_filters_is_unchanged():
    out = render_ci_workflow(plugin_version="1.23.0")
    assert "paths" not in out
    assert "    branches: [main]\n\npermissions:" in out


def _workflows(tmp_path, files: dict[str, str]):
    wf = tmp_path / ".github" / "workflows"
    wf.mkdir(parents=True)
    for name, body in files.items():
        (wf / name).write_text(body)
    return wf


@pytest.mark.parametrize(
    "body",
    [
        "on:\n  pull_request:\n    paths:\n      - src/**\n",
        "on:\n  push:\n  pull_request_target:\n    branches: [main]\n    # docs\n\n    paths-ignore: ['docs/**']\n",
        "on:\n  pull_request: {branches: [main], paths: ['src/**']}\n",
        "jobs:\n  t:\n    steps:\n      - uses: dorny/paths-filter@v3\n",
    ],
)
def test_path_filter_default_applied_detects_filtered_workflow(tmp_path, body):
    wf = _workflows(tmp_path, {"a-plain.yml": "on: push\n", "ci.yaml": body})
    assert find_path_filtered_workflow(tmp_path) == wf / "ci.yaml"


def test_path_filter_default_not_applied_without_filtered_workflow(tmp_path):
    assert find_path_filtered_workflow(tmp_path) is None  # no .github/workflows at all
    _workflows(
        tmp_path,
        {
            "ci.yml": "on:\n  pull_request:\njobs:\n  t:\n    steps:\n      - uses: actions/cache@v4\n        with:\n          path: ~/.cache\n",
            # The gate's own file is excluded, so a regenerated gate never detects its own default.
            "assess-gate.yml": "on:\n  pull_request:\n    paths-ignore:\n      - '**/*.md'\n",
            "notes.txt": "paths: [src]\n",
            # A paths: filter on push only (a publish trigger) says nothing about PR checks.
            "publish.yml": "on:\n  push:\n    paths: [.claude-plugin/plugin.json]\n  pull_request:\n    branches: [main]\njobs:\n  t:\n    steps:\n      - uses: actions/upload-artifact@v4\n        with:\n          paths: dist\n",
        },
    )
    assert find_path_filtered_workflow(tmp_path) is None

"""Unit tests for the pure logic inside complexity-treemap.py.

The script imports lizard/matplotlib/numpy at module load (it's a CLI wrapper),
so those are stubbed in sys.modules before import. We only exercise functions
that don't touch the real heavy deps: the build-artifact filter, the plugin
version stamp, and the stats-sidecar enrichment (field naming + hotspot rank).
"""
from __future__ import annotations

import importlib.util
import json
import sys
import types
from pathlib import Path

import pytest

_SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "complexity-treemap.py"


class _StubNumpy(types.ModuleType):
    """Minimal numpy: only percentile, with numpy's default linear interp."""

    @staticmethod
    def percentile(values, q):
        s = sorted(values)
        if not s:
            return 0.0
        k = (len(s) - 1) * q / 100.0
        f = int(k)
        c = min(f + 1, len(s) - 1)
        return float(s[f] + (s[c] - s[f]) * (k - f))


def _load_treemap():
    """Import complexity-treemap.py with heavy deps stubbed out."""
    for name in ("lizard", "matplotlib", "matplotlib.pyplot", "squarify"):
        sys.modules.setdefault(name, types.ModuleType(name))
    sys.modules.setdefault("numpy", _StubNumpy("numpy"))
    # complexity-treemap does `import matplotlib.pyplot as plt`
    sys.modules["matplotlib"].pyplot = sys.modules["matplotlib.pyplot"]
    spec = importlib.util.spec_from_file_location("complexity_treemap", _SCRIPT)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


@pytest.fixture(scope="module")
def treemap():
    return _load_treemap()


@pytest.fixture(scope="module")
def render_lib(treemap):
    """The shared treemap_render module. Depends on `treemap` so the scripts
    dir is on sys.path and numpy is stubbed before import."""
    import importlib

    return importlib.import_module("lib.treemap_render")


@pytest.mark.parametrize("name", [
    "canvaskit.js",
    "canvaskit/chromium/canvaskit.js",  # nested, basename still matches
    "skwasm.js",
    "skwasm_heavy.js",
    "main.dart.js",                     # pre-existing Flutter artifact
])
def test_flutter_runtime_bundles_are_filtered(treemap, name):
    assert treemap._is_build_artifact(Path(name)) is True


@pytest.mark.parametrize("name", ["app.js", "widget.dart", "canvaskit_helper.dart"])
def test_real_source_is_not_filtered(treemap, name):
    assert treemap._is_build_artifact(Path(name)) is False


def test_plugin_version_is_stamped_from_plugin_json(treemap):
    # Resolves the real .claude-plugin/plugin.json three dirs up; must be a real
    # version string, never the "unknown" fallback.
    version = treemap._read_plugin_version()
    assert version != "unknown"
    assert version[0].isdigit()


def test_write_stats_uses_commits_field_and_balanced_rank(treemap, tmp_path):
    """The per-file churn count is emitted as `commits` (what consumers read),
    and the balanced composite ranks a moderately-complex active file above a
    very-complex frozen one (issue #47, observation 2 + 5)."""
    root = tmp_path
    frozen_complex = root / "frozen.go"   # high ccn, barely touched
    active_moderate = root / "active.go"  # moderate ccn, churning
    files = [
        (frozen_complex, 800, 1396.0, "lizard"),
        (active_moderate, 300, 140.0, "lizard"),
    ]
    aux_data = {frozen_complex: 1, active_moderate: 45}
    out = root / "stats.json"
    # The composite now includes a sqrt(est_tokens) size axis. Hold size equal
    # so this test isolates the churn axis it is about (issue #47); otherwise
    # frozen.go's larger size would confound the ranking.
    tokens = {frozen_complex: 1000, active_moderate: 1000}
    treemap.write_stats(files, aux_data, "commits (last 12mo)", root, out,
                        tokens_by_path=tokens)

    stats = json.loads(out.read_text())
    assert "plugin_version" in stats
    hotspots = stats["top_hotspots"]
    # Balanced composite: the active moderate-complexity file leads.
    assert hotspots[0]["path"] == "active.go"
    # Field is `commits`, not the legacy `churn`.
    for h in hotspots:
        assert "commits" in h
        assert "churn" not in h
    by_path = {h["path"]: h for h in hotspots}
    assert by_path["active.go"]["commits"] == 45
    assert by_path["frozen.go"]["commits"] == 1


def test_write_stats_stamps_schema_and_tool_versions(treemap, tmp_path, monkeypatch):
    """The sidecar stamps the stats schema version and the complexity backend
    versions so a later run can detect a schema or tool change and void a
    non-comparable diff. scc_version is present only when scc scored files."""
    monkeypatch.setattr(treemap, "_lizard_version", lambda: "1.23.0")
    monkeypatch.setattr(treemap, "_scc_version", lambda: "3.7.0")
    root = tmp_path
    lz = root / "a.go"
    sc = root / "b.rb"
    out = root / "stats.json"

    # lizard-only: no scc_version key.
    treemap.write_stats([(lz, 100, 5.0, "lizard")], None, None, root, out)
    stats = json.loads(out.read_text())
    assert stats["schema_version"] == treemap.STATS_SCHEMA_VERSION
    assert stats["lizard_version"] == "1.23.0"
    assert "scc_version" not in stats

    # A file scored by scc adds scc_version.
    treemap.write_stats(
        [(lz, 100, 5.0, "lizard"), (sc, 80, 4.0, "scc")], None, None, root, out
    )
    stats = json.loads(out.read_text())
    assert stats["lizard_version"] == "1.23.0"
    assert stats["scc_version"] == "3.7.0"


def test_tool_versions_omits_scc_when_not_scored(treemap, monkeypatch):
    """_tool_versions always carries lizard; scc appears only when a file was
    scored by scc AND scc is resolvable."""
    monkeypatch.setattr(treemap, "_lizard_version", lambda: "1.23.0")
    monkeypatch.setattr(treemap, "_scc_version", lambda: "3.7.0")
    assert treemap._tool_versions([(Path("a.go"), 1, 1.0, "lizard")]) == {
        "lizard": "1.23.0"
    }
    assert treemap._tool_versions([(Path("b.rb"), 1, 1.0, "scc")]) == {
        "lizard": "1.23.0", "scc": "3.7.0"
    }


def test_tool_versions_drops_scc_when_binary_absent(treemap, monkeypatch):
    """When scc scored files but the binary can't report a version, scc is
    omitted rather than stamped as a false 'unknown'."""
    monkeypatch.setattr(treemap, "_lizard_version", lambda: "1.23.0")
    monkeypatch.setattr(treemap, "_scc_version", lambda: None)
    assert treemap._tool_versions([(Path("b.rb"), 1, 1.0, "scc")]) == {
        "lizard": "1.23.0"
    }


def test_write_stats_records_churn_degenerate_flag(treemap, tmp_path):
    """Issue #172: the stats sidecar carries ``churn_degenerate`` so the report
    and a reader know the saturation axis / commits column is inactive. Default
    is False; passing the flag records True."""
    root = tmp_path
    f = root / "a.go"
    out = root / "stats.json"
    treemap.write_stats([(f, 100, 5.0, "lizard")], {f: 1}, "commits (all-time)",
                        root, out)
    assert json.loads(out.read_text())["churn_degenerate"] is False

    treemap.write_stats([(f, 100, 5.0, "lizard")], {f: 1}, "commits (all-time)",
                        root, out, churn_degenerate=True)
    assert json.loads(out.read_text())["churn_degenerate"] is True


def test_write_stats_commits_none_without_git(treemap, tmp_path):
    """No churn data (no git) -> commits is None, distinct from a real 0."""
    root = tmp_path
    f = root / "a.go"
    out = root / "stats.json"
    treemap.write_stats([(f, 100, 5.0, "lizard")], None, None, root, out)
    stats = json.loads(out.read_text())
    assert stats["top_hotspots"][0]["commits"] is None


def test_write_stats_separates_aggregate_from_per_function_ccn(treemap, tmp_path):
    """Issue #58: the file-level aggregate ccn (sum of per-function complexity)
    must be labelled as an aggregate and never conflated with the per-function
    value a linter threshold gates. A file summing to ccn 136 whose worst
    single function is only 13 is NOT a per-function violation."""
    root = tmp_path
    f = root / "service_modules.go"   # the issue's actual offender shape
    out = root / "stats.json"
    # 13 functions whose complexities sum to 136 (the reported aggregate),
    # worst single function = 13 (under a cyclop:15 threshold).
    fn_ccns = [13.0, 13.0, 12.0, 12.0, 11.0, 11.0, 10.0, 10.0,
               9.0, 9.0, 8.0, 8.0, 10.0]
    assert sum(fn_ccns) == 136.0
    treemap.write_stats(
        [(f, 800, 136.0, "lizard")], {f: 3}, "commits (last 12mo)", root, out,
        fn_ccn_by_path={f: fn_ccns},
    )
    stats = json.loads(out.read_text())

    # The aggregate block self-labels and the per-function block is separate.
    assert stats["ccn"]["basis"] == "file-aggregate"
    assert stats["ccn"]["max"] == 136.0
    assert stats["fn_ccn"]["basis"] == "per-function"
    assert stats["fn_ccn"]["function_count"] == 13
    assert stats["fn_ccn"]["max"] == 13.0   # worst function, not the sum

    row = stats["top_complex"][0]
    assert row["ccn"] == 136.0              # aggregate preserved for the hue
    assert row["ccn_basis"] == "file-aggregate"
    assert row["max_fn_ccn"] == 13.0        # the per-function truth for Layer 3


def test_write_stats_scc_file_has_null_max_fn_ccn(treemap, tmp_path):
    """scc reports file-level complexity with no function breakdown, so a
    scc-scored file carries max_fn_ccn=null - the report must not invent a
    per-function value it never measured."""
    root = tmp_path
    f = root / "report.sql"
    out = root / "stats.json"
    # No fn_ccn_by_path entry for this path -> scc-style, per-function unknown.
    treemap.write_stats([(f, 400, 50.0, "scc")], None, None, root, out,
                        fn_ccn_by_path={})
    stats = json.loads(out.read_text())
    assert stats["top_complex"][0]["max_fn_ccn"] is None
    assert stats["fn_ccn"]["function_count"] == 0


def test_hotspot_rank_favours_per_function_offender(treemap, tmp_path):
    """Issue #115: for a class-per-file language the hotspot composite must rank
    on the worst single function, not the file aggregate, so a broad coordinator
    class can't bury a genuinely complex single method.

    Real shape from the first Java/JVM run: a coordinator at aggregate ccn 107
    whose worst method is only 14 (not a violation) out-ranked a DAO at ccn 28
    that is one complex method. With equal churn the DAO must now lead."""
    root = tmp_path
    coordinator = root / "Coordinator.java"  # broad: ccn 107, worst method 14
    dao = root / "Dao.java"                   # one genuinely complex method
    files = [
        (coordinator, 600, 107.0, "lizard"),
        (dao, 200, 28.0, "lizard"),
    ]
    # Many small methods summing to 107, worst single = 14.
    coordinator_fns = [14.0, 13.0, 12.0, 11.0, 10.0, 10.0, 9.0,
                       9.0, 8.0, 6.0, 5.0]
    assert sum(coordinator_fns) == 107.0
    dao_fns = [28.0]  # the single complex method is the whole file's ccn
    aux_data = {coordinator: 5, dao: 5}  # equal churn isolates the ccn re-weight
    out = root / "stats.json"
    # Equal est_tokens too, so the new sqrt(est_tokens) size axis doesn't
    # confound the per-function re-weight this test is about (issue #115).
    tokens = {coordinator: 1000, dao: 1000}
    treemap.write_stats(
        files, aux_data, "commits (last 12mo)", root, out,
        fn_ccn_by_path={coordinator: coordinator_fns, dao: dao_fns},
        tokens_by_path=tokens,
    )
    stats = json.loads(out.read_text())
    hotspots = stats["top_hotspots"]

    # The true per-function offender ranks at or above the coordinator class.
    assert hotspots[0]["path"] == "Dao.java"
    # The aggregate is still reported faithfully - only the ranking changed.
    by_path = {h["path"]: h for h in hotspots}
    assert by_path["Coordinator.java"]["ccn"] == 107.0
    assert by_path["Coordinator.java"]["max_fn_ccn"] == 14.0
    # The complexity-only rank (treemap hue) stays aggregate-driven.
    assert stats["top_complex"][0]["path"] == "Coordinator.java"


def test_hotspot_rank_unchanged_for_single_function_per_file(treemap, tmp_path):
    """Must-not-regress guard (issue #115): for single-function-per-file
    languages (Python/Go) the aggregate is the worst function, so the
    per-function re-weight is a no-op and the existing ranking is preserved -
    the more-complex-and-equally-churned file still leads."""
    root = tmp_path
    complex_go = root / "complex.go"   # one big function, ccn 40
    simple_go = root / "simple.go"     # one small function, ccn 8
    files = [
        (complex_go, 300, 40.0, "lizard"),
        (simple_go, 120, 8.0, "lizard"),
    ]
    # aggregate == worst function: the per-function weight collapses to aggregate.
    aux_data = {complex_go: 10, simple_go: 10}
    out = root / "stats.json"
    treemap.write_stats(
        files, aux_data, "commits (last 12mo)", root, out,
        fn_ccn_by_path={complex_go: [40.0], simple_go: [8.0]},
    )
    stats = json.loads(out.read_text())
    hotspots = stats["top_hotspots"]

    # Ranking is unchanged: the genuinely complex file still leads.
    assert hotspots[0]["path"] == "complex.go"
    # And it matches the aggregate-only rank - no per-function divergence here.
    assert stats["top_complex"][0]["path"] == "complex.go"


def test_effective_ccn_collapses_to_aggregate_without_per_function_data(treemap):
    """`_effective_ccn` returns the raw aggregate when there is no per-function
    signal (scc files: max_fn_ccn is None), and when the worst function already
    equals the aggregate (single-function file) - the two no-regression paths."""
    assert treemap._effective_ccn(50.0, None) == 50.0   # scc: no breakdown
    assert abs(treemap._effective_ccn(40.0, 40.0) - 40.0) < 1e-9  # single fn
    # A coordinator (aggregate >> worst fn) is pulled below its aggregate but
    # never below the worst function itself.
    eff = treemap._effective_ccn(107.0, 14.0)
    assert 14.0 < eff < 107.0


def test_assess_dir_is_self_excluded_by_default(treemap):
    """A prior run's run-context.json must not be scored on the next run -
    the script's own output directory is in EXCLUDE_DIRS. Otherwise re-runs
    pollute the heatmap with their own past output (issue #50 bonus)."""
    assert ".assess" in treemap.EXCLUDE_DIRS


def test_is_user_excluded_matches_dir_name(treemap):
    """A plain dir name in the user excludes filters every file under it,
    at any depth."""
    extra_dirs = {"regulatory-raw"}
    assert treemap._is_user_excluded(
        Path("regulatory-raw/2024-Q1/data.csv"), extra_dirs, []
    ) is True
    assert treemap._is_user_excluded(
        Path("src/data/sub/regulatory-raw/file.txt"), extra_dirs, []
    ) is True
    # A different directory must not be filtered.
    assert treemap._is_user_excluded(
        Path("src/data/file.txt"), extra_dirs, []
    ) is False


def test_is_user_excluded_matches_glob_pattern(treemap):
    """A glob pattern matches by basename, not by full path."""
    extra_patterns = ["*.csv", "seed-*.json"]
    assert treemap._is_user_excluded(
        Path("data/reference.csv"), set(), extra_patterns
    ) is True
    assert treemap._is_user_excluded(
        Path("fixtures/seed-orders.json"), set(), extra_patterns
    ) is True
    # A glob that doesn't match the basename must not filter.
    assert treemap._is_user_excluded(
        Path("src/main.py"), set(), extra_patterns
    ) is False
    # No globs at all => no excludes.
    assert treemap._is_user_excluded(Path("anything.txt"), set(), []) is False


def test_is_user_excluded_dir_and_pattern_combine(treemap):
    """Dir excludes and pattern excludes are independent - either match
    is enough to exclude. Mirrors how the built-in defaults already work."""
    extra_dirs = {"vetted-context"}
    extra_patterns = ["*.parquet"]
    # Dir hit
    assert treemap._is_user_excluded(
        Path("vetted-context/note.md"), extra_dirs, extra_patterns
    ) is True
    # Pattern hit
    assert treemap._is_user_excluded(
        Path("data/silver/events.parquet"), extra_dirs, extra_patterns
    ) is True


def test_cli_exclude_classifies_glob_vs_dir(treemap, monkeypatch, tmp_path):
    """The CLI's `--exclude X` argument routes globby patterns to
    extra_patterns and plain strings to extra_dirs, transparently to the
    caller. Verified by capturing what collect() receives."""
    captured = {}

    def fake_collect(*args, **kwargs):
        captured["extra_dirs"] = kwargs.get("extra_exclude_dirs")
        captured["extra_patterns"] = kwargs.get("extra_exclude_patterns")
        # Return an empty result so main bails out early but cleanly.
        return [], "complexity", None, None, {}

    monkeypatch.setattr(treemap, "collect", fake_collect)
    monkeypatch.setattr(
        sys, "argv",
        ["complexity-treemap.py", str(tmp_path),
         "--exclude", "regulatory-raw",
         "--exclude", "*.csv",
         "--exclude", "seed-data",
         "--exclude", "data-*.json"],
    )
    rc = treemap.main()
    assert rc == 1  # "no scoreable files" - expected with empty collect()
    assert captured["extra_dirs"] == {"regulatory-raw", "seed-data"}
    assert sorted(captured["extra_patterns"]) == ["*.csv", "data-*.json"]


def test_argparse_help_builds_on_current_python(treemap, monkeypatch, capsys):
    """Regression for the Python 3.14 crash: argparse now eagerly validates help
    strings and rejects a bare ``%`` (it must be escaped ``%%``). Building the
    parser via ``--help`` must raise SystemExit (help printed), never ValueError
    ('badly formed help string'). Runs under whatever Python the suite is on, so
    a 3.14 CI job catches a reintroduced bare ``%`` in any help text."""
    monkeypatch.setattr(sys, "argv", ["complexity-treemap.py", "--help"])
    with pytest.raises(SystemExit) as exc:
        treemap.main()
    assert exc.value.code == 0
    assert "--test-pressure" in capsys.readouterr().out


def test_cli_exclude_merges_with_config_toml(treemap, monkeypatch, tmp_path):
    """`.assess/config.toml` and `--exclude` both layer onto the defaults;
    neither replaces the other. Config-supplied dirs join CLI dirs, and
    glob patterns merge across both sources."""
    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        'exclude_dirs = ["vetted-context", "regulatory-raw"]\n'
        'exclude_patterns = ["*.parquet"]\n',
        encoding="utf-8",
    )
    captured = {}

    def fake_collect(*args, **kwargs):
        captured["extra_dirs"] = kwargs.get("extra_exclude_dirs")
        captured["extra_patterns"] = kwargs.get("extra_exclude_patterns")
        return [], "complexity", None, None, {}

    monkeypatch.setattr(treemap, "collect", fake_collect)
    monkeypatch.setattr(
        sys, "argv",
        ["complexity-treemap.py", str(tmp_path),
         "--exclude", "seed-data",
         "--exclude", "*.csv"],
    )
    rc = treemap.main()
    assert rc == 1  # no scoreable files
    assert captured["extra_dirs"] == {
        "vetted-context", "regulatory-raw", "seed-data",
    }
    assert sorted(captured["extra_patterns"]) == ["*.csv", "*.parquet"]


def test_config_loader_missing_file_is_empty(tmp_path):
    """A repo with no .assess/config.toml degrades silently - no warning,
    no error, just an empty config (the common case)."""
    from lib.assess_config import load_excludes

    dirs, pats = load_excludes(tmp_path)
    assert dirs == set()
    assert pats == []


def test_config_loader_malformed_toml_returns_empty(tmp_path, capsys):
    """A broken TOML file must never block the assessment - the loader
    returns empty excludes and prints a one-line warning."""
    from lib.assess_config import load_excludes

    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        "this is not valid = = toml\n", encoding="utf-8",
    )
    dirs, pats = load_excludes(tmp_path)
    assert dirs == set()
    assert pats == []
    captured = capsys.readouterr()
    assert "could not read" in captured.err


def test_config_loader_drops_non_string_entries(tmp_path):
    """A schema violation in one entry doesn't poison the rest - e.g.
    `exclude_dirs = ["regulatory-raw", 42]` keeps the string and drops
    the integer."""
    from lib.assess_config import load_excludes

    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        'exclude_dirs = ["regulatory-raw", 42, "vetted-context"]\n'
        'exclude_patterns = ["*.csv", true]\n',
        encoding="utf-8",
    )
    dirs, pats = load_excludes(tmp_path)
    assert dirs == {"regulatory-raw", "vetted-context"}
    assert pats == ["*.csv"]


def test_config_loader_no_legacy_section_needed(tmp_path):
    """The schema is top-level - no `[treemap]` or `[exclude]` wrapper.
    The file is already namespaced by living under `.assess/config.toml`."""
    from lib.assess_config import load_excludes

    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        'exclude_dirs = ["regulatory-raw"]\n'
        'exclude_patterns = ["*.csv"]\n',
        encoding="utf-8",
    )
    dirs, pats = load_excludes(tmp_path)
    assert dirs == {"regulatory-raw"}
    assert pats == ["*.csv"]


def test_config_loader_scalar_string_degrades_to_empty(tmp_path):
    """`exclude_dirs = "regulatory-raw"` (string, not list) used to iterate
    character-by-character, silently producing single-char "dir names"
    that match unexpectedly. The loader now rejects non-list values."""
    from lib.assess_config import load_excludes

    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        'exclude_dirs = "regulatory-raw"\n',
        encoding="utf-8",
    )
    dirs, pats = load_excludes(tmp_path)
    assert dirs == set()
    assert pats == []


def test_config_loader_scalar_int_does_not_raise(tmp_path):
    """`exclude_dirs = 5` is valid TOML but the wrong type. It used to
    raise `TypeError` (int not iterable), propagate through `load_excludes`,
    and abort the whole assessment - the opposite of "degrade silently"."""
    from lib.assess_config import load_excludes

    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        'exclude_dirs = 5\nexclude_patterns = true\n',
        encoding="utf-8",
    )
    # The test passes if this call returns without raising.
    dirs, pats = load_excludes(tmp_path)
    assert dirs == set()
    assert pats == []


# ── survivor-density overlay (task 5) ─────────────────────────────────────────


@pytest.mark.parametrize("density,expected", [
    (None, ""),       # unknown -> no overlay
    (0.0, ""),
    (0.30, ""),       # boundary: must exceed, not equal
    (0.31, "diag"),
    (0.50, "diag"),   # boundary: cross only above 0.5
    (0.51, "cross"),
    (0.95, "cross"),
])
def test_hatch_for_density_thresholds(treemap, density, expected):
    assert treemap._hatch_for_density(density) == expected


def test_survivor_overrides_applies_hatch_per_file(treemap):
    p1, p2, p3 = Path("/repo/a.py"), Path("/repo/b.py"), Path("/repo/c.py")
    files = [(p1, 100, 5.0, "lizard"),
             (p2, 50, 3.0, "lizard"),
             (p3, 10, 1.0, "lizard")]
    density = {p1: 0.6, p2: 0.4, p3: 0.1}
    overrides = treemap._survivor_overrides(files, density)
    assert overrides[p1] == {"hatch": "cross"}
    assert overrides[p2] == {"hatch": "diag"}
    assert p3 not in overrides  # below threshold -> no overlay


def test_survivor_overrides_empty_data_is_silent(treemap):
    """Absent or empty survivor data renders no overlay, no error."""
    files = [(Path("/repo/a.py"), 100, 5.0, "lizard")]
    assert treemap._survivor_overrides(files, None) == {}
    assert treemap._survivor_overrides(files, {}) == {}


def test_write_svg_emits_hatch_overlay_and_legend(render_lib, tmp_path):
    """A hatched node gets a pattern-filled overlay, the <defs> patterns are
    emitted, and the legend explains what the hatch means."""
    node = render_lib.Node(name="a.py", rel_path="a.py", loc=100,
                           metric=5.0, color=(0.8, 0.2, 0.1, 1.0),
                           is_file=True, hatch="diag")
    rects = [(0.0, 0.0, 100.0, 100.0, node)]
    out = tmp_path / "hatched.svg"
    render_lib.write_svg(rects, Path("/repo"), 1600.0, 1000.0, out,
                         False, "ccn", show_survivor_legend=True)
    svg = out.read_text()
    # pattern definition + overlay reference
    assert 'id="survivor-diag"' in svg
    assert 'fill="url(#survivor-diag)"' in svg
    # legend explains the survivor meaning with both thresholds
    assert "survivor density" in svg.lower()
    assert "30%" in svg
    assert "50%" in svg
    # canvas extended by the legend band (1000 + 84)
    assert 'height="1084"' in svg


def test_write_svg_emits_a11y_title_and_desc(render_lib, tmp_path):
    """Task 17: the root <svg> is role="img" with a <title>/<desc> pair as its
    first children, so a screen reader announces the image and how it encodes."""
    node = render_lib.Node(name="a.py", rel_path="a.py", loc=100,
                           metric=5.0, color=(0.8, 0.2, 0.1, 1.0),
                           is_file=True)
    rects = [(0.0, 0.0, 100.0, 100.0, node)]
    out = tmp_path / "a11y.svg"
    render_lib.write_svg(rects, Path("/repo"), 1600.0, 1000.0, out, False, "ccn")
    svg = out.read_text()
    assert 'role="img"' in svg
    assert "<title>Complexity Hotspot Heatmap</title>" in svg
    assert "hue indicates cyclomatic complexity" in svg
    assert "saturation indicates git churn" in svg
    # <title>/<desc> are the root's first children (before the <style> block).
    assert svg.index("<title>") < svg.index("<style>")
    assert svg.index("<desc>") < svg.index("<style>")


def test_write_svg_no_overlay_without_survivor_data(render_lib, tmp_path):
    """No hatch and no legend flag -> original full-canvas treemap, untouched:
    no survivor patterns, no <defs>, no extra legend band."""
    node = render_lib.Node(name="a.py", rel_path="a.py", loc=100,
                           metric=5.0, color=(0.8, 0.2, 0.1, 1.0),
                           is_file=True)
    rects = [(0.0, 0.0, 100.0, 100.0, node)]
    out = tmp_path / "plain.svg"
    render_lib.write_svg(rects, Path("/repo"), 1600.0, 1000.0, out,
                         False, "ccn")
    svg = out.read_text()
    assert "survivor-" not in svg
    assert "<defs>" not in svg
    assert 'height="1000"' in svg


def test_load_survivor_density_from_per_file(treemap, tmp_path):
    """Per-file density is survived/total; entries without a total (mutmut)
    are skipped, and paths resolve against the repo root."""
    ctx = {"test_pressure": {"per_file": [
        {"file": "src/a.py", "killed": 2, "survived": 8, "total": 10},
        {"file": "src/b.py", "killed": 9, "survived": 1, "total": 10},
        {"file": "src/c.py", "killed": None, "survived": 4, "total": None},
    ]}}
    j = tmp_path / "run-context.json"
    j.write_text(json.dumps(ctx), encoding="utf-8")
    density = treemap.load_survivor_density(j, tmp_path)
    assert density[(tmp_path / "src/a.py").resolve()] == 0.8
    assert density[(tmp_path / "src/b.py").resolve()] == 0.1
    assert (tmp_path / "src/c.py").resolve() not in density  # no total


def test_mutmut_junitxml_drives_hatch_overlay(treemap, tmp_path, fixtures_dir):
    """End to end: a real mutmut junitxml parse -> run-context per_file ->
    load_survivor_density -> hatch overrides. Before the junitxml fix the mutmut
    path carried no totals, so this overlay could never render on a Python repo."""
    from lib.test_pressure import _parse_mutmut_junitxml

    per_file = _parse_mutmut_junitxml(fixtures_dir / "mutmut-junitxml.xml")
    ctx = {"test_pressure": {"per_file": per_file}}
    j = tmp_path / "run-context.json"
    j.write_text(json.dumps(ctx), encoding="utf-8")

    density = treemap.load_survivor_density(j, tmp_path)
    calc = (tmp_path / "src/calc.py").resolve()
    util = (tmp_path / "src/util.py").resolve()
    assert density[calc] == 2 / 3      # real density, not skipped
    assert density[util] == 0.0         # all killed -> real 0 density (has a total)

    files = [(calc, 100, 5.0, "lizard"), (util, 50, 3.0, "lizard")]
    overrides = treemap._survivor_overrides(files, density)
    assert overrides[calc] == {"hatch": "cross"}  # 0.67 > 0.5
    assert util not in overrides                   # 0.0 below hatch threshold


def test_load_survivor_density_absent_block_is_empty(treemap, tmp_path):
    j = tmp_path / "run-context.json"
    j.write_text(json.dumps({"doc_graph": {}}), encoding="utf-8")
    assert treemap.load_survivor_density(j, tmp_path) == {}


def test_load_survivor_density_missing_file_is_empty(treemap, tmp_path):
    assert treemap.load_survivor_density(tmp_path / "nope.json", tmp_path) == {}


# --- Estimated tokens as the keyhole size unit (PRD 2026-06) -----------------

def test_est_token_count_is_chars_over_four(treemap, tmp_path):
    """est_tokens = ceil(len(text)/4) for a real on-disk file."""
    f = tmp_path / "a.py"
    f.write_text("x" * 800, encoding="utf-8")  # 800 chars -> 200 tokens
    assert treemap.est_token_count(f, 0) == 200


def test_est_token_count_falls_back_to_loc_when_unreadable(treemap, tmp_path):
    """An unreadable/absent file estimates from loc - a conservative floor that
    can't inflate a benign file's rank."""
    missing = tmp_path / "gone.py"
    assert treemap.est_token_count(missing, 137) == 137


def test_write_stats_emits_est_tokens_per_row_and_uses_real_text(treemap, tmp_path):
    """Each row carries est_tokens; for on-disk files it is the char-based
    estimate, not the loc (a dense file reads higher than its line count)."""
    root = tmp_path
    dense = root / "dense.py"
    dense.write_text("y" * 4000, encoding="utf-8")  # 1000 est tokens
    out = root / "stats.json"
    treemap.write_stats([(dense, 50, 5.0, "lizard")], None, None, root, out)
    stats = json.loads(out.read_text())
    row = stats["top_hotspots"][0]
    assert row["est_tokens"] == 1000          # chars/4, not the 50 loc
    assert row["loc"] == 50                    # loc preserved alongside
    assert stats["est_tokens"]["total"] == 1000


def test_hotspot_score_includes_token_factor(treemap, tmp_path):
    """With ccn and churn held equal, the larger file (more estimated tokens)
    ranks first - the size axis is live in the composite."""
    root = tmp_path
    big = root / "big.go"
    small = root / "small.go"
    files = [(big, 200, 30.0, "lizard"), (small, 200, 30.0, "lizard")]
    aux_data = {big: 10, small: 10}
    tokens = {big: 40000, small: 4000}  # same ccn + churn, 10x size
    out = root / "stats.json"
    treemap.write_stats(files, aux_data, "commits (last 12mo)", root, out,
                        tokens_by_path=tokens)
    hotspots = json.loads(out.read_text())["top_hotspots"]
    assert hotspots[0]["path"] == "big.go"


def test_big_but_simple_stable_file_does_not_top_on_size_alone(treemap, tmp_path):
    """PRD validation guard: a large-but-simple-stable file (a long config or
    data table - low ccn, no churn, huge size) must NOT top the hotspot list.
    The sqrt bounding keeps its single big axis from dominating a genuine
    complex+churning hotspot."""
    root = tmp_path
    data_table = root / "data.json"      # huge, trivial, frozen
    hotspot = root / "engine.go"         # complex AND churning, modest size
    files = [(data_table, 5000, 1.0, "lizard"), (hotspot, 300, 100.0, "lizard")]
    aux_data = {data_table: 0, hotspot: 30}
    tokens = {data_table: 200000, hotspot: 5000}  # data table 40x bigger
    out = root / "stats.json"
    treemap.write_stats(files, aux_data, "commits (last 12mo)", root, out,
                        tokens_by_path=tokens)
    hotspots = json.loads(out.read_text())["top_hotspots"]
    assert hotspots[0]["path"] == "engine.go"  # complexity+churn beats raw size


def test_keyhole_budget_rollup_counts_files_and_subtrees(treemap, tmp_path):
    """The est_tokens.budget block reports the repo total plus how many files
    and top-level subtrees exceed one context-window keyhole."""
    root = tmp_path
    over_file = root / "giant.py"           # single file over budget
    a1 = root / "pkg_a" / "x.py"            # pkg_a subtree over budget in sum
    a2 = root / "pkg_a" / "y.py"
    small = root / "tiny.py"
    files = [
        (over_file, 10, 1.0, "lizard"),
        (a1, 10, 1.0, "lizard"),
        (a2, 10, 1.0, "lizard"),
        (small, 10, 1.0, "lizard"),
    ]
    tokens = {over_file: 250000, a1: 150000, a2: 120000, small: 100}
    out = root / "stats.json"
    treemap.write_stats(files, None, None, root, out, tokens_by_path=tokens)
    budget = json.loads(out.read_text())["est_tokens"]["budget"]
    assert budget["budget"] == treemap.CONTEXT_WINDOW_BUDGET_TOKENS
    assert budget["total"] == 250000 + 150000 + 120000 + 100
    assert budget["files_over_budget"] == 1           # only giant.py alone
    # pkg_a (270k) and giant.py-as-its-own-subtree (250k) both exceed 200k.
    assert budget["subtrees_over_budget"] == 2
    over_names = {s["path"] for s in budget["over_budget_subtrees"]}
    assert "pkg_a" in over_names and "giant.py" in over_names


def test_est_tokens_are_post_artifact_filter(treemap, tmp_path):
    """est_tokens are computed only over the files passed in (already filtered
    by collect), so a filtered bundle never inflates the totals or budget."""
    root = tmp_path
    real = root / "real.py"
    real.write_text("z" * 400, encoding="utf-8")  # 100 tokens
    out = root / "stats.json"
    # The bundle is simply absent from `files` (collect dropped it) - the
    # totals reflect only the surviving file.
    treemap.write_stats([(real, 20, 5.0, "lizard")], None, None, root, out)
    stats = json.loads(out.read_text())
    assert stats["est_tokens"]["total"] == 100


def test_build_tree_size_by_decouples_area_from_loc(render_lib):
    """size_by overrides the block area (estimated tokens) while each leaf keeps
    its real loc and records est_tokens for the tooltip."""
    root = Path("/repo")
    a = root / "a.py"
    files_colored = [(a, 500, 5.0, "lizard", (0.8, 0.2, 0.1, 1.0))]
    tree = render_lib.build_tree(files_colored, root, size_by={a: 1800})
    leaf = tree.children[0]
    assert leaf.size == 1800        # layout area = estimated tokens
    assert leaf.loc == 500          # real loc preserved
    assert leaf.est_tokens == 1800


def test_build_tree_without_size_by_is_unchanged(render_lib):
    """No size_by (the docs-heatmap path) keeps area == loc, est_tokens 0."""
    root = Path("/repo")
    a = root / "a.py"
    files_colored = [(a, 500, 5.0, "lizard", (0.8, 0.2, 0.1, 1.0))]
    leaf = render_lib.build_tree(files_colored, root).children[0]
    assert leaf.size == 500 and leaf.loc == 500 and leaf.est_tokens == 0


def test_write_svg_tooltip_shows_est_tokens_and_loc(render_lib, tmp_path):
    """A code-heatmap node (est_tokens set) leads its tooltip with estimated
    tokens and keeps LOC alongside."""
    node = render_lib.Node(name="a.py", rel_path="a.py", loc=514,
                           est_tokens=8200, metric=12.0,
                           color=(0.8, 0.2, 0.1, 1.0), is_file=True)
    rects = [(0.0, 0.0, 100.0, 100.0, node)]
    out = tmp_path / "tok.svg"
    render_lib.write_svg(rects, Path("/repo"), 1600.0, 1000.0, out, False, "ccn")
    svg = out.read_text()
    assert "8,200 est. tokens" in svg
    assert "514 loc" in svg


def test_write_stats_stamps_run_id_and_schema_version(treemap, tmp_path):
    """The complexity-stats sidecar carries an artifact_schema_version and a
    unique run_id (assess-obey-thyself), so each stats emission is traceable.
    Distinct from the stats-layout `schema_version` (an int, versions the diff
    comparability)."""
    root = tmp_path
    f = root / "a.go"
    out = root / "stats.json"
    treemap.write_stats([(f, 100, 5.0, "lizard")], None, None, root, out)
    stats = json.loads(out.read_text())
    assert stats["artifact_schema_version"] == treemap.ARTIFACT_SCHEMA_VERSION == "1.1.0"
    # The stats-layout schema_version (from #244) still coexists as an int.
    assert stats["schema_version"] == treemap.STATS_SCHEMA_VERSION
    run_id = stats["run_id"]
    stamp, _, suffix = run_id.partition("-")
    assert len(stamp) == 14 and stamp.isdigit()
    assert len(suffix) == 8

    out2 = root / "stats2.json"
    treemap.write_stats([(f, 100, 5.0, "lizard")], None, None, root, out2)
    assert json.loads(out2.read_text())["run_id"] != run_id


# --- generated-file exclusion (header sniff, long lines, filename globs) -----

@pytest.mark.parametrize("name", [
    "types.generated.ts", "schema.generated.sql", "client.gen.ts",
    "database.types.ts",
])
def test_generated_header_free_filename_globs_are_filtered(treemap, name):
    assert treemap._is_build_artifact(Path("src") / name) is True


def _fake_scorers(treemap, monkeypatch, paths):
    monkeypatch.setattr(
        treemap, "lizard_scores",
        lambda root, **kw: {p: (10, 3.0, [3.0]) for p in paths},
    )
    monkeypatch.setattr(treemap, "scc_scores", lambda root, **kw: {})


def test_collect_drops_generated_header_and_long_line_files(
        treemap, tmp_path, monkeypatch):
    root = tmp_path
    (root / "db").mkdir()
    (root / "src").mkdir()
    schema = root / "db" / "schema.sql"
    schema.write_text("-- GENERATED FILE - DO NOT EDIT\nCREATE TABLE t (id int);\n")
    font = root / "src" / "font.ts"
    font.write_text('export const F = "' + "A" * 40000 + '";\n')
    hand = root / "src" / "hand.py"
    hand.write_text("def f():\n    return 1\n" + "# x\n" * 196
                    + "# do not edit the table above\n")
    _fake_scorers(treemap, monkeypatch, [schema, font, hand])

    excluded: list[dict] = []
    files, *_rest, fn_ccn = treemap.collect(
        root, by="complexity", excluded_generated=excluded)
    assert [f[0] for f in files] == [hand]
    assert set(fn_ccn) == {hand}
    assert excluded == [
        {"path": "db/schema.sql", "reason": "generated-header"},
        {"path": "src/font.ts", "reason": "long-lines"},
    ]


def test_collect_include_artifacts_keeps_generated_header_files(
        treemap, tmp_path, monkeypatch):
    schema = tmp_path / "schema.sql"
    schema.write_text("-- @generated\nCREATE TABLE t (id int);\n")
    _fake_scorers(treemap, monkeypatch, [schema])
    excluded: list[dict] = []
    files, *_ = treemap.collect(tmp_path, by="complexity",
                                include_artifacts=True,
                                excluded_generated=excluded)
    assert [f[0] for f in files] == [schema]
    assert excluded == []


def test_write_stats_carries_generated_header_exclusions(treemap, tmp_path):
    root = tmp_path
    f = root / "a.py"
    f.write_text("x = 1\n")
    out = root / "stats.json"
    listed = [{"path": "db/schema.sql", "reason": "generated-header"}]
    treemap.write_stats([(f, 1, 1.0, "lizard")], None, None, root, out,
                        excluded_generated=listed)
    stats = json.loads(out.read_text())
    assert stats["excluded_generated"] == listed
    assert isinstance(stats["schema_version"], int) and stats["schema_version"] > 1
    treemap.write_stats([(f, 1, 1.0, "lizard")], None, None, root, out)
    assert json.loads(out.read_text())["excluded_generated"] == []


def test_generated_header_all_excluded_error_names_the_exclusion(
        treemap, tmp_path, monkeypatch, capsys):
    schema = tmp_path / "schema.sql"
    schema.write_text("-- GENERATED FILE - DO NOT EDIT\nCREATE TABLE t (id int);\n")
    _fake_scorers(treemap, monkeypatch, [schema])
    monkeypatch.setattr(sys, "argv", ["complexity-treemap.py", str(tmp_path)])
    assert treemap.main() == 1
    err = capsys.readouterr().err
    assert "no scoreable files found" in err
    assert "1 excluded as generated" in err
    assert "--include-artifacts" in err


def test_write_stats_paths_match_generated_header_list_separator(treemap, tmp_path):
    """Row paths use forward slashes on every host, the same form as
    excluded_generated, so assess_core can intersect the two sets on Windows
    (where str() of a relative path would use backslashes)."""
    (tmp_path / "db").mkdir()
    f = tmp_path / "db" / "a.py"
    f.write_text("x = 1\n")
    out = tmp_path / "stats.json"
    treemap.write_stats([(f, 1, 1.0, "lizard")], None, None, tmp_path, out)
    paths = [r["path"] for r in json.loads(out.read_text())["top_large"]]
    assert paths == ["db/a.py"]
    src = (Path(treemap.__file__)).read_text()
    rel_body = src[src.index("    def rel(p: Path) -> str:"):][:400]
    assert "as_posix()" in rel_body and "str(p" not in rel_body


# --- generated test reports, code/data maxima, scc-only hint -----------------

@pytest.mark.parametrize("rel", [
    "web/tests/html-report/index.html",
    "e2e/playwright-report/index.html",
    "web/accessibility/lighthouse-report.html",
    "web/accessibility/lighthouse-results.json",
    "security/zap-report.html",
    "security/zap-report.json",
    "security/zap_report.html",
    "mcp/test/fixtures/big/lines.jsonl",
    "a/fixtures/lines.jsonl",
])
def test_report_default_excludes_drop_generated_reports(treemap, rel):
    path = Path(rel)
    in_dir = any(part in treemap.EXCLUDE_DIRS for part in path.parts)
    assert in_dir or treemap._is_build_artifact(path)


@pytest.mark.parametrize("rel", [
    "data/events.jsonl",           # .jsonl outside any fixtures/ directory
    "fixtures/lines.jsonl",        # bare top-level fixtures/ stays scored
    "fixtures/taxonomy/concepts.json",
    "mcp/test/fixtures/big/case.json",  # only .jsonl leaves nested fixtures/
    "src/report.html",
    "security/zap_report.py",  # the script that runs ZAP, not its output
])
def test_report_default_excludes_keep_hand_kept_files(treemap, rel):
    path = Path(rel)
    assert not any(part in treemap.EXCLUDE_DIRS for part in path.parts)
    assert treemap._is_build_artifact(path) is False


def test_report_default_excludes_bypassed_by_include_artifacts(
        treemap, tmp_path, monkeypatch):
    """The nested-fixture .jsonl rule is a filename default like the globs, so
    --include-artifacts scores it."""
    import subprocess as sp

    nested = tmp_path / "mcp" / "fixtures" / "lines.jsonl"
    nested.parent.mkdir(parents=True)
    nested.write_text('{"a": 1}\n')
    payload = json.dumps([{"Name": "JSONL", "Files": [
        {"Location": str(nested), "Code": 1, "Complexity": 0}]}])
    monkeypatch.setattr(treemap.shutil, "which", lambda _: "/usr/bin/scc")
    monkeypatch.setattr(treemap.subprocess, "run", lambda *a, **k:
                        sp.CompletedProcess(a, 0, stdout=payload))
    assert treemap.scc_scores(tmp_path) == {}
    langs: dict = {}
    assert treemap.scc_scores(tmp_path, include_artifacts=True,
                              languages=langs) == {nested.resolve(): (1, 0.0)}
    assert langs == {nested.resolve(): "JSONL"}


def test_code_data_maxima_split_by_scc_language(treemap, tmp_path):
    root = tmp_path
    code = root / "app.py"
    code.write_text("x = 1\n" * 30)
    data = root / "big.json"
    data.write_text('{"k": 1}\n' * 500)
    conf = root / "settings.yaml"
    conf.write_text("k: 1\n" * 100)
    out = root / "stats.json"
    langs = {data: "JSON", conf: "YAML"}
    treemap.write_stats(
        [(code, 30, 4.0, "lizard"), (data, 500, 0.0, "scc"),
         (conf, 100, 0.0, "scc")],
        None, None, root, out, languages_by_path=langs)
    stats = json.loads(out.read_text())
    rows = {r["path"]: r for r in stats["top_large"]}
    assert stats["loc"]["max"] == 500
    assert stats["loc"]["max_code"] == rows["app.py"]["loc"] == 30
    assert stats["loc"]["max_data"] == rows["big.json"]["loc"] == 500
    assert stats["est_tokens"]["max_code"] == rows["app.py"]["est_tokens"]
    assert stats["est_tokens"]["max_data"] == rows["big.json"]["est_tokens"]
    assert stats["schema_version"] >= 3


def test_code_data_maxima_empty_side_reports_zero(treemap, tmp_path):
    f = tmp_path / "a.py"
    f.write_text("x = 1\n")
    out = tmp_path / "stats.json"
    treemap.write_stats([(f, 1, 1.0, "lizard")], None, None, tmp_path, out)
    stats = json.loads(out.read_text())
    assert stats["loc"]["max_code"] == 1
    assert stats["loc"]["max_data"] == 0
    assert stats["est_tokens"]["max_data"] == 0


def _scc_row(tmp_path, name, loc, ccn=0.0, src="scc"):
    p = tmp_path / name
    return (p, loc, ccn, src)


_LANG_BY_SUFFIX = {".json": "JSON", ".py": "Python", ".ex": "Elixir",
                   ".md": "Markdown"}


def _langs(files):
    return {f[0]: _LANG_BY_SUFFIX[f[0].suffix] for f in files}


def test_scc_only_hint_fires_when_largest_files_are_scc_ccn_zero(
        treemap, tmp_path, capsys):
    files = [_scc_row(tmp_path, f"d{i}.json", 200) for i in range(12)]
    files.append(_scc_row(tmp_path, "tiny.py", 2, 1.0, "lizard"))
    tokens = {f[0]: f[1] * 10 for f in files}
    treemap._hint_if_largest_files_scc_only(files, tokens, _langs(files))
    err = capsys.readouterr().err
    assert ".assess/config.toml" in err
    assert "d0.json" in err


def test_scc_only_hint_silent_when_largest_file_is_code(
        treemap, tmp_path, capsys):
    files = [_scc_row(tmp_path, f"d{i}.json", 200) for i in range(12)]
    files.append(_scc_row(tmp_path, "big.py", 1200, 600.0, "lizard"))
    tokens = {f[0]: f[1] * 10 for f in files}
    treemap._hint_if_largest_files_scc_only(files, tokens, _langs(files))
    assert capsys.readouterr().err == ""


def test_scc_only_hint_silent_on_scored_scc_code(treemap, tmp_path, capsys):
    """An scc-scored file with complexity above 0 is code (an Elixir or Dart
    module), so it keeps the hint quiet."""
    files = [_scc_row(tmp_path, f"m{i}.ex", 200, 3.0) for i in range(12)]
    tokens = {f[0]: f[1] * 10 for f in files}
    treemap._hint_if_largest_files_scc_only(files, tokens, _langs(files))
    assert capsys.readouterr().err == ""


def test_scc_only_hint_silent_on_markdown(treemap, tmp_path, capsys):
    """scc gives Markdown complexity 0 too, but on a docs-first repo those
    blocks are the deliverable, not data to exclude."""
    files = [_scc_row(tmp_path, f"s{i}.md", 200) for i in range(12)]
    tokens = {f[0]: f[1] * 10 for f in files}
    treemap._hint_if_largest_files_scc_only(files, tokens, _langs(files))
    assert capsys.readouterr().err == ""


def test_scc_only_hint_silent_below_top_n(treemap, tmp_path, capsys):
    files = [_scc_row(tmp_path, f"d{i}.json", 200)
             for i in range(treemap.SCC_ONLY_HINT_TOP_N - 1)]
    tokens = {f[0]: f[1] * 10 for f in files}
    treemap._hint_if_largest_files_scc_only(files, tokens, _langs(files))
    assert capsys.readouterr().err == ""


@pytest.mark.parametrize("include_artifacts", [False, True])
def test_scc_only_hint_skipped_under_include_artifacts(
        treemap, tmp_path, monkeypatch, capsys, include_artifacts):
    paths = []
    for i in range(treemap.SCC_ONLY_HINT_TOP_N):
        p = tmp_path / f"d{i}.json"
        p.write_text('{"k": 1}\n' * 50)
        paths.append(p)

    def fake_collect(root, **kw):
        kw["scc_languages"].update({p: "JSON" for p in paths})
        return [(p, 50, 0.0, "scc") for p in paths], "hotspot", None, None, {}

    monkeypatch.setattr(treemap, "collect", fake_collect)
    monkeypatch.setattr(treemap, "render", lambda *a, **k: None)
    argv = ["complexity-treemap.py", str(tmp_path), "-o",
            str(tmp_path / "out.svg")]
    if include_artifacts:
        argv.append("--include-artifacts")
    monkeypatch.setattr(sys, "argv", argv)
    assert treemap.main() == 0
    hinted = ".assess/config.toml" in capsys.readouterr().err
    assert hinted is not include_artifacts


# --------------------------------------------------------------------------
# Per-function backend per language and the worst function's name (issue #363)


def test_write_stats_backend_by_language_maps_lizard_and_null(treemap, tmp_path):
    """fn_ccn.source lists the backends that scored a file, as objects, and
    backend_by_language maps each programming language to its backend or to
    null when only scc scored it at file level. Data and markup languages,
    where scc counts no decision points, carry no key."""
    root = tmp_path
    py = root / "src" / "app.py"
    ex = root / "lib" / "router.ex"
    js = root / "data.json"
    md = root / "README.md"
    out = root / "stats.json"
    treemap.write_stats(
        [(py, 20, 8.0, "lizard"), (ex, 9, 2.0, "scc"),
         (js, 50, 0.0, "scc"), (md, 30, 0.0, "scc")],
        None, None, root, out,
        fn_ccn_by_path={py: [1.0, 7.0]},
        fn_name_by_path={py: "gnarly"},
        languages_by_path={py: "Python", ex: "Elixir",
                           js: "JSON", md: "Markdown"},
    )
    fn = json.loads(out.read_text())["fn_ccn"]
    assert fn["source"] == [{"name": "lizard", "approximate": False}]
    assert fn["backend_by_language"] == {"Python": "lizard", "Elixir": None}


def test_write_stats_backend_by_language_partial_coverage_is_null(
        treemap, tmp_path):
    """A language a backend covers only in part maps to null: one lizard file
    must not make the language's scc-only files read as covered. A file with
    no decision points loses no per-function figure and does not downgrade."""
    root = tmp_path
    cpp, ipp = root / "a.cpp", root / "a.ipp"
    js, mjs = root / "a.js", root / "b.mjs"
    out = root / "stats.json"
    treemap.write_stats(
        [(cpp, 20, 8.0, "lizard"), (ipp, 30, 4.0, "scc"),
         (js, 20, 3.0, "lizard"), (mjs, 5, 0.0, "scc")],
        None, None, root, out,
        fn_ccn_by_path={cpp: [8.0], js: [3.0]},
        languages_by_path={cpp: "C++", ipp: "C++",
                           js: "JavaScript", mjs: "JavaScript"},
    )
    fn = json.loads(out.read_text())["fn_ccn"]
    assert fn["backend_by_language"] == {"C++": None, "JavaScript": "lizard"}


def test_write_stats_backend_by_language_empty_source_when_no_backend(
        treemap, tmp_path):
    """An scc-only run lists no backend rather than claiming lizard."""
    root = tmp_path
    ex = root / "router.ex"
    out = root / "stats.json"
    treemap.write_stats([(ex, 9, 2.0, "scc")], None, None, root, out,
                        languages_by_path={ex: "Elixir"})
    fn = json.loads(out.read_text())["fn_ccn"]
    assert fn["source"] == []
    assert fn["backend_by_language"] == {"Elixir": None}


def test_write_stats_max_fn_name_names_worst_function(treemap, tmp_path):
    """Every ranked row carries max_fn_name beside max_fn_ccn; it is null
    wherever max_fn_ccn is null (an scc-scored file, or a lizard file with no
    functions)."""
    root = tmp_path
    py = root / "app.py"
    flat = root / "flat.py"
    ex = root / "router.ex"
    out = root / "stats.json"
    treemap.write_stats(
        [(py, 20, 8.0, "lizard"), (flat, 5, 1.0, "lizard"),
         (ex, 9, 2.0, "scc")],
        None, None, root, out,
        fn_ccn_by_path={py: [1.0, 7.0], flat: []},
        fn_name_by_path={py: "gnarly"},
    )
    stats = json.loads(out.read_text())
    for key in ("top_hotspots", "top_complex", "top_large"):
        rows = {r["path"]: r for r in stats[key]}
        assert rows["app.py"]["max_fn_ccn"] == 7.0
        assert rows["app.py"]["max_fn_name"] == "gnarly"
        assert rows["flat.py"]["max_fn_ccn"] is None
        assert rows["flat.py"]["max_fn_name"] is None
        assert rows["router.ex"]["max_fn_name"] is None


def test_lizard_scores_fills_max_fn_name_with_worst_function(
        treemap, tmp_path, monkeypatch):
    """lizard_scores records the name of each file's highest-ccn function in
    the optional fn_names map, and collect threads it through."""
    src = tmp_path / "app.py"
    src.write_text("def simple(a):\n    return a\n")

    def fn(name, ccn):
        return types.SimpleNamespace(name=name, cyclomatic_complexity=ccn)

    fake = types.SimpleNamespace(
        filename=str(src), nloc=10,
        function_list=[fn("simple", 1), fn("gnarly", 7), fn("tie", 7)],
    )
    monkeypatch.setattr(treemap.lizard, "analyze",
                        lambda **kw: [fake], raising=False)
    monkeypatch.setattr(treemap, "scc_scores", lambda root, **kw: {})
    names: dict = {}
    scores = treemap.lizard_scores(tmp_path, fn_names=names)
    assert scores[src.resolve()][2] == [1.0, 7.0, 7.0]
    assert names == {src.resolve(): "gnarly"}

    via_collect: dict = {}
    treemap.collect(tmp_path, by="complexity", fn_names=via_collect)
    assert via_collect == {src.resolve(): "gnarly"}


def test_stats_schema_version_raised_for_backend_by_language(treemap):
    assert treemap.STATS_SCHEMA_VERSION >= 4


# Approximate per-function backend for Dart (issue #364)


def test_collect_dart_scanner_scores_scc_dart_files(
        treemap, tmp_path, monkeypatch):
    """collect adds the Dart scanner's per-function figures to scc-scored
    .dart files, names the worst function and records the backend; other
    scc files stay without a breakdown."""
    dart = tmp_path / "lib" / "order.dart"
    dart.parent.mkdir()
    dart.write_text("int a(x) { if (x) {} return 1; }\nint b() => 2;\n")
    ex = tmp_path / "router.ex"
    ex.write_text("defmodule R do\nend\n")
    monkeypatch.setattr(treemap, "lizard_scores", lambda root, **kw: {})
    monkeypatch.setattr(
        treemap, "scc_scores",
        lambda root, **kw: {dart.resolve(): (2, 3.0), ex.resolve(): (2, 1.0)})
    names: dict = {}
    backends: dict = {}
    *_, fn_ccn = treemap.collect(tmp_path, by="complexity",
                                 fn_names=names, fn_backends=backends)
    assert fn_ccn == {dart.resolve(): [2.0, 1.0]}
    assert names == {dart.resolve(): "a"}
    assert backends == {dart.resolve(): "dart-scanner"}


def test_write_stats_dart_scanner_marked_approximate(treemap, tmp_path):
    """The Dart scanner appears in fn_ccn.source with approximate true, maps
    Dart in backend_by_language, and fills the Dart row's max_fn_ccn and
    max_fn_name."""
    root = tmp_path
    py = root / "app.py"
    dart = root / "order.dart"
    out = root / "stats.json"
    treemap.write_stats(
        [(py, 20, 8.0, "lizard"), (dart, 40, 30.0, "scc")],
        None, None, root, out,
        fn_ccn_by_path={py: [7.0], dart: [1.0, 12.0]},
        fn_name_by_path={py: "gnarly", dart: "routeOrder"},
        languages_by_path={py: "Python", dart: "Dart"},
        fn_backend_by_path={dart: "dart-scanner"},
    )
    stats = json.loads(out.read_text())
    fn = stats["fn_ccn"]
    assert fn["source"] == [{"name": "dart-scanner", "approximate": True},
                            {"name": "lizard", "approximate": False}]
    assert fn["backend_by_language"] == {"Dart": "dart-scanner",
                                         "Python": "lizard"}
    row = {r["path"]: r for r in stats["top_hotspots"]}["order.dart"]
    assert (row["max_fn_ccn"], row["max_fn_name"]) == (12.0, "routeOrder")


def test_write_stats_version_keys_are_tool_versions_or_listed_non_tools(
        treemap, tmp_path, monkeypatch):
    """Every `*_version` key write_stats emits is either a tool version that
    assess_core._stats_tool_versions reads or a stamp listed in
    _NON_TOOL_VERSION_KEYS, so the writer and the reader cannot drift."""
    import assess_core

    monkeypatch.setattr(treemap, "_scc_version", lambda: "3.7.0")
    root = tmp_path
    py, dart = root / "app.py", root / "order.dart"
    out = root / "stats.json"
    treemap.write_stats(
        [(py, 20, 8.0, "lizard"), (dart, 40, 30.0, "scc")],
        None, None, root, out,
        fn_ccn_by_path={py: [7.0], dart: [12.0]},
        fn_backend_by_path={dart: "dart-scanner"},
    )
    stats = json.loads(out.read_text())
    version_keys = {k for k in stats if k.endswith("_version")}
    tools = {f"{t}_version" for t in assess_core._stats_tool_versions(stats)}
    assert tools == {"lizard_version", "scc_version"}
    assert version_keys - tools == set(assess_core._NON_TOOL_VERSION_KEYS)


def test_collect_dart_scanner_skips_files_with_no_function(
        treemap, tmp_path, monkeypatch):
    """A Dart file the scanner finds no function in stays scc-only, so it
    records no backend and cannot make Dart read as covered."""
    dart = tmp_path / "consts.dart"
    dart.write_text("const a = 1;\n")
    monkeypatch.setattr(treemap, "lizard_scores", lambda root, **kw: {})
    monkeypatch.setattr(treemap, "scc_scores",
                        lambda root, **kw: {dart.resolve(): (1, 1.0)})
    backends: dict = {}
    *_, fn_ccn = treemap.collect(tmp_path, by="complexity",
                                 fn_backends=backends)
    assert fn_ccn == {} and backends == {}


def test_effective_ccn_clamps_dart_scanner_max_to_scc_aggregate(treemap):
    """A Dart row takes ccn from scc and max_fn_ccn from the scanner; a
    scanner figure above the aggregate must not lift the effective value
    past it. Lizard rows, where max <= aggregate, are unchanged."""
    assert treemap._effective_ccn(1.0, 5.0) == 1.0
    assert treemap._effective_ccn(0.0, 3.0) == 0.0
    w = treemap.PER_FUNCTION_WEIGHT
    expected = 10.0 ** w * 100.0 ** (1 - w)
    assert abs(treemap._effective_ccn(100.0, 10.0) - expected) < 1e-9


def test_stats_schema_version_raised_for_dart_scanner(treemap):
    assert treemap.STATS_SCHEMA_VERSION >= 5

"""Tests for lib/config_drift.py and the shared gh helper lib/gh_cli.py.

GitHub is faked with a `gh` shell script placed first on PATH: it logs every
call and answers from JSON files in a directory, so the tests exercise the real
subprocess path, the remote-then-auth-then-calls order and the 403 mapping.
"""
from __future__ import annotations

import json
import os
import stat
import subprocess
import sys
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))

from lib.config_drift import diff_values, find_snapshots, scan_config_drift  # noqa: E402
from lib.gh_cli import (  # noqa: E402
    GhUnavailable,
    gh_json,
    open_github,
    parse_github_remote,
)

FAKE_GH = """#!/bin/sh
echo "$*" >> "$FAKE_GH/log"
serve() { [ -f "$FAKE_GH/$1" ] && cat "$FAKE_GH/$1" && exit 0; }
case "$1:$*" in
  auth:*) [ -f "$FAKE_GH/noauth" ] || exit 0 ;;
  pr:*) serve prs.json ;;
  api:*rulesets/[0-9]*) serve ruleset.json ;;
  api:*rulesets*) serve rulesets.json ;;
  api:*/protection*) serve protection.json ;;
esac
cat "$FAKE_GH/fail" >&2
exit 1
"""


def _ruleset(strict: bool, **extra) -> dict:
    return {
        "id": 7, "name": "main", "target": "branch", "enforcement": "active",
        "updated_at": extra.pop("updated_at", "2026-01-01T00:00:00Z"),
        "rules": [
            {"type": "deletion"},
            {"type": "pull_request", "parameters": {"required_approving_review_count": 1}},
            {"type": "required_status_checks", "parameters": {
                "strict_required_status_checks_policy": strict,
                "required_status_checks": [{"context": "ci"}],
            }},
        ],
        **extra,
    }


def _protection(strict: bool) -> dict:
    return {
        "url": "https://api.github.com/repos/acme/widget/branches/main/protection",
        "required_status_checks": {"strict": strict, "contexts": ["ci"]},
        "enforce_admins": {"url": "https://x/enforce_admins", "enabled": True},
        "required_pull_request_reviews": {"required_approving_review_count": 1},
    }


def _git(repo: Path, *args: str) -> None:
    env = {**os.environ, "GIT_CONFIG_GLOBAL": "/dev/null"}
    subprocess.run(
        ["git", "-C", str(repo), "-c", "user.email=t@example.com", "-c", "user.name=t", *args],
        check=True, capture_output=True, env=env,
    )


@pytest.fixture
def world(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
    """A git repo with a github.com origin and a fake gh first on PATH."""
    repo = tmp_path / "repo"
    (repo / "src").mkdir(parents=True)
    (repo / "src" / "a.py").write_text("x = 1\n")
    _git(repo, "init", "-q", "-b", "main")
    _git(repo, "remote", "add", "origin", "https://github.com/acme/widget.git")

    bindir, ghdir = tmp_path / "bin", tmp_path / "gh"
    bindir.mkdir()
    ghdir.mkdir()
    gh = bindir / "gh"
    gh.write_text(FAKE_GH)
    gh.chmod(gh.stat().st_mode | stat.S_IEXEC)
    (ghdir / "log").write_text("")
    (ghdir / "fail").write_text("gh: Not Found (HTTP 404)\n")
    monkeypatch.setenv("PATH", f"{bindir}{os.pathsep}{os.environ['PATH']}")
    monkeypatch.setenv("FAKE_GH", str(ghdir))

    class World:
        root = repo

        def track(self, rel: str, doc: object) -> None:
            path = repo / rel
            path.parent.mkdir(parents=True, exist_ok=True)
            path.write_text(json.dumps(doc))
            _git(repo, "add", rel)

        def serve(self, name: str, doc: object) -> None:
            (ghdir / name).write_text(json.dumps(doc))

        def fail_with(self, line: str) -> None:
            (ghdir / "fail").write_text(line + "\n")

        def calls(self) -> list[str]:
            return (ghdir / "log").read_text().splitlines()

    return World()


# ---------------------------------------------------------------------------
# gh helper
# ---------------------------------------------------------------------------


@pytest.mark.parametrize("url", [
    "https://github.com/acme/widget.git",
    "https://github.com/acme/widget",
    "git@github.com:acme/widget.git",
    "ssh://git@github.com/acme/widget.git",
])
def test_parse_github_remote_accepts_github_forms(url: str) -> None:
    repo = parse_github_remote(url)
    assert repo is not None and repo.slug == "acme/widget"


def test_parse_github_remote_rejects_other_hosts() -> None:
    assert parse_github_remote("https://gitlab.com/acme/widget.git") is None


def test_no_remote_never_invokes_gh(world) -> None:
    _git(world.root, "remote", "remove", "origin")
    with pytest.raises(GhUnavailable) as e:
        open_github(world.root)
    assert e.value.reason
    assert world.calls() == []


def test_unauthenticated_gh_degrades(world) -> None:
    (Path(os.environ["FAKE_GH"]) / "noauth").write_text("")
    with pytest.raises(GhUnavailable) as e:
        open_github(world.root)
    assert e.value.reason.startswith("not_authenticated")


def test_gh_json_parses_pr_list(world) -> None:
    world.serve("prs.json", [{"number": 1, "extra": "x"}])
    assert gh_json(["pr", "list", "--state", "merged", "--json", "number"])[0]["number"] == 1


# ---------------------------------------------------------------------------
# config_drift
# ---------------------------------------------------------------------------


def test_ruleset_drift_reports_one_entry(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.serve("rulesets.json", [{"id": 7, "name": "main"}])
    world.serve("ruleset.json", _ruleset(True, updated_at="2026-08-01T00:00:00Z"))
    block = scan_config_drift(world.root)
    assert block["available"] is True
    assert block["entries"] == [{
        "file": ".github/rulesets/main.json",
        "key": "rules[required_status_checks].parameters.strict_required_status_checks_policy",
        "tracked": False,
        "live": True,
    }]


def test_identical_ruleset_gives_empty_entries(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.serve("rulesets.json", [{"id": 7, "name": "main"}])
    world.serve("ruleset.json", _ruleset(False, updated_at="2026-08-01T00:00:00Z",
                                         node_id="X", _links={"self": {"href": "h"}}))
    block = scan_config_drift(world.root)
    assert block == {"available": True, "entries": [], "dropped": 0,
                     "snapshots": [{"file": ".github/rulesets/main.json", "kind": "ruleset"}]}


def test_ruleset_matched_by_name_outside_rulesets_dir(world) -> None:
    doc = _ruleset(False)
    del doc["id"]
    world.track("infra/github/protect-main.json", doc)
    world.serve("rulesets.json", [{"id": 99, "name": "main"}])
    world.serve("ruleset.json", _ruleset(True))
    block = scan_config_drift(world.root)
    assert [e["file"] for e in block["entries"]] == ["infra/github/protect-main.json"]


def test_rule_dropped_or_added_live_is_drift_without_the_live_object() -> None:
    tracked = _ruleset(False)
    live = _ruleset(False)
    live["rules"] = live["rules"][1:] + [{"type": "non_fast_forward", "parameters": {"x": 1}}]
    assert diff_values(tracked, live) == [
        ("rules[deletion]", "present", "absent"),
        ("rules[non_fast_forward]", "absent", "present"),
    ]


def test_reordered_lists_are_not_drift() -> None:
    tracked = {"required_status_checks": {"contexts": ["ci", "lint"]},
               "bypass_actors": [{"actor_id": 1, "actor_type": "Team"},
                                 {"actor_id": 2, "actor_type": "Integration"}]}
    live = {"required_status_checks": {"contexts": ["lint", "ci"]},
            "bypass_actors": [{"actor_id": 2, "actor_type": "Integration", "bypass_mode": "always"},
                              {"actor_id": 1, "actor_type": "Team", "bypass_mode": "always"}]}
    assert diff_values(tracked, live) == []


def test_changed_scalar_list_is_one_bounded_entry() -> None:
    tracked = {"required_status_checks": {"contexts": ["ci"]}}
    live = {"required_status_checks": {"contexts": ["lint", "ci"]}}
    assert diff_values(tracked, live) == [
        ("required_status_checks.contexts",
         {"count": 1, "removed": 0, "sample": []},
         {"count": 2, "added": 1, "sample": ["lint"]})]


def test_scalar_list_drift_never_stores_the_whole_live_list() -> None:
    tracked = {"required_status_checks": {"contexts": ["ci", "old-a", "old-b", "old-c", "old-d"]}}
    live_names = ["ci"] + [f"zzlive-{i:02d}" for i in range(30)]
    live = {"required_status_checks": {"contexts": live_names}}
    [(key, was, now)] = diff_values(tracked, live)
    assert key == "required_status_checks.contexts"
    assert was == {"count": 5, "removed": 4, "sample": ["old-a", "old-b", "old-c"]}
    assert now == {"count": 31, "added": 30, "sample": ["zzlive-00", "zzlive-01", "zzlive-02"]}
    assert json.dumps(now).count("zzlive") == 3


def test_identity_less_object_list_reports_counts_only() -> None:
    tracked = {"x": [{"a": 1}]}
    live = {"x": [{"a": 1}, {"a": 2, "secret_ish": "org detail"}]}
    assert diff_values(tracked, live) == [("x.count", 1, 2)]


@pytest.mark.parametrize("doc", [
    {"description": "not an export"},                       # no rules at all
    {"rules": [{"type": "lint-rule"}]},                     # rules but no name/id
])
def test_non_export_json_is_not_a_snapshot(world, doc) -> None:
    world.track(".github/rulesets/schema.json", doc)
    world.track("config/eslint-ish.json", doc)
    assert find_snapshots(world.root) == []
    assert scan_config_drift(world.root)["entries"] == []
    assert world.calls() == []


def test_deleted_branch_is_drift_not_outage(world) -> None:
    world.track(".github/branch-protection/old.json", _protection(True) | {"url": ""})
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.serve("rulesets.json", [{"id": 7, "name": "main"}])
    world.serve("ruleset.json", _ruleset(True))
    world.fail_with("gh: Branch not found (HTTP 404)")
    block = scan_config_drift(world.root)
    assert block["available"] is True
    assert {"file": ".github/branch-protection/old.json", "key": "branch",
            "tracked": "old", "live": "absent"} in block["entries"]
    assert any(e["file"] == ".github/rulesets/main.json" for e in block["entries"])


def test_unprotected_branch_is_drift(world) -> None:
    world.track(".github/branch-protection/main.json", _protection(True))
    world.fail_with("gh: Branch not protected (HTTP 404)")
    block = scan_config_drift(world.root)
    assert block["entries"] == [{"file": ".github/branch-protection/main.json",
                                 "key": "branch_protection", "tracked": "present",
                                 "live": "absent"}]


def test_other_404_degrades_the_block(world) -> None:
    world.track(".github/branch-protection/main.json", _protection(True))
    block = scan_config_drift(world.root)  # default fail: "gh: Not Found (HTTP 404)"
    assert block["available"] is False and block["reason"].startswith("not_found")


def test_missing_live_ruleset_is_drift(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.serve("rulesets.json", [])
    block = scan_config_drift(world.root)
    assert block["entries"] == [{"file": ".github/rulesets/main.json", "key": "ruleset",
                                 "tracked": "main", "live": "absent"}]


def test_branch_protection_export_drift(world) -> None:
    world.track(".github/branch-protection/main.json", _protection(False))
    world.serve("protection.json", _protection(True))
    block = scan_config_drift(world.root)
    assert block["available"] is True
    assert block["entries"] == [{"file": ".github/branch-protection/main.json",
                                 "key": "required_status_checks.strict",
                                 "tracked": False, "live": True}]
    assert any("repos/acme/widget/branches/main/protection" in c for c in world.calls())


def test_branch_protection_branch_from_file_stem_and_write_shape(world) -> None:
    doc = _protection(True)
    del doc["url"]
    doc["enforce_admins"] = True  # the PUT payload shape
    world.track(".github/protection/release.json", doc)
    world.serve("protection.json", _protection(True))
    block = scan_config_drift(world.root)
    assert block["entries"] == []
    assert any("branches/release/protection" in c for c in world.calls())


def test_403_degrades_to_no_access(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.fail_with("gh: Resource not accessible by personal access token (HTTP 403)")
    block = scan_config_drift(world.root)
    assert block["available"] is False
    assert "no_access" in block["reason"]
    assert world.calls()


def test_no_remote_degrades_without_calling_gh(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    _git(world.root, "remote", "remove", "origin")
    block = scan_config_drift(world.root)
    assert block["available"] is False and block["reason"]
    assert world.calls() == []


def test_no_snapshots_is_clean_without_calling_gh(world) -> None:
    world.track("package.json", {"name": "x", "rules": "not a ruleset"})
    assert scan_config_drift(world.root) == {"available": True, "entries": [], "dropped": 0,
                                              "snapshots": []}
    assert world.calls() == []


def test_untracked_snapshot_is_ignored(world) -> None:
    path = world.root / ".github" / "rulesets" / "main.json"
    path.parent.mkdir(parents=True)
    path.write_text(json.dumps(_ruleset(False)))
    assert find_snapshots(world.root) == []


def test_key_omitted_live_is_absent_not_null() -> None:
    tracked = {"required_status_checks": {"strict": True},
               "required_pull_request_reviews": {"required_approving_review_count": 1}}
    live = {"required_status_checks": {"strict": True}}
    assert diff_values(tracked, live) == [("required_pull_request_reviews", "present", "absent")]
    assert diff_values({"a": {"b": False}}, {"a": {}}) == [("a.b", False, "absent")]
    assert diff_values({"a": None}, {"a": None}) == []


def test_ruleset_list_excludes_inherited_rulesets(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.serve("rulesets.json", [{"id": 7, "name": "main"}])
    world.serve("ruleset.json", _ruleset(False))
    scan_config_drift(world.root)
    listing = [c for c in world.calls() if "rulesets" in c and "rulesets/" not in c]
    assert listing and all("includes_parents=false" in c for c in listing)


def test_json_without_a_snapshot_key_is_not_parsed(world, monkeypatch) -> None:
    import lib.config_drift as cd

    world.track("data/big.json", {"items": list(range(100))})
    parsed: list[str] = []
    real = cd.json.loads
    monkeypatch.setattr(cd.json, "loads", lambda t: parsed.append(t) or real(t))
    assert find_snapshots(world.root) == []
    assert parsed == []


def test_entries_rank_worst_first(world) -> None:
    tracked = _protection(True)  # required_status_checks precedes enforce_admins
    live = _protection(True)
    live["required_status_checks"]["contexts"] = ["ci-renamed"]
    live["enforce_admins"] = {"url": "u", "enabled": False}
    del live["required_pull_request_reviews"]
    world.track(".github/branch-protection/main.json", tracked)
    world.serve("protection.json", live)
    keys = [e["key"] for e in scan_config_drift(world.root)["entries"]]
    assert keys == ["required_pull_request_reviews", "enforce_admins",
                    "required_status_checks.contexts"]


def test_entries_are_capped_with_a_dropped_count(world) -> None:
    from lib.config_drift import MAX_ENTRIES
    n = MAX_ENTRIES + 7
    tracked = _ruleset(False)
    tracked["rules"] = [{"type": f"rule-{i:02d}", "parameters": {"v": 1}} for i in range(n)]
    live = json.loads(json.dumps(tracked))
    for rule in live["rules"]:
        rule["parameters"]["v"] = 2
    world.track(".github/rulesets/main.json", tracked)
    world.serve("rulesets.json", [{"id": 7, "name": "main"}])
    world.serve("ruleset.json", live)
    block = scan_config_drift(world.root)
    assert len(block["entries"]) == MAX_ENTRIES
    assert block["dropped"] == 7


def test_no_drift_reports_zero_dropped(world) -> None:
    world.track(".github/rulesets/main.json", _ruleset(False))
    world.serve("rulesets.json", [{"id": 7, "name": "main"}])
    world.serve("ruleset.json", _ruleset(False))
    block = scan_config_drift(world.root)
    assert block["entries"] == [] and block["dropped"] == 0


def test_absent_key_reports_the_normalised_tracked_value() -> None:
    tracked = {"enforce_admins": {"url": "u", "enabled": False}}
    assert diff_values(tracked, {}) == [("enforce_admins", False, "absent")]


def test_type_mismatch_never_emits_the_live_object() -> None:
    tracked = {"required_pull_request_reviews": None, "restrictions": None}
    live = {"required_pull_request_reviews": {"dismissal_restrictions": {
                "users": [{"login": "zzuser"}], "teams": [{"slug": "zzteam"}]}},
            "restrictions": {"users": [], "teams": [{"slug": "zzteam"}]}}
    out = diff_values(tracked, live)
    assert out == [("required_pull_request_reviews", None, "present"),
                   ("restrictions", None, "present")]
    assert "zz" not in json.dumps(out)
    assert diff_values({"a": {"b": 1}}, {"a": 3}) == [("a", "present", 3)]


def test_tracked_null_against_omitted_live_key_is_not_drift() -> None:
    tracked = {"required_status_checks": {"strict": True},
               "required_pull_request_reviews": None, "restrictions": None}
    live = {"required_status_checks": {"strict": True}}
    assert diff_values(tracked, live) == []
    live_flip = {"required_status_checks": {"strict": False}}
    assert diff_values(tracked, live_flip) == [("required_status_checks.strict", True, False)]


def _user(login: str, uid: int) -> dict:
    # A GitHub simple-user object: `type` is the class discriminator, not an identity.
    return {"login": login, "id": uid, "type": "User", "site_admin": False}


@pytest.mark.parametrize("path", ["restrictions", "required_pull_request_reviews.dismissal_restrictions"])
def test_single_user_swap_is_one_removed_and_one_added(path: str) -> None:
    def shape(user: dict) -> dict:
        doc: dict = {"users": [user], "teams": []}
        for part in reversed(path.split(".")):
            doc = {part: doc}
        return doc
    out = diff_values(shape(_user("alice", 1)), shape(_user("bob", 2)))
    assert out == [(f"{path}.users[alice]", "present", "absent"),
                   (f"{path}.users[bob]", "absent", "present")]
    assert all(v in ("present", "absent") for _, was, now in out for v in (was, now))


def test_single_team_swap_is_one_removed_and_one_added() -> None:
    # Team objects carry `type` ("organization" / "enterprise") as a discriminator.
    tracked = {"restrictions": {"users": [], "teams": [
        {"slug": "core", "name": "Core", "id": 1, "type": "organization"}]}}
    live = {"restrictions": {"users": [], "teams": [
        {"slug": "infra", "name": "Infra", "id": 2, "type": "organization"}]}}
    assert diff_values(tracked, live) == [
        ("restrictions.teams[core]", "present", "absent"),
        ("restrictions.teams[infra]", "absent", "present")]


def test_ruleset_rules_still_pair_on_type() -> None:
    tracked = {"rules": [{"type": "pull_request",
                          "parameters": {"required_approving_review_count": 1}}]}
    live = {"rules": [{"type": "pull_request",
                       "parameters": {"required_approving_review_count": 2}}]}
    assert diff_values(tracked, live) == [
        ("rules[pull_request].parameters.required_approving_review_count", 1, 2)]


_WRITE_VS_READ = [
    ("restrictions.users", ["octocat"], [_user("octocat", 1)]),
    ("restrictions.teams", ["core"],
     [{"slug": "core", "name": "Core", "id": 1, "type": "organization"}]),
    ("restrictions.apps", ["deploy-bot"],
     [{"slug": "deploy-bot", "name": "Deploy Bot", "id": 9, "owner": {"login": "acme"}}]),
    ("required_pull_request_reviews.dismissal_restrictions.users", ["octocat"],
     [_user("octocat", 1)]),
    ("required_pull_request_reviews.dismissal_restrictions.teams", ["core"],
     [{"slug": "core", "name": "Core", "id": 1, "type": "organization"}]),
]


def _nest(path: str, value: object) -> dict:
    doc: object = value
    for part in reversed(path.split(".")):
        doc = {part: doc}
    assert isinstance(doc, dict)
    return doc


@pytest.mark.parametrize("path,write,read", _WRITE_VS_READ)
def test_write_shape_names_match_read_shape_objects(path: str, write: list, read: list) -> None:
    assert diff_values(_nest(path, write), _nest(path, read)) == []


@pytest.mark.parametrize("path,write,read", _WRITE_VS_READ)
def test_write_shape_names_report_a_real_change(path: str, write: list, read: list) -> None:
    [(key, was, now)] = diff_values(_nest(path, ["someone-else"]), _nest(path, read))
    assert key == path
    assert was["removed"] == 1 and now["added"] == 1


def test_write_shape_protection_snapshot_is_clean_against_the_read(world) -> None:
    doc = _protection(True)
    doc["restrictions"] = {"users": ["octocat"], "teams": ["core"], "apps": ["deploy-bot"]}
    live = _protection(True)
    live["restrictions"] = {"users": [_user("octocat", 1)],
                            "teams": [{"slug": "core", "name": "Core", "id": 1}],
                            "apps": [{"slug": "deploy-bot", "name": "Deploy Bot", "id": 9}]}
    world.track(".github/branch-protection/main.json", doc)
    world.serve("protection.json", live)
    block = scan_config_drift(world.root)
    assert block["available"] is True and block["entries"] == []

"""Tests for the B3 static-vs-historical disagreement cross (coupling_analysis).

The inputs (per-directory containment ratios + an optional per-directory
static-modularity view) are **mocked directly** rather than derived from real
git histories and grimp graphs: B3 is a pure function of those two upstream
signals, which already have their own contract tests (test_change_coupling.py,
test_structure_graph.py). Mocking keeps these tests fast and makes the
disagreement logic auditable in isolation. Expected classifications are spelled
out in each test so the contract is explicit.
"""
from __future__ import annotations

from lib.coupling_analysis import (
    DEFAULT_HIGH_CONTAINMENT,
    DEFAULT_LOW_CONTAINMENT,
    detect_hidden_coupling,
    find_refactor_boundaries,
)


def _finding_for(results: list[dict], path: str):
    """The `finding` for `path` in a results list, or KeyError-free None."""
    for r in results:
        if r["path"] == path:
            return r["finding"]
    return "ABSENT"


# --------------------------------------------------------------------------
# detect_hidden_coupling
# --------------------------------------------------------------------------

def test_high_static_modularity_plus_low_containment_is_hidden_coupling():
    """Looks modular statically (high Q) but bleeds historically -> hidden_coupling."""
    containment = {"pkg/a": 0.1}
    static = {"pkg/a": {"modularity_q": 0.6, "front_door_ratio": 0.95}}
    results = detect_hidden_coupling(containment, static_modularity=static)
    assert len(results) == 1
    entry = results[0]
    assert entry["finding"] == "hidden_coupling"
    assert entry["path"] == "pkg/a"
    assert entry["containment_ratio"] == 0.1
    assert "seam" in entry["recommendation"].lower()


def test_high_front_door_alone_triggers_hidden_coupling():
    """Front-door ratio high (A3) is enough to count as 'looks modular'."""
    containment = {"pkg/a": 0.2}
    # modularity low, but a clean front door -> still looks modular statically.
    static = {"pkg/a": {"modularity_q": 0.0, "front_door_ratio": 0.9}}
    results = detect_hidden_coupling(containment, static_modularity=static)
    assert _finding_for(results, "pkg/a") == "hidden_coupling"


def test_low_containment_no_static_input_is_bleeding_module():
    """No static graph at all -> graceful historical-only fallback label."""
    containment = {"pkg/a": 0.15}
    results = detect_hidden_coupling(containment, static_modularity=None)
    assert len(results) == 1
    assert results[0]["finding"] == "bleeding_module"
    assert results[0]["path"] == "pkg/a"


def test_low_containment_dir_absent_from_static_dict_is_bleeding_module():
    """Static graph present but no evidence for THIS dir -> per-dir fallback."""
    containment = {"pkg/a": 0.15}
    static = {"pkg/other": {"modularity_q": 0.6, "front_door_ratio": 0.9}}
    results = detect_hidden_coupling(containment, static_modularity=static)
    assert _finding_for(results, "pkg/a") == "bleeding_module"


def test_low_static_and_high_containment_is_suppressed():
    """Looks coupled statically + never co-changes (high containment) -> suppressed.

    The static graph already surfaces the coupling; with no behavioural bleed
    there is nothing new to flag, so the directory is simply omitted (it does
    not bleed, so it is not this function's concern).
    """
    containment = {"pkg/a": 0.95}  # high: edits stay contained
    static = {"pkg/a": {"modularity_q": -0.1, "front_door_ratio": 0.2}}
    results = detect_hidden_coupling(containment, static_modularity=static)
    assert results == []


def test_low_static_and_low_containment_agree_coupled_finding_none():
    """Static AND history agree it's coupled -> reported but finding=None (not hidden)."""
    containment = {"pkg/a": 0.1}  # bleeds
    static = {"pkg/a": {"modularity_q": -0.2, "front_door_ratio": 0.1}}  # looks coupled
    results = detect_hidden_coupling(containment, static_modularity=static)
    assert len(results) == 1
    assert results[0]["finding"] is None
    assert results[0]["path"] == "pkg/a"


def test_non_bleeding_dirs_are_omitted():
    """Directories at or above the low threshold are not hidden-coupling concerns."""
    containment = {"safe": 0.8, "edge": DEFAULT_LOW_CONTAINMENT, "bleeds": 0.1}
    results = detect_hidden_coupling(containment, static_modularity=None)
    paths = {r["path"] for r in results}
    assert paths == {"bleeds"}  # 0.8 and the 0.3 edge are excluded


def test_low_containment_threshold_is_strict_lower_bound():
    """containment == threshold is NOT low (boundary not flagged); just below IS."""
    containment = {"at": DEFAULT_LOW_CONTAINMENT, "below": DEFAULT_LOW_CONTAINMENT - 0.01}
    results = detect_hidden_coupling(containment, static_modularity=None)
    assert _finding_for(results, "at") == "ABSENT"
    assert _finding_for(results, "below") == "bleeding_module"


def test_custom_low_threshold_is_honoured():
    containment = {"pkg/a": 0.45}
    # default 0.3 would not flag 0.45; raise the bar to 0.5 and it bleeds.
    assert detect_hidden_coupling(containment, threshold_low_containment=0.3) == []
    results = detect_hidden_coupling(containment, threshold_low_containment=0.5)
    assert _finding_for(results, "pkg/a") == "bleeding_module"


def test_hidden_coupling_results_sorted_worst_bleed_first():
    containment = {"a": 0.05, "b": 0.25, "c": 0.15}
    results = detect_hidden_coupling(containment, static_modularity=None)
    assert [r["path"] for r in results] == ["a", "c", "b"]
    assert [r["containment_ratio"] for r in results] == [0.05, 0.15, 0.25]


def test_partial_static_metrics_only_modularity():
    """A static dict carrying only modularity_q (no front_door) still classifies."""
    containment = {"pkg/a": 0.2}
    static = {"pkg/a": {"modularity_q": 0.5}}  # front_door_ratio missing
    assert _finding_for(
        detect_hidden_coupling(containment, static_modularity=static), "pkg/a"
    ) == "hidden_coupling"


def test_empty_containment_returns_empty():
    assert detect_hidden_coupling({}, static_modularity=None) == []
    assert detect_hidden_coupling({}, static_modularity={}) == []


# --------------------------------------------------------------------------
# find_refactor_boundaries
# --------------------------------------------------------------------------

def test_high_containment_is_refactor_boundary():
    """High containment (> 0.7) -> safe zone, even with no static graph."""
    containment = {"pkg/island": 0.9}
    results = find_refactor_boundaries(containment)
    assert len(results) == 1
    entry = results[0]
    assert entry["finding"] == "refactor_boundary"
    assert entry["path"] == "pkg/island"
    assert entry["containment_ratio"] == 0.9
    assert "isolation" in entry["recommendation"].lower()


def test_high_containment_threshold_is_strict_upper_bound():
    """containment == threshold is NOT high enough; just above IS."""
    containment = {"at": DEFAULT_HIGH_CONTAINMENT, "above": DEFAULT_HIGH_CONTAINMENT + 0.01}
    results = find_refactor_boundaries(containment)
    paths = {r["path"] for r in results}
    assert paths == {"above"}


def test_low_containment_is_not_a_refactor_boundary():
    containment = {"pkg/bleeds": 0.2}
    assert find_refactor_boundaries(containment) == []


def test_refactor_boundary_static_agreement_enriches_recommendation():
    """A modular static boundary that agrees gets the 'lenses agree' note."""
    containment = {"pkg/clean": 0.9, "pkg/quiet": 0.85}
    static = {
        "pkg/clean": {"modularity_q": 0.6, "front_door_ratio": 0.95},  # looks modular
        "pkg/quiet": {"modularity_q": -0.1, "front_door_ratio": 0.2},  # looks coupled
    }
    results = find_refactor_boundaries(containment, static_modularity=static)
    by_path = {r["path"]: r for r in results}
    # Both qualify on containment; static only changes the wording.
    assert by_path["pkg/clean"]["finding"] == "refactor_boundary"
    assert by_path["pkg/quiet"]["finding"] == "refactor_boundary"
    assert "agree" in by_path["pkg/clean"]["recommendation"].lower()
    assert "agree" not in by_path["pkg/quiet"]["recommendation"].lower()


def test_refactor_boundaries_sorted_safest_first():
    containment = {"a": 0.75, "b": 0.99, "c": 0.85}
    results = find_refactor_boundaries(containment)
    assert [r["path"] for r in results] == ["b", "c", "a"]


def test_custom_high_threshold_is_honoured():
    containment = {"pkg/a": 0.6}
    assert find_refactor_boundaries(containment, threshold_high_containment=0.7) == []
    results = find_refactor_boundaries(containment, threshold_high_containment=0.5)
    assert _finding_for(results, "pkg/a") == "refactor_boundary"


def test_refactor_empty_containment_returns_empty():
    assert find_refactor_boundaries({}) == []


# --------------------------------------------------------------------------
# The two functions partition the bleed/island space cleanly
# --------------------------------------------------------------------------

def test_hidden_coupling_and_refactor_boundaries_are_disjoint():
    """No directory is both a bleed concern and a safe refactor boundary."""
    containment = {"bleeds": 0.1, "island": 0.95, "middle": 0.5}
    static = {"bleeds": {"modularity_q": 0.6, "front_door_ratio": 0.9}}
    hidden = {r["path"] for r in detect_hidden_coupling(containment, static_modularity=static)}
    safe = {r["path"] for r in find_refactor_boundaries(containment, static_modularity=static)}
    assert hidden == {"bleeds"}
    assert safe == {"island"}
    assert hidden.isdisjoint(safe)
    # "middle" (0.3 <= c <= 0.7) is neither flagged nor declared safe.

"""Contract suite for the coverage-report parser.

The parser reads an *existing* coverage report (Cobertura ``coverage.xml`` or
``lcov.info``) into the shape ``scan_test_pressure`` consumes:
``{"_overall": float, "per_file": {relpath: line_rate}}``. These tests pin the
two parse formats, the detection search order, and the hard contract that any
absent or malformed input degrades to ``None`` rather than raising.

Expected ratios are hand-computed in the fixtures so the contract is auditable:
- ``fixtures/coverage.xml`` - root line-rate 0.75; src/a.py 0.8, src/b.py 0.5.
- ``fixtures/lcov.info`` - a: LH 8/LF 10 = 0.8; b: 2/10 = 0.2;
  overall (8+2)/(10+10) = 0.5.
"""
from __future__ import annotations

from pathlib import Path

from lib.coverage_report import (
    _parse_cobertura,
    _parse_lcov,
    detect_coverage_report,
    load_coverage_data,
)


# --- Cobertura ------------------------------------------------------------

def test_parse_cobertura_nested_schema(fixtures_dir: Path) -> None:
    result = _parse_cobertura(fixtures_dir / "coverage.xml")
    assert result is not None
    assert result["_overall"] == 0.75
    assert result["per_file"] == {"src/a.py": 0.8, "src/b.py": 0.5}


def test_parse_cobertura_flat_schema(tmp_path: Path) -> None:
    """A flat ``<coverage><classes><class>`` report (no ``<packages>``) parses
    via the same tree walk."""
    xml = (
        '<?xml version="1.0" ?>\n'
        '<coverage line-rate="0.6">\n'
        '  <classes>\n'
        '    <class filename="x.py" line-rate="0.6"/>\n'
        '  </classes>\n'
        '</coverage>\n'
    )
    path = tmp_path / "coverage.xml"
    path.write_text(xml)
    result = _parse_cobertura(path)
    assert result == {"_overall": 0.6, "per_file": {"x.py": 0.6}}


def test_parse_cobertura_malformed_returns_none(tmp_path: Path) -> None:
    path = tmp_path / "coverage.xml"
    path.write_text("<coverage line-rate=\"0.5\"><classes><not-closed")
    assert _parse_cobertura(path) is None


def test_parse_cobertura_absent_returns_none(tmp_path: Path) -> None:
    assert _parse_cobertura(tmp_path / "nope.xml") is None


# --- lcov -----------------------------------------------------------------

def test_parse_lcov(fixtures_dir: Path) -> None:
    result = _parse_lcov(fixtures_dir / "lcov.info")
    assert result is not None
    assert result["per_file"] == {"src/a.py": 0.8, "src/b.py": 0.2}
    assert result["_overall"] == 0.5


def test_parse_lcov_no_terminator_still_flushes(tmp_path: Path) -> None:
    """A record without ``end_of_record`` is flushed at EOF."""
    path = tmp_path / "lcov.info"
    path.write_text("SF:a.py\nLF:4\nLH:2\n")
    result = _parse_lcov(path)
    assert result == {"_overall": 0.5, "per_file": {"a.py": 0.5}}


def test_parse_lcov_zero_lines_returns_none(tmp_path: Path) -> None:
    """A record with LF:0 contributes nothing; an all-zero report degrades."""
    path = tmp_path / "lcov.info"
    path.write_text("SF:a.py\nLF:0\nLH:0\nend_of_record\n")
    assert _parse_lcov(path) is None


def test_parse_lcov_absent_returns_none(tmp_path: Path) -> None:
    assert _parse_lcov(tmp_path / "nope.info") is None


# --- detection ------------------------------------------------------------

def test_detect_prefers_cobertura_at_root(tmp_path: Path) -> None:
    (tmp_path / "coverage.xml").write_text("<coverage line-rate=\"0.5\"/>")
    (tmp_path / "lcov.info").write_text("SF:a\nLF:1\nLH:1\nend_of_record\n")
    assert detect_coverage_report(tmp_path) == {
        "source": "coverage.xml", "format": "cobertura"}


def test_detect_lcov_in_coverage_subdir(tmp_path: Path) -> None:
    (tmp_path / "coverage").mkdir()
    (tmp_path / "coverage" / "lcov.info").write_text(
        "SF:a\nLF:1\nLH:1\nend_of_record\n")
    assert detect_coverage_report(tmp_path) == {
        "source": "coverage/lcov.info", "format": "lcov"}


def test_detect_dot_coverage_directory(tmp_path: Path) -> None:
    (tmp_path / ".coverage").mkdir()
    (tmp_path / ".coverage" / "coverage.xml").write_text(
        "<coverage line-rate=\"0.5\"/>")
    assert detect_coverage_report(tmp_path) == {
        "source": ".coverage/coverage.xml", "format": "cobertura"}


def test_detect_dot_coverage_sqlite_file_out_of_scope(tmp_path: Path) -> None:
    """A bare ``.coverage`` SQLite *file* (not a directory) is never matched -
    reading it needs the coverage.py library, which is out of scope."""
    (tmp_path / ".coverage").write_text("SQLite format 3\x00binary junk")
    assert detect_coverage_report(tmp_path) is None


def test_detect_none_when_absent(tmp_path: Path) -> None:
    assert detect_coverage_report(tmp_path) is None


# --- load (end to end) ----------------------------------------------------

def test_load_cobertura_end_to_end(tmp_path: Path) -> None:
    (tmp_path / "coverage.xml").write_text(
        '<coverage line-rate="0.9"><classes>'
        '<class filename="m.py" line-rate="0.9"/></classes></coverage>')
    assert load_coverage_data(tmp_path) == {
        "_overall": 0.9, "per_file": {"m.py": 0.9}}


def test_load_returns_none_when_no_report(tmp_path: Path) -> None:
    assert load_coverage_data(tmp_path) is None


def test_load_malformed_report_degrades_to_none(tmp_path: Path) -> None:
    """Detected but unparseable -> None, never an exception."""
    (tmp_path / "coverage.xml").write_text("not xml at all <<<")
    assert load_coverage_data(tmp_path) is None


def test_lcov_path_normalised(tmp_path: Path) -> None:
    """lcov SF: paths are emitted as the runner saw them - absolute, or
    ./-prefixed. load_coverage_data normalises both to repo-relative POSIX keys
    so test_focus's exact-key lookup matches (#317). Resolving both sides keeps
    macOS /var vs /private/var from breaking the relative_to."""
    root = tmp_path / "repo"
    (root / "src").mkdir(parents=True)
    abs_a = (root / "src" / "a.ts").resolve()
    (root / "lcov.info").write_text(
        f"SF:{abs_a}\nLF:10\nLH:10\nend_of_record\n"
        "SF:./src/b.ts\nLF:10\nLH:9\nend_of_record\n"
        "SF:src/c.ts\nLF:4\nLH:1\nend_of_record\n",
        encoding="utf-8",
    )
    data = load_coverage_data(root)
    assert data is not None
    assert data["per_file"] == {"src/a.ts": 1.0, "src/b.ts": 0.9, "src/c.ts": 0.25}


def test_lcov_path_normalised_unresolved_root_and_outside_path(tmp_path: Path) -> None:
    """An unresolved root spelling still matches a resolved SF: path, and an
    absolute path outside the repo root is kept verbatim (no crash)."""
    root = tmp_path / "repo"
    (root / "coverage").mkdir(parents=True)
    abs_a = (root / "src" / "a.ts").resolve()
    (root / "coverage" / "lcov.info").write_text(
        f"SF:{abs_a}\nLF:2\nLH:1\nend_of_record\n"
        "SF:/elsewhere/x.ts\nLF:2\nLH:2\nend_of_record\n",
        encoding="utf-8",
    )
    data = load_coverage_data(tmp_path / "repo" / ".." / "repo")
    assert data is not None
    assert data["per_file"] == {"src/a.ts": 0.5, "/elsewhere/x.ts": 1.0}


def test_lcov_path_normalised_windows_relative(tmp_path: Path) -> None:
    """A Windows runner writes relative SF: paths with backslashes, with or
    without a .\\ prefix: both normalise to the repo-relative POSIX key."""
    (tmp_path / "lcov.info").write_text(
        "SF:.\\src\\a.ts\nLF:10\nLH:10\nend_of_record\n"
        "SF:src\\b.ts\nLF:10\nLH:9\nend_of_record\n",
        encoding="utf-8",
    )
    data = load_coverage_data(tmp_path)
    assert data is not None
    assert data["per_file"] == {"src/a.ts": 1.0, "src/b.ts": 0.9}

"""Dart capability entries (#352): linting and liveness for a Dart/Flutter repo.

A repository is Dart when it holds a ``pubspec.yaml`` outside excluded paths.
Linting is credited to the analyzer when the nearest ``analysis_options.yaml``
enables lint rules and honest-degrades naming ``dart analyze`` otherwise. Liveness always
honest-degrades naming the analyzer's built-in ``unused_*`` diagnostics, never a
third-party package, and ``dead_code.tools`` carries a matching Dart entry.
"""
from __future__ import annotations

import json
from pathlib import Path

from assess_core import build_run_context
from lib.dart_capabilities import scan_dart_capabilities
from lib.liveness_scan import scan_liveness


def _write(root: Path, rel: str, text: str = "x") -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _flutter_app(root: Path, *, analysis_options: bool) -> Path:
    """A Flutter app with its generated Gradle wrapper, as `flutter create` lays it out."""
    _write(root, "pubspec.yaml", "name: demo\n")
    _write(root, "lib/main.dart", "void main() {}\n")
    _write(root, "android/build.gradle.kts", "plugins {}\n")
    _write(root, "android/app/build.gradle.kts", "plugins {}\n")
    if analysis_options:
        _write(root, "analysis_options.yaml",
               "include: package:flutter_lints/flutter.yaml\n")
    return root


def _dart_tools(dead_code: dict) -> list[dict]:
    return [t for t in dead_code.get("tools", []) if t.get("language") == "dart"]


# ── detection ──────────────────────────────────────────────────────────────

def test_no_pubspec_is_not_dart(tmp_path: Path) -> None:
    _write(tmp_path, "a.py", "x = 1\n")
    _write(tmp_path, "analysis_options.yaml", "linter: {}\n")
    assert scan_dart_capabilities(tmp_path) == {"available": False, "pubspec_files": []}


def test_pubspec_under_excluded_path_is_not_dart(tmp_path: Path) -> None:
    _write(tmp_path, "node_modules/pkg/pubspec.yaml", "name: vendored\n")
    _write(tmp_path, "tests/fixtures/app/pubspec.yaml", "name: fixture\n")
    assert scan_dart_capabilities(tmp_path)["available"] is False


def test_pubspec_under_user_exclude_is_not_dart(tmp_path: Path) -> None:
    _write(tmp_path, "vendor_sdk/pubspec.yaml", "name: sdk\n")
    result = scan_dart_capabilities(tmp_path, extra_exclude_dirs={"vendor_sdk"})
    assert result["available"] is False


# ── linting ────────────────────────────────────────────────────────────────

def test_linting_credited_when_analysis_options_present(tmp_path: Path) -> None:
    result = scan_dart_capabilities(_flutter_app(tmp_path, analysis_options=True))
    linting = result["capabilities"]["linting"]
    assert linting["state"] == "credited"
    assert linting["served_by"] == ["dart analyze"]
    assert "analysis_options.yaml" in linting["note"]
    assert {"candidate_tool", "gloss", "note"} <= linting.keys()


def test_linting_credits_flutter_analyze_for_a_flutter_package(tmp_path: Path) -> None:
    _flutter_app(tmp_path, analysis_options=True)
    _write(tmp_path, "pubspec.yaml",
           "name: demo\ndependencies:\n  flutter:\n    sdk: flutter\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["served_by"] == ["flutter analyze"]


def test_analysis_options_in_an_ancestor_directory_credits_linting(tmp_path: Path) -> None:
    # The analyzer resolves analysis_options.yaml by walking up from each file,
    # so a monorepo root config serves a nested package.
    _write(tmp_path, "analysis_options.yaml", "include: package:lints/core.yaml\n")
    _write(tmp_path, "packages/core/pubspec.yaml", "name: core\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "credited"


def test_analysis_options_outside_every_package_does_not_credit(tmp_path: Path) -> None:
    _write(tmp_path, "pubspec.yaml", "name: demo\n")
    _write(tmp_path, "tool/analysis_options.yaml", "include: package:lints/core.yaml\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "honest_degrade"


def test_analysis_options_that_enables_no_rules_does_not_credit(tmp_path: Path) -> None:
    # Dart lints are opt-in: an exclude-only file (the usual codegen workaround)
    # enables no rule, so it must not read as served linting.
    _write(tmp_path, "pubspec.yaml", "name: demo\n")
    _write(tmp_path, "analysis_options.yaml",
           "# include: package:lints/recommended.yaml\n"
           "analyzer:\n  exclude:\n    - \"**/*.g.dart\"\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "honest_degrade"
    assert "enables no lint rules" in linting["note"]


def test_analysis_options_with_linter_rules_credits(tmp_path: Path) -> None:
    _write(tmp_path, "pubspec.yaml", "name: demo\n")
    _write(tmp_path, "analysis_options.yaml",
           "analyzer:\n  exclude: []\nlinter:\n  rules:\n    - avoid_print\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "credited"


def test_linter_rules_after_a_comment_and_a_blank_line_credit(tmp_path: Path) -> None:
    _write(tmp_path, "pubspec.yaml", "name: demo\n")
    _write(tmp_path, "analysis_options.yaml",
           "linter:\n  # house rules\n\n  rules:\n    - avoid_print\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "credited"


def test_rules_under_another_top_level_key_does_not_credit(tmp_path: Path) -> None:
    _write(tmp_path, "pubspec.yaml", "name: demo\n")
    _write(tmp_path, "analysis_options.yaml",
           "linter:\n  enabled: true\nformatter:\n  rules: []\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "honest_degrade"


def test_long_linter_block_without_rules_is_linear(tmp_path: Path) -> None:
    # A linter: block of many indented lines and no rules: child used to
    # backtrack exponentially in a regex; the line scan must stay linear.
    import time
    _write(tmp_path, "pubspec.yaml", "name: demo\n")
    body = "".join(f"    key{i}: value {i}\n" for i in range(30))
    _write(tmp_path, "analysis_options.yaml", "linter:\n" + body + "  \n")
    start = time.monotonic()
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert time.monotonic() - start < 2.0
    assert linting["state"] == "honest_degrade"


def test_nearest_analysis_options_decides(tmp_path: Path) -> None:
    # The analyzer uses the nearest file only: a package-level file that enables
    # nothing shadows a root file that does.
    _write(tmp_path, "analysis_options.yaml", "include: package:lints/core.yaml\n")
    _write(tmp_path, "packages/core/pubspec.yaml", "name: core\n")
    _write(tmp_path, "packages/core/analysis_options.yaml",
           "analyzer:\n  exclude: []\n")
    linting = scan_dart_capabilities(tmp_path)["capabilities"]["linting"]
    assert linting["state"] == "honest_degrade"


def test_linting_honest_degrades_without_analysis_options(tmp_path: Path) -> None:
    result = scan_dart_capabilities(_flutter_app(tmp_path, analysis_options=False))
    linting = result["capabilities"]["linting"]
    assert linting["state"] == "honest_degrade"
    assert "dart analyze" in linting["candidate_tool"]
    assert "served_by" not in linting


# ── liveness ───────────────────────────────────────────────────────────────

def test_liveness_names_the_analyzer_unused_lints(tmp_path: Path) -> None:
    for with_options in (True, False):
        root = tmp_path / str(with_options)
        liveness = scan_dart_capabilities(
            _flutter_app(root, analysis_options=with_options))["capabilities"]["liveness"]
        assert liveness["state"] == "honest_degrade"
        assert "unused_" in liveness["candidate_tool"]
        assert "dart_code_metrics" not in json.dumps(liveness)


def test_dead_code_tools_carry_one_dart_honest_degrade_entry(tmp_path: Path) -> None:
    out = scan_liveness(_flutter_app(tmp_path, analysis_options=True), run_dead_code=False)
    dart = _dart_tools(out["dead_code"])
    assert len(dart) == 1
    assert dart[0]["status"] == "honest_degrade"
    assert "unused_" in dart[0]["tool"]
    assert dart[0]["reason"]
    assert out["dead_code"]["available"] is False


def test_non_dart_repo_gets_no_dart_tool_entry(tmp_path: Path) -> None:
    _write(tmp_path, "a.py", "x = 1\n")
    out = scan_liveness(tmp_path, run_dead_code=False)
    assert _dart_tools(out["dead_code"]) == []
    assert "dart_capabilities" not in out


# ── run-context wiring ─────────────────────────────────────────────────────

def test_run_context_carries_language_capabilities_dart(tmp_path: Path) -> None:
    ctx = build_run_context(repo_root=_flutter_app(tmp_path, analysis_options=True),
                            run_date="2026-09-18", non_interactive=True)
    dart = ctx["language_capabilities"]["dart"]
    assert set(dart) == {"linting", "liveness"}
    assert dart["linting"]["state"] == "credited"
    assert dart["liveness"]["state"] == "honest_degrade"
    # The Gradle wrapper under android/ is not a JVM codebase: no JVM offer, no
    # JVM tool named anywhere.
    blob = json.dumps([ctx.get("capability_offers"), ctx["language_capabilities"],
                       ctx["dead_code"]])
    for jvm_name in ("mvn", "jdeps", "Checkstyle", "OpenRewrite"):
        assert jvm_name not in blob
    assert "dart_code_metrics" not in blob


def test_run_context_omits_language_capabilities_without_dart(tmp_path: Path) -> None:
    _write(tmp_path, "a.py", "x = 1\n")
    ctx = build_run_context(repo_root=tmp_path, run_date="2026-09-18",
                            non_interactive=True)
    assert "dart" not in (ctx.get("language_capabilities") or {})

"""Tests for lib.dart_complexity, the approximate Dart per-function scanner
(issue #364)."""
from __future__ import annotations

import time
from pathlib import Path

import pytest

from lib import dart_complexity
from lib.dart_complexity import dart_function_scores, scan_dart_functions

# The acceptance fixture: routeOrder has 10 decision points in its own body and
# 1 in a nested closure (ccn 12 with the closure folded in), behind about 20
# decoy keywords and unbalanced braces in comments and strings.
ROUTE_ORDER = """\
// Decoys: if (a && b) { while (x) { for (;;) {} } }
/* block comment: if else if while for && || { */
int helper(int v) {
  return v + 1;
}

int routeOrder(int a, int b, List<int> items) {
  var label = "if (a && b) { while (true) { ";
  var banner = \"\"\"
    if (x) { for (;;) { while (y || z) {
  \"\"\";
  // if (total > 5 && a < b) { while (true) {
  var total = 0;
  if (a > 0 && b > 0) {
    total += 1;
  } else if (a < 0 || b < 0) {
    total -= 1;
  }
  for (var i = 0; i < a; i++) {
    if (i == b) {
      total += i;
    }
  }
  while (total > 100) {
    total -= 10;
  }
  if (items.isEmpty) {
    return total;
  }
  for (final item in items) {
    if (item > total) {
      total = item;
    }
  }
  final bump = (int v) {
    if (v > 3) {
      return v + helper(v);
    }
    return v;
  };
  return bump(total) + label.length + banner.length;
}
"""


def test_dart_scanner_scores_route_order_fixture(tmp_path: Path) -> None:
    assert scan_dart_functions(ROUTE_ORDER) == [
        ("helper", 1.0), ("routeOrder", 12.0)]
    f = tmp_path / "order.dart"
    f.write_text(ROUTE_ORDER)
    assert dart_function_scores(f) == ([1.0, 12.0], "routeOrder")


def test_dart_scanner_skips_every_string_and_comment_form() -> None:
    """Raw, escaped, triple-quoted and nested-comment decoys add nothing;
    ${...} interpolation is code and counts."""
    src = r"""
int f(bool c, String x) {
  var a = r'if (x) { \' ;
  var b = 'it\'s if && { ';
  var d = r'''if { while ''';
  var e = '''if {
  for ( ''';
  /* outer /* inner if { */ still comment while { */
  var g = "${c ? 'if {' : "while"} $x if {";
  return 0;
}
"""
    assert scan_dart_functions(src) == [("f", 2.0)]


def test_dart_scanner_folds_closures_and_scores_named_locals_apart() -> None:
    src = """
void main() {
  items.forEach((i) { if (i > 0) {} });
  final xs = items.where((i) => i > 0 && i < 9);
  bool inner(int k) { while (k > 0) { k--; } return true; }
}
"""
    assert scan_dart_functions(src) == [("main", 3.0), ("inner", 2.0)]


def test_dart_scanner_scores_top_level_closures_as_anonymous() -> None:
    src = """
final isReady = (x) => x > 0 && ready;
final handler = (req) { if (req.ok) {} };
"""
    assert scan_dart_functions(src) == [
        ("<anonymous>", 2.0), ("<anonymous>", 2.0)]


def test_dart_scanner_names_getters_generics_and_arrow_bodies() -> None:
    src = """
class A<T> extends B<T> {
  int get size => n > 0 ? n : 0;
  set size(int v) { if (v < 0) throw 1; }
  Future<void> load<R>(R r) async { try { await f(); } on E catch (e) {} }
  String? label(int? n) => n?.toString() ?? 'none';
}
"""
    assert scan_dart_functions(src) == [
        ("size", 2.0), ("size", 2.0), ("load", 2.0), ("label", 2.0)]


@pytest.mark.parametrize("text", [
    "void f() {" + "{" * 200_000,
    "void f() {" * 100_000,
    "void f() {" * 50_000 + "}" * 50_000,
    "void f() { var s = '" + "if (x) " * 50_000,
    "void f() { var s = '''" + "${" * 50_000,
    "/*" * 100_000,
    "void f() { if (a && b || c) {} } " * 10_000,
    "x" * 1_000_000,
], ids=["deep-nesting", "unclosed-functions", "nested-functions", "unterminated-string", "unterminated-interpolation",
        "nested-comment", "long-line", "one-token"])
def test_dart_scanner_pathological_input_is_fast(text: str) -> None:
    start = time.perf_counter()
    scan_dart_functions(text)
    assert time.perf_counter() - start < 1.0


def test_dart_scanner_reads_a_bounded_prefix(tmp_path: Path,
                                             monkeypatch) -> None:
    monkeypatch.setattr(dart_complexity, "_READ_BYTES", 64)
    f = tmp_path / "big.dart"
    f.write_text("int a() { return 1; }\n" + " " * 100
                 + "int b(x) { if (x) {} }\n")
    assert dart_function_scores(f) == ([1.0], "a")


def test_dart_scanner_unreadable_or_empty_file_has_no_functions(
        tmp_path: Path) -> None:
    assert dart_function_scores(tmp_path / "missing.dart") == ([], None)
    empty = tmp_path / "empty.dart"
    empty.write_text("// only a comment\n")
    assert dart_function_scores(empty) == ([], None)

"""Tests for decline-marker provenance + re-offer-on-major-bump (Task 12)."""
from __future__ import annotations

import json
from pathlib import Path

from lib.decline_markers import (
    build_decline_block,
    read_decline_markers,
)


def _assess(tmp_path: Path) -> Path:
    d = tmp_path / ".assess"
    d.mkdir(parents=True, exist_ok=True)
    return d


def _write_marker(assess_dir: Path, tool: str, payload: object) -> None:
    p = assess_dir / f".no-{tool}"
    if isinstance(payload, str):
        p.write_text(payload, encoding="utf-8")
    else:
        p.write_text(json.dumps(payload), encoding="utf-8")


# ── provenance recording ────────────────────────────────────────────────────

def test_provenance_recorded(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "mutmut", {
        "declined_by": "ben",
        "declined_at": "2026-07-07",
        "plugin_version": "1.54.4",
        "reason": "pure-docs repo",
    })
    markers = read_decline_markers(d, "1.54.4")
    assert len(markers) == 1
    m = markers[0]
    assert m.tool == "mutmut"
    assert m.path == ".no-mutmut"
    assert m.declined_by == "ben"
    assert m.declined_at == "2026-07-07"
    assert m.version == "1.54.4"
    assert m.reason == "pure-docs repo"
    assert m.reoffer is False


def test_block_shape(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "scc", {
        "declined_by": "ben", "declined_at": "2026-07-07",
        "plugin_version": "1.54.4",
    })
    block = build_decline_block(d, "1.54.4")
    assert set(block) == {"markers", "reoffer_mutation", "disclosures"}
    entry = block["markers"][0]
    assert set(entry) >= {
        "path", "tool", "declined_by", "declined_at", "version", "reason",
        "reoffer",
    }


# ── disclosure in report ────────────────────────────────────────────────────

def test_disclosure_names_user_and_date(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "mutmut", {
        "declined_by": "ben", "declined_at": "2026-07-07",
        "plugin_version": "1.54.4",
    })
    block = build_decline_block(d, "1.54.4")
    disclosure = block["disclosures"][0]
    assert "Mutation testing permanently declined by ben on 2026-07-07" in disclosure


def test_disclosure_legacy_unknown(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "scc", "")  # legacy empty touch file
    block = build_decline_block(d, "1.54.4")
    disclosure = block["disclosures"][0]
    assert "an unknown user" in disclosure
    assert "an unknown date" in disclosure


# ── re-offer on major bump ──────────────────────────────────────────────────

def test_major_bump_sets_reoffer(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "mutmut", {
        "declined_by": "ben", "declined_at": "2025-01-01",
        "plugin_version": "1.9.0",
    })
    block = build_decline_block(d, "2.0.0")
    assert block["reoffer_mutation"] is True
    assert block["markers"][0]["reoffer"] is True
    # A mutation tool IS re-offered (Step 2d), so its disclosure says so.
    assert "re-offer eligible" in block["disclosures"][0]


def test_minor_bump_no_reoffer(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "mutmut", {
        "declined_by": "ben", "declined_at": "2026-06-01",
        "plugin_version": "1.50.0",
    })
    block = build_decline_block(d, "1.54.4")
    assert block["reoffer_mutation"] is False
    assert block["markers"][0]["reoffer"] is False


def test_patch_bump_no_reoffer(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "stryker", {
        "declined_by": "ben", "declined_at": "2026-07-01",
        "plugin_version": "1.54.3",
    })
    block = build_decline_block(d, "1.54.4")
    assert block["reoffer_mutation"] is False


def test_reoffer_only_for_mutation_tools(tmp_path: Path) -> None:
    # An old-major dead-code linter decline must not trip reoffer_mutation.
    d = _assess(tmp_path)
    _write_marker(d, "vulture", {
        "declined_by": "ben", "declined_at": "2025-01-01",
        "plugin_version": "1.0.0",
    })
    block = build_decline_block(d, "2.0.0")
    assert block["reoffer_mutation"] is False
    # ...but the marker itself is still flagged reoffer-eligible for its own line.
    assert block["markers"][0]["reoffer"] is True
    # The disclosure must NOT claim "re-offer eligible": only mutation tools are
    # re-offered (Step 2d); Step 2b never re-asks a linter decline, so promising
    # a re-offer here would be a lying map.
    assert "re-offer eligible" not in block["disclosures"][0]


# ── legacy / malformed markers degrade gracefully ───────────────────────────

def test_legacy_empty_marker_no_crash(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "mutmut", "")
    markers = read_decline_markers(d, "2.0.0")
    assert len(markers) == 1
    m = markers[0]
    assert m.version is None
    assert m.declined_by is None
    # Legacy markers have no major to compare, so they are never auto-re-offered.
    assert m.reoffer is False


def test_non_json_marker_no_crash(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "scc", "declined by hand\n")
    markers = read_decline_markers(d, "1.54.4")
    assert markers[0].version is None
    assert markers[0].reason is None


def test_no_assess_dir(tmp_path: Path) -> None:
    assert read_decline_markers(tmp_path / ".assess", "1.54.4") == []
    block = build_decline_block(tmp_path / ".assess", "1.54.4")
    assert block["markers"] == []
    assert block["reoffer_mutation"] is False


def test_markers_sorted_stable(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "scc", "")
    _write_marker(d, "mutmut", "")
    _write_marker(d, "vulture", "")
    tools = [m.tool for m in read_decline_markers(d, "1.54.4")]
    assert tools == sorted(tools)


def test_malformed_version_no_reoffer(tmp_path: Path) -> None:
    d = _assess(tmp_path)
    _write_marker(d, "mutmut", {
        "declined_by": "ben", "declined_at": "2025-01-01",
        "plugin_version": "not-a-version",
    })
    block = build_decline_block(d, "2.0.0")
    assert block["reoffer_mutation"] is False

"""Parity harness for the Part 3 SKILL.md decomposition.

The decomposition (orchestrator + layer-scorer agent + findings-writer sub-skill
+ pr-and-issues sub-skill) must be *behaviour-preserving*: it only reorganizes
Markdown and touches zero Python, so the deterministic pipeline
(``assess_core.build_run_context`` -> ``assess_report.render_report``) must
produce the byte-for-byte identical report it did before.

This module pins that invariant two ways:

1. **Report parity.** Build a fixed first-run fixture, render the deterministic
   report, normalize it (golden.normalize_report masks the version/commit
   provenance lines), and assert it equals the committed golden. A first-run
   fixture is used so the diff section and measured-commit provenance are
   deterministic (no prior sidecar, no git work-tree).
2. **Structural contract.** The decomposed units exist on disk and the
   orchestrator SKILL.md delegates to each of them, so a future edit that
   re-inlines or drops a unit fails loudly.
"""
from __future__ import annotations

import json
from pathlib import Path

from assess_core import build_run_context
from assess_report import render_report
from golden import normalize_report

# skills/assess/tests/ -> repo root is three parents up from this file's dir.
REPO_ROOT = Path(__file__).resolve().parents[3]
ASSESS_SKILL = REPO_ROOT / "skills" / "assess" / "SKILL.md"
GOLDEN = Path(__file__).parent / "fixtures" / "golden" / "decomposition-parity-report.md"


def _build_parity_fixture(repo: Path) -> Path:
    """Create the deterministic first-run fixture the golden was captured from.

    Plain dir (no git) + a fixed complexity-stats sidecar + a CLAUDE.md, so the
    pipeline output depends only on these inputs and the passed run_date.
    """
    repo.mkdir()
    assess = repo / ".assess"
    assess.mkdir()
    stats = {
        "files_scored": 3,
        "loc": {"p50": 30.0, "p95": 200.0, "max": 500.0, "total": 600},
        "ccn": {"p50": 2.0, "p95": 8.0, "max": 20.0, "basis": "file-aggregate"},
        "top_hotspots": [
            {"path": "src/a.py", "loc": 500, "ccn": 20.0, "commits": 5},
            {"path": "src/b.py", "loc": 80, "ccn": 6.0, "commits": 2},
        ],
        "top_complex": [{"path": "src/a.py", "ccn": 20}],
        "top_large": [{"path": "src/a.py", "loc": 500}],
    }
    (assess / "complexity-stats.json").write_text(json.dumps(stats))
    (repo / "CLAUDE.md").write_text("# Project\n\nDo X. Always Y. Never Z.\n")
    return repo


def _render_parity_report(repo: Path) -> str:
    ctx = build_run_context(repo_root=repo, run_date="2026-01-01")
    return normalize_report(render_report(ctx, "parity-fixture"))


def test_report_parity_matches_golden(tmp_path):
    """The deterministic report must reproduce the committed golden byte-for-byte."""
    repo = _build_parity_fixture(tmp_path / "repo")
    assert _render_parity_report(repo) == GOLDEN.read_text(encoding="utf-8")


def test_report_render_is_deterministic(tmp_path):
    """Two independent builds of the same fixture render identical reports."""
    a = _render_parity_report(_build_parity_fixture(tmp_path / "a"))
    b = _render_parity_report(_build_parity_fixture(tmp_path / "b"))
    assert a == b


# --- structural contract: the decomposed units exist and are wired up --------

def test_layer_scorer_agent_exists():
    agent = REPO_ROOT / "agents" / "assess-layer-scorer.md"
    assert agent.is_file()
    assert agent.read_text(encoding="utf-8").startswith("---")


def test_findings_and_pr_subskills_exist():
    for name in ("assess-findings", "assess-pr"):
        skill = REPO_ROOT / "skills" / name / "SKILL.md"
        assert skill.is_file(), f"missing decomposed sub-skill: {name}"
        assert "TRIGGER" in skill.read_text(encoding="utf-8"), f"{name}: needs TRIGGER clause"


def test_orchestrator_delegates_to_each_unit():
    body = ASSESS_SKILL.read_text(encoding="utf-8")
    assert "assess-layer-scorer" in body, "orchestrator must delegate layer scoring"
    assert "assess-findings" in body, "orchestrator must delegate report writing"
    assert "assess-pr" in body, "orchestrator must delegate end-of-run offers"


def test_orchestrator_is_thin():
    """The monolith was ~1290 lines; the thin orchestrator must stay well under."""
    lines = ASSESS_SKILL.read_text(encoding="utf-8").splitlines()
    assert len(lines) < 500, f"orchestrator grew to {len(lines)} lines - re-check the seams"


def test_attention_low_signal_is_read_before_the_rule_that_uses_it():
    """The findings sub-skill's run-context read loads every key its Top 3 rule branches on."""
    body = (REPO_ROOT / "skills" / "assess-findings" / "SKILL.md").read_text()
    read = next(line for line in body.splitlines() if line.startswith("jq ") and ".prescribed_actions" in line)
    rule = next(line for line in body.splitlines() if line.startswith("**Mandatory attention rule"))
    for key in ("attention", "attention_low_signal", "prescribed_actions", "gap_actions"):
        assert f"`{key}`" in rule
        assert f".{key}," in read or read.rstrip().split("'")[1].endswith(f".{key}")

"""Tests for Signal C: the complexity x doc-state join.

Inputs are MOCKED dicts shaped like the real artifacts (``complexity-stats.json``
and ``analyze_doc_staleness``'s return) -- no git, no filesystem -- so every
``doc_value`` below is hand-computable from the documented formula:

    freshness  = clamp((T - ratio) / T, -1, +1),   T = STALENESS_RATIO_THRESHOLD = 2.0
    doc_value  = complexity_summarised x freshness
    threshold  = max(ccn.p95, MIN_HIGH_CCN=10)
"""
from __future__ import annotations

import json
from pathlib import Path

from lib.doc_complexity_join import (
    MIN_HIGH_CCN,
    STALENESS_RATIO_THRESHOLD,
    analyze_doc_complexity_join,
)

# A repo whose 95th-percentile CCN (8) sits below the McCabe floor, so the
# high-complexity gate is the floor, 10. core.py (CCN 30) is "complex";
# helper.py (CCN 2) is trivial.
COMPLEXITY_STATS = {
    "ccn": {"p50": 3.0, "p95": 8.0, "max": 30.0},
    "files_scored": 2,
    "top_complex": [
        {"path": "pkg/engine/core.py", "loc": 400, "ccn": 30.0, "commits": 50},
        {"path": "pkg/util/helper.py", "loc": 20, "ccn": 2.0, "commits": 1},
    ],
    "top_hotspots": [],
    "top_large": [],
}


def _staleness(docs: list[dict]) -> dict:
    return {"available": True, "churn_window": "12mo", "docs": docs}


def _doc(path: str, ratio: float, confidence: str = "high") -> dict:
    return {
        "path": path,
        "ratio": ratio,
        "last_commit_days": 10,
        "doc_churn_in_window": 4,
        "code_churn_in_window": int(ratio * 4),
        "subject_code_count": 1,
        "subject_method": "nearest-ancestor",
        "confidence": confidence,
    }


def _by_path(result: dict) -> dict[str, dict]:
    return {u["path"]: u for u in result["docs"]}


def test_complex_plus_fresh_is_good_contract() -> None:
    """Fresh doc (ratio 0.5) over CCN-30 code -> good_contract, positive value."""
    staleness = _staleness([_doc("pkg/engine/README.md", ratio=0.5)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    doc = _by_path(result)["pkg/engine/README.md"]
    # freshness = (2.0 - 0.5) / 2.0 = 0.75 ; doc_value = 30 * 0.75 = 22.5
    assert doc["complexity_summarised"] == 30.0
    assert doc["freshness"] == 0.75
    assert doc["doc_value"] == 22.5
    assert doc["doc_value"] > 0
    assert doc["finding"] == "good_contract"
    assert [u["path"] for u in result["findings"]["good_contracts"]] == [
        "pkg/engine/README.md"
    ]


def test_complex_plus_stale_is_lying_map_negative_value() -> None:
    """Stale doc (ratio 6.0) over CCN-30 code -> lying_map, NEGATIVE value."""
    staleness = _staleness([_doc("pkg/engine/README.md", ratio=6.0)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    doc = _by_path(result)["pkg/engine/README.md"]
    # freshness = clamp((2 - 6) / 2, -1, 1) = -1.0 ; doc_value = 30 * -1 = -30
    assert doc["freshness"] == -1.0
    assert doc["doc_value"] == -30.0
    assert doc["doc_value"] < 0
    assert doc["finding"] == "lying_map"
    # Slop-doc guard: the recommendation never says "auto-generate".
    rec = doc["recommendation"].lower()
    assert "delete" in rec
    assert "auto-generate" in rec  # ...prefixed by "do not"
    assert "do not auto-generate" in rec


def test_degenerate_churn_caps_confidence_and_suppresses_lying_map() -> None:
    """Issue #172: a precise (nearest-ancestor, high-confidence) association over
    a DEGENERATE churn history must not stamp a lying_map. The churn count means
    nothing - confidence encodes association precision, not measurement
    reliability - so the join caps confidence to 'low' (the existing guard then
    suppresses the finding). Same stale ratio and high confidence as the
    lying_map case; only ``churn_degenerate`` differs."""
    staleness = _staleness([_doc("pkg/engine/README.md", ratio=6.0)])
    staleness["churn_degenerate"] = True
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    doc = _by_path(result)["pkg/engine/README.md"]
    # The ratio still computes negative freshness from the inflated churn...
    assert doc["freshness"] == -1.0
    # ...but the measurement is unreliable: confidence is capped and no lie called.
    assert doc["confidence"] == "low"
    assert doc["finding"] is None
    assert result["findings"]["lying_maps"] == []


def test_non_degenerate_churn_preserves_high_confidence_lying_map() -> None:
    """Regression guard: with genuine churn variance (churn_degenerate False, the
    default) the same precise association still produces a high-confidence
    lying_map - the fix must not blunt real findings."""
    staleness = _staleness([_doc("pkg/engine/README.md", ratio=6.0)])
    staleness["churn_degenerate"] = False
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    doc = _by_path(result)["pkg/engine/README.md"]
    assert doc["confidence"] == "high"
    assert doc["finding"] == "lying_map"
    assert [u["path"] for u in result["findings"]["lying_maps"]] == [
        "pkg/engine/README.md"
    ]


def test_low_confidence_stale_doc_is_not_a_lying_map() -> None:
    """A stale-by-ratio doc whose staleness is low-confidence (subject_method ==
    'repo-baseline') must NOT be classified a lying_map: the ratio is measured
    against repo-wide churn, not the code the doc describes, so a doc edited
    today reads as 'stale' purely because the repo is busy. Mirrors the Layer 0
    stale-hub confidence guard. Same ratio as the lying_map case above, only the
    confidence differs."""
    staleness = _staleness(
        [_doc("pkg/engine/README.md", ratio=6.0, confidence="low")])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    doc = _by_path(result)["pkg/engine/README.md"]
    # freshness still computes negative from the coarse ratio...
    assert doc["freshness"] == -1.0
    # ...but the low-confidence signal is too coarse to call a lie.
    assert doc["finding"] is None
    assert result["findings"]["lying_maps"] == []


def test_complex_plus_no_doc_is_unexplained_complexity() -> None:
    """CCN-30 code with no doc covering it -> unexplained_complexity, value 0."""
    # Only a doc far away that covers nothing complex.
    staleness = _staleness([_doc("docs/unrelated/notes.md", ratio=0.5)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    core = _by_path(result)["pkg/engine/core.py"]
    assert core["finding"] == "unexplained_complexity"
    assert core["freshness"] == 0.0
    assert core["doc_value"] == 0.0  # missing -> 0
    assert [u["path"] for u in result["findings"]["unexplained_complexity"]] == [
        "pkg/engine/core.py"
    ]
    # The recommendation forbids auto-generation (slop-doc guard).
    assert "do not auto-generate" in core["recommendation"].lower()


def test_trivial_file_has_near_zero_doc_value_and_no_finding() -> None:
    """A doc over CCN-2 code scores ~0 and raises no finding, fresh or stale."""
    staleness = _staleness([_doc("pkg/util/README.md", ratio=0.5)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))

    doc = _by_path(result)["pkg/util/README.md"]
    # complexity_summarised = 2 (helper.py) ; freshness 0.75 -> doc_value 1.5
    assert doc["complexity_summarised"] == 2.0
    assert doc["doc_value"] == 1.5
    assert abs(doc["doc_value"]) < MIN_HIGH_CCN  # negligible vs a real hotspot
    assert doc["finding"] is None
    # The trivial doc appears in no findings bucket. (core.py, which this doc
    # does not cover, is correctly surfaced as unexplained_complexity elsewhere.)
    flagged = {
        u["path"]
        for bucket in result["findings"].values()
        for u in bucket
    }
    assert "pkg/util/README.md" not in flagged
    assert result["findings"]["lying_maps"] == []
    assert result["findings"]["good_contracts"] == []


def test_slop_doc_guard_honest_gap_beats_lying_map() -> None:
    """An undocumented unit must score strictly safer than a hollow stale doc."""
    lying = analyze_doc_complexity_join(
        COMPLEXITY_STATS, _staleness([_doc("pkg/engine/README.md", ratio=6.0)]),
        Path("/repo"),
    )
    honest = analyze_doc_complexity_join(
        COMPLEXITY_STATS, _staleness([_doc("docs/unrelated/notes.md", ratio=0.5)]),
        Path("/repo"),
    )
    lying_value = lying["findings"]["lying_maps"][0]["doc_value"]
    honest_value = honest["findings"]["unexplained_complexity"][0]["doc_value"]
    assert honest_value > lying_value  # 0 > -30


def test_result_is_json_serialisable() -> None:
    staleness = _staleness([
        _doc("pkg/engine/README.md", ratio=6.0),
        _doc("pkg/util/README.md", ratio=0.5),
    ])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("/repo"))
    # Round-trips without error and preserves the threshold contract.
    reloaded = json.loads(json.dumps(result))
    assert reloaded["available"] is True
    assert reloaded["high_ccn_threshold"] == max(8.0, MIN_HIGH_CCN)
    assert STALENESS_RATIO_THRESHOLD == 2.0


# --- Provenance-aware freshness for generated docs (issue #178) -----------

def _gen_doc(path: str, source_newer, ratio: float = 0.0,
             confidence: str = "low") -> dict:
    """A generated doc carrying a provenance verdict. ratio is deliberately set
    low/zero (the churn signal is irrelevant once provenance decides freshness)
    and confidence "low" to prove the provenance verdict bypasses the guard."""
    d = _doc(path, ratio, confidence=confidence)
    d["subject_method"] = "repo-baseline"
    d["provenance"] = {
        "method": "frontmatter",
        "sources": ["data/jira.tsv"],
        "generated_by": None,
        "source_newer": source_newer,
    }
    return d


def test_generated_doc_source_not_moved_is_not_lying_map() -> None:
    """source_newer False -> freshness +1 -> good_contract, never lying_map,
    even though the churn ratio is low-confidence (repo-baseline). This is the
    issue #178 hard requirement: an accurate generated doc is not a lying map."""
    staleness = _staleness([_gen_doc("pkg/engine/api.md", source_newer=False)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("."))
    api = _by_path(result)["pkg/engine/api.md"]
    assert api["freshness"] == 1.0
    assert api["finding"] == "good_contract"
    assert result["findings"]["lying_maps"] == []


def test_generated_doc_source_moved_on_is_lying_map() -> None:
    """source_newer True -> freshness -1 -> lying_map over complex code, and the
    repo-baseline low-confidence guard does NOT suppress it (the provenance
    verdict is a direct, high-confidence source comparison)."""
    staleness = _staleness([_gen_doc("pkg/engine/api.md", source_newer=True)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("."))
    api = _by_path(result)["pkg/engine/api.md"]
    assert api["freshness"] == -1.0
    assert api["finding"] == "lying_map"
    assert api["confidence"] == "high"
    assert [u["path"] for u in result["findings"]["lying_maps"]] == ["pkg/engine/api.md"]


def test_provenance_indeterminate_falls_back_to_ratio() -> None:
    """source_newer None (no usable timestamps) -> the churn ratio decides, so a
    busy-ratio repo-baseline doc stays unclassified under the low-confidence
    guard exactly as before provenance existed."""
    staleness = _staleness([_gen_doc("pkg/engine/api.md", source_newer=None,
                                      ratio=5.0)])
    result = analyze_doc_complexity_join(COMPLEXITY_STATS, staleness, Path("."))
    api = _by_path(result)["pkg/engine/api.md"]
    assert api["freshness"] < 0  # ratio 5 > threshold -> negative
    assert api["finding"] is None  # low-confidence repo-baseline guard holds

"""Tests for the doc link-graph (Layer 0 navigability)."""
from __future__ import annotations

from pathlib import Path


import lib.doc_graph as doc_graph
from lib.doc_graph import build_doc_graph, group_broken_links


def _write(root: Path, rel: str, text: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def test_empty_repo_is_available_but_zero(tmp_path: Path) -> None:
    r = build_doc_graph(tmp_path)
    assert r.available is True
    assert r.doc_count == 0


def test_linked_wiki_builds_edges_and_reachability(tmp_path: Path) -> None:
    _write(tmp_path, "index.md", "# Index\n[[setup]] [a](api.md) [[guide#intro]]")
    _write(tmp_path, "setup.md", "see [[guide]]")
    _write(tmp_path, "guide.md", "back to [[index]] and [src](app.py)")
    _write(tmp_path, "api.md", "[[setup]]")
    _write(tmp_path, "app.py", "print(1)")
    _write(tmp_path, "lonely.md", "I link to nobody")

    r = build_doc_graph(tmp_path)
    assert r.doc_count == 5  # app.py is code, not a doc node
    assert r.edge_count >= 5
    # index is a declared MOC and a structural hub (out-degree >= 3)
    assert any(m["path"] == "index.md" and m["is_structural_hub"] for m in r.declared_mocs)
    assert r.moc_named_but_not_wired == []
    # lonely.md has no inbound links and is not an entry -> orphan
    assert "lonely.md" in r.orphans
    # two islands: the linked cluster + lonely
    assert r.island_count == 2
    # reachable from entry (index): everything except lonely
    assert 0.7 <= r.reachability_pct <= 0.85
    assert "lonely.md" in r.unreachable
    # guide.md is reachable, proving the [[guide#intro]] anchor was stripped and
    # still resolved to guide.md (a dangling link would have left it unreachable)
    assert "guide.md" not in r.unreachable


def test_doc_to_code_edges_detected(tmp_path: Path) -> None:
    _write(tmp_path, "guide.md", "code is [here](src/app.py)")
    _write(tmp_path, "src/app.py", "x = 1")
    r = build_doc_graph(tmp_path)
    assert {"doc": "guide.md", "code": "src/app.py"} in r.doc_to_code_edges


def test_declared_moc_not_wired_is_flagged(tmp_path: Path) -> None:
    # index.md is named like a MOC but links to nothing -> named but not wired.
    _write(tmp_path, "index.md", "# Index\nNo links here.")
    _write(tmp_path, "a.md", "content")
    _write(tmp_path, "b.md", "content")
    r = build_doc_graph(tmp_path)
    assert "index.md" in r.moc_named_but_not_wired
    moc = next(m for m in r.declared_mocs if m["path"] == "index.md")
    assert moc["is_structural_hub"] is False


def test_hubs_ranked_by_centrality(tmp_path: Path) -> None:
    # hub.md is pointed to by many docs -> highest PageRank.
    _write(tmp_path, "hub.md", "I am the hub")
    for i in range(4):
        _write(tmp_path, f"leaf{i}.md", "see [hub](hub.md)")
    r = build_doc_graph(tmp_path)
    assert r.hubs[0]["path"] == "hub.md"
    assert r.hubs[0]["in_degree"] == 4
    # full pagerank map exposed for the heatmap, kept off as_dict()
    assert "hub.md" in r.pagerank
    assert "pagerank" not in r.as_dict()


def test_wikilink_collision_is_counted_ambiguous(tmp_path: Path) -> None:
    _write(tmp_path, "one/setup.md", "a")
    _write(tmp_path, "two/setup.md", "b")
    _write(tmp_path, "home.md", "[[setup]]")
    r = build_doc_graph(tmp_path)
    assert r.ambiguous_wikilinks >= 1


def test_dangling_wikilink_counted(tmp_path: Path) -> None:
    _write(tmp_path, "a.md", "[[does-not-exist]]")
    r = build_doc_graph(tmp_path)
    assert r.dangling_links >= 1


def test_vault_detected_at_repo_root(tmp_path: Path) -> None:
    """`.obsidian/` at the scan target -> the repo is the vault root."""
    (tmp_path / ".obsidian").mkdir()
    _write(tmp_path, "note.md", "content")
    r = build_doc_graph(tmp_path)
    assert r.vault_detected is True


def test_vault_detected_when_nested_below_repo_root(tmp_path: Path) -> None:
    """A vault kept as a subdirectory of a git repo (`repo/notes/.obsidian/`)
    puts `.obsidian/` below the scan target. The flag must still read true -
    the false negative this guards against silently disabled every downstream
    vault accommodation (#179)."""
    (tmp_path / "notes" / ".obsidian").mkdir(parents=True)
    _write(tmp_path, "notes/note.md", "content")
    r = build_doc_graph(tmp_path)
    assert r.vault_detected is True


def test_vault_not_detected_on_plain_repo(tmp_path: Path) -> None:
    """A repo with no `.obsidian/` anywhere reports false."""
    _write(tmp_path, "README.md", "no vault here")
    r = build_doc_graph(tmp_path)
    assert r.vault_detected is False


def test_vault_not_detected_for_obsidian_under_excluded_dir(tmp_path: Path) -> None:
    """A `.obsidian/` vendored under a pruned tree (e.g. `node_modules/`) is a
    build/dependency artifact, not this repo's vault - it must not trip the
    flag."""
    (tmp_path / "node_modules" / "pkg" / ".obsidian").mkdir(parents=True)
    _write(tmp_path, "README.md", "real repo, not a vault")
    r = build_doc_graph(tmp_path)
    assert r.vault_detected is False


def test_wikilink_inside_fenced_code_block_is_not_counted(tmp_path: Path) -> None:
    """A FORMAT spec or Obsidian-syntax tutorial that *shows* `[[foo]]` as a
    sample inside a fenced code block must not contribute a phantom edge or
    a dangling link. The writer formatted it as code on purpose.
    """
    _write(
        tmp_path,
        "obsidian-skill.md",
        "How to write wikilinks:\n\n```markdown\n[[Note Title]]\n[[wikilinks]]\n```\n",
    )
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert "Note Title" not in targets
    assert "wikilinks" not in targets


def test_mdlink_inside_fenced_code_block_is_not_counted(tmp_path: Path) -> None:
    """FORMAT specs commonly show `[Ordering](./src/ordering/CONTEXT.md)` as a
    sample of the format they teach. Inside a fence, that's documentation
    syntax, not navigation - it must not show up in broken_links.
    """
    _write(
        tmp_path,
        "context-FORMAT.md",
        "Example layout:\n\n```markdown\n[Ordering](./src/ordering/CONTEXT.md)\n```\n",
    )
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert "./src/ordering/CONTEXT.md" not in targets


def test_link_inside_inline_code_span_is_not_counted(tmp_path: Path) -> None:
    """Inline-code spans (single backticks) are equally code: `[[wikilinks]]`
    in a sentence is teaching syntax, not navigating.
    """
    _write(
        tmp_path,
        "guide.md",
        "Use the `[[Note Title]]` syntax to link notes. "
        "Markdown form looks like `[label](./file.md)`.\n",
    )
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0


def test_real_links_outside_code_still_extracted(tmp_path: Path) -> None:
    """Prose-form links to real docs must still build edges. Stripping code
    spans is meant to reduce false positives, not break navigation."""
    _write(tmp_path, "README.md", "see [the guide](./guide.md)\n")
    _write(tmp_path, "guide.md", "real doc")
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    # Edge must be present.
    edges = {(h["path"], h.get("pagerank", 0)) for h in r.hubs}
    assert any(p == "guide.md" for p, _ in edges) or r.edge_count >= 1


def test_doc_graph_honors_user_exclude_dirs(tmp_path: Path) -> None:
    """A user-supplied exclude (from `.assess/config.toml` or CLI) keeps
    docs inside that directory out of the graph entirely - the same
    semantics every other /assess scan applies. See test_assess_core for
    the orchestrator-level integration that loads excludes once and
    threads them everywhere."""
    _write(tmp_path, "README.md", "see [vetted](./regulatory-raw/notes.md)\n")
    _write(tmp_path, "regulatory-raw/notes.md", "ref data note")

    # Baseline: both docs are counted.
    assert build_doc_graph(tmp_path).doc_count == 2

    # With the exclude: regulatory-raw/notes.md vanishes from the graph.
    r = build_doc_graph(tmp_path, extra_exclude_dirs={"regulatory-raw"})
    assert r.doc_count == 1


def test_doc_graph_honors_user_exclude_patterns(tmp_path: Path) -> None:
    """A glob pattern in the user excludes filters by basename. Same
    fnmatch semantics as `EXCLUDE_FILE_PATTERNS`."""
    _write(tmp_path, "README.md", "real")
    _write(tmp_path, "SCRATCH-NOTES.md", "scratch")

    assert build_doc_graph(tmp_path).doc_count == 2
    r = build_doc_graph(tmp_path, extra_exclude_patterns=["SCRATCH-*.md"])
    assert r.doc_count == 1


def test_excludes_assess_and_vendor_dirs(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "real doc")
    _write(tmp_path, ".assess/log.md", "our own output")
    _write(tmp_path, "node_modules/pkg/readme.md", "vendored")
    r = build_doc_graph(tmp_path)
    assert r.doc_count == 1


def test_excludes_test_fixtures_and_orphan_rate_reflects_it(tmp_path: Path) -> None:
    """Markdown under `**/tests/fixtures/**` is a scanner input, not a repo
    doc, so it must not count toward the doc graph or inflate the orphan rate
    (issue #83). One linked entry doc -> 0% orphans; without the exclusion the
    fixture files would be unreachable orphans and the rate would spike."""
    _write(tmp_path, "README.md", "see [guide](./guide.md)\n")
    _write(tmp_path, "guide.md", "the guide\n")
    # Fixtures that exist only to exercise the detectors - never navigation.
    _write(tmp_path, "skills/assess/tests/fixtures/lean/CLAUDE.md", "fixture")
    _write(tmp_path, "tests/fixtures/monolithic_instructions.md", "fixture")

    r = build_doc_graph(tmp_path)
    assert r.doc_count == 2
    assert not any("fixtures" in o for o in r.orphans)
    assert r.orphan_rate == 0.0


def test_unrelated_top_level_fixtures_dir_not_excluded(tmp_path: Path) -> None:
    """Only the `tests/fixtures` *sequence* is excluded - a top-level
    `fixtures/` of real content (not preceded by `tests`) still counts."""
    _write(tmp_path, "README.md", "real doc")
    _write(tmp_path, "fixtures/data-model.md", "real architecture doc")
    r = build_doc_graph(tmp_path)
    assert r.doc_count == 2


def test_is_excluded_path_helper() -> None:
    from lib.doc_graph import is_excluded_path

    assert is_excluded_path(Path("a/tests/fixtures/x.md"))
    assert is_excluded_path(Path("tests/fixtures/x.md"))
    assert is_excluded_path(Path(".assess/log.md"))
    # `fixtures` not preceded by `tests`, and `tests` not followed by `fixtures`.
    assert not is_excluded_path(Path("src/fixtures/x.md"))
    assert not is_excluded_path(Path("tests/unit/x.md"))
    assert not is_excluded_path(Path("tests/x/fixtures/y.md"))


def test_graph_object_exposed_for_renderer(tmp_path: Path) -> None:
    """DocGraphResult.graph carries the networkx graph (the SVG renderer needs
    the full edge list, which as_dict doesn't serialise)."""
    _write(tmp_path, "a.md", "[[b]]")
    _write(tmp_path, "b.md", "x")
    r = build_doc_graph(tmp_path)
    assert r.graph is not None
    assert set(r.graph.nodes()) == {"a.md", "b.md"}
    assert "graph" not in r.as_dict()


def test_is_repo_file_rejects_symlink_escape(tmp_path: Path) -> None:
    import os
    from lib.doc_graph import is_repo_file
    repo = tmp_path / "repo"
    repo.mkdir()
    outside = tmp_path / "outside.md"
    outside.write_text("not ours", encoding="utf-8")
    (repo / "real.md").write_text("ours", encoding="utf-8")
    os.symlink(outside, repo / "link.md")  # symlink inside repo -> outside
    rr = repo.resolve()
    assert is_repo_file(repo / "real.md", rr, None) is True
    assert is_repo_file(repo / "link.md", rr, None) is False  # resolves outside repo


def test_untracked_files_excluded_in_git_repo(git_repo) -> None:
    """A contributor's untracked personal doc is not part of the repo and must
    not be scanned (the external-CLAUDE.md class of false positive)."""
    repo, commit = git_repo
    (repo / "README.md").write_text("# Home\n[[guide]]", encoding="utf-8")
    (repo / "guide.md").write_text("tracked", encoding="utf-8")
    commit("docs")
    (repo / "personal.md").write_text("my private notes", encoding="utf-8")  # untracked

    r = build_doc_graph(repo)
    nodes = set(r.graph.nodes())
    assert {"README.md", "guide.md"} <= nodes
    assert "personal.md" not in nodes


def test_radial_shells_and_classify(tmp_path: Path) -> None:
    """The headline claim — reachable = central, unreachable = banished to the
    rim — is the BFS/shell logic; lock it in deterministically (no rendering)."""
    from lib.doc_graph import classify_node, radial_shells
    _write(tmp_path, "index.md", "# Index\n[[a]]")
    _write(tmp_path, "a.md", "[[b]]")
    _write(tmp_path, "b.md", "leaf")
    _write(tmp_path, "lonely.md", "nobody links here")
    r = build_doc_graph(tmp_path)
    assert r.entry_points == ["index.md"]

    shells = radial_shells(r.graph, set(r.entry_points))
    assert shells[0] == ["index.md"]          # entry at the centre
    assert "a.md" in shells[1]                 # 1 hop out
    assert "b.md" in shells[2]                 # 2 hops out
    assert "lonely.md" in shells[-1]           # unreachable -> outer rim
    lonely_ring = next(i for i, s in enumerate(shells) if "lonely.md" in s)
    assert lonely_ring > 2                      # past every reachable shell

    entries, unreachable, orphans = set(r.entry_points), set(r.unreachable), set(r.orphans)
    assert classify_node("index.md", entries, unreachable, orphans) == "entry"
    assert classify_node("a.md", entries, unreachable, orphans) == "reachable"
    assert classify_node("lonely.md", entries, unreachable, orphans) == "orphan"


def test_broken_links_recorded_as_ghosts(tmp_path: Path) -> None:
    """Links to files that don't exist are captured (wikilink + CommonMark) so
    the renderer can draw them as ghost nodes."""
    _write(tmp_path, "a.md", "[[ghost-note]] and [also](./missing.md) and [ok](b.md)")
    _write(tmp_path, "b.md", "real")
    r = build_doc_graph(tmp_path).as_dict()
    targets = {bl["target"] for bl in r["broken_links"]}
    assert "ghost-note" in targets          # dangling wikilink
    assert "./missing.md" in targets        # broken CommonMark link
    assert r["dangling_links"] == len(r["broken_links"])
    # the valid link to b.md is not a ghost
    assert not any(bl["target"] == "b.md" for bl in r["broken_links"])


def test_directory_link_not_flagged_broken(tmp_path: Path) -> None:
    """A link to an existing folder is valid navigation, not a broken link."""
    (tmp_path / "guides").mkdir()
    (tmp_path / "guides" / "x.md").write_text("hi", encoding="utf-8")
    _write(tmp_path, "a.md", "see [folder](guides/) and [ghost](nope.md)")
    r = build_doc_graph(tmp_path).as_dict()
    targets = {bl["target"] for bl in r["broken_links"]}
    assert "guides/" not in targets   # existing directory -> not broken
    assert "nope.md" in targets       # genuinely missing -> ghost


def test_missing_xrefs_named_not_linked(tmp_path: Path) -> None:
    """A doc that names another doc's filename in prose but never links it."""
    _write(tmp_path, "overview.md", "The payments.md flow is described elsewhere.")
    _write(tmp_path, "payments.md", "payments")
    _write(tmp_path, "linked.md", "see [payments](payments.md)")  # already linked
    r = build_doc_graph(tmp_path).as_dict()
    pairs = {(x["from"], x["to"]) for x in r["missing_xrefs"]}
    assert ("overview.md", "payments.md") in pairs       # named, not linked
    assert ("linked.md", "payments.md") not in pairs     # already linked -> not missing


def test_group_broken_links_merges_same_missing_file() -> None:
    """Several links to the same missing file collapse to one ghost they share."""
    broken = [
        {"from": "README.md", "target": "CLAUDE.md", "kind": "mdlink"},
        {"from": "CONTRIBUTING.md", "target": "CLAUDE.md", "kind": "mdlink"},
    ]
    groups = group_broken_links(broken)
    assert len(groups) == 1
    assert groups[0]["target"] == "CLAUDE.md"
    assert sorted(groups[0]["sources"]) == ["CONTRIBUTING.md", "README.md"]


def test_group_broken_links_resolves_relative_targets() -> None:
    """Targets written differently but pointing at distinct paths stay separate;
    the same resolved path merges even when the link text differs."""
    broken = [
        {"from": "README.md", "target": "CLAUDE.md", "kind": "mdlink"},
        # resolves to docs/CLAUDE.md, not the root CLAUDE.md -> separate ghost
        {"from": "docs/guide.md", "target": "CLAUDE.md", "kind": "mdlink"},
        # ../CLAUDE.md from docs/ resolves back to root CLAUDE.md -> merges with README
        {"from": "docs/other.md", "target": "../CLAUDE.md", "kind": "mdlink"},
    ]
    groups = {g["target"]: sorted(g["sources"]) for g in group_broken_links(broken)}
    assert groups["CLAUDE.md"] == ["README.md", "docs/other.md"]
    assert groups["docs/CLAUDE.md"] == ["docs/guide.md"]


def test_group_broken_links_merges_root_absolute_spelling() -> None:
    """A root-absolute link (/CLAUDE.md) and a plain one (CLAUDE.md) at the same
    missing root file must merge — they only differ in spelling. Regression for
    the leading-slash key mismatch."""
    broken = [
        {"from": "README.md", "target": "CLAUDE.md", "kind": "mdlink"},
        {"from": "docs/guide.md", "target": "/CLAUDE.md", "kind": "mdlink"},
    ]
    groups = group_broken_links(broken)
    assert len(groups) == 1
    assert groups[0]["target"] == "CLAUDE.md"
    assert sorted(groups[0]["sources"]) == ["README.md", "docs/guide.md"]


def test_group_broken_links_wikilink_and_mdlink_do_not_merge() -> None:
    """Documented limit: a wikilink ([[CLAUDE]]) and a markdown link (CLAUDE.md)
    to the same missing file live in different resolution domains and stay
    separate. Pinned so the behaviour is intentional, not accidental."""
    broken = [
        {"from": "a.md", "target": "CLAUDE", "kind": "wikilink"},
        {"from": "b.md", "target": "CLAUDE.md", "kind": "mdlink"},
    ]
    keys = {g["target"] for g in group_broken_links(broken)}
    assert keys == {"CLAUDE", "CLAUDE.md"}


def test_group_broken_links_wikilinks_key_by_name() -> None:
    """Wikilinks resolve by note name globally, so they key on the bare name
    regardless of the source directory."""
    broken = [
        {"from": "a.md", "target": "ghost-note", "kind": "wikilink"},
        {"from": "deep/b.md", "target": "ghost-note", "kind": "wikilink"},
    ]
    groups = group_broken_links(broken)
    assert len(groups) == 1
    assert groups[0]["target"] == "ghost-note"
    assert sorted(groups[0]["sources"]) == ["a.md", "deep/b.md"]


def test_group_broken_links_orders_by_source_count() -> None:
    """The most-referenced missing file comes first so it renders first."""
    broken = [
        {"from": "x.md", "target": "rare.md", "kind": "mdlink"},
        {"from": "a.md", "target": "popular.md", "kind": "mdlink"},
        {"from": "b.md", "target": "popular.md", "kind": "mdlink"},
    ]
    groups = group_broken_links(broken)
    assert [g["target"] for g in groups] == ["popular.md", "rare.md"]


def test_degrades_when_networkx_unavailable(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "README.md", "[[a]]")
    _write(tmp_path, "a.md", "x")
    monkeypatch.setattr(doc_graph, "_NETWORKX_AVAILABLE", False)
    r = build_doc_graph(tmp_path)
    assert r.available is False
    assert "networkx" in r.reason
    # must not crash; as_dict is still serialisable
    assert r.as_dict()["available"] is False


# ---- vault-native navigation (issue #176) ---------------------------------

def test_base_hub_links_folder_notes_no_longer_orphaned(tmp_path: Path) -> None:
    # A `.base` viewing `_jira` is the only navigation surface: no static links
    # anywhere. Before #176 every note scored as an orphan / unreachable.
    _write(tmp_path, "tasks.base",
           'filters:\n  and:\n    - file.inFolder("_jira")\n    - file.ext == "md"\n'
           'views:\n  - type: table\n    name: All\n')
    for i in range(5):
        _write(tmp_path, f"_jira/ABC-{i}.md", f"# Ticket {i}\nstatus: open\n")

    r = build_doc_graph(tmp_path)
    # The .base hub is a node + entry point; the 5 notes are its descendants.
    assert "tasks.base" in r.entry_points
    assert r.edge_count == 5
    assert r.orphans == []           # every note has the hub as an inbound link
    assert r.orphan_rate == 0.0
    assert r.reachability_pct == 1.0  # all reachable from the hub entry


def test_base_that_selects_nothing_is_not_added(tmp_path: Path) -> None:
    # A `.base` whose query matches no note must not appear as an orphan hub node.
    _write(tmp_path, "empty.base", '- file.inFolder("does-not-exist")\n')
    _write(tmp_path, "README.md", "# Home\n")
    r = build_doc_graph(tmp_path)
    assert "empty.base" not in r.entry_points
    assert r.doc_count == 1  # only README.md; the empty base is not a node


def test_dataview_hub_links_notes_from_its_note(tmp_path: Path) -> None:
    # A `dataview` block inside a hub note (itself reachable from the README)
    # surfaces the `_archive` folder; those notes become reachable, not orphans.
    _write(tmp_path, "README.md", "Start at the [hub](hub.md)")
    _write(tmp_path, "hub.md",
           "# Hub\n\n```dataview\nLIST\nFROM \"_archive\"\n```\n")
    for i in range(3):
        _write(tmp_path, f"_archive/note-{i}.md", f"old note {i}")

    r = build_doc_graph(tmp_path)
    # hub.md -> each archive note (3) plus README -> hub (1)
    assert r.edge_count == 4
    assert r.orphans == []
    assert r.reachability_pct == 1.0


def test_dataview_tag_hub_uses_frontmatter(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "see [hub](hub.md)")
    _write(tmp_path, "hub.md", "```dataview\nLIST FROM #project\n```")
    _write(tmp_path, "p1.md", "---\ntags: [project]\n---\nbody")
    _write(tmp_path, "p2.md", "---\ntags: [other]\n---\nbody")

    r = build_doc_graph(tmp_path)
    # hub -> p1 (tagged project) only; p2 is not tagged so stays an orphan.
    assert "p1.md" not in r.orphans
    assert "p2.md" in r.orphans


# ---- non-navigational URI scheme exclusions (issue #227) -------------------

def test_tel_mdlink_not_counted_broken(tmp_path: Path) -> None:
    """[text](tel:+1-555-1234) is a phone-dialer link. It is not a broken
    navigation edge -- the file `tel:+1-555-1234` does not exist, and that
    is expected. The broken-link counter must not count it."""
    _write(tmp_path, "contact.md", "Call us at [phone](tel:+1-555-1234)")
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert not any("tel:" in t for t in targets)


def test_mailto_mdlink_not_counted_broken(tmp_path: Path) -> None:
    """[text](mailto:hello@example.com) is an email link, not a broken file
    reference. The broken-link counter must not count it."""
    _write(tmp_path, "contact.md", "Email us at [email](mailto:hello@example.com)")
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert not any("mailto:" in t for t in targets)


def test_other_non_http_scheme_mdlink_not_counted_broken(tmp_path: Path) -> None:
    """Non-navigational URI schemes beyond tel:/mailto: (sms:, callto:, etc.)
    are not file references and must not contribute broken links."""
    _write(
        tmp_path,
        "contact.md",
        "Text us at [sms](sms:+1-555-1234) or via [Skype](skype:username)",
    )
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert not any("sms:" in t or "skype:" in t for t in targets)


def test_tel_wikilink_not_counted_broken(tmp_path: Path) -> None:
    """[[tel:+1-555-1234]] is a non-navigational URI in wikilink form. It
    must not be counted as a broken wikilink to a missing note."""
    _write(tmp_path, "contact.md", "Dial [[tel:+1-555-1234]] for support")
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert not any("tel:" in t for t in targets)


def test_mailto_wikilink_not_counted_broken(tmp_path: Path) -> None:
    """[[mailto:user@example.com]] in wikilink form must not count as a broken
    note reference."""
    _write(tmp_path, "contact.md", "Write to [[mailto:user@example.com]]")
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert not any("mailto:" in t for t in targets)


def test_uri_scheme_inside_code_fence_not_counted(tmp_path: Path) -> None:
    """A tel: or mailto: link shown as an example inside a fenced code block
    (e.g. in a FORMAT spec or tutorial) must not count -- it is documentation
    syntax, not a navigation edge."""
    _write(
        tmp_path,
        "guide.md",
        "Contact links look like:\n\n```markdown\n"
        "[phone](tel:+1-555-1234)\n"
        "[email](mailto:hello@example.com)\n"
        "```\n",
    )
    r = build_doc_graph(tmp_path)
    assert r.dangling_links == 0
    targets = {bl["target"] for bl in r.broken_links}
    assert not any("tel:" in t or "mailto:" in t for t in targets)


def test_real_file_links_still_flagged_after_scheme_exclusions(tmp_path: Path) -> None:
    """URI-scheme exclusions must not accidentally suppress genuine broken
    relative-path links. A link to a missing file must still be flagged."""
    _write(tmp_path, "a.md", "[gone](missing-file.md) and [phone](tel:555-1234)")
    r = build_doc_graph(tmp_path)
    targets = {bl["target"] for bl in r.broken_links}
    assert "missing-file.md" in targets
    assert not any("tel:" in t for t in targets)


# --- Raw-source-tree exclusion (issue #225) -------------------------------

def _curated_wiki(root: Path) -> None:
    """A small, well-linked curated wiki: index hub + three linked notes."""
    _write(root, "index.md", "# Index\n[[setup]] [[guide]] [[api]]")
    _write(root, "setup.md", "see [[guide]]")
    _write(root, "guide.md", "back to [[index]]")
    _write(root, "api.md", "[[setup]]")


def _raw_export(root: Path, subdir: str, n: int) -> None:
    """A raw-source dump: ``n`` link-isolated docs each carrying a
    machine-extracted (mailto:/tel:) link, the SAR-export fingerprint."""
    for i in range(n):
        _write(
            root, f"{subdir}/msg-{i:03d}.md",
            f"From: sender{i}@example.com\n"
            f"Contact [email](mailto:user{i}@example.com) or [call](tel:+1-555-{i:04d}).\n"
            "Body text extracted from the original message.\n",
        )


def test_raw_source_tree_excluded_from_metrics(tmp_path: Path) -> None:
    _curated_wiki(tmp_path)
    _raw_export(tmp_path, "sar-export", 14)
    r = build_doc_graph(tmp_path)

    # The raw subtree is named with its file count.
    assert r.excluded_raw_trees == [{"path": "sar-export", "file_count": 14}]
    assert r.raw_source_doc_count == 14

    # Curated metrics exclude the raw docs: none of the raw files appear as
    # orphans, and the curated layer is small + well-connected.
    assert not any(o.startswith("sar-export/") for o in r.orphans)
    assert r.curated_doc_count == 4
    assert r.doc_count == 4  # headline doc_count is the curated layer
    # Orphan rate over the curated wiki is low, not the ~78% the raw dump
    # would have produced if counted.
    assert r.orphan_rate <= 0.25
    # The raw layer's own orphan rate is reported separately and is high.
    assert r.raw_source_orphan_rate >= 0.9


def test_no_raw_tree_is_unaffected(tmp_path: Path) -> None:
    _curated_wiki(tmp_path)
    _write(tmp_path, "lonely.md", "I link to nobody")
    r = build_doc_graph(tmp_path)
    assert r.excluded_raw_trees == []
    assert r.raw_source_doc_count == 0
    assert r.raw_source_broken_links == 0
    assert r.curated_doc_count == r.doc_count == 5
    # lonely.md is still a genuine orphan - not swept up by raw detection.
    assert "lonely.md" in r.orphans


def test_raw_broken_links_excluded_from_headline(tmp_path: Path) -> None:
    _curated_wiki(tmp_path)
    # Raw docs that also carry a broken relative link: the broken link must be
    # attributed to the raw layer, not the curated headline count.
    for i in range(14):
        _write(
            tmp_path, f"dump/msg-{i:03d}.md",
            f"[email](mailto:user{i}@example.com) and [missing](./ghost-{i}.md)\n",
        )
    r = build_doc_graph(tmp_path)
    assert r.excluded_raw_trees == [{"path": "dump", "file_count": 14}]
    # No curated broken link points at a raw ghost target.
    assert not any(bl["from"].startswith("dump/") for bl in r.broken_links)
    assert r.raw_source_broken_links >= 14


def test_isolated_curated_folder_not_excluded(tmp_path: Path) -> None:
    # A folder of hand-written standalone notes (link-isolated but NO machine
    # fingerprint) must not be mistaken for a raw dump.
    _curated_wiki(tmp_path)
    for i in range(14):
        _write(tmp_path, f"notes/note-{i:03d}.md", "A standalone hand-written note.\n")
    r = build_doc_graph(tmp_path)
    assert r.excluded_raw_trees == []
    assert any(o.startswith("notes/") for o in r.orphans)


def _notes_and_wiki(root: Path) -> None:
    """50 plan notes under one backlog index, beside a nine-page wiki the
    README links seven of."""
    for i in range(1, 51):
        _write(root, f"notes/plan_{i:02d}.md", f"# plan {i:02d}\n")
    _write(root, "notes/backlog.md", "".join(
        f"- [plan {i:02d}](plan_{i:02d}.md)\n" for i in range(1, 51)
    ))
    pages = "architecture deploy testing security glossary onboarding releases attic scratch".split()
    for w in pages:
        _write(root, f"wiki/{w}.md", f"# {w}\n")
    _write(root, "README.md", "# Home\n[backlog](notes/backlog.md)\n" + "".join(
        f"[{w}](wiki/{w}.md)\n" for w in pages[:7]
    ))


def test_working_notes_tree_excluded_from_headline(tmp_path: Path) -> None:
    _notes_and_wiki(tmp_path)
    _write(tmp_path, "notes/plan_03.md", "[ghost](./missing.md)\n")
    d = build_doc_graph(tmp_path).as_dict()
    assert d["excluded_working_notes_trees"] == [{"path": "notes", "file_count": 51}]
    assert d["working_notes_doc_count"] == 51
    assert (d["doc_count"], d["orphan_rate"], d["reachability_pct"]) == (10, 0.2, 0.8)
    assert not any(h["path"].startswith("notes/") for h in d["hubs"])
    # The notes layer's own figures are reported beside the headline.
    assert d["working_notes_orphan_rate"] == 0.0
    assert d["working_notes_broken_links"] == 1
    assert d["dangling_links"] == 0
    assert d["excluded_raw_trees"] == []


def test_base_hub_beside_notes_is_not_a_notes_member(tmp_path: Path) -> None:
    # A vault-wide .base stored in notes/ selects the wiki pages. It is not a
    # doc, so it neither joins the tree's count nor leaves the headline graph,
    # and the wiki pages it surfaces keep their inbound edge.
    _notes_and_wiki(tmp_path)
    _write(tmp_path, "notes/pages.base",
           'filters:\n  and:\n    - file.inFolder("wiki")\n    - file.ext == "md"\n'
           'views:\n  - type: table\n    name: All\n')
    d = build_doc_graph(tmp_path).as_dict()
    assert d["excluded_working_notes_trees"] == [{"path": "notes", "file_count": 51}]
    assert d["working_notes_doc_count"] == 51
    assert not any(o.startswith("wiki/") for o in d["orphans"])


def test_no_working_notes_tree_keys_present_and_empty(tmp_path: Path) -> None:
    _curated_wiki(tmp_path)
    d = build_doc_graph(tmp_path).as_dict()
    assert d["excluded_working_notes_trees"] == []
    assert d["working_notes_doc_count"] == 0
    assert d["working_notes_orphan_rate"] == 0.0
    assert d["working_notes_broken_links"] == 0


def test_raw_tree_is_not_also_a_working_notes_tree(tmp_path: Path) -> None:
    _curated_wiki(tmp_path)
    _raw_export(tmp_path, "sar-export", 30)
    r = build_doc_graph(tmp_path)
    assert r.excluded_raw_trees == [{"path": "sar-export", "file_count": 30}]
    assert r.excluded_working_notes_trees == []


# --- Reference edges (backticked doc paths) --------------------------------


def _edges(r) -> list[list]:
    return sorted([u, v, d.get("kind")] for u, v, d in r.graph.edges(data=True))


def test_reference_edge_from_backticked_existing_path(tmp_path: Path) -> None:
    """A backticked token that resolves to an existing doc is a reference edge;
    one that resolves to nothing adds no edge and no node. Markdown links keep
    kind link."""
    _write(
        tmp_path, "CLAUDE.md",
        "# Entry\nSee `docs/arch.md` and `docs/missing.md` and `not-a-path`, "
        "then [guide](guide.md).\n",
    )
    _write(tmp_path, "docs/arch.md", "# Arch")
    _write(tmp_path, "guide.md", "# Guide")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == [
        ["CLAUDE.md", "docs/arch.md", "reference"],
        ["CLAUDE.md", "guide.md", "link"],
    ]
    assert "docs/missing.md" not in r.graph


def test_reference_edge_resolves_relative_to_the_citing_doc(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "[docs](docs/index.md)")
    _write(tmp_path, "docs/index.md", "Read `setup.md` next.")
    _write(tmp_path, "docs/setup.md", "# Setup")
    r = build_doc_graph(tmp_path)
    assert ["docs/index.md", "docs/setup.md", "reference"] in _edges(r)


def test_reference_inside_fence_adds_no_edge(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "```\n`guide.md`\n```\n")
    _write(tmp_path, "guide.md", "# Guide")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == []


def test_link_kind_wins_when_a_doc_both_links_and_cites(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "Read `guide.md`, or [the guide](guide.md).")
    _write(tmp_path, "guide.md", "# Guide")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == [["README.md", "guide.md", "link"]]


def test_cited_claude_file_becomes_a_reachable_node(tmp_path: Path) -> None:
    """A `.claude/` doc that a reference names is a node and reachable; an
    uncited one stays excluded. The headline figures count reference edges;
    the link-only figures sit beside them."""
    _write(tmp_path, "CLAUDE.md", "# Entry\nOpen `.claude/skills/x/SKILL.md` first.\n")
    _write(tmp_path, ".claude/skills/x/SKILL.md", "# x")
    _write(tmp_path, ".claude/skills/y/SKILL.md", "# y")
    _write(tmp_path, "docs/lonely.md", "# lonely")
    r = build_doc_graph(tmp_path)
    d = r.as_dict()
    assert sorted(r.graph.nodes()) == [
        ".claude/skills/x/SKILL.md", "CLAUDE.md", "docs/lonely.md",
    ]
    assert d["unreachable"] == ["docs/lonely.md"]
    assert d["doc_count"] == 3
    assert d["orphan_rate"] == 0.333
    assert d["reachability_pct"] == 0.667
    assert d["link_only_reachability_pct"] < d["reachability_pct"]
    assert d["link_only_orphan_rate"] > d["orphan_rate"]


def test_cited_claude_doc_is_parsed_for_its_own_edges(tmp_path: Path) -> None:
    _write(tmp_path, "CLAUDE.md", "Open `.claude/skills/x/SKILL.md`.")
    _write(tmp_path, ".claude/skills/x/SKILL.md", "See [ref](../../../docs/ref.md).")
    _write(tmp_path, "docs/ref.md", "# Ref")
    r = build_doc_graph(tmp_path)
    assert [".claude/skills/x/SKILL.md", "docs/ref.md", "link"] in _edges(r)
    assert r.unreachable == []


def test_reference_edge_clears_missing_xref(tmp_path: Path) -> None:
    _write(tmp_path, "CLAUDE.md", "# Entry\nRead `guide.md` before editing.\n")
    _write(tmp_path, "guide.md", "# Guide")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == [["CLAUDE.md", "guide.md", "reference"]]
    assert r.as_dict()["missing_xrefs"] == []


def test_link_only_figures_equal_headline_without_references(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "[a](a.md)")
    _write(tmp_path, "a.md", "# A")
    _write(tmp_path, "b.md", "# B")
    d = build_doc_graph(tmp_path).as_dict()
    assert d["link_only_orphan_rate"] == d["orphan_rate"]
    assert d["link_only_reachability_pct"] == d["reachability_pct"]


def test_reference_inside_tilde_or_long_fence_adds_no_edge(tmp_path: Path) -> None:
    """CommonMark fences: a tilde fence, and a four-backtick fence holding a
    shorter backtick run, both hide their content from the reference pass."""
    _write(
        tmp_path, "README.md",
        "~~~\n`a.md`\n~~~\n\n````\n```\n`b.md`\n```\n````\n",
    )
    _write(tmp_path, "a.md", "# A")
    _write(tmp_path, "b.md", "# B")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == []


def test_bare_basename_resolves_across_the_tree_when_unique(tmp_path: Path) -> None:
    """A bare basename with no doc-relative match falls back to the one doc in
    the tree with that name."""
    _write(tmp_path, "CLAUDE.md", "# Entry\nSee `setup.md`.\n")
    _write(tmp_path, "docs/guides/setup.md", "# Setup")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == [["CLAUDE.md", "docs/guides/setup.md", "reference"]]


def test_ambiguous_bare_basename_adds_no_edge(tmp_path: Path) -> None:
    """Two docs share the cited basename: the citation names neither, so the
    basename fallback adds nothing rather than spraying edges."""
    _write(tmp_path, "README.md", "Read `SKILL.md`.")
    _write(tmp_path, "skills/a/SKILL.md", "# a")
    _write(tmp_path, "skills/b/SKILL.md", "# b")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == []


def test_cited_excluded_doc_guards(tmp_path: Path) -> None:
    """A cited `.claude/` doc joins the graph only when every other exclusion
    lets it: no parent-dir escape, no user exclude, tracked, inside scope."""
    _write(tmp_path, ".claude/skills/x/SKILL.md", "# x")
    _write(tmp_path, "docs/a.md", "# a")
    target = (tmp_path / ".claude/skills/x/SKILL.md").resolve()

    def cite(rel_path, tracked=None, scope=None, dirs=None, pats=None):
        return doc_graph._cited_excluded_doc(
            rel_path, tmp_path, tracked, scope, dirs or set(), pats or [],
        )

    assert cite(".claude/skills/x/SKILL.md") == target
    assert cite(".claude/../.claude/skills/x/SKILL.md") is None
    assert cite(".claude/skills/x/SKILL.md", dirs={"x"}) is None
    assert cite(".claude/skills/x/SKILL.md", pats=["SKILL.md"]) is None
    assert cite(".claude/skills/x/SKILL.md", tracked=frozenset()) is None
    assert cite(".claude/skills/x/SKILL.md", scope=tmp_path / "docs") is None
    assert cite("docs/a.md") is None  # not under .claude: the walk owns it


def test_link_reaches_cited_claude_doc_from_a_doc_read_earlier(tmp_path: Path) -> None:
    """References settle before the link pass, so a doc walked before the
    citing doc still links to (and wikilinks to) the cited `.claude/` doc."""
    _write(tmp_path, "AAA.md", "[x](.claude/skills/x/SKILL.md) and [[notes]]")
    _write(tmp_path, "CLAUDE.md", "Open `.claude/skills/x/SKILL.md` and `.claude/notes.md`.")
    _write(tmp_path, ".claude/skills/x/SKILL.md", "# x")
    _write(tmp_path, ".claude/notes.md", "# notes")
    r = build_doc_graph(tmp_path)
    edges = _edges(r)
    assert ["AAA.md", ".claude/skills/x/SKILL.md", "link"] in edges
    assert ["AAA.md", ".claude/notes.md", "link"] in edges
    assert r.as_dict()["dangling_links"] == 0


def test_tilde_fenced_link_sample_is_not_a_broken_link(tmp_path: Path) -> None:
    """The link harvest uses the same CommonMark fence parser as references: a
    wikilink sample in a tilde fence is neither an edge nor a ghost."""
    _write(tmp_path, "README.md", "~~~\n[[nowhere]] and [x](gone.md)\n~~~\n")
    r = build_doc_graph(tmp_path)
    assert r.as_dict()["dangling_links"] == 0
    assert _edges(r) == []


def test_reference_inside_indented_fence_adds_no_edge(tmp_path: Path) -> None:
    """A fence nested under a list item sits four or more spaces in; its
    content is still a sample, not a citation."""
    _write(tmp_path, "README.md", "- step\n\n      ```\n      `docs/arch.md`\n      ```\n")
    _write(tmp_path, "docs/arch.md", "# Arch")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == []


def test_root_level_mdx_citation_is_a_reference_edge(tmp_path: Path) -> None:
    """Every doc extension the graph walks is citable, with or without a slash."""
    _write(tmp_path, "README.md", "See `guide.mdx` and `docs/intro.markdown`.")
    _write(tmp_path, "guide.mdx", "# Guide")
    _write(tmp_path, "docs/intro.markdown", "# Intro")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == [
        ["README.md", "docs/intro.markdown", "reference"],
        ["README.md", "guide.mdx", "reference"],
    ]


def test_reference_inside_container_prefixed_fence_adds_no_edge(tmp_path: Path) -> None:
    """A fence behind a blockquote or list-item marker hides its body, and its
    indented closer does not reopen a fence that swallows the rest of the doc."""
    _write(
        tmp_path, "README.md",
        "> ```\n> `a.md` [[nowhere]]\n> ```\n\n"
        "- ~~~\n  `b.md`\n  ~~~\n\n"
        "Then [c](c.md).\n",
    )
    for name in ("a.md", "b.md", "c.md"):
        _write(tmp_path, name, "# x")
    r = build_doc_graph(tmp_path)
    assert _edges(r) == [["README.md", "c.md", "link"]]
    assert r.as_dict()["dangling_links"] == 0


def test_root_level_exact_name_beats_a_same_named_doc_elsewhere(tmp_path: Path) -> None:
    """A bare name that is a root-level doc resolves there, even when a doc of
    the same name sits deeper in the tree."""
    _write(tmp_path, "docs/x/index.md", "See `CHANGELOG.md`.")
    _write(tmp_path, "CHANGELOG.md", "# root")
    _write(tmp_path, "pkg/CHANGELOG.md", "# pkg")
    r = build_doc_graph(tmp_path)
    assert ["docs/x/index.md", "CHANGELOG.md", "reference"] in _edges(r)
    assert not any(e[1] == "pkg/CHANGELOG.md" for e in _edges(r))


def test_link_only_figures_share_the_headline_entry_points(tmp_path: Path, monkeypatch) -> None:
    """The link-only pass is handed the headline's entry points instead of
    re-picking them from link-only PageRank, so the two figures differ only in
    their edge set. Without it, a repo with no conventional entry doc could
    measure the two from different roots."""
    calls: list = []
    real = doc_graph._derive_signals

    def spy(**kw):
        out = real(**kw)
        calls.append((kw.get("entries"), out.entry_points))
        return out

    monkeypatch.setattr(doc_graph, "_derive_signals", spy)
    _write(tmp_path, "hub-a.md", "`n1.md` `n2.md`")
    _write(tmp_path, "hub-b.md", "[1](m1.md)")
    for name in ("n1.md", "n2.md", "m1.md"):
        _write(tmp_path, name, "# x")
    build_doc_graph(tmp_path)
    (headline_in, headline_entries), (link_only_in, link_only_entries) = calls
    assert headline_in is None
    assert link_only_in == headline_entries == link_only_entries


# --- directory_breakdown (issue #365) ----------------------------------------


def _two_doc_dirs(root: Path) -> None:
    _write(root, "README.md", "# Home\n[a](docs/a.md) [g1](guides/g1.md)\n")
    _write(root, "docs/a.md", "# a\n")
    _write(root, "docs/b.md", "# b\n[gone](missing.md)\n")
    for n in (1, 2, 3):
        _write(root, f"guides/g{n}.md", f"# g{n}\n")


def test_directory_breakdown_counts_per_top_level_directory(tmp_path: Path) -> None:
    _two_doc_dirs(tmp_path)
    d = build_doc_graph(tmp_path).as_dict()
    rows = {r["path"]: r for r in d["directory_breakdown"]}
    assert rows["docs"] == {"path": "docs", "doc_count": 2,
                            "unreachable_count": 1, "broken_link_count": 1}
    assert rows["guides"] == {"path": "guides", "doc_count": 3,
                              "unreachable_count": 2, "broken_link_count": 0}
    # Root-level docs group under ".".
    assert rows["."] == {"path": ".", "doc_count": 1,
                         "unreachable_count": 0, "broken_link_count": 0}
    assert d["directory_count"] == 3


def test_directory_breakdown_reconciles_with_headline(tmp_path: Path) -> None:
    # A working-notes tree leaves the headline, so it leaves the breakdown too:
    # the rows sum to the headline doc_count, unreachable list and dangling_links.
    _notes_and_wiki(tmp_path)
    _write(tmp_path, "notes/plan_03.md", "[ghost](./missing.md)\n")
    _write(tmp_path, "wiki/scratch.md", "[ghost](./nowhere.md)\n")
    d = build_doc_graph(tmp_path).as_dict()
    rows = d["directory_breakdown"]
    assert "notes" not in {r["path"] for r in rows}
    assert sum(r["doc_count"] for r in rows) == d["doc_count"]
    assert sum(r["unreachable_count"] for r in rows) == len(d["unreachable"])
    assert sum(r["broken_link_count"] for r in rows) == d["dangling_links"] == 1


def test_directory_breakdown_is_capped_gap_first(tmp_path: Path, monkeypatch) -> None:
    monkeypatch.setattr(doc_graph, "MAX_DIRECTORY_BREAKDOWN", 2)
    _write(tmp_path, "README.md", "# Home\n[a](a/x.md) [b](b/x.md)\n")
    _write(tmp_path, "a/x.md", "# a\n")
    _write(tmp_path, "b/x.md", "# b\n")
    _write(tmp_path, "c/x.md", "# c orphan\n")
    d = build_doc_graph(tmp_path).as_dict()
    assert d["directory_count"] == 4
    # The directory holding the unreachable doc outranks the healthy ones.
    assert [r["path"] for r in d["directory_breakdown"]] == ["c", "."]


def test_directory_breakdown_empty_repo(tmp_path: Path) -> None:
    d = build_doc_graph(tmp_path).as_dict()
    assert d["directory_breakdown"] == []
    assert d["directory_count"] == 0

"""The doc-graph SVG honours the same excludes as the scorer (issue #177).

`doc-graph-svg.py` is a CLI wrapper that imports matplotlib/numpy at load, so
those are stubbed before import (same approach as test_complexity_treemap). We
then drive `main()` with `build_doc_graph` / `analyze_doc_staleness` / `render`
patched to capture the excludes they receive, proving the SVG path resolves
`.assess/config.toml` + `--exclude` and threads the union into both scans - so
the SVG and `lib.doc_graph` compute over the identical doc set.
"""
from __future__ import annotations

import importlib.util
import sys
import types
from pathlib import Path

import pytest

_SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "doc-graph-svg.py"


def _load_svg():
    for name in ("matplotlib", "matplotlib.pyplot", "numpy"):
        sys.modules.setdefault(name, types.ModuleType(name))
    sys.modules["matplotlib"].pyplot = sys.modules["matplotlib.pyplot"]
    spec = importlib.util.spec_from_file_location("doc_graph_svg", _SCRIPT)
    mod = importlib.util.module_from_spec(spec)
    assert spec and spec.loader
    spec.loader.exec_module(mod)
    return mod


@pytest.fixture(scope="module")
def svg():
    return _load_svg()


class _FakeResult:
    available = True
    doc_count = 1
    graph = object()
    doc_to_code_edges: list = []
    entry_points: list = []
    unreachable: list = []
    orphans: list = []
    pagerank: dict = {}
    broken_links: list = []
    island_count = 0
    orphan_rate = 0.0
    reachability_pct = 0.0


def test_svg_threads_config_and_cli_excludes(svg, tmp_path, monkeypatch, capsys):
    # A repo with a durable config exclude plus an ad-hoc CLI exclude.
    (tmp_path / ".assess").mkdir()
    (tmp_path / ".assess" / "config.toml").write_text(
        'exclude_dirs = ["_archive"]\nexclude_patterns = ["*.csv"]\n'
        'working_notes_dirs = ["journal"]\nworking_notes_ignore = ["docs/chapters"]\n',
        encoding="utf-8",
    )

    captured: dict = {}

    def fake_build(root, *, extra_exclude_dirs=None, extra_exclude_patterns=None,
                   working_notes_dirs=None, working_notes_ignore=None):
        captured["graph_dirs"] = extra_exclude_dirs
        captured["graph_patterns"] = extra_exclude_patterns
        captured["notes"] = (working_notes_dirs, working_notes_ignore)
        return _FakeResult()

    def fake_staleness(root, *, doc_to_code_edges=None,
                       extra_exclude_dirs=None, extra_exclude_patterns=None):
        captured["stale_dirs"] = extra_exclude_dirs
        captured["stale_patterns"] = extra_exclude_patterns
        return {"docs": []}

    monkeypatch.setattr(svg, "build_doc_graph", fake_build)
    monkeypatch.setattr(svg, "analyze_doc_staleness", fake_staleness)
    monkeypatch.setattr(svg, "render", lambda *a, **k: None)
    monkeypatch.setattr(
        sys, "argv",
        ["doc-graph-svg.py", str(tmp_path), "-o", str(tmp_path / "out.svg"),
         "--exclude", "_jira", "--exclude", "*.tmp"],
    )

    assert svg.main() == 0

    # config dir + CLI dir merged; config glob + CLI glob merged.
    assert captured["graph_dirs"] == {"_archive", "_jira"}
    assert captured["graph_patterns"] == ["*.csv", "*.tmp"]
    # The working-notes overrides reach the graph, as in assess_core.
    assert captured["notes"] == (["journal"], ["docs/chapters"])
    # The staleness scan (drives the SVG's colour) gets the identical excludes,
    # so colour and structure speak about the same doc set.
    assert captured["stale_dirs"] == captured["graph_dirs"]
    assert captured["stale_patterns"] == captured["graph_patterns"]


def _render_two_kinds(svg, tmp_path, monkeypatch, colour: str) -> list:
    """Render one link edge and one reference edge; return the parsed elements.

    numpy and matplotlib are stubbed here, so the colour map and the radial
    layout (``nx.shell_layout`` needs numpy) are replaced with fixed stand-ins;
    the edge and legend markup under test is the real code."""
    import xml.etree.ElementTree as ET

    import networkx as nx

    graph = nx.DiGraph()
    graph.add_edge("CLAUDE.md", "docs/linked.md", kind="link")
    graph.add_edge("CLAUDE.md", "docs/ref.md", kind="reference")
    result = _FakeResult()
    result.graph = graph
    result.entry_points = ["CLAUDE.md"]
    result.pagerank = {}
    fixed = {"CLAUDE.md": (500.0, 500.0), "docs/linked.md": (300.0, 300.0),
             "docs/ref.md": (700.0, 300.0)}
    monkeypatch.setattr(svg, "_radial_positions", lambda *a, **k: dict(fixed))
    monkeypatch.setattr(svg.plt, "get_cmap", lambda _name: (lambda _v: (1.0, 1.0, 1.0, 1.0)),
                        raising=False)
    out = tmp_path / "out.svg"
    svg.render(result, out, tmp_path, colour=colour)
    return list(ET.parse(out).iter())


_STYLE_KEYS = ("stroke", "stroke-dasharray", "stroke-width", "opacity")


@pytest.mark.parametrize("colour", ["staleness", "status"])
def test_reference_edge_drawn_distinct_from_link_with_legend(svg, tmp_path, monkeypatch, colour):
    """A reference edge (a backticked doc path) and a link edge render in two
    styles told apart by presentation attributes, and the legend names both.
    The reference dash must not reuse the ghost tether (4,3) or the orphan and
    ghost rings (3,2), which already carry meaning."""
    els = _render_two_kinds(svg, tmp_path, monkeypatch, colour)
    styles = {
        kind: [[e.get(k) for k in _STYLE_KEYS] for e in els if e.get("data-edge-kind") == kind]
        for kind in ("link", "reference")
    }
    assert len(styles["link"]) == 1
    assert len(styles["reference"]) == 1
    assert styles["link"][0] != styles["reference"][0]
    assert styles["reference"][0][1] not in ("4,3", "3,2")
    # Round caps add half the stroke width to both ends of a dash, so the painted
    # bead is dash + width and the painted gap is gap - width. That ratio is
    # scale-invariant, so this assertion proves the caps can never swallow the
    # gap at any scale - not that the dots stay visually distinct once rendered
    # small (at README embed scale both fall under a pixel and only the weight
    # and opacity difference actually survives).
    dash, gap = (float(v) for v in styles["reference"][0][1].split(","))
    width = float(styles["reference"][0][2])
    assert gap - width >= dash + width
    legend = sorted({e.get("data-legend-kind") for e in els if e.get("data-legend-kind")})
    assert legend == ["link", "reference"]
    # Legend samples are drawn in the same style as the edges they explain.
    for kind in ("link", "reference"):
        sample = next(e for e in els if e.get("data-legend-kind") == kind)
        assert [sample.get(k) for k in _STYLE_KEYS] == styles[kind][0]
    texts = [" ".join(e.itertext()).lower() for e in els if e.tag.endswith("text")]
    assert any("reference" in t for t in texts)
    assert any("link" in t for t in texts)


@pytest.mark.parametrize("colour", ["staleness", "status"])
def test_missing_or_unknown_edge_kind_draws_as_link(svg, tmp_path, monkeypatch, colour):
    """An edge with no `kind`, or one that names a kind the SVG doesn't know,
    normalizes to a link - both in styling and in the `data-edge-kind`
    attribute. `_edge_attrs` and the `data-edge-kind` markup both delegate to
    `_normalize_edge_kind`, so the two sites cannot diverge on this rule."""
    import xml.etree.ElementTree as ET

    import networkx as nx

    graph = nx.DiGraph()
    graph.add_edge("CLAUDE.md", "docs/nokind.md")
    graph.add_edge("CLAUDE.md", "docs/weird.md", kind="footnote")
    result = _FakeResult()
    result.graph = graph
    result.entry_points = ["CLAUDE.md"]
    result.pagerank = {}
    fixed = {"CLAUDE.md": (500.0, 500.0), "docs/nokind.md": (300.0, 300.0),
             "docs/weird.md": (700.0, 300.0)}
    monkeypatch.setattr(svg, "_radial_positions", lambda *a, **k: dict(fixed))
    monkeypatch.setattr(svg.plt, "get_cmap", lambda _name: (lambda _v: (1.0, 1.0, 1.0, 1.0)),
                        raising=False)
    out = tmp_path / "out.svg"
    svg.render(result, out, tmp_path, colour=colour)
    els = list(ET.parse(out).iter())
    edges = [e for e in els if e.get("data-edge-kind")]
    assert len(edges) == 2
    link_style = [svg._EDGE_STYLE["link"][k] for k in _STYLE_KEYS]
    for edge in edges:
        assert edge.get("data-edge-kind") == "link"
        assert [edge.get(k) for k in _STYLE_KEYS] == link_style


def test_normalize_edge_kind(svg):
    assert svg._normalize_edge_kind("link") == "link"
    assert svg._normalize_edge_kind("reference") == "reference"
    assert svg._normalize_edge_kind("footnote") == "link"
    assert svg._normalize_edge_kind("") == "link"

"""Tests for provenance-aware staleness of generated docs (issue #178)."""
from __future__ import annotations

import os
from pathlib import Path

from lib.doc_provenance import (
    parse_frontmatter_provenance,
    resolve_doc_sources,
    source_is_newer,
)


def _write(root: Path, rel: str, text: str) -> Path:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")
    return p


def _set_mtime(path: Path, when: float) -> None:
    os.utime(path, (when, when))


# --- frontmatter parsing ---------------------------------------------------

def test_frontmatter_scalar_source(tmp_path: Path) -> None:
    doc = _write(tmp_path, "notes.md", "---\nsource: data/jira.tsv\n---\nbody")
    sources, generated_by = parse_frontmatter_provenance(doc)
    assert sources == ["data/jira.tsv"]
    assert generated_by is None


def test_frontmatter_flow_list_and_generated_by(tmp_path: Path) -> None:
    doc = _write(
        tmp_path, "ref.md",
        "---\nsource: [a.tsv, b.tsv]\ngenerated_by: scripts/gen.py\n---\nx",
    )
    sources, generated_by = parse_frontmatter_provenance(doc)
    assert sources == ["a.tsv", "b.tsv"]
    assert generated_by == "scripts/gen.py"


def test_frontmatter_block_list(tmp_path: Path) -> None:
    doc = _write(
        tmp_path, "ref.md",
        "---\nsource:\n  - a.tsv\n  - b.tsv\n---\nx",
    )
    sources, _ = parse_frontmatter_provenance(doc)
    assert sources == ["a.tsv", "b.tsv"]


def test_frontmatter_quotes_and_inline_comment(tmp_path: Path) -> None:
    doc = _write(tmp_path, "n.md", "---\nsource: \"data/x.tsv\"  # the dump\n---\n")
    sources, _ = parse_frontmatter_provenance(doc)
    assert sources == ["data/x.tsv"]


def test_no_frontmatter_returns_empty(tmp_path: Path) -> None:
    doc = _write(tmp_path, "plain.md", "# Just a heading\nbody")
    assert parse_frontmatter_provenance(doc) == ([], None)


def test_unterminated_frontmatter_degrades(tmp_path: Path) -> None:
    doc = _write(tmp_path, "bad.md", "---\nsource: x.tsv\nno closing fence")
    assert parse_frontmatter_provenance(doc) == ([], None)


# --- resolution ------------------------------------------------------------

def test_resolve_frontmatter_repo_relative(tmp_path: Path) -> None:
    _write(tmp_path, "data/jira.tsv", "data")
    doc = _write(tmp_path, "notes/dump.md", "---\nsource: data/jira.tsv\n---\n")
    resolved, _, method = resolve_doc_sources(doc, tmp_path, [])
    assert method == "frontmatter"
    assert [p.name for p in resolved] == ["jira.tsv"]


def test_resolve_skips_missing_source(tmp_path: Path) -> None:
    doc = _write(tmp_path, "notes/dump.md", "---\nsource: data/gone.tsv\n---\n")
    resolved, _, method = resolve_doc_sources(doc, tmp_path, [])
    assert resolved == []
    assert method == ""


def test_resolve_via_config_mapping(tmp_path: Path) -> None:
    _write(tmp_path, "data/jira.tsv", "data")
    doc = _write(tmp_path, "notes/123.md", "no frontmatter")
    config = [("notes", ["data/jira.tsv"])]
    resolved, _, method = resolve_doc_sources(doc, tmp_path, config)
    assert method == "config"
    assert [p.name for p in resolved] == ["jira.tsv"]


def test_frontmatter_wins_over_config(tmp_path: Path) -> None:
    _write(tmp_path, "data/fm.tsv", "fm")
    _write(tmp_path, "data/cfg.tsv", "cfg")
    doc = _write(tmp_path, "notes/x.md", "---\nsource: data/fm.tsv\n---\n")
    config = [("notes", ["data/cfg.tsv"])]
    resolved, _, method = resolve_doc_sources(doc, tmp_path, config)
    assert method == "frontmatter"
    assert [p.name for p in resolved] == ["fm.tsv"]


def test_config_does_not_match_sibling_prefix(tmp_path: Path) -> None:
    """`path = "notes"` must not match `notes-archive/` (prefix-on-segment)."""
    _write(tmp_path, "data/jira.tsv", "data")
    doc = _write(tmp_path, "notes-archive/x.md", "no fm")
    config = [("notes", ["data/jira.tsv"])]
    _, _, method = resolve_doc_sources(doc, tmp_path, config)
    assert method == ""


# --- source_is_newer (mtime fallback when not in git) ----------------------

def test_source_newer_true(tmp_path: Path) -> None:
    src = _write(tmp_path, "data/jira.tsv", "data")
    doc = _write(tmp_path, "notes/dump.md", "---\nsource: data/jira.tsv\n---\n")
    _set_mtime(doc, 1_000_000)
    _set_mtime(src, 2_000_000)  # source changed after the doc
    assert source_is_newer(doc, [src]) is True


def test_source_newer_false(tmp_path: Path) -> None:
    src = _write(tmp_path, "data/jira.tsv", "data")
    doc = _write(tmp_path, "notes/dump.md", "---\nsource: data/jira.tsv\n---\n")
    _set_mtime(src, 1_000_000)
    _set_mtime(doc, 2_000_000)  # doc regenerated after the source
    assert source_is_newer(doc, [src]) is False


def test_source_newer_none_without_sources(tmp_path: Path) -> None:
    doc = _write(tmp_path, "notes/dump.md", "body")
    assert source_is_newer(doc, []) is None

"""Tests for the doc-staleness metric and doc->code association."""
from __future__ import annotations

from pathlib import Path

from lib.doc_staleness import LARGE_REPO_CODE_FILES, analyze_doc_staleness


def _write(root: Path, rel: str, text: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def test_nearest_ancestor_respects_inner_base_doc(tmp_path: Path) -> None:
    """A base doc owns its subtree down to the next base doc, not past it."""
    _write(tmp_path, "src/payments/README.md", "payments")
    _write(tmp_path, "src/payments/pay.py", "x")
    _write(tmp_path, "src/payments/refund.py", "y")
    _write(tmp_path, "src/payments/ledger/ledger.md", "ledger")  # <dir>.md convention
    _write(tmp_path, "src/payments/ledger/l.py", "z")

    r = analyze_doc_staleness(tmp_path)
    by_path = {d["path"]: d for d in r["docs"]}
    # README owns pay.py + refund.py (2), but NOT ledger/l.py (claimed by ledger.md)
    assert by_path["src/payments/README.md"]["subject_code_count"] == 2
    assert by_path["src/payments/README.md"]["subject_method"] == "nearest-ancestor"
    assert by_path["src/payments/ledger/ledger.md"]["subject_code_count"] == 1


def test_parallel_docs_tree_fallback(tmp_path: Path) -> None:
    _write(tmp_path, "docs/auth.md", "auth docs")
    _write(tmp_path, "src/auth/a.py", "x")
    r = analyze_doc_staleness(tmp_path)
    auth = next(d for d in r["docs"] if d["path"] == "docs/auth.md")
    assert auth["subject_method"] == "parallel-docs-tree"
    assert auth["subject_code_count"] == 1


def test_explicit_links_fallback(tmp_path: Path) -> None:
    _write(tmp_path, "notes.md", "see [code](src/x.py)")
    _write(tmp_path, "src/x.py", "x")
    r = analyze_doc_staleness(
        tmp_path, doc_to_code_edges=[{"doc": "notes.md", "code": "src/x.py"}]
    )
    notes = next(d for d in r["docs"] if d["path"] == "notes.md")
    assert notes["subject_method"] == "explicit-links"


def test_repo_baseline_when_no_association(tmp_path: Path) -> None:
    _write(tmp_path, "floating.md", "no links, no co-location")
    _write(tmp_path, "src/x.py", "x")
    r = analyze_doc_staleness(tmp_path)
    floating = next(d for d in r["docs"] if d["path"] == "floating.md")
    assert floating["subject_method"] == "repo-baseline"


def test_boilerplate_is_not_a_base_doc(tmp_path: Path) -> None:
    _write(tmp_path, "src/LICENSE.md", "MIT")
    _write(tmp_path, "src/x.py", "x")
    r = analyze_doc_staleness(tmp_path)
    # LICENSE must not claim ownership of src/x.py as a base doc
    assert r["association"]["code_under_base_doc"] == 0


def test_modularity_large_repo_flag(tmp_path: Path) -> None:
    for i in range(LARGE_REPO_CODE_FILES + 1):
        _write(tmp_path, f"mod{i}/f.py", "x")
    r = analyze_doc_staleness(tmp_path)
    assert r["modularity"]["large_repo"] is True
    assert r["modularity"]["base_doc_coverage_when_present"] == 0.0  # no base docs anywhere
    assert r["modularity"]["base_doc_dir_ratio"] == 0.0


def test_base_doc_coverage_is_size_weighted(tmp_path: Path) -> None:
    """One 30-file service with a base doc should not be drowned by ten
    1-file utility dirs without one. Size-weighting reflects what an agent
    actually needs to navigate; the un-weighted dir ratio is reported alongside
    for transparency.
    """
    # A large module (30 files) with a base doc...
    _write(tmp_path, "services/payments/README.md", "payments")
    for i in range(30):
        _write(tmp_path, f"services/payments/f{i}.py", "x")
    # ...and ten utility/leaf dirs (1 file each) with no doc.
    for i in range(10):
        _write(tmp_path, f"internal/util{i}/u.py", "x")

    r = analyze_doc_staleness(tmp_path)
    # Un-weighted dir ratio is low (1 doc'd dir out of 11), but the size-weighted
    # coverage reflects that ~75% of code sits under a maintained base doc.
    assert r["modularity"]["base_doc_dir_ratio"] < 0.2
    assert r["modularity"]["base_doc_coverage_when_present"] >= 0.7
    # Sanity: the when-present number matches what the association block reports.
    assert r["modularity"]["base_doc_coverage_when_present"] == r["association"]["pct_code_under_base_doc"]


def test_no_git_degrades_to_zero_churn(tmp_path: Path) -> None:
    """Without git history, churn is zero and last_commit_days is None - no crash."""
    _write(tmp_path, "README.md", "doc")
    _write(tmp_path, "app.py", "x")
    r = analyze_doc_staleness(tmp_path)
    assert r["available"] is True
    readme = next(d for d in r["docs"] if d["path"] == "README.md")
    assert readme["last_commit_days"] is None
    assert readme["code_churn_in_window"] == 0


def test_stale_doc_beside_churny_code_has_high_ratio(git_repo) -> None:
    """The decaying-map signal: old doc + actively churning subject = high ratio."""
    repo, commit = git_repo
    (repo / "README.md").write_text("module map", encoding="utf-8")
    (repo / "app.py").write_text("v = 0", encoding="utf-8")
    # Doc committed long ago, outside the 12-month window.
    commit("initial docs+code", days_ago=500)
    # Code churns repeatedly and recently; the doc never moves again.
    for i in range(5):
        (repo / "app.py").write_text(f"v = {i + 1}", encoding="utf-8")
        commit(f"change {i}", days_ago=20 - i * 2)

    r = analyze_doc_staleness(repo)
    readme = next(d for d in r["docs"] if d["path"] == "README.md")
    assert readme["last_commit_days"] is not None and readme["last_commit_days"] >= 400
    assert readme["code_churn_in_window"] >= 5
    assert readme["doc_churn_in_window"] == 0  # didn't move inside the window
    assert readme["ratio"] >= 5  # frozen map of a churning module


def test_staleness_uses_author_time_not_committer_time(git_repo) -> None:
    """A rebase must not certify a stale doc as fresh.

    A doc authored 90 days ago but rebased/cherry-picked yesterday (fresh
    committer time, original author time) must still read ~90 days stale. Author
    time (`%at`) reflects when the change was originally made; committer time
    (`%ct`) would reset the clock on every rebase and hide the decay.
    """
    repo, commit = git_repo
    (repo / "README.md").write_text("module map", encoding="utf-8")
    (repo / "app.py").write_text("v = 0", encoding="utf-8")
    # Authored 90 days ago, but committer time is yesterday (the rebase artifact).
    commit("docs authored long ago, rebased yesterday", days_ago=90, committer_days_ago=1)

    r = analyze_doc_staleness(repo)
    readme = next(d for d in r["docs"] if d["path"] == "README.md")
    # Author time wins: ~90 days, not ~1. A committer-time read would report <=2.
    assert readme["last_commit_days"] is not None
    assert readme["last_commit_days"] >= 85


def test_churn_degenerate_flag_on_single_commit_per_file_repo(git_repo) -> None:
    """Issue #172: a history where every file shows one commit (a bulk import /
    shallow clone / squashed tree) is degenerate - the churn count is an
    extraction artifact, not activity. The doc-staleness block surfaces that as
    ``churn_degenerate: True`` so downstream consumers discount churn findings."""
    repo, commit = git_repo
    (repo / "README.md").write_text("module map", encoding="utf-8")
    for i in range(6):
        (repo / f"mod{i}.py").write_text(f"x = {i}", encoding="utf-8")
    commit("bulk import - one commit touches every file", days_ago=10)

    r = analyze_doc_staleness(repo)
    assert r["churn_degenerate"] is True


def test_churn_not_degenerate_with_genuine_variance(git_repo) -> None:
    """Regression guard: a repo with a real spread of commits-per-file is NOT
    degenerate, so its high-confidence churn findings are untouched."""
    repo, commit = git_repo
    (repo / "README.md").write_text("module map", encoding="utf-8")
    for i in range(6):
        (repo / f"mod{i}.py").write_text("start", encoding="utf-8")
    commit("init", days_ago=30)
    # mod0 churns repeatedly; mod1 once more; mod2..5 stay frozen -> a spread.
    for j in range(8):
        (repo / "mod0.py").write_text(f"v = {j}", encoding="utf-8")
        commit(f"churn {j}", days_ago=20 - j)
    (repo / "mod1.py").write_text("v = 99", encoding="utf-8")
    commit("touch mod1", days_ago=5)

    r = analyze_doc_staleness(repo)
    assert r["churn_degenerate"] is False


def test_fresh_doc_beside_fresh_code_has_low_ratio(git_repo) -> None:
    repo, commit = git_repo
    (repo / "README.md").write_text("module map", encoding="utf-8")
    (repo / "app.py").write_text("v = 1", encoding="utf-8")
    commit("recent docs+code", days_ago=5)

    r = analyze_doc_staleness(repo)
    readme = next(d for d in r["docs"] if d["path"] == "README.md")
    assert readme["last_commit_days"] is not None and readme["last_commit_days"] <= 30
    # doc and code moved together -> ratio stays near 1 (not a decaying map)
    assert readme["ratio"] <= 2


def test_untracked_files_excluded_from_staleness(git_repo) -> None:
    """Untracked personal docs/code are not part of the repo and aren't scored."""
    repo, commit = git_repo
    (repo / "README.md").write_text("doc", encoding="utf-8")
    (repo / "app.py").write_text("x = 1", encoding="utf-8")
    commit("init", days_ago=3)
    (repo / "personal.md").write_text("private", encoding="utf-8")  # untracked

    r = analyze_doc_staleness(repo)
    doc_paths = {d["path"] for d in r["docs"]}
    assert "README.md" in doc_paths
    assert "personal.md" not in doc_paths
    assert r["association"]["doc_count"] == 1  # only the tracked doc counted


def test_doc_staleness_honors_user_excludes(tmp_path: Path) -> None:
    """User-supplied excludes drop docs AND code under the named dir from
    every staleness calculation - so a `regulatory-raw/` directory full of
    CSV-driven Python loaders doesn't inflate the code-churn denominator
    or surface as a stale-hub candidate."""
    _write(tmp_path, "README.md", "main doc")
    _write(tmp_path, "src/app.py", "x = 1")
    _write(tmp_path, "regulatory-raw/loader.py", "y = 2")
    _write(tmp_path, "regulatory-raw/notes.md", "ref data")

    # Baseline: regulatory-raw files are counted.
    r = analyze_doc_staleness(tmp_path)
    assert r["association"]["doc_count"] == 2
    assert r["association"]["code_file_count"] == 2

    # With the exclude: regulatory-raw drops out of both code and docs.
    r = analyze_doc_staleness(
        tmp_path, extra_exclude_dirs={"regulatory-raw"},
    )
    assert r["association"]["doc_count"] == 1
    assert r["association"]["code_file_count"] == 1
    assert all("regulatory-raw" not in d["path"] for d in r["docs"])


def test_doc_staleness_excludes_test_fixtures(tmp_path: Path) -> None:
    """Markdown and code under `**/tests/fixtures/**` are scanner inputs, not
    repo content, so they must not count toward the staleness association
    (issue #83)."""
    _write(tmp_path, "README.md", "main doc")
    _write(tmp_path, "src/app.py", "x = 1")
    _write(tmp_path, "tests/fixtures/sample/CLAUDE.md", "fixture")
    _write(tmp_path, "tests/fixtures/sample/loader.py", "y = 2")

    r = analyze_doc_staleness(tmp_path)
    assert r["association"]["doc_count"] == 1
    assert r["association"]["code_file_count"] == 1
    assert all("fixtures" not in d["path"] for d in r["docs"])


# --- Provenance-aware staleness for generated docs (issue #178) -----------

def test_generated_doc_source_newer_is_flagged(git_repo) -> None:
    """A generated doc whose declared source committed AFTER it -> source_newer
    True. Staleness is measured against the source, not the doc's own age."""
    repo, commit = git_repo
    (repo / "data").mkdir()
    (repo / "data" / "jira.tsv").write_text("rows v1", encoding="utf-8")
    (repo / "notes").mkdir()
    (repo / "notes" / "dump.md").write_text(
        "---\nsource: data/jira.tsv\ngenerated_by: scripts/gen.py\n---\nnotes",
        encoding="utf-8",
    )
    commit("generate notes from source", days_ago=24)
    # The source moves on; the generated dump is never regenerated.
    (repo / "data" / "jira.tsv").write_text("rows v2", encoding="utf-8")
    commit("source data updated", days_ago=1)

    r = analyze_doc_staleness(repo)
    dump = next(d for d in r["docs"] if d["path"] == "notes/dump.md")
    assert dump["provenance"]["method"] == "frontmatter"
    assert dump["provenance"]["sources"] == ["data/jira.tsv"]
    assert dump["provenance"]["generated_by"] == "scripts/gen.py"
    assert dump["provenance"]["source_newer"] is True


def test_generated_doc_source_not_newer_is_fresh(git_repo) -> None:
    """An old-but-accurate generated doc (regenerated AFTER its source last
    moved) is fresh: source_newer False and ratio forced to 0 so no downstream
    consumer reads it as a decaying/lying map."""
    repo, commit = git_repo
    (repo / "data").mkdir()
    (repo / "data" / "jira.tsv").write_text("rows", encoding="utf-8")
    commit("source data", days_ago=30)
    # Regenerate the dump well after the source last changed.
    (repo / "notes").mkdir()
    (repo / "notes" / "dump.md").write_text(
        "---\nsource: data/jira.tsv\n---\nnotes", encoding="utf-8",
    )
    commit("regenerate notes", days_ago=2)

    r = analyze_doc_staleness(repo)
    dump = next(d for d in r["docs"] if d["path"] == "notes/dump.md")
    assert dump["provenance"]["source_newer"] is False
    assert dump["ratio"] == 0.0  # provably matches source -> not a decaying map


def test_generated_doc_via_config_mapping(tmp_path: Path) -> None:
    """A bulk-generated tree declares provenance via .assess/config.toml rather
    than per-file frontmatter; staleness still measured against the source."""
    import os
    (tmp_path / "data").mkdir()
    src = tmp_path / "data" / "jira.tsv"
    src.write_text("rows", encoding="utf-8")
    (tmp_path / "notes").mkdir()
    doc = tmp_path / "notes" / "123.md"
    doc.write_text("no frontmatter here", encoding="utf-8")
    os.utime(doc, (1_000_000, 1_000_000))
    os.utime(src, (2_000_000, 2_000_000))  # source newer than the doc

    r = analyze_doc_staleness(
        tmp_path, generated_sources=[("notes", ["data/jira.tsv"])]
    )
    doc_row = next(d for d in r["docs"] if d["path"] == "notes/123.md")
    assert doc_row["provenance"]["method"] == "config"
    assert doc_row["provenance"]["source_newer"] is True


def test_ordinary_doc_has_no_provenance_block(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "plain doc, no source declared")
    _write(tmp_path, "app.py", "x")
    r = analyze_doc_staleness(tmp_path)
    readme = next(d for d in r["docs"] if d["path"] == "README.md")
    assert "provenance" not in readme


# --- Bulk mechanical commits (issue #333) -----------------------------------

_BULK_DOCS = [
    "CLAUDE.md", "docs/architecture.md", "docs/billing.md", "docs/caching.md",
    "docs/deploy.md", "docs/events.md", "docs/glossary.md", "docs/logging.md",
    "docs/metrics.md", "docs/onboarding.md", "docs/releases.md",
    "docs/security.md",
]


def _bulk_fixture(repo: Path, commit) -> None:
    """Twelve docs written 300..190 days ago, one licence-header commit 8 days
    ago touching all twelve, then a genuine one-doc edit 3 days ago."""
    days = 300
    for rel in _BULK_DOCS:
        _write(repo, rel, f"Original text of {rel}.\n")
        commit(f"docs: write {rel}", days_ago=days)
        days -= 10
    for rel in _BULK_DOCS:
        p = repo / rel
        p.write_text("<!-- SPDX-License-Identifier: MIT -->\n" + p.read_text(), encoding="utf-8")
    commit("chore: licence headers", days_ago=8)
    p = repo / "docs/caching.md"
    p.write_text(p.read_text() + "A genuine closing section.\n", encoding="utf-8")
    commit("docs: caching invalidation", days_ago=3)


def _head_sha(repo: Path, rev: str) -> str:
    import subprocess
    return subprocess.run(["git", "-C", str(repo), "rev-parse", rev],
                          capture_output=True, text=True, check=True).stdout.strip()


def test_bulk_commit_does_not_reset_doc_staleness(git_repo) -> None:
    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    r = analyze_doc_staleness(repo)
    days = {d["path"]: d["last_commit_days"] for d in r["docs"]}
    expected = {rel: 300 - 10 * i for i, rel in enumerate(_BULK_DOCS)}
    expected["docs/caching.md"] = 3
    # One day of slack: the fixture stamps naive local time, so a DST change
    # between then and now moves a 300-day-old commit by an hour.
    assert set(days) == set(expected)
    assert all(abs(days[k] - v) <= 1 for k, v in expected.items()), days
    assert days["docs/caching.md"] == 3


def test_bulk_commit_is_recorded_with_full_sha(git_repo) -> None:
    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    r = analyze_doc_staleness(repo)
    bulk_sha = _head_sha(repo, "HEAD~1")
    skipped = r["bulk_commits_skipped"]
    assert [s["sha"] for s in skipped] == [bulk_sha]
    assert len(skipped[0]["sha"]) == 40
    assert skipped[0]["docs_touched"] == 12
    assert skipped[0]["doc_count"] == 12
    assert r["bulk_commits_skipped_total"] == 1
    assert r["bulk_commit_scan_complete"] is True


def test_single_doc_commit_is_not_bulk(git_repo) -> None:
    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    r = analyze_doc_staleness(repo)
    caching_edit = _head_sha(repo, "HEAD")
    assert caching_edit not in {s["sha"] for s in r["bulk_commits_skipped"]}


def test_doc_created_in_bulk_commit_keeps_its_creation_date(git_repo) -> None:
    """A bulk import that adds every doc is the docs' content creation: a later
    bulk sweep falls back to it, not to the sweep and not to None."""
    repo, commit = git_repo
    for rel in _BULK_DOCS:
        _write(repo, rel, f"Imported {rel}.\n")
    commit("import docs", days_ago=100)
    for rel in _BULK_DOCS:
        p = repo / rel
        p.write_text("<!-- header -->\n" + p.read_text(), encoding="utf-8")
    commit("chore: headers", days_ago=5)
    r = analyze_doc_staleness(repo)
    assert {d["last_commit_days"] for d in r["docs"]} == {100}
    assert [s["sha"] for s in r["bulk_commits_skipped"]] == [_head_sha(repo, "HEAD")]


def test_small_repo_all_docs_commit_is_not_bulk(git_repo) -> None:
    """Below the minimum-docs floor, editing every doc at once is ordinary work."""
    repo, commit = git_repo
    for rel in ("README.md", "docs/a.md", "docs/b.md"):
        _write(repo, rel, "v1\n")
    commit("docs", days_ago=50)
    for rel in ("README.md", "docs/a.md", "docs/b.md"):
        _write(repo, rel, "v2\n")
    commit("docs: rewrite", days_ago=4)
    r = analyze_doc_staleness(repo)
    assert {d["last_commit_days"] for d in r["docs"]} == {4}
    assert r["bulk_commits_skipped"] == []


def test_no_git_reports_no_bulk_commits(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "doc")
    r = analyze_doc_staleness(tmp_path)
    assert r["bulk_commits_skipped"] == []
    assert r["bulk_commits_skipped_total"] == 0


def test_instruction_freshness_skips_bulk_commit(git_repo) -> None:
    """The instruction grader's clock shares the bulk-commit skip."""
    from assess_core import _grade_instruction_files

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    files = _grade_instruction_files(repo)[0]
    assert files["CLAUDE.md"]["freshness_days"] in (299, 300)  # DST slack


def _sweep(repo: Path, commit, tag: str, days_ago: int, extra=()) -> None:
    for rel in list(_BULK_DOCS) + list(extra):
        p = repo / rel
        p.write_text(f"<!-- {tag} -->\n" + p.read_text(), encoding="utf-8")
    commit(f"chore: {tag}", days_ago=days_ago)


def test_doc_regenerated_only_in_bulk_is_flagged_as_creation_date(git_repo) -> None:
    """Docs regenerated in bulk every release have no content commit: the
    creation-date fallback is disclosed and discounted, not passed off as age."""
    repo, commit = git_repo
    for rel in _BULK_DOCS:
        _write(repo, rel, f"Generated {rel}.\n")
    commit("docs: generate", days_ago=400)
    for n, days in enumerate((200, 30, 2)):
        _sweep(repo, commit, f"regen {n}", days)
    r = analyze_doc_staleness(repo)
    assert r["creation_date_fallback_count"] == 12
    for d in r["docs"]:
        assert d["last_change_basis"] == "creation"
        assert d["confidence"] == "low"


def test_content_dated_doc_has_no_basis_key(git_repo) -> None:
    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    r = analyze_doc_staleness(repo)
    assert r["creation_date_fallback_count"] == 0
    assert all("last_change_basis" not in d for d in r["docs"])


def test_skipped_list_is_capped_and_total_is_kept(git_repo) -> None:
    from lib.git_churn import BULK_COMMITS_SKIPPED_CAP

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    sweeps = BULK_COMMITS_SKIPPED_CAP + 1
    for n in range(sweeps):
        _sweep(repo, commit, f"sweep {n}", days_ago=2)
    r = analyze_doc_staleness(repo)
    assert len(r["bulk_commits_skipped"]) == BULK_COMMITS_SKIPPED_CAP
    assert r["bulk_commits_skipped_total"] == sweeps + 1
    assert r["bulk_commits_skipped"][0]["sha"] == _head_sha(repo, "HEAD")


def test_mass_rename_keeps_pre_rename_content_dates(git_repo) -> None:
    import subprocess

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    subprocess.run(["git", "-C", str(repo), "mv", "docs", "guide"], check=True)
    commit("chore: move docs to guide", days_ago=1)
    r = analyze_doc_staleness(repo)
    days = {d["path"]: d["last_commit_days"] for d in r["docs"]}
    assert days["guide/caching.md"] == 3
    assert days["guide/security.md"] in (189, 190)  # DST slack


def test_scan_incomplete_when_git_log_times_out(git_repo, monkeypatch) -> None:
    """A timed-out history read degrades to the plain newest-commit clock and
    says so, rather than reading as "no bulk commits"."""
    import subprocess

    import lib.git_churn as gc

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    real_run = subprocess.run

    def fake_run(cmd, *a, **k):
        if "--no-renames" in cmd:
            raise subprocess.TimeoutExpired(cmd, 1)
        return real_run(cmd, *a, **k)

    gc.content_commit_clock.cache_clear()
    monkeypatch.setattr(gc.subprocess, "run", fake_run)
    r = analyze_doc_staleness(repo)
    gc.content_commit_clock.cache_clear()
    assert r["bulk_commit_scan_complete"] is False
    assert r["bulk_commits_skipped"] == []
    days = {d["path"]: d["last_commit_days"] for d in r["docs"]}
    assert days["CLAUDE.md"] == 8  # plain newest-commit read


def test_shallow_clone_marks_scan_incomplete(git_repo, tmp_path: Path) -> None:
    import subprocess

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    clone = tmp_path / "shallow"
    subprocess.run(["git", "clone", "-q", "--depth", "2", f"file://{repo}", str(clone)],
                   check=True)
    r = analyze_doc_staleness(clone)
    assert r["bulk_commit_scan_complete"] is False


def test_non_doc_instruction_file_skips_bulk_commit(git_repo) -> None:
    """`.cursorrules` is outside the docs' pathspec; the per-file route applies
    the same bulk skip."""
    from assess_core import _grade_instruction_files

    repo, commit = git_repo
    _write(repo, ".cursorrules", "Prefer small functions.\n")
    commit("add cursor rules", days_ago=400)
    _bulk_fixture(repo, commit)
    rules = repo / ".cursorrules"
    rules.write_text("# header\n" + rules.read_text(), encoding="utf-8")
    for rel in _BULK_DOCS:
        p = repo / rel
        p.write_text("<!-- again -->\n" + p.read_text(), encoding="utf-8")
    commit("chore: headers everywhere", days_ago=5)
    files = _grade_instruction_files(repo)[0]
    assert files[".cursorrules"]["freshness_days"] in (399, 400)  # DST slack


def test_shallow_probe_timeout_marks_scan_incomplete(git_repo, monkeypatch) -> None:
    """A timed-out shallow probe must not escape the clock or vouch for it."""
    import subprocess

    import lib.git_churn as gc

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    real_run = subprocess.run

    def fake_run(cmd, *a, **k):
        if "--is-shallow-repository" in cmd:
            raise subprocess.TimeoutExpired(cmd, 1)
        return real_run(cmd, *a, **k)

    gc.content_commit_clock.cache_clear()
    monkeypatch.setattr(gc.subprocess, "run", fake_run)
    r = analyze_doc_staleness(repo)
    gc.content_commit_clock.cache_clear()
    assert r["bulk_commit_scan_complete"] is False
    days = {d["path"]: d["last_commit_days"] for d in r["docs"]}
    assert days["docs/caching.md"] == 3


def test_rename_scan_failure_marks_scan_incomplete(git_repo, monkeypatch) -> None:
    """A rename map that could not be read leaves renames unfollowed, so the
    completeness flag must not vouch for the scan."""
    import lib.change_coupling as cc
    import lib.doc_staleness as ds
    import lib.git_churn as gc

    repo, commit = git_repo
    _bulk_fixture(repo, commit)
    monkeypatch.setattr(cc, "build_rename_map",
                        lambda *a, **k: cc.RenameMap({}, complete=False))
    ds._clock_at.cache_clear()
    gc.content_commit_clock.cache_clear()
    r = analyze_doc_staleness(repo)
    ds._clock_at.cache_clear()
    assert r["bulk_commit_scan_complete"] is False
    days = {d["path"]: d["last_commit_days"] for d in r["docs"]}
    assert days["docs/caching.md"] == 3

"""Tests for the emit-workflow CLI wrapper (assess_emit_workflow.py).

The wrapper derives sensible defaults (version from the running plugin, checked
against the published tags; branch from git; tools from PATH) so the
orchestrator can emit the frozen-harness workflow with a single argument. These
tests pin the default derivation, the tag check and arg parsing. Every network
call goes through ``assess_emit_workflow._run``, stubbed here with a fake
``gh`` / ``git ls-remote`` so no test touches the network.
"""
from __future__ import annotations

import json
import re
from pathlib import Path

import pytest

import assess_emit_workflow as emit
from assess_emit_workflow import main

RUNNING = "1.60.2"


def _write_ctx(tmp_path: Path, version: str | None) -> None:
    (tmp_path / ".assess").mkdir(parents=True, exist_ok=True)
    ctx = {"plugin_version": version} if version is not None else {}
    (tmp_path / ".assess" / "run-context.json").write_text(json.dumps(ctx))


def _workflow(tmp_path: Path) -> str:
    return (tmp_path / ".github" / "workflows" / "assess-gate.yml").read_text()


def _pins(text: str) -> set[str]:
    """Every toolkit version the workflow names (header comment and uses: line)."""
    return set(re.findall(r"ai-native-toolkit[ @]v([0-9][0-9.]*)", text))


def _fake_remote(tags: list[str] | None, with_action: set[str], *, gh_up: bool = True):
    """A stand-in for ``_run``: ``git ls-remote`` lists ``tags`` (``None`` = git
    offline); ``gh api .../contents/action.yml?ref=<tag>`` succeeds for tags in
    ``with_action`` and answers HTTP 404 otherwise (``gh_up=False`` = gh offline)."""

    def run(cmd: list[str]) -> tuple[int, str, str]:
        if cmd[0] == "git":
            if tags is None:
                return 128, "", "fatal: Could not resolve host: github.com"
            out = "".join(f"{i:040x}\trefs/tags/{t}\n" for i, t in enumerate(tags))
            return 0, out, ""
        if cmd[0] == "gh":
            if not gh_up:
                return 1, "", "error connecting to api.github.com"
            ref = cmd[-1].rsplit("ref=", 1)[-1]
            if ref in with_action:
                return 0, '{"path": "action.yml"}', ""
            return 1, "", f"gh: No commit found for the ref {ref} (HTTP 404)"
        raise AssertionError(f"unexpected command {cmd}")

    return run


@pytest.fixture
def running(monkeypatch):
    monkeypatch.setattr(emit, "_running_version", lambda: RUNNING)


def test_stale_run_context_ignored(tmp_path, monkeypatch, running):
    _write_ctx(tmp_path, "1.23.2")
    monkeypatch.setattr(emit, "_run", _fake_remote(["v1.23.0", f"v{RUNNING}"], {f"v{RUNNING}"}))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    text = _workflow(tmp_path)
    assert _pins(text) == {RUNNING}
    assert f"uses: bjcoombs/ai-native-toolkit@v{RUNNING}" in text


def test_unpublished_version_falls_back(tmp_path, monkeypatch, running, capsys):
    # The running tag is unpublished and the newest tag ships no action.yml:
    # the generator walks down to the newest tag that does.
    tags = ["v1.23.0", "v1.41.0", "v1.57.0", "v1.58.2", "v1.59.0", "standalone-skills-v1.60.2"]
    monkeypatch.setattr(emit, "_run", _fake_remote(tags, {"v1.57.0", "v1.58.2"}))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    assert _pins(_workflow(tmp_path)) == {"1.58.2"}
    err = capsys.readouterr().err
    assert "v1.58.2" in err and f"v{RUNNING}" in err


def test_unpublished_version_falls_back_without_gh(tmp_path, monkeypatch, running, capsys):
    # gh unreachable but git works: the newest tag at or after the first
    # release that shipped action.yml is chosen from the ls-remote list.
    tags = ["v1.23.0", "v1.58.2", "v1.41.0", "standalone-skills-v1.60.2"]
    monkeypatch.setattr(emit, "_run", _fake_remote(tags, set(), gh_up=False))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    assert _pins(_workflow(tmp_path)) == {"1.58.2"}
    assert "v1.58.2" in capsys.readouterr().err


def test_published_version_pinned_without_gh(tmp_path, monkeypatch, running):
    monkeypatch.setattr(emit, "_run", _fake_remote(["v1.58.2", f"v{RUNNING}"], set(), gh_up=False))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    assert _pins(_workflow(tmp_path)) == {RUNNING}


def test_offline_emits_unverified(tmp_path, monkeypatch, running, capsys):
    _write_ctx(tmp_path, "1.23.2")
    monkeypatch.setattr(emit, "_run", _fake_remote(None, set(), gh_up=False))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    assert _pins(_workflow(tmp_path)) == {RUNNING}
    err = capsys.readouterr().err
    assert any("unverified" in line.lower() and f"v{RUNNING}" in line for line in err.splitlines())


def test_no_published_tag_with_action_refuses(tmp_path, monkeypatch, running, capsys):
    # gh 404s the running tag and no published tag qualifies: v<running> is known
    # missing, so nothing is written rather than a uses: line that cannot resolve.
    monkeypatch.setattr(emit, "_run", _fake_remote(["v1.23.0"], set()))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 1
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()
    err = capsys.readouterr().err
    assert f"v{RUNNING} is not published" in err and "--version" in err


def test_running_tag_404_and_git_offline_refuses(tmp_path, monkeypatch, running, capsys):
    # gh 404s the running tag, then git ls-remote fails: no fallback list, and
    # the running tag is known missing, so the generator refuses.
    fake = _fake_remote(None, set())
    monkeypatch.setattr(emit, "_run", fake)
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 1
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()
    assert "--version" in capsys.readouterr().err


def test_happy_path_skips_tag_listing(tmp_path, monkeypatch, running):
    # The running tag ships action.yml: one gh call, no git ls-remote round trip.
    calls: list[str] = []
    fake = _fake_remote([f"v{RUNNING}"], {f"v{RUNNING}"})

    def run(cmd):
        calls.append(cmd[0])
        return fake(cmd)

    monkeypatch.setattr(emit, "_run", run)
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    assert _pins(_workflow(tmp_path)) == {RUNNING}
    assert calls == ["gh"]


def test_gh_failing_mid_walk_pins_published_tag(tmp_path, monkeypatch, running, capsys):
    # gh answers the running tag with a definite 404, then degrades (a secondary
    # rate limit): the newest published release after action.yml shipped is
    # pinned, never the running tag gh just said does not exist.
    gh_calls = 0
    tags = ["v1.41.0", "v1.57.0", "v1.58.2"]
    fake = _fake_remote(tags, set())

    def run(cmd):
        nonlocal gh_calls
        if cmd[0] == "gh":
            gh_calls += 1
            if gh_calls > 1:
                return 1, "", "gh: You have exceeded a secondary rate limit (HTTP 403)"
        return fake(cmd)

    monkeypatch.setattr(emit, "_run", run)
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 0
    assert _pins(_workflow(tmp_path)) == {"1.58.2"}
    assert "v1.58.2" in capsys.readouterr().err


def test_unknown_running_version_without_fallback_refuses(tmp_path, monkeypatch, capsys):
    # No readable plugin.json and no published tag: a guessed ref (vlatest) can
    # never resolve, so nothing is written and the exit code is non-zero.
    monkeypatch.setattr(emit, "_running_version", lambda: None)
    monkeypatch.setattr(emit, "_run", _fake_remote(None, set(), gh_up=False))
    assert main([str(tmp_path), "--branch", "main", "--tools", "lizard"]) == 1
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()
    err = capsys.readouterr().err
    assert "version is unknown" in err and "--version" in err


def test_running_version_reads_plugin_json():
    root = Path(emit.__file__).resolve().parents[3]
    expected = json.loads((root / ".claude-plugin" / "plugin.json").read_text())["version"]
    assert emit._running_version() == expected


def test_main_emits_with_explicit_flags(tmp_path, monkeypatch):
    # An explicit --version is the user's override: emitted as given, no lookup.
    def no_network(cmd):
        raise AssertionError(f"explicit --version must not hit the network: {cmd}")

    monkeypatch.setattr(emit, "_run", no_network)
    rc = main([str(tmp_path), "--version", "1.23.0", "--branch", "develop", "--tools", "lizard,scc"])
    assert rc == 0
    workflow = _workflow(tmp_path)
    assert _pins(workflow) == {"1.23.0"}
    assert "branches: [develop]" in workflow
    assert "Install scc" in workflow


def test_main_no_args_usage_error(capsys):
    assert main([]) == 2
    assert "Usage" in capsys.readouterr().err


def _pull_request(tmp_path: Path) -> dict:
    yaml = pytest.importorskip("yaml")
    doc = yaml.safe_load(_workflow(tmp_path))
    on = doc.get("on", doc.get(True))  # PyYAML reads a bare `on:` key as True
    return on["pull_request"]


_FLAGS = ["--version", "9.9.9", "--branch", "main", "--tools", "lizard"]
_NOTICE = "Applied the default paths-ignore"


def _existing_workflow(tmp_path: Path, body: str) -> None:
    wf = tmp_path / ".github" / "workflows"
    wf.mkdir(parents=True)
    (wf / "ci.yml").write_text(body)


_FILTERED = "on:\n  pull_request:\n    paths:\n      - src/**\n"


def test_main_paths_ignore_flag(tmp_path):
    assert main([str(tmp_path), *_FLAGS, "--paths-ignore", "**/*.md"]) == 0
    assert _pull_request(tmp_path) == {"branches": ["main"], "paths-ignore": ["**/*.md"]}


def test_main_paths_flag_repeatable(tmp_path):
    assert main([str(tmp_path), *_FLAGS, "--paths", "src/**", "--paths", "lib/**"]) == 0
    assert _pull_request(tmp_path) == {"branches": ["main"], "paths": ["src/**", "lib/**"]}


def test_main_paths_and_paths_ignore_together_is_usage_error(tmp_path, capsys):
    assert main([str(tmp_path), *_FLAGS, "--paths", "src/**", "--paths-ignore", "**/*.md"]) == 2
    assert "--paths" in capsys.readouterr().err
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()


@pytest.mark.parametrize("body", [_FILTERED, "jobs:\n  t:\n    steps:\n      - uses: dorny/paths-filter@v3\n"])
def test_path_filter_default_applied(tmp_path, capsys, body):
    _existing_workflow(tmp_path, body)
    assert main([str(tmp_path), *_FLAGS]) == 0
    assert _pull_request(tmp_path) == {"branches": ["main"], "paths-ignore": ["**/*.md", ".assess/**"]}
    notice = [line for line in capsys.readouterr().err.splitlines() if _NOTICE in line]
    assert len(notice) == 1
    assert "**/*.md" in notice[0] and ".assess/" in notice[0] and "ci.yml" in notice[0]
    assert "lying_map" in notice[0]  # names what the default stops gating
    assert "required status check" in notice[0]  # a skipped PR reports no gate check


def test_path_filter_default_not_applied_without_filtered_workflow(tmp_path, capsys):
    _existing_workflow(tmp_path, "on:\n  pull_request:\njobs:\n  t:\n    steps:\n      - run: true\n")
    assert main([str(tmp_path), *_FLAGS]) == 0
    assert _pull_request(tmp_path) == {"branches": ["main"]}
    assert _NOTICE not in capsys.readouterr().err


def test_path_filter_default_not_applied_over_explicit_flag(tmp_path, capsys):
    _existing_workflow(tmp_path, _FILTERED)
    assert main([str(tmp_path), *_FLAGS, "--paths", "src/**"]) == 0
    assert _pull_request(tmp_path) == {"branches": ["main"], "paths": ["src/**"]}
    assert _NOTICE not in capsys.readouterr().err


@pytest.mark.parametrize("flag", ["--paths", "--paths-ignore", "--branch"])
def test_main_flag_without_value_is_usage_error(tmp_path, capsys, flag):
    _existing_workflow(tmp_path, _FILTERED)
    assert main([str(tmp_path), "--version", "9.9.9", "--tools", "lizard", flag]) == 2
    assert f"{flag} needs a value" in capsys.readouterr().err
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()


@pytest.mark.parametrize("flag", ["--paths", "--paths-ignore"])
def test_main_flag_followed_by_another_flag_is_usage_error(tmp_path, capsys, flag):
    # `--paths --branch main` must not emit a `paths: ['--branch']` filter.
    assert main([str(tmp_path), "--version", "9.9.9", "--tools", "lizard", flag, "--branch", "main"]) == 2
    assert f"{flag} needs a value" in capsys.readouterr().err
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()


def test_main_unquoted_glob_expansion_is_usage_error(tmp_path, capsys):
    # `--paths src/*` unquoted: the shell hands over src/a and src/b.
    assert main([str(tmp_path), *_FLAGS, "--paths", "src/a", "src/b"]) == 2
    assert "src/b" in capsys.readouterr().err
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()


@pytest.mark.parametrize("flag", ["--paths", "--paths-ignore"])
@pytest.mark.parametrize("value", ["", "  "])
def test_main_empty_filter_value_is_usage_error(tmp_path, capsys, flag, value):
    # `--paths ""` must not emit a `paths:` list holding one empty scalar, a
    # filter that parses but never fires.
    assert main([str(tmp_path), *_FLAGS, flag, value]) == 2
    assert f"{flag} needs a non-empty value" in capsys.readouterr().err
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()


@pytest.mark.parametrize("arg", ["--paths=src/**", "--paths-ignore=**/*.md", "--bogus"])
def test_main_unknown_option_is_usage_error(tmp_path, capsys, arg):
    # The equals form was skipped silently, so the default paths-ignore was
    # written: the inverse of `--paths=src/**`.
    _existing_workflow(tmp_path, _FILTERED)
    assert main([str(tmp_path), *_FLAGS, arg]) == 2
    assert f"Unknown option {arg}" in capsys.readouterr().err
    assert not (tmp_path / ".github" / "workflows" / "assess-gate.yml").exists()

"""Tests for lib/evidence_check.py - deterministic re-check of scorer evidence.

Each evidence entry is re-checked with exists() or a literal substring search.
A false entry lands in ``evidence_rejected`` with its kind and arguments intact
(that is what "naming the entry" means); a true one lands in ``evidence``.
"""
from __future__ import annotations

import json
import os
import subprocess
import sys
from pathlib import Path

import pytest

from lib.evidence_check import check_evidence, is_referenced_in

SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"

WORKFLOW = (
    "on: push\n"
    "jobs:\n"
    "  lint:\n"
    "    runs-on: ubuntu-latest\n"
    "    steps:\n"
    "      - run: bash scripts/check-x.sh\n"
)


@pytest.fixture
def repo(tmp_path: Path) -> Path:
    (tmp_path / "docs").mkdir()
    (tmp_path / "scripts").mkdir()
    (tmp_path / ".github" / "workflows").mkdir(parents=True)
    (tmp_path / "docs" / "guide.md").write_text("# guide\n")
    (tmp_path / "scripts" / "check-x.sh").write_text("echo ok\n")
    (tmp_path / ".github" / "workflows" / "ci.yml").write_text(WORKFLOW)
    return tmp_path


def test_path_absent_for_existing_file_is_rejected_and_named(repo: Path) -> None:
    entry = {"layer": 0, "kind": "path_absent", "path": "docs/guide.md"}
    result = check_evidence(repo, [entry])
    assert result["evidence"] == []
    assert len(result["evidence_rejected"]) == 1
    rejected = result["evidence_rejected"][0]
    assert rejected["kind"] == "path_absent"
    assert rejected["path"] == "docs/guide.md"
    assert rejected["layer"] == 0
    assert rejected["reason"]


def test_not_referenced_in_for_script_a_workflow_calls_is_rejected(repo: Path) -> None:
    entry = {
        "layer": 7,
        "kind": "not_referenced_in",
        "needle": "scripts/check-x.sh",
        "path": ".github/workflows",
    }
    result = check_evidence(repo, [entry])
    assert result["evidence"] == []
    rejected = result["evidence_rejected"]
    assert [(e["kind"], e["path"], e["needle"]) for e in rejected] == [
        ("not_referenced_in", ".github/workflows", "scripts/check-x.sh")
    ]


def test_all_true_input_passes_with_no_rejected_entries(repo: Path) -> None:
    entries = [
        {"layer": 0, "kind": "path_exists", "path": "docs/guide.md"},
        {"layer": 0, "kind": "path_absent", "path": "docs/missing.md"},
        {"layer": 7, "kind": "referenced_in", "needle": "scripts/check-x.sh",
         "path": ".github/workflows"},
        {"layer": 7, "kind": "not_referenced_in", "needle": "scripts/other.sh",
         "path": ".github/workflows"},
        {"layer": 0, "kind": "file_contains", "path": "docs/guide.md",
         "needle": "# guide"},
    ]
    result = check_evidence(repo, entries)
    assert result["evidence_rejected"] == []
    assert result["evidence"] == entries


def test_one_false_entry_of_each_kind_is_rejected(repo: Path) -> None:
    entries = [
        {"layer": 0, "kind": "path_exists", "path": "docs/missing.md"},
        {"layer": 0, "kind": "path_absent", "path": "docs/guide.md"},
        {"layer": 7, "kind": "referenced_in", "needle": "scripts/other.sh",
         "path": ".github/workflows"},
        {"layer": 7, "kind": "not_referenced_in", "needle": "scripts/check-x.sh",
         "path": ".github/workflows"},
        {"layer": 0, "kind": "file_contains", "path": "docs/guide.md",
         "needle": "no such text"},
    ]
    result = check_evidence(repo, entries)
    assert result["evidence"] == []
    assert [e["kind"] for e in result["evidence_rejected"]] == [
        e["kind"] for e in entries
    ]


def test_unknown_keys_pass_through_and_input_is_not_mutated(repo: Path) -> None:
    entry = {"layer": 0, "kind": "path_exists", "path": "docs/guide.md", "note": "x"}
    result = check_evidence(repo, [entry])
    assert result["evidence"] == [entry]
    bad = {"layer": 0, "kind": "path_exists", "path": "nope", "note": "y"}
    result = check_evidence(repo, [bad])
    assert result["evidence_rejected"][0]["note"] == "y"
    assert "reason" not in bad


@pytest.mark.parametrize(
    ("entry", "reason"),
    [
        ({"layer": 0, "kind": "no_such_kind", "path": "docs/guide.md"}, "unknown kind"),
        ({"layer": 0, "kind": "path_exists"}, "missing path"),
        ({"layer": 7, "kind": "referenced_in", "path": ".github/workflows"}, "missing needle"),
        ({"layer": 0, "kind": "file_contains", "path": "docs/guide.md", "needle": ""},
         "missing needle"),
        ({"layer": 0, "kind": "path_exists", "path": "../outside.md"},
         "outside the repository root"),
        ({"layer": 0, "kind": "path_absent", "path": "/etc/passwd"},
         "outside the repository root"),
        ({"layer": 0, "kind": "file_contains", "path": "docs", "needle": "guide"},
         "not a file"),
        ({"layer": 7, "kind": "not_referenced_in", "needle": "x.sh",
          "path": ".github/nowhere"}, "does not exist"),
        ("not an object", "not an object"),
    ],
)
def test_malformed_or_unverifiable_entries_are_rejected(repo: Path, entry, reason: str) -> None:
    result = check_evidence(repo, [entry])
    assert result["evidence"] == []
    assert len(result["evidence_rejected"]) == 1
    assert reason in result["evidence_rejected"][0]["reason"]


def test_named_path_through_a_symlinked_directory_out_of_the_repo_is_rejected(
    repo: Path, tmp_path_factory
) -> None:
    outside = tmp_path_factory.mktemp("outside")
    (outside / "notes.md").write_text("scripts/secret.sh\n")
    (repo / "docs" / "ext").symlink_to(outside, target_is_directory=True)
    entries = [
        {"layer": 0, "kind": "path_exists", "path": "docs/ext/notes.md"},
        {"layer": 0, "kind": "file_contains", "path": "docs/ext/notes.md",
         "needle": "scripts/secret.sh"},
        {"layer": 7, "kind": "referenced_in", "needle": "scripts/secret.sh",
         "path": "docs/ext"},
    ]
    result = check_evidence(repo, entries)
    assert result["evidence"] == []
    assert all("outside the repository root" in e["reason"]
               for e in result["evidence_rejected"])
    assert is_referenced_in(repo, "scripts/secret.sh", "docs/ext") is False


def test_lone_surrogate_needle_is_rejected_not_raised(repo: Path) -> None:
    [needle] = json.loads('["\\ud800"]')
    entries = [
        {"layer": 7, "kind": kind, "needle": needle, "path": path}
        for kind, path in (("referenced_in", ".github/workflows"),
                           ("not_referenced_in", ".github/workflows"),
                           ("file_contains", "docs/guide.md"))
    ]
    result = check_evidence(repo, entries)
    assert result["evidence"] == []
    assert all("not valid text" in e["reason"] for e in result["evidence_rejected"])
    assert is_referenced_in(repo, needle, ".github/workflows") is False


def test_is_referenced_in_searches_a_directory_or_a_single_file(repo: Path) -> None:
    assert is_referenced_in(repo, "scripts/check-x.sh", ".github/workflows") is True
    assert is_referenced_in(repo, "scripts/other.sh", ".github/workflows") is False
    assert is_referenced_in(repo, "scripts/check-x.sh", ".github/workflows/ci.yml") is True
    assert is_referenced_in(repo, "scripts/check-x.sh", ".github/missing") is False
    nested = repo / ".github" / "workflows" / "sub"
    nested.mkdir()
    (nested / "deep.yml").write_text("run: scripts/deep.sh\n")
    assert is_referenced_in(repo, "scripts/deep.sh", ".github/workflows") is True


def test_cli_writes_both_lists_to_the_json_out_file(repo: Path, tmp_path_factory) -> None:
    out_dir = tmp_path_factory.mktemp("out")
    ev = out_dir / "ev.json"
    out = out_dir / "out.json"
    ev.write_text(json.dumps([
        {"layer": 0, "kind": "path_exists", "path": "docs/guide.md"},
        {"layer": 0, "kind": "path_absent", "path": "docs/guide.md"},
    ]))
    proc = subprocess.run(
        [sys.executable, "-m", "lib.evidence_check", str(repo), str(ev),
         "--json", str(out)],
        cwd=SCRIPTS_DIR, capture_output=True, text=True,
    )
    assert proc.returncode == 1
    assert "path_absent" in proc.stdout
    data = json.loads(out.read_text())
    assert [e["kind"] for e in data["evidence"]] == ["path_exists"]
    assert [e["kind"] for e in data["evidence_rejected"]] == ["path_absent"]


def test_cli_refuses_input_that_is_not_a_flat_array(repo: Path, tmp_path_factory) -> None:
    out_dir = tmp_path_factory.mktemp("out")
    ev = out_dir / "ev.json"
    ev.write_text(json.dumps({"evidence": []}))
    proc = subprocess.run(
        [sys.executable, "-m", "lib.evidence_check", str(repo), str(ev),
         "--json", str(out_dir / "out.json")],
        cwd=SCRIPTS_DIR, capture_output=True, text=True,
    )
    assert proc.returncode == 2
    assert not (out_dir / "out.json").exists()


def test_path_with_nul_is_rejected_not_raised(repo: Path) -> None:
    entries = [
        {"layer": 0, "kind": "path_exists", "path": "docs/\0guide.md"},
        {"layer": 7, "kind": "referenced_in", "needle": "x", "path": ".github\0"},
    ]
    result = check_evidence(repo, entries)
    assert result["evidence"] == []
    assert len(result["evidence_rejected"]) == 2
    assert is_referenced_in(repo, "x", ".github\0") is False


def test_reference_search_does_not_enter_git_metadata(repo: Path) -> None:
    (repo / ".git").mkdir()
    (repo / ".git" / "config").write_text("scripts/check-x.sh\n")
    assert is_referenced_in(repo, "scripts/check-x.sh", ".git") is False
    assert is_referenced_in(repo, "scripts/check-x.sh", ".git/config") is False
    for kind in ("referenced_in", "not_referenced_in"):
        result = check_evidence(
            repo, [{"layer": 7, "kind": kind, "needle": "x", "path": ".git/config"}]
        )
        assert result["evidence"] == [], kind


@pytest.mark.skipif(sys.platform == "win32" or not hasattr(os, "geteuid") or os.geteuid() == 0,
                    reason="permission bits do not restrict root or Windows")
def test_not_referenced_in_is_rejected_when_the_search_is_incomplete(repo: Path) -> None:
    hidden = repo / ".github" / "workflows" / "locked"
    hidden.mkdir()
    (hidden / "ci.yml").write_text("run: scripts/other.sh\n")
    unreadable = repo / ".github" / "workflows" / "unreadable.yml"
    unreadable.write_text("run: scripts/third.sh\n")
    hidden.chmod(0)
    unreadable.chmod(0)
    try:
        for needle in ("scripts/other.sh", "scripts/third.sh"):
            entry = {"layer": 7, "kind": "not_referenced_in", "needle": needle,
                     "path": ".github/workflows"}
            result = check_evidence(repo, [entry])
            assert result["evidence"] == [], needle
            assert "could not be searched" in result["evidence_rejected"][0]["reason"]
        # A match found elsewhere still verifies a positive claim.
        ok = {"layer": 7, "kind": "referenced_in", "needle": "scripts/check-x.sh",
              "path": ".github/workflows"}
        assert check_evidence(repo, [ok])["evidence"] == [ok]
    finally:
        hidden.chmod(0o755)
        unreadable.chmod(0o644)


def _not_referenced(needle: str, path: str = ".github/workflows") -> dict:
    return {"layer": 7, "kind": "not_referenced_in", "needle": needle, "path": path}


def test_walk_skips_symlinks_out_of_the_repo(repo: Path, tmp_path_factory) -> None:
    outside = tmp_path_factory.mktemp("outside")
    (outside / "hosts").write_text("scripts/secret.sh\n")
    (repo / ".github" / "workflows" / "link.yml").symlink_to(outside / "hosts")
    (repo / ".github" / "workflows" / "linkdir").symlink_to(outside, target_is_directory=True)
    (repo / ".github" / "workflows" / "dangling.yml").symlink_to(repo / "no-such-file")
    assert is_referenced_in(repo, "scripts/secret.sh", ".github/workflows") is False
    entry = _not_referenced("scripts/secret.sh")
    # Content outside the root is not repository content: the claim holds.
    assert check_evidence(repo, [entry])["evidence"] == [entry]


@pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="no FIFOs on this platform")
def test_fifo_under_the_path_makes_a_negative_claim_incomplete(repo: Path) -> None:
    os.mkfifo(repo / ".github" / "workflows" / "pipe")
    result = check_evidence(repo, [_not_referenced("scripts/other.sh")])
    assert result["evidence"] == []
    assert "could not be searched" in result["evidence_rejected"][0]["reason"]
    # Named directly as the path, the FIFO is incomplete too, never an empty search.
    named = check_evidence(repo, [
        _not_referenced("scripts/other.sh", ".github/workflows/pipe"),
        {"layer": 7, "kind": "referenced_in", "needle": "scripts/other.sh",
         "path": ".github/workflows/pipe"},
    ])
    assert named["evidence"] == []
    assert all("could not be searched" in e["reason"] for e in named["evidence_rejected"])
    assert is_referenced_in(repo, "scripts/other.sh", ".github/workflows/pipe") is False
    # The FIFO is never opened, and a match elsewhere still verifies.
    ok = {"layer": 7, "kind": "referenced_in", "needle": "scripts/check-x.sh",
          "path": ".github/workflows"}
    assert check_evidence(repo, [ok])["evidence"] == [ok]


def test_symlinked_file_inside_the_repo_is_searched_at_its_target(repo: Path) -> None:
    (repo / "ci-shared").mkdir()
    (repo / "ci-shared" / "deploy.yml").write_text("run: scripts/deploy.sh\n")
    (repo / ".github" / "workflows" / "shared.yml").symlink_to(
        repo / "ci-shared" / "deploy.yml")
    assert is_referenced_in(repo, "scripts/deploy.sh", ".github/workflows") is True
    result = check_evidence(repo, [_not_referenced("scripts/deploy.sh")])
    assert "needle found" in result["evidence_rejected"][0]["reason"]


def test_symlinked_directory_inside_the_repo_makes_a_negative_claim_incomplete(
    repo: Path,
) -> None:
    (repo / "ci-shared").mkdir()
    (repo / "ci-shared" / "deploy.yml").write_text("run: scripts/deploy.sh\n")
    (repo / ".github" / "workflows" / "shared").symlink_to(
        repo / "ci-shared", target_is_directory=True)
    result = check_evidence(repo, [_not_referenced("scripts/deploy.sh")])
    assert result["evidence"] == []
    assert "could not be searched" in result["evidence_rejected"][0]["reason"]
    # A link back into the directory already being searched adds nothing unread.
    (repo / ".github" / "workflows" / "shared").unlink()
    (repo / ".github" / "workflows" / "self").symlink_to(
        repo / ".github" / "workflows", target_is_directory=True)
    entry = _not_referenced("scripts/deploy.sh")
    assert check_evidence(repo, [entry])["evidence"] == [entry]


def test_walk_does_not_read_previous_assess_output(repo: Path) -> None:
    (repo / ".assess").mkdir()
    (repo / ".assess" / "assess-report.md").write_text("scripts/stale.sh is not wired\n")
    entry = _not_referenced("scripts/stale.sh", ".")
    assert check_evidence(repo, [entry])["evidence"] == [entry]
    # Naming .assess directly still searches it.
    assert is_referenced_in(repo, "scripts/stale.sh", ".assess") is True


def test_needle_spanning_a_read_chunk_boundary_is_found(repo: Path) -> None:
    from lib import evidence_check

    needle = "scripts/boundary.sh"
    pad = "x" * (evidence_check._CHUNK - 5)
    (repo / "docs" / "big.txt").write_text(pad + needle + "\n")
    assert is_referenced_in(repo, needle, "docs") is True
    assert is_referenced_in(repo, needle, "docs/big.txt") is True


def test_root_that_is_not_a_directory_verifies_nothing(tmp_path: Path) -> None:
    missing = tmp_path / "no-such-root"
    entry = {"layer": 0, "kind": "path_absent", "path": "docs/guide.md"}
    result = check_evidence(missing, [entry])
    assert result["evidence"] == []
    assert "not a directory" in result["evidence_rejected"][0]["reason"]


def test_cli_refuses_a_root_that_is_not_a_directory(tmp_path: Path) -> None:
    ev = tmp_path / "ev.json"
    ev.write_text(json.dumps([{"layer": 0, "kind": "path_absent", "path": "x"}]))
    proc = subprocess.run(
        [sys.executable, "-m", "lib.evidence_check", str(tmp_path / "nope"), str(ev),
         "--json", str(tmp_path / "out.json")],
        cwd=SCRIPTS_DIR, capture_output=True, text=True, timeout=30,
    )
    assert proc.returncode == 2
    assert not (tmp_path / "out.json").exists()


def test_cli_refuses_evidence_that_is_not_utf8(repo: Path, tmp_path_factory) -> None:
    out_dir = tmp_path_factory.mktemp("out")
    ev = out_dir / "ev.json"
    ev.write_bytes(b'[{"layer": 0, "kind": "path_exists", "path": "docs/\xff.md"}]')
    proc = subprocess.run(
        [sys.executable, "-m", "lib.evidence_check", str(repo), str(ev),
         "--json", str(out_dir / "out.json")],
        cwd=SCRIPTS_DIR, capture_output=True, text=True, timeout=30,
    )
    assert proc.returncode == 2, proc.stderr
    assert "Traceback" not in proc.stderr
    assert not (out_dir / "out.json").exists()


def test_symlinks_into_git_metadata_are_not_searched(repo: Path) -> None:
    (repo / ".git").mkdir()
    (repo / ".git" / "config").write_text("scripts/hidden.sh\n")
    (repo / "docs" / "gitlink").symlink_to(repo / ".git", target_is_directory=True)
    (repo / "config-link").symlink_to(repo / ".git" / "config")
    (repo / ".github" / "workflows" / "cfg.yml").symlink_to(repo / ".git" / "config")
    for path in ("docs/gitlink", "config-link", ".github/workflows"):
        assert is_referenced_in(repo, "scripts/hidden.sh", path) is False, path
    named = check_evidence(repo, [
        {"layer": 7, "kind": "referenced_in", "needle": "x", "path": "docs/gitlink"},
        {"layer": 7, "kind": "not_referenced_in", "needle": "x", "path": "config-link"},
    ])
    assert named["evidence"] == []
    assert all(".git/" in e["reason"] for e in named["evidence_rejected"])
    walked = _not_referenced("scripts/hidden.sh")
    assert check_evidence(repo, [walked])["evidence"] == [walked]


def test_cli_exits_2_when_the_json_output_cannot_be_written(repo: Path, tmp_path_factory) -> None:
    out_dir = tmp_path_factory.mktemp("out")
    ev = out_dir / "ev.json"
    ev.write_text(json.dumps([{"layer": 0, "kind": "path_absent", "path": "docs/guide.md"}]))
    proc = subprocess.run(
        [sys.executable, "-m", "lib.evidence_check", str(repo), str(ev),
         "--json", str(out_dir / "missing-dir" / "out.json")],
        cwd=SCRIPTS_DIR, capture_output=True, text=True, timeout=30,
    )
    assert proc.returncode == 2, proc.stderr
    assert "Traceback" not in proc.stderr

"""Unit tests for lib.gap_actions: the deterministic Top 3 gap candidates."""
from __future__ import annotations

from lib.gap_actions import REACHABILITY_FLOOR, build_gap_actions

SOFTWARE = {"available": True, "archetype": "software"}
KB = {"available": True, "archetype": "knowledge-base"}
NO_COVERAGE = {"available": False, "source": "none found"}
COVERAGE = {"available": True, "source": "lcov.info", "format": "lcov", "parsed": True}
HOTSPOTS = [{"path": p, "loc": 2, "ccn": 1.0, "commits": 12}
            for p in ("src/zeta.py", "src/mid.py", "src/a.py", "src/b.py")]


def _docs(pct: float, doc_count: int = 10, unreachable: list[str] | None = None) -> dict:
    return {"available": True, "doc_count": doc_count, "reachability_pct": pct,
            "unreachable": unreachable or []}


def test_gap_actions_floor_is_one_half() -> None:
    assert REACHABILITY_FLOOR == 0.5


def test_gap_actions_coverage_entry_names_top_hotspots() -> None:
    gaps = build_gap_actions(NO_COVERAGE, _docs(1.0), HOTSPOTS, SOFTWARE)
    assert len(gaps) == 1
    assert gaps[0]["signal"] == "coverage_report"
    assert gaps[0]["action"]
    assert gaps[0]["paths"] == ["src/zeta.py", "src/mid.py", "src/a.py"]


def test_gap_actions_empty_when_coverage_present_and_docs_reachable() -> None:
    assert build_gap_actions(COVERAGE, _docs(0.8), HOTSPOTS, SOFTWARE) == []


def test_gap_actions_reachability_entry_below_floor() -> None:
    gaps = build_gap_actions(COVERAGE, _docs(0.3, unreachable=["docs/z.md", "docs/a.md"]), HOTSPOTS, SOFTWARE)
    assert [g["signal"] for g in gaps] == ["doc_graph"]
    assert gaps[0]["paths"] == ["docs/a.md", "docs/z.md"]
    assert "30%" in gaps[0]["action"]


def test_gap_actions_reachability_at_floor_does_not_fire() -> None:
    assert build_gap_actions(COVERAGE, _docs(REACHABILITY_FLOOR), HOTSPOTS, SOFTWARE) == []


def test_gap_actions_coverage_comes_before_reachability() -> None:
    gaps = build_gap_actions(NO_COVERAGE, _docs(0.1), HOTSPOTS, SOFTWARE)
    assert [g["signal"] for g in gaps] == ["coverage_report", "doc_graph"]


def test_gap_actions_no_markdown_is_not_a_reachability_gap() -> None:
    """A repo with no docs reports reachability 0.0 with available true: nothing
    is unreachable, so no link-the-docs action fires."""
    no_docs = {"available": True, "reason": "no markdown docs found",
               "doc_count": 0, "reachability_pct": 0.0}
    assert build_gap_actions(COVERAGE, no_docs, HOTSPOTS, SOFTWARE) == []


def test_gap_actions_unavailable_doc_graph_is_not_a_gap() -> None:
    assert build_gap_actions(COVERAGE, {"available": False, "reachability_pct": 0.0}, HOTSPOTS, SOFTWARE) == []


def test_gap_actions_missing_blocks_degrade_to_empty() -> None:
    assert build_gap_actions(None, None, None, None) == []


def test_gap_actions_no_coverage_entry_on_knowledge_base() -> None:
    assert build_gap_actions(NO_COVERAGE, _docs(1.0), HOTSPOTS, KB) == []


def test_gap_actions_no_coverage_entry_without_hotspots() -> None:
    assert build_gap_actions(NO_COVERAGE, _docs(1.0), [], SOFTWARE) == []


def test_gap_actions_coverage_entry_skips_archive_hotspots() -> None:
    hot = [{"path": "archive/legacy_service.py"}, {"path": "attic/old.py"}, *HOTSPOTS]
    gaps = build_gap_actions(NO_COVERAGE, _docs(1.0), hot, SOFTWARE)
    assert gaps[0]["paths"] == ["src/zeta.py", "src/mid.py", "src/a.py"]
    only_archive = [{"path": "archive/legacy_service.py"}]
    assert build_gap_actions(NO_COVERAGE, _docs(1.0), only_archive, SOFTWARE) == []

"""Tests for lib/gate_cost.py: the CI gate's Actions cost estimate.

GitHub is faked with a `gh` shell script first on PATH (the pattern in
test_config_drift.py), so the real subprocess path through lib/gh_cli.py runs.
"""
from __future__ import annotations

import json
import os
import shutil
import stat
import subprocess
import sys
from datetime import datetime, timedelta, timezone
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))

from lib.gate_cost import MINUTES_PER_RUN, estimate_gate_cost  # noqa: E402

FAKE_GH = """#!/bin/sh
echo "$*" >> "$FAKE_GH/log"
serve() { [ -f "$FAKE_GH/$1" ] && cat "$FAKE_GH/$1" && exit 0; }
case "$1:$*" in
  auth:*) [ -f "$FAKE_GH/noauth" ] || exit 0 ;;
  repo:*) serve repo.json ;;
  pr:*) serve prs.json ;;
esac
cat "$FAKE_GH/fail" >&2
exit 1
"""

NOW = datetime(2026, 9, 19, 12, 0, tzinfo=timezone.utc)


def _git(repo: Path, *args: str) -> None:
    env = {**os.environ, "GIT_CONFIG_GLOBAL": "/dev/null"}
    subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True, env=env)


def _merged(n: int, when: datetime) -> list[dict]:
    stamp = when.strftime("%Y-%m-%dT%H:%M:%SZ")
    return [{"number": i + 1, "mergedAt": stamp, "title": f"t{i}"} for i in range(n)]


@pytest.fixture
def world(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q", "-b", "main")
    _git(repo, "remote", "add", "origin", "https://github.com/acme/widget.git")

    bindir, ghdir = tmp_path / "bin", tmp_path / "gh"
    bindir.mkdir()
    ghdir.mkdir()
    gh = bindir / "gh"
    gh.write_text(FAKE_GH)
    gh.chmod(gh.stat().st_mode | stat.S_IEXEC)
    (ghdir / "log").write_text("")
    (ghdir / "fail").write_text("gh: Not Found (HTTP 404)\n")
    (ghdir / "repo.json").write_text(json.dumps({"nameWithOwner": "acme/widget", "isPrivate": True}))
    monkeypatch.setenv("PATH", f"{bindir}{os.pathsep}{os.environ['PATH']}")
    monkeypatch.setenv("FAKE_GH", str(ghdir))

    class World:
        root = repo
        gh_dir = ghdir

        def serve(self, name: str, doc: object) -> None:
            (ghdir / name).write_text(json.dumps(doc))

        def calls(self) -> list[str]:
            return (ghdir / "log").read_text().splitlines()

    return World()


def test_gate_cost_forty_merged(world) -> None:
    world.serve("prs.json", _merged(40, NOW - timedelta(days=1)))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["available"] is True
    assert block["runs_per_month"] == 40
    assert block["minutes_per_run"] == MINUTES_PER_RUN == 5
    assert block["minutes_per_month"] == 200
    assert block["private"] is True
    assert "assum" in block["assumption"].lower() and "5 minutes" in block["assumption"]
    pr_call = next(c for c in world.calls() if c.startswith("pr list"))
    assert "--state merged" in pr_call and "--limit" in pr_call
    assert "--jq" not in pr_call and "--template" not in pr_call


def test_gate_cost_counts_only_the_last_thirty_days(world) -> None:
    world.serve("prs.json", _merged(3, NOW - timedelta(days=2)) + _merged(5, NOW - timedelta(days=45)))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["runs_per_month"] == 3
    assert block["minutes_per_month"] == 15


def test_gate_cost_no_merge_history(world) -> None:
    world.serve("prs.json", [])
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["available"] is False
    assert block["reason"].startswith("no_merge_history")


def test_gate_cost_no_gh(world, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    # PATH holds git and nothing else: the remote resolves, gh is missing.
    only_git = tmp_path / "only-git"
    only_git.mkdir()
    git = shutil.which("git")
    assert git is not None
    (only_git / "git").symlink_to(git)
    monkeypatch.setenv("PATH", str(only_git))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block == {"available": False, "reason": block["reason"]}
    assert block["reason"].startswith("gh_not_installed")


def test_gate_cost_unauthenticated(world) -> None:
    (world.gh_dir / "noauth").write_text("")
    world.serve("prs.json", _merged(40, NOW))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["available"] is False
    assert block["reason"].startswith("not_authenticated")
    assert not any(c.startswith("pr ") for c in world.calls())


def test_gate_cost_no_remote_never_calls_gh(world) -> None:
    _git(world.root, "remote", "remove", "origin")
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["available"] is False
    assert block["reason"].startswith("no_remote")
    assert world.calls() == []


def test_gate_cost_private_unknown_when_repo_view_fails(world) -> None:
    (world.gh_dir / "repo.json").unlink()
    world.serve("prs.json", _merged(2, NOW))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["available"] is True
    assert block["private"] is None


def test_gate_cost_capped_at_listing_limit(world, monkeypatch: pytest.MonkeyPatch) -> None:
    import lib.gate_cost as gate_cost

    monkeypatch.setattr(gate_cost, "PR_LIMIT", 3)
    world.serve("prs.json", _merged(3, NOW))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["capped"] is True
    assert "at least 3 merged" in block["assumption"]
    pr_call = next(c for c in world.calls() if c.startswith("pr list"))
    assert "--limit 3" in pr_call


def test_gate_cost_not_capped_below_limit(world) -> None:
    world.serve("prs.json", _merged(2, NOW))
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["capped"] is False
    assert "at least" not in block["assumption"]


def test_gate_cost_non_list_answer_degrades(world) -> None:
    world.serve("prs.json", {"message": "unexpected"})
    block = estimate_gate_cost(world.root, now=NOW)
    assert block["available"] is False
    assert block["reason"].startswith("gh_bad_json")

"""Tests for lib/generated_files.py: the header sniff and long-line detector."""
from __future__ import annotations

import sys
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))

from lib.generated_files import (  # noqa: E402
    LONG_LINE_THRESHOLD,
    matches_generated_name,
    average_line_length,
    generated_reason,
    has_generated_header,
    is_long_line_artifact,
)


@pytest.mark.parametrize("marker", [
    "-- GENERATED FILE - DO NOT EDIT",
    "// Code generated by protoc-gen-go. DO NOT EDIT.",
    "# @generated by buck",
    "/* This file is auto-generated */",
    "// AUTOGENERATED - regenerate with make",
    "// AUTO-GENERATED by tool",
    "# auto generated from schema.yaml",
    "// do not edit: owned by the schema tool",
])
def test_generated_header_markers_match_case_insensitively(tmp_path, marker):
    f = tmp_path / "x.sql"
    f.write_text(f"{marker}\nSELECT 1;\n")
    assert has_generated_header(f) is True
    assert generated_reason(f) == "generated-header"


@pytest.mark.parametrize("line", [
    "generated file whose name looks ordinary, such as a schema dump",
    "Writes the generated file; do not edit it by hand, rerun make.",
    "    return render(autogenerated=True)",
])
def test_generated_header_prose_without_comment_leader_is_ignored(tmp_path, line):
    f = tmp_path / "codegen.py"
    q = '"' * 3
    f.write_text(q + "Codegen driver.\n\n" + line + "\n" + q + "\n")
    assert has_generated_header(f) is False


@pytest.mark.parametrize("first_line,expected", [
    ('"""Writes the generated file for the API client."""', False),
    ("# Loads the generated file and patches it", False),
    ("-- GENERATED FILE - regenerate with make schema", True),
    ("/* Generated file */", True),
    ("# === GENERATED FILE ===", True),
])
def test_generated_header_generated_file_only_as_banner(tmp_path, first_line, expected):
    f = tmp_path / "x.py"
    f.write_text(first_line + "\nA = 1\n")
    assert has_generated_header(f) is expected


def test_long_line_small_file_skips_read(tmp_path, monkeypatch):
    f = tmp_path / "small.py"
    f.write_text("x = 1\n")
    import lib.generated_files as mod
    monkeypatch.setattr(mod, "average_line_length",
                        lambda p: (_ for _ in ()).throw(AssertionError("read")))
    assert mod.is_long_line_artifact(f) is False


def test_generated_header_markdown_bullet_is_not_a_comment(tmp_path):
    f = tmp_path / "CHANGELOG.md"
    f.write_text("Release notes\n\n* Auto-generated release notes now include PRs\n"
                 "* Do not edit this table by hand\n")
    assert has_generated_header(f) is False


def test_generated_header_markdown_heading_is_not_a_comment(tmp_path):
    md = tmp_path / "guide.md"
    md.write_text("# Do not edit these by hand\n\n## Auto-generated sections\n")
    assert has_generated_header(md) is False
    marked = tmp_path / "api.md"
    marked.write_text("<!-- DO NOT EDIT: generated by docgen -->\n# API\n")
    assert has_generated_header(marked) is True


def test_generated_header_after_utf8_bom_matches(tmp_path):
    f = tmp_path / "Client.cs"
    f.write_bytes("\ufeff// <auto-generated/>\nclass C {}\n".encode("utf-8"))
    assert has_generated_header(f) is True


def test_generated_header_jsdoc_and_docstring_leaders_match(tmp_path):
    js = tmp_path / "a.js"
    js.write_text("/**\n * @generated\n */\nexport const a = 1;\n")
    py = tmp_path / "b.py"
    q = '"' * 3
    py.write_text(q + "Autogenerated by schema2py." + q + "\nA = 1\n")
    assert has_generated_header(js) is True
    assert has_generated_header(py) is True


def test_generated_header_on_line_five_matches(tmp_path):
    f = tmp_path / "x.py"
    f.write_text("a = 1\nb = 2\nc = 3\nd = 4\n# DO NOT EDIT\ne = 5\n")
    assert has_generated_header(f) is True


def test_generated_header_after_a_long_first_line_matches(tmp_path):
    f = tmp_path / "bundle.js"
    f.write_text("var a = '" + "x" * 100_000 + "';\n// @generated by bundler\nvar b = 1;\n")
    assert has_generated_header(f) is True


def test_generated_header_after_line_five_is_ignored(tmp_path):
    f = tmp_path / "hand.py"
    body = ["def route(x):"] + [f"# note {i}" for i in range(198)]
    body.append("# do not edit the routing table above without updating the docs")
    f.write_text("\n".join(body) + "\n")
    assert has_generated_header(f) is False
    assert generated_reason(f) is None


def test_generated_header_unreadable_file_is_not_excluded(tmp_path):
    assert has_generated_header(tmp_path / "missing.sql") is False
    assert generated_reason(tmp_path / "missing.sql") is None


def test_long_line_payload_is_excluded(tmp_path):
    f = tmp_path / "font.ts"
    f.write_text('export const FONT = "' + "A" * 40000 + '";\nexport default FONT;\n')
    assert average_line_length(f) > 20000
    assert is_long_line_artifact(f) is True
    assert generated_reason(f) == "long-lines"


def test_long_line_threshold_keeps_wide_hand_written_code(tmp_path):
    f = tmp_path / "wide.py"
    f.write_text("\n".join(["    x = x + 1  # " + "p" * 85] * 20) + "\n")
    assert 90 < average_line_length(f) < 110
    assert is_long_line_artifact(f) is False


def test_long_line_threshold_calibration_band():
    # Above a JSONL fixture (296 chars/line, kept), below a hand-built
    # HTML explainer page with inline data (3,817 chars/line, excluded).
    assert 296 < LONG_LINE_THRESHOLD < 3817  # strict: is_long_line_artifact uses >


def test_long_line_measures_characters_not_bytes(tmp_path):
    f = tmp_path / "cjk.py"
    f.write_text("\n".join(["# " + "\u6f22" * 600] * 3) + "\n", encoding="utf-8")
    assert average_line_length(f) < LONG_LINE_THRESHOLD
    assert is_long_line_artifact(f) is False


def test_long_line_counts_unterminated_last_line(tmp_path):
    f = tmp_path / "one.txt"
    f.write_bytes(b"abcd")
    assert average_line_length(f) == 4.0
    assert average_line_length(tmp_path / "gone.txt") == 0.0


def test_generated_header_sniff_spares_its_own_module():
    """The module documents the markers; they must stay out of its first lines."""
    import lib.generated_files as mod
    assert has_generated_header(Path(mod.__file__)) is False
    assert generated_reason(Path(mod.__file__)) is None


def test_long_line_average_uses_capped_head(tmp_path):
    f = tmp_path / "big.txt"
    # ~1.6 MB: a short-line first 1 MB followed by one enormous final line.
    f.write_text(("y" * 99 + "\n") * 10500 + "z" * 600000)
    assert average_line_length(f) < LONG_LINE_THRESHOLD



@pytest.mark.parametrize("path,expected", [
    ("web/src/database.types.ts", True),
    ("api.generated.ts", True),
    ("schema.generated.sql", True),
    ("client.gen.ts", True),
    ("src/types.ts", False),
    ("generated/readme.md", False),
])
def test_generated_header_free_name_patterns(path, expected):
    assert matches_generated_name(path) is expected

"""Contract tests for the churn-degeneracy detector (issue #172).

`churn_is_degenerate` is the single source of truth that lets every downstream
consumer (doc->complexity join, keyhole summary, treemap) tell a meaningless
churn signal from a real one. A degenerate window - every file ~1 commit, the
fingerprint of a shallow clone / fresh import / squashed or extracted history -
must be flagged so a precise doc->code association can no longer stamp a
high-confidence finding onto pure extraction artifact.
"""
from __future__ import annotations

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))

from lib.git_churn import churn_is_degenerate  # noqa: E402


def test_all_ones_is_degenerate() -> None:
    """The canonical artifact: every file shows exactly one commit."""
    assert churn_is_degenerate([1] * 1979) is True


def test_single_outlier_among_ones_still_degenerate() -> None:
    """One genuinely-churned file among thousands of single-commit files does
    not rescue the signal - p95 (not max) reports on the flat bulk."""
    counts = [1] * 1978 + [50]
    assert churn_is_degenerate(counts) is True


def test_zero_commit_files_are_ignored() -> None:
    """Idle files (0 commits in the window) don't count toward the distribution:
    degeneracy is the shape of the activity among files that actually moved."""
    counts = [0] * 500 + [1] * 10
    assert churn_is_degenerate(counts) is True


def test_genuine_variance_is_not_degenerate() -> None:
    """A real history with a spread of commits-per-file carries signal."""
    counts = list(range(1, 60))  # 1..59, p95 well above 1
    assert churn_is_degenerate(counts) is False


def test_uniform_high_count_is_not_degenerate() -> None:
    """Flat-but-active (every file committed several times) still has p95 > 1, so
    it is not the single-commit artifact this guards against."""
    assert churn_is_degenerate([5] * 100) is False


def test_too_few_active_files_is_not_called() -> None:
    """Below the minimum active-file count the distribution is too small to judge
    - a tiny utility repo where each file shows one commit is not the
    shallow-clone artifact, so we don't flatten its churn signal."""
    assert churn_is_degenerate([1, 1, 1]) is False
    assert churn_is_degenerate([]) is False


def test_at_minimum_active_files_all_ones_is_degenerate() -> None:
    """Exactly at the threshold, an all-ones distribution is degenerate."""
    assert churn_is_degenerate([1, 1, 1, 1, 1]) is True


def test_accepts_any_iterable() -> None:
    """Consumers pass a generator of churn-map values; the detector consumes it
    once without requiring a materialised list."""
    assert churn_is_degenerate(c for c in [1, 1, 1, 1, 1, 1]) is True

"""Tests for git_churn.git_commit_info - the measured-commit snapshot that lets
the /assess report pin its absolute LOC/CCN figures to a SHA and warn when the
snapshot is stale (issue #59)."""
from __future__ import annotations

import importlib.util
from pathlib import Path

_LIB = Path(__file__).resolve().parents[1] / "scripts" / "lib" / "git_churn.py"
_spec = importlib.util.spec_from_file_location("git_churn", _LIB)
git_churn = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(git_churn)


def test_returns_unavailable_outside_git_repo(tmp_path):
    """A plain directory (no .git) degrades to available:False with a reason,
    so the report omits the snapshot line rather than inventing a SHA."""
    info = git_churn.git_commit_info(tmp_path)
    assert info["available"] is False
    assert "reason" in info


def test_pins_head_sha_and_clean_tree(git_repo):
    repo, commit = git_repo
    (repo / "a.py").write_text("x = 1\n", encoding="utf-8")
    commit("initial commit")

    info = git_churn.git_commit_info(repo)
    assert info["available"] is True
    assert len(info["head_sha"]) == 40
    assert info["head_short"] == info["head_sha"][:12]
    assert info["subject"] == "initial commit"
    assert info["committed_date"]  # ISO short date, non-empty
    # Clean working tree, and a fresh repo has no upstream configured.
    assert info["dirty"] is False
    assert info["upstream"] is None
    assert info["behind"] is None


def test_flags_dirty_working_tree(git_repo):
    """Uncommitted edits to a tracked file mean the measured numbers reflect
    the working tree, not HEAD - the report must warn on this."""
    repo, commit = git_repo
    (repo / "a.py").write_text("x = 1\n", encoding="utf-8")
    commit("initial commit")
    # Modify the tracked file without committing.
    (repo / "a.py").write_text("x = 2\nprint(x)\n", encoding="utf-8")

    info = git_churn.git_commit_info(repo)
    assert info["dirty"] is True


def test_untracked_file_does_not_mark_dirty(git_repo):
    """Only tracked-file changes count as dirty - a stray untracked file (e.g.
    a contributor's scratch note) must not flip the snapshot warning."""
    repo, commit = git_repo
    (repo / "a.py").write_text("x = 1\n", encoding="utf-8")
    commit("initial commit")
    (repo / "scratch.txt").write_text("notes\n", encoding="utf-8")

    info = git_churn.git_commit_info(repo)
    assert info["dirty"] is False


def test_reports_behind_count_vs_upstream(git_repo, tmp_path):
    """When HEAD trails its upstream, `behind` is the commit gap - that is the
    staleness signal that explains absolute figures drifting low (#59)."""
    import subprocess

    repo, commit = git_repo
    (repo / "a.py").write_text("v = 1\n", encoding="utf-8")
    commit("c1")
    (repo / "a.py").write_text("v = 2\n", encoding="utf-8")
    commit("c2")

    # Stand up a local "remote" two commits ahead, then point the branch's
    # upstream at it while leaving HEAD one commit back.
    def _g(*args, cwd=repo):
        subprocess.run(["git", "-C", str(cwd), *args],
                       check=True, capture_output=True, text=True)

    remote = tmp_path / "remote.git"
    _g("clone", "--bare", str(repo), str(remote), cwd=tmp_path)
    branch = subprocess.run(
        ["git", "-C", str(repo), "rev-parse", "--abbrev-ref", "HEAD"],
        check=True, capture_output=True, text=True).stdout.strip()
    _g("remote", "add", "origin", str(remote))
    _g("fetch", "-q", "origin")
    _g("branch", f"--set-upstream-to=origin/{branch}", branch)

    # Advance the remote by one commit so HEAD is exactly 1 behind.
    (repo / "a.py").write_text("v = 3\n", encoding="utf-8")
    commit("c3")
    _g("push", "-q", "origin", branch)
    _g("reset", "-q", "--hard", "HEAD~1")  # move HEAD back behind upstream

    info = git_churn.git_commit_info(repo)
    assert info["upstream"] == f"origin/{branch}"
    assert info["behind"] == 1

"""Tests for the /assess dogfood golden baseline (Phase 0 of assess-dogfooded).

These guard the captured regression baseline itself: that the golden fixtures
are complete (every block the report's prose depends on is present), that the
normalization is idempotent and actually masks the volatile fields, and that the
loaders work. Part 3's decomposition parity test reuses `golden.normalize_*` and
`golden.load_*` from here - so a break in this scaffolding surfaces before the
decomposition work depends on it.
"""
from __future__ import annotations

import golden
from lib import keyhole_signals as ks

# Blocks the report's prose sections read from run-context.json. The test
# strategy for task 1 names these explicitly: a golden missing any of them would
# let a decomposed pipeline silently drop a section and still "pass" parity.
EXPECTED_BLOCKS = (
    "derived_findings",
    "attention",
    "behaviour",
    "documentation",
    "understanding",
    "runtime",
    "structure",
    "test_focus",
    "coverage_report",
)


def test_golden_run_context_has_all_expected_blocks() -> None:
    ctx = golden.load_golden_run_context()
    for block in EXPECTED_BLOCKS:
        assert block in ctx, f"golden run-context missing {block!r}"


def test_golden_run_context_volatile_fields_are_normalized() -> None:
    ctx = golden.load_golden_run_context()
    assert ctx["plugin_version"] == golden.SENTINEL
    assert ctx["prior_plugin_version"] == golden.SENTINEL
    assert ctx["run_date"] == golden.SENTINEL
    mc = ctx["measured_commit"]
    assert mc["head_sha"] == golden.SENTINEL
    assert mc["committed_date"] == golden.SENTINEL
    # Structural fields survive normalization.
    assert mc["available"] is True


def test_golden_run_context_keeps_derived_findings_shape() -> None:
    """All eight keyhole findings present in fixed order - the contract the
    report's findings section and Part 1's deterministic surfacing rely on. The
    E1/E2 trust-axis findings (untrusted_hotspot, self_referential_tests) join
    the original six between unexplained_complexity and orphaned_understanding."""
    ctx = golden.load_golden_run_context()
    names = [f["name"] for f in ctx["derived_findings"]]
    assert names == [
        "hidden_coupling",
        "lying_map",
        "unexplained_complexity",
        "untrusted_hotspot",
        "self_referential_tests",
        "orphaned_understanding",
        "candidate_dead_weight",
        "refactor_boundary",
    ]


def test_golden_run_context_has_deterministic_keyhole_products() -> None:
    """Part 1 adds three deterministic report-skeleton products to the bus: the
    pre-rendered findings markdown, the keyhole readiness summary (reported
    alongside the 0-8 score), and the mandatory attention-derived Top-3
    actions."""
    ctx = golden.load_golden_run_context()
    assert ctx["findings_markdown"].startswith(
        "## Cross-Layer Findings (Keyhole Readiness)"
    )
    assert set(ctx["keyhole_summary"]) == {
        "concerns", "safe_zones", "total_concerns", "summary_text"
    }
    assert isinstance(ctx["prescribed_actions"], list)


def test_normalize_run_context_is_idempotent() -> None:
    ctx = golden.load_golden_run_context()
    assert golden.normalize_run_context(ctx) == ctx


def test_normalize_run_context_does_not_mutate_input() -> None:
    ctx = {"plugin_version": "9.9.9", "measured_commit": {"head_sha": "abc", "available": True}}
    snapshot = {"plugin_version": "9.9.9", "measured_commit": {"head_sha": "abc", "available": True}}
    golden.normalize_run_context(ctx)
    assert ctx == snapshot


def test_golden_report_has_normalized_provenance() -> None:
    report = golden.load_golden_report()
    assert f"_Generated {golden.SENTINEL}._" in report
    assert f"- **Measured at commit:** {golden.SENTINEL}" in report
    # The report still carries its substantive sections (the scorecard table
    # now lives inside the 📊 fold rather than under a bare ## AI Readiness).
    assert "## Top 3 Actions" in report
    assert "Full scorecard" in report
    assert "| Layer | What it asks |" in report


def test_normalize_report_is_idempotent() -> None:
    report = golden.load_golden_report()
    assert golden.normalize_report(report) == report


def test_report_has_single_cross_layer_findings_heading() -> None:
    """The 'Cross-Layer Findings (Keyhole Readiness)' heading appears exactly
    once: `findings_markdown` owns it, and the report writer places framing
    prose directly under it instead of adding a duplicate framing heading
    (issue #164)."""
    report = golden.load_golden_report()
    assert report.count("Cross-Layer Findings (Keyhole Readiness)") == 1


def test_load_bearing_surface_is_outside_folds() -> None:
    """The two-audience report keeps a short, picture-led human surface while
    keeping every verbose section present in the raw markdown inside collapsed
    <details> folds (an agent reading the file still sees all of it).

    A section-ablation A/B established the split: the score headline and the
    Top 3 Actions are load-bearing (folding the Top 3 made a fresh agent act on
    the wrong item), so they must stay on the visible surface; the verbose
    scorecard / findings / framing are foldable. This guard fails loudly if that
    split ever regresses in either direction.
    """
    report = golden.load_golden_report()
    surface, sep, folded = report.partition("<details>")
    assert sep, "report must contain at least one <details> fold"

    # Load-bearing: must be on the default-visible surface, never folded.
    assert "## Top 3 Actions" in surface
    assert "Score: 6.0 / 8" in surface
    # The two SVG snapshots carry the human value up top.
    assert surface.count("![") >= 2

    # Foldable verbose detail must live inside a fold, never on the surface.
    for marker in (
        "| Layer | What it asks |",          # the 9-layer scorecard table
        "## Cross-Layer Findings",            # the keyhole findings block
        "How to read this report",            # the framing/method preamble
    ):
        assert marker not in surface, f"{marker!r} leaked onto the visible surface"
        assert marker in folded, f"{marker!r} missing from the folded detail"


def test_opening_summary_is_bespoke_not_boilerplate() -> None:
    """The first thing a human reads (the line under the score headline) must be
    a bespoke, strength-led summary of *this* run - not the old fixed caveat that
    printed identically under every score. The non-verdict reassurance still
    lives in the 'How to read' fold; it must not lead the report.
    """
    report = golden.load_golden_report()
    surface, _, folded = report.partition("<details>")
    boilerplate = "This is an improvement roadmap, not a verdict"
    assert boilerplate not in surface, (
        "the fixed 'not a verdict' caveat must not lead the report - the opening "
        "is a bespoke, strength-led summary"
    )
    assert boilerplate in folded, "the non-verdict framing should remain in the 'How to read' fold"


def test_not_a_verdict_frame_adjacent_to_score() -> None:
    """A short 'not a verdict' frame sits on the score line above the fold, so a
    reader never mistakes the LLM score for a pass/fail gate (task 20). The full
    'improvement roadmap, not a verdict' framing still lives in the 'How to read'
    fold - guarded by test_opening_summary_is_bespoke_not_boilerplate - so this
    short frame must use different wording and must not reintroduce the boiler-
    plate onto the surface.
    """
    report = golden.load_golden_report()
    surface, sep, _ = report.partition("<details>")
    assert sep
    score_line = next(
        line for line in surface.splitlines() if line.startswith("**Score:")
    )
    assert "not a verdict" in score_line
    # The compact frame is not the folded boilerplate sentence.
    assert "This is an improvement roadmap, not a verdict" not in score_line


def test_agents_start_here_pointer_above_the_fold() -> None:
    """The deterministic 'agents start here -> .assess/actions.json' pointer sits
    above the first fold and names the durable machine-readable Top-3 contract
    (actions.json schema v2, task 16), so an executing agent - even a smaller
    model - picks up the prioritized work without parsing the report prose."""
    report = golden.load_golden_report()
    surface, sep, _ = report.partition("<details>")
    assert sep
    assert "Agents start here" in surface
    assert "`.assess/actions.json`" in surface
    # It points at the Top 3 and therefore precedes the Top 3 Actions table.
    assert surface.index("Agents start here") < surface.index("## Top 3 Actions")


def test_mutation_caveat_present_when_mutation_not_run() -> None:
    """The golden is a mutation-not-run snapshot, so the deterministic
    MUTATION_CAVEAT line appears above the fold: Layer 6 (Coverage) is capped at
    Partial and truth-pressure is unproven (task 8 data). It renders only when
    mutation did not run - keyed on mutation_not_run_cap.applies / mutation_run.
    """
    report = golden.load_golden_report()
    surface, sep, _ = report.partition("<details>")
    assert sep
    assert (
        "Mutation testing was not run. Layer 6 (Coverage) is capped at Partial "
        "and truth-pressure remains unproven." in surface
    )


def test_golden_has_structure_drift_block_with_both_tiers() -> None:
    """The captured baseline carries the structure_drift block (Tier 0 + Tier 1).

    This repo declares an ownership map (the lib README seam doc + the README
    cross-links), so Tier 0 is available; the static import graph exists, so
    Tier 1 is available too. The block's shape is pinned here so a future
    pipeline change that drops or reshapes it fails loudly.
    """
    ctx = golden.load_golden_run_context()
    assert "structure_drift" in ctx, "golden run-context missing structure_drift"
    sd = ctx["structure_drift"]

    t0 = sd["tier_0"]
    assert t0["available"] is True
    assert isinstance(t0["empty_ownership_patterns"], list)
    assert isinstance(t0["total_patterns"], int)
    assert isinstance(t0["matched_patterns"], int)
    # Every empty-pattern row has the documented {pattern, declared_in, owners}.
    for row in t0["empty_ownership_patterns"]:
        assert set(row) == {"pattern", "declared_in", "owners"}

    t1 = sd["tier_1"]
    assert t1["available"] is True
    for key in (
        "human_grouped_static_splits",
        "human_split_static_fuses",
        "human_grouped_never_cochange",
        "human_split_but_cochange",
        "human_static_agree",
        "human_cochange_agree",
    ):
        assert isinstance(t1[f"{key}_count"], int)
    assert t1["seam_allowlist_applied"] is True
    assert isinstance(t1["allowlist_pairs_count"], int)


def test_golden_structure_drift_tier1_has_no_false_positive_seam() -> None:
    """After the seam allowlist this repo surfaces no hidden-coupling seam.

    The documented seams (lib<->tests, build<->skills) are absorbed by the
    allowlist, and the version hot-file's repo-wide couplings don't recur as a
    directory pair - so the drift-derived hidden_coupling contribution is empty.
    The captured derived hidden_coupling finding therefore carries only the
    pre-existing containment-derived directories, never a drift false positive.
    """
    ctx = golden.load_golden_run_context()
    hc = next(f for f in ctx["derived_findings"] if f["name"] == "hidden_coupling")
    # The version-hot-file directory must never appear as a hidden-coupling seam.
    assert ".claude-plugin" not in hc["paths"]


def test_golden_run_context_has_test_focus_and_coverage_shape() -> None:
    """The focus-funnel blocks the report's 'Where to focus testing' table reads:
    a ranked `test_focus` list and the `coverage_report` provenance. Pinned here
    so a pipeline change that drops or reshapes either fails loudly."""
    ctx = golden.load_golden_run_context()

    tf = ctx["test_focus"]
    assert tf["available"] is True
    assert isinstance(tf["coverage_present"], bool)
    assert tf["total_focus_targets"] == len(tf["entries"])
    assert tf["entries"], "golden test_focus must carry entries to exercise the table"
    for entry in tf["entries"]:
        assert set(entry) == {
            "path", "risk_band", "test_signal",
            "hollow_heuristic_kinds", "suggested_action",
        }
        assert entry["risk_band"] in {"high", "medium", "low"}
        assert entry["test_signal"] in {
            "no_covering_test", "covered_but_hollow",
            "unknown_no_coverage", "covered_clean", "unsupported",
            "sibling_test_only",
        }
        # The orchestrator always passes repo_root, so the no-repo_root degrade
        # can no longer reach the golden.
        assert entry["test_signal"] != "unknown_no_coverage"
        assert entry["suggested_action"] in {
            "add_tests", "strengthen_assertions", "measure_coverage", "none",
        }

    cov = ctx["coverage_report"]
    assert isinstance(cov["available"], bool)
    assert "source" in cov


def test_report_renders_where_to_focus_testing_table() -> None:
    """The report renders the focus read inside a fold: the section heading, the
    File|Risk|Test Signal|Suggested Action columns, and at least one mapped row.
    The raw `test_focus` signal values must NOT leak - they are mapped to the
    human-readable labels."""
    report = golden.load_golden_report()
    surface, sep, folded = report.partition("<details>")
    assert sep

    assert "#### Where to focus testing" in folded
    assert "| File | Risk | Test Signal | Suggested Action |" in folded
    # The golden is a no-coverage run with repo_root passed (the orchestrator
    # always passes it), so no row can carry the Unknown label; every hot file in
    # this repo has a conventionally named test file.
    assert "Test file present, coverage unmeasured" in folded
    assert "Measure coverage" in folded
    assert "Unknown (no coverage)" not in report
    # Raw schema values must be mapped, never rendered verbatim into the table.
    assert "sibling_test_only" not in report
    assert "measure_coverage" not in report
    assert "unknown_no_coverage" not in report
    assert "add_tests" not in report
    # The verbose section lives in a fold, never on the human surface.
    assert "Where to focus testing" not in surface


def test_report_always_explains_hatching() -> None:
    """The always-present hatching explainer kills the silent-absence problem:
    this golden is a mutation-not-run snapshot, so the report states the hatching
    is absent and why, rather than leaving a green-but-unverified treemap to read
    as safe."""
    report = golden.load_golden_report()
    assert "No hatching visible - mutation analysis was not run." in report
    assert "accept the mutation offer to enable it." in report


def test_report_has_coverage_provenance_line() -> None:
    """The coverage provenance line states whether the test signals rest on a
    real coverage report or on heuristics alone. The golden has no report, so it
    must read 'none found'."""
    report = golden.load_golden_report()
    assert "Coverage data: none found - test signals are heuristic-only." in report


def test_agent_assess_block_is_not_duplicated() -> None:
    """The 'read the .assess/ directory' block is for agents and belongs only in
    the Machine-readable fold - it used to also appear in the Strengths fold.
    """
    report = golden.load_golden_report()
    assert report.count("the `.assess/` directory is actionable feedback written for you") == 1


def test_golden_attention_tie_break_order() -> None:
    """The stored attention rows agree with the tie-break key, and no
    non-hotspot row sits directly above a hotspot row of equal score. The
    golden's rows are five score-1 hidden_coupling directories (none a hotspot),
    so this pins the coupling arm only: skills/assess/tests (containment 0.0357)
    stays last and the stored order did not move. The marker arm is covered by
    the unit tests; run-context carries no marker scan to feed it here."""
    ctx = golden.load_golden_run_context()
    rows = ctx["attention"]
    assert rows
    tie_break = ks.attention_tie_break(ctx["stats_summary"], None, ctx["behaviour"])
    assert rows == sorted(rows, key=tie_break.key)
    hot = {h["path"] for h in ctx["stats_summary"]["top_hotspots"]}
    for above, below in zip(rows, rows[1:]):
        if above["score"] == below["score"]:
            assert above["path"] in hot or below["path"] not in hot

"""Golden-SVG tests: run the REAL renderers and lock their colour encoding.

Unlike ``test_complexity_treemap.py`` / ``test_doc_graph_svg.py`` (which stub
matplotlib to exercise pure logic), these tests drive the *actual* render path:
they synthesize a git history over a tiny fixture repo, invoke the shipped
script via ``uv run --script`` (matplotlib/lizard/squarify resolved from the
script's PEP-723 inline metadata - no stubbing, no mocking), and parse the SVG
the renderer produces on disk. That is the only way to prove the whole pipeline
- lizard -> cap/blend maths -> OrRd colormap -> SVG - actually encodes
``ccn -> hue`` and ``churn -> saturation`` the way the report claims.

The fixtures and their expected values are documented in
``tests/fixtures/golden-svg-repo/README.md`` and
``tests/fixtures/golden-doc-repo/FIXTURE.md``. If the colour maths changes these
assertions fail - that is the point: update the fixture tables and these tests
together, deliberately.

``uv`` drives the isolated script env, so the tests skip when it is absent
(never true in CI, which installs uv). Renders are cached by uv after the first
resolve; the fixtures are deliberately tiny to keep CI runtime low.
"""
from __future__ import annotations

import os
import re
import shutil
import subprocess
from pathlib import Path

import pytest

_SCRIPTS = Path(__file__).resolve().parents[1] / "scripts"
_FIXTURES = Path(__file__).resolve().parent / "fixtures"

# uv runs the script in an isolated env from its inline metadata. Skip only when
# uv is missing (a machine that can't run the scripts at all); CI always has it.
_UV = shutil.which("uv")
pytestmark = pytest.mark.skipif(_UV is None, reason="uv not on PATH")


def _hex_to_rgb(h: str) -> tuple[int, int, int]:
    h = h.lstrip("#")
    return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)


def _chroma(rgb: tuple[int, int, int]) -> int:
    """Saturation proxy: distance between the max and min RGB channel. A vivid
    (saturated) colour has a large spread; a colour blended toward neutral grey
    collapses toward zero chroma."""
    return max(rgb) - min(rgb)


def _git(repo: Path, *args: str, env: dict) -> None:
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True, env=env)


def _git_env() -> dict:
    """Ambient-config-free git env, matching conftest's hermetic-git policy, so a
    signing-enabled global config can't break commits in the disposable repo."""
    env = {**os.environ}
    env["GIT_CONFIG_GLOBAL"] = os.devnull
    env["GIT_CONFIG_SYSTEM"] = os.devnull
    env["GIT_CONFIG_NOSYSTEM"] = "1"
    # uv must resolve the script's OWN isolated env from inline metadata, not
    # reuse the pytest runner's active venv.
    env.pop("VIRTUAL_ENV", None)
    return env


def _init_repo(repo: Path, env: dict) -> None:
    _git(repo, "init", "-q", env=env)
    _git(repo, "config", "user.email", "test@example.com", env=env)
    _git(repo, "config", "user.name", "Test", env=env)


def _run_script(script: str, repo: Path, out: Path, env: dict,
                *extra: str) -> str:
    """Run a shipped renderer via ``uv run --script`` and return the SVG text."""
    result = subprocess.run(
        ["uv", "run", "--script", str(_SCRIPTS / script),
         str(repo), "-o", str(out), *extra],
        capture_output=True, text=True, env=env,
    )
    assert result.returncode == 0, (
        f"{script} failed (rc={result.returncode})\nstderr:\n{result.stderr}"
    )
    assert out.exists(), f"{script} did not write {out}\nstderr:\n{result.stderr}"
    return out.read_text(encoding="utf-8")


# ── complexity-treemap.py (code heatmap) ──────────────────────────────────────

_RECT_RE = re.compile(
    r'<rect\b[^>]*\bfill="(#[0-9a-f]{6})"[^>]*>\s*<title>(.*?)</title>',
    re.DOTALL,
)


def _parse_rects(svg: str) -> dict[str, tuple[str, str]]:
    """Map ``basename -> (fill_hex, full_title)`` for every leaf rect. The
    tooltip's first line is the file's relative path."""
    out: dict[str, tuple[str, str]] = {}
    for fill, title in _RECT_RE.findall(svg):
        rel = title.splitlines()[0].strip()
        out[Path(rel).name] = (fill, title)
    return out


@pytest.fixture(scope="module")
def treemap_svg(tmp_path_factory) -> str:
    """Render golden-svg-repo through the real complexity-treemap pipeline.

    hot.py + simple_active.py are committed several extra times to create a
    churn gradient; complex_stable.py + simple_stable.py stay at one commit.
    """
    env = _git_env()
    repo = tmp_path_factory.mktemp("golden_svg_repo")
    src = _FIXTURES / "golden-svg-repo"
    # Copy only the scored source; README.md is fixture documentation, not input.
    for name in ("hot.py", "complex_stable.py",
                 "simple_active.py", "simple_stable.py"):
        shutil.copy(src / name, repo / name)

    _init_repo(repo, env)
    _git(repo, "add", "-A", env=env)
    _git(repo, "commit", "-q", "-m", "init", env=env)
    # Churn the two "active" files so churn (saturation) is a live gradient.
    for i in range(4):
        for name in ("hot.py", "simple_active.py"):
            with (repo / name).open("a", encoding="utf-8") as fh:
                fh.write(f"\n# churn {i}\n")
        _git(repo, "add", "-A", env=env)
        _git(repo, "commit", "-q", "-m", f"churn {i}", env=env)

    out = repo / "out.svg"
    return _run_script("complexity-treemap.py", repo, out, env)


def test_treemap_a11y_metadata(treemap_svg):
    """Task 17: the root <svg> is role="img" with a <title>/<desc> pair as its
    first children (the accessible name + description)."""
    assert 'role="img"' in treemap_svg
    assert "<title>Complexity Hotspot Heatmap</title>" in treemap_svg
    assert (
        "<desc>Treemap showing code complexity by file size, hue indicates "
        "cyclomatic complexity, saturation indicates git churn</desc>"
    ) in treemap_svg
    # <title>/<desc> precede the first drawn element (<style>), i.e. they are the
    # root's first children.
    assert treemap_svg.index("<title>") < treemap_svg.index("<style>")
    assert treemap_svg.index("<desc>") < treemap_svg.index("<style>")


def test_treemap_per_rect_titles_carry_path_loc_ccn(treemap_svg):
    """Task 17: every file rect has a <title> naming the path, LOC and CCN."""
    rects = _parse_rects(treemap_svg)
    assert set(rects) == {
        "hot.py", "complex_stable.py", "simple_active.py", "simple_stable.py"
    }
    for name, (_fill, title) in rects.items():
        assert name in title
        assert "loc" in title
        assert "ccn" in title
    # The two complex files scored the known aggregate CCN 21.
    assert "ccn 21" in rects["hot.py"][1]
    assert "ccn 21" in rects["complex_stable.py"][1]


def test_treemap_ccn_maps_to_red_hue(treemap_svg):
    """ccn -> hue: with churn held equal (both high-churn), the high-CCN file is
    dark red while the low-CCN file is pale - red = low green/blue channels."""
    rects = _parse_rects(treemap_svg)
    hot = _hex_to_rgb(rects["hot.py"][0])           # ccn 21, churn high
    simple = _hex_to_rgb(rects["simple_active.py"][0])  # ccn 2, churn high
    # High CCN collapses green and blue toward zero (OrRd dark-red end).
    assert hot[1] < simple[1], "high-CCN green channel must be lower (redder)"
    assert hot[2] < simple[2], "high-CCN blue channel must be lower (redder)"
    assert hot[0] >= 120, "red channel stays high at the dark-red end"
    # Exact golden lock (see fixture README).
    assert rects["hot.py"][0] == "#7f0000"


def test_treemap_churn_maps_to_saturation(treemap_svg):
    """churn -> saturation: with CCN held equal (both aggregate 21), the
    high-churn file is vivid and the low-churn file is blended toward grey."""
    rects = _parse_rects(treemap_svg)
    hot = _hex_to_rgb(rects["hot.py"][0])              # ccn 21, churn high
    stable = _hex_to_rgb(rects["complex_stable.py"][0])  # ccn 21, churn low
    assert _chroma(hot) > _chroma(stable), (
        "high-churn file must be more saturated than the frozen one"
    )
    assert _chroma(hot) > 100 and _chroma(stable) < 50
    # Same axis at the low-CCN end: active file stays more saturated than frozen.
    active = _hex_to_rgb(rects["simple_active.py"][0])
    idle = _hex_to_rgb(rects["simple_stable.py"][0])
    assert _chroma(active) > _chroma(idle)
    # Exact golden lock (see fixture README).
    assert rects["complex_stable.py"][0] == "#c0a7ab"


# ── doc-graph-svg.py (doc navigability graph) ─────────────────────────────────

_CIRCLE_RE = re.compile(r'(<circle\b[^>]*>)\s*<title>(.*?)</title>', re.DOTALL)
_ATTR_RE = re.compile(r'(\S+?)="([^"]*)"')


def _parse_circles(svg: str) -> dict[str, dict]:
    """Map ``doc-basename -> {fill, stroke, stroke-width, title}`` for each node.
    The tooltip's first line is the doc's path."""
    out: dict[str, dict] = {}
    for tag, title in _CIRCLE_RE.findall(svg):
        attrs = dict(_ATTR_RE.findall(tag))
        rel = title.splitlines()[0].strip()
        attrs["title"] = title
        out[Path(rel).name] = attrs
    return out


@pytest.fixture(scope="module")
def doc_graph_svg(tmp_path_factory) -> str:
    """Render golden-doc-repo through the real doc-graph-svg pipeline.

    old.md is committed far in the past (stale); everything else is committed
    "now". src/app.py is churned so the staleness saturation axis is live.
    """
    env = _git_env()
    repo = tmp_path_factory.mktemp("golden_doc_repo")
    src = _FIXTURES / "golden-doc-repo"
    (repo / "src").mkdir()
    # Explicit allowlist: FIXTURE.md is documentation, not a graphed doc.
    for name in ("README.md", "guide.md", "old.md"):
        shutil.copy(src / name, repo / name)
    shutil.copy(src / "src" / "app.py", repo / "src" / "app.py")

    _init_repo(repo, env)
    old = "2020-01-01T00:00:00"
    stale_env = {**env, "GIT_AUTHOR_DATE": old, "GIT_COMMITTER_DATE": old}
    _git(repo, "add", "old.md", env=env)
    _git(repo, "commit", "-q", "-m", "old notes", env=stale_env)
    _git(repo, "add", "README.md", "guide.md", "src/app.py", env=env)
    _git(repo, "commit", "-q", "-m", "docs + code", env=env)
    for i in range(3):
        with (repo / "src" / "app.py").open("a", encoding="utf-8") as fh:
            fh.write(f"\n# churn {i}\n")
        _git(repo, "add", "-A", env=env)
        _git(repo, "commit", "-q", "-m", f"code churn {i}", env=env)

    out = repo / "doc.svg"
    return _run_script("doc-graph-svg.py", repo, out, env)


def test_doc_graph_a11y_metadata(doc_graph_svg):
    """Task 17: root <svg> is role="img" with the doc-graph <title>/<desc> pair
    as its first children."""
    assert 'role="img"' in doc_graph_svg
    assert "<title>Documentation Navigability Graph</title>" in doc_graph_svg
    assert (
        "<desc>Graph showing documentation structure, reachability from entry "
        "point, and staleness indicators</desc>"
    ) in doc_graph_svg
    assert doc_graph_svg.index("<title>") < doc_graph_svg.index("<style>")
    assert doc_graph_svg.index("<desc>") < doc_graph_svg.index("<style>")


def test_doc_graph_per_node_labels_carry_path_and_staleness(doc_graph_svg):
    """Task 17: every node's <title> is an accessible label with the doc path
    and its staleness."""
    circles = _parse_circles(doc_graph_svg)
    assert {"README.md", "guide.md", "old.md"} <= set(circles)
    for name in ("README.md", "guide.md", "old.md"):
        title = circles[name]["title"]
        assert name in title
        assert "stale" in title


def test_doc_graph_entry_node_marked(doc_graph_svg):
    """The entry point (README.md) carries the blue entry ring - the navigation
    root stays obvious even though colour now encodes staleness."""
    circles = _parse_circles(doc_graph_svg)
    entry = circles["README.md"]
    assert entry["stroke"] == "#0072B2"
    assert float(entry["stroke-width"]) >= 3.0
    assert "entry" in entry["title"]


def test_doc_graph_staleness_maps_to_red_hue(doc_graph_svg):
    """days-stale -> hue: the stale doc (committed years ago) is dark red while
    the fresh entry/guide docs are pale - staleness = low green/blue channels."""
    circles = _parse_circles(doc_graph_svg)
    old = _hex_to_rgb(circles["old.md"]["fill"])
    fresh = _hex_to_rgb(circles["README.md"]["fill"])
    assert old[1] < fresh[1], "stale doc green channel must be lower (redder)"
    assert old[2] < fresh[2], "stale doc blue channel must be lower (redder)"
    assert _chroma(old) > _chroma(fresh), "stale doc must be more saturated"
    # Exact golden lock (see fixture FIXTURE.md): oldest doc caps at darkest red,
    # same-day docs sit at the pale OrRd end.
    assert circles["old.md"]["fill"] == "#7f0000"
    assert circles["README.md"]["fill"] == "#fff7ec"
    assert circles["guide.md"]["fill"] == "#fff7ec"


def test_doc_graph_unmeasured_node_is_hatched_not_a_measured_colour(tmp_path):
    """A `.claude/` doc brought in by a reference has no staleness row (the
    staleness scan keeps excluding `.claude/`). It is drawn hatched, a fill no
    measured doc can receive, with a legend key and an "unmeasured" tooltip,
    rather than the grey a zero-churn measured doc gets."""
    env = _git_env()
    repo = tmp_path / "repo"
    (repo / ".claude").mkdir(parents=True)
    (repo / "README.md").write_text("# Entry\nOpen `.claude/notes.md`.\n", encoding="utf-8")
    (repo / ".claude" / "notes.md").write_text("# Notes\n", encoding="utf-8")
    _init_repo(repo, env)
    _git(repo, "add", "-A", env=env)
    _git(repo, "commit", "-q", "-m", "docs", env=env)
    svg = _run_script("doc-graph-svg.py", repo, tmp_path / "doc.svg", env)
    circles = _parse_circles(svg)
    assert circles["notes.md"]["fill"] == "url(#unmeasured)"
    assert '<pattern id="unmeasured"' in svg
    assert ">not measured</text>" in svg
    assert "staleness not measured" in circles["notes.md"]["title"]
    assert "0d stale" not in circles["notes.md"]["title"]
    assert "stale" in circles["README.md"]["title"]  # measured docs keep the scale
    assert circles["README.md"]["fill"].startswith("#")
    assert "2 docs, 1 edges" in svg

"""Executable invariant for the /assess hotspot wiki (assess-obey-thyself, task 9).

The `.assess/` wiki is a compounding history: a hotspot page survives across runs
even after the file graduates off the top list. But a page whose *source file has
been deleted* is a lying map - it keeps describing a file that no longer exists.
The contract this suite enforces:

    No active (non-retired) hotspot page references a source path absent from disk.

`prune_orphan_hotspots` maintains it by stamping every orphaned page RETIRED (the
file's history is preserved; the page just stops claiming the file is live). The
invariant helper below is the same check phrased as an assertion, so a page that
slips through the pruner - or a pruner regression - fails the build. Mirrors the
`test_self_architecture.py` idiom: a pure filesystem scan asserting a property.
"""
from __future__ import annotations

import json
import os
import shutil
import subprocess
from pathlib import Path

import pytest

from assess_core import build_run_context
from assess_finalize import finalize_run
from lib.badge import maturity_band
from lib.wiki_writer import (
    RETIRED_EXCLUDED_STATUS,
    RETIRED_STATUS,
    slug_for_path,
    verify_log_chain,
    hotspot_page_source_path,
    hotspot_page_status,
    is_retired_status,
    prune_orphan_hotspots,
    retire_excluded_hotspots,
    write_hotspot_page,
)


def _active_orphans(assess_dir: Path, repo_root: Path) -> list[str]:
    """Every source path an *active* (non-retired) hotspot page names that is
    absent from disk. The invariant holds iff this list is empty."""
    hotspots_dir = assess_dir / "hotspots"
    if not hotspots_dir.is_dir():
        return []
    orphans: list[str] = []
    for page in sorted(hotspots_dir.glob("*.md")):
        content = page.read_text(encoding="utf-8")
        path = hotspot_page_source_path(content)
        if path is None:
            continue
        if is_retired_status(hotspot_page_status(content)):
            continue  # retired pages are allowed to reference a missing file
        if not (repo_root / path).exists():
            orphans.append(path)
    return orphans


def _write_page(assess_dir: Path, path: str, status: str = "active") -> None:
    assess_dir.mkdir(parents=True, exist_ok=True)
    write_hotspot_page(
        assess_dir, path=path, first_flagged="2026-01-01", last_seen="2026-07-07",
        status=status, loc=600, ccn=30, commits=5, has_tests=None,
        history_rows="| 2026-07-07 | 600 | 30 | 5 | active |",
        briefing="x", actions="- y",
    )


def test_prune_retires_orphan_leaves_live_page(tmp_path: Path) -> None:
    """A deleted file's page is retired; a live file's page is untouched."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    (repo / "src").mkdir(parents=True)
    (repo / "src" / "live.go").write_text("package main\n")
    _write_page(assess, "src/live.go")
    _write_page(assess, "src/gone.go")  # never created on disk

    retired = prune_orphan_hotspots(assess, repo)
    assert retired == ["src/gone.go"]

    # The invariant now holds: no active page references a missing file.
    assert _active_orphans(assess, repo) == []


def test_orphan_invariant_fails_before_prune(tmp_path: Path) -> None:
    """The invariant helper catches a surviving active orphan - proving it isn't
    vacuously passing."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    assess.mkdir(parents=True)
    _write_page(assess, "src/gone.go")
    assert _active_orphans(assess, repo) == ["src/gone.go"]


def test_retired_page_preserves_history(tmp_path: Path) -> None:
    """Retirement stamps the status and a banner but keeps the page's history."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    assess.mkdir(parents=True)
    _write_page(assess, "src/gone.go")

    prune_orphan_hotspots(assess, repo)
    page = next((assess / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert RETIRED_STATUS in content
    assert "Retired:" in content
    # History section and the original path are preserved.
    assert "src/gone.go" in content
    assert "## History across runs" in content
    assert hotspot_page_status(content) == RETIRED_STATUS


def test_prune_is_idempotent(tmp_path: Path) -> None:
    """A second prune retires nothing new and doesn't double-stamp the banner."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    assess.mkdir(parents=True)
    _write_page(assess, "src/gone.go")

    assert prune_orphan_hotspots(assess, repo) == ["src/gone.go"]
    assert prune_orphan_hotspots(assess, repo) == []

    page = next((assess / "hotspots").iterdir())
    assert page.read_text(encoding="utf-8").count("Retired:") == 1


def test_prune_no_hotspots_dir(tmp_path: Path) -> None:
    """A repo with no hotspots/ directory yet prunes nothing (fresh install)."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    assess.mkdir(parents=True)
    assert prune_orphan_hotspots(assess, repo) == []


def test_file_recreated_can_be_rewritten_active(tmp_path: Path) -> None:
    """A retired page is overwritten fresh (active) if the file returns and is
    still a hotspot - write_hotspot_page rewrites the whole page."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    (repo / "src").mkdir(parents=True)
    _write_page(assess, "src/flap.go")
    prune_orphan_hotspots(assess, repo)
    page = next((assess / "hotspots").iterdir())
    assert hotspot_page_status(page.read_text()) == RETIRED_STATUS

    # File comes back and is re-written as a live hotspot.
    (repo / "src" / "flap.go").write_text("package main\n")
    _write_page(assess, "src/flap.go", status="regressed")
    content = page.read_text(encoding="utf-8")
    assert hotspot_page_status(content) == "regressed"
    assert "Retired:" not in content
    assert _active_orphans(assess, repo) == []


# --- excluded after an unfinalized run (#356) ---------------------------------
#
# A file first flagged by a core run that was never finalized, then excluded in
# `.assess/config.toml` before the next run, was never part of a finished
# assessment. Its page is retired (not deleted, not left live), its
# first-flagged.json entry is dropped, and it does not re-enter index.md as
# "graduated" through the rotated prior stats. An excluded file first flagged in
# a finalized run keeps its page and its date.

_EXCLUDE_DAY = "2026-09-18"


def _git(repo: Path, *args: str) -> None:
    subprocess.run(
        ["git", "-C", str(repo), "-c", "user.email=t@example.com", "-c", "user.name=T", *args],
        check=True, capture_output=True, text=True, env=os.environ,
    )


@pytest.fixture
def excl_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    for rel in ("src/hot.py", "gen/big.py", "vendor/fin.py"):
        (repo / rel).parent.mkdir(parents=True, exist_ok=True)
        (repo / rel).write_text("def f(a):\n    return a\n", encoding="utf-8")
    _git(repo, "init", "-q")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "c1")
    (repo / ".assess").mkdir()
    return repo


def _stats(assess_dir: Path, paths: list[str]) -> None:
    current = assess_dir / "complexity-stats.json"
    if current.exists():
        shutil.copy(current, assess_dir / "complexity-stats.prior.json")
    current.write_text(json.dumps({
        "files_scored": len(paths), "loc": {"total": len(paths)},
        "ccn": {"max": 1, "mean": 1},
        "top_hotspots": [{"path": p, "loc": 1, "ccn": 1, "commits": 1} for p in paths],
        "top_complex": [], "top_large": [],
    }), encoding="utf-8")


def _core(repo: Path, day: str = _EXCLUDE_DAY) -> dict:
    return build_run_context(repo_root=repo, run_date=day, non_interactive=True)


def _finalize(assess_dir: Path, ctx: dict) -> None:
    (assess_dir / ".cache").mkdir(exist_ok=True)
    (assess_dir / ".cache" / "finalize-input.json").write_text(json.dumps({
        "run_id": ctx["run_id"], "score": 4.0, "denominator": 8,
        "maturity_label": maturity_band(4.0, 8),
        "top_action": "fixture action", "hotspot_actions": {},
    }), encoding="utf-8")
    finalize_run(assess_dir=assess_dir)


def _status(assess_dir: Path, path: str) -> str | None:
    page = assess_dir / "hotspots" / f"{slug_for_path(path)}.md"
    return hotspot_page_status(page.read_text(encoding="utf-8")) if page.exists() else None


def _exclude(repo: Path, dirs: list[str]) -> None:
    (repo / ".assess" / "config.toml").write_text(f"exclude_dirs = {dirs!r}\n", encoding="utf-8")


def test_core_retires_page_excluded_after_unfinalized_run(excl_repo: Path) -> None:
    assess = excl_repo / ".assess"
    _stats(assess, ["src/hot.py", "vendor/fin.py"])
    _finalize(assess, _core(excl_repo, "2026-09-17"))
    _stats(assess, ["gen/big.py", "src/hot.py", "vendor/fin.py"])
    _core(excl_repo)  # flags gen/big.py, never finalized
    _exclude(excl_repo, ["gen", "vendor"])
    _stats(assess, ["src/hot.py"])
    ctx = _core(excl_repo)
    _finalize(assess, ctx)

    assert _status(assess, "gen/big.py") == RETIRED_EXCLUDED_STATUS
    for live in ("vendor/fin.py", "src/hot.py"):
        status = _status(assess, live)
        assert status is not None and not status.startswith("retired")
    flagged = json.loads((assess / "first-flagged.json").read_text(encoding="utf-8"))
    assert flagged == {"src/hot.py": "2026-09-17", "vendor/fin.py": "2026-09-17"}
    index = (assess / "index.md").read_text(encoding="utf-8")
    assert "gen/big.py" not in index
    assert [p["path"] for p in ctx["diff_detail"]["graduated"]] == ["vendor/fin.py"]
    assert ctx["retired_excluded_hotspots"] == ["gen/big.py"]
    assert ctx["dropped_first_flagged"] == ["gen/big.py"]
    assert verify_log_chain(assess) == (True, None)


def test_excluded_after_unfinalized_run_chain_of_superseded_runs(excl_repo: Path) -> None:
    """The file stays provisional across a second unfinalized run that
    supersedes the first, where it is no longer "new"."""
    assess = excl_repo / ".assess"
    _stats(assess, ["src/hot.py"])
    _finalize(assess, _core(excl_repo, "2026-09-17"))
    _stats(assess, ["gen/big.py", "src/hot.py"])
    _core(excl_repo)
    _stats(assess, ["gen/big.py", "src/hot.py"])
    _core(excl_repo)  # gen/big.py is persistent here, still unfinalized
    _exclude(excl_repo, ["gen"])
    _stats(assess, ["src/hot.py"])
    _core(excl_repo)

    assert _status(assess, "gen/big.py") == RETIRED_EXCLUDED_STATUS
    flagged = json.loads((assess / "first-flagged.json").read_text(encoding="utf-8"))
    assert flagged == {"src/hot.py": "2026-09-17"}


def test_excluded_after_unfinalized_run_on_new_commit_is_kept(excl_repo: Path) -> None:
    """A run on a new commit does not supersede the unfinalized one, so the
    rule does not fire and the file graduates as before."""
    assess = excl_repo / ".assess"
    _stats(assess, ["gen/big.py", "src/hot.py"])
    _core(excl_repo)
    (excl_repo / "src" / "other.py").write_text("x = 1\n", encoding="utf-8")
    _git(excl_repo, "add", "-A")
    _git(excl_repo, "commit", "-q", "-m", "c2")
    _exclude(excl_repo, ["gen"])
    _stats(assess, ["src/hot.py"])
    ctx = _core(excl_repo)

    assert ctx["retired_excluded_hotspots"] == []
    status = _status(assess, "gen/big.py")
    assert status is not None and not status.startswith("retired")


def test_excluded_after_unfinalized_run_ignores_pre_upgrade_run_context(excl_repo: Path) -> None:
    """A superseded run-context without provisional_first_flagged (written
    before the key existed) retires nothing, even for a path it lists as new."""
    assess = excl_repo / ".assess"
    _stats(assess, ["gen/big.py", "src/hot.py"])
    _core(excl_repo)
    ctx_path = assess / "run-context.json"
    prior = json.loads(ctx_path.read_text(encoding="utf-8"))
    assert "gen/big.py" in [h["path"] for h in prior["diff_detail"]["new"]]
    del prior["provisional_first_flagged"]
    ctx_path.write_text(json.dumps(prior), encoding="utf-8")
    _exclude(excl_repo, ["gen"])
    _stats(assess, ["src/hot.py"])
    ctx = _core(excl_repo)

    assert ctx["retired_excluded_hotspots"] == []
    assert ctx["dropped_first_flagged"] == []
    status = _status(assess, "gen/big.py")
    assert status is not None and not status.startswith("retired")
    flagged = json.loads((assess / "first-flagged.json").read_text(encoding="utf-8"))
    assert flagged["gen/big.py"] == _EXCLUDE_DAY


def test_prune_leaves_excluded_retired_page_alone(tmp_path: Path) -> None:
    """A page already retired for another reason is not re-stamped when its
    file is later deleted."""
    repo = tmp_path / "repo"
    assess = repo / ".assess"
    _write_page(assess, "gen/big.py", status=RETIRED_EXCLUDED_STATUS)
    assert prune_orphan_hotspots(assess, repo) == []
    page = next((assess / "hotspots").iterdir())
    assert hotspot_page_status(page.read_text(encoding="utf-8")) == RETIRED_EXCLUDED_STATUS
    # The file is absent from disk, yet the invariant holds: the page is retired.
    assert _active_orphans(assess, repo) == []


def test_retire_excluded_skips_page_without_status_token(tmp_path: Path) -> None:
    """A page with no status token cannot be stamped, so it is reported as
    unstamped rather than retired, and the core keeps its first-flagged entry."""
    assess = tmp_path / ".assess"
    _write_page(assess, "gen/big.py")
    _write_page(assess, "gen/odd.py")
    odd = assess / "hotspots" / f"{slug_for_path('gen/odd.py')}.md"
    odd.write_text("# Hotspot: `gen/odd.py`\n\nno metadata line\n", encoding="utf-8")
    before = odd.read_text(encoding="utf-8")

    retired, unstamped = retire_excluded_hotspots(assess, ["gen/odd.py", "gen/big.py", "gen/none.py"])
    assert retired == ["gen/big.py"]
    assert unstamped == ["gen/odd.py"]
    assert odd.read_text(encoding="utf-8") == before

"""Tests for the instruction-file bloat penalty and skills-delegation credit.

The core thesis (see `test_monolith_scores_strictly_below_lean_plus_skills`):
an oversized monolithic instruction file that is NOT factored into on-demand
skills scores STRICTLY BELOW an equivalent lean-file-plus-skills repo. The
monolith is penalized, not merely annotated. Conservative thresholds ensure
small/legitimate instruction files are never penalized.
"""
from __future__ import annotations

from pathlib import Path

from lib.agent_instructions_grader import (
    SIZE_THRESHOLD_LINES,
    compute_bloat_penalty,
    compute_size_metrics,
    detect_skills_delegation,
    detect_skills_dir,
    grade_instructions,
)


def test_bloat_penalty_on_monolith(fixtures_dir: Path) -> None:
    """Monolithic 600+ line file without skills gets a bloat penalty."""
    text = (fixtures_dir / "monolithic_instructions.md").read_text()
    size = compute_size_metrics(text)
    assert size["exceeds_line_threshold"] is True

    penalty, msg = compute_bloat_penalty(
        size, skills_present=False, delegates_to_skills=False
    )
    assert penalty >= 5
    assert msg is not None
    assert "factor guidance into on-demand skills" in msg


def test_no_bloat_penalty_with_skills(fixtures_dir: Path) -> None:
    """Lean file with skills delegation gets no bloat penalty."""
    repo = fixtures_dir / "lean_with_skills"
    text = (repo / "CLAUDE.md").read_text()
    size = compute_size_metrics(text)
    skills = detect_skills_dir(repo)
    delegation = detect_skills_delegation(text)

    penalty, msg = compute_bloat_penalty(
        size,
        skills["skills_dirs_present"],
        delegation["delegates_to_skills"],
    )
    assert penalty == 0
    assert msg is None


def test_oversized_but_factored_into_skills_no_penalty(fixtures_dir: Path) -> None:
    """An oversized hub file is NOT penalized when skills are present - it may
    be a hub that points to skills (progressive disclosure)."""
    text = (fixtures_dir / "monolithic_instructions.md").read_text()
    size = compute_size_metrics(text)
    assert size["exceeds_line_threshold"] is True

    # skills_present short-circuits the penalty even for an oversized file.
    penalty, msg = compute_bloat_penalty(
        size, skills_present=True, delegates_to_skills=False
    )
    assert penalty == 0
    assert msg is None

    # delegation pointers in the text alone also suppress the penalty.
    penalty2, _ = compute_bloat_penalty(
        size, skills_present=False, delegates_to_skills=True
    )
    assert penalty2 == 0


def test_monolith_scores_strictly_below_lean_plus_skills(fixtures_dir: Path) -> None:
    """REGRESSION TEST (core thesis): equivalent guidance scores STRICTLY LOWER
    as an unfactored monolith than as a lean-file-plus-skills repo.

    Grading the same guidance two ways isolates the penalty as the sole
    difference: one repo inlines everything (no skills factoring), the other
    factors it into on-demand skills. The monolith is penalized, not merely
    annotated, so its score is strictly lower.
    """
    text = (fixtures_dir / "monolithic_instructions.md").read_text()

    monolith_grade = grade_instructions(
        text, freshness_days=10, skills_present=False, delegates_to_skills=False
    )
    factored_grade = grade_instructions(
        text, freshness_days=10, skills_present=True
    )

    assert monolith_grade.subscores["bloat_penalty"] >= 5
    assert factored_grade.subscores["bloat_penalty"] == 0
    assert monolith_grade.score < factored_grade.score


def test_lean_fixture_repo_detects_skills_and_avoids_penalty(fixtures_dir: Path) -> None:
    """End-to-end on the lean fixture repo: skills dir is detected, delegation
    pointers are present, and the graded file carries no bloat penalty."""
    repo = fixtures_dir / "lean_with_skills"
    text = (repo / "CLAUDE.md").read_text()

    skills = detect_skills_dir(repo)
    assert skills["skills_dirs_present"] is True
    assert skills["skills_count"] == 2
    assert any("java-conventions" in f for f in skills["skill_files"])

    grade = grade_instructions(
        text, freshness_days=10, skills_present=skills["skills_dirs_present"]
    )
    assert grade.subscores["bloat_penalty"] == 0


def test_graceful_no_skills_dir(tmp_path: Path) -> None:
    """Repos without any skills directory degrade gracefully."""
    skills = detect_skills_dir(tmp_path)
    assert skills["skills_dirs_present"] is False
    assert skills["skills_count"] == 0
    assert skills["skill_files"] == []
    assert skills["skills_dirs"] == []


def test_small_file_no_penalty() -> None:
    """Small/legitimate instruction files are never penalized."""
    small_text = "Use bcrypt for password hashing.\n" * 100  # 100 lines
    size = compute_size_metrics(small_text)

    assert size["exceeds_line_threshold"] is False
    assert size["exceeds_word_threshold"] is False
    penalty, msg = compute_bloat_penalty(
        size, skills_present=False, delegates_to_skills=False
    )
    assert penalty == 0
    assert msg is None


def test_threshold_boundary_lines() -> None:
    """Files at exactly the line threshold are not penalized; one more is."""
    boundary_text = "Line\n" * SIZE_THRESHOLD_LINES
    size = compute_size_metrics(boundary_text)
    assert size["line_count"] == SIZE_THRESHOLD_LINES
    assert size["exceeds_line_threshold"] is False

    over_text = "Line\n" * (SIZE_THRESHOLD_LINES + 1)
    over_size = compute_size_metrics(over_text)
    assert over_size["exceeds_line_threshold"] is True
    penalty, _ = compute_bloat_penalty(
        over_size, skills_present=False, delegates_to_skills=False
    )
    assert penalty == 5


def test_penalty_tiers_by_lines() -> None:
    """Penalty escalates with overage: -5 / -10 / -15."""
    def lines_penalty(n: int) -> int:
        size = compute_size_metrics("x\n" * n)
        return compute_bloat_penalty(size, False, False)[0]

    assert lines_penalty(600) == 5    # 500-750
    assert lines_penalty(800) == 10   # 750-1000
    assert lines_penalty(1200) == 15  # 1000+


def test_penalty_tiers_by_words() -> None:
    """Word-count tiers mirror the line tiers at 3000/4500/6000."""
    def words_penalty(n: int) -> int:
        # Few lines, many words: isolates the word-count metric.
        size = compute_size_metrics(" ".join(["word"] * n))
        return compute_bloat_penalty(size, False, False)[0]

    assert words_penalty(3500) == 5    # 3000-4500
    assert words_penalty(5000) == 10   # 4500-6000
    assert words_penalty(7000) == 15   # 6000+


def test_penalty_takes_higher_of_two_metrics() -> None:
    """When both metrics exceed, the higher penalty wins."""
    # 600 lines (-5 by lines) but 7000 words (-15 by words) -> expect -15.
    text = ("word " * 12 + "\n") * 600
    size = compute_size_metrics(text)
    assert size["line_count"] > SIZE_THRESHOLD_LINES
    assert size["word_count"] > 6000
    penalty, _ = compute_bloat_penalty(size, False, False)
    assert penalty == 15

"""Tests for lib/instruction_claims.py - verifying claims in agent instruction files.

An instruction file that says "`scripts/check-x.sh` is enforced in CI" or "Node
20.11.0 is pinned in `.nvmrc`" makes a checkable promise. The scan extracts each
such sentence and checks it against the repository, so a claim nothing backs
surfaces as a failure with its file and line.
"""
from __future__ import annotations

import json
import os
from pathlib import Path

import pytest

from lib.instruction_claims import extract_claims, scan_instruction_claims

ENFORCED = "# Agents\n\nKeep changes small.\n\n`scripts/check-x.sh` is enforced in CI.\n"
WORKFLOW_WITHOUT = (
    "on: push\njobs:\n  hello:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo hello\n"
)
WORKFLOW_WITH = (
    "on: push\njobs:\n  lint:\n    runs-on: ubuntu-latest\n    steps:\n"
    "      - run: bash scripts/check-x.sh\n"
)


def _failures(block: dict) -> list[list]:
    return [[f["file"], f["line"], f["kind"]] for f in block["failures"]]


@pytest.fixture
def repo(tmp_path: Path) -> Path:
    (tmp_path / "scripts").mkdir()
    (tmp_path / "scripts" / "check-x.sh").write_text("echo ok\n")
    (tmp_path / ".github" / "workflows").mkdir(parents=True)
    return tmp_path


def test_enforcement_claim_with_no_workflow_reference_fails_with_its_line(repo: Path) -> None:
    (repo / "AGENTS.md").write_text(ENFORCED)
    (repo / ".github" / "workflows" / "ci.yml").write_text(WORKFLOW_WITHOUT)
    block = scan_instruction_claims(repo, ["AGENTS.md"])
    assert (block["total"], block["verified"], block["failed"]) == (1, 0, 1)
    assert _failures(block) == [["AGENTS.md", 5, "enforcement"]]
    assert block["failures"][0]["path"] == "scripts/check-x.sh"


def test_enforcement_claim_verifies_when_a_workflow_calls_the_script(repo: Path) -> None:
    (repo / "AGENTS.md").write_text(ENFORCED)
    (repo / ".github" / "workflows" / "ci.yml").write_text(WORKFLOW_WITH)
    block = scan_instruction_claims(repo, ["AGENTS.md"])
    assert block == {"total": 1, "verified": 1, "failed": 0, "failures": []}


def test_enforcement_claim_is_skipped_when_the_repo_has_no_ci_config(tmp_path: Path) -> None:
    # Nothing to check against: unverifiable, not false - no accusation.
    (tmp_path / "AGENTS.md").write_text(ENFORCED)
    assert scan_instruction_claims(tmp_path, ["AGENTS.md"])["total"] == 0


def test_enforcement_failure_carries_a_reason(repo: Path) -> None:
    (repo / "AGENTS.md").write_text(ENFORCED)
    (repo / ".github" / "workflows" / "ci.yml").write_text(WORKFLOW_WITHOUT)
    reason = scan_instruction_claims(repo, ["AGENTS.md"])["failures"][0]["reason"]
    assert "references the script" in reason


@pytest.mark.parametrize("ci_file", [".gitlab-ci.yml", "Jenkinsfile", ".circleci/config.yml"])
def test_enforcement_claim_verifies_against_non_github_ci(tmp_path: Path, ci_file: str) -> None:
    (tmp_path / "AGENTS.md").write_text(ENFORCED)
    (tmp_path / ci_file).parent.mkdir(parents=True, exist_ok=True)
    (tmp_path / ci_file).write_text("lint:\n  script: bash scripts/check-x.sh\n")
    block = scan_instruction_claims(tmp_path, ["AGENTS.md"])
    assert (block["total"], block["verified"]) == (1, 1)


@pytest.mark.parametrize("runner, body", [
    ("Makefile", "lint:\n\tbash scripts/check-x.sh\n"),
    ("package.json", '{"scripts": {"lint": "scripts/check-x.sh"}}\n'),
    (".pre-commit-config.yaml", "- id: x\n  entry: scripts/check-x.sh\n"),
])
def test_enforcement_claim_verifies_through_a_task_runner(repo: Path, runner: str, body: str) -> None:
    # The workflow calls `make lint` / `npm run lint` / pre-commit, not the path.
    (repo / "AGENTS.md").write_text(ENFORCED)
    (repo / ".github" / "workflows" / "ci.yml").write_text(WORKFLOW_WITHOUT)
    (repo / runner).write_text(body)
    block = scan_instruction_claims(repo, ["AGENTS.md"])
    assert (block["total"], block["verified"]) == (1, 1)


def test_file_with_no_matching_pattern_yields_zero_claims(repo: Path) -> None:
    (repo / "AGENTS.md").write_text("# Agents\n\nKeep changes small. Prefer plain names.\n")
    block = scan_instruction_claims(repo, ["AGENTS.md"])
    assert block == {"total": 0, "verified": 0, "failed": 0, "failures": []}


def test_no_instruction_files_yields_the_empty_block(tmp_path: Path) -> None:
    assert scan_instruction_claims(tmp_path, []) == {
        "total": 0, "verified": 0, "failed": 0, "failures": []}


def test_unreadable_or_missing_file_is_skipped_not_raised(tmp_path: Path) -> None:
    (tmp_path / "AGENTS.md").write_bytes(b"\xff\xfe not utf-8 `scripts/a.sh` runs in CI")
    block = scan_instruction_claims(tmp_path, ["AGENTS.md", "CLAUDE.md"])
    assert block["total"] == 0


def test_pin_claims_verify_on_version_either_side_of_pinned_in(tmp_path: Path) -> None:
    (tmp_path / ".nvmrc").write_text("18.19.0\n")
    (tmp_path / ".tool-versions").write_text("golang 1.22.3\n")
    (tmp_path / "AGENTS.md").write_text(
        "# Agents\n\nNode 20.11.0 is pinned in `.nvmrc`.\n\n"
        "The Go toolchain is pinned in `.tool-versions` at 1.22.3.\n\n"
        "Ruby 3.3.0 is pinned in `.ruby-version`.\n"
    )
    block = scan_instruction_claims(tmp_path, ["AGENTS.md"])
    assert (block["total"], block["verified"], block["failed"]) == (3, 1, 2)
    assert sorted(_failures(block)) == [["AGENTS.md", 3, "pin"], ["AGENTS.md", 7, "pin"]]
    by_line = {f["line"]: f for f in block["failures"]}
    assert (by_line[3]["path"], by_line[3]["version"]) == (".nvmrc", "20.11.0")
    assert by_line[3]["reason"] == "pinned file does not contain the version"
    assert by_line[7]["path"] == ".ruby-version"
    assert by_line[7]["reason"] == "pinned file does not exist"


def test_pin_sentence_without_a_version_is_skipped() -> None:
    assert extract_claims("The toolchain is pinned in `.tool-versions`.\n") == []


def test_pin_sentence_with_two_versions_is_skipped_as_ambiguous() -> None:
    text = "Node 20.11.0 is pinned in `.nvmrc`, upgraded from 18.19.0.\n"
    assert extract_claims(text) == []


def test_claim_in_a_wrapped_paragraph_reports_the_line_the_sentence_starts_on() -> None:
    text = "# Agents\n\nKeep it small. The lint script\n`scripts/lint.sh` is enforced\nin CI.\n"
    claims = extract_claims(text)
    assert [(c.kind, c.line, c.path) for c in claims] == [("enforcement", 3, "scripts/lint.sh")]


def test_fenced_code_is_not_read_as_claims() -> None:
    text = "```\n`scripts/lint.sh` is enforced in CI.\n```\n"
    assert extract_claims(text) == []


def test_enforcement_needs_a_trigger_phrase_and_a_script_path() -> None:
    assert extract_claims("Run `scripts/lint.sh` before pushing.\n") == []
    assert extract_claims("Linting is enforced in CI.\n") == []
    # "CI" is a word, not a substring of another word.
    assert extract_claims("Run `scripts/lint.sh` for CIRCLE builds.\n") == []
    # A backticked workflow file is not a script the workflows would call.
    assert extract_claims("CI runs `.github/workflows/ci.yml`.\n") == []


@pytest.mark.parametrize("sentence", [
    "Do not edit `src/db/env.py`; CI will fail if you do.",
    "`src/index.ts` must compile before CI passes.",
    "`lib/scripts_helper.rb` is checked by the linter.",
])
def test_ordinary_source_files_are_not_enforcement_claims(sentence: str) -> None:
    assert extract_claims(sentence + "\n") == []


@pytest.mark.parametrize("path", ["scripts/gate.py", "bin/check.js", "tools/ci/lint.ts",
                                  "hack/verify.rb", "ops/deploy.sh"])
def test_script_paths_that_ci_invokes_are_enforcement_claims(path: str) -> None:
    claims = extract_claims(f"`{path}` is enforced in CI.\n")
    assert [c.path for c in claims] == [path]


@pytest.mark.parametrize("phrase", ["is enforced by the pipeline", "runs in the lint job",
                                    "is checked by the gate", "gates CI"])
def test_each_enforcement_trigger_phrase_makes_a_claim(phrase: str) -> None:
    claims = extract_claims(f"`./scripts/lint.sh` {phrase}.\n")
    assert [(c.kind, c.path) for c in claims] == [("enforcement", "scripts/lint.sh")]


def test_duplicate_file_through_a_symlink_is_scanned_once(repo: Path) -> None:
    (repo / "CLAUDE.md").write_text(ENFORCED)
    (repo / "AGENTS.md").symlink_to("CLAUDE.md")
    block = scan_instruction_claims(repo, ["CLAUDE.md", "AGENTS.md"])
    assert block["total"] == 1


def test_block_is_json_serialisable(repo: Path) -> None:
    (repo / "AGENTS.md").write_text(ENFORCED)
    json.dumps(scan_instruction_claims(repo, ["AGENTS.md"]))


def test_build_run_context_carries_the_block(tmp_path: Path) -> None:
    from assess_core import build_run_context

    (tmp_path / "AGENTS.md").write_text(ENFORCED)
    (tmp_path / ".github" / "workflows").mkdir(parents=True)
    (tmp_path / ".github" / "workflows" / "ci.yml").write_text(WORKFLOW_WITHOUT)
    ctx = build_run_context(repo_root=tmp_path, run_date="2026-09-18")
    assert _failures(ctx["instruction_claims"]) == [["AGENTS.md", 5, "enforcement"]]
    written = json.loads((tmp_path / ".assess" / "run-context.json").read_text())
    assert written["instruction_claims"]["failed"] == 1


def test_heading_directly_above_prose_does_not_lend_its_words_or_line() -> None:
    # No blank line under the heading: the `CI` in it must not trigger the
    # sentence below, and a claim there reports its own line, not the heading's.
    assert extract_claims("## CI\n`scripts/lint.sh` must pass.\n") == []
    claims = extract_claims("# Agents\n## Lint\n`scripts/lint.sh` is enforced in CI.\n")
    assert [(c.kind, c.line) for c in claims] == [("enforcement", 3)]


@pytest.fixture
def counted(tmp_path: Path) -> Path:
    (tmp_path / "supabase" / "tests").mkdir(parents=True)
    for i in range(177):
        (tmp_path / "supabase" / "tests" / f"t{i}.sql").write_text("")
    (tmp_path / "cmds").mkdir()
    for i in range(7):
        (tmp_path / "cmds" / f"c{i}.md").write_text("# cmd\n")
    return tmp_path


def test_count_claim_far_from_the_pattern_fails_with_both_numbers(counted: Path) -> None:
    (counted / "AGENTS.md").write_text(
        "# Agents\n\nThere are 43 pgTAP suites matching `supabase/tests/*.sql`.\n")
    block = scan_instruction_claims(counted, ["AGENTS.md"])
    assert (block["total"], block["verified"], block["failed"]) == (1, 0, 1)
    failure = block["failures"][0]
    assert [failure["file"], failure["line"], failure["kind"]] == ["AGENTS.md", 3, "count"]
    assert (failure["claimed"], failure["actual"]) == (43, 177)
    assert failure["path"] == "supabase/tests/*.sql"


def test_count_sentence_without_a_backticked_pattern_is_no_claim(counted: Path) -> None:
    (counted / "AGENTS.md").write_text("# Agents\n\nWe maintain 43 pgTAP suites.\n")
    assert scan_instruction_claims(counted, ["AGENTS.md"]) == {
        "total": 0, "verified": 0, "failed": 0, "failures": []}


def test_count_within_ten_percent_or_two_verifies(counted: Path) -> None:
    # 170 vs 177 is inside 10%; 5 vs 7 is a difference of exactly 2; 150 vs 177 is not.
    (counted / "AGENTS.md").write_text(
        "# Agents\n\nThere are 170 pgTAP files matching `supabase/tests/*.sql`.\n\n"
        "The plugin ships 5 commands in `cmds/*.md`.\n\n"
        "The 150 migrations live in `supabase/tests/*.sql`.\n")
    block = scan_instruction_claims(counted, ["AGENTS.md"])
    assert (block["total"], block["verified"], block["failed"]) == (3, 2, 1)
    failure = block["failures"][0]
    assert (failure["line"], failure["claimed"], failure["actual"]) == (7, 150, 177)


def test_count_tolerance_is_the_larger_of_ten_percent_or_two() -> None:
    from lib.instruction_claims import count_within_tolerance

    assert count_within_tolerance(5, 7)
    assert not count_within_tolerance(4, 7)
    assert count_within_tolerance(100, 110)
    assert not count_within_tolerance(100, 112)


def test_count_pattern_matching_nothing_in_an_existing_directory_fails_with_actual_zero(
        tmp_path: Path) -> None:
    (tmp_path / "tests").mkdir()
    (tmp_path / "AGENTS.md").write_text("There are 12 suites in `tests/*.sql`.\n")
    failure = scan_instruction_claims(tmp_path, ["AGENTS.md"])["failures"][0]
    assert (failure["kind"], failure["claimed"], failure["actual"]) == ("count", 12, 0)


def test_count_pattern_whose_directory_is_missing_is_unverifiable_not_failed(
        tmp_path: Path) -> None:
    (tmp_path / "AGENTS.md").write_text("There are 12 suites in `tests/*.sql`.\n")
    assert scan_instruction_claims(tmp_path, ["AGENTS.md"])["total"] == 0


def _thirty_pages(root: Path) -> None:
    for i in range(30):
        sub = root / "docs" / ("a" if i % 2 else "b/c")
        sub.mkdir(parents=True, exist_ok=True)
        (sub / f"p{i}.md").write_text("")


def test_count_recursive_glob_counts_files_not_directories(tmp_path: Path) -> None:
    _thirty_pages(tmp_path)
    for i in range(10):  # directories whose names match the pattern
        (tmp_path / "docs" / f"legacy{i}.md").mkdir()
        (tmp_path / "docs" / f"legacy{i}.md" / "keep").write_text("")
    (tmp_path / "AGENTS.md").write_text("The 30 pages under `docs/**/*.md` are the map.\n")
    block = scan_instruction_claims(tmp_path, ["AGENTS.md"])
    assert (block["total"], block["verified"]) == (1, 1)


def test_count_skips_git_metadata_and_matches_outside_the_repo(tmp_path: Path) -> None:
    repo, outside = tmp_path / "repo", tmp_path / "outside"
    _thirty_pages(repo)
    (repo / "docs" / ".git").mkdir()
    outside.mkdir()
    for i in range(10):
        (repo / "docs" / ".git" / f"g{i}.md").write_text("")
        (outside / f"o{i}.md").write_text("")
    (repo / "docs" / "vendor").symlink_to(outside)
    (repo / "AGENTS.md").write_text("The 30 pages under `docs/**/*.md` are the map.\n")
    block = scan_instruction_claims(repo, ["AGENTS.md"])
    assert (block["total"], block["verified"]) == (1, 1)


def test_count_does_not_count_a_symlinked_file_outside_the_repo(tmp_path: Path) -> None:
    repo, outside = tmp_path / "repo", tmp_path / "outside"
    _thirty_pages(repo)
    outside.mkdir()
    for i in range(10):
        (outside / f"o{i}.md").write_text("")
        (repo / "docs" / "a" / f"link{i}.md").symlink_to(outside / f"o{i}.md")
    (repo / "AGENTS.md").write_text("The 30 pages under `docs/**/*.md` are the map.\n")
    block = scan_instruction_claims(repo, ["AGENTS.md"])
    assert (block["total"], block["verified"]) == (1, 1)


@pytest.mark.parametrize("pattern", ["skills/*", "skills/*/"])
def test_count_of_directories_is_unverifiable_not_a_zero_count(tmp_path: Path, pattern: str) -> None:
    for i in range(12):
        (tmp_path / "skills" / f"s{i}").mkdir(parents=True)
        (tmp_path / "skills" / f"s{i}" / "SKILL.md").write_text("")
    (tmp_path / "AGENTS.md").write_text(f"The 12 skills live in `{pattern}`.\n")
    assert scan_instruction_claims(tmp_path, ["AGENTS.md"])["total"] == 0


def test_count_ignores_tool_output_and_dependency_trees_below_the_pattern(tmp_path: Path) -> None:
    _thirty_pages(tmp_path)
    for tree in (".assess/hotspots", "node_modules/pkg", ".venv/lib"):
        (tmp_path / tree).mkdir(parents=True)
        for i in range(10):
            (tmp_path / tree / f"x{i}.md").write_text("")
    (tmp_path / "AGENTS.md").write_text("The 30 pages under `**/*.md` are the map.\n")
    # AGENTS.md itself is the 31st page; within tolerance.
    block = scan_instruction_claims(tmp_path, ["AGENTS.md"])
    assert (block["total"], block["verified"]) == (1, 1)


def test_count_inside_an_excluded_directory_named_on_purpose_still_counts(tmp_path: Path) -> None:
    (tmp_path / "vendor" / "docs").mkdir(parents=True)
    for i in range(30):
        (tmp_path / "vendor" / "docs" / f"v{i}.md").write_text("")
    (tmp_path / "AGENTS.md").write_text("We vendor 12 pages in `vendor/docs/*.md`.\n")
    failure = scan_instruction_claims(tmp_path, ["AGENTS.md"])["failures"][0]
    assert (failure["claimed"], failure["actual"]) == (12, 30)


@pytest.mark.skipif(not hasattr(os, "geteuid") or os.geteuid() == 0,
                    reason="root reads a directory whatever its mode")
def test_count_with_an_unreadable_subtree_is_unverifiable(tmp_path: Path) -> None:
    _thirty_pages(tmp_path)
    locked = tmp_path / "docs" / "b"
    locked.chmod(0)
    try:
        (tmp_path / "AGENTS.md").write_text("The 30 pages under `docs/**/*.md` are the map.\n")
        assert scan_instruction_claims(tmp_path, ["AGENTS.md"])["total"] == 0
    finally:
        locked.chmod(0o755)


@pytest.mark.parametrize("sentence", [
    "Keep every page under `docs/**/*.md` below 500 lines.",
    "Keep at most 10 files in `x/*.md`.",
    "Cap `src/**/*.ts` at 80 columns.",
    "Review any change to `skills/*/SKILL.md` within 3 days.",
    "Allow no more than 5 pages in `docs/*.md`.",
])
def test_count_threshold_integer_is_not_a_count_claim(sentence: str) -> None:
    assert [c for c in extract_claims(sentence + "\n") if c.kind == "count"] == []


@pytest.mark.parametrize("sentence", [
    "Indent `scripts/*.sh` with 4 spaces.",
    "Cap `src/**/*.ts` at 15 cyclomatic complexity.",
    "Run the suite 2 times before touching `tests/*.py`.",
    # The pattern before the integer, even with a linking word.
    "Files in `docs/*.md` number 30.",
])
def test_count_needs_the_integer_then_a_linking_word_before_the_pattern(sentence: str) -> None:
    assert [c for c in extract_claims(sentence + "\n") if c.kind == "count"] == []


@pytest.mark.parametrize("sentence, claimed", [
    ("There are 43 pgTAP suites matching `supabase/tests/*.sql`.", 43),
    ("There are 170 pgTAP files matching `supabase/tests/*.sql`.", 170),
    ("The plugin ships 5 commands in `cmds/*.md`.", 5),
    ("The 150 migrations live in `supabase/tests/*.sql`.", 150),
])
def test_count_contract_sentences_pass_the_order_gate(sentence: str, claimed: int) -> None:
    claims = extract_claims(sentence + "\n")
    assert [(c.kind, c.fields) for c in claims] == [("count", {"claimed": claimed})]


def test_count_claim_without_a_unit_or_comparator_is_still_extracted() -> None:
    claims = extract_claims("There are 43 pgTAP suites matching `supabase/tests/*.sql`.\n")
    assert [(c.kind, c.fields) for c in claims] == [("count", {"claimed": 43})]


def test_count_non_recursive_pattern_over_files_and_directories_is_unverifiable(
        tmp_path: Path) -> None:
    (tmp_path / "docs").mkdir()
    (tmp_path / "docs" / "README.md").write_text("")
    for i in range(12):
        (tmp_path / "docs" / f"guide{i}").mkdir()
    (tmp_path / "AGENTS.md").write_text("The 12 guides live in `docs/*`.\n")
    assert scan_instruction_claims(tmp_path, ["AGENTS.md"])["total"] == 0


def test_count_non_recursive_pattern_over_files_only_still_counts(tmp_path: Path) -> None:
    (tmp_path / "docs").mkdir()
    for i in range(30):
        (tmp_path / "docs" / f"g{i}").write_text("")
    (tmp_path / "AGENTS.md").write_text("The 12 guides live in `docs/*`.\n")
    failure = scan_instruction_claims(tmp_path, ["AGENTS.md"])["failures"][0]
    assert (failure["claimed"], failure["actual"]) == (12, 30)


def test_count_glob_error_is_unverifiable_not_a_zero_count(
        counted: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    def broken(self: Path, pattern: str) -> list[Path]:
        raise ValueError("Invalid pattern")

    monkeypatch.setattr(Path, "glob", broken)
    (counted / "AGENTS.md").write_text("There are 43 suites in `supabase/tests/*.sql`.\n")
    assert scan_instruction_claims(counted, ["AGENTS.md"])["total"] == 0


@pytest.mark.parametrize("sentence", [
    # A path with no wildcard: a directory may hold files or subdirectories.
    "The 12 skills live in `skills/`.",
    # Two numbers: which one is the count is a guess.
    "Keep 5 of the 7 commands in `cmds/*.md`.",
    # Two patterns: which one the number counts is a guess.
    "There are 7 commands in `cmds/*.md` and `extra/*.md`.",
    # A version, a percentage or a number inside the backticks is not a count.
    "Node 20.11.0 builds `cmds/*.md`.",
    "Keep 80% coverage in `cmds/*.md`.",
    "Run `ls cmds/*.md | head -3` first.",
    # A pattern that leaves the repository is not counted.
    "There are 3 files in `../other/*.md`.",
    "There are 3 files in `/etc/*.conf`.",
    "There are 3 files in `C:\\logs\\*.txt`.",
    # Not path-shaped: code, placeholders, flags.
    "All 3 helpers take `**kwargs`.",
    "All 3 helpers take `*args`.",
    "Write `?` for 3 unless known.",
    "Pass `--only=*` to run 5 checks.",
    # A year is not a count.
    "Since 2024 every migration lives in `supabase/migrations/*.sql`.",
])
def test_count_claim_is_skipped_when_the_sentence_is_ambiguous(sentence: str) -> None:
    assert [c for c in extract_claims(sentence + "\n") if c.kind == "count"] == []


def test_count_claim_is_extracted_with_its_number_and_pattern() -> None:
    claims = extract_claims("# Agents\n\nThe plugin ships 5 commands in `cmds/*.md`.\n")
    assert [(c.kind, c.line, c.path, c.fields) for c in claims] == [
        ("count", 3, "cmds/*.md", {"claimed": 5})]

"""Tests for the non-interactive consent contract (Task 13).

The decider is an **explicit** signal the orchestrator passes in, never a
subprocess stdin probe: the core always runs under `uv run ...` from a Bash
tool with no controlling terminal, so `isatty()` is False even in a normal
interactive /assess. A run is interactive by default and non-interactive only
when marked so (the --non-interactive flag / ASSESS_NON_INTERACTIVE env var) or
when CI is set.
"""
from __future__ import annotations

from lib.interactivity import (
    NON_INTERACTIVE_ENV,
    OFFER_TYPES,
    build_offers_block,
    is_interactive,
    non_interactive_offers,
)


# ── detection ───────────────────────────────────────────────────────────────

def test_default_run_is_interactive() -> None:
    # No flag, no CI env: a normal /assess invocation is interactive.
    assert is_interactive(env={}) is True


def test_explicit_flag_forces_non_interactive() -> None:
    assert is_interactive(non_interactive=True, env={}) is False


def test_ci_env_forces_non_interactive() -> None:
    assert is_interactive(env={"CI": "true"}) is False


def test_assess_non_interactive_env_forces_non_interactive() -> None:
    assert is_interactive(env={NON_INTERACTIVE_ENV: "1"}) is False


def test_empty_ci_env_is_not_ci() -> None:
    assert is_interactive(env={"CI": ""}) is True


def test_empty_non_interactive_env_is_interactive() -> None:
    assert is_interactive(env={NON_INTERACTIVE_ENV: ""}) is True


def test_flag_wins_even_without_env() -> None:
    # The explicit flag alone is sufficient; no env var needed.
    assert is_interactive(non_interactive=True, env={"CI": ""}) is False


# ── offer recording ─────────────────────────────────────────────────────────

def test_non_interactive_offers_all_skipped() -> None:
    offers = non_interactive_offers()
    assert {o["type"] for o in offers} == set(OFFER_TYPES)
    assert all(o["status"] == "skipped" for o in offers)
    assert all(o["reason"] == "non-interactive" for o in offers)


def test_block_default_run_presents_offers() -> None:
    # A normal (no-flag, no-CI) run is interactive: offers stay empty for the
    # orchestrator to present live, NOT pre-recorded as skipped.
    block = build_offers_block(env={})
    assert block["interactive"] is True
    assert block["offers"] == []


def test_block_non_interactive_records_every_offer_skipped() -> None:
    block = build_offers_block(non_interactive=True, env={})
    assert block["interactive"] is False
    assert len(block["offers"]) == len(OFFER_TYPES)
    # Mutation (code modification) is recorded as skipped like every other offer.
    assert any(o["type"] == "mutation" and o["status"] == "skipped"
               for o in block["offers"])


def test_block_ci_env_records_every_offer_skipped() -> None:
    block = build_offers_block(env={"CI": "true"})
    assert block["interactive"] is False
    assert len(block["offers"]) == len(OFFER_TYPES)


def test_offer_types_cover_all_three_phases_plus_uninstall() -> None:
    assert "tool_install" in OFFER_TYPES      # Phase 1
    assert "mutation" in OFFER_TYPES          # Phase 3
    assert {"pr", "issue_tracking", "ci_gate", "feedback"} <= set(OFFER_TYPES)  # Phase 2
    assert "uninstall" in OFFER_TYPES         # end-of-run

"""Signal-consumption tests for the capability-driven JVM offer flow (#113).

The CI contract is *signal consumption*: given a tool's output (canned
``mvn dependency:analyze`` text), the deterministic core feeds the scorecard
correctly. The agent's runtime tool *choice* is human-judged and not tested
here. A synthetic Maven fixture under ``tests/fixtures/maven_project/`` stands in
for the real Helidon repo CI cannot reach.
"""
from __future__ import annotations

import json
from pathlib import Path

import pytest

from lib.jvm_capabilities import (
    count_used_undeclared,
    detect_build_system,
    detect_configured_plugins,
    parse_dependency_analyze,
    scan_jvm_capabilities,
)
from lib.liveness_scan import scan_liveness

FIXTURE = Path(__file__).parent / "fixtures" / "maven_project"


def _write(root: Path, rel: str, text: str = "x") -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _analyze_output() -> str:
    return (FIXTURE / "dependency-analyze-output.txt").read_text(encoding="utf-8")


# ── parsing dependency:analyze (the consumed signal) ───────────────────────

def test_parse_dependency_analyze_extracts_unused_declared() -> None:
    candidates = parse_dependency_analyze(_analyze_output(), pom_path="pom.xml")
    symbols = {c["symbol"] for c in candidates}
    assert symbols == {
        "org.apache.commons:commons-lang3",
        "com.google.guava:guava",
    }
    # Used-undeclared (slf4j) is NOT a liveness dead-weight candidate.
    assert "org.slf4j:slf4j-api" not in symbols
    for c in candidates:
        assert c["kind"] == "unused declared dependency"
        assert c["path"] == "pom.xml"


def test_used_undeclared_counted_but_not_a_candidate() -> None:
    assert count_used_undeclared(_analyze_output()) == 1


def test_parse_empty_output_is_no_candidates() -> None:
    assert parse_dependency_analyze("[INFO] BUILD SUCCESS\n") == []


def test_parse_stops_at_section_boundary() -> None:
    # An unused block followed by a non-coordinate line must not bleed into it.
    text = (
        "[WARNING] Unused declared dependencies found:\n"
        "[WARNING]    a.b:c:jar:1.0:compile\n"
        "[INFO] BUILD SUCCESS\n"
        "    d.e:f:jar:2.0:compile\n"  # outside the block - ignored
    )
    syms = {c["symbol"] for c in parse_dependency_analyze(text)}
    assert syms == {"a.b:c"}


# ── build-system detection ─────────────────────────────────────────────────

def test_detect_maven_in_fixture() -> None:
    system, files = detect_build_system(FIXTURE)
    assert system == "maven"
    assert "pom.xml" in files


def test_detect_gradle(tmp_path: Path) -> None:
    _write(tmp_path, "build.gradle", "plugins { id 'java' }")
    _write(tmp_path, "src/Main.java", "class Main {}")
    system, files = detect_build_system(tmp_path)
    assert system == "gradle"
    assert "build.gradle" in files


def test_maven_wins_over_gradle_when_both_present(tmp_path: Path) -> None:
    _write(tmp_path, "pom.xml", "<project/>")
    _write(tmp_path, "build.gradle", "plugins {}")
    _write(tmp_path, "src/main/java/A.java", "class A {}")
    system, _ = detect_build_system(tmp_path)
    assert system == "maven"


def test_detect_none_for_non_jvm(tmp_path: Path) -> None:
    _write(tmp_path, "main.py", "x = 1")
    system, files = detect_build_system(tmp_path)
    assert system is None
    assert files == []


def test_fixture_pom_excluded_when_under_tests_fixtures(tmp_path: Path) -> None:
    # A pom under tests/fixtures/ must not make a repo look like a Maven project
    # (the auto-exclude that keeps the assess run-context baseline stable).
    # JVM source outside the fixture meets the source threshold, so a null
    # result here can only come from the fixture exclusion.
    _write(tmp_path, "tests/fixtures/sample/pom.xml", "<project/>")
    _write(tmp_path, "src/main/java/A.java", "class A {}")
    system, _ = detect_build_system(tmp_path)
    assert system is None


def test_user_exclude_dir_prunes_build_file(tmp_path: Path) -> None:
    _write(tmp_path, "legacy/pom.xml", "<project/>")
    _write(tmp_path, "src/main/java/A.java", "class A {}")
    assert detect_build_system(tmp_path)[0] == "maven"
    assert detect_build_system(tmp_path, extra_exclude_dirs={"legacy"}) == (None, [])


def test_user_exclude_pattern_on_source_drops_threshold(tmp_path: Path) -> None:
    # A basename pattern applies to source files too: excluding the only JVM
    # source leaves the build file below the source threshold.
    _write(tmp_path, "pom.xml", "<project/>")
    _write(tmp_path, "src/main/java/Generated.java", "class Generated {}")
    assert detect_build_system(tmp_path)[0] == "maven"
    assert detect_build_system(
        tmp_path, extra_exclude_patterns=["Generated*.java"]) == (None, [])


def test_requires_jvm_source_groovy_counts(tmp_path: Path) -> None:
    # Grails apps, Jenkins plugins and Gradle plugin projects hold Groovy only.
    _write(tmp_path, "build.gradle", "plugins { id 'groovy' }")
    _write(tmp_path, "src/main/groovy/Plugin.groovy", "class Plugin {}")
    assert detect_build_system(tmp_path) == ("gradle", ["build.gradle"])


# ── JVM source threshold and platform wrappers ──────────────────────────────

def _flutter_app(root: Path, prefix: str = "") -> None:
    _write(root, f"{prefix}pubspec.yaml", "name: demo")
    _write(root, f"{prefix}lib/main.dart", "void main() {}")
    _write(root, f"{prefix}android/build.gradle.kts", "plugins {}")
    _write(root, f"{prefix}android/app/build.gradle.kts", "plugins {}")
    _write(root, f"{prefix}android/app/src/main/kotlin/MainActivity.kt",
           "class MainActivity")


def test_requires_jvm_source_pom_alone_is_not_maven(tmp_path: Path) -> None:
    _write(tmp_path, "pom.xml", "<project/>")
    assert detect_build_system(tmp_path) == (None, [])


def test_requires_jvm_source_one_file_meets_threshold(tmp_path: Path) -> None:
    _write(tmp_path, "build.gradle", "plugins {}")
    _write(tmp_path, "src/main/scala/App.scala", "object App")
    assert detect_build_system(tmp_path) == ("gradle", ["build.gradle"])


def test_requires_jvm_source_outside_wrapper_not_inside(tmp_path: Path) -> None:
    # A root build file does not make a JVM codebase when the only JVM source
    # sits inside the Flutter wrapper.
    _flutter_app(tmp_path)
    _write(tmp_path, "build.gradle", "plugins {}")
    assert detect_build_system(tmp_path) == (None, [])


def test_platform_wrapper_flutter_android_is_not_jvm(tmp_path: Path) -> None:
    _flutter_app(tmp_path)
    assert detect_build_system(tmp_path) == (None, [])
    assert scan_jvm_capabilities(tmp_path, mvn_on_path=False) == {
        "available": False, "build_system": None, "build_files": []}


def test_platform_wrapper_nested_flutter_app_is_not_jvm(tmp_path: Path) -> None:
    _flutter_app(tmp_path, "apps/shop/")
    assert detect_build_system(tmp_path) == (None, [])


@pytest.mark.parametrize("section, package", [
    ("dependencies", "react-native"),
    ("dependencies", "@capacitor/android"),
    ("devDependencies", "cordova-android"),
])
def test_platform_wrapper_package_json_android_is_not_jvm(
        tmp_path: Path, section: str, package: str) -> None:
    _write(tmp_path, "package.json", json.dumps({section: {package: "1.0.0"}}))
    _write(tmp_path, "android/build.gradle", "buildscript {}")
    _write(tmp_path, "android/app/src/main/java/MainActivity.java",
           "class MainActivity {}")
    assert detect_build_system(tmp_path) == (None, [])


def test_platform_wrapper_package_json_without_wrapper_dep_counts(
        tmp_path: Path) -> None:
    # A package.json that names no wrapper dependency leaves android/ counted.
    _write(tmp_path, "package.json", json.dumps({"dependencies": {"left-pad": "1"}}))
    _write(tmp_path, "android/build.gradle", "buildscript {}")
    _write(tmp_path, "android/app/src/main/java/MainActivity.java",
           "class MainActivity {}")
    assert detect_build_system(tmp_path) == ("gradle", ["android/build.gradle"])


def _cordova_app(root: Path, prefix: str = "", package: str | None = None,
                 config_xml: bool = True) -> None:
    # `cordova platform add android` layout: config.xml and package.json at the
    # app root, the generated Android project under platforms/android/.
    if config_xml:
        _write(root, f"{prefix}config.xml",
               '<widget xmlns:cdv="http://cordova.apache.org/ns/1.0"></widget>')
    deps = {"devDependencies": {package: "13.0.0"}} if package else {}
    _write(root, f"{prefix}package.json", json.dumps(deps))
    _write(root, f"{prefix}platforms/android/build.gradle", "buildscript {}")
    _write(root, f"{prefix}platforms/android/app/build.gradle", "apply plugin: 'x'")
    _write(root, f"{prefix}platforms/android/app/src/main/java/MainActivity.java",
           "class MainActivity {}")


@pytest.mark.parametrize("package", [None, "cordova-android"])
def test_platform_wrapper_cordova_platforms_android_is_not_jvm(
        tmp_path: Path, package: str | None) -> None:
    _cordova_app(tmp_path, package=package)
    assert detect_build_system(tmp_path) == (None, [])


def test_platform_wrapper_cordova_package_json_alone_is_not_jvm(
        tmp_path: Path) -> None:
    # No config.xml: the cordova-android package.json alone marks the root.
    _cordova_app(tmp_path, package="cordova-android", config_xml=False)
    assert detect_build_system(tmp_path) == (None, [])


@pytest.mark.parametrize("package", ["react-native", "@capacitor/android"])
def test_platform_wrapper_platforms_android_other_wrapper_package_counts(
        tmp_path: Path, package: str) -> None:
    # Only cordova-android marks platforms/android/; other wrapper packages
    # mark a sibling android/ and nothing else.
    _cordova_app(tmp_path, package=package, config_xml=False)
    assert detect_build_system(tmp_path)[0] == "gradle"


def test_platform_wrapper_nested_cordova_app_is_not_jvm(tmp_path: Path) -> None:
    _cordova_app(tmp_path, "apps/hybrid/")
    assert detect_build_system(tmp_path) == (None, [])


def test_platform_wrapper_platforms_android_without_cordova_counts(
        tmp_path: Path) -> None:
    # platforms/android/ with no Cordova marker beside platforms/ stays counted.
    _write(tmp_path, "platforms/android/build.gradle", "buildscript {}")
    _write(tmp_path, "platforms/android/src/main/java/A.java", "class A {}")
    assert detect_build_system(tmp_path) == (
        "gradle", ["platforms/android/build.gradle"])


def test_platform_wrapper_does_not_hide_backend_jvm_source(tmp_path: Path) -> None:
    _flutter_app(tmp_path, "mobile/")
    _write(tmp_path, "backend/build.gradle.kts", "plugins {}")
    _write(tmp_path, "backend/src/main/kotlin/demo/App.kt", "fun main() {}")
    result = scan_jvm_capabilities(tmp_path, mvn_on_path=False)
    assert result["build_system"] == "gradle"
    assert result["build_files"] == ["backend/build.gradle.kts"]
    assert {k: v["state"] for k, v in result["capabilities"].items()} == {
        c: "honest_degrade" for c in
        ("liveness", "module_graph", "linting", "modernization")}


def test_platform_wrapper_scan_liveness_has_no_java_tool(tmp_path: Path) -> None:
    _flutter_app(tmp_path)
    result = scan_liveness(tmp_path, run_dead_code=False)
    assert "jvm_capabilities" not in result
    assert not [t for t in result["dead_code"]["tools"]
                if t.get("language") == "java"]


# ── plugin crediting ───────────────────────────────────────────────────────

def test_configured_checkstyle_is_credited() -> None:
    served = detect_configured_plugins(FIXTURE, ["pom.xml"])
    assert served.get("linting") == ["Checkstyle"]
    # Nothing configures modernization in the fixture.
    assert "modernization" not in served


def test_error_prone_compiler_arg_credits_linting(tmp_path: Path) -> None:
    _write(tmp_path, "pom.xml",
           "<project><build><plugins><plugin>"
           "<artifactId>maven-compiler-plugin</artifactId>"
           "<configuration><annotationProcessorPaths><path>"
           "<artifactId>error_prone_core</artifactId></path>"
           "</annotationProcessorPaths></configuration>"
           "</plugin></plugins></build></project>")
    served = detect_configured_plugins(tmp_path, ["pom.xml"])
    assert served.get("linting") == ["error-prone"]


# ── capability scan: states ────────────────────────────────────────────────

def test_maven_liveness_offers_run_consent_when_mvn_present() -> None:
    result = scan_jvm_capabilities(FIXTURE, mvn_on_path=True)
    liveness = result["capabilities"]["liveness"]
    assert liveness["state"] == "offer"
    assert liveness["consent"] == "run"
    assert liveness["candidate_tool"] == "mvn dependency:analyze"


def test_maven_liveness_offers_install_consent_when_mvn_absent() -> None:
    result = scan_jvm_capabilities(FIXTURE, mvn_on_path=False)
    liveness = result["capabilities"]["liveness"]
    assert liveness["state"] == "offer"
    assert liveness["consent"] == "install"


def test_served_liveness_feeds_candidates() -> None:
    result = scan_jvm_capabilities(
        FIXTURE, mvn_on_path=True, analyze_output=_analyze_output())
    liveness = result["capabilities"]["liveness"]
    assert liveness["state"] == "served"
    assert liveness["candidate_count"] == 2
    assert liveness["used_undeclared_count"] == 1


def test_linting_credited_module_graph_and_modernization_degrade() -> None:
    result = scan_jvm_capabilities(FIXTURE, mvn_on_path=True)
    caps = result["capabilities"]
    assert caps["linting"]["state"] == "credited"
    assert caps["linting"]["served_by"] == ["Checkstyle"]
    # Honest-degrade is a deliverable: state set AND a candidate tool named.
    assert caps["module_graph"]["state"] == "honest_degrade"
    assert caps["module_graph"]["candidate_tool"] == "jdeps"
    assert caps["modernization"]["state"] == "honest_degrade"
    assert caps["modernization"]["candidate_tool"] == "OpenRewrite"


def test_every_capability_names_a_candidate_tool() -> None:
    # No capability may be silently absent - each carries a candidate.
    caps = scan_jvm_capabilities(FIXTURE, mvn_on_path=True)["capabilities"]
    for name, cap in caps.items():
        assert cap.get("candidate_tool"), f"{name} has no candidate tool"
        assert cap.get("gloss"), f"{name} has no gloss"


def test_gradle_honest_degrades_liveness(tmp_path: Path) -> None:
    _write(tmp_path, "build.gradle", "plugins { id 'java' }")
    _write(tmp_path, "src/Main.java", "class Main {}")
    result = scan_jvm_capabilities(tmp_path, mvn_on_path=True)
    assert result["build_system"] == "gradle"
    liveness = result["capabilities"]["liveness"]
    assert liveness["state"] == "honest_degrade"
    assert liveness["candidate_tool"] == "mvn dependency:analyze"


def test_non_jvm_repo_reports_unavailable(tmp_path: Path) -> None:
    _write(tmp_path, "main.py", "x = 1")
    result = scan_jvm_capabilities(tmp_path)
    assert result == {"available": False, "build_system": None, "build_files": []}


# ── integration: scan_liveness merges JVM signal ───────────────────────────

def test_scan_liveness_attaches_jvm_block_and_offer_tool() -> None:
    result = scan_liveness(FIXTURE, run_dead_code=False)
    assert "jvm_capabilities" in result
    java_tools = [t for t in result["dead_code"]["tools"]
                  if t.get("language") == "java"]
    assert len(java_tools) == 1
    assert java_tools[0]["status"] == "available_not_run"
    assert java_tools[0]["consent"] in {"run", "install"}


def test_scan_liveness_served_merges_candidates_into_dead_code(monkeypatch) -> None:
    # Drive the served path by stubbing the analyze run so dead_code carries the
    # Maven candidates the runtime block (static_reachability) consumes.
    import lib.jvm_capabilities as jc

    monkeypatch.setattr(jc, "_run_dependency_analyze",
                        lambda root: _analyze_output())
    monkeypatch.setattr(jc.shutil, "which", lambda _: "/usr/bin/mvn")
    result = scan_liveness(FIXTURE, run_dead_code=False, run_build_tools=True)
    dc = result["dead_code"]
    java_candidates = [c for c in dc["candidates"]
                       if c["kind"] == "unused declared dependency"]
    assert len(java_candidates) == 2
    assert dc["available"] is True


def test_non_jvm_scan_liveness_has_no_jvm_key(tmp_path: Path) -> None:
    _write(tmp_path, "main.py", "x = 1")
    result = scan_liveness(tmp_path, run_dead_code=False)
    assert "jvm_capabilities" not in result

"""Unit tests for the deterministic keyhole-signal integration helpers.

These cover the *derivation* logic that turns the five lib modules' outputs
into the run-context blocks and the six named derived findings - the pure,
git-free core of task #5. End-to-end wiring (build_run_context) is covered in
test_assess_core.py.
"""
from __future__ import annotations

from pathlib import Path

from lib import keyhole_signals as ks


# --- containment_by_dir ------------------------------------------------------

def test_containment_by_dir_flags_island_and_bleeder() -> None:
    """A directory whose commits stay inside it scores high; one whose commits
    keep dragging in outside files scores low."""
    commit_sets = [
        # island/ changes alone, repeatedly (self-contained)
        {Path("island/a.py")},
        {Path("island/a.py"), Path("island/b.py")},
        {Path("island/b.py")},
        {Path("island/a.py")},
        {Path("island/c.py")},
        # bleeder/ always drags in core/
        {Path("bleeder/x.py"), Path("core/util.py")},
        {Path("bleeder/y.py"), Path("core/util.py")},
        {Path("bleeder/x.py"), Path("core/other.py")},
        {Path("bleeder/z.py"), Path("core/util.py")},
        {Path("bleeder/x.py"), Path("shared/s.py")},
    ]
    cont = ks.containment_by_dir(Path("/nonexistent"), commit_sets, min_commits=5)
    assert cont["island"] == 1.0
    assert cont["bleeder"] == 0.0
    # The repo root "." is never a candidate directory (vacuously contained).
    assert "." not in cont


def test_containment_by_dir_respects_min_commits() -> None:
    """Directories touched fewer than min_commits times are omitted."""
    commit_sets = [{Path("rare/a.py")}, {Path("rare/a.py")}]
    cont = ks.containment_by_dir(Path("/nonexistent"), commit_sets, min_commits=5)
    assert cont == {}


# --- static-modularity projection -------------------------------------------

def test_project_static_modularity_repo_level_onto_dirs() -> None:
    structure = {"available": True, "modularity_q": 0.5, "front_door_ratio": 0.9}
    proj = ks.project_static_modularity(structure, ["a", "b"])
    assert proj == {
        "a": {"modularity_q": 0.5, "front_door_ratio": 0.9},
        "b": {"modularity_q": 0.5, "front_door_ratio": 0.9},
    }


def test_project_static_modularity_none_when_unavailable() -> None:
    assert ks.project_static_modularity({"available": False}, ["a"]) is None
    assert ks.project_static_modularity(None, ["a"]) is None


# --- behaviour block ---------------------------------------------------------

def test_behaviour_block_hidden_coupling_when_modular_but_bleeds() -> None:
    """A bleeding dir that looks modular statically becomes hidden_coupling."""
    commit_sets = [
        {Path("looksmodular/x.py"), Path("core/util.py")},
        {Path("looksmodular/y.py"), Path("core/util.py")},
        {Path("looksmodular/x.py"), Path("core/other.py")},
        {Path("looksmodular/z.py"), Path("core/util.py")},
        {Path("looksmodular/x.py"), Path("shared/s.py")},
    ]
    structure = {"available": True, "modularity_q": 0.6, "front_door_ratio": 0.95}
    block = ks.build_behaviour_block(Path("/nonexistent"), commit_sets, structure)
    assert block["available"] is True
    hc_paths = [h["path"] for h in block["hidden_coupling_findings"]]
    assert "looksmodular" in hc_paths
    # B1 change-coupling pairs are wired in (a list; exact contents depend on
    # min_support, exercised in test_change_coupling.py).
    assert isinstance(block["change_coupling_pairs"], list)


def test_behaviour_block_bleeding_module_without_static_graph() -> None:
    """No static graph -> a bleeding dir degrades to bleeding_module."""
    commit_sets = [
        {Path("bleeder/x.py"), Path("core/util.py")},
        {Path("bleeder/y.py"), Path("core/util.py")},
        {Path("bleeder/x.py"), Path("core/other.py")},
        {Path("bleeder/z.py"), Path("core/util.py")},
        {Path("bleeder/x.py"), Path("shared/s.py")},
    ]
    block = ks.build_behaviour_block(
        Path("/nonexistent"), commit_sets, {"available": False}
    )
    findings = {f["finding"] for f in block["static_history_disagreement"]}
    assert "bleeding_module" in findings
    assert block["hidden_coupling_findings"] == []


def test_behaviour_block_non_python_dir_never_hidden_coupling() -> None:
    """The static import graph is silent on doc/config trees, so a bleeding
    non-Python dir degrades to bleeding_module, never a false hidden_coupling -
    even when a Python static graph is available."""
    commit_sets = [
        {Path("docs/a.md"), Path("core/util.py")},
        {Path("docs/b.md"), Path("core/util.py")},
        {Path("docs/a.md"), Path("core/other.py")},
        {Path("docs/c.md"), Path("core/util.py")},
        {Path("docs/a.md"), Path("src/s.py")},
    ]
    structure = {"available": True, "modularity_q": 0.6, "front_door_ratio": 0.95}
    block = ks.build_behaviour_block(Path("/nonexistent"), commit_sets, structure)
    hc_paths = [h["path"] for h in block["hidden_coupling_findings"]]
    assert "docs" not in hc_paths
    findings = {f["path"]: f["finding"] for f in block["static_history_disagreement"]}
    assert findings.get("docs") == "bleeding_module"


def test_behaviour_block_refactor_boundary_is_positive() -> None:
    commit_sets = [
        {Path("island/a.py")},
        {Path("island/b.py")},
        {Path("island/a.py")},
        {Path("island/c.py")},
        {Path("island/b.py")},
    ]
    block = ks.build_behaviour_block(Path("/nonexistent"), commit_sets, None)
    assert any(b["path"] == "island" for b in block["refactor_boundaries"])


# --- documentation block -----------------------------------------------------

def test_documentation_block_maps_doc_join() -> None:
    doc_join = {
        "available": True,
        "high_ccn_threshold": 10.0,
        "docs": [
            {"path": "docs/api.md", "complexity_summarised": 20.0, "freshness": -1.0,
             "doc_value": -20.0, "finding": "lying_map", "confidence": "high",
             "subject_code_count": 2, "recommendation": "fix or delete"},
            {"path": "src/hot.py", "complexity_summarised": 25.0, "freshness": 0.0,
             "doc_value": 0.0, "finding": "unexplained_complexity", "confidence": None,
             "subject_code_count": 0, "recommendation": "write contract"},
        ],
        "findings": {
            "lying_maps": [{"path": "docs/api.md"}],
            "unexplained_complexity": [{"path": "src/hot.py"}],
            "good_contracts": [],
        },
    }
    block = ks.build_documentation_block(doc_join)
    assert block["available"] is True
    assert block["freshness_by_doc"] == {"docs/api.md": -1.0}
    assert "docs/api.md" in block["complexity_coverage"]
    assert "src/hot.py" not in block["freshness_by_doc"]  # not a real doc
    assert [d["path"] for d in block["stale_doc_on_complexity"]] == ["docs/api.md"]
    assert [d["path"] for d in block["unexplained_complexity"]] == ["src/hot.py"]


def test_documentation_block_unavailable_passthrough() -> None:
    block = ks.build_documentation_block({"available": False})
    assert block["available"] is False


# --- understanding block -----------------------------------------------------

def test_understanding_block_maps_understanding() -> None:
    understanding = {
        "available": True,
        "high_ccn_threshold": 10.0,
        "modules": [
            {"path": "a.py", "human_anchor": True, "intent_source": False,
             "authorship_class": "human", "days_since_comprehension_event": 3,
             "finding": None, "recommendation": None},
            {"path": "b.py", "human_anchor": False, "intent_source": False,
             "authorship_class": "agent", "days_since_comprehension_event": None,
             "finding": "orphaned_understanding", "recommendation": "anchor"},
        ],
        "orphaned_understanding": ["b.py"],
    }
    block = ks.build_understanding_block(understanding)
    assert block["human_anchor_by_path"] == {"a.py": True, "b.py": False}
    assert block["intent_source_by_path"] == {"a.py": False, "b.py": False}
    assert block["authorship_class_by_path"] == {"a.py": "human", "b.py": "agent"}
    assert block["orphaned_understanding"] == ["b.py"]


# --- runtime block -----------------------------------------------------------

def test_runtime_block_carries_static_reachability() -> None:
    dead_code = {
        "available": True, "candidate_count": 1,
        "candidates": [{"path": "dead.py", "symbol": "f", "line": 1, "kind": "unused"}],
        "tools": [{"tool": "vulture", "status": "ran"}],
        "caveat": "static only",
    }
    observability = {"rung": 1, "reachable": {"present": False, "signals": []}}
    block = ks.build_runtime_block(dead_code, observability)
    assert block["static_reachability"]["candidate_count"] == 1
    assert block["static_reachability"]["candidates"][0]["path"] == "dead.py"
    assert block["observability_rung"] == 1
    assert block["runtime_evidence_available"] is False


# --- derived findings --------------------------------------------------------

def test_assemble_findings_fixed_order_and_actions() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": ["dir/a"],
        "lying_map": ["docs/x.md"],
        "unexplained_complexity": ["src/c.py"],
        "orphaned_understanding": ["src/o.py"],
        "candidate_dead_weight": ["src/d.py"],
        "refactor_boundary": ["island"],
    })
    names = [f["name"] for f in findings]
    assert names == ks.FINDING_ORDER
    for f in findings:
        assert set(f) == {"name", "paths", "action"}
        assert isinstance(f["paths"], list)
        assert f["action"] == ks.FINDING_ACTIONS[f["name"]]
    # spot-check the exact action strings the task contract requires
    by_name = {f["name"]: f for f in findings}
    assert by_name["hidden_coupling"]["action"] == "investigate the seam"
    assert by_name["unexplained_complexity"]["action"] == (
        "write the missing contract (do NOT auto-generate)"
    )
    assert by_name["refactor_boundary"]["action"] == "safe to hand an agent in isolation"


def test_assemble_findings_dedupes_and_sorts_paths() -> None:
    findings = ks.assemble_findings({"lying_map": ["b.md", "a.md", "b.md"]})
    lying = next(f for f in findings if f["name"] == "lying_map")
    assert lying["paths"] == ["a.md", "b.md"]


def test_candidate_dead_weight_requires_positive_dead_code_evidence() -> None:
    """Bias-to-keep: a high-complexity path is dead weight ONLY when static
    reachability positively flags it AND no intent source explains it."""
    complexity_stats = {
        "ccn": {"p95": 8.0},
        "top_complex": [
            {"path": "dead.py", "ccn": 30},
            {"path": "documented.py", "ccn": 30},
            {"path": "alive.py", "ccn": 30},
        ],
    }
    dead_code = {"candidates": [
        {"path": "dead.py", "symbol": "f"},
        {"path": "documented.py", "symbol": "g"},
    ]}
    intent_source_by_path = {"documented.py": True}
    paths = ks.candidate_dead_weight_paths(
        complexity_stats, dead_code, intent_source_by_path
    )
    assert paths == ["dead.py"]  # documented.py has intent; alive.py not flagged


def test_candidate_dead_weight_empty_without_dead_code() -> None:
    """No static-reachability evidence -> no dead-weight finding (keep bias)."""
    complexity_stats = {"ccn": {"p95": 8.0}, "top_complex": [{"path": "x.py", "ccn": 30}]}
    assert ks.candidate_dead_weight_paths(complexity_stats, {"candidates": []}, {}) == []


# --- attention list ----------------------------------------------------------

def test_attention_list_ranks_by_cross_axis_count() -> None:
    findings = [
        {"name": "hidden_coupling", "paths": ["worst"], "action": "x"},
        {"name": "lying_map", "paths": ["worst"], "action": "x"},
        {"name": "unexplained_complexity", "paths": ["worst", "single"], "action": "x"},
        {"name": "refactor_boundary", "paths": ["safe"], "action": "x"},
    ]
    attention = ks.build_attention_list(findings)
    assert attention[0]["path"] == "worst"
    assert attention[0]["score"] == 3
    # the positive refactor_boundary is never an attention (worst-across-axes) row
    assert all(a["path"] != "safe" for a in attention)
    paths = [a["path"] for a in attention]
    assert "single" in paths


def test_attention_tie_break_orders_hotspot_rank_then_severity_then_path() -> None:
    """Five score-1 rows: top_hotspots members lead in hotspot rank order (here
    the reverse of path order), then descending marker severity, then path."""
    findings = ks.assemble_findings({
        "unactioned_intent": [
            "src/zeta.py", "src/mid.py", "src/beta.py", "src/gamma.py", "src/alpha.py",
        ],
    })
    tie_break = ks.attention_tie_break(
        {"top_hotspots": [{"path": "src/zeta.py"}, {"path": "src/mid.py"}]},
        {"top_offenders": [
            {"path": "src/alpha.py", "severity": 6.0},
            {"path": "src/beta.py", "severity": 11.0},
            {"path": "src/gamma.py", "severity": 3.0},
            {"path": "src/gamma.py", "severity": 9.0},  # the file's highest counts
        ]},
        {},
    )
    attention = ks.build_attention_list(findings, tie_break=tie_break)
    assert [(u["path"], u["score"]) for u in attention] == [
        ("src/zeta.py", 1), ("src/mid.py", 1),
        ("src/beta.py", 1), ("src/gamma.py", 1), ("src/alpha.py", 1),
    ]


def test_attention_tie_break_never_outranks_score() -> None:
    """The tie-break only orders equal scores: a score-2 row still leads."""
    findings = ks.assemble_findings({
        "unactioned_intent": ["hot.py", "cold.py"],
        "lying_map": ["cold.py"],
    })
    tie_break = ks.attention_tie_break({"top_hotspots": [{"path": "hot.py"}]}, None, {})
    ranked = [u["path"] for u in ks.build_attention_list(findings, tie_break=tie_break)]
    assert ranked == ["cold.py", "hot.py"]


def test_attention_tie_break_hidden_coupling_lower_containment_first() -> None:
    """Hidden-coupling severity is 1 - containment_ratio: the directory whose
    commits bleed out most leads; a drift-only directory falls back to
    containment_by_dir, and equal severity falls through to path."""
    findings = ks.assemble_findings({"hidden_coupling": ["a", "b", "c", "d"]})
    tie_break = ks.attention_tie_break(
        {"top_hotspots": []},
        None,
        {
            "hidden_coupling_findings": [
                {"path": "a", "containment_ratio": 0.4},
                {"path": "b", "containment_ratio": 0.1},
                {"path": "c", "containment_ratio": 0.4},
            ],
            "containment_by_dir": {"d": 0.0},
        },
    )
    ranked = [u["path"] for u in ks.build_attention_list(findings, tie_break=tie_break)]
    assert ranked == ["d", "b", "a", "c"]


def test_attention_tie_break_mixed_marker_and_coupling_rows_share_one_scale() -> None:
    """Marker severity (at least 5 for a stale marker) and coupling severity
    (0-1) meet in one sort. On a shared 0-1 scale a fully bleeding seam ranks
    with the worst marker file instead of below every marker file, and at the
    attention cap coupling rows are not all evicted by marker rows."""
    markers = [f"m{i}.py" for i in range(10)]
    findings = ks.assemble_findings({
        "unactioned_intent": markers,
        "hidden_coupling": ["bleeds", "tight"],
    })
    tie_break = ks.attention_tie_break(
        {"top_hotspots": []},
        {"top_offenders": [
            {"path": p, "severity": 50.0 - i} for i, p in enumerate(markers)
        ]},
        {"hidden_coupling_findings": [
            {"path": "bleeds", "containment_ratio": 0.0},
            {"path": "tight", "containment_ratio": 0.9},
        ]},
    )
    ranked = [u["path"] for u in ks.build_attention_list(findings, tie_break=tie_break)]
    assert ranked[:2] == ["bleeds", "m0.py"]  # both 1.0; path breaks the tie
    assert len(ranked) == ks.MAX_ATTENTION_UNITS
    assert "bleeds" in ranked and "tight" not in ranked  # 0.1 sits below m8.py (0.84)


def test_attention_tie_break_absent_falls_back_to_path() -> None:
    findings = ks.assemble_findings({"unactioned_intent": ["b.py", "a.py"]})
    assert [u["path"] for u in ks.build_attention_list(findings)] == ["a.py", "b.py"]


def test_integrate_attention_tie_break_uses_top_hotspots(tmp_path: Path) -> None:
    """integrate threads top_hotspots and marker severity into the ranking."""
    pm = {
        "available": True, "aging_reliable": True,
        "stale_by_file": {"a.py": {}, "b.py": {}, "c.py": {}},
        "top_offenders": [
            {"path": "a.py", "severity": 1.0}, {"path": "b.py", "severity": 5.0},
        ],
    }
    out = ks.integrate(
        repo_root=tmp_path,
        complexity_stats={"top_hotspots": [{"path": "c.py"}]},
        doc_staleness={}, dead_code={}, observability={}, structure={},
        promissory_markers=pm,
    )
    assert [u["path"] for u in out["attention"]] == ["c.py", "b.py", "a.py"]


# --- Task 2: render_findings_markdown ----------------------------------------

def _sample_findings() -> list[dict]:
    """Two findings with paths + the positive boundary, the rest empty."""
    return ks.assemble_findings({
        "hidden_coupling": ["dir/a"],
        "lying_map": ["docs/x.md", "docs/y.md"],
        "refactor_boundary": ["island"],
    })


def test_render_findings_markdown_includes_paths_and_actions() -> None:
    findings = _sample_findings()
    attention = ks.build_attention_list(findings)
    md = ks.render_findings_markdown(findings, attention)
    assert md.startswith("## Cross-Layer Findings (Keyhole Readiness)")
    # Only findings with paths render a heading.
    assert "### hidden_coupling" in md
    assert "### lying_map" in md
    assert "### refactor_boundary" in md
    # The deterministic action text appears verbatim.
    assert f"Action: {ks.FINDING_ACTIONS['hidden_coupling']}" in md
    # Every path is listed.
    assert "- docs/x.md" in md
    assert "- docs/y.md" in md
    # Empty findings produce no heading.
    assert "### unexplained_complexity" not in md
    assert md.endswith("\n")


def test_render_findings_markdown_empty_is_minimal_but_valid() -> None:
    findings = ks.assemble_findings({})  # all six/eight empty
    md = ks.render_findings_markdown(findings, [])
    assert md.startswith("## Cross-Layer Findings (Keyhole Readiness)")
    assert "No cross-layer findings surfaced" in md
    # No finding headings when nothing has paths.
    assert "###" not in md


def test_render_findings_markdown_caps_paths_at_ten() -> None:
    findings = ks.assemble_findings({
        "lying_map": [f"docs/{i}.md" for i in range(20)],
    })
    md = ks.render_findings_markdown(findings, [])
    listed = [ln for ln in md.splitlines() if ln.startswith("- docs/")]
    assert len(listed) == ks.MAX_FINDING_PATHS_RENDERED


def test_render_findings_markdown_attention_section_caps_at_five() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": [f"u{i}" for i in range(8)],
        "lying_map": [f"u{i}" for i in range(8)],  # each unit scores 2
    })
    attention = ks.build_attention_list(findings)
    md = ks.render_findings_markdown(findings, attention)
    assert "### Attention List (Priority Order)" in md
    # Attention rows carry the "(score N)" marker; finding path bullets do not.
    rows = [ln for ln in md.splitlines() if ln.startswith("- u") and "(score" in ln]
    assert len(rows) == ks.MAX_ATTENTION_ROWS_RENDERED


# --- Issue #172: degenerate churn drops churn-derived findings ----------------

# A bleeding-but-statically-modular dir -> hidden_coupling; reused below.
_BLEEDING_COMMIT_SETS = [
    {Path("looksmodular/x.py"), Path("core/util.py")},
    {Path("looksmodular/y.py"), Path("core/util.py")},
    {Path("looksmodular/x.py"), Path("core/other.py")},
    {Path("looksmodular/z.py"), Path("core/util.py")},
    {Path("looksmodular/x.py"), Path("shared/s.py")},
]
_MODULAR_STRUCTURE = {
    "available": True, "modularity_q": 0.6, "front_door_ratio": 0.95,
}
# A complex code file under a doc dir, so a stale high-confidence doc -> lying_map.
_COMPLEXITY_STATS = {
    "ccn": {"p50": 3.0, "p95": 8.0, "max": 30.0},
    "files_scored": 1,
    "top_complex": [{"path": "pkg/core.py", "loc": 400, "ccn": 30.0}],
    "top_hotspots": [],
    "top_large": [],
}


def _stale_doc_staleness(*, churn_degenerate: bool) -> dict:
    """A high-confidence stale doc over pkg/core.py - a lying_map when the churn
    history is real, suppressed when it is degenerate."""
    return {
        "available": True,
        "churn_window": "commits (last 12mo)",
        "churn_degenerate": churn_degenerate,
        "docs": [{
            "path": "pkg/README.md",
            "ratio": 6.0,
            "last_commit_days": 10,
            "doc_churn_in_window": 1,
            "code_churn_in_window": 6,
            "subject_code_count": 1,
            "subject_method": "nearest-ancestor",
            "confidence": "high",
        }],
    }


def _integrate(*, churn_degenerate: bool) -> dict:
    return ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=churn_degenerate),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
    )


def _finding_paths(result: dict, name: str) -> list[str]:
    return next(f["paths"] for f in result["derived_findings"] if f["name"] == name)


def test_real_churn_produces_churn_derived_findings() -> None:
    """Baseline: with real churn (not degenerate), the lying_map and
    hidden_coupling findings fire and are counted in the keyhole summary."""
    result = _integrate(churn_degenerate=False)
    assert _finding_paths(result, "lying_map") == ["pkg/README.md"]
    assert _finding_paths(result, "hidden_coupling") == ["looksmodular"]
    counted = {c["name"] for c in result["keyhole_summary"]["concerns"]}
    assert {"lying_map", "hidden_coupling"} <= counted


def test_degenerate_churn_drops_churn_derived_findings_from_summary() -> None:
    """Issue #172: on a degenerate churn history the same inputs yield zero
    churn-derived findings - lying_map (confidence capped in the join) and
    hidden_coupling (dropped here) are absent from derived_findings AND the
    keyhole_summary, so a reader sees 0 lying maps from a meaningless signal."""
    result = _integrate(churn_degenerate=True)
    assert _finding_paths(result, "lying_map") == []
    assert _finding_paths(result, "hidden_coupling") == []
    counted = {c["name"] for c in result["keyhole_summary"]["concerns"]}
    assert "lying_map" not in counted
    assert "hidden_coupling" not in counted


# --- Task 3: build_keyhole_summary -------------------------------------------

def test_build_keyhole_summary_counts_concerns_and_safe_zones() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": ["a", "b"],
        "lying_map": ["c"],
        "refactor_boundary": ["s1", "s2", "s3"],
    })
    summary = ks.build_keyhole_summary(findings)
    assert summary["safe_zones"] == 3
    assert summary["total_concerns"] == 3
    by_name = {c["name"]: c["count"] for c in summary["concerns"]}
    assert by_name == {"hidden_coupling": 2, "lying_map": 1}
    # The summary text is a pure count, parallel to the 0-8 score - never a score.
    assert summary["summary_text"] == (
        "3 structural concerns (2 hidden coupling, 1 lying map), 3 safe zones."
    )


def test_build_keyhole_summary_empty_findings_neutral_message() -> None:
    summary = ks.build_keyhole_summary(ks.assemble_findings({}))
    assert summary["concerns"] == []
    assert summary["total_concerns"] == 0
    assert summary["safe_zones"] == 0
    assert summary["summary_text"] == "No structural concerns, 0 safe zones."


def test_build_keyhole_summary_singular_plural() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": ["a"],
        "refactor_boundary": ["s1"],
    })
    summary = ks.build_keyhole_summary(findings)
    assert summary["summary_text"] == (
        "1 structural concern (1 hidden coupling), 1 safe zone."
    )


def test_build_keyhole_summary_no_concerns_with_safe_zones() -> None:
    findings = ks.assemble_findings({"refactor_boundary": ["s1", "s2"]})
    summary = ks.build_keyhole_summary(findings)
    assert summary["summary_text"] == "No structural concerns, 2 safe zones."


def test_build_keyhole_summary_hyphenates_self_referential_tests() -> None:
    """Compound-adjective finding names get an explicit display name
    ('self-referential tests'), not a naive underscore->space replace."""
    findings = ks.assemble_findings({"self_referential_tests": ["a", "b"]})
    summary = ks.build_keyhole_summary(findings)
    assert summary["summary_text"] == (
        "2 structural concerns (2 self-referential tests), 0 safe zones."
    )


def test_finding_display_name_map_with_space_fallback() -> None:
    """Mapped names use the display-name override; unmapped names fall back to
    the plain underscore->space replace."""
    assert ks.finding_display_name("self_referential_tests") == "self-referential tests"
    assert ks.finding_display_name("hidden_coupling") == "hidden coupling"
    assert ks.finding_display_name("some_future_finding") == "some future finding"


# --- Task 4: build_prescribed_actions / render_prescribed_actions ------------

def test_build_prescribed_actions_picks_worst_finding_per_unit() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": ["worst"],
        "lying_map": ["worst", "mid"],
        "unexplained_complexity": ["worst", "mid"],
    })
    attention = ks.build_attention_list(findings)
    prescribed = ks.build_prescribed_actions(attention, findings)
    # 'worst' lands in 3 findings (score 3) -> ranks first.
    assert prescribed[0]["path"] == "worst"
    assert prescribed[0]["rank"] == 1
    # 'worst' spans hidden_coupling + lying_map + unexplained; hidden_coupling
    # is highest severity (earliest in FINDING_ORDER).
    assert prescribed[0]["action"] == ks.FINDING_ACTIONS["hidden_coupling"]
    # 'mid' lands in lying_map + unexplained_complexity; lying_map is worse.
    mid = next(p for p in prescribed if p["path"] == "mid")
    assert mid["action"] == ks.FINDING_ACTIONS["lying_map"]


def test_build_prescribed_actions_caps_at_three() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": [f"u{i}" for i in range(5)],
        "lying_map": [f"u{i}" for i in range(5)],
    })
    attention = ks.build_attention_list(findings)
    prescribed = ks.build_prescribed_actions(attention, findings)
    assert len(prescribed) == 3
    assert [p["rank"] for p in prescribed] == [1, 2, 3]


def test_build_prescribed_actions_empty_attention() -> None:
    assert ks.build_prescribed_actions([], ks.assemble_findings({})) == []


def test_attention_low_signal_when_top_score_is_one() -> None:
    """Every row in one finding only: the ranking is weak, so it is flagged."""
    findings = ks.assemble_findings({"lying_map": [f"u{i}" for i in range(5)]})
    attention = ks.build_attention_list(findings)
    assert ks.is_attention_low_signal(attention) is True


def test_attention_low_signal_false_when_any_row_scores_two() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": ["worst"],
        "lying_map": ["worst", "u1", "u2", "u3"],
    })
    assert ks.is_attention_low_signal(ks.build_attention_list(findings)) is False


def test_attention_low_signal_false_on_empty_attention() -> None:
    """No rows means nothing to cap: the flag stays false."""
    assert ks.is_attention_low_signal([]) is False


def test_integrate_attention_low_signal_caps_prescribed_at_one(tmp_path: Path) -> None:
    """Five score-1 rows: flag true, one prescribed action (rank 1), attention intact."""
    pm = {
        "available": True, "aging_reliable": True,
        "stale_by_file": {f"u{i}.py": {} for i in range(5)},
        "top_offenders": [],
    }
    out = ks.integrate(
        repo_root=tmp_path, complexity_stats={"top_hotspots": [{"path": "u3.py"}]},
        doc_staleness={}, dead_code={}, observability={}, structure={},
        promissory_markers=pm,
    )
    assert out["attention_low_signal"] is True
    assert len(out["attention"]) == 5
    assert [(p["path"], p["rank"]) for p in out["prescribed_actions"]] == [("u3.py", 1)]


def test_build_prescribed_actions_attention_low_signal_false_keeps_three() -> None:
    """One score-2 row: flag false, prescribed_actions built as before (three)."""
    findings = ks.assemble_findings({
        "hidden_coupling": ["u0.py"],
        "unactioned_intent": [f"u{i}.py" for i in range(5)],
    })
    attention = ks.build_attention_list(findings)
    assert ks.is_attention_low_signal(attention) is False
    assert len(ks.build_prescribed_actions(attention, findings)) == 3


def test_render_prescribed_actions_rows_and_empty() -> None:
    findings = ks.assemble_findings({
        "hidden_coupling": ["worst"],
        "lying_map": ["worst"],
    })
    attention = ks.build_attention_list(findings)
    prescribed = ks.build_prescribed_actions(attention, findings)
    rows = ks.render_prescribed_actions(prescribed)
    # Seven-column table row matching the SKILL.md Top 3 Actions template.
    assert rows.startswith("| 1 |")
    assert rows.count("|") == 8  # 7 columns => 8 pipes
    assert "`worst`" in rows
    assert ks.render_prescribed_actions([]) == ""


# --- Task 5 E1: find_untrusted_hotspots --------------------------------------

def test_find_untrusted_hotspots_flags_high_survivor_density() -> None:
    complexity_stats = {"top_hotspots": [
        {"path": "src/hot.py"}, {"path": "src/cold.py"},
    ]}
    test_pressure = {"per_file": [
        {"file": "src/hot.py", "survived": 4, "total": 10},   # 0.4 >= 0.3
        {"file": "src/cold.py", "survived": 1, "total": 10},  # 0.1 < 0.3
    ]}
    assert ks.find_untrusted_hotspots(complexity_stats, test_pressure) == ["src/hot.py"]


def test_find_untrusted_hotspots_silent_without_mutation_data() -> None:
    complexity_stats = {"top_hotspots": [{"path": "src/hot.py"}]}
    # No per_file -> no mutation evidence -> nothing flagged (read-only default).
    assert ks.find_untrusted_hotspots(complexity_stats, {"per_file": []}) == []
    assert ks.find_untrusted_hotspots(complexity_stats, {}) == []
    assert ks.find_untrusted_hotspots(complexity_stats, None) == []


def test_find_untrusted_hotspots_only_flags_actual_hotspots() -> None:
    complexity_stats = {"top_hotspots": [{"path": "src/hot.py"}]}
    test_pressure = {"per_file": [
        {"file": "src/not_a_hotspot.py", "survived": 9, "total": 10},
    ]}
    assert ks.find_untrusted_hotspots(complexity_stats, test_pressure) == []


# --- Task 5 E2: test-to-code mapping -----------------------------------------

def test_build_test_to_code_map_finds_colocated_tests(tmp_path: Path) -> None:
    repo = tmp_path
    (repo / "pkg").mkdir()
    (repo / "pkg" / "svc.go").write_text("package pkg")
    (repo / "pkg" / "svc_test.go").write_text("package pkg")
    (repo / "pkg" / "lonely.go").write_text("package pkg")  # no sibling test
    mapping = ks.build_test_to_code_map(repo, ["pkg/svc.go", "pkg/lonely.go"])
    assert mapping == {"pkg/svc_test.go": "pkg/svc.go"}


def test_build_test_to_code_map_python_and_adjacent_dir(tmp_path: Path) -> None:
    repo = tmp_path
    (repo / "src").mkdir()
    (repo / "src" / "mod.py").write_text("x = 1")
    (repo / "src" / "tests").mkdir()
    (repo / "src" / "tests" / "test_mod.py").write_text("x = 1")
    mapping = ks.build_test_to_code_map(repo, ["src/mod.py"])
    assert mapping == {"src/tests/test_mod.py": "src/mod.py"}


def test_find_sibling_test_skips_test_files_themselves(tmp_path: Path) -> None:
    repo = tmp_path
    (repo / "foo_test.go").write_text("package x")
    assert ks._find_sibling_test(repo, "foo_test.go") is None
    assert ks.build_test_to_code_map(repo, ["foo_test.go"]) == {}


# --- Accretion ratchet finding -----------------------------------------------

def _accreting_block(*, reliable: bool = True) -> dict:
    """A minimal well-formed accretion_ratchet run-context block."""
    return {
        "available": True,
        "reliable": reliable,
        "deletion_fraction_threshold": 0.15,
        "total_in_band": 2,
        "files": [
            {
                "path": "src/fat.py",
                "net_additions": 2400,
                "commit_count": 31,
                "deletion_fraction": 0.0,
                "time_span_months": 18.0,
            },
            {
                "path": "lib/bloat.py",
                "net_additions": 800,
                "commit_count": 12,
                "deletion_fraction": 0.05,
                "time_span_months": 6.0,
            },
        ],
    }


def test_accretion_ratchet_finding_returns_paths_worst_first() -> None:
    """Files are returned sorted by net additions descending, then path."""
    run_ctx = {"accretion_ratchet": _accreting_block()}
    paths = ks._accretion_ratchet_finding(run_ctx)
    # net_additions: fat.py=2400 > bloat.py=800
    assert paths == ["src/fat.py", "lib/bloat.py"]


def test_accretion_ratchet_finding_unavailable_returns_empty() -> None:
    """Block with available=False -> no finding paths (graceful degrade)."""
    run_ctx = {"accretion_ratchet": {"available": False, "files": []}}
    assert ks._accretion_ratchet_finding(run_ctx) == []


def test_accretion_ratchet_finding_absent_block_returns_empty() -> None:
    """Missing accretion_ratchet key -> no finding paths."""
    assert ks._accretion_ratchet_finding({}) == []


def test_accretion_ratchet_finding_no_files_returns_empty() -> None:
    """Available block but empty files list -> no finding paths."""
    run_ctx = {"accretion_ratchet": {"available": True, "reliable": True, "files": []}}
    assert ks._accretion_ratchet_finding(run_ctx) == []


def test_accretion_ratchet_finding_action_text_matches_config() -> None:
    """The action string in FINDING_ACTIONS matches the requirement."""
    assert ks.FINDING_ACTIONS["accretion_ratchet"] == (
        "refactor down: extract, delete dead code, or split the file"
    )


def test_format_accretion_items_roll_up_and_per_file_lines() -> None:
    """Roll-up sentence + one line per file in worst-first order."""
    run_ctx = {"accretion_ratchet": _accreting_block()}
    items = ks._format_accretion_items(run_ctx)
    # First item is the roll-up sentence.
    assert items[0].startswith("2 files show monotonic growth")
    assert "2 hottest" in items[0]
    # Per-file lines include path, LOC, time span, commits, deletion fraction.
    assert any("src/fat.py" in line and "+2,400 LOC" in line for line in items)
    assert any("lib/bloat.py" in line for line in items)
    # Worst offender comes first.
    fat_idx = next(i for i, line in enumerate(items) if "src/fat.py" in line)
    bloat_idx = next(i for i, line in enumerate(items) if "lib/bloat.py" in line)
    assert fat_idx < bloat_idx


def test_format_accretion_items_reliable_false_adds_disclaimer() -> None:
    """Unreliable history appends a disclaimer line."""
    run_ctx = {"accretion_ratchet": _accreting_block(reliable=False)}
    items = ks._format_accretion_items(run_ctx)
    assert any("UNRELIABLE" in line for line in items)


def test_format_accretion_items_reliable_true_no_disclaimer() -> None:
    """Reliable history: no disclaimer line."""
    run_ctx = {"accretion_ratchet": _accreting_block(reliable=True)}
    items = ks._format_accretion_items(run_ctx)
    assert not any("UNRELIABLE" in line for line in items)


def test_accretion_ratchet_in_finding_order_and_actions() -> None:
    """accretion_ratchet is present in both FINDING_ORDER and FINDING_ACTIONS."""
    assert "accretion_ratchet" in ks.FINDING_ORDER
    assert "accretion_ratchet" in ks.FINDING_ACTIONS
    # Placement: after unactioned_intent, before orphaned_understanding.
    order = ks.FINDING_ORDER
    ui_idx = order.index("unactioned_intent")
    ar_idx = order.index("accretion_ratchet")
    ou_idx = order.index("orphaned_understanding")
    assert ui_idx < ar_idx < ou_idx


def test_integrate_accretion_ratchet_wired_in() -> None:
    """When accretion_ratchet block is passed to integrate(), the finding fires.

    assemble_findings sorts paths alphabetically for determinism - the finding
    result carries both files regardless of net_additions order.
    """
    accreting = _accreting_block()
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
        accretion_ratchet=accreting,
    )
    paths = _finding_paths(result, "accretion_ratchet")
    # assemble_findings sorts alphabetically: lib/ before src/
    assert paths == sorted(["src/fat.py", "lib/bloat.py"])
    assert "src/fat.py" in paths
    assert "lib/bloat.py" in paths


def test_integrate_accretion_ratchet_absent_is_silent() -> None:
    """Without accretion_ratchet arg, the finding is silent (empty paths)."""
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
    )
    assert _finding_paths(result, "accretion_ratchet") == []


# --- override_contradicts_signals finding (archetype marker vs signals) ------

def test_override_contradicts_in_finding_order_and_actions() -> None:
    """override_contradicts_signals is a named finding, positioned before the
    one positive finding (refactor_boundary stays last)."""
    assert "override_contradicts_signals" in ks.FINDING_ORDER
    assert "override_contradicts_signals" in ks.FINDING_ACTIONS
    order = ks.FINDING_ORDER
    assert order.index("override_contradicts_signals") < order.index("refactor_boundary")
    assert ks.FINDING_ACTIONS["override_contradicts_signals"] == (
        "Review archetype marker - deterministic signals suggest a different "
        "classification"
    )


def test_integrate_override_contradiction_fires_finding() -> None:
    """A contradicting archetype block makes the finding fire against its source."""
    archetype = {
        "available": True,
        "override_contradicts_signals": True,
        "override_source": "CLAUDE.md",
    }
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
        archetype=archetype,
    )
    assert _finding_paths(result, "override_contradicts_signals") == ["CLAUDE.md"]


def test_integrate_override_contradiction_absent_is_silent() -> None:
    """No archetype contradiction -> the finding is silent (empty paths)."""
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
        archetype={"available": True, "override_contradicts_signals": False},
    )
    assert _finding_paths(result, "override_contradicts_signals") == []


# --- config-exclusion disclosure (apply_config_excludes) ---------------------

def test_apply_config_excludes_filters_and_counts() -> None:
    """Excluded finding paths are dropped from findings and returned separately."""
    findings = [
        {"name": "hidden_coupling", "paths": ["vendor/x", "src/a"], "action": "z"},
        {"name": "refactor_boundary", "paths": ["vendor/y"], "action": "z"},
    ]
    filtered, dropped = ks.apply_config_excludes(findings, {"vendor"}, [])
    kept = [p for f in filtered for p in f["paths"]]
    assert kept == ["src/a"]
    assert dropped == ["vendor/x", "vendor/y"]


def test_apply_config_excludes_pattern_match() -> None:
    """A basename glob pattern suppresses matching finding paths."""
    findings = [{"name": "lying_map", "paths": ["docs/gen.md", "docs/hand.md"],
                 "action": "z"}]
    filtered, dropped = ks.apply_config_excludes(findings, set(), ["gen.md"])
    assert filtered[0]["paths"] == ["docs/hand.md"]
    assert dropped == ["docs/gen.md"]


def test_apply_config_excludes_noop_without_config() -> None:
    """No excludes -> findings untouched, nothing dropped."""
    findings = [{"name": "hidden_coupling", "paths": ["a"], "action": "z"}]
    filtered, dropped = ks.apply_config_excludes(findings, set(), [])
    assert filtered == findings
    assert dropped == []


# A self-contained directory: repeatedly touched alone, so it reads as a
# refactor_boundary (the git-log containment view, which scan-level excludes
# never filter).
_ISLAND_COMMIT_SETS = [
    {Path("island/a.py")},
    {Path("island/b.py")},
    {Path("island/a.py")},
    {Path("island/c.py")},
    {Path("island/b.py")},
]


def test_integrate_excludes_suppress_finding_and_report_paths() -> None:
    """A config-excluded finding path is filtered from findings but disclosed.

    The refactor_boundary comes from the git-log containment view, which the
    scan-level exclude never touches - so integrate() is where it is filtered.
    """
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=None,
        commit_sets=_ISLAND_COMMIT_SETS,
        exclude_dirs={"island"},
    )
    # island/ was a refactor_boundary; the exclude filters it out of findings.
    assert "island" not in _finding_paths(result, "refactor_boundary")
    # ...but it is disclosed as a suppressed finding path.
    assert "island" in result["excluded_finding_paths"]


def test_integrate_no_excludes_reports_empty_suppression() -> None:
    """Without excludes, excluded_finding_paths is empty."""
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=None,
        commit_sets=_ISLAND_COMMIT_SETS,
    )
    assert result["excluded_finding_paths"] == []
    assert "island" in _finding_paths(result, "refactor_boundary")


# --- structure drift (Tier 1) folded into hidden_coupling --------------------

def _drift_tier1(pairs: list[tuple[str, str]]) -> dict:
    """A minimal available Tier 1 result carrying only the hidden-seam list."""
    return {
        "available": True,
        "human_split_but_cochange": [
            {"file_a": a, "file_b": b} for a, b in pairs
        ],
    }


def test_drift_hidden_coupling_unavailable_is_empty() -> None:
    """An unavailable Tier 1 result yields no hidden-coupling dirs."""
    assert ks.structure_drift_hidden_coupling_dirs({"available": False}) == []
    assert ks.structure_drift_hidden_coupling_dirs({}) == []


def test_drift_hidden_coupling_recurring_dir_pair_surfaces() -> None:
    """Two trees straddled by >= min_pairs distinct file pairs both surface.

    Two distinct file pairs link src/ and lib/; the pair recurs, so both
    directories read as a genuine hidden seam.
    """
    tier1 = _drift_tier1([
        ("src/a.py", "lib/x.py"),
        ("src/b.py", "lib/y.py"),
    ])
    assert ks.structure_drift_hidden_coupling_dirs(tier1) == ["lib", "src"]


def test_drift_hidden_coupling_hub_file_is_not_a_seam() -> None:
    """A single hub file coupling with every tree manufactures no seam.

    The version hot-file shape: one file in cfg/ co-changes with a different
    directory on each pair. Each directory *pair* occurs exactly once, so none
    recurs and no directory surfaces - the version-bump ritual is not drift.
    """
    tier1 = _drift_tier1([
        ("cfg/v.json", "src/a.py"),
        ("cfg/v.json", "lib/b.py"),
        ("cfg/v.json", "docs/c.md"),
    ])
    assert ks.structure_drift_hidden_coupling_dirs(tier1) == []


def test_drift_hidden_coupling_ignores_root_and_intra_dir() -> None:
    """Pairs touching the repo root, or within one directory, are ignored.

    A root-level file (dir ``.``) has vacuous containment; an intra-directory
    pair is cohesion, not a cross-tree seam. Neither contributes a finding even
    when repeated.
    """
    tier1 = _drift_tier1([
        ("README.md", "src/a.py"),   # root side -> ignored
        ("README.md", "src/b.py"),   # root side -> ignored
        ("src/c.py", "src/d.py"),    # intra-dir -> ignored
        ("src/e.py", "src/f.py"),    # intra-dir -> ignored
    ])
    assert ks.structure_drift_hidden_coupling_dirs(tier1) == []


def test_drift_hidden_coupling_single_pair_below_threshold() -> None:
    """One file pair straddling two trees is below the recurrence threshold."""
    tier1 = _drift_tier1([("src/a.py", "lib/x.py")])
    assert ks.structure_drift_hidden_coupling_dirs(tier1) == []


def test_drift_tier1_silent_without_static_graph() -> None:
    """_structure_drift_tier1 returns unavailable when the static graph is out.

    With no import graph there is nothing to disagree with, so Tier 1 is not
    even attempted - the detector is never called.
    """
    out = ks._structure_drift_tier1(
        Path("/nonexistent"),
        {"available": False},
        {"available": True, "change_coupling_pairs": []},
    )
    assert out == {"available": False}


def test_integrate_returns_structure_drift_tier1() -> None:
    """integrate() exposes the Tier 1 result for the orchestrator to serialise.

    With a /nonexistent repo there is no ownership map, so the detector degrades
    to available:False - but the key is present, proving the wiring exists.
    """
    result = ks.integrate(
        repo_root=Path("/nonexistent"),
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
    )
    assert "structure_drift_tier1" in result
    assert result["structure_drift_tier1"].get("available") in (True, False)


# --- FINDING_MODES / mode_for_finding ---------------------------------------

def test_finding_modes_cover_every_finding() -> None:
    """Every named finding maps to a mode - no finding reaches the report
    without a deterministic execution posture."""
    assert set(ks.FINDING_MODES) == set(ks.FINDING_ORDER)


def test_finding_modes_use_only_the_closed_mode_set() -> None:
    """The three modes are a closed vocabulary; no finding invents a fourth."""
    allowed = {"characterize_first", "verify_then_retire", "refactor_safe"}
    assert set(ks.FINDING_MODES.values()) <= allowed
    assert ks.FINDING_MODE_VALUES == frozenset(ks.FINDING_MODES.values())


def test_mode_for_finding_maps_known_types() -> None:
    assert ks.mode_for_finding("lying_map") == "verify_then_retire"
    assert ks.mode_for_finding("refactor_boundary") == "refactor_safe"
    assert ks.mode_for_finding("hidden_coupling") == "characterize_first"


def test_mode_for_finding_defaults_for_unknown_or_missing() -> None:
    """An unknown or absent finding falls back to the conservative default."""
    assert ks.mode_for_finding(None) == ks.DEFAULT_FINDING_MODE
    assert ks.mode_for_finding("not_a_real_finding") == ks.DEFAULT_FINDING_MODE
    assert ks.DEFAULT_FINDING_MODE == "characterize_first"


# --- archive exclusion from attention ------------------------------------------

def test_archive_paths_excluded_from_attention_and_disclosed() -> None:
    """A path with an archive/archived/attic component never ranks in attention.

    The archived plan scores 2 (two negative findings) and would lead the list;
    it is excluded from attention and prescribed actions, and returned for the
    disclosure. A file whose name merely contains "archive" is not excluded.
    """
    findings = ks.assemble_findings({
        "accretion_ratchet": ["docs/archive/PLAN.md", "src/app.py"],
        "unactioned_intent": ["docs/archive/PLAN.md", "old/Attic/x.py"],
        "lying_map": ["legacy/archived/notes.py", "src/archive_writer.py"],
        "refactor_boundary": ["archive"],
    })
    attention, archived = ks.exclude_archive_from_attention(findings)
    ranked = [u["path"] for u in attention]
    assert ranked == ["src/app.py", "src/archive_writer.py"]
    assert archived == [
        "docs/archive/PLAN.md", "legacy/archived/notes.py", "old/Attic/x.py",
    ]
    prescribed = ks.build_prescribed_actions(attention, findings)
    assert [p["path"] for p in prescribed] == ["src/app.py", "src/archive_writer.py"]
    # The findings themselves still name the archived path (a true observation).
    acc = next(f for f in findings if f["name"] == "accretion_ratchet")
    assert "docs/archive/PLAN.md" in acc["paths"]


def test_archive_paths_excluded_noop_without_archive() -> None:
    """No archive path -> attention equals build_attention_list, nothing disclosed."""
    findings = ks.assemble_findings({"accretion_ratchet": ["src/a.py"]})
    attention, archived = ks.exclude_archive_from_attention(findings)
    assert attention == ks.build_attention_list(findings)
    assert archived == []


# --- prune_missing_finding_paths (renamed / deleted history) -----------------

def test_pruned_finding_paths_only_git_history_findings(tmp_path: Path) -> None:
    """A git-history finding path absent from disk is dropped and returned
    sorted; paths that exist, and findings read from the working tree, are
    untouched."""
    (tmp_path / "live").mkdir()
    findings = ks.assemble_findings({
        "hidden_coupling": ["live", "gone", "also_gone"],
        "refactor_boundary": ["gone_island"],
        "unactioned_intent": ["not/on/disk.py"],
    })
    pruned, dropped = ks.prune_missing_finding_paths(findings, tmp_path)
    by_name = {f["name"]: f["paths"] for f in pruned}
    assert by_name["hidden_coupling"] == ["live"]
    assert by_name["refactor_boundary"] == []
    assert by_name["unactioned_intent"] == ["not/on/disk.py"]
    assert dropped == ["also_gone", "gone", "gone_island"]
    assert [f["name"] for f in pruned] == [f["name"] for f in findings]


def test_pruned_finding_paths_stand_down_when_rename_map_incomplete(tmp_path: Path) -> None:
    """With git history read, a hidden_coupling dir absent from disk is pruned.
    When the rename map could not be built (git failed), a missing path may be
    an unfolded old name rather than a deletion, so nothing is pruned."""
    import subprocess

    from lib.change_coupling import RenameMap

    subprocess.run(["git", "init", "-q", str(tmp_path)], check=True)

    def run(complete: bool) -> dict:
        return ks.integrate(
            repo_root=tmp_path,
            complexity_stats=_COMPLEXITY_STATS,
            doc_staleness=_stale_doc_staleness(churn_degenerate=False),
            dead_code={"available": False, "candidate_count": 0,
                       "candidates": [], "tools": []},
            observability={"rung": None, "reachable": {"present": False}},
            structure=_MODULAR_STRUCTURE,
            commit_sets=_BLEEDING_COMMIT_SETS,
            rename_map=RenameMap({}, complete=complete),
        )

    stood_down = run(complete=False)
    assert _finding_paths(stood_down, "hidden_coupling")
    assert stood_down["pruned_finding_paths"] == []
    assert stood_down["rename_map_complete"] is False
    pruned = run(complete=True)
    assert _finding_paths(pruned, "hidden_coupling") == []
    assert pruned["pruned_finding_paths"] == sorted(
        _finding_paths(stood_down, "hidden_coupling"))


def test_rename_map_incomplete_when_ancestry_check_fails(tmp_path: Path, monkeypatch) -> None:
    """A chain hop needs `git merge-base --is-ancestor`. Exit 128 (an object git
    cannot resolve, as at a shallow boundary) is a failure, not "unrelated": the
    map comes back empty and incomplete, and the prune stands down, so a live
    finding is never reported as deleted."""
    import subprocess

    import lib.change_coupling as cc

    def git(*args: str) -> None:
        subprocess.run(["git", "-C", str(tmp_path), "-c", "user.email=t@example.com",
                        "-c", "user.name=T", *args], check=True, capture_output=True)

    git("init", "-q")
    (tmp_path / "a.py").write_text("a = 1\n" * 5)
    git("add", "-A")
    git("commit", "-q", "-m", "a")
    git("mv", "a.py", "b.py")
    git("commit", "-q", "-m", "a -> b")
    git("mv", "b.py", "c.py")
    git("commit", "-q", "-m", "b -> c")

    real_run = subprocess.run

    def fake_run(cmd, *args, **kwargs):
        if "--is-ancestor" in cmd:
            return subprocess.CompletedProcess(cmd, 128, b"", b"fatal: bad object")
        return real_run(cmd, *args, **kwargs)

    monkeypatch.setattr(cc.subprocess, "run", fake_run)
    rename_map = cc.build_rename_map(tmp_path)
    assert rename_map == cc.RenameMap({}, complete=False)

    result = ks.integrate(
        repo_root=tmp_path,
        complexity_stats=_COMPLEXITY_STATS,
        doc_staleness=_stale_doc_staleness(churn_degenerate=False),
        dead_code={"available": False, "candidate_count": 0,
                   "candidates": [], "tools": []},
        observability={"rung": None, "reachable": {"present": False}},
        structure=_MODULAR_STRUCTURE,
        commit_sets=_BLEEDING_COMMIT_SETS,
        rename_map=rename_map,
    )
    assert _finding_paths(result, "hidden_coupling")
    assert result["pruned_finding_paths"] == []
    assert result["rename_map_complete"] is False

"""Tests for Layer 1 liveness inputs: dead-code tier + observability rungs."""
from __future__ import annotations

import subprocess
from pathlib import Path

import lib.liveness_scan as liveness
from lib.liveness_scan import (
    _parse_deadcode,
    _parse_staticcheck,
    _parse_ts_prune,
    _parse_vulture,
    scan_dead_code,
    scan_observability,
)


def _write(root: Path, rel: str, text: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


# ── dead-code parsers ──────────────────────────────────────────────────────

def test_parse_vulture() -> None:
    out = (
        "src/foo.py:12: unused function 'bar' (60% confidence)\n"
        "src/foo.py:3: unused import 'os' (90% confidence)\n"
    )
    parsed = _parse_vulture(out)
    assert len(parsed) == 2
    assert parsed[0]["symbol"] == "bar"
    assert parsed[0]["line"] == 12


def test_parse_ts_prune_skips_used_in_module() -> None:
    out = "src/a.ts:4 - unusedThing\nsrc/b.ts:9 - helper (used in module)\n"
    parsed = _parse_ts_prune(out)
    assert len(parsed) == 1
    assert parsed[0]["symbol"] == "unusedThing"


def test_parse_staticcheck_and_deadcode() -> None:
    sc = "pkg/x.go:10:2: func unusedHelper is unused (U1000)\n"
    assert _parse_staticcheck(sc)[0]["line"] == 10
    dc = "pkg/y.go:5:1: unreachable func: deadOne\n"
    assert "unreachable" in _parse_deadcode(dc)[0]["kind"]


# ── dead-code scan plumbing ────────────────────────────────────────────────

def test_dead_code_degrades_when_tool_absent(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "foo.py", "x = 1")
    monkeypatch.setattr(liveness.shutil, "which", lambda _tool: None)
    r = scan_dead_code(tmp_path).as_dict()
    assert r["available"] is False
    assert r["candidate_count"] == 0
    assert any(t["status"] == "tool_absent" for t in r["tools"])
    assert "external consumer" in r["caveat"]  # the hard-limit caveat is present


def test_dead_code_runs_and_parses(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "foo.py", "def unused(): pass")
    monkeypatch.setattr(liveness.shutil, "which", lambda _tool: "/usr/bin/" + _tool)

    def fake_run(cmd, **kwargs):
        return subprocess.CompletedProcess(
            cmd, 3, stdout="foo.py:1: unused function 'unused' (60% confidence)\n",
            stderr="",
        )

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path).as_dict()
    assert r["available"] is True
    assert r["candidate_count"] == 1
    assert r["candidates"][0]["symbol"] == "unused"


def test_dead_code_timeout_degrades(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "foo.py", "x = 1")
    monkeypatch.setattr(liveness.shutil, "which", lambda _tool: "/usr/bin/" + _tool)

    def fake_run(cmd, **kwargs):
        raise subprocess.TimeoutExpired(cmd, 60)

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path).as_dict()
    assert any(t["status"] == "timeout" for t in r["tools"])
    assert r["candidate_count"] == 0  # no crash


def test_dead_code_no_languages(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "just docs")
    r = scan_dead_code(tmp_path).as_dict()
    assert r["available"] is False
    assert r["candidate_count"] == 0


def test_dead_code_skips_user_excluded_dirs_at_probe(
    tmp_path: Path, monkeypatch,
) -> None:
    """User excludes apply at the language-presence probe too. A repo whose
    only Python lives in `regulatory-raw/` reports `tool_absent` (vulture
    never runs) when that dir is excluded - same as if no Python existed
    in scope at all."""
    _write(tmp_path, "regulatory-raw/loader.py", "x = 1")
    monkeypatch.setattr(liveness.shutil, "which", lambda _tool: "/usr/bin/" + _tool)
    ran = []

    def fake_run(cmd, **kwargs):
        ran.append(cmd)
        return subprocess.CompletedProcess(cmd, 0, stdout="", stderr="")

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(
        tmp_path, extra_exclude_dirs={"regulatory-raw"},
    ).as_dict()
    # vulture must not have been invoked - no Python in scope.
    assert ran == []
    assert r["available"] is False


def test_dead_code_filters_user_excluded_candidates_post_scan(
    tmp_path: Path, monkeypatch,
) -> None:
    """When vulture runs and emits candidates from a user-excluded dir,
    the post-scan filter drops them so they never reach the report."""
    _write(tmp_path, "app.py", "def used(): pass")
    _write(tmp_path, "regulatory-raw/loader.py", "def unused(): pass")
    monkeypatch.setattr(liveness.shutil, "which", lambda _tool: "/usr/bin/" + _tool)

    def fake_run(cmd, **kwargs):
        return subprocess.CompletedProcess(
            cmd, 3,
            stdout=(
                "app.py:1: unused function 'foo' (60% confidence)\n"
                "regulatory-raw/loader.py:1: unused function 'unused' (60% confidence)\n"
            ),
            stderr="",
        )

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(
        tmp_path, extra_exclude_dirs={"regulatory-raw"},
    ).as_dict()
    assert r["available"] is True
    paths = {c["path"] for c in r["candidates"]}
    assert "app.py" in paths
    assert all("regulatory-raw" not in p for p in paths)


def test_dead_code_excludes_test_fixtures(tmp_path: Path, monkeypatch) -> None:
    """Vulture is told to skip `**/tests/fixtures/**` at scan time, and the
    post-scan filter drops any fixture candidate that slips through, so a
    deliberately-dead fixture file never surfaces as repo dead code (#83)."""
    from lib.liveness_scan import _under_excluded, _vulture_excludes

    assert "*/tests/fixtures/*" in _vulture_excludes().split(",")
    assert _under_excluded("a/tests/fixtures/sample.py") is True
    assert _under_excluded("src/app.py") is False


# ── observability rungs ────────────────────────────────────────────────────

def test_observability_none(tmp_path: Path) -> None:
    _write(tmp_path, "README.md", "nothing runtime here")
    assert scan_observability(tmp_path).rung == 0


def test_instrumented_but_human_only_is_rung_2(tmp_path: Path) -> None:
    """The meridian case: telemetry + a prose runbook, but no agent-invokable path."""
    _write(tmp_path, "package.json", '{"dependencies":{"prom-client":"1","winston":"3"}}')
    _write(tmp_path, "OBSERVABILITY.md",
           "Dashboards live in Grafana. SLOs are tracked by the platform team.")
    r = scan_observability(tmp_path).as_dict()
    assert r["rung"] == 2
    assert r["instrumented"]["present"] is True
    assert r["discoverable"]["present"] is True
    assert r["reachable"]["present"] is False


def test_agent_queryable_is_rung_3_via_mcp_and_runbook(tmp_path: Path) -> None:
    _write(tmp_path, "pyproject.toml", '[project]\ndependencies = ["opentelemetry-sdk"]')
    _write(tmp_path, ".mcp.json", '{"mcpServers":{"loki-logs":{"command":"loki-mcp"}}}')
    _write(tmp_path, "runbooks/oncall.md",
           "Query logs:\n```bash\nkubectl logs deploy/api\n```\n")
    r = scan_observability(tmp_path).as_dict()
    assert r["rung"] == 3
    assert r["reachable"]["present"] is True
    # both the MCP server and the runnable runbook are recorded
    assert len(r["reachable"]["signals"]) >= 2


def test_prose_mention_of_grafana_does_not_reach_rung_3(tmp_path: Path) -> None:
    """A runbook that merely *names* a dashboard tool isn't agent-reachable."""
    _write(tmp_path, "go.mod", "require go.opentelemetry.io/otel v1.0.0")
    _write(tmp_path, "runbooks/notes.md",
           "We use Grafana and Datadog. Ask the on-call engineer for access.")
    r = scan_observability(tmp_path)
    assert r.rung == 2  # discoverable, not reachable - no runnable command in a fence


def test_repo_skill_for_logs_is_reachable(tmp_path: Path) -> None:
    _write(tmp_path, "requirements.txt", "structlog\n")
    _write(tmp_path, ".claude/skills/tail-logs/SKILL.md", "# tail logs")
    r = scan_observability(tmp_path)
    assert r.rung == 3
    assert any("repo skill" in s for s in r.reachable)


def test_overloaded_token_names_do_not_reach_rung_3(tmp_path: Path) -> None:
    """changelog/blog/login etc. must not be mistaken for telemetry channels."""
    _write(tmp_path, "requirements.txt", "structlog\n")  # rung 1 instrumentation
    _write(tmp_path, ".mcp.json", '{"mcpServers":{"changelog-bot":{"command":"x"},"login":{"command":"y"}}}')
    _write(tmp_path, "skills/blog-publisher/SKILL.md", "# blog")
    _write(tmp_path, "skills/catalog-search/SKILL.md", "# catalog")
    r = scan_observability(tmp_path)
    assert r.reachable == []      # no genuine log/metric/trace tool
    assert r.rung == 1            # instrumented only


def test_observ_substring_does_not_reach_rung_3(tmp_path: Path) -> None:
    """`observer`/`observation` are not observability tooling; only `observab*` is."""
    _write(tmp_path, "requirements.txt", "structlog\n")
    _write(tmp_path, ".mcp.json", '{"mcpServers":{"observer-service":{"command":"x"}}}')
    assert scan_observability(tmp_path).rung == 1  # observer != observability

    _write(tmp_path, ".mcp.json", '{"mcpServers":{"observability-gw":{"command":"x"}}}')
    assert scan_observability(tmp_path).rung == 3  # observability is genuine


def test_single_body_token_does_not_reach_discoverable(tmp_path: Path) -> None:
    """A lone product 'dashboard'/'alerting' mention isn't an observability doc."""
    _write(tmp_path, "features.md", "Our product dashboard shows charts to users.")
    _write(tmp_path, "ops.md", "We have alerting in the UI.")
    assert scan_observability(tmp_path).rung == 0


def test_two_body_tokens_reach_discoverable(tmp_path: Path) -> None:
    # Instrumentation present so the discoverable doc can elevate the rung -
    # this test isolates the 2-distinct-token threshold for *discoverable*
    # detection, not the rung floor (see test_docs_only_without_instrumentation).
    _write(tmp_path, "requirements.txt", "structlog\n")
    _write(tmp_path, "ops.md",
           "We watch SLOs in Grafana and page via alerting when budgets burn.")
    r = scan_observability(tmp_path)
    assert r.rung == 2
    assert r.discoverable


def test_docs_only_without_instrumentation_is_rung_0(tmp_path: Path) -> None:
    """A repo that only *documents* observability - no telemetry emitted - must
    not inflate past rung 0. Regression for the self-referential false positive
    where this toolkit's own SKILL.md (prose describing runbooks/runnable
    queries) scored rung 3 with `instrumented: false`."""
    _write(tmp_path, "runbooks/oncall.md",
           "We watch SLOs in Grafana and Datadog.\n"
           "Query logs:\n```bash\nkubectl logs deploy/api\n```\n")
    r = scan_observability(tmp_path).as_dict()
    assert r["instrumented"]["present"] is False
    # the doc still registers as discoverable/reachable evidence...
    assert r["discoverable"]["present"] is True
    assert r["reachable"]["present"] is True
    # ...but with nothing instrumented there is no telemetry to reach: rung 0.
    assert r["rung"] == 0


def test_mcp_tooling_reaches_rung_3_without_instrumentation(tmp_path: Path) -> None:
    """An invokable telemetry tool (.mcp.json log/metric server) is real
    agent-reachability on its own - it stands at rung 3 even with no in-repo
    instrumentation manifest (the telemetry lives in deployed infra)."""
    _write(tmp_path, ".mcp.json",
           '{"mcpServers":{"loki-logs":{"command":"loki-mcp"}}}')
    r = scan_observability(tmp_path).as_dict()
    assert r["instrumented"]["present"] is False
    assert r["rung"] == 3
    assert any("MCP server" in s for s in r["reachable"]["signals"])


# ── read-only: build-mutating dead-code tools are gated ────────────────────

def test_build_tools_not_run_by_default(tmp_path: Path, monkeypatch) -> None:
    """Go tools (deadcode/staticcheck) compile the project, so a read-only run
    reports them available-but-not-run rather than executing them."""
    _write(tmp_path, "main.go", "package main\nfunc main(){}")
    monkeypatch.setattr(liveness.shutil, "which", lambda t: "/usr/bin/" + t)

    def fake_run(cmd, **kwargs):
        raise AssertionError("a build tool was executed in a read-only scan")

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path).as_dict()  # run_build_tools defaults False
    deadcode = next(t for t in r["tools"] if t["tool"] == "deadcode")
    assert deadcode["status"] == "available_not_run"
    assert "build" in deadcode["reason"].lower()
    assert r["candidate_count"] == 0


def test_build_tools_run_when_opted_in(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "main.go", "package main\nfunc main(){}")
    monkeypatch.setattr(liveness.shutil, "which", lambda t: "/usr/bin/" + t)

    def fake_run(cmd, **kwargs):
        return subprocess.CompletedProcess(
            cmd, 0, stdout="main.go:9:1: unreachable func: helper\n", stderr="")

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path, run_build_tools=True).as_dict()
    assert r["available"] is True
    assert r["candidate_count"] == 1


def test_vendored_dead_code_is_filtered(tmp_path: Path, monkeypatch) -> None:
    """Candidates under .venv/node_modules are dropped so the cap stays about THIS repo."""
    _write(tmp_path, "app.py", "x = 1")
    monkeypatch.setattr(liveness.shutil, "which", lambda t: "/usr/bin/" + t)

    def fake_run(cmd, **kwargs):
        return subprocess.CompletedProcess(cmd, 3, stderr="", stdout=(
            ".venv/lib/dep.py:5: unused function 'vendored' (60% confidence)\n"
            "app.py:1: unused function 'mine' (60% confidence)\n"))

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path).as_dict()
    paths = {c["path"] for c in r["candidates"]}
    assert paths == {"app.py"}  # vendored candidate dropped


# ── JavaScript / TypeScript tool choice ────────────────────────────────────

def _which_without(*hidden: str):
    return lambda t, *a, **k: None if t in hidden else "/usr/bin/" + t


def test_ts_prune_requires_tsconfig_not_applicable_without_one(
    tmp_path: Path, monkeypatch,
) -> None:
    """ts-prune run bare from the root needs a root tsconfig.json; without one
    it has no project to analyse, so it is recorded not_applicable, not run,
    and never reads as a clean '0 candidate(s)'."""
    for i in range(6):
        _write(tmp_path, f"src/m{i}.ts", f"export const v{i} = {i};")
    monkeypatch.setattr(liveness.shutil, "which", _which_without("knip"))

    def fake_run(cmd, **kwargs):
        raise AssertionError(f"{cmd[0]} ran without a tsconfig.json")

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path).as_dict()
    ts_prune = [t for t in r["tools"] if t["tool"] == "ts-prune"]
    assert [t["status"] for t in ts_prune] == ["not_applicable"]
    assert "tsconfig.json" in ts_prune[0]["reason"]
    assert r["available"] is False
    assert r["candidate_count"] == 0


def test_ts_prune_requires_tsconfig_runs_with_root_tsconfig(
    tmp_path: Path, monkeypatch,
) -> None:
    for i in range(6):
        _write(tmp_path, f"src/m{i}.ts", f"export const v{i} = {i};")
    _write(tmp_path, "tsconfig.json", '{"include": ["src"]}')
    monkeypatch.setattr(liveness.shutil, "which", _which_without("knip"))
    monkeypatch.setattr(
        liveness.subprocess, "run",
        lambda cmd, **kw: subprocess.CompletedProcess(
            cmd, 0, stdout="src/m1.ts:1 - v1\n", stderr=""),
    )
    r = scan_dead_code(tmp_path).as_dict()
    ts_prune = next(t for t in r["tools"] if t["tool"] == "ts-prune")
    assert ts_prune["status"] == "ran"
    assert r["available"] is True
    assert r["candidate_count"] == 1


def test_dominant_language_javascript_names_knip_when_absent(
    tmp_path: Path, monkeypatch,
) -> None:
    """A JavaScript-dominant repository with a stray TypeScript subproject
    (its own nested tsconfig.json) is judged by its JavaScript: ts-prune does
    not run, and JavaScript liveness honest-degrades with knip named."""
    for i in range(6):
        _write(tmp_path, f"src/m{i}.js", f"export const v{i} = {i};")
    _write(tmp_path, "src/esm.mjs", "export const e = 1;")
    _write(tmp_path, "jsconfig.json", "{}")
    _write(tmp_path, "cdk/stack.ts", "export const c = 1;")
    _write(tmp_path, "cdk/tsconfig.json", "{}")
    monkeypatch.setattr(liveness.shutil, "which", _which_without("knip"))

    def fake_run(cmd, **kwargs):
        raise AssertionError(f"{cmd[0]} ran on a JavaScript-dominant repo")

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path).as_dict()
    assert r["available"] is False
    assert all(t["status"] != "ran" for t in r["tools"])
    typescript = [t for t in r["tools"] if t["language"] == "typescript"]
    assert [(t["tool"], t["status"]) for t in typescript] == [
        ("ts-prune", "not_applicable"),
    ]
    assert "1 TypeScript file(s) are not analysed" in typescript[0]["reason"]
    knip = [t for t in r["tools"] if t["tool"] == "knip"]
    assert len(knip) == 1
    assert knip[0]["language"] == "javascript"
    assert knip[0]["status"] == "honest_degrade"
    assert "knip" in knip[0]["reason"]


def test_dominant_language_typescript_keeps_ts_prune_despite_some_js(
    tmp_path: Path, monkeypatch,
) -> None:
    for i in range(4):
        _write(tmp_path, f"src/m{i}.ts", f"export const v{i} = {i};")
    _write(tmp_path, "scripts/build.js", "module.exports = {};")
    _write(tmp_path, "tsconfig.json", "{}")
    monkeypatch.setattr(liveness.shutil, "which", _which_without("knip"))
    monkeypatch.setattr(
        liveness.subprocess, "run",
        lambda cmd, **kw: subprocess.CompletedProcess(cmd, 0, stdout="", stderr=""),
    )
    r = scan_dead_code(tmp_path).as_dict()
    assert [(t["language"], t["tool"], t["status"]) for t in r["tools"]] == [
        ("typescript", "ts-prune", "ran"),
        ("javascript", "knip", "not_applicable"),
    ]
    js = r["tools"][1]
    assert "1 JavaScript file(s) are not analysed" in js["reason"]


def test_dominant_language_follows_scope_not_sibling_subtree(
    tmp_path: Path, monkeypatch,
) -> None:
    """A run scoped to a TypeScript package picks its tool from the in-scope
    files, not from a larger JavaScript sibling package elsewhere in the repo.
    The tool still runs repo-wide; only the language choice and candidates
    follow the scope."""
    for i in range(4):
        _write(tmp_path, f"packages/web/m{i}.ts", f"export const v{i} = {i};")
    for i in range(8):
        _write(tmp_path, f"packages/legacy/m{i}.js", f"export const v{i} = {i};")
    _write(tmp_path, "tsconfig.json", "{}")
    monkeypatch.setattr(liveness.shutil, "which", _which_without("knip"))
    calls = []

    def fake_run(cmd, **kwargs):
        calls.append(kwargs["cwd"])
        return subprocess.CompletedProcess(
            cmd, 0, stdout="packages/web/m1.ts:1 - v1\n", stderr="")

    monkeypatch.setattr(liveness.subprocess, "run", fake_run)
    r = scan_dead_code(tmp_path, scope=tmp_path / "packages" / "web").as_dict()
    assert [(t["language"], t["tool"], t["status"]) for t in r["tools"]] == [
        ("typescript", "ts-prune", "ran"),
    ]
    assert calls == [str(tmp_path.resolve())]
    assert r["candidate_count"] == 1


def test_dominant_language_counts_mts_and_cts_as_typescript(
    tmp_path: Path, monkeypatch,
) -> None:
    _write(tmp_path, "src/a.mts", "export const a = 1;")
    _write(tmp_path, "src/b.cts", "export const b = 1;")
    _write(tmp_path, "scripts/build.js", "module.exports = {};")
    _write(tmp_path, "tsconfig.json", "{}")
    monkeypatch.setattr(liveness.shutil, "which", _which_without("knip"))
    monkeypatch.setattr(
        liveness.subprocess, "run",
        lambda cmd, **kw: subprocess.CompletedProcess(cmd, 0, stdout="", stderr=""),
    )
    r = scan_dead_code(tmp_path).as_dict()
    assert [(t["language"], t["tool"], t["status"]) for t in r["tools"]] == [
        ("typescript", "ts-prune", "ran"),
        ("javascript", "knip", "not_applicable"),
    ]


def test_dominant_language_javascript_knip_present_is_available_not_run(
    tmp_path: Path, monkeypatch,
) -> None:
    _write(tmp_path, "index.js", "module.exports = {};")
    monkeypatch.setattr(liveness.shutil, "which", _which_without())
    r = scan_dead_code(tmp_path).as_dict()
    assert [(t["language"], t["tool"], t["status"]) for t in r["tools"]] == [
        ("javascript", "knip", "available_not_run"),
    ]


def test_scorer_doc_names_every_dead_code_status() -> None:
    """Every `tools[].status` the scan can emit is named in the layer-scorer
    agent's guidance, so a new status never reaches the report unhandled (a
    skipped tool read as "no language tool present")."""
    import re

    lib_dir = Path(liveness.__file__).resolve().parent
    source = (lib_dir / "liveness_scan.py").read_text()
    emitted = set(re.findall(r'"(?:absent_)?status":\s*"(\w+)"', source))
    emitted |= set(re.findall(r'get\("absent_status",\s*"(\w+)"\)', source))
    assert {"not_applicable", "honest_degrade", "tool_absent"} <= emitted
    repo_root = lib_dir.parents[3]
    doc = (repo_root / "agents" / "assess-layer-scorer.md").read_text()
    missing = sorted(s for s in emitted if f"`{s}`" not in doc)
    assert not missing, f"assess-layer-scorer.md does not name: {missing}"

"""log.md entry replacement and re-chain across core runs and finalize (#355).

A core run on the same date and measured commit as the previous, never
finalized run replaces that run's log entry instead of stacking a second one.
Finalize fills the entry stamped with its run id, re-chains the log, and
refuses while an earlier same-date entry still carries placeholders.
"""
from __future__ import annotations

import json
import os
import subprocess
import sys
from pathlib import Path

import pytest

from assess_core import build_run_context
from assess_finalize import FinalizeValidationError, finalize_run
from lib.badge import maturity_band
from lib.wiki_writer import (
    LOG_PLACEHOLDER,
    read_log_entries,
    rewrite_log_entry,
    verify_log_chain,
)

DAY = "2026-09-18"


def _git(repo: Path, *args: str) -> None:
    subprocess.run(
        ["git", "-C", str(repo), "-c", "user.email=t@example.com", "-c", "user.name=T", *args],
        check=True, capture_output=True, text=True, env=os.environ,
    )


@pytest.fixture
def repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    (repo / "src").mkdir(parents=True)
    (repo / "src" / "hot.py").write_text("def hot(a):\n    return a\n", encoding="utf-8")
    _git(repo, "init", "-q")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "c1")
    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 1, "loc": {"total": 2}, "ccn": {"max": 1, "mean": 1},
        "top_hotspots": [{"path": "src/hot.py", "loc": 2, "ccn": 1, "commits": 1}],
        "top_complex": [], "top_large": [],
    }), encoding="utf-8")
    return repo


def _run(repo: Path) -> dict:
    return build_run_context(repo_root=repo, run_date=DAY, non_interactive=True)


def _stage_finalize(assess_dir: Path, run_id: str) -> None:
    (assess_dir / ".cache").mkdir(exist_ok=True)
    (assess_dir / ".cache" / "finalize-input.json").write_text(json.dumps({
        "run_id": run_id, "score": 4.0, "denominator": 8,
        "maturity_label": maturity_band(4.0, 8),
        "top_action": "fixture action", "hotspot_actions": {},
    }), encoding="utf-8")


def _day_headings(assess_dir: Path) -> int:
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    return sum(1 for line in log.splitlines() if line.startswith(f"## {DAY}"))


def test_core_replaces_superseded_same_day_entry(repo: Path) -> None:
    assess_dir = repo / ".assess"
    first = _run(repo)
    second = _run(repo)
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    assert _day_headings(assess_dir) == 1
    assert first["run_id"] not in log
    assert second["run_id"] in log
    assert verify_log_chain(assess_dir) == (True, None)
    assert second["log_integrity"]["valid"] is True

    _stage_finalize(assess_dir, second["run_id"])
    finalize_run(assess_dir=assess_dir)
    assert _day_headings(assess_dir) == 1
    assert verify_log_chain(assess_dir) == (True, None)

    # A finalized entry is history: the next run appends, and discloses nothing.
    third = _run(repo)
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    assert _day_headings(assess_dir) == 2
    assert "fixture action" in log
    assert "History integrity broken" not in log
    assert third["log_integrity"]["valid"] is True


def test_core_keeps_superseded_same_day_entry_on_new_commit(repo: Path) -> None:
    assess_dir = repo / ".assess"
    _run(repo)
    (repo / "src" / "warm.py").write_text("def warm(a):\n    return a\n", encoding="utf-8")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "c2")
    _run(repo)
    assert _day_headings(assess_dir) == 2


def test_finalize_refuses_earlier_same_date_placeholder_entry(repo: Path) -> None:
    assess_dir = repo / ".assess"
    first = _run(repo)
    (repo / "src" / "warm.py").write_text("def warm(a):\n    return a\n", encoding="utf-8")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "c2")
    second = _run(repo)
    before = (assess_dir / "log.md").read_text(encoding="utf-8")
    _stage_finalize(assess_dir, second["run_id"])
    with pytest.raises(FinalizeValidationError, match=first["run_id"]):
        finalize_run(assess_dir=assess_dir)
    # Fail-closed: nothing written.
    assert (assess_dir / "log.md").read_text(encoding="utf-8") == before
    assert before.count(LOG_PLACEHOLDER) == 2


def test_rewrite_log_entry_keeps_an_earlier_break_detectable(repo: Path) -> None:
    """Re-chaining after an edit must not bless an entry that was already broken."""
    assess_dir = repo / ".assess"
    for n in range(3):
        (repo / "src" / f"m{n}.py").write_text("x = 1\n", encoding="utf-8")
        _git(repo, "add", "-A")
        _git(repo, "commit", "-q", "-m", f"m{n}")
        _run(repo)
    log_path = assess_dir / "log.md"
    # An untampered log: rewriting the first entry re-chains the two after it.
    rewrite_log_entry(assess_dir, 0, read_log_entries(assess_dir)[0] + "\n")
    assert verify_log_chain(assess_dir) == (True, None)
    # Tamper with the middle entry only, then rewrite the first one.
    text = log_path.read_text(encoding="utf-8")
    cut = text.index("<!-- chain:") + len("<!-- chain:0123456789abcdef -->\n")
    log_path.write_text(
        text[:cut] + text[cut:].replace("**Files scored:**", "**Files scored (edited):**", 1),
        encoding="utf-8",
    )
    assert verify_log_chain(assess_dir) == (False, 2)
    entries = read_log_entries(assess_dir)
    rewrite_log_entry(assess_dir, 0, entries[0] + "\n")
    assert verify_log_chain(assess_dir) == (False, 2)


def test_drop_entry_clears_earlier_same_date_placeholder_refusal(repo: Path) -> None:
    """The refusal names a supported recovery; following it lets finalize run
    and leaves a chain that verifies."""
    assess_dir = repo / ".assess"
    first = _run(repo)
    (repo / "src" / "warm.py").write_text("def warm(a):\n    return a\n", encoding="utf-8")
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "c2")
    second = _run(repo)
    _stage_finalize(assess_dir, second["run_id"])
    with pytest.raises(FinalizeValidationError, match=f"--drop-entry {first['run_id']}"):
        finalize_run(assess_dir=assess_dir)

    script = Path(__file__).resolve().parents[1] / "scripts" / "assess_finalize.py"
    done = subprocess.run(
        [sys.executable, str(script), str(repo), "--drop-entry", first["run_id"]],
        capture_output=True, text=True,
    )
    assert done.returncode == 0, done.stderr
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    # The run is recorded as a tombstone, not erased: no heading, no placeholders.
    assert f"> Dropped run {first['run_id']} ({DAY})" in log
    assert log.count(LOG_PLACEHOLDER) == 1
    assert _day_headings(assess_dir) == 1
    assert verify_log_chain(assess_dir) == (True, None)
    finalize_run(assess_dir=assess_dir)
    assert _day_headings(assess_dir) == 1
    assert verify_log_chain(assess_dir) == (True, None)

    # A finalized entry is history: --drop-entry refuses it.
    refused = subprocess.run(
        [sys.executable, str(script), str(repo), "--drop-entry", second["run_id"]],
        capture_output=True, text=True,
    )
    assert refused.returncode == 1
    assert "finalized" in refused.stderr


def test_finalize_refuses_stamped_log_without_this_runs_entry(repo: Path) -> None:
    """In a stamped log, a run whose entry is missing must not fall back to
    filling another run's unfilled entry."""
    assess_dir = repo / ".assess"
    other = _run(repo)
    before = (assess_dir / "log.md").read_text(encoding="utf-8")
    _stage_finalize(assess_dir, other["run_id"])
    ctx_path = assess_dir / "run-context.json"
    ctx = json.loads(ctx_path.read_text(encoding="utf-8"))
    ctx["run_id"] = "20260918000000-deadbeef"
    ctx_path.write_text(json.dumps(ctx), encoding="utf-8")
    fi = assess_dir / ".cache" / "finalize-input.json"
    fi.write_text(fi.read_text(encoding="utf-8").replace(other["run_id"], ctx["run_id"]), encoding="utf-8")
    with pytest.raises(FinalizeValidationError, match="no entry stamped"):
        finalize_run(assess_dir=assess_dir)
    assert (assess_dir / "log.md").read_text(encoding="utf-8") == before


def test_core_replaces_superseded_same_day_entry_without_git(tmp_path: Path) -> None:
    """A target with no git has no commit to key on; two same-day runs still
    replace rather than stack, so finalize is not blocked."""
    root = tmp_path / "plain"
    (root / "src").mkdir(parents=True)
    (root / "src" / "hot.py").write_text("def hot(a):\n    return a\n", encoding="utf-8")
    first = build_run_context(repo_root=root, run_date=DAY, non_interactive=True)
    assert first["measured_commit"]["available"] is False
    second = build_run_context(repo_root=root, run_date=DAY, non_interactive=True)
    assess_dir = root / ".assess"
    assert _day_headings(assess_dir) == 1
    assert second["run_id"] in (assess_dir / "log.md").read_text(encoding="utf-8")
    assert verify_log_chain(assess_dir) == (True, None)


_LEGACY_LOG = (
    "# Assess Log\n\n"
    "## 2026-05-01\n\n"
    "- **Files scored:** 80\n"
    "- **AI Readiness:** 5.0 / 8 (Solid)\n\n"
    "---\n"
)


def test_superseded_same_day_entry_keeps_pre_chain_history(repo: Path) -> None:
    """A pre-chain log's body and the first chained entry parse as one span;
    superseding must not remove it, or the legacy history goes with it."""
    assess_dir = repo / ".assess"
    (assess_dir / "log.md").write_text(_LEGACY_LOG, encoding="utf-8")
    first = _run(repo)
    _run(repo)
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    assert "## 2026-05-01" in log
    assert first["run_id"] in log
    assert _day_headings(assess_dir) == 2
    assert verify_log_chain(assess_dir) == (True, None)


def test_drop_entry_refuses_span_holding_pre_chain_history(repo: Path) -> None:
    from assess_finalize import drop_unfinalized_entry

    assess_dir = repo / ".assess"
    (assess_dir / "log.md").write_text(_LEGACY_LOG, encoding="utf-8")
    first = _run(repo)
    before = (assess_dir / "log.md").read_text(encoding="utf-8")
    with pytest.raises(FinalizeValidationError, match="before the integrity chain"):
        drop_unfinalized_entry(assess_dir=assess_dir, run_id=first["run_id"])
    assert (assess_dir / "log.md").read_text(encoding="utf-8") == before


def test_earlier_same_date_placeholder_without_run_id_does_not_block_finalize(repo: Path) -> None:
    """An unstamped earlier entry cannot be dropped by id; refusing on it would
    leave finalize with no way out, so it stays as history and finalize fills
    this run's entry."""
    from lib.wiki_writer import LogEntry, append_log_entry

    assess_dir = repo / ".assess"
    append_log_entry(assess_dir, LogEntry(
        run_date=DAY, files_scored=1, readiness_score=0.0,
        maturity_label=LOG_PLACEHOLDER, instructions_grade=None,
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="Deterministic ranker not yet wired (LLM picks Top 3)",
    ))
    ctx = _run(repo)
    _stage_finalize(assess_dir, ctx["run_id"])
    finalize_run(assess_dir=assess_dir)
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    assert log.count(LOG_PLACEHOLDER) == 1
    assert "fixture action" in log
    assert verify_log_chain(assess_dir) == (True, None)

"""The assess-pr no-contributions scan: extract the marked bash block and run it.

The scan decides whether the end-of-run PR offer may target the upstream repo.
It lives as bash inside skills/assess-pr/SKILL.md, so the test drives the exact
text an agent would run rather than a paraphrase of it.
"""
from __future__ import annotations

import re
import shutil
import subprocess
from pathlib import Path

import pytest

ASSESS_PR_SKILL = Path(__file__).resolve().parents[2] / "assess-pr" / "SKILL.md"
START = "# no-contributions scan: start"
END = "# no-contributions scan: end"
STATEMENT = "This repository does not accept contributions. Please do not send a pull request."


def _scan_block() -> str:
    lines = ASSESS_PR_SKILL.read_text(encoding="utf-8").splitlines()
    start = lines.index(START)
    end = lines.index(END)
    assert end - start >= 2, "scan block must hold at least one line of bash"
    return "\n".join(lines[start : end + 1]) + "\n"


def _run_scan(repo_root: Path, var: str = "NO_CONTRIBUTIONS") -> str:
    script = f'REPO_ROOT="{repo_root}"\n{_scan_block()}printf %s "${var}"\n'
    result = subprocess.run(
        ["sh", "-c", script], capture_output=True, text=True, check=True
    )
    assert result.stderr == ""
    return result.stdout


@pytest.mark.parametrize(
    "files, expected",
    [
        ({"README.md": f"# App\n{STATEMENT}\n"}, "1"),
        ({"README.md": "# App\n", "CONTRIBUTING.md": f"# Contributing\n{STATEMENT}\n"}, "1"),
        ({"README.md": "# App\nContributions are welcome. Please open a pull request.\n"}, "0"),
        ({"README.md": "# App\nWe are not accepting pull requests at this time.\n"}, "1"),
        ({"README.md": "# App\nPull requests are not accepted.\n"}, "1"),
        ({"README.md": "# App\nPRs welcome! See CONTRIBUTING.md.\n"}, "0"),
        ({"README.md": "# App\nWe cannot accept contributions.\n"}, "1"),
        ({"README.md": "# App\nSorry, we can't accept pull requests.\n"}, "1"),
        ({"README.md": "# App\nThe team is unable to accept external contributions.\n"}, "1"),
        ({"README.md": "# App\nWe don\u2019t accept pull requests.\n"}, "1"),
        ({"README.md": "# App\nThis project does not accept unsolicited pull requests.\n"}, "1"),
        ({"CONTRIBUTING.md": "Please do not open a pull request without first opening an issue.\n"}, "0"),
        ({"CONTRIBUTING.md": "Do not submit a PR until all tests pass locally.\n"}, "0"),
        ({"CONTRIBUTING.md": "Please don't open a PR directly against main.\n"}, "0"),
        ({"CONTRIBUTING.md": "PRs are not accepted without a linked issue.\n"}, "0"),
        ({"CONTRIBUTING.md": "Please do not open a pull request for trivial typo fixes.\n"}, "0"),
        ({"CONTRIBUTING.md": "Do not submit a PR with unrelated changes.\n"}, "0"),
        ({"CONTRIBUTING.md": "Do not open a pull request from a fork of a fork.\n"}, "0"),
        ({"CONTRIBUTING.md": "Do not open PRs to the release branch.\n"}, "0"),
        ({"CONTRIBUTING.md": "Do not open a pull request if you have not signed the CLA.\n"}, "0"),
        ({"README.md": "# App\nDo not open a pull request; open an issue instead.\n"}, "1"),
        ({"README.md": "# App\nPlease don't send PRs\n"}, "1"),
        ({"README.md": "# App\nWe are not currently accepting contributions.\n"}, "1"),
        ({"README.md": "# App\nWe are not accepting new contributions.\n"}, "1"),
        ({"README.md": "# App\nThis repo does not accept community contributions.\n"}, "1"),
        ({"README.md": "# App\nThis repo does not accept a pull request from anyone.\n"}, "1"),
        # Word boundary after the noun: "prs?" must not match the start of an
        # ordinary word once the modifier slot lets any word precede it.
        ({"README.md": "# App\nContributions welcome! The API does not accept a promise, only a value.\n"}, "0"),
        ({"README.md": "# App\nThis endpoint does not accept preflight requests.\n"}, "0"),
        ({"README.md": "# App\nWe do not accept private forks of the config.\n"}, "0"),
        ({"README.md": "# App\nThe daemon does not accept process signals.\n"}, "0"),
        ({"README.md": "# App\nThe loader does not accept project files.\n"}, "0"),
        ({"README.md": "# App\nThe CLI does not accept provided defaults.\n"}, "0"),
        ({"README.md": "# App\nWe do not accept prior versions of the schema.\n"}, "0"),
        ({"README.md": "# App\nDo not open private issues.\n"}, "0"),
        ({"README.md": "# App\nWe do not accept PRs.\n"}, "1"),
        ({"README.md": "# App\nWe are not accepting PRs right now.\n"}, "1"),
        ({"README.md": "# App\nWe do not accept PRs\n"}, "1"),
        ({}, "0"),
    ],
    ids=["readme", "contributing", "welcome", "not-accepting-prs", "prs-not-accepted",
         "prs-welcome", "cannot", "cant", "unable-to", "curly-apostrophe", "unsolicited",
         "cond-without", "cond-until", "cond-directly", "cond-accepted-without", "cond-for", "cond-with", "cond-from", "cond-to", "cond-if",
         "imperative-semicolon", "imperative-eol", "not-currently-accepting", "not-accepting-new",
         "community-contributions", "singular-pull-request",
         "fp-promise", "fp-preflight", "fp-private", "fp-process", "fp-project", "fp-provide",
         "fp-prior", "fp-imperative-private", "accept-prs-dot", "accepting-prs-right-now",
         "accept-prs-eol", "no-docs"],
)
def test_scan_sets_no_contributions(tmp_path: Path, files: dict[str, str], expected: str) -> None:
    for name, body in files.items():
        (tmp_path / name).write_text(body, encoding="utf-8")
    assert _run_scan(tmp_path) == expected


def test_scan_keeps_the_matching_file_and_statement(tmp_path: Path) -> None:
    (tmp_path / "README.md").write_text("# App\n", encoding="utf-8")
    (tmp_path / "CONTRIBUTING.md").write_text(f"# Contributing\n{STATEMENT}\n", encoding="utf-8")
    assert _run_scan(tmp_path, "NO_CONTRIBUTIONS_SOURCE") == "CONTRIBUTING.md"
    assert _run_scan(tmp_path, "NO_CONTRIBUTIONS_STATEMENT") == STATEMENT


def test_scan_reads_github_contributing_with_its_relative_path(tmp_path: Path) -> None:
    (tmp_path / ".github").mkdir()
    (tmp_path / ".github" / "CONTRIBUTING.md").write_text(f"{STATEMENT}\n", encoding="utf-8")
    assert _run_scan(tmp_path) == "1"
    assert _run_scan(tmp_path, "NO_CONTRIBUTIONS_SOURCE") == ".github/CONTRIBUTING.md"


def test_scan_reads_docs_contributing_with_its_relative_path(tmp_path: Path) -> None:
    # GitHub also recognises docs/CONTRIBUTING.md; a refusal stated only there
    # must still suppress the fork-to-upstream offer.
    (tmp_path / "README.md").write_text("# App\n", encoding="utf-8")
    (tmp_path / "docs").mkdir()
    (tmp_path / "docs" / "CONTRIBUTING.md").write_text(f"{STATEMENT}\n", encoding="utf-8")
    assert _run_scan(tmp_path) == "1"
    assert _run_scan(tmp_path, "NO_CONTRIBUTIONS_SOURCE") == "docs/CONTRIBUTING.md"


def test_phase_2_variant_is_scoped_to_read_only_targets() -> None:
    text = ASSESS_PR_SKILL.read_text(encoding="utf-8")
    phase2 = text.split("## Phase 2", 1)[1].split("## Step 5", 1)[0]
    bullet = next(line for line in phase2.splitlines() if "no-contributions" in line)
    tail = bullet.split("offer the fork variant instead.", 1)[1]
    assert "read-only" in tail


def test_no_contributions_flow_never_references_the_upstream_pr_step() -> None:
    step5 = _step5()
    flow = step5.split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    assert "steps 1-2" not in flow
    assert "gh pr create --repo <owner>/<repo>" not in flow
    # The PR is created on the fork's own endpoint, never via a base-repo lookup.
    assert "repos/$FORK_SLUG/pulls" in flow


def test_reusing_the_current_fork_needs_push_access() -> None:
    # A READ clone of someone else's fork is also IS_FORK=true; it must fork
    # again rather than push to a repo the user cannot write to.
    flow = _step5().split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    assert "`IS_OWN_FORK=true` and `CAN_PUSH=1`" in flow


def _own_fork_block() -> str:
    lines = _step5().splitlines()
    start = next(i for i, line in enumerate(lines) if line.startswith("VIEWER_LC="))
    end = next(i for i in range(start, len(lines)) if lines[i] == "fi")
    return "\n".join(lines[start : end + 1]) + "\n"


@pytest.mark.parametrize(
    "viewer, owner, is_fork, expected",
    [
        ("alice", "alice", "true", "true"),
        ("Alice", "alice", "true", "true"),
        # Push-capable collaborator on another user's fork: not their fork.
        ("bob", "alice", "true", "false"),
        ("alice", "alice", "false", "false"),
        # gh api user failed: never assume ownership.
        ("", "alice", "true", "false"),
    ],
    ids=["own", "own-case", "collaborator", "not-a-fork", "no-viewer"],
)
def test_is_own_fork_compares_viewer_with_fork_owner(
    tmp_path: Path, viewer: str, owner: str, is_fork: str, expected: str
) -> None:
    fake = tmp_path / "gh"
    body = f"echo '{{\"login\": \"{viewer}\"}}'" if viewer else "exit 1"
    fake.write_text(f"#!/bin/sh\n{body}\n", encoding="utf-8")
    fake.chmod(0o755)
    push_info = f'{{"isFork": {is_fork}, "owner": {{"login": "{owner}"}}}}'
    script = f"IS_FORK={is_fork}\nPUSH_INFO='{push_info}'\n{_own_fork_block()}printf %s \"$IS_OWN_FORK\"\n"
    result = subprocess.run(
        ["sh", "-c", script], capture_output=True, text=True, check=True,
        env={"PATH": f"{tmp_path}:/usr/bin:/bin:/opt/homebrew/bin:/usr/local/bin"},
    )
    assert result.stdout == expected


def test_reusing_the_current_fork_needs_the_viewer_to_own_it() -> None:
    step5 = _step5()
    assert "owner" in step5.split("PUSH_INFO=", 1)[1].split("\n", 1)[0]
    flow = step5.split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    assert "any clone of someone else's fork, whatever the permission" in flow
    assert "skipping its fork step" not in step5


def test_fork_pr_is_based_on_what_was_assessed() -> None:
    # A pre-existing fork's default branch can differ from the assessed
    # checkout; the PR must not carry the commits in between.
    flow = _step5().split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    pulls = flow.index("repos/$FORK_SLUG/pulls")
    for needle in ("BASE_SHA=", "assess/base-<YYYY-MM-DD>", "tell the user"):
        assert needle in flow[:pulls], needle
    assert flow.index("BASE_SHA=") < flow.index("FORK_BRANCH=assess/base-")


def test_fork_pr_url_check_is_host_agnostic() -> None:
    flow = _step5().split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    assert "https://github.com/$FORK_SLUG" not in flow
    assert "/$FORK_SLUG/pull/<number>" in flow


def test_fork_pr_body_file_is_written_before_it_is_used() -> None:
    flow = _step5().split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    assert flow.index("<body-file>") < flow.index("body=@<body-file>")
    assert "temp file" in flow[: flow.index("body=@<body-file>")]


def test_fork_slug_is_derived_not_guessed() -> None:
    step5 = _step5()
    assert "<fork-owner>" not in step5
    flow = step5.split("(no-contributions flow,", 1)[1].split("\n\n", 1)[0]
    assert "FORK_SLUG=" in flow
    assert "repos/$FORK_SLUG/actions/permissions" in flow


def test_fork_clone_of_a_no_contributions_repo_stays_in_the_fork() -> None:
    # In a clone of the user's own fork, viewerPermission is ADMIN (CAN_PUSH=1)
    # and a bare `gh pr create` targets the parent: the statement must still win.
    step5 = _step5()
    assert "isFork" in step5.split("PUSH_INFO=", 1)[1].split("\n", 1)[0]
    assert "IS_FORK=" in step5
    direct = next(line for line in step5.splitlines() if line.startswith("- `CAN_PUSH=1`"))
    assert "IS_FORK=true" in direct and "no-contributions flow" in direct
    flow_head = step5.split("(no-contributions flow,", 1)[1].split("\n", 1)[0]
    assert "IS_FORK=true" in flow_head


def test_scan_leaves_source_empty_without_a_statement(tmp_path: Path) -> None:
    (tmp_path / "README.md").write_text("# App\nPRs welcome!\n", encoding="utf-8")
    assert _run_scan(tmp_path, "NO_CONTRIBUTIONS_SOURCE") == ""
    assert _run_scan(tmp_path, "NO_CONTRIBUTIONS_STATEMENT") == ""


def test_push_capable_user_is_told_about_the_statement() -> None:
    text = ASSESS_PR_SKILL.read_text(encoding="utf-8")
    step5 = text.split("## Step 5", 1)[1].split("## Step 6", 1)[0]
    direct = next(line for line in step5.splitlines() if line.startswith("- `CAN_PUSH=1`"))
    assert "NO_CONTRIBUTIONS=1" in direct and "NO_CONTRIBUTIONS_SOURCE" in direct


def _step5() -> str:
    text = ASSESS_PR_SKILL.read_text(encoding="utf-8")
    return text.split("## Step 5", 1)[1].split("## Step 6", 1)[0]


def test_no_contributions_offer_needs_a_github_permission() -> None:
    # CAN_PUSH is 0 both for READ/TRIAGE and when gh returned nothing; only the
    # former can fork, so the no-contributions bullet must name the permission.
    bullet = next(line for line in _step5().splitlines()
                  if line.startswith("- `CAN_PUSH=0`") and "NO_CONTRIBUTIONS=1" in line)
    assert "`READ` / `TRIAGE`" in bullet
    no_remote = next(line for line in _step5().splitlines() if "`$PUSH_INFO` empty" in line)
    assert "every PR offer" in no_remote


def test_pr_body_template_is_shared_by_every_flow() -> None:
    step5 = _step5()
    flows = [m.start() for m in re.finditer(r"If the user \*\*selected the PR offer\*\*", step5)]
    assert len(flows) == 3
    footer = step5.index("plugin reference at the bottom")
    assert footer > flows[-1]
    footer_line = step5[: footer].rsplit("\n", 1)[1]
    assert not re.match(r"\s*\d+\.", footer_line), "template must not be a step of one flow"
    for name in ("direct", "fork", "no-contributions"):
        assert name in step5[step5.rfind("\n", 0, footer) : step5.index("\n", footer)]


def test_each_flow_numbers_its_steps_once() -> None:
    step5 = _step5()
    for block in re.split(r"If the user \*\*selected the PR offer\*\*", step5)[1:]:
        numbers = [int(n) for n in re.findall(r"^(\d+)\. ", block.split("\n\n", 1)[0], re.M)]
        assert numbers == list(range(1, len(numbers) + 1)), numbers


def test_scan_sits_in_step_5_before_the_offer_text() -> None:
    text = ASSESS_PR_SKILL.read_text(encoding="utf-8")
    step5 = text.split("## Step 5", 1)[1].split("## Step 6", 1)[0]
    assert START in step5 and END in step5
    assert step5.index(END) < step5.index("Interpret the result")


def test_step_5_replaces_upstream_offer_when_flag_is_set() -> None:
    text = ASSESS_PR_SKILL.read_text(encoding="utf-8")
    step5 = text.split("## Step 5", 1)[1].split("## Step 6", 1)[0]
    lowered = step5.lower()
    assert step5.count("NO_CONTRIBUTIONS") >= 3
    for phrase in ("inside your fork", "fork's default branch", "share the link"):
        assert phrase in lowered, phrase
    assert re.search(r"disabl[a-z]* actions", lowered)
    # The ordinary fork-to-upstream flow stays for READ/TRIAGE with no statement.
    assert "gh pr create --repo <owner>/<repo>" in step5
    phase2 = text.split("## Phase 2", 1)[1].split("## Step 5", 1)[0]
    assert "no-contributions" in phase2.lower()


@pytest.mark.skipif(shutil.which("zsh") is None, reason="zsh not installed")
@pytest.mark.parametrize("body, expected", [(STATEMENT, "1"), ("PRs welcome!", "0")])
def test_scan_runs_under_zsh(tmp_path: Path, body: str, expected: str) -> None:
    # Agents often run the block in the user's zsh, where an unbraced
    # "$var[" is a subscript, not a variable followed by a bracket class.
    (tmp_path / "README.md").write_text(f"# App\n{body}\n", encoding="utf-8")
    script = f'REPO_ROOT="{tmp_path}"\n{_scan_block()}printf %s "$NO_CONTRIBUTIONS"\n'
    result = subprocess.run(["zsh", "-c", script], capture_output=True, text=True, check=True)
    assert result.stderr == ""
    assert result.stdout == expected

"""Contract suite for the ownership-map parser.

The parser turns the two declaration formats - GitHub ``CODEOWNERS`` (glob ->
owner) and a boundary-declaring markdown doc (``ARCHITECTURE.md`` / a seam-map
``README.md``) - into ``{declared_boundary: {matched_file_paths}}`` maps, and
flags the globs that already match zero files. These tests pin that behaviour
plus the two contracts the structure-drift signals depend on: deterministic,
byte-identical output run to run, and honest degradation (missing / malformed
input never crashes the assessment).

Fixtures build small repos in ``tmp_path``. CODEOWNERS resolution is against the
*tracked* file set, so a fixture that asserts on matched files commits them; a
fixture that only exercises parsing of patterns need not. Ambient git config is
neutralised process-wide by the package ``conftest.py``.
"""
from __future__ import annotations

import os
import subprocess
from pathlib import Path

from lib.ownership_parser import (
    find_empty_globs,
    is_glob,
    parse_architecture_md,
    parse_codeowners,
    parse_ownership,
)


def _git(repo: Path, *args: str) -> None:
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True,
                   env={**os.environ})


def _init_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "dev@example.com")
    _git(repo, "config", "user.name", "Dev")
    return repo


def _write(repo: Path, rel: str, text: str = "x\n") -> None:
    p = repo / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _commit_all(repo: Path, message: str = "c") -> None:
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", message)


def _matched_strs(files: set[Path]) -> set[str]:
    return {p.as_posix() for p in files}


# --- 1. CODEOWNERS parsing ---------------------------------------------------

def test_codeowners_multi_owner_comments_and_globs(tmp_path: Path) -> None:
    """A CODEOWNERS with multi-owner lines, comments, and globs parses cleanly.

    The parser keeps the glob pattern (the declared boundary), drops comment and
    blank lines, and ignores the owner tokens. Patterns are resolved against the
    tracked file set: ``*.js`` claims the two committed JS files, ``docs/`` claims
    everything under ``docs``, and ``src/**/*.py`` claims the nested python file.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "a.js")
    _write(repo, "b.js")
    _write(repo, "src/pkg/mod.py")
    _write(repo, "docs/guide.md")
    _write(repo, "docs/api/ref.md")
    _write(repo, "README.md")
    _write(repo, "CODEOWNERS", "\n".join([
        "# top comment",
        "",
        "*.js   @frontend @web-team",
        "docs/  @docs-team",
        "src/**/*.py  @backend",
        "  # indented comment",
    ]) + "\n")
    _commit_all(repo)

    owners = parse_codeowners(repo)

    assert set(owners) == {"*.js", "docs/", "src/**/*.py"}
    assert _matched_strs(owners["*.js"]) == {"a.js", "b.js"}
    assert _matched_strs(owners["docs/"]) == {"docs/guide.md", "docs/api/ref.md"}
    assert _matched_strs(owners["src/**/*.py"]) == {"src/pkg/mod.py"}


def test_codeowners_anchored_and_bare_pattern_depth(tmp_path: Path) -> None:
    """A leading ``/`` anchors to root; a bare name matches at any depth.

    ``/config.yml`` matches only the root file, not the nested one. A bare
    ``Makefile`` (no slash, unanchored) matches at any depth - GitHub semantics.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "config.yml")
    _write(repo, "sub/config.yml")
    _write(repo, "Makefile")
    _write(repo, "tools/Makefile")
    _write(repo, "CODEOWNERS", "/config.yml @a\nMakefile @b\n")
    _commit_all(repo)

    owners = parse_codeowners(repo)
    assert _matched_strs(owners["/config.yml"]) == {"config.yml"}
    assert _matched_strs(owners["Makefile"]) == {"Makefile", "tools/Makefile"}


def test_codeowners_duplicate_pattern_is_unioned(tmp_path: Path) -> None:
    """The same pattern on two lines unions its match set rather than overwriting."""
    repo = _init_repo(tmp_path)
    _write(repo, "x.py")
    _write(repo, "CODEOWNERS", "*.py @a\n*.py @b\n")
    _commit_all(repo)

    owners = parse_codeowners(repo)
    assert set(owners) == {"*.py"}
    assert _matched_strs(owners["*.py"]) == {"x.py"}


def test_codeowners_respects_gitignore(tmp_path: Path) -> None:
    """An ignored file never counts toward a glob's match set.

    ``tracked_files`` is the file universe, so a ``*.py`` glob over a repo with a
    gitignored ``secret.py`` claims only the tracked python file.
    """
    repo = _init_repo(tmp_path)
    _write(repo, ".gitignore", "secret.py\n")
    _write(repo, "kept.py")
    _write(repo, "secret.py")  # ignored, never tracked
    _write(repo, "CODEOWNERS", "*.py @a\n")
    _commit_all(repo)

    owners = parse_codeowners(repo)
    assert _matched_strs(owners["*.py"]) == {"kept.py"}


def test_codeowners_in_github_dir_is_found(tmp_path: Path) -> None:
    """``.github/CODEOWNERS`` is honoured - GitHub's standard location."""
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _write(repo, ".github/CODEOWNERS", "*.py @a\n")
    _commit_all(repo)

    owners = parse_codeowners(repo)
    assert _matched_strs(owners["*.py"]) == {"a.py"}


# --- 2. ARCHITECTURE.md parsing ----------------------------------------------

def test_architecture_md_module_extraction(tmp_path: Path) -> None:
    """Section headers name modules; their path references resolve to files.

    Two ``##`` sections each declare a module owning a directory and naming files
    in inline code. The parser attributes each section's references to that
    section's header (keyed ``<doc>::<header>``) and resolves directory and bare
    references to the tracked files.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/api/server.py")
    _write(repo, "src/api/routes.py")
    _write(repo, "src/db/models.py")
    _write(repo, "ARCHITECTURE.md", "\n".join([
        "# System",
        "",
        "## API layer",
        "The API module owns `src/api/` and exposes the HTTP surface.",
        "",
        "## Data layer",
        "The data module owns `src/db/models.py`.",
    ]) + "\n")
    _commit_all(repo)

    modules = parse_architecture_md(repo)
    api = modules["ARCHITECTURE.md::API layer"]
    data = modules["ARCHITECTURE.md::Data layer"]
    assert _matched_strs(api) == {"src/api/server.py", "src/api/routes.py"}
    assert _matched_strs(data) == {"src/db/models.py"}


def test_architecture_md_ignores_fenced_code_paths(tmp_path: Path) -> None:
    """Paths inside a fenced code block are samples, not boundary declarations.

    A fenced listing of a path the module does *not* own must not be attributed
    to it - only the inline-code reference in prose counts.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/real.py")
    _write(repo, "examples/sample.py")
    _write(repo, "DESIGN.md", "\n".join([
        "## Core",
        "The core module owns `src/real.py`.",
        "",
        "```",
        "examples/sample.py  # illustrative only",
        "```",
    ]) + "\n")
    _commit_all(repo)

    modules = parse_architecture_md(repo)
    core = modules["DESIGN.md::Core"]
    assert _matched_strs(core) == {"src/real.py"}
    assert all("sample.py" not in str(p) for files in modules.values() for p in files)


def test_architecture_readme_only_when_it_declares_boundaries(tmp_path: Path) -> None:
    """A generic README is skipped; a seam-declaring README is parsed.

    A README without ownership/seam vocabulary contributes no module. A README
    whose prose declares module ownership does, so a repo carrying its boundary
    map in a README (rather than ARCHITECTURE.md) is still read.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "lib/core.py")
    _write(repo, "plain/README.md", "Just a project. Run `make`.\n")
    _write(repo, "lib/README.md", "\n".join([
        "## Module reference",
        "The core module owns `lib/core.py` - this seam is owned by design.",
    ]) + "\n")
    _commit_all(repo)

    modules = parse_architecture_md(repo)
    keys = set(modules)
    assert any(k.startswith("lib/README.md::") for k in keys)
    assert not any(k.startswith("plain/README.md::") for k in keys)


def test_architecture_wikilink_references_resolve(tmp_path: Path) -> None:
    """A ``[[wikilink]]`` path reference resolves to its tracked file."""
    repo = _init_repo(tmp_path)
    _write(repo, "docs/payments.md")
    _write(repo, "ARCHITECTURE.md", "\n".join([
        "## Payments",
        "The payments module owns [[docs/payments.md]].",
    ]) + "\n")
    _commit_all(repo)

    modules = parse_architecture_md(repo)
    assert _matched_strs(modules["ARCHITECTURE.md::Payments"]) == {"docs/payments.md"}


# --- 3. Empty-glob detection -------------------------------------------------

def test_find_empty_globs_flags_zero_match_patterns(tmp_path: Path) -> None:
    """A glob matching no tracked file is reported; a matching one is not.

    ``*.py`` matches the committed file; ``legacy/**`` matches nothing (the
    directory is gone). Only the latter surfaces, with its declared source.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _write(repo, "CODEOWNERS", "*.py @a\nlegacy/** @b\n")
    _commit_all(repo)

    owners = parse_codeowners(repo)
    empties = find_empty_globs(owners)
    assert empties == [{"pattern": "legacy/**", "declared_in": "CODEOWNERS"}]


def test_find_empty_globs_is_sorted(tmp_path: Path) -> None:
    """Empty globs are returned sorted by pattern for deterministic output."""
    owners = {
        "z/**": set(),
        "a/**": set(),
        "m.py": {Path("m.py")},  # matches - excluded
        "k/**": set(),
    }
    empties = find_empty_globs(owners)
    assert [e["pattern"] for e in empties] == ["a/**", "k/**", "z/**"]


def test_is_glob_classification() -> None:
    """Wildcard and directory patterns are globs; a literal file path is not."""
    assert is_glob("*.py")
    assert is_glob("src/**/*.ts")
    assert is_glob("docs/")  # trailing slash = directory
    assert is_glob("a[bc].py")
    assert not is_glob("README.md")
    assert not is_glob("src/main.py")


# --- 4. Graceful degradation -------------------------------------------------

def test_no_ownership_map_degrades(tmp_path: Path) -> None:
    """A repo with no CODEOWNERS and no boundary doc reports no ownership map."""
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _commit_all(repo)

    assert parse_codeowners(repo) == {}
    assert parse_architecture_md(repo) == {}

    summary = parse_ownership(repo)
    assert summary["available"] is False
    assert summary["reason"] == "no ownership map"
    assert summary["codeowners_globs"] == []
    assert summary["architecture_modules"] == []
    assert summary["empty_globs"] == []


def test_malformed_codeowners_line_is_skipped(tmp_path: Path) -> None:
    """A blank-ish / comment-only file parses to an empty map, never raises.

    Comment and blank lines carry no pattern; a file of only those yields an
    empty (but available-elsewhere) parse rather than crashing.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _write(repo, "CODEOWNERS", "# only comments\n\n   \n")
    _commit_all(repo)

    assert parse_codeowners(repo) == {}


def test_non_git_directory_resolves_via_filesystem(tmp_path: Path) -> None:
    """Outside git, the glob resolver falls back to a filesystem walk.

    No git history means ``tracked_files`` is None; the parser walks the tree
    (with the same excludes + symlink guard) so a CODEOWNERS still resolves.
    """
    plain = tmp_path / "plain"
    plain.mkdir()
    (plain / "a.py").write_text("x\n", encoding="utf-8")
    (plain / "CODEOWNERS").write_text("*.py @a\n", encoding="utf-8")

    owners = parse_codeowners(plain)
    assert _matched_strs(owners["*.py"]) == {"a.py"}


# --- 5. Determinism ----------------------------------------------------------

def test_parse_ownership_is_byte_identical_across_runs(tmp_path: Path) -> None:
    """Two parses of one repo serialize to identical output.

    Sets are sorted at the boundary, so no iteration order leaks. Serialising the
    full summary twice and asserting equality pins the determinism contract the
    structure-drift signals rely on.
    """
    import json

    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "src/b.py")
    _write(repo, "docs/x.md")
    _write(repo, "CODEOWNERS", "src/** @a\ndocs/ @b\nghost/** @c\n")
    _write(repo, "ARCHITECTURE.md", "## Core\nowns `src/`\n")
    _commit_all(repo)

    first = json.dumps(parse_ownership(repo), sort_keys=True)
    second = json.dumps(parse_ownership(repo), sort_keys=True)
    assert first == second

    summary = parse_ownership(repo)
    assert summary["available"] is True
    assert {e["pattern"] for e in summary["empty_globs"]} == {"ghost/**"}


# --- 6. Integration: this repo's own seam map --------------------------------

def test_integration_parses_lib_readme_seam_declaration() -> None:
    """Parsing this repo finds the lib README's co-change seam declaration.

    ``skills/assess/scripts/lib/README.md`` declares the module-ownership seam
    map (the ``assess_core.py -> lib`` seam and the wider co-change seams). Its
    boundary-declaring prose admits it as an architecture doc, and its seam
    section names ``doc_graph.py`` as a load-bearing module, which resolves to
    the real tracked file. This is the dogfood guard that the parser reads a
    genuine, human-written ownership declaration on real data.
    """
    repo_root = Path(__file__).resolve().parents[3]  # repo top
    modules = parse_architecture_md(repo_root)

    lib_readme = "skills/assess/scripts/lib/README.md"
    lib_sections = {k: v for k, v in modules.items() if k.startswith(lib_readme + "::")}
    assert lib_sections, "lib README should be parsed as a boundary declaration"

    # The seam map names doc_graph.py; it resolves to the real module file.
    resolved = {p.as_posix() for files in lib_sections.values() for p in files}
    assert "skills/assess/scripts/lib/doc_graph.py" in resolved


def test_extract_path_refs_suffixes_default_and_widened() -> None:
    """Slash-free spans count only with a listed suffix: the default keeps
    `.md` / `.py` (so prose naming `.mdx` is no stale-reference finding), and
    the doc graph widens it to every doc extension."""
    from lib.ownership_parser import _extract_path_refs
    seg = "we render `.mdx` pages; see `guide.mdx` and `notes.md`"
    assert _extract_path_refs(seg) == {"notes.md"}
    assert _extract_path_refs(seg, (".md", ".mdx")) == {".mdx", "guide.mdx", "notes.md"}

"""Tests for the promissory-marker scan (stale TODOs, suppressions, skips).

Fixtures build synthetic git histories in tmp dirs with explicit author dates
so survived-touches counts are deterministic. Expected values are hand-computed
in each test's comments so the contract is auditable.
"""
from __future__ import annotations

import os
import subprocess
from pathlib import Path

from lib.keyhole_signals import FINDING_ORDER, integrate
from lib.promissory_markers import (
    FAMILY_PATTERNS,
    MarkerScan,
    scan_promissory_markers,
)

_HUMAN = ("Dev One", "dev@example.com")
_AGENT = ("Claude", "claude[bot]@users.noreply.github.com")


def _git(repo: Path, *args: str, env: dict | None = None) -> None:
    full_env = {**os.environ, **(env or {})}
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True, env=full_env)


def _init_repo(repo: Path) -> None:
    repo.mkdir(parents=True, exist_ok=True)
    _git(repo, "init", "-q")
    _git(repo, "config", "user.name", _HUMAN[0])
    _git(repo, "config", "user.email", _HUMAN[1])


def _commit(
    repo: Path,
    files: dict[str, str],
    message: str = "change",
    *,
    day: int = 1,
    author: tuple[str, str] | None = None,
) -> None:
    """Commit files with a deterministic author date (2024-01-<day>)."""
    for rel, text in files.items():
        p = repo / rel
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(text, encoding="utf-8")
    _git(repo, "add", "-A")
    name, email = author or _HUMAN
    date = f"2024-01-{day:02d}T12:00:00"
    _git(
        repo, "commit", "-q", "-m", message,
        env={
            "GIT_AUTHOR_NAME": name, "GIT_AUTHOR_EMAIL": email,
            "GIT_COMMITTER_NAME": name, "GIT_COMMITTER_EMAIL": email,
            "GIT_AUTHOR_DATE": date, "GIT_COMMITTER_DATE": date,
        },
    )


def _scan(repo: Path, **kw) -> MarkerScan:
    scan = scan_promissory_markers(repo, **kw)
    assert scan.available, scan.reason
    return scan


# ---------------------------------------------------------------------------
# Detection + classification
# ---------------------------------------------------------------------------

def test_detects_all_four_families(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    _commit(repo, {
        "app.py": "# TODO fix this\nx = 1  # noqa: E501\n",
        "legacy.java": "// @Deprecated use NewThing\nclass A {}\n",
        "app_test.py": "import pytest\n@pytest.mark.skip\ndef test_x():\n    pass\n",
    }, day=1)
    scan = _scan(repo)
    families = {m.family for m in scan.markers}
    assert families == {"todo", "suppression", "deprecation", "disabled_test"}


def test_string_literal_todo_dropped_but_comment_kept(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    _commit(repo, {
        "app.py": 'msg = "TODO is a word"\n# TODO real one\n',
    }, day=1)
    scan = _scan(repo)
    todos = [m for m in scan.markers if m.family == "todo"]
    assert len(todos) == 1
    assert todos[0].line == 2


def test_case_sensitive_word_boundary() -> None:
    """A Dart toDouble() call must not match the todo family (regression:
    case-insensitive matching flagged every toDouble in a Flutter repo)."""
    import re
    assert not re.search(FAMILY_PATTERNS["todo"], "x = (y as num).toDouble()")


def test_linked_vs_bare_todo(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    _commit(repo, {
        "app.py": "# TODO(#123) tracked\n# TODO untracked\n# TODO JIRA-42 also tracked\n",
    }, day=1)
    scan = _scan(repo)
    s = scan.summary()
    assert s["todo_linked"] == 2
    assert s["todo_bare"] == 1


def test_justified_suppression_counts_as_linked(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    _commit(repo, {
        "a.go": "return nil //nolint:nilerr // error conveyed via response\n",
        "b.go": "return nil //nolint:nilerr\n",
    }, day=1)
    scan = _scan(repo)
    by_path = {m.path: m for m in scan.markers if m.family == "suppression"}
    assert by_path["a.go"].linked is True
    assert by_path["b.go"].linked is False


# One justified form per recognised syntax (issue #335), a bare suppression,
# and a bare TODO. Each file's marker line stays put while a second line
# changes on every commit, so every marker survives the later edits.
_JUSTIFIED_FORMS = {
    "src/sim.js": (
        "const pick = () => words[0]; // eslint-disable-line "
        "sonarjs/pseudo-random -- simulator only, not security-sensitive"
    ),
    "src/cli.js": "/* eslint-disable no-console -- CLI entry point prints by design */",
    "src/url.py": "URL = 1  # noqa: E501  # long URL kept on one line",
    "src/h.go": "x := run() //nolint:errcheck // error conveyed via response status",
    "src/G.java": '@SuppressWarnings("unchecked") // generic array creation is safe here',
}
_BARE_FORMS = {
    "src/bare.js": "console.log(1); // eslint-disable-line no-console",
    "src/todo.py": "# TODO tidy this up",
}


def _aged_marker_repo(repo: Path, lines: dict[str, str], *, edits: int) -> None:
    _init_repo(repo)
    for i in range(edits + 1):
        _commit(repo, {p: f"{t}\nv = {i}\n" for p, t in lines.items()}, day=1 + i)


def test_justified_not_stale_counts_each_recognised_form(tmp_path: Path) -> None:
    """Five justified suppressions survive 6 edits: all five are counted in
    ``families.suppression.justified`` and none is stale. The bare suppression
    and the bare TODO of the same age stay stale."""
    repo = tmp_path / "repo"
    _aged_marker_repo(repo, {**_JUSTIFIED_FORMS, **_BARE_FORMS}, edits=6)
    summary = _scan(repo).summary()
    suppression = summary["families"]["suppression"]
    assert suppression["total"] == 6
    assert suppression["justified"] == 5
    assert suppression["stale"] == 1
    assert set(summary["stale_by_file"]) == {"src/bare.js", "src/todo.py"}
    assert all(
        m["path"] not in _JUSTIFIED_FORMS for m in summary["top_offenders"]
    )


def test_justified_not_stale_keeps_file_out_of_unactioned_intent(
    tmp_path: Path,
) -> None:
    repo = tmp_path / "repo"
    _aged_marker_repo(repo, {**_JUSTIFIED_FORMS, **_BARE_FORMS}, edits=6)
    result = integrate(
        repo_root=repo, complexity_stats={}, doc_staleness={},
        dead_code={}, observability={}, structure={},
        promissory_markers=_scan(repo).summary(),
    )
    findings = {f["name"]: f for f in result["derived_findings"]}
    assert findings["unactioned_intent"]["paths"] == ["src/bare.js", "src/todo.py"]
    assert not {a["path"] for a in result["attention"]} & set(_JUSTIFIED_FORMS)


def test_linked_markers_of_other_families_still_go_stale(tmp_path: Path) -> None:
    """Only a justified suppression is exempt. A ticketed TODO, an expired
    dated deprecation and a ticketed skip still age: the promise can go stale
    while the reference stays, and the Layer 5 cap reads disabled_test.stale."""
    repo = tmp_path / "repo"
    _aged_marker_repo(repo, {
        "a.py": "# TODO(#123) tracked",
        "d.py": "# DEPRECATED: use v2, deadline 2019-06-01",
        "s.test.js": "it.skip('see JIRA-42', () => {});",
    }, edits=6)
    summary = _scan(repo).summary()
    fams = summary["families"]
    assert set(summary["stale_by_file"]) == {"a.py", "d.py", "s.test.js"}
    assert fams["todo"]["linked"] == fams["todo"]["stale"] >= 1
    assert fams["deprecation"]["linked"] == fams["deprecation"]["stale"] == 1
    assert fams["disabled_test"]["linked"] == fams["disabled_test"]["stale"] == 1
    assert all(row["justified"] == 0 for row in fams.values())


def test_bare_suppression_rule_names_with_hyphens_are_not_justified() -> None:
    """A hyphenated rule name is not a ``-- reason`` separator."""
    from lib.promissory_markers import JUSTIFIED_SUPPRESSION_RE
    assert not JUSTIFIED_SUPPRESSION_RE.search(
        "x; // eslint-disable-line @typescript-eslint/no-explicit-any"
    )
    assert not JUSTIFIED_SUPPRESSION_RE.search("/* eslint-disable no-console */")
    # Code after the block comment closes is not the directive's reason.
    assert not JUSTIFIED_SUPPRESSION_RE.search(
        '/* eslint-disable no-console */ const s = "a -- b";'
    )
    assert JUSTIFIED_SUPPRESSION_RE.search(
        "/* eslint-disable no-console */ // CLI prints by design"
    )
    assert JUSTIFIED_SUPPRESSION_RE.search(
        "// eslint-disable-next-line no-alert -- confirm is the UX here"
    )


def test_generated_and_prose_exclusions(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    _commit(repo, {
        # codegen boilerplate: never debt
        "model.g.dart": "// ignore_for_file: type=lint\n",
        # syntactic marker in prose: a code example, not debt
        "docs/guide.md": "Use t.Skip(\"reason\") to skip.\n",
        # prose TODO: real (docs carry intent too)
        "docs/plan.md": "TODO write the rollout section\n",
    }, day=1)
    scan = _scan(repo)
    paths_by_family = {
        fam: {m.path for m in scan.markers if m.family == fam}
        for fam in ("suppression", "disabled_test", "todo")
    }
    assert paths_by_family["suppression"] == set()
    assert paths_by_family["disabled_test"] == set()
    assert paths_by_family["todo"] == {"docs/plan.md"}


# ---------------------------------------------------------------------------
# Aging: survived touches
# ---------------------------------------------------------------------------

def _busy_repo_with_marker(repo: Path, *, edits_after: int) -> None:
    """Marker lands on day 2; `edits_after` later commits touch the same file.

    Three other files get two commits each so churn_is_degenerate() stays
    False (aging_reliable True) without inflating the marker file's count.
    """
    _init_repo(repo)
    _commit(repo, {"app.py": "x = 0\n", "a.py": "a", "b.py": "b", "c.py": "c"}, day=1)
    _commit(repo, {"app.py": "x = 0\n# FIXME handle zero\ny = 1\n"}, day=2)
    for i in range(edits_after):
        _commit(repo, {"app.py": f"x = {i + 1}\n# FIXME handle zero\ny = {i}\n"},
                day=3 + i)
    _commit(repo, {"a.py": "a2", "b.py": "b2", "c.py": "c2"}, day=20)


def test_survived_touches_counts_later_commits(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _busy_repo_with_marker(repo, edits_after=6)
    scan = _scan(repo)
    fixme = [m for m in scan.markers if m.family == "todo"][0]
    # 6 edits after the introducing commit; the introducing commit itself and
    # the day-1 commit don't count.
    assert fixme.survived_touches == 6
    assert fixme.path in scan.stale_by_file()
    assert scan.stale_by_file()["app.py"]["max_survived"] == 6


def test_fresh_marker_is_not_stale(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _busy_repo_with_marker(repo, edits_after=1)
    scan = _scan(repo)
    assert scan.stale_by_file() == {}
    assert scan.summary()["total_stale"] == 0


def test_degenerate_history_marks_aging_unreliable(tmp_path: Path) -> None:
    """Squashed-import shape (every file exactly one commit, many files): the
    scan still reports markers but flags aging as carrying no information."""
    repo = tmp_path / "repo"
    _init_repo(repo)
    files = {f"f{i}.py": f"# TODO item {i}\n" for i in range(12)}
    _commit(repo, files, day=1)
    scan = _scan(repo)
    assert scan.markers  # detection still works
    assert scan.aging_reliable is False


# ---------------------------------------------------------------------------
# Authorship
# ---------------------------------------------------------------------------

def test_agent_vs_human_introduction(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    _commit(repo, {"by_human.py": "# TODO human wrote this\n"}, day=1)
    _commit(repo, {"by_agent.py": "# TODO agent wrote this\n"}, day=2,
            author=_AGENT)
    scan = _scan(repo)
    by_path = {m.path: m for m in scan.markers}
    assert by_path["by_human.py"].agent_introduced is False
    assert by_path["by_agent.py"].agent_introduced is True


# ---------------------------------------------------------------------------
# Degrade contract + keyhole finding
# ---------------------------------------------------------------------------

def test_non_git_dir_degrades(tmp_path: Path) -> None:
    scan = scan_promissory_markers(tmp_path)
    assert scan.available is False
    assert "git" in scan.reason


def test_unactioned_intent_finding_in_integrate(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _busy_repo_with_marker(repo, edits_after=6)
    summary = _scan(repo).summary()
    result = integrate(
        repo_root=repo, complexity_stats={}, doc_staleness={},
        dead_code={}, observability={}, structure={},
        promissory_markers=summary,
    )
    findings = {f["name"]: f for f in result["derived_findings"]}
    assert "unactioned_intent" in findings
    assert findings["unactioned_intent"]["paths"] == ["app.py"]


def test_unactioned_intent_action_states_stale_threshold(tmp_path: Path) -> None:
    """The finding says how many edits a marker must survive to count as stale,
    so a reader can weigh a 6-edit suppression against a 65-edit TODO."""
    repo = tmp_path / "repo"
    _busy_repo_with_marker(repo, edits_after=6)
    summary = scan_promissory_markers(repo, stale_touches=4).summary()
    result = integrate(
        repo_root=repo, complexity_stats={}, doc_staleness={},
        dead_code={}, observability={}, structure={},
        promissory_markers=summary,
    )
    findings = {f["name"]: f for f in result["derived_findings"]}
    assert "survived 4 or more edits" in findings["unactioned_intent"]["action"]
    md = result["findings_markdown"]
    section = md.split("### unactioned_intent", 1)[1].split("### ", 1)[0]
    assert "survived 4 or more edits" in section


def test_unactioned_intent_silent_without_reliable_aging(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    _init_repo(repo)
    files = {f"f{i}.py": f"# TODO item {i}\n" for i in range(12)}
    _commit(repo, files, day=1)
    summary = _scan(repo).summary()
    assert summary["aging_reliable"] is False
    result = integrate(
        repo_root=repo, complexity_stats={}, doc_staleness={},
        dead_code={}, observability={}, structure={},
        promissory_markers=summary,
    )
    findings = {f["name"]: f for f in result["derived_findings"]}
    assert findings["unactioned_intent"]["paths"] == []


def test_finding_order_contains_unactioned_intent() -> None:
    assert "unactioned_intent" in FINDING_ORDER

"""Tests for raw-source subtree detection (issue #225).

The pure classifier in ``lib.raw_source`` decides, from three per-doc graph
signals, whether a directory subtree is a dump of raw, machine-extracted source
documents that should be excluded from the headline read-side metrics. These
tests pin the threshold contract so the detector behaves identically regardless
of which LLM is driving the surrounding assessment.
"""
from __future__ import annotations

import pytest

from lib.raw_source import (
    RAW_TREE_ISOLATION_DENSITY,
    RAW_TREE_MACHINE_DENSITY,
    RAW_TREE_MIN_FILES,
    WORKING_NOTES_INDEX_SHARE,
    WORKING_NOTES_LOW_INDEGREE_DENSITY,
    WORKING_NOTES_MIN_FILES,
    WORKING_NOTES_NAME_DENSITY,
    _name_key,
    classify_raw_trees,
    classify_working_notes_trees,
)


def _signal(in_degree: int = 0, out_degree: int = 0, machine_links: int = 0) -> dict:
    return {
        "in_degree": in_degree,
        "out_degree": out_degree,
        "machine_links": machine_links,
    }


def _raw_tree(prefix: str, n: int, machine_share: float = 1.0) -> dict[str, dict]:
    """A subtree of ``n`` link-isolated docs; ``machine_share`` of them carry a
    machine-extracted (non-navigational) link."""
    signals: dict[str, dict] = {}
    machine_count = round(n * machine_share)
    for i in range(n):
        signals[f"{prefix}/doc-{i:03d}.md"] = _signal(
            machine_links=1 if i < machine_count else 0,
        )
    return signals


def test_no_docs_returns_empty() -> None:
    assert classify_raw_trees({}) == []


def test_large_isolated_machine_tree_detected() -> None:
    signals = _raw_tree("sar-export", RAW_TREE_MIN_FILES + 2)
    trees = classify_raw_trees(signals)
    assert len(trees) == 1
    assert trees[0]["path"] == "sar-export"
    assert trees[0]["file_count"] == RAW_TREE_MIN_FILES + 2
    assert len(trees[0]["docs"]) == RAW_TREE_MIN_FILES + 2


def test_below_min_files_not_detected() -> None:
    signals = _raw_tree("sar-export", RAW_TREE_MIN_FILES - 1)
    assert classify_raw_trees(signals) == []


def test_isolated_but_no_machine_links_not_detected() -> None:
    # A folder of genuinely standalone-but-curated notes: link-isolated, but
    # none carry the machine-extraction fingerprint. Must NOT be excluded.
    signals = _raw_tree("notes", RAW_TREE_MIN_FILES + 5, machine_share=0.0)
    assert classify_raw_trees(signals) == []


def test_well_linked_machine_tree_not_detected() -> None:
    # Files carry machine links but are also internally navigable (in/out edges).
    signals: dict[str, dict] = {}
    for i in range(RAW_TREE_MIN_FILES + 4):
        signals[f"corpus/doc-{i:03d}.md"] = _signal(
            in_degree=2, out_degree=2, machine_links=1,
        )
    assert classify_raw_trees(signals) == []


def test_entry_point_excluded_from_isolation_numerator() -> None:
    # An entry doc in the subtree is not counted as isolated; with enough
    # isolated machine docs around it the tree still qualifies.
    signals = _raw_tree("dump", RAW_TREE_MIN_FILES + 4)
    entry = "dump/index.md"
    signals[entry] = _signal(out_degree=5, machine_links=0)
    trees = classify_raw_trees(signals, entries={entry})
    assert len(trees) == 1
    assert trees[0]["path"] == "dump"


def test_outermost_subtree_is_kept() -> None:
    # Two qualifying batch subtrees nested under a qualifying parent: only the
    # outermost ("export") is reported, not its children.
    signals: dict[str, dict] = {}
    signals.update(_raw_tree("export/batch-1", RAW_TREE_MIN_FILES + 1))
    signals.update(_raw_tree("export/batch-2", RAW_TREE_MIN_FILES + 1))
    trees = classify_raw_trees(signals)
    assert [t["path"] for t in trees] == ["export"]
    assert trees[0]["file_count"] == 2 * (RAW_TREE_MIN_FILES + 1)


def test_two_independent_raw_trees_both_reported() -> None:
    signals: dict[str, dict] = {}
    signals.update(_raw_tree("sar-export", RAW_TREE_MIN_FILES + 1))
    signals.update(_raw_tree("disclosure-dump", RAW_TREE_MIN_FILES + 1))
    trees = classify_raw_trees(signals)
    assert sorted(t["path"] for t in trees) == ["disclosure-dump", "sar-export"]


def test_root_level_docs_never_excluded() -> None:
    # Root-level isolated machine docs (no enclosing subtree) are never excluded
    # so a whole-repo false positive can't zero out the metrics.
    signals = {
        f"doc-{i:03d}.md": _signal(machine_links=1)
        for i in range(RAW_TREE_MIN_FILES + 5)
    }
    assert classify_raw_trees(signals) == []


def test_thresholds_are_tunable() -> None:
    # A smaller tree is detected once the min-files threshold is lowered.
    signals = _raw_tree("small-dump", 4)
    assert classify_raw_trees(signals) == []
    trees = classify_raw_trees(signals, min_files=3)
    assert [t["path"] for t in trees] == ["small-dump"]


def test_machine_density_threshold_boundary() -> None:
    # Exactly at the machine-density threshold qualifies; just below does not.
    n = 20
    at = _raw_tree("a", n, machine_share=RAW_TREE_MACHINE_DENSITY)
    assert [t["path"] for t in classify_raw_trees(at)] == ["a"]
    below = _raw_tree("b", n, machine_share=RAW_TREE_MACHINE_DENSITY - 0.1)
    assert classify_raw_trees(below) == []


def test_isolation_density_threshold() -> None:
    # A subtree where too many docs are linked (below the isolation density)
    # does not qualify even with machine links everywhere.
    n = 20
    linked = round(n * (1 - RAW_TREE_ISOLATION_DENSITY) + 1)
    signals: dict[str, dict] = {}
    for i in range(n):
        is_linked = i < linked
        signals[f"mix/doc-{i:03d}.md"] = _signal(
            in_degree=1 if is_linked else 0,
            out_degree=1 if is_linked else 0,
            machine_links=1,
        )
    assert classify_raw_trees(signals) == []


# --- Working-notes trees (issue #366) ---------------------------------------


def _wn_signal(sources: list[str]) -> dict:
    return {"in_degree": len(sources), "inbound_sources": sources}


def _notes_tree(prefix: str, n: int, stem: str = "plan_{i:02d}") -> dict[str, dict]:
    """``n`` pattern-named notes each linked once from ``<prefix>/backlog.md``,
    and the backlog index linked once from the README."""
    signals = {
        f"{prefix}/{stem.format(i=i)}.md": _wn_signal([f"{prefix}/backlog.md"])
        for i in range(1, n + 1)
    }
    signals[f"{prefix}/backlog.md"] = _wn_signal(["README.md"])
    return signals


def test_working_notes_tree_counts_the_index_too() -> None:
    signals = _notes_tree("notes", 50)
    signals["README.md"] = _wn_signal([])
    trees = classify_working_notes_trees(signals)
    assert [(t["path"], t["file_count"]) for t in trees] == [("notes", 51)]
    assert "notes/backlog.md" in trees[0]["docs"]


def test_working_notes_date_and_ticket_names_match() -> None:
    dated = {
        f"journal/2026-01-{d:02d}-standup.md": _wn_signal(["journal/log.md"])
        for d in range(1, 29)
    }
    tickets = {
        f"tickets/PROJ-{i}.md": _wn_signal(["tickets/board.md"]) for i in range(100, 130)
    }
    trees = classify_working_notes_trees({**dated, **tickets})
    assert [t["path"] for t in trees] == ["journal", "tickets"]


def test_varied_cross_linked_wiki_is_not_working_notes() -> None:
    names = [f"topic{chr(97 + i % 26)}{chr(97 + i // 26)}" for i in range(50)]
    words = ["auth", "billing", "cache", "deploy", "events"] * 10
    stems = [f"{w}{n}" for w, n in zip(words, names)]
    signals = {
        f"wiki/{s}.md": _wn_signal([f"wiki/{stems[(i + k) % 50]}.md" for k in (1, 7, 13)])
        for i, s in enumerate(stems)
    }
    assert classify_working_notes_trees(signals) == []


def test_small_curated_wiki_does_not_match() -> None:
    names = "architecture billing caching deploy events glossary logging metrics onboarding"
    stems = names.split()
    signals = {
        f"docs/{s}.md": _wn_signal([f"docs/{stems[(i + 1) % 9]}.md", f"docs/{stems[(i + 4) % 9]}.md"])
        for i, s in enumerate(stems)
    }
    assert classify_working_notes_trees(signals) == []


def test_working_notes_below_size_threshold_not_classified() -> None:
    signals = _notes_tree("notes", WORKING_NOTES_MIN_FILES - 2)
    assert classify_working_notes_trees(signals) == []


def test_pattern_named_notes_without_an_index_hub_not_classified() -> None:
    # Same names, but every note is linked from a different source: no index
    # holds the inbound links, so the index leg fails.
    signals = {
        f"notes/plan_{i:02d}.md": _wn_signal([f"docs/page{i}.md"]) for i in range(40)
    }
    assert classify_working_notes_trees(signals) == []


def test_heavily_linked_pattern_names_not_classified() -> None:
    # Pattern names under one index, but each page has several inbound links:
    # a curated series (release notes cross-linked), not working notes.
    signals = {
        f"notes/plan_{i:02d}.md": _wn_signal(
            ["notes/index.md", f"notes/plan_{(i + 1) % 40:02d}.md", f"notes/plan_{(i + 2) % 40:02d}.md"]
        )
        for i in range(40)
    }
    assert classify_working_notes_trees(signals) == []


def test_working_notes_nested_tree_keeps_curated_siblings() -> None:
    # A notes tree inside docs/ must not pull its curated siblings with it.
    signals = _notes_tree("docs/notes", 50)
    signals["docs/guide.md"] = _wn_signal(["README.md"])
    trees = classify_working_notes_trees(signals)
    assert [t["path"] for t in trees] == ["docs/notes"]


def test_prefix_named_indexed_section_is_not_working_notes() -> None:
    # A curated how-to section: same-prefixed pages each linked once from the
    # section README. Passes in-degree and index; the name leg must fail it,
    # because a shared word is not a sequence.
    topics = [f"how-to-{w}" for w in (
        "deploy rotate-keys restore scale debug profile migrate upgrade rollback "
        "tag release audit onboard offboard backup patch seed index cache trace"
    ).split()]
    signals = {f"docs/how-to/{t}.md": _wn_signal(["docs/how-to/README.md"]) for t in topics}
    signals["docs/how-to/README.md"] = _wn_signal(["README.md"])
    assert classify_working_notes_trees(signals) == []


def _indexed_section(prefix: str, stems: list[str]) -> dict[str, dict]:
    """Pages each linked once from ``<prefix>/README.md``, linked from the root."""
    signals = {f"{prefix}/{s}.md": _wn_signal([f"{prefix}/README.md"]) for s in stems}
    signals[f"{prefix}/README.md"] = _wn_signal(["README.md"])
    return signals


def test_dotted_release_pages_are_not_working_notes() -> None:
    signals = _indexed_section("releases", [f"release-2.{i}.1" for i in range(30)])
    assert classify_working_notes_trees(signals) == []


def test_v_prefixed_version_pages_are_not_working_notes() -> None:
    signals = _indexed_section("releases", [f"v1.{i}.0" for i in range(30)])
    assert classify_working_notes_trees(signals) == []


def test_titled_decision_records_are_not_working_notes() -> None:
    adrs = _indexed_section("docs/adr", [f"adr-{i:04d}-decision-{i}x" for i in range(1, 25)])
    rfcs = _indexed_section("docs/rfc", [f"rfc-{i:03d}-proposal" for i in range(1, 25)])
    assert classify_working_notes_trees(adrs) == []
    assert classify_working_notes_trees(rfcs) == []


@pytest.mark.parametrize(
    ("rel", "key"),
    [
        ("notes/plan_07.md", "plan"),
        ("notes/plan-07.md", "plan"),
        ("tickets/PROJ-123.md", "proj"),
        ("tickets/gh-42.md", "gh"),
        ("journal/2026-01-31-standup.md", "<date>"),
        ("releases/release-2.1.0.md", None),
        ("releases/v1.2.3.md", None),
        ("docs/adr/adr-0001-use-postgres.md", None),
        ("docs/rfc/rfc-042-streaming.md", None),
        ("docs/how-to/how-to-deploy.md", None),
        ("docs/adr/0001-use-postgres.md", None),
    ],
)
def test_name_key_families(rel: str, key: str | None) -> None:
    assert _name_key(rel) == key


def test_mixed_hyphen_series_count_as_separate_families() -> None:
    # plan-/spike-/retro-/audit- are four families: over the three-prefix
    # ceiling, so no three of them reach the name density.
    stems = [f"{w}-{i:02d}" for w in ("plan", "spike", "retro", "audit") for i in range(1, 7)]
    signals = _indexed_section("notes", stems)
    assert classify_working_notes_trees(signals) == []


def test_curated_sibling_citing_one_note_stays_in_headline() -> None:
    signals = _notes_tree("docs/notes", 50)
    signals["docs/notes/plan_01.md"] = _wn_signal(["docs/notes/backlog.md", "docs/guide.md"])
    signals["docs/guide.md"] = _wn_signal(["README.md"])
    trees = classify_working_notes_trees(signals)
    assert [t["path"] for t in trees] == ["docs/notes"]


def test_notes_split_by_period_keep_their_index_in_the_tree() -> None:
    signals = {
        f"notes/{y}/plan_{i:02d}.md": _wn_signal(["notes/backlog.md"])
        for y in (2025, 2026) for i in range(25)
    }
    signals["notes/backlog.md"] = _wn_signal(["README.md"])
    trees = classify_working_notes_trees(signals)
    assert [(t["path"], t["file_count"]) for t in trees] == [("notes", 51)]


def test_sparsely_linked_notes_pile_is_not_working_notes() -> None:
    # One stray link into an otherwise unlinked pile: the few edges that exist
    # are concentrated, but no index covers the tree, so it stays counted.
    signals = {f"notes/topic-{i}.md": _wn_signal([]) for i in range(1, 26)}
    signals["notes/topic-1.md"] = _wn_signal(["README.md"])
    assert classify_working_notes_trees(signals) == []
    signals["notes/topic-2.md"] = _wn_signal(["docs/guide.md"])
    assert classify_working_notes_trees(signals) == []


def test_non_absorbing_subdirectory_shields_its_curated_page() -> None:
    # docs/team refuses to absorb docs/team/notes because of onboarding.md;
    # docs must not then treat onboarding.md as nested and absorb it anyway.
    signals = {
        f"docs/team/notes/plan_{i:02d}.md": _wn_signal(["docs/index.md"]) for i in range(1, 51)
    }
    signals["docs/index.md"] = _wn_signal(["README.md"])
    signals["docs/team/onboarding.md"] = _wn_signal(["README.md"])
    trees = classify_working_notes_trees(signals)
    assert [(t["path"], t["file_count"]) for t in trees] == [("docs/team/notes", 50)]


def test_curated_subdirectory_below_the_floor_stays_counted() -> None:
    # docs/ holds 50 notes directly and docs/guides/ (9 pages and a README,
    # under the size floor, so it never qualifies). docs clears every leg over
    # all 61 docs, but the guides carry no name family and are no index into
    # the notes: only the notes and their index leave the headline.
    signals = {f"docs/plan_{i:02d}.md": _wn_signal(["docs/index.md"]) for i in range(1, 51)}
    signals["docs/index.md"] = _wn_signal(["README.md"])
    guides = "architecture billing caching deploy events glossary logging metrics onboarding".split()
    for g in guides:
        signals[f"docs/guides/{g}.md"] = _wn_signal(["docs/guides/README.md"])
    signals["docs/guides/README.md"] = _wn_signal(["docs/index.md"])
    trees = classify_working_notes_trees(signals)
    assert [(t["path"], t["file_count"]) for t in trees] == [("docs", 51)]
    assert not any(r.startswith("docs/guides/") for r in trees[0]["docs"])


def test_working_notes_thresholds_are_precision_first() -> None:
    assert WORKING_NOTES_MIN_FILES >= 10
    assert 0.5 < WORKING_NOTES_NAME_DENSITY <= 1.0
    assert 0.5 < WORKING_NOTES_LOW_INDEGREE_DENSITY <= 1.0
    assert 0.5 < WORKING_NOTES_INDEX_SHARE <= 1.0

"""Tests for lib/review_reality.py.

GitHub is faked with a `gh` shell script first on PATH that logs every call and
answers from JSON files, so the tests run the real subprocess path through
lib/gh_cli.py, including the 403 mapping.
"""
from __future__ import annotations

import json
import os
import stat
import subprocess
import sys
from pathlib import Path

import pytest

sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "scripts"))

from lib.review_reality import scan_review_reality  # noqa: E402

FAKE_GH = """#!/bin/sh
echo "$*" >> "$FAKE_GH/log"
serve() { [ -f "$FAKE_GH/$1" ] && cat "$FAKE_GH/$1" && exit 0; }
case "$1:$*" in
  auth:*) [ -f "$FAKE_GH/noauth" ] || exit 0 ;;
  pr:*) serve prs.json ;;
  api:*rules/branches*) serve branchrules.json ;;
  api:*/protection*) serve protection.json ;;
  api:*users/*) serve "user-$(echo "$2" | sed 's|.*/||')" ;;
  api:*repos/acme/widget) serve apirepo.json ;;
esac
cat "$FAKE_GH/fail" >&2
exit 1
"""

PERSON = {"login": "Alice", "is_bot": False}
REVIEWER = {"login": "bob", "is_bot": False}


def _git(repo: Path, *args: str) -> None:
    env = {**os.environ, "GIT_CONFIG_GLOBAL": "/dev/null"}
    subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True, env=env)


def _pr(n: int, *, merger=PERSON, reviews=(), comments=(), state="APPROVED",
        merged_at="2026-09-01T00:00:00Z") -> dict:
    return {
        "number": n, "title": f"SECRET-TITLE-{n}", "reviewDecision": "",
        "author": PERSON, "mergedBy": merger, "mergedAt": merged_at,
        "reviews": [{"author": a, "state": state} for a in reviews],
        "comments": [{"author": a, "body": "SECRET-BODY"} for a in comments],
    }


@pytest.fixture
def world(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q", "-b", "main")
    _git(repo, "remote", "add", "origin", "https://github.com/acme/widget.git")
    bindir, ghdir = tmp_path / "bin", tmp_path / "gh"
    bindir.mkdir()
    ghdir.mkdir()
    gh = bindir / "gh"
    gh.write_text(FAKE_GH)
    gh.chmod(gh.stat().st_mode | stat.S_IEXEC)
    (ghdir / "log").write_text("")
    (ghdir / "fail").write_text("gh: Not Found (HTTP 404)\n")
    monkeypatch.setenv("PATH", f"{bindir}{os.pathsep}{os.environ['PATH']}")
    monkeypatch.setenv("FAKE_GH", str(ghdir))

    class World:
        root = repo

        def serve(self, name: str, doc: object) -> None:
            (ghdir / name).write_text(json.dumps(doc))

        def fail_with(self, line: str) -> None:
            (ghdir / "fail").write_text(line + "\n")

        def calls(self) -> list[str]:
            return (ghdir / "log").read_text().splitlines()

    w = World()
    w.serve("apirepo.json", {"full_name": "acme/widget", "default_branch": "main"})
    return w


def _require_by_ruleset(world) -> None:
    world.serve("branchrules.json", [
        {"type": "pull_request", "parameters": {"required_approving_review_count": 1}},
    ])


def test_review_reality_unreviewed_required_review_is_hollow(world) -> None:
    _require_by_ruleset(world)
    world.serve("prs.json", [_pr(n) for n in range(10)])
    block = scan_review_reality(world.root)
    del block["oldest_merged_days_ago"]
    assert block == {
        "available": True, "merged_count": 10, "reviewed_share": 0.0,
        "approved_share": 0.0, "bot_review_share": 0.0, "self_merged_share": 1.0,
        "review_required": True, "hollow_required_review": True,
        "required_approval_bypassed": True,
    }
    # The ruleset already said yes: the protection read is skipped.
    assert not any("/protection" in c for c in world.calls())


def test_review_reality_mixed_sample_counts_each_share(world) -> None:
    _require_by_ruleset(world)
    bot = {"login": "reviewbot", "is_bot": True, "type": "Bot"}
    actions = {"login": "github-actions", "is_bot": True, "type": "Bot"}
    human = {"login": "carol", "is_bot": False, "type": "User"}
    prs = [
        _pr(0, merger=REVIEWER, comments=[bot]),
        _pr(1, merger=REVIEWER, comments=[bot]),
        _pr(2, merger=REVIEWER, comments=[bot]),
        _pr(3, merger=REVIEWER, comments=[actions]),
        _pr(4, comments=[actions]),
        _pr(5, comments=[human]),
        _pr(6), _pr(7),
        _pr(8, reviews=[{"login": "alice"}]),  # the author's own review, case aside
        _pr(9, reviews=[REVIEWER]),
    ]
    world.serve("prs.json", prs)
    block = scan_review_reality(world.root)
    assert block["reviewed_share"] == 0.1
    assert block["bot_review_share"] == 0.3
    assert block["self_merged_share"] == 0.6
    assert block["hollow_required_review"] is True


def test_review_reality_half_reviewed_is_not_hollow(world) -> None:
    world.serve("branchrules.json", [])
    world.serve("protection.json", {"required_pull_request_reviews": {
        "required_approving_review_count": 2}})
    world.serve("prs.json", [_pr(n, reviews=[REVIEWER] if n < 5 else []) for n in range(10)])
    block = scan_review_reality(world.root)
    assert block["review_required"] is True
    assert block["reviewed_share"] == 0.5
    assert block["hollow_required_review"] is False


def test_review_reality_no_requirement_is_never_hollow(world) -> None:
    world.serve("branchrules.json", [])
    world.fail_with("gh: Branch not protected (HTTP 404)")
    world.serve("prs.json", [_pr(n) for n in range(3)])
    block = scan_review_reality(world.root)
    assert block["review_required"] is False
    assert block["hollow_required_review"] is False


def test_review_reality_refused_protection_leaves_requirement_unknown(world) -> None:
    world.serve("branchrules.json", [])
    world.fail_with("gh: Resource not accessible by integration (HTTP 403)")
    world.serve("prs.json", [_pr(n) for n in range(3)])
    block = scan_review_reality(world.root)
    assert block["available"] is True
    assert block["review_required"] is None
    assert block["hollow_required_review"] is None


def test_review_reality_403_degrades_to_unavailable(world) -> None:
    world.fail_with("gh: Resource not accessible by personal access token (HTTP 403)")
    block = scan_review_reality(world.root)
    assert block["available"] is False
    assert block["reason"].startswith("no_access")
    assert "hollow_required_review" not in block
    assert world.calls()


def test_review_reality_no_remote_never_calls_gh(world) -> None:
    _git(world.root, "remote", "remove", "origin")
    block = scan_review_reality(world.root)
    assert block["available"] is False and block["reason"]
    assert world.calls() == []


def test_review_reality_probes_unmarked_comment_logins_once(world) -> None:
    _require_by_ruleset(world)
    world.serve("user-reviewbot%5Bbot%5D", {"login": "reviewbot[bot]", "type": "Bot"})
    # "dave[bot]" is absent from the fake, so the probe 404s: dave is a person.
    prs = [
        _pr(0, comments=[{"login": "reviewbot"}]),
        _pr(1, comments=[{"login": "reviewbot"}, {"login": "dave"}]),
        _pr(2, comments=[{"login": "dave"}]),
        _pr(3, comments=[{"login": "github-actions"}]),
    ]
    world.serve("prs.json", prs)
    block = scan_review_reality(world.root)
    assert block["bot_review_share"] == 0.5
    probes = [c for c in world.calls() if "users/" in c]
    assert sorted(probes) == ["api users/dave%5Bbot%5D", "api users/reviewbot%5Bbot%5D"]


def test_review_reality_unknown_commenter_type_withholds_bot_share(world) -> None:
    _require_by_ruleset(world)
    world.fail_with("gh: Resource not accessible (HTTP 403)")
    world.serve("prs.json", [_pr(0, comments=[{"login": "mystery"}])])
    block = scan_review_reality(world.root)
    assert block["available"] is True
    assert block["bot_review_share"] is None


def test_review_reality_writes_no_title_or_login(world) -> None:
    _require_by_ruleset(world)
    bot = {"login": "reviewbot", "is_bot": True, "type": "Bot"}
    world.serve("prs.json", [_pr(0, merger=REVIEWER, reviews=[REVIEWER], comments=[bot])])
    text = json.dumps(scan_review_reality(world.root)).lower()
    for secret in ("secret", "alice", "bob", "reviewbot"):
        assert secret not in text


def test_review_reality_bot_comment_reviews_are_not_approvals(world) -> None:
    # An AI reviewer leaves a COMMENTED review on every PR; nobody approves.
    _require_by_ruleset(world)
    world.serve("prs.json", [_pr(n, reviews=[REVIEWER], state="COMMENTED") for n in range(10)])
    block = scan_review_reality(world.root)
    assert block["reviewed_share"] == 1.0
    assert block["approved_share"] == 0.0
    assert block["hollow_required_review"] is False
    assert block["required_approval_bypassed"] is True


def test_review_reality_small_sample_withholds_both_flags(world) -> None:
    _require_by_ruleset(world)
    world.serve("prs.json", [_pr(n) for n in range(4)])
    block = scan_review_reality(world.root)
    assert block["reviewed_share"] == 0.0
    assert block["hollow_required_review"] is None
    assert block["required_approval_bypassed"] is None


def test_review_reality_reports_age_of_oldest_merge() -> None:
    from datetime import datetime, timezone

    from lib.review_reality import summarize

    now = datetime(2026, 9, 19, tzinfo=timezone.utc)
    prs = [_pr(0, merged_at="2026-09-18T12:00:00Z"), _pr(1, merged_at="2026-08-20T00:00:00Z"),
           _pr(2, merged_at=None)]
    assert summarize(prs, True, now=now)["oldest_merged_days_ago"] == 30
    assert summarize([_pr(0, merged_at=None)], True, now=now)["oldest_merged_days_ago"] is None


def test_review_reality_comment_without_author_is_unknown(world) -> None:
    _require_by_ruleset(world)
    bot = {"login": "reviewbot", "is_bot": True, "type": "Bot"}
    # A confirmed bot comment still counts; an authorless comment alone is unknown.
    world.serve("prs.json", [_pr(0, comments=[None, bot]), _pr(1, comments=[None])])
    assert scan_review_reality(world.root)["bot_review_share"] is None
    world.serve("prs.json", [_pr(0, comments=[None, bot]), _pr(1)])
    assert scan_review_reality(world.root)["bot_review_share"] == 0.5

"""Monorepo scoping for `/assess <path>` (task assess-obey-thyself.19).

A scoped run confines every signal to a subtree: the complexity stats, the doc
graph, the churn axis, the badge, the wiki, and the artifact directory all
describe the scope and carry no signal from a sibling directory. The key
invariant guarded here is default-preservation: a run with no scope is
byte-for-byte the pre-scope behaviour.
"""
from __future__ import annotations

import importlib.util
import json
import sys
import types
from pathlib import Path

import pytest

import assess_core
from assess_core import build_run_context, resolve_scope
from lib.badge import fallback_badge, score_badge
from lib.doc_graph import build_doc_graph, discover_doc_files
from lib.git_churn import git_churn_scores
from lib.wiki_writer import HotspotEntry, write_index

_SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "complexity-treemap.py"


_STATS_SHAPE = {
    "files_scored": 0, "loc": {}, "ccn": {},
    "top_hotspots": [], "top_complex": [], "top_large": [],
}


# --------------------------------------------------------------------------
# Two-service fixture: a monorepo with two sibling service subtrees, each with
# its own complex code file and its own docs, committed to git so churn and
# tracked-file filters have real history to read.
# --------------------------------------------------------------------------
def _two_service_repo(git_repo) -> tuple[Path, object]:
    repo, commit = git_repo
    for svc, fn in (("service-a", "alpha"), ("service-b", "beta")):
        d = repo / svc
        d.mkdir()
        # A deliberately branchy function so lizard/scc would score it a hotspot,
        # plus an unused helper (dead-code candidate) and a TODO (promissory
        # marker) so a scoped run has real sibling signal to exclude.
        (d / "app.py").write_text(
            f"# TODO: refactor {svc}\n"
            f"def {fn}(x):\n"
            + "".join(f"    if x == {i}:\n        return {i}\n" for i in range(12))
            + "    return -1\n\n"
            f"def _unused_{fn}():\n    return 0\n",
            encoding="utf-8",
        )
        (d / "README.md").write_text(f"# {svc}\n\nDocs for {svc}.\n", encoding="utf-8")
    commit("two services")
    return repo, commit


# --------------------------------------------------------------------------
# resolve_scope
# --------------------------------------------------------------------------
def test_resolve_scope_none_is_whole_repo(tmp_path: Path) -> None:
    assert resolve_scope(tmp_path, None) == (None, None, "")


def test_resolve_scope_computes_slug(tmp_path: Path) -> None:
    sub = tmp_path / "services" / "api"
    sub.mkdir(parents=True)
    scope_abs, scope_rel, slug = resolve_scope(tmp_path, Path("services/api"))
    assert scope_abs == sub.resolve()
    assert scope_rel == "services/api"
    assert slug == "services-api"  # separators hyphenated for a flat dir name


def test_resolve_scope_rejects_missing_path(tmp_path: Path) -> None:
    with pytest.raises(ValueError, match="does not exist"):
        resolve_scope(tmp_path, Path("nope"))


def test_resolve_scope_rejects_outside_repo(tmp_path: Path) -> None:
    outside = tmp_path.parent / "elsewhere"
    outside.mkdir()
    with pytest.raises(ValueError, match="not under repo root"):
        resolve_scope(tmp_path, outside)


# --------------------------------------------------------------------------
# git_churn scope
# --------------------------------------------------------------------------
def test_git_churn_scope_isolates_subtree(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    scoped = git_churn_scores(repo, scope=repo / "service-a")
    assert scoped, "expected churn for the scoped subtree"
    assert all("service-a" in str(p) for p in scoped)
    assert not any("service-b" in str(p) for p in scoped)


def test_git_churn_no_scope_sees_whole_repo(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    full = git_churn_scores(repo)
    assert any("service-a" in str(p) for p in full)
    assert any("service-b" in str(p) for p in full)


# --------------------------------------------------------------------------
# doc_graph scope
# --------------------------------------------------------------------------
def test_doc_graph_scope_excludes_sibling_docs(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    scoped = discover_doc_files(repo, scope=repo / "service-a")
    names = {str(p.relative_to(repo)) for p in scoped}
    assert "service-a/README.md" in names
    assert "service-b/README.md" not in names


def test_build_doc_graph_scope_confines_docs(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    full = build_doc_graph(repo)
    scoped = build_doc_graph(repo, scope=repo / "service-a")
    assert full.doc_count > scoped.doc_count
    scoped_paths = set(scoped.graph.nodes) if scoped.graph is not None else set()
    assert not any("service-b" in n for n in scoped_paths)


# --------------------------------------------------------------------------
# treemap collect scope (lizard/scc stubbed - no heavy deps in the test env)
# --------------------------------------------------------------------------
def _load_treemap():
    for name in ("lizard", "matplotlib", "matplotlib.pyplot", "squarify", "numpy"):
        sys.modules.setdefault(name, types.ModuleType(name))
    sys.modules["matplotlib"].pyplot = sys.modules["matplotlib.pyplot"]
    spec = importlib.util.spec_from_file_location("complexity_treemap_scope", _SCRIPT)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


def test_treemap_collect_filters_to_scope(tmp_path: Path) -> None:
    mod = _load_treemap()
    a = (tmp_path / "service-a" / "app.py")
    b = (tmp_path / "service-b" / "app.py")
    a.parent.mkdir(parents=True)
    b.parent.mkdir(parents=True)
    a.write_text("x = 1\n")
    b.write_text("y = 2\n")

    def fake_lizard(root, **kw):
        return {a.resolve(): (10, 5.0, [5.0]), b.resolve(): (20, 9.0, [9.0])}

    def fake_scc(root, **kw):
        return {}

    mod.lizard_scores = fake_lizard
    mod.scc_scores = fake_scc

    files, *_ = mod.collect(tmp_path, by="complexity", scope=tmp_path / "service-a")
    paths = {f[0] for f in files}
    assert a.resolve() in paths
    assert b.resolve() not in paths


# --------------------------------------------------------------------------
# badge + wiki labelling
# --------------------------------------------------------------------------
def test_badge_labels_scope() -> None:
    scoped = score_badge(4.0, "Basic", scope="services/api")
    assert scoped["label"] == "AI-readiness (services/api)"
    assert score_badge(4.0, "Basic")["label"] == "AI-readiness"  # default unchanged
    assert fallback_badge(1, 0, scope="services/api")["label"] == "AI-readiness (services/api)"


def test_write_index_scope_note(tmp_assess_dir: Path) -> None:
    entries = [HotspotEntry(path="service-a/app.py", first_flagged="2026-07-07",
                            last_seen="2026-07-07", status="new", ccn=9, loc=20)]
    write_index(tmp_assess_dir, entries, last_updated="2026-07-07", scope="service-a")
    scoped = (tmp_assess_dir / "index.md").read_text(encoding="utf-8")
    assert "_Scope: `service-a`_" in scoped

    write_index(tmp_assess_dir, entries, last_updated="2026-07-07")
    assert "_Scope:" not in (tmp_assess_dir / "index.md").read_text(encoding="utf-8")


# --------------------------------------------------------------------------
# assess_core end-to-end: scoped run routes artifacts and isolates signal
# --------------------------------------------------------------------------
def _seed_scoped_stats(repo: Path, slug: str, hotspot_path: str) -> None:
    d = repo / ".assess" / slug
    d.mkdir(parents=True)
    (d / "complexity-stats.json").write_text(json.dumps({
        **_STATS_SHAPE,
        "files_scored": 1,
        "top_hotspots": [{"path": hotspot_path, "loc": 20, "ccn": 9,
                          "commits_12mo": 1}],
    }))


def test_scoped_run_routes_artifacts_and_records_scope(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    _seed_scoped_stats(repo, "service-a", "service-a/app.py")

    ctx = build_run_context(repo_root=repo, run_date="2026-07-07",
                            scope=Path("service-a"))

    # Scope recorded in the bus for the report/badge/wiki.
    assert ctx["scope"] == "service-a"
    assert ctx["scope_slug"] == "service-a"

    # Artifacts land under .assess/<slug>/, not the repo-root .assess/.
    scoped_dir = repo / ".assess" / "service-a"
    assert (scoped_dir / "run-context.json").exists()
    assert (scoped_dir / "index.md").exists()
    assert (scoped_dir / "log.md").exists()
    assert not (repo / ".assess" / "run-context.json").exists()

    # The only hotspot is the scoped one; the sibling never appears.
    hotspot_paths = [h["path"] for h in ctx["stats_summary"]["top_hotspots"]]
    assert hotspot_paths == ["service-a/app.py"]
    blob = (scoped_dir / "run-context.json").read_text(encoding="utf-8")
    assert "service-b" not in blob

    # The scoped wiki index names the scope and never the sibling.
    index = (scoped_dir / "index.md").read_text(encoding="utf-8")
    assert "_Scope: `service-a`_" in index
    assert "service-b" not in index

    # The behaviour block's change-coupling saw the single commit that touched
    # both services, but the sibling is confined out: no service-b co-change.
    behaviour = ctx.get("behaviour", {})
    for pair in behaviour.get("change_coupling_pairs", []):
        assert "service-b" not in json.dumps(pair)
    # And the dead-code / marker scans carry no sibling candidate.
    assert "service-b" not in json.dumps(ctx.get("dead_code", {}))


def test_scoped_run_doc_graph_has_no_sibling_signal(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    _seed_scoped_stats(repo, "service-a", "service-a/app.py")
    ctx = build_run_context(repo_root=repo, run_date="2026-07-07",
                            scope=Path("service-a"))
    dg = ctx["doc_graph"]
    if dg.get("available"):
        # Whatever docs the scoped graph found, none is the sibling's.
        serialized = json.dumps(dg)
        assert "service-b" not in serialized


def test_root_run_unchanged_by_scope_support(git_repo) -> None:
    """The key invariant: a no-scope run is byte-identical to pre-scope."""
    repo, _ = _two_service_repo(git_repo)
    (repo / ".assess").mkdir()
    (repo / ".assess" / "complexity-stats.json").write_text(json.dumps(_STATS_SHAPE))

    ctx = build_run_context(repo_root=repo, run_date="2026-07-07")
    assert ctx["scope"] is None
    assert ctx["scope_slug"] is None
    # Artifacts stay at the repo-root .assess/.
    assert (repo / ".assess" / "run-context.json").exists()
    assert not (repo / ".assess" / "service-a").exists()


def test_invalid_scope_raises_valueerror(git_repo) -> None:
    repo, _ = _two_service_repo(git_repo)
    with pytest.raises(ValueError):
        build_run_context(repo_root=repo, run_date="2026-07-07",
                          scope=Path("no-such-dir"))


def test_cli_invalid_scope_exits_nonzero(git_repo, capsys) -> None:
    repo, _ = _two_service_repo(git_repo)
    (repo / ".assess").mkdir()
    (repo / ".assess" / "complexity-stats.json").write_text(json.dumps(_STATS_SHAPE))
    rc = assess_core.main([str(repo), "--scope", "no-such-dir"])
    assert rc == 2
    assert "error" in capsys.readouterr().err.lower()

"""Contract for the layer scorer's structured evidence (issue #361).

The scorer returns an ``evidence`` list beside its prose; the orchestrator
re-checks it with ``lib.evidence_check`` between scoring and report writing, and
the findings step cites only verified entries. These tests pin the three halves:

1. The scorer definition states the evidence schema with one example per kind,
   and every example is true of this repository (the deterministic half of a
   dry run on this repo: an ``evidence`` list and an empty ``evidence_rejected``).
2. ``skills/assess/SKILL.md`` runs the check after scoring and before finalize.
3. ``skills/assess-findings/SKILL.md`` restricts existence and wiring claims to
   verified entries.
"""
from __future__ import annotations

import json
import re
from pathlib import Path

from lib.evidence_check import KINDS, check_evidence

REPO_ROOT = Path(__file__).resolve().parents[3]
SCORER = REPO_ROOT / "agents" / "assess-layer-scorer.md"
ASSESS_SKILL = REPO_ROOT / "skills" / "assess" / "SKILL.md"
FINDINGS_SKILL = REPO_ROOT / "skills" / "assess-findings" / "SKILL.md"


def _schema_examples() -> list:
    text = SCORER.read_text(encoding="utf-8")
    headings = re.findall(r"^#{2,4} Evidence schema$", text, flags=re.M)
    assert len(headings) == 1, "scorer must carry exactly one Evidence schema heading"
    after = text[re.search(r"^#{2,4} Evidence schema$", text, flags=re.M).end():]
    block = re.search(r"^```json\n(.*?)^```$", after, flags=re.M | re.S)
    assert block, "no json block under the Evidence schema heading"
    return json.loads(block.group(1))


def test_scorer_return_section_names_evidence_list():
    text = SCORER.read_text(encoding="utf-8")
    # The return list only, not the Evidence schema subsection that follows it,
    # so deleting the bullet fails this test even though the schema prose stays.
    section = text.split("## What you return", 1)[1].split("### Evidence schema", 1)[0]
    bullets = [line for line in section.splitlines() if line.startswith("- ")]
    assert any("`evidence`" in line for line in bullets)


def test_scorer_schema_has_one_example_per_kind():
    examples = _schema_examples()
    assert sorted(e["kind"] for e in examples) == sorted(KINDS)
    assert all(isinstance(e.get("layer"), int) and 0 <= e["layer"] <= 8 for e in examples)


def test_scorer_schema_examples_verify_against_this_repo():
    result = check_evidence(REPO_ROOT, _schema_examples())
    assert result["evidence_rejected"] == []
    assert len(result["evidence"]) == len(KINDS)


def test_orchestrator_checks_evidence_between_scoring_and_finalize():
    text = ASSESS_SKILL.read_text(encoding="utf-8")
    window = text.split("## Step 3: Score the Layers\n", 1)[1].split("## Step 7.5", 1)[0]
    assert "evidence_check" in window
    assert "evidence_rejected" in window


def test_findings_cites_only_verified_evidence():
    assert "cite only verified" in FINDINGS_SKILL.read_text(encoding="utf-8").lower()


def test_orchestrator_runs_the_check_by_script_path():
    # An /assess run's cwd is the target repo, where `python -m lib.evidence_check`
    # fails with "No module named lib" and exits 1 - the same code as "an entry was
    # rejected". The call must name the script by path, like every sibling call.
    text = ASSESS_SKILL.read_text(encoding="utf-8")
    window = text.split("## Step 3: Score the Layers\n", 1)[1].split("## Step 7.5", 1)[0]
    assert '"${CLAUDE_SKILL_DIR}/scripts/lib/evidence_check.py"' in window
    assert "-m lib.evidence_check" not in window
    assert "<!-- chat-replace:evidence-check -->" in window


def _step4_check_paragraph() -> str:
    text = ASSESS_SKILL.read_text(encoding="utf-8")
    step4 = text.split("## Step 4: Write the Report\n", 1)[1].split("## Step 7.5", 1)[0]
    return next(p for p in step4.split("\n\n") if "evidence_check.py" in p)


def test_step4_names_the_check_by_the_substituted_skill_dir():
    # Step 2's shell variables do not survive to Step 4 (Step 3's subagent sits
    # in between), so the check must not lean on one. ${CLAUDE_SKILL_DIR} is
    # substituted into the skill text before the model reads it, so the call
    # carries an absolute path and needs no re-resolution in the shell.
    para = _step4_check_paragraph()
    assert '"${CLAUDE_SKILL_DIR}/scripts/lib/evidence_check.py"' in para
    assert "SKILL_DIR=" not in para
    assert "$SKILL_DIR" not in para
    assert "CLAUDE_PLUGIN_ROOT" not in para
    assert "as in Step 2" not in para


def test_step4_hands_rejected_entries_on_to_the_findings_step():
    # The findings step renders the refuted-claims gap from `evidence_rejected`,
    # so the orchestrator must pass the list on rather than drop it.
    para = _step4_check_paragraph()
    assert "removed from the report input" not in para
    assert "`evidence_rejected`" in para and "handed on" in para


def _evidence_cell_rule() -> str:
    text = FINDINGS_SKILL.read_text(encoding="utf-8")
    return next(p for p in text.split("\n\n") if "`(unverified)`" in p)


def test_evidence_cell_marks_only_unoffered_evidence_unverified():
    # No entries offered is an honest limit of the run: keep the note, flag it.
    rule = _evidence_cell_rule()
    unverified = next(s for s in rule.split(". ") if "`(unverified)`" in s)
    assert "offered no" in unverified
    assert "rejected" not in unverified and "held" not in unverified


def test_evidence_cell_gives_na_layer_no_unverified_marker():
    # An N/A layer is scored with no entries by design (the scorer skips
    # `na_layers`), so it must not fall into the no-entries-offered state.
    rule = _evidence_cell_rule()
    na = next(s for s in rule.split(". ") if "N/A layer" in s)
    assert "`(unverified)`" not in na
    assert "archetype rule" in na and "no marker" in na


def test_evidence_cell_rule_sits_beside_archetype_rule():
    # The two rules govern the same cell; kept apart they contradicted each other.
    text = FINDINGS_SKILL.read_text(encoding="utf-8")
    paras = text.split("\n\n")
    archetype = next(i for i, p in enumerate(paras) if "Archetype-aware Status" in p)
    assert "`(unverified)`" in paras[archetype + 1]


def test_evidence_cell_renders_refuted_claims_as_a_gap():
    # Entries offered and all rejected were checked and found false: repeating
    # the note, even flagged, restates the claim that just failed.
    rule = _evidence_cell_rule()
    assert "no verified evidence - N claim(s) rejected" in rule
    assert "drop the scorer's note" in rule
    assert "`reason`" in rule


def test_evidence_cell_strikes_refuted_claims_when_only_some_entries_fail():
    # The common case is neither empty state: a layer cites three entries, two
    # hold, one is refuted. Rendering the note verbatim publishes the refuted claim.
    rule = _evidence_cell_rule()
    partial = next(s for s in rule.split(". ") if "only some" in s)
    assert "strike the refuted claims" in partial
    assert "N of M claim(s) rejected" in partial
    assert "`(unverified)`" not in partial


def test_cite_only_verified_exempts_only_the_empty_evidence_cell_states():
    # Exempting the whole Evidence cell let a partly refuted note through verbatim.
    text = FINDINGS_SKILL.read_text(encoding="utf-8")
    para = next(p for p in text.split("\n\n") if "cite only verified evidence" in p)
    cell = next(s for s in para.split(". ") if "Evidence cell" in s)
    assert "exempt only in its two empty states" in cell
    assert "some verified entries" in cell

"""Executable architecture contract for the /assess deterministic core.

`CLAUDE.md` states the layering: the deterministic core in
`skills/assess/scripts/lib/` does all the data work, and the orchestrator
scripts in `skills/assess/scripts/` (assess_core, assess_finalize, ...) call
into it and assemble `run-context.json`. Dependencies point **inward**: a lib
module may import other lib modules and third-party libraries, but it must never
import an orchestrator. That keeps the core independently testable and reusable -
the property the decomposition-parity test relies on.

This was a convention enforced only by review (the L4 "Partial" the tool's own
self-assessment flagged). This test makes it a contract: an `ast` scan over every
module in `lib/` asserts none imports an orchestrator. The forbidden set is
*derived* from disk - every `.py` directly under `scripts/` (not in `lib/`) - so
a newly added orchestrator is forbidden automatically, with no edit here.

Pure stdlib (`ast`, `pathlib`); no import side effects, so it is safe and fast.
"""
from __future__ import annotations

import ast
from pathlib import Path

# tests/ -> assess/ ; the deterministic core and its orchestrators live under scripts/.
SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
LIB_DIR = SCRIPTS_DIR / "lib"


def _orchestrator_modules() -> set[str]:
    """Importable module names of the orchestrator layer: every ``*.py`` directly
    under ``scripts/`` (excluding the ``lib/`` package). Hyphenated run-only
    scripts (``complexity-treemap.py``) are kept for completeness - their stems
    are not valid identifiers, so they can never appear as an import anyway."""
    return {p.stem for p in SCRIPTS_DIR.glob("*.py")}


def _lib_modules() -> list[Path]:
    """Every Python module in the deterministic core, recursively (includes the
    ``test_pressure/`` subpackage)."""
    return sorted(LIB_DIR.rglob("*.py"))


def _imported_names(tree: ast.AST) -> set[str]:
    """Collect the dotted module path of every ``import`` / ``from ... import``
    in a parsed module (absolute imports only; relative imports stay in-package
    by construction and cannot reach an orchestrator)."""
    names: set[str] = set()
    for node in ast.walk(tree):
        if isinstance(node, ast.Import):
            for alias in node.names:
                names.add(alias.name)
        elif isinstance(node, ast.ImportFrom):
            # level > 0 is a relative import (``from . import x``) - in-package,
            # never an orchestrator. Only absolute imports can cross the boundary.
            if node.level == 0 and node.module:
                names.add(node.module)
    return names


def test_fixture_paths_resolve() -> None:
    """Guard against a path bug making the boundary test vacuously pass."""
    orchestrators = _orchestrator_modules()
    libs = _lib_modules()
    assert LIB_DIR.is_dir(), f"lib package not found at {LIB_DIR}"
    assert "assess_core" in orchestrators, "expected assess_core.py among the orchestrators"
    assert libs, "expected at least one module in the deterministic core"


def test_core_does_not_import_orchestrators() -> None:
    """No `lib/` module may import an orchestrator script - dependencies point
    inward. A failure means the deterministic core grew an upward dependency."""
    orchestrators = _orchestrator_modules()
    violations: list[str] = []

    for module in _lib_modules():
        tree = ast.parse(module.read_text(encoding="utf-8"), filename=str(module))
        for imported in _imported_names(tree):
            # Match an orchestrator stem appearing as any dotted component, so
            # both ``import assess_core`` and ``import scripts.assess_core`` are
            # caught.
            hit = next((o for o in orchestrators if o in imported.split(".")), None)
            if hit:
                rel = module.relative_to(LIB_DIR.parent)
                violations.append(f"{rel} imports orchestrator '{hit}' (via '{imported}')")

    assert not violations, (
        "deterministic core must not import the orchestrator layer "
        "(dependencies point inward - see CLAUDE.md /assess architecture):\n  "
        + "\n  ".join(violations)
    )

"""The capstone self-check: /assess's deterministic core must obey the very
invariants the assess-obey-thyself marathon added (tasks 2-16).

Every prior task in the marathon hardened one property of the emitted wiki -
a provenance stamp, a contradiction flag, an exclusion disclosure, a mutation
cap, a deterministic badge, a versioned action contract, an orphan-free hotspot
set, a verifiable log chain, decline-marker provenance. This test runs the
*deterministic* pipeline (``build_run_context`` - never the LLM finalize, which
CI cannot drive with no network/model) against a small, hermetic, purpose-built
fixture repo and asserts the output honours each invariant. If a future change
regresses one of them, this build goes red: the tool would no longer obey its
own rules.

Why a built fixture, not the live repo tree: the fixture is fast, deterministic,
and hermetic (the live ``.assess/`` drifts run to run and would make the test
flaky). It is a real ``build_run_context`` run over a real git repo - the same
code path a user's ``/assess`` drives - just over a controlled tree that pins
every signal the invariants read.
"""
from __future__ import annotations

import json
import os
import re
import subprocess
from pathlib import Path

import pytest

import assess_core
from assess_core import build_run_context
from assess_finalize import _write_actions_contract
from lib.keyhole_signals import FINDING_MODE_VALUES, mode_for_finding
from lib.wiki_writer import (
    hotspot_page_source_path,
    hotspot_page_status,
    is_retired_status,
    verify_log_chain,
)

RUN_ID_RE = re.compile(r"^\d{14}-[0-9a-f]{8}$")

# Two source files that the seeded stats name as top hotspots. They must exist
# on disk so the no-orphan invariant (task 9) is exercised, not vacuously true.
_HOT_ONE = "src/hot_one.py"
_HOT_TWO = "src/hot_two.py"


def _git(repo: Path, *args: str) -> None:
    subprocess.run(
        ["git", "-C", str(repo), *args],
        check=True, capture_output=True, text=True, env=os.environ,
    )


def _build_dogfood_repo(root: Path, fixtures_dir: Path) -> Path:
    """A small software repo with every signal the invariants read pinned:
    a committed instruction file, two on-disk hotspot files, a seeded stats
    sidecar naming them, and a provenance-carrying decline marker.
    """
    repo = root / "repo"
    (repo / "src").mkdir(parents=True)
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "test@example.com")
    _git(repo, "config", "user.name", "Test")

    # Committed instruction file so Layer 0 has a real surface to grade.
    (repo / "CLAUDE.md").write_text(
        (fixtures_dir / "good_instructions.md").read_text(encoding="utf-8"),
        encoding="utf-8",
    )
    (repo / "pyproject.toml").write_text("[project]\nname='dogfood'\n", encoding="utf-8")

    # Enough code files that archetype classifies the repo as software.
    for i in range(12):
        (repo / "src" / f"mod_{i}.py").write_text(
            f"def f{i}(x):\n    return x + {i}\n", encoding="utf-8"
        )
    # The two named hotspots, present on disk (no-orphan invariant).
    (repo / _HOT_ONE).write_text(
        "def tangled(a, b):\n" + "    a = a + b\n" * 40 + "    return a\n",
        encoding="utf-8",
    )
    (repo / _HOT_TWO).write_text(
        "def sprawl(a):\n" + "    a += 1\n" * 30 + "    return a\n",
        encoding="utf-8",
    )

    assess_dir = repo / ".assess"
    assess_dir.mkdir()
    (assess_dir / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 14,
        "loc": {"total": 900},
        "ccn": {"max": 34, "mean": 6},
        "top_hotspots": [
            {"path": _HOT_ONE, "loc": 620, "ccn": 34, "commits": 8},
            {"path": _HOT_TWO, "loc": 540, "ccn": 22, "commits": 4},
        ],
        "top_complex": [{"path": _HOT_ONE, "ccn": 34}],
        "top_large": [{"path": _HOT_ONE, "loc": 620}],
    }), encoding="utf-8")

    # Decline marker with full provenance (task 12): declined_by / declined_at /
    # plugin_version / reason all present.
    (assess_dir / ".no-mutmut").write_text(json.dumps({
        "declined_by": "ben",
        "declined_at": "2026-07-01",
        "plugin_version": "1.55.5",
        "reason": "bounded mutation pass declined for the fixture",
    }), encoding="utf-8")

    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", "dogfood fixture")
    return repo


@pytest.fixture(scope="module")
def dogfood_run(tmp_path_factory, request) -> dict:
    """Run the deterministic pipeline once; every test asserts one invariant on
    the shared result. Module-scoped so the (git-backed) pipeline runs a single
    time - the output is a pure function of the pinned tree, so sharing is safe.
    """
    fixtures_dir = Path(request.fspath).parent / "fixtures"
    root = tmp_path_factory.mktemp("dogfood")
    repo = _build_dogfood_repo(root, fixtures_dir)
    ctx = build_run_context(
        repo_root=repo, run_date="2026-07-07", non_interactive=True,
    )
    assess_dir = repo / ".assess"
    on_disk = json.loads((assess_dir / "run-context.json").read_text(encoding="utf-8"))
    return {"repo": repo, "assess_dir": assess_dir, "ctx": ctx, "on_disk": on_disk}


# --- task 2: run_id + artifact_schema_version provenance stamps ---------------

def test_run_id_and_schema_version_stamped(dogfood_run: dict) -> None:
    ctx = dogfood_run["ctx"]
    assert RUN_ID_RE.match(ctx["run_id"]), ctx["run_id"]
    assert ctx["artifact_schema_version"] == assess_core.ARTIFACT_SCHEMA_VERSION
    # The stamp is persisted, not just returned in-process.
    assert dogfood_run["on_disk"]["run_id"] == ctx["run_id"]
    assert (
        dogfood_run["on_disk"]["artifact_schema_version"]
        == assess_core.ARTIFACT_SCHEMA_VERSION
    )


def test_run_id_propagates_to_badge(dogfood_run: dict) -> None:
    """The run_id stamped in run-context is the same id carried on the artifact
    every consumer reads first - proving the stamp is one run, not per-writer."""
    badge = json.loads((dogfood_run["assess_dir"] / "badge.json").read_text(encoding="utf-8"))
    assert badge["run_id"] == dogfood_run["ctx"]["run_id"]


# --- task 3: archetype.override_contradicts_signals is a real bool ------------

def test_archetype_override_contradicts_signals_present(dogfood_run: dict) -> None:
    arch = dogfood_run["ctx"]["archetype"]
    assert arch["available"] is True
    assert "override_contradicts_signals" in arch
    assert isinstance(arch["override_contradicts_signals"], bool)
    # No override marker in the fixture, so the flag is False (not merely present).
    assert arch["override_contradicts_signals"] is False


# --- task 7: excluded_by_config disclosure block ------------------------------

def test_excluded_by_config_block_present(dogfood_run: dict) -> None:
    block = dogfood_run["ctx"]["excluded_by_config"]
    assert set(block) >= {"dirs", "patterns", "affected_finding_paths", "count"}
    assert isinstance(block["dirs"], list)
    assert isinstance(block["patterns"], list)
    # count is the honest tally of suppressed finding paths - never out of sync.
    assert block["count"] == len(block["affected_finding_paths"])


# --- task 8: mutation_not_run_cap on a default read-only run ------------------

def test_mutation_not_run_cap_applies_and_caps_layer6(dogfood_run: dict) -> None:
    cap = dogfood_run["ctx"]["mutation_not_run_cap"]
    assert cap["applies"] is True
    assert cap["mutation_run"] is False
    assert cap["max_layer6_band"] == "Partial"
    assert cap["annotation"]  # a non-empty annotation the LLM must carry


# --- task 15: deterministic badge (findings count, not an LLM score) ----------

def test_badge_is_deterministic_findings_count(dogfood_run: dict) -> None:
    badge = json.loads((dogfood_run["assess_dir"] / "badge.json").read_text(encoding="utf-8"))
    assert "findings" in badge["message"]
    # The shipped badge never bakes in an LLM-derived layered score.
    assert "/8" not in badge["message"]
    assert badge["link"] == "./assess-report.md"


# --- task 16: actions.json v2 (schema 2, status, derived mode) ----------------

def test_actions_json_v2_schema_status_and_derived_mode(dogfood_run: dict) -> None:
    """actions.json is written by the deterministic ``_write_actions_contract``
    (the writer finalize calls). Drive it directly - CI has no LLM to author the
    Top 3 - and assert the v2 shape: schema 2, a lifecycle ``status`` per action,
    and a ``mode`` derived from each action's finding type."""
    assess_dir = dogfood_run["assess_dir"]
    run_id = dogfood_run["ctx"]["run_id"]
    actions = [
        {"rank": 1, "action": "Characterize the src/hot_one.py seam",
         "done_when": "seam mapped", "scope_fence": "read only",
         "finding": "hidden_coupling"},
        {"rank": 2, "action": "Verify and retire the aged marker",
         "done_when": "marker resolved", "scope_fence": "one file",
         "finding": "unactioned_intent"},
        {"rank": 3, "action": "Split the accreted module",
         "done_when": "module under budget", "scope_fence": "no API change",
         "finding": "accretion_ratchet"},
    ]
    _write_actions_contract(assess_dir, actions, run_id=run_id)
    payload = json.loads((assess_dir / "actions.json").read_text(encoding="utf-8"))

    assert payload["schema"] == 2
    assert payload["run_id"] == run_id
    entries = payload["actions"]
    assert len(entries) == 3
    for entry in entries:
        assert entry["status"] == "pending"  # fresh contract, no carry-forward
        assert entry["mode"] in FINDING_MODE_VALUES
        # The mode is *derived* from the finding type, not free text.
        assert entry["mode"] == mode_for_finding(entry.get("finding"))
    # The derivation is discriminating: distinct finding types earn distinct modes.
    modes = {e["finding"]: e["mode"] for e in entries}
    assert modes["hidden_coupling"] == "characterize_first"
    assert modes["unactioned_intent"] == "verify_then_retire"
    assert modes["accretion_ratchet"] == "refactor_safe"


# --- task 9: no active hotspot page references a path absent from disk ---------

def test_no_orphan_hotspot_pages(dogfood_run: dict) -> None:
    assess_dir = dogfood_run["assess_dir"]
    repo = dogfood_run["repo"]
    pages = sorted((assess_dir / "hotspots").glob("*.md"))
    assert pages, "expected at least one hotspot page (invariant must not be vacuous)"
    active_referenced = 0
    orphans: list[str] = []
    for page in pages:
        content = page.read_text(encoding="utf-8")
        path = hotspot_page_source_path(content)
        if path is None:
            continue
        if is_retired_status(hotspot_page_status(content)):
            continue
        active_referenced += 1
        if not (repo / path).exists():
            orphans.append(path)
    assert active_referenced >= 1
    assert orphans == []


# --- task 11: log.md integrity chain verifies ---------------------------------

def test_log_chain_verifies(dogfood_run: dict) -> None:
    # The run-context claim...
    integrity = dogfood_run["ctx"]["log_integrity"]
    assert integrity["valid"] is True
    assert integrity["broken_at_entry"] is None
    # ...and the artifact itself, recomputed independently.
    valid, broken_at = verify_log_chain(dogfood_run["assess_dir"])
    assert valid is True
    assert broken_at is None


# --- task 12: decline-marker provenance shape ---------------------------------

def test_decline_marker_provenance_shape(dogfood_run: dict) -> None:
    markers = dogfood_run["ctx"]["decline_markers"]
    assert markers, "fixture writes one decline marker"
    mutmut = next((m for m in markers if m["tool"] == "mutmut"), None)
    assert mutmut is not None
    assert set(mutmut) >= {
        "path", "tool", "declined_by", "declined_at", "version", "reason", "reoffer",
    }
    # Provenance is populated (a legacy marker would carry None here).
    assert mutmut["declined_by"] == "ben"
    assert mutmut["declined_at"] == "2026-07-01"
    assert mutmut["version"] == "1.55.5"
    assert isinstance(mutmut["reoffer"], bool)


def test_log_chain_verifies_after_finalize(dogfood_run: dict, tmp_path: Path) -> None:
    """Finalize fills the run's log entry in place; the chain must still verify.

    Finalize runs on a copy so the shared module fixture stays unfinalized for
    the other invariants. Before #355 finalize rewrote the entry text but kept
    its old chain marker, so every finalized log failed verification and the
    next core run disclosed a broken history.
    """
    import shutil

    from assess_finalize import finalize_run
    from lib.badge import maturity_band

    assess_dir = tmp_path / ".assess"
    shutil.copytree(dogfood_run["assess_dir"], assess_dir)
    assert verify_log_chain(assess_dir) == (True, None)
    (assess_dir / ".cache").mkdir(exist_ok=True)
    (assess_dir / ".cache" / "finalize-input.json").write_text(json.dumps({
        "run_id": dogfood_run["ctx"]["run_id"],
        "score": 4.0,
        "denominator": 8,
        "maturity_label": maturity_band(4.0, 8),
        "top_action": "dogfood finalize action",
        "hotspot_actions": {},
    }), encoding="utf-8")
    finalize_run(assess_dir=assess_dir)
    log = (assess_dir / "log.md").read_text(encoding="utf-8")
    assert "dogfood finalize action" in log
    assert "(LLM fills in)" not in log
    assert verify_log_chain(assess_dir) == (True, None)

"""Contract tests for ``lib/sibling_tests``: the one sibling-test resolver.

The hotspot page (``assess_core._has_sibling_test``), the E2 test-to-code map
(``keyhole_signals._find_sibling_test``), and the focus signal
(``test_focus.compute_test_focus``) must answer "does this file have a test
file?" the same way in one run. These tests pin that agreement on a fixture set
spanning every naming idiom, so a convention added to one consumer and not the
others fails here.
"""
from __future__ import annotations

from pathlib import Path

import assess_core
from lib import keyhole_signals as ks
from lib import sibling_tests as tc
from lib.test_focus import compute_test_focus, mutation_scope

# Co-located fixtures: source -> test file beside it or in an adjacent dir.
COLOCATED = {
    "go/foo.go": "go/foo_test.go",
    "ts/bar.ts": "ts/bar.test.ts",
    "ng/baz.ts": "ng/baz.spec.ts",
    "rb/qux.rb": "rb/qux_spec.rb",
    "py/mod.py": "py/test_mod.py",
    "java/Foo.java": "java/FooTest.java",
    "cs/Bar.cs": "cs/BarTests.cs",
    "js/e.js": "js/__tests__/e.test.js",
    "js/f.js": "js/__tests__/f.js",
    "rb2/g.rb": "rb2/spec/g_spec.rb",
    "scripts/tree-map.py": "scripts/test_tree_map.py",
}
# Sources with no test file anywhere.
UNTESTED = ["java/Lonely.java", "py/alone.py", "ts/solo.ts"]


def _touch(root: Path, rel: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text("x\n", encoding="utf-8")


def _fixture(root: Path) -> None:
    for src, test in COLOCATED.items():
        _touch(root, src)
        _touch(root, test)
    for src in UNTESTED:
        _touch(root, src)


def test_three_resolvers_agree_on_colocated_fixtures(tmp_path: Path) -> None:
    """Every co-located idiom (including FooTest.java / BarTests.cs) is credited
    by all three consumers, and every untested source by none of them."""
    _fixture(tmp_path)
    sources = [*COLOCATED, *UNTESTED]
    focus: dict[str, str] = {}
    for start in range(0, len(sources), 10):  # the focus block reads a top 10
        block = compute_test_focus(sources[start:start + 10], None, None,
                                   repo_root=tmp_path)
        focus.update({e["path"]: e["test_signal"] for e in block["entries"]})

    for src in sources:
        expected = src in COLOCATED
        assert assess_core._has_sibling_test(tmp_path, src) is expected, src
        found = ks._find_sibling_test(tmp_path, src)
        assert (found is not None) is expected, src
        if expected:
            assert found == tmp_path / COLOCATED[src]
        assert focus[src] == ("sibling_test_only" if expected else "unsupported"), src


def test_resolvers_agree_that_a_test_file_is_test_evidence(tmp_path: Path) -> None:
    """A hot file that is itself a test: the hotspot page and the focus signal
    both credit it, and E2 maps it to no sibling (it is not a source)."""
    _fixture(tmp_path)
    for test in COLOCATED.values():
        assert tc.is_test_path(test), test
        assert assess_core._has_sibling_test(tmp_path, test) is True
        assert ks._find_sibling_test(tmp_path, test) is None
        block = compute_test_focus([test], None, None, repo_root=tmp_path)
        assert block["entries"][0]["test_signal"] == "sibling_test_only"


def test_hotspot_page_and_focus_agree_on_mirrored_and_flat_trees(tmp_path: Path) -> None:
    """Beyond co-location the hotspot page reads the same tree probe as the
    focus signal: a mirrored tests/ tree credits in both, and a flat-tree match
    on a bare name two hot files share credits neither."""
    for rel in ("src/pkg/view.py", "tests/src/pkg/test_view.py",
                "a/mod.py", "b/mod.py", "tests/test_mod.py"):
        _touch(tmp_path, rel)
    hot = ["src/pkg/view.py", "a/mod.py", "b/mod.py"]
    shared = tc.shared_name_keys(hot)
    assert shared == frozenset({"mod.py"})
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    focus = {e["path"]: e["test_signal"] == "sibling_test_only" for e in block["entries"]}
    for src in hot:
        assert assess_core._has_sibling_test(tmp_path, src, shared) is focus[src], src
    assert focus == {"src/pkg/view.py": True, "a/mod.py": False, "b/mod.py": False}


def test_missing_source_is_unknown_not_credited(tmp_path: Path) -> None:
    """A stale path whose test outlived it: unknown on the hotspot page, no
    sibling for E2, unsupported in the focus block."""
    _touch(tmp_path, "src/gone.test.ts")
    assert assess_core._has_sibling_test(tmp_path, "src/gone.ts") is None
    assert ks._find_sibling_test(tmp_path, "src/gone.ts") is None
    block = compute_test_focus(["src/gone.ts"], None, None, repo_root=tmp_path)
    assert block["entries"][0]["test_signal"] == "unsupported"


def test_sibling_test_names_cover_every_builder_and_hyphen_fold() -> None:
    names = tc.sibling_test_names("Foo-bar.java")
    for stem in ("Foo-bar", "Foo_bar"):
        assert f"{stem}Test.java" in names
        assert f"{stem}Tests.java" in names
        assert f"{stem}_spec.java" in names
        assert f"test_{stem}.java" in names
    assert len(names) == 2 * len(tc.TEST_SIBLING_BUILDERS)


# Parallel test trees that neither co-locate nor mirror the source path: the
# issue's fixture, the reported case where the test tree drops a directory, and
# the Dart layout (``lib/`` stripped, tests under ``test/unit``).
PARALLEL = {
    "app/functions/foo.js": "app/unit-tests/functions/foo.test.js",
    "app/functions/hmrc/hmrcVatReturnPost.js":
        "app/unit-tests/functions/hmrcVatReturnPost.test.js",
    "shop/lib/features/crm/repositories/customer_repository.dart":
        "shop/test/unit/customer_repository_test.dart",
}


def test_parallel_tree_basename_credits_the_three_layouts(tmp_path: Path) -> None:
    """A conventionally named test anywhere under a shared directory credits the
    source in the focus block and on the hotspot page, and enters the mutation
    scope; a source with no test anywhere stays unsupported."""
    for src, test in PARALLEL.items():
        _touch(tmp_path, src)
        _touch(tmp_path, test)
    _touch(tmp_path, "app/functions/bar.js")
    hot = [*PARALLEL, "app/functions/bar.js"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    assert by_path == {**{p: "sibling_test_only" for p in PARALLEL},
                       "app/functions/bar.js": "unsupported"}
    assert mutation_scope(block) == list(PARALLEL)
    for src in PARALLEL:
        assert tc.sibling_test_match(tmp_path, src) == tc.MATCH_BASENAME, src
        assert assess_core._has_sibling_test(tmp_path, src) is True, src
        assert ks._find_sibling_test(tmp_path, src) is None, src  # E2: co-located only
    assert assess_core._has_sibling_test(tmp_path, "app/functions/bar.js") is False


def test_parallel_tree_basename_common_name_goes_to_the_closest_source(
    tmp_path: Path,
) -> None:
    """Two sources sharing a basename (``index.js``): the test credits the one
    source with the strictly closest common ancestor, and a tie credits none,
    across the whole repository rather than only the hot files."""
    for rel in ("web/pages/index.js", "api/index.js",
                "web/unit-tests/pages/index.test.js",
                "svc/a/util.js", "svc/b/util.js", "svc/unit-tests/util.test.js"):
        _touch(tmp_path, rel)
    assert assess_core._has_sibling_test(tmp_path, "web/pages/index.js") is True
    assert assess_core._has_sibling_test(tmp_path, "api/index.js") is False
    # svc/a and svc/b tie on svc/: the test cannot say which util.js it tests.
    assert assess_core._has_sibling_test(tmp_path, "svc/a/util.js") is False
    assert assess_core._has_sibling_test(tmp_path, "svc/b/util.js") is False


def test_parallel_tree_basename_needs_a_shared_directory(tmp_path: Path) -> None:
    """A bare-name match whose only common ancestor is the repository root
    carries no path relationship, and a test under an excluded tree
    (``node_modules``, ``tests/fixtures``) is never evidence."""
    for rel in ("pkg/sub/deep/mod.py", "other/tests/test_mod.py",
                "app/lib/widget.js", "app/node_modules/x/widget.test.js",
                "tool/src/cfg.py", "tool/tests/fixtures/test_cfg.py"):
        _touch(tmp_path, rel)
    for src in ("pkg/sub/deep/mod.py", "app/lib/widget.js", "tool/src/cfg.py"):
        assert tc.sibling_test_match(tmp_path, src) is None, src


def test_parallel_tree_basename_reads_git_index_when_present(tmp_path: Path) -> None:
    """In a git repository the index is the tracked file list: an untracked
    stray test file is not evidence, a committed one is."""
    import subprocess

    for rel in ("app/functions/foo.js", "app/unit-tests/functions/foo.test.js",
                "app/functions/baz.js"):
        _touch(tmp_path, rel)
    git = ["git", "-C", str(tmp_path), "-c", "user.email=t@example.com",
           "-c", "user.name=t"]
    subprocess.run([*git, "init", "-q"], check=True)
    subprocess.run([*git, "add", "-A"], check=True)
    subprocess.run([*git, "commit", "-q", "-m", "init"], check=True)
    _touch(tmp_path, "app/unit-tests/functions/baz.test.js")  # untracked
    index = tc.build_test_index(tmp_path)
    assert tc.has_sibling_test(tmp_path, "app/functions/foo.js", index=index) is True
    assert tc.has_sibling_test(tmp_path, "app/functions/baz.js", index=index) is False


def test_parallel_tree_basename_truncated_index_credits_nothing(
    tmp_path: Path, monkeypatch,
) -> None:
    """A walk cut off at the index cap can drop a rival source as readily as a
    test, so a truncated index is empty: it fails closed rather than credit a
    source on evidence the complete index calls a tie."""
    for rel in ("svc/a/util.js", "svc/a-tests/util.test.js", "svc/b/util.js"):
        _touch(tmp_path, rel)
    # Complete index: svc/a and svc/b tie on svc/, so neither is credited.
    assert tc.sibling_test_match(tmp_path, "svc/a/util.js") is None
    # Cap at two files: the walk keeps svc/a and the test but drops svc/b.
    monkeypatch.setattr(tc, "MAX_INDEX_FILES", 2)
    index = tc.build_test_index(tmp_path)
    assert index == tc.TestIndex()
    assert tc.sibling_test_match(tmp_path, "svc/a/util.js", index) is None


def test_parallel_tree_basename_index_is_built_only_when_a_probe_reads_it(
    tmp_path: Path, monkeypatch,
) -> None:
    """A coverage report that records every hot file never reaches the test-file
    probe, so the repository index is not built; a caller's index is reused."""
    from lib import test_focus as tf

    for rel in ("app/functions/foo.js", "app/unit-tests/functions/foo.test.js"):
        _touch(tmp_path, rel)
    built: list[Path] = []
    real = tf.build_test_index
    monkeypatch.setattr(tf, "build_test_index",
                        lambda root: built.append(root) or real(root))
    coverage = {"_overall": 0.9, "per_file": {"app/functions/foo.js": 0.9}}
    compute_test_focus(["app/functions/foo.js"], coverage, None, repo_root=tmp_path)
    assert built == []
    shared = tc.build_test_index(tmp_path)
    block = compute_test_focus(["app/functions/foo.js"], None, None,
                               repo_root=tmp_path, index=shared)
    assert built == []
    assert block["entries"][0]["test_signal"] == "sibling_test_only"
    compute_test_focus(["app/functions/foo.js"], None, None, repo_root=tmp_path)
    assert built == [tmp_path]


def test_parallel_tree_basename_skips_tracked_files_deleted_from_disk(
    tmp_path: Path,
) -> None:
    """A tracked file deleted from the working tree (deletion not yet staged)
    is not evidence: ``git ls-files`` still lists it, the index does not."""
    import subprocess

    for rel in ("app/functions/foo.js", "app/unit-tests/functions/foo.test.js"):
        _touch(tmp_path, rel)
    git = ["git", "-C", str(tmp_path), "-c", "user.email=t@example.com",
           "-c", "user.name=t"]
    subprocess.run([*git, "init", "-q"], check=True)
    subprocess.run([*git, "add", "-A"], check=True)
    subprocess.run([*git, "commit", "-q", "-m", "init"], check=True)
    (tmp_path / "app/unit-tests/functions/foo.test.js").unlink()
    assert tc.build_test_index(tmp_path).tests_by_name == {}
    assert tc.sibling_test_match(tmp_path, "app/functions/foo.js") is None


def test_parallel_tree_basename_unreadable_subtree_credits_nothing(
    tmp_path: Path,
) -> None:
    """A walk that cannot read a directory may have missed a rival source, so
    it yields an empty index, the same fail-closed rule as truncation."""
    import os

    for rel in ("svc/a/util.js", "svc/a-tests/util.test.js", "svc/b/util.js"):
        _touch(tmp_path, rel)
    locked = tmp_path / "svc/b"
    locked.chmod(0)
    try:
        if os.access(locked, os.R_OK):
            import pytest
            pytest.skip("running with privileges that ignore file modes")
        assert tc.build_test_index(tmp_path) == tc.TestIndex()
    finally:
        locked.chmod(0o755)

"""Smoke test: verify the test harness runs and lib is importable."""
from __future__ import annotations

from lib import __version__


def test_lib_importable() -> None:
    assert __version__ == "0.1.0"


def test_fixtures_dir_exists(fixtures_dir):
    # fixtures dir doesn't need contents yet; just verify the fixture works
    assert fixtures_dir.parent.name == "tests"

"""Tests for stats sidecar diff."""
from __future__ import annotations

from pathlib import Path

import pytest

from lib.stats_diff import (
    diff_stats,
    hotspot_commits,
    load_stats,
)


def test_hotspot_commits_reads_commits_then_legacy_churn() -> None:
    """`commits` is the current field; `churn` is the legacy producer name a
    seeded/older prior snapshot may still carry (issue #47, observation 5)."""
    assert hotspot_commits({"commits": 12}) == 12
    assert hotspot_commits({"churn": 7}) == 7        # legacy fallback
    assert hotspot_commits({"commits": 3, "churn": 99}) == 3  # commits wins
    assert hotspot_commits({}) == 0
    assert hotspot_commits({"commits": None, "churn": None}) == 0


@pytest.fixture
def prior_stats(fixtures_dir: Path) -> dict:
    return load_stats(fixtures_dir / "prior_stats.json")


@pytest.fixture
def current_stats(fixtures_dir: Path) -> dict:
    return load_stats(fixtures_dir / "current_stats.json")


def test_load_stats_returns_dict(fixtures_dir: Path) -> None:
    stats = load_stats(fixtures_dir / "prior_stats.json")
    assert stats["files_scored"] == 100


def test_load_stats_missing_returns_none(tmp_path: Path) -> None:
    assert load_stats(tmp_path / "nope.json") is None


def test_diff_identifies_graduated(prior_stats: dict, current_stats: dict) -> None:
    diff = diff_stats(prior=prior_stats, current=current_stats)
    graduated_paths = {h.path for h in diff.graduated}
    assert "src/legacy/parser.go" in graduated_paths


def test_diff_identifies_regressed(prior_stats: dict, current_stats: dict) -> None:
    diff = diff_stats(prior=prior_stats, current=current_stats)
    regressed_paths = {h.path for h in diff.regressed}
    assert "src/api/handler.go" in regressed_paths
    # Regression must capture the delta
    handler = next(h for h in diff.regressed if h.path == "src/api/handler.go")
    assert handler.ccn_delta == 4  # 32 - 28
    assert handler.commits_delta == 7  # 15 - 8


def test_diff_identifies_new(prior_stats: dict, current_stats: dict) -> None:
    diff = diff_stats(prior=prior_stats, current=current_stats)
    new_paths = {h.path for h in diff.new}
    assert "src/new/feature.go" in new_paths


def test_diff_identifies_persistent(prior_stats: dict, current_stats: dict) -> None:
    diff = diff_stats(prior=prior_stats, current=current_stats)
    persistent_paths = {h.path for h in diff.persistent}
    assert "src/util/helpers.go" in persistent_paths


def test_diff_no_prior_means_all_new(current_stats: dict) -> None:
    diff = diff_stats(prior=None, current=current_stats)
    assert len(diff.graduated) == 0
    assert len(diff.regressed) == 0
    assert len(diff.persistent) == 0
    assert len(diff.new) == len(current_stats["top_hotspots"])


def test_diff_summary_counts(prior_stats: dict, current_stats: dict) -> None:
    diff = diff_stats(prior=prior_stats, current=current_stats)
    summary = diff.summary()
    assert summary["graduated"] == 1
    assert summary["regressed"] == 1
    assert summary["new"] == 1
    assert summary["persistent"] == 1

"""Contract suite for the Tier 0 path-existence structure-drift signal.

Tier 0 is the zero-threshold cut: a declared ownership pattern (a CODEOWNERS glob
or an ARCHITECTURE.md path reference) that matches *zero* tracked files on disk -
a boundary the filesystem has left behind. These tests pin the enumerate-both-
sides behaviour, the two contracts the signal inherits from the parser
(deterministic byte-identical output, honest degradation when no map exists), and
the excluded-only-matches-as-empty rule.

Fixtures build small repos in ``tmp_path``; resolution is against the *tracked*
file set, so they commit their files. Ambient git config is neutralised
process-wide by the package ``conftest.py``.
"""
from __future__ import annotations

import json
import os
import subprocess
from pathlib import Path

from lib import ownership_parser, structure_drift
from lib import structure_graph as sg
from lib.structure_drift import (
    SEAM_ALLOWLIST,
    apply_seam_allowlist,
    cochange_grouping_relation,
    compute_grouping_disagreement,
    detect_grouping_disagreement,
    detect_path_existence_drift,
    human_grouping_relation,
    static_grouping_relation,
)

FIXTURES = Path(__file__).parent / "fixtures" / "structure_drift"


def _copy_fixture(repo: Path, name: str, dest: str) -> None:
    """Copy a structure_drift fixture into a repo at a given relative path."""
    target = repo / dest
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text((FIXTURES / name).read_text(encoding="utf-8"),
                      encoding="utf-8")


def _git(repo: Path, *args: str) -> None:
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True,
                   env={**os.environ})


def _init_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "dev@example.com")
    _git(repo, "config", "user.name", "Dev")
    return repo


def _write(repo: Path, rel: str, text: str = "x\n") -> None:
    p = repo / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _commit_all(repo: Path, message: str = "c") -> None:
    _git(repo, "add", "-A")
    _git(repo, "commit", "-q", "-m", message)


def _patterns(result: dict) -> list[str]:
    return [e["pattern"] for e in result["empty_ownership_patterns"]]


# --- 1. CODEOWNERS empty-glob detection --------------------------------------

def test_empty_codeowners_glob_is_flagged(tmp_path: Path) -> None:
    """A CODEOWNERS glob matching no tracked file surfaces as drift.

    ``*.py`` matches the committed file (no drift); ``legacy/**`` matches nothing
    (the directory is gone) and is the sole empty pattern, attributed to
    ``CODEOWNERS``.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _write(repo, "CODEOWNERS", "*.py @a\nlegacy/** @b\n")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert result["available"] is True
    assert result["tier_0_available"] is True
    assert result["empty_ownership_patterns"] == [
        {"pattern": "legacy/**", "declared_in": "CODEOWNERS", "owners": []}
    ]


def test_all_valid_codeowners_yields_no_findings(tmp_path: Path) -> None:
    """When every glob matches at least one file, there is no drift.

    The map is still available; the empty list is empty and coverage is full.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "docs/guide.md")
    _write(repo, "CODEOWNERS", "src/** @a\ndocs/ @b\n")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert result["available"] is True
    assert result["empty_ownership_patterns"] == []
    assert result["total_patterns"] == 2
    assert result["matched_patterns"] == 2
    assert result["coverage_ratio"] == 1.0


def test_mixed_state_reports_only_the_empty_pattern(tmp_path: Path) -> None:
    """A repo with both live and stale globs reports only the stale one.

    Coverage reflects the split: two of three declared patterns match.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "docs/x.md")
    _write(repo, "CODEOWNERS", "src/** @a\ndocs/ @b\nghost/** @c\n")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert _patterns(result) == ["ghost/**"]
    assert result["total_patterns"] == 3
    assert result["matched_patterns"] == 2
    assert result["coverage_ratio"] == 0.667


# --- 2. ARCHITECTURE.md stale-reference detection ----------------------------

def test_architecture_stale_module_ref_to_deleted_dir(tmp_path: Path) -> None:
    """A stale ARCHITECTURE.md path reference to a missing dir surfaces as drift.

    The doc declares two boundaries: a live one owning ``src/api/`` (matches) and
    a stale one owning ``src/legacy/`` (deleted, matches nothing). Only the stale
    reference is flagged, attributed to its ``<doc>::<header>`` boundary.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/api/server.py")
    _write(repo, "ARCHITECTURE.md", "\n".join([
        "## API layer",
        "The API module owns `src/api/`.",
        "",
        "## Legacy",
        "The legacy module owns `src/legacy/`.",
    ]) + "\n")
    _commit_all(repo)

    # The parser normalises a reference's trailing punctuation, so the prose
    # ``src/legacy/`` is captured as ``src/legacy`` - that normalised form is the
    # reported pattern.
    result = detect_path_existence_drift(repo)
    assert result["empty_ownership_patterns"] == [
        {"pattern": "src/legacy", "declared_in": "ARCHITECTURE.md::Legacy",
         "owners": []}
    ]


def test_codeowners_and_architecture_empties_merge_and_sort(tmp_path: Path) -> None:
    """Empties from both sources merge into one list sorted by (pattern, source).

    A stale CODEOWNERS glob and a stale architecture reference both appear,
    ordered by pattern then declaring source - the deterministic merge key.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "CODEOWNERS", "src/** @a\nzzz/** @b\n")
    _write(repo, "ARCHITECTURE.md", "\n".join([
        "## Core",
        "owns `src/`",
        "## Ghost",
        "owns `aaa/gone/`",
    ]) + "\n")
    _commit_all(repo)

    # Architecture prose ``aaa/gone/`` normalises to ``aaa/gone``; the merge then
    # sorts the two empties by (pattern, source).
    result = detect_path_existence_drift(repo)
    assert _patterns(result) == ["aaa/gone", "zzz/**"]


# --- 3. Excluded-only patterns count as empty --------------------------------

def test_pattern_matching_only_excluded_files_is_empty(tmp_path: Path) -> None:
    """A glob whose only matches sit under an excluded dir reports as drift.

    ``node_modules`` is a built-in exclude, so a ``node_modules/**`` glob resolves
    to an empty set even though files exist there - the excluded tree is not part
    of the navigable repo a contributor reasons over.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "node_modules/dep/index.js")
    _write(repo, "CODEOWNERS", "src/** @a\nnode_modules/** @vendor\n")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert _patterns(result) == ["node_modules/**"]


# --- 4. Graceful degradation -------------------------------------------------

def test_no_ownership_map_degrades(tmp_path: Path) -> None:
    """A repo with no CODEOWNERS and no boundary doc reports no ownership map."""
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert result["available"] is False
    assert result["reason"] == "no ownership map"
    assert result["tier_0_available"] is False
    assert result["empty_ownership_patterns"] == []
    assert result["total_patterns"] == 0
    assert result["coverage_ratio"] == 0.0


# --- 5. Determinism ----------------------------------------------------------

def test_output_is_byte_identical_across_runs(tmp_path: Path) -> None:
    """Two runs over one repo serialize to identical output.

    Sets are sorted at the boundary, so no iteration order leaks. Serialising the
    full block twice and asserting equality pins the determinism contract.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "src/b.py")
    _write(repo, "CODEOWNERS", "src/** @a\nghost/** @b\nz/** @c\n")
    _write(repo, "ARCHITECTURE.md", "## Core\nowns `src/` and `dead/`\n")
    _commit_all(repo)

    first = json.dumps(detect_path_existence_drift(repo), sort_keys=True)
    second = json.dumps(detect_path_existence_drift(repo), sort_keys=True)
    assert first == second


# --- 6. Integration: this repo's own seam map --------------------------------

def test_integration_lib_readme_seam_paths_are_not_false_positives() -> None:
    """This repo's lib README seam declaration does not false-positive.

    ``skills/assess/scripts/lib/README.md`` names ``doc_graph.py`` and the
    ``skills/assess/...`` seam directories as load-bearing boundaries; they all
    resolve to real tracked paths, so none of them appears in
    ``empty_ownership_patterns``. This is the dogfood guard that Tier 0 reads a
    genuine, human-written ownership map on real data without manufacturing drift.
    """
    repo_root = Path(__file__).resolve().parents[3]  # repo top
    result = detect_path_existence_drift(repo_root)

    assert result["available"] is True
    seam_doc = "skills/assess/scripts/lib/README.md"
    offenders = [
        e for e in result["empty_ownership_patterns"]
        if e["declared_in"].startswith(seam_doc + "::")
        and "doc_graph.py" in e["pattern"]
    ]
    assert offenders == [], offenders


# =====================================================================
# Tier 1 - equivalence-relation grouping disagreement
# =====================================================================

def _p(name: str) -> Path:
    return Path(name)


# --- 7. Relation construction from a grouping --------------------------------

def test_human_relation_emits_all_same_group_pairs() -> None:
    """A boundary owning n files contributes its n*(n-1)/2 canonical pairs.

    Two boundaries each owning two files yield two intra-group pairs; the cross-
    boundary pairs are absent (different groups), and every pair is canonical
    (``file_a < file_b``).
    """
    ownership = {
        "A": {_p("f1.py"), _p("f2.py")},
        "B": {_p("f3.py"), _p("f4.py")},
    }
    rel = human_grouping_relation(ownership)
    assert rel == {
        (_p("f1.py"), _p("f2.py")),
        (_p("f3.py"), _p("f4.py")),
    }


def test_singleton_group_contributes_no_pair() -> None:
    """A boundary owning one file declares no co-membership, so adds no pair."""
    assert human_grouping_relation({"solo": {_p("only.py")}}) == set()


def test_cochange_relation_filters_by_support_threshold() -> None:
    """Only co-change pairs at or above the support threshold enter the relation.

    The pair below ``threshold_pct`` is dropped; the survivor is canonicalised
    regardless of the order ``change_coupling`` listed its files.
    """
    pairs = [
        {"file_a": "b.py", "file_b": "a.py", "co_change_count": 9, "support_pct": 12.0},
        {"file_a": "c.py", "file_b": "d.py", "co_change_count": 2, "support_pct": 1.0},
    ]
    rel = cochange_grouping_relation(pairs, threshold_pct=5.0)
    assert rel == {(_p("a.py"), _p("b.py"))}


# --- 8. Split-vs-fuse disagreement -------------------------------------------

def test_split_and_fuse_are_directional_set_differences() -> None:
    """human-static and static-human capture the two disagreement directions.

    ``human`` groups (f1,f2); ``static`` instead groups (f2,f3). The pair the
    human declares but static splits is (f1,f2); the pair static fuses but the
    human splits is (f2,f3); they share no agreement.
    """
    human = {(_p("f1"), _p("f2"))}
    static = {(_p("f2"), _p("f3"))}
    d = compute_grouping_disagreement(human, static, cochange_rel=set())
    assert d["human_grouped_static_splits"] == [{"file_a": "f1", "file_b": "f2"}]
    assert d["human_grouped_static_splits_count"] == 1
    assert d["human_split_static_fuses"] == [{"file_a": "f2", "file_b": "f3"}]
    assert d["human_static_agree"] == []


def test_agreement_is_the_intersection() -> None:
    """A pair both lenses group lands in the agree set, not either difference."""
    human = {(_p("f1"), _p("f2")), (_p("f3"), _p("f4"))}
    static = {(_p("f1"), _p("f2"))}
    d = compute_grouping_disagreement(human, static, cochange_rel=set())
    assert d["human_static_agree"] == [{"file_a": "f1", "file_b": "f2"}]
    assert d["human_grouped_static_splits"] == [{"file_a": "f3", "file_b": "f4"}]


# --- 9. THE label-permutation invariance test (the hard gate) ----------------

def test_disagreement_is_invariant_to_community_relabeling() -> None:
    """Relabeling / reordering the communities must not change any metric.

    Communities ``[A:{f1,f2}, B:{f3,f4}]`` and the relabelled, reordered
    ``[X:{f3,f4}, Y:{f1,f2}]`` are the SAME partition - same co-membership
    relation. The disagreement against a fixed human grouping must be byte-
    identical. This is the correctness property of the whole tier: the metric
    carries pairs, never community labels.
    """
    human = {(_p("f1"), _p("f2"))}

    static_a = {(_p("f1"), _p("f2")), (_p("f3"), _p("f4"))}
    # Same partition, communities swapped and relabelled - identical relation.
    static_b = {(_p("f3"), _p("f4")), (_p("f1"), _p("f2"))}

    d_a = compute_grouping_disagreement(human, static_a, cochange_rel=set())
    d_b = compute_grouping_disagreement(human, static_b, cochange_rel=set())
    assert json.dumps(d_a, sort_keys=True) == json.dumps(d_b, sort_keys=True)


def test_static_relation_invariant_to_community_order(tmp_path: Path) -> None:
    """``static_grouping_relation`` ignores community order and labels.

    Building the relation from communities in one order and from the reversed
    list yields the identical pair set - the relation never records which
    community a pair came from. Uses bare module names that resolve to no file,
    so the relation is exercised purely as set math (empty here), the invariance
    holding trivially and by construction.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _commit_all(repo)
    comms = [{"lib.x", "lib.y"}, {"lib.z", "lib.w"}]
    forward = static_grouping_relation(repo, comms)
    reverse = static_grouping_relation(repo, list(reversed(comms)))
    assert forward == reverse


# --- 10. Seam allowlist ------------------------------------------------------

def test_seam_allowlist_drops_the_allowlisted_pair() -> None:
    """A pair straddling an allowlisted seam is subtracted from the denominator.

    The lib<->tests seam pair is removed from the disagreement list and its count
    drops to zero; a genuine off-seam disagreement is untouched.
    """
    seam_pair = {
        "file_a": "skills/assess/scripts/lib/foo.py",
        "file_b": "skills/assess/tests/test_foo.py",
    }
    off_seam = {"file_a": "src/a.py", "file_b": "src/b.py"}
    disagreement = {
        "human_grouped_never_cochange": [seam_pair, off_seam],
        "human_grouped_never_cochange_count": 2,
    }
    filtered = apply_seam_allowlist(disagreement)
    assert filtered["human_grouped_never_cochange"] == [off_seam]
    assert filtered["human_grouped_never_cochange_count"] == 1


def test_seam_allowlist_only_removes_never_adds() -> None:
    """An allowlist can only shrink a list (correct-by-construction denominator)."""
    disagreement = {
        "human_split_but_cochange": [{"file_a": "x/a.py", "file_b": "y/b.py"}],
        "human_split_but_cochange_count": 1,
    }
    filtered = apply_seam_allowlist(disagreement)
    assert len(filtered["human_split_but_cochange"]) <= 1


# --- 11. Top-level callable: degradation + determinism -----------------------

def test_tier1_degrades_with_no_ownership_map(tmp_path: Path) -> None:
    """No CODEOWNERS and no boundary doc -> available:False, all lists empty."""
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _commit_all(repo)

    result = detect_grouping_disagreement(repo)
    assert result["available"] is False
    assert result["reason"] == "no ownership map"
    assert result["tier_1_available"] is False
    assert result["human_grouped_static_splits"] == []
    assert result["human_grouped_static_splits_count"] == 0


def test_tier1_is_byte_identical_across_runs(tmp_path: Path) -> None:
    """Two runs over one repo serialize identically (no set order leaks)."""
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "src/b.py")
    _write(repo, "CODEOWNERS", "src/** @a\n")
    _commit_all(repo)

    first = json.dumps(
        detect_grouping_disagreement(repo, communities=[], coupling_pairs=[]),
        sort_keys=True,
    )
    second = json.dumps(
        detect_grouping_disagreement(repo, communities=[], coupling_pairs=[]),
        sort_keys=True,
    )
    assert first == second


def test_tier1_human_only_groups_codeowners_files(tmp_path: Path) -> None:
    """With no static / co-change lens, a multi-file boundary self-disagrees.

    A CODEOWNERS glob grouping two files declares them co-grouped; with empty
    static and co-change relations, that pair is ``human_grouped_static_splits``
    AND ``human_grouped_never_cochange`` (no lens corroborates it) and never
    ``agree``.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "pkg/a.py")
    _write(repo, "pkg/b.py")
    _write(repo, "CODEOWNERS", "pkg/** @team\n")
    _commit_all(repo)

    result = detect_grouping_disagreement(repo, communities=[], coupling_pairs=[])
    assert result["available"] is True
    pair = {"file_a": "pkg/a.py", "file_b": "pkg/b.py"}
    assert pair in result["human_grouped_static_splits"]
    assert pair in result["human_grouped_never_cochange"]
    assert result["human_static_agree"] == []


# --- 12. Integration: this repo, zero false positives after allowlist --------

def test_tier1_integration_no_false_positives_after_allowlist() -> None:
    """On this repo the documented seams don't surface as Tier 1 disagreement.

    The lib README declares the ``skills/assess/scripts/lib`` <-> ``skills/assess/
    tests`` seam; any co-change pair straddling it must be absorbed by the seam
    allowlist, never reported as ``human_split_but_cochange``. This is the dogfood
    guard that the allowlist matches the README's stated seams.
    """
    repo_root = Path(__file__).resolve().parents[3]
    result = detect_grouping_disagreement(repo_root)
    assert result["available"] in (True, False)
    if not result["available"]:
        return
    for row in result["human_split_but_cochange"]:
        a, b = row["file_a"], row["file_b"]
        lib_test_seam = (
            (a.startswith("skills/assess/scripts/lib")
             and b.startswith("skills/assess/tests"))
            or (b.startswith("skills/assess/scripts/lib")
                and a.startswith("skills/assess/tests"))
        )
        assert not lib_test_seam, row


# =====================================================================
# 13. Tier 0 determinism, isolated from the rest of the block
# =====================================================================
#
# Tasks 9/10 pin determinism of the *serialised block* (tests 5 and 14).
# These isolate the three primitives that feed it: the CODEOWNERS parse, the
# empty-set ordering, and the filesystem walk - each independently reproducible
# so a regression in any one is localised rather than read off the merged block.

def test_codeowners_parse_is_identical_across_two_reads(tmp_path: Path) -> None:
    """Parsing one CODEOWNERS twice yields identical glob->match maps.

    ``parse_codeowners`` resolves each glob against the tracked file set; the
    same repo must produce the same map on every call (no walk-order or
    set-iteration nondeterminism leaks into the resolved paths).
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "src/b.py")
    _copy_fixture(repo, "codeowners_mixed", "CODEOWNERS")
    _commit_all(repo)

    first = ownership_parser.parse_codeowners(repo)
    second = ownership_parser.parse_codeowners(repo)
    # Compare as sorted POSIX strings so the dict-of-sets equality is on the
    # resolved relation, not on set object identity.
    norm = {p: sorted(f.as_posix() for f in files)
            for p, files in first.items()}
    norm2 = {p: sorted(f.as_posix() for f in files)
             for p, files in second.items()}
    assert norm == norm2


def test_empty_patterns_emit_in_sorted_order_regardless_of_declaration(
    tmp_path: Path,
) -> None:
    """Empty patterns sort by (pattern, source), independent of file order.

    Three stale globs are declared in reverse-alphabetical order in the file;
    the reported list is sorted ascending - the merge key, not the line order,
    fixes the output sequence.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "CODEOWNERS",
           "src/** @keep\nzzz/** @c\nmmm/** @b\naaa/** @a\n")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert _patterns(result) == ["aaa/**", "mmm/**", "zzz/**"]


def test_filesystem_walk_match_set_is_reproducible(tmp_path: Path) -> None:
    """A glob's match set is the sorted tracked files, stable across runs.

    The drift signal resolves ``src/**`` against the git ls-files set; two runs
    must report the same coverage counts, pinning the walk's reproducibility.
    """
    repo = _init_repo(tmp_path)
    for name in ("d.py", "a.py", "c.py", "b.py"):
        _write(repo, f"src/{name}")
    _write(repo, "CODEOWNERS", "src/** @team\n")
    _commit_all(repo)

    first = detect_path_existence_drift(repo)
    second = detect_path_existence_drift(repo)
    assert first["matched_patterns"] == second["matched_patterns"] == 1
    assert first["empty_ownership_patterns"] == []
    assert first == second


# =====================================================================
# 14. Label-permutation invariance - the reorder + relabel variant
# =====================================================================
#
# THE critical test. Task 10 added relation-relabel invariance (test 9) over
# pre-built relations and the static-relation order invariance (test 10). This
# pins the contract end-to-end at the level the requirement states it: two
# *static communities* expressing the SAME partition - once swapped X<->Y and
# once with the community LIST reversed - must yield byte-identical disagreement
# against a fixed human grouping. The metric keys on the equivalence relation,
# not the partition labels.

def test_disagreement_invariant_to_community_swap_and_reorder() -> None:
    """THE critical test - metric keys on the equivalence relation, not labels.

    Human groups A={f1,f2}, B={f3,f4}. Static communities X={f1,f2}, Y={f3,f4}.
    The disagreement against the human grouping is computed three ways that all
    describe the SAME partition: (a) the baseline, (b) the two communities
    relabelled and swapped (X<->Y), and (c) the community list reversed. All
    three must serialise byte-identically - any label or order dependence would
    break here and nowhere else.
    """
    f1, f2, f3, f4 = (_p("f1.py"), _p("f2.py"), _p("f3.py"), _p("f4.py"))
    human = human_grouping_relation({"A": {f1, f2}, "B": {f3, f4}})

    # Relation built from communities listed [X, Y].
    static_xy = (structure_drift._pairs_within({f1, f2})
                 | structure_drift._pairs_within({f3, f4}))
    # Same partition, communities swapped/relabelled [Y, X].
    static_yx = (structure_drift._pairs_within({f3, f4})
                 | structure_drift._pairs_within({f1, f2}))

    base = compute_grouping_disagreement(human, static_xy, cochange_rel=set())
    swapped = compute_grouping_disagreement(human, static_yx, cochange_rel=set())

    base_json = json.dumps(base, sort_keys=True)
    assert base_json == json.dumps(swapped, sort_keys=True)
    # And the disagreement is the expected, label-free content: the two human
    # boundaries are exactly the two static communities, so everything agrees
    # and nothing splits.
    assert base["human_grouped_static_splits"] == []
    assert base["human_split_static_fuses"] == []
    assert base["human_static_agree_count"] == 2


# =====================================================================
# 15. Seam allowlist - the denominator arithmetic, pinned exactly
# =====================================================================

def test_seam_allowlist_subtracts_from_denominator_not_the_ratio() -> None:
    """Allowlisted pairs leave the denominator BEFORE any ratio is taken.

    Pins the requirement's worked example: of 100 declared-grouping pairs, 47
    straddle an allowlisted seam and 10 of the remaining 53 are genuine
    disagreements. The honest drift ratio is 10 / (100 - 47) = 10/53, never
    10/100 - the allowlist shrinks the denominator, it does not divide into the
    raw total. Here the disagreement list is the 10 off-seam pairs plus the 47
    seam pairs; after the allowlist only the 10 survive, so the count is 10 and
    a caller dividing by the surviving universe gets 10/53.
    """
    seam = SEAM_ALLOWLIST[0]  # skills/assess/scripts/lib <-> skills/assess/tests
    lo, hi = seam
    # 47 pairs that straddle the allowlisted seam.
    seam_pairs = [
        {"file_a": f"{lo}/mod{i}.py", "file_b": f"{hi}/test_mod{i}.py"}
        for i in range(47)
    ]
    # 10 genuine off-seam disagreements.
    off_seam = [
        {"file_a": f"src/a{i}.py", "file_b": f"src/b{i}.py"} for i in range(10)
    ]
    disagreement = {
        "human_grouped_never_cochange": seam_pairs + off_seam,
        "human_grouped_never_cochange_count": 57,
    }
    filtered = apply_seam_allowlist(disagreement)
    survivors = filtered["human_grouped_never_cochange"]

    assert filtered["human_grouped_never_cochange_count"] == 10
    assert {(r["file_a"], r["file_b"]) for r in survivors} == {
        (r["file_a"], r["file_b"]) for r in off_seam
    }
    # The honest ratio the orchestrator would form: 10 over the post-allowlist
    # denominator (100 - 47 = 53), not over the raw 100.
    total_pairs, allowlisted = 100, 47
    denominator = total_pairs - allowlisted
    assert denominator == 53
    assert filtered["human_grouped_never_cochange_count"] / denominator == 10 / 53


def test_seam_allowlist_filters_agreement_lists_too(tmp_path: Path) -> None:
    """A seam pair is not double-counted as agreement after suppression.

    ``apply_seam_allowlist`` filters every list, the ``*_agree`` sets included,
    so a pair removed from a disagreement list cannot reappear as agreement.
    """
    seam = SEAM_ALLOWLIST[0]
    lo, hi = seam
    seam_pair = {"file_a": f"{lo}/x.py", "file_b": f"{hi}/test_x.py"}
    disagreement = {
        "human_static_agree": [seam_pair],
        "human_static_agree_count": 1,
    }
    filtered = apply_seam_allowlist(disagreement)
    assert filtered["human_static_agree"] == []
    assert filtered["human_static_agree_count"] == 0


def test_seam_allowlist_respects_both_orderings_of_a_pair() -> None:
    """A seam matches whichever side each tree lands on in the canonical pair.

    The ``scripts`` <-> ``skills`` seam must absorb a pair regardless of which
    of the two trees sorts first into ``file_a``.
    """
    # scripts sorts before skills, so the canonical pair has scripts as file_a;
    # assert the allowlist still matches when the lib seam's order is reversed.
    pair = {"file_a": "scripts/build.py", "file_b": "skills/assess/SKILL.md"}
    out = apply_seam_allowlist({"human_split_but_cochange": [pair],
                                "human_split_but_cochange_count": 1})
    assert out["human_split_but_cochange"] == []


# =====================================================================
# 16. Graceful degradation - the remaining honest-degrade branches
# =====================================================================

def test_empty_codeowners_file_still_degrades(tmp_path: Path) -> None:
    """A CODEOWNERS with only comments/blank lines is no ownership map.

    The file exists but declares zero globs and no boundary doc accompanies it,
    so there is nothing to drift against - Tier 0 degrades to available:False.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "a.py")
    _copy_fixture(repo, "codeowners_empty", "CODEOWNERS")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert result["available"] is False
    assert result["reason"] == "no ownership map"


def test_unreadable_architecture_doc_is_skipped_without_crashing(
    tmp_path: Path, monkeypatch,
) -> None:
    """A doc that fails to read is skipped; the rest of the scan still runs.

    The honest-degrade contract: an OSError on one architecture doc warns and
    is dropped, never aborting the assessment. A live CODEOWNERS glob alongside
    it still resolves, so the signal stays available.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "CODEOWNERS", "src/** @team\n")
    _copy_fixture(repo, "ARCHITECTURE_modules.md", "ARCHITECTURE.md")
    _commit_all(repo)

    real_read_text = Path.read_text

    def boom(self, *args, **kwargs):
        if self.name == "ARCHITECTURE.md":
            raise OSError("simulated unreadable doc")
        return real_read_text(self, *args, **kwargs)

    monkeypatch.setattr(Path, "read_text", boom)

    # The CODEOWNERS side still parses, so the block is available; the doc's
    # stale ``src/legacy`` reference never surfaces because the doc was skipped.
    # structure_drift's own OSError guard degrades silently (it never aborts the
    # scan), so no exception escapes - the contract is "skip, don't crash".
    result = detect_path_existence_drift(repo)
    assert result["available"] is True
    assert all("ARCHITECTURE.md" not in e["declared_in"]
               for e in result["empty_ownership_patterns"])


def test_malformed_codeowners_line_partial_parses_with_warning(
    tmp_path: Path, capsys,
) -> None:
    """A blank/comment-only line is skipped; valid globs still parse.

    CODEOWNERS tolerates noise: comment lines and blank lines are ignored while
    the genuine globs around them resolve. The parse is partial, never aborted -
    a live glob matches, a stale one is still flagged.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.py")
    _write(repo, "CODEOWNERS", "\n".join([
        "# ownership",
        "",
        "src/** @team",
        "   ",
        "gone/** @nobody",
    ]) + "\n")
    _commit_all(repo)

    result = detect_path_existence_drift(repo)
    assert result["available"] is True
    assert _patterns(result) == ["gone/**"]
    assert result["matched_patterns"] == 1


def test_tier1_runs_without_a_static_graph(tmp_path: Path) -> None:
    """No importable package -> Tier 1 static lens empty, but the tier still runs.

    With an ownership map but no Python package, ``_compute_communities`` returns
    no communities (line 687), so the static relation is empty. Tier 1 is still
    available and reports the human grouping's self-disagreement - Tier 0's
    existence test and Tier 1's grouping test both degrade honestly, never crash.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "src/a.txt")  # no .py, so discover_packages finds nothing
    _write(repo, "src/b.txt")
    _write(repo, "CODEOWNERS", "src/** @team\n")
    _commit_all(repo)

    # coupling_pairs omitted too, so both non-human lenses are empty.
    result = detect_grouping_disagreement(repo, coupling_pairs=[])
    assert result["available"] is True
    assert result["tier_1_available"] is True
    # The two .txt files are co-owned but no static community backs them.
    pair = {"file_a": "src/a.txt", "file_b": "src/b.txt"}
    assert pair in result["human_grouped_static_splits"]
    assert result["human_static_agree"] == []


def test_compute_communities_degrades_when_networkx_missing(
    tmp_path: Path, monkeypatch,
) -> None:
    """No networkx -> the static lens is empty, Tier 1 still available.

    Patching ``structure_graph._NETWORKX_AVAILABLE`` False makes
    ``_compute_communities`` short-circuit to ``[]`` (line 683); the standalone
    Tier 1 call then sees an empty static relation and still returns available.
    """
    monkeypatch.setattr(sg, "_NETWORKX_AVAILABLE", False)
    repo = _init_repo(tmp_path)
    _write(repo, "pkg/__init__.py")
    _write(repo, "pkg/a.py", "x = 1\n")
    _write(repo, "pkg/b.py", "y = 2\n")
    _write(repo, "CODEOWNERS", "pkg/** @team\n")
    _commit_all(repo)

    # communities omitted -> computed internally, but networkx is "missing".
    result = detect_grouping_disagreement(repo, coupling_pairs=[])
    assert result["available"] is True
    assert result["tier_1_available"] is True
    # No static community formed, so the human pair is a split, not agreement.
    assert result["human_static_agree"] == []


def test_build_module_path_map_resolves_real_package_modules() -> None:
    """The module->path map resolves this repo's own package to tracked files.

    Exercises the happy path of ``_build_module_path_map`` against a real grimp
    graph: every mapped module's value is a repo-relative ``.py`` source file
    under the package, the exact paths the human and co-change relations speak.
    """
    repo_root = Path(__file__).resolve().parents[3]
    mapping = structure_drift._build_module_path_map(repo_root)
    assert mapping  # the assess package resolves
    for module, rel in mapping.items():
        assert not rel.is_absolute()
        assert rel.suffix in (".py", "")  # a module file or package __init__
        assert (repo_root / rel).exists()


def test_build_module_path_map_drops_unresolvable_and_out_of_tree(
    tmp_path: Path, monkeypatch,
) -> None:
    """Modules with no source file or one outside the repo root are dropped.

    Stubs grimp's graph with three modules: one that resolves to a tracked file
    (kept), one ``_module_file`` cannot resolve (``src is None`` -> skipped), and
    one whose source resolves outside ``repo_root`` (``relative_to`` ValueError
    -> skipped). The map keeps only the in-tree resolvable module - the two
    defensive guards drop the rest rather than crashing.
    """
    repo = _init_repo(tmp_path)
    _write(repo, "pkg/__init__.py")
    _write(repo, "pkg/a.py", "x = 1\n")
    _commit_all(repo)
    repo = repo.resolve()

    inside = repo / "pkg" / "a.py"
    outside = (tmp_path.parent / "elsewhere" / "z.py")

    class _StubGraph:
        modules = ["pkg.a", "pkg.unresolved", "pkg.external"]

    def fake_discover(_root):
        return [repo / "pkg"]

    def fake_build(_dirs):
        return _StubGraph(), {}, {}

    def fake_module_file(module, _roots):
        if module == "pkg.a":
            return inside
        if module == "pkg.external":
            return outside  # resolves, but outside repo_root
        return None  # pkg.unresolved -> src is None

    monkeypatch.setattr(sg, "discover_packages", fake_discover)
    monkeypatch.setattr(sg, "_build_grimp_graph", fake_build)
    monkeypatch.setattr(sg, "_module_file", fake_module_file)

    mapping = structure_drift._build_module_path_map(repo)
    assert mapping == {"pkg.a": Path("pkg/a.py")}


def test_static_relation_empty_when_module_map_unavailable(
    tmp_path: Path, monkeypatch,
) -> None:
    """No resolvable module map -> the static relation is empty, not an error."""
    monkeypatch.setattr(structure_drift, "_build_module_path_map",
                        lambda _root: {})
    rel = static_grouping_relation(tmp_path, [{"lib.x", "lib.y"}])
    assert rel == set()

"""Tests for the static dependency-structure analysis (Signals A1-A4).

The deterministic core's contract: every signal is reproducible and verifiable
from a fixed source tree. These tests pin each signal's arithmetic (A1
footprint additivity + direct-only-ness), graph semantics (A2 SCCs and Q range,
A3 front-door vs burrow, A4 cut-lines), the config read, and graceful
degradation when grimp / networkx are absent -- plus an integration run against
this package itself.
"""
from __future__ import annotations

import networkx as nx

from lib import structure_graph as sg
from lib.assess_config import DEFAULT_KEYHOLE_BUDGET


# --------------------------------------------------------------------------
# Graceful degradation
# --------------------------------------------------------------------------

def test_degrades_when_grimp_missing(monkeypatch, tmp_path):
    monkeypatch.setattr(sg, "_GRIMP_AVAILABLE", False)
    result = sg.analyze_structure(tmp_path)
    assert result.available is False
    assert "grimp" in result.reason
    # Still JSON-serialisable and carries the budget.
    assert result.as_dict()["available"] is False


def test_degrades_when_networkx_missing(monkeypatch, tmp_path):
    monkeypatch.setattr(sg, "_NETWORKX_AVAILABLE", False)
    result = sg.analyze_structure(tmp_path)
    assert result.available is False
    assert "networkx" in result.reason


def test_no_packages_is_available_but_empty(tmp_path):
    (tmp_path / "loose.py").write_text("x = 1\n")  # no __init__.py anywhere
    result = sg.analyze_structure(tmp_path)
    assert result.available is True
    assert result.footprints == []
    assert "no importable" in result.reason


# --------------------------------------------------------------------------
# A1 -- comprehension footprint
# --------------------------------------------------------------------------

def test_footprint_components_sum_to_total():
    surfaces = {"A": 3, "B": 2}
    sizes = {"A": 100, "B": 40}
    fp = sg.compute_footprint("A", ["B"], surfaces, sizes, keyhole_budget=2000)
    assert fp["size"] == 100
    assert fp["dep_surface"] == 2          # public_surface(B)
    assert fp["exposed_surface"] == 3      # public_surface(A)
    assert fp["total"] == fp["size"] + fp["dep_surface"] + fp["exposed_surface"]
    assert fp["total"] == 105


def test_footprint_over_budget_flag():
    fp = sg.compute_footprint(
        "A", [], {"A": 0}, {"A": 5000}, keyhole_budget=2000,
    )
    assert fp["over_budget"] is True
    fp2 = sg.compute_footprint(
        "A", [], {"A": 0}, {"A": 10}, keyhole_budget=2000,
    )
    assert fp2["over_budget"] is False


def test_footprint_uses_direct_deps_only():
    # A -> B -> C. A's direct dep is only B. C's surface must NOT leak in.
    surfaces = {"A": 1, "B": 2, "C": 999}
    sizes = {"A": 10, "B": 10, "C": 10}
    fp = sg.compute_footprint("A", ["B"], surfaces, sizes, keyhole_budget=2000)
    assert fp["dep_surface"] == 2  # B only, not B + C
    # Changing C's surface leaves A's footprint untouched (transitive isolation).
    surfaces["C"] = 1
    fp_again = sg.compute_footprint("A", ["B"], surfaces, sizes, keyhole_budget=2000)
    assert fp_again["total"] == fp["total"]


# --------------------------------------------------------------------------
# A2 -- blob vs modular
# --------------------------------------------------------------------------

def test_cycle_is_one_scc():
    g = nx.DiGraph()
    g.add_edges_from([("A", "B"), ("B", "C"), ("C", "A")])
    sccs, q = sg.compute_modularity(g)
    assert len(sccs) == 1
    assert sccs[0] == ["A", "B", "C"]
    assert -0.5 <= q <= 1.0


def test_acyclic_has_no_multi_member_scc():
    g = nx.DiGraph()
    g.add_edges_from([("A", "B"), ("B", "C")])
    sccs, q = sg.compute_modularity(g)
    assert sccs == []
    assert -0.5 <= q <= 1.0


def test_separated_clusters_score_higher_than_dense_crosstalk():
    # Two tight triangles joined by a single bridge edge: clear modularity.
    separated = nx.DiGraph()
    separated.add_edges_from([
        ("a1", "a2"), ("a2", "a3"), ("a3", "a1"),
        ("b1", "b2"), ("b2", "b3"), ("b3", "b1"),
        ("a1", "b1"),
    ])
    _, q_sep = sg.compute_modularity(separated)

    # Everything wired to everything: near-zero / negative modularity.
    dense = nx.DiGraph()
    nodes = ["n1", "n2", "n3", "n4"]
    for u in nodes:
        for v in nodes:
            if u != v:
                dense.add_edge(u, v)
    _, q_dense = sg.compute_modularity(dense)

    assert q_sep > q_dense
    assert -0.5 <= q_sep <= 1.0
    assert -0.5 <= q_dense <= 1.0


# --------------------------------------------------------------------------
# A3 -- contracts (front door vs burrow)
# --------------------------------------------------------------------------

def test_all_imports_via_front_door_ratio_is_one():
    g = nx.DiGraph()
    # app imports the pkg package itself (its __init__ / public API).
    g.add_edge("app", "pkg")
    ratio, burrow = sg.compute_front_door_ratio(g, packages={"app", "pkg"})
    assert ratio == 1.0
    assert burrow == []


def test_burrowing_lowers_ratio_and_records_edges():
    g = nx.DiGraph()
    g.add_edge("app", "pkg")            # front door
    g.add_edge("app", "pkg.internal")   # burrow into internals
    ratio, burrow = sg.compute_front_door_ratio(g, packages={"app", "pkg"})
    assert ratio == 0.5  # 1 front / 2 total -- exactly representable
    assert burrow == [{"importer": "app", "imported": "pkg.internal"}]


def test_intra_package_edges_are_not_contract_edges():
    g = nx.DiGraph()
    g.add_edge("pkg.a", "pkg.b")  # same package -> internal cohesion, ignored
    ratio, burrow = sg.compute_front_door_ratio(g, packages={"pkg"})
    assert ratio == 1.0
    assert burrow == []


# --------------------------------------------------------------------------
# A4 -- breakup candidates
# --------------------------------------------------------------------------

def test_cohesive_package_is_not_a_breakup_candidate():
    # One dense cluster of 4 modules -> cohesive, no proposed split.
    g = nx.DiGraph()
    mods = ["p.a", "p.b", "p.c", "p.d"]
    for u in mods:
        for v in mods:
            if u != v:
                g.add_edge(u, v)
    assert sg.find_breakup_candidates("p", g) is None


def test_two_clusters_yield_a_candidate_with_two_cuts():
    g = nx.DiGraph()
    # Two tight triangles, one thin bridge -> two natural cut-lines.
    g.add_edges_from([
        ("p.a1", "p.a2"), ("p.a2", "p.a3"), ("p.a3", "p.a1"),
        ("p.b1", "p.b2"), ("p.b2", "p.b3"), ("p.b3", "p.b1"),
        ("p.a1", "p.b1"),
    ])
    candidate = sg.find_breakup_candidates("p", g)
    assert candidate is not None
    assert candidate["package"] == "p"
    assert candidate["num_clusters"] == 2
    assert len(candidate["clusters"]) == 2
    # Every module is assigned to exactly one cut-line.
    flat = [m for cluster in candidate["clusters"] for m in cluster]
    assert sorted(flat) == sorted(g.nodes())


def test_too_small_package_returns_none():
    g = nx.DiGraph()
    g.add_edges_from([("p.a", "p.b"), ("p.c", "p.a")])  # 3 nodes < threshold
    assert sg.find_breakup_candidates("p", g) is None


# --------------------------------------------------------------------------
# Config
# --------------------------------------------------------------------------

def test_keyhole_budget_default_when_no_config(tmp_path):
    from lib.assess_config import load_structure_config
    cfg = load_structure_config(tmp_path)
    assert cfg["keyhole_budget"] == DEFAULT_KEYHOLE_BUDGET


def test_keyhole_budget_read_from_config(tmp_path):
    from lib.assess_config import load_structure_config
    assess = tmp_path / ".assess"
    assess.mkdir()
    (assess / "config.toml").write_text(
        "[structure]\nkeyhole_budget = 1500\n"
    )
    cfg = load_structure_config(tmp_path)
    assert cfg["keyhole_budget"] == 1500


def test_keyhole_budget_rejects_malformed_value(tmp_path):
    from lib.assess_config import load_structure_config
    assess = tmp_path / ".assess"
    assess.mkdir()
    # A non-positive / wrong-typed value falls back to the default.
    (assess / "config.toml").write_text(
        '[structure]\nkeyhole_budget = "lots"\n'
    )
    cfg = load_structure_config(tmp_path)
    assert cfg["keyhole_budget"] == DEFAULT_KEYHOLE_BUDGET


# --------------------------------------------------------------------------
# Package discovery
# --------------------------------------------------------------------------

def test_discover_packages_finds_top_level_only(tmp_path):
    pkg = tmp_path / "pkg"
    sub = pkg / "sub"
    pkg.mkdir()
    sub.mkdir()
    (pkg / "__init__.py").write_text("")
    (sub / "__init__.py").write_text("")
    found = sg.discover_packages(tmp_path)
    assert found == [pkg.resolve()]  # sub is a subpackage, not top-level


def test_discover_packages_skips_excluded_dirs(tmp_path):
    real = tmp_path / "real"
    real.mkdir()
    (real / "__init__.py").write_text("")
    venv_pkg = tmp_path / ".venv" / "junk"
    venv_pkg.mkdir(parents=True)
    (venv_pkg / "__init__.py").write_text("")
    found = sg.discover_packages(tmp_path)
    assert found == [real.resolve()]


# --------------------------------------------------------------------------
# Integration -- analyse this package itself
# --------------------------------------------------------------------------

def test_analyze_structure_on_lib_itself():
    from pathlib import Path
    lib_dir = Path(__file__).resolve().parent.parent / "scripts" / "lib"
    result = sg.analyze_structure(lib_dir)
    assert result.available is True
    assert result.reason == ""
    assert result.module_count > 0

    modules = {fp["module"] for fp in result.footprints}
    assert "lib.structure_graph" in modules
    assert "lib.assess_config" in modules

    # Q is computed and in range; result round-trips to JSON-friendly dict.
    assert -0.5 <= result.modularity_q <= 1.0
    d = result.as_dict()
    assert d["module_count"] == result.module_count
    assert isinstance(d["footprints"], list)
    # Every footprint exposes the expected arithmetic shape.
    sample = result.footprints[0]
    assert sample["total"] == (
        sample["size"] + sample["dep_surface"] + sample["exposed_surface"]
    )

"""Contract tests for ``lib/test_focus.compute_test_focus``.

Cover each signal classification, the risk-band assignment by hotspot position,
the ranking order, the ``covered_clean`` filter, the honest no-coverage degrade
(``coverage_data=None`` without ``repo_root`` -> every entry
``unknown_no_coverage`` and ``coverage_present: False``), the test-file fallback
under ``repo_root`` (``sibling_test_only`` / ``unsupported``), and the
``mutation_scope`` filter.
"""
from __future__ import annotations

import sys
from pathlib import Path

# scripts/ on the path so ``lib`` imports resolve the same way the orchestrator does.
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))

from lib.test_focus import compute_test_focus, mutation_scope  # noqa: E402


def _hot(*paths: str) -> list[dict]:
    """Build a top_hotspots-shaped list (ranked, each entry a dict with a path)."""
    return [{"path": p} for p in paths]


def _coverage(per_file: dict[str, float], overall: float = 0.5) -> dict:
    return {"_overall": overall, "per_file": per_file}


def _empty_heuristics() -> dict:
    return {
        "assertion_on_internal": [],
        "untested_boundaries": [],
        "duplicate_truth": [],
    }


def _entry(block: dict, path: str) -> dict:
    return next(e for e in block["entries"] if e["path"] == path)


# ── signal classification ─────────────────────────────────────────────────────

def test_no_covering_test_when_file_absent_from_report() -> None:
    block = compute_test_focus(_hot("a.py"), _coverage({"other.py": 0.8}),
                               _empty_heuristics())
    entry = _entry(block, "a.py")
    assert entry["test_signal"] == "no_covering_test"
    assert entry["suggested_action"] == "add_tests"
    assert entry["hollow_heuristic_kinds"] == []


def test_no_covering_test_when_line_rate_zero() -> None:
    block = compute_test_focus(_hot("a.py"), _coverage({"a.py": 0.0}),
                               _empty_heuristics())
    assert _entry(block, "a.py")["test_signal"] == "no_covering_test"


def test_covered_but_hollow_when_in_a_heuristic_bucket() -> None:
    heuristics = {
        "assertion_on_internal": [],
        "untested_boundaries": [{"file": "a.py", "line": 3, "operator": "<="}],
        "duplicate_truth": [],
    }
    block = compute_test_focus(_hot("a.py"), _coverage({"a.py": 0.9}), heuristics)
    entry = _entry(block, "a.py")
    assert entry["test_signal"] == "covered_but_hollow"
    assert entry["suggested_action"] == "strengthen_assertions"
    assert entry["hollow_heuristic_kinds"] == ["untested_boundaries"]


def test_covered_but_hollow_matches_test_file_key() -> None:
    """assertion_on_internal entries name the file under ``test_file``; a hot file
    matching that key still counts as hollow."""
    heuristics = {
        "assertion_on_internal": [
            {"test_file": "a.py", "subject_function": "test_x:obj",
             "internal_field": "_y", "confidence": "medium"}
        ],
        "untested_boundaries": [],
        "duplicate_truth": [],
    }
    block = compute_test_focus(_hot("a.py"), _coverage({"a.py": 0.9}), heuristics)
    assert _entry(block, "a.py")["hollow_heuristic_kinds"] == ["assertion_on_internal"]


def test_multiple_hollow_kinds_collected_in_report_order() -> None:
    heuristics = {
        "assertion_on_internal": [{"test_file": "a.py", "internal_field": "_y"}],
        "untested_boundaries": [{"file": "a.py", "line": 1, "operator": "<"}],
        "duplicate_truth": [{"file": "a.py", "field_name": "x", "derives_from": "y"}],
    }
    block = compute_test_focus(_hot("a.py"), _coverage({"a.py": 0.9}), heuristics)
    assert _entry(block, "a.py")["hollow_heuristic_kinds"] == [
        "assertion_on_internal", "untested_boundaries", "duplicate_truth",
    ]


def test_covered_clean_is_filtered_out() -> None:
    block = compute_test_focus(_hot("a.py"), _coverage({"a.py": 0.95}),
                               _empty_heuristics())
    assert block["entries"] == []
    assert block["total_focus_targets"] == 0
    assert block["coverage_present"] is True


# ── risk bands ────────────────────────────────────────────────────────────────

def test_risk_band_by_hotspot_position() -> None:
    paths = [f"f{i}.py" for i in range(10)]
    # No coverage report -> every file is a focus target, so all 10 appear.
    block = compute_test_focus(_hot(*paths), None, _empty_heuristics())
    band = {e["path"]: e["risk_band"] for e in block["entries"]}
    assert [band[f"f{i}.py"] for i in range(3)] == ["high", "high", "high"]
    assert [band[f"f{i}.py"] for i in range(3, 7)] == ["medium"] * 4
    assert [band[f"f{i}.py"] for i in range(7, 10)] == ["low"] * 3


def test_files_beyond_top_ten_are_excluded() -> None:
    paths = [f"f{i}.py" for i in range(13)]
    block = compute_test_focus(_hot(*paths), None, _empty_heuristics())
    assert block["total_focus_targets"] == 10
    assert all(int(e["path"][1:-3]) < 10 for e in block["entries"])


# ── ranking ───────────────────────────────────────────────────────────────────

def test_ranking_risk_band_dominates_then_signal_severity() -> None:
    # low-risk file with the most severe signal vs high-risk with a milder one:
    # the high-risk file must still rank first (band dominates).
    hot = _hot(*[f"f{i}.py" for i in range(8)])  # f0-f2 high, f3-f6 medium, f7 low
    coverage = _coverage({
        "f0.py": 0.95,  # high, covered_clean -> filtered
        "f7.py": 0.0,   # low, no_covering_test (severe)
    })
    # f0 filtered; f1,f2 high no_covering_test; f3-f6 medium; f7 low severe.
    block = compute_test_focus(hot, coverage, _empty_heuristics())
    ranked = [e["path"] for e in block["entries"]]
    # First entries are the high-band files, low-band f7 is last despite severity.
    assert ranked[0] in {"f1.py", "f2.py"}
    assert ranked[-1] == "f7.py"
    assert block["entries"][0]["risk_band"] == "high"


def test_signal_severity_orders_within_a_band() -> None:
    # Two high-risk files: one with no test (severe), one covered-but-hollow.
    hot = _hot("a.py", "b.py")
    coverage = _coverage({"b.py": 0.9})  # a.py absent -> no_covering_test
    heuristics = {
        "assertion_on_internal": [],
        "untested_boundaries": [{"file": "b.py", "line": 1, "operator": "<"}],
        "duplicate_truth": [],
    }
    block = compute_test_focus(hot, coverage, heuristics)
    ranked = [e["path"] for e in block["entries"]]
    assert ranked == ["a.py", "b.py"]  # no_covering_test outranks covered_but_hollow


# ── honest degrade ────────────────────────────────────────────────────────────

def test_no_coverage_degrades_to_unknown_not_clean() -> None:
    paths = [f"f{i}.py" for i in range(3)]
    block = compute_test_focus(_hot(*paths), None, _empty_heuristics())
    assert block["coverage_present"] is False
    assert block["available"] is True
    assert block["total_focus_targets"] == 3
    for entry in block["entries"]:
        assert entry["test_signal"] == "unknown_no_coverage"
        assert entry["suggested_action"] == "add_tests"
        assert entry["hollow_heuristic_kinds"] == []


def test_empty_inputs_produce_empty_block() -> None:
    block = compute_test_focus([], None, None)
    assert block == {
        "available": True,
        "coverage_present": False,
        "entries": [],
        "total_focus_targets": 0,
    }


def test_bare_string_hotspot_entries_supported() -> None:
    block = compute_test_focus(["a.py", "b.py"], None, _empty_heuristics())
    assert {e["path"] for e in block["entries"]} == {"a.py", "b.py"}


def test_malformed_hotspot_entries_are_skipped() -> None:
    block = compute_test_focus(
        [{"path": "a.py"}, {"no_path": 1}, None, 42],
        _coverage({"a.py": 0.0}),
        _empty_heuristics(),
    )
    assert [e["path"] for e in block["entries"]] == ["a.py"]


# ── sibling-test fallback and the unsupported signal (#317) ───────────────────


def _touch(root: Path, rel: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text("x\n", encoding="utf-8")


def test_sibling_test_fallback_credits_file_with_sibling_test(tmp_path: Path) -> None:
    """No coverage report, but a sibling test file exists: the file is credited
    as sibling_test_only / measure_coverage (never a covered bucket, never
    unknown/no_covering_test/unsupported, never add_tests). Covers each naming
    convention and the sibling __tests__/ directory."""
    for rel in ("src/a.ts", "src/a.test.ts",
                "src/b.tsx", "src/b.spec.tsx",
                "pkg/c.go", "pkg/c_test.go",
                "lib/d.py", "lib/test_d.py",
                "web/e.js", "web/__tests__/e.test.js",
                "web/f.js", "web/__tests__/f.js"):
        _touch(tmp_path, rel)
    hot = ["src/a.ts", "src/b.tsx", "pkg/c.go", "lib/d.py", "web/e.js", "web/f.js"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    assert block["coverage_present"] is False
    by_path = {e["path"]: e for e in block["entries"]}
    assert set(by_path) == set(hot)
    for path in hot:
        assert by_path[path]["test_signal"] == "sibling_test_only"
        assert by_path[path]["suggested_action"] == "measure_coverage"
        assert by_path[path]["hollow_heuristic_kinds"] == []


def test_sibling_test_fallback_keeps_hollow_heuristics(tmp_path: Path) -> None:
    """A sibling-tested file that trips a hollow heuristic keeps the
    sibling_test_only signal (no coverage was measured) but carries the hollow
    kinds so that evidence is not lost."""
    _touch(tmp_path, "src/a.py")
    _touch(tmp_path, "src/test_a.py")
    heur = _empty_heuristics()
    heur["untested_boundaries"] = [{"file": "src/a.py"}]
    block = compute_test_focus(["src/a.py"], None, heur, repo_root=tmp_path)
    entry = _entry(block, "src/a.py")
    assert entry["test_signal"] == "sibling_test_only"
    assert entry["suggested_action"] == "measure_coverage"
    assert entry["hollow_heuristic_kinds"] == ["untested_boundaries"]


def test_unsupported_test_signal_when_no_coverage_and_no_sibling(tmp_path: Path) -> None:
    """No coverage report and no sibling test: the honest signal is unsupported,
    with its own action and a severity below a known no_covering_test."""
    _touch(tmp_path, "src/b.ts")
    block = compute_test_focus(["src/b.ts"], None, None, repo_root=tmp_path)
    entry = _entry(block, "src/b.ts")
    assert entry["test_signal"] == "unsupported"
    assert entry["suggested_action"] == "measure_coverage"


def test_unsupported_test_signal_ranks_within_band(tmp_path: Path) -> None:
    """unsupported has its own severity rank: less tested ranks higher, so a file
    with no test found anywhere outranks a sibling-tested one in the same band,
    whatever the hotspot order."""
    _touch(tmp_path, "a.py")
    _touch(tmp_path, "test_a.py")
    _touch(tmp_path, "b.py")
    heur = _empty_heuristics()
    heur["duplicate_truth"] = [{"file": "a.py"}]
    block = compute_test_focus(["a.py", "b.py"], None, heur, repo_root=tmp_path)
    assert [(e["path"], e["test_signal"]) for e in block["entries"]] == [
        ("b.py", "unsupported"), ("a.py", "sibling_test_only"),
    ]


def test_sibling_test_fallback_skips_deleted_source(tmp_path: Path) -> None:
    """A stale hotspot entry for a deleted source is never credited by a test
    file that outlived it."""
    _touch(tmp_path, "src/a.test.ts")
    block = compute_test_focus(["src/a.ts"], None, None, repo_root=tmp_path)
    assert _entry(block, "src/a.ts")["test_signal"] == "unsupported"


def test_sibling_test_fallback_parallel_tests_tree(tmp_path: Path) -> None:
    """The parallel tests/ layout credits: this repo's own convention
    (skills/assess/tests/test_<stem>.py for skills/assess/scripts/lib/<stem>.py),
    a root tests/ tree mirroring the source path, a mirror that drops a src/
    root, an adjacent test/ directory, and a Go-style root test/ tree."""
    for rel in ("skills/assess/scripts/lib/doc_graph.py",
                "skills/assess/tests/test_doc_graph.py",
                "src/pkg/mod.py", "tests/src/pkg/test_mod.py",
                "src/app/view.ts", "tests/app/view.spec.ts",
                "lib/util.js", "lib/test/util.test.js",
                "cmd/run.go", "test/run_test.go"):
        _touch(tmp_path, rel)
    hot = ["skills/assess/scripts/lib/doc_graph.py", "src/pkg/mod.py",
           "src/app/view.ts", "lib/util.js", "cmd/run.go"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    assert by_path == {path: "sibling_test_only" for path in hot}


def test_sibling_test_fallback_parallel_tree_needs_matching_name(tmp_path: Path) -> None:
    """A tests/ tree with only unrelated test files does not credit a source."""
    _touch(tmp_path, "skills/assess/scripts/lib/doc_graph.py")
    _touch(tmp_path, "skills/assess/tests/test_other.py")
    _touch(tmp_path, "tests/doc_graph.py")
    block = compute_test_focus(
        ["skills/assess/scripts/lib/doc_graph.py"], None, None, repo_root=tmp_path,
    )
    assert block["entries"][0]["test_signal"] == "unsupported"


def test_no_repo_root_keeps_unknown_no_coverage() -> None:
    """Backward compatible: without repo_root the no-report degrade is unchanged."""
    block = compute_test_focus(["a.py"], None, None)
    assert block["entries"][0]["test_signal"] == "unknown_no_coverage"


def test_sibling_test_fallback_hyphenated_stem_and_test_files(tmp_path: Path) -> None:
    """A hyphenated script matches its underscore test name (this repo's
    complexity-treemap.py -> tests/test_complexity_treemap.py), and a hot file
    that is itself a test is test evidence, never 'no test found'."""
    for rel in ("skills/assess/scripts/complexity-treemap.py",
                "skills/assess/tests/test_complexity_treemap.py",
                "src/a.test.ts", "web/__tests__/b.js"):
        _touch(tmp_path, rel)
    hot = ["skills/assess/scripts/complexity-treemap.py",
           "skills/assess/tests/test_complexity_treemap.py",
           "src/a.test.ts", "web/__tests__/b.js"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    assert by_path == {path: "sibling_test_only" for path in hot}


def test_flat_tests_tree_does_not_credit_every_same_named_file(tmp_path: Path) -> None:
    """A single root tests/test_mod.py carries no path relationship to either
    src/a/mod.py or src/b/mod.py, so a bare-name match cannot credit both; this
    repo's own flat skills/assess/tests layout is still credited alongside."""
    for rel in ("src/a/mod.py", "src/b/mod.py", "tests/test_mod.py",
                "skills/assess/scripts/lib/doc_graph.py",
                "skills/assess/tests/test_doc_graph.py"):
        _touch(tmp_path, rel)
    hot = ["src/a/mod.py", "src/b/mod.py", "skills/assess/scripts/lib/doc_graph.py"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    credited = [p for p in ("src/a/mod.py", "src/b/mod.py")
                if by_path[p] == "sibling_test_only"]
    assert len(credited) <= 1
    assert by_path["skills/assess/scripts/lib/doc_graph.py"] == "sibling_test_only"


def test_flat_tests_tree_bounded_to_package_depth(tmp_path: Path) -> None:
    """A flat root tests/ tree does not reach a source nested deeper than its
    top-level package directory, while a mirrored path at the same root and a
    same-named file with a direct sibling test keep their credit."""
    for rel in ("pkg/sub/deep/mod.py", "tests/test_mod.py",
                "pkg/sub/deep/view.py", "tests/sub/deep/test_view.py",
                "src/x/util.py", "src/x/test_util.py",
                "src/y/util.py"):
        _touch(tmp_path, rel)
    hot = ["pkg/sub/deep/mod.py", "pkg/sub/deep/view.py",
           "src/x/util.py", "src/y/util.py"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    assert by_path == {
        "pkg/sub/deep/mod.py": "unsupported",
        "pkg/sub/deep/view.py": "sibling_test_only",
        "src/x/util.py": "sibling_test_only",
        "src/y/util.py": "unsupported",
    }


def test_sibling_test_fallback_jvm_ruby_and_dotnet_spellings(tmp_path: Path) -> None:
    """The focus signal reads the shared convention list, so JUnit / XCTest /
    RSpec spellings credit a file, a Ruby spec/ mirror tree credits it, and a hot
    file that is itself a ``_spec`` / ``Test`` file is test evidence."""
    for rel in ("src/Foo.java", "src/FooTest.java",
                "src/Bar.cs", "src/BarTests.cs",
                "lib/baz.rb", "lib/baz_spec.rb",
                "app/models/qux.rb", "spec/app/models/qux_spec.rb",
                "lib/quux_spec.rb", "src/CorgeTest.kt"):
        _touch(tmp_path, rel)
    hot = ["src/Foo.java", "src/Bar.cs", "lib/baz.rb", "app/models/qux.rb",
           "lib/quux_spec.rb", "src/CorgeTest.kt"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    assert by_path == {path: "sibling_test_only" for path in hot}


def test_sibling_test_fallback_with_partial_coverage_report(tmp_path: Path) -> None:
    """A present report that omits a file is not evidence of no test: with a
    sibling test on disk the file reads sibling_test_only / measure_coverage.
    Without one it stays no_covering_test, and a file the report records at a
    0 rate stays no_covering_test even with a sibling test (the report measured
    it)."""
    for rel in ("src/a.ts", "src/a.test.ts", "src/b.ts",
                "src/c.ts", "src/c.test.ts"):
        _touch(tmp_path, rel)
    cov = _coverage({"src/c.ts": 0.0, "src/other.ts": 0.8})
    heur = _empty_heuristics()
    heur["untested_boundaries"] = [{"file": "src/a.ts"}]
    block = compute_test_focus(["src/a.ts", "src/b.ts", "src/c.ts"], cov, heur,
                               repo_root=tmp_path)
    assert block["coverage_present"] is True
    got = {e["path"]: (e["test_signal"], e["suggested_action"],
                       e["hollow_heuristic_kinds"]) for e in block["entries"]}
    assert got == {
        "src/a.ts": ("sibling_test_only", "measure_coverage", ["untested_boundaries"]),
        "src/b.ts": ("no_covering_test", "add_tests", []),
        "src/c.ts": ("no_covering_test", "add_tests", []),
    }


def test_mutation_scope_keeps_only_entries_with_test_evidence(tmp_path: Path) -> None:
    """The mutation pass skips files with no test: an unsupported head entry
    (which outranks sibling_test_only in the table) never enters the scope, and
    the scope keeps the table's ranked order among the rest."""
    for rel in ("a.py", "b.py", "test_b.py", "c.py", "d.py", "test_d.py"):
        _touch(tmp_path, rel)
    block = compute_test_focus(["a.py", "b.py", "c.py", "d.py"], None, None,
                               repo_root=tmp_path)
    assert [e["test_signal"] for e in block["entries"]] == [
        "unsupported", "unsupported", "sibling_test_only", "sibling_test_only"]
    assert mutation_scope(block) == ["b.py", "d.py"]
    assert mutation_scope(block["entries"]) == ["b.py", "d.py"]
    hollow = {"entries": [
        {"path": "x.py", "test_signal": "no_covering_test"},
        {"path": "y.py", "test_signal": "covered_but_hollow"},
        {"path": "z.py", "test_signal": "unknown_no_coverage"},
    ]}
    assert mutation_scope(hollow) == ["y.py"]
    assert mutation_scope(None) == []
    assert mutation_scope({"entries": "bad"}) == []


def test_mutation_scope_excludes_hot_file_that_is_itself_a_test(tmp_path: Path) -> None:
    """A hot test file counts as its own test (sibling_test_only, never
    unsupported) and keeps its table row, but nothing tests it, so mutating it
    measures nothing: it never enters the mutation scope."""
    for rel in ("src/a.py", "src/test_a.py", "web/b.ts", "web/b.test.ts",
                "web/__tests__/c.ts"):
        _touch(tmp_path, rel)
    hot = ["src/test_a.py", "web/b.test.ts", "web/__tests__/c.ts", "src/a.py", "web/b.ts"]
    block = compute_test_focus(hot, None, None, repo_root=tmp_path)
    by_path = {e["path"]: e["test_signal"] for e in block["entries"]}
    assert by_path == {path: "sibling_test_only" for path in hot}
    assert mutation_scope(block) == ["src/a.py", "web/b.ts"]
    hollow = {"entries": [
        {"path": "tests/test_x.py", "test_signal": "covered_but_hollow"},
        {"path": "x.py", "test_signal": "covered_but_hollow"},
    ]}
    assert mutation_scope(hollow) == ["x.py"]


def test_skill_md_mutation_scope_jq_mirrors_test_path_rule() -> None:
    """SKILL.md Step 2d re-derives the mutation scope in jq; its test-file regex
    must stay the same pattern as ``sibling_tests.IS_TEST_RE`` so the offer and
    the core never disagree about which hot files are tests."""
    from lib.sibling_tests import IS_TEST_RE

    skill = (Path(__file__).resolve().parents[1] / "SKILL.md").read_text()
    focus_line = next(line for line in skill.splitlines() if line.startswith("FOCUS_FILES="))
    assert IS_TEST_RE.pattern.replace("\\", "\\\\") in focus_line
    assert '"__tests__"' in focus_line

"""Tests for Layer 1 write-side truth pressure: mutation tier + cheap heuristics."""
from __future__ import annotations

import subprocess
from pathlib import Path

import lib.test_pressure as tp
from lib.test_pressure import (
    compute_cheap_heuristics,
    compute_gap_signal,
    compute_survivor_density,
    detect_assertion_on_internal,
    detect_duplicate_truth,
    detect_mutation_config,
    detect_untested_boundaries,
    identify_survivor_clusters,
    run_bounded_mutation,
    scan_test_pressure,
    _parse_cargo_mutants,
    _parse_gremlins,
    _parse_mutmut,
    _parse_mutmut_junitxml,
    _parse_stryker_json,
)


def _write(root: Path, rel: str, text: str) -> None:
    p = root / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


# ════════════════════════════════════════════════════════════════════════════
# TASK 2 - mutation config detection
# ════════════════════════════════════════════════════════════════════════════

def test_mutation_config_none(tmp_path: Path) -> None:
    _write(tmp_path, "app.py", "x = 1")
    r = detect_mutation_config(tmp_path)
    assert r["present"] is False
    assert r["tools"] == []
    assert r["ci_integrated"] is False


def test_mutation_config_stryker_file(tmp_path: Path) -> None:
    _write(tmp_path, "stryker.conf.json", "{}")
    r = detect_mutation_config(tmp_path)
    assert r["present"] is True
    assert "stryker" in r["tools"]
    assert r["ci_integrated"] is False


def test_mutation_config_mutmut_dotfile_and_pyproject(tmp_path: Path) -> None:
    _write(tmp_path, ".mutmut.toml", "")
    r = detect_mutation_config(tmp_path)
    assert "mutmut" in r["tools"]

    other = tmp_path / "proj2"
    _write(other, "pyproject.toml", "[tool.mutmut]\npaths_to_mutate = 'src/'")
    r2 = detect_mutation_config(other)
    assert "mutmut" in r2["tools"]


def test_mutation_config_cosmic_ray(tmp_path: Path) -> None:
    _write(tmp_path, "cosmic-ray.toml", "[cosmic-ray]")
    assert "cosmic-ray" in detect_mutation_config(tmp_path)["tools"]


def test_mutation_config_cargo_mutants(tmp_path: Path) -> None:
    _write(tmp_path, "Cargo.toml",
           "[dev-dependencies]\n# uses cargo-mutants in CI\n")
    assert "cargo-mutants" in detect_mutation_config(tmp_path)["tools"]


def test_mutation_config_ci_integration(tmp_path: Path) -> None:
    """A CI file that invokes a mutation tool sets ci_integrated even with no
    config file present."""
    _write(tmp_path, ".github/workflows/mutation.yml",
           "jobs:\n  mut:\n    steps:\n      - run: npx stryker run\n")
    r = detect_mutation_config(tmp_path)
    assert r["present"] is True
    assert r["ci_integrated"] is True
    assert "stryker" in r["tools"]


def test_mutation_config_gremlins_in_gitlab_ci(tmp_path: Path) -> None:
    _write(tmp_path, ".gitlab-ci.yml", "mutation:\n  script:\n    - gremlins unleash\n")
    r = detect_mutation_config(tmp_path)
    assert r["ci_integrated"] is True
    assert "gremlins" in r["tools"]


def test_mutation_config_jenkinsfile(tmp_path: Path) -> None:
    _write(tmp_path, "Jenkinsfile", "sh 'cargo mutants'")
    r = detect_mutation_config(tmp_path)
    assert "cargo-mutants" in r["tools"]
    assert r["ci_integrated"] is True


# ════════════════════════════════════════════════════════════════════════════
# TASK 2 - mutation output parsers
# ════════════════════════════════════════════════════════════════════════════

def test_parse_stryker_json() -> None:
    out = (
        '{"files": {"src/a.ts": {"mutants": ['
        '{"status": "Killed"}, {"status": "Survived"}, {"status": "Survived"}]}}}'
    )
    parsed = _parse_stryker_json(out)
    assert len(parsed) == 1
    assert parsed[0]["file"] == "src/a.ts"
    assert parsed[0]["killed"] == 1
    assert parsed[0]["survived"] == 2
    assert parsed[0]["total"] == 3


def test_parse_stryker_json_garbage_degrades() -> None:
    assert _parse_stryker_json("not json") == []


def test_parse_mutmut_survivors_only() -> None:
    out = "src/foo.py:12\nsrc/foo.py:15\nsrc/bar.py:7\n"
    parsed = {p["file"]: p for p in _parse_mutmut(out)}
    assert parsed["src/foo.py"]["survived"] == 2
    assert parsed["src/foo.py"]["total"] is None  # mutmut only lists survivors
    assert parsed["src/bar.py"]["survived"] == 1


def test_parse_gremlins() -> None:
    out = (
        "KILLED   pkg/x.go:10:2\n"
        "LIVED    pkg/x.go:12:4\n"
        "NOT COVERED pkg/y.go:3:1\n"
    )
    by_file = {p["file"]: p for p in _parse_gremlins(out)}
    assert by_file["pkg/x.go"]["killed"] == 1
    assert by_file["pkg/x.go"]["survived"] == 1
    assert by_file["pkg/y.go"]["survived"] == 1


def test_parse_cargo_mutants() -> None:
    out = (
        "MISSED   src/lib.rs:10:5: replace foo -> bar\n"
        "CAUGHT   src/lib.rs:12:1: replace baz\n"
        "UNVIABLE src/lib.rs:14:1: nope\n"
    )
    by_file = {p["file"]: p for p in _parse_cargo_mutants(out)}
    assert by_file["src/lib.rs"]["survived"] == 1  # MISSED
    assert by_file["src/lib.rs"]["killed"] == 1    # CAUGHT, UNVIABLE ignored
    assert by_file["src/lib.rs"]["total"] == 2


# ════════════════════════════════════════════════════════════════════════════
# TASK 2 - bounded mutation run
# ════════════════════════════════════════════════════════════════════════════

def test_run_bounded_mutation_requires_opt_in(tmp_path: Path) -> None:
    _write(tmp_path, "app.py", "x = 1")
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=False)
    assert r["mutation_run"] is False
    assert r["available"] is False
    assert "opt-in" in r["reason"]


def test_run_bounded_mutation_tool_absent(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "app.py", "x = 1")
    monkeypatch.setattr(tp.shutil, "which", lambda _t: None)
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=True)
    assert r["mutation_run"] is False
    assert r["available"] is False


def test_run_bounded_mutation_runs_and_parses(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "app.py", "def f(): pass")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)

    def fake_run(cmd, **kwargs):
        return subprocess.CompletedProcess(
            cmd, 0, stdout="app.py:3\napp.py:9\n", stderr="")

    monkeypatch.setattr(tp.subprocess, "run", fake_run)
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=True)
    assert r["mutation_run"] is True
    assert r["tool"] == "mutmut"
    assert r["per_file"][0]["survived"] == 2


def test_run_bounded_mutation_caps_scope(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "app.py", "x = 1")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)
    monkeypatch.setattr(
        tp.subprocess, "run",
        lambda cmd, **k: subprocess.CompletedProcess(cmd, 0, stdout="", stderr=""))
    many = [f"f{i}.py" for i in range(20)]
    r = run_bounded_mutation(tmp_path, hot_files=many, opt_in=True)
    assert len(r["scope"]) == tp.MAX_FILES_TO_MUTATE


def test_run_bounded_mutation_timeout_degrades(tmp_path: Path, monkeypatch) -> None:
    _write(tmp_path, "app.py", "x = 1")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)

    def fake_run(cmd, **kwargs):
        raise subprocess.TimeoutExpired(cmd, tp.MUTATION_TIMEOUT)

    monkeypatch.setattr(tp.subprocess, "run", fake_run)
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=True)
    assert r["mutation_run"] is False
    assert "timeout" in r["reason"].lower()
    assert r["per_file"] == []


def test_run_bounded_mutation_prefers_detected_tool(tmp_path: Path, monkeypatch) -> None:
    """When a stryker config is present and both go+ts source exist, the
    config-detected tool wins over a merely-language-present one."""
    _write(tmp_path, "src/a.ts", "export const x = 1;")
    _write(tmp_path, "main.go", "package main")
    _write(tmp_path, "stryker.conf.json", "{}")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)
    captured = {}

    def fake_run(cmd, **kwargs):
        captured["cmd"] = cmd
        return subprocess.CompletedProcess(cmd, 0, stdout="{}", stderr="")

    monkeypatch.setattr(tp.subprocess, "run", fake_run)
    r = run_bounded_mutation(tmp_path, hot_files=["src/a.ts"], opt_in=True)
    assert r["tool"] == "stryker"
    assert captured["cmd"][0] == "stryker"


# ════════════════════════════════════════════════════════════════════════════
# TASK 2 - aggregation
# ════════════════════════════════════════════════════════════════════════════

def test_compute_survivor_density_with_totals() -> None:
    per_file = [
        {"file": "a.ts", "killed": 8, "survived": 2, "total": 10},
        {"file": "b.ts", "killed": 5, "survived": 5, "total": 10},
    ]
    d = compute_survivor_density(per_file)
    assert d["total_survived"] == 7
    assert d["total_mutants"] == 20
    assert abs(d["overall"] - 0.35) < 1e-9
    assert d["by_file"]["b.ts"] == 5


def test_compute_survivor_density_no_totals_is_none() -> None:
    per_file = [{"file": "x.py", "killed": None, "survived": 3, "total": None}]
    d = compute_survivor_density(per_file)
    assert d["overall"] is None
    assert d["total_mutants"] is None
    assert d["total_survived"] == 3


def test_identify_survivor_clusters() -> None:
    per_file = [
        {"file": "hot.py", "survived": 7},
        {"file": "warm.py", "survived": 3},
        {"file": "cool.py", "survived": 1},
    ]
    clusters = identify_survivor_clusters(per_file)
    assert [c["file"] for c in clusters] == ["hot.py", "warm.py"]  # cool below threshold
    assert clusters[0]["survived"] == 7  # sorted descending


def test_compute_gap_signal_variants() -> None:
    assert compute_gap_signal(0.9, 0.3) == "high coverage + low mutation score"
    assert compute_gap_signal(0.9, 0.8) == "no gap"
    assert compute_gap_signal(None, 0.3) == "not assessed"
    assert compute_gap_signal(0.9, None) == "not assessed"


# ════════════════════════════════════════════════════════════════════════════
# TASK 2 - mutmut junitxml parser (real totals, not survivor-only)
# ════════════════════════════════════════════════════════════════════════════

def test_parse_mutmut_junitxml_per_file_totals(fixtures_dir: Path) -> None:
    """A real mutmut junitxml fixture yields per-file killed/survived/total.
    A <testcase> with a <failure> child is a survivor; otherwise it was killed."""
    parsed = {p["file"]: p for p in
              _parse_mutmut_junitxml(fixtures_dir / "mutmut-junitxml.xml")}
    assert parsed["src/calc.py"]["killed"] == 1
    assert parsed["src/calc.py"]["survived"] == 2
    assert parsed["src/calc.py"]["total"] == 3
    assert parsed["src/util.py"]["killed"] == 2
    assert parsed["src/util.py"]["survived"] == 0
    assert parsed["src/util.py"]["total"] == 2


def test_parse_mutmut_junitxml_classname_fallback(tmp_path: Path) -> None:
    """Some versions encode the path in classname (mutmut.<dotted>) instead of
    the file attribute - derive <path>.py from it when file= is absent."""
    xml = (
        '<?xml version="1.0" ?>\n'
        '<testsuites><testsuite name="mutmut">'
        '<testcase classname="mutmut.pkg.mod" name="m1"></testcase>'
        '<testcase classname="mutmut.pkg.mod" name="m2">'
        '<failure message="bad_survived">x</failure></testcase>'
        '</testsuite></testsuites>'
    )
    p = tmp_path / "report.xml"
    p.write_text(xml, encoding="utf-8")
    parsed = {row["file"]: row for row in _parse_mutmut_junitxml(p)}
    assert parsed["pkg/mod.py"] == {
        "file": "pkg/mod.py", "killed": 1, "survived": 1, "total": 2}


def test_parse_mutmut_junitxml_missing_file_degrades(tmp_path: Path) -> None:
    assert _parse_mutmut_junitxml(tmp_path / "nope.xml") == []


def test_parse_mutmut_junitxml_malformed_degrades(tmp_path: Path) -> None:
    p = tmp_path / "bad.xml"
    p.write_text("not xml at all <<<", encoding="utf-8")
    assert _parse_mutmut_junitxml(p) == []


def test_junitxml_to_density_overall_is_non_null(fixtures_dir: Path) -> None:
    """The whole point of the fix: junitxml carries totals, so survivor density
    has a real overall value (unlike the survivor-only stdout parse)."""
    per_file = _parse_mutmut_junitxml(fixtures_dir / "mutmut-junitxml.xml")
    d = compute_survivor_density(per_file)
    assert d["overall"] is not None
    assert d["total_mutants"] == 5
    assert d["total_survived"] == 2
    assert abs(d["overall"] - 0.4) < 1e-9


def test_run_bounded_mutation_uses_junitxml(tmp_path: Path, monkeypatch,
                                            fixtures_dir: Path) -> None:
    """The two-step mutmut path: `mutmut run` then `mutmut junitxml`. The junitxml
    parse wins, so per_file carries real totals."""
    _write(tmp_path, "app.py", "def f(): pass")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)
    xml = (fixtures_dir / "mutmut-junitxml.xml").read_text(encoding="utf-8")

    def fake_run(cmd, **kwargs):
        if cmd[:2] == ["mutmut", "junitxml"]:
            return subprocess.CompletedProcess(cmd, 0, stdout=xml, stderr="")
        return subprocess.CompletedProcess(cmd, 0, stdout="app.py:3\n", stderr="")

    monkeypatch.setattr(tp.subprocess, "run", fake_run)
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=True)
    assert r["mutation_run"] is True
    assert r["tool"] == "mutmut"
    by_file = {p["file"]: p for p in r["per_file"]}
    assert by_file["src/calc.py"]["total"] == 3
    assert compute_survivor_density(r["per_file"])["overall"] is not None


def test_run_bounded_mutation_junitxml_empty_falls_back_to_stdout(
        tmp_path: Path, monkeypatch) -> None:
    """When `mutmut junitxml` is absent/empty (e.g. mutmut 3.x dropped it), the
    run degrades to the survivor-only stdout parse - exactly as before the fix."""
    _write(tmp_path, "app.py", "def f(): pass")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)

    def fake_run(cmd, **kwargs):
        if cmd[:2] == ["mutmut", "junitxml"]:
            return subprocess.CompletedProcess(cmd, 1, stdout="", stderr="no cmd")
        return subprocess.CompletedProcess(cmd, 0, stdout="app.py:3\napp.py:9\n",
                                           stderr="")

    monkeypatch.setattr(tp.subprocess, "run", fake_run)
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=True)
    assert r["mutation_run"] is True
    assert r["per_file"][0]["survived"] == 2
    assert r["per_file"][0]["total"] is None  # stdout parse: no totals


# ════════════════════════════════════════════════════════════════════════════
# TASK 3 - assertion on internal
# ════════════════════════════════════════════════════════════════════════════

def test_assertion_on_internal_flags_private_only(tmp_path: Path) -> None:
    """The hollow fingerprint: asserts on a private field, no public assertion."""
    _write(tmp_path, "test_guard.py",
           "def test_resume():\n"
           "    g = Guard()\n"
           "    assert g._resume_count == 1\n")
    findings = detect_assertion_on_internal(tmp_path)
    assert len(findings) == 1
    assert findings[0]["internal_field"] == "_resume_count"
    assert findings[0]["confidence"] == "medium"


def test_assertion_on_internal_honest_test_not_flagged(tmp_path: Path) -> None:
    """A test that also asserts on a public attribute is honest - not flagged."""
    _write(tmp_path, "test_guard.py",
           "def test_resume():\n"
           "    g = Guard()\n"
           "    assert g._resume_count == 1\n"
           "    assert g.status == 'ok'\n")
    assert detect_assertion_on_internal(tmp_path) == []


def test_assertion_on_internal_unittest_style(tmp_path: Path) -> None:
    _write(tmp_path, "test_svc_test.py",
           "class T:\n"
           "    def test_it(self):\n"
           "        self.assertEqual(svc._cache, {})\n")
    findings = detect_assertion_on_internal(tmp_path)
    assert findings and findings[0]["internal_field"] == "_cache"


def test_assertion_on_internal_dunder_not_flagged(tmp_path: Path) -> None:
    """Dunders (__len__ etc.) are protocol, not private internals."""
    _write(tmp_path, "test_x.py",
           "def test_len():\n    assert obj.__len__() == 3\n")
    assert detect_assertion_on_internal(tmp_path) == []


def test_assertion_on_internal_ts_private(tmp_path: Path) -> None:
    _write(tmp_path, "guard.test.ts",
           "it('guards', () => { expect(g._resumeCount).toBe(1); });\n")
    findings = detect_assertion_on_internal(tmp_path)
    assert findings and findings[0]["confidence"] == "low"


def test_assertion_on_internal_skips_non_test_files(tmp_path: Path) -> None:
    """A production file with `_field` access is not a test - not scanned."""
    _write(tmp_path, "guard.py", "assert g._x == 1\n")
    assert detect_assertion_on_internal(tmp_path) == []


def test_assertion_on_internal_degrades_on_syntax_error(tmp_path: Path) -> None:
    _write(tmp_path, "test_broken.py", "def test_(:\n  assert x._y\n")
    assert detect_assertion_on_internal(tmp_path) == []  # no crash


# ── #81: testing a private helper *as the subject under test* is legitimate ────

def test_assertion_on_internal_private_helper_called_not_flagged(tmp_path: Path) -> None:
    """A direct unit test of a module-private helper function calls the helper as
    the subject under test - it is not the meridian "assert on internal state"
    anti-pattern. The private name is in call position (`mod._helper(...)`), not
    a field read, so it must NOT be flagged. Reproduces the 8 false positives
    from the v1.14.0 self-check (e.g. `_is_build_artifact`, `_has_sibling_test`)."""
    _write(tmp_path, "test_treemap.py",
           "import treemap\n"
           "def test_is_build_artifact():\n"
           "    assert treemap._is_build_artifact(Path('x')) is True\n"
           "def test_has_sibling_test():\n"
           "    assert treemap._has_sibling_test(repo, 'go/foo.go') is True\n")
    assert detect_assertion_on_internal(tmp_path) == []


def test_assertion_on_internal_private_field_read_still_flagged(tmp_path: Path) -> None:
    """The #81 refinement must not weaken the true positive: a private field
    *read as a value* (not called) with no public assertion is still hollow."""
    _write(tmp_path, "test_guard.py",
           "def test_cursor():\n"
           "    p = Processor()\n"
           "    p.process(['a', 'b'])\n"
           "    assert p._last_processed_line == 2\n")
    findings = detect_assertion_on_internal(tmp_path)
    assert len(findings) == 1
    assert findings[0]["internal_field"] == "_last_processed_line"


def test_assertion_on_internal_public_method_call_keeps_test_honest(tmp_path: Path) -> None:
    """A test that calls a public method (observable behaviour) alongside a
    private-field read is honest - the public call must still count as a public
    assertion so the test is not flagged."""
    _write(tmp_path, "test_guard.py",
           "def test_mix():\n"
           "    g = Guard()\n"
           "    assert g._resume_count == 1\n"
           "    assert g.public_status() == 'ok'\n")
    assert detect_assertion_on_internal(tmp_path) == []


# ════════════════════════════════════════════════════════════════════════════
# TASK 3 - untested boundaries
# ════════════════════════════════════════════════════════════════════════════

def test_untested_boundaries_requires_coverage(tmp_path: Path) -> None:
    _write(tmp_path, "app.py", "def f(n):\n    return n <= 10\n")
    assert detect_untested_boundaries(tmp_path, coverage_data=None) == []


def test_untested_boundaries_python_compare(tmp_path: Path) -> None:
    _write(tmp_path, "app.py", "def f(n):\n    if n <= 10:\n        return n + 1\n")
    cov = {"app.py": [2, 3]}  # both lines covered
    findings = detect_untested_boundaries(tmp_path, coverage_data=cov)
    ops = {f["operator"] for f in findings}
    assert "<=" in ops
    assert "+1" in ops
    assert all(f["boundary_tested"] is False for f in findings)  # candidate only


def test_untested_boundaries_only_covered_lines(tmp_path: Path) -> None:
    _write(tmp_path, "app.py",
           "def f(n):\n    if n < 5:\n        return 0\n    if n > 9:\n        return 1\n")
    cov = {"app.py": [2]}  # only the first comparison line covered
    findings = detect_untested_boundaries(tmp_path, coverage_data=cov)
    lines = {f["line"] for f in findings}
    assert lines == {2}  # line 4 (n > 9) not covered, excluded


def test_untested_boundaries_coverage_dict_form(tmp_path: Path) -> None:
    """Coverage as {file: {line: hits}} with a zero-hit line excluded."""
    _write(tmp_path, "app.go", "func f(n int) bool {\n    return n >= 3\n}\n")
    cov = {"app.go": {2: 5, 1: 0}}
    findings = detect_untested_boundaries(tmp_path, coverage_data=cov)
    assert findings and findings[0]["operator"] == ">="


def test_untested_boundaries_skips_test_files(tmp_path: Path) -> None:
    _write(tmp_path, "app_test.go", "func TestF(t *testing.T) {\n    if n <= 1 {}\n}\n")
    cov = {"app_test.go": [2]}
    assert detect_untested_boundaries(tmp_path, coverage_data=cov) == []


# ════════════════════════════════════════════════════════════════════════════
# TASK 3 - duplicate truth
# ════════════════════════════════════════════════════════════════════════════

def test_duplicate_truth_python_direct_copy(tmp_path: Path) -> None:
    _write(tmp_path, "model.py",
           "class M:\n"
           "    def __init__(self, balance):\n"
           "        self.balance = balance\n"
           "        self.shadow = self.balance\n")
    findings = detect_duplicate_truth(tmp_path)
    dup = [f for f in findings if f["field_name"] == "shadow"]
    assert dup and dup[0]["derives_from"] == "balance"


def test_duplicate_truth_python_offset(tmp_path: Path) -> None:
    _write(tmp_path, "model.py",
           "class M:\n"
           "    def shift(self):\n"
           "        self.next_index = self.index + 1\n")
    findings = detect_duplicate_truth(tmp_path)
    assert any(f["field_name"] == "next_index"
               and f["derives_from"] == "index" for f in findings)


def test_duplicate_truth_independent_computation_not_flagged(tmp_path: Path) -> None:
    """A field also assigned from an independent computation is honest."""
    _write(tmp_path, "model.py",
           "class M:\n"
           "    def calc(self, items):\n"
           "        self.total = self.base\n"
           "        self.total = sum(items)\n")  # second assignment is independent
    findings = detect_duplicate_truth(tmp_path)
    assert all(f["field_name"] != "total" for f in findings)


def test_duplicate_truth_ts(tmp_path: Path) -> None:
    _write(tmp_path, "model.ts",
           "class M {\n  update() {\n    this.mirror = this.source;\n  }\n}\n")
    findings = detect_duplicate_truth(tmp_path)
    assert any(f["field_name"] == "mirror"
               and f["derives_from"] == "source" for f in findings)


def test_duplicate_truth_degrades_on_syntax_error(tmp_path: Path) -> None:
    _write(tmp_path, "broken.py", "class M(:\n  x =\n")
    assert detect_duplicate_truth(tmp_path) == []  # no crash


# ── #82: function-local aliasing is a transient binding, not a duplicate field ─

def test_duplicate_truth_ignores_function_local_aliasing(tmp_path: Path) -> None:
    """Ordinary local-variable aliasing inside a function body is a transient
    binding, not a duplicate source-of-truth *field*. Reproduces the 14 false
    positives from the v1.14.0 self-check (`raw = result.stdout`,
    `current = node.parent`, SVG coordinate locals `gx = mid`)."""
    _write(tmp_path, "app.py",
           "def run(result, node, mid):\n"
           "    raw = result.stdout\n"
           "    current = node.parent\n"
           "    gx = mid\n"
           "    return raw, current, gx\n")
    assert detect_duplicate_truth(tmp_path) == []


def test_duplicate_truth_instance_attribute_inside_method_still_flagged(tmp_path: Path) -> None:
    """A `self.x = self.y` copy inside a method is an instance *field*, not a
    local, and must still be flagged even though it is lexically inside a
    function."""
    _write(tmp_path, "model.py",
           "class M:\n"
           "    def sync(self):\n"
           "        self.mirror = self.source\n")
    findings = detect_duplicate_truth(tmp_path)
    assert any(f["field_name"] == "mirror" and f["derives_from"] == "source"
               for f in findings)


def test_duplicate_truth_module_level_field_still_flagged(tmp_path: Path) -> None:
    """A module-level name that only ever copies another name is a duplicate
    source of truth and stays in scope."""
    _write(tmp_path, "config.py",
           "PRIMARY = compute_primary()\n"
           "ALIAS = PRIMARY\n")
    findings = detect_duplicate_truth(tmp_path)
    assert any(f["field_name"] == "ALIAS" and f["derives_from"] == "PRIMARY"
               for f in findings)


# ════════════════════════════════════════════════════════════════════════════
# Aggregation + public entry point
# ════════════════════════════════════════════════════════════════════════════

def test_compute_cheap_heuristics_shape(tmp_path: Path) -> None:
    _write(tmp_path, "test_x.py", "def test_a():\n    assert o._p == 1\n")
    r = compute_cheap_heuristics(tmp_path)
    assert set(r) == {
        "assertion_on_internal", "untested_boundaries",
        "duplicate_truth", "confidence_note",
    }
    assert r["confidence_note"] == tp.CHEAP_HEURISTIC_NOTE
    assert r["assertion_on_internal"]  # the hollow test was flagged


def test_scan_test_pressure_full_block(tmp_path: Path) -> None:
    _write(tmp_path, "stryker.conf.json", "{}")
    _write(tmp_path, "src/a.ts", "export const x = 1;")
    _write(tmp_path, "guard.test.ts",
           "it('x', () => { expect(g._secret).toBe(1); });\n")
    block = scan_test_pressure(tmp_path, hot_files=None, opt_in=False)
    expected_keys = {
        "mutation_config_present", "mutation_tools_detected", "ci_integrated",
        "mutation_run", "mutation_scope", "per_file", "survivor_density",
        "survivor_clusters", "gap_signal", "cheap_heuristics",
    }
    assert expected_keys <= set(block)
    assert block["mutation_config_present"] is True
    assert "stryker" in block["mutation_tools_detected"]
    assert block["mutation_run"] is False         # opt_in defaulted off
    assert block["gap_signal"] == "not assessed"  # no coverage / no run
    assert block["cheap_heuristics"]["assertion_on_internal"]  # ts hollow test


def test_scan_test_pressure_never_raises_on_empty(tmp_path: Path) -> None:
    block = scan_test_pressure(tmp_path)
    assert block["mutation_config_present"] is False
    assert block["per_file"] == []
    assert block["survivor_clusters"] == []


# ════════════════════════════════════════════════════════════════════════════
# Thesis integration test - hollow vs honest fixture repos
#
# The two fixture repos under tests/fixtures/ carry an IDENTICAL source file
# (src/processor.py) and differ ONLY in what their test asserts on: the hollow
# repo pins the private `_last_processed_line` cursor; the honest repo pins the
# public `process` return value. This is the load-bearing claim of the whole
# module - a suite can have full line coverage yet pin the implementation, and
# the assertion-on-internal heuristic is what tells those two apart.
# ════════════════════════════════════════════════════════════════════════════

def test_thesis_hollow_repo_flags_internal_assertion(fixtures_dir: Path) -> None:
    """The hollow fixture asserts only on a private field -> flagged."""
    findings = detect_assertion_on_internal(fixtures_dir / "hollow_test_repo")
    assert len(findings) == 1
    assert findings[0]["internal_field"] == "_last_processed_line"
    assert findings[0]["test_file"] == "tests/test_processor.py"
    assert findings[0]["confidence"] == "medium"


def test_thesis_honest_repo_yields_no_findings(fixtures_dir: Path) -> None:
    """The honest fixture asserts on the public return value -> not flagged.

    Same source, same coverage as the hollow repo. The only variable is what the
    test pins, so a finding here would mean the heuristic flags honest tests."""
    assert detect_assertion_on_internal(fixtures_dir / "honest_test_repo") == []


def test_thesis_full_scan_separates_hollow_from_honest(fixtures_dir: Path) -> None:
    """End-to-end via the public scan_test_pressure entry point: the hollow repo
    surfaces an assertion_on_internal candidate in its test_pressure block; the
    honest repo's identical-source block carries none. This is the signal the
    LLM consumes from run-context.json."""
    hollow = scan_test_pressure(fixtures_dir / "hollow_test_repo")
    honest = scan_test_pressure(fixtures_dir / "honest_test_repo")
    assert hollow["cheap_heuristics"]["assertion_on_internal"]
    assert honest["cheap_heuristics"]["assertion_on_internal"] == []
    # The thesis is about test-pinning, not mutation setup: neither fixture
    # configures mutation testing, so that signal stays identical across both.
    assert hollow["mutation_config_present"] is False
    assert honest["mutation_config_present"] is False


def test_mutation_run_requires_parsed_mutants(tmp_path: Path, monkeypatch) -> None:
    """A tool that runs and exits 0 but yields no parsed mutants must not claim a
    run (#317): a stryker spec on a TypeScript repo used to report mutation_run
    True off an empty parse, lifting the Layer 6 cap with no evidence."""
    _write(tmp_path, "src/a.ts", "export const a = 1;")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)
    monkeypatch.setattr(
        tp.subprocess, "run",
        lambda cmd, **k: subprocess.CompletedProcess(cmd, 0, stdout="", stderr=""))
    r = run_bounded_mutation(tmp_path, hot_files=["src/a.ts"], opt_in=True)
    assert r["mutation_run"] is False
    assert r["available"] is True
    assert r["tool"] == "stryker"
    assert r["per_file"] == []
    assert r["reason"] == "no mutant records recovered from stryker output (exit code 0)"


def test_mutation_run_requires_parsed_mutants_true_with_records(
        tmp_path: Path, monkeypatch) -> None:
    """The honest path still reports a run when the parser yields mutant data."""
    _write(tmp_path, "app.py", "def f(): pass")
    monkeypatch.setattr(tp.shutil, "which", lambda t: "/usr/bin/" + t)
    monkeypatch.setattr(
        tp.subprocess, "run",
        lambda cmd, **k: subprocess.CompletedProcess(
            cmd, 0, stdout="app.py:3\n", stderr=""))
    r = run_bounded_mutation(tmp_path, hot_files=["app.py"], opt_in=True)
    assert r["mutation_run"] is True
    assert r["per_file"]

"""Tests for the understanding analysis (B4) + velocity clock (D2).

Two styles, matching the contract:
  - Pure-logic tests mock ``authorship_by_path`` / ``doc_staleness`` /
    ``complexity_stats`` and assert the orphaned-understanding logic and
    intent-source detection in isolation (repo_root is a non-git temp dir, so
    the velocity clock is exercised through its ``None`` degrade path).
  - Git-integration tests build synthetic histories with controlled commit
    metadata, feed the *real* ``authorship_analysis`` output in, and assert the
    end-to-end classification and the velocity clock against backdated commits.

Expected values are hand-noted so the contract stays auditable.
"""
from __future__ import annotations

import datetime as _dt
import os
import subprocess
from pathlib import Path

from lib.change_coupling import authorship_analysis
from lib.understanding_analysis import analyze_understanding


# --- git fixture helpers (local, for full control of author/committer/date) --

def _git(repo: Path, *args: str, env: dict | None = None) -> None:
    full_env = {**os.environ, **(env or {})}
    subprocess.run(["git", "-C", str(repo), *args],
                   check=True, capture_output=True, text=True, env=full_env)


def _write(repo: Path, rel: str, text: str) -> None:
    p = repo / rel
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(text, encoding="utf-8")


def _commit(
    repo: Path,
    files: dict[str, str],
    message: str = "change",
    *,
    author: tuple[str, str] | None = None,
    committer: tuple[str, str] | None = None,
    co_authors: list[str] | None = None,
    days_ago: int | None = None,
) -> None:
    """Write ``files`` (rel path -> contents), stage, and commit.

    ``author``/``committer`` are (name, email) tuples; ``co_authors`` is a list
    of "Name <email>" strings folded into Co-Authored-By trailers; ``days_ago``
    backdates author + committer time (git rejects relative strings, so we emit
    a strict ISO timestamp) to drive the velocity clock.
    """
    for rel, text in files.items():
        _write(repo, rel, text)
    _git(repo, "add", "-A")
    body = message
    for ca in co_authors or []:
        body += f"\n\nCo-Authored-By: {ca}"
    env: dict[str, str] = {}
    if author:
        env["GIT_AUTHOR_NAME"], env["GIT_AUTHOR_EMAIL"] = author
    if committer:
        env["GIT_COMMITTER_NAME"], env["GIT_COMMITTER_EMAIL"] = committer
    if days_ago is not None:
        when = _dt.datetime.now() - _dt.timedelta(days=days_ago)
        stamp = when.strftime("%Y-%m-%dT%H:%M:%S")
        env["GIT_AUTHOR_DATE"] = stamp
        env["GIT_COMMITTER_DATE"] = stamp
    _git(repo, "commit", "-q", "-m", body, env=env)


def _init_repo(tmp_path: Path) -> Path:
    repo = tmp_path / "repo"
    repo.mkdir()
    _git(repo, "init", "-q")
    _git(repo, "config", "user.email", "dev@example.com")
    _git(repo, "config", "user.name", "Dev Human")
    return repo


# Complexity stats with one high-CCN file. p95 absent -> MIN_HIGH_CCN (10) floor.
def _stats_high(path: str, ccn: float = 25.0) -> dict:
    return {"ccn": {"p95": 0.0}, "top_complex": [{"path": path, "ccn": ccn}]}


def _no_docs() -> dict:
    return {"available": False, "docs": []}


# --- pure-logic: the orphaned-understanding finding --------------------------

def test_orphaned_when_agent_high_complexity_no_doc(tmp_path: Path) -> None:
    """High complexity ∧ no human anchor ∧ no intent source -> orphaned."""
    authorship = {"lib/x.py": {"human_anchor": False, "authorship_class": "agent",
                               "intent_source": False, "contributors": []}}
    result = analyze_understanding(
        tmp_path, authorship, _no_docs(), _stats_high("lib/x.py"))

    assert result["available"] is True
    assert result["orphaned_understanding"] == ["lib/x.py"]
    mod = result["modules"][0]
    assert mod["finding"] == "orphaned_understanding"
    assert mod["authorship_class"] == "agent"
    assert mod["human_anchor"] is False
    assert mod["intent_source"] is False
    assert mod["recommendation"] is not None
    # Non-git repo_root -> the velocity clock degrades to None, never "fresh".
    assert mod["days_since_comprehension_event"] is None


def test_human_anchor_suppresses_orphan(tmp_path: Path) -> None:
    authorship = {"lib/x.py": {"human_anchor": True, "authorship_class": "human",
                               "intent_source": True, "contributors": []}}
    result = analyze_understanding(
        tmp_path, authorship, _no_docs(), _stats_high("lib/x.py"))

    assert result["orphaned_understanding"] == []
    assert result["modules"][0]["finding"] is None
    assert result["modules"][0]["recommendation"] is None


def test_intent_source_suppresses_orphan(tmp_path: Path) -> None:
    """A co-located doc is an intent source even with no human anchor."""
    authorship = {"lib/x.py": {"human_anchor": False, "authorship_class": "agent",
                               "intent_source": False, "contributors": []}}
    doc_staleness = {"available": True, "docs": [{"path": "lib/README.md"}]}
    result = analyze_understanding(
        tmp_path, authorship, doc_staleness, _stats_high("lib/x.py"))

    assert result["orphaned_understanding"] == []
    mod = result["modules"][0]
    assert mod["intent_source"] is True
    assert mod["finding"] is None


def test_low_complexity_not_orphaned(tmp_path: Path) -> None:
    """Below the CCN gate, agent + no doc is still not orphaned."""
    authorship = {"lib/x.py": {"human_anchor": False, "authorship_class": "agent",
                               "intent_source": False, "contributors": []}}
    # ccn 3 is below the MIN_HIGH_CCN (10) floor.
    result = analyze_understanding(
        tmp_path, authorship, _no_docs(), _stats_high("lib/x.py", ccn=3.0))

    assert result["orphaned_understanding"] == []
    assert result["modules"][0]["finding"] is None


def test_root_doc_covers_everything(tmp_path: Path) -> None:
    """A repo-root doc is an ancestor of all paths -> intent source everywhere."""
    authorship = {"lib/x.py": {"human_anchor": False, "authorship_class": "agent",
                               "intent_source": False, "contributors": []}}
    doc_staleness = {"available": True, "docs": [{"path": "README.md"}]}
    result = analyze_understanding(
        tmp_path, authorship, doc_staleness, _stats_high("lib/x.py"))

    assert result["modules"][0]["intent_source"] is True
    assert result["orphaned_understanding"] == []


def test_unrelated_doc_is_not_intent_source(tmp_path: Path) -> None:
    """A doc in a sibling subtree does not cover the module."""
    authorship = {"lib/x.py": {"human_anchor": False, "authorship_class": "agent",
                               "intent_source": False, "contributors": []}}
    doc_staleness = {"available": True, "docs": [{"path": "other/README.md"}]}
    result = analyze_understanding(
        tmp_path, authorship, doc_staleness, _stats_high("lib/x.py"))

    assert result["modules"][0]["intent_source"] is False
    assert result["orphaned_understanding"] == ["lib/x.py"]


def test_unavailable_when_no_authorship(tmp_path: Path) -> None:
    result = analyze_understanding(tmp_path, {}, _no_docs(), {})
    assert result["available"] is False
    assert result["modules"] == []
    assert result["orphaned_understanding"] == []


def test_mixed_class_passthrough(tmp_path: Path) -> None:
    authorship = {"lib/x.py": {"human_anchor": True, "authorship_class": "mixed",
                               "intent_source": True, "contributors": []}}
    result = analyze_understanding(
        tmp_path, authorship, _no_docs(), _stats_high("lib/x.py"))
    assert result["modules"][0]["authorship_class"] == "mixed"


# --- git-integration: real authorship + the velocity clock -------------------

def test_agent_only_repo_is_orphaned(tmp_path: Path) -> None:
    """Only agent commits, no doc, high complexity -> orphaned; clock is None."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"svc.py": "v1"}, "feat",
            author=("dependabot[bot]", "49699333+dependabot[bot]@users.noreply.github.com"),
            committer=("dependabot[bot]", "49699333+dependabot[bot]@users.noreply.github.com"))

    authorship = {"svc.py": authorship_analysis(repo, "svc.py")}
    assert authorship["svc.py"]["authorship_class"] == "agent"

    result = analyze_understanding(repo, authorship, _no_docs(), _stats_high("svc.py"))
    assert result["orphaned_understanding"] == ["svc.py"]
    mod = result["modules"][0]
    assert mod["finding"] == "orphaned_understanding"
    # No human-authored commit exists -> clock indeterminate.
    assert mod["days_since_comprehension_event"] is None


def test_human_commit_sets_anchor_and_clock(tmp_path: Path) -> None:
    """A backdated human commit -> human_anchor, no orphan, dated velocity clock."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"svc.py": "v1"}, "feat",
            author=("Alice", "alice@example.com"),
            committer=("Alice", "alice@example.com"),
            days_ago=30)

    authorship = {"svc.py": authorship_analysis(repo, "svc.py")}
    assert authorship["svc.py"]["human_anchor"] is True

    result = analyze_understanding(repo, authorship, _no_docs(), _stats_high("svc.py"))
    assert result["orphaned_understanding"] == []
    mod = result["modules"][0]
    assert mod["finding"] is None
    # Clock reads ~30 days; allow a day of rounding/clock drift.
    assert mod["days_since_comprehension_event"] is not None
    assert 29 <= mod["days_since_comprehension_event"] <= 31


def test_mixed_repo_classified_mixed(tmp_path: Path) -> None:
    """Human author + agent co-author -> mixed, and the clock follows the human."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"svc.py": "v1"}, "feat",
            author=("Bob", "bob@example.com"),
            committer=("Bob", "bob@example.com"),
            co_authors=["Claude <noreply@anthropic.com>"],
            days_ago=10)

    authorship = {"svc.py": authorship_analysis(repo, "svc.py")}
    assert authorship["svc.py"]["authorship_class"] == "mixed"

    result = analyze_understanding(repo, authorship, _no_docs(), _stats_high("svc.py"))
    mod = result["modules"][0]
    assert mod["authorship_class"] == "mixed"
    assert mod["human_anchor"] is True
    assert mod["finding"] is None
    assert 9 <= mod["days_since_comprehension_event"] <= 11


def test_agent_commit_does_not_count_as_comprehension_event(tmp_path: Path) -> None:
    """Newest commit is an agent's; the clock dates the older human commit."""
    repo = _init_repo(tmp_path)
    _commit(repo, {"svc.py": "v1"}, "human work",
            author=("Carol", "carol@example.com"),
            committer=("Carol", "carol@example.com"),
            days_ago=40)
    _commit(repo, {"svc.py": "v2"}, "agent tweak",
            author=("github-actions[bot]", "github-actions[bot]@users.noreply.github.com"),
            committer=("github-actions[bot]", "github-actions[bot]@users.noreply.github.com"),
            days_ago=5)

    authorship = {"svc.py": authorship_analysis(repo, "svc.py")}
    result = analyze_understanding(repo, authorship, _no_docs(), _stats_high("svc.py"))
    mod = result["modules"][0]
    # The agent commit (5 days ago) is ignored; the clock reads the human one.
    assert 39 <= mod["days_since_comprehension_event"] <= 41

"""Tests for the uninstall path: run-context pointer, doc completeness, offer (Task 14)."""
from __future__ import annotations

import json
from pathlib import Path

from assess_core import build_run_context

# skills/assess/tests/ -> skills/assess is two parents up.
ASSESS_DIR = Path(__file__).resolve().parents[1]
UNINSTALL_DOC = ASSESS_DIR / "references" / "uninstall.md"
ASSESS_PR_SKILL = ASSESS_DIR.parent / "assess-pr" / "SKILL.md"
ASSESS_SKILL = ASSESS_DIR / "SKILL.md"


# ── run-context pointer ─────────────────────────────────────────────────────

def test_run_context_carries_uninstall_path(tmp_path: Path) -> None:
    repo = tmp_path / "repo"
    repo.mkdir()
    (repo / ".assess").mkdir()
    (repo / ".assess" / "complexity-stats.json").write_text(json.dumps({
        "files_scored": 1, "loc": {}, "ccn": {},
        "top_hotspots": [], "top_complex": [], "top_large": [],
    }))
    ctx = build_run_context(repo_root=repo, run_date="2026-05-22")
    assert ctx["uninstall_instructions_path"] == "references/uninstall.md"


def test_uninstall_path_resolves_to_real_doc() -> None:
    # The pointer is relative to the skill dir; it must name a file that ships.
    assert (ASSESS_DIR / "references" / "uninstall.md").is_file()


# ── doc completeness / accuracy ─────────────────────────────────────────────

def test_uninstall_doc_covers_every_artifact_class() -> None:
    text = UNINSTALL_DOC.read_text(encoding="utf-8")
    # Each artifact class /assess can leave in a target repo.
    assert "rm -rf" in text and ".assess" in text          # 1. the wiki dir
    assert "badge.json" in text                              # 2. README badge
    assert ".github/workflows/assess-gate.yml" in text       # 3. CI gate
    assert ".no-" in text                                    # 4. decline markers
    assert "assess-archetype" in text                        # 5. archetype marker
    # Findings issues are acknowledged but explicitly NOT auto-closed.
    assert "assess-finding" in text


def test_uninstall_doc_lists_instruction_files_for_archetype_marker() -> None:
    text = UNINSTALL_DOC.read_text(encoding="utf-8")
    for name in ("CLAUDE.md", "AGENTS.md", "GEMINI.md",
                 ".cursorrules", ".github/copilot-instructions.md"):
        assert name in text, f"uninstall doc omits instruction file {name}"


# ── offer appears at end of run ─────────────────────────────────────────────

def test_uninstall_offered_in_assess_pr() -> None:
    text = ASSESS_PR_SKILL.read_text(encoding="utf-8")
    assert "Step 8" in text and "Uninstall" in text
    assert "uninstall_instructions_path" in text


def test_orchestrator_references_uninstall() -> None:
    text = ASSESS_SKILL.read_text(encoding="utf-8")
    assert "uninstall" in text.lower()
    assert "uninstall_instructions_path" in text

"""Unit tests for the vault-native navigation query parser (issue #176).

Covers the three predicate kinds (folder / tag / frontmatter field) across both
hub forms (`.base` filter expressions and ```dataview``` query blocks), the
frontmatter parser, and the union selection semantics.
"""
from __future__ import annotations

from pathlib import Path

from lib.vault_queries import (
    TAGS_KEY,
    parse_base_queries,
    parse_dataview_queries,
    parse_frontmatter,
    select_notes,
)


# ---- query parsing --------------------------------------------------------

def test_base_infolder_predicate_extracts_folder() -> None:
    text = 'filters:\n  and:\n    - file.inFolder("_jira")\n    - file.ext == "md"\n'
    queries = parse_base_queries(text)
    assert len(queries) == 1
    q = queries[0]
    assert q.folders == {"_jira"}
    # `file.ext == "md"` is file metadata, never a frontmatter-field predicate.
    assert q.fields == []


def test_base_frontmatter_field_predicate() -> None:
    q = parse_base_queries('filters:\n  and:\n    - status == "open"\n')[0]
    assert ("status", "open") in q.fields
    assert q.folders == set()


def test_base_tag_predicate() -> None:
    q = parse_base_queries('filters:\n  - tags.contains("project")\n')[0]
    assert q.tags == {"project"}


def test_dataview_from_folder_and_where() -> None:
    block = (
        "```dataview\n"
        'TABLE status FROM "_jira"\n'
        'WHERE status = "open"\n'
        "```\n"
    )
    queries = parse_dataview_queries(block)
    assert len(queries) == 1
    q = queries[0]
    assert q.folders == {"_jira"}
    assert ("status", "open") in q.fields


def test_dataview_from_tag() -> None:
    q = parse_dataview_queries("```dataview\nLIST FROM #project\n```")[0]
    assert q.tags == {"project"}


def test_dataviewjs_block_is_not_parsed() -> None:
    # dataviewjs is arbitrary JS - not statically resolvable, so no edges.
    block = '```dataviewjs\ndv.pages(\'"_jira"\')\n```'
    assert parse_dataview_queries(block) == []


def test_empty_query_is_dropped() -> None:
    assert parse_dataview_queries("```dataview\nLIST\n```") == []
    assert parse_base_queries("views:\n  - type: table\n") == []


# ---- frontmatter ----------------------------------------------------------

def test_frontmatter_inline_tags_and_scalar() -> None:
    fm = parse_frontmatter('---\nstatus: open\ntags: [project, urgent]\n---\nbody')
    assert fm["status"] == "open"
    assert fm[TAGS_KEY] == {"project", "urgent"}


def test_frontmatter_block_tags() -> None:
    fm = parse_frontmatter("---\ntags:\n  - alpha\n  - beta\n---\n")
    assert fm[TAGS_KEY] == {"alpha", "beta"}


def test_no_frontmatter_returns_empty() -> None:
    assert parse_frontmatter("# Just a heading\n") == {}


# ---- selection ------------------------------------------------------------

def _doc_rels(*rels: str) -> list[tuple[Path, Path]]:
    return [(Path("/repo") / r, Path(r)) for r in rels]


def test_select_by_folder() -> None:
    q = parse_base_queries('- file.inFolder("_jira")')[0]
    docs = _doc_rels("_jira/a.md", "_jira/deep/b.md", "notes/c.md")
    selected = {p.name for p in select_notes(q, docs, lambda _d: {})}
    assert selected == {"a.md", "b.md"}


def test_select_union_never_emptied_by_unmatched_field() -> None:
    # folder selects two notes; an unsatisfiable field predicate must NOT wipe
    # them out - selection is a union, so over-linking is the failure direction.
    q = parse_base_queries(
        '- file.inFolder("_jira")\n- nonexistent == "value"'
    )[0]
    docs = _doc_rels("_jira/a.md", "_jira/b.md")
    assert len(select_notes(q, docs, lambda _d: {})) == 2


def test_select_by_tag_uses_frontmatter() -> None:
    q = parse_dataview_queries("```dataview\nLIST FROM #project\n```")[0]
    docs = _doc_rels("a.md", "b.md")
    fm = {docs[0][0]: {TAGS_KEY: {"project"}}, docs[1][0]: {TAGS_KEY: {"other"}}}
    selected = {p.name for p in select_notes(q, docs, lambda d: fm.get(d, {}))}
    assert selected == {"a.md"}

"""Tests for wiki writer module."""
from __future__ import annotations

from pathlib import Path


from lib.wiki_writer import (
    HotspotEntry,
    LogEntry,
    append_log_entry,
    slug_for_path,
    verify_log_chain,
    write_hotspot_page,
    write_index,
)


def _log_entry(**overrides: object) -> LogEntry:
    """A baseline LogEntry; overrides win."""
    base = dict(
        run_date="2026-07-07", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="Action X", plugin_version="1.55.0",
    )
    base.update(overrides)
    return LogEntry(**base)


def test_slug_for_path_basic() -> None:
    assert slug_for_path("src/foo/bar.go").startswith("src-foo-bar-go-")
    assert slug_for_path("services/api/handler.ts").startswith("services-api-handler-ts-")


def test_slug_for_path_handles_special_chars() -> None:
    assert slug_for_path("src/foo bar/baz.go").startswith("src-foo-bar-baz-go-")


def test_slug_for_path_avoids_collision() -> None:
    """Distinct paths must produce distinct slugs even when they normalize the same."""
    slug_a = slug_for_path("src/foo-bar.py")
    slug_b = slug_for_path("src/foo/bar.py")
    assert slug_a != slug_b
    # Both still start with the readable form
    assert slug_a.startswith("src-foo-bar-py-")
    assert slug_b.startswith("src-foo-bar-py-")


def test_write_index_creates_file(tmp_assess_dir: Path) -> None:
    entries = [
        HotspotEntry(
            path="src/foo.go", first_flagged="2026-01-01", last_seen="2026-05-22",
            status="active", ccn=30, loc=600,
        ),
    ]
    write_index(tmp_assess_dir, entries, last_updated="2026-05-22")
    index = tmp_assess_dir / "index.md"
    assert index.exists()
    content = index.read_text()
    assert "src/foo.go" in content
    assert "active" in content


def test_write_index_overwrites(tmp_assess_dir: Path) -> None:
    (tmp_assess_dir / "index.md").write_text("OLD")
    entries = [HotspotEntry(
        path="src/new.go", first_flagged="2026-05-22", last_seen="2026-05-22",
        status="active", ccn=20, loc=300,
    )]
    write_index(tmp_assess_dir, entries, last_updated="2026-05-22")
    content = (tmp_assess_dir / "index.md").read_text()
    assert "OLD" not in content
    assert "src/new.go" in content


def test_write_index_renders_none_metrics_as_dash(tmp_assess_dir: Path) -> None:
    """A graduated file that fell off every top-N list has unknown current
    metrics. The wiki must render those as `-`, never as `0` - zero in this
    column reads as "the file was emptied" and contradicts the report
    (issue #52 Bug 1)."""
    entries = [HotspotEntry(
        path="src/grad.go", first_flagged="2026-01-01", last_seen="2026-05-29",
        status="graduated", ccn=None, loc=None,
    )]
    write_index(tmp_assess_dir, entries, last_updated="2026-05-29")
    content = (tmp_assess_dir / "index.md").read_text()
    # `-` appears in the row's metric cells; `0` must not.
    row = [line for line in content.splitlines() if "src/grad.go" in line][0]
    assert "| - | - |" in row
    # Real zeros remain zeros (rare for tracked source, but the renderer
    # must distinguish them from unknown values).
    entries = [HotspotEntry(
        path="src/empty.go", first_flagged="2026-01-01", last_seen="2026-05-29",
        status="graduated", ccn=0, loc=0,
    )]
    write_index(tmp_assess_dir, entries, last_updated="2026-05-29")
    content = (tmp_assess_dir / "index.md").read_text()
    row = [line for line in content.splitlines() if "src/empty.go" in line][0]
    assert "| 0 | 0 |" in row


def test_write_index_legend_defines_every_status_token(tmp_assess_dir: Path) -> None:
    """The legend must define every status a hotspot row can carry: the four
    tokens assess_core's diff/status map emits (graduated, new, regressed,
    persistent) plus the `active` fallback for paths with no diff entry."""
    entries = [HotspotEntry(
        path="src/foo.go", first_flagged="2026-06-07", last_seen="2026-06-07",
        status="new", ccn=30, loc=600,
    )]
    write_index(tmp_assess_dir, entries, last_updated="2026-06-07")
    content = (tmp_assess_dir / "index.md").read_text()
    legend = content.split("## Legend", 1)[1]
    for status in ("active", "new", "graduated", "regressed", "persistent"):
        assert f"- **{status}**" in legend, f"legend missing status {status!r}"


def test_append_log_entry_creates_file_if_missing(tmp_assess_dir: Path) -> None:
    entry = LogEntry(
        run_date="2026-05-22", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=1, regressed_count=0, new_count=0, persistent_count=2,
        top_action="Add complexity rules to .golangci.yml",
    )
    append_log_entry(tmp_assess_dir, entry)
    log = tmp_assess_dir / "log.md"
    assert log.exists()
    assert "2026-05-22" in log.read_text()


def test_append_log_entry_appends(tmp_assess_dir: Path) -> None:
    (tmp_assess_dir / "log.md").write_text("# Assess Log\n\n## 2026-05-01\n\nOld entry.\n\n---\n")
    entry = LogEntry(
        run_date="2026-05-22", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="Action X",
    )
    append_log_entry(tmp_assess_dir, entry)
    content = (tmp_assess_dir / "log.md").read_text()
    assert "2026-05-01" in content  # old entry preserved
    assert "2026-05-22" in content  # new entry appended
    assert content.index("2026-05-01") < content.index("2026-05-22")


def test_log_heading_includes_plugin_version(tmp_assess_dir: Path) -> None:
    """The log heading always carries the plugin version when known. This
    makes the log a version history at a glance and naturally disambiguates
    same-day runs across versions (issue #52 Bug 2)."""
    entry = LogEntry(
        run_date="2026-05-29", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="X", plugin_version="1.13.0",
    )
    append_log_entry(tmp_assess_dir, entry)
    content = (tmp_assess_dir / "log.md").read_text()
    assert "## 2026-05-29 (v1.13.0)" in content


def test_log_heading_disambiguates_same_date_same_version(tmp_assess_dir: Path) -> None:
    """Two runs on the same date AT THE SAME version must produce distinct
    headings - otherwise GitHub anchors collide and markdownlint MD024
    fires. Second run appends a HH:MM timestamp inside the parentheses."""
    base = dict(
        run_date="2026-05-29", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="X", plugin_version="1.13.0",
    )
    append_log_entry(tmp_assess_dir, LogEntry(**base))
    append_log_entry(tmp_assess_dir, LogEntry(**base))

    content = (tmp_assess_dir / "log.md").read_text()
    headings = [line for line in content.splitlines() if line.startswith("## ")]
    assert len(headings) == 2
    # First heading has no time; second has a HH:MM stamp inside the parens.
    assert headings[0] == "## 2026-05-29 (v1.13.0)"
    assert headings[1].startswith("## 2026-05-29 (v1.13.0 ")
    assert headings[1].endswith(")")
    # No two identical headings (the bug condition).
    assert headings[0] != headings[1]


def test_log_heading_same_date_different_versions_each_unique(tmp_assess_dir: Path) -> None:
    """Same-day runs at different plugin versions distinguish themselves
    via the version in the heading - no time stamp needed."""
    base = dict(
        run_date="2026-05-29", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="X",
    )
    append_log_entry(tmp_assess_dir, LogEntry(**base, plugin_version="1.12.0"))
    append_log_entry(tmp_assess_dir, LogEntry(**base, plugin_version="1.13.0"))

    content = (tmp_assess_dir / "log.md").read_text()
    assert "## 2026-05-29 (v1.12.0)" in content
    assert "## 2026-05-29 (v1.13.0)" in content


def test_log_heading_omits_version_when_none(tmp_assess_dir: Path) -> None:
    """A caller that doesn't pass plugin_version (older code path) still
    works - the heading falls back to the bare date format."""
    entry = LogEntry(
        run_date="2026-05-29", files_scored=100, readiness_score=4.5,
        maturity_label="Solid", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="X",
    )
    append_log_entry(tmp_assess_dir, entry)
    content = (tmp_assess_dir / "log.md").read_text()
    assert "## 2026-05-29" in content
    assert "(v" not in content


def test_write_hotspot_page_creates_file(tmp_assess_dir: Path) -> None:
    write_hotspot_page(
        tmp_assess_dir,
        path="src/foo.go",
        first_flagged="2026-01-01",
        last_seen="2026-05-22",
        status="regressed",
        loc=600,
        ccn=30,
        commits=15,
        has_tests=False,
        history_rows="| 2026-01-01 | 500 | 25 | 8 | active |\n| 2026-05-22 | 600 | 30 | 15 | regressed |",
        briefing="Go API handler. Pairs with handler_test.go (which is missing).",
        actions="- Add `handler_test.go`\n- Split into smaller functions",
    )
    hotspots_dir = tmp_assess_dir / "hotspots"
    pages = list(hotspots_dir.iterdir())
    assert len(pages) == 1
    page = pages[0]
    assert page.name.startswith("src-foo-go-")
    assert page.name.endswith(".md")
    content = page.read_text(encoding="utf-8")
    assert "src/foo.go" in content
    assert "regressed" in content
    assert "handler_test.go" in content


def test_write_hotspot_page_unknown_has_tests(tmp_assess_dir: Path) -> None:
    """When has_tests is None, the page shows 'unknown' (not 'no').

    Test pairing is a deferred feature; honest reporting beats false negatives.
    """
    write_hotspot_page(
        tmp_assess_dir,
        path="src/foo.go",
        first_flagged="2026-01-01",
        last_seen="2026-05-22",
        status="active",
        loc=600,
        ccn=30,
        commits=15,
        has_tests=None,
        history_rows="| 2026-05-22 | 600 | 30 | 15 | active |",
        briefing="Go API handler.",
        actions="- Investigate complexity",
    )
    page = next((tmp_assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert "Has test file | unknown" in content


def _hotspot_kwargs(**overrides: object) -> dict:
    """Baseline write_hotspot_page kwargs; overrides win."""
    base = dict(
        path="src/foo.go",
        first_flagged="2026-01-01",
        last_seen="2026-06-17",
        status="active",
        loc=600,
        ccn=30,
        commits=15,
        has_tests=None,
        history_rows="| 2026-06-17 | 600 | 30 | 15 | active |",
        briefing="Go API handler.",
        actions="- Investigate complexity",
    )
    base.update(overrides)
    return base


def test_hotspot_page_includes_growth_profile_when_accreting(tmp_assess_dir: Path) -> None:
    """A file present in the accretion data gets one growth-profile line in the
    briefing - the monotonic-growth tendency named where an agent is briefed."""
    write_hotspot_page(tmp_assess_dir, **_hotspot_kwargs(accretion_data={
        "path": "src/foo.go", "net_additions": 420, "commit_count": 18,
        "deletion_fraction": 0.04, "time_span_months": 7.2, "reliable": True,
    }))
    page = next((tmp_assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert "Growth profile: monotonic" in content
    assert "+420 LOC" in content
    assert "0 net reductions over 18 commits in 7 months" in content
    # No new section header - the line rides inside the existing briefing.
    assert "## Growth" not in content


def test_hotspot_page_no_growth_profile_without_accretion_data(tmp_assess_dir: Path) -> None:
    """A file with no accretion entry (None) earns no line - growth that wasn't
    flagged as pure accretion is normal development, not a ratchet."""
    write_hotspot_page(tmp_assess_dir, **_hotspot_kwargs(accretion_data=None))
    page = next((tmp_assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert "Growth profile" not in content


def test_hotspot_page_growth_profile_defaults_to_none(tmp_assess_dir: Path) -> None:
    """accretion_data is optional: a caller that doesn't pass it still works and
    produces no growth line (back-compat with the pre-accretion call site)."""
    write_hotspot_page(tmp_assess_dir, **_hotspot_kwargs())
    page = next((tmp_assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert "Growth profile" not in content


def test_hotspot_page_growth_profile_disclaims_unreliable_history(tmp_assess_dir: Path) -> None:
    """reliable=False (shallow/squashed clone) still reports the profile but
    appends the incomplete-history disclaimer so the count isn't over-trusted."""
    write_hotspot_page(tmp_assess_dir, **_hotspot_kwargs(accretion_data={
        "path": "src/foo.go", "net_additions": 200, "commit_count": 5,
        "deletion_fraction": 0.02, "time_span_months": 3.0, "reliable": False,
    }))
    page = next((tmp_assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert "Growth profile: monotonic" in content
    assert "history may be incomplete" in content
    assert "shallow/squashed repo" in content


# --- run_id / schema_version provenance stamps (assess-obey-thyself) ----------


def test_write_index_stamps_run_id_comment(tmp_assess_dir: Path) -> None:
    entries = [HotspotEntry(
        path="src/foo.go", first_flagged="2026-01-01", last_seen="2026-07-07",
        status="active", ccn=30, loc=600,
    )]
    write_index(
        tmp_assess_dir, entries, last_updated="2026-07-07",
        run_id="20260707120000-abcdef01", schema_version="1.0.0",
    )
    content = (tmp_assess_dir / "index.md").read_text()
    assert "<!-- assess:run_id=20260707120000-abcdef01 artifact_schema_version=1.0.0 -->" in content


def test_write_index_no_run_id_is_byte_identical(tmp_assess_dir: Path) -> None:
    """Omitting run_id emits no comment - legacy callers get unchanged output."""
    entries = [HotspotEntry(
        path="src/foo.go", first_flagged="2026-01-01", last_seen="2026-07-07",
        status="active", ccn=30, loc=600,
    )]
    write_index(tmp_assess_dir, entries, last_updated="2026-07-07")
    content = (tmp_assess_dir / "index.md").read_text()
    assert "<!-- assess:run_id" not in content


def test_append_log_entry_stamps_run_id_per_entry(tmp_assess_dir: Path) -> None:
    entry = LogEntry(
        run_date="2026-07-07", files_scored=100, readiness_score=0.0,
        maturity_label="(LLM fills in)", instructions_grade="B+",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="x", plugin_version="1.54.0",
        run_id="20260707120000-abcdef01", schema_version="1.0.0",
    )
    append_log_entry(tmp_assess_dir, entry)
    content = (tmp_assess_dir / "log.md").read_text()
    assert "<!-- assess:run_id=20260707120000-abcdef01 artifact_schema_version=1.0.0 -->" in content


def test_write_hotspot_page_stamps_run_id(tmp_assess_dir: Path) -> None:
    write_hotspot_page(
        tmp_assess_dir, path="src/foo.go", first_flagged="2026-01-01",
        last_seen="2026-07-07", status="active", loc=600, ccn=30, commits=5,
        has_tests=True, history_rows="| 2026-07-07 | 600 | 30 | 5 | active |",
        briefing="x", actions="- y",
        run_id="20260707120000-abcdef01", schema_version="1.0.0",
    )
    page = next((tmp_assess_dir / "hotspots").iterdir())
    content = page.read_text(encoding="utf-8")
    assert content.startswith("<!-- assess:run_id=20260707120000-abcdef01 artifact_schema_version=1.0.0 -->")


# --- log.md integrity chain (assess-obey-thyself, task 11) --------------------


def test_log_entry_carries_chain_marker(tmp_assess_dir: Path) -> None:
    """Every appended entry gets a 16-hex-char chain marker."""
    append_log_entry(tmp_assess_dir, _log_entry())
    content = (tmp_assess_dir / "log.md").read_text()
    import re
    markers = re.findall(r"<!-- chain:([0-9a-f]{16}) -->", content)
    assert len(markers) == 1


def test_log_chain_verifies_valid(tmp_assess_dir: Path) -> None:
    """A log written only via append_log_entry verifies clean across many runs."""
    for i in range(3):
        append_log_entry(tmp_assess_dir, _log_entry(run_date=f"2026-07-0{i + 1}"))
    valid, broken_at = verify_log_chain(tmp_assess_dir)
    assert valid is True
    assert broken_at is None


def test_log_chain_genesis_no_file(tmp_assess_dir: Path) -> None:
    """No log yet (fresh install) is vacuously valid - nothing to contradict."""
    valid, broken_at = verify_log_chain(tmp_assess_dir)
    assert valid is True
    assert broken_at is None


def test_log_chain_first_entry_uses_genesis(tmp_assess_dir: Path) -> None:
    """The first entry chains off the literal 'genesis' - a lone entry verifies."""
    append_log_entry(tmp_assess_dir, _log_entry())
    valid, broken_at = verify_log_chain(tmp_assess_dir)
    assert valid is True
    assert broken_at is None


def test_log_chain_hash_is_deterministic(tmp_path: Path) -> None:
    """Identical content in two fresh logs yields byte-identical chain markers."""
    import re
    a = tmp_path / "a"
    b = tmp_path / "b"
    a.mkdir()
    b.mkdir()
    append_log_entry(a, _log_entry())
    append_log_entry(b, _log_entry())
    marker_a = re.search(r"<!-- chain:([0-9a-f]{16}) -->", (a / "log.md").read_text())
    marker_b = re.search(r"<!-- chain:([0-9a-f]{16}) -->", (b / "log.md").read_text())
    assert marker_a is not None and marker_b is not None
    assert marker_a.group(1) == marker_b.group(1)


def test_log_chain_detects_edited_prior_entry(tmp_assess_dir: Path) -> None:
    """Editing a prior entry breaks the chain; the next run detects the break at
    entry N and discloses it in the log."""
    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-01", top_action="First"))
    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-02", top_action="Second"))
    log_path = tmp_assess_dir / "log.md"

    # Tamper with the first entry's body after the fact.
    tampered = log_path.read_text().replace("First", "Tampered")
    log_path.write_text(tampered)

    valid, broken_at = verify_log_chain(tmp_assess_dir)
    assert valid is False
    assert broken_at == 1

    # Next run discloses the break in the log itself.
    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-03", top_action="Third"))
    content = log_path.read_text()
    assert "History integrity broken at entry 1" in content


def test_log_chain_disclosure_added_once(tmp_assess_dir: Path) -> None:
    """A persistent break is disclosed once, not re-spammed on every later run."""
    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-01", top_action="First"))
    log_path = tmp_assess_dir / "log.md"
    log_path.write_text(log_path.read_text().replace("First", "Tampered"))

    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-02"))
    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-03"))
    content = log_path.read_text()
    assert content.count("History integrity broken at entry 1") == 1


def test_log_chain_legacy_entry_without_marker_is_valid(tmp_assess_dir: Path) -> None:
    """A pre-chain log (entries with no markers) verifies as valid, and a new
    chained entry appended after it still verifies."""
    (tmp_assess_dir / "log.md").write_text(
        "# Assess Log\n\n## 2026-05-01\n\nOld entry.\n\n---\n"
    )
    valid, broken_at = verify_log_chain(tmp_assess_dir)
    assert valid is True and broken_at is None

    append_log_entry(tmp_assess_dir, _log_entry(run_date="2026-07-02"))
    valid, broken_at = verify_log_chain(tmp_assess_dir)
    assert valid is True and broken_at is None


def test_log_heading_unique_within_minute(tmp_assess_dir: Path) -> None:
    """Three runs in the same second (same date, same version) with distinct run
    ids get three distinct headings (#317): HH:MM alone collided on the third
    same-minute run. The short run id is the disambiguator."""
    base = dict(
        run_date="2026-09-14", files_scored=1, readiness_score=1.0,
        maturity_label="x", instructions_grade="B",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="none", plugin_version="9.9.9",
    )
    for rid in ("20260914101010-aaaa1111", "20260914101010-bbbb2222", "r7e8f9"):
        append_log_entry(tmp_assess_dir, LogEntry(**base, run_id=rid))
    content = (tmp_assess_dir / "log.md").read_text()
    headings = [line for line in content.splitlines() if line.startswith("## ")]
    assert len(headings) == 3
    assert len(set(headings)) == 3
    assert headings[0] == "## 2026-09-14 (v9.9.9, run aaaa1111)"
    assert headings[1] == "## 2026-09-14 (v9.9.9, run bbbb2222)"
    assert headings[2] == "## 2026-09-14 (v9.9.9, run r7e8f9)"


def test_log_heading_unique_within_minute_no_version(tmp_assess_dir: Path) -> None:
    """The run id renders without a plugin version too."""
    entry = LogEntry(
        run_date="2026-09-14", files_scored=1, readiness_score=1.0,
        maturity_label="x", instructions_grade="B",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="none", run_id="20260914101010-cccc3333",
    )
    append_log_entry(tmp_assess_dir, entry)
    content = (tmp_assess_dir / "log.md").read_text()
    assert "## 2026-09-14 (run cccc3333)" in content


def test_log_heading_unique_within_minute_short_id_collision(tmp_assess_dir: Path) -> None:
    """Distinct run ids that share the 8-hex suffix still get distinct headings:
    the clash falls back to the full run id, then a counter."""
    base = dict(
        run_date="2026-09-14", files_scored=1, readiness_score=1.0,
        maturity_label="x", instructions_grade="B",
        graduated_count=0, regressed_count=0, new_count=0, persistent_count=0,
        top_action="none", plugin_version="9.9.9",
    )
    for rid in ("20260914101010-abcd1234", "20260914101011-abcd1234",
                "20260914101011-abcd1234", "20260914101012-abcd1234"):
        append_log_entry(tmp_assess_dir, LogEntry(**base, run_id=rid))
    content = (tmp_assess_dir / "log.md").read_text()
    headings = [line for line in content.splitlines() if line.startswith("## ")]
    assert headings == [
        "## 2026-09-14 (v9.9.9, run abcd1234)",
        "## 2026-09-14 (v9.9.9, run 20260914101011-abcd1234)",
        "## 2026-09-14 (v9.9.9, run 20260914101011-abcd1234 #2)",
        "## 2026-09-14 (v9.9.9, run 20260914101012-abcd1234)",
    ]