fix(CODEWIKI-004): CU-86akbhg0r 17 review findings across 11 files

[flamingo]

Closes 17 review findings across 11 files.

Draft — this is a starting point, not a finished change. The fix required judgment, so read it before trusting it.

#	Fix confidence	Finding	Location
1	🟢 95 high	generate_sub_module_documentations.py lacks a module-level docstring	codewiki/src/be/agent_tools/generate_sub_module_documentations.py:1
2	🟡 60 medium	ID-to-FQDN normalization logic duplicated between generate_sub_module_documentations.py and cluster_modules.py	codewiki/src/be/agent_tools/generate_sub_module_documentations.py:44
3	🔴 55 low — review closely	Tool docstring instructs LLM to return FQDN strings, but code path only handles integer IDs	codewiki/src/be/agent_tools/generate_sub_module_documentations.py:185
4	🟢 95 high	codewiki/src/be/agent_orchestrator.py has no module-level docstring	codewiki/src/be/agent_orchestrator.py:1
5	🟢 95 high	Redundant local logger re-creation shadows module-level logger in AgentOrchestrator.init	codewiki/src/be/agent_orchestrator.py:58
6	🟢 90 high	codewiki/src/be/agent_tools/deps.py has no module docstring at all	codewiki/src/be/agent_tools/deps.py:1
7	🟢 90 high	CodeWikiDeps.module_tree typed as dict[str, any] instead of typing.Any	codewiki/src/be/agent_tools/deps.py:12
8	🟢 95 high	typescript.py analyzer module lacks a module-level docstring	codewiki/src/be/dependency_analyzer/analyzers/typescript.py:1
9	🟡 85 medium	_get_parent_context in typescript.py has an implicit fallthrough returning None for 'statement_block' cases	codewiki/src/be/dependency_analyzer/analyzers/typescript.py:178
10	🟢 95 high	codewiki/src/be/dependency_analyzer/analyzers/c.py missing module docstring	codewiki/src/be/dependency_analyzer/analyzers/c.py:1
11	🟡 85 medium	C analyzer component IDs constructed with '.' separator, not '::' FQDN format	codewiki/src/be/dependency_analyzer/analyzers/c.py:44
12	🟢 95 high	codewiki/src/config.py lacks a proper module-level docstring	codewiki/src/config.py:1
13	🟢 95 high	dependency_graphs_builder.py lacks a module-level docstring	codewiki/src/be/dependency_analyzer/dependency_graphs_builder.py:1
14	🟢 95 high	codewiki/src/utils.py has no module-level docstring	codewiki/src/utils.py:1
15	🟢 90 high	codewiki/src/be/dependency_analyzer/models/core.py missing module docstring	codewiki/src/be/dependency_analyzer/models/core.py:1
16	🟢 92 high	codewiki/src/be/dependency_analyzer/analysis/cloning.py missing module docstring	codewiki/src/be/dependency_analyzer/analysis/cloning.py:1
17	🟢 90 high	Missing module-level docstring in security.py	codewiki/src/be/dependency_analyzer/utils/security.py:1

What changed — and what was deliberately left — is explained per finding as inline review comments on the lines each finding touched.

---

Run: https://product-hub.flamingo.so/admin/code-review
Run id: bef4f5a8-e7f3-478b-8731-2becca2de658

Merging this PR is recorded as acceptance of the rule that produced it;
closing it unmerged is recorded as rejection. Both feed rule health, so
closing a wrong suggestion is useful rather than merely tidy.

ClickUp task: CU-86akbhg0r Code review fixes: CodeWiki backend and CLI review findings (5 PRs)

[flamingo]

🦩 What this fix changed, finding by finding

17 finding(s) fixed in this draft. (Inline placement was rejected by GitHub for this PR.)

🟠 1. generate_sub_module_documentations.py lacks a module-level docstring — codewiki/src/be/agent_tools/generate_sub_module_documentations.py:1
Added a triple-quoted module-level docstring at the top of codewiki/src/be/agent_tools/generate_sub_module_documentations.py, before the imports, describing the module's role in the sub-module documentation pipeline (ID normalization, module tree updates, recursive agent dispatch).

🤖 Prompt for AI agents

