-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathrectify_folder_docs.py
More file actions
142 lines (109 loc) Β· 4.34 KB
/
rectify_folder_docs.py
File metadata and controls
142 lines (109 loc) Β· 4.34 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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()