oct_lint.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/linter/oct_lint.py
 
"""
Purpose
-------
Provide a strict, deterministic linter for Option C projects that validates
mandatory header blocks, module docstrings, diagnostics profiles, and basic
testing presence, and can optionally auto-fix header blocks.
 
Responsibilities
----------------
- Walk the project tree from a given Option C project root or directory or single file given as an argument.
- Skip excluded directories and the linter's own files.
- Validate the 4-line mandatory header block for every Python module.
- Validate the presence and structure of the module docstring.
- Validate the presence of a Diagnostics profile block (Domain + L2/L3/L4).
- Validate basic ``_dbg`` usage in non-trivial modules; ``_dbg`` is the
  structured debug logger provided by the ``oc_diagnostics`` package
  (``from oc_diagnostics import _dbg``).
- Validate the presence of regression tests for each module.
- Optionally auto-fix header blocks while archiving originals.
- Produce a detailed log file and a colorized terminal summary.
- Optionally emit machine-readable JSON to stdout (``--json``).
 
Diagnostics
-----------
Domain: OCT-LINTER
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Must not modify files unless ``--fix-headers`` is explicitly requested.
- Must treat the provided project root as authoritative for all relative paths.
- Must write a deterministic log file into the project's ``logs/`` directory
  when writable; warns and continues if the log directory is unwritable.
- Must not import project modules; analysis is purely static.
- Must be callable both from the OCT CLI and as a standalone module.
 
Dependencies
------------
- oct.core.exclusions (directory and wildcard exclusion lists)
- oct.core.parsing (safe AST parsing helper)
- oct.core.paths (project-relative path helper)
- oct.core.waivers (inline waiver parsing)
"""
 
import argparse
import ast
import concurrent.futures
import json
import re
import shutil
import subprocess
import threading
import sys
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Any
 
# ---------------------------------------------------------------------
# OI-513: log state is owned by :class:`LinterContext`. The previous
# module-level ``LOG_HANDLE`` global is gone — concurrent linter runs
# (parallel --jobs, MCP, health dashboard) each carry their own handle
# on their own context without cross-contamination.
# ---------------------------------------------------------------------
 
# Resolved path to OCT's own package directory — used to exclude OCT internals
# from linting when the project tree contains OCT itself.
_OCT_PACKAGE_DIR = Path(__file__).resolve().parent.parent
 
# ---------------------------------------------------------------------
# Directory exclusion rules
# ---------------------------------------------------------------------
 
from oct.core.exclusions import LINTER_EXCLUDE_DIRS as EXCLUDE_DIRS
from oct.core.exclusions import WILDCARD_EXCLUDE_DIRS
from oct.core.parsing import safe_parse
from oct.core.paths import to_project_relative
from oct.core.waivers import parse_inline_waivers
 
# ---------------------------------------------------------------------
# Lint rule profiles
# ---------------------------------------------------------------------
 
_DEFAULT_RULES = {
    "header": True,
    "docstring": True,
    "diagnostics_profile": True,
    "dbg_usage": True,
    "dbg_import": True,
    "func_pattern": True,
    "tests_exist": True,
    "type_hints": True,
    "no_hardcoded_secrets": True,
    "dbg_assert_safety": True,
    "dependencies_section": True,
}
 
_PROFILES = {
    # V3.1 spec profiles: proto / compact / strict
    "strict": dict(_DEFAULT_RULES),
    "compact": {
        "header": True,
        "docstring": True,
        "diagnostics_profile": True,
        "dbg_usage": True,
        "dbg_import": True,
        "func_pattern": True,
        "tests_exist": True,
        "type_hints": True,
        "no_hardcoded_secrets": True,
        "dbg_assert_safety": True,
        # Spec C1 / Drift A: Dependencies section enforced at strict only
        "dependencies_section": False,
        # compact: public-function-only checking for dbg/func/docstring
        "_compact_mode": True,
    },
    "proto": {
        "header": True,
        "docstring": True,
        "diagnostics_profile": False,
        "dbg_usage": False,
        "dbg_import": False,
        "func_pattern": False,
        "tests_exist": False,
        "type_hints": False,
        "no_hardcoded_secrets": False,
        "dbg_assert_safety": False,
        "dependencies_section": False,
    },
    # Deprecated aliases (backwards compat)
    "default": dict(_DEFAULT_RULES),
    "minimal": {
        "header": True,
        "docstring": True,
        "diagnostics_profile": False,
        "dbg_usage": False,
        "dbg_import": False,
        "func_pattern": False,
        "tests_exist": False,
        "type_hints": False,
        "no_hardcoded_secrets": False,
        "dbg_assert_safety": False,
        "dependencies_section": False,
    },
}
 
# ---------------------------------------------------------------------
# .octrc.json schema validation (OI-411)
# ---------------------------------------------------------------------
 
def _strict_config_requested() -> bool:
    """Return True when strict-config enforcement is active.
 
    Strict mode is opt-in via the ``OCT_STRICT_CONFIG`` environment variable
    (any truthy value: ``1``, ``true``, ``yes``, ``on``). The ``--strict-config``
    CLI flag wired up in ``oct/cli.py`` sets this env var before dispatch.
    """
    import os as _os
    val = _os.environ.get("OCT_STRICT_CONFIG", "").strip().lower()
    return val in ("1", "true", "yes", "on")
 
 
