Fix ruff findings in files touched by artifact-aware generation

CI lints every changed Python file in full, so pre-existing findings in the
files this branch touches also fail the check. Apply ruff's safe fixes and
formatting (pep585/pep604 annotations, import ordering, regex flag aliases)
and resolve the rest by hand without behaviour changes:

- blind `except Exception` sites get `# noqa: BLE001` with the reason, as the
  codebase already does elsewhere; bare `except:` becomes `except Exception`
- subprocess.run calls pass `check=False` and use `capture_output=True`
- dead assignments removed (`repo_name`, `filtered_folders_path`,
  `generation_time`, `start_time`, `generation_options`, `current_branch`)
  along with the imports they kept alive
- mutable default arguments in `cluster_modules()` become `None` and are
  normalised at the top of the function
- nested ifs merged, `endswith` tuple, needless-bool return, loop-variable
  closure in the package.json exports walker takes explicit parameters
- shebang removed from the non-executable str_replace_editor module

Author: anhnh2002

codewiki/cli/adapters/doc_generator.py

@@ -6,104 +6,108 @@
 to the backend Config class when running documentation generation.
 """
 
-from dataclasses import dataclass, asdict, field
-from typing import Optional, List
-from pathlib import Path
+from dataclasses import dataclass, field
 
 from codewiki.cli.utils.validation import (
-    validate_url,
-    validate_api_key,
     validate_model_name,
+    validate_url,
 )
 
 
 @dataclass
 class AgentInstructions:
     """
     Custom instructions for the documentation agent.
-    
+
     Allows users to customize:
     - File filtering (include/exclude patterns)
     - Module focus (prioritize certain modules)
     - Documentation type (API docs, architecture docs, etc.)
     - Custom instructions for the LLM
-    
+
     Attributes:
         include_patterns: File patterns to include (e.g., ["*.cs", "*.py"])
         exclude_patterns: File/directory patterns to exclude (e.g., ["*Tests*", "*test*"])
         focus_modules: Modules to document in more detail
         doc_type: Type of documentation to generate
         custom_instructions: Additional instructions for the documentation agent
     """
-    include_patterns: Optional[List[str]] = None  # e.g., ["*.cs"] for C# projects
-    exclude_patterns: Optional[List[str]] = None  # e.g., ["*Tests*", "*Specs*"]
-    focus_modules: Optional[List[str]] = None  # e.g., ["src/core", "src/api"]
-    doc_type: Optional[str] = None  # e.g., "api", "architecture", "user-guide"
-    custom_instructions: Optional[str] = None  # Free-form instructions
-    artifact_exclude: Optional[List[str]] = None  # e.g., ["docker/data/*"] skipped by artifact analysis
-    
+
+    include_patterns: list[str] | None = None  # e.g., ["*.cs"] for C# projects
+    exclude_patterns: list[str] | None = None  # e.g., ["*Tests*", "*Specs*"]
+    focus_modules: list[str] | None = None  # e.g., ["src/core", "src/api"]
+    doc_type: str | None = None  # e.g., "api", "architecture", "user-guide"
+    custom_instructions: str | None = None  # Free-form instructions
+    artifact_exclude: list[str] | None = (
+        None  # e.g., ["docker/data/*"] skipped by artifact analysis
+    )
+
     def to_dict(self) -> dict:
         """Convert to dictionary, excluding None values."""
         result = {}
         if self.include_patterns:
-            result['include_patterns'] = self.include_patterns
+            result["include_patterns"] = self.include_patterns
         if self.exclude_patterns:
-            result['exclude_patterns'] = self.exclude_patterns
+            result["exclude_patterns"] = self.exclude_patterns
         if self.artifact_exclude:
-            result['artifact_exclude'] = self.artifact_exclude
+            result["artifact_exclude"] = self.artifact_exclude
         if self.focus_modules:
-            result['focus_modules'] = self.focus_modules
+            result["focus_modules"] = self.focus_modules
         if self.doc_type:
-            result['doc_type'] = self.doc_type
+            result["doc_type"] = self.doc_type
         if self.custom_instructions:
-            result['custom_instructions'] = self.custom_instructions
+            result["custom_instructions"] = self.custom_instructions
         return result
-    
+
     @classmethod
-    def from_dict(cls, data: dict) -> 'AgentInstructions':
+    def from_dict(cls, data: dict) -> "AgentInstructions":
         """Create AgentInstructions from dictionary."""
         return cls(
-            include_patterns=data.get('include_patterns'),
-            exclude_patterns=data.get('exclude_patterns'),
-            focus_modules=data.get('focus_modules'),
-            doc_type=data.get('doc_type'),
-            custom_instructions=data.get('custom_instructions'),
-            artifact_exclude=data.get('artifact_exclude'),
+            include_patterns=data.get("include_patterns"),
+            exclude_patterns=data.get("exclude_patterns"),
+            focus_modules=data.get("focus_modules"),
+            doc_type=data.get("doc_type"),
+            custom_instructions=data.get("custom_instructions"),
+            artifact_exclude=data.get("artifact_exclude"),
         )
-    
+
     def is_empty(self) -> bool:
         """Check if all fields are empty/None."""
-        return not any([
-            self.include_patterns,
-            self.exclude_patterns,
-            self.artifact_exclude,
-            self.focus_modules,
-            self.doc_type,
-            self.custom_instructions,
-        ])
-    
+        return not any(
+            [
+                self.include_patterns,
+                self.exclude_patterns,
+                self.artifact_exclude,
+                self.focus_modules,
+                self.doc_type,
+                self.custom_instructions,
+            ]
+        )
+
     def get_prompt_addition(self) -> str:
         """Generate prompt additions based on instructions."""
         additions = []
-        
+
         if self.doc_type:
             doc_type_instructions = {
-                'api': "Focus on API documentation: endpoints, parameters, return types, and usage examples.",
-                'architecture': "Focus on architecture documentation: system design, component relationships, and data flow.",
-                'user-guide': "Focus on user guide documentation: how to use features, step-by-step tutorials.",
-                'developer': "Focus on developer documentation: code structure, contribution guidelines, and implementation details.",
+                "api": "Focus on API documentation: endpoints, parameters, return types, and usage examples.",
+                "architecture": "Focus on architecture documentation: system design, component relationships, and data flow.",
+                "user-guide": "Focus on user guide documentation: how to use features, step-by-step tutorials.",
+                "developer": "Focus on developer documentation: code structure, contribution guidelines, and implementation details.",
             }
             if self.doc_type.lower() in doc_type_instructions:
                 additions.append(doc_type_instructions[self.doc_type.lower()])
             else:
                 additions.append(f"Focus on generating {self.doc_type} documentation.")
-        
+
         if self.focus_modules:
-            additions.append(f"Pay special attention to and provide more detailed documentation for these modules: {', '.join(self.focus_modules)}")
-        
+            additions.append(
+                f"Pay special attention to and provide more detailed documentation for these modules: {', '.join(self.focus_modules)}"
+            )
+
         if self.custom_instructions:
             additions.append(f"Additional instructions: {self.custom_instructions}")
-        
+
         return "\n".join(additions) if additions else ""
 
 
@@ -130,6 +134,7 @@ class Configuration:
         prompt_caching: Add prompt-cache breakpoints to agentic LLM calls (default: True)
         agent_instructions: Custom agent instructions for documentation generation
     """
