Health

#!/usr/bin/env python3
"""Summarize the agent-instruction surface for a project.

Inventories AGENTS.md / CLAUDE.md / Codex / Copilot / Gemini instruction files,
parses Codex config.toml for project trust + plugin/feature state (with sensitive
values redacted), and flags drift between Claude and Codex surfaces.

Run as: python3 check_agent_context.py [ROOT] [summary|deep]
"""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
from pathlib import Path

SENSITIVE_RE = re.compile(r"(api[_-]?key|token|secret|password|credential)", re.IGNORECASE)
PROJECT_RE = re.compile(r'^\[projects\."(.+)"\]\s*$')
TABLE_RE = re.compile(r'^\[([A-Za-z0-9_.@"\-/]+)\]\s*$')
OPERATIONAL_RULE_RE = re.compile(
    r"(Git Safety|Public Issue Replies|Investigation Honesty|Verification|Response Style|Commit|Security)",
    re.IGNORECASE,
)


def rel(path: Path, root: Path) -> str:
    try:
        return path.resolve().relative_to(root).as_posix()
    except ValueError:
        return path.as_posix()


def read(path: Path, limit: int | None = None) -> str:
    try:
        data = path.read_text(encoding="utf-8", errors="replace")
    except OSError:
        return ""
    return data[:limit] if limit else data


def yes(path: Path) -> str:
    return "yes" if path.exists() else "no"


def print_list(title: str, items: list[str], empty: str = "(none)", limit: int | None = None) -> None:
    print(f"{title}:")
    shown = items if limit is None else items[:limit]
    if not shown:
        print(f"  {empty}")
        return
    for item in shown:
        print(f"  {item}")
    if limit is not None and len(items) > limit:
        print(f"  ... {len(items) - limit} more")


def load_json(path: Path) -> tuple[object | None, str | None]:
    if not path.is_file():
        return None, None
    try:
        return json.loads(read(path)), None
    except json.JSONDecodeError as exc:
        return None, f"{path.name}: invalid JSON at line {exc.lineno}"


def redact_sensitive_entries(value: object, prefix: str = "") -> list[str]:
    entries: list[str] = []
    if isinstance(value, dict):
        for key, child in value.items():
            child_prefix = f"{prefix}.{key}" if prefix else str(key)
            if SENSITIVE_RE.search(str(key)):
                entries.append(f"{child_prefix}=[REDACTED]")
                continue
            entries.extend(redact_sensitive_entries(child, child_prefix))
    elif isinstance(value, list):
        for index, child in enumerate(value):
            entries.extend(redact_sensitive_entries(child, f"{prefix}[{index}]"))
    return entries


def string_list(value: object) -> list[str]:
    if isinstance(value, list):
        return [str(item) if not SENSITIVE_RE.search(str(item)) else "[REDACTED]" for item in value]
    if isinstance(value, dict):
        return sorted(str(key) for key in value)
    if isinstance(value, str):
        return ["[REDACTED]" if SENSITIVE_RE.search(value) else value]
    return []


def skill_root_count(path: Path, include_root_md: bool) -> int:
    if not path.is_dir():
        return 0
    count = len(list(path.rglob("SKILL.md")))
    if include_root_md:
        count += len([p for p in path.glob("*.md") if p.name != "SKILL.md"])
    return count


def project_instruction_files(root: Path) -> list[Path]:
    files = [
        root / "AGENTS.md",
        root / "CLAUDE.md",
        root / ".github" / "copilot-instructions.md",
        root / "GEMINI.md",
    ]
    instructions_dir = root / ".github" / "instructions"
    if instructions_dir.is_dir():
        files.extend(sorted(instructions_dir.glob("*.md")))
    return [path for path in files if path.is_file()]


def claude_delegates_to_agents(path: Path) -> bool:
    text = read(path, 20_000)
    if not text:
        return False
    meaningful = [
        line.strip()
        for line in text.splitlines()
        if line.strip() and not line.strip().startswith("#")
    ]
    return any("AGENTS.md" in line for line in meaningful)


def has_operational_rules(path: Path) -> bool:
    text = read(path, 40_000)
    if not text:
        return False
    return len(set(m.group(1).lower() for m in OPERATIONAL_RULE_RE.finditer(text))) >= 2


def looks_identity_only(path: Path) -> bool:
    text = read(path, 40_000)
    if not text:
        return False
    return "nian-identity:start" in text and not has_operational_rules(path)


def parse_codex_config(
    path: Path,
) -> tuple[dict[str, str], list[str], list[str], list[str], list[str]]:
    projects: dict[str, str] = {}
    features: list[str] = []
    plugins: list[str] = []
    marketplaces: list[str] = []
    redacted: list[str] = []
    if not path.is_file():
        return projects, features, plugins, marketplaces, redacted

    section = ""
    for raw in read(path).splitlines():
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        project_match = PROJECT_RE.match(line)
        if project_match:
            section = f'projects."{project_match.group(1)}"'
            projects.setdefault(project_match.group(1), "")
            continue
        table_match = TABLE_RE.match(line)
        if table_match:
            section = table_match.group(1)
            marketplace_match = re.match(r'marketplaces\.([A-Za-z0-9_.@-]+)$', section)
            plugin_match = re.match(r'plugins\."?([^"]+)"?$', section)
            if marketplace_match:
                marketplaces.append(marketplace_match.group(1))
            if plugin_match:
                plugins.append(plugin_match.group(1))
            continue

        if SENSITIVE_RE.search(line):
            key = line.split("=", 1)[0].strip() if "=" in line else "sensitive"
            redacted.append(f"{key}=[REDACTED]")
            continue

        if "=" not in line:
            continue
        key, value = [part.strip() for part in line.split("=", 1)]
        if section == "features" and value.split("#", 1)[0].strip().strip('"').lower() == "true":
            features.append(key)
        elif section.startswith('projects."') and key == "trust_level":
            project = section[len('projects."'): -1]
            projects[project] = value.strip('"')

    return (
        projects,
        sorted(set(features)),
        sorted(set(plugins)),
        sorted(set(marketplaces)),
        sorted(set(redacted)),
    )


