rectify_folder_docs.py

import argparse
import os
from datetime import datetime
from pathlib import Path

AGENTS_TEMPLATE = """# {module_name} Agents — Local Coordination

**Version**: v1.0.0 | **Status**: Active | **Last Updated**: {date}

## Purpose

Coordination and navigation hub for agents interacting with `{module_name}`.

## Operating Contracts

- **Respect Modularity**: Changes must not break external boundaries.
- **Maintain Documentation Alignment**: Keep all documentation synced with code logic.
- **Traceability**: Leave structured tracks for upstream orchestration agents.
"""

README_TEMPLATE = """# {module_name}

Internal module for the Codomyrmex ecosystem.

## Overview

This directory provides functionality and resources for `{module_name}`. Follow the project's standard modular practices when adding or modifying code within this namespace.
"""

SPEC_TEMPLATE = """# {module_name} Specification

## 1. Description

Functional and technical requirements for the `{module_name}` module.

## 2. Core Capabilities

- Adherence to Zero-Mock implementation standards.
- Modular self-containment for reliable orchestrator interaction.
"""


def extract_module_name(path_str):
    name = os.path.basename(path_str)
    if name in {"src", "codomyrmex", "projects"}:
        return path_str.split("/")[-1]
    return name.replace("_", " ").title()


def rectify_docs(start_path):
    start_dir = Path(start_path)
    if not start_dir.exists():
        return

    today = datetime.now().strftime("%B %Y")

    for root, dirs, files in os.walk(start_dir):
        # Prevent recursion into ignored folders
        dirs[:] = [
            d
            for d in dirs
            if d
            not in (
                ".git",
                "__pycache__",
                ".pytest_cache",
                ".venv",
                ".github",
                "node_modules",
                ".mypy_cache",
                "docs",
                "documentation",
            )
        ]

        # Don't touch the docs_gen generated outputs
        if "/documentation/" in root:
            continue

        current_dir = Path(root)

        has_py = any(f.endswith(".py") for f in files)
        has_agents = "AGENTS.md" in files
        has_readme = "README.md" in files
        has_spec = "SPEC.md" in files

        # We process directories possessing existing markdown files (even if stub) or code, to ensure enforcement
        if not (has_py or has_agents or has_readme or has_spec):
            # Also if it's an interior directory in `agents` we should probably document it
            if "/agents/" in root or "/daf-consulting/" in root:
                pass
            else:
                continue

        module_name = extract_module_name(root)

        paths = [
            (current_dir / "AGENTS.md", AGENTS_TEMPLATE, has_agents),
            (current_dir / "README.md", README_TEMPLATE, has_readme),
            (current_dir / "SPEC.md", SPEC_TEMPLATE, has_spec),
        ]

        for file_path, template, exists in paths:
            if not exists:
                print(
                    f"Creating missing {file_path.name} in {current_dir.relative_to(start_dir.parent)}"
                )
                # Fill in template values
                content = template.format(module_name=module_name, date=today)
                file_path.write_text(content, encoding="utf-8")
            else:
                # Check for stub
                content = file_path.read_text(encoding="utf-8")
                if len(content.strip()) < 50:
                    print(
                        f"Replacing stub {file_path.name} in {current_dir.relative_to(start_dir.parent)}"
                    )
                    content = template.format(module_name=module_name, date=today)
                    file_path.write_text(content, encoding="utf-8")


def main():
    parser = argparse.ArgumentParser(
        description="Rectify stub folder docs for selected Codomyrmex trees."
    )
    parser.add_argument(
        "--repo-root",
        type=Path,
        default=Path.cwd(),
        help="Repository root. Defaults to the current working directory.",
    )
    args = parser.parse_args()
    repo_root = args.repo_root.resolve()

    print("Running Doc Rectification...")
    rectify_docs(f"{repo_root}/src/codomyrmex")
    rectify_docs(f"{repo_root}/projects")
    print("Done")


if __name__ == "__main__":
    main()