+
     base_url: str
     main_model: str
     cluster_model: str
@@ -146,7 +151,7 @@ class Configuration:
     use_gitignore: bool = True
     prompt_caching: bool = True
     agent_instructions: AgentInstructions = field(default_factory=AgentInstructions)
-    
+
     def validate(self):
         """
         Validate all configuration fields.
@@ -158,71 +163,72 @@ def validate(self):
             ConfigurationError: If validation fails
         """
         from codewiki.src.be.backend import is_caw_provider
+
         if is_caw_provider(self.provider):
             validate_model_name(self.main_model)
             return
         validate_url(self.base_url)
         validate_model_name(self.main_model)
         validate_model_name(self.cluster_model)
         validate_model_name(self.fallback_model)
-    
+
     def to_dict(self) -> dict:
         """Convert to dictionary."""
         result = {
-            'base_url': self.base_url,
-            'main_model': self.main_model,
-            'cluster_model': self.cluster_model,
-            'default_output': self.default_output,
-            'provider': self.provider,
-            'aws_region': self.aws_region,
-            'api_version': self.api_version,
-            'azure_deployment': self.azure_deployment,
-            'max_tokens': self.max_tokens,
-            'max_token_per_module': self.max_token_per_module,
-            'max_token_per_leaf_module': self.max_token_per_leaf_module,
-            'max_depth': self.max_depth,
-            'use_gitignore': self.use_gitignore,
-            'prompt_caching': self.prompt_caching,
-            'fallback_model': self.fallback_model,
+            "base_url": self.base_url,
+            "main_model": self.main_model,
+            "cluster_model": self.cluster_model,
+            "default_output": self.default_output,
+            "provider": self.provider,
+            "aws_region": self.aws_region,
+            "api_version": self.api_version,
+            "azure_deployment": self.azure_deployment,
+            "max_tokens": self.max_tokens,
+            "max_token_per_module": self.max_token_per_module,
+            "max_token_per_leaf_module": self.max_token_per_leaf_module,
+            "max_depth": self.max_depth,
+            "use_gitignore": self.use_gitignore,
+            "prompt_caching": self.prompt_caching,
+            "fallback_model": self.fallback_model,
         }
         if self.agent_instructions and not self.agent_instructions.is_empty():
-            result['agent_instructions'] = self.agent_instructions.to_dict()
+            result["agent_instructions"] = self.agent_instructions.to_dict()
         return result
-    
+
     @classmethod
