patchwork-conventions 0.1.0__py3-none-any.whl

patchwork_conventions-0.1.0.dist-info/METADATA

@@ -0,0 +1,393 @@
+Metadata-Version: 2.4
+Name: patchwork-conventions
+Version: 0.1.0
+Summary: Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.
+Author: patchwork contributors
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/patchwork
+Project-URL: Repository, https://github.com/yourusername/patchwork
+Project-URL: Issues, https://github.com/yourusername/patchwork/issues
+Keywords: ai,claude-code,conventions,code-style,context-engineering,mcp,agent-skills,static-analysis,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: mcp>=1.0
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pathspec>=0.11
+Requires-Dist: toml>=0.10; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: full
+Requires-Dist: tree-sitter-rust>=0.23; extra == "full"
+Requires-Dist: tree-sitter-go>=0.23; extra == "full"
+Requires-Dist: tree-sitter-java>=0.23; extra == "full"
+Dynamic: license-file
+
+# patchwork
+
+**Mine your codebase. Generate CONVENTIONS.md. Stop AI agents from making up your style.**
+
+[![PyPI](https://img.shields.io/pypi/v/patchwork-conventions)](https://pypi.org/project/patchwork-conventions/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![agent-skills](https://img.shields.io/badge/agent--skills-compatible-brightgreen)](https://github.com/topics/agent-skills)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://github.com/topics/mcp)
+
+---
+
+Every team that uses AI coding assistants hits the same wall: **Claude writes `getUserById` in a codebase that uses `get_user_by_id`. Cursor creates `components/userCard.tsx` in a project that uses `user-card.tsx`. The agent invented a response shape that doesn't match the rest of the API.**
+
+You write a `CLAUDE.md` manually. It goes stale in two weeks. You write it again.
+
+**patchwork automates this.** It scans your actual source code using AST analysis and detects what your team really does — not what you think you do.
+
+---
+
+## What it detects
+
+| Category | What's mined |
+|---|---|
+| **Naming** | Functions, classes, variables, constants, files — with confidence score and real examples |
+| **Imports** | Absolute vs relative, path aliases (`@/`, `src/`), barrel files, destructuring style |
+| **Structure** | Source root, test layout, feature vs layer organisation, monorepo detection |
+| **Error Handling** | try/except vs Result types, logging framework, custom exception naming, propagation style |
+| **Testing** | Framework, assertion style, mocking library, coverage tool, fixture patterns |
+| **API Patterns** | Response shape, route param style, ORM, async pattern, GraphQL/gRPC presence |
+| **Git Workflow** | Commit message style, branch naming, co-change file pairs |
+| **Tech Stack** | Frameworks, package manager, linters, formatters, type checker, build tool, scripts |
+
+---
+
+## Quick start
+
+```bash
+pip install patchwork-conventions
+cd your-project
+patchwork scan
+```
+
+That's it. You'll get a `CONVENTIONS.md` like this:
+
+```markdown
+# CONVENTIONS.md
+> Auto-generated by patchwork on 2026-06-25
+
+## Tech Stack
+**Language:** python
+**Runtime:** Python >=3.11
+**Package Manager:** uv
+**Frameworks:** fastapi, sqlalchemy
+**Linters:** ruff
+**Formatters:** ruff, black
+
+## Naming Conventions
+
+### Python
+- **Functions:** `snake_case` (97% consistent)
+  - Examples: `get_user`, `parse_response`, `create_session`
+- **Classes:** `PascalCase` (100% consistent)
+  - Examples: `UserService`, `AuthHandler`, `DatabaseClient`
+- **Constants:** `SCREAMING_SNAKE`
+  - Examples: `MAX_RETRIES`, `API_BASE_URL`
+- **Files:** `snake_case`
+- **Private prefix:** `_`
+- **Test functions:** prefix `test_`
+
+## Project Structure
+**Source root:** `src/`
+**Organisation:** layer-based
+**Tests:** separate (`tests/`)
+
+**Key directories:**
+  - `src/` — source root
+  - `tests/` — test suite
+  - `migrations/` — database migrations
+
+## Error Handling
+
+### Python
+- **Pattern:** try/except
+- **Propagation:** raise
+- **Logging:** `structlog`
+- **Custom exception naming:** Error suffix
+  - `ValidationError`, `AuthError`, `NotFoundError`
+
+## Testing Conventions
+
+### Python
+- **Framework:** pytest
+- **Coverage:** 34 test files / 89 source files (38% ratio)
+- **Assertions:** `assert(...)`
+- **Coverage tool:** `pytest-cov`
+- **Patterns:** fixtures, factories
+
+## Git Conventions
+- **Commit style:** conventional commits
+- **Examples:** `feat(auth): add JWT refresh`, `fix(api): handle null user`
+- **Branch naming:** feature/name + fix/name
+```
+
+---
+
+## Why not argus or sourcebook?
+
+| Feature | patchwork | argus | sourcebook |
+|---|---|---|---|
+| AST-based naming analysis | ✅ tree-sitter | ❌ filesystem only | ❌ not done |
+| Confidence scores | ✅ per-category | ❌ | ❌ |
+| Real examples from your code | ✅ | ❌ | ❌ |
+| Counter-examples (inconsistencies) | ✅ | ❌ | ❌ |
+| Error handling pattern mining | ✅ | ❌ | ❌ |
+| API response shape detection | ✅ | ❌ | ❌ |
+| Co-change file pairs | ✅ | ❌ | ✅ |
+| Convention checking (`check` cmd) | ✅ | ❌ | ❌ |
+| MCP server with 8 tools | ✅ | ❌ | ✅ (4 tools) |
+| Watch mode | ✅ | ✅ (`sync`) | ✅ |
+| Zero LLM required | ✅ | ✅ | ✅ (layer A) |
+| Open source / MIT | ✅ | ✅ | ❌ BSL |
+
+---
+
+## Commands
+
+```bash
+# Generate CONVENTIONS.md
+patchwork scan
+
+# Generate for a specific path
+patchwork scan /path/to/project
+
+# Generate AGENTS.md
+patchwork scan --agents-md
+
+# Append to CLAUDE.md
+patchwork scan --claude-md
+
+# Output JSON (for programmatic use)
+patchwork scan --json
+
+# Print to stdout (don't write file)
+patchwork scan --stdout
+
+# Limit to specific languages
+patchwork scan --lang python --lang typescript
+
+# Re-scan and update, preserving manual edits
+patchwork update
+
+# Show what would change
+patchwork diff
+
+# Print detected conventions to terminal
+patchwork show
+
+# Auto-watch mode (regenerate on change)
+patchwork watch
+
+# Start MCP server
+patchwork serve --stdio    # for Claude Code
+patchwork serve --port 3742  # HTTP mode
+```
+
+---
+
+## Claude Code integration
+
+### Option 1: CONVENTIONS.md (recommended)
+
+```bash
+patchwork scan      # run once
+# CONVENTIONS.md is automatically read by Claude Code
+```
+
+### Option 2: Append to CLAUDE.md
+
+```bash
+patchwork scan --claude-md
+```
+
+### Option 3: MCP server
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "patchwork": {
+      "command": "patchwork",
+      "args": ["serve", "--stdio", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+Then Claude Code can use 8 on-demand tools:
+
+| Tool | When to use |
+|---|---|
+| `patchwork_scan` | Get complete conventions overview |
+| `patchwork_naming` | Before writing new identifiers |
+| `patchwork_structure` | Before creating new files/directories |
+| `patchwork_stack` | When choosing libraries or commands |
+| `patchwork_errors` | Before writing error handling |
+| `patchwork_testing` | Before writing test files |
+| `patchwork_git` | Before writing commit messages |
+| `patchwork_check` | Validate a proposed name |
+
+### Option 4: Claude Code skill (SKILL.md)
+
+Copy `SKILL.md` from this repo to `~/.claude/skills/patchwork/SKILL.md` to get `/patchwork` slash commands.
+
+---
+
+## Watch mode (CI/auto-update)
+
+```bash
+# Keep CONVENTIONS.md updated as you code
+patchwork watch &
+
+# Or in CI — fail if conventions changed
+patchwork diff || (patchwork update && git add CONVENTIONS.md && git commit -m "chore: update conventions")
+```
+
+---
+
+## Python API
+
+```python
+from patchwork import scan
+from patchwork.scanner import ScanOptions
+from pathlib import Path
+
+# Full scan
+report = scan(ScanOptions(root=Path(".")))
+
+# Render to markdown
+print(report.to_markdown())
+
+# Render to JSON
+import json
+data = json.loads(report.to_json())
+
+# Access specific results
+naming = report.naming.get("python")
+print(f"Functions: {naming.functions.style} ({naming.functions.confidence:.0%})")
+print(f"Examples: {naming.functions.examples}")
+
+structure = report.structure
+print(f"Source root: {structure.source_root}")
+print(f"Organisation: {structure.organisation}")
+```
+
+---
+
+## Supported languages
+
+| Language | AST (tree-sitter) | Fallback regex |
+|---|---|---|
+| Python | ✅ full | ✅ |
+| TypeScript | ✅ full | ✅ |
+| JavaScript | ✅ full | ✅ |
+| Go | ✅ (with `full` extra) | ✅ |
+| Rust | ✅ (with `full` extra) | ✅ |
+| Java | ✅ (with `full` extra) | ✅ |
+| Ruby, PHP, C#, C++ | ❌ | ✅ regex only |
+
+Install full language support:
+
+```bash
+pip install 'patchwork-conventions[full]'
+```
+
+---
+
+## How it works
+
+```
+your codebase
+     │
+     ▼
+ConfigDetector        ← reads package.json, pyproject.toml, go.mod, Cargo.toml
+     │
+     ▼
+File discovery        ← respects .gitignore, skips node_modules etc.
+     │
+     ▼
+Per-language AST      ← tree-sitter parses every file into a syntax tree
+     │
+     ├── NamingMiner       → extracts function/class/variable names, classifies style
+     ├── ImportMiner        → detects import patterns, aliases, barrel files
+     ├── StructureMiner     → analyses directory layout, test co-location
+     ├── ErrorHandlingMiner → detects try/catch patterns, logging, custom exceptions
+     ├── TestingMiner       → identifies framework, assertion style, mocking
+     ├── APIPatternMiner    → finds response shapes, ORMs, route styles
+     └── GitPatternMiner    → mines commit history, branches, co-change pairs
+          │
+          ▼
+     ConventionReport
+          │
+          ├── CONVENTIONS.md  (default)
+          ├── AGENTS.md       (--agents-md)
+          ├── CLAUDE.md       (--claude-md, appends)
+          └── JSON            (--json)
+```
+
+All analysis is **100% local** — no API calls, no telemetry, no data leaves your machine.
+
+---
+
+## Performance
+
+On a 1,000-file TypeScript monorepo:
+- Without tree-sitter: ~0.8s
+- With tree-sitter (full AST): ~2.1s
+
+On a 500-file Python project:
+- ~1.1s
+
+Results are deterministic — same codebase always produces the same output.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/yourusername/patchwork
+cd patchwork
+pip install -e '.[dev]'
+pytest
+```
+
+Pull requests welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — free for personal and commercial use.
+
+---
+
+## Topics
+
+`claude-code` · `agent-skills` · `mcp` · `context-engineering` · `hallucination-detection` · `code-conventions` · `static-analysis` · `tree-sitter` · `developer-tools` · `ai-coding`

patchwork_conventions-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+patchwork/__init__.py,sha256=zFnPm2cWBIn2JDk87e6qu8nPtVip8lLOiZbC5fwoYZY,260
+patchwork/cli.py,sha256=OwhdmXO6GaF98kWlAjz0cXWuj-eRt0SzANR-s9YC9xE,11473
+patchwork/scanner.py,sha256=Tr-0Vjj04K-AVxYZrnS_S9o5bzdBHXjmtRi37yng8ts,5003
+patchwork/mcp/__init__.py,sha256=eNowugtpL_Oy7r0klmZe8Ue0v-uQT6Z-qcp8hcqxWY0,14
+patchwork/mcp/server.py,sha256=odT0hFhxEMc5h0jsDxvZ3SU-9cMnFzi4-BX6NRVEvy8,17697
+patchwork/miners/__init__.py,sha256=Kpk8Cak7K8WzA6nNZfdfS8lJgMxPm3sf2NX2hWZyhOc,17
+patchwork/miners/api_patterns.py,sha256=rbGv04sHM-KN9Sc207K5XG7OkxrDkbZ2hOycNucMbGA,7708
+patchwork/miners/ast_base.py,sha256=gj3H8BZb-r3G89KRG3HmcXFq_j13Qu4DIBc5rDTgoM4,3603
+patchwork/miners/config_detector.py,sha256=49Qu34CM0D1NOA5cpmhwLKOZ9y0VtIkm41mgDiGkG4g,8990
+patchwork/miners/error_handling.py,sha256=NrDb-oViLIY1gxDMgldrHt9oDe0h7jbZfIp0q6v_ZmA,7171
+patchwork/miners/git_patterns.py,sha256=Hs1OMLGv--9uCtiDH9YG3PP9qF2-INW_i734rCbecDA,5437
+patchwork/miners/imports.py,sha256=NVzTDlLhRpkqvRLBcEZABVWWGQahR_3Ngeq4_rSOIbs,5858
+patchwork/miners/naming.py,sha256=z3VkwC_cZaVACg4GkpTMC7BKUh2-PjcC38theqbz7Dw,11086
+patchwork/miners/structure.py,sha256=w7LyyreYAGxuiDZcW-iZQA1fY5P8gyvIDcLPR4N38iw,6970
+patchwork/miners/testing.py,sha256=Xi-9-FjGjtXdiaXEvDQVl25gHan_j_MZuW7NQEQdxGE,7346
+patchwork/output/__init__.py,sha256=jJqTUADPphzvTRbB4QscOs3mSf-jIXyE1qIGjlRDWB0,17
+patchwork/output/report.py,sha256=OwNyGMTluXb1HygJXSgLcIXz1YkUU8QEstiOlNpiO6o,16620
+patchwork_conventions-0.1.0.dist-info/licenses/LICENSE,sha256=0Bzg8X3qKFT990jWkHnMN1zw70scmtM1P75TZ0zHF7s,1079
+patchwork_conventions-0.1.0.dist-info/METADATA,sha256=2tuA67tmCFL_fg0mefPUv8MifnkHAm24t5hFWHSuJHc,11547
+patchwork_conventions-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+patchwork_conventions-0.1.0.dist-info/entry_points.txt,sha256=mMBjspsdLQOId-R273l7aO22cU5O9UFaEQRJlfllkko,49
+patchwork_conventions-0.1.0.dist-info/top_level.txt,sha256=aLF4R1vFf2HfqmKmZHlBkLny_-8Ye5nT-Pi8pKL2vE8,10
+patchwork_conventions-0.1.0.dist-info/RECORD,,

patchwork_conventions-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

patchwork_conventions-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+patchwork = patchwork.cli:main

patchwork_conventions-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 patchwork contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

patchwork_conventions-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+patchwork