def project_trust(projects: dict[str, str], root: Path) -> str:
    root_text = root.as_posix()
    if root_text in projects:
        return f"exact:{projects[root_text] or 'configured'}"
    candidates = []
    for project, level in projects.items():
        try:
            project_path = Path(project).expanduser().resolve()
        except OSError:
            continue
        if project_path == root:
            return f"exact:{level or 'configured'}"
        try:
            root.relative_to(project_path)
        except ValueError:
            continue
        candidates.append(
            (len(project_path.as_posix()), level or "configured", project_path.as_posix())
        )
    if candidates:
        _, level, project = sorted(candidates, reverse=True)[0]
        return f"inherited:{level} from {project}"
    return "missing"


def summarize_pi_surface(root: Path, home: Path) -> tuple[str, list[str]]:
    global_settings = home / ".pi" / "agent" / "settings.json"
    project_settings = root / ".pi" / "settings.json"
    settings_sources = [
        ("global_settings", global_settings),
        ("project_settings", project_settings),
    ]

    configured_skills: list[str] = []
    configured_packages: list[str] = []
    redacted_entries: list[str] = []
    findings: list[str] = []
    malformed = False

    for label, path in settings_sources:
        data, error = load_json(path)
        if error:
            malformed = True
            findings.append(error)
            continue
        if not isinstance(data, dict):
            continue
        configured_skills.extend(
            f"{label}.skills: {item}" for item in string_list(data.get("skills"))
        )
        configured_packages.extend(
            f"{label}.packages: {item}" for item in string_list(data.get("packages"))
        )
        redacted_entries.extend(
            f"{label}.{item}" for item in redact_sensitive_entries(data)
        )

    package_path = root / "package.json"
    package_pi_skills: list[str] = []
    data, error = load_json(package_path)
    if error:
        findings.append(error)
    elif isinstance(data, dict):
        pi_manifest = data.get("pi")
        if isinstance(pi_manifest, dict):
            package_pi_skills = string_list(pi_manifest.get("skills"))

    pi_skill_dirs = [
        ("global_pi_skill_roots", home / ".pi" / "agent" / "skills", True),
        ("project_pi_skill_roots", root / ".pi" / "skills", True),
        ("global_agents_skill_roots", home / ".agents" / "skills", False),
        ("project_agents_skill_roots", root / ".agents" / "skills", False),
    ]
    skill_counts = [
        f"{label}: {skill_root_count(path, include_root_md)}"
        for label, path, include_root_md in pi_skill_dirs
    ]

    has_pi_surface = (
        global_settings.is_file()
        or project_settings.is_file()
        or bool(package_pi_skills)
        or any(not line.endswith(": 0") for line in skill_counts)
        or bool(configured_skills)
        or bool(configured_packages)
    )
    if not has_pi_surface:
        findings.append("no Pi settings, package manifest, or skill directories found")

    status = "WARN" if malformed else "PASS"
    lines = [
        "=== PI SURFACE ===",
        f"pi_status: {status}",
        f"global_settings_json: {yes(global_settings)}",
        f"project_settings_json: {yes(project_settings)}",
        f"package_json: {yes(package_path)}",
    ]
    lines.extend(skill_counts)
    lines.append("package_pi_skills:")
    lines.extend(f"  {item}" for item in (package_pi_skills or ["(none)"]))
    lines.append("configured_skills:")
    lines.extend(f"  {item}" for item in (configured_skills or ["(none)"]))
    lines.append("configured_packages:")
    lines.extend(f"  {item}" for item in (configured_packages or ["(none)"]))
    lines.append("redacted_pi_entries:")
    lines.extend(f"  {item}" for item in (redacted_entries or ["(none)"]))
    lines.append("pi_findings:")
    lines.extend(f"  {item}" for item in (findings or ["(none)"]))
    return status, lines


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("root", nargs="?", default=".", help="Repo root (default: cwd)")
    parser.add_argument(
        "mode", nargs="?", default="summary", choices=("summary", "deep"),
        help="Output detail level",
    )
    args = parser.parse_args()
    root = Path(args.root).resolve()
    mode = args.mode
    home = Path(os.environ.get("HOME", str(Path.home()))).expanduser()

    if not root.is_dir():
        print(f"Repo root not found: {root}", file=sys.stderr)
        return 2

    instruction_files = project_instruction_files(root)
    agents = root / "AGENTS.md"
    claude = root / "CLAUDE.md"
    claude_delegates = claude_delegates_to_agents(claude)
    github_instructions_dir = root / ".github" / "instructions"
    github_instruction_count = (
        len(list(github_instructions_dir.glob("*.md"))) if github_instructions_dir.is_dir() else 0
    )

    instruction_findings: list[str] = []
    if not instruction_files:
        instruction_findings.append("no project agent instruction files")
    if agents.is_file() and claude.is_file() and not claude_delegates:
        claude_lines = len(read(claude).splitlines())
        agents_lines = len(read(agents).splitlines())
        if claude_lines > 20 and agents_lines > 20:
            instruction_findings.append(
                "AGENTS.md and CLAUDE.md both contain substantial guidance without delegation"
            )

    global_codex_agents = home / ".codex" / "AGENTS.md"
    codex_config = home / ".codex" / "config.toml"
    projects, features, plugins, marketplaces, redacted = parse_codex_config(codex_config)
    trust = project_trust(projects, root) if codex_config.is_file() else "unavailable"
    codex_findings: list[str] = []
    if not global_codex_agents.is_file() and not codex_config.is_file():
        codex_findings.append("Codex surface not found")
    elif codex_config.is_file() and trust == "missing":
        codex_findings.append("current project is not configured in Codex trust table")

    global_claude = home / ".claude" / "CLAUDE.md"
    project_settings = root / ".claude" / "settings.local.json"
    project_rules = root / ".claude" / "rules"
    project_skills = root / ".claude" / "skills"
    global_skills = home / ".claude" / "skills"
    claude_findings: list[str] = []
    if claude.is_file() and claude_delegates:
        claude_findings.append("CLAUDE.md delegates to AGENTS.md")
    if not global_claude.is_file() and not claude.is_file():
        claude_findings.append("Claude instruction surface not found")

    if (
        global_claude.is_file()
        and has_operational_rules(global_claude)
        and global_codex_agents.is_file()
        and looks_identity_only(global_codex_agents)
    ):
        codex_findings.append(
            "global Codex AGENTS.md has identity/memory context but lacks operational rules present in global Claude CLAUDE.md"
        )
    codex_config_text = read(codex_config) if codex_config.is_file() else ""
    if (
        'sandbox_mode = "danger-full-access"' in codex_config_text
        and 'approval_policy = "never"' in codex_config_text
        and "deny" not in codex_config_text.lower()
    ):
        codex_findings.append(
            "Codex high-permission mode lacks a deny floor; add denies for secrets, credentials, pipe-to-shell installers, and outbound shells"
        )

    conflict_findings: list[str] = []
    if agents.is_file() and claude.is_file() and not claude_delegates:
        conflict_findings.append("AGENTS.md and CLAUDE.md both exist; verify they do not diverge")

    instruction_status = "FAIL" if not instruction_files else ("WARN" if instruction_findings else "PASS")
    codex_status = "WARN" if codex_findings else "PASS"
    claude_status = (
        "WARN"
        if claude_findings and "surface not found" in " ".join(claude_findings)
        else "PASS"
    )
    conflict_status = "WARN" if conflict_findings else "PASS"

    print("=== AGENT INSTRUCTION SURFACE ===")
    print(f"agent_instruction_status: {instruction_status}")
    print(f"mode: {mode}")
    print(f"AGENTS.md: {yes(agents)}")
    print(f"CLAUDE.md: {yes(claude)}")
    print(f"claude_delegates_to_agents: {'yes' if claude_delegates else 'no'}")
    print(f".github/copilot-instructions.md: {yes(root / '.github' / 'copilot-instructions.md')}")
    print(f".github/instructions/*.md: {github_instruction_count}")
    print(f"GEMINI.md: {yes(root / 'GEMINI.md')}")
    print_list("instruction_files", [rel(path, root) for path in instruction_files])
    print_list("instruction_findings", instruction_findings)

    print("=== CODEX SURFACE ===")
    print(f"codex_status: {codex_status}")
    print(f"global_agents_md: {yes(global_codex_agents)}")
    print(f"global_config_toml: {yes(codex_config)}")
    print(f"project_trust: {trust}")
    print_list("features", features, limit=20 if mode == "summary" else None)
    print_list("enabled_plugins", plugins, limit=20 if mode == "summary" else None)
    print_list("marketplaces", marketplaces, limit=20 if mode == "summary" else None)
    print_list("redacted_config_entries", redacted)
    print_list("codex_findings", codex_findings)

    print("=== CLAUDE SURFACE ===")
    print(f"claude_status: {claude_status}")
    print(f"global_claude_md: {yes(global_claude)}")
    print(f"project_claude_md: {yes(claude)}")
    print(f"settings_local_json: {yes(project_settings)}")
    rule_count = len(list(project_rules.glob('*.md'))) if project_rules.is_dir() else 0
    local_skill_count = len(list(project_skills.glob('*/SKILL.md'))) if project_skills.is_dir() else 0
    global_skill_count = len(list(global_skills.glob('*/SKILL.md'))) if global_skills.is_dir() else 0
    print(f"project_rules: {rule_count}")
    print(f"project_skills: {local_skill_count}")
    print(f"global_skills: {global_skill_count}")
    print_list("claude_findings", claude_findings)

    _, pi_lines = summarize_pi_surface(root, home)
    for line in pi_lines:
        print(line)

    print("=== INSTRUCTION CONFLICTS ===")
    print(f"conflict_status: {conflict_status}")
    print_list("conflict_findings", conflict_findings)
    return 0


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