def _validate_octrc_schema(cfg: dict) -> list[str]:
    """Validate the structure of a loaded ``.octrc.json`` dict.
 
    Returns a list of human-readable error strings. Empty list means the
    config is structurally acceptable. Unknown keys are tolerated (forward
    compat); only known keys are type-checked.
    """
    errors: list[str] = []
    if not isinstance(cfg, dict):
        return [f"top-level must be an object, got {type(cfg).__name__}"]
 
    linter_cfg = cfg.get("linter")
    if linter_cfg is not None and not isinstance(linter_cfg, dict):
        errors.append(f"'linter' must be an object, got {type(linter_cfg).__name__}")
        linter_cfg = None  # skip further linter validation
 
    profile = linter_cfg.get("profile") if isinstance(linter_cfg, dict) else None
    if profile is not None:
        if not isinstance(profile, str):
            errors.append(f"'linter.profile' must be a string, got {type(profile).__name__}")
        elif profile not in _PROFILES:
            valid = ", ".join(p for p in _PROFILES if not p.startswith("_"))
            errors.append(f"'linter.profile' unknown value '{profile}' (valid: {valid})")
 
    if isinstance(linter_cfg, dict):
        for key in ("exclude_dirs_add", "exclude_dirs_remove", "wildcard_exclude_add"):
            val = linter_cfg.get(key)
            if val is None:
                continue
            if not isinstance(val, list):
                errors.append(f"'linter.{key}' must be a list, got {type(val).__name__}")
                continue
            for i, item in enumerate(val):
                if not isinstance(item, str):
                    errors.append(f"'linter.{key}[{i}]' must be a string, got {type(item).__name__}")
 
        rules = linter_cfg.get("rules")
        if rules is not None:
            if not isinstance(rules, dict):
                errors.append(f"'linter.rules' must be an object, got {type(rules).__name__}")
            else:
                for rule_name, rule_val in rules.items():
                    if not isinstance(rule_val, bool):
                        errors.append(
                            f"'linter.rules.{rule_name}' must be a bool, got {type(rule_val).__name__}"
                        )
 
    # OI-424: validate the optional formatter section. Only the
    # ``max_backups_per_file`` key is currently type-checked; unknown
    # keys stay tolerated for forward compatibility.
    formatter_cfg = cfg.get("formatter")
    if formatter_cfg is not None:
        if not isinstance(formatter_cfg, dict):
            errors.append(
                f"'formatter' must be an object, got {type(formatter_cfg).__name__}"
            )
        else:
            max_backups = formatter_cfg.get("max_backups_per_file")
            if max_backups is not None:
                if not isinstance(max_backups, int) or isinstance(max_backups, bool):
                    errors.append(
                        "'formatter.max_backups_per_file' must be an int, "
                        f"got {type(max_backups).__name__}"
                    )
                elif max_backups < 0:
                    errors.append(
                        "'formatter.max_backups_per_file' must be >= 0, "
                        f"got {max_backups}"
                    )
 
    # Phase 4E — G-E8: validate the optional git section (blueprint §13.1).
    git_cfg = cfg.get("git")
    if git_cfg is not None:
        if not isinstance(git_cfg, dict):
            errors.append(f"'git' must be an object, got {type(git_cfg).__name__}")
        else:
            _GIT_VALID_PROFILES = ("proto", "compact", "strict", "auto")
 
            pb = git_cfg.get("protected_branches")
            if pb is not None:
                if not isinstance(pb, list):
                    errors.append(f"'git.protected_branches' must be a list, got {type(pb).__name__}")
                else:
                    for i, item in enumerate(pb):
                        if not isinstance(item, str):
                            errors.append(f"'git.protected_branches[{i}]' must be a string, got {type(item).__name__}")
 
            bn = git_cfg.get("branch_naming")
            if bn is not None:
                if not isinstance(bn, dict):
                    errors.append(f"'git.branch_naming' must be an object, got {type(bn).__name__}")
                else:
                    bn_enabled = bn.get("enabled")
                    if bn_enabled is not None and not isinstance(bn_enabled, bool):
                        errors.append(f"'git.branch_naming.enabled' must be a bool, got {type(bn_enabled).__name__}")
                    bn_patterns = bn.get("patterns")
                    if bn_patterns is not None:
                        if not isinstance(bn_patterns, list):
                            errors.append(f"'git.branch_naming.patterns' must be a list, got {type(bn_patterns).__name__}")
                        else:
                            for i, pat in enumerate(bn_patterns):
                                if not isinstance(pat, str):
                                    errors.append(f"'git.branch_naming.patterns[{i}]' must be a string, got {type(pat).__name__}")
 
            pcp = git_cfg.get("pre_commit_profile")
            if pcp is not None:
                if not isinstance(pcp, str):
                    errors.append(f"'git.pre_commit_profile' must be a string, got {type(pcp).__name__}")
                elif pcp not in _GIT_VALID_PROFILES:
                    errors.append(f"'git.pre_commit_profile' unknown value '{pcp}' (valid: {', '.join(_GIT_VALID_PROFILES)})")
 
            for bool_key in (
                "conventional_commits", "require_changelog_update",
                "auto_branch_on_protected", "add_post_check",
            ):
                val = git_cfg.get(bool_key)
                if val is not None and not isinstance(val, bool):
                    errors.append(f"'git.{bool_key}' must be a bool, got {type(val).__name__}")
 
            sds = git_cfg.get("status_default_scope")
            if sds is not None:
                if not isinstance(sds, str):
                    errors.append(
                        f"'git.status_default_scope' must be a string, "
                        f"got {type(sds).__name__}"
                    )
                elif sds not in ("project", "repo", "auto"):
                    errors.append(
                        f"'git.status_default_scope' unknown value "
                        f"'{sds}' (valid: project, repo, auto)"
                    )
 
            oum = git_cfg.get("observe_unstaged_mutation")
            if oum is not None:
                if isinstance(oum, bool):
                    pass  # bool form: False == "off", True == "warn"
                elif isinstance(oum, str):
                    if oum not in ("off", "warn", "block"):
                        errors.append(
                            f"'git.observe_unstaged_mutation' unknown "
                            f"value '{oum}' (valid: off, warn, block)"
                        )
                else:
                    errors.append(
                        f"'git.observe_unstaged_mutation' must be a "
                        f"bool or string, got {type(oum).__name__}"
                    )
 
            ids = git_cfg.get("ignore_default_scope")
            if ids is not None:
                if not isinstance(ids, str):
                    errors.append(
                        f"'git.ignore_default_scope' must be a string, "
                        f"got {type(ids).__name__}"
                    )
                elif ids not in ("workspace", "project", "nearest"):
                    errors.append(
                        f"'git.ignore_default_scope' unknown value "
                        f"'{ids}' (valid: workspace, project, nearest)"
                    )
 
            for num_key in ("large_file_warn_mb", "timeout", "long_timeout"):
                val = git_cfg.get(num_key)
                if val is not None:
                    if not isinstance(val, (int, float)) or isinstance(val, bool):
                        errors.append(f"'git.{num_key}' must be a number, got {type(val).__name__}")
                    elif val <= 0:
                        errors.append(f"'git.{num_key}' must be > 0, got {val}")
 
    # FS-507: validate the optional secret_scanner section.
    scanner_cfg = cfg.get("secret_scanner")
    if scanner_cfg is not None:
        if not isinstance(scanner_cfg, dict):
            errors.append(f"'secret_scanner' must be an object, got {type(scanner_cfg).__name__}")
        else:
            et = scanner_cfg.get("code_entropy_threshold")
            if et is not None:
                if not isinstance(et, (int, float)) or isinstance(et, bool):
                    errors.append(
                        f"'secret_scanner.code_entropy_threshold' must be a number, got {type(et).__name__}"
                    )
                elif et < 0:
                    errors.append(
                        f"'secret_scanner.code_entropy_threshold' must be >= 0, got {et}"
                    )
            for key in ("docstring_entropy_threshold", "comment_entropy_threshold"):
                val = scanner_cfg.get(key)
                if val is not None:
                    if not isinstance(val, (int, float)) or isinstance(val, bool):
                        errors.append(
                            f"'secret_scanner.{key}' must be a number, got {type(val).__name__}"
                        )
                    elif val < 0:
                        errors.append(
                            f"'secret_scanner.{key}' must be >= 0, got {val}"
                        )
 
            # OI-540: validate entropy_exclusions array.
            excl = scanner_cfg.get("entropy_exclusions")
            if excl is not None:
                if not isinstance(excl, list):
                    errors.append("'secret_scanner.entropy_exclusions' must be an array")
                else:
                    for i, entry in enumerate(excl):
                        if not isinstance(entry, dict):
                            errors.append(
                                f"'secret_scanner.entropy_exclusions[{i}]' must be an object"
                            )
                            continue
                        ctx_val = entry.get("context")
                        if ctx_val not in ("namedtuple_field", "test_directory", "module_self_doc"):
                            errors.append(
                                f"'secret_scanner.entropy_exclusions[{i}].context' "
                                f"must be 'namedtuple_field', 'test_directory', or 'module_self_doc'"
                            )
                        if ctx_val == "namedtuple_field":
                            if not isinstance(entry.get("field_name_pattern"), str):
                                errors.append(
                                    f"'secret_scanner.entropy_exclusions[{i}].field_name_pattern' "
                                    f"must be a string"
                                )
                        elif ctx_val in ("test_directory", "module_self_doc"):
                            if not isinstance(entry.get("path_pattern"), str):
                                errors.append(
                                    f"'secret_scanner.entropy_exclusions[{i}].path_pattern' "
                                    f"must be a string"
                                )
                            restrictions = entry.get("restrictions", {})
                            if not isinstance(restrictions, dict):
                                errors.append(
                                    f"'secret_scanner.entropy_exclusions[{i}].restrictions' "
                                    f"must be an object"
                                )
 
    return errors
 
 
# ---------------------------------------------------------------------
# Header constants
# ---------------------------------------------------------------------
 
SHEBANG = "#!/usr/bin/env python3"
ENCODING = "# -*- coding: utf-8 -*-"
 
 
# ---------------------------------------------------------------------
# LinterContext
# ---------------------------------------------------------------------
 
 
@dataclass
class LinterContext:
    """
    Immutable per-run context for the linter.  Replaces module-level globals
    so that concurrent linter invocations do not share mutable state.
    """
 
    project_root: Path
    project_name: str
    diagnostics_dir: Path
    tests_dir: Path
    docs_dir: Path
    log_handle: Any = None
    log_path: Path | None = None
    log_lock: threading.Lock = field(default_factory=threading.Lock)
    # OI-510 / FS-516: one-shot test discovery index. ``name_stems`` is the
    # set of module stems for which a ``test_<stem>.py`` file exists;
    # ``imported_stems`` is the set of module stems imported (whole-word)
    # by any file in tests_dir. ``None`` means "not yet built" — lazy path.
    test_index: dict[str, set[str]] | None = None
    # OI-529: secret-name matching strategy. "substring" (default) matches
    # the legacy behaviour; "word" splits names on _/-/camelCase and only
    # flags whole-segment hits, eliminating false positives like "compass"
    # or "tokenizer".
    secret_match_mode: str = "substring"  # OCT-LINT: disable=no_hardcoded_secrets reason="Field name; documents the matcher mode, not a credential"
    # FS-507: Shannon entropy threshold for string literals. Default 4.5
    # bits/char. Set to 0 to disable entropy checking.
    code_entropy_threshold: float = 4.5
    # Per-context entropy thresholds (docstrings use strict >, code uses >=).
    docstring_entropy_threshold: float = 5.0
    comment_entropy_threshold: float = 5.0
    # OI-540: entropy exclusions from octrc.
    entropy_exclusions: list = field(default_factory=list)
    excluded_field_patterns: list = field(default_factory=list)
    # FS-C4 / Drift item C4: name of the active profile (proto / compact /
    # strict). Used to resolve per-rule severity (advisory vs blocking)
    # via :func:`oct.linter.rule_registry.get_severity`.
    profile_name: str = "strict"
    # FS-510: incremental lint cache. None means cache disabled.
    lint_cache: Any = None
    no_cache_read: bool = False
 
 
# ---------------------------------------------------------------------
# Logging helpers
# ---------------------------------------------------------------------
 
 
def log(message: str, ctx: LinterContext | None = None) -> None:
    """
    Write a single line to the linter log file.
 
    OI-513: ``ctx`` is required in practice — every internal callsite
    threads it through. The ``None`` branch is kept as a silent no-op so
    external callers that import ``log()`` standalone do not crash.
    """
    if ctx is None or ctx.log_handle is None:
        return
    with ctx.log_lock:
        ctx.log_handle.write(message + "\n")
 
 
def print_header(title: str, ctx: LinterContext | None = None) -> None:
    """
    Write a section header to the log.
    """
    log("", ctx)
    log("=" * 70, ctx)
    log(title, ctx)
    log("=" * 70, ctx)
 
 
def report(result: bool, message: str, fix_mode: bool = False,
           ctx: LinterContext | None = None) -> bool:
    """
    Log a PASS/FAIL (or FIXED) line and return the result.
    """
    if fix_mode and not result:
        status = "FIXED"
    else:
        status = "PASS" if result else "FAIL"
    log(f"[{status}] {message}", ctx)
    return result
 
 
# ---------------------------------------------------------------------
# Utility helpers
# ---------------------------------------------------------------------
 
 
def is_excluded_dir(path: Path, exclude_dirs: set, wildcard_exclude_dirs: list) -> bool:
    """
    Return True if the directory name should be excluded from scanning.
    """
    name = path.name
    if name in exclude_dirs:
        return True
    for pattern in wildcard_exclude_dirs:
        if pattern in name:
            return True
    return False
 
 
def read_file(path: Path, ctx: LinterContext | None = None) -> str:
    """
    Read a file as UTF-8, returning an empty string on failure.
    """
    try:
        return path.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as e:
        if ctx is not None:
            log(f"[WARN] Could not read {path}: {e}", ctx)
        return ""
 
 
