patchwork-conventions 0.1.1__tar.gz → 0.1.3__tar.gz

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchwork-conventions
-Version: 0.1.1
+Version: 0.1.3
 Summary: Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.
 Author: patchwork contributors
 License: MIT
@@ -228,20 +228,46 @@ patchwork scan --claude-md
 
 ### Option 3: MCP server
 
-Add to `~/.claude/settings.json`:
+**Claude Code** — add to `~/.claude.json` (or run `claude mcp add` interactively):
 
 ```json
 {
   "mcpServers": {
     "patchwork": {
       "command": "patchwork",
-      "args": ["serve", "--stdio", "/path/to/your/project"]
+      "args": ["serve", "/path/to/your/project", "--stdio"]
     }
   }
 }
 ```
 
-Then Claude Code can use 8 on-demand tools:
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", "/path/to/your/project", "--stdio"]
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", ".", "--stdio"]
+    }
+  }
+}
+```
+
+Then your AI agent can use 8 on-demand tools:
 
 | Tool | When to use |
 |---|---|

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/README.md

@@ -183,20 +183,46 @@ patchwork scan --claude-md
 
 ### Option 3: MCP server
 
-Add to `~/.claude/settings.json`:
+**Claude Code** — add to `~/.claude.json` (or run `claude mcp add` interactively):
 
 ```json
 {
   "mcpServers": {
     "patchwork": {
       "command": "patchwork",
-      "args": ["serve", "--stdio", "/path/to/your/project"]
+      "args": ["serve", "/path/to/your/project", "--stdio"]
     }
   }
 }
 ```
 
-Then Claude Code can use 8 on-demand tools:
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", "/path/to/your/project", "--stdio"]
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", ".", "--stdio"]
+    }
+  }
+}
+```
+
+Then your AI agent can use 8 on-demand tools:
 
 | Tool | When to use |
 |---|---|

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "patchwork-conventions"
-version = "0.1.1"
+version = "0.1.3"
 description = "Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style."
 readme = "README.md"
 license = { text = "MIT" }

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/src/patchwork/cli.py

