patchwork-conventions 0.1.0__py3-none-any.whl

patchwork/miners/structure.py

@@ -0,0 +1,204 @@
+"""
+StructureMiner — Detects project layout conventions:
+  - Source root (src/, lib/, app/)
+  - Test layout (tests/, __tests__/, *.test.ts co-location)
+  - Feature vs layer organisation
+  - Monorepo vs single-package
+  - Key directories and their roles
+"""
+from __future__ import annotations
+
+import os
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class StructureResult:
+    source_root: str | None             # e.g. 'src', 'lib', None (flat)
+    test_layout: str | None             # 'colocated' | 'separate' | 'both'
+    test_dirs: list[str]
+    organisation: str | None            # 'feature' | 'layer' | 'flat'
+    is_monorepo: bool
+    monorepo_packages: list[str]        # e.g. ['packages/api', 'packages/web']
+    key_dirs: dict[str, str]            # dir → role description
+    depth_avg: float                    # average nesting depth
+    notes: list[str] = field(default_factory=list)
+
+
+_KNOWN_SOURCE_ROOTS = ["src", "lib", "app", "source", "core", "pkg"]
+_KNOWN_TEST_DIRS = ["tests", "test", "__tests__", "spec", "specs", "e2e"]
+_LAYER_DIRS = {"controllers", "services", "models", "views", "routes",
+               "middleware", "utils", "helpers", "handlers", "repositories",
+               "components", "pages", "hooks", "stores", "api"}
+_FEATURE_SIGNAL = 4   # if a dir has ≥4 of the above names as siblings, it's layer-based
+
+
+def _top_dirs(root: Path) -> list[str]:
+    try:
+        return [
+            d.name for d in root.iterdir()
+            if d.is_dir() and not d.name.startswith(".")
+        ]
+    except PermissionError:
+        return []
+
+
+def _detect_source_root(top_dirs: list[str]) -> str | None:
+    for name in _KNOWN_SOURCE_ROOTS:
+        if name in top_dirs:
+            return name
+    return None
+
+
+def _detect_test_layout(files: list[tuple[Path, str]]) -> tuple[str | None, list[str]]:
+    colocated = 0
+    separate_dirs: set[str] = set()
+
+    for path, _ in files:
+        parts = path.parts
+        stem = path.stem
+        # Co-located: *.test.ts / *.spec.js / test_*.py next to source
+        if any(x in stem for x in (".test", ".spec", "test_")) or (
+            stem.startswith("test_") or stem.endswith("_test")
+        ):
+            # Check if it's inside a dedicated test dir
+            if any(p in _KNOWN_TEST_DIRS for p in parts):
+                separate_dirs.add(next(p for p in parts if p in _KNOWN_TEST_DIRS))
+            else:
+                colocated += 1
+
+    layout = None
+    if colocated > 0 and separate_dirs:
+        layout = "both"
+    elif colocated > 0:
+        layout = "colocated"
+    elif separate_dirs:
+        layout = "separate"
+
+    return layout, sorted(separate_dirs)
+
+
+def _detect_organisation(root: Path, source_root: str | None) -> str | None:
+    """Heuristic: if the immediate children of src/ look like layers, it's layer-based."""
+    check_root = root / source_root if source_root else root
+    try:
+        children = {d.name.lower() for d in check_root.iterdir() if d.is_dir()}
+    except (PermissionError, OSError):
+        return None
+    layer_hits = children & _LAYER_DIRS
+    if len(layer_hits) >= 3:
+        return "layer"
+    # Feature-based: children are domain names, each containing index/types
+    feature_signals = 0
+    for child in check_root.iterdir():
+        if child.is_dir():
+            sub = {d.name for d in child.iterdir() if d.is_dir() or d.is_file()}
+            if any(n in sub for n in ("index.ts", "index.js", "types.ts", "types.py")):
+                feature_signals += 1
+    if feature_signals >= 3:
+        return "feature"
+    return "flat"
+
+
+def _detect_monorepo(root: Path, top_dirs: list[str]) -> tuple[bool, list[str]]:
+    monorepo_roots = ["packages", "apps", "services", "libs", "modules"]
+    for mr in monorepo_roots:
+        if mr in top_dirs:
+            mr_path = root / mr
+            try:
+                pkgs = [
+                    f"{mr}/{d.name}"
+                    for d in mr_path.iterdir()
+                    if d.is_dir() and (d / "package.json").exists()
+                    or (d / "pyproject.toml").exists()
+                    or (d / "go.mod").exists()
+                ]
+                if len(pkgs) >= 2:
+                    return True, pkgs[:10]
+            except (PermissionError, OSError):
+                pass
+    return False, []
+
+
+def _avg_depth(files: list[tuple[Path, str]], root: Path) -> float:
+    if not files:
+        return 0.0
+    return round(
+        sum(len(p.relative_to(root).parts) for p, _ in files) / len(files), 1
+    )
+
+
+_DIR_ROLES = {
+    "src": "source root",
+    "lib": "source root / shared libraries",
+    "app": "application source",
+    "tests": "test suite",
+    "test": "test suite",
+    "__tests__": "co-located Jest test suite",
+    "spec": "test suite (RSpec/Jasmine style)",
+    "docs": "documentation",
+    "scripts": "build / utility scripts",
+    "config": "configuration files",
+    "public": "static assets served publicly",
+    "static": "static assets",
+    "assets": "static assets",
+    "migrations": "database migrations",
+    "db": "database-related code",
+    "api": "API layer",
+    "models": "data models",
+    "views": "view layer / templates",
+    "controllers": "controller layer",
+    "services": "service layer",
+    "utils": "utility functions",
+    "helpers": "helper functions",
+    "hooks": "React / lifecycle hooks",
+    "components": "UI components",
+    "pages": "page components (Next.js / Nuxt style)",
+    "types": "TypeScript type definitions",
+    "interfaces": "TypeScript interfaces",
+    "constants": "shared constants",
+    "middleware": "middleware layer",
+    "routes": "route definitions",
+    "plugins": "plugin definitions",
+    "store": "state management store",
+    "stores": "state management stores",
+    "i18n": "internationalisation strings",
+    "locales": "locale/translation files",
+}
+
+
+class StructureMiner:
+    def __init__(self, root: Path):
+        self.root = root
+
+    def mine(self, files: list[tuple[Path, str]]) -> StructureResult:
+        top = _top_dirs(self.root)
+        source_root = _detect_source_root(top)
+        test_layout, test_dirs = _detect_test_layout(files)
+        organisation = _detect_organisation(self.root, source_root)
+        is_mono, mono_pkgs = _detect_monorepo(self.root, top)
+        depth = _avg_depth(files, self.root)
+
+        key_dirs = {
+            name: role
+            for name, role in _DIR_ROLES.items()
+            if name in top
+        }
+
+        notes: list[str] = []
+        if is_mono:
+            notes.append(f"Monorepo with {len(mono_pkgs)} packages")
+
+        return StructureResult(
+            source_root=source_root,
+            test_layout=test_layout,
+            test_dirs=test_dirs,
+            organisation=organisation,
+            is_monorepo=is_mono,
+            monorepo_packages=mono_pkgs,
+            key_dirs=key_dirs,
+            depth_avg=depth,
+            notes=notes,
+        )

