new_python_file.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/generator/new_python_file.py
 
"""
File Generator
==============
 
Purpose
-------
Create new Option C-compliant Python files with the mandatory 3-line header
block and a complete module docstring skeleton, ready for immediate development.
 
Responsibilities
----------------
- Accept a target path relative to or absolute from the project root.
- Write the mandatory 3-line header block (shebang, encoding, file identity).
- Write the Option C module docstring template next, including the
  Diagnostics section with a ``Domain`` derived from the file's path and a
  Dependencies section, so the docstring is the real module docstring.
- Write the ``from oc_diagnostics import _dbg`` import AFTER the docstring.
  It used to come first, which made the docstring a bare string statement
  (found during the chart C runtime trace work, 2026-09-27).
- Refuse to overwrite existing files unless ``--force`` is explicitly requested.
 
Diagnostics
-----------
Domain: OCT-GENERATOR
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- Must not overwrite existing files unless ``force=True``.
- Generated file must pass the OCT linter header, docstring,
  diagnostics-profile and dependencies-section checks immediately. It
  fails ``dbg_usage`` until its first function logs something, which is
  the intended reminder.
- Target path may be absolute or relative to the project root.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.project_root (find_project_root, imported but unused; the caller passes project_root)
- click (ClickException for refused paths and existing files)
"""
 
from pathlib import Path
import click
from oct.core.project_root import find_project_root
from oct.core.diagnostics import _dbg
 
SHEBANG = "#!/usr/bin/env python3"
ENCODING = "# -*- coding: utf-8 -*-"
 
# Import block placed after the module docstring (oc_diagnostics is the
# source of _dbg). Before the docstring it turned the docstring into a bare
# string statement.
IMPORT_BLOCK = "\nfrom oc_diagnostics import _dbg\n"
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Generated-file docstring/skeleton templates are high-entropy but not credentials"
DOCSTRING_TEMPLATE = '''"""
Purpose
-------
Describe the purpose of this module.
 
Responsibilities
----------------
- List the responsibilities of this module.
 
Diagnostics
-----------
Domain: {domain}
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- State the contracts and guarantees of this module.
 
Dependencies
------------
- oc_diagnostics (_dbg structured logger)
"""
'''
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Generated-file docstring/skeleton templates are high-entropy but not credentials"
TEST_DOCSTRING_TEMPLATE = '''"""
Purpose
-------
Unit tests for {module_name}.
 
Responsibilities
----------------
- Verify the public API of {module_name}.
 
Diagnostics
-----------
Domain: TESTS
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- Must not modify external state.
- Must be deterministic and repeatable.
"""
'''
 
TEST_BODY_TEMPLATE = '''
{import_line}
 
 
def test_{stem}_placeholder():
    """Placeholder test - replace with real tests."""
    assert True
'''
 
 
# Package-marker docstring for generated ``__init__.py`` files. Package
# markers carry no runtime logic, so - unlike ordinary generated modules -
# they deliberately OMIT both the ``from oc_diagnostics import _dbg`` import
# (an unused import trips the ``dbg_usage`` rule) and the Diagnostics
# docstring section (which implies ``_dbg`` usage), mirroring hand-written
# package inits such as ``oct/git/__init__.py``.
PACKAGE_INIT_DOCSTRING = '''"""
Purpose
-------
Package marker for this Python package.
 
Responsibilities
----------------
- Mark this directory as an importable Python package.
 
Contracts
---------
- Contains no runtime logic; created by ``oct new`` as a package marker.
"""
'''
 
 
def _make_header(rel_posix: str) -> str:
    """Build the 4-line Option C header block (shebang, encoding, identity, blank)."""
    return f"{SHEBANG}\n{ENCODING}\n# {rel_posix}\n\n"
 
 
def _make_package_init_content(rel_posix: str) -> str:
    """Build a header-bearing package-marker ``__init__.py``.
 
    Plan 151 T6 (oct footgun fix): replaces the previous EMPTY, header-less
    ``__init__.py`` - which failed the linter's mandatory header rule the
    moment it was created - with the standard Option C header block plus a
    minimal module docstring, matching the house style of hand-written
    package inits.
    """
    return _make_header(rel_posix) + PACKAGE_INIT_DOCSTRING
 
 
