pmat 3.17.0

PMAT - Zero-config AI context generation and code quality toolkit (CLI, MCP, HTTP)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249

# PMAT Documentation

Welcome to the PMAT (Pragmatic AI MCP Agent Toolkit) documentation.

## 📚 Documentation Structure

### Core Documentation
- **[SPECIFICATION.md](./SPECIFICATION.md)** - Complete system specification (source of truth)
- **[CLAUDE_CODE_AGENT.md](./CLAUDE_CODE_AGENT.md)** - Claude Code Agent Mode user guide (v2.12.0)
- **[DISTRIBUTION_STATUS.md](./DISTRIBUTION_STATUS.md)** - Multi-ecosystem distribution status and automation
- **[DOCUMENTATION_STRUCTURE.md](./DOCUMENTATION_STRUCTURE.md)** - Documentation organization guide

### Active Documentation

#### Architecture & Design
- **[architecture/](./architecture/)** - System architecture and design decisions
  - [ARCHITECTURE.md](./architecture/ARCHITECTURE.md) - High-level architecture overview
  - [decisions/](./architecture/decisions/) - Architecture Decision Records (ADRs)

#### Development
- **[execution/](./execution/)** - Sprint planning and execution
  - [roadmap.md](./execution/roadmap.md) - Development roadmap with task tracking
  - [quality-gates.md](./execution/quality-gates.md) - Quality enforcement standards
  - [velocity.json](./execution/velocity.json) - Sprint velocity metrics

#### Features
- **[features/](./features/)** - Feature documentation
  - [README.md](./features/README.md) - Feature overview
  - **[SCAFFOLDING-AND-MAINTENANCE.md](./features/SCAFFOLDING-AND-MAINTENANCE.md)** - **🆕 v2.139.0** Project Scaffolding & Maintenance System (Complete Guide)
  - **[SEMANTIC-SEARCH-GUIDE.md](./SEMANTIC-SEARCH-GUIDE.md)** - **🆕 v2.159.0** Semantic Code Search - Complete User Guide
  - [claude-agent-sdk-guide.md](./claude-agent-sdk-guide.md) - Claude Agent SDK Integration Guide
  - [deep-wasm-usage.md](./deep-wasm-usage.md) - Deep WASM Pipeline Inspection (Phases 1-2.7 Complete)
  - [mutation-testing.md](./mutation-testing.md) - Mutation Testing with ML Prediction
  - Individual feature guides for each major capability

#### User Guides
- **[guides/](./guides/)** - User and integration guides
  - [interfaces-overview.md](./guides/interfaces-overview.md) - CLI, MCP, HTTP interfaces
  - [refactor-auto-guide.md](./guides/refactor-auto-guide.md) - Automated refactoring guide
  - [github-actions-quality-gate.md](./guides/github-actions-quality-gate.md) - CI/CD integration

#### Dogfooding
- **[dogfooding/](./dogfooding/)** - Real-world validation of PMAT features
  - [README.md](./dogfooding/README.md) - Dogfooding overview and command reference
  - [v2.139.0-INTEGRATION-SHOWCASE.md](./dogfooding/v2.139.0-INTEGRATION-SHOWCASE.md) - **🆕** Complete v2.139.0 integration showcase
  - [SPRINT-19-DOGFOODING-RESULTS.md](./dogfooding/SPRINT-19-DOGFOODING-RESULTS.md) - Sprint 19 findings

#### Operations
- **[operations/](./operations/)** - Operational documentation
  - [configuration.md](./operations/configuration.md) - Configuration guide
  - [error-handling.md](./operations/error-handling.md) - Error handling patterns
  - [telemetry.md](./operations/telemetry.md) - Monitoring and telemetry

#### Quality & Testing
- **[quality/](./quality/)** - Quality standards and metrics
  - [standards.md](./quality/standards.md) - Code quality standards
- **[testing/](./testing/)** - Testing documentation
  - [property-based.md](./testing/property-based.md) - Property-based testing guide
  - [integration.md](./testing/integration.md) - Integration testing
  - [performance.md](./testing/performance.md) - Performance testing

#### Specifications
- **[specifications/](./specifications/)** - Feature specifications
  - [roadmap-todo-quality-gate-spec.md](./specifications/components/work-management.md) - Roadmap management spec
  - [publish-mcp-registry.md](./specifications/components/mcp-protocol.md) - MCP Registry publishing specification

### Release Information
- **[release-process.md](./release-process.md)** - Release workflow and procedures
- **[release_notes/](./release_notes/)** - Recent release notes (v2.x+)
- **[/CHANGELOG.md](../CHANGELOG.md)** - Complete version history

