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)
- oct.core.diagnostics (_dbg structured logger)
- oct.core.option_c_dir (resolve_debug_config, resolve_octrc, option_c_dir - config and cache locations)
- oct.core.terminal (CYAN, GREEN, RED, RESET - terminal summary colours)
- oct.tools.secret_scanner (check_no_hardcoded_secrets and its helpers - the secrets rule, re-exported)
- oct (lazy; __version__ - stamps the lint cache)
- oct.core.compat (lazy; check_oc_diagnostics_compat - the version handshake with oc_diagnostics)
- oct.core.git (lazy; git_changed_files, GitError - the file list for --changed)
- oct.core.octrc (lazy; load_octrc - per-project overrides)
- oct.core.workspace (lazy; find_workspace_root, load_workspace, assign_to_subproject - the lens for each file)
- oct.deps.dependency_check (lazy; check_dependencies_match - the dependencies_match rule)
- oct.linter.lint_baseline (lazy; save_baseline, load_baseline, diff_against_baseline - the baseline flags)
- oct.linter.lint_cache (lazy; LintCache, current_linter_identity, content_hash, rules_hash - the incremental lint cache)
- oct.linter.prompt_invariant_rules (lazy; check_prompt_invariants - the prompt_invariants rule)
- oct.linter.rule_registry (lazy; get_severity, get_rule_info, list_rules - rule severities and --explain)
"""
 
import argparse
import ast
import concurrent.futures
import json
import re
import shutil
import subprocess
import threading
import sys
from collections.abc import Iterator
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Any, NamedTuple, TYPE_CHECKING
 
if TYPE_CHECKING:  # pragma: no cover - typing only
    from oct.core.workspace import Workspace
 
# ---------------------------------------------------------------------
# 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.option_c_dir import resolve_debug_config, resolve_octrc
from oct.core.paths import to_project_relative
from oct.core.waivers import LINE_SCOPED_RULES, apply_waivers, parse_inline_waivers
 
# ---------------------------------------------------------------------
# Lint rule profiles
# ---------------------------------------------------------------------
 
_DEFAULT_RULES = {
    # F21 / Plan 170: unconditionally active at every profile - never
    # gated behind `_rule_active()` in `_lint_single_file` (see below),
    # so no profile or octrc rule override can waive an unparseable file
    # into "compliant". Present here only so it registers with
    # rule_registry's completeness tests and `--explain syntax_error`.
    "syntax_error": True,
    "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,
    # 2026-09-28 (operator rulings): ADVISORY check that the Dependencies
    # section matches what the module imports - every first- and third-party
    # import declared, lazy ones marked, nothing stale. Runs at EVERY
    # profile (it never blocks) and exempts test modules itself.
    "dependencies_match": True,
    # Plan 151 T6: OC Chat prompt invariants (Plan 140), lifted from the
    # OC Chat pytest wrapper into the strict profile. Scoped to the OC Chat
    # runtime source tree - a no-op for every other project.
    "prompt_invariants": True,
    # Plan 193: ADVISORY burn-down counter for secret waivers still
    # relying on pre-193 whole-file semantics. Never blocks; reaching
    # zero tree-wide is the precondition for deleting the legacy branch.
    "legacy_file_scoped_waiver": 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,
        "dependencies_match": True,
        # Plan 151 T6: prompt invariants are a strict-only rule. _rule_active
        # defaults a missing key to True, so non-strict profiles must set it
        # False explicitly.
        "prompt_invariants": False,
        # Plan 193: advisory-only; active wherever no_hardcoded_secrets is.
        "legacy_file_scoped_waiver": True,
        # 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,
        "dependencies_match": True,
        "prompt_invariants": False,
        # Plan 193: proto does not scan for secrets, so there is no
        # waiver blindness to count down.
        "legacy_file_scoped_waiver": 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,
        "dependencies_match": True,
        "prompt_invariants": False,
        "legacy_file_scoped_waiver": False,
    },
}
 
# Plan 260: one table drives the log summary, the terminal summary and
# the JSON counters, so a rule cannot be checked without being reported.
# Each row is ``(rule_key, label, log_tabs, json_key)``:
#
# - ``rule_key`` indexes both the per-file result dict and the per-file
#   ``json_detail["checks"]`` block. Before this table the summary named
#   ten of the fifteen rules, so a file could be non-compliant with every
#   printed row at 100% and nothing on stdout saying which check failed.
# - ``label`` is the bracketed name printed in both text blocks.
# - ``log_tabs`` reproduces the log block's hand-tuned tab padding
#   byte-for-byte. It is NOT derivable from the label width: "[Syntax
#   error]:" and "[func pattern]:" are both 15 columns and carry two and
#   three tabs respectively. The terminal block's padding IS uniform
#   (label field width 27) and is computed instead of stored.
# - ``json_key`` is the summary counter name. The ten pre-existing names
#   are irregular (``dbg_usage`` counts as ``pass_dbg``, ``tests_exist``
#   as ``pass_tests``) and are kept byte-identical so no consumer breaks;
#   the five rules added here use ``pass_<rule_key>``.
#
# The ``[Compliant files]`` row is deliberately NOT in this table: it is
# a derived aggregate over the blocking rules, not a rule, and it keeps
# its own hand-written line after the loop.
SUMMARY_ROWS: tuple[tuple[str, str, int, str], ...] = (
    ("syntax_error", "Syntax error", 2, "pass_syntax_error"),
    ("header", "Header block", 2, "pass_header"),
    ("docstring", "Docstring structure", 2, "pass_docstring"),
    ("diagnostics_profile", "Diagnostics profile", 2, "pass_diagnostics_profile"),
    ("dbg_usage", "_dbg usage", 3, "pass_dbg"),
    ("dbg_import", "_dbg import", 3, "pass_dbg_import"),
    ("func_pattern", "func pattern", 3, "pass_func"),
    ("syntax_warnings", "Syntax warnings", 2, "pass_syntax"),
    ("type_hints", "Type hints", 3, "pass_type_hints"),
    ("tests_exist", "Regression test exists", 1, "pass_tests"),
    # Plan 260: the five rules that ran but were never summarised.
    ("dependencies_section", "Dependencies section", 2, "pass_dependencies_section"),
    ("no_hardcoded_secrets", "Hardcoded secrets", 2, "pass_no_hardcoded_secrets"),
    ("dbg_assert_safety", "dbg_assert safety", 2, "pass_dbg_assert_safety"),
    ("prompt_invariants", "Prompt invariants", 2, "pass_prompt_invariants"),
    (
        "legacy_file_scoped_waiver",
        "Legacy file-scoped waiver",
        1,
        "pass_legacy_file_scoped_waiver",
    ),
    # 2026-09-28: the declared-versus-actual Dependencies check.
    ("dependencies_match", "Dependencies match imports", 1, "pass_dependencies_match"),
)
 
# Width of the bracketed label field in the colourised terminal summary.
# The label is left-justified to one less than this and a single space
# follows, so a label longer than the field still gets a separator.
_TERMINAL_LABEL_WIDTH = 27
 
 
# ---------------------------------------------------------------------
# Rule-set resolution (plan 262)
# ---------------------------------------------------------------------
 
 
def resolve_active_rules(
    profile_name: str,
    octrc_rules: dict | None,
    cli_profile: str | None,
) -> tuple[dict[str, bool], list[str]]:
    """Resolve the active rule set for one linter run.
 
    Plan 262 - the project's ``linter.rules`` overrides are applied on
    top of the profile table in BOTH directions: whether the profile came
    from ``.octrc.json`` or from an explicit ``--profile`` flag. Before
    this plan the flag replaced the merged set wholesale, so ``oct lint
    --profile compact`` re-fired rules the project had deliberately
    switched off and reported files non-compliant that the commit gate
    passed, with nothing printed to explain the difference.
 
    Parameters
    ----------
    profile_name
        The profile named by the project's ``linter.profile`` key, or
        ``"default"`` when the project names none.
    octrc_rules
        The project's ``linter.rules`` block. Non-boolean values are
        ignored, exactly as they were before this plan.
    cli_profile
        A validated ``--profile`` name, or ``None``. When given it
        chooses the BASE rule set; the overrides still apply on top.
 
    Returns
    -------
    (active_rules, disabled_by_octrc) : tuple[dict[str, bool], list[str]]
        ``active_rules`` is the profile table with the overrides merged
        in. ``disabled_by_octrc`` names, sorted, the rules the overrides
        switched OFF that the chosen profile would otherwise have run -
        that is, exactly what a caller reading the profile name alone
        would wrongly have believed active. Keys starting with ``_`` are
        mode markers (``_compact_mode``), not rules, and never appear.
    """
    base_profile = cli_profile if cli_profile else profile_name
    active_rules = dict(_PROFILES.get(base_profile, _DEFAULT_RULES))
    overrides = {
        key: value
        for key, value in (octrc_rules or {}).items()
        if isinstance(value, bool)
    }
    disabled_by_octrc = sorted(
        key
        for key, value in overrides.items()
        if value is False
        and not key.startswith("_")
        # ``_rule_active`` treats a key missing from the profile table as
        # active, so the same default decides what was "otherwise on".
        and active_rules.get(key, True)
    )
    active_rules.update(overrides)
    return active_rules, disabled_by_octrc
 
 
# ---------------------------------------------------------------------
# Path-scoped rule overrides (plan 268)
# ---------------------------------------------------------------------
 
 
def _path_rule_matches(prefix: str, rel_posix: str) -> bool:
    """Return True when *rel_posix* is covered by *prefix*.
 
    Plan 268 - the prefix form is deliberately the one the scanner's
    ``entropy_exclusions[].path_pattern`` already uses, with one added
    distinction that makes a single file addressable: a prefix ending in
    ``/`` matches every file under that directory at any depth, and a
    prefix without one matches that exact file and nothing else. There is
    no globbing; a rule set that decides a verdict must be readable
    without running it.
    """
    if prefix.endswith("/"):
        return rel_posix.startswith(prefix)
    return rel_posix == prefix
 
 
def effective_rules(
    active_rules: dict[str, bool],
    rel_posix: str,
    path_rules: list,
) -> tuple[dict[str, bool], list[str]]:
    """Resolve the rule set for ONE file under the project's path rules.
 
    Plan 268 - :func:`resolve_active_rules` returns one dict for the whole
    run; this applies the project's ``linter.path_rules`` on top of it for
    a single file, so a test tree can be exempt from a rule its own
    package must keep. Every matching entry applies in list order and a
    later entry overrides an earlier one, exactly as ``linter.rules``
    overrides the profile.
 
    Two kinds of key are REFUSED here as well as at the schema, so a
    hand-edited octrc that slipped past a warning still cannot reach them:
    a rule in :data:`~oct.core.waivers.LINE_SCOPED_RULES` (a waiver never
    switches such a rule off for a whole file either - plan 193; and the
    commit gate's secrets pass is a separate always-on pass, G-D4), and
    any key starting with ``_``, which names a mode marker such as
    ``_compact_mode`` rather than a rule.
 
    Parameters
    ----------
    active_rules
        The run's rule set from :func:`resolve_active_rules`. Never
        mutated - the parallel linter shares one dict across threads.
    rel_posix
        The file's project-relative POSIX path, as
        :func:`~oct.core.paths.to_project_relative` renders it.
    path_rules
        Validated ``(prefix, {rule: bool})`` pairs from
        :func:`parse_path_rules`, usually ``ctx.path_rules``.
 
    Returns
    -------
    (file_rules, changed) : tuple[dict[str, bool], list[str]]
        ``file_rules`` is a fresh dict for this file. ``changed`` names,
        sorted, the rules whose value ends up DIFFERENT from what
        *active_rules* said - the net effect, so an entry that restates
        the run's own value, or one that a later entry puts back, names
        nothing. A missing key counts as ``True``, the same default
        ``_rule_active`` applies.
    """
    file_rules = dict(active_rules)
    if not path_rules:
        return file_rules, []
 
    touched: set[str] = set()
    for prefix, rules in path_rules:
        if not _path_rule_matches(prefix, rel_posix):
            continue
        for rule, value in rules.items():
            if not isinstance(value, bool):
                continue
            if rule.startswith("_") or rule in LINE_SCOPED_RULES:
                continue
            file_rules[rule] = value
            touched.add(rule)
 
    changed = sorted(
        rule for rule in touched
        if file_rules.get(rule, True) != active_rules.get(rule, True)
    )
    return file_rules, changed
 
 
def parse_path_rules(linter_cfg: dict | None) -> list:
    """Return the validated ``linter.path_rules`` entries, worst case ``[]``.
 
    Plan 268 - the runtime twin of the ``linter.path_rules`` schema check
    in :func:`_validate_octrc_schema`. Every shape that validator reports
    is dropped here rather than half-applied: a malformed entry is
    ignored, and the entries around it still apply. An entry left with no
    usable rule after the refusals is dropped too, since it can no longer
    change a verdict.
 
    Returns a list of ``(prefix, {rule: bool})`` pairs in file order, the
    form :func:`effective_rules` and :class:`LinterContext.path_rules`
    carry.
    """
    func = "parse_path_rules"
    if not isinstance(linter_cfg, dict):
        return []
    raw = linter_cfg.get("path_rules")
    if not isinstance(raw, list):
        return []
 
    parsed: list = []
    for entry in raw:
        if not isinstance(entry, dict):
            continue
        prefix = entry.get("path_prefix")
        if not isinstance(prefix, str) or not prefix:
            continue
        if ".." in prefix or prefix.startswith("/"):
            continue
        rules = entry.get("rules")
        if not isinstance(rules, dict):
            continue
        usable = {
            name: value
            for name, value in rules.items()
            if isinstance(value, bool)
            and not name.startswith("_")
            and name not in LINE_SCOPED_RULES
        }
        if not usable:
            continue
        parsed.append((prefix, usable))
 
    _dbg("OCT-LINTER", func, f"parsed {len(parsed)} path rule(s)", 3)
    return parsed
 
 
# ---------------------------------------------------------------------
# .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")
 
 
#: Plan 197 (T3) - top-level keys that LOOK like a real setting but are
#: read by nothing, mapped to the nested key that actually applies.
#: These are rejected rather than aliased: a security-relevant setting
#: must have exactly ONE spelling, or every audit has to check two
#: places and a near-miss typo stays silent. Silently ignoring them is
#: what let ``oc_chat`` declare ``linter_profile: "strict"`` while the
#: quality gate ran it at ``compact``. Genuinely unknown keys remain
#: tolerated for forward compatibility - only this known-misplaced set
#: is flagged.
_MISPLACED_TOP_LEVEL_KEYS: dict[str, str] = {
    "linter_profile": "linter.profile",
    "profile": "linter.profile",
    "pre_commit_profile": "git.pre_commit_profile",
    "protected_branches": "git.protected_branches",
}
 
 
def _validate_path_rule_entry(index: int, entry: object) -> list[str]:
    """Validate one ``linter.path_rules`` entry (plan 268).
 
    Returns the human-readable errors for this entry; an empty list means
    :func:`parse_path_rules` will apply it as written. Unknown keys inside
    an entry stay tolerated for forward compatibility, exactly as unknown
    keys are elsewhere in the octrc.
    """
    where = f"linter.path_rules[{index}]"
    if not isinstance(entry, dict):
        return [f"'{where}' must be an object, got {type(entry).__name__}"]
 
    errors: list[str] = []
 
    prefix = entry.get("path_prefix")
    if not isinstance(prefix, str) or not prefix:
        errors.append(f"'{where}.path_prefix' must be a non-empty string")
    else:
        if ".." in prefix:
            errors.append(f"'{where}.path_prefix' must not contain '..'")
        if prefix.startswith("/"):
            errors.append(
                f"'{where}.path_prefix' must be project-relative "
                f"(no leading '/')"
            )
 
    rules = entry.get("rules")
    if not isinstance(rules, dict):
        errors.append(f"'{where}.rules' must be an object, got {type(rules).__name__}")
    else:
        for name, value in rules.items():
            if name in LINE_SCOPED_RULES:
                # The one refusal that is a security invariant rather than
                # a typo: a line-scoped rule is never switched off for a
                # whole file (plan 193), so it is never switched off for a
                # whole directory either.
                errors.append(
                    f"'{where}.rules.{name}' cannot be scoped by path "
                    f"(line-scoped rules are never switched off)"
                )
            elif name.startswith("_"):
                errors.append(
                    f"'{where}.rules.{name}' is not a rule "
                    f"(keys starting with '_' are mode markers)"
                )
            elif not isinstance(value, bool):
                errors.append(
                    f"'{where}.rules.{name}' must be a bool, "
                    f"got {type(value).__name__}"
                )
 
    reason = entry.get("reason")
    if reason is not None and not isinstance(reason, str):
        errors.append(f"'{where}.reason' must be a string, got {type(reason).__name__}")
 
    return errors
 
 
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.
 
    Exception (Plan 197 T3): keys in :data:`_MISPLACED_TOP_LEVEL_KEYS`
    are reported as misplaced. They are inert where they sit, and the
    setting they appear to configure is security-relevant, so a silent
    no-op is the one outcome that is not acceptable.
    """
    errors: list[str] = []
    if not isinstance(cfg, dict):
        return [f"top-level must be an object, got {type(cfg).__name__}"]
 
    # Plan 197 (T3): misplaced top-level keys that nothing reads.
    for bad_key, correct_key in _MISPLACED_TOP_LEVEL_KEYS.items():
        if bad_key in cfg:
            errors.append(
                f"'{bad_key}' is not a top-level key and is IGNORED; "
                f"move it to '{correct_key}'"
            )
 
    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__}"
                        )
 
        # Plan 268: per-path rule overrides, applied after the profile and
        # after ``linter.rules``. A malformed entry is reported and then
        # ignored by ``parse_path_rules``; the entries around it apply.
        path_rules = linter_cfg.get("path_rules")
        if path_rules is not None:
            if not isinstance(path_rules, list):
                errors.append(
                    f"'linter.path_rules' must be a list, "
                    f"got {type(path_rules).__name__}"
                )
            else:
                for i, entry in enumerate(path_rules):
                    errors.extend(_validate_path_rule_entry(i, entry))
 
    # 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".
    # OCT-LINT: disable=no_hardcoded_secrets reason="Field name; documents the matcher mode, not a credential"
    secret_match_mode: str = "substring"
    # 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"
    # Plan 268: validated ``(prefix, {rule: bool})`` pairs from the
    # project's ``linter.path_rules``, produced by
    # :func:`parse_path_rules` and applied per file by
    # :func:`effective_rules`. Empty means "no path scoping", which is
    # every project that does not ask for it.
    path_rules: list = field(default_factory=list)
    # FS-510: incremental lint cache. None means cache disabled.
    lint_cache: Any = None
    no_cache_read: bool = False
    # dependencies_match: the filesystem probes of
    # :mod:`oct.deps.dependency_check`, memoised for this run only, so a
    # long-lived process sees files created between runs.
    dependency_memo: dict = field(default_factory=dict)
 
 