@@ -111,7 +111,7 @@ def scan(
 
     if claude_md and out_path.exists():
         # Append patchwork section to existing CLAUDE.md
-        existing = out_path.read_text()
+        existing = out_path.read_text(encoding="utf-8")
         marker = "<!-- patchwork:start -->"
         end_marker = "<!-- patchwork:end -->"
         if marker in existing:
@@ -126,7 +126,7 @@ def scan(
         else:
             text = existing.rstrip() + f"\n\n{marker}\n{text}\n{end_marker}\n"
 
-    out_path.write_text(text)
+    out_path.write_text(text, encoding="utf-8")
 
     if not quiet:
         _print_summary(report, out_path)
@@ -145,7 +145,7 @@ def update(path: str, output: str | None) -> None:
     # Load any existing manual annotations
     manual_sections: dict[str, str] = {}
     if out_path.exists():
-        manual_sections = _extract_manual_sections(out_path.read_text())
+        manual_sections = _extract_manual_sections(out_path.read_text(encoding="utf-8"))
 
     opts = ScanOptions(root=root)
     with Progress(SpinnerColumn(), TextColumn("{task.description}"), transient=True) as p:
@@ -158,7 +158,7 @@ def update(path: str, output: str | None) -> None:
     for heading, content in manual_sections.items():
         text += f"\n\n## {heading} (manual)\n\n{content}"
 
-    out_path.write_text(text)
+    out_path.write_text(text, encoding="utf-8")
     console.print(f"[green]✓[/green] Updated [bold]{out_path}[/bold]")
     if manual_sections:
         console.print(f"  Preserved {len(manual_sections)} manual section(s)")
@@ -182,7 +182,7 @@ def diff(path: str) -> None:
         console.print("[yellow]No existing CONVENTIONS.md — run `patchwork scan` first[/yellow]")
         sys.exit(1)
 
-    old_text = out_path.read_text()
+    old_text = out_path.read_text(encoding="utf-8")
     diffs = list(difflib.unified_diff(
         old_text.splitlines(),
         new_text.splitlines(),
@@ -241,7 +241,7 @@ def watch(path: str, interval: float) -> None:
             if changed:
                 last_mtime = current
                 report = do_scan(opts)
-                out_path.write_text(report.to_markdown())
+                out_path.write_text(report.to_markdown(), encoding="utf-8")
                 console.print(f"[green]↺[/green] CONVENTIONS.md updated")
     except KeyboardInterrupt:
         console.print("\n[dim]Stopped[/dim]")

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/src/patchwork/mcp/server.py

@@ -36,7 +36,7 @@ def _get_or_scan(root: Path) -> ConventionReport:
     cached = _CACHE.get(key)
     if cached is not None:
         return cached
-    opts = ScanOptions(root=root, max_files=300)
+    opts = ScanOptions(root=root, max_files=500)
     report = do_scan(opts)
     _CACHE[key] = report
     return report
@@ -189,9 +189,34 @@ async def run_server(root: Path, port: int = 3742, stdio: bool = True) -> None:
             ),
         ]
 
+    def _resolve_scan_root(raw_path: str | None) -> Path:
+        """Resolve and validate the scan path.
+
+        Rejects paths that escape the filesystem root or point to sensitive
+        system directories, and normalises symlinks so containment checks
+        are reliable.  The MCP server is a read-only tool, but we still
+        validate inputs at the boundary to follow least-privilege.
+        """
+        candidate = Path(raw_path).resolve() if raw_path else root.resolve()
+
+        # Reject obviously dangerous system paths
+        _BLOCKED = {"/etc", "/proc", "/sys", "/dev", "/private/etc"}
+        for blocked in _BLOCKED:
+            if str(candidate).startswith(blocked):
+                raise ValueError(f"Scanning system path '{candidate}' is not allowed.")
+
+        # Must be an existing directory (not a file or a socket etc.)
+        if not candidate.is_dir():
+            raise ValueError(f"Path '{candidate}' is not a directory.")
+
+        return candidate
+
     @server.call_tool()
     async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
-        scan_root = Path(arguments.get("path", str(root))).resolve()
+        try:
+            scan_root = _resolve_scan_root(arguments.get("path"))
+        except ValueError as exc:
+            return [types.TextContent(type="text", text=f"Error: {exc}")]
 
         if arguments.get("refresh"):
             _invalidate(scan_root)
@@ -305,6 +330,8 @@ async def run_server(root: Path, port: int = 3742, stdio: bool = True) -> None:
                     lines.append(f"  logging: {er.logging_framework}")
                 if er.propagation_style:
                     lines.append(f"  propagation: {er.propagation_style}")
+                if er.custom_exceptions:
+                    lines.append(f"  custom exceptions: {', '.join(er.custom_exceptions[:6])}")
                 for note in er.notes:
                     lines.append(f"  note: {note}")
             return [types.TextContent(type="text", text="\n".join(lines) or "No error patterns found.")]
@@ -360,8 +387,13 @@ async def run_server(root: Path, port: int = 3742, stdio: bool = True) -> None:
             return [types.TextContent(type="text", text="\n".join(lines))]
 
         elif name == "patchwork_check":
-            sym = arguments["name"]
-            kind = arguments["kind"]
+            sym = arguments.get("name")
+            kind = arguments.get("kind")
+            if not sym or not kind:
+                return [types.TextContent(
+                    type="text",
+                    text="Error: 'name' and 'kind' are required arguments.",
+                )]
             lang = arguments.get("language", "")
             return [types.TextContent(
                 type="text",
@@ -391,7 +423,7 @@ async def run_server(root: Path, port: int = 3742, stdio: bool = True) -> None:
             Route("/sse", endpoint=handle_sse),
             Mount("/messages", app=sse.handle_post_message),
         ])
-        uvicorn.run(app, host="0.0.0.0", port=port)
+        uvicorn.run(app, host="127.0.0.1", port=port)
 
 
 def _check_convention(name: str, kind: str, lang: str, report: ConventionReport) -> str:

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/src/patchwork/miners/api_patterns.py

@@ -34,10 +34,23 @@ _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>
+# Route parameter styles — match route strings passed to known route-registration calls.
+# We look for the route string ONLY when it appears as an argument to a route decorator
+# or router method, to avoid matching f-strings, format strings, and other /path usages.
+
+# FastAPI/Starlette: @app.get("/items/{item_id}") or @router.post("/x/{id:int}")
+_ROUTE_BRACE = re.compile(
+    r'(?:@?\w+\.(?:get|post|put|patch|delete|websocket|route|add_api_route)\s*\()'
+    r'\s*[f]?["\'][^"\']*\{[a-zA-Z_]\w*(?::[a-zA-Z]+)?\}'
+)
+# Flask: @app.route("/items/<int:item_id>")
+_ROUTE_ANGLE = re.compile(
+    r'(?:@?\w+\.route\s*\()\s*[f]?["\'][^"\']*<(?:[a-zA-Z_]+:)?[a-zA-Z_]\w*>'
+)
+# Express: router.get("/:id") or app.use("/items/:id")
+_ROUTE_COLON = re.compile(
+    r'(?:\w+\.(?:get|post|put|patch|delete|use|all)\s*\()\s*["\'][^"\']*(?<!\{):(?!\w*\})[a-zA-Z_]\w*'
+)
 
 # ORM signals
 _ORM_SIGNALS = {
@@ -57,7 +70,8 @@ _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\("],
+    # For Express: require both the require() AND usage — router.get alone is too generic
+    "Express": [r"require\(['\"]express['\"]\)", r"express\(\)"],
     "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\("],
@@ -105,9 +119,10 @@ 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
+    # Track route style per FILE (not per match) to avoid single-file anomalies
+    colon_route_files = 0
+    brace_route_files = 0
+    angle_route_files = 0
     # Track per-file hits (not per-match) to avoid false positives from
     # code that merely mentions framework names in strings, comments, or docs.
     orm_files: Counter[str] = Counter()
@@ -127,9 +142,9 @@ def _detect_apis(paths: list[Path], lang: str) -> APIResult:
         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))
+        if _ROUTE_COLON.search(text): colon_route_files += 1
+        if _ROUTE_BRACE.search(text): brace_route_files += 1
+        if _ROUTE_ANGLE.search(text): angle_route_files += 1
 
         # Skip files that are themselves pattern-definition files (e.g. this miner)
         # to avoid self-matching on our own regex strings.
@@ -175,17 +190,17 @@ def _detect_apis(paths: list[Path], lang: str) -> APIResult:
     elif result_shape > 3:
         response_shape = "{result}"
 
-    # Route param style
-    route_total = colon_routes + brace_routes + angle_routes
+    # Route param style — pick the style seen in the most files.
+    # Require at least 2 files to avoid single-file anomalies.
     route_style = None
-    if route_total > 0:
-        best = max(colon_routes, brace_routes, angle_routes)
-        if colon_routes == best:
-            route_style = ":id (Express style)"
-        elif brace_routes == best:
-            route_style = "{id} (FastAPI style)"
-        else:
+    best = max(brace_route_files, angle_route_files, colon_route_files)
+    if best >= 2:
+        if brace_route_files == best:
+            route_style = "{id} (FastAPI/Starlette style)"
+        elif angle_route_files == best:
             route_style = "<id> (Flask style)"
+        else:
+            route_style = ":id (Express style)"
 
     return APIResult(
         response_shape=response_shape,

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/src/patchwork/miners/config_detector.py

@@ -17,6 +17,19 @@ except ImportError:
     except ImportError:
         tomllib = None  # type: ignore
 
+# Hard limit on config file size to prevent DoS from pathologically large files
+_MAX_CONFIG_BYTES = 1 * 1024 * 1024  # 1 MB
+
+
+def _safe_read(path: Path) -> str | None:
+    """Read a config file, returning None if it exceeds the size limit."""
+    try:
+        if path.stat().st_size > _MAX_CONFIG_BYTES:
+            return None
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+
 
 @dataclass
 class ProjectConfig:
@@ -129,9 +142,12 @@ class ConfigDetector:
         return cfg
 
     def _read_package_json(self, path: Path, cfg: ProjectConfig) -> None:
+        text = _safe_read(path)
+        if text is None:
+            return
         try:
-            data = json.loads(path.read_text())
-        except (json.JSONDecodeError, OSError):
+            data = json.loads(text)
+        except json.JSONDecodeError:
             return
 
         cfg.language = "javascript/typescript"
@@ -179,8 +195,11 @@ class ConfigDetector:
         cfg.language = "python"
         if tomllib is None:
             return
+        text = _safe_read(path)
+        if text is None:
+            return
         try:
-            data = tomllib.loads(path.read_text())
+            data = tomllib.loads(text)
         except Exception:
             return
 
@@ -225,9 +244,8 @@ class ConfigDetector:
     def _read_go_mod(self, path: Path, cfg: ProjectConfig) -> None:
         cfg.language = "go"
         cfg.package_manager = "go"
-        try:
-            text = path.read_text()
-        except OSError:
+        text = _safe_read(path)
+        if text is None:
             return
         m = re.search(r'^module\s+(\S+)', text, re.MULTILINE)
         if m:
@@ -253,8 +271,11 @@ class ConfigDetector:
         cfg.package_manager = "cargo"
         if tomllib is None:
             return
+        text = _safe_read(path)
+        if text is None:
+            return
         try:
-            data = tomllib.loads(path.read_text())
+            data = tomllib.loads(text)
         except Exception:
             return
         pkg = data.get("package", {})

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/src/patchwork/miners/git_patterns.py

@@ -9,7 +9,7 @@ GitPatternMiner — Mines git history for workflow conventions:
 from __future__ import annotations
 
 import re
-import subprocess
+import subprocess  # nosec B404 — used only for 'git' with a hardcoded arg list, no shell=True
 from collections import Counter, defaultdict
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -40,7 +40,7 @@ _BRANCH_FIX = re.compile(r'^(fix|hotfix|bugfix)/[\w/-]+$')
 
 def _run_git(args: list[str], cwd: Path, max_bytes: int = 500_000) -> str:
     try:
-        result = subprocess.run(
+        result = subprocess.run(  # nosec B603 — list args, no shell=True, cwd is a validated Path
             ["git"] + args,
             cwd=str(cwd),
             capture_output=True,

{patchwork_conventions-0.1.1 → patchwork_conventions-0.1.3}/src/patchwork_conventions.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchwork-conventions
-Version: 0.1.1
+Version: 0.1.3
 Summary: Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.
 Author: patchwork contributors
 License: MIT
@@ -228,20 +228,46 @@ patchwork scan --claude-md
 
 ### Option 3: MCP server
 
-Add to `~/.claude/settings.json`:
+**Claude Code** — add to `~/.claude.json` (or run `claude mcp add` interactively):
 
 ```json
 {
   "mcpServers": {
     "patchwork": {
       "command": "patchwork",
-      "args": ["serve", "--stdio", "/path/to/your/project"]
+      "args": ["serve", "/path/to/your/project", "--stdio"]
     }
   }
 }
 ```
 
-Then Claude Code can use 8 on-demand tools:
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", "/path/to/your/project", "--stdio"]
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", ".", "--stdio"]
+    }
+  }
+}
+```
+
+Then your AI agent can use 8 on-demand tools:
 
 | Tool | When to use |
 |---|---|