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)
1.15.0