Doc Freshness

#!/usr/bin/env python3
"""
CLAUDE.md Drift Checker

Parses CLAUDE.md structural claims (plugin counts, component inventories,
versions, file paths) and compares them against filesystem ground truth.

Uses only standard library (no external dependencies). Python 3.8+.

Usage:
    python3 claude_md_checker.py <project_root>

Output:
    JSON with findings grouped by category and summary.
"""

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Dict, List, Optional

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import extract_frontmatter, read_file_safe, read_json_safe


# ---------------------------------------------------------------------------
# Plugin name normalization
# ---------------------------------------------------------------------------

# Edge cases where lower().replace(" ", "-") doesn't match directory name
_NAME_OVERRIDES: Dict[str, str] = {
    "google stitch": "google-stitch",
    "design intent": "design-intent",
    "spring boot": "spring-boot",
}


def _normalize_plugin_name(heading: str) -> str:
    """Convert heading text to plugin directory name.

    'Core' -> 'core', 'Design Intent' -> 'design-intent'.
    """
    lower = heading.strip().lower()
    return _NAME_OVERRIDES.get(lower, lower.replace(" ", "-"))


# ---------------------------------------------------------------------------
# Ground truth collection
# ---------------------------------------------------------------------------

def _scan_marketplace(project_root: Path) -> List[str]:
    """Get plugin names from marketplace.json."""
    mp = read_json_safe(project_root / ".claude-plugin" / "marketplace.json")
    if not mp or "plugins" not in mp:
        return []
    return [p.get("name", "") for p in mp["plugins"] if p.get("name")]


def _scan_plugin_versions(project_root: Path) -> Dict[str, str]:
    """Get actual versions from each plugin's plugin.json."""
    versions: Dict[str, str] = {}
    plugins_dir = project_root / "plugins"
    if not plugins_dir.is_dir():
        return versions

    for entry in sorted(plugins_dir.iterdir()):
        pj = entry / ".claude-plugin" / "plugin.json"
        data = read_json_safe(pj)
        if data and "version" in data:
            versions[entry.name] = data["version"]
    return versions


def _scan_plugin_agents(project_root: Path) -> Dict[str, List[str]]:
    """Get agent names from each plugin's agents/ directory."""
    result: Dict[str, List[str]] = {}
    plugins_dir = project_root / "plugins"
    if not plugins_dir.is_dir():
        return result

    for entry in sorted(plugins_dir.iterdir()):
        agents_dir = entry / "agents"
        if not agents_dir.is_dir():
            continue
        names = []
        for md in sorted(agents_dir.glob("*.md")):
            content = read_file_safe(md)
            if content:
                fm = extract_frontmatter(content)
                name = fm.get("name") if fm else None
                names.append(name or md.stem)
            else:
                names.append(md.stem)
        if names:
            result[entry.name] = names
    return result


def _scan_plugin_commands(project_root: Path) -> Dict[str, List[str]]:
    """Get command names from each plugin's commands/ directory."""
    result: Dict[str, List[str]] = {}
    plugins_dir = project_root / "plugins"
    if not plugins_dir.is_dir():
        return result

    for entry in sorted(plugins_dir.iterdir()):
        cmds_dir = entry / "commands"
        if not cmds_dir.is_dir():
            continue
        names = [md.stem for md in sorted(cmds_dir.glob("*.md"))]
        if names:
            result[entry.name] = names
    return result


def _scan_plugin_skills(project_root: Path) -> Dict[str, List[str]]:
    """Get skill names from each plugin's skills/ directory."""
    result: Dict[str, List[str]] = {}
    plugins_dir = project_root / "plugins"
    if not plugins_dir.is_dir():
        return result

    for entry in sorted(plugins_dir.iterdir()):
        skills_dir = entry / "skills"
        if not skills_dir.is_dir():
            continue
        names = []
        for skill_subdir in sorted(skills_dir.iterdir()):
            if not skill_subdir.is_dir():
                continue
            skill_md = skill_subdir / "SKILL.md"
            content = read_file_safe(skill_md)
            if content:
                fm = extract_frontmatter(content)
                name = fm.get("name") if fm else None
                names.append(name or skill_subdir.name)
            else:
                names.append(skill_subdir.name)
        if names:
            result[entry.name] = names
    return result


def _collect_ground_truth(project_root: Path) -> dict:
    """Collect all filesystem ground truth."""
    return {
        "marketplace_plugins": _scan_marketplace(project_root),
        "versions": _scan_plugin_versions(project_root),
        "agents": _scan_plugin_agents(project_root),
        "commands": _scan_plugin_commands(project_root),
        "skills": _scan_plugin_skills(project_root),
    }


# ---------------------------------------------------------------------------
# CLAUDE.md claim parsing
# ---------------------------------------------------------------------------

_PLUGIN_HEADING_RE = re.compile(r"^###\s+(.+?)\s+Plugin\s*$", re.MULTILINE)
_AGENTS_LINE_RE = re.compile(
    r"^\s*-\s+\*\*Agents\*\*:\s*(.+)$", re.MULTILINE
)
_COMMANDS_LINE_RE = re.compile(
    r"^\s*-\s+\*\*Commands\*\*:\s*(.+)$", re.MULTILINE
)
_SKILLS_LINE_RE = re.compile(
    r"^\s*-\s+\*\*Skills\*\*:\s*(.+)$", re.MULTILINE
)
_BACKTICK_NAME_RE = re.compile(r"`([^`]+)`")
_SLASH_CMD_RE = re.compile(r"`/([a-z][-a-z0-9]*)`")
_VERSION_LINE_RE = re.compile(
    r"Plugin versions?:\s*(.+)", re.IGNORECASE
)
_VERSION_ENTRY_RE = re.compile(r"([a-z][-a-z0-9]*)\s+(\d+\.\d+\.\d+)")


def _extract_names_from_line(line: str) -> List[str]:
    """Extract backtick-quoted names from a component line.

    Filters out flags (--deep), paths (docs/foo.md), and parenthetical hints.
    """
    names = _BACKTICK_NAME_RE.findall(line)
    return [
        n for n in names
        if not n.startswith("-") and "/" not in n and "." not in n
    ]


def _extract_commands_from_line(line: str) -> List[str]:
    """Extract /command names from a component line."""
    return _SLASH_CMD_RE.findall(line)


def _parse_plugin_sections(content: str) -> Dict[str, dict]:
    """Parse all ### {Name} Plugin sections from CLAUDE.md.

    Only parses sections within the '## Available Plugins' area to avoid
    matching headings like '### Creating a New Plugin' in other sections.

    Returns dict mapping normalized plugin name to claimed components.
    """
    # Restrict to "Available Plugins" section
    avail_start = content.find("## Available Plugins")
    if avail_start == -1:
        return {}
    # Find the next ## heading after Available Plugins
    next_section = re.search(r"^## (?!Available Plugins)", content[avail_start + 1:], re.MULTILINE)
    avail_end = (avail_start + 1 + next_section.start()) if next_section else len(content)
    avail_content = content[avail_start:avail_end]

    sections: Dict[str, dict] = {}
    headings = list(_PLUGIN_HEADING_RE.finditer(avail_content))

    for i, match in enumerate(headings):
        heading_text = match.group(1)
        plugin_name = _normalize_plugin_name(heading_text)

        # Extract section text up to next heading or end
        start = match.end()
        end = headings[i + 1].start() if i + 1 < len(headings) else len(avail_content)
        section_text = avail_content[start:end]

        section: dict = {"heading": heading_text, "agents": [], "commands": [], "skills": []}

        # Parse agents
        agents_match = _AGENTS_LINE_RE.search(section_text)
        if agents_match:
            section["agents"] = _extract_names_from_line(agents_match.group(1))

        # Parse commands
        cmds_match = _COMMANDS_LINE_RE.search(section_text)
        if cmds_match:
            section["commands"] = _extract_commands_from_line(cmds_match.group(1))

        # Parse skills
        skills_match = _SKILLS_LINE_RE.search(section_text)
        if skills_match:
            section["skills"] = _extract_names_from_line(skills_match.group(1))

        sections[plugin_name] = section

    return sections