### Development Planning
- **[todo/](./todo/)** - Future development specifications
  - Active specifications for upcoming features
  - [archive/](./todo/archive/) - Completed or deprecated specs

### Reference
- **[cli-reference.md](./cli-reference.md)** - CLI command reference
- **[bugs/](./bugs/)** - Known issues and bug reports
  - [archived/](./bugs/archived/) - Resolved issues

## 🗄️ Archived Documentation

Historical and deprecated documentation has been moved to the archive:
- **[archive/](./archive/)** - Archived documentation
  - [ARCHIVE_INDEX.md](./archive/ARCHIVE_INDEX.md) - Archive navigation guide
  - [pre-v2.0/](./archive/pre-v2.0/) - Pre-2.0 version documentation
  - Historical release notes, implementation docs, and deprecated features

## 🚀 Quick Start

1. **New Users**: Start with [SPECIFICATION.md](./SPECIFICATION.md) for system overview
2. **Developers**: Check [execution/roadmap.md](./execution/roadmap.md) for current tasks
3. **Contributors**: Review [quality/standards.md](./quality/standards.md) for quality requirements
4. **Integrators**: See [guides/interfaces-overview.md](./guides/interfaces-overview.md) for API details

## 📖 Getting Started with PMAT

PMAT (Pragmatic Multi-language Analysis Tool) analyzes codebases across 14+ languages to provide:

- **Technical Debt Grading (TDG)**: Letter grades (A+ to F) for code quality
- **Complexity Analysis**: Cyclomatic complexity, cognitive complexity, nesting depth
- **Dead Code Detection**: Unused functions, variables, imports
- **SATD Analysis**: Self-Admitted Technical Debt annotations (TODO, FIXME, HACK)
- **Architecture Insights**: Dependency graphs, module relationships
- **MCP Integration**: AI-powered code analysis via Model Context Protocol
- **Quality Gates**: Pre-commit hooks enforcing quality standards

### Quick Start Commands

```bash
# Analyze current directory
pmat analyze .

# Get Technical Debt Grade
pmat analyze tdg .

# Generate comprehensive context for AI assistants
pmat context

# Run quality gate checks
pmat quality-gate --threshold B+
```

### 📚 Comprehensive User Documentation

