patchwork-conventions 0.1.0__py3-none-any.whl

patchwork/output/report.py

@@ -0,0 +1,417 @@
+"""
+ConventionReport — the aggregated result of a scan.
+Can render to:
+  - Markdown (CONVENTIONS.md)
+  - AGENTS.md format
+  - JSON (for MCP/programmatic use)
+  - Rich terminal summary
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from patchwork.miners.config_detector import ProjectConfig
+    from patchwork.miners.naming import NamingResult
+    from patchwork.miners.imports import ImportResult
+    from patchwork.miners.structure import StructureResult
+    from patchwork.miners.error_handling import ErrorResult
+    from patchwork.miners.testing import TestingResult
+    from patchwork.miners.api_patterns import APIResult
+    from patchwork.miners.git_patterns import GitResult
+
+
+@dataclass
+class ConventionReport:
+    root: Path
+    config: "ProjectConfig | None" = None
+    file_count: int = 0
+    by_lang: dict[str, int] = field(default_factory=dict)
+    naming: dict[str, "NamingResult"] = field(default_factory=dict)
+    imports: dict[str, "ImportResult"] = field(default_factory=dict)
+    structure: "StructureResult | None" = None
+    errors: dict[str, "ErrorResult"] = field(default_factory=dict)
+    testing: dict[str, "TestingResult"] = field(default_factory=dict)
+    api: dict[str, "APIResult"] = field(default_factory=dict)
+    git: "GitResult | None" = None
+    elapsed: float = 0.0
+
+    # ── Rendering ─────────────────────────────────────────────────────────────
+
+    def to_markdown(self, *, agents_md: bool = False) -> str:
+        """Render full CONVENTIONS.md (or AGENTS.md) content."""
+        lines: list[str] = []
+        filename = "AGENTS.md" if agents_md else "CONVENTIONS.md"
+        ts = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+        lines += [
+            f"# {filename}",
+            f"> Auto-generated by [patchwork](https://github.com/yourusername/patchwork) on {ts}  ",
+            f"> Scanned {self.file_count} files in {self.elapsed:.1f}s",
+            f"> **Do not edit manually** — run `patchwork update` to refresh",
+            "",
+        ]
+
+        # Tech stack
+        if self.config:
+            lines += self._section_stack()
+
+        # Project structure
+        if self.structure:
+            lines += self._section_structure()
+
+        # Naming conventions (per language)
+        if self.naming:
+            lines += self._section_naming()
+
+        # Import conventions
+        if self.imports:
+            lines += self._section_imports()
+
+        # Error handling
+        if self.errors:
+            lines += self._section_errors()
+
+        # Testing conventions
+        if self.testing:
+            lines += self._section_testing()
+
+        # API patterns
+        if self.api:
+            lines += self._section_api()
+
+        # Git conventions
+        if self.git:
+            lines += self._section_git()
+
+        # Quick reference card (AI-optimised)
+        lines += self._section_quick_ref()
+
+        return "\n".join(lines)
+
+    def to_json(self) -> str:
+        """Return JSON-serialisable dict of all findings."""
+        return json.dumps(self._to_dict(), indent=2, default=str)
+
+    def _to_dict(self) -> dict:
+        def _conv(obj):
+            if hasattr(obj, "__dataclass_fields__"):
+                return {k: _conv(v) for k, v in obj.__dict__.items()}
+            if isinstance(obj, dict):
+                return {k: _conv(v) for k, v in obj.items()}
+            if isinstance(obj, list):
+                return [_conv(v) for v in obj]
+            if isinstance(obj, Path):
+                return str(obj)
+            return obj
+
+        return {
+            "root": str(self.root),
+            "scanned_at": datetime.now(timezone.utc).isoformat(),
+            "file_count": self.file_count,
+            "by_lang": self.by_lang,
+            "elapsed_s": round(self.elapsed, 3),
+            "config": _conv(self.config),
+            "naming": _conv(self.naming),
+            "imports": _conv(self.imports),
+            "structure": _conv(self.structure),
+            "errors": _conv(self.errors),
+            "testing": _conv(self.testing),
+            "api": _conv(self.api),
+            "git": _conv(self.git),
+        }
+
+    # ── Section builders ──────────────────────────────────────────────────────
+
+    def _section_stack(self) -> list[str]:
+        cfg = self.config
+        lines = ["## Tech Stack", ""]
+        if cfg.name:
+            lines.append(f"**Project:** `{cfg.name}`" + (f" v{cfg.version}" if cfg.version else ""))
+        if cfg.language:
+            lines.append(f"**Language:** {cfg.language}")
+        if cfg.runtime:
+            lines.append(f"**Runtime:** {cfg.runtime}")
+        if cfg.package_manager:
+            lines.append(f"**Package Manager:** {cfg.package_manager}")
+        if cfg.frameworks:
+            lines.append(f"**Frameworks:** {', '.join(cfg.frameworks)}")
+        if cfg.linters:
+            lines.append(f"**Linters:** {', '.join(cfg.linters)}")
+        if cfg.formatters:
+            lines.append(f"**Formatters:** {', '.join(cfg.formatters)}")
+        if cfg.type_checker:
+            lines.append(f"**Type Checker:** {cfg.type_checker}")
+        if cfg.build_tool:
+            lines.append(f"**Build Tool:** {cfg.build_tool}")
+        if cfg.has_docker:
+            lines.append("**Docker:** yes")
+        if cfg.has_ci and cfg.ci_platform:
+            lines.append(f"**CI:** {cfg.ci_platform}")
+        if cfg.scripts:
+            lines.append("")
+            lines.append("**Key Scripts:**")
+            lines.append("```")
+            for name, cmd in cfg.scripts.items():
+                lines.append(f"{name}: {cmd}")
+            lines.append("```")
+        lines.append("")
+        return lines
+
+    def _section_structure(self) -> list[str]:
+        s = self.structure
+        lines = ["## Project Structure", ""]
+        if s.is_monorepo:
+            lines.append(f"**Layout:** Monorepo ({len(s.monorepo_packages)} packages)")
+            for pkg in s.monorepo_packages[:8]:
+                lines.append(f"  - `{pkg}/`")
+        else:
+            if s.source_root:
+                lines.append(f"**Source root:** `{s.source_root}/`")
+            if s.organisation:
+                lines.append(f"**Organisation:** {s.organisation}-based")
+            if s.test_layout:
+                test_dirs = (", ".join(f"`{d}/`" for d in s.test_dirs)
+                             if s.test_dirs else "co-located")
+                lines.append(f"**Tests:** {s.test_layout} ({test_dirs})")
+            if s.key_dirs:
+                lines.append("")
+                lines.append("**Key directories:**")
+                for d, role in s.key_dirs.items():
+                    lines.append(f"  - `{d}/` — {role}")
+        if s.notes:
+            for note in s.notes:
+                lines.append(f"> {note}")
+        lines.append("")
+        return lines
+
+    def _section_naming(self) -> list[str]:
+        lines = ["## Naming Conventions", ""]
+        for lang, nr in self.naming.items():
+            if not any([nr.functions, nr.classes, nr.variables]):
+                continue
+            lines.append(f"### {lang.capitalize()}", )
+            lines.append("")
+
+            if nr.functions:
+                conf_pct = int(nr.functions.confidence * 100)
+                lines.append(
+                    f"- **Functions:** `{nr.functions.style}` "
+                    f"({conf_pct}% consistent)"
+                )
+                if nr.functions.examples:
+                    lines.append(
+                        f"  - Examples: {', '.join(f'`{e}`' for e in nr.functions.examples[:4])}"
+                    )
+                if nr.functions.counter_examples and nr.functions.confidence < 0.9:
+                    lines.append(
+                        f"  - Exceptions: {', '.join(f'`{e}`' for e in nr.functions.counter_examples[:2])}"
+                    )
+
+            if nr.classes:
+                conf_pct = int(nr.classes.confidence * 100)
+                lines.append(
+                    f"- **Classes:** `{nr.classes.style}` ({conf_pct}% consistent)"
+                )
+                if nr.classes.examples:
+                    lines.append(
+                        f"  - Examples: {', '.join(f'`{e}`' for e in nr.classes.examples[:4])}"
+                    )
+
+            if nr.variables:
+                lines.append(f"- **Variables:** `{nr.variables.style}`")
+
+            if nr.constants and nr.constants.examples:
+                lines.append(f"- **Constants:** `{nr.constants.style}`")
+                if nr.constants.examples:
+                    lines.append(
+                        f"  - Examples: {', '.join(f'`{e}`' for e in nr.constants.examples[:3])}"
+                    )
+
+            if nr.files:
+                lines.append(f"- **Files:** `{nr.files.style}`")
+
+            if nr.private_prefix:
+                lines.append(f"- **Private prefix:** `{nr.private_prefix}`")
+
+            if nr.test_prefix:
+                lines.append(f"- **Test functions:** prefix `{nr.test_prefix}`")
+
+            for note in nr.notes:
+                lines.append(f"> ⚠️ {note}")
+
+            lines.append("")
+
+        return lines
+
+    def _section_imports(self) -> list[str]:
+        lines = ["## Import Conventions", ""]
+        for lang, ir in self.imports.items():
+            lines.append(f"### {lang.capitalize()}")
+            lines.append("")
+            lines.append(f"- **Style:** {ir.style} imports")
+            if ir.aliases_used:
+                lines.append(f"- **Path aliases:** {', '.join(f'`{a}`' for a in ir.aliases_used)}")
+            if ir.destructuring:
+                lines.append(f"- **Import syntax:** {ir.destructuring}")
+            if ir.barrel_files:
+                lines.append(f"- **Barrel files:** `index.ts` re-exports are used")
+            if ir.common_third_party:
+                lines.append(
+                    f"- **Key dependencies:** "
+                    f"{', '.join(f'`{p}`' for p in ir.common_third_party[:6])}"
+                )
+            lines.append("")
+        return lines
+
+    def _section_errors(self) -> list[str]:
+        lines = ["## Error Handling", ""]
+        for lang, er in self.errors.items():
+            lines.append(f"### {lang.capitalize()}")
+            lines.append("")
+            lines.append(f"- **Pattern:** {er.primary_pattern}")
+            if er.propagation_style:
+                lines.append(f"- **Propagation:** {er.propagation_style}")
+            if er.logging_framework:
+                lines.append(f"- **Logging:** `{er.logging_framework}`")
+            if er.exception_naming:
+                lines.append(f"- **Custom exception naming:** {er.exception_naming}")
+            if er.custom_exceptions:
+                lines.append(
+                    f"- **Custom exceptions:** "
+                    f"{', '.join(f'`{e}`' for e in er.custom_exceptions[:6])}"
+                )
+            for note in er.notes:
+                lines.append(f"> {note}")
+            lines.append("")
+        return lines
+
+    def _section_testing(self) -> list[str]:
+        lines = ["## Testing Conventions", ""]
+        for lang, tr in self.testing.items():
+            if tr.test_file_count == 0 and not tr.framework:
+                continue
+            lines.append(f"### {lang.capitalize()}")
+            lines.append("")
+            if tr.framework:
+                lines.append(f"- **Framework:** {tr.framework}")
+            lines.append(
+                f"- **Coverage:** {tr.test_file_count} test files / "
+                f"{tr.source_file_count} source files "
+                f"({int(tr.test_ratio * 100)}% ratio)"
+            )
+            if tr.organisation:
+                lines.append(f"- **Organisation:** {tr.organisation}")
+            if tr.assertion_style:
+                lines.append(f"- **Assertions:** `{tr.assertion_style}(...)`")
+            if tr.has_coverage and tr.coverage_tool:
+                lines.append(f"- **Coverage tool:** `{tr.coverage_tool}`")
+            if tr.has_mocking and tr.mock_library:
+                lines.append(f"- **Mocking:** `{tr.mock_library}`")
+            flags = []
+            if tr.has_fixtures:
+                flags.append("fixtures")
+            if tr.has_factories:
+                flags.append("factories")
+            if flags:
+                lines.append(f"- **Patterns:** {', '.join(flags)}")
+            lines.append("")
+        return lines
+
+    def _section_api(self) -> list[str]:
+        lines = ["## API Patterns", ""]
+        for lang, ar in self.api.items():
+            lines.append(f"### {lang.capitalize()}")
+            lines.append("")
+            if ar.api_frameworks:
+                lines.append(f"- **Framework:** {', '.join(ar.api_frameworks)}")
+            if ar.async_pattern:
+                lines.append(f"- **Async style:** {ar.async_pattern}")
+            if ar.response_shape:
+                lines.append(f"- **Response shape:** `{ar.response_shape}`")
+            if ar.route_param_style:
+                lines.append(f"- **Route params:** {ar.route_param_style}")
+            if ar.orm:
+                lines.append(f"- **ORM/Query layer:** {ar.orm}")
+            if ar.http_client:
+                lines.append(f"- **HTTP client:** `{ar.http_client}`")
+            if ar.has_graphql:
+                lines.append("- **GraphQL:** yes")
+            if ar.has_grpc:
+                lines.append("- **gRPC/protobuf:** yes")
+            lines.append("")
+        return lines
+
+    def _section_git(self) -> list[str]:
+        if not self.git:
+            return []
+        g = self.git
+        lines = ["## Git Conventions", ""]
+        if g.commit_style:
+            lines.append(f"- **Commit style:** {g.commit_style}")
+        if g.commit_examples:
+            lines.append("- **Examples:**")
+            for ex in g.commit_examples[:3]:
+                lines.append(f"  - `{ex}`")
+        if g.branch_style:
+            lines.append(f"- **Branch naming:** {g.branch_style}")
+        if g.avg_files_per_commit > 0:
+            lines.append(f"- **Avg files/commit:** {g.avg_files_per_commit}")
+        for note in g.notes:
+            lines.append(f"> {note}")
+        if g.cochange_pairs:
+            lines.append("")
+            lines.append("**Files that change together:**")
+            for a, b, count in g.cochange_pairs[:3]:
+                lines.append(f"  - `{a}` ↔ `{b}` ({count}x)")
+        lines.append("")
+        return lines
+
+    def _section_quick_ref(self) -> list[str]:
+        """AI-optimised quick reference — most useful for agents."""
+        lines = ["## Quick Reference", "", "<!-- AI agents: read this section first -->", ""]
+        lines.append("| Convention | Rule |")
+        lines.append("|---|---|")
+
+        for lang, nr in self.naming.items():
+            if nr.functions:
+                lines.append(
+                    f"| {lang} functions | `{nr.functions.style}` "
+                    f"({int(nr.functions.confidence * 100)}% consistent) |"
+                )
+            if nr.classes:
+                lines.append(f"| {lang} classes | `{nr.classes.style}` |")
+
+        if self.structure:
+            s = self.structure
+            if s.source_root:
+                lines.append(f"| Source root | `{s.source_root}/` |")
+            if s.test_layout:
+                lines.append(f"| Test layout | {s.test_layout} |")
+            if s.organisation:
+                lines.append(f"| Structure | {s.organisation}-based |")
+
+        for lang, er in self.errors.items():
+            lines.append(f"| {lang} errors | {er.primary_pattern} |")
+
+        for lang, tr in self.testing.items():
+            if tr.framework:
+                lines.append(f"| {lang} test framework | {tr.framework} |")
+
+        if self.git and self.git.commit_style:
+            lines.append(f"| Commit style | {self.git.commit_style} |")
+
+        if self.config:
+            if self.config.package_manager:
+                lines.append(f"| Package manager | {self.config.package_manager} |")
+            if self.config.linters:
+                lines.append(f"| Linters | {', '.join(self.config.linters)} |")
+            if self.config.formatters:
+                lines.append(f"| Formatters | {', '.join(self.config.formatters)} |")
+
+        lines.append("")
+        return lines

patchwork/scanner.py

@@ -0,0 +1,162 @@
+"""
+Core scanner: discovers files, dispatches language miners, aggregates results.
+"""
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator
+
+import pathspec
+
+from patchwork.miners.naming import NamingMiner
+from patchwork.miners.imports import ImportMiner
+from patchwork.miners.structure import StructureMiner
+from patchwork.miners.error_handling import ErrorHandlingMiner
+from patchwork.miners.testing import TestingMiner
+from patchwork.miners.api_patterns import APIPatternMiner
+from patchwork.miners.git_patterns import GitPatternMiner
+from patchwork.miners.config_detector import ConfigDetector
+from patchwork.output.report import ConventionReport  # noqa: E402 — keep at top
+
+# File extensions → language tags
+LANGUAGE_MAP: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".rb": "ruby",
+    ".php": "php",
+    ".cs": "csharp",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".c": "c",
+    ".h": "c",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".scala": "scala",
+}
+
+DEFAULT_IGNORE_PATTERNS = [
+    "node_modules/", ".git/", "__pycache__/", ".venv/", "venv/",
+    "dist/", "build/", ".next/", ".nuxt/", "target/",
+    "*.min.js", "*.min.css", "*.bundle.js",
+    "*.lock", "package-lock.json", "yarn.lock",
+    ".mypy_cache/", ".pytest_cache/", ".ruff_cache/",
+    "*.egg-info/", "site-packages/",
+    "vendor/", "third_party/",
+    "*.pb.go", "*.generated.*", "*_gen.*",
+]
+
+
+@dataclass
+class ScanOptions:
+    root: Path
+    max_files: int = 500
+    max_file_size_kb: int = 500
+    include_git: bool = True
+    languages: list[str] = field(default_factory=list)  # empty = all
+    extra_ignore: list[str] = field(default_factory=list)
+    verbose: bool = False
+
+
+def _build_ignore_spec(root: Path, extra: list[str]) -> pathspec.PathSpec:
+    patterns = list(DEFAULT_IGNORE_PATTERNS) + extra
+    gitignore = root / ".gitignore"
+    if gitignore.exists():
+        with open(gitignore) as f:
+            patterns.extend(f.read().splitlines())
+    return pathspec.PathSpec.from_lines("gitignore", patterns)
+
+
+def _iter_source_files(
+    root: Path,
+    spec: pathspec.PathSpec,
+    languages: list[str],
+    max_files: int,
+    max_file_size_kb: int,
+) -> Iterator[tuple[Path, str]]:
+    """Yield (path, language) for every scannable source file."""
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel_dir = Path(dirpath).relative_to(root)
+        # Prune ignored directories in-place
+        dirnames[:] = [
+            d for d in dirnames
+            if not spec.match_file(str(rel_dir / d) + "/")
+        ]
+        for fname in filenames:
+            fpath = Path(dirpath) / fname
+            rel = fpath.relative_to(root)
+            if spec.match_file(str(rel)):
+                continue
+            lang = LANGUAGE_MAP.get(fpath.suffix.lower())
+            if lang is None:
+                continue
+            if languages and lang not in languages:
+                continue
+            if fpath.stat().st_size > max_file_size_kb * 1024:
+                continue
+            yield fpath, lang
+            count += 1
+            if count >= max_files:
+                return
+
+
+def scan(opts: ScanOptions) -> ConventionReport:
+    """
+    Full pipeline: discover → mine → aggregate → return ConventionReport.
+    """
+    t0 = time.perf_counter()
+    root = opts.root.resolve()
+
+    # Detect project config/stack first (no AST needed)
+    config = ConfigDetector(root).detect()
+
+    # Discover all source files
+    spec = _build_ignore_spec(root, opts.extra_ignore)
+    files: list[tuple[Path, str]] = list(
+        _iter_source_files(root, spec, opts.languages, opts.max_files, opts.max_file_size_kb)
+    )
+
+    if not files:
+        return ConventionReport(root=root, config=config, elapsed=time.perf_counter() - t0)
+
+    # Group by language for efficient miner dispatch
+    by_lang: dict[str, list[Path]] = {}
+    for fpath, lang in files:
+        by_lang.setdefault(lang, []).append(fpath)
+
+    # Run all miners
+    naming = NamingMiner().mine(by_lang)
+    imports = ImportMiner().mine(by_lang)
+    structure = StructureMiner(root).mine(files)
+    errors = ErrorHandlingMiner().mine(by_lang)
+    testing = TestingMiner(root).mine(by_lang)
+    api = APIPatternMiner().mine(by_lang)
+    git = GitPatternMiner(root).mine() if opts.include_git else None
+
+    elapsed = time.perf_counter() - t0
+
+    return ConventionReport(
+        root=root,
+        config=config,
+        file_count=len(files),
+        by_lang={lang: len(paths) for lang, paths in by_lang.items()},
+        naming=naming,
+        imports=imports,
+        structure=structure,
+        errors=errors,
+        testing=testing,
+        api=api,
+        git=git,
+        elapsed=elapsed,
+    )