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

# Quality Gates

> Sub-spec of [pmat-spec.md](../pmat-spec.md) | Component 2

## O(1) Quality Gate Enforcement

### Architecture

Pre-commit hooks validate cached metrics in <30ms instead of re-running full analysis.

```
Developer commits -> Pre-commit hook -> Read .pmat-metrics/ -> Compare thresholds -> Pass/Fail
```

### Metric Recording

Metrics recorded during development populate `.pmat-metrics/`:
- `make lint` -> lint duration
- `make test-fast` -> test duration
- `make coverage` -> coverage percentage
- `make release` -> binary size, dependency count

### Thresholds (`.pmat-metrics.toml`)

| Metric | Threshold | Staleness |
|--------|-----------|-----------|
| lint | <=30s | 7 days |
| test-fast | <=5min | 7 days |
| coverage | <=10min | 7 days |
| binary size | <=50MB | 7 days |
| dependencies | <=3,000 | 7 days |

### Staleness Policy

- Metrics older than 7 days trigger warnings
- Emergency bypass: `git commit --no-verify`
- Metric files: `.pmat-metrics/commit-<sha>-meta.json`

## Phase 3.2: Trueno-Graph Integration

### CSR Graph Database

trueno-graph provides:
- O(1) symbol lookups via HashMap + CSR
- PageRank-based importance scoring
- Bidirectional NodeId mapping

### Integration Points

1. **Context Generation** (`context.rs`, `context_graph.rs`):
   - `analyze_project_with_cache()` builds ProjectContextGraph
   - 7/7 tests passing (context_graph_tests.rs)

2. **TDG Analysis** (`tdg/tdg_graph.rs`):
   - TdgGraph provides O(1) function dependency tracking
   - PageRank criticality scoring
   - 14/14 tests passing (tdg_graph_tests.rs)

### Key Insight

CSR graphs only track nodes with edges. Use `node_map.len()` not `graph.num_nodes()`.

## Phase 4: Predictive Quality Gates

### ML-Based Early Detection

Using Aprender ML for predicting quality issues:
- Features: complexity trend, churn velocity, TDG trajectory
- Model: gradient boosting on historical data
- Prediction: probability of CI failure before full suite runs

### Triggered Actions

| Prediction | Confidence | Action |
|-----------|------------|--------|
| CI will pass | >90% | Skip slow tests |
| CI will fail | >80% | Block commit, suggest fixes |
| Uncertain | <80% | Run full suite |

## Pre-Commit Complexity Gates

### Thresholds

- Cyclomatic complexity: <=30 per function
- Cognitive complexity: <=25 per function

### Implementation

Hook runs `pmat analyze complexity --file` using `language_analyzer.rs` RustAnalyzer.
Pre-commit also gates on `cargo fmt --check` (PMAT-509, implemented).

### Current State (v3.11.1)

`pmat quality-gate` reports 157 total violations:
- 142 complexity violations (most at 24 vs 23 threshold — 1 point over recommended)
- 15 SATD violations (informational, no critical)
- 0 dead code, 0 security, 0 duplicate violations

8 functions with cognitive complexity >30 were reduced to <25 in v3.11.1.

### Known Issues

- `include!()` helper files cause false positives (tree-sitter fallback)
- Solution: inline methods in main file
- Cascading violations: fix ALL in same file at once

## Key Files

| File | Purpose |
|------|---------|
| `.pmat-metrics/` | Cached metric values |
| `.pmat-metrics.toml` | Threshold configuration |
| `src/services/context_graph.rs` | trueno-graph integration |
| `src/services/tdg/tdg_graph.rs` | TDG O(1) graph |

## References

- Consolidated from: quick-test-build-O(1)-checking, O1-quality-gates-phase-3.2-trueno-graph,
  o1-quality-gates-phase3.2-trueno-graph, o1-quality-gates-phase4-predictive, quality-gate-specification