# ---------------------------------------------------------------------
# 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,
) -> Iterator[Path]:
    """
    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
        # Plan 282: the exclusion answers a question about DIRECTORIES, so
        # it is asked of the directory parts ONLY. ``parts`` of a file path
        # ends with the filename, and asking it there dropped every module
        # whose NAME contained an excluded substring - ``venv_sitecustomize.py``,
        # ``lint_cache.py``, ``logs.py`` - from the linter, the formatter, the
        # dashboard and the quality gate's all-files scope, which is the list
        # its secrets pass scans. The predicate itself is unchanged.
        parts = path.relative_to(root).parts[:-1]
        if any(is_excluded_dir(Path(p), exclude_dirs, wildcard_exclude_dirs) for p in parts):
            continue
        yield path
 
 
# ---------------------------------------------------------------------
# Plan 213 / D-D - the lens for a file is a function of the FILE
# ---------------------------------------------------------------------
 
 
def _load_workspace_for(root: Path):
    """Return ``(workspace, is_workspace_root)`` for *root*, or ``(None, False)``.
 
    Mirrors ``oct.git.oct_git._maybe_load_workspace`` but is kept local so
    the linter never imports the git layer. Any load failure degrades to
    single-project mode - a malformed manifest must not stop ``oct lint``
    from linting.
    """
    try:
        from oct.core.workspace import find_workspace_root, load_workspace
    except ImportError:
        return None, False
    ws_path = find_workspace_root(root)
    if ws_path is None:
        return None, False
    try:
        workspace = load_workspace(ws_path)
    except Exception:
        return None, False
    return workspace, ws_path.resolve() == root.resolve()
 
 
def group_paths_by_lens(
    files: list[Path], workspace: "Workspace",
) -> dict[Path, list[Path]]:
    """Group *files* by the project root whose lens governs each one.
 
    Plan 213 / D-D. The "lens" is the ``project_root`` handed to
    :class:`LinterContext` / ``FormatterContext``: it decides the expected
    ``# path/to/file.py`` identity header, ``tests_dir``,
    ``diagnostics_dir``, and which ``octrc.json`` applies. Before 213 that
    root was whatever the caller passed - the invocation cwd - so the same
    file linted clean from its subproject and dirty from the workspace
    root, and ``oct format --fix`` would rewrite its header to the wrong
    lens.
 
    A file inside a subproject is governed by that subproject; longest
    prefix wins for nested subprojects. Every other file keeps the
    workspace-root lens, matching how the commit gate treats its
    ``workspace`` and ``__unscoped__`` buckets.
 
    The returned mapping partitions *files*: every input path appears
    under exactly one root.
    """
    from oct.core.workspace import assign_to_subproject
 
    groups: dict[Path, list[Path]] = {}
    for path in files:
        subproject = assign_to_subproject(path, workspace)
        root = subproject.path if subproject is not None else workspace.root
        groups.setdefault(root, []).append(path)
    return groups
 
 
def _linter_flag_argv(args) -> list[str]:
    """Rebuild the non-positional argv from parsed *args*.
 
    Used to re-invoke the single-root engine once per lens group with the
    caller's flags preserved. Rebuilt from the parsed namespace rather
    than filtered out of the raw argv so option-with-value forms
    (``--jobs 4``, ``-j4``, ``--profile strict``) cannot be mistaken for
    positional targets.
    """
    flags: list[str] = []
    if args.fix_headers:
        flags.append("--fix-headers")
    if args.dry_run:
        flags.append("--dry-run")
    if args.json:
        flags.append("--json")
    if args.jobs != 1:
        flags.extend(["--jobs", str(args.jobs)])
    if args.profile:
        flags.extend(["--profile", args.profile])
    if args.secret_match != "substring":
        flags.extend(["--secret-match", args.secret_match])
    if args.entropy_threshold is not None:
        flags.extend(
            ["--code-entropy-threshold", str(args.entropy_threshold)]
        )
    if args.no_entropy:
        flags.append("--no-entropy")
    if args.no_cache:
        flags.append("--no-cache")
    if args.baseline:
        flags.append("--baseline")
    if args.against_baseline:
        flags.append("--against-baseline")
    return flags
 
 
def _expand_lint_targets(
    targets: list[str], exclude_dirs, wildcard_exclude,
) -> list[Path]:
    """Resolve CLI target strings to a de-duplicated list of Python files."""
    files: list[Path] = []
    for target in targets:
        path = Path(target).resolve()
        if path.is_file() and path.suffix == ".py":
            files.append(path)
        elif path.is_dir():
            files.extend(
                find_python_files(path, exclude_dirs, wildcard_exclude)
            )
    return list(dict.fromkeys(files))
 
 
# ---------------------------------------------------------------------
# Project-level requirements
# ---------------------------------------------------------------------
 
 
def project_required_docs(ctx: LinterContext) -> list[Path]:
    """Return the project-level documents ``oct lint`` requires for *ctx*.
 
    Plan 213 / T0: the ``debug_config.json`` entry resolves through
    :func:`oct.core.option_c_dir.resolve_debug_config` rather than
    ``ctx.diagnostics_dir / "debug_config.json"``. The old expression
    hard-coded the pre-FS-539 layout, so a project migrated to
    ``.option_c/`` was reported as missing a config file it actually had
    - and, worse, the workaround was to keep an ``oc_diagnostics/``
    directory in the project root purely to satisfy the check, which is
    exactly the directory that shadowed the real ``oc_diagnostics``
    package on every ``python -m pytest`` run.
 
    ``ctx.diagnostics_dir`` is untouched: it still drives the legacy
    ``diagnostics/`` deprecation warning in :func:`run_linter`.
    """
    return [
        ctx.docs_dir / "ARCHITECTURE.md",
        ctx.tests_dir / "run_tests.py",
        ctx.tests_dir / "Tests_README.md",
        resolve_debug_config(ctx.project_root),
    ]
 
 
# ---------------------------------------------------------------------
# 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,
) -> tuple[bool, list[str]]:
    """
    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 _docstring_for_rule(
    text: str, tree: ast.Module | None = None,
) -> tuple[str | None, str]:
    """The module docstring a docstring-reading rule judges, or why there is none.
 
    Located structurally, by :func:`_extract_module_docstring` (the plan-204
    authority): the module's first statement must be the string literal.
    Before 2026-09-28 the docstring and dependencies rules matched the first
    triple-quoted string anywhere, so a "docstring" below an import - a bare
    string statement Python does not treat as the docstring - passed
    (``oct new`` generated exactly that).
 
    A file that does not parse keeps the old text match: ``syntax_error``
    already fails it, and "the first statement must be the docstring" would
    misreport a file whose only problem is a syntax error further down.
 
    Returns ``(docstring, "")`` or ``(None, message)``. *tree*, when given,
    must be the parse of *text*; it spares both parses below.
    """
    doc = _extract_module_docstring(text, tree)
    if doc is not None:
        return doc, ""
    if tree is None:
        tree, _ = safe_parse(text)
    if tree is not None:
        return None, "Missing module docstring (the first statement must be the docstring)"
    m = re.search(r'"""(.*?)"""', text, re.DOTALL)
    return (m.group(1), "") if m else (None, "Missing module docstring")
 
 