def _derive_domain(rel_posix: str) -> str:
    """The Diagnostics domain for a new module, from its path.
 
    oct's own convention: the package path, upper-cased and joined with
    hyphens (``oct/deps/call_graph.py`` -> ``OCT-DEPS``); a module at the
    project root takes its own name (``script.py`` -> ``SCRIPT``).
    """
    parts = rel_posix.split("/")
    words = parts[:-1] or [parts[-1].rsplit(".", 1)[0]]
    domain = "-".join(words).upper()
    return "".join(ch if ch.isalnum() else "-" for ch in domain).strip("-") or "MODULE"
 
 
def _derive_import_path(rel_posix: str) -> str:
    """Convert a relative posix path to a dotted Python import path (without .py)."""
    no_ext = rel_posix.replace(".py", "")
    return no_ext.replace("/", ".")
 
 
def _print_content(label: str, content: str) -> None:
    """Print generated file content with a visual frame."""
    print(f"\n--- {label} ---")
    print(content, end="")
    print("--- end ---")
 
 
def create_new_file(
    project_root: Path, path: str, force: bool,
    dry_run: bool = False, test: bool = False,
    verbose: bool = False,
) -> None:
    func = "create_new_file"
    _dbg("OCT-GENERATOR", func, "creating a new Option C file", 3)
    target = Path(path)
    if not target.is_absolute():
        target = project_root / target
 
    if target.suffix != ".py":
        raise click.ClickException(
            f"oct new only creates Python (.py) files. Got: '{target.suffix or '(no extension)'}'"
        )
 
    # Ensure the target is inside the project root.
    try:
        target.resolve().relative_to(project_root.resolve())
    except ValueError:
        raise click.ClickException(
            f"Target path {target} is outside the project root ({project_root}). "
            "Use a relative path or a path inside the project."
        )
 
    if target.exists() and not force:
        raise click.ClickException(f"File already exists: {target}")
 
    # Derive test file path
    test_target = None
    if test:
        test_target = project_root / "tests" / f"test_{target.stem}.py"
        if test_target.exists() and not force:
            raise click.ClickException(f"Test file already exists: {test_target}")
 
    # Build content (needed for both dry-run verbose preview and actual write)
    rel = target.relative_to(project_root).as_posix()
    header = _make_header(rel)
    main_content = header + DOCSTRING_TEMPLATE.format(domain=_derive_domain(rel)) + IMPORT_BLOCK
 
    test_content = None
    if test_target:
        test_rel = test_target.relative_to(project_root).as_posix()
        test_header = _make_header(test_rel)
        import_path = _derive_import_path(rel)
        test_docstring = TEST_DOCSTRING_TEMPLATE.format(module_name=target.stem)
        test_body = TEST_BODY_TEMPLATE.format(
            import_line=f"from {import_path} import *",
            stem=target.stem,
        )
        test_content = test_header + test_docstring + test_body
 
    if dry_run:
        if not target.parent.exists():
            print(f"[DRY RUN] Would create directory: {target.parent}")
        # Report __init__.py files that would be created
        current = target.parent
        while current != project_root and current != current.parent:
            try:
                current.relative_to(project_root)
            except ValueError:
                break
            init_file = current / "__init__.py"
            if not init_file.exists():
                print(f"[DRY RUN] Would create package marker: {init_file.relative_to(project_root)}")
            current = current.parent
        print(f"[DRY RUN] Would write file: {target}")
        if test_target:
            print(f"[DRY RUN] Would write test file: {test_target}")
        if verbose:
            _print_content(rel, main_content)
            if test_content:
                _print_content(test_rel, test_content)
        return
 
    target.parent.mkdir(parents=True, exist_ok=True)
 
    # Ensure __init__.py exists in all new package directories up to project root
    current = target.parent
    while current != project_root and current != current.parent:
        try:
            current.relative_to(project_root)
        except ValueError:
            break
        init_file = current / "__init__.py"
        if not init_file.exists():
            init_rel = init_file.relative_to(project_root).as_posix()
            init_file.write_text(
                _make_package_init_content(init_rel), encoding="utf-8"
            )
            print(f"  Created package marker: {init_file.relative_to(project_root)}")
        current = current.parent
 
    target.write_text(main_content, encoding="utf-8")
    print(f"Created Option C-compliant file: {target}")
    if verbose:
        _print_content(rel, main_content)
 
    # Generate companion test file
    if test_target and test_content:
        test_target.parent.mkdir(parents=True, exist_ok=True)
        test_target.write_text(test_content, encoding="utf-8")
        print(f"Created companion test file: {test_target}")
        if verbose:
            _print_content(test_rel, test_content)