#!/usr/bin/env python3
# file: scripts/audit_rust_export_completeness.py
# version: 2

"""Audit Rust crate-root façade completeness and canonical same-crate references."""

from __future__ import annotations

import argparse
import dataclasses
import pathlib
import re
import sys
import tomllib

from _rust_audit_common import line_depths, mask_source

_IGNORED_DIRECTORY_NAMES = frozenset({
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "builds",
    "dist",
    "node_modules",
    "target",
})


@dataclasses.dataclass(frozen=True)
class Candidate:
    """One façade or canonical-reference violation candidate."""

    code: str
    path: str
    line: int
    message: str


@dataclasses.dataclass(frozen=True)
class Declaration:
    """One module-level public or crate-public declaration."""

    module: str
    name: str
    visibility: str
    kind: str
    path: pathlib.Path
    line: int
    column: int


@dataclasses.dataclass(frozen=True)
class Target:
    """One Rust crate target and the module files reachable from its root."""

    package: pathlib.Path
    root: pathlib.Path
    modules: tuple[tuple[pathlib.Path, str], ...]


@dataclasses.dataclass(frozen=True)
class CanonicalItem:
    """One visible item with its canonical crate-root name."""

    declaration: Declaration
    canonical_name: str


def _is_ignored(path: pathlib.Path, root: pathlib.Path) -> bool:
    """Return whether a path belongs to a generated or local-only tree."""

    try:
        relative = path.relative_to(root)
    except ValueError:
        return True
    return bool(set(relative.parts) & _IGNORED_DIRECTORY_NAMES)


def crate_roots(root: pathlib.Path) -> list[pathlib.Path]:
    """Discover Rust package roots recursively below one project root."""

    crates: set[pathlib.Path] = set()
    for manifest in root.rglob("Cargo.toml"):
        if _is_ignored(manifest, root):
            continue
        crate = manifest.parent
        if (crate / "src/lib.rs").is_file() or (crate / "src/main.rs").is_file() or _explicit_target_paths(crate):
            crates.add(crate)
    return sorted(crates)


def _explicit_target_paths(crate: pathlib.Path) -> tuple[pathlib.Path, ...]:
    """Return existing explicit lib/bin target paths declared in Cargo.toml."""

    manifest = crate / "Cargo.toml"
    if not manifest.is_file():
        return ()
    try:
        data = tomllib.loads(manifest.read_text(encoding="utf-8"))
    except (OSError, tomllib.TOMLDecodeError):
        return ()
    paths: set[pathlib.Path] = set()
    lib = data.get("lib")
    if isinstance(lib, dict) and isinstance(lib.get("path"), str):
        candidate = crate / lib["path"]
        if candidate.is_file():
            paths.add(candidate)
    bins = data.get("bin", [])
    if isinstance(bins, list):
        for entry in bins:
            if isinstance(entry, dict) and isinstance(entry.get("path"), str):
                candidate = crate / entry["path"]
                if candidate.is_file():
                    paths.add(candidate)
    return tuple(sorted(paths))


def target_roots(crate: pathlib.Path) -> list[pathlib.Path]:
    """Return standard and explicitly configured Rust crate target roots."""

    roots: set[pathlib.Path] = set(_explicit_target_paths(crate))
    manifest = crate / "Cargo.toml"
    package: dict[str, object] = {}
    if manifest.is_file():
        try:
            parsed = tomllib.loads(manifest.read_text(encoding="utf-8"))
            raw_package = parsed.get("package", {})
            if isinstance(raw_package, dict):
                package = raw_package
        except (OSError, tomllib.TOMLDecodeError):
            package = {}

    library = crate / "src/lib.rs"
    if library.is_file():
        roots.add(library)

    if package.get("autobins", True) is not False:
        main = crate / "src/main.rs"
        if main.is_file():
            roots.add(main)
        bin_dir = crate / "src/bin"
        if bin_dir.is_dir():
            roots.update(path for path in bin_dir.glob("*.rs") if path.is_file())
            roots.update(path for path in bin_dir.glob("*/main.rs") if path.is_file())
    return sorted(roots)