#!/usr/bin/env python3
"""Check that doc references (@path, ~/.claude/..., docs/..., references/...) in
AGENTS.md, CLAUDE.md, .claude/rules/*.md, and .claude/skills/*/SKILL.md resolve
to real files. Prints `doc references: ok` on success, otherwise lists every
MISSING reference with source location.

Run as: python3 check_doc_refs.py [ROOT]
ROOT defaults to the current working directory.
"""

from __future__ import annotations

import argparse
import os
import re
import sys
from pathlib import Path


REF_RE = re.compile(
    r"(?<![\w/.-])("
    r"@[A-Za-z0-9_~/.-]+(?:\.md|/)|"
    r"~/\.claude/[A-Za-z0-9_/.-]+(?:\.md|/)|"
    r"(?:docs|references)/[A-Za-z0-9_/.-]+\.md"
    r")"
)


def resolve_ref(source: Path, raw: str, root: Path, home: Path) -> Path:
    ref = raw[1:] if raw.startswith("@") else raw

    if ref.startswith("~/"):
        return (home / ref[2:]).resolve()

    path = Path(ref)
    if path.is_absolute():
        return path.resolve()

    if raw.startswith("@"):
        return (root / ref).resolve()

    if ref.startswith("docs/"):
        return (root / ref).resolve()

    if ref.startswith("references/"):
        source_parts = source.relative_to(root).parts
        if len(source_parts) >= 4 and source_parts[:2] == (".claude", "skills"):
            skill_root = root.joinpath(*source_parts[:3])
            return (skill_root / ref).resolve()
        return (root / ref).resolve()

    return (source.parent / ref).resolve()


