oct.formatter.oct_format module

Option C auto-formatter implementation.

Purpose

Detect and fix structural Option C compliance violations automatically. Complements the linter by fixing violations while preserving code semantics.

Responsibilities

• Detect formatting violations using reused linter checks.

• Fix violations: headers, docstrings, imports, function patterns.

• Support report-only (dry-run) and fix modes.

• Archive originals before modification.

• Provide terminal and JSON output.

• Respect project exclusions and configuration.

Diagnostics

Domain: OCT.FORMATTER Levels:

L2 — formatter lifecycle and command routing L3 — file discovery and processing, fix application decisions L4 — detailed fixer implementations, archival operations, output formatting

Contracts

• Files are only modified if fix_mode is True.

• Originals are archived before any modification.

• All code below headers is preserved exactly.

• Docstrings are not replaced; missing sections are appended.

• Each fixer is idempotent (running twice is same as once).

Dependencies

• oct (package version)

• oct.linter.oct_lint (reused validation checks)

• oct.core.exclusions (directory and wildcard exclusion lists)

• oct.core.project_root (project root detection)

• oct.core.parsing (safe AST parsing helper)

• oct.core.git (git changed-file discovery)

class oct.formatter.oct_format.FormatterContext(project_root: Path, project_name: str, diagnostics_dir: Path, tests_dir: Path, docs_dir: Path, fix_mode: bool, dry_run_mode: bool, json_mode: bool, verbose: bool, max_backups_per_file: int = 10, max_archive_bytes: int = 5242880)

Bases: object

Immutable per-run context for the formatter.

diagnostics_dir: Path

docs_dir: Path

dry_run_mode: bool

fix_mode: bool

json_mode: bool

max_archive_bytes: int = 5242880

OI-516 — aggregate cap across all backups in one .formatter_archive/ directory.

max_backups_per_file: int = 10

project_name: str

project_root: Path

tests_dir: Path

verbose: bool

oct.formatter.oct_format.compute_summary(file_results: List[Dict[str, Any]]) → Dict[str, Any]

Aggregate results into summary.

oct.formatter.oct_format.fix_dbg_import(path: Path, text: str, ctx: FormatterContext) → Tuple[bool, str, List[str]]

Ensure canonical _dbg import exists at module level.

Skips trivial files (< 20 lines).

oct.formatter.oct_format.fix_docstring(path: Path, text: str, ctx: FormatterContext) → Tuple[bool, str, List[str]]

Ensure module has complete docstring with all required sections.

If no docstring: insert skeleton. If incomplete: add missing sections. If complete: no change.

oct.formatter.oct_format.fix_func_pattern(path: Path, text: str, ctx: FormatterContext) → Tuple[bool, str, List[str]]

Ensure every function with _dbg() calls has func = “function_name” as first statement.

Delegates violation detection to oct.linter.oct_lint.find_func_pattern_violations() so the linter remains the single source of truth for what constitutes a func-pattern violation. This function only handles the fix (inserting the func = "..." line).

Skips trivial files (< 20 lines).

oct.formatter.oct_format.fix_header_block(path: Path, text: str, ctx: FormatterContext) → Tuple[bool, str, List[str]]

Ensure file has correct 4-line header block.

Returns (changed, new_text, messages). Caller is responsible for archiving and writing to disk.

oct.formatter.oct_format.format_file(path: Path, ctx: FormatterContext) → Dict[str, Any]

Process a single file through all formatters.

oct.formatter.oct_format.run_formatter(project_root: Path, argv: List[str] | None = None) → None

Run the Option C formatter on the given project root.

Parameters:

• project_root (Path) – The detected Option C project root directory.

• argv (list[str] | None) – Optional list of command-line arguments. If None, argparse will use sys.argv[1:].