refactor(docs): code analysis engine

changes:
  - file: mermaid_exporter.py
    area: core
    added: [_sanitize_identifier]
    modified: [MermaidExporter, _readable_id, _safe_module]
  - file: test_analyzer.py
    area: analyzer
    new_tests: 1
    modified: [TestExporters]

testing:
  new_tests: 1
  scenarios:
    - mermaid_export_sanitizes_unsafe_identifiers

stats:
  lines: "+263/-238 (net +25)"
  files: 13
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.5.97] - 2026-03-26
+
+### Docs
+- Update project/context.md
+
+### Test
+- Update tests/test_analyzer.py
+
+### Other
+- Update code2llm/exporters/mermaid_exporter.py
+- Update project/analysis.toon.yaml
+- Update project/calls.mmd
+- Update project/calls.png
+- Update project/compact_flow.mmd
+- Update project/compact_flow.png
+- Update project/flow.mmd
+- Update project/flow.png
+- Update project/index.html
+- Update project/map.toon.yaml
+
 ## [0.5.96] - 2026-03-26
 
 ### Docs

README.md

@@ -26,8 +26,8 @@ When you run `code2llm ./ -f all`, the following files are created:
 # Quick health check (TOON format only)
 code2llm ./ -f toon
 
-# Generate all formats + project.toon.yaml + prompt.txt (single-project mode)
-code2llm ./ -f all -o ./project --no-chunk
+# Generate all formats (what created these files)
+code2llm ./ -f all
 
 # LLM-ready context only
 code2llm ./ -f context
@@ -142,12 +142,13 @@ grep -E "^  .*[0-9]{3,}$" project.toon.yaml | sort -t',' -k2 -n -r | head -10
 
 ### `prompt.txt` - Ready-to-Send LLM Prompt
 **Purpose**: Pre-formatted prompt listing all generated files for LLM conversation
-**Generation**: Written when `code2llm` runs with a source path and requests `-f all` (including `--no-chunk`) or `code2logic`; `-f all` also writes `project.toon.yaml`
+**Generation**: Written when `code2llm` runs with a source path and requests `-f all` (including `--no-chunk`) or `code2logic`
 **Contents**:
-- **Files section**: Lists all existing generated files with descriptions
+- **Files section**: Lists all existing generated files with descriptions, including `project.toon.yaml` when generated by `-f all`
 - **Source files section**: Highlights important source files such as `cli_exports/orchestrator.py`
 - **Missing section**: Shows which files weren't generated (if any)
-- **Task section**: Instructions for LLM analysis
+- **Task section**: Refactoring brief with concrete execution instructions, not just analysis
+- **Priority Order section**: State-dependent refactoring priorities, starting with blockers and then architecture cleanup
 - **Requirements section**: Guidelines for suggested changes
 
 **Example usage**:
@@ -322,7 +323,7 @@ code2llm ./ -f yaml --separate-orphans
 
 **Generated by**: `code2llm ./ -f all --readme`  
 **Analysis Date**: 2026-03-26  
-**Total Functions**: 931  
+**Total Functions**: 934  
 **Total Classes**: 106  
 **Modules**: 122  
 

VERSION

@@ -1 +1 @@
-0.5.96
+0.5.97

code2llm/__init__.py

@@ -8,7 +8,7 @@
 and entity resolution with multilingual support.
 """
 
-__version__ = "0.5.96"
+__version__ = "0.5.97"
 __author__ = "STTS Project"
 
 # Core analysis components (lightweight, always needed)

code2llm/exporters/mermaid_exporter.py

@@ -12,6 +12,7 @@
 """
 
 from collections import defaultdict
+import re
 from pathlib import Path
 from typing import Dict, List, Set, Tuple, Optional
 from .base import Exporter
@@ -581,32 +582,22 @@ def _readable_id(self, name: str) -> str:
           code2llm.core.analyze → code2llm__core__analyze
           code2llm.core.PipelineDetector.__init__ → code2llm__core__PipelineDetector____init__
         """
-        # Convert dots to double underscores to preserve hierarchy
-        safe = name.replace('.', '__')
-        # Replace other unsafe chars
-        safe = safe.replace('-', '_').replace(':', '_').replace(' ', '_')
-        # Keep reasonable length but preserve class+method uniqueness
-        if len(safe) > 60:
-            parts = name.split('.')
-            if len(parts) >= 3:
-                # module__Class__method or module__subpackage__Class__method
-                module = parts[0]
-                method = parts[-1]
-                # Include class name if present (parts[-2] is usually class or subpackage)
-                if len(parts) >= 4 and parts[-2][0].isupper():
-                    # Definitely a class: module.sub.Class.method
-                    class_name = parts[-2]
-                    safe = f"{module}__{class_name}__{method}"
-                else:
-                    # Might be module.subpackage.function
-                    middle = '__'.join(parts[1:-1])
-                    safe = f"{module}__{middle}__{method}"
-            safe = safe[:60]
-        return safe
+        return self._sanitize_identifier(name, prefix="N")
 
     def _safe_module(self, name: str) -> str:
         """Create safe subgraph name."""
-        return name.replace('.', '_').replace('-', '_').replace('/', '_').replace(' ', '_')
+        return self._sanitize_identifier(name, prefix="M")
+
+    @staticmethod
+    def _sanitize_identifier(name: str, prefix: str) -> str:
+        """Convert an arbitrary string into a Mermaid-safe identifier."""
+        safe = (name or "").replace('.', '__')
+        safe = re.sub(r'[^A-Za-z0-9_]+', '_', safe)
+        if not safe:
+            return prefix
+        if not safe[0].isalpha():
+            safe = f"{prefix}_{safe}"
+        return safe
 
     def _module_of(self, func_name: str) -> str:
         """Extract module from qualified name.

code2llm/nlp/__init__.py

@@ -4,7 +4,7 @@
 with multilingual support and fuzzy matching.
 """
 
-__version__ = "0.5.96"
+__version__ = "0.5.97"
 
 from .pipeline import NLPPipeline
 from .normalization import QueryNormalizer

project/analysis.toon.yaml

@@ -20,9 +20,9 @@ REFACTOR[1]:
 PIPELINES[637]:
   [1] Src [read_readme]: read_readme
       PURITY: 100% pure
-  [2] Src [run_benchmark]: run_benchmark → load_previous
+  [2] Src [save_report]: save_report
       PURITY: 100% pure
-  [3] Src [save_report]: save_report
+  [3] Src [run_benchmark]: run_benchmark → load_previous
       PURITY: 100% pure
   [4] Src [main]: main → load_file → is_toon_file
       PURITY: 100% pure