def collect_scan_files(root: Path) -> list[Path]:
    scan_files: list[Path] = []
    for candidate in (root / "AGENTS.md", root / "CLAUDE.md"):
        if candidate.is_file():
            scan_files.append(candidate)
    for pattern in (".claude/rules/*.md", ".claude/skills/*/SKILL.md"):
        scan_files.extend(sorted(root.glob(pattern)))
    return scan_files


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("root", nargs="?", default=".", help="Project root (default: cwd)")
    args = parser.parse_args()
    root = Path(args.root).resolve()
    home = Path(os.environ.get("HOME", "")).expanduser()

    scan_files = collect_scan_files(root)

    missing: list[str] = []
    seen: set[tuple[Path, int, str]] = set()
    for path in scan_files:
        in_fence = False
        for lineno, line in enumerate(
            path.read_text(encoding="utf-8", errors="replace").splitlines(), start=1
        ):
            stripped = line.lstrip()
            if stripped.startswith("```") or stripped.startswith("~~~"):
                in_fence = not in_fence
                continue
            if in_fence:
                continue

            for match in REF_RE.finditer(line):
                raw = match.group(1)
                key = (path, lineno, raw)
                if key in seen:
                    continue
                seen.add(key)

                target = resolve_ref(path, raw, root, home)
                exists = target.is_dir() if raw.endswith("/") else target.is_file()
                if not exists:
                    source = path.relative_to(root)
                    missing.append(f"MISSING: {source}:{lineno} -> {raw}")

    if missing:
        print("\n".join(missing))
        return 1

    print("doc references: ok")
    return 0


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

#!/usr/bin/env python3
"""AI maintainability audit: project shape, context surface, verification surface,
decision artifacts, drift markers, hotspot ownership, markdown links.

Run as: python3 check_maintainability.py [ROOT] [summary|deep]
"""

from __future__ import annotations

import argparse
import json
import os
import re
import subprocess
import sys
import urllib.parse
from collections import Counter
from pathlib import Path


EXCLUDED_DIRS = {
    ".git",
    ".hg",
    ".svn",
    "node_modules",
    "dist",
    "build",
    ".next",
    "__pycache__",
    ".turbo",
    "target",
    ".venv",
    "venv",
    "vendor",
    "coverage",
    ".cache",
    ".parcel-cache",
    ".pytest_cache",
    ".mypy_cache",
    ".ruff_cache",
}

SOURCE_EXTS = {
    ".c", ".cc", ".cpp", ".cs", ".css", ".go", ".h", ".hpp", ".html",
    ".java", ".js", ".jsx", ".kt", ".lua", ".m", ".mm", ".md", ".mjs",
    ".php", ".py", ".rb", ".rs", ".scss", ".sh", ".swift", ".ts", ".tsx",
    ".vue", ".yaml", ".yml",
}

MARKER_RE = re.compile(r"\b(TODO|FIXME|HACK|XXX)\b", re.IGNORECASE)
MAKE_RE = re.compile(r"^([A-Za-z0-9_.-]+)\s*:(?![=])")
MAKE_CMD_RE = re.compile(r"\bmake\s+([A-Za-z0-9_.-]+)\b")
NPM_CMD_RE = re.compile(r"\b(?:npm|pnpm|yarn|bun)\s+run\s+([A-Za-z0-9:_-]+)\b")
COMMAND_LINE_RE = re.compile(r"^(?:make|npm|pnpm|yarn|bun)\s+")
MARKDOWN_LINK_RE = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
URL_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
HOTSPOT_WORD_RE = re.compile(
    r"(hotspot|large file|ownership|owner|boundary|module|owned|owns|"
    r"负责|边界|模块|热点|大文件)",
    re.IGNORECASE,
)
VERIFICATION_WORD_RE = re.compile(
    r"(verification|verify|test|check|make\s+\w+|pytest|go test|cargo test|"
    r"npm test|npm run|pnpm|yarn|swift test|xcodebuild|验证|测试)",
    re.IGNORECASE,
)


# The file-walk helpers below are deliberately duplicated in
# skills/check/scripts/audit_signals.py. Both scripts ship standalone
# (see packaging.allowlist) and run inside an arbitrary target project, so
# they import only stdlib. Do not hoist them into a shared scripts/
# module: it is dev-only, not on the ship allowlist, and would couple a
# standalone tool to the install layout.
def rel(path: Path, root: Path) -> str:
    try:
        return path.resolve().relative_to(root).as_posix()
    except ValueError:
        return path.as_posix()


def is_excluded(path: Path, root: Path) -> bool:
    parts = path.relative_to(root).parts if path.is_absolute() else path.parts
    return any(part in EXCLUDED_DIRS for part in parts)


def read_text(path: Path, limit: int | None = None) -> str:
    try:
        data = path.read_text(encoding="utf-8", errors="replace")
    except OSError:
        return ""
    return data[:limit] if limit else data


def iter_files(root: Path) -> list[Path]:
    try:
        proc = subprocess.run(
            ["git", "-C", str(root), "ls-files", "--cached", "--others", "--exclude-standard"],
            text=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.DEVNULL,
            check=False,
        )
        if proc.returncode == 0 and proc.stdout.strip():
            files = []
            for line in proc.stdout.splitlines():
                path = root / line
                if path.is_file() and not is_excluded(path, root):
                    files.append(path)
            return files
    except OSError:
        pass

    files = []
    for dirpath, dirnames, filenames in os.walk(root):
        current = Path(dirpath)
        dirnames[:] = [name for name in dirnames if name not in EXCLUDED_DIRS]
        if is_excluded(current, root):
            continue
        for filename in filenames:
            path = current / filename
            if path.is_file() and not is_excluded(path, root):
                files.append(path)
    return files


