code2llm 0.5.155__tar.gz → 0.5.156__tar.gz

{code2llm-0.5.155/code2llm.egg-info → code2llm-0.5.156}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code2llm
-Version: 0.5.155
+Version: 0.5.156
 Summary: High-performance Python code flow analysis with optimized TOON format - CFG, DFG, call graphs, and intelligent code queries
 Home-page: https://github.com/wronai/stts
 Author: STTS Project
@@ -66,13 +66,13 @@ Dynamic: requires-python
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.155-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-79.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.156-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-79.7h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (208 commits)
-- 👤 **Human dev:** ~$7906 (79.1h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (211 commits)
+- 👤 **Human dev:** ~$7972 (79.7h @ $100/h, 30min dedup)
 
-Generated on 2026-05-24 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-05-25 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 

{code2llm-0.5.155 → code2llm-0.5.156}/README.md

@@ -2,13 +2,13 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.155-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-79.1h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.156-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-79.7h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (208 commits)
-- 👤 **Human dev:** ~$7906 (79.1h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (211 commits)
+- 👤 **Human dev:** ~$7972 (79.7h @ $100/h, 30min dedup)
 
-Generated on 2026-05-24 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-05-25 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 

code2llm-0.5.156/VERSION

@@ -0,0 +1 @@
+0.5.156

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/__init__.py

@@ -8,7 +8,7 @@ Includes NLP Processing Pipeline for query normalization, intent matching,
 and entity resolution with multilingual support.
 """
 
-__version__ = "0.5.155"
+__version__ = "0.5.156"
 __author__ = "STTS Project"
 
 # Core analysis components (lightweight, always needed)

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/analysis/pipeline_detector.py

@@ -63,9 +63,11 @@ class Pipeline:
 
     @property
     def purity_ratio(self) -> float:
+        """Fraction of stages that are free of side effects."""
         return self.pure_count / self.total_stages if self.total_stages else 0.0
 
     def to_dict(self) -> Dict[str, Any]:
+        """Serialise the Pipeline to a plain dict."""
         return {
             "name": self.name,
             "domain": self.domain,
@@ -125,6 +127,7 @@ class PipelineDetector:
         type_engine: Optional[TypeInferenceEngine] = None,
         side_effect_detector: Optional[SideEffectDetector] = None,
     ):
+        """Initialise with optional shared type engine and side-effect detector."""
         self._type_engine = type_engine or TypeInferenceEngine()
         self._se_detector = side_effect_detector or SideEffectDetector()
         self._resolver = PipelineResolver()

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/cli_analysis.py

@@ -283,6 +283,15 @@ def _merge_chunked_results(all_results, source_path: Path):
 
     merged = AnalysisResult(project_path=str(source_path))
 
+    # Track seen (file, simple_name) pairs to deduplicate overlapping chunk scopes.
+    # When the splitter assigns the same directory to multiple chunks (e.g. root and
+    # batch_1 both point at the project root), the same class/function would otherwise
+    # appear multiple times in the merged result and trigger false-positive duplicate
+    # detection in the TOON exporter.
+    _seen_funcs: set = set()
+    _seen_classes: set = set()
+    _seen_modules: set = set()
+
     for name, result, output_dir in all_results:
         if not result:
             continue
@@ -290,14 +299,26 @@ def _merge_chunked_results(all_results, source_path: Path):
         prefix = f"{name}."
 
         for func_name, func_info in result.functions.items():
+            dedup_key = (func_info.file, func_info.name)
+            if dedup_key in _seen_funcs:
+                continue
+            _seen_funcs.add(dedup_key)
             new_name = f"{prefix}{func_name}" if "." not in func_name else func_name
             merged.functions[new_name] = func_info
 
         for class_name, class_info in result.classes.items():
+            dedup_key = (class_info.file, class_info.name)
+            if dedup_key in _seen_classes:
+                continue
+            _seen_classes.add(dedup_key)
             new_name = f"{prefix}{class_name}" if "." not in class_name else class_name
             merged.classes[new_name] = class_info
 
         for mod_name, mod_info in result.modules.items():
+            dedup_key = (mod_info.file, mod_info.name)
+            if dedup_key in _seen_modules:
+                continue
+            _seen_modules.add(dedup_key)
             new_name = f"{prefix}{mod_name}" if "." not in mod_name else mod_name
             merged.modules[new_name] = mod_info
 
@@ -336,6 +357,7 @@ def _run_streaming_analysis(args, config, source_path: Path):
     if args.verbose:
 
         def on_progress(update):
+            """Print a progress percentage line in-place."""
             pct = update.get("percentage", 0)
             print(f"\r[{pct:.0f}%] {update.get('message', '')}", end="", flush=True)
 

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/core/export_pipeline.py

@@ -19,23 +19,28 @@ class SharedExportContext:
     __slots__ = ("_result", "_computed")
 
     def __init__(self, result: AnalysisResult):
+        """Wrap an AnalysisResult for lazy computed-metric access."""
         self._result = result
         self._computed: Dict[str, Any] = {}
 
     @property
     def result(self) -> AnalysisResult:
+        """Return the underlying AnalysisResult."""
         return self._result
 
     @property
     def functions(self) -> Dict:
+        """Return the functions dict from the underlying result."""
         return self._result.functions
 
     @property
     def classes(self) -> Dict:
+        """Return the classes dict from the underlying result."""
         return self._result.classes
 
     @property
     def modules(self) -> Dict:
+        """Return the modules dict from the underlying result."""
         return self._result.modules
 
     @property

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/core/lang/php.py

@@ -11,6 +11,7 @@ from code2llm.core.lang.base import (
 def _parse_php_metadata(
     content: str, module_name: str, result: Dict
 ) -> Tuple[Optional[str], bool]:
+    """Extract PHP namespace and import declarations from source content."""
     lines = content.split("\n")
     current_namespace = None
     in_php = False
@@ -35,6 +36,7 @@ def _parse_php_metadata(
 
 
 def _adjust_qualified_names(result: Dict, module_name: str, namespace: str) -> None:
+    """Prefix all class/function qualified names with the PHP namespace."""
     ns_prefix = f".{namespace}"
     for key in ["classes", "functions"]:
         new_items = {}
@@ -56,6 +58,7 @@ def _extract_php_traits(
     result: Dict,
     stats: Dict,
 ) -> None:
+    """Detect PHP trait declarations and add them as ClassInfo entries."""
     trait_pattern = re.compile(r"^\s*trait\s+(\w+)")
     for line_no, line in enumerate(content.split("\n"), 1):
         tm = trait_pattern.match(line.strip())
@@ -79,6 +82,7 @@ def _extract_php_traits(
 def analyze_php(
     content: str, file_path: str, module_name: str, ext: str, stats: Dict
 ) -> Dict:
+    """Analyze a PHP source file and return declarations, complexity, and call info."""
     patterns = {
         "import": re.compile(
             r'^(?:include|require|include_once|require_once)\s*["\']([^"\']+)["\']'

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/core/lang/ts_extractors.py

@@ -108,6 +108,7 @@ def _extract_functions_ts(
     func_types = FUNCTION_TYPES.get(lang, ())
 
     def visit(node, class_context: Optional[str] = None):
+        """Recursively visit a tree-sitter node, extracting function declarations."""
         if node.type in func_types:
             name_node = _find_name_node(node)
             if name_node:
@@ -156,6 +157,7 @@ def _extract_classes_ts(
     class_types = CLASS_TYPES.get(lang, ())
 
     def visit(node):
+        """Recursively visit a tree-sitter node, extracting class declarations."""
         if node.type in class_types:
             name_node = _find_name_node(node)
             if name_node:

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/core/large_repo.py

@@ -44,6 +44,7 @@ class SubProject:
 
     @property
     def file_count(self) -> int:
+        """Return the number of files in this sub-project."""
         return len(self.files)
 
 

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/core/streaming/cache.py

@@ -11,6 +11,7 @@ class StreamingFileCache:
     """Memory-efficient cache with LRU eviction."""
 
     def __init__(self, max_size: int = 100, cache_dir: str = ".code2llm_cache"):
+        """Initialise the hybrid (memory + disk) LRU cache."""
         self.max_size = max_size
         self.cache_dir = Path(cache_dir)
         self.cache_dir.mkdir(parents=True, exist_ok=True)
@@ -18,6 +19,7 @@ class StreamingFileCache:
         self._access_order: List[str] = []
 
     def _get_cache_key(self, file_path: str, content: str) -> str:
+        """Derive the cache key for a given file path and content."""
         return make_cache_key(file_path, content)
 
     def _evict_if_needed(self) -> None:

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/article_view.py

@@ -13,6 +13,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
     """Generate status.md — publishable project health article."""
 
     def _render(self, data: Dict[str, Any]) -> List[str]:
+        """Render the full article from project.yaml data, returning Markdown lines."""
         proj = data.get("project", {})
         health = data.get("health", {})
         hotspots = data.get("hotspots", [])
@@ -31,6 +32,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_frontmatter(proj: Dict) -> List[str]:
+        """Render YAML frontmatter and H1 heading."""
         stats = proj.get("stats", {})
         return [
             "---",
@@ -49,6 +51,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_health_summary(proj: Dict, health: Dict) -> List[str]:
+        """Render the health summary table with overall verdict."""
         stats = proj.get("stats", {})
         cc_avg = health.get("cc_avg", 0)
         crit = health.get("critical_count", 0)
@@ -78,6 +81,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_alerts(health: Dict) -> List[str]:
+        """Render the alert list (health warnings/errors)."""
         alerts = health.get("alerts", [])
         if not alerts:
             return []
@@ -95,6 +99,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_hotspots(hotspots: List[Dict]) -> List[str]:
+        """Render the top hotspot functions by fan-out."""
         if not hotspots:
             return []
         lines = [
@@ -112,6 +117,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_roadmap(refactoring: Dict) -> List[str]:
+        """Render the refactoring roadmap priority list."""
         priorities = refactoring.get("priorities", [])
         if not priorities:
             return []
@@ -128,6 +134,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_evolution(evolution: List[Dict]) -> List[str]:
+        """Render the Evolution table with CC trend delta."""
         if len(evolution) <= 1:
             return []
         lines = [
@@ -161,6 +168,7 @@ class ArticleViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_footer() -> List[str]:
+        """Render the article footer with generation timestamp."""
         return [
             "---",
             f"*Generated by code2llm on {datetime.now().strftime('%Y-%m-%d %H:%M')}*",

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/context_exporter.py

@@ -64,6 +64,7 @@ class ContextExporter(BaseExporter):
         return path
 
     def _get_overview(self, result: AnalysisResult) -> List[str]:
+        """Build the Overview section listing language, file counts, and top classes."""
         lang_info = self._detect_languages(result)
         primary = lang_info[0][0] if lang_info else "unknown"
         lang_summary = ", ".join(f"{l}: {c}" for l, c in lang_info[:5])
@@ -99,6 +100,7 @@ class ContextExporter(BaseExporter):
         return sorted(lang_counts.items(), key=lambda x: -x[1])
 
     def _get_architecture_by_module(self, result: AnalysisResult) -> List[str]:
+        """Build the Architecture section grouped by module with stats."""
         lines = ["## Architecture by Module", ""]
         module_stats = []
         for mod_name, mod in result.modules.items():
@@ -121,6 +123,7 @@ class ContextExporter(BaseExporter):
     def _get_important_entries(
         self, result: AnalysisResult
     ) -> List[Tuple[str, int, Any]]:
+        """Return (name, fan_out, func_info) triples for notable entry-point functions."""
         entries = []
         for ep in result.entry_points:
             func = result.functions.get(ep)
@@ -133,6 +136,7 @@ class ContextExporter(BaseExporter):
     def _get_key_entry_points(
         self, important_entries: List[Tuple[str, int, Any]]
     ) -> List[str]:
+        """Build the Key Entry Points section from pre-ranked entry list."""
         lines = ["## Key Entry Points", "", "Main execution flows into the system:", ""]
         for ep, _, func in important_entries[:30]:
             lines.append(f"### {ep}")

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/context_view.py

@@ -13,6 +13,7 @@ class ContextViewGenerator(ViewGeneratorMixin):
     """Generate context.md from project.yaml data."""
 
     def _render(self, data: Dict[str, Any]) -> List[str]:
+        """Render the full context narrative from project.yaml data."""
         proj = data.get("project", {})
         health = data.get("health", {})
         modules = data.get("modules", [])
@@ -30,6 +31,7 @@ class ContextViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_overview(proj: Dict, health: Dict) -> List[str]:
+        """Render the Overview section with key project stats."""
         stats = proj.get("stats", {})
         return [
             "# System Architecture Analysis",
@@ -49,6 +51,7 @@ class ContextViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_architecture(modules: List[Dict]) -> List[str]:
+        """Render the Architecture section grouped by directory."""
         lines = ["## Architecture", ""]
         dir_groups: Dict[str, List[Dict]] = {}
         for m in modules:
@@ -81,6 +84,7 @@ class ContextViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_exports(modules: List[Dict]) -> List[str]:
+        """Render the Key Exports section (flagged classes and functions)."""
         lines = ["## Key Exports", ""]
         for m in modules:
             for exp in m.get("exports", []):
@@ -104,6 +108,7 @@ class ContextViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_hotspots(hotspots: List[Dict]) -> List[str]:
+        """Render the Hotspots section (top 7 by fan-out)."""
         if not hotspots:
             return []
         lines = ["## Hotspots (High Fan-Out)", ""]
@@ -116,6 +121,7 @@ class ContextViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_refactoring(refactoring: Dict) -> List[str]:
+        """Render the Refactoring Priorities table."""
         priorities = refactoring.get("priorities", [])
         if not priorities:
             return []

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/html_dashboard.py

@@ -23,10 +23,12 @@ class HTMLDashboardGenerator:
     """
 
     def __init__(self):
+        """Initialise with a DashboardDataBuilder and DashboardRenderer."""
         self._data_builder = DashboardDataBuilder()
         self._renderer = DashboardRenderer()
 
     def generate(self, data: Dict[str, Any], output_path: str) -> None:
+        """Render dashboard HTML from data and write it to output_path."""
         html = self._render(data)
         Path(output_path).parent.mkdir(parents=True, exist_ok=True)
         with open(output_path, "w", encoding="utf-8") as f:

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/planfile_tickets.py

@@ -159,6 +159,7 @@ class PlanfileTicketsExporter(BaseExporter):
 
 
 def _high_cc_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion]:
+    """Yield refactor tickets for functions whose cyclomatic complexity exceeds the limit."""
     tickets: list[PlanfileTicketSuggestion] = []
     for func in result.functions.values():
         cc = _function_cc(func)
@@ -187,6 +188,7 @@ def _high_cc_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion]:
 
 
 def _god_module_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion]:
+    """Yield split tickets for modules that are too large (god-module smell)."""
     tickets: list[PlanfileTicketSuggestion] = []
     for module in result.modules.values():
         class_count = len(module.classes)
@@ -213,6 +215,7 @@ def _god_module_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion
 
 
 def _duplicate_class_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion]:
+    """Yield deduplication tickets for class pairs with ≥60% method-name overlap."""
     tickets: list[PlanfileTicketSuggestion] = []
     classes = list(result.classes.values())
     for index, left in enumerate(classes):
@@ -251,6 +254,7 @@ def _duplicate_class_tickets(result: AnalysisResult) -> list[PlanfileTicketSugge
 
 
 def _smell_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion]:
+    """Yield tickets for structural smells not already covered by other ticket generators."""
     tickets: list[PlanfileTicketSuggestion] = []
     for smell in result.smells:
         if smell.type == "god_function" and smell.context.get("complexity", 0) >= _CC_LIMIT:
@@ -277,6 +281,7 @@ def _smell_tickets(result: AnalysisResult) -> list[PlanfileTicketSuggestion]:
 
 
 def _function_cc(func: FunctionInfo) -> int:
+    """Extract the cyclomatic complexity integer from a FunctionInfo, defaulting to 0."""
     raw = func.complexity.get("cyclomatic_complexity", func.complexity.get("cc", 0))
     try:
         return int(raw)