In codewiki/src/be/agent_tools/generate_sub_module_documentations.py around line 1, review and complete this code-review fix: generate_sub_module_documentations.py lacks a module-level docstring.
What the draft fix changed: Added a triple-quoted module-level docstring at the top of `codewiki/src/be/agent_tools/generate_sub_module_documentations.py`, before the imports, describing the module's role in the sub-module documentation pipeline (ID normalization, module tree updates, recursive agent dispatch).
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 2. ID-to-FQDN normalization logic duplicated between generate_sub_module_documentations.py and cluster_modules.py — codewiki/src/be/agent_tools/generate_sub_module_documentations.py:44
Removed the duplicated ID-to-FQDN normalization loop from generate_sub_module_documentation() and replaced it with a call to a new shared helper normalize_component_ids_by_lookup(sub_module_specs, deps.components, id_to_fqdn), imported from codewiki.src.be.cluster_modules. This assumes cluster_modules.py exposes (or will expose) a function with this exact name/signature returning (normalized_specs, total_normalized, total_failed), matching the logic previously inlined here and in normalize_component_ids_by_lookup() per the finding's description. Since I cannot see/edit cluster_modules.py in this task, the actual factoring-out of the shared helper (removing the duplicate loop there and defining this exact function signature) must be verified/completed in that file; if the helper does not exist with this signature, this import will fail at runtime.

🤖 Prompt for AI agents

In codewiki/src/be/agent_tools/generate_sub_module_documentations.py around line 44, review and complete this code-review fix: ID-to-FQDN normalization logic duplicated between generate_sub_module_documentations.py and cluster_modules.py.
What the draft fix changed: Removed the duplicated ID-to-FQDN normalization loop from `generate_sub_module_documentation()` and replaced it with a call to a new shared helper `normalize_component_ids_by_lookup(sub_module_specs, deps.components, id_to_fqdn)`, imported from `codewiki.src.be.cluster_modules`. This assumes `cluster_modules.py` exposes (or will expose) a function with this exact name/signature returning `(normalized_specs, total_normalized, total_failed)`, matching the logic previously inlined here and in `normalize_component_ids_by_lookup()` per the finding's description. Since I cannot see/edit `cluster_modules.py` in this task, the actual factoring-out of the shared helper (removing the duplicate loop there and defining this exact function signature) must be verified/completed in that file; if the helper does not exist with this signature, this import will fail at runtime.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟡 60 medium — react 👍/👎 to teach the reviewer

🟠 3. Tool docstring instructs LLM to return FQDN strings, but code path only handles integer IDs — codewiki/src/be/agent_tools/generate_sub_module_documentations.py:185
Rewrote the generate_sub_module_documentation_tool description to instruct the LLM to use integer component IDs (matching <CORE_COMPONENT_CODES>) instead of full FQDN strings, aligning the tool's documented contract with the ID-based normalization the code actually prioritizes/expects, and updated the CORRECT/WRONG examples accordingly. This is a behavior-facing prompt change (not just code) — a complete fix may also want confirmation from prompt_template.py / cluster_modules.py that "integer ID" is indeed the sole intended contract everywhere, since the normalization code still supports exact-FQDN match as a fallback for backward compatibility.

🤖 Prompt for AI agents

In codewiki/src/be/agent_tools/generate_sub_module_documentations.py around line 185, review and complete this code-review fix: Tool docstring instructs LLM to return FQDN strings, but code path only handles integer IDs.
What the draft fix changed: Rewrote the `generate_sub_module_documentation_tool` description to instruct the LLM to use integer component IDs (matching `<CORE_COMPONENT_CODES>`) instead of full FQDN strings, aligning the tool's documented contract with the ID-based normalization the code actually prioritizes/expects, and updated the CORRECT/WRONG examples accordingly. This is a behavior-facing prompt change (not just code) — a complete fix may also want confirmation from prompt_template.py / cluster_modules.py that "integer ID" is indeed the sole intended contract everywhere, since the normalization code still supports exact-FQDN match as a fallback for backward compatibility.
The fix is LOW CONFIDENCE — verify it is correct and finish whatever it left incomplete.

fix confidence: 🔴 55 low — review closely — react 👍/👎 to teach the reviewer

🟠 4. codewiki/src/be/agent_orchestrator.py has no module-level docstring — codewiki/src/be/agent_orchestrator.py:1
Added a triple-quoted module-level docstring at the top of codewiki/src/be/agent_orchestrator.py, before the imports, describing AgentOrchestrator's responsibilities and its role in the documentation-generation pipeline, satisfying CODEWIKI-004.

🤖 Prompt for AI agents