-    def from_dict(cls, data: dict) -> 'Configuration':
+    def from_dict(cls, data: dict) -> "Configuration":
         """
         Create Configuration from dictionary.
-        
+
         Args:
             data: Configuration dictionary
-            
+
         Returns:
             Configuration instance
         """
         agent_instructions = AgentInstructions()
-        if 'agent_instructions' in data:
-            agent_instructions = AgentInstructions.from_dict(data['agent_instructions'])
-        
+        if "agent_instructions" in data:
+            agent_instructions = AgentInstructions.from_dict(data["agent_instructions"])
+
         return cls(
-            base_url=data.get('base_url', ''),
-            main_model=data.get('main_model', ''),
-            cluster_model=data.get('cluster_model', ''),
-            fallback_model=data.get('fallback_model', 'glm-4p5'),
-            default_output=data.get('default_output', 'docs'),
-            provider=data.get('provider', 'openai-compatible'),
-            aws_region=data.get('aws_region', 'us-east-1'),
-            api_version=data.get('api_version', '2024-12-01-preview'),
-            azure_deployment=data.get('azure_deployment', ''),
-            max_tokens=data.get('max_tokens', 32768),
-            max_token_per_module=data.get('max_token_per_module', 36369),
-            max_token_per_leaf_module=data.get('max_token_per_leaf_module', 16000),
-            max_depth=data.get('max_depth', 2),
-            use_gitignore=data.get('use_gitignore', True),
-            prompt_caching=data.get('prompt_caching', True),
+            base_url=data.get("base_url", ""),
+            main_model=data.get("main_model", ""),
+            cluster_model=data.get("cluster_model", ""),
+            fallback_model=data.get("fallback_model", "glm-4p5"),
+            default_output=data.get("default_output", "docs"),
+            provider=data.get("provider", "openai-compatible"),
+            aws_region=data.get("aws_region", "us-east-1"),
+            api_version=data.get("api_version", "2024-12-01-preview"),
+            azure_deployment=data.get("azure_deployment", ""),
+            max_tokens=data.get("max_tokens", 32768),
+            max_token_per_module=data.get("max_token_per_module", 36369),
+            max_token_per_leaf_module=data.get("max_token_per_leaf_module", 16000),
+            max_depth=data.get("max_depth", 2),
+            use_gitignore=data.get("use_gitignore", True),
+            prompt_caching=data.get("prompt_caching", True),
             agent_instructions=agent_instructions,
         )
-    
+
     def is_complete(self) -> bool:
         """Check if all required fields are set.
 
@@ -231,45 +237,53 @@ def is_complete(self) -> bool:
         are unused.
         """
         from codewiki.src.be.backend import is_caw_provider
+
         if is_caw_provider(self.provider):
             return bool(self.main_model)
         return bool(
-            self.base_url and
-            self.main_model and
-            self.cluster_model and
-            self.fallback_model
+            self.base_url and self.main_model and self.cluster_model and self.fallback_model
         )
-    
-    def to_backend_config(self, repo_path: str, output_dir: str, api_key: str, runtime_instructions: AgentInstructions = None):
+
+    def to_backend_config(
+        self,
+        repo_path: str,
+        output_dir: str,
+        api_key: str,
+        runtime_instructions: AgentInstructions = None,
+    ):
         """
         Convert CLI Configuration to Backend Config.
-        
+
         This method bridges the gap between persistent user settings (CLI Configuration)
         and runtime job configuration (Backend Config).
-        
+
         Args:
             repo_path: Path to the repository to document
             output_dir: Output directory for generated documentation
             api_key: LLM API key (from keyring)
             runtime_instructions: Runtime agent instructions (override persistent settings)
-            
+
         Returns:
             Backend Config instance ready for documentation generation
         """
         from codewiki.src.config import Config
-        
+
         # Merge runtime instructions with persistent settings
         # Runtime instructions take precedence
         final_instructions = self.agent_instructions
         if runtime_instructions and not runtime_instructions.is_empty():
             final_instructions = AgentInstructions(
-                include_patterns=runtime_instructions.include_patterns or self.agent_instructions.include_patterns,
-                exclude_patterns=runtime_instructions.exclude_patterns or self.agent_instructions.exclude_patterns,
-                focus_modules=runtime_instructions.focus_modules or self.agent_instructions.focus_modules,
+                include_patterns=runtime_instructions.include_patterns
+                or self.agent_instructions.include_patterns,
+                exclude_patterns=runtime_instructions.exclude_patterns
+                or self.agent_instructions.exclude_patterns,
+                focus_modules=runtime_instructions.focus_modules
+                or self.agent_instructions.focus_modules,
                 doc_type=runtime_instructions.doc_type or self.agent_instructions.doc_type,
-                custom_instructions=runtime_instructions.custom_instructions or self.agent_instructions.custom_instructions,
+                custom_instructions=runtime_instructions.custom_instructions
+                or self.agent_instructions.custom_instructions,
             )
-        
+
         return Config.from_cli(
             repo_path=repo_path,
             output_dir=output_dir,