patchwork-conventions 0.1.0__py3-none-any.whl

patchwork/mcp/server.py

@@ -0,0 +1,442 @@
+"""
+patchwork MCP server — exposes convention mining as MCP tools.
+
+Tools:
+  patchwork_scan         Full scan → returns CONVENTIONS.md text
+  patchwork_naming       Naming conventions for a specific language
+  patchwork_structure    Project structure summary
+  patchwork_errors       Error handling conventions
+  patchwork_testing      Testing conventions
+  patchwork_stack        Tech stack detection
+  patchwork_git          Git workflow conventions
+  patchwork_check        Check a symbol/path against detected conventions
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    import mcp.types as types
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+
+from patchwork.scanner import scan as do_scan, ScanOptions
+from patchwork.output.report import ConventionReport
+
+# Simple in-process cache keyed by root path + mtime of CONVENTIONS.md
+_CACHE: dict[str, ConventionReport] = {}
+
+
+def _get_or_scan(root: Path) -> ConventionReport:
+    key = str(root)
+    cached = _CACHE.get(key)
+    if cached is not None:
+        return cached
+    opts = ScanOptions(root=root, max_files=300)
+    report = do_scan(opts)
+    _CACHE[key] = report
+    return report
+
+
+def _invalidate(root: Path) -> None:
+    _CACHE.pop(str(root), None)
+
+
+async def run_server(root: Path, port: int = 3742, stdio: bool = True) -> None:
+    if not MCP_AVAILABLE:
+        raise RuntimeError(
+            "MCP package not installed. Run: pip install 'patchwork-conventions[mcp]'"
+        )
+
+    server = Server("patchwork")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name="patchwork_scan",
+                description=(
+                    "Scan the codebase and return full CONVENTIONS.md content. "
+                    "Use this when you need a complete picture of project conventions."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "Absolute path to scan (default: current project root)",
+                        },
+                        "format": {
+                            "type": "string",
+                            "enum": ["markdown", "json"],
+                            "description": "Output format",
+                            "default": "markdown",
+                        },
+                        "refresh": {
+                            "type": "boolean",
+                            "description": "Force re-scan even if cached",
+                            "default": False,
+                        },
+                    },
+                },
+            ),
+            types.Tool(
+                name="patchwork_naming",
+                description=(
+                    "Return naming conventions for a specific language detected in this project. "
+                    "Use before writing new functions, classes, or variables."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string"},
+                        "language": {
+                            "type": "string",
+                            "description": "Language to query (python, typescript, go, etc.)",
+                        },
+                    },
+                    "required": ["language"],
+                },
+            ),
+            types.Tool(
+                name="patchwork_structure",
+                description=(
+                    "Return project structure conventions: source root, test layout, "
+                    "organisation style, key directories. Use before creating new files."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {"path": {"type": "string"}},
+                },
+            ),
+            types.Tool(
+                name="patchwork_stack",
+                description=(
+                    "Return the detected tech stack: frameworks, package manager, "
+                    "linters, formatters, build tools, scripts."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {"path": {"type": "string"}},
+                },
+            ),
+            types.Tool(
+                name="patchwork_errors",
+                description=(
+                    "Return error-handling conventions for this project. "
+                    "Use before writing new error handling code."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string"},
+                        "language": {"type": "string"},
+                    },
+                },
+            ),
+            types.Tool(
+                name="patchwork_testing",
+                description=(
+                    "Return testing conventions: framework, assertion style, "
+                    "test layout, mocking approach."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string"},
+                        "language": {"type": "string"},
+                    },
+                },
+            ),
+            types.Tool(
+                name="patchwork_git",
+                description=(
+                    "Return git workflow conventions: commit message style, "
+                    "branch naming, co-change file pairs."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {"path": {"type": "string"}},
+                },
+            ),
+            types.Tool(
+                name="patchwork_check",
+                description=(
+                    "Check whether a proposed symbol name or file path follows "
+                    "this project's conventions. Returns 'ok' or a specific violation."
+                ),
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "path": {"type": "string"},
+                        "name": {
+                            "type": "string",
+                            "description": "Symbol or file name to check",
+                        },
+                        "kind": {
+                            "type": "string",
+                            "enum": ["function", "class", "variable", "constant", "file"],
+                            "description": "What kind of name to check",
+                        },
+                        "language": {"type": "string"},
+                    },
+                    "required": ["name", "kind", "language"],
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+        scan_root = Path(arguments.get("path", str(root))).resolve()
+
+        if arguments.get("refresh"):
+            _invalidate(scan_root)
+
+        report = _get_or_scan(scan_root)
+
+        if name == "patchwork_scan":
+            fmt = arguments.get("format", "markdown")
+            text = report.to_json() if fmt == "json" else report.to_markdown()
+            return [types.TextContent(type="text", text=text)]
+
+        elif name == "patchwork_naming":
+            lang = arguments.get("language", "")
+            nr = (report.naming or {}).get(lang)
+            if nr is None:
+                return [types.TextContent(
+                    type="text",
+                    text=f"No naming data for '{lang}'. Available: {list(report.naming or {})}"
+                )]
+            lines = [f"Naming conventions for {lang}:"]
+            if nr.functions:
+                lines.append(
+                    f"- functions: {nr.functions.style} "
+                    f"({int(nr.functions.confidence * 100)}% consistent)"
+                )
+                if nr.functions.examples:
+                    lines.append(f"  examples: {', '.join(nr.functions.examples[:4])}")
+            if nr.classes:
+                lines.append(f"- classes: {nr.classes.style}")
+                if nr.classes.examples:
+                    lines.append(f"  examples: {', '.join(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.files:
+                lines.append(f"- files: {nr.files.style}")
+            if nr.private_prefix:
+                lines.append(f"- private prefix: {nr.private_prefix}")
+            for note in nr.notes:
+                lines.append(f"note: {note}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        elif name == "patchwork_structure":
+            s = report.structure
+            if s is None:
+                return [types.TextContent(type="text", text="No structure data available.")]
+            lines = ["Project 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.test_dirs:
+                    lines.append(f"  directories: {', '.join(s.test_dirs)}")
+            if s.organisation:
+                lines.append(f"- organisation: {s.organisation}")
+            if s.is_monorepo:
+                lines.append(f"- monorepo: {len(s.monorepo_packages)} packages")
+                for pkg in s.monorepo_packages[:5]:
+                    lines.append(f"  - {pkg}/")
+            if s.key_dirs:
+                lines.append("- key directories:")
+                for d, role in s.key_dirs.items():
+                    lines.append(f"  {d}/ = {role}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        elif name == "patchwork_stack":
+            cfg = report.config
+            if cfg is None:
+                return [types.TextContent(type="text", text="No config detected.")]
+            lines = ["Tech stack:"]
+            if cfg.name:
+                lines.append(f"- project: {cfg.name}")
+            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.scripts:
+                lines.append("- scripts:")
+                for k, v in cfg.scripts.items():
+                    lines.append(f"  {k}: {v}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        elif name == "patchwork_errors":
+            lang = arguments.get("language")
+            errors = report.errors or {}
+            if lang:
+                er = errors.get(lang)
+                if er is None:
+                    return [types.TextContent(
+                        type="text",
+                        text=f"No error data for '{lang}'. Available: {list(errors)}"
+                    )]
+                data = {lang: er}
+            else:
+                data = errors
+            lines = []
+            for lng, er in data.items():
+                lines.append(f"{lng}: {er.primary_pattern}")
+                if er.logging_framework:
+                    lines.append(f"  logging: {er.logging_framework}")
+                if er.propagation_style:
+                    lines.append(f"  propagation: {er.propagation_style}")
+                for note in er.notes:
+                    lines.append(f"  note: {note}")
+            return [types.TextContent(type="text", text="\n".join(lines) or "No error patterns found.")]
+
+        elif name == "patchwork_testing":
+            lang = arguments.get("language")
+            testing = report.testing or {}
+            if lang:
+                tr = testing.get(lang)
+                if tr is None:
+                    return [types.TextContent(
+                        type="text",
+                        text=f"No testing data for '{lang}'."
+                    )]
+                data = {lang: tr}
+            else:
+                data = testing
+            lines = []
+            for lng, tr in data.items():
+                lines.append(f"{lng}:")
+                if tr.framework:
+                    lines.append(f"  framework: {tr.framework}")
+                lines.append(f"  test files: {tr.test_file_count}")
+                if tr.organisation:
+                    lines.append(f"  organisation: {tr.organisation}")
+                if tr.assertion_style:
+                    lines.append(f"  assertions: {tr.assertion_style}(...)")
+                if tr.mock_library:
+                    lines.append(f"  mocking: {tr.mock_library}")
+            return [types.TextContent(type="text", text="\n".join(lines) or "No testing data.")]
+
+        elif name == "patchwork_git":
+            g = report.git
+            if g is None:
+                return [types.TextContent(type="text", text="No git data (not a git repo or no commits).")]
+            lines = [f"Git conventions ({g.total_commits_sampled} commits sampled):"]
+            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:
+                lines.append(f"- avg files/commit: {g.avg_files_per_commit}")
+            if g.cochange_pairs:
+                lines.append("- files that change together:")
+                for a, b, count in g.cochange_pairs[:3]:
+                    lines.append(f"  {a} <-> {b} ({count}x)")
+            for note in g.notes:
+                lines.append(f"note: {note}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        elif name == "patchwork_check":
+            sym = arguments["name"]
+            kind = arguments["kind"]
+            lang = arguments.get("language", "")
+            return [types.TextContent(
+                type="text",
+                text=_check_convention(sym, kind, lang, report),
+            )]
+
+        return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    # Transport
+    if stdio:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(read_stream, write_stream, server.create_initialization_options())
+    else:
+        # SSE transport for HTTP mode
+        from mcp.server.sse import SseServerTransport
+        from starlette.applications import Starlette
+        from starlette.routing import Mount, Route
+        import uvicorn
+
+        sse = SseServerTransport("/messages")
+
+        async def handle_sse(request):
+            async with sse.connect_sse(request.scope, request.receive, request._send) as streams:
+                await server.run(streams[0], streams[1], server.create_initialization_options())
+
+        app = Starlette(routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages", app=sse.handle_post_message),
+        ])
+        uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+def _check_convention(name: str, kind: str, lang: str, report: ConventionReport) -> str:
+    """Check if a name follows detected conventions. Returns descriptive verdict."""
+    import re
+
+    naming = (report.naming or {}).get(lang)
+    if naming is None:
+        return f"ok (no convention data for {lang})"
+
+    convention_map = {
+        "function": naming.functions,
+        "class": naming.classes,
+        "variable": naming.variables,
+        "constant": naming.constants,
+        "file": naming.files,
+    }
+    conv = convention_map.get(kind)
+    if conv is None or conv.confidence < 0.6:
+        return f"ok (no strong convention detected for {lang} {kind}s)"
+
+    expected = conv.style
+    actual = _classify_name(name)
+
+    if actual == expected:
+        return f"✓ ok — `{name}` follows `{expected}` convention for {lang} {kind}s"
+    else:
+        example = conv.examples[0] if conv.examples else "N/A"
+        return (
+            f"⚠ violation — `{name}` looks like `{actual}` "
+            f"but this project uses `{expected}` for {lang} {kind}s. "
+            f"Example: `{example}`"
+        )
+
+
+def _classify_name(name: str) -> str:
+    import re
+    if re.match(r'^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$', name):
+        return "SCREAMING_SNAKE"
+    if re.match(r'^[a-z][a-z0-9]*(_[a-z0-9]+)*$', name):
+        return "snake_case"
+    if re.match(r'^[a-z][a-zA-Z0-9]*$', name):
+        return "camelCase"
+    if re.match(r'^[A-Z][a-zA-Z0-9]*$', name):
+        return "PascalCase"
+    if re.match(r'^[a-z][a-z0-9]*(-[a-z0-9]+)*$', name):
+        return "kebab-case"
+    return "mixed"

patchwork/miners/__init__.py

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

patchwork/miners/api_patterns.py

@@ -0,0 +1,204 @@
+"""
+APIPatternMiner — Detects API / data-layer conventions:
+  - REST response shape: {data, error} | {result} | {success, data} | raw
+  - HTTP method naming pattern
+  - Route parameter style: :id vs {id} vs <id>
+  - ORM in use and query style
+  - Async patterns: async/await vs callbacks vs coroutines
+  - GraphQL presence
+  - gRPC presence
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class APIResult:
+    response_shape: str | None      # e.g. '{data, error}' | '{success, data}' | 'raw'
+    route_param_style: str | None   # ':id' | '{id}' | '<id>'
+    async_pattern: str | None       # 'async/await' | 'callbacks' | 'coroutines'
+    orm: str | None
+    has_graphql: bool
+    has_grpc: bool
+    api_frameworks: list[str]
+    http_client: str | None
+    notes: list[str] = field(default_factory=list)
+
+
+# Response shape patterns
+_RESP_DATA_ERROR = re.compile(r'["\'](?:data|error)["\']', re.IGNORECASE)
+_RESP_SUCCESS_DATA = re.compile(r'["\']success["\'].*["\']data["\']', re.DOTALL | re.IGNORECASE)
+_RESP_RESULT = re.compile(r'["\']result["\']', re.IGNORECASE)
+
+# Route parameter styles
+_ROUTE_COLON = re.compile(r'(?:app|router)\.\w+\(["\'][^"\']*:\w+')   # Express :id
+_ROUTE_BRACE = re.compile(r'(?:path|url)\s*=\s*["\'][^"\']*\{[a-zA-Z_]+\}')  # FastAPI {id}
+_ROUTE_ANGLE = re.compile(r'(?:app|blueprint)\.\w+\(["\'][^"\']*<[a-zA-Z_:]+>')   # Flask <id>
+
+# ORM signals
+_ORM_SIGNALS = {
+    "SQLAlchemy": [r"\bsessionmaker\b", r"Column\(", r"declarative_base", r"db\.session"],
+    "Prisma": [r"prisma\.\w+\.find", r"prisma\.\w+\.create", r"from ['\"]@prisma"],
+    "Sequelize": [r"Sequelize\b", r"\.define\(", r"sequelize\.query"],
+    "TypeORM": [r"@Entity\(\)", r"getRepository\(", r"createQueryBuilder"],
+    "Django ORM": [r"models\.Model\b", r"\.objects\.filter\(", r"\.objects\.get\("],
+    "GORM": [r"\bgorm\b.*\.Find\(", r"db\.Where\(", r"AutoMigrate\("],
+    "Mongoose": [r"mongoose\.model\(", r"new Schema\(", r"\.populate\("],
+    "Drizzle": [r"from ['\"]drizzle-orm", r"drizzle\("],
+    "Hibernate": [r"@Entity\b.*@Table\b", r"SessionFactory\b"],
+}
+
+# Web framework signals
+_FRAMEWORK_SIGNALS = {
+    "FastAPI": [r"from fastapi import", r"@app\.get\(", r"@router\."],
+    "Flask": [r"from flask import", r"@app\.route\(", r"Blueprint\("],
+    "Django": [r"from django", r"urlpatterns\s*=", r"HttpResponse"],
+    "Express": [r"require\(['\"]express['\"]", r"app\.use\(", r"router\.get\("],
+    "Fastify": [r"require\(['\"]fastify['\"]", r"fastify\.register"],
+    "Hono": [r"from ['\"]hono['\"]", r"new Hono\("],
+    "Gin": [r"\bgin\b.*\bDefault\(\)", r"r\.GET\(", r"c\.JSON\("],
+    "Echo": [r"\becho\b.*\bNew\(\)", r"e\.GET\("],
+    "Actix": [r"use actix_web", r"HttpServer::new"],
+    "Axum": [r"use axum::", r"Router::new\(\)"],
+    "NestJS": [r"@Controller\(", r"@Injectable\(\)", r"@Module\("],
+    "Spring": [r"@RestController\b", r"@GetMapping", r"@SpringBootApplication"],
+}
+
+_ASYNC_SIGNALS = {
+    "python": {
+        "async/await": [r"\basync def\b", r"\bawait\b"],
+        "coroutines": [r"asyncio\.run\(", r"@asyncio\.coroutine"],
+        "callbacks": [r"\.add_done_callback\(", r"concurrent\.futures"],
+    },
+    "javascript": {
+        "async/await": [r"\basync\s+function\b", r"\bawait\b"],
+        "promises": [r"\.then\(", r"new Promise\(", r"Promise\.all"],
+        "callbacks": [r"callback\s*\)", r"cb\s*\)"],
+    },
+    "typescript": {
+        "async/await": [r"\basync\s+function\b", r"\bawait\b"],
+        "promises": [r"Promise<", r"\.then\("],
+    },
+    "go": {
+        "goroutines": [r"\bgo\s+\w+\(", r"\bchan\b"],
+    },
+    "rust": {
+        "async/await": [r"\basync\s+fn\b", r"\.await\b"],
+        "futures": [r"Box<dyn Future", r"impl Future"],
+    },
+}
+
+_HTTP_CLIENTS = {
+    "python": ["requests", "httpx", "aiohttp", "urllib3", "pycurl"],
+    "javascript": ["axios", "fetch", "got", "node-fetch", "superagent", "ky"],
+    "typescript": ["axios", "fetch", "got", "ky", "ofetch"],
+    "go": ["net/http", "resty", "fasthttp"],
+    "rust": ["reqwest", "hyper", "ureq"],
+}
+
+
+def _detect_apis(paths: list[Path], lang: str) -> APIResult:
+    data_error = 0
+    success_data = 0
+    result_shape = 0
+    colon_routes = 0
+    brace_routes = 0
+    angle_routes = 0
+    orm_counts: Counter[str] = Counter()
+    fw_counts: Counter[str] = Counter()
+    async_counts: Counter[str] = Counter()
+    http_client_counts: Counter[str] = Counter()
+    has_graphql = False
+    has_grpc = False
+
+    for path in paths[:200]:
+        try:
+            text = path.read_text(errors="replace")
+        except OSError:
+            continue
+
+        data_error += len(_RESP_DATA_ERROR.findall(text))
+        success_data += len(_RESP_SUCCESS_DATA.findall(text))
+        result_shape += len(_RESP_RESULT.findall(text))
+
+        colon_routes += len(_ROUTE_COLON.findall(text))
+        brace_routes += len(_ROUTE_BRACE.findall(text))
+        angle_routes += len(_ROUTE_ANGLE.findall(text))
+
+        for orm, patterns in _ORM_SIGNALS.items():
+            for pat in patterns:
+                if re.search(pat, text):
+                    orm_counts[orm] += 1
+                    break
+
+        for fw, patterns in _FRAMEWORK_SIGNALS.items():
+            for pat in patterns:
+                if re.search(pat, text):
+                    fw_counts[fw] += 1
+                    break
+
+        for style, patterns in _ASYNC_SIGNALS.get(lang, {}).items():
+            for pat in patterns:
+                if re.search(pat, text):
+                    async_counts[style] += 1
+                    break
+
+        for client in _HTTP_CLIENTS.get(lang, []):
+            if client in text:
+                http_client_counts[client] += 1
+
+        if "graphql" in text.lower() or "GraphQL" in text or "gql`" in text:
+            has_graphql = True
+        if "proto" in text.lower() or "grpc" in text.lower() or "protobuf" in text.lower():
+            has_grpc = True
+
+    # Response shape
+    response_shape = None
+    if success_data > 3:
+        response_shape = "{success, data}"
+    elif data_error > 3:
+        response_shape = "{data, error}"
+    elif result_shape > 3:
+        response_shape = "{result}"
+
+    # Route param style
+    route_total = colon_routes + brace_routes + angle_routes
+    route_style = None
+    if route_total > 0:
+        if colon_routes == max(colon_routes, brace_routes, angle_routes):
+            route_style = ":id (Express style)"
+        elif brace_routes == max(colon_routes, brace_routes, angle_routes):
+            route_style = "{id} (FastAPI style)"
+        else:
+            route_style = "<id> (Flask style)"
+
+    async_pattern = async_counts.most_common(1)[0][0] if async_counts else None
+    orm = orm_counts.most_common(1)[0][0] if orm_counts else None
+    http_client = http_client_counts.most_common(1)[0][0] if http_client_counts else None
+    api_frameworks = [fw for fw, _ in fw_counts.most_common(3)]
+
+    return APIResult(
+        response_shape=response_shape,
+        route_param_style=route_style,
+        async_pattern=async_pattern,
+        orm=orm,
+        has_graphql=has_graphql,
+        has_grpc=has_grpc,
+        api_frameworks=api_frameworks,
+        http_client=http_client,
+    )
+
+
+class APIPatternMiner:
+    def mine(self, by_lang: dict[str, list[Path]]) -> dict[str, APIResult]:
+        results: dict[str, APIResult] = {}
+        for lang, paths in by_lang.items():
+            result = _detect_apis(paths, lang)
+            # Only include if we found something meaningful
+            if result.api_frameworks or result.orm or result.async_pattern:
+                results[lang] = result
+        return results