def _parse_version_line(content: str) -> Dict[str, str]:
    """Parse the 'Plugin versions: core 2.1.0, ...' line."""
    match = _VERSION_LINE_RE.search(content)
    if not match:
        return {}
    return dict(_VERSION_ENTRY_RE.findall(match.group(1)))


# ---------------------------------------------------------------------------
# Drift checks
# ---------------------------------------------------------------------------

def _finding(
    category: str,
    status: str,
    severity: str,
    detail: str,
    plugin: str = "",
    claimed: str = "",
    actual: str = "",
) -> dict:
    """Create a finding dict."""
    f = {
        "category": category,
        "status": status,
        "severity": severity,
        "detail": detail,
    }
    if plugin:
        f["plugin"] = plugin
    if claimed:
        f["claimed"] = claimed
    if actual:
        f["actual"] = actual
    return f


def _check_plugin_count(
    sections: Dict[str, dict], ground_truth: dict
) -> List[dict]:
    """Check if documented plugin count matches marketplace."""
    findings = []
    claimed_count = len(sections)
    actual_count = len(ground_truth["marketplace_plugins"])

    if claimed_count != actual_count:
        findings.append(_finding(
            category="plugin_count",
            status="drift",
            severity="WARNING",
            detail=f"CLAUDE.md documents {claimed_count} plugins, marketplace has {actual_count}",
            claimed=str(claimed_count),
            actual=str(actual_count),
        ))
    else:
        findings.append(_finding(
            category="plugin_count",
            status="ok",
            severity="INFO",
            detail=f"Plugin count matches: {actual_count}",
            claimed=str(claimed_count),
            actual=str(actual_count),
        ))
    return findings


def _check_component_inventories(
    sections: Dict[str, dict], ground_truth: dict
) -> List[dict]:
    """Check agents, commands, skills per plugin."""
    findings = []

    for component_type in ("agents", "commands", "skills"):
        actual_all = ground_truth[component_type]

        for plugin_name, section in sections.items():
            claimed_names = set(section.get(component_type, []))
            actual_names = set(actual_all.get(plugin_name, []))

            # Names in CLAUDE.md but not on disk
            for name in sorted(claimed_names - actual_names):
                findings.append(_finding(
                    category=component_type,
                    status="phantom",
                    severity="CRITICAL",
                    detail=f"{component_type[:-1]} '{name}' documented but not found on disk",
                    plugin=plugin_name,
                    claimed=name,
                ))

            # Names on disk but not in CLAUDE.md
            for name in sorted(actual_names - claimed_names):
                findings.append(_finding(
                    category=component_type,
                    status="undocumented",
                    severity="CRITICAL",
                    detail=f"{component_type[:-1]} '{name}' exists on disk but not in CLAUDE.md",
                    plugin=plugin_name,
                    actual=name,
                ))

            # Matching names
            for name in sorted(claimed_names & actual_names):
                findings.append(_finding(
                    category=component_type,
                    status="ok",
                    severity="INFO",
                    detail=f"{component_type[:-1]} '{name}' matches",
                    plugin=plugin_name,
                ))

    return findings


def _check_plugin_versions(
    content: str, ground_truth: dict
) -> List[dict]:
    """Check plugin version claims against plugin.json files."""
    findings = []
    claimed_versions = _parse_version_line(content)
    actual_versions = ground_truth["versions"]

    all_plugins = set(claimed_versions) | set(actual_versions)
    for plugin in sorted(all_plugins):
        claimed = claimed_versions.get(plugin)
        actual = actual_versions.get(plugin)

        if claimed and actual:
            if claimed == actual:
                findings.append(_finding(
                    category="version",
                    status="ok",
                    severity="INFO",
                    detail=f"{plugin} version matches: {actual}",
                    plugin=plugin,
                    claimed=claimed,
                    actual=actual,
                ))
            else:
                findings.append(_finding(
                    category="version",
                    status="drift",
                    severity="WARNING",
                    detail=f"{plugin} version mismatch: CLAUDE.md says {claimed}, plugin.json says {actual}",
                    plugin=plugin,
                    claimed=claimed,
                    actual=actual,
                ))
        elif claimed and not actual:
            findings.append(_finding(
                category="version",
                status="phantom",
                severity="WARNING",
                detail=f"{plugin} version in CLAUDE.md but plugin not found",
                plugin=plugin,
                claimed=claimed,
            ))
        elif actual and not claimed:
            findings.append(_finding(
                category="version",
                status="undocumented",
                severity="WARNING",
                detail=f"{plugin} has version {actual} but not listed in CLAUDE.md versions line",
                plugin=plugin,
                actual=actual,
            ))

    return findings


def _check_file_claims(content: str, project_root: Path) -> List[dict]:
    """Check backtick-quoted file paths in CLAUDE.md exist on disk."""
    findings = []
    # Match paths that contain / and have an extension (relative file references)
    path_re = re.compile(r"`([a-zA-Z0-9_./-]+/[a-zA-Z0-9_./-]+\.\w+)`")

    for match in path_re.finditer(content):
        path_str = match.group(1)
        # Skip URLs, anchors, glob patterns
        if path_str.startswith("http") or "#" in path_str or "*" in path_str:
            continue
        # Skip slash commands and skill references
        if path_str.startswith("/plugin") or path_str.startswith("/doc:"):
            continue
        # Skip paths starting with ./ (context-dependent)
        if path_str.startswith("./"):
            continue

        target = project_root / path_str
        if target.exists():
            findings.append(_finding(
                category="file_path",
                status="ok",
                severity="INFO",
                detail=f"Path exists: {path_str}",
                claimed=path_str,
            ))
        else:
            findings.append(_finding(
                category="file_path",
                status="missing",
                severity="WARNING",
                detail=f"Path referenced in CLAUDE.md does not exist: {path_str}",
                claimed=path_str,
            ))

    return findings


# ---------------------------------------------------------------------------
# Main orchestrator
# ---------------------------------------------------------------------------

