feat(docs): code analysis engine

changes:
  - file: config.py
    area: config
    modified: [Code2LlmConfig, to_yaml, Code2DocsConfig, from_yaml]
  - file: code2llm_gen.py
    area: docs
    added: [parse_gitignore]
    modified: [_run_code2llm, Code2LlmGenerator]

stats:
  lines: "+44110/-547 (net +43563)"
  files: 31
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.10] - 2026-03-08
+
+### Docs
+- Update CONTRIBUTING.md
+- Update README.md
+- Update code2docs/README.md
+- Update code2docs/project/README.md
+- Update code2docs/project/context.md
+- Update docs/api.md
+- Update docs/architecture.md
+- Update docs/configuration.md
+- Update docs/coverage.md
+- Update docs/dependency-graph.md
+- ... and 3 more files
+
+### Other
+- Update code2docs/config.py
+- Update code2docs/generators/code2llm_gen.py
+- Update code2docs/project/analysis.json
+- Update code2docs/project/analysis.toon
+- Update code2docs/project/analysis.yaml
+- Update code2docs/project/calls.mmd
+- Update code2docs/project/compact_flow.mmd
+- Update code2docs/project/dashboard.html
+- Update code2docs/project/evolution.toon
+- Update code2docs/project/flow.mmd
+- ... and 23 more files
+
 ## [0.2.9] - 2026-03-07
 
 ## [0.2.8] - 2026-03-07

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to code2docs
+
+## Development Setup
+
+```bash
+git clone <repository-url>
+cd code2docs
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+## Development Workflow
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Add or update tests
+4. Run the test suite
+5. Submit a pull request
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov --cov-report=term-missing
+
+# Run a specific test file
+pytest tests/test_specific.py -v
+```
+
+## Code Style
+
+- **Formatting:** [Black](https://black.readthedocs.io/) — `black .`
+- **Linting:** [Ruff](https://docs.astral.sh/ruff/) — `ruff check .`
+- **Type checking:** [mypy](https://mypy.readthedocs.io/) — `mypy .`
+
+## Pull Request Guidelines
+
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new functionality
+- Update documentation if needed
+- Ensure all tests pass before submitting
+- Use descriptive commit messages

README.md

@@ -1 +1 @@
-0.2.9
+0.2.10

VERSION

@@ -5,7 +5,7 @@
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = "0.2.9"
+__version__ = "0.2.10"
 __author__ = "Tom Sapletta"
 
 from .config import Code2DocsConfig

code2docs/README.md

@@ -62,6 +62,17 @@ class Code2LlmConfig:
     output_dir: str = "project"  # Relative to project root
     chunk: bool = False  # Enable chunking for large repos
     no_png: bool = True  # Skip PNG generation (faster)
+    max_depth: int = 3  # Maximum directory depth to scan (default 3 levels)
+    exclude_patterns: List[str] = field(default_factory=lambda: [
+        "venv", ".venv", "env", ".env",
+        "node_modules", "bower_components",
+        "__pycache__", ".pytest_cache", ".mypy_cache",
+        ".git", ".hg", ".svn",
+        "dist", "build", "target", "out",
+        ".tox", ".eggs", "*.egg-info",
+        "vendor", "third_party", "third-party",
+        "site-packages", "lib/python*",
+    ])  # Patterns to exclude from scanning
 
 
 @dataclass
@@ -214,6 +225,17 @@ def from_yaml(cls, path: str) -> "Code2DocsConfig":
                 output_dir=code2llm_data.get("output_dir", "project"),
                 chunk=code2llm_data.get("chunk", False),
                 no_png=code2llm_data.get("no_png", True),
+                max_depth=code2llm_data.get("max_depth", 3),
+                exclude_patterns=code2llm_data.get("exclude_patterns", [
+                    "venv", ".venv", "env", ".env",
+                    "node_modules", "bower_components",
+                    "__pycache__", ".pytest_cache", ".mypy_cache",
+                    ".git", ".hg", ".svn",
+                    "dist", "build", "target", "out",
+                    ".tox", ".eggs", "*.egg-info",
+                    "vendor", "third_party", "third-party",
+                    "site-packages", "lib/python*",
+                ]),
             )
 
         return config
@@ -266,6 +288,8 @@ def to_yaml(self, path: str) -> None:
                 "output_dir": self.code2llm.output_dir,
                 "chunk": self.code2llm.chunk,
                 "no_png": self.code2llm.no_png,
+                "max_depth": self.code2llm.max_depth,
+                "exclude_patterns": self.code2llm.exclude_patterns,
             },
         }
         with open(path, "w", encoding="utf-8") as f:

code2docs/__init__.py

@@ -2,13 +2,63 @@
 
 import subprocess
 from pathlib import Path
-from typing import List, Optional, Dict
+from typing import List, Optional, Dict, Set
 
 from code2llm.api import AnalysisResult
 
 from ..config import Code2DocsConfig
 
 
+def parse_gitignore(project_path: Path) -> List[str]:
+    """Parse .gitignore file and return list of patterns to exclude.
+    
+    Filters out:
+    - Empty lines
+    - Comments (lines starting with #)
+    - Negation patterns (starting with !)
+    - Complex patterns with ** or regex
+    
+    Returns simple directory/file patterns that can be passed to --skip-subprojects.
+    """
+    gitignore_path = project_path / ".gitignore"
+    if not gitignore_path.exists():
+        return []
+    
+    patterns = []
+    try:
+        content = gitignore_path.read_text(encoding="utf-8")
+        for line in content.split("\n"):
+            line = line.strip()
+            # Skip empty lines and comments
+            if not line or line.startswith("#"):
+                continue
+            # Skip negation patterns (too complex)
+            if line.startswith("!"):
+                continue
+            # Skip patterns with ** (globstar - too complex)
+            if "**" in line:
+                continue
+            # Skip file-specific patterns (with wildcards)
+            if "*" in line and "/" not in line:
+                # Wildcard without path - likely file pattern, skip
+                continue
+            # Clean up the pattern
+            pattern = line.rstrip("/")  # Remove trailing slash
+            # Skip patterns starting with / (root-only patterns)
+            if pattern.startswith("/"):
+                pattern = pattern[1:]
+            # Skip if still has special characters
+            if any(c in pattern for c in "[]?*"):
+                continue
+            # Valid directory pattern
+            if pattern and len(pattern) > 1:
+                patterns.append(pattern)
+    except Exception:
+        pass  # Silently fail if can't read gitignore
+    
+    return patterns
+
+
 class Code2LlmGenerator:
     """Generate code2llm analysis files in project/ directory.
     
@@ -81,6 +131,7 @@ def _run_code2llm(self, project_path: Path, output_dir: Path) -> None:
             "-f", ",".join(cfg.formats),
             "-o", str(output_dir),
             "--strategy", cfg.strategy,
+            "--max-depth", str(cfg.max_depth),
         ]
 
         # Add options based on config
@@ -91,6 +142,24 @@ def _run_code2llm(self, project_path: Path, output_dir: Path) -> None:
         if self.config.verbose:
             cmd.append("-v")
 
+        # Add exclude patterns as skip-subprojects if specified
+        if cfg.exclude_patterns:
+            # Convert patterns to skip-subprojects (folders to skip)
+            skip_dirs = [p for p in cfg.exclude_patterns if not p.startswith(".") and not p.startswith("*")]
+            if skip_dirs:
+                cmd.extend(["--skip-subprojects"] + skip_dirs[:10])  # Limit to 10
+        
+        # Add patterns from .gitignore
+        gitignore_patterns = parse_gitignore(project_path)
+        if gitignore_patterns:
+            # Merge with existing patterns, remove duplicates
+            existing = set(skip_dirs) if cfg.exclude_patterns else set()
+            new_patterns = [p for p in gitignore_patterns if p not in existing][:10]
+            if new_patterns:
+                if "--skip-subprojects" not in cmd:
+                    cmd.append("--skip-subprojects")
+                cmd.extend(new_patterns)
+        
         # Run the command
         result = subprocess.run(
             cmd,