def _standard_child_module_path(current: pathlib.Path, target_root: pathlib.Path, name: str) -> pathlib.Path | None:
    """Resolve a standard `mod name;` file relative to one source module."""

    if current == target_root or current.name == "mod.rs":
        base = current.parent
    else:
        base = current.parent / current.stem
    direct = base / f"{name}.rs"
    nested = base / name / "mod.rs"
    if direct.is_file():
        return direct
    if nested.is_file():
        return nested
    return None


def _module_children(path: pathlib.Path, target_root: pathlib.Path) -> list[tuple[pathlib.Path, str]]:
    """Return top-level external module declarations from one Rust source file."""

    text = path.read_text(encoding="utf-8")
    lines = text.splitlines()
    masked, _ = mask_source(text)
    masked_lines = masked.splitlines()
    depths = line_depths(masked)
    module_pattern = re.compile(r"^\s*(?:(?:pub|pub\([^)]*\))\s+)?mod\s+([A-Za-z_][A-Za-z0-9_]*)\s*;")
    path_pattern = re.compile(r'^\s*#\[path\s*=\s*"([^"]+)"\]\s*$')
    found: list[tuple[pathlib.Path, str]] = []
    for index, masked_line in enumerate(masked_lines):
        if index >= len(depths) or depths[index] != 0:
            continue
        match = module_pattern.match(masked_line)
        if match is None:
            continue
        module_name = match.group(1)
        explicit: pathlib.Path | None = None
        probe = index - 1
        while probe >= 0 and lines[probe].lstrip().startswith("#["):
            path_match = path_pattern.match(lines[probe])
            if path_match is not None:
                candidate = (path.parent / path_match.group(1)).resolve()
                if candidate.is_file():
                    explicit = candidate
                break
            probe -= 1
        child = explicit or _standard_child_module_path(path, target_root, module_name)
        if child is not None:
            found.append((child.resolve(), module_name))
    return found


def target_modules(crate: pathlib.Path, target_root: pathlib.Path) -> dict[pathlib.Path, str]:
    """Return module files reachable from one target root and their logical paths."""

    root = target_root.resolve()
    modules: dict[pathlib.Path, str] = {root: ""}
    pending: list[pathlib.Path] = [root]
    while pending:
        current = pending.pop()
        parent_module = modules[current]
        for child, name in _module_children(current, root):
            if _is_ignored(child, crate) or child in modules:
                continue
            module = f"{parent_module}::{name}" if parent_module else name
            modules[child] = module
            pending.append(child)
    return modules


def targets(crate: pathlib.Path) -> list[Target]:
    """Return independently compiled crate targets for one Cargo package."""

    found: list[Target] = []
    for root in target_roots(crate):
        modules = target_modules(crate, root)
        found.append(Target(crate, root.resolve(), tuple(sorted(modules.items(), key=lambda item: item[0].as_posix()))))
    return found


def declaration_candidates(path: pathlib.Path, module: str) -> list[Declaration]:
    """Return top-level public or crate-public declarations from one module file."""

    text = path.read_text(encoding="utf-8")
    lines = text.splitlines()
    masked, _ = mask_source(text)
    depths = line_depths(masked)
    pattern = re.compile(
        r"^\s*(pub(?:\(crate\))?)\s+"
        r"(?:(?:async|unsafe|const)\s+)*"
        r"(const|static|type|struct|enum|trait|union|fn)\s+"
        r"([A-Za-z_][A-Za-z0-9_]*)"
    )
    found: list[Declaration] = []
    for line_number, line in enumerate(lines, 1):
        if line_number - 1 >= len(depths) or depths[line_number - 1] != 0:
            continue
        match = pattern.match(line)
        if match is None:
            continue
        found.append(
            Declaration(
                module=module,
                name=match.group(3),
                visibility=match.group(1),
                kind=match.group(2),
                path=path,
                line=line_number,
                column=match.start(3),
            )
        )
    return found


def _parse_export_item(module: str, item: str) -> tuple[tuple[str, str], str] | None:
    """Parse one simple explicit item from a crate-root re-export."""

    stripped = item.strip()
    if not stripped or stripped == "*" or "{" in stripped or "}" in stripped:
        return None
    alias_match = re.fullmatch(
        r"([A-Za-z_][A-Za-z0-9_]*)(?:\s+as\s+([A-Za-z_][A-Za-z0-9_]*))?",
        stripped,
    )
    if alias_match is None:
        return None
    name = alias_match.group(1)
    alias = alias_match.group(2) or name
    return (module, name), alias