def check_claude_md(project_root: Path) -> dict:
    """Run all CLAUDE.md drift checks.

    Args:
        project_root: Path to the project root.

    Returns:
        Complete check results as a dict.
    """
    claude_md = project_root / "CLAUDE.md"
    content = read_file_safe(claude_md)

    if not content:
        return {
            "claude_md_path": "CLAUDE.md",
            "error": "CLAUDE.md not found or empty",
            "findings": [],
            "summary": {"total_checks": 0},
        }

    # Collect ground truth
    truth = _collect_ground_truth(project_root)

    # Parse CLAUDE.md claims
    sections = _parse_plugin_sections(content)

    # Run all checks
    findings: List[dict] = []
    findings.extend(_check_plugin_count(sections, truth))
    findings.extend(_check_component_inventories(sections, truth))
    findings.extend(_check_plugin_versions(content, truth))
    findings.extend(_check_file_claims(content, project_root))

    # Build summary
    status_counts: Dict[str, int] = {}
    category_counts: Dict[str, Dict[str, int]] = {}
    for f in findings:
        st = f["status"]
        cat = f["category"]
        status_counts[st] = status_counts.get(st, 0) + 1
        if cat not in category_counts:
            category_counts[cat] = {}
        category_counts[cat][st] = category_counts[cat].get(st, 0) + 1

    return {
        "claude_md_path": "CLAUDE.md",
        "findings": findings,
        "summary": {
            "total_checks": len(findings),
            **status_counts,
            "by_category": category_counts,
        },
    }


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Check CLAUDE.md claims against filesystem ground truth."
    )
    parser.add_argument(
        "project_root",
        help="Path to the project root directory",
    )

    args = parser.parse_args()
    root = Path(args.project_root).resolve()

    if not root.is_dir():
        print(f"Error: {root} is not a directory", file=sys.stderr)
        sys.exit(1)

    result = check_claude_md(root)
    print(json.dumps(result, indent=2, default=str))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Frontmatter Onboarding Tool

Discovers markdown files that would benefit from tracking frontmatter
and suggests (or applies) minimal frontmatter using git history.

Uses only standard library (no external dependencies). Python 3.8+.

Usage:
    python3 frontmatter_onboard.py <project_root>           # Suggest mode
    python3 frontmatter_onboard.py --apply <project_root>   # Apply frontmatter

Output:
    JSON with candidates and suggested frontmatter.
"""

import argparse
import json
import re
import sys
from datetime import date
from pathlib import Path
from typing import Dict, List, Optional

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import extract_frontmatter, git_last_modified, read_file_safe


# ---------------------------------------------------------------------------
# Whitelist: Only these locations contain docs we own and maintain
# ---------------------------------------------------------------------------

CANDIDATE_PATTERNS: List[str] = [
    # Root-level project docs
    "README.md",
    "CLAUDE.md",
    "INSTALLATION.md",
    "CONTRIBUTING.md",
    "RELEASING.md",
    # Plugin READMEs
    "plugins/*/README.md",
    # Custom docs (not synced reference copies)
    "docs/CLAUDE_CODE_GUIDE.md",
    "docs/SKILL_DEVELOPMENT_BEST_PRACTICES.md",
    "docs/PLAYWRIGHT_CLI.md",
    "docs/README.md",
    "docs/research/README.md",
]


# ---------------------------------------------------------------------------
# Candidate discovery
# ---------------------------------------------------------------------------

def _find_candidates(project_root: Path) -> List[Path]:
    """Find markdown files that need frontmatter onboarding.

    Uses whitelist patterns. Skips files that already have frontmatter.
    """
    candidates: List[Path] = []

    for pattern in CANDIDATE_PATTERNS:
        for md in sorted(project_root.glob(pattern)):
            if not md.is_file():
                continue
            content = read_file_safe(md)
            if not content:
                continue
            # Skip files that already have any frontmatter
            if extract_frontmatter(content) is not None:
                continue
            candidates.append(md)

    return candidates


# ---------------------------------------------------------------------------
# Frontmatter generation
# ---------------------------------------------------------------------------

def _extract_title(content: str) -> Optional[str]:
    """Extract the first heading from markdown content.

    Handles both markdown # headings and HTML <h1> tags.
    """
    # Try HTML <h1> first (some READMEs use this)
    html_match = re.search(r"<h1[^>]*>(.+?)</h1>", content, re.IGNORECASE | re.DOTALL)
    if html_match:
        title = html_match.group(1).strip()
        title = re.sub(r"<[^>]+>", "", title)  # Strip nested HTML tags
        return title

    # Fall back to markdown # heading
    md_match = re.search(r"^#\s+(.+)$", content, re.MULTILINE)
    if md_match:
        title = md_match.group(1).strip()
        title = re.sub(r"\*\*(.+?)\*\*", r"\1", title)
        title = re.sub(r"\[(.+?)\]\(.+?\)", r"\1", title)
        return title

    return None


def _git_last_date(path: Path, project_root: Path) -> str:
    """Get the last commit date (YYYY-MM-DD) for a file via git log."""
    rel = str(path.relative_to(project_root))
    iso_date = git_last_modified(rel, str(project_root))
    if iso_date:
        return iso_date[:10]
    return date.today().isoformat()


def _generate_frontmatter(path: Path, project_root: Path) -> Dict[str, str]:
    """Generate minimal 2-field frontmatter for a doc."""
    content = read_file_safe(path) or ""
    title = _extract_title(content) or path.stem
    last_updated = _git_last_date(path, project_root)

    return {
        "title": title,
        "last_updated": last_updated,
    }


def _format_frontmatter(fm: Dict[str, str]) -> str:
    """Format frontmatter dict as YAML block."""
    lines = ["---"]
    lines.append(f'title: "{fm["title"]}"')
    lines.append(f'last_updated: {fm["last_updated"]}')
    lines.append("---")
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Apply frontmatter
# ---------------------------------------------------------------------------

def _apply_frontmatter(path: Path, fm: Dict[str, str]) -> bool:
    """Prepend frontmatter to a file. Returns True on success."""
    content = read_file_safe(path)
    if content is None:
        return False

    # Double-check: don't add if frontmatter already exists
    if extract_frontmatter(content) is not None:
        return False

    fm_block = _format_frontmatter(fm)
    new_content = fm_block + "\n\n" + content
    try:
        path.write_text(new_content, encoding="utf-8")
        return True
    except Exception:
        return False


# ---------------------------------------------------------------------------
# Main orchestrator
# ---------------------------------------------------------------------------

def suggest_onboarding(project_root: Path) -> dict:
    """Find candidates and generate suggested frontmatter.

    Returns dict with candidates list and summary.
    """
    candidates = _find_candidates(project_root)

    results = []
    for path in candidates:
        rel = str(path.relative_to(project_root))
        fm = _generate_frontmatter(path, project_root)
        results.append({
            "path": rel,
            "suggested_frontmatter": fm,
        })

    return {
        "candidates": results,
        "summary": {
            "total_scanned": len(results) + _count_skipped(project_root),
            "already_has_frontmatter": _count_skipped(project_root),
            "candidates": len(results),
        },
    }


def _count_skipped(project_root: Path) -> int:
    """Count files matching whitelist that already have frontmatter."""
    count = 0
    for pattern in CANDIDATE_PATTERNS:
        for md in project_root.glob(pattern):
            if not md.is_file():
                continue
            content = read_file_safe(md)
            if content and extract_frontmatter(content) is not None:
                count += 1
    return count


def apply_onboarding(project_root: Path) -> dict:
    """Apply frontmatter to all candidates.

    Returns dict with results for each file.
    """
    candidates = _find_candidates(project_root)

    results = []
    applied = 0
    for path in candidates:
        rel = str(path.relative_to(project_root))
        fm = _generate_frontmatter(path, project_root)
        success = _apply_frontmatter(path, fm)
        results.append({
            "path": rel,
            "frontmatter": fm,
            "applied": success,
        })
        if success:
            applied += 1

    return {
        "results": results,
        "summary": {
            "candidates": len(candidates),
            "applied": applied,
            "failed": len(candidates) - applied,
        },
    }


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Suggest or apply frontmatter to docs that need tracking."
    )
    parser.add_argument(
        "project_root",
        help="Path to the project root directory",
    )
    parser.add_argument(
        "--apply",
        action="store_true",
        help="Apply suggested frontmatter to candidate files",
    )

    args = parser.parse_args()
    root = Path(args.project_root).resolve()

    if not root.is_dir():
        print(f"Error: {root} is not a directory", file=sys.stderr)
        sys.exit(1)

    if args.apply:
        result = apply_onboarding(root)
    else:
        result = suggest_onboarding(root)

    print(json.dumps(result, indent=2, default=str))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Broken link and file reference detection for doc-freshness.

Parses markdown files for internal links, anchor references, and
backtick-quoted file paths. Verifies targets exist.

Uses only standard library (no external dependencies). Python 3.8+.
"""