@@ -285,10 +290,12 @@ def _function_cc(func: FunctionInfo) -> int:
 
 
 def _method_names(cls: ClassInfo) -> set[str]:
+    """Return the set of unqualified method names for a class."""
     return {method.split(".")[-1] for method in cls.methods}
 
 
 def _rel_path(path: str, project_path: str) -> str:
+    """Return path relative to project_path, falling back to the original if resolution fails."""
     if not path:
         return ""
     raw = Path(path)

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/toon/helpers.py

@@ -11,11 +11,13 @@ from code2llm.exporters.flow_constants import is_excluded_path
 
 
 def _is_excluded(path: str) -> bool:
+    """Return True if the given file path should be excluded from duplicate analysis."""
     return is_excluded_path(path)
 
 
 @lru_cache(maxsize=4096)
 def _rel_path(fpath: str, project_path: str) -> str:
+    """Return fpath relative to project_path, or fpath unchanged if resolution fails."""
     if not project_path or not fpath:
         return fpath or ""
     try:
@@ -51,6 +53,7 @@ def _package_of_module(module_name: str) -> str:
 
 
 def _traits_from_cfg(fi: FunctionInfo, result: AnalysisResult) -> list:
+    """Derive structural trait labels (loops/cond/ret) from a function's CFG nodes."""
     traits = []
     node_types = set()
     for nid in fi.cfg_nodes or []:
@@ -67,6 +70,7 @@ def _traits_from_cfg(fi: FunctionInfo, result: AnalysisResult) -> list:
 
 
 def _dup_file_set(ctx: Dict[str, Any]) -> Set[str]:
+    """Return the set of file paths that appear in at least one duplicate pair."""
     s: Set[str] = set()
     for d in ctx["duplicates"]:
         s.add(d["fileA"])
@@ -75,6 +79,7 @@ def _dup_file_set(ctx: Dict[str, Any]) -> Set[str]:
 
 
 def _hotspot_description(fi: FunctionInfo, fan_out: int) -> str:
+    """Generate a short human-readable description for a hotspot function."""
     if fi.name == "to_dict":
         return f"{fan_out} conditional field serializations"
     if "format" in fi.name.lower() or "dispatch" in fi.name.lower():

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/exporters/toon_view.py

@@ -52,6 +52,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
     """Generate project.toon.yaml from project.yaml data."""
 
     def _render(self, data: Dict[str, Any]) -> List[str]:
+        """Render the full TOON view from project.yaml data."""
         proj = data.get("project", {})
         health = data.get("health", {})
         modules = data.get("modules", [])
@@ -71,6 +72,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_header(proj: Dict) -> List[str]:
+        """Render single-line project header with key stats."""
         stats = proj.get("stats", {})
         lang = proj.get("language", "unknown")
         return [
@@ -85,6 +87,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_health(health: Dict) -> List[str]:
+        """Render one-line HEALTH summary."""
         return [
             "HEALTH:",
             f"  CC̄={health.get('cc_avg', 0)}  "
@@ -95,6 +98,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_alerts(health: Dict) -> List[str]:
+        """Render ALERTS block (returns empty list if no alerts)."""
         alerts = health.get("alerts", [])
         if not alerts:
             return []
@@ -116,6 +120,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_modules(modules: List[Dict]) -> List[str]:
+        """Render MODULES block with top-15 by size and language breakdown."""
         # Show top modules by size (lines) - works for all languages
         top_by_lines = sorted(modules, key=lambda m: m.get("lines", 0), reverse=True)[
             :15
@@ -149,6 +154,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_hotspots(hotspots: List[Dict]) -> List[str]:
+        """Render HOTSPOTS block (top 5 by fan-out)."""
         if not hotspots:
             return []
         lines = ["", f"HOTSPOTS[{len(hotspots)}]:"]
@@ -161,6 +167,7 @@ class ToonViewGenerator(ViewGeneratorMixin):
 
     @staticmethod
     def _render_refactoring(refactoring: Dict) -> List[str]:
+        """Render REFACTOR block with top 5 refactoring actions."""
         priorities = refactoring.get("priorities", [])
         if not priorities:
             return []

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/generators/llm_flow/analysis.py

@@ -11,6 +11,8 @@ from .parsing import _parse_call_label
 
 @dataclass(frozen=True)
 class FuncSummary:
+    """Immutable summary of a single function's decisions and outgoing calls."""
+
     name: str
     file: Optional[str]
     line: Optional[int]
@@ -67,6 +69,7 @@ def _pick_relevant_functions(
     ]
 
     def score(fn: str) -> int:
+        """Rank function by node count, calls, and entry-point status for flow selection."""
         s = 0
         s += min(500, counts.get(fn, 0))  # node count baseline
         for needle, boost in keyword_boosts:
@@ -147,6 +150,7 @@ def _summarize_functions(
 def _build_call_graph(
     func_summaries: Dict[str, FuncSummary], known_functions: Set[str]
 ) -> Dict[str, Set[str]]:
+    """Build adjacency list of internal calls between known functions."""
     g: Dict[str, Set[str]] = defaultdict(set)
     for fn, s in func_summaries.items():
         for callee in s.calls:
@@ -158,6 +162,7 @@ def _build_call_graph(
 def _reachable(
     g: Dict[str, Set[str]], roots: Iterable[str], max_nodes: int
 ) -> List[str]:
+    """BFS from roots through call graph; return up to max_nodes reachable functions."""
     seen: Set[str] = set()
     q: deque[str] = deque([r for r in roots if r])
 

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/generators/llm_flow/cli.py

@@ -11,6 +11,7 @@ from .generator import generate_llm_flow, render_llm_flow_md
 
 
 def create_parser() -> argparse.ArgumentParser:
+    """Build and return the argument parser for the llm-flow-generator CLI."""
     p = argparse.ArgumentParser(
         prog="llm-flow-generator",
         description="Generate compact LLM-friendly app flow summary from code2llm analysis.yaml",
@@ -39,6 +40,7 @@ def create_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Optional[List[str]] = None) -> int:
+    """Entry point: parse args, run flow generation, write output files."""
     args = create_parser().parse_args(argv)
 
     input_path = Path(args.input)

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/generators/llm_flow/generator.py

@@ -16,6 +16,7 @@ def generate_llm_flow(
     limit_decisions: int,
     limit_calls: int,
 ) -> Dict[str, Any]:
+    """Build a compact LLM-friendly flow dict from a code2llm analysis result."""
     nodes = _collect_nodes(analysis)
     entrypoints = _collect_entrypoints(nodes)
 
@@ -62,6 +63,7 @@ def generate_llm_flow(
 
 
 def render_llm_flow_md(flow: Dict[str, Any]) -> str:
+    """Render a flow dict (from generate_llm_flow) as a Markdown summary string."""
     app = _as_dict(flow.get("app"))
     entrypoints = _as_list(app.get("entrypoints"))
     selected = _as_list(_as_dict(flow.get("flow")).get("selected_functions"))

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/generators/llm_task.py

@@ -9,10 +9,12 @@ from ._utils import dump_yaml
 
 
 def _strip_bom(text: str) -> str:
+    """Strip UTF-8 BOM from the start of text if present."""
     return text[1:] if text.startswith("\ufeff") else text
 
 
 def _ensure_list(value: Any) -> List[Any]:
+    """Wrap scalar value in a list; return value unchanged if already a list."""
     if value is None:
         return []
     if isinstance(value, list):
@@ -30,6 +32,7 @@ def _deep_get(d: Dict[str, Any], path: Tuple[str, ...]) -> Any:
 
 
 def normalize_llm_task(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalise a raw LLM task dict into a canonical structure with all required keys."""
     task = data.get("task") or {}
     context = data.get("context") or {}
     deliverables = data.get("deliverables") or {}
@@ -308,6 +311,7 @@ def load_input(path: Path) -> Dict[str, Any]:
 
 
 def create_parser() -> argparse.ArgumentParser:
+    """Build and return the CLI argument parser for the LLM task generator."""
     p = argparse.ArgumentParser(
         prog="llm-task-generator",
         description="Generate normalized llm_task.yaml from simplified task spec (text/YAML/JSON).",
@@ -325,6 +329,7 @@ def create_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: Optional[List[str]] = None) -> int:
+    """Entry point for the LLM task generator CLI."""
     args = create_parser().parse_args(argv)
 
     input_path = Path(args.input)

{code2llm-0.5.155 → code2llm-0.5.156}/code2llm/nlp/__init__.py

@@ -4,7 +4,7 @@ Provides query normalization, intent matching, and entity resolution
 with multilingual support and fuzzy matching.
 """
 
-__version__ = "0.5.155"
+__version__ = "0.5.156"
 
 from .pipeline import NLPPipeline
 from .normalization import QueryNormalizer