def _git_changed_files(root: Path) -> list[Path]:
    """Return .py files modified in the git working tree (staged + unstaged).
 
    Phase 4A (G-A7): thin shim over :func:`oct.core.git.git_changed_files`.
    The core module enforces subprocess discipline, credential redaction,
    and path-escape filtering; the linter's sole contract here is to
    preserve the historical "never crash on any git failure" behaviour
    by collapsing every ``GitError`` back to an empty list.
    """
    from oct.core import git as core_git
    try:
        return core_git.git_changed_files(root, extensions={".py"})
    except core_git.GitError:
        return []
 
 
def find_python_files(
    root: Path,
    exclude_dirs: set | None = None,
    wildcard_exclude_dirs: list | None = None,
):
    """
    Yield all Python files under root, excluding the linter itself and
    excluded directories.
 
    Parameters
    ----------
    root:
        The project root to scan.
    exclude_dirs:
        Set of directory names to exclude.  Defaults to the module-level
        ``EXCLUDE_DIRS`` constant.
    wildcard_exclude_dirs:
        List of substrings; directories whose name contains any of these
        are excluded.  Defaults to ``WILDCARD_EXCLUDE_DIRS``.
    """
    if exclude_dirs is None:
        exclude_dirs = EXCLUDE_DIRS
    if wildcard_exclude_dirs is None:
        wildcard_exclude_dirs = WILDCARD_EXCLUDE_DIRS
    for path in root.rglob("*.py"):
        # Skip files inside OCT's own package directory
        try:
            if path.resolve().is_relative_to(_OCT_PACKAGE_DIR):
                continue
        except (OSError, ValueError):
            pass
        parts = path.relative_to(root).parts
        if any(is_excluded_dir(Path(p), exclude_dirs, wildcard_exclude_dirs) for p in parts):
            continue
        yield path
 
 
# ---------------------------------------------------------------------
# Header validation and fixing
# ---------------------------------------------------------------------
 
 
def expected_path_header(path: Path, ctx: LinterContext) -> str:
    """
    Compute the expected file identity header for a given module path.
    """
    rel = to_project_relative(path, ctx.project_root)
    return f"# {rel}"
 
 
def validate_header_block(lines: list[str], path: Path, ctx: LinterContext):
    """
    Validate the mandatory 4-line header block.
 
    Returns (ok, errors) where:
    - ok = True if header block is correct
    - errors = list of error messages
    """
    errors: list[str] = []
 
    if len(lines) < 4:
        errors.append("File too short to contain mandatory header block")
        return False, errors
 
    if lines[0].strip() != SHEBANG:
        errors.append("Shebang missing or incorrect")
 
    if lines[1].strip() != ENCODING:
        errors.append("Encoding line missing or incorrect")
 
    if lines[2].strip() != expected_path_header(path, ctx):
        errors.append("File identity header missing or incorrect")
 
    if lines[3].strip() != "":
        errors.append("Missing mandatory blank line after header block")
 
    return len(errors) == 0, errors
 
 
def _header_boundary(lines: list[str], path: Path, ctx: LinterContext) -> int:
    """
    Return the line index where file content begins, after any existing
    header elements.  OI-509: thin wrapper that delegates to
    :func:`oct.core.parsing.header_boundary` so linter and formatter share
    one implementation.
    """
    from oct.core.parsing import header_boundary
    return header_boundary(
        lines, path, expected_identity=expected_path_header(path, ctx),
    )
 
 
def fix_header_block(path: Path, text: str, ctx: LinterContext) -> bool:
    """
    Rewrite the top of the file to enforce the Option C 4-line header.
    The original file is archived in a `.linter_archive` directory.
    """
    lines = text.splitlines()
 
    # Archive original
    archive_dir = path.parent / ".linter_archive"
    archive_dir.mkdir(exist_ok=True)
    ts = datetime.now().strftime("%Y%m%d-%H%M%S")
    backup_path = archive_dir / f"{path.name}.{ts}.bak"
    shutil.copy2(path, backup_path)
 
    boundary = _header_boundary(lines, path, ctx)
    content = lines[boundary:]
 
    new_header = [
        SHEBANG,
        ENCODING,
        expected_path_header(path, ctx),
        "",
    ]
 
    new_text = "\n".join(new_header + content)
    path.write_text(new_text, encoding="utf-8")
    return True
 
 
def preview_header_fix(path: Path, ctx: LinterContext) -> str:
    """
    Compute what fix_header_block would produce, without writing.
    Returns the corrected 4-line header block as a string.
    """
    new_header = [
        SHEBANG,
        ENCODING,
        expected_path_header(path, ctx),
        "",
    ]
    return "\n".join(new_header)
 
 
# ---------------------------------------------------------------------
# Other rule checks
# ---------------------------------------------------------------------
 
 
def check_docstring(text: str):
    """
    Validate that a module docstring exists and contains the required
    Option C sections.
    """
    m = re.search(r'"""(.*?)"""', text, re.DOTALL)
    if not m:
        return False, "Missing module docstring"
    doc = m.group(1)
    required = ["Purpose", "Responsibilities", "Diagnostics", "Contracts"]
    missing = [s for s in required if s not in doc]
    if missing:
        return False, f"Missing sections: {', '.join(missing)}"
    return True, ""
 
 
_DEP_SECTION_RE = re.compile(
    r'Dependencies\s*\n\s*[-]+\s*\n(.*?)(?:\n\s*\n|\Z)',
    re.DOTALL,
)
_DEP_LINE_RE = re.compile(r'^\s*-\s+\S+\s*\‍([^)]+\‍)\s*$', re.MULTILINE)
_DEP_BULLET_RE = re.compile(r'^\s*[-*]\s+\S', re.MULTILINE)
 
 
def check_dependencies_section(text: str):
    """
    Validate the Dependencies section of a module docstring at strict profile.
 
    Spec reference: Appendix C — Dependencies docstring format. Each entry
    must follow ``- module_name (purpose description)`` so ``oct deps`` can
    parse the dependency graph.
 
    Returns ``(ok, msg)``. Empty Dependencies sections are accepted (a module
    may have no project-internal dependencies); malformed entries are rejected.
    """
    m = re.search(r'"""(.*?)"""', text, re.DOTALL)
    if not m:
        return False, "Missing module docstring"
    doc = m.group(1)
    if "Dependencies" not in doc:
        return False, "Missing Dependencies section in module docstring"
    section_match = _DEP_SECTION_RE.search(doc)
    if not section_match:
        return False, "Malformed Dependencies section (missing underline)"
    section = section_match.group(1)
    bullets = _DEP_BULLET_RE.findall(section)
    if not bullets:
        return True, ""
    valid_lines = _DEP_LINE_RE.findall(section)
    if len(valid_lines) != len(bullets):
        return False, (
            "Malformed Dependencies entry; expected '- module_name (purpose)'"
        )
    return True, ""
 
 
def _extract_module_docstring(text: str) -> str | None:
    """
    Return the text of the first module-level triple-quoted string found
    before the first ``def`` or ``class`` statement, or ``None`` if absent.
 
    Scoping to pre-code text prevents false positives from in-function
    string literals that happen to contain keywords like 'L2', 'Diagnostics',
    or 'Domain:'.
    """
    pre_code_match = re.search(r'^\s*(def|class)\s', text, re.MULTILINE)
    pre_code = text[:pre_code_match.start()] if pre_code_match else text
    for pattern in (r'"""(.*?)"""', r"'''(.*?)'''"):
        m = re.search(pattern, pre_code, re.DOTALL)
        if m:
            return m.group(1)
    return None
 
 
def check_diagnostics_profile(text: str):
    """
    Validate that a Diagnostics profile is present in the module docstring.
 
    Scopes the search to the module docstring (text before the first
    ``def``/``class``) to avoid false positives from in-code string literals
    that happen to contain 'L2', 'L3', 'L4', 'Diagnostics', or 'Domain:'.
    Falls back to the full file if no module docstring is found.
    """
    docstring = _extract_module_docstring(text)
    scope = docstring if docstring is not None else text
    if "Diagnostics" not in scope:
        return False, "Missing Diagnostics section in module docstring"
    if "Domain:" not in scope:
        return False, "Missing Diagnostics domain in module docstring"
    if "L2" not in scope or "L3" not in scope or "L4" not in scope:
        return False, "Missing Diagnostics level definitions in module docstring"
    return True, ""
 
 
def check_dbg_usage(text: str, tree: ast.Module | None = None):
    """
    Validate that non-trivial modules call ``_dbg()`` for diagnostics.
 
    ``_dbg`` is the structured debug logger from ``oc_diagnostics``
    (``from oc_diagnostics import _dbg``).  Files shorter than 20 lines
    are considered trivial scaffolding and are exempt from this check.
 
    Uses AST parsing to detect actual ``_dbg()`` call nodes, avoiding
    false positives from comments or string literals.
    """
    if len(text.splitlines()) < 20:
        return True, ""
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is None:
        return True, ""
    for node in ast.walk(tree):
        if (isinstance(node, ast.Call)
                and isinstance(node.func, ast.Name)
                and node.func.id == "_dbg"):
            return True, ""
        if (isinstance(node, ast.Call)
                and isinstance(node.func, ast.Attribute)
                and node.func.attr == "_dbg"):
            return True, ""
    return False, "Missing _dbg usage"
 
 
def check_dbg_import(text: str, tree: ast.Module | None = None):
    """
    Verify that ``_dbg`` is imported from ``oc_diagnostics`` at module level.
 
    The canonical import is ``from oc_diagnostics import _dbg``.  Files shorter
    than 20 lines are exempt (same threshold as ``check_dbg_usage``).  Aliased
    imports (``import _dbg as ...``) are not accepted — the Option C spec
    requires the canonical form.
    """
    if len(text.splitlines()) < 20:
        return True, ""
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is None:
        return True, ""
    for node in ast.iter_child_nodes(tree):
        if (isinstance(node, ast.ImportFrom)
                and node.module == "oc_diagnostics"
                and any(alias.name == "_dbg" and alias.asname is None
                        for alias in node.names)):
            return True, ""
    return False, "Missing `from oc_diagnostics import _dbg`"
 
 
def _walk_function_body(func_node: ast.FunctionDef | ast.AsyncFunctionDef):
    """
    Yield AST nodes within a function body, stopping at nested function
    boundaries so that each function gets an independent check.
    """
    for node in ast.walk(func_node):
        if node is func_node:
            continue
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            # Don't descend into nested functions; they are checked separately
            continue
        yield node
 
 
def _direct_body_nodes(func_node):
    """
    Yield AST nodes that are directly in this function's body (not in
    nested function bodies).  Uses an iterative approach to avoid
    descending into nested FunctionDef/AsyncFunctionDef.
    """
    stack = list(func_node.body)
    while stack:
        node = stack.pop()
        yield node
        for child in ast.iter_child_nodes(node):
            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
                continue
            stack.append(child)
 
 
def find_func_pattern_violations(
    text: str,
    tree: ast.Module | None = None,
) -> list[tuple[str, int]]:
    """
    Return ``[(func_name, lineno), ...]`` for every function that calls
    ``_dbg()`` without a prior ``func = "..."`` assignment.
 
    Returns an empty list for trivial files (< 20 lines) or files with
    syntax errors.  This is the single source of truth for func-pattern
    detection — used by :func:`check_func_pattern` (linter pass/fail)
    and by :func:`oct.formatter.oct_format.fix_func_pattern` (auto-fix).
    """
    lines = text.splitlines()
    if len(lines) < 20:
        return []
 
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is None:
        return []
 
    violations: list[tuple[str, int]] = []
 
    func_nodes = [
        node for node in ast.walk(tree)
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
    ]
 
    for func_node in func_nodes:
        has_func_var = False
        has_dbg_call = False
 
        # Check for func = "..." in first 3 non-docstring statements
        non_doc_seen = 0
        for stmt in func_node.body:
            if (isinstance(stmt, ast.Expr)
                    and isinstance(stmt.value, ast.Constant)
                    and isinstance(stmt.value.value, str)):
                continue
            if (isinstance(stmt, ast.Assign)
                    and len(stmt.targets) == 1
                    and isinstance(stmt.targets[0], ast.Name)
                    and stmt.targets[0].id == "func"
                    and isinstance(stmt.value, ast.Constant)
                    and isinstance(stmt.value.value, str)):
                has_func_var = True
                break
            non_doc_seen += 1
            if non_doc_seen >= 3:
                break
 
        # Check for _dbg() anywhere in direct body (Name or Attribute form)
        for node in _direct_body_nodes(func_node):
            if isinstance(node, ast.Call):
                if (isinstance(node.func, ast.Name)
                        and node.func.id == "_dbg"):
                    has_dbg_call = True
                if (isinstance(node.func, ast.Attribute)
                        and node.func.attr == "_dbg"):
                    has_dbg_call = True
 
        if has_dbg_call and not has_func_var:
            violations.append((func_node.name, func_node.lineno))
 
    return violations
 
 
def check_func_pattern(text: str, tree: ast.Module | None = None):
    """
    Validate that every function body containing ``_dbg()`` first defines
    ``func = "function_name"``.
 
    Uses ``ast.parse()`` to build a syntax tree, then walks each function's
    body (stopping at nested function boundaries) to check for the pattern.
    Exempt trivial files (< 20 lines) — same threshold as check_dbg_usage.
 
    Delegates to :func:`find_func_pattern_violations` for the actual
    detection; this wrapper converts the result into a ``(bool, message)``
    pair for the linter pipeline.
    """
    lines = text.splitlines()
    if len(lines) < 20:
        return True, "trivial"
 
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is None:
        return True, "syntax error; skipped"
 
    violations = find_func_pattern_violations(text, tree=tree)
    if violations:
        names = ", ".join(f"{name}()" for name, _ in violations)
        return False, f'Missing `func = "..."` before `_dbg()` in: {names}'
    return True, ""
 
 
# OI-514: secret-scanning logic lives in :mod:`oct.tools.secret_scanner`.
# The symbols are re-exported below so any external callers that import
# them from ``oct.linter.oct_lint`` (historical location) keep working.
from oct.tools.secret_scanner import (  # noqa: E402  (re-export)
    _SECRET_NAME_PATTERNS,
    _is_string_like,
    _is_string_literal,
    _name_matches_secret,
    check_no_hardcoded_secrets,
)
 
 
def check_syntax_warnings(text: str, warnings_list: list[str] | None = None):
    """
    Check for Python syntax warnings (invalid escape sequences etc.).
 
    Python 3.12+ emits ``SyntaxWarning`` for invalid escape sequences in
    string literals.  These will become ``SyntaxError`` in a future Python
    version, so they should be surfaced as lint findings.
    """
    if warnings_list is None:
        _, warnings_list = safe_parse(text)
    if warnings_list:
        return False, f"{len(warnings_list)} syntax warning(s): {'; '.join(warnings_list)}"
    return True, ""
 
 
def check_type_hints(text: str, tree: ast.Module | None = None, compact_mode: bool = False):
    """
    Validate that public functions have type annotations on all parameters
    and a return annotation.
 
    Private functions (leading underscore) and dunder methods are always
    exempt — they are internal implementation details (OI-417). The
    ``compact_mode`` parameter is retained for API compatibility but no
    longer changes behaviour.
 
    Trivial files (< 20 lines) are exempt.
    """
    if len(text.splitlines()) < 20:
        return True, ""
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is None:
        return True, "syntax error; skipped"
 
    violations: list[str] = []
 
    for node in ast.walk(tree):
        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            continue
        # Skip dunder methods (always exempt)
        if node.name.startswith("__") and node.name.endswith("__"):
            continue
        # Private functions (single leading underscore) are exempt from type hint
        # requirements in all profiles — internal implementation details (OI-417).
        if node.name.startswith("_"):
            continue
 
        # Check parameters (skip 'self' and 'cls')
        missing_params = []
        for arg in node.args.args:
            if arg.arg in ("self", "cls"):
                continue
            if arg.annotation is None:
                missing_params.append(arg.arg)
 
        # Check return annotation
        missing_return = node.returns is None
 
        if missing_params or missing_return:
            parts = []
            if missing_params:
                parts.append(f"params: {', '.join(missing_params)}")
            if missing_return:
                parts.append("return type")
            violations.append(f"{node.name}() missing {'; '.join(parts)}")
 
    if violations:
        return False, f"Type hints: {'; '.join(violations[:5])}"
    return True, ""
 
 
# Keywords that mark a function/class/module as "security-sensitive" for
# the purposes of OI-403. A ``_dbg_assert`` call inside any such context is
# flagged because ``_dbg_assert`` is a no-op in production (AP-16) and must
# never be relied upon for safety invariants.
_SECURITY_SENSITIVE_KEYWORDS = frozenset({
    "auth", "authenticate", "authorize", "permission", "security",
    "validate", "verify", "credential", "login", "session", "sanitize",
    "encrypt", "decrypt", "password", "token",
})
 
 
def _is_security_sensitive_name(name: str) -> bool:
    lowered = name.lower()
    return any(kw in lowered for kw in _SECURITY_SENSITIVE_KEYWORDS)
 
 
def check_dbg_assert_safety(
    text: str, tree: ast.Module | None = None, filename: str = ""
) -> tuple[bool, str]:
    """
    Flag ``_dbg_assert`` calls made inside security-sensitive contexts.
 
    ``_dbg_assert`` is a diagnostic aid — in production mode it is a no-op.
    Per AP-16 it must never be used for safety invariants (authentication,
    authorization, input validation, crypto, etc.). This check walks the AST
    looking for calls named ``_dbg_assert`` (bare or attribute access) and
    verifies that none of the enclosing functions, classes, or the module's
    filename stem contain a security-sensitive keyword.
    """
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is None:
        return True, "syntax error; skipped"
 
    # Is the module itself security-sensitive by filename?
    module_sensitive = False
    if filename:
        stem = Path(filename).stem
        if _is_security_sensitive_name(stem):
            module_sensitive = True
 
    violations: list[str] = []
 
    def _walk(node: ast.AST, scopes: list[str]) -> None:
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
            new_scopes = scopes + [node.name]
            for child in ast.iter_child_nodes(node):
                _walk(child, new_scopes)
            return
 
        if isinstance(node, ast.Call):
            func = node.func
            call_name = ""
            if isinstance(func, ast.Name):
                call_name = func.id
            elif isinstance(func, ast.Attribute):
                call_name = func.attr
            if call_name == "_dbg_assert":
                sensitive_scope = None
                for scope in scopes:
                    if _is_security_sensitive_name(scope):
                        sensitive_scope = scope
                        break
                if sensitive_scope is None and module_sensitive:
                    sensitive_scope = f"module '{Path(filename).stem}'"
                if sensitive_scope is not None:
                    violations.append(
                        f"L{node.lineno}: _dbg_assert used in security-sensitive "
                        f"context '{sensitive_scope}' — use a hard assertion (AP-16)"
                    )
 
        for child in ast.iter_child_nodes(node):
            _walk(child, scopes)
 
    _walk(tree, [])
 
    if violations:
        return False, "; ".join(violations[:5])
    return True, ""
 
 
# ---- Inline waiver parsing ----
# OI-540: parse_inline_waivers() moved to oct.core.waivers (imported above).
 
 
_IMPORT_STMT_RE = re.compile(
    r'(?:^|\s)(?:import|from)\s+([a-zA-Z_][a-zA-Z0-9_]*)',
    re.MULTILINE,
)
 
 
def build_test_index(ctx: LinterContext) -> dict[str, set[str]]:
    """
    OI-510 / FS-516: one-shot scan of ``ctx.tests_dir`` producing two
    lookup sets so :func:`check_tests_exist` becomes O(1) per module
    instead of re-walking the tests tree for every file linted.
 
    The index is cached on :attr:`LinterContext.test_index` — subsequent
    calls return the cached value directly.
 
    Returns a dict with:
 
    * ``name_stems``     — stems ``<s>`` for which ``test_<s>.py`` exists.
    * ``imported_stems`` — module stems referenced in any test file by
      a whole-word ``import`` / ``from`` statement.
    """
    if ctx.test_index is not None:
        return ctx.test_index
 
    name_stems: set[str] = set()
    imported_stems: set[str] = set()
 
    if ctx.tests_dir.is_dir():
        for test_file in ctx.tests_dir.rglob("*.py"):
            stem = test_file.stem
            if stem.startswith("test_"):
                name_stems.add(stem[len("test_"):])
            try:
                text = test_file.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue
            for m in _IMPORT_STMT_RE.finditer(text):
                imported_stems.add(m.group(1))
 
    ctx.test_index = {
        "name_stems": name_stems,
        "imported_stems": imported_stems,
    }
    return ctx.test_index
 
 
def check_tests_exist(module_path: Path, ctx: LinterContext):
    """
    Validate that at least one test file references the module either by
    naming convention (``test_<module>.py``) or by an explicit import
    statement (``import <module>`` or ``from <module>``).
 
    Two-stage check, now O(1) per call: consults the index built once
    per :func:`run_linter` invocation by :func:`build_test_index`.
    """
    index = build_test_index(ctx)
    stem = module_path.stem
    return stem in index["name_stems"] or stem in index["imported_stems"]
 
 
# ---------------------------------------------------------------------
# Terminal color helpers
# ---------------------------------------------------------------------
 
from oct.core.terminal import CYAN, GREEN, RED, RESET
 
 
_MAX_LINT_LOG_FILES = 10
 
 
def _rotate_lint_logs(log_dir: Path, max_files: int = _MAX_LINT_LOG_FILES) -> None:
    """Remove old lint log files, keeping only the most recent max_files."""
    logs = sorted(log_dir.glob("oct_lint_output-*.txt"), key=lambda p: p.name)
    excess = len(logs) - max_files
    for old in logs[:excess]:
        try:
            old.unlink()
        except OSError:
            pass
 
 
def _lint_single_file(
    path: Path,
    ctx: LinterContext,
    active_rules: dict,
    fix_mode: bool,
    dry_run: bool = False,
) -> dict:
    """Lint one Python file and return a result dict with check outcomes.
 
    Thread-safe: logging uses ctx.log_lock internally.
    """
    text = read_file(path, ctx)
    rel = to_project_relative(path, ctx.project_root)
 
    log("", ctx)
    log(f"--- {rel} ---", ctx)
 
    # FS-510: check lint cache before running checks
    _file_hash: str | None = None
    _rules_hash: str | None = None
    if ctx.lint_cache is not None and not fix_mode:
        from oct.linter.lint_cache import content_hash, rules_hash
        _file_hash = content_hash(text)
        _rules_hash = rules_hash(active_rules)
        if not ctx.no_cache_read:
            cached = ctx.lint_cache.get(_file_hash, _rules_hash)
            if cached is not None:
                log("  (cached)", ctx)
                result = dict(cached.rule_results)
                result["json_detail"] = cached.json_detail
                result["fixed"] = False
                result["rel"] = str(rel)
                # FS-510 fix: recompute "compliant" — excluded from
                # cache storage, must be derived from per-check severity
                # in the cached json_detail (FS-C4: advisory failures
                # don't break compliance).
                from oct.linter.rule_registry import SEVERITY_BLOCKING as _SB
                _checks = (cached.json_detail or {}).get("checks", {})
                if _checks:
                    result["compliant"] = all(
                        c.get("pass", True)
                        for c in _checks.values()
                        if c.get("severity", _SB) == _SB
                    )
                else:
                    # Pre-FS-C4 cache entries have no severity field.
                    # Fall back to the legacy "all booleans must pass"
                    # rule so we don't suddenly flip results during the
                    # rollover window.
                    result["compliant"] = all(
                        v for k, v in result.items()
                        if isinstance(v, bool) and k != "fixed"
                    )
                return result
 
    # Parse AST once and share across all check functions
    tree, syntax_warnings_list = safe_parse(text)
 
    lines = text.splitlines()
    header_errors: list[str] = []
    doc_msg = diag_msg = dbg_msg = dbg_imp_msg = func_msg = secrets_msg = ""  # OCT-LINT: disable=no_hardcoded_secrets reason="Variable holds lint output, not a credential"
 
    compact_mode = active_rules.get("_compact_mode", False)
 
    # Parse inline waivers (# OCT-LINT: disable=<rule>)
    waivers = parse_inline_waivers(text)
    waived_rules: set[str] = {w["rule"] for w in waivers.values() if w["reason"] is not None}
    waiver_warnings: list[str] = []
    for lineno, w in waivers.items():
        if w["reason"] is None:
            waiver_warnings.append(
                f"Line {lineno}: waiver for '{w['rule']}' has no reason"
            )
 
    result: dict = {
        "header": False, "docstring": False, "diagnostics_profile": False,
        "dbg_usage": False, "dbg_import": False, "func_pattern": False,
        "syntax_warnings": False, "tests_exist": False, "type_hints": False,
        "no_hardcoded_secrets": False,
        "fixed": False, "rel": str(rel),
        "waivers": [{"line": ln, **w} for ln, w in waivers.items()],
    }
 
    # Helper: check if a rule is active (enabled in profile AND not waived)
    def _rule_active(rule: str) -> bool:
        return active_rules.get(rule, True) and rule not in waived_rules
 
    if _rule_active("header"):
        ok_header, header_errors = validate_header_block(lines, path, ctx)
        if fix_mode and not ok_header:
            if dry_run:
                result["fixed"] = True
                result["header"] = False
                report(False, f"Would fix header: {', '.join(header_errors)}", fix_mode=True, ctx=ctx)
                preview = preview_header_fix(path, ctx)
                boundary = _header_boundary(lines, path, ctx)
                log("  Current header lines:", ctx)
                if boundary == 0:
                    log("    (none)", ctx)
                else:
                    for i, hl in enumerate(lines[:boundary], 1):
                        log(f"    {i}: {hl}", ctx)
                log("  Corrected header:", ctx)
                for i, hl in enumerate(preview.splitlines() + [""], 1):
                    log(f"    {i}: {hl}", ctx)
            else:
                fix_header_block(path, text, ctx)
                result["fixed"] = True
                result["header"] = True
                report(False, f"Header block corrected: {', '.join(header_errors)}", fix_mode=True, ctx=ctx)
        else:
            result["header"] = ok_header
            report(ok_header, f"Header block: {', '.join(header_errors) if header_errors else 'OK'}", ctx=ctx)
    else:
        ok_header = True
        result["header"] = True
 
    if _rule_active("docstring"):
        ok_doc, doc_msg = check_docstring(text)
        result["docstring"] = ok_doc
        report(ok_doc, f"Docstring structure: {doc_msg or 'OK'}", ctx=ctx)
    else:
        ok_doc = True
        result["docstring"] = True
 
    if _rule_active("dependencies_section"):
        ok_deps, deps_msg = check_dependencies_section(text)
        result["dependencies_section"] = ok_deps
        report(ok_deps, f"Dependencies section: {deps_msg or 'OK'}", ctx=ctx)
    else:
        ok_deps = True
        result["dependencies_section"] = True
 
    if _rule_active("diagnostics_profile"):
        ok_diag, diag_msg = check_diagnostics_profile(text)
        result["diagnostics_profile"] = ok_diag
        report(ok_diag, f"Diagnostics profile: {diag_msg or 'OK'}", ctx=ctx)
    else:
        ok_diag = True
        result["diagnostics_profile"] = True
 
    if _rule_active("dbg_usage"):
        ok_dbg, dbg_msg = check_dbg_usage(text, tree=tree)
        result["dbg_usage"] = ok_dbg
        report(ok_dbg, f"_dbg usage: {dbg_msg or 'OK'}", ctx=ctx)
    else:
        ok_dbg = True
        result["dbg_usage"] = True
 
    if _rule_active("dbg_import"):
        ok_dbg_imp, dbg_imp_msg = check_dbg_import(text, tree=tree)
        result["dbg_import"] = ok_dbg_imp
        report(ok_dbg_imp, f"_dbg import: {dbg_imp_msg or 'OK'}", ctx=ctx)
    else:
        ok_dbg_imp = True
        result["dbg_import"] = True
 
    if _rule_active("func_pattern"):
        ok_func, func_msg = check_func_pattern(text, tree=tree)
        result["func_pattern"] = ok_func
        report(ok_func, f"func pattern: {func_msg or 'OK'}", ctx=ctx)
    else:
        ok_func = True
        result["func_pattern"] = True
 
    ok_syntax, syntax_msg = check_syntax_warnings(text, warnings_list=syntax_warnings_list)
    result["syntax_warnings"] = ok_syntax
    report(ok_syntax, f"Syntax warnings: {syntax_msg or 'OK'}", ctx=ctx)
 
    if _rule_active("type_hints"):
        ok_hints, hints_msg = check_type_hints(text, tree=tree, compact_mode=compact_mode)
        result["type_hints"] = ok_hints
        report(ok_hints, f"Type hints: {hints_msg or 'OK'}", ctx=ctx)
    else:
        ok_hints = True
        result["type_hints"] = True
 
    if _rule_active("no_hardcoded_secrets"):
        # OI-540: path-based entropy exclusions. Both ``test_directory``
        # (test fixtures) and ``module_self_doc`` (source files dominated
        # by help-text/templates/scaffold strings) honour the same
        # ``exempt_entropy_only`` semantics.
        file_entropy = ctx.code_entropy_threshold
        for excl in ctx.entropy_exclusions:
            if excl.get("context") in ("test_directory", "module_self_doc"):
                pattern = excl.get("path_pattern", "")
                restrictions = excl.get("restrictions", {})
                if pattern and rel.replace("\\", "/").startswith(pattern):
                    if restrictions.get("exempt_entropy_only"):
                        file_entropy = 0
                    break
        ok_secrets, secrets_msg = check_no_hardcoded_secrets(
            text, tree=tree, mode=ctx.secret_match_mode,
            code_entropy_threshold=file_entropy,
            docstring_entropy_threshold=ctx.docstring_entropy_threshold,
            comment_entropy_threshold=ctx.comment_entropy_threshold,
            excluded_field_patterns=ctx.excluded_field_patterns,
        )
        result["no_hardcoded_secrets"] = ok_secrets
        report(ok_secrets, f"Hardcoded secrets: {secrets_msg or 'OK'}", ctx=ctx)
    else:
        ok_secrets = True
        result["no_hardcoded_secrets"] = True
 
    if _rule_active("dbg_assert_safety"):
        ok_dbg_assert, dbg_assert_msg = check_dbg_assert_safety(
            text, tree=tree, filename=str(path)
        )
        result["dbg_assert_safety"] = ok_dbg_assert
        report(ok_dbg_assert, f"dbg_assert safety: {dbg_assert_msg or 'OK'}", ctx=ctx)
    else:
        ok_dbg_assert = True
        result["dbg_assert_safety"] = True
 
    if _rule_active("tests_exist"):
        ok_test = check_tests_exist(path, ctx)
        result["tests_exist"] = ok_test
        report(ok_test, "Regression test exists", ctx=ctx)
    else:
        ok_test = True
        result["tests_exist"] = True
 
    # Log waiver warnings
    for ww in waiver_warnings:
        report(False, f"Waiver warning: {ww}", ctx=ctx)
 
    # FS-C4: per-rule severity lookup. A failed rule classified as
    # ``advisory`` is reported but does NOT contribute to ``compliant``.
    from oct.linter.rule_registry import get_severity, SEVERITY_BLOCKING
    _check_results = {
        "header": ok_header or fix_mode,
        "docstring": ok_doc,
        "dependencies_section": result.get("dependencies_section", True),
        "diagnostics_profile": ok_diag,
        "dbg_usage": ok_dbg,
        "dbg_import": ok_dbg_imp,
        "func_pattern": ok_func,
        "syntax_warnings": ok_syntax,
        "type_hints": ok_hints,
        "no_hardcoded_secrets": ok_secrets,
        "dbg_assert_safety": ok_dbg_assert,
        "tests_exist": ok_test,
    }
    _check_severities = {
        rule: get_severity(rule, ctx.profile_name)
        for rule in _check_results
    }
    # ``compliant`` ignores advisory failures so AI agents and CI can
    # surface advisory items without flipping the build red.
    result["compliant"] = all(
        passed
        for rule, passed in _check_results.items()
        if _check_severities[rule] == SEVERITY_BLOCKING
    )
 
    def _check_block(passed: bool, message: str, rule: str) -> dict:
        return {
            "pass": passed,
            "message": message,
            "severity": _check_severities[rule],
        }
 
    # JSON-mode detail block
    result["json_detail"] = {
        "path": rel,
        "checks": {
            "header": _check_block(
                ok_header or (fix_mode and not ok_header),
                ", ".join(header_errors) if header_errors else "OK",
                "header",
            ),
            "docstring": _check_block(ok_doc, doc_msg or "OK", "docstring"),
            "dependencies_section": _check_block(
                result.get("dependencies_section", True),
                "OK" if result.get("dependencies_section", True) else "Missing or malformed Dependencies section",
                "dependencies_section",
            ),
            "diagnostics_profile": _check_block(ok_diag, diag_msg or "OK", "diagnostics_profile"),
            "dbg_usage": _check_block(ok_dbg, dbg_msg or "OK", "dbg_usage"),
            "dbg_import": _check_block(ok_dbg_imp, dbg_imp_msg or "OK", "dbg_import"),
            "func_pattern": _check_block(ok_func, func_msg or "OK", "func_pattern"),
            "syntax_warnings": _check_block(ok_syntax, syntax_msg or "OK", "syntax_warnings"),
            "type_hints": _check_block(ok_hints, hints_msg if not ok_hints else "OK", "type_hints"),
            "no_hardcoded_secrets": _check_block(ok_secrets, secrets_msg if not ok_secrets else "OK", "no_hardcoded_secrets"),
            "dbg_assert_safety": _check_block(ok_dbg_assert, dbg_assert_msg if not ok_dbg_assert else "OK", "dbg_assert_safety"),
            "tests_exist": _check_block(ok_test, "OK" if ok_test else "No test found", "tests_exist"),
        },
        "compliant": result["compliant"],
        "waivers": result["waivers"],
    }
 
    # FS-510: store result in cache
    if ctx.lint_cache is not None and not fix_mode and _file_hash and _rules_hash:
        from oct.linter.lint_cache import LintCacheEntry
        from datetime import datetime as _dt
        from oct import __version__ as _ver
        cache_entry = LintCacheEntry(
            content_hash=_file_hash,
            rule_results={
                k: v for k, v in result.items()
                if k not in ("fixed", "rel", "json_detail", "waivers", "compliant")
            },
            json_detail=result["json_detail"],
            oct_version=_ver,
            timestamp=_dt.now().isoformat(),
        )
        ctx.lint_cache.put(_file_hash, _rules_hash, cache_entry)
 
    return result
 
 
# ---------------------------------------------------------------------
# Main linter entry point
# ---------------------------------------------------------------------
 
 
def run_linter(project_root: Path, argv: list[str] | None = None) -> int:
    """
    Run the Option C linter on the given project root.
 
    Parameters
    ----------
    project_root:
        The detected Option C project root directory.
    argv:
        Optional list of command-line arguments (e.g. ["--fix-headers"]).
        If None, ``argparse`` will use ``sys.argv``.
 
    Returns
    -------
    int
        Exit code: 0 if all checks passed, 1 if any failures detected.
    """
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument("--help", action="store_true")
    parser.add_argument("--fix-headers", action="store_true")
    parser.add_argument("--dry-run", action="store_true",
                        help="Preview changes without modifying files")
    parser.add_argument(
        "--json",
        action="store_true",
        help="Emit machine-readable JSON to stdout instead of colorized terminal output",
    )
    parser.add_argument(
        "--jobs", "-j",
        type=int,
        default=1,
        help="Parallel workers for file processing (default: 1)",
    )
    parser.add_argument(
        "--changed", action="store_true",
        help="Lint only git-modified Python files",
    )
    parser.add_argument(
        "--profile",
        type=str,
        default=None,
        help="Lint profile: proto, compact, strict (overrides .octrc.json)",
    )
    parser.add_argument(
        "--secret-match",
        type=str,
        choices=("substring", "word"),
        default="substring",
        help=(
            "Secret-name matcher (OI-529): 'substring' (default, legacy) or "
            "'word' (segment-aware; avoids false positives like 'compass')."
        ),
    )
    parser.add_argument(
        "--code-entropy-threshold",
        type=float,
        default=None,
        dest="entropy_threshold",
        help="Shannon entropy threshold for code string literals (default: 4.5)",
    )
    parser.add_argument(
        "--no-entropy",
        action="store_true",
        help="Disable entropy-based secret detection",
    )
    parser.add_argument(
        "--no-cache",
        action="store_true",
        help="Bypass lint cache reads (still writes updated cache)",
    )
    parser.add_argument(
        "--baseline",
        action="store_true",
        help="Save current violations as the baseline",
    )
    parser.add_argument(
        "--against-baseline",
        action="store_true",
        help="Report only new/resolved violations vs saved baseline",
    )
    parser.add_argument(
        "--explain",
        type=str,
        default=None,
        help="Show documentation for a lint rule (rationale, pattern, spec ref)",
    )
    parser.add_argument(
        "targets", nargs="*", default=None,
        help="Files or directories to lint (default: entire project)",
    )
    args = parser.parse_args(argv)
 
    if args.help:
        print("Option C Linter")
        print("Usage:")
        print("  oct lint [--fix-headers] [--dry-run] [--json] [--jobs N] [--changed] [--profile P] [--secret-match MODE] [PATH ...]")
        print("  oct lint --explain RULE [--json]")
        print("")
        print("Arguments:")
        print("  --help                  Show this help message")
        print("  --fix-headers           Automatically fix shebang, encoding, and path headers")
        print("  --dry-run               Preview changes without modifying files")
        print("  --json                  Emit machine-readable JSON to stdout")
        print("  --jobs N, -j N          Parallel workers for file processing (default: 1)")
        print("  --changed               Lint only git-modified Python files")
        print("  --profile P             Lint profile: proto, compact, strict (overrides .octrc.json)")
        print("  --secret-match MODE     Secret-name matcher: substring (default) | word (segment-aware)")
        print("  --code-entropy-threshold N  Shannon entropy threshold for code strings (default: 4.5)")
        print("  --no-entropy            Disable entropy-based secret detection")
        print("  --no-cache              Bypass lint cache reads (still writes)")
        print("  --baseline              Save current violations as the baseline")
        print("  --against-baseline      Report only new/resolved vs saved baseline")
        print("  --explain RULE          Show rule documentation (rationale, pattern, spec ref)")
        print("  PATH ...                Files or directories to lint (default: entire project)")
        return 0
 
    # ---- FS-509: --explain handler ----
    if args.explain:
        from oct.linter.rule_registry import get_rule_info, list_rules
        info = get_rule_info(args.explain)
        if info is None:
            available = ", ".join(r.name for r in list_rules())
            print(f"Error: unknown rule '{args.explain}'", file=sys.stderr)
            print(f"Available rules: {available}", file=sys.stderr)
            return 1
        if args.json:
            from dataclasses import asdict
            json.dump(asdict(info), sys.stdout, indent=2)
            print()
        else:
            print(f"Rule: {info.name}")
            print(f"Label: {info.label}")
            print(f"Fixable: {'yes' if info.fixable else 'no'}")
            print(f"Profiles: {', '.join(info.profiles)}")
            print(f"Spec: {info.spec_reference}")
            print("")
            print("Rationale:")
            print(f"  {info.rationale}")
            print("")
            print("Correct pattern:")
            for line in info.correct_pattern.splitlines():
                print(f"  {line}")
            print("")
            print("Common mistake:")
            print(f"  {info.common_mistake}")
        return 0
 
    # FS-508: --baseline and --against-baseline are mutually exclusive
    if args.baseline and args.against_baseline:
        print("Error: --baseline and --against-baseline are mutually exclusive.",
              file=sys.stderr)
        return 1
 
    # Version handshake with oc_diagnostics (warning-only, always stderr)
    from oct.core.compat import check_oc_diagnostics_compat
    compat_msg = check_oc_diagnostics_compat()
    if compat_msg:
        print(compat_msg, file=sys.stderr)
 
    root = project_root.resolve()
    _oc_diag = root / "oc_diagnostics"
    ctx = LinterContext(
        project_root=root,
        project_name=root.name,
        diagnostics_dir=_oc_diag if _oc_diag.exists() else root / "diagnostics",
        tests_dir=root / "tests",
        docs_dir=root / "docs",
        secret_match_mode=args.secret_match,
    )
 
    if ctx.diagnostics_dir.name == "diagnostics":
        print(
            "Warning: 'diagnostics/' is deprecated and will be removed in v1.0.0. "
            "Rename to 'oc_diagnostics/'.",
            file=sys.stderr,
        )
 
    # OI-510 / FS-516: build the test discovery index once, up front — the
    # per-file tests_exist rule then performs O(1) set lookups instead of
    # re-walking tests/ for every linted file.
    build_test_index(ctx)
 
    # ---- Per-project overrides from .octrc.json ----
    # OI-519: routed through central oct.core.octrc loader; strict mode
    # still escalates JSON/schema errors to exit 2.
    from oct.core.octrc import load_octrc
    active_exclude_dirs = set(EXCLUDE_DIRS)
    active_wildcard_exclude = list(WILDCARD_EXCLUDE_DIRS)
    active_rules = dict(_DEFAULT_RULES)
    octrc, octrc_errors = load_octrc(root)
    if octrc_errors:
        msg = "; ".join(octrc_errors)
        if _strict_config_requested():
            print(f"Error: {msg}", file=sys.stderr)
            raise SystemExit(2)
        print(f"Warning: {msg}; using defaults.", file=sys.stderr)
 
    if octrc:
            # OI-411: validate schema and enforce in strict mode
            schema_errors = _validate_octrc_schema(octrc)
            if schema_errors:
                msg = f".octrc.json schema errors: {'; '.join(schema_errors)}"
                if _strict_config_requested():
                    print(f"Error: {msg}", file=sys.stderr)
                    raise SystemExit(2)
                print(f"Warning: {msg}", file=sys.stderr)
 
            linter_cfg = octrc.get("linter", {})
            if not isinstance(linter_cfg, dict):
                linter_cfg = {}
            for key in ("exclude_dirs_add", "exclude_dirs_remove", "wildcard_exclude_add"):
                val = linter_cfg.get(key)
                if val is not None and not isinstance(val, list):
                    linter_cfg[key] = []
            if not isinstance(linter_cfg.get("profile", "default"), str):
                linter_cfg["profile"] = "default"
            if linter_cfg.get("rules") is not None and not isinstance(linter_cfg["rules"], dict):
                linter_cfg["rules"] = {}
            for d in linter_cfg.get("exclude_dirs_add", []):
                if isinstance(d, str):
                    active_exclude_dirs.add(d)
            for d in linter_cfg.get("exclude_dirs_remove", []):
                if isinstance(d, str):
                    active_exclude_dirs.discard(d)
            for d in linter_cfg.get("wildcard_exclude_add", []):
                if isinstance(d, str) and d not in active_wildcard_exclude:
                    active_wildcard_exclude.append(d)
            # Rule profile and per-rule overrides
            profile_name = linter_cfg.get("profile", "default")
            active_rules = dict(_PROFILES.get(profile_name, _DEFAULT_RULES))
            rule_overrides = linter_cfg.get("rules", {}) or {}
            active_rules.update({k: v for k, v in rule_overrides.items() if isinstance(v, bool)})
            ctx.profile_name = profile_name  # FS-C4: route profile to severity lookup
 
            # FS-507: read entropy thresholds from octrc
            scanner_cfg = octrc.get("secret_scanner", {})
            if isinstance(scanner_cfg, dict):
                octrc_threshold = scanner_cfg.get("code_entropy_threshold")
                if isinstance(octrc_threshold, (int, float)) and not isinstance(octrc_threshold, bool):
                    ctx.code_entropy_threshold = float(octrc_threshold)
                for key in ("docstring_entropy_threshold", "comment_entropy_threshold"):
                    val = scanner_cfg.get(key)
                    if isinstance(val, (int, float)) and not isinstance(val, bool):
                        setattr(ctx, key, float(val))
 
                # OI-540: load entropy exclusions.
                exclusions = scanner_cfg.get("entropy_exclusions", [])
                if isinstance(exclusions, list):
                    ctx.entropy_exclusions = exclusions
                    ctx.excluded_field_patterns = [
                        e["field_name_pattern"] for e in exclusions
                        if e.get("context") == "namedtuple_field"
                        and isinstance(e.get("field_name_pattern"), str)
                    ]
 
    # ---- CLI --profile flag overrides .octrc.json ----
    if args.profile:
        cli_profile = args.profile.lower()
        if cli_profile in _PROFILES:
            active_rules = dict(_PROFILES[cli_profile])
            ctx.profile_name = cli_profile  # FS-C4: route profile to severity lookup
        else:
            print(
                f"Warning: unknown profile '{args.profile}'; "
                f"valid: {', '.join(p for p in _PROFILES if not p.startswith('_'))}",
                file=sys.stderr,
            )
 
    # ---- FS-507: CLI entropy flags override octrc ----
    if args.no_entropy:
        ctx.code_entropy_threshold = 0.0
    elif args.entropy_threshold is not None:
        ctx.code_entropy_threshold = args.entropy_threshold
 
    # ---- FS-510: initialise lint cache ----
    from oct.core.option_c_dir import option_c_dir
    from oct import __version__
    cache_dir = option_c_dir(root) / "cache"
    if not args.fix_headers:
        from oct.linter.lint_cache import LintCache
        ctx.lint_cache = LintCache(cache_dir / "lint-cache.json", __version__)
        ctx.no_cache_read = args.no_cache
 
    # ---- Open log file (non-fatal if unwritable) ----
    try:
        log_dir = root / "logs"
        log_dir.mkdir(exist_ok=True)
        _rotate_lint_logs(log_dir)
        timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
        log_file = log_dir / f"oct_lint_output-{timestamp}.txt"
        ctx.log_handle = log_file.open("w", encoding="utf-8")
        ctx.log_path = log_file
    except OSError as exc:
        print(f"Warning: Could not open lint log file: {exc}", file=sys.stderr)
        ctx.log_handle = None
 
    fix_mode = args.fix_headers
    dry_run = args.dry_run
    json_mode = args.json
 
    if fix_mode and dry_run and not json_mode:
        print("Dry-run mode: showing what --fix-headers would change. "
              "Fix details will be written to the log file.",
              file=sys.stderr)
 
    if not json_mode:
        print_header("Option C Linter — Project Scan", ctx)
    log(f"Project root: {ctx.project_root}", ctx)
    log(f"Project name: {ctx.project_name}", ctx)
 
    # Project-level requirements
    required_docs = [
        ctx.docs_dir / "ARCHITECTURE.md",
        ctx.tests_dir / "run_tests.py",
        ctx.tests_dir / "Tests_README.md",
        ctx.diagnostics_dir / "debug_config.json",
    ]
 
    if not json_mode:
        print_header("Project-Level Requirements", ctx)
    for req in required_docs:
        report(req.exists(), f"Required file: {req}", fix_mode=False, ctx=ctx)
 
    # Module-level checks
    if not json_mode:
        print_header("Module-Level Checks", ctx)
 
    # Force sequential when fixing (parallel writes are unsafe)
    jobs = max(1, args.jobs)
    if fix_mode and jobs > 1:
        jobs = 1
        if not json_mode:
            print("Note: --jobs forced to 1 when --fix-headers is active.", file=sys.stderr)
 
    if args.changed:
        if args.targets:
            if not json_mode:
                print("Note: --changed overrides explicit PATH targets.", file=sys.stderr)
        python_files = _git_changed_files(ctx.project_root)
        # Apply exclusion filters
        python_files = [
            p for p in python_files
            if p.is_file() and not any(
                is_excluded_dir(Path(part), active_exclude_dirs, active_wildcard_exclude)
                for part in p.relative_to(ctx.project_root).parts
            )
        ]
        if not python_files:
            if not json_mode:
                print("No modified Python files found.", file=sys.stderr)
            return 0
    elif args.targets:
        python_files = []
        for t in args.targets:
            p = Path(t).resolve()
            if p.is_file() and p.suffix == ".py":
                python_files.append(p)
            elif p.is_dir():
                python_files.extend(
                    find_python_files(p, active_exclude_dirs, active_wildcard_exclude)
                )
            else:
                print(f"Warning: Not a Python file or directory: {t}", file=sys.stderr)
        python_files = list(dict.fromkeys(python_files))
        if not python_files:
            print("No matching Python files found.", file=sys.stderr)
            return 0
    else:
        python_files = list(find_python_files(ctx.project_root, active_exclude_dirs, active_wildcard_exclude))
    total_files = len(python_files)
 
    # Dispatch per-file linting (sequential or parallel)
    if jobs <= 1:
        results = [_lint_single_file(p, ctx, active_rules, fix_mode, dry_run) for p in python_files]
    else:
        with concurrent.futures.ThreadPoolExecutor(max_workers=jobs) as pool:
            futures = [pool.submit(_lint_single_file, p, ctx, active_rules, fix_mode, dry_run) for p in python_files]
            results = [f.result() for f in futures]
 
    # Aggregate counters from per-file results
    pass_header = sum(1 for r in results if r["header"])
    pass_docstring = sum(1 for r in results if r["docstring"])
    pass_diag = sum(1 for r in results if r["diagnostics_profile"])
    pass_dbg = sum(1 for r in results if r["dbg_usage"])
    pass_dbg_import = sum(1 for r in results if r["dbg_import"])
    pass_func = sum(1 for r in results if r["func_pattern"])
    pass_syntax = sum(1 for r in results if r["syntax_warnings"])
    pass_hints = sum(1 for r in results if r["type_hints"])
    pass_tests = sum(1 for r in results if r["tests_exist"])
    fully_compliant = sum(1 for r in results if r["compliant"])
    fixed_files = sum(1 for r in results if r["fixed"])
 
    file_results: list[dict] = []
    if json_mode:
        file_results = [r["json_detail"] for r in results]
 
    if not json_mode:
        print_header("Final Result", ctx)
    if fully_compliant == total_files:
        log("All checks passed. Project conforms to Option C.", ctx)
    else:
        log("Some checks failed. See above for details.", ctx)
 
    if not json_mode:
        print_header("Summary", ctx)
 
    def pct(n: int) -> str:
        return f"{(n / total_files * 100):.1f}%" if total_files else "0%"
 
    log(f"Number of files checked:\t{total_files}", ctx)
    log(f"[Header block]:\t\t{pass_header} PASS ({pct(pass_header)})", ctx)
    log(f"[Docstring structure]:\t\t{pass_docstring} PASS ({pct(pass_docstring)})", ctx)
    log(f"[Diagnostics profile]:\t\t{pass_diag} PASS ({pct(pass_diag)})", ctx)
    log(f"[_dbg usage]:\t\t\t{pass_dbg} PASS ({pct(pass_dbg)})", ctx)
    log(f"[_dbg import]:\t\t\t{pass_dbg_import} PASS ({pct(pass_dbg_import)})", ctx)
    log(f"[func pattern]:\t\t\t{pass_func} PASS ({pct(pass_func)})", ctx)
    log(f"[Syntax warnings]:\t\t{pass_syntax} PASS ({pct(pass_syntax)})", ctx)
    log(f"[Type hints]:\t\t\t{pass_hints} PASS ({pct(pass_hints)})", ctx)
    log(f"[Regression test exists]:\t{pass_tests} PASS ({pct(pass_tests)})", ctx)
    log(f"[Compliant files]:\t\t{fully_compliant} PASS ({pct(fully_compliant)})", ctx)
 
    if fix_mode:
        label = "Would fix" if dry_run else "Files fixed"
        log(f"[{label}]:\t\t{fixed_files}", ctx)
 
    if ctx.log_handle is not None:
        ctx.log_handle.close()
        ctx.log_handle = None
 
    # FS-510: save lint cache
    if ctx.lint_cache is not None:
        try:
            ctx.lint_cache.save()
        except OSError:
            pass
 
    # FS-508: baseline handling
    baseline_info: dict | None = None
    if args.baseline:
        from oct.linter.lint_baseline import save_baseline
        baseline_path = cache_dir / "lint-baseline.json"
        profile_name = args.profile or "strict"
        count = save_baseline(results, baseline_path, profile_name)
        baseline_info = {"action": "saved", "count": count, "path": str(baseline_path)}
        if not json_mode:
            print(f"\nBaseline saved: {count} violation(s) -> {baseline_path}",
                  file=sys.stderr)
 
    if args.against_baseline:
        from oct.linter.lint_baseline import load_baseline, diff_against_baseline
        baseline_path = cache_dir / "lint-baseline.json"
        baseline = load_baseline(baseline_path)
        if baseline is None:
            print("Error: no baseline found. Run 'oct lint --baseline' first.",
                  file=sys.stderr)
            return 1
        new_violations, resolved = diff_against_baseline(results, baseline)
        baseline_info = {
            "action": "compared",
            "new_violations": [{"path": v[0], "rule": v[1], "message": v[2]} for v in new_violations],
            "resolved_violations": [{"path": v[0], "rule": v[1], "message": v[2]} for v in resolved],
            "new_count": len(new_violations),
            "resolved_count": len(resolved),
            "baselined_count": len(baseline.entries),
        }
        if not json_mode:
            if new_violations:
                print(f"\n{RED}New violations ({len(new_violations)}):{RESET}", file=sys.stderr)
                for path_str, rule, msg in new_violations:
                    print(f"  {path_str}: [{rule}] {msg}", file=sys.stderr)
            if resolved:
                print(f"\n{GREEN}Resolved ({len(resolved)}):{RESET}", file=sys.stderr)
                for path_str, rule, msg in resolved:
                    print(f"  {path_str}: [{rule}] {msg}", file=sys.stderr)
            if not new_violations:
                print(f"\n{GREEN}No new violations vs baseline.{RESET}", file=sys.stderr)
 
    # JSON output (stdout — separate from the log file)
    if json_mode:
        output = {
            "project": ctx.project_name,
            "oct_version": __version__,
            "timestamp": datetime.now().isoformat(),
            "summary": {
                "total_files": total_files,
                "fully_compliant": fully_compliant,
                "pass_header": pass_header,
                "pass_docstring": pass_docstring,
                "pass_diagnostics_profile": pass_diag,
                "pass_dbg": pass_dbg,
                "pass_dbg_import": pass_dbg_import,
                "pass_func": pass_func,
                "pass_syntax": pass_syntax,
                "pass_type_hints": pass_hints,
                "pass_tests": pass_tests,
            },
            "files": file_results,
        }
        if baseline_info is not None:
            output["baseline"] = baseline_info
        json.dump(output, sys.stdout, indent=2)
        print()  # trailing newline after JSON block
        if args.against_baseline and baseline_info:
            return 1 if baseline_info.get("new_count", 0) > 0 else 0
        return 0 if fully_compliant == total_files else 1
 
    # Terminal summary (colorized)
    print(f"{CYAN}Option C Linter Summary{RESET}")
    print(f"Files checked: {total_files}")
 
    def color(n: int) -> str:
        return GREEN if n == total_files else RED
 
    print(f"[Header block]:            {color(pass_header)}{pass_header}{RESET} PASS ({pct(pass_header)})")
    print(f"[Docstring structure]:     {color(pass_docstring)}{pass_docstring}{RESET} PASS ({pct(pass_docstring)})")
    print(f"[Diagnostics profile]:     {color(pass_diag)}{pass_diag}{RESET} PASS ({pct(pass_diag)})")
    print(f"[_dbg usage]:              {color(pass_dbg)}{pass_dbg}{RESET} PASS ({pct(pass_dbg)})")
    print(f"[_dbg import]:             {color(pass_dbg_import)}{pass_dbg_import}{RESET} PASS ({pct(pass_dbg_import)})")
    print(f"[func pattern]:            {color(pass_func)}{pass_func}{RESET} PASS ({pct(pass_func)})")
    print(f"[Syntax warnings]:         {color(pass_syntax)}{pass_syntax}{RESET} PASS ({pct(pass_syntax)})")
    print(f"[Type hints]:              {color(pass_hints)}{pass_hints}{RESET} PASS ({pct(pass_hints)})")
    print(f"[Regression test exists]:  {color(pass_tests)}{pass_tests}{RESET} PASS ({pct(pass_tests)})")
    print(f"[Compliant files]:         {color(fully_compliant)}{fully_compliant}{RESET} PASS ({pct(fully_compliant)})")
 
    if fix_mode:
        label = "Would fix" if dry_run else "Files fixed"
        print(f"[{label}]:             {GREEN}{fixed_files}{RESET}")
        if dry_run and fixed_files > 0 and ctx.log_path:
            print(f"\nDry-run fix details written to: {ctx.log_path}")
 
    if args.against_baseline and baseline_info:
        return 1 if baseline_info.get("new_count", 0) > 0 else 0
    return 0 if fully_compliant == total_files else 1
 
 
def main() -> None:
    """
    Standalone entry point when running this module directly.
    """
    raise SystemExit(run_linter(Path.cwd(), None))
 
 
if __name__ == "__main__":
    main()