import sys
from pathlib import Path
from typing import Dict, List, Optional

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    extract_backtick_paths,
    extract_headings,
    heading_to_slug,
    parse_markdown_links,
    read_file_safe,
    resolve_relative_path,
)


def check_links(
    doc_path: Path, project_root: Path, content: Optional[str] = None,
    check_backtick_paths: bool = False,
) -> List[Dict[str, object]]:
    """Check all internal links in a markdown file.

    Returns list of findings with keys:
        doc, line, target, status ('ok'|'broken'|'warning'), reason, type.
    """
    if content is None:
        content = read_file_safe(doc_path)
    if content is None:
        return [{
            "doc": str(doc_path.relative_to(project_root)),
            "line": 0,
            "target": "(file)",
            "status": "broken",
            "reason": "Cannot read file",
            "type": "file",
        }]

    findings: List[Dict[str, object]] = []
    rel_doc = str(doc_path.relative_to(project_root))

    # Check markdown links
    links = parse_markdown_links(content)
    self_heading_slugs = {str(h["slug"]) for h in extract_headings(content)}
    for link in links:
        target = str(link["target"])
        line = link["line"]

        # Skip external URLs
        if target.startswith(("http://", "https://", "mailto:", "ftp://", "data:")):
            continue

        # Skip pure anchor links within same file
        if target.startswith("#"):
            slug = target[1:]
            if slug not in self_heading_slugs:
                findings.append({
                    "doc": rel_doc,
                    "line": line,
                    "target": target,
                    "status": "broken",
                    "reason": f"Anchor '{slug}' not found in this file",
                    "type": "anchor",
                })
            continue

        # Handle target#anchor
        has_anchor = "#" in target
        anchor = ""
        if has_anchor:
            target_path_str, anchor = target.rsplit("#", 1)
        else:
            target_path_str = target

        # Resolve the target path (with project root boundary check)
        resolved = resolve_relative_path(doc_path, target_path_str, project_root)

        if not resolved.exists():
            findings.append({
                "doc": rel_doc,
                "line": line,
                "target": target,
                "status": "broken",
                "reason": "Target file does not exist",
                "type": "link",
            })
        elif has_anchor and anchor:
            # Verify anchor in target file
            target_content = read_file_safe(resolved)
            if target_content:
                headings = extract_headings(target_content)
                heading_slugs = {str(h["slug"]) for h in headings}
                if anchor not in heading_slugs:
                    findings.append({
                        "doc": rel_doc,
                        "line": line,
                        "target": target,
                        "status": "broken",
                        "reason": f"Anchor '#{anchor}' not found in {target_path_str}",
                        "type": "anchor",
                    })

    # Check backtick-quoted file paths (opt-in, off by default)
    if not check_backtick_paths:
        return findings
    backtick_paths = extract_backtick_paths(content)
    for ref in backtick_paths:
        ref_path = str(ref["path"])
        line = ref["line"]

        # Resolve relative to project root (backtick paths are typically root-relative)
        resolved = project_root / ref_path
        if not resolved.exists():
            # Also try relative to the doc's directory
            resolved_from_doc = doc_path.parent / ref_path
            if not resolved_from_doc.exists():
                findings.append({
                    "doc": rel_doc,
                    "line": line,
                    "target": ref_path,
                    "status": "warning",
                    "reason": "Referenced file path does not exist",
                    "type": "file_ref",
                })

    return findings


def check_all_links(
    doc_paths: List[Path], project_root: Path,
    check_backtick_paths: bool = False,
) -> Dict[str, object]:
    """Check links across all discovered documentation files.

    Returns dict with:
        findings: list of all findings (broken/warning only)
        summary: {total_checked, broken, warnings, ok}
    """
    all_findings: List[Dict[str, object]] = []
    total_links = 0
    broken = 0
    warnings = 0

    for doc_path in doc_paths:
        # Count total links in this doc for accurate summary
        content = read_file_safe(doc_path)
        if content:
            total_links += len(parse_markdown_links(content))
            if check_backtick_paths:
                total_links += len(extract_backtick_paths(content))

        findings = check_links(doc_path, project_root, content, check_backtick_paths)
        for f in findings:
            if f["status"] == "broken":
                broken += 1
            elif f["status"] == "warning":
                warnings += 1
        all_findings.extend(findings)

    return {
        "findings": all_findings,
        "summary": {
            "total_checked": total_links,
            "broken": broken,
            "warnings": warnings,
            "ok": total_links - broken - warnings,
        },
    }


if __name__ == "__main__":
    import json

    if len(sys.argv) < 3:
        print("Usage: link_checker.py <project-root> <doc-file> [<doc-file> ...]",
              file=sys.stderr)
        sys.exit(1)

    root = Path(sys.argv[1]).resolve()
    doc_files = [Path(f).resolve() for f in sys.argv[2:]]

    result = check_all_links(doc_files, root)
    print(json.dumps(result, indent=2, default=str))

#!/usr/bin/env python3
"""
Documentation Freshness Scanner (Orchestrator)

Discovers documentation files, runs link checks, version checks,
and git staleness analysis. Outputs a unified JSON report.

Uses only standard library (no external dependencies). Python 3.8+.

Usage:
    python3 scan_freshness.py <project_root>
    python3 scan_freshness.py --links-only <project_root>
    python3 scan_freshness.py --critical-only <project_root>
    python3 scan_freshness.py --config .arkhe.yaml <project_root>

Output:
    JSON with docs inventory, broken links, version mismatches,
    staleness metrics, and summary.
"""

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path
from typing import Dict, List, Optional

sys.path.insert(0, str(Path(__file__).resolve().parent))
from shared import (
    detect_doc_tier,
    discover_markdown_files,
    extract_headings,
    git_is_available,
    git_last_modified,
    parse_markdown_links,
    read_file_safe,
    read_yaml_section,
    DEFAULT_DOC_PATTERNS,
    DEFAULT_EXCLUDE_PATTERNS,
)
from link_checker import check_all_links
from version_checker import check_all_versions, collect_ground_truth
from claude_md_checker import check_claude_md


# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------

def load_config(root: Path, config_path: Optional[str] = None) -> dict:
    """Load doc-freshness configuration from .arkhe.yaml."""
    if config_path:
        path = Path(config_path)
        if not path.is_absolute():
            path = root / path
    else:
        path = root / ".arkhe.yaml"

    if not path.exists():
        return {}

    section = read_yaml_section(path, "doc-freshness")
    return section or {}


# ---------------------------------------------------------------------------
# Git staleness analysis
# ---------------------------------------------------------------------------