def line_count(path: Path) -> int:
    try:
        with path.open("rb") as handle:
            return sum(1 for _ in handle)
    except OSError:
        return 0


def print_list(items: list[str], empty: str = "(none)", limit: int | None = None) -> None:
    shown = items if limit is None else items[:limit]
    if not shown:
        print(f"  {empty}")
        return
    for item in shown:
        print(f"  {item}")
    if limit is not None and len(items) > limit:
        print(f"  ... {len(items) - limit} more")


def instruction_paths(root: Path) -> list[Path]:
    candidates = [
        root / "AGENTS.md",
        root / "CLAUDE.md",
        root / ".github" / "copilot-instructions.md",
        root / "GEMINI.md",
    ]
    instructions_dir = root / ".github" / "instructions"
    if instructions_dir.is_dir():
        candidates.extend(sorted(instructions_dir.glob("*.md")))
    return [path for path in candidates if path.is_file() and not is_excluded(path, root)]


def find_text_signal(paths: list[Path], patterns: list[str]) -> bool:
    regexes = [re.compile(pattern, re.IGNORECASE) for pattern in patterns]
    for path in paths:
        text = read_text(path, 200_000)
        if any(regex.search(text) for regex in regexes):
            return True
    return False


def parse_makefile(root: Path) -> tuple[set[str], list[str]]:
    makefile = root / "Makefile"
    targets: set[str] = set()
    commands: list[str] = []
    if not makefile.is_file():
        return targets, commands
    for line in read_text(makefile).splitlines():
        match = MAKE_RE.match(line)
        if not match:
            continue
        target = match.group(1)
        if target.startswith("."):
            continue
        targets.add(target)
        if re.search(r"(test|check|lint|type|build|package|verify|smoke)", target, re.IGNORECASE):
            commands.append(f"make {target}")
    return targets, commands


def parse_package_json(root: Path) -> tuple[set[str], list[str]]:
    package = root / "package.json"
    script_names: set[str] = set()
    commands: list[str] = []
    if not package.is_file():
        return script_names, commands
    try:
        data = json.loads(read_text(package))
    except json.JSONDecodeError:
        return script_names, commands
    scripts = data.get("scripts", {})
    if not isinstance(scripts, dict):
        return script_names, commands
    for name in sorted(scripts):
        script_names.add(name)
        if re.search(r"(test|check|lint|type|build|verify)", name, re.IGNORECASE):
            commands.append(f"npm run {name}")
    return script_names, commands


def parse_ci_commands(root: Path) -> list[str]:
    workflows_dir = root / ".github" / "workflows"
    workflows = sorted(workflows_dir.glob("*.yml")) if workflows_dir.is_dir() else []
    workflows += sorted(workflows_dir.glob("*.yaml")) if workflows_dir.is_dir() else []
    commands: list[str] = []
    for workflow in workflows:
        for raw in read_text(workflow).splitlines():
            line = raw.strip()
            if line.startswith("- run:"):
                command = line.split("- run:", 1)[1].strip().strip("'\"")
            elif line.startswith("run:"):
                command = line.split("run:", 1)[1].strip().strip("'\"")
            else:
                continue
            if command and command != "|":
                commands.append(f"{rel(workflow, root)}: {command}")
    return commands


def scan_markdown_links(files: list[Path], root: Path) -> list[str]:
    missing: list[str] = []
    markdown_files = [path for path in files if path.suffix.lower() == ".md"]
    for path in markdown_files:
        for lineno, line in enumerate(read_text(path).splitlines(), 1):
            for raw in MARKDOWN_LINK_RE.findall(line):
                target = raw.strip().split()[0].strip("<>")
                if not target or target.startswith("#") or URL_RE.match(target):
                    continue
                target = urllib.parse.unquote(target.split("#", 1)[0])
                if not target:
                    continue
                full = (path.parent / target).resolve()
                if not full.exists():
                    missing.append(f"{rel(path, root)}:{lineno} -> {target}")
    return missing


def verification_surface(
    root: Path, instruction_files: list[Path]
) -> tuple[list[str], list[str], set[str], set[str]]:
    make_targets, make_commands = parse_makefile(root)
    package_scripts, package_commands = parse_package_json(root)
    commands = make_commands + package_commands + parse_ci_commands(root)

    if (root / "Cargo.toml").is_file():
        commands.extend(["cargo test", "cargo check"])
    if (root / "go.mod").is_file():
        commands.append("go test ./...")
    if (root / "pyproject.toml").is_file() or (root / "pytest.ini").is_file():
        commands.append("pytest")
    if (root / "pom.xml").is_file():
        commands.append("mvn test")
    if (root / "deno.json").is_file() or (root / "deno.jsonc").is_file():
        commands.append("deno test")

    missing: list[str] = []
    for path in instruction_files:
        text = read_text(path, 200_000)
        snippets: list[str] = []
        for raw_line in text.splitlines():
            snippets.extend(re.findall(r"`([^`]+)`", raw_line))
            stripped = raw_line.strip().strip("`")
            if COMMAND_LINE_RE.match(stripped):
                snippets.append(stripped)
        for snippet in snippets:
            for target in MAKE_CMD_RE.findall(snippet):
                if target not in make_targets:
                    missing.append(f"{rel(path, root)} references missing make target: {target}")
            for script in NPM_CMD_RE.findall(snippet):
                if script not in package_scripts:
                    missing.append(f"{rel(path, root)} references missing package script: {script}")

    unique_commands = list(dict.fromkeys(commands))
    unique_missing = list(dict.fromkeys(missing))
    return unique_commands, unique_missing, make_targets, package_scripts