def check_docstring(text: str, tree: ast.Module | None = None) -> tuple[bool, str]:
    """
    Validate that a module docstring exists and contains the required
    Option C sections. The docstring is found by :func:`_docstring_for_rule`;
    pass *tree* (the parse of *text*) to spare a re-parse.
    """
    doc, why = _docstring_for_rule(text, tree)
    if doc is None:
        return False, why
    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, tree: ast.Module | None = None,
) -> tuple[bool, 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.
    The docstring is found by :func:`_docstring_for_rule` (structural since
    2026-09-28, operator ruling; it matched the first triple-quoted string
    anywhere before). Pass *tree* (the parse of *text*) to spare a re-parse.
    """
    doc, why = _docstring_for_rule(text, tree)
    if doc is None:
        return False, why
    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, ""
 
 
#: Line breaks exactly as the Python parser sees them. ``str.splitlines``
#: also splits on form feed, vertical tab and U+2028, which would desynchronise
#: line numbers from ``ast``'s.
_SOURCE_LINE_BREAK_RE = re.compile(r'\r\n|\r|\n')
 
#: The ``r``/``u`` prefix a string literal may carry before its quotes.
_STRING_PREFIX_RE = re.compile(r'[A-Za-z]*')
 
 
class _DocstringSlice(NamedTuple):
    """Where the module docstring is, in SOURCE-TEXT terms.
 
    ``text`` is the raw source between the quotes - NOT the decoded value:
    ``source[open_index:close_index] == text``. ``quote`` is the delimiter
    that surrounds it and ``prefix`` is the literal's string prefix, so
    ``prefix + quote + text + quote`` reconstructs the literal exactly and
    decodes to the value ``ast.get_docstring`` reports. The prefix matters
    for that reconstruction alone: an ``r``-prefixed docstring decodes
    differently with it than without.
    """
 
    text: str
    open_index: int
    close_index: int
    quote: str
    prefix: str
 
 
def _source_offset(
    text: str, line_starts: list[int], lineno: int, col_offset: int,
) -> int | None:
    """
    Convert an AST ``(lineno, col_offset)`` pair into an offset into *text*.
 
    ``ast`` reports ``col_offset`` as a UTF-8 BYTE offset within the line, so
    a line containing any non-ASCII character needs the prefix re-decoded
    rather than added. Returns ``None`` if the position is not addressable,
    so callers fail closed rather than slicing at a guessed offset.
    """
    if lineno < 1 or lineno > len(line_starts):
        return None
    line_start = line_starts[lineno - 1]
    line_end = line_starts[lineno] if lineno < len(line_starts) else len(text)
    line = text[line_start:line_end]
    if line.isascii():
        return line_start + col_offset if col_offset <= len(line) else None
    try:
        prefix = line.encode("utf-8")[:col_offset].decode("utf-8")
    except UnicodeDecodeError:
        return None
    return line_start + len(prefix)
 
 
def _module_docstring_slice(
    text: str, tree: ast.Module | None = None,
) -> _DocstringSlice | None:
    """
    Locate the module docstring structurally, and report it as SOURCE TEXT.
 
    204: this is the one authority for "where is the module docstring". It
    asks ``ast`` - the same question Python itself answers - instead of
    matching quotes with a regex, which could neither see a docstring
    containing a column-0 ``def`` (``^\\s*(def|class)\\s`` matches inside
    string literals) nor rank a ``'''`` docstring above a ``\"\"\"`` banner.
 
    The RAW SLICE, not ``ast.get_docstring``'s decoded value, is the return
    contract, and it is what lets one helper serve both consumers: the
    formatter's ``fix_docstring`` must find the docstring *in the source*
    to know where to append Option C sections, and a decoded value is not
    there to be found on any docstring carrying a backslash or an escaped
    quote (plan 200 measured 16 such files).
 
    Returns ``None`` - "no docstring" - when the source does not parse, when
    the module does not open with a string literal, or when the literal
    cannot be expressed as one delimited slice (implicit concatenation, an
    f-string). Every one of those is a fail-closed answer: callers must not
    widen their scope on ``None``.
 
    *tree*, when given, must be the parse of *text* itself. The linter
    passes the tree it already built so a file is parsed once, not once per
    docstring-reading rule (measured 2026-09-28: those re-parses were two
    of every three parses in a cold ``oct lint``). Without it the source is
    parsed here, as before.
    """
    if tree is None:
        try:
            tree = ast.parse(text)
        except (SyntaxError, ValueError):
            return None
    if not tree.body:
        return None
    node = tree.body[0]
    if not isinstance(node, ast.Expr):
        return None
    literal = node.value
    if not isinstance(literal, ast.Constant) or not isinstance(literal.value, str):
        return None
    if node.end_lineno is None or node.end_col_offset is None:
        return None
 
    line_starts = [0]
    line_starts.extend(m.end() for m in _SOURCE_LINE_BREAK_RE.finditer(text))
    begin = _source_offset(text, line_starts, node.lineno, node.col_offset)
    end = _source_offset(text, line_starts, node.end_lineno, node.end_col_offset)
    if begin is None or end is None or not 0 <= begin < end <= len(text):
        return None
 
    segment = text[begin:end]
    prefix_match = _STRING_PREFIX_RE.match(segment)
    prefix = prefix_match.group(0) if prefix_match else ""
    if set(prefix.lower()) - {"r", "u"}:
        return None
    body = segment[len(prefix):]
    quote = next(
        (q for q in ('"""', "'''", '"', "'") if body.startswith(q)), None,
    )
    if quote is None or len(body) < 2 * len(quote) or not body.endswith(quote):
        return None
    inner = body[len(quote):-len(quote)]
    if quote in inner:
        # Implicitly concatenated literals ("a" "b") are one docstring to
        # Python but not one slice of source; there is no single span to
        # hand the formatter, so report no docstring rather than a wrong one.
        return None
    try:
        if ast.literal_eval(segment) != literal.value:
            return None
    except (SyntaxError, ValueError):
        return None
 
    open_index = begin + len(prefix) + len(quote)
    return _DocstringSlice(
        inner, open_index, open_index + len(inner), quote, prefix,
    )
 
 
