code2docs 3.0.29__tar.gz → 3.0.33__tar.gz

{code2docs-3.0.29 → code2docs-3.0.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code2docs
-Version: 3.0.29
+Version: 3.0.33
 Summary: Auto-generate and sync project documentation from source code analysis
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0
@@ -53,17 +53,17 @@ Dynamic: license-file
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-3.0.29-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-23.8h-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-3.0.33-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-25.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (68 commits)
-- 👤 **Human dev:** ~$2384 (23.8h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (73 commits)
+- 👤 **Human dev:** ~$2534 (25.3h @ $100/h, 30min dedup)
 
-Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-04-20 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![version](https://img.shields.io/badge/version-3.0.29-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.33-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -200,7 +200,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.29-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.33-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

{code2docs-3.0.29 → code2docs-3.0.33}/README.md

@@ -1,16 +1,16 @@
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-3.0.29-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-23.8h-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-3.0.33-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-25.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (68 commits)
-- 👤 **Human dev:** ~$2384 (23.8h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (73 commits)
+- 👤 **Human dev:** ~$2534 (25.3h @ $100/h, 30min dedup)
 
-Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-04-20 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![version](https://img.shields.io/badge/version-3.0.29-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.33-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -147,7 +147,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.29-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.33-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/__init__.py

@@ -5,7 +5,7 @@ Uses code2llm's AnalysisResult to produce human-readable documentation:
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = '3.0.29'
+__version__ = '3.0.33'
 __author__ = 'Tom Sapletta'
 __all__ = ['Code2DocsConfig', 'generate_readme', 'generate_docs', 'analyze_and_document']
 

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/analyzers/__init__.py

@@ -4,10 +4,20 @@ from .project_scanner import ProjectScanner
 from .endpoint_detector import EndpointDetector
 from .docstring_extractor import DocstringExtractor
 from .dependency_scanner import DependencyScanner
+from .markdown_validator import (
+    MarkdownIssue,
+    ValidationReport,
+    validate_markdown_file,
+    validate_markdown_tree,
+)
 
 __all__ = [
     "ProjectScanner",
     "EndpointDetector",
     "DocstringExtractor",
     "DependencyScanner",
+    "MarkdownIssue",
+    "ValidationReport",
+    "validate_markdown_file",
+    "validate_markdown_tree",
 ]

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/analyzers/dependency_scanner.py

@@ -1,4 +1,4 @@
-"""Scan project dependencies from requirements.txt, pyproject.toml, setup.py, package.json, Cargo.toml, go.mod."""
+"""Scan project dependencies from requirements.txt, pyproject.toml, setup.py, package.json, composer.json, Cargo.toml, go.mod."""
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -50,6 +50,11 @@ class DependencyScanner:
             if tsconfig.exists():
                 deps.language = 'typescript'
             return deps
+        composer_json = project / 'composer.json'
+        if composer_json.exists():
+            deps = self._parse_composer_json(composer_json)
+            deps.source_file = 'composer.json'
+            return deps
         cargo_toml = project / 'Cargo.toml'
         if cargo_toml.exists():
             deps = self._parse_cargo_toml(cargo_toml)
@@ -171,6 +176,26 @@ class DependencyScanner:
             deps.keywords = data.get('keywords', [])
         return deps
 
+    def _parse_composer_json(self, path: Path) -> ProjectDependencies:
+        """Parse composer.json for PHP dependencies."""
+        import json
+        deps = ProjectDependencies(language='php')
+        try:
+            data = json.loads(path.read_text(encoding='utf-8'))
+        except (json.JSONDecodeError, OSError):
+            return deps
+        deps.version = data.get('version', '')
+        deps.keywords = data.get('keywords', []) or []
+        for dep_name, ver in (data.get('require', {}) or {}).items():
+            if dep_name.lower() == 'php':
+                deps.runtime_version = ver
+                continue
+            deps.dependencies.append(DependencyInfo(name=dep_name, version_spec=ver))
+        for dep_name, ver in (data.get('require-dev', {}) or {}).items():
+            deps.dev_dependencies.append(DependencyInfo(name=dep_name, version_spec=ver, group='dev'))
+        deps.install_command = 'composer install'
+        return deps
+
     def _parse_cargo_toml(self, path: Path) -> ProjectDependencies:
         """Parse Cargo.toml for Rust dependencies."""
         deps = ProjectDependencies(language='rust')

code2docs-3.0.33/code2docs/analyzers/markdown_validator.py

@@ -0,0 +1,194 @@
+"""Validate generated markdown: checks local links/images, table shape, duplicate headings."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, List, Optional
+from urllib.parse import urlparse
+
+_LINK_RE = re.compile(r'!?\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)')
+_HEADING_RE = re.compile(r'^(#{1,6})\s+(.+?)\s*#*\s*$')
+_FENCE_RE = re.compile(r'^(```|~~~)')
+_TABLE_SEP_RE = re.compile(r'^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$')
+
+
+@dataclass
+class MarkdownIssue:
+    """A single validation issue in a markdown file."""
+    file: str
+    line: int
+    kind: str
+    message: str
+
+    def __str__(self) -> str:
+        return f'{self.file}:{self.line} [{self.kind}] {self.message}'
+
+
+@dataclass
+class ValidationReport:
+    """Aggregate result of markdown validation."""
+    issues: List[MarkdownIssue] = field(default_factory=list)
+    files_checked: int = 0
+
+    @property
+    def ok(self) -> bool:
+        return not self.issues
+
+    def by_kind(self, kind: str) -> List[MarkdownIssue]:
+        return [i for i in self.issues if i.kind == kind]
+
+    def summary(self) -> str:
+        if self.ok:
+            return f'✅ {self.files_checked} file(s) checked, no issues'
+        kinds: dict = {}
+        for issue in self.issues:
+            kinds[issue.kind] = kinds.get(issue.kind, 0) + 1
+        parts = ', '.join(f'{k}={v}' for k, v in sorted(kinds.items()))
+        return f'❌ {len(self.issues)} issue(s) across {self.files_checked} file(s): {parts}'
+
+
+def validate_markdown_file(md_path: Path, project_root: Optional[Path] = None) -> List[MarkdownIssue]:
+    """Validate a single markdown file.
+
+    Checks:
+    - Local links/images resolve to existing files (skips URLs and in-page anchors).
+    - Tables have consistent column count.
+    - Duplicate headings at the same level are flagged.
+    """
+    md_path = Path(md_path)
+    if not md_path.exists():
+        return [MarkdownIssue(str(md_path), 0, 'missing', 'file does not exist')]
+    root = Path(project_root) if project_root else md_path.parent
+    try:
+        lines = md_path.read_text(encoding='utf-8').splitlines()
+    except OSError as exc:
+        return [MarkdownIssue(str(md_path), 0, 'read_error', str(exc))]
+    issues: List[MarkdownIssue] = []
+    issues.extend(_check_links(md_path, root, lines))
+    issues.extend(_check_tables(md_path, lines))
+    issues.extend(_check_headings(md_path, lines))
+    return issues
+
+
+def validate_markdown_tree(root: Path, patterns: Iterable[str] = ('*.md',),
+                           ignore: Iterable[str] = ('node_modules', 'venv', '.venv',
+                                                    'vendor', '.git', '__pycache__')) -> ValidationReport:
+    """Validate every markdown file under ``root`` matching ``patterns``."""
+    root = Path(root)
+    ignore_set = set(ignore)
+    report = ValidationReport()
+    seen: set = set()
+    for pattern in patterns:
+        for md_file in root.rglob(pattern):
+            if any(part in ignore_set for part in md_file.parts):
+                continue
+            if md_file in seen:
+                continue
+            seen.add(md_file)
+            report.files_checked += 1
+            report.issues.extend(validate_markdown_file(md_file, project_root=root))
+    return report
+
+
+def _strip_code_fences(lines: List[str]) -> List[bool]:
+    """Return a per-line boolean: True if the line is inside a fenced code block."""
+    inside = False
+    mask: List[bool] = []
+    for line in lines:
+        if _FENCE_RE.match(line.strip()):
+            mask.append(True)
+            inside = not inside
+            continue
+        mask.append(inside)
+    return mask
+
+
+def _check_links(md_path: Path, root: Path, lines: List[str]) -> List[MarkdownIssue]:
+    issues: List[MarkdownIssue] = []
+    in_code = _strip_code_fences(lines)
+    for lineno, line in enumerate(lines, 1):
+        if in_code[lineno - 1]:
+            continue
+        for match in _LINK_RE.finditer(line):
+            target = match.group(2).strip()
+            if not target or target.startswith('#'):
+                continue
+            parsed = urlparse(target)
+            if parsed.scheme in ('http', 'https', 'mailto', 'ftp', 'tel', 'data'):
+                continue
+            if parsed.scheme and parsed.scheme not in ('file',):
+                continue
+            rel = parsed.path
+            if not rel:
+                continue
+            if rel.startswith('/'):
+                resolved = root / rel.lstrip('/')
+            else:
+                resolved = (md_path.parent / rel).resolve()
+            if not resolved.exists():
+                issues.append(MarkdownIssue(
+                    str(md_path), lineno, 'broken_link',
+                    f'link target not found: {target}'))
+    return issues
+
+
+def _check_tables(md_path: Path, lines: List[str]) -> List[MarkdownIssue]:
+    issues: List[MarkdownIssue] = []
+    in_code = _strip_code_fences(lines)
+    i = 0
+    while i < len(lines):
+        if in_code[i]:
+            i += 1
+            continue
+        line = lines[i]
+        if '|' in line and i + 1 < len(lines) and _TABLE_SEP_RE.match(lines[i + 1]):
+            header_cols = _count_cells(line)
+            sep_cols = _count_cells(lines[i + 1])
+            if header_cols != sep_cols:
+                issues.append(MarkdownIssue(
+                    str(md_path), i + 2, 'table_shape',
+                    f'separator has {sep_cols} cells, header has {header_cols}'))
+            j = i + 2
+            while j < len(lines) and not in_code[j] and lines[j].strip() and '|' in lines[j]:
+                cells = _count_cells(lines[j])
+                if cells != header_cols:
+                    issues.append(MarkdownIssue(
+                        str(md_path), j + 1, 'table_shape',
+                        f'row has {cells} cells, expected {header_cols}'))
+                j += 1
+            i = j
+        else:
+            i += 1
+    return issues
+
+
+def _count_cells(row: str) -> int:
+    stripped = row.strip()
+    if stripped.startswith('|'):
+        stripped = stripped[1:]
+    if stripped.endswith('|'):
+        stripped = stripped[:-1]
+    return len(stripped.split('|'))
+
+
+def _check_headings(md_path: Path, lines: List[str]) -> List[MarkdownIssue]:
+    issues: List[MarkdownIssue] = []
+    in_code = _strip_code_fences(lines)
+    seen: dict = {}
+    for lineno, line in enumerate(lines, 1):
+        if in_code[lineno - 1]:
+            continue
+        match = _HEADING_RE.match(line)
+        if not match:
+            continue
+        level = len(match.group(1))
+        title = match.group(2).strip().lower()
+        key = (level, title)
+        if key in seen:
+            issues.append(MarkdownIssue(
+                str(md_path), lineno, 'duplicate_heading',
+                f'H{level} "{match.group(2).strip()}" already at line {seen[key]}'))
+        else:
+            seen[key] = lineno
+    return issues

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/cli.py

@@ -93,6 +93,36 @@ def check(project_path, config_path, target) -> None:
     config = _load_config(project_path, config_path)
     _run_check(project_path, config, target)
 
+@main.command()
+@click.argument('project_path', default='.', type=click.Path(exists=True))
+@click.option('--pattern', multiple=True, default=('*.md',), show_default=True,
+              help='Glob pattern(s) of markdown files to validate.')
+@click.option('--strict', is_flag=True, help='Exit with non-zero status if any issues are found.')
+def validate(project_path, pattern, strict) -> None:
+    """Validate generated markdown: broken links, table shape, duplicate headings."""
+    from .analyzers.markdown_validator import validate_markdown_tree
+    project = Path(project_path).resolve()
+    console.print(f'[bold blue]🔎 code2docs validate:[/] {project.name}')
+    report = validate_markdown_tree(project, patterns=pattern)
+    if report.ok:
+        console.print(f'[green]{report.summary()}[/]')
+        return
+    table = Table(title='Markdown Issues', show_lines=False)
+    table.add_column('File', style='cyan', overflow='fold')
+    table.add_column('Line', justify='right')
+    table.add_column('Kind', style='magenta')
+    table.add_column('Message', style='dim', overflow='fold')
+    for issue in report.issues:
+        try:
+            rel = Path(issue.file).relative_to(project)
+        except ValueError:
+            rel = Path(issue.file)
+        table.add_row(str(rel), str(issue.line), issue.kind, issue.message)
+    console.print(table)
+    console.print(f'[yellow]{report.summary()}[/]')
+    if strict:
+        sys.exit(1)
+
 @main.command()
 @click.argument('project_path', default='.', type=click.Path(exists=True))
 @click.option('--config', '-c', 'config_path', default=None, help='Path to code2docs.yaml')

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/config.py

@@ -14,7 +14,7 @@ except ImportError:
 @dataclass
 class ReadmeConfig:
     """Configuration for README generation."""
-    sections: List[str] = field(default_factory=lambda: ['overview', 'install', 'quickstart', 'generated_output', 'config', 'sync_markers', 'architecture', 'api', 'structure', 'requirements', 'contributing', 'docs_nav'])
+    sections: List[str] = field(default_factory=lambda: ['overview', 'install', 'quickstart', 'architecture', 'api', 'structure', 'requirements', 'endpoints', 'contributing', 'docs_nav'])
     badges: List[str] = field(default_factory=lambda: ['version', 'python', 'coverage', 'complexity'])
     sync_markers: bool = True
 

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/formatters/badges.py

@@ -27,6 +27,9 @@ def _make_badge(badge_type: str, project_name: str,
         return f"![version](https://img.shields.io/badge/version-0.1.0-blue)"
 
     elif badge_type == "python":
+        lang = getattr(deps, "language", "python") if deps else "python"
+        if lang and lang != "python":
+            return _runtime_badge(lang, deps)
         py_version = ""
         if deps and hasattr(deps, "python_version"):
             py_version = deps.python_version
@@ -50,3 +53,20 @@ def _make_badge(badge_type: str, project_name: str,
         return f"![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)"
 
     return None
+
+
+_RUNTIME_LABELS = {
+    "php": ("php", "777BB4"),
+    "javascript": ("node", "339933"),
+    "typescript": ("typescript", "3178C6"),
+    "rust": ("rust", "B7410E"),
+    "go": ("go", "00ADD8"),
+}
+
+
+def _runtime_badge(lang: str, deps) -> Optional[str]:
+    """Generate a runtime badge for non-Python languages."""
+    label, color = _RUNTIME_LABELS.get(lang, (lang, "blue"))
+    version = getattr(deps, "runtime_version", "") if deps else ""
+    version = version or "any"
+    return f"![{label}](https://img.shields.io/badge/{quote(label)}-{quote(version)}-{color})"

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/generators/examples_gen.py

@@ -1,33 +1,3 @@
-
-PORT_4 = 4
-CONSTANT_5 = 5
-CONSTANT_50 = 50
-
-
-PORT_4 = PORT_4
-CONSTANT_5 = CONSTANT_5
-CONSTANT_50 = CONSTANT_50
-
-
-PORT_4 = PORT_4
-CONSTANT_5 = CONSTANT_5
-CONSTANT_50 = CONSTANT_50
-
-
-PORT_4 = PORT_4
-CONSTANT_5 = CONSTANT_5
-CONSTANT_50 = CONSTANT_50
-
-
-
-PORT_4 = PORT_4
-CONSTANT_5 = CONSTANT_5
-CONSTANT_50 = CONSTANT_50
-
-PORT_4 = PORT_4
-CONSTANT_5 = CONSTANT_5
-CONSTANT_50 = CONSTANT_50
-
 """Auto-generate usage examples from public signatures and entry points."""
 
 from pathlib import Path
@@ -37,10 +7,12 @@ from code2llm.api import AnalysisResult, FunctionInfo, ClassInfo
 
 from ..config import Code2DocsConfig
 
-# Default type hints → example values
+PORT_4 = 4
+CONSTANT_5 = 5
+CONSTANT_50 = 50
 
-if __name__ == "__main__":
-    _TYPE_EXAMPLES = {
+# Default type hints → example values
+_TYPE_EXAMPLES = {
     "str": '"./my-project"',
     "Path": 'Path("./my-project")',
     "int": "10",
@@ -55,7 +27,7 @@ if __name__ == "__main__":
 }
 
 # Arg name → realistic example value
-    _ARG_EXAMPLES = {
+_ARG_EXAMPLES = {
     "project_path": '"./my-project"',
     "path": '"./my-project"',
     "source": '"./src"',

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/generators/readme_gen.py

@@ -57,7 +57,38 @@ class ReadmeGenerator:
         project_description = self._generate_description(project_name, entry_points)
         metadata = self._extract_project_metadata()
         extras = self._extract_extras()
-        return {'project_name': project_name, 'project_path': self.result.project_path, 'project_description': project_description, 'badges': generate_badges(project_name, self.config.readme.badges, stats, deps), 'stats': stats, 'avg_complexity': avg_complexity, 'dependencies': deps, 'endpoints': endpoints, 'public_functions': public_functions, 'public_classes': public_classes, 'entry_points': entry_points, 'module_tree': module_tree, 'modules': self.result.modules, 'sync_markers': self.config.readme.sync_markers, 'author': metadata.get('author', ''), 'license': metadata.get('license', ''), 'license_file': metadata.get('license_file', ''), 'contributors': metadata.get('contributors', []), 'repo_url': self.config.repo_url, 'version': metadata.get('version', '0.1.0'), 'extras': extras}
+        lang = getattr(deps, 'language', 'python') or 'python'
+        docs_nav_items, generated_files = self._collect_existing_docs()
+        has_contributing = (Path(self.result.project_path) / 'CONTRIBUTING.md').exists()
+        return {'docs_nav_items': docs_nav_items, 'generated_files': generated_files, 'has_contributing': has_contributing, 'project_name': project_name, 'project_path': self.result.project_path, 'project_description': project_description, 'badges': generate_badges(project_name, self.config.readme.badges, stats, deps), 'stats': stats, 'avg_complexity': avg_complexity, 'dependencies': deps, 'language': lang, 'endpoints': endpoints, 'public_functions': public_functions, 'public_classes': public_classes, 'entry_points': entry_points, 'module_tree': module_tree, 'modules': self.result.modules, 'sync_markers': self.config.readme.sync_markers, 'author': metadata.get('author', ''), 'license': metadata.get('license', ''), 'license_file': metadata.get('license_file', ''), 'contributors': metadata.get('contributors', []), 'repo_url': self.config.repo_url, 'version': metadata.get('version', '0.1.0'), 'extras': extras}
+
+    _DOC_FILE_SPECS = [
+        ('docs/getting-started.md', 'Getting Started', '🚀', 'Quick start guide'),
+        ('docs/api.md', 'API Reference', '📚', 'Complete API documentation'),
+        ('docs/modules.md', 'Module Reference', '📦', 'Module reference with metrics'),
+        ('docs/architecture.md', 'Architecture', '🏛️', 'Architecture with diagrams'),
+        ('docs/dependency-graph.md', 'Dependency Graph', '🔗', 'Module dependency graphs'),
+        ('docs/coverage.md', 'Coverage', '📊', 'Docstring coverage report'),
+        ('docs/configuration.md', 'Configuration', '🔧', 'Configuration reference'),
+        ('docs/api-changelog.md', 'API Changelog', '📝', 'API change tracking'),
+        ('CONTRIBUTING.md', 'Contributing', '🤝', 'Contribution guidelines'),
+        ('examples', 'Examples', '💡', 'Usage examples and code samples'),
+        ('mkdocs.yml', 'MkDocs Config', '⚙️', 'MkDocs site configuration'),
+    ]
+
+    def _collect_existing_docs(self) -> tuple:
+        """Return (docs_nav_items, generated_files) only for files/dirs that exist."""
+        project = Path(self.result.project_path)
+        nav_items = []
+        generated = []
+        for rel_path, title, icon, description in self._DOC_FILE_SPECS:
+            target = project / rel_path
+            if not target.exists():
+                continue
+            link = f'./{rel_path}'
+            nav_items.append({'title': title, 'icon': icon, 'path': link, 'description': description})
+            generated.append({'output': rel_path, 'description': description, 'link': link})
+        return nav_items, generated
 
     def _calc_avg_complexity(self) -> float:
         """Calculate average cyclomatic complexity."""
@@ -179,14 +210,19 @@ class ReadmeGenerator:
             pass
 
     def _detect_license(self, metadata: Dict) -> None:
-        """Detect license type from LICENSE files."""
-        license_paths = [Path(self.result.project_path) / lf for lf in ['LICENSE', 'LICENSE.txt', 'LICENSE.md', 'COPYING']]
-        parent_path = Path(self.result.project_path).parent
-        if parent_path != Path(self.result.project_path):
-            license_paths += [parent_path / lf for lf in ['LICENSE', 'LICENSE.txt', 'LICENSE.md', 'COPYING']]
-        for license_path in license_paths:
+        """Detect license type from LICENSE files.
+
+        Only sets ``license_file`` (used as a link target) when the file lives
+        in the project root, so README links resolve correctly.
+        """
+        project_root = Path(self.result.project_path)
+        in_project = [project_root / lf for lf in ['LICENSE', 'LICENSE.txt', 'LICENSE.md', 'COPYING']]
+        parent = project_root.parent
+        in_parent = [parent / lf for lf in ['LICENSE', 'LICENSE.txt', 'LICENSE.md', 'COPYING']] if parent != project_root else []
+        for license_path in in_project + in_parent:
             if license_path.exists():
-                metadata['license_file'] = license_path.name
+                if license_path.parent == project_root:
+                    metadata['license_file'] = license_path.name
                 if not metadata['license']:
                     try:
                         content = license_path.read_text(encoding='utf-8').lower()

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs/templates/readme.md.j2

@@ -23,6 +23,50 @@
 {% if "install" in sections %}
 ## Installation
 
+{% if language == 'php' %}
+### Requirements
+
+{% if dependencies and dependencies.runtime_version %}- PHP {{ dependencies.runtime_version }}
+{% else %}- PHP 8.0+
+{% endif %}- [Composer](https://getcomposer.org/)
+
+### From Source
+
+```bash
+git clone {{ repo_url or '<repository-url>' }}
+cd {{ project_name }}
+composer install
+```
+{% elif language in ('javascript', 'typescript') %}
+### Requirements
+
+{% if dependencies and dependencies.runtime_version %}- Node.js {{ dependencies.runtime_version }}
+{% else %}- Node.js 18+
+{% endif %}
+### From Source
+
+```bash
+git clone {{ repo_url or '<repository-url>' }}
+cd {{ project_name }}
+{{ dependencies.install_command if dependencies and dependencies.install_command else 'npm install' }}
+```
+{% elif language == 'rust' %}
+### From Source
+
+```bash
+git clone {{ repo_url or '<repository-url>' }}
+cd {{ project_name }}
+cargo build --release
+```
+{% elif language == 'go' %}
+### From Source
+
+```bash
+git clone {{ repo_url or '<repository-url>' }}
+cd {{ project_name }}
+go build ./...
+```
+{% else %}
 ### From PyPI
 
 ```bash
@@ -46,10 +90,37 @@ pip install -e .
 ```
 {% endif %}
 {% endif %}
+{% endif %}
 
 {% if "quickstart" in sections %}
 ## Quick Start
 
+{% if language == 'php' %}
+Serve the project with your preferred PHP runtime (built-in server shown for local development):
+
+```bash
+php -S localhost:8000
+```
+
+Or with Docker Compose if a `docker-compose.yml` is provided:
+
+```bash
+docker compose up
+```
+{% elif language in ('javascript', 'typescript') %}
+```bash
+{% if dependencies and dependencies.install_command %}{{ dependencies.install_command }}
+{% endif %}npm start
+```
+{% elif language == 'rust' %}
+```bash
+cargo run
+```
+{% elif language == 'go' %}
+```bash
+go run .
+```
+{% else %}
 ### CLI Usage
 
 ```bash
@@ -82,6 +153,7 @@ config = Code2DocsConfig(project_name="mylib", verbose=True)
 docs = generate_docs("./my-project", config=config)
 ```
 {% endif %}
+{% endif %}
 
 {% if "generated_output" in sections %}
 ## Generated Output
@@ -171,8 +243,12 @@ Content outside the markers is preserved when regenerating. Enable this with `sy
 
 ```
 {{ project_name }}/
-{% for mod_name, mod in modules.items()|list %}{% if not mod_name.startswith('_') %}{% set parts = mod_name.split('.') %}{{ '    ' * (parts|length - 1) }}├── {{ parts[-1] }}{% if mod.is_package %}/{% endif %}
-{% endif %}{% endfor %}
+{% for mod_name, mod in modules.items()|list -%}
+{% if not mod_name.startswith('_') -%}
+{% set parts = mod_name.split('.') -%}
+{{ '    ' * (parts|length - 1) }}├── {{ parts[-1] }}{% if mod.is_package %}/{% endif %}{{ "\n" -}}
+{% endif -%}
+{% endfor -%}
 ```
 {% endif %}
 
@@ -240,7 +316,7 @@ Content outside the markers is preserved when regenerating. Enable this with `sy
 {% endfor %}
 {% endif %}
 
-We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+{% if has_contributing %}We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.{% else %}We welcome contributions! Open an issue or pull request to get started.{% endif %}
 
 ### Development Setup
 
@@ -249,46 +325,51 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu
 git clone {{ repo_url or '<repository-url>' }}
 cd {{ project_name }}
 
+{% if language == 'php' %}
+# Install dependencies
+composer install
+
+# Run tests
+vendor/bin/phpunit
+{% elif language in ('javascript', 'typescript') %}
+# Install dependencies
+{{ dependencies.install_command if dependencies and dependencies.install_command else 'npm install' }}
+
+# Run tests
+npm test
+{% elif language == 'rust' %}
+# Run tests
+cargo test
+{% elif language == 'go' %}
+# Run tests
+go test ./...
+{% else %}
 # Install in development mode
 pip install -e ".[dev]"
 
 # Run tests
 pytest
+{% endif %}
 ```
 {% endif %}
 
-{% if "docs_nav" in sections %}
+{% if "docs_nav" in sections and docs_nav_items %}
 ## Documentation
 
-{% if repo_url %}
-- 📖 [Full Documentation]({{ repo_url }}/tree/main/docs) — API reference, module docs, architecture
-- 🚀 [Getting Started]({{ repo_url }}/blob/main/docs/getting-started.md) — Quick start guide
-- 📚 [API Reference]({{ repo_url }}/blob/main/docs/api.md) — Complete API documentation
-- 🔧 [Configuration]({{ repo_url }}/blob/main/docs/configuration.md) — Configuration options
-{% else %}
-- 📖 [Full Documentation](./docs) — API reference, module docs, architecture
-- 🚀 [Getting Started](./docs/getting-started.md) — Quick start guide
-- 📚 [API Reference](./docs/api.md) — Complete API documentation
-- 🔧 [Configuration](./docs/configuration.md) — Configuration options
-{% endif %}
-- 💡 [Examples](./examples) — Usage examples and code samples
+{% for item in docs_nav_items %}
+- {{ item.icon }} [{{ item.title }}]({{ item.path }}) — {{ item.description }}
+{% endfor %}
 
+{% if generated_files %}
 ### Generated Files
 
 | Output | Description | Link |
 |--------|-------------|------|
 | `README.md` | Project overview (this file) | — |
-| `docs/api.md` | Consolidated API reference | [View](./docs/api.md) |
-| `docs/modules.md` | Module reference with metrics | [View](./docs/modules.md) |
-| `docs/architecture.md` | Architecture with diagrams | [View](./docs/architecture.md) |
-| `docs/dependency-graph.md` | Dependency graphs | [View](./docs/dependency-graph.md) |
-| `docs/coverage.md` | Docstring coverage report | [View](./docs/coverage.md) |
-| `docs/getting-started.md` | Getting started guide | [View](./docs/getting-started.md) |
-| `docs/configuration.md` | Configuration reference | [View](./docs/configuration.md) |
-| `docs/api-changelog.md` | API change tracking | [View](./docs/api-changelog.md) |
-| `CONTRIBUTING.md` | Contribution guidelines | [View](./CONTRIBUTING.md) |
-| `examples/` | Usage examples | [Browse](./examples) |
-| `mkdocs.yml` | MkDocs configuration | — |
+{% for file in generated_files %}
+| `{{ file.output }}` | {{ file.description }} | [View]({{ file.link }}) |
+{% endfor %}
+{% endif %}
 {% endif %}
 
 {% if sync_markers %}<!-- code2docs:end -->{% endif %}

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code2docs
-Version: 3.0.29
+Version: 3.0.33
 Summary: Auto-generate and sync project documentation from source code analysis
 Author-email: Tom Sapletta <tom@sapletta.com>
 License-Expression: Apache-2.0
@@ -53,17 +53,17 @@ Dynamic: license-file
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-3.0.29-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-23.8h-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-3.0.33-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-25.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (68 commits)
-- 👤 **Human dev:** ~$2384 (23.8h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (73 commits)
+- 👤 **Human dev:** ~$2534 (25.3h @ $100/h, 30min dedup)
 
-Generated on 2026-04-19 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
+Generated on 2026-04-20 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![version](https://img.shields.io/badge/version-3.0.29-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-3.0.33-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -200,7 +200,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-3.0.29-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
+![version](https://img.shields.io/badge/version-3.0.33-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
 > **276** functions | **57** classes | **51** files | CC̄ = 3.8
 
 > Auto-generated project documentation from source code analysis.

{code2docs-3.0.29 → code2docs-3.0.33}/code2docs.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ code2docs/analyzers/__init__.py
 code2docs/analyzers/dependency_scanner.py
 code2docs/analyzers/docstring_extractor.py
 code2docs/analyzers/endpoint_detector.py
+code2docs/analyzers/markdown_validator.py
 code2docs/analyzers/project_scanner.py
 code2docs/examples/advanced_usage.py
 code2docs/examples/quickstart.py
@@ -60,5 +61,6 @@ tests/test_config.py
 tests/test_formatters.py
 tests/test_generators.py
 tests/test_llm_helper.py
+tests/test_markdown_validator.py
 tests/test_registry.py
 tests/test_sync.py

{code2docs-3.0.29 → code2docs-3.0.33}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code2docs"
-version = "3.0.29"
+version = "3.0.33"
 description = "Auto-generate and sync project documentation from source code analysis"
 readme = "README.md"
 requires-python = ">=3.9"

code2docs-3.0.33/tests/test_markdown_validator.py

@@ -0,0 +1,75 @@
+"""Tests for markdown validator."""
+from pathlib import Path
+
+from code2docs.analyzers.markdown_validator import (
+    validate_markdown_file,
+    validate_markdown_tree,
+)
+
+
+def test_validate_broken_link(tmp_path: Path) -> None:
+    md = tmp_path / "README.md"
+    md.write_text(
+        "# Title\n\n"
+        "[missing](./does-not-exist.md)\n"
+        "[existing](./present.md)\n",
+        encoding="utf-8",
+    )
+    (tmp_path / "present.md").write_text("# Present", encoding="utf-8")
+    issues = validate_markdown_file(md, project_root=tmp_path)
+    kinds = {i.kind for i in issues}
+    assert "broken_link" in kinds
+    assert any("does-not-exist" in i.message for i in issues)
+    assert not any("present.md" in i.message for i in issues)
+
+
+def test_validate_ignores_http_and_anchors(tmp_path: Path) -> None:
+    md = tmp_path / "a.md"
+    md.write_text(
+        "[web](https://example.com)\n"
+        "[anchor](#section)\n"
+        "[mail](mailto:x@example.com)\n",
+        encoding="utf-8",
+    )
+    assert validate_markdown_file(md, project_root=tmp_path) == []
+
+
+def test_validate_ignores_links_in_code_fences(tmp_path: Path) -> None:
+    md = tmp_path / "a.md"
+    md.write_text(
+        "```\n[missing](./nope.md)\n```\n",
+        encoding="utf-8",
+    )
+    assert validate_markdown_file(md, project_root=tmp_path) == []
+
+
+def test_validate_detects_table_shape(tmp_path: Path) -> None:
+    md = tmp_path / "a.md"
+    md.write_text(
+        "| a | b | c |\n"
+        "|---|---|---|\n"
+        "| 1 | 2 |\n",
+        encoding="utf-8",
+    )
+    issues = validate_markdown_file(md, project_root=tmp_path)
+    assert any(i.kind == "table_shape" for i in issues)
+
+
+def test_validate_detects_duplicate_headings(tmp_path: Path) -> None:
+    md = tmp_path / "a.md"
+    md.write_text(
+        "## Intro\n\n## Intro\n",
+        encoding="utf-8",
+    )
+    issues = validate_markdown_file(md, project_root=tmp_path)
+    assert any(i.kind == "duplicate_heading" for i in issues)
+
+
+def test_validate_tree_skips_ignored_dirs(tmp_path: Path) -> None:
+    (tmp_path / "good.md").write_text("# ok\n", encoding="utf-8")
+    vendor = tmp_path / "vendor"
+    vendor.mkdir()
+    (vendor / "bad.md").write_text("[x](./missing.md)\n", encoding="utf-8")
+    report = validate_markdown_tree(tmp_path)
+    assert report.files_checked == 1
+    assert report.ok