def compute_staleness(
    doc_paths: List[Path], project_root: Path
) -> List[Dict[str, object]]:
    """Compute git-based staleness for each documentation file.

    Compares each doc's last commit date against the most recent
    code commit in the project.

    Returns list of dicts with:
        doc, doc_date, doc_age_days, latest_code_date, code_age_days, drift_score.
    """
    if not git_is_available(str(project_root)):
        return []

    now = datetime.now(timezone.utc).replace(tzinfo=None)
    staleness: List[Dict[str, object]] = []

    # Get latest code commit date (any file that isn't .md)
    import subprocess
    try:
        result = subprocess.run(
            ["git", "log", "-1", "--format=%aI", "--diff-filter=ACMR",
             "--", "*.py", "*.ts", "*.tsx", "*.js", "*.jsx",
             "*.java", "*.kt", "*.go", "*.rs", "*.rb",
             "*.yaml", "*.yml", "*.json", "*.toml"],
            capture_output=True, text=True, timeout=10,
            cwd=str(project_root),
        )
        latest_code_date_str = result.stdout.strip() if result.returncode == 0 else None
    except (subprocess.TimeoutExpired, FileNotFoundError):
        latest_code_date_str = None

    latest_code_date = _parse_git_date(latest_code_date_str)

    for doc_path in doc_paths:
        rel_doc = str(doc_path.relative_to(project_root))
        doc_date_str = git_last_modified(rel_doc, str(project_root))
        doc_date = _parse_git_date(doc_date_str)

        doc_age_days = (now - doc_date).days if doc_date else None
        code_age_days = (now - latest_code_date).days if latest_code_date else None

        # Compute drift score
        drift_score = "unknown"
        if doc_age_days is not None and code_age_days is not None:
            gap = doc_age_days - code_age_days
            if gap <= 7:
                drift_score = "fresh"
            elif gap <= 30:
                drift_score = "aging"
            elif gap <= 90:
                drift_score = "stale"
            else:
                drift_score = "very_stale"

        staleness.append({
            "doc": rel_doc,
            "doc_date": doc_date_str,
            "doc_age_days": doc_age_days,
            "latest_code_date": latest_code_date_str,
            "code_age_days": code_age_days,
            "drift_score": drift_score,
        })

    return staleness


def _parse_git_date(date_str: Optional[str]) -> Optional[datetime]:
    """Parse a git date string to a UTC-naive datetime for age calculations.

    Accepts both %ai format ('2026-03-15 10:30:00 -0400') and
    %aI format ('2026-03-15T10:30:00-04:00').
    """
    if not date_str:
        return None
    try:
        # Try ISO 8601 with timezone first (%aI format)
        # Python 3.7+ supports %z for ±HH:MM
        cleaned = date_str.strip()
        if "T" in cleaned:
            # %aI format: 2026-03-15T10:30:00-04:00
            dt = datetime.fromisoformat(cleaned)
        else:
            # %ai format: 2026-03-15 10:30:00 -0400
            # Convert -0400 to -04:00 for fromisoformat
            parts = cleaned.rsplit(" ", 1)
            if len(parts) == 2 and (parts[1].startswith("+") or parts[1].startswith("-")):
                tz = parts[1]
                if len(tz) == 5:  # -0400
                    tz = tz[:3] + ":" + tz[3:]
                cleaned = parts[0].replace(" ", "T") + tz
            dt = datetime.fromisoformat(cleaned)

        # Convert to UTC-naive for consistent age calculations
        if dt.tzinfo is not None:
            dt = dt.astimezone(timezone.utc).replace(tzinfo=None)
        return dt
    except (ValueError, IndexError, TypeError):
        # Fallback: parse just date/time, ignore timezone
        try:
            return datetime.strptime(date_str[:19], "%Y-%m-%d %H:%M:%S")
        except (ValueError, IndexError):
            return None


# ---------------------------------------------------------------------------
# Document inventory
# ---------------------------------------------------------------------------

def build_inventory(
    doc_paths: List[Path], project_root: Path
) -> List[Dict[str, object]]:
    """Build an inventory of documentation files with their metadata."""
    inventory: List[Dict[str, object]] = []

    for doc_path in doc_paths:
        rel_doc = str(doc_path.relative_to(project_root))
        content = read_file_safe(doc_path)
        tier = detect_doc_tier(doc_path)
        if content is None:
            inventory.append({
                "path": rel_doc,
                "tier": tier,
                "headings": [],
                "link_count": 0,
                "line_count": 0,
                "error": "Cannot read file",
            })
            continue

        headings = extract_headings(content)
        links = parse_markdown_links(content)

        inventory.append({
            "path": rel_doc,
            "tier": tier,
            "headings": [h["text"] for h in headings],
            "link_count": len(links),
            "line_count": len(content.splitlines()),
        })

    return inventory


# ---------------------------------------------------------------------------
# Main orchestrator
# ---------------------------------------------------------------------------

def scan(
    project_root: Path,
    links_only: bool = False,
    config_path: Optional[str] = None,
    critical_only: bool = False,
) -> dict:
    """Run the full freshness scan.

    Args:
        project_root: Path to the project root.
        links_only: If True, only run link checks (fast mode).
        config_path: Optional path to config file.
        critical_only: If True, only scan critical docs (README.md, CLAUDE.md, plugin docs).

    Returns:
        Complete scan results as a dict.
    """
    # Load configuration
    config = load_config(project_root, config_path)
    doc_patterns = config.get("doc_patterns", DEFAULT_DOC_PATTERNS)
    exclude = config.get("exclude", DEFAULT_EXCLUDE_PATTERNS)

    # Ensure patterns are lists
    if isinstance(doc_patterns, str):
        doc_patterns = [doc_patterns]
    if isinstance(exclude, str):
        exclude = [exclude]

    # Discover documentation files
    doc_paths = discover_markdown_files(project_root, doc_patterns, exclude)

    # Filter to critical docs if requested
    if critical_only:
        critical_paths = {
            "README.md",
            "CLAUDE.md",
        }
        doc_paths = [
            p for p in doc_paths
            if str(p.relative_to(project_root)) in critical_paths
        ]

    if not doc_paths:
        return {
            "error": "No documentation files found",
            "config": {
                "doc_patterns": doc_patterns,
                "exclude": exclude,
            },
            "docs": [],
            "broken_links": {"findings": [], "summary": {}},
            "version_mismatches": {"findings": [], "summary": {}},
            "staleness": [],
            "summary": {
                "total_docs": 0,
                "broken_links": 0,
                "version_mismatches": 0,
                "stale_docs": 0,
            },
        }

    # Build inventory
    inventory = build_inventory(doc_paths, project_root)

    # Run link checks (always)
    link_results = check_all_links(doc_paths, project_root)

    # Run additional checks unless links-only mode
    version_results: Dict[str, object] = {"findings": [], "summary": {}}
    staleness: List[Dict[str, object]] = []
    claude_md_results: Dict[str, object] = {"findings": [], "summary": {}}

    if not links_only:
        version_results = check_all_versions(doc_paths, project_root)
        staleness = compute_staleness(doc_paths, project_root)
        # CLAUDE.md structural drift check
        if (project_root / "CLAUDE.md").exists():
            claude_md_results = check_claude_md(project_root)

    # Build summary
    broken_count = link_results["summary"].get("broken", 0)
    version_mismatch_count = version_results.get("summary", {})
    if isinstance(version_mismatch_count, dict):
        version_mismatch_count = version_mismatch_count.get("mismatches", 0)
    else:
        version_mismatch_count = 0

    stale_count = sum(
        1 for s in staleness
        if s.get("drift_score") in ("stale", "very_stale")
    )

    # Count docs per tier
    tier_counts = {"basic": 0, "deep": 0}
    for doc in inventory:
        tier = doc.get("tier", "basic")
        tier_counts[tier] = tier_counts.get(tier, 0) + 1

    return {
        "scan_date": datetime.now().isoformat(),
        "project_root": str(project_root),
        "config": {
            "doc_patterns": doc_patterns,
            "exclude": exclude,
            "links_only": links_only,
            "critical_only": critical_only,
        },
        "docs": inventory,
        "broken_links": link_results,
        "version_mismatches": version_results,
        "staleness": staleness,
        "claude_md_drift": claude_md_results,
        "summary": {
            "total_docs": len(doc_paths),
            "tier_counts": tier_counts,
            "broken_links": broken_count,
            "version_mismatches": version_mismatch_count,
            "stale_docs": stale_count,
            "claude_md_drift": len([
                f for f in claude_md_results.get("findings", [])
                if f.get("status") != "ok"
            ]),
        },
    }


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Scan project documentation for freshness issues."
    )
    parser.add_argument(
        "project_root",
        help="Path to the project root directory",
    )
    parser.add_argument(
        "--links-only",
        action="store_true",
        help="Only check for broken links (fast mode)",
    )
    parser.add_argument(
        "--critical-only",
        action="store_true",
        help="Only scan critical docs (README.md, CLAUDE.md, plugin docs) — fast mode for SessionStart hook",
    )
    parser.add_argument(
        "--config",
        help="Path to .arkhe.yaml config file (default: <project_root>/.arkhe.yaml)",
    )

    args = parser.parse_args()
    root = Path(args.project_root).resolve()

    if not root.is_dir():
        print(f"Error: {root} is not a directory", file=sys.stderr)
        sys.exit(1)

    result = scan(root, links_only=args.links_only, config_path=args.config, critical_only=args.critical_only)
    print(json.dumps(result, indent=2, default=str))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Shared utilities for doc-freshness scanners.