def hotspot_ownership_surface(
    records: list[tuple[int, int, Path]],
    instruction_files: list[Path],
    mode: str,
    root: Path,
) -> tuple[str, list[str], list[str], list[str]]:
    if mode != "deep":
        return "SKIPPED", [], [], []
    if not records:
        return "PASS", [], [], []

    snippets: list[str] = []
    for path in instruction_files:
        snippets.append(f"\n# {rel(path, root)}\n{read_text(path, 200_000)}")
    instruction_text = "\n".join(snippets)
    lower_text = instruction_text.lower()
    instruction_lines = instruction_text.splitlines()

    documented: list[str] = []
    missing: list[str] = []
    for lines, _size, path in records:
        relative = rel(path, root)
        relative_lower = relative.lower()
        indices: list[int] = []
        start = 0
        while True:
            index = lower_text.find(relative_lower, start)
            if index < 0:
                break
            indices.append(index)
            start = index + len(relative_lower)

        if not indices:
            missing.append(f"{relative} lines={lines} reason=not mentioned in agent instructions")
            continue

        saw_hotspot_context = False
        saw_verification_context = False
        has_documented_entry = False
        for index in indices:
            window = lower_text[max(0, index - 700): index + len(relative_lower) + 700]
            line_no = lower_text[:index].count("\n")
            local_lines = instruction_lines[max(0, line_no - 1): line_no + 4]
            local_context = "\n".join(local_lines)
            has_hotspot_context = bool(HOTSPOT_WORD_RE.search(window))
            has_verification_context = bool(VERIFICATION_WORD_RE.search(local_context))
            saw_hotspot_context = saw_hotspot_context or has_hotspot_context
            saw_verification_context = saw_verification_context or has_verification_context
            if has_hotspot_context and has_verification_context:
                has_documented_entry = True
                break

        if has_documented_entry:
            documented.append(f"{relative} lines={lines}")
        else:
            reasons = []
            if not saw_hotspot_context:
                reasons.append("missing ownership/boundary context")
            if not saw_verification_context:
                reasons.append("missing verification context")
            if saw_hotspot_context and saw_verification_context:
                reasons.append("ownership and verification are not in the same hotspot entry")
            missing.append(f"{relative} lines={lines} reason={'; '.join(reasons)}")

    findings: list[str] = []
    if missing:
        findings.append("large source files lack hotspot ownership or verification map")
    return ("WARN" if missing else "PASS"), documented, missing, findings


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("root", nargs="?", default=".", help="Repo root (default: cwd)")
    parser.add_argument(
        "mode", nargs="?", default="summary", choices=("summary", "deep"),
        help="Output detail level",
    )
    args = parser.parse_args()
    root = Path(args.root).resolve()
    mode = args.mode

    if not root.is_dir():
        print(f"Repo root not found: {root}", file=sys.stderr)
        return 2

    files = iter_files(root)
    tracked_count = len(files)
    extensions = Counter(path.suffix.lower() or "(none)" for path in files)
    detected_manifests = [
        name
        for name in [
            "Makefile", "package.json", "Cargo.toml", "go.mod", "pyproject.toml",
            "pytest.ini", "pom.xml", "deno.json", "deno.jsonc",
        ]
        if (root / name).is_file()
    ]
    workflows_dir = root / ".github" / "workflows"
    workflow_count = 0
    if workflows_dir.is_dir():
        workflow_count = len(list(workflows_dir.glob("*.yml"))) + len(list(workflows_dir.glob("*.yaml")))
    if workflow_count:
        detected_manifests.append(f".github/workflows ({workflow_count})")

    source_files = [path for path in files if path.suffix.lower() in SOURCE_EXTS]
    source_stats: list[tuple[int, int, Path]] = []
    for path in source_files:
        try:
            size = path.stat().st_size
        except OSError:
            size = 0
        source_stats.append((line_count(path), size, path))
    source_stats.sort(key=lambda item: (item[0], item[1]), reverse=True)

    dir_counts: Counter[str] = Counter()
    for path in files:
        relative_parts = Path(rel(path, root)).parts
        top = relative_parts[0] if len(relative_parts) > 1 else "."
        dir_counts[top] += 1

    instruction_files = instruction_paths(root)
    project_map = find_text_signal(
        instruction_files,
        [r"repository map", r"project map", r"repo map", r"\bproject\b", r"目录", r"仓库", r"结构"],
    )
    instruction_verification = find_text_signal(
        instruction_files,
        [r"verification", r"test plan", r"make test", r"npm test", r"pytest", r"cargo test", r"验证", r"测试"],
    )
    boundaries = find_text_signal(
        instruction_files,
        [r"not for", r"do not", r"non-?goals?", r"scope", r"boundar", r"never", r"avoid", r"边界", r"非目标", r"不要"],
    )
    commands, missing_references, make_targets, _package_scripts = verification_surface(root, instruction_files)
    stable_make_targets = sorted(make_targets & {"check", "test", "verify"})
    wrapper_warnings: list[str] = []
    if len(commands) >= 2 and (root / "Makefile").is_file() and not stable_make_targets:
        wrapper_warnings.append(
            "multiple verification commands discovered but Makefile lacks check/test/verify wrapper"
        )

    decision_artifacts = {
        "docs_dir": (root / "docs").is_dir(),
        "specs_dir": (root / "specs").is_dir(),
        "specify_dir": (root / ".specify").is_dir(),
        "handoff_md": any(path.name.upper() == "HANDOFF.MD" for path in root.glob("*.md")),
        "changelog": any(path.name.upper().startswith("CHANGELOG") for path in root.glob("*")),
        "issue_templates": (root / ".github" / "ISSUE_TEMPLATE").exists(),
        "pr_template": any(
            path.is_file()
            for path in [
                root / ".github" / "pull_request_template.md",
                root / ".github" / "PULL_REQUEST_TEMPLATE.md",
            ]
        ),
    }

    todo_counts: Counter[str] = Counter()
    todo_total = 0
    for path in source_files:
        text = read_text(path, 200_000)
        # Count marker-bearing lines, not marker words. Documentation often names
        # the full marker family in one rule line; treating that as four issues
        # makes the checker flag itself instead of real TODO piles.
        count = sum(1 for line in text.splitlines() if MARKER_RE.search(line))
        if count:
            todo_counts[rel(path, root)] += count
            todo_total += count

    large_line_limit = 1200 if mode == "summary" else 800
    large_file_records = [
        (lines, size, path) for lines, size, path in source_stats if lines >= large_line_limit
    ]
    large_files = [f"{rel(path, root)} lines={lines} bytes={size}" for lines, size, path in large_file_records]
    todo_hotspots = [
        f"{path} markers={count}" for path, count in todo_counts.most_common(8 if mode == "deep" else 5)
    ]

    doc_ref_status = "unavailable"
    doc_ref_detail = ""
    checker = os.environ.get("DOC_REF_CHECKER")
    if checker and Path(checker).is_file():
        proc = subprocess.run(
            ["bash", checker, str(root)],
            text=True,
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            check=False,
        )
        doc_ref_status = "pass" if proc.returncode == 0 else "fail"
        if proc.stdout.strip():
            first_lines = proc.stdout.strip().splitlines()[:8]
            doc_ref_detail = " | ".join(first_lines)

    has_instruction_surface = bool(instruction_files)
    has_command_surface = bool(commands)
    context_warnings: list[str] = []
    verification_warnings: list[str] = []
    drift_warnings: list[str] = []

    if not has_instruction_surface:
        context_warnings.append("no agent instruction surface")
    if has_instruction_surface and not project_map:
        context_warnings.append("instructions lack project map")
    if has_instruction_surface and not instruction_verification:
        context_warnings.append("instructions lack verification guidance")
    if has_instruction_surface and not boundaries:
        context_warnings.append("instructions lack scope/boundary language")
    if not has_command_surface:
        verification_warnings.append("no executable verification command discovered")
    if missing_references:
        verification_warnings.append("instruction references missing commands")
    if todo_total >= (50 if mode == "summary" else 25):
        drift_warnings.append("TODO/FIXME/HACK/XXX markers are concentrated")
    hotspot_status, documented_hotspots, missing_hotspot_ownership, hotspot_findings = (
        hotspot_ownership_surface(large_file_records, instruction_files, mode, root)
    )
    if large_files and mode != "deep":
        drift_warnings.append("large source files need ownership or module boundaries")
    if hotspot_status == "WARN":
        drift_warnings.extend(hotspot_findings)
    if doc_ref_status == "fail":
        drift_warnings.append("broken documentation references")

    markdown_missing: list[str] = []
    markdown_link_status = "SKIPPED"
    if mode == "deep":
        markdown_missing = scan_markdown_links(files, root)
        markdown_link_status = "WARN" if markdown_missing else "PASS"
        if markdown_missing:
            drift_warnings.append("broken Markdown links")

    context_status = "FAIL" if not has_instruction_surface else ("WARN" if context_warnings else "PASS")
    verification_status = "FAIL" if not has_command_surface else ("WARN" if verification_warnings else "PASS")
    decision_status = "PASS"
    wrapper_status = "WARN" if wrapper_warnings else "PASS"
    drift_status = "WARN" if drift_warnings else "PASS"

    if context_status == "FAIL" or verification_status == "FAIL" or doc_ref_status == "fail":
        overall = "FAIL"
    elif "WARN" in {
        context_status, verification_status, decision_status, wrapper_status,
        drift_status, markdown_link_status, hotspot_status,
    }:
        overall = "WARN"
    else:
        overall = "PASS"

    top_ext = [f"{ext} files={count}" for ext, count in extensions.most_common(10)]
    largest_sources = [
        f"{rel(path, root)} lines={lines} bytes={size}"
        for lines, size, path in source_stats[: (10 if mode == "deep" else 5)]
    ]
    largest_dirs = [f"{directory} files={count}" for directory, count in dir_counts.most_common(8)]

    print("=== PROJECT SHAPE ===")
    print(f"maintainability_status: {overall}")
    print(f"mode: {mode}")
    print(f"tracked_files: {tracked_count}")
    print("top_extensions:")
    print_list(top_ext)
    print("largest_source_files:")
    print_list(largest_sources)
    print("largest_directories:")
    print_list(largest_dirs)

    print("=== AI CONTEXT SURFACE ===")
    print(f"context_status: {context_status}")
    print(f"AGENTS.md: {'yes' if (root / 'AGENTS.md').is_file() else 'no'}")
    print(f"CLAUDE.md: {'yes' if (root / 'CLAUDE.md').is_file() else 'no'}")
    print(f".github/copilot-instructions.md: {'yes' if (root / '.github' / 'copilot-instructions.md').is_file() else 'no'}")
    github_instruction_count = (
        len(list((root / ".github" / "instructions").glob("*.md")))
        if (root / ".github" / "instructions").is_dir() else 0
    )
    print(f".github/instructions/*.md: {github_instruction_count}")
    print(f"GEMINI.md: {'yes' if (root / 'GEMINI.md').is_file() else 'no'}")
    print(f"project_map: {'yes' if project_map else 'no'}")
    print(f"verification_guidance: {'yes' if instruction_verification else 'no'}")
    print(f"boundary_guidance: {'yes' if boundaries else 'no'}")
    print("context_findings:")
    print_list(context_warnings)
    print("instruction_files:")
    print_list([rel(path, root) for path in instruction_files])

    print("=== VERIFICATION SURFACE ===")
    print(f"verification_status: {verification_status}")
    print("detected_manifests:")
    print_list(detected_manifests)
    print("commands:")
    print_list(commands, limit=12 if mode == "summary" else None)
    print("missing_referenced_commands:")
    print_list(missing_references, limit=10 if mode == "summary" else None)
    print("verification_findings:")
    print_list(verification_warnings)

    print("=== VERIFICATION WRAPPER SURFACE ===")
    print(f"wrapper_status: {wrapper_status}")
    print(f"makefile_present: {'yes' if (root / 'Makefile').is_file() else 'no'}")
    print("stable_make_targets:")
    print_list([f"make {target}" for target in stable_make_targets])
    print("wrapper_findings:")
    print_list(wrapper_warnings)

    print("=== DECISION ARTIFACTS ===")
    print(f"decision_artifacts_status: {decision_status}")
    for key, value in decision_artifacts.items():
        print(f"{key}: {'yes' if value else 'no'}")

    print("=== DRIFT MARKERS ===")
    print(f"drift_status: {drift_status}")
    print(f"todo_markers: {todo_total}")
    print("todo_hotspots:")
    print_list(todo_hotspots)
    print("large_source_files:")
    print_list(large_files[: (10 if mode == "deep" else 5)])
    print(f"broken_doc_references: {doc_ref_status}")
    if doc_ref_detail and (mode == "deep" or doc_ref_status == "fail"):
        print(f"broken_doc_reference_detail: {doc_ref_detail}")
    print("drift_findings:")
    print_list(drift_warnings)

    print("=== HOTSPOT OWNERSHIP SURFACE ===")
    print(f"hotspot_ownership_status: {hotspot_status}")
    print(f"large_hotspot_threshold_lines: {large_line_limit if mode == 'deep' else '(deep mode only)'}")
    print("documented_hotspots:")
    if mode == "deep":
        print_list(documented_hotspots)
    else:
        print("  (skipped: deep mode only)")
    print("missing_hotspot_ownership:")
    if mode == "deep":
        print_list(missing_hotspot_ownership)
    else:
        print("  (skipped: deep mode only)")
    print("hotspot_ownership_findings:")
    if mode == "deep":
        print_list(hotspot_findings)
    else:
        print("  (skipped: deep mode only)")

    print("=== MARKDOWN LINK SURFACE ===")
    print(f"markdown_link_status: {markdown_link_status}")
    print("missing_markdown_links:")
    if mode == "deep":
        print_list(markdown_missing, limit=20)
    else:
        print("  (skipped: deep mode only)")
    return 0


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