def _extract_module_docstring(
    text: str, tree: ast.Module | None = None,
) -> str | None:
    """
    Return the module docstring as it is written in the source, or ``None``.
 
    The returned value is the raw text between the quotes - escapes
    undecoded - so it can be located in the source with ``str.find``. See
    :func:`_module_docstring_slice`, which is the authority; this is the
    value-only view of it that most callers want. *tree* is passed through
    to it unchanged.
    """
    located = _module_docstring_slice(text, tree)
    return None if located is None else located.text
 
 
def check_diagnostics_profile(
    text: str, tree: ast.Module | None = None,
) -> tuple[bool, str]:
    """
    Validate that a Diagnostics profile is present in the module docstring.
 
    Scopes the search to the module docstring so in-code string literals that
    happen to contain 'L2', 'L3', 'L4', 'Diagnostics' or 'Domain:' cannot
    satisfy the rule.
 
    204: no docstring means the rule FAILS. It used to mean "scan the whole
    file instead", which is strictly more permissive - a module whose
    docstring carried no profile at all could pass on tokens found in its
    code, and under the AST authority every unparseable file would take that
    path. A rule may not become more lenient the less it can see. An
    unparseable file is separately blocked by the ``syntax_error`` rule
    (170/F21), so this costs no file a correct verdict. Pass *tree* (the
    parse of *text*) to spare a re-parse.
    """
    docstring = _extract_module_docstring(text, tree)
    if docstring is None:
        return False, "Missing Diagnostics section in module docstring"
    scope = docstring
    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) -> tuple[bool, str]:
    """
    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"
 
 
#: The modules a ``_dbg`` import may name. ``oc_diagnostics`` is the
#: canonical source for every Option C project. The second entry exists
#: because 263 resolved a contradiction inside oct itself: oct declares
#: no dependency on the diagnostics package, so it re-exports ``_dbg``
#: through one fail-soft module of its own
#: (``oct/core/diagnostics.py``, which degrades to a signature-identical
#: no-op when the package is absent), and oct's module contract requires
#: every oct module to import from there rather than duplicate the
#: try/except stub. The rule accepted only the direct import, so the
#: contract and the rule contradicted each other and 19 modules that
#: obeyed the contract failed the rule. A package that must run without
#: the diagnostics runtime may name one such re-export module here; the
#: list is exact - no prefix, alias or wildcard is honoured.
_DBG_IMPORT_SOURCES = ("oc_diagnostics", "oct.core.diagnostics")
 
 
def check_dbg_import(text: str, tree: ast.Module | None = None) -> tuple[bool, str]:
    """
    Verify that ``_dbg`` is imported at module level from an accepted source.
 
    The canonical import is ``from oc_diagnostics import _dbg``. oct's own
    fail-soft re-export, ``from oct.core.diagnostics import _dbg``, is the
    one other accepted form (263/P1; see :data:`_DBG_IMPORT_SOURCES` for
    why). 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 - and neither
    is a plain ``import <module>``, which binds no ``_dbg`` name at all.
    """
    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 in _DBG_IMPORT_SOURCES
                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` "
        "(or `from oct.core.diagnostics import _dbg` within oct)"
    )
 
 
def _walk_function_body(
    func_node: ast.FunctionDef | ast.AsyncFunctionDef,
) -> Iterator[ast.AST]:
    """
    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: ast.AST) -> Iterator[ast.AST]:
    """
    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.
 
    A nested definition that is itself a statement of the body is skipped
    too (2026-09-28). Before, only nested definitions met as CHILDREN were
    skipped, so a decorator's inner ``wrapper`` - a body statement - had
    its ``_dbg`` calls credited to the decorator as well, and func_pattern
    flagged the decorator for a call it never makes.
    """
    stack = [
        stmt for stmt in func_node.body
        if not isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef))
    ]
    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.
 
    ``func`` also counts as present (2026-09-28, operator ruling) when it
    is one of the function's parameters - a logging helper such as
    oc_diagnostics' ``dbg_timed`` takes the caller's context as ``func`` -
    or when it is assigned from any expression, not only a literal - a
    decorator's wrapper labels records ``func = fn.__name__``. Before, both
    were flagged, and the formatter's fix would have overwritten the
    parameter with a literal, breaking every caller's label.
 
    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:
        params = func_node.args
        has_func_var = any(
            a.arg == "func"
            for a in (*params.posonlyargs, *params.args, *params.kwonlyargs)
        )
        has_dbg_call = False
 
        # Check for func = <value> in first 3 non-docstring statements
        non_doc_seen = 0
        for stmt in func_node.body:
            if has_func_var:
                break
            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"):
                has_func_var = True
                break
            if (isinstance(stmt, ast.AnnAssign)
                    and stmt.value is not None
                    and isinstance(stmt.target, ast.Name)
                    and stmt.target.id == "func"):
                has_func_var = True
                break
            non_doc_seen += 1
            if non_doc_seen >= 3:
                break
 
        # A function that sets ``func`` cannot be a finding, so its body is
        # not walked at all, and the walk stops at the first ``_dbg`` call
        # (2026-09-28: the full walk of every body was most of this rule's
        # cost, and this rule was the costliest in lint, the gate and health).
        if has_func_var:
            continue
 
        # Check for _dbg() anywhere in direct body (Name or Attribute form)
        for node in _direct_body_nodes(func_node):
            if isinstance(node, ast.Call) and (
                (isinstance(node.func, ast.Name) and node.func.id == "_dbg")
                or (isinstance(node.func, ast.Attribute)
                    and node.func.attr == "_dbg")
            ):
                has_dbg_call = True
                break
 
        if has_dbg_call:
            violations.append((func_node.name, func_node.lineno))
 
    return violations
 
 