def root_exports(root_source: pathlib.Path) -> dict[tuple[str, str], str]:
    """Return explicit crate-root re-exports keyed by source module and symbol."""

    exports: dict[tuple[str, str], str] = {}
    text = root_source.read_text(encoding="utf-8")
    pattern = re.compile(
        r"^\s*pub(?:\(crate\))?\s+use\s+(?:self|crate)::(.*?);",
        re.MULTILINE | re.DOTALL,
    )
    for match in pattern.finditer(text):
        body = " ".join(part.strip() for part in match.group(1).splitlines())
        if "{" in body and body.endswith("}"):
            prefix, group = body.split("{", 1)
            module = prefix.rstrip().rstrip(":")
            for item in group[:-1].split(","):
                parsed = _parse_export_item(module, item)
                if parsed is not None:
                    key, alias = parsed
                    exports[key] = alias
            continue
        if "::" not in body:
            continue
        module, item = body.rsplit("::", 1)
        parsed = _parse_export_item(module, item)
        if parsed is not None:
            key, alias = parsed
            exports[key] = alias
    return exports


def _reexport_lines(root_source: pathlib.Path) -> set[int]:
    """Return crate-root line numbers occupied by explicit re-export statements."""

    text = root_source.read_text(encoding="utf-8")
    pattern = re.compile(
        r"^\s*pub(?:\(crate\))?\s+use\s+(?:self|crate)::.*?;",
        re.MULTILINE | re.DOTALL,
    )
    lines: set[int] = set()
    for match in pattern.finditer(text):
        start = text.count("\n", 0, match.start()) + 1
        end = text.count("\n", 0, match.end()) + 1
        lines.update(range(start, end + 1))
    return lines


def _target_declarations(target: Target) -> list[Declaration]:
    """Return visible module-level declarations for one crate target."""

    return [
        declaration
        for path, module in target.modules
        for declaration in declaration_candidates(path, module)
    ]


def _external_usage(target: Target, declaration: Declaration) -> bool:
    """Return whether a crate-public item is clearly referenced from another module file."""

    if not declaration.module:
        return True
    direct = f"crate::{declaration.module}::{declaration.name}"
    root_direct = f"crate::{declaration.name}"
    super_direct = f"super::{declaration.name}"
    for path, _ in target.modules:
        if path.resolve() == declaration.path.resolve():
            continue
        masked, _ = mask_source(path.read_text(encoding="utf-8"))
        if direct in masked or root_direct in masked or super_direct in masked:
            return True
    return False


def _declaration_lookup(declarations: list[Declaration]) -> dict[tuple[pathlib.Path, int, str], Declaration]:
    """Index declaration-name occurrences that must not be treated as references."""

    return {(item.path.resolve(), item.line, item.name): item for item in declarations}


def _canonical_reference_candidates(
    workspace: pathlib.Path,
    target: Target,
    declarations: list[Declaration],
    exports: dict[tuple[str, str], str],
) -> list[Candidate]:
    """Return non-canonical references to items that have a crate-root identity."""

    items: list[CanonicalItem] = []
    for declaration in declarations:
        if declaration.path.resolve() == target.root and not declaration.module:
            items.append(CanonicalItem(declaration, declaration.name))
            continue
        alias = exports.get((declaration.module, declaration.name))
        if alias is not None:
            items.append(CanonicalItem(declaration, alias))

    by_token: dict[str, list[CanonicalItem]] = {}
    for item in items:
        by_token.setdefault(item.declaration.name, []).append(item)
        if item.canonical_name != item.declaration.name:
            by_token.setdefault(item.canonical_name, []).append(item)
    if not by_token:
        return []

    token_pattern = re.compile(r"\b(?:" + "|".join(re.escape(name) for name in sorted(by_token, key=len, reverse=True)) + r")\b")
    declaration_lookup = _declaration_lookup(declarations)
    root_reexport_lines = _reexport_lines(target.root)
    internal_roots = {segment for _, module in target.modules if module for segment in module.split("::")}
    candidates: list[Candidate] = []

    for path, _ in target.modules:
        relative = path.relative_to(workspace).as_posix()
        masked, _ = mask_source(path.read_text(encoding="utf-8"))
        for line_number, line in enumerate(masked.splitlines(), 1):
            for match in token_pattern.finditer(line):
                token = match.group(0)
                for item in by_token[token]:
                    declaration = item.declaration
                    if declaration.kind == "fn" and re.match(r"\s*(?:\(|::<)", line[match.end():]) is None:
                        continue
                    prefix = line[:match.start()]
                    if re.search(r"(?:const|static|type|struct|enum|trait|union|fn)\s+$", prefix) is not None:
                        continue
                    if (path.resolve(), line_number, token) in declaration_lookup and token == declaration.name:
                        continue

                    if path.resolve() == target.root and line_number in root_reexport_lines:
                        continue

                    if token == item.canonical_name and re.search(r"\bcrate::\s*$", prefix) is not None:
                        continue

                    if match.start() > 0 and line[match.start() - 1] == ".":
                        continue

                    qualified = re.search(
                        r"([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*)::\s*$",
                        prefix,
                    )
                    if qualified is not None:
                        first = qualified.group(1).split("::", 1)[0]
                        if first not in internal_roots and first not in {"crate", "self", "super"}:
                            continue

                    candidates.append(
                        Candidate(
                            code="RUST-IMPORT-201",
                            path=relative,
                            line=line_number,
                            message=(
                                f"non-canonical same-crate reference `{token}` for shared "
                                f"{declaration.visibility} `{declaration.name}`; use `crate::{item.canonical_name}`"
                            ),
                        )
                    )
    return candidates


def audit_target(workspace: pathlib.Path, target: Target) -> list[Candidate]:
    """Audit one independently compiled Rust crate target."""

    declarations = _target_declarations(target)
    exports = root_exports(target.root)
    candidates: list[Candidate] = []

    for declaration in declarations:
        if declaration.path.resolve() == target.root and not declaration.module:
            continue
        required = declaration.visibility == "pub" or _external_usage(target, declaration)
        if required and (declaration.module, declaration.name) not in exports:
            reason = "public item" if declaration.visibility == "pub" else "crate-public item used outside its module"
            candidates.append(
                Candidate(
                    code="RUST-API-201",
                    path=declaration.path.relative_to(workspace).as_posix(),
                    line=declaration.line,
                    message=f"{reason} `{declaration.name}` requires an explicit crate-root re-export",
                )
            )

    candidates.extend(_canonical_reference_candidates(workspace, target, declarations, exports))
    return candidates


def audit_crate(workspace: pathlib.Path, crate: pathlib.Path) -> list[Candidate]:
    """Audit every independently compiled target in one Cargo package."""

    return [candidate for target in targets(crate) for candidate in audit_target(workspace, target)]


def audit_workspace(root: pathlib.Path) -> tuple[list[pathlib.Path], list[Candidate]]:
    """Return discovered packages and all façade candidates below one project root."""

    crates = crate_roots(root)
    candidates = list({candidate for crate in crates for candidate in audit_crate(root, crate)})
    candidates.sort(key=lambda candidate: (candidate.code, candidate.path, candidate.line, candidate.message))
    return crates, candidates


def main() -> int:
    """Run the export-completeness audit."""

    parser = argparse.ArgumentParser()
    parser.add_argument("--root", default=".")
    parser.add_argument("--report-only", action="store_true")
    parser.add_argument("--summary-only", action="store_true")
    arguments = parser.parse_args()

    workspace = pathlib.Path(arguments.root).resolve()
    if not workspace.is_dir():
        sys.stderr.write(f"Rust export completeness audit: invalid root: {workspace}\n")
        return 2

    crates, candidates = audit_workspace(workspace)
    if not crates:
        sys.stderr.write(f"Rust export completeness audit: no Rust package found below {workspace}\n")
        return 2

    counts: dict[str, int] = {}
    for candidate in candidates:
        counts[candidate.code] = counts.get(candidate.code, 0) + 1

    sys.stdout.write(f"Rust export completeness audit: {len(candidates)} candidate(s) across {len(crates)} package(s)\n")
    for code in sorted(counts):
        sys.stdout.write(f"{code}: {counts[code]}\n")
    if not arguments.summary_only:
        for candidate in candidates:
            sys.stdout.write(f"{candidate.code} {candidate.path}:{candidate.line}: {candidate.message}\n")
    return 0 if arguments.report_only or not candidates else 1


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