#!/usr/bin/env python3
"""Scan a verifier log for stale external paths and suggest cache-clean commands.

Detects /tmp/ and /private/tmp/ file references that no longer exist; these are
the signature of stale worktrees pointed at by a verifier (golangci-lint cache,
go build cache, npm cache, etc.).

Run as: python3 check_verifier_output.py ROOT LOG_FILE
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path


TOKEN_RE = re.compile(
    r"(?P<path>(?:/|\.\./)(?:[^\s:'\"(),]+/)*[^\s:'\"(),]+\.[A-Za-z0-9_+-]+)"
)
TMP_RE = re.compile(r"(^|/)(private/)?tmp/")


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("root", help="Repo root")
    parser.add_argument("log_file", help="Verifier log to scan")
    args = parser.parse_args()

    root = Path(args.root).resolve()
    log_file = Path(args.log_file).resolve()
    if not root.is_dir():
        print(f"Repo root not found: {root}", file=sys.stderr)
        return 2
    if not log_file.is_file():
        print(f"Log file not found: {log_file}", file=sys.stderr)
        return 2

    text = log_file.read_text(encoding="utf-8", errors="replace")

    def normalize(token: str) -> Path:
        if token.startswith("/"):
            return Path(token)
        return (root / token).resolve()

    paths: list[Path] = []
    for match in TOKEN_RE.finditer(text):
        token = match.group("path").rstrip(".")
        if "/.git/" in token:
            continue
        path = normalize(token)
        if TMP_RE.search(path.as_posix()):
            paths.append(path)

    unique_paths = []
    seen = set()
    for path in paths:
        value = path.as_posix()
        if value in seen:
            continue
        seen.add(value)
        unique_paths.append(path)

    stale_paths = [path for path in unique_paths if not path.exists()]
    existing_paths = [path for path in unique_paths if path.exists()]
    lower = text.lower()

    actions: list[str] = []
    if stale_paths:
        if "golangci-lint" in lower or "errcheck" in lower:
            actions.append("golangci-lint cache clean")
        if re.search(r"\bgo (test|vet|build)\b", lower) or "go-build" in lower:
            actions.append("go clean -cache -testcache")
        if "npm" in lower or "node_modules" in lower:
            actions.append("npm cache verify")
        if not actions:
            actions.append("rerun the verifier after removing stale temporary worktrees")

    status = "WARN" if stale_paths else "PASS"

    print("=== VERIFIER OUTPUT SURFACE ===")
    print(f"verifier_output_status: {status}")
    print(f"log_file: {log_file}")
    print("stale_paths:")
    if stale_paths:
        for path in stale_paths[:20]:
            print(f"  {path}")
        if len(stale_paths) > 20:
            print(f"  ... {len(stale_paths) - 20} more")
    else:
        print("  (none)")
    print("existing_tmp_paths:")
    if existing_paths:
        for path in existing_paths[:10]:
            print(f"  {path}")
        if len(existing_paths) > 10:
            print(f"  ... {len(existing_paths) - 10} more")
    else:
        print("  (none)")
    print("recommended_actions:")
    if actions:
        for action in dict.fromkeys(actions):
            print(f"  {action}")
    else:
        print("  (none)")
    print("verifier_findings:")
    if stale_paths:
        print("  stale external verifier paths detected")
    else:
        print("  (none)")
    return 0


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

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
exec python3 "$SCRIPT_DIR/check_agent_context.py" "$@"

#!/usr/bin/env bash
set -euo pipefail

ROOT="${1:-$PWD}"
ROOT="$(cd "$ROOT" && pwd)"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

exec python3 "$SCRIPT_DIR/check_doc_refs.py" "$ROOT"