def check_func_pattern(text: str, tree: ast.Module | None = None) -> tuple[bool, str]:
    """
    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,
) -> tuple[bool, str]:
    """
    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, ""
 
 
# F21 / Plan 170: shared message for every AST-dependent check
# (dbg_usage, dbg_import, type_hints, dbg_assert_safety, syntax_warnings)
# when the file failed to parse. Distinguishes "not run because the file
# is unparseable" from a genuine "OK" - the vacuous-PASS shape F21 found.
_AST_SKIP_MSG = "NOT-RUN (syntax error prevents AST parsing)"
 
 
def _describe_syntax_error(text: str) -> str:
    """Re-parse *text* (known to fail ``safe_parse()``) to recover a
    human-readable SyntaxError description for the ``syntax_error`` rule.
 
    ``safe_parse()`` collapses every parse failure to ``(None, [])`` -
    this is the one place that re-raises to read the actual message.
    """
    try:
        ast.parse(text)
    except SyntaxError as e:
        # Some messages already carry a line reference (e.g. "unterminated
        # string literal (detected at line N)"); only append one when the
        # message doesn't already have it.
        if e.lineno is not None and "line" not in e.msg.lower():
            return f"{e.msg} (line {e.lineno})"
        return e.msg
    except (ValueError, RecursionError) as e:
        # ast.parse() also documents these for null bytes / excessive
        # nesting; still "unparseable", still must block.
        return str(e)
    # Unreachable in practice (safe_parse() only returns tree=None on one
    # of the exceptions above) but never claim a pass we can't explain.
    return "unknown parse failure"
 
 
def check_type_hints(
    text: str, tree: ast.Module | None = None, compact_mode: bool = False,
) -> tuple[bool, str]:
    """
    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) -> bool:
    """
    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