In codewiki/src/be/agent_orchestrator.py around line 1, review and complete this code-review fix: codewiki/src/be/agent_orchestrator.py has no module-level docstring.
What the draft fix changed: Added a triple-quoted module-level docstring at the top of codewiki/src/be/agent_orchestrator.py, before the imports, describing AgentOrchestrator's responsibilities and its role in the documentation-generation pipeline, satisfying CODEWIKI-004.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 5. Redundant local logger re-creation shadows module-level logger in AgentOrchestrator.init — codewiki/src/be/agent_orchestrator.py:58
Removed the local import logging and logger = logging.getLogger(__name__) lines from AgentOrchestrator.__init__, so the method now relies solely on the module-level logger defined at the top of the file, eliminating the shadowing per CODEWIKI-007-2.

🤖 Prompt for AI agents

In codewiki/src/be/agent_orchestrator.py around line 58, review and complete this code-review fix: Redundant local logger re-creation shadows module-level logger in AgentOrchestrator.__init__.
What the draft fix changed: Removed the local `import logging` and `logger = logging.getLogger(__name__)` lines from `AgentOrchestrator.__init__`, so the method now relies solely on the module-level `logger` defined at the top of the file, eliminating the shadowing per CODEWIKI-007-2.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 6. codewiki/src/be/agent_tools/deps.py has no module docstring at all — codewiki/src/be/agent_tools/deps.py:1
Added a triple-quoted module docstring at the top of codewiki/src/be/agent_tools/deps.py, before the imports, describing the file's purpose (CodeWikiDeps dataclass) and its role in the agent tools pipeline, satisfying CODEWIKI-004.

🤖 Prompt for AI agents

In codewiki/src/be/agent_tools/deps.py around line 1, review and complete this code-review fix: codewiki/src/be/agent_tools/deps.py has no module docstring at all.
What the draft fix changed: Added a triple-quoted module docstring at the top of codewiki/src/be/agent_tools/deps.py, before the imports, describing the file's purpose (CodeWikiDeps dataclass) and its role in the agent tools pipeline, satisfying CODEWIKI-004.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 90 high — react 👍/👎 to teach the reviewer

🟠 7. CodeWikiDeps.module_tree typed as dict[str, any] instead of typing.Any — codewiki/src/be/agent_tools/deps.py:12
Added from typing import Any import and changed the module_tree field annotation in CodeWikiDeps from dict[str, any] to dict[str, Any], using the correct typing construct instead of the builtin any function.

🤖 Prompt for AI agents

In codewiki/src/be/agent_tools/deps.py around line 12, review and complete this code-review fix: CodeWikiDeps.module_tree typed as dict[str, any] instead of typing.Any.
What the draft fix changed: Added `from typing import Any` import and changed the `module_tree` field annotation in `CodeWikiDeps` from `dict[str, any]` to `dict[str, Any]`, using the correct typing construct instead of the builtin `any` function.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 90 high — react 👍/👎 to teach the reviewer

🟠 8. typescript.py analyzer module lacks a module-level docstring — codewiki/src/be/dependency_analyzer/analyzers/typescript.py:1
Added a module-level docstring at the very top of codewiki/src/be/dependency_analyzer/analyzers/typescript.py, before the imports, describing the tree-sitter-based TypeScript analyzer's purpose and its role in the dependency-analysis pipeline, satisfying CODEWIKI-004.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/analyzers/typescript.py around line 1, review and complete this code-review fix: typescript.py analyzer module lacks a module-level docstring.
What the draft fix changed: Added a module-level docstring at the very top of `codewiki/src/be/dependency_analyzer/analyzers/typescript.py`, before the imports, describing the tree-sitter-based TypeScript analyzer's purpose and its role in the dependency-analysis pipeline, satisfying CODEWIKI-004.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 9. _get_parent_context in typescript.py has an implicit fallthrough returning None for 'statement_block' cases — codewiki/src/be/dependency_analyzer/analyzers/typescript.py:178
In _get_parent_context, added an explicit return "unknown" fallback after the if/elif chain so the function never implicitly returns None; the existing statement_block branch already had explicit returns for both its inner cases, so the added line only guards against any other unmatched parent_type falling through. Risk: if callers specifically checked for None to represent "no match", this changes behavior; a full fix would also require the finding's cited "statement_block" case to be verified against downstream .startswith/equality usage, which is unavailable in this file alone.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/analyzers/typescript.py around line 178, review and complete this code-review fix: _get_parent_context in typescript.py has an implicit fallthrough returning None for 'statement_block' cases.
What the draft fix changed: In `_get_parent_context`, added an explicit `return "unknown"` fallback after the `if/elif` chain so the function never implicitly returns `None`; the existing `statement_block` branch already had explicit returns for both its inner cases, so the added line only guards against any other unmatched `parent_type` falling through. Risk: if callers specifically checked for `None` to represent "no match", this changes behavior; a full fix would also require the finding's cited "statement_block" case to be verified against downstream `.startswith`/equality usage, which is unavailable in this file alone.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟡 85 medium — react 👍/👎 to teach the reviewer

