oct_hooks.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/hooks/oct_hooks.py
 
"""
Purpose
-------
Generate pre-commit hook configuration for Option C projects.
 
Responsibilities
----------------
- Generate a ``.pre-commit-config.yaml`` with ``oct lint --profile strict``
  as a pre-commit hook.
- Support ``--force`` to overwrite existing configuration.
 
Diagnostics
-----------
Domain: OCT-HOOKS
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- Must not overwrite existing ``.pre-commit-config.yaml`` without ``--force``.
- Generated configuration must be valid YAML.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from pathlib import Path
from oct.core.diagnostics import _dbg
 
_PRE_COMMIT_TEMPLATE = """\
# Option C pre-commit configuration
# Generated by: oct install-hooks
# See https://pre-commit.com for more information
 
repos:
  - repo: local
    hooks:
      - id: oct-lint
        name: Option C Linter
        entry: oct lint --profile strict
        language: system
        types: [python]
        pass_filenames: false
 
      - id: oct-format-check
        name: Option C Format Check
        entry: oct format --dry-run
        language: system
        types: [python]
        pass_filenames: false
"""
 
 
def install_hooks(root: Path, force: bool = False) -> int:
    """Generate .pre-commit-config.yaml in the project root.
 
    Returns exit code: 0 on success, 1 on failure.
    """
    func = "install_hooks"
    _dbg("OCT-HOOKS", func, "installing the pre-commit hooks", 3)
    config_path = root / ".pre-commit-config.yaml"
 
    if config_path.exists() and not force:
        print(f"Error: {config_path} already exists. Use --force to overwrite.")
        return 1
 
    config_path.write_text(_PRE_COMMIT_TEMPLATE, encoding="utf-8")
    print(f"Created {config_path}")
    print("Run 'pre-commit install' to activate the hooks.")
    return 0