from oct.core.diagnostics import _dbg
 
 
_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 _dbg_rule_outcomes(rel: str, checks: dict, cached: bool) -> None:
    """One L3 record per rule: which rules ran on *rel* and what each found.
 
    The individual check functions log nothing, so without this a debug
    log showed that a file was linted but not which rules ran or what they
    said (found by the chart C runtime trace of ``oct git commit``,
    2026-09-27). A failing rule's message is included, truncated, except
    ``no_hardcoded_secrets``: its message can quote the matched text, so
    only its verdict is logged.
    """
    func = "_dbg_rule_outcomes"
    source = " (cached)" if cached else ""
    for rule, check in checks.items():
        passed = bool(check.get("pass", True))
        detail = ""
        if not passed and rule != "no_hardcoded_secrets":
            detail = f": {str(check.get('message', ''))[:120]}"
        _dbg("OCT-LINTER", func,
             f"rule {rule} {'pass' if passed else 'FAIL'} "
             f"[{check.get('severity', '?')}] {rel}{source}{detail}", 3)
 
 
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.
    """
    func = "_lint_single_file"
    text = read_file(path, ctx)
    rel = to_project_relative(path, ctx.project_root)
 
    # Plan 268: the project's path-scoped overrides are the LAST thing to
    # move a rule, and they move it for this file only. Rebinding
    # ``active_rules`` here is deliberate: every decision below - the
    # ``_rule_active`` gate, ``_compact_mode``, and the cache's rules
    # hash - then reads the per-file set without a second spelling. The
    # returned dict is always a fresh one, so the single ``active_rules``
    # the parallel linter shares across threads is never touched.
    active_rules, path_rule_changes = effective_rules(
        active_rules, rel, ctx.path_rules,
    )
 
    log("", ctx)
    log(f"--- {rel} ---", ctx)
 
    # Parse inline waivers (# OCT-LINT: disable=<rule>) up front - needed by
    # both the cache-hit fast path (Plan 168 fix 1 recompute) and the normal
    # full-check path below.
    waivers = parse_inline_waivers(text)
    # Plan 193 (sec): a waiver no longer switches a LINE-SCOPED rule off
    # for the whole file. Those rules' checks always RUN and their
    # findings are scoped per line at the call site (see
    # ``no_hardcoded_secrets`` below), so one waived false positive can
    # no longer blind the file to a real secret. Every other rule keeps
    # whole-file waiver semantics - its check reports a verdict, not
    # located findings, so there is nothing to scope against. An
    # explicit ``disable-file=`` waiver is handled by ``apply_waivers``
    # for line-scoped rules and here for the rest.
    waived_rules: set[str] = {
        w["rule"] for w in waivers.values()
        if w["reason"] is not None and w["rule"] not in LINE_SCOPED_RULES
    }
 
    # 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
 
    # 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)
                # FS-510 stale-path fix (Plan 151 T6): the cache is keyed by
                # CONTENT hash, so two byte-identical files at different paths
                # collide on one entry. json_detail carries the ORIGINAL
                # file's ``path`` - rebind it to the CURRENT file so a
                # cache-hit never reports a stale path (e.g. two empty
                # ``__init__.py`` package markers). Copy first, never mutate
                # the shared cached dict.
                _detail = dict(cached.json_detail) if cached.json_detail else {}
                _detail["path"] = rel
                # Plan 268: the changed-rule list is a function of the
                # file's PATH, like ``path`` above. Two files can share a
                # content hash AND an effective rule set while only one of
                # them was moved there by a path entry, so recompute it
                # rather than inherit the writer's.
                if path_rule_changes:
                    _detail["path_rules"] = path_rule_changes
                else:
                    _detail.pop("path_rules", None)
                result["json_detail"] = _detail
                result["fixed"] = False
                result["rel"] = str(rel)
 
                # Plan 168 fix 1: ``header``, ``tests_exist`` and
                # ``prompt_invariants`` are functions of the file's PATH /
                # STEM, not its content - two content-identical files can
                # legitimately disagree on them (e.g. "foo.py" has a
                # "test_foo.py" but same-content "bar.py" has no
                # "test_bar.py"). The path-display rebind above does not
                # correct these booleans, so recompute them fresh on every
                # cache hit instead of trusting the cached verdict.
                # A copy: ``_detail`` above is shallow, so its "checks" is
                # still the cached dict every later hit on this content reads.
                _detail_checks = dict(_detail.get("checks", {}))
 
                # F21 / Plan 170: "syntax_error" is content-derived (a
                # cache hit's content_hash guarantees the same parse
                # outcome), but cache entries written by a pre-fix oct
                # version carry no "syntax_error" key at all. Recompute
                # fresh on every cache hit - cheap (one ast.parse) - so a
                # stale disk cache can never resurrect the vacuous-PASS
                # shape (F21) for an already-cached broken file.
                from oct.linter.rule_registry import SEVERITY_BLOCKING as _SB_CACHE
                _cache_tree, _ = safe_parse(text)
                ok_syntax_error_fresh = _cache_tree is not None
                syntax_error_msg_fresh = (
                    None if ok_syntax_error_fresh else _describe_syntax_error(text)
                )
                result["syntax_error"] = ok_syntax_error_fresh
                _detail_checks["syntax_error"] = {
                    **_detail_checks.get("syntax_error", {}),
                    "pass": ok_syntax_error_fresh,
                    "message": syntax_error_msg_fresh if not ok_syntax_error_fresh else "OK",
                    "severity": _SB_CACHE,
                }
 
                if _rule_active("header"):
                    _lines = text.splitlines()
                    ok_header_fresh, header_errors_fresh = validate_header_block(
                        _lines, path, ctx,
                    )
                    result["header"] = ok_header_fresh
                    if "header" in _detail_checks:
                        _detail_checks["header"] = {
                            **_detail_checks["header"],
                            "pass": ok_header_fresh,
                            "message": (
                                ", ".join(header_errors_fresh)
                                if header_errors_fresh else "OK"
                            ),
                        }
                if _rule_active("tests_exist"):
                    ok_test_fresh = check_tests_exist(path, ctx)
                    result["tests_exist"] = ok_test_fresh
                    if "tests_exist" in _detail_checks:
                        _detail_checks["tests_exist"] = {
                            **_detail_checks["tests_exist"],
                            "pass": ok_test_fresh,
                            "message": "OK" if ok_test_fresh else "No test found",
                        }
                if _rule_active("prompt_invariants"):
                    from oct.linter.prompt_invariant_rules import check_prompt_invariants
                    ok_prompt_fresh, prompt_msg_fresh = check_prompt_invariants(rel, text)
                    result["prompt_invariants"] = ok_prompt_fresh
                    if "prompt_invariants" in _detail_checks:
                        _detail_checks["prompt_invariants"] = {
                            **_detail_checks["prompt_invariants"],
                            "pass": ok_prompt_fresh,
                            "message": prompt_msg_fresh or "OK",
                        }
                # dependencies_match depends on the file's PATH (its own
                # dotted name, relative imports) and on which OTHER modules
                # exist, neither of which the content-keyed cache sees, so
                # it is recomputed on every hit like the path rules above.
                if _rule_active("dependencies_match"):
                    from oct.deps.dependency_check import check_dependencies_match
                    ok_match_fresh, match_msg_fresh = check_dependencies_match(
                        path, ctx.project_root, _cache_tree, memo=ctx.dependency_memo,
                    )
                    result["dependencies_match"] = ok_match_fresh
                    if "dependencies_match" in _detail_checks:
                        _detail_checks["dependencies_match"] = {
                            **_detail_checks["dependencies_match"],
                            "pass": ok_match_fresh,
                            "message": match_msg_fresh,
                        }
                _detail["checks"] = _detail_checks
 
                # 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 = _detail_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"
                    )
                _dbg_rule_outcomes(str(rel), _detail_checks, cached=True)
                return result
 
    # Parse AST once and share across all check functions
    tree, syntax_warnings_list = safe_parse(text)
 
    # F21 / Plan 170: safe_parse() swallows SyntaxError into (None, []) -
    # indistinguishable from "parsed cleanly, zero warnings". Re-parse here
    # (broken-file path only) to recover the actual SyntaxError text and
    # line number for the syntax_error blocking finding below.
    syntax_error_msg = None if tree is not None else _describe_syntax_error(text)
 
    lines = text.splitlines()
    header_errors: list[str] = []
    # OCT-LINT: disable=no_hardcoded_secrets reason="Variable holds lint output, not a credential"
    doc_msg = diag_msg = dbg_msg = dbg_imp_msg = func_msg = secrets_msg = ""
    hints_msg = dbg_assert_msg = ""
 
    compact_mode = active_rules.get("_compact_mode", False)
 
    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"
            )
 
    # Plan 193 (sec): lines of bare ``disable=`` waivers that suppressed
    # findings ONLY via the pre-193 whole-file fallback. Populated by the
    # ``no_hardcoded_secrets`` check below and surfaced as the advisory
    # ``legacy_file_scoped_waiver`` burn-down finding. Stays empty when
    # the rule is inactive - a file whose secret scanning is off has no
    # waiver blindness to report.
    legacy_waiver_lines: tuple[int, ...] = ()
 
    result: dict = {
        "syntax_error": False,
        "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, "prompt_invariants": False,
        "legacy_file_scoped_waiver": True,
        "fixed": False, "rel": str(rel),
        "waivers": [{"line": ln, **w} for ln, w in waivers.items()],
    }
 
    # F21 / Plan 170: unconditional - never gated by `_rule_active()` /
    # inline waivers. Unparseable Python is never compliant, at any
    # profile (see the _DEFAULT_RULES comment on "syntax_error").
    ok_syntax_error = tree is not None
    result["syntax_error"] = ok_syntax_error
    report(
        ok_syntax_error,
        f"Syntax error: {syntax_error_msg if not ok_syntax_error else 'OK'}",
        ctx=ctx,
    )
 
    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, tree=tree)
        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, tree=tree)
        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
 
    # Advisory: the Dependencies section against the module's real imports
    # (operator rulings 2026-09-28). Never raises; exempts test modules.
    # The docstring comes from *tree*; an unparseable file is "not run".
    if _rule_active("dependencies_match"):
        from oct.deps.dependency_check import check_dependencies_match
        ok_match, match_msg = check_dependencies_match(
            path, ctx.project_root, tree, memo=ctx.dependency_memo,
        )
        result["dependencies_match"] = ok_match
        report(ok_match, f"Dependencies match imports: {match_msg}", ctx=ctx)
    else:
        ok_match, match_msg = True, "OK"
        result["dependencies_match"] = True
 
    if _rule_active("diagnostics_profile"):
        ok_diag, diag_msg = check_diagnostics_profile(text, tree=tree)
        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"):
        if tree is None:
            ok_dbg, dbg_msg = True, _AST_SKIP_MSG
        else:
            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"):
        if tree is None:
            ok_dbg_imp, dbg_imp_msg = True, _AST_SKIP_MSG
        else:
            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"):
        if tree is None:
            ok_func, func_msg = True, _AST_SKIP_MSG
        else:
            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
 
    if tree is None:
        ok_syntax, syntax_msg = True, _AST_SKIP_MSG
    else:
        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"):
        if tree is None:
            ok_hints, hints_msg = True, _AST_SKIP_MSG
        else:
            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,
        )
        _dbg("OCT-LINTER", func,
             f"secrets scan {rel}: clean={ok_secrets} "
             f"(code entropy threshold {file_entropy})", 3)
        if not ok_secrets:
            # Plan 193 (sec): scope the file's waivers over the findings
            # the scanner just reported instead of dropping the whole
            # rule. Detection is untouched - only which findings are
            # excused changes, and strictly fewer are.
            _waiver_outcome = apply_waivers(
                secrets_msg, waivers, "no_hardcoded_secrets",
            )
            legacy_waiver_lines = _waiver_outcome.legacy_lines
            secrets_msg = _waiver_outcome.message
            ok_secrets = not _waiver_outcome.blocked
        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"):
        if tree is None:
            ok_dbg_assert, dbg_assert_msg = True, _AST_SKIP_MSG
        else:
            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
 
    if _rule_active("prompt_invariants"):
        from oct.linter.prompt_invariant_rules import check_prompt_invariants
        ok_prompt, prompt_msg = check_prompt_invariants(rel, text)
        result["prompt_invariants"] = ok_prompt
        report(ok_prompt, f"Prompt invariants: {prompt_msg or 'OK'}", ctx=ctx)
    else:
        ok_prompt = True
        prompt_msg = ""
        result["prompt_invariants"] = True
 
    # Plan 193 (sec): the migration burn-down counter. A bare
    # ``disable=<rule>`` waiver that is adjacent to none of the findings
    # it excuses is relying on pre-193 whole-file semantics; it still
    # suppresses (so the ~200 legacy files do not storm the gate in one
    # landing) but says so, as an ADVISORY that never blocks. Migrate the
    # file - move the waiver onto the offending line, or state whole-file
    # scope with ``disable-file=`` - and this clears. When the tree-wide
    # count reaches zero the legacy branch in ``apply_waivers`` can be
    # deleted as a behavioural no-op.
    ok_legacy_waiver = not legacy_waiver_lines
    legacy_waiver_msg = "" if ok_legacy_waiver else (
        "file-scoped secret waiver(s) at line "
        + ", ".join(str(ln) for ln in legacy_waiver_lines)
        + " suppressed finding(s) elsewhere in the file; move the waiver "
        "onto the offending line or use 'disable-file=' for deliberate "
        "whole-file scope"
    )
    result["legacy_file_scoped_waiver"] = ok_legacy_waiver
 
    # Log waiver warnings
    for ww in waiver_warnings:
        report(False, f"Waiver warning: {ww}", ctx=ctx)
    if not ok_legacy_waiver:
        report(False, f"Legacy waiver scope: {legacy_waiver_msg}", 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 = {
        "syntax_error": ok_syntax_error,
        "header": ok_header or fix_mode,
        "docstring": ok_doc,
        "dependencies_section": result.get("dependencies_section", True),
        "dependencies_match": ok_match,
        "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,
        "prompt_invariants": ok_prompt,
        "legacy_file_scoped_waiver": ok_legacy_waiver,
    }
    _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
    )
    _dbg("OCT-LINTER", func,
         f"verdict {rel}: compliant={result['compliant']}", 3)
 
    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": {
            "syntax_error": _check_block(
                ok_syntax_error,
                syntax_error_msg if not ok_syntax_error else "OK",
                "syntax_error",
            ),
            "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",
            ),
            "dependencies_match": _check_block(ok_match, match_msg, "dependencies_match"),
            "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 or "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 or "OK", "dbg_assert_safety"),
            "tests_exist": _check_block(ok_test, "OK" if ok_test else "No test found", "tests_exist"),
            "prompt_invariants": _check_block(
                ok_prompt, prompt_msg or "OK", "prompt_invariants"
            ),
            "legacy_file_scoped_waiver": _check_block(
                ok_legacy_waiver,
                legacy_waiver_msg or "OK",
                "legacy_file_scoped_waiver",
            ),
        },
        "compliant": result["compliant"],
        "waivers": result["waivers"],
    }
    # Plan 268: name the rules a path entry moved for THIS file, and only
    # when one did. A project that scopes nothing serialises exactly the
    # document it serialised before this plan.
    if path_rule_changes:
        result["json_detail"]["path_rules"] = path_rule_changes
    _dbg_rule_outcomes(str(rel), result["json_detail"]["checks"], cached=False)
 
    # 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 _maybe_dispatch_by_lens(project_root: Path, args) -> int | None:
    """Fan ``oct lint`` out to one engine run per owning subproject.
 
    Plan 213 / D-D. Returns the merged (worst-wins) exit code when the
    invocation fanned out, or ``None`` to let the caller run the ordinary
    single-root pass. Returning ``None`` is the common case: a
    single-project repo, or an invocation from inside a subproject whose
    targets all live in that subproject, behaves byte-identically to
    before.
 
    Two situations fan out:
 
    1. *project_root* IS the workspace root. Every candidate file is
       grouped by owning subproject and the existing single-root engine
       runs once per group, under that group's root and octrc.
    2. *project_root* is a subproject but an explicit target resolves
       outside it - the sibling-file case. The target is linted under the
       lens that owns it rather than the invocation's.
 
    A target that resolves outside the workspace entirely can be given no
    lens; rather than emit a wrong-lens verdict the dispatcher refuses and
    names the directory to run from.
    """
    if args.explain or args.help:
        return None
 
    workspace, is_workspace_root = _load_workspace_for(project_root)
    if workspace is None or not workspace.subprojects:
        return None
 
    exclude_dirs = set(EXCLUDE_DIRS)
    wildcard_exclude = list(WILDCARD_EXCLUDE_DIRS)
    flags = _linter_flag_argv(args)
    root_resolved = project_root.resolve()
 
    # -- Case 1: bare project scan at the workspace root ---------------
    # Fan out to a full per-subproject scan so each subproject's own
    # required-docs and octrc rules apply, then sweep the workspace-root
    # leftovers (files under no subproject) under the workspace lens.
    if is_workspace_root and not args.targets and not args.changed:
        exit_codes: list[int] = []
        for subproject in workspace.subprojects:
            if not subproject.path.is_dir():
                continue
            exit_codes.append(
                run_linter(subproject.path, list(flags), _dispatch=False)
            )
        leftovers = [
            path
            for path in find_python_files(
                workspace.root, exclude_dirs, wildcard_exclude,
            )
            if not any(
                _is_within(path, sp.path) for sp in workspace.subprojects
            )
        ]
        if leftovers:
            exit_codes.append(run_linter(
                workspace.root,
                list(flags) + [str(p) for p in leftovers],
                _dispatch=False,
            ))
        return max(exit_codes, default=0)
 
    # -- Resolve the candidate set for the remaining cases -------------
    if args.changed:
        if not is_workspace_root:
            return None
        candidates = [
            path for path in _git_changed_files(workspace.root)
            if path.is_file() and path.suffix == ".py"
        ]
    elif args.targets:
        candidates = _expand_lint_targets(
            list(args.targets), exclude_dirs, wildcard_exclude,
        )
        # Case 2 only triggers when a target escapes the invocation root.
        if not is_workspace_root and all(
            _is_within(path, root_resolved) for path in candidates
        ):
            return None
    else:
        return None
 
    if not candidates:
        return None
 
    unlensed = [
        path for path in candidates
        if not _is_within(path, workspace.root)
        and _assigned_subproject(path, workspace) is None
    ]
    if unlensed:
        names = ", ".join(str(p) for p in unlensed)
        print(
            "Error: no Option C lens governs these paths, so any verdict "
            f"would be arbitrary: {names}\n"
            "They lie outside the workspace "
            f"({workspace.root}) and outside every declared subproject. "
            "Run oct lint from the project that owns them.",
            file=sys.stderr,
        )
        return 1
 
    groups = group_paths_by_lens(candidates, workspace)
    if len(groups) == 1 and root_resolved in groups:
        # Everything already belongs to the invocation lens.
        return None
 
    exit_codes = []
    for group_root, group_files in groups.items():
        exit_codes.append(run_linter(
            group_root,
            list(flags) + [str(p) for p in group_files],
            _dispatch=False,
        ))
    return max(exit_codes, default=0)
 
 
def _is_within(path: Path, root: Path) -> bool:
    """True when *path* resolves inside *root*. Never raises."""
    try:
        Path(path).resolve().relative_to(Path(root).resolve())
        return True
    except (OSError, ValueError):
        return False
 
 
def _assigned_subproject(path: Path, workspace):
    """Thin wrapper over ``assign_to_subproject`` for readability."""
    from oct.core.workspace import assign_to_subproject
    return assign_to_subproject(path, workspace)
 
 
def _print_non_compliant_section(results: list[dict]) -> None:
    """Print each non-compliant file and the checks that failed it.
 
    Plan 260 P2. ``report()`` writes per-file PASS/FAIL lines to the log
    file only, so before this the operator got a summary of counts with
    no indication of which file or which rule was at fault. One line per
    failing check, taken verbatim from the per-file ``json_detail``
    block that ``--json`` already emitted: blocking findings first, then
    advisory ones suffixed ``[advisory]``.
 
    Nothing here re-runs a check or re-derives a verdict; the scanner's
    message is already truncated to a 24-character preview at the point
    of detection, so no secret is widened on the way out.
    """
    non_compliant = [r for r in results if not r.get("compliant", True)]
    if not non_compliant:
        return
 
    from oct.linter.rule_registry import SEVERITY_BLOCKING
 
    print(f"\nNon-compliant files ({len(non_compliant)}):")
    for result in non_compliant:
        detail = result.get("json_detail", {})
        print(f"  {detail.get('path', result.get('rel', '<unknown>'))}")
        checks = detail.get("checks", {})
        failing = [
            (rule, block)
            for rule, block in checks.items()
            if not block.get("pass", True)
        ]
        blocking = [
            (rule, block) for rule, block in failing
            if block.get("severity", SEVERITY_BLOCKING) == SEVERITY_BLOCKING
        ]
        advisory = [
            (rule, block) for rule, block in failing
            if block.get("severity", SEVERITY_BLOCKING) != SEVERITY_BLOCKING
        ]
        for rule, block in blocking:
            print(f"    {rule}: {block.get('message', '')}")
        for rule, block in advisory:
            print(f"    {rule}: {block.get('message', '')}  [advisory]")
 
 
def run_linter(
    project_root: Path,
    argv: list[str] | None = None,
    *,
    _dispatch: bool = True,
) -> int:
    """
    Run the Option C linter on the given project root.
 
    ``_dispatch`` is the plan-213 re-entrancy guard: the workspace lens
    dispatcher re-invokes this function once per owning subproject with
    ``_dispatch=False`` so the per-group runs cannot fan out again.
 
    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.
    """
    func = "run_linter"
    _dbg("OCT-LINTER", func, f"lint run starting at {project_root}", 3)
    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(
        "--quiet", action="store_true",
        help="Print the summary only; suppress the non-compliant file section",
    )
    parser.add_argument(
        "--profile",
        type=str,
        default=None,
        help=(
            "Lint profile: proto, compact, strict. Layers on the project's "
            ".octrc.json linter.rules overrides"
        ),
    )
    parser.add_argument(
        "--profile-only", action="store_true",
        help=(
            "With --profile, ignore the project's .octrc.json linter.rules "
            "and linter.path_rules overrides and report what the profile "
            "alone would say"
        ),
    )
    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("  --quiet                 Summary only; no non-compliant file section")
        print("  --profile P             Lint profile: proto, compact, strict (layers on .octrc.json)")
        print("  --profile-only          With --profile, ignore .octrc.json rule and path-rule overrides")
        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)
 
    # ---- Plan 213 / D-D: dispatch each file to its owning lens ----
    if _dispatch:
        dispatched = _maybe_dispatch_by_lens(project_root, args)
        if dispatched is not None:
            return dispatched
 
    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,
    )
 
    # Plan 151 T6 (G7 deprecation-clearance): warn ONLY when a LEGACY
    # ``diagnostics/`` directory actually exists. Previously the warning
    # fired whenever ``oc_diagnostics/`` was merely absent (the fallback
    # name is always "diagnostics"), so a subproject with NO diagnostics
    # directory at all still inherited the deprecation notice under the
    # aggregated per-subproject strict lint. Mirrors project_root.py's
    # ``has_legacy and not has_oc_diag`` guard.
    if ctx.diagnostics_dir.name == "diagnostics" and ctx.diagnostics_dir.is_dir():
        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)
    # Plan 262: the project's profile name and rule overrides are only
    # collected here; the rule set itself is resolved once, below, so the
    # octrc and the --profile flag are merged in exactly one place.
    octrc_profile_name = "default"
    octrc_rule_overrides: dict = {}
    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
            octrc_profile_name = linter_cfg.get("profile", "default")
            octrc_rule_overrides = linter_cfg.get("rules", {}) or {}
            ctx.profile_name = octrc_profile_name  # FS-C4: route profile to severity lookup
            # Plan 268: the per-path overrides ride the context, because
            # they are resolved per file rather than once per run.
            ctx.path_rules = parse_path_rules(linter_cfg)
 
            # 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)
                    ]
 
    # ---- Plan 262: a CLI --profile LAYERS on the .octrc.json overrides ----
    cli_profile: str | None = None
    if args.profile:
        candidate = args.profile.lower()
        if candidate in _PROFILES:
            cli_profile = candidate
            ctx.profile_name = candidate  # 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,
            )
 
    disabled_by_octrc: list[str] = []
    if cli_profile is not None and args.profile_only:
        # P3 - the explicit escape hatch: what the named profile alone
        # would say if the project carried no overrides at all. This is
        # the ONLY way to get the pre-262 wholesale replacement, so the
        # change of behaviour is visible in every invocation.
        active_rules = dict(_PROFILES[cli_profile])
        # Plan 268 / P4: "the profile alone" means the path-scoped
        # overrides are out too - they are the project's configuration by
        # the same token the rule overrides are.
        ctx.path_rules = []
    else:
        active_rules, octrc_disabled = resolve_active_rules(
            octrc_profile_name, octrc_rule_overrides, cli_profile
        )
        # P2 - the note reports what an EXPLICIT profile would otherwise
        # have re-enabled. With no flag the overrides are simply the
        # project's configuration and there is nothing to announce.
        if cli_profile is not None:
            disabled_by_octrc = octrc_disabled
 
    # ---- 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:
        # Plan 265: the store also keys on the linter's own code, so an
        # edit to any module that decides a verdict invalidates every
        # cached verdict. Computed once per run.
        from oct.linter.lint_cache import LintCache, current_linter_identity
        ctx.lint_cache = LintCache(
            cache_dir / "lint-cache.json",
            __version__,
            linter_identity=current_linter_identity(),
        )
        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 = project_required_docs(ctx)
 
    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 - plan 282: to the DIRECTORY parts only,
        # the same slice ``find_python_files`` takes, so ``--changed`` and a
        # full scan agree on whether a file named like an excluded directory
        # is a source file.
        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[:-1]
            )
        ]
        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 (plan 260: one per
    # SUMMARY_ROWS entry, so adding a rule to the table is the only step
    # needed to get it counted, printed and serialised). A rule that is
    # inactive under the active profile still gets a row and counts as
    # passing, which is how ``tests_exist`` already behaved under proto.
    pass_counts = {
        rule: sum(1 for r in results if r.get(rule, True))
        for rule, _label, _tabs, _json_key in SUMMARY_ROWS
    }
    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)
    for rule, label, log_tabs, _json_key in SUMMARY_ROWS:
        n = pass_counts[rule]
        padding = "\t" * log_tabs
        log(f"[{label}]:{padding}{n} PASS ({pct(n)})", 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 (
            blocking_violations, diff_against_baseline, load_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)
        # Only a new BLOCKING failure fails the comparison (operator ruling
        # 2026-09-28); new advisory ones are listed, marked as advisory.
        new_blocking = blocking_violations(new_violations, results)
        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),
            "new_blocking_count": len(new_blocking),
            "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)}, "
                      f"{len(new_blocking)} blocking):{RESET}", file=sys.stderr)
                blocking_set = set(new_blocking)
                for v in new_violations:
                    path_str, rule, msg = v
                    note = "" if v in blocking_set else " (advisory)"
                    print(f"  {path_str}: [{rule}]{note} {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,
                # Plan 260: the ten pre-existing key names are preserved
                # byte-for-byte by SUMMARY_ROWS; the five new counters
                # join them in the same table order.
                **{
                    json_key: pass_counts[rule]
                    for rule, _label, _tabs, json_key in SUMMARY_ROWS
                },
            },
            "files": file_results,
        }
        # Plan 260 P3: the per-file [FAIL] lines live in the log, so the
        # machine-readable document carries the path to reach them.
        if ctx.log_path is not None:
            output["log_path"] = str(ctx.log_path)
        # Plan 262 P2: the same thing the stderr note says, for machines.
        # Absent whenever the note would not print, so a document from a
        # project with no overrides is what it was before this plan.
        if disabled_by_octrc:
            output["disabled_by_octrc"] = disabled_by_octrc
        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_blocking_count", 0) > 0 else 0
        return 0 if fully_compliant == total_files else 1
 
    # Plan 262 P2: say once, before the rows it explains, that the named
    # profile did not get the last word on these rules. --quiet (plan
    # 260) suppresses it along with the rest of the narrative output.
    if disabled_by_octrc and not args.quiet:
        print(
            f"note: profile '{cli_profile}' with {len(disabled_by_octrc)} "
            f"rule(s) disabled by {to_project_relative(resolve_octrc(root), root)}: "
            f"{', '.join(disabled_by_octrc)}",
            file=sys.stderr,
        )
 
    # 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
 
    def label_field(label: str) -> str:
        """Left-justify ``[label]:`` into the summary's label column."""
        return f"[{label}]:".ljust(_TERMINAL_LABEL_WIDTH - 1) + " "
 
    for rule, label, _tabs, _json_key in SUMMARY_ROWS:
        n = pass_counts[rule]
        print(f"{label_field(label)}{color(n)}{n}{RESET} PASS ({pct(n)})")
    print(
        f"{label_field('Compliant files')}"
        f"{color(fully_compliant)}{fully_compliant}{RESET} "
        f"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}")
 
    # Plan 260 P2: name the non-compliant files and the checks that
    # failed them. The per-file [FAIL] lines only ever reached the log
    # file, so the operator saw a summary of green rows and no reason.
    # --quiet restores the pre-260 summary-only form for scripts.
    if not args.quiet:
        _print_non_compliant_section(results)
        # P3: the log holds the full per-file detail; say where it is.
        if ctx.log_path is not None:
            print(f"\nLint log: {ctx.log_path}")
 
    if args.against_baseline and baseline_info:
        return 1 if baseline_info.get("new_blocking_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()