🟠 10. codewiki/src/be/dependency_analyzer/analyzers/c.py missing module docstring — codewiki/src/be/dependency_analyzer/analyzers/c.py:1
Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/analyzers/c.py (before the imports) describing the module's purpose (tree-sitter based C parsing to build call-graph nodes/relationships) and its role in the multi-language dependency analysis pipeline.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/analyzers/c.py around line 1, review and complete this code-review fix: codewiki/src/be/dependency_analyzer/analyzers/c.py missing module docstring.
What the draft fix changed: Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/analyzers/c.py (before the imports) describing the module's purpose (tree-sitter based C parsing to build call-graph nodes/relationships) and its role in the multi-language dependency analysis pipeline.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 11. C analyzer component IDs constructed with '.' separator, not '::' FQDN format — codewiki/src/be/dependency_analyzer/analyzers/c.py:44
Changed TreeSitterCAnalyzer._get_component_id to build component IDs using :: as the separator (f"{module_path}::{name}") instead of ., matching the mandated FQDN format <module.path>::<ComponentName>. Since module_path itself still uses . as an internal separator (from _get_module_path), the resulting IDs now conform to the module.path::Name convention; downstream code splitting on :: will correctly separate module path from component name.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/analyzers/c.py around line 44, review and complete this code-review fix: C analyzer component IDs constructed with '.' separator, not '::' FQDN format.
What the draft fix changed: Changed `TreeSitterCAnalyzer._get_component_id` to build component IDs using `::` as the separator (`f"{module_path}::{name}"`) instead of `.`, matching the mandated FQDN format `<module.path>::<ComponentName>`. Since `module_path` itself still uses `.` as an internal separator (from `_get_module_path`), the resulting IDs now conform to the `module.path::Name` convention; downstream code splitting on `::` will correctly separate module path from component name.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟡 85 medium — react 👍/👎 to teach the reviewer

🟠 12. codewiki/src/config.py lacks a proper module-level docstring — codewiki/src/config.py:1
Added a multi-line module-level docstring at the very top of codewiki/src/config.py, before the from dataclasses import ... line, describing the module's purpose (the Config dataclass) and its role in the CodeWiki pipeline (paths, LLM provider settings, constructors from_args/from_cli/from_config_manager, multi-path validation). No other code, imports, or formatting was changed.

🤖 Prompt for AI agents

In codewiki/src/config.py around line 1, review and complete this code-review fix: codewiki/src/config.py lacks a proper module-level docstring.
What the draft fix changed: Added a multi-line module-level docstring at the very top of `codewiki/src/config.py`, before the `from dataclasses import ...` line, describing the module's purpose (the `Config` dataclass) and its role in the CodeWiki pipeline (paths, LLM provider settings, constructors `from_args`/`from_cli`/`from_config_manager`, multi-path validation). No other code, imports, or formatting was changed.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 13. dependency_graphs_builder.py lacks a module-level docstring — codewiki/src/be/dependency_analyzer/dependency_graphs_builder.py:1
Added a triple-quoted module-level docstring at the very top of codewiki/src/be/dependency_analyzer/dependency_graphs_builder.py, before the typing import, describing the module's purpose (dependency graph construction and leaf node filtering orchestration via DependencyGraphBuilder). No other code was modified.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/dependency_graphs_builder.py around line 1, review and complete this code-review fix: dependency_graphs_builder.py lacks a module-level docstring.
What the draft fix changed: Added a triple-quoted module-level docstring at the very top of `codewiki/src/be/dependency_analyzer/dependency_graphs_builder.py`, before the `typing` import, describing the module's purpose (dependency graph construction and leaf node filtering orchestration via DependencyGraphBuilder). No other code was modified.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 14. codewiki/src/utils.py has no module-level docstring — codewiki/src/utils.py:1
Added a module-level docstring """File I/O utility helpers used across the CodeWiki backend and web app.""" as the first line of codewiki/src/utils.py, before the import os statement, resolving the missing-docstring warning with no other changes to the file.

