1+ import os
2+
13from pydantic_ai import RunContext , Tool , Agent
24
35from codewiki .src .be .agent_tools .deps import CodeWikiDeps
6+ from codewiki .src .be .module_naming import normalize_sub_module_specs
47from codewiki .src .be .agent_tools .read_code_components import read_code_components_tool
58from codewiki .src .be .agent_tools .str_replace_editor import str_replace_editor_tool
69from codewiki .src .be .llm_services import create_fallback_models
@@ -20,25 +23,41 @@ async def generate_sub_module_documentation(
2023 """Delegate documentation generation of sub-modules to sub-agents. Each sub-module will be documented separately.
2124
2225 Args:
23- sub_module_specs: A dictionary mapping sub-module names to their core component IDs.
26+ sub_module_specs: A dictionary mapping sub-module names to their core component IDs.
2427 Example: {"authentication": ["auth_handler.py::AuthHandler", "auth_middleware.py::verify_token"], "database": ["db_client.py::DBClient", "models.py::UserModel"]}
2528 Each key is a descriptive sub-module name, and the value is a list of component IDs from the current module's core components that belong to that sub-module.
29+ Sub-module names must be unique across the whole wiki; a name that is already used by another
30+ module is automatically prefixed with the current module name, and the tool result reports the
31+ final file names actually saved.
2632 """
2733
2834 deps = ctx .deps
2935 previous_module_name = deps .current_module_name
30-
36+
3137 # Create fallback models from config
3238 fallback_models = create_fallback_models (deps .config )
3339
40+ # Resolve name collisions against the module tree and files already on disk
41+ # before touching the tree (issue #76): docs live in one flat directory.
42+ name_map = normalize_sub_module_specs (
43+ sub_module_specs ,
44+ previous_module_name ,
45+ deps .module_tree ,
46+ deps .absolute_docs_path ,
47+ )
48+ final_specs = {
49+ name_map [requested_name ]: core_component_ids
50+ for requested_name , core_component_ids in sub_module_specs .items ()
51+ }
52+
3453 # add the sub-module to the module tree
3554 value = deps .module_tree
3655 for key in deps .path_to_current_module :
3756 value = value [key ]["children" ]
38- for sub_module_name , core_component_ids in sub_module_specs .items ():
57+ for sub_module_name , core_component_ids in final_specs .items ():
3958 value [sub_module_name ] = {"components" : core_component_ids , "children" : {}}
40-
41- for sub_module_name , core_component_ids in sub_module_specs .items ():
59+
60+ for sub_module_name , core_component_ids in final_specs .items ():
4261
4362 # Create visual indentation for nested modules
4463 indent = " " * deps .current_depth
@@ -88,7 +107,23 @@ async def generate_sub_module_documentation(
88107 # restore the previous module name
89108 deps .current_module_name = previous_module_name
90109
91- return f"Generate successfully. Documentations: { ', ' .join ([key + '.md' for key in sub_module_specs .keys ()])} are saved in the working directory."
110+ # Report what actually landed on disk so the parent agent links real filenames.
111+ saved = []
112+ missing = []
113+ for requested_name , final_name in name_map .items ():
114+ entry = f"{ final_name } .md"
115+ if final_name != requested_name :
116+ entry += f" (requested '{ requested_name } ', renamed to avoid a collision)"
117+ if os .path .exists (os .path .join (deps .absolute_docs_path , f"{ final_name } .md" )):
118+ saved .append (entry )
119+ else :
120+ missing .append (entry )
121+
122+ report = f"Saved documentations: { ', ' .join (saved ) if saved else 'none' } ."
123+ if missing :
124+ report += f" MISSING (generation did not produce these files): { ', ' .join (missing )} ."
125+ logger .warning ("Sub-module documentation missing after generation: %s" , ", " .join (missing ))
126+ return report
92127
93128
94129generate_sub_module_documentation_tool = Tool (
0 commit comments