For detailed guides, examples, and best practices, see the **[PMAT Book](https://github.com/paiml/pmat-book)** - the official comprehensive documentation with 28 chapters covering all PMAT features, including:

- Installation and setup guides
- Complete command reference
- Real-world examples with TDD validation
- Multi-language project tutorials
- MCP integration guides
- Quality-driven development workflows

**New users should start with the PMAT Book for step-by-step tutorials and practical examples.**

## 📖 Documentation Standards

All documentation follows these principles:
- **Single Source of Truth**: SPECIFICATION.md is the authoritative reference
- **Version Synchronized**: Documentation updates required with code changes
- **Quality Enforced**: Pre-commit hooks ensure documentation quality
- **Toyota Way Aligned**: Continuous improvement (Kaizen) approach

## 🔗 External Resources

- **Repository**: [github.com/paiml/paiml-mcp-agent-toolkit](https://github.com/paiml/paiml-mcp-agent-toolkit)
<!-- PMAT not yet published to crates.io: - **Crates.io**: <!-- PMAT not yet published to crates.io: [crates.io/crates/pmat](https://crates.io/crates/pmat) --> -->
- **MCP Registry**: [registry.modelcontextprotocol.io (io.github.paiml/pmat-agent)](https://registry.modelcontextprotocol.io/v0/servers?search=pmat)
- **Homepage**: [paiml.com](https://paiml.com)

## 🎯 Featured Capabilities

### Deep WASM Pipeline Inspection
Complete Rust/Ruchy → WebAssembly analysis pipeline with bidirectional tracing. **[Full Guide →](./deep-wasm-usage.md)**

- ✅ **Phase 1-2.7 Complete**: WASM binary parsing, DWARF correlation, mutation testing, unified parser
- 🔬 WASM binary parser with zero-copy analysis (wasmparser)
- 🗺️ DWARF v5 bidirectional source mapping (gimli)
- 🧬 WASM mutation testing with 3 operators (180 tests passing)
- ⚡ Unified WASM parser with 40-50% performance improvement
- 🎭 Ruchy language support for actor systems
- 📋 Phase 3 scoped: Runtime analysis, profiling, security scanning

### Semantic Code Search ✨ NEW (v2.159.0)
**AI-powered code search using natural language and vector embeddings.** **[Full Guide →](./SEMANTIC-SEARCH-GUIDE.md)**

- 🔍 **Natural language search** - Find code by meaning: "authentication middleware"
- 🧠 **Hybrid search** - Combines keyword + semantic understanding (Reciprocal Rank Fusion)
- 🔎 **Find similar code** - Discover duplicates and refactoring opportunities
- 🗂️ **Auto-clustering** - Group code by semantic similarity (K-means, hierarchical, DBSCAN)
- 📊 **Topic extraction** - Identify architectural patterns and themes
- 🤖 **MCP integration** - 4 tools for AI assistants (Claude Code, Cursor)
- 🌐 **Multi-language** - Rust, TypeScript, Python, C/C++, Go
- ⚡ **Fast** - <150ms hybrid search on 10K chunks
- 💰 **Low cost** - $0.01-$0.05 for most codebases (one-time)
- 📦 **Published** - Available on crates.io v2.159.0

**Quick Start:**
```bash
export OPENAI_API_KEY="sk-..."
pmat embed sync .
pmat semantic search "authentication logic"
pmat analyze cluster --method kmeans --k 5
```

### Mutation Testing Engine
Empirical mutation testing with actual test execution and optional ML prediction. **[Full Guide →](./mutation-testing.md)**

- ⚡ **20× faster than cargo-mutants** with smart test filtering (v2.135.0)
- ✨ **Properly formatted output** using prettyplease (v2.136.0)
- 🔧 **CRITICAL BUG FIXED**: File corruption issue resolved (Issue #64, v2.136.0)
- 🧪 Real test execution with `cargo test --lib` on each mutant
- 🔀 6 mutation operators (AOR, ROR, COR, UOR, CRR, SDL)
- 🌐 Multi-language support (Rust, WASM/WAT)
- 🧠 Optional ML prediction with decision tree classifier (75-95% accuracy)
- 🚀 Distributed execution with work-stealing queue
- 📈 CI/CD learning and auto-training (50 sample threshold)

### TypeScript/JavaScript Mutation Testing ✨ NEW (v2.144.0)
**Production-ready AST-based mutation testing for TypeScript and JavaScript.** **[Full Guide →](./features/TYPESCRIPT-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Quantify test suite quality
- ⚡ **Fast generation** - 67 mutants in 14ms using tree-sitter AST
- 🔍 **Real test execution** - Works with jest, vitest, mocha
- 🧬 **5 mutation operators** - Arithmetic, equality, optional chaining, nullish coalescing, async/await
- 📊 **Identifies test gaps** - Surviving mutants show actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Reusable for Python, Go, C++

### Python Mutation Testing ✨ NEW (v2.152.0)
**Production-ready AST-based mutation testing for Python 3.6+.** **[Full Guide →](./features/PYTHON-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Validate test suite quality
- ⚡ **Ultra-fast generation** - 56 mutants in 5ms using tree-sitter AST
- 🔍 **Real test execution** - Works with pytest and unittest
- 🧬 **5 mutation operators** - Binary (AOR), relational (ROR), logical (LOR), identity (is/is not), membership (in/not in)
- 📊 **Identifies test gaps** - Surviving mutants reveal actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Shared with TypeScript implementation

### Go Mutation Testing ✨ NEW (v2.153.0)
**Production-ready AST-based mutation testing for Go 1.21+.** **[Full Guide →](./features/GO-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Validate test suite quality
- ⚡ **FASTEST generation** - <3ms for ~60 mutants using tree-sitter AST
- 🔍 **Real test execution** - Works with standard `go test`
- 🧬 **6 mutation operators** - Binary (AOR), relational (ROR), logical (LOR), **bitwise (BOR)**, **unary (UOR)**, **assignment**
- 🔷 **Go-specific features** - Bitwise ops, compound assignment, unary operators
- 📊 **Identifies test gaps** - Surviving mutants reveal actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Shared with TypeScript/Python

### C++ Mutation Testing ✨ NEW (v2.154.0)
**Production-ready AST-based mutation testing for C++17+.** **[Full Guide →](./features/CPP-MUTATION-TESTING.md)**

- 🎯 **80%+ mutation scores achievable** - Quantify test suite quality
- ⚡ **Fast generation** - ~5ms for ~75 mutants using tree-sitter AST
- 🔍 **Real test execution** - Works with CMake/CTest and Google Test
- 🧬 **7 mutation operators** - Binary (AOR), relational (ROR), logical (LOR), **bitwise (BOR)**, **unary (UOR)**, **pointer (POR)**, **member access (MAR)**
- 🔷 **C++-specific features** - Pointer operators, member access, pre/post increment
- 📊 **Identifies test gaps** - Surviving mutants reveal actual weaknesses
- 🔄 **Full automation** - Source → mutants → tests → score
- 🏗️ **Language-agnostic architecture** - Shared with TypeScript/Python/Go

---

*Last Updated: 2025-10-10 | Version: 2.159.0*