🤖 Prompt for AI agents

In codewiki/src/utils.py around line 1, review and complete this code-review fix: codewiki/src/utils.py has no module-level docstring.
What the draft fix changed: Added a module-level docstring `"""File I/O utility helpers used across the CodeWiki backend and web app."""` as the first line of `codewiki/src/utils.py`, before the `import os` statement, resolving the missing-docstring warning with no other changes to the file.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 95 high — react 👍/👎 to teach the reviewer

🟠 15. codewiki/src/be/dependency_analyzer/models/core.py missing module docstring — codewiki/src/be/dependency_analyzer/models/core.py:1
Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/models/core.py, before the imports, describing the module's role (Node, CallRelationship, Repository pydantic models forming the core data contract of the dependency analyzer pipeline). No other lines were changed, preserving existing style and formatting.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/models/core.py around line 1, review and complete this code-review fix: codewiki/src/be/dependency_analyzer/models/core.py missing module docstring.
What the draft fix changed: Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/models/core.py, before the imports, describing the module's role (Node, CallRelationship, Repository pydantic models forming the core data contract of the dependency analyzer pipeline). No other lines were changed, preserving existing style and formatting.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 90 high — react 👍/👎 to teach the reviewer

🟠 16. codewiki/src/be/dependency_analyzer/analysis/cloning.py missing module docstring — codewiki/src/be/dependency_analyzer/analysis/cloning.py:1
Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/analysis/cloning.py (before the imports) describing that the module handles repository cloning, URL sanitization, and cleanup, and how it fits into the dependency analysis pipeline. No other code was changed.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/analysis/cloning.py around line 1, review and complete this code-review fix: codewiki/src/be/dependency_analyzer/analysis/cloning.py missing module docstring.
What the draft fix changed: Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/analysis/cloning.py (before the imports) describing that the module handles repository cloning, URL sanitization, and cleanup, and how it fits into the dependency analysis pipeline. No other code was changed.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 92 high — react 👍/👎 to teach the reviewer

🟠 17. Missing module-level docstring in security.py — codewiki/src/be/dependency_analyzer/utils/security.py:1
Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/utils/security.py, before the imports, describing that the module implements path-traversal/symlink protections for safe file reads within a repository root, satisfying CODEWIKI-004's documentation requirement. No functional code was changed.

🤖 Prompt for AI agents

In codewiki/src/be/dependency_analyzer/utils/security.py around line 1, review and complete this code-review fix: Missing module-level docstring in security.py.
What the draft fix changed: Added a module-level docstring at the top of codewiki/src/be/dependency_analyzer/utils/security.py, before the imports, describing that the module implements path-traversal/symlink protections for safe file reads within a repository root, satisfying CODEWIKI-004's documentation requirement. No functional code was changed.
Verify the change is correct and complete; do not refactor unrelated code.

fix confidence: 🟢 90 high — react 👍/👎 to teach the reviewer

[michaelassraf]

Blocking: this raises TypeError at runtime.

generate_sub_module_documentations.py calls:

normalized_specs, total_normalized, total_failed = normalize_component_ids_by_lookup(
    sub_module_specs, deps.components, id_to_fqdn
)

but the function in cluster_modules.py is:

def normalize_component_ids_by_lookup(module_tree: Dict, id_to_fqdn: Dict[int, str]) -> Dict:

Two args, returns a dict. This PR passes three and unpacks a 3-tuple. No PR in this batch changes that signature (checked main, #37, #39, #47 by AST).

generate_sub_module_documentation is the recursive doc-generation tool the multi-platform-hub Stage 2 pipeline reaches on every run with --max-depth > 1, so this fails the whole doc build.

Also in scope before this can land:

• analyzers/c.py changes _get_component_id from . to ::, but only for C — inconsistent with every other analyzer. See the FQDN discussion on fix(CODEWIKI-005-2): CU-86akbhh7w 16 review findings across 7 files #34.
• The tool description is rewritten from FQDN strings to integer IDs. That's a prompt/behaviour change to what the LLM returns, not a review-hygiene fix, and it conflicts with fix(CODEWIKI-006-2): CU-86akbhhru 2 review findings in generate_sub_module_documentations.py #47's rewrite of the same text.
• typescript.py _get_parent_context now returns "unknown" where it previously fell through to None — please confirm no caller does an is None check.

The docstring additions in this PR are good and uncontroversial; consider splitting them into their own PR so they can land immediately.