patchwork/miners/testing.py

@@ -0,0 +1,204 @@
+"""
+TestingMiner — Detects testing conventions:
+  - Framework (pytest / unittest / jest / vitest / go test / etc.)
+  - Test organisation (describe/it / class-based / function-based)
+  - Coverage tooling present
+  - Fixture/factory patterns
+  - Assertion style (assert vs expect vs should)
+  - Test file ratio
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class TestingResult:
+    framework: str | None
+    test_file_count: int
+    source_file_count: int
+    test_ratio: float               # test files / source files
+    organisation: str | None        # 'describe/it' | 'class-based' | 'function-based'
+    assertion_style: str | None     # 'assert' | 'expect' | 'should' | 'mixed'
+    has_coverage: bool
+    coverage_tool: str | None
+    has_fixtures: bool
+    has_factories: bool
+    has_mocking: bool
+    mock_library: str | None
+    notes: list[str] = field(default_factory=list)
+
+
+_FRAMEWORK_SIGNALS = {
+    "python": {
+        "pytest": [r"\bimport pytest\b", r"\bfrom pytest\b", r"@pytest\.fixture", r"def test_"],
+        "unittest": [r"\bimport unittest\b", r"class\s+\w+\(unittest\.TestCase\)"],
+        "nose": [r"\bimport nose\b", r"\bfrom nose\b"],
+    },
+    "javascript": {
+        "jest": [r"\bimport.*from\s+['\"]jest['\"]", r"\bdescribe\(", r"\btest\(", r"\bit\("],
+        "vitest": [r"\bimport.*from\s+['\"]vitest['\"]", r"\bdescribe\(", r"\bit\("],
+        "mocha": [r"\bimport.*from\s+['\"]mocha['\"]", r"\bdescribe\(", r"\bit\("],
+        "jasmine": [r"\bjasmine\.", r"\bdescribe\("],
+    },
+    "typescript": {
+        "jest": [r"\bimport.*from\s+['\"]@jest/", r"\bdescribe\(", r"\bit\("],
+        "vitest": [r"\bimport.*from\s+['\"]vitest['\"]", r"\bdescribe\("],
+        "mocha": [r"\bimport.*from\s+['\"]mocha['\"]"],
+    },
+    "go": {
+        "testing": [r"\bimport\s+\"testing\"", r"\bfunc\s+Test\w+\(t\s+\*testing\.T\)"],
+        "testify": [r"\bimport.*testify"],
+    },
+    "rust": {
+        "built-in": [r"#\[cfg\(test\)\]", r"#\[test\]", r"\bmod\s+tests\s*\{"],
+    },
+}
+
+_COVERAGE = {
+    "python": ["coverage", "pytest-cov", "coveragepy"],
+    "javascript": ["c8", "istanbul", "nyc", "jest --coverage"],
+    "typescript": ["c8", "istanbul", "nyc"],
+    "go": ["go test -cover"],
+    "rust": ["cargo-tarpaulin", "cargo-llvm-cov"],
+}
+
+_MOCK_LIBRARIES = {
+    "python": ["unittest.mock", "pytest-mock", "mock", "MagicMock", "patch"],
+    "javascript": ["jest.fn", "sinon", "jest.mock"],
+    "typescript": ["jest.fn", "ts-mockito", "jest.mock"],
+    "go": ["testify/mock", "gomock"],
+}
+
+_RE_DESCRIBE = re.compile(r'\bdescribe\s*\(')
+_RE_IT = re.compile(r'\bit\s*\(')
+_RE_EXPECT = re.compile(r'\bexpect\s*\(')
+_RE_ASSERT = re.compile(r'\bassert\s')
+_RE_SHOULD = re.compile(r'\.should\.')
+_RE_FIXTURE = re.compile(r'@pytest\.fixture|@fixture|class\s+\w+Factory')
+_RE_FACTORY = re.compile(r'Factory\b|factory_boy|FactoryBot|factory\.create')
+
+
+def _is_test_file(path: Path) -> bool:
+    stem = path.stem
+    return (
+        stem.startswith("test_") or stem.endswith("_test")
+        or ".test." in path.name or ".spec." in path.name
+        or stem.startswith("Test") or path.parent.name in ("tests", "test", "__tests__", "spec")
+    )
+
+
+class TestingMiner:
+    def __init__(self, root: Path):
+        self.root = root
+
+    def mine(self, by_lang: dict[str, list[Path]]) -> dict[str, TestingResult]:
+        results: dict[str, TestingResult] = {}
+        for lang, paths in by_lang.items():
+            results[lang] = self._mine_lang(lang, paths)
+        return results
+
+    def _mine_lang(self, lang: str, paths: list[Path]) -> TestingResult:
+        test_files = [p for p in paths if _is_test_file(p)]
+        src_files = [p for p in paths if not _is_test_file(p)]
+        ratio = len(test_files) / len(src_files) if src_files else 0.0
+
+        framework_counts: Counter[str] = Counter()
+        describe_count = 0
+        expect_count = 0
+        assert_count = 0
+        should_count = 0
+        has_fixtures = False
+        has_factories = False
+        has_mocking = False
+        mock_libs: Counter[str] = Counter()
+        has_coverage = False
+        coverage_tool: str | None = None
+
+        for path in (test_files + src_files)[:200]:
+            try:
+                text = path.read_text(errors="replace")
+            except OSError:
+                continue
+
+            # Framework detection
+            for fw, patterns in _FRAMEWORK_SIGNALS.get(lang, {}).items():
+                for pat in patterns:
+                    if re.search(pat, text):
+                        framework_counts[fw] += 1
+                        break
+
+            describe_count += len(_RE_DESCRIBE.findall(text))
+            expect_count += len(_RE_EXPECT.findall(text))
+            assert_count += len(_RE_ASSERT.findall(text))
+            should_count += len(_RE_SHOULD.findall(text))
+
+            if _RE_FIXTURE.search(text):
+                has_fixtures = True
+            if _RE_FACTORY.search(text):
+                has_factories = True
+
+            for ml in _MOCK_LIBRARIES.get(lang, []):
+                if ml in text:
+                    has_mocking = True
+                    mock_libs[ml] += 1
+
+        # Coverage detection from config files
+        for cov in _COVERAGE.get(lang, []):
+            cfg_files = [
+                self.root / "pyproject.toml",
+                self.root / "setup.cfg",
+                self.root / "package.json",
+                self.root / "jest.config.js",
+                self.root / "jest.config.ts",
+                self.root / ".nycrc",
+            ]
+            for cfg in cfg_files:
+                if cfg.exists():
+                    try:
+                        if cov.split()[0] in cfg.read_text():
+                            has_coverage = True
+                            coverage_tool = cov.split()[0]
+                            break
+                    except OSError:
+                        pass
+
+        framework = framework_counts.most_common(1)[0][0] if framework_counts else None
+
+        org = None
+        if describe_count > 3:
+            org = "describe/it"
+        elif lang == "python" and "unittest" in (framework or ""):
+            org = "class-based"
+        elif lang in ("python", "go", "rust"):
+            org = "function-based"
+
+        assertion_style = None
+        total_assert = expect_count + assert_count + should_count
+        if total_assert > 0:
+            if expect_count >= max(assert_count, should_count):
+                assertion_style = "expect"
+            elif assert_count >= max(expect_count, should_count):
+                assertion_style = "assert"
+            else:
+                assertion_style = "should"
+
+        mock_lib = mock_libs.most_common(1)[0][0] if mock_libs else None
+
+        return TestingResult(
+            framework=framework,
+            test_file_count=len(test_files),
+            source_file_count=len(src_files),
+            test_ratio=round(ratio, 2),
+            organisation=org,
+            assertion_style=assertion_style,
+            has_coverage=has_coverage,
+            coverage_tool=coverage_tool,
+            has_fixtures=has_fixtures,
+            has_factories=has_factories,
+            has_mocking=has_mocking,
+            mock_library=mock_lib,
+        )

patchwork/output/__init__.py

@@ -0,0 +1 @@
+# output package