Chapter 5: pmat - Quality Enforcement Toolkit

Run this chapter’s examples:

make run-ch05

Introduction

This chapter demonstrates EXTREME TDD quality enforcement using pmat. We show:

• ✅ O(1) pre-commit validation (hash-based caching)
• ✅ TDG (Test-Driven Grade) scoring
• ✅ ≥95% coverage enforcement

Example 1: O(1) Quality Gates

Location: examples/ch05-pmat/src/quality_gates.rs

Concept: Quality gates should run in <30ms via hash-based caching.

Run:

make run-ch05-quality-gates
# or
cargo run --package ch05-pmat --bin quality_gates

Output:

📊 Scenario 1: First run (cache MISS)
   All gates must be validated from scratch

   🔍 Running lint            took    0ms  [✅ PASS]
   🔍 Running test-fast       took    0ms  [✅ PASS]
   🔍 Running coverage        took    0ms  [✅ PASS]

📊 Scenario 2: Second run (cache HIT, code unchanged)
   O(1) lookup via hash comparison

   ⚡ Checking lint            cached    0ms  [✅ PASS]  (lookup: 711ns)
   ⚡ Checking test-fast       cached    0ms  [✅ PASS]  (lookup: 241ns)
   ⚡ Checking coverage        cached    0ms  [✅ PASS]  (lookup: 231ns)

Key principle: Hash-based caching eliminates waste (Toyota Way - Muda).

Example 2: TDG (Test-Driven Grade) Analysis

Location: examples/ch05-pmat/src/tdg_analysis.rs

Concept: Convert subjective “quality” into objective score.

Formula:

TDG = (Coverage × 0.40) + (Mutation × 0.30) + (Complexity × 0.15) + (Quality × 0.15)

Run:

make run-ch05-tdg
# or
cargo run --package ch05-pmat --bin tdg_analysis

Output (Example 1 - Excellent):

📈 Example 1: EXCELLENT quality (target for this book)
   Project: Sovereign AI Stack Book

   📊 Raw metrics:
      Line coverage:     95.5%
      Branch coverage:   93.2%
      Mutation score:    82.0%
      Avg complexity:    8.3
      Max complexity:    12
      Clippy warnings:   0
      Clippy errors:     0

   🎯 TDG Score: 91.2 (Grade: A)

   ✅ PASS: TDG 91.2 ≥ 90.0 (meets A- standard)

METRICS OVER ADJECTIVES: “TDG 91.2 (A)” is objective, “good quality” is vague.

Example 3: Coverage Enforcement (≥95%)

Location: examples/ch05-pmat/src/coverage_demo.rs

Concept: Enforce 95% minimum test coverage.

Run:

make run-ch05-coverage
# or
cargo run --package ch05-pmat --bin coverage_demo

Output:

   File-by-file breakdown:
      ✅ src/vector.rs           100.0%  (150/150 lines)
      ✅ src/matrix.rs            96.0%  (192/200 lines)
         Uncovered lines: [145, 146, 187, 213, 214, 215, 278, 289]
      ⚠️  src/backend.rs          92.8%  (167/180 lines)
         Uncovered lines: [23, 45, 67, 89, 102, ...]
      ✅ src/error.rs             98.0%  (49/50 lines)
         Uncovered lines: [42]

   📊 Total Coverage: 94.2%
      Covered: 558 lines
      Total:   593 lines
      Missing: 35 lines

   ❌ FAIL: Coverage below 95% requirement
      Shortfall: 0.8 percentage points
      Need 5 more covered lines

BRUTAL HONESTY: We show which lines are uncovered, not just percentages.

Configuration

This book uses these pmat configurations:

File: .pmat-gates.toml

# PMAT Quality Gates Configuration
# See: https://github.com/paiml/pmat

[quality]
# Minimum thresholds for quality gates
rust_project_score = 85
repo_score = 85
test_coverage = 80
mutation_score = 60

[gates]
# Enforce quality gates in CI
enforce_in_ci = true
block_on_failure = true

[thresholds]
# Complexity thresholds
max_cyclomatic_complexity = 20
max_cognitive_complexity = 15
max_function_lines = 100

[testing]
# Testing requirements
require_unit_tests = true
require_integration_tests = true
require_doc_tests = true

[documentation]
# Documentation requirements
require_readme = true
require_changelog = true
require_api_docs = true

File: pmat.toml

# PMAT Configuration - Sovereign AI Stack Book
# EXTREME TDD Quality Standards
# Pattern: Noah Gift style - CODE IS THE WAY

[quality_gate]
max_cyclomatic_complexity = 15  # Strict complexity limits
max_cognitive_complexity = 12   # Keep code simple
max_satd_comments = 0           # Zero technical debt tolerance
min_test_coverage = 95.0        # SPEC requirement: ≥95% coverage

[documentation]
required_updates = [
    "SPEC.md",
    "CHANGELOG.md"
]
task_id_pattern = "CH[0-9]{2}-[0-9]{3}"  # e.g., CH01-001

[toyota_way]
enable_mcp_first_dogfooding = false     # Not using MCP
enforce_jidoka_automation = true        # Rust compiler as Andon cord
kaizen_cycle_enforcement = true         # Continuous improvement

[scientific_reproducibility]
# SPEC.md core principle: "git clone → make test"
enforce_makefile_targets = true
benchmark_variance_tolerance = 5.0      # ±5% acceptable
require_test_environment_docs = true

[noah_gift_style]
# CODE IS THE WAY principles
metrics_over_adjectives = true          # "11.9x faster" not "blazing fast"
brutal_honesty = true                   # Show failures, not just successes
zero_vaporware = true                   # Delete "coming soon", show working code
master_only_git = true                  # No feature branches

Testing

Run tests:

make test-ch05

Tests validate:

• ✅ Cache hit/miss logic (O(1) lookup)
• ✅ TDG score calculation accuracy
• ✅ Coverage aggregation across files
• ✅ Grade thresholds (A+ = 95-100, etc.)

Toyota Way Principles

Quality Standards for This Book

• ✅ 95%+ test coverage (currently: 95.3%)
• ✅ TDG grade A- or better (currently: A with 91.2)
• ✅ Zero compiler warnings (enforced in CI)
• ✅ 80%+ mutation score (tests catch real bugs)

Comparison: Traditional vs EXTREME TDD

Key Takeaways

1. O(1) VALIDATION: Hash-based caching makes quality gates fast
2. OBJECTIVE SCORING: TDG converts “quality” into numbers
3. BRUTAL HONESTY: Show uncovered lines, don’t hide them
4. SCIENTIFIC REPRODUCIBILITY: Run make run-ch05 to verify all claims

Code Location

• Quality gates: examples/ch05-pmat/src/quality_gates.rs
• TDG analysis: examples/ch05-pmat/src/tdg_analysis.rs
• Coverage demo: examples/ch05-pmat/src/coverage_demo.rs
• Tests: Inline in each file (13 tests total)

Next Chapter

Chapter 6: Deep dive into trueno’s vector and matrix operations with advanced SIMD techniques.