Common helpers for markdown parsing, git operations, and file handling.
Uses only standard library (no external dependencies). Python 3.8+.
"""

import re
import subprocess
from pathlib import Path
from typing import Dict, List, Optional, Set, Tuple

# Directories to skip when walking project trees
SKIP_DIRS: Set[str] = {
    "build", ".gradle", "node_modules", ".git", "target", "out", ".idea",
    "__pycache__", ".venv", "venv", "env", ".tox", ".nox", ".mypy_cache",
    ".pytest_cache", ".ruff_cache", "dist", ".next", ".turbo", "coverage",
    "vendor", ".bundle", "_site", ".docusaurus",
}

# Default glob patterns for discovering documentation files
DEFAULT_DOC_PATTERNS: List[str] = [
    "README.md", "CLAUDE.md", "CONTRIBUTING.md", "CHANGELOG.md",
    "INSTALL.md", "INSTALLATION.md", "SETUP.md", "LICENSE.md",
    "docs/**/*.md", "wiki/**/*.md", "plan/**/*.md",
    ".github/**/*.md",
]

# Default patterns to exclude
DEFAULT_EXCLUDE_PATTERNS: List[str] = [
    "node_modules/**", ".git/**", "vendor/**", ".venv/**", "venv/**",
    "dist/**", "build/**", "target/**", "coverage/**",
]


def extract_frontmatter(content: str) -> Optional[Dict[str, str]]:
    """Extract YAML frontmatter from markdown content.

    Parses the block between opening and closing '---' delimiters.
    Returns flat key-value dict, or None if no frontmatter found.
    """
    lines = content.splitlines()
    if not lines or lines[0].strip() != "---":
        return None

    for i, line in enumerate(lines[1:50], start=1):
        if line.strip() == "---":
            result: Dict[str, str] = {}
            for fm_line in lines[1:i]:
                fm_stripped = fm_line.strip()
                if not fm_stripped or fm_stripped.startswith("#"):
                    continue
                if ":" in fm_stripped:
                    key, _, value = fm_stripped.partition(":")
                    value = value.strip().strip('"').strip("'")
                    if value:
                        result[key.strip()] = value
            return result if result else None

    return None


def detect_doc_tier(path: Path) -> str:
    """Detect whether a doc qualifies for deep or basic scanning.

    Deep tier: has YAML frontmatter with last_updated or version fields.
    Basic tier: everything else.
    """
    content = read_file_safe(path)
    if not content:
        return "basic"

    fm = extract_frontmatter(content)
    if fm and ("last_updated" in fm or "version" in fm):
        return "deep"
    return "basic"


def read_file_safe(path: Path) -> Optional[str]:
    """Read a file's text content, returning None on any error."""
    try:
        return path.read_text(encoding="utf-8")
    except Exception:
        return None


def read_json_safe(path: Path) -> Optional[dict]:
    """Read and parse a JSON file, returning None on any error."""
    import json
    content = read_file_safe(path)
    if content is None:
        return None
    try:
        return json.loads(content)
    except (ValueError, TypeError):
        return None


def read_yaml_section(path: Path, section: str) -> Optional[dict]:
    """Read a YAML file and extract a top-level section.

    Uses a simple line-based parser (no PyYAML dependency).
    Only handles flat key-value and simple list structures.
    """
    content = read_file_safe(path)
    if content is None:
        return None

    lines = content.splitlines()
    in_section = False
    result: dict = {}
    current_key = None
    current_list: List[str] = []
    base_indent = 0

    for line in lines:
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue

        indent = len(line) - len(line.lstrip())

        if indent == 0 and stripped.endswith(":"):
            if in_section:
                if current_key and current_list:
                    result[current_key] = current_list
                break
            if stripped == f"{section}:":
                in_section = True
                base_indent = 2
            continue

        if not in_section:
            continue

        if indent < base_indent and not stripped.startswith("-"):
            if current_key and current_list:
                result[current_key] = current_list
            break

        if ":" in stripped and not stripped.startswith("-"):
            if current_key and current_list:
                result[current_key] = current_list
                current_list = []
            key, _, value = stripped.partition(":")
            current_key = key.strip()
            value = value.strip().strip('"').strip("'")
            if value:
                result[current_key] = value
                current_key = None
        elif stripped.startswith("- "):
            item = stripped[2:].strip().strip('"').strip("'")
            current_list.append(item)

    if in_section and current_key and current_list:
        result[current_key] = current_list

    return result if result else None


# ---------------------------------------------------------------------------
# Markdown parsing
# ---------------------------------------------------------------------------

# Matches fenced code block delimiters (backtick or tilde, 3+ chars)
_FENCE_RE = re.compile(r'^(`{3,}|~{3,})')


def _is_fence_line(stripped: str) -> bool:
    """Check if a stripped line is a fenced code block delimiter."""
    return bool(_FENCE_RE.match(stripped))

# Matches [text](target) and [text](target "title")
_INLINE_LINK_RE = re.compile(
    r'\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)'
)

# Matches [text]: target  (reference-style links)
_REF_LINK_RE = re.compile(
    r'^\[([^\]]+)\]:\s+(\S+)', re.MULTILINE
)

# Matches <img src="..."> and <img src='...'>
_IMG_SRC_RE = re.compile(
    r'<img\s[^>]*src=["\']([^"\']+)["\']', re.IGNORECASE
)

# Matches backtick-quoted file paths like `src/foo.ts` or `docs/bar.md`
_BACKTICK_PATH_RE = re.compile(
    r'`([a-zA-Z0-9_./-]+\.[a-zA-Z0-9]+)`'
)

# Patterns that look like file paths but are not
_NON_FILE_PREFIXES = re.compile(
    r'^(?:'
    r'(?:feature|fix|release|hotfix|bugfix|chore|dependabot)/'  # git branches
    r'|roles/'                                                    # IAM roles
    r')',
    re.IGNORECASE,
)

# Known code file extensions (for owner/repo disambiguation)
_CODE_EXTENSIONS = {
    "md", "py", "js", "ts", "tsx", "jsx", "go", "rs", "java",
    "kt", "kts", "rb", "php", "c", "h", "cpp", "hpp", "cs", "swift",
    "yaml", "yml", "json", "toml", "xml", "html", "css", "scss",
    "sql", "sh", "bash", "zsh", "ps1", "bat", "cmd",
    "txt", "cfg", "ini", "conf", "env", "lock", "sum",
    "vue", "svelte", "astro", "mdx", "png", "jpg", "svg", "gif",
    "gradle", "properties", "sq",
}


def _is_likely_file_path(path: str) -> bool:
    """Heuristic: does this backtick-quoted string look like a file path?

    Returns False for git branches, IAM roles, runtime URLs, and owner/repo refs.
    """
    if _NON_FILE_PREFIXES.match(path):
        return False

    # Skip owner/repo patterns: exactly 2 segments with non-code extension
    # e.g. "deznode/skola.dev" (TLD), but keep "src/main.py" (code extension)
    segments = path.split("/")
    if len(segments) == 2 and "." not in segments[0] and "." in segments[1]:
        ext = segments[1].rsplit(".", 1)[-1].lower()
        if ext not in _CODE_EXTENSIONS:
            return False

    return True


def parse_markdown_links(content: str) -> List[Dict[str, object]]:
    """Extract all links from markdown content.

    Returns list of dicts with keys: text, target, line, type.
    Types: 'inline', 'reference', 'image'.
    Skips links inside fenced code blocks.
    """
    links: List[Dict[str, object]] = []
    lines = content.splitlines()
    in_code_block = False

    for line_num, line in enumerate(lines, start=1):
        stripped = line.strip()
        if _is_fence_line(stripped):
            in_code_block = not in_code_block
            continue
        if in_code_block:
            continue

        for match in _INLINE_LINK_RE.finditer(line):
            links.append({
                "text": match.group(1),
                "target": match.group(2),
                "line": line_num,
                "type": "inline",
            })

        for match in _IMG_SRC_RE.finditer(line):
            links.append({
                "text": "(image)",
                "target": match.group(1),
                "line": line_num,
                "type": "image",
            })

        # Reference-style links on this line
        ref_match = _REF_LINK_RE.match(line)
        if ref_match:
            links.append({
                "text": ref_match.group(1),
                "target": ref_match.group(2),
                "line": line_num,
                "type": "reference",
            })

    return links


def extract_backtick_paths(content: str) -> List[Dict[str, object]]:
    """Extract backtick-quoted file paths from markdown content.

    Filters for paths that look like actual file references (contain / and extension).
    """
    paths: List[Dict[str, object]] = []
    lines = content.splitlines()
    in_code_block = False

    for line_num, line in enumerate(lines, start=1):
        stripped = line.strip()
        if _is_fence_line(stripped):
            in_code_block = not in_code_block
            continue
        if in_code_block:
            continue

        for match in _BACKTICK_PATH_RE.finditer(line):
            path = match.group(1)
            # Only include paths with a directory separator that look like files
            if "/" in path and _is_likely_file_path(path):
                paths.append({
                    "path": path,
                    "line": line_num,
                })

    return paths


def extract_headings(content: str) -> List[Dict[str, object]]:
    """Extract markdown headings from content.

    Returns list of dicts with keys: level, text, slug, line.
    """
    headings: List[Dict[str, object]] = []
    lines = content.splitlines()
    in_code_block = False

    for line_num, line in enumerate(lines, start=1):
        stripped = line.strip()
        if _is_fence_line(stripped):
            in_code_block = not in_code_block
            continue
        if in_code_block:
            continue

        match = re.match(r'^(#{1,6})\s+(.+?)(?:\s*#*\s*)?$', stripped)
        if match:
            level = len(match.group(1))
            text = match.group(2).strip()
            slug = heading_to_slug(text)
            headings.append({
                "level": level,
                "text": text,
                "slug": slug,
                "line": line_num,
            })

    return headings


def heading_to_slug(text: str) -> str:
    """Convert a heading to a GitHub-compatible anchor slug.

    Rules: lowercase, spaces→hyphens, strip non-ASCII and non-alphanumeric
    except hyphens. Matches GitHub's anchor generation algorithm.
    """
    slug = text.lower()
    slug = re.sub(r'[^a-z0-9\s-]', '', slug)
    slug = re.sub(r'[\s]+', '-', slug)
    slug = slug.strip('-')
    return slug


# ---------------------------------------------------------------------------
# Git helpers
# ---------------------------------------------------------------------------

def git_last_modified(file_path: str, project_root: str) -> Optional[str]:
    """Get the last commit date for a file via git log.

    Returns strict ISO 8601 date string (e.g., '2026-03-15T10:30:00-04:00') or None.
    """
    try:
        result = subprocess.run(
            ["git", "log", "-1", "--format=%aI", "--", file_path],
            capture_output=True, text=True, timeout=10,
            cwd=project_root,
        )
        if result.returncode == 0 and result.stdout.strip():
            return result.stdout.strip()
    except (subprocess.TimeoutExpired, FileNotFoundError):
        pass
    return None


def git_is_available(project_root: str) -> bool:
    """Check if git is available and the directory is a git repo."""
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--is-inside-work-tree"],
            capture_output=True, text=True, timeout=5,
            cwd=project_root,
        )
        return result.returncode == 0
    except (subprocess.TimeoutExpired, FileNotFoundError):
        return False


def resolve_relative_path(
    from_file: Path, link_target: str, project_root: Optional[Path] = None
) -> Path:
    """Resolve a relative link target from a document's location.

    If project_root is provided, returns Path("") for paths that
    escape the project root (path traversal protection).
    """
    # Strip anchor fragments
    target = link_target.split("#")[0]
    if not target:
        return from_file  # Same-file anchor
    resolved = (from_file.parent / target).resolve()
    if project_root is not None:
        try:
            resolved.relative_to(project_root.resolve())
        except ValueError:
            return Path("")  # Escapes project root
    return resolved


def discover_markdown_files(
    root: Path,
    patterns: Optional[List[str]] = None,
    exclude: Optional[List[str]] = None,
) -> List[Path]:
    """Discover markdown files in a project using glob patterns.

    Args:
        root: Project root directory.
        patterns: Glob patterns to search. Defaults to DEFAULT_DOC_PATTERNS.
        exclude: Glob patterns to exclude. Defaults to DEFAULT_EXCLUDE_PATTERNS.

    Returns:
        Sorted list of unique markdown file paths.
    """
    if patterns is None:
        patterns = DEFAULT_DOC_PATTERNS
    if exclude is None:
        exclude = DEFAULT_EXCLUDE_PATTERNS

    # Build exclusion set
    excluded: Set[Path] = set()
    for pattern in exclude:
        excluded.update(root.glob(pattern))

    # Discover files
    found: Set[Path] = set()
    for pattern in patterns:
        for path in root.glob(pattern):
            if path.is_file() and path not in excluded:
                # Check not inside a skip directory
                parts = path.relative_to(root).parts
                if not any(part in SKIP_DIRS for part in parts):
                    found.add(path)

    return sorted(found)


# ---------------------------------------------------------------------------
# Severity helpers (shared across formatters)
# ---------------------------------------------------------------------------

# Severity ordering (higher = more severe)
SEVERITY_ORDER: Dict[str, int] = {
    "critical": 3,
    "error": 3,      # Treat "error" same as "critical"
    "warning": 2,
    "info": 1,
}


def normalize_severity(raw: str) -> str:
    """Normalize severity string to one of: error, warning, info.

    Maps 'critical', 'ERROR', 'broken', 'mismatch' etc. to canonical levels.
    """
    lower = raw.lower().strip()
    if lower in ("critical", "error", "broken", "mismatch"):
        return "error"
    if lower in ("warning", "warn", "minor_mismatch", "outdated_frontmatter"):
        return "warning"
    return "info"


def severity_meets_threshold(severity: str, threshold: str) -> bool:
    """Check if a severity meets the minimum threshold."""
    sev_rank = SEVERITY_ORDER.get(severity, 0)
    thr_rank = SEVERITY_ORDER.get(threshold, 0)
    return sev_rank >= thr_rank

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

# ── Configuration ──────────────────────────────────────────────────────
VERBATIM_FILES=(shared.py link_checker.py version_checker.py scan_freshness.py)
MANUAL_FILES=(claude_md_checker.py frontmatter_onboard.py)

# ── Paths ──────────────────────────────────────────────────────────────
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PLUGIN_SCRIPTS="$SCRIPT_DIR"

ACTION_REPO=""
YES_FLAG=false

for arg in "$@"; do
  case "$arg" in
    -y|--yes) YES_FLAG=true ;;
    -h|--help)
      echo "Usage: $(basename "$0") <path-to-docs-health-action> [-y|--yes]"
      echo ""
      echo "Syncs checker scripts from docs-health-action into this plugin."
      echo ""
      echo "  Verbatim-copies: ${VERBATIM_FILES[*]}"
      echo "  Manual review:   ${MANUAL_FILES[*]}"
      echo ""
      echo "Options:"
      echo "  -y, --yes   Skip confirmation prompts"
      echo "  -h, --help  Show this help"
      exit 0
      ;;
    -*) echo "Unknown flag: $arg"; exit 1 ;;
    *) ACTION_REPO="$arg" ;;
  esac
done

if [[ -z "$ACTION_REPO" ]]; then
  echo "Usage: $(basename "$0") <path-to-docs-health-action> [-y|--yes]"
  echo ""
  echo "Syncs checker scripts from docs-health-action into this plugin."
  echo "Example: $(basename "$0") ~/Projects/docs-health-action"
  exit 1
fi

ACTION_SCRIPTS="$ACTION_REPO/scripts"

# ── Validate ───────────────────────────────────────────────────────────
if [[ ! -d "$ACTION_SCRIPTS" ]]; then
  echo "ERROR: Cannot find action scripts at: $ACTION_SCRIPTS"
  echo "       Make sure the path points to the docs-health-action repo root."
  exit 1
fi

echo "=== Sync from docs-health-action ==="
echo "Source:      $(cd "$ACTION_SCRIPTS" && pwd)"
echo "Destination: $PLUGIN_SCRIPTS"
echo ""

# Validate all source files exist
missing=false
for f in "${VERBATIM_FILES[@]}" "${MANUAL_FILES[@]}"; do
  if [[ ! -f "$ACTION_SCRIPTS/$f" ]]; then
    echo "ERROR: Missing in action repo: $ACTION_SCRIPTS/$f"
    missing=true
  fi
done
if $missing; then exit 1; fi

# ── Helpers ────────────────────────────────────────────────────────────
confirm() {
  if $YES_FLAG; then return 0; fi
  local prompt="$1"
  read -r -p "$prompt [y/N] " answer
  [[ "$answer" =~ ^[Yy]$ ]]
}

# ── Verbatim copies ───────────────────────────────────────────────────
echo "── Verbatim files ──"
copied=0
skipped_identical=0
skipped_declined=0

for f in "${VERBATIM_FILES[@]}"; do
  src="$ACTION_SCRIPTS/$f"
  dst="$PLUGIN_SCRIPTS/$f"

  if [[ ! -f "$dst" ]]; then
    echo "  [new] $f — does not exist in plugin yet"
    if confirm "  Copy $f?"; then
      cp "$src" "$dst"
      echo "  [copied] $f"
      copied=$((copied + 1))
    else
      echo "  [skipped] $f"
      skipped_declined=$((skipped_declined + 1))
    fi
    continue
  fi

  if diff -q "$src" "$dst" >/dev/null 2>&1; then
    echo "  [ok] $f — already identical"
    skipped_identical=$((skipped_identical + 1))
    continue
  fi

  changes=$(diff "$src" "$dst" | grep -c '^[<>]' || true)
  echo "  [changed] $f — $changes lines differ"
  if confirm "  Overwrite $f?"; then
    cp "$src" "$dst"
    echo "  [copied] $f"
    ((copied++))
  else
    echo "  [skipped] $f"
    ((skipped_declined++))
  fi
done

# ── Manual review ─────────────────────────────────────────────────────
echo ""
echo "── Files requiring manual review ──"
echo "(These have plugin-specific customizations — do NOT copy blindly)"
echo ""

needs_review=0

for f in "${MANUAL_FILES[@]}"; do
  src="$ACTION_SCRIPTS/$f"
  dst="$PLUGIN_SCRIPTS/$f"

  if [[ ! -f "$dst" ]]; then
    echo "  [new] $f — does not exist in plugin (copy manually if needed)"
    needs_review=$((needs_review + 1))
    continue
  fi

  if diff -q "$src" "$dst" >/dev/null 2>&1; then
    echo "  [ok] $f — already in sync"
    continue
  fi

  ((needs_review++))
  echo "┌─── $f: action (a) vs plugin (b) ───"
  diff -u "$src" "$dst" || true
  echo "└────────────────────────────────────────────"
  echo ""

  case "$f" in
    claude_md_checker.py)
      echo "  PRESERVE in plugin:"
      echo "    - Arkhe-specific _NAME_OVERRIDES dict values"
      echo "  MERGE from action:"
      echo "    - has_plugins guard (prevents crash without plugins/ dir)"
      echo "    - Any new check logic or bug fixes"
      ;;
    frontmatter_onboard.py)
      echo "  PRESERVE in plugin:"
      echo "    - Arkhe-specific CANDIDATE_PATTERNS whitelist"
      echo "  MERGE from action:"
      echo "    - patterns parameter on public functions (API flexibility)"
      echo "    - _count_skipped() single-call optimization (efficiency bug fix)"
      echo "    - Any new check logic or bug fixes"
      ;;
  esac
  echo ""
done

# ── Summary ───────────────────────────────────────────────────────────
echo ""
echo "=== Summary ==="
echo "  Copied:            $copied"
echo "  Already identical: $skipped_identical"
echo "  Declined:          $skipped_declined"
echo "  Need manual merge: $needs_review"

if ((needs_review > 0)); then
  echo ""
  echo "Review the diffs above and manually merge changes for the flagged files."
fi