The PMAT Book

PAIML MCP Agent Toolkit

Zero-configuration AI context generation with extreme quality enforcement

Version 2.173.0

By Pragmatic AI Labs

The comprehensive guide to mastering PMAT - the industry-leading tool for AI-powered code analysis, technical debt detection, and MCP-based agent integration.

Foreword

Welcome to the PMAT Book - your comprehensive guide to the PAIML MCP Agent Toolkit.

In the rapidly evolving landscape of AI-assisted development, the need for reliable, high-quality code analysis has never been more critical. PMAT represents a breakthrough in making agentic coding not just possible, but reliable and production-ready.

Why PMAT?

Traditional code analysis tools operate in isolation, providing metrics without context. AI coding assistants work with limited understanding of your codebase. PMAT bridges this gap by:

• Zero Configuration: Works instantly with any codebase
• MCP Integration: Native support for the Model Context Protocol
• Extreme Quality: Toyota Way standards with zero-defect tolerance
• Multi-Language: Support for 10+ programming languages
• Production Ready: Used in enterprise environments worldwide

What You’ll Learn

This book takes you from installation to mastery:

1. Getting Started: Install PMAT and run your first analysis in minutes
2. Core Concepts: Understand how PMAT analyzes and grades code
3. MCP Integration: Connect PMAT with Claude and other AI agents
4. Advanced Features: Master technical debt grading, similarity detection, and more
5. Real-World Usage: Apply PMAT in production environments

Who This Book Is For

• Developers wanting to improve code quality
• Team Leads implementing quality gates
• DevOps Engineers integrating analysis into CI/CD
• AI Engineers building reliable coding agents
• Anyone working with modern codebases

How to Use This Book

Each chapter includes:

• Status Indicators: Know what’s production-ready
• Working Examples: Copy-paste ready code
• Practical Tips: Real-world best practices
• Troubleshooting: Common issues and solutions

Let’s begin your journey to mastering AI-powered code analysis with PMAT.

Introduction

Chapter Status: ✅ 100% Working

Last updated: 2025-10-26
PMAT version: pmat 2.213.1

The Evolution of Code Analysis

Code analysis has evolved through three distinct generations:

1. Static Analysis Era: Tools that find bugs and style issues
2. Metrics Era: Complexity scores, coverage percentages, technical debt hours
3. AI Context Era: Intelligent understanding of code purpose and quality

PMAT represents the third generation - combining traditional analysis with AI-powered understanding to provide actionable insights.

What Makes PMAT Different

Zero Configuration Philosophy

# Traditional tools require setup
eslint --init
sonarqube configure
pylint --generate-rcfile

# PMAT just works — no config file, no init step
pmat analyze comprehensive

(analyze is a parent command: the subcommand carries the analysis, and comprehensive is the one that runs them all. --path defaults to ., so there is nothing else to pass.)

Instant Results

Within seconds, PMAT provides:

• Complete repository overview
• Language distribution
• Technical debt grading (A+ to F)
• Actionable recommendations
• MCP-ready context

Production Quality Standards

PMAT follows the Toyota Way principles:

• Kaizen: Continuous improvement in every release
• Genchi Genbutsu: Go and see for yourself (real code analysis)
• Jidoka: Built-in quality at every step

Core Capabilities

1. Repository Analysis

pmat analyze comprehensive --path /path/to/repo

Instant insights into any codebase - structure, languages, complexity, and patterns. The path goes through --path; a positional path is rejected.

2. Technical Debt Grading (TDG)

pmat analyze tdg --path /path/to/repo

Six orthogonal metrics provide comprehensive quality scoring:

• Structural Complexity
• Semantic Complexity
• Code Duplication
• Coupling Analysis
• Documentation Coverage
• Consistency Patterns

3. Code Similarity Detection

pmat similarity /path/to/repo

Advanced detection of duplicates and similar code:

• Type-1: Exact clones
• Type-2: Renamed variables
• Type-3: Modified logic
• Type-4: Semantic similarity

4. MCP Integration

{
  "tool": "analyze_repository",
  "params": {
    "path": "/workspace/project"
  }
}

Native Model Context Protocol support for AI agents.

Real-World Impact

Teams using PMAT report:

• 50% reduction in code review time
• 80% faster onboarding for new developers
• 90% accuracy in technical debt identification
• 100% coverage of multi-language codebases

Your Journey Starts Here

Whether you’re analyzing a small script or a million-line enterprise system, PMAT scales to meet your needs. This book will take you from basic usage to advanced mastery.

In the next chapter, we’ll get PMAT installed and run your first analysis. The journey to reliable, AI-powered code understanding begins now.

Chapter 1: Installation and Setup

Chapter Status: ✅ 100% Working (All methods tested)

Last updated: 2025-12-13 PMAT version: pmat 3.19.2

Overview

PMAT is designed for immediate productivity. This chapter covers:

• Multiple installation methods for every platform
• Verification and troubleshooting
• Your first analysis
• Understanding the output

By the end of this chapter, you’ll have PMAT running and will have analyzed your first repository.

Quick Start

The fastest way to get started:

# Install via Cargo (recommended)
cargo install pmat

# Verify installation
pmat --version

# Analyze current directory
# (`analyze` is a parent command — `comprehensive` is the subcommand that
#  runs the whole suite; `pmat analyze .` does not work)
pmat analyze comprehensive

That’s it! PMAT is now analyzing your code.

What’s Next

The following sections dive deeper into:

• Installing PMAT - All installation methods
• First Analysis (TDD) - Running your first analysis
• Understanding Output - Interpreting the results
• Using PMAT Effectively - CLI vs MCP, workflow tracking, finding documentation

Installing PMAT

Chapter Status: ✅ 100% Working (1/1 methods)

Last updated: 2026-06-11
PMAT version: pmat 3.19.2

Installation

PMAT is installed from crates.io with Cargo. This is the single supported install method — one way, no scripts, no hand-managed binaries.

cargo install pmat

Prerequisites: Rust 1.95+ installed via rustup.rs.

This installs the pmat binary to ~/.cargo/bin/pmat (which rustup adds to your PATH). It always builds the latest published version, optimized for your CPU, on every platform.

From source (latest unreleased)

To install the in-development version directly from a checkout:

git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit
cargo install --path .

This uses the same Cargo path — it does not introduce a second install location.

Verification

# Check version
pmat --version
# Output: pmat 3.19.2

# Show help
pmat --help

# Quick test — note --file for a single file, not a positional path
echo "print('Hello PMAT')" > test.py
pmat analyze complexity --file test.py

Upgrading

cargo install pmat --force

Pre-flight verification (pmat verify)

Before committing changes to a Rust project, run the CI-faithful pre-flight gate:

pmat verify --format json

It runs format, complexity, satd, clippy, tests fail-fast — the exact set CI enforces — so you get a “green here ⇒ green in CI” signal before pushing. See Pre-commit Hooks Management.

Feature Flags (Optional)

PMAT supports optional features enabled at compile time. They add functionality and dependencies.

# Default (no optional features)
cargo install pmat

# With a feature
cargo install pmat --features git-lib

# Multiple features
cargo install pmat --features "git-lib,github-api"

# All features
cargo install pmat --all-features

Without git-lib, PMAT shells out to git (works on any system with git). github-api enables repo-size checks and rate-limit awareness, and reads GITHUB_TOKEN for authenticated requests.

System Requirements

• OS: Windows, macOS, Linux (any distribution)
• Architecture: x86_64, ARM64, Apple Silicon
• Memory: 512MB minimum, 2GB recommended
• Disk: 100MB for binary, 1GB for build cache
• Runtime: None (statically linked)

Troubleshooting

Command not found

Ensure Cargo’s bin directory is on your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Old version installed

cargo install pmat --force

Next Steps

With PMAT installed, continue to First Analysis.

First Analysis - Test-Driven Documentation

Chapter Status: ✅ 100% Working (8/8 examples)

Last updated: 2025-10-26
PMAT version: pmat 2.213.1
Test-Driven: All examples validated in tests/ch01/test_02_first_analysis.sh

Test-First Approach

Every example in this chapter follows TDD principles:

1. Test Written First: Each example has corresponding test validation
2. Red-Green-Refactor: Tests fail until implementation works
3. Automated Validation: Run make test-ch01 to verify all examples

# Run all Chapter 1 tests
make test-ch01

# Output shows each test passing
✅ PASS: Current directory analysis  
✅ PASS: JSON output contains repository info
✅ PASS: Python files detected
✅ PASS: TDG analysis complete
✅ PASS: Summary format contains file count

Example 1: Basic Analysis (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 83

This test creates a controlled environment with known files:

# Test creates: src/main.py
def calculate_sum(a, b):
    """Calculate sum of two numbers."""
    return a + b

def calculate_product(a, b):
    """Calculate product of two numbers."""
    return a * b

# Test creates: src/utils.py
def validate_input(value):
    """Validate input value."""
    if not isinstance(value, (int, float)):
        raise ValueError("Input must be a number")
    return True

Command Tested:

pmat analyze comprehensive

analyze is a parent command. pmat analyze ., which earlier printings of this chapter presented as the first command a reader runs, exits 2 with error: unrecognized subcommand. comprehensive is the subcommand that runs the suite, and --path defaults to .. The test now asserts both directions: that pmat analyze comprehensive succeeds, and that pmat analyze . fails, so the old form cannot creep back in unnoticed.

Test Validation:

• ✅ Command executes successfully (exit code 0)
• ✅ pmat analyze . is rejected (exit code 2)
• ✅ JSON output carries a summary section
• ✅ At least one file is analyzed

Verified Output Structure (--format json, trimmed):

{
  "summary": {
    "total_files": 3,
    "total_issues": 0,
    "critical_issues": 0,
    "quality_score": 100,
    "recommendations": [
      "Code quality looks good! Continue following best practices."
    ]
  },
  "dead_code": null,
  "satd": {
    "census": {
      "discovered": 3,
      "analyzed": 2,
      "not_read": { "tests": 1, "out_of_scope": 0, "minified_or_vendor": 0, "too_large": 0, "unreadable": 0 }
    }
  }
}

"dead_code": null is load-bearing. Dead-code analysis is Rust-only, and on a Python project PMAT reports that it did not run rather than reporting 0. The test asserts null specifically — a 0 there would be a metric that measures nothing while looking clean.

Example 2: Technical Debt Grading (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 130

Command Tested:

pmat analyze tdg --path .

analyze tdg takes its path through -p/--path. pmat analyze tdg . fails with error: unexpected argument found — the test asserts that too. (The top-level pmat tdg command does accept a positional path: pmat tdg ..)

Test Validation:

• ✅ TDG analysis completes
• ✅ average_grade exists in output
• ✅ average_score is present
• ✅ pmat analyze tdg . is rejected

Verified Output Structure (project summary; .files[] omitted here):

{
  "average_score": 96.45316,
  "average_grade": "A+",
  "not_measured": [],
  "total_files": 3,
  "language_distribution": { "Python": 2, "Markdown": 1 },
  "grade_distribution": { "A+": 2, "A": 1 },
  "f_grade_count": 0,
  "grade_capped": false,
  "files_reported": 3,
  "files_truncated": false,
  "ungraded_files": [],
  "cross_file_duplication_ratio": 0,
  "cross_file_duplication_coverage": { "measured": 2, "total": 3 }
}

The keys are average_grade/average_score, not grade/overall_score, and the per-file component breakdown lives under .files[] (or in the table printed by --include-components), not under a top-level components object.

Example 3: JSON Output Format (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 105

Command Tested:

pmat analyze comprehensive --path . --format json

Test Validation:

• ✅ Output is valid JSON (parsed by jq)
• ✅ summary section exists
• ✅ complexity section exists
• ✅ satd.census reports the population that was read

JSON Schema Validation:

# Test verifies these fields exist
echo "$OUTPUT" | jq -e '.summary.total_files'
echo "$OUTPUT" | jq -e '.complexity.summary'
echo "$OUTPUT" | jq -e '.satd.census.analyzed'

Progress lines go to stderr and the JSON document to stdout, so no grep '^{' filtering is needed before piping into jq.

Example 4: Language Detection (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 171

Test Setup: Creates multi-language project:

• Python files (.py)
• Markdown files (.md)
• Test files (test_*.py)

Test Validation:

• ✅ Python language detected
• ✅ Markdown language detected
• ✅ File counts accurate
• ✅ Percentages calculated correctly

Verified Language Detection — from pmat analyze tdg --path . --format json:

{
  "language_distribution": {
    "Python": 2,
    "Markdown": 1
  },
  "total_files": 3
}

The distribution is a plain file count per language. There is no per-language line count and no percentage field; percentages appear only in the human-readable table that pmat analyze tdg prints without --format json.

Example 5: Complexity Metrics (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 180

Test Creates Functions With Known Complexity:

# Simple function (complexity = 1)
def simple_function():
    return "hello"

# Complex function (complexity = 4)
def complex_function(x):
    if x > 0:
        if x < 10:
            return "small positive"
        else:
            return "large positive"
    else:
        return "negative or zero"

Test Validation:

• ✅ Complexity metrics calculated
• ✅ Average complexity reasonable
• ✅ Max complexity detected
• ✅ No division by zero errors

Example 6: Recommendations Engine (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 189

Test Creates Code With Known Issues:

# Missing docstring (documentation issue)
def undocumented_function():
    pass

# High complexity (refactoring recommendation)
def very_complex_function(a, b, c, d):
    if a:
        if b:
            if c:
                if d:
                    return "nested"
    return "default"

Test Validation:

• ✅ Recommendations array exists
• ✅ At least one recommendation provided
• ✅ Recommendations have priority levels
• ✅ Effort estimates included

Verified Recommendations — recommendations lives under summary in the analyze comprehensive document, and is a list of plain strings:

{
  "summary": {
    "total_issues": 4,
    "critical_issues": 4,
    "quality_score": 90.0,
    "recommendations": [
      "Consider refactoring high-complexity functions",
      "Address technical debt items (TODO/FIXME comments)"
    ]
  }
}

There are no per-recommendation priority, location or effort fields. Locations come from the violation lists — complexity.violations[] and satd.violations[] — each of which carries file_path, line_number and a severity.

Example 7: Single File Analysis (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 163

Command Tested:

pmat analyze complexity --file src/main.py

A single file goes through --file, not as a positional argument. The banner confirms the scope: 🔍 Analyzing complexity of file: src/main.py.

Test Validation:

• ✅ Single file analysis works
• ✅ Output focuses on specified file
• ✅ Analysis completes successfully

Example 8: Summary Format (TDD Verified)

Test Location: tests/ch01/test_02_first_analysis.sh line 155

Command Tested:

pmat analyze comprehensive --path . --executive-summary

There is no --summary flag. --executive-summary is the real one, and --format summary is the default anyway.

Test Validation:

• ✅ Summary contains “Total Files:” keyword
• ✅ Human-readable format
• ✅ Concise output for quick overview

Verified Summary Output:

Comprehensive Code Analysis Report

Executive Summary

  Project analysis completed with 3 total files analyzed.

  Quality Score: 100.0%
  Total Files:   3
  Total Issues:  0
  Critical:      0

  Key Recommendations

    - Code quality looks good! Continue following best practices.

Running the Tests Yourself

Verify all examples work on your system:

# Run specific test
./tests/ch01/test_02_first_analysis.sh

# Run all Chapter 1 tests
make test-ch01

# View test results
cat test-results/ch01/test_02_first_analysis.log

Test Infrastructure

The test creates a temporary directory with:

• Python source files with known characteristics
• Markdown documentation
• Test files
• Known complexity patterns
• Deliberate documentation gaps

This ensures predictable, reproducible test results across all environments.

Next Steps

Now that you’ve seen TDD-verified analysis examples, explore:

• Understanding Output - Interpret the results
• Core Concepts - Deeper analysis capabilities
• Test Results - View actual test output

Understanding Output

Chapter Status: ✅ 100% Working

Last updated: 2026-03-08 PMAT version: pmat 3.6.1

Colorized Terminal Output

Starting with v3.6.1, all PMAT CLI commands use a standardized colorized output system for terminal display. The shared cli::colors module provides consistent styling across every command:

Example: Diagnostics Output

PMAT Self-Diagnostic Report
  Version: 3.6.1    Duration: 0ms

✓ analysis.complexity (0μs)
✓ analysis.deep_context (6μs)
✓ ast.python (0μs)
✓ ast.rust (137μs)
✓ ast.typescript (0μs)
✓ cache.subsystem (50μs)
✓ integration.git (4μs)
✓ output.mermaid (0μs)

Summary:
  Total: 8
  Passed: 8
  Failed: 0
  Success Rate: 100.0%

Example: Complexity Analysis

Complexity Analysis Summary

  Files analyzed: 1
  Total functions: 15

Complexity Metrics

  Median Cyclomatic: 1.0
  Median Cognitive: 0.0
  Max Cyclomatic: 7
  Max Cognitive: 10

Top Files by Complexity

  1. src/cli/colors.rs - Cyclomatic: 26, Cognitive: 19, Functions: 15

Disabling Colors

Colors are automatically disabled when piping output or when the terminal does not support ANSI codes. You can also control color output with environment variables:

# Disable colors
NO_COLOR=1 pmat analyze complexity --file src/main.rs

# Force colors (even when piping)
CLICOLOR_FORCE=1 pmat diagnose | less -R

Machine-Readable Output

When using --format json or --format sarif, PMAT outputs clean machine-readable data with no ANSI codes. (There is no yaml format.) Use these formats for CI/CD pipelines, scripting, and tool integration.

Output Formats

PMAT supports multiple output formats to integrate with your workflow:

pmat analyze is a parent command — every example below names a subcommand. comprehensive is the one that runs the whole suite; --path defaults to ., so it is written out only where the path matters. Progress lines go to stderr and the document to stdout, so | jq needs no pre-filtering.

analyze comprehensive accepts five formats: summary (the default), detailed, json, markdown and sarif.

JSON Format

Structured data for programmatic use:

pmat analyze comprehensive --path . --format json

{
  "complexity": {
    "total_files": 4,
    "violations": [
      {
        "file_path": "./src/payment_processor.py",
        "function_name": "process",
        "line_number": 4,
        "complexity": 39,
        "complexity_type": "cognitive-complexity"
      }
    ],
    "average_complexity": 4.333333333333333,
    "max_complexity": 39,
    "summary": "Analyzed 4 file(s) in . with 1 violation(s)"
  },
  "dead_code": null,
  "satd": {
    "total_files": 2,
    "summary": "Found 3 SATD violations in 2 files (analysed 4 of 4 file(s) walked)",
    "census": {
      "discovered": 4,
      "analyzed": 4,
      "not_read": { "tests": 0, "out_of_scope": 0, "minified_or_vendor": 0, "too_large": 0, "unreadable": 0 }
    }
  },
  "summary": {
    "total_files": 4,
    "total_issues": 4,
    "critical_issues": 4,
    "quality_score": 90.0,
    "recommendations": [
      "Consider refactoring high-complexity functions",
      "Address technical debt items (TODO/FIXME comments)"
    ]
  },
  "duration_ms": 55
}

Two fields repay attention. "dead_code": null means that analyser did not run (it is Rust-only) — distinct from a measured zero. satd.census reports the population the walk actually read, so a falling violation count cannot be mistaken for progress when the denominator moved instead.

Markdown Format

Human-readable reports:

pmat analyze comprehensive --path . --format markdown

# Comprehensive Code Analysis Report

## Complexity Analysis

- **Files Analyzed**: 4
- **Average Complexity**: 4.3
- **Max Complexity**: 39
- **Violations**: 1

### Top Complexity Violations

1. ./src/payment_processor.py - process (complexity: 39)

## Technical Debt (SATD) Analysis

- **Files Analyzed**: 2
- **Violations**: 3

### SATD Violations

1. ./src/payment_processor.py:1 - Requirement (Low)
2. ./src/payment_processor.py:14 - Defect (High)
3. ./web/app.js:1 - Design (Medium)

For a letter grade rather than raw counts, use pmat analyze tdg --path . (or pmat tdg .), which is where A+–F grading lives.

Detailed Format

The default summary format with every section expanded:

pmat analyze comprehensive --path . --format detailed

SARIF Format

For IDE and CI/CD integration:

pmat analyze comprehensive --path . --format sarif > analysis.sarif

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "pmat-comprehensive",
          "version": "3.32.0",
          "informationUri": "https://github.com/paiml/paiml-mcp-agent-toolkit"
        }
      },
      "results": [
        {
          "ruleId": "high-complexity",
          "level": "error",
          "message": { "text": "Function process has complexity 39" },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": { "uri": "./src/payment_processor.py" },
                "region": { "startLine": 4 }
              }
            }
          ]
        }
      ]
    }
  ]
}

Compatible with:

• GitHub Code Scanning
• Visual Studio Code
• Azure DevOps
• GitLab

Not available in pmat 3.32.0. Earlier printings of this chapter documented --format html and --format csv here, with sample reports. Neither exists: --format html exits 2 with a clap error naming the five formats that do. pmat quality-gate additionally offers human and junit, and pmat context offers llm-optimized — but no command emits HTML or CSV.

Key Metrics Explained

Complexity Metrics

Cyclomatic Complexity: Number of independent paths through code

• 1-4: Simple, low risk
• 5-7: Moderate complexity
• 8-10: Complex, needs attention
• 11+: Very complex, refactor recommended

Cognitive Complexity: How hard code is to understand

• Penalizes nested structures
• Rewards linear flow
• Better predictor of maintainability

Duplication Metrics

Type-1 (Exact): Identical code blocks

# Found in file1.py and file2.py
def calculate_tax(amount):
    return amount * 0.08

Type-2 (Renamed): Same structure, different names

# file1.py
def calc_tax(amt):
    return amt * 0.08

# file2.py  
def compute_tax(value):
    return value * 0.08

Type-3 (Modified): Similar with changes

# file1.py
def calc_tax(amt):
    return amt * 0.08

# file2.py
def calc_tax(amt, rate=0.08):
    return amt * rate

Type-4 (Semantic): Different code, same behavior

# file1.py
sum([1, 2, 3])

# file2.py
result = 0
for n in [1, 2, 3]:
    result += n

Quality Grades

PMAT uses academic-style grading:

Understanding Recommendations

PMAT provides actionable recommendations:

Priority Levels

{
  "recommendations": [
    {
      "priority": "HIGH",
      "type": "complexity",
      "message": "Refactor function 'process_data' (complexity: 28)",
      "location": "src/processor.py:142",
      "effort": "2 hours"
    },
    {
      "priority": "MEDIUM",
      "type": "duplication",
      "message": "Extract common code into shared function",
      "locations": ["src/a.py:20", "src/b.py:45"],
      "effort": "30 minutes"
    },
    {
      "priority": "LOW",
      "type": "documentation",
      "message": "Add docstring to 'helper_function'",
      "location": "src/utils.py:88",
      "effort": "5 minutes"
    }
  ]
}

Acting on Recommendations

High Priority: Address immediately

• Security vulnerabilities
• Critical complexity
• Major duplication

Medium Priority: Plan for next sprint

• Moderate complexity
• Documentation gaps
• Minor duplication

Low Priority: Continuous improvement

• Style issues
• Nice-to-have documentation
• Micro-optimizations

Filtering and Focusing Output

Focus on Specific Metrics

Each analyser is its own subcommand, so “only complexity” means running only that subcommand. analyze comprehensive opts analysers in by name:

# Only complexity
pmat analyze complexity --path .

# Only duplication (comprehensive deliberately excludes it — it says so on stderr)
pmat analyze duplicates --path .

# Two analysers in one comprehensive pass
pmat analyze comprehensive --path . --include-complexity --include-tdg

Filter by Severity

# Only high-severity self-admitted debt
pmat analyze satd --path . --severity high

# Critical only
pmat analyze satd --path . --critical-only

--severity takes exactly one of low, medium, high, critical — not a comma-separated list.

Language-Specific Analysis

# Only the Python files
pmat analyze complexity --path . --toolchain python-uv

# Only the Rust files
pmat analyze complexity --path . --toolchain rust

--toolchain takes one value (rust, deno or python-uv), not a list. To scope by file instead, use --include "**/*.py".

Integration Examples

VS Code Integration

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "PMAT Analysis",
      "type": "shell",
      "command": "pmat analyze comprehensive --path . --format sarif > pmat.sarif",
      "problemMatcher": "$pmat"
    }
  ]
}

Git Pre-Push Hook

#!/bin/bash
# .git/hooks/pre-push
GRADE=$(pmat analyze tdg --path . --format json | jq -r '.average_grade')
if [[ "$GRADE" < "B" ]]; then
  echo "Warning: Code quality grade $GRADE is below B"
  read -p "Continue push? (y/n) " -n 1 -r
  echo
  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    exit 1
  fi
fi

Next Steps

Now that you understand PMAT’s output, explore:

• Chapter 2: Core Concepts - Deep dive into analysis
• Chapter 3: MCP Protocol - AI agent integration
• Chapter 4: Advanced Features - TDG and similarity detection

Using PMAT Effectively

Chapter Status: ✅ 100% Working

Last updated: 2025-12-13 PMAT version: pmat 2.213.1

This section answers common questions about PMAT usage patterns, including CLI vs MCP mode, workflow tracking, and finding documentation.

CLI vs MCP: Understanding the Modes

What is MCP?

MCP (Model Context Protocol) is an open protocol that allows AI assistants (like Claude) to interact with external tools. PMAT supports both:

1. CLI Mode: Direct command-line usage by humans
2. MCP Mode: Protocol-based communication with AI assistants

Are All Services Available via MCP?

Yes, with some nuances:

Key Differences:

# CLI Mode - Human-friendly output with colors and formatting
pmat analyze complexity --project-path .

# MCP Mode - JSON output for AI consumption
# (automatically detected when running via MCP server)
pmat --mode mcp analyze complexity --project-path .

MCP Server Setup (for Claude Desktop/Code):

{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["--mode", "mcp", "mcp-server"]
    }
  }
}

When to Use Each Mode

Workflow Tracking: pmat work and pmat roadmap

PMAT includes a unified workflow system for tracking development work. This integrates with both GitHub Issues and local YAML-based roadmaps.

Quick Start with pmat work

# Initialize workflow in your project
pmat work init

# Start working on a task (GitHub issue or roadmap ticket)
pmat work start 42           # GitHub issue #42
pmat work start PERF-001     # Roadmap ticket PERF-001

# Check current work status
pmat work status

# Complete the work
pmat work complete

Understanding roadmap.yaml

The roadmap.yaml file is your project’s source of truth for planned work:

# roadmap.yaml
meta:
  project: My Project
  approach: Extreme TDD
  quality_gates:
    min_coverage: 0.85
    max_complexity: 10

active_sprints:
  - id: sprint-1
    name: "Initial Setup"
    tickets:
      - id: SETUP-001
        title: "Configure CI/CD"
        status: in_progress
        priority: high

      - id: SETUP-002
        title: "Add test infrastructure"
        status: planned
        priority: medium

Best Practices for pmat work

1. Always Initialize First

# In your project root
pmat work init

# This creates:
# - roadmap.yaml (if not exists)
# - .pmat/ directory for state
# - Git hooks for workflow tracking

2. Use Consistent Ticket IDs

# Good - Clear category prefixes
tickets:
  - id: PERF-001    # Performance work
  - id: BUG-042     # Bug fixes
  - id: FEAT-007    # New features
  - id: DOC-003     # Documentation

# Bad - Unclear IDs
tickets:
  - id: 1
  - id: task
  - id: todo

3. Track Work State Transitions

# Start work (moves to in_progress)
pmat work start PERF-001

# Check what you're working on
pmat work status

# Complete work (moves to done)
pmat work complete

# The workflow enforces:
# planned → in_progress → done

4. Sync with GitHub

# Create GitHub issue from roadmap ticket
pmat work start PERF-001 --create-github

# Sync status between GitHub and roadmap
pmat work sync

5. Validate Before Commits

# Check roadmap.yaml syntax
pmat work validate

# Auto-fix common issues
pmat work migrate

Integration with Quality Gates

# roadmap.yaml quality gates are enforced
meta:
  quality_gates:
    max_complexity: 10
    min_coverage: 0.85

# When you run pmat work complete, it checks:
# 1. All tests pass
# 2. Coverage meets threshold
# 3. No new complexity violations

Finding Command Documentation

PMAT has extensive CLI documentation. Here’s how to navigate it:

Built-in Help

# Top-level help
pmat --help

# Command-specific help
pmat analyze --help
pmat work --help
pmat tdg --help

# Subcommand help
pmat analyze complexity --help
pmat work start --help

Command Discovery

# List all available commands
pmat --help

# Common command groups:
# - analyze    Code analysis (complexity, satd, dead-code)
# - tdg        Technical Debt Gradient scoring
# - context    Generate project context for AI
# - work       Workflow tracking
# - roadmap    Roadmap management (alias for work)
# - quality-gate  CI/CD quality enforcement

MCP Tool Discovery

When using PMAT via MCP, tools are auto-discovered:

# List MCP tools (for debugging)
pmat mcp-server --list-tools

# Available MCP tools match CLI commands:
# - analyze_complexity
# - analyze_satd
# - analyze_dead_code
# - tdg_analyze
# - context_generate
# - quality_gate_check
# - work_start
# - work_status
# - work_complete

Documentation Resources

Quick Reference Card

# Analysis Commands
pmat analyze complexity -p .       # Cyclomatic complexity
pmat analyze satd -p .             # Self-Admitted Technical Debt
pmat analyze dead-code -p .        # Unused code detection
pmat analyze churn -p .            # Git churn analysis

# Scoring Commands
pmat tdg .                         # Technical Debt Gradient
pmat perfection-score              # 200-point quality score
pmat repo-score                    # Repository health score
pmat rust-project-score            # Rust-specific scoring

# Context Commands
pmat context                       # Full project context
pmat context --format markdown     # AI-optimized format

# Workflow Commands
pmat work init                     # Initialize workflow
pmat work start <ID>               # Start working on ticket
pmat work status                   # Show current work
pmat work complete                 # Complete current work
pmat work validate                 # Validate roadmap.yaml

# Quality Commands
pmat quality-gate                  # Run quality checks
pmat quality-gate --strict         # Fail on any issue

Next Steps

• First Analysis - Run your first code analysis
• MCP Protocol - Deep dive into MCP integration
• TDG Scoring - Understanding Technical Debt Gradient
• Command Reference - Complete command listing

Chapter 2: Getting Started with PMAT

Chapter Status: ✅ Verified against pmat 3.32.0

Last updated: 2026-08-25 PMAT version: pmat 3.32.0

What changed in this rewrite. pmat context has eight options. The 2025 edition of this chapter documented twenty-six, and eighteen of them have never existed: --include, --exclude, --exclude-large, --max-file-size, --with-analysis, --max-tokens, --max-files, --sort-by, --smart-truncate, --max-lines-per-file, --cache, --refresh, --clear-cache, --ttl, --ai-format, --prepend, --template, --repos-file, --monorepo, --incremental, --since, --timeout, --parallel, --stream, --max-memory, --skip-errors. Whole sections (“Size Management”, “Caching for Performance”, “Custom Templates”, “Multiple Repositories”, “Incremental Context”) were built on flags the parser rejects with exit 2, so they are gone rather than rewritten around a substitute that does not exist either.

Two further corrections:

• pmat context takes no positional path. pmat context /path/to/project exits 2. The path goes in -p / --project-path.
• There is no --include / --exclude filtering. The real way to narrow a context is --language / --languages, or pointing -p at a subdirectory. Both are demonstrated below.

Your First PMAT Analysis

After installing PMAT (Chapter 1), pmat context is the command you will reach for first. It walks a project, parses every source file it recognises, and prints a structured summary — file inventory, per-function complexity, and a quality scorecard — in a form an LLM or a tool can consume.

The Worked Example

Everything below runs against this four-file polyglot project, which exercises pmat’s multi-language support:

Cargo.toml
src/lib.rs      // TODO: harden the parser  + two Rust fns
src/main.rs     one Rust fn
py/app.py       two Python fns
web/index.ts    two TypeScript fns + one arrow

Basic Context Generation

pmat context

⏳ Analyzing project...
Analyses complete
Analysis complete!
# Project Context

**Language**: rust
**Project Path**: .

## Project Structure

- **Total Files**: 4
- **Total Functions**: 8
- **Median Cyclomatic**: 2.00
- **Median Cognitive**: 2.00

## Quality Scorecard

- **Overall Health**: 100.0%
- **Maintainability Index**: not measured
- **Complexity Score**: 100.0
- **Test Coverage**: N/A

## Files

### ./py/app.py

**File Complexity**: 3 | **Functions**: 2

- **Function**: `parse` [complexity: 3] [cognitive: 3] [big-o: O(1)] [satd: 0] [churn: low(1)]
- **Function**: `double` [complexity: 3] [cognitive: 3] [big-o: O(1)] [satd: 0] [churn: low(1)]

### ./src/lib.rs

**File Complexity**: 1 | **Functions**: 2

- **Function**: `parse` [complexity: 1] [cognitive: 0] [big-o: O(1)] [satd: 1 items] [churn: low(1)]
- **Function**: `double` [complexity: 1] [cognitive: 0] [big-o: O(1)] [satd: 1 items] [churn: low(1)]

### ./src/main.rs

**File Complexity**: 1 | **Functions**: 1

- **Function**: `main` [complexity: 1] [cognitive: 0] [big-o: O(1)] [satd: 0] [churn: low(1)]

### ./web/index.ts

**File Complexity**: 2 | **Functions**: 3

- **Function**: `parse` [complexity: 2] [cognitive: 2] [big-o: O(1)] [satd: 0] [churn: low(1)]
- **Function**: `anonymous` [satd: 0] [churn: low(1)]
- **Function**: `double` [complexity: 2] [cognitive: 2] [big-o: O(1)] [satd: 0] [churn: low(1)]

Note what each function line carries: cyclomatic complexity, cognitive complexity, an inferred Big-O class, an SATD count, and a git churn bucket. The TODO in src/lib.rs shows up as [satd: 1 items] on both functions in that file — SATD is attributed per file, not per function.

**Language**: rust is the detected primary language. It does not mean the Python and TypeScript were skipped; all four files are in the inventory.

Redirect, or use -o:

pmat context > project_context.txt
pmat context -o ctx.md

Analysis complete!
✅ Context written to: ctx.md

Scope to a subdirectory with -p:

pmat context -p ./py

# Project Context

**Language**: python
**Project Path**: ./py

## Project Structure

- **Total Files**: 1
- **Total Functions**: 2
- **Median Cyclomatic**: 3.00
- **Median Cognitive**: 3.00

Detection re-runs against the narrowed path — the primary language is now python.

Narrowing by Language

This is the real replacement for the --include / --exclude globs the old chapter documented. --language restricts the analysis to a single language:

pmat context --language python

# Project Context

**Language**: python
**Project Path**: .

## Project Structure

- **Total Files**: 1
- **Total Functions**: 2
- **Median Cyclomatic**: 2.00
- **Median Cognitive**: 2.00

One file, not four. --languages takes a comma-separated list:

pmat context --languages rust,typescript

# Project Context

**Language**: rust
**Project Path**: .

## Project Structure

- **Total Files**: 3
- **Total Functions**: 6
- **Median Cyclomatic**: 2.00
- **Median Cognitive**: 2.00

Three files — the Python is excluded. An unsupported name is rejected loudly, and the error doubles as the list of what pmat can parse:

pmat context --language klingon

Error: Language 'klingon' is not supported. Supported languages: rust, python, javascript, typescript, go, cpp, c, java, kotlin, swift, ruby, php, bash, sh, shell, wasm, wat, lean

Exit code 1.

-t / --toolchain also exists and is auto-detected when omitted. Unlike --language, an unrecognised toolchain is not rejected — pmat context -t nonsense exits 0 and analyses the project as if the flag were absent. Prefer --language, which validates.

Output Formats

--format takes markdown (default), json, sarif and llm-optimized.

JSON

pmat context --format json > context.json

{
  "version": "1.0",
  "project": {
    "language": "rust",
    "path": ".",
    "total_files": 4,
    "total_functions": 8,
    "overall_health": 100.0,
    "maintainability_index": null
  },
  "files": [
    {
      "path": "./py/app.py",
      "items": [
        {
          "name": "parse",
          "type": "function",
          "line": 1,
          "complexity": 3,
          "cognitive_complexity": 3
        },
        {
          "name": "double",
          "type": "function",
          "line": 8,
          "complexity": 3,
          "cognitive_complexity": 3
        }
      ]
    },
    {
      "path": "./web/index.ts",
      "items": [
        {
          "name": "parse",
          "type": "function",
          "line": 1,
          "complexity": 2,
          "cognitive_complexity": 2
        },
        {
          "name": "anonymous",
          "type": "function",
          "line": 1
        }
      ]
    }
  ]
}

(Abridged to two files; the real output lists all four.) Note that the JSON carries less than the Markdown: no Big-O, no SATD count, no churn bucket, and maintainability_index is null. Items pmat could not measure — the TypeScript arrow function, listed as anonymous — simply omit the complexity keys rather than reporting zero.

SARIF

pmat context --format sarif > context.sarif

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "pmat",
          "informationUri": "https://github.com/paiml/pmat",
          "semanticVersion": "3.32.0"
        }
      },
      "invocations": [
        {
          "executionSuccessful": true,
          "toolConfigurationNotifications": []
        }
      ],
      "properties": {
        "language": "rust",
        "projectPath": "."
      },
      "results": []
    }
  ]
}

results is empty, on a project that has an SATD marker and four files of measurable complexity. pmat context --format sarif emits a well-formed but finding-free SARIF document. Do not wire it into a code-scanning upload expecting annotations; use pmat analyze satd or pmat report and convert, or check whether a later pmat has populated it.

Markdown and llm-optimized

pmat context --format markdown > PROJECT_CONTEXT.md
pmat context --format llm-optimized

On this project llm-optimized is byte-identical to markdown:

diff <(pmat context --format markdown) <(pmat context --format llm-optimized)

produces no output. Treat llm-optimized as an alias until proven otherwise on your own tree.

The Remaining Two Flags

--include-large-files pulls in files over 500 KB, which are skipped by default. --skip-expensive-metrics skips TDG and complexity analysis for speed:

pmat context --include-large-files
pmat context --skip-expensive-metrics

On a four-file project --skip-expensive-metrics produces output identical to the default run — there is nothing expensive to skip. Its value is on large trees; measure it on yours before assuming a speedup.

That is the complete option set:

Integration Examples

Feeding an LLM

There is no --ai-format and no --prepend. Compose with the shell:

pmat context --format llm-optimized -o ctx.md
{ echo "Analyze this codebase for security vulnerabilities:"; cat ctx.md; } | your-llm-cli

In CI

- name: Generate project context
  run: |
    pmat context --format json -o context.json
    pmat context --format markdown -o PROJECT_CONTEXT.md
- uses: actions/upload-artifact@v3
  with:
    name: pmat-context
    path: |
      context.json
      PROJECT_CONTEXT.md

For an editor workspace

mkdir -p .vscode && pmat context --format json -o .vscode/pmat-context.json

The mkdir -p matters: pmat context -o does not create parent directories, and shell redirection into a missing directory fails before pmat even starts.

Managing Size

There is no --max-tokens, --max-files or --smart-truncate. The levers that exist are:

1. Narrow the path: pmat context -p ./src
2. Narrow the language: pmat context --language rust
3. Pick a leaner format: JSON omits the Big-O, SATD and churn annotations and is smaller than the Markdown for the same project.
4. Post-process: the Markdown is one ### ./path section per file, so awk/csplit can slice it however your context window needs.

Troubleshooting

error: unexpected argument found

You passed a positional path or one of the eighteen flags listed in the banner at the top of this chapter. pmat context --help is the authority; it fits on one screen.

Error: Language 'X' is not supported

Exit 1, and the message lists every accepted value. Note that --toolchain does not validate this way — a typo there is silently ignored.

The SARIF file has no results

That is current behaviour, not a configuration problem. See the SARIF section.

.vscode/pmat-context.json: No such file or directory

Shell redirection into a directory that does not exist. mkdir -p first.

Best Practices

1. Use -p, never a positional path.
2. Filter with --language/--languages, not with globs — globs do not exist here.
3. Choose the format for the consumer: Markdown for humans and LLMs, JSON for tools. SARIF currently carries no findings.
4. Check the primary language line. **Language**: rust on a polyglot repo means “detected primary”, not “only language analysed”.
5. Never point pmat at a tree containing secrets. There is no exclude flag to rescue you; scope with -p instead.

Summary

pmat context generates a structured, multi-language snapshot of a project for humans, tools and LLMs. It has eight options, all documented above, and every example in this chapter was executed against pmat 3.32.0.

Key takeaways:

• Path via -p; there is no positional argument.
• Filtering is by language or by path, not by glob.
• Markdown carries the richest annotations; JSON is leaner; SARIF is currently empty of results.
• llm-optimized was byte-identical to markdown in this test.

Next Steps

• Chapter 3: MCP Protocol - Integrate PMAT with AI agents
• Chapter 4: Technical Debt Grading - Analyze code quality

Chapter 3: MCP Protocol

Chapter Status: ✅ 100% Working

Last updated: 2025-10-19 PMAT version: pmat 2.213.1 MCP version: v2024-11-05

Overview

The Model Context Protocol (MCP) enables seamless integration between PMAT and AI agents like Claude, ChatGPT, and custom AI assistants. PMAT provides 19 MCP tools across 6 categories for comprehensive code analysis, quality assessment, and AI-assisted development.

Protocol Version: MCP v2024-11-05 Total Tools: 19 Transport: HTTP/1.1 (JSON-RPC 2.0)

What is MCP?

Model Context Protocol (MCP) is a standardized protocol for AI agents to interact with tools and services. PMAT exposes its code analysis capabilities via MCP, enabling:

• AI-powered code review - Automated quality analysis with actionable recommendations
• Automated documentation validation - Zero hallucinations via semantic entropy detection
• Quality gate integration - Technical Debt Grading (TDG) for CI/CD pipelines
• Technical debt analysis - Comprehensive code quality metrics with A+ to F grades
• WebAssembly deep analysis - Bytecode-level optimization and issue detection

Quick Start

1. Start the MCP Server

# Start with default configuration (localhost:3000)
pmat mcp-server

# Start with custom bind address
pmat mcp-server --bind 127.0.0.1:8080

2. Connect a Client

TypeScript/JavaScript Client

import { McpClient } from '@modelcontextprotocol/sdk';

const client = new McpClient({
  endpoint: 'http://localhost:3000',
  protocolVersion: '2024-11-05'
});

await client.connect();
await client.initialize({
  clientInfo: {
    name: "my-ai-agent",
    version: "1.0.0"
  }
});

Python Client

from mcp import Client

client = Client(
    endpoint="http://localhost:3000",
    protocol_version="2024-11-05"
)

await client.connect()

3. Call a Tool

// Validate documentation against codebase
const result = await client.callTool('validate_documentation', {
  documentation_path: 'README.md',
  deep_context_path: 'deep_context.md',
  similarity_threshold: 0.7,
  fail_on_error: true
});

// Analyze technical debt
const analysis = await client.callTool('analyze_technical_debt', {
  path: 'src/main.rs',
  include_penalties: true
});

// Get quality recommendations
const recommendations = await client.callTool('get_quality_recommendations', {
  path: 'src/complex_module.rs',
  max_recommendations: 10,
  min_severity: 'high'
});

MCP Tools Overview (19 Total)

Documentation Quality (2 tools)

• validate_documentation - Validate docs against codebase (zero hallucinations)
• check_claim - Verify individual documentation claims

Code Quality (2 tools)

• analyze_technical_debt - TDG quality analysis (A+ to F grades)
• get_quality_recommendations - Actionable refactoring suggestions

Agent-Based Analysis (5 tools)

• analyze - Comprehensive code analysis
• transform - Code transformation and refactoring
• validate - Code validation and verification
• orchestrate - Multi-agent workflow coordination
• quality_gate - Comprehensive quality checks

Deep WASM Analysis (5 tools)

• deep_wasm_analyze - Bytecode-level analysis
• deep_wasm_query_mapping - Source-to-bytecode mappings
• deep_wasm_trace_execution - Execution path tracing
• deep_wasm_compare_optimizations - Optimization comparison
• deep_wasm_detect_issues - Issue detection and diagnostics

Semantic Search (4 tools)

• semantic_search - Semantic code search (requires OpenAI API key)
• find_similar_code - Find similar code patterns
• cluster_code - Cluster code by similarity
• analyze_topics - Topic analysis and extraction

Testing (1 tool)

• mutation_test - Mutation testing for test suite quality

Architecture

┌─────────────┐
│  AI Agent   │
└──────┬──────┘
       │ MCP Protocol
       │ (JSON-RPC over HTTP)
       ▼
┌─────────────┐
│ MCP Server  │ ← server/src/mcp_integration/server.rs
├─────────────┤
│   Tools     │
├─────────────┤
│ - validate_ │ ← hallucination_detection_tools.rs
│   documenta │
│   tion      │
│ - check_    │
│   claim     │
├─────────────┤
│ - analyze_  │ ← tdg_tools.rs
│   technical │
│   _debt     │
│ - get_      │
│   quality_  │
│   recommend │
│   ations    │
├─────────────┤
│ - analyze   │ ← tools.rs
│ - transform │
│ - validate  │
│ - orchestr  │
│   ate       │
├─────────────┤
│ - deep_wasm │ ← deep_wasm_tools.rs
│   _*        │
├─────────────┤
│ - semantic_ │ ← tools.rs (adapters)
│   search    │
├─────────────┤
│ - mutation_ │ ← mutation_tools.rs
│   test      │
└─────────────┘
       │
       ▼
┌─────────────┐
│  Services   │
├─────────────┤
│ - Hallucin  │
│   ation     │
│   Detector  │
│ - TDG       │
│   Analyzer  │
│ - Agent     │
│   Registry  │
│ - Deep WASM │
│ - Semantic  │
│   Search    │
└─────────────┘

Topics Covered

• MCP Server Setup - Configure PMAT as MCP server
• Available Tools - MCP tools reference and usage
• Claude Code Integration - Connect with Claude Desktop

Common Use Cases

Pre-Commit Hook: Validate Documentation

#!/bin/bash
# .git/hooks/pre-commit

# Generate deep context
pmat context --output deep_context.md

# Validate documentation via MCP
node scripts/validate-docs.js || exit 1

CI/CD: Quality Gate

# .github/workflows/quality.yml
- name: Quality Gate
  run: |
    pmat mcp-server &
    sleep 2
    node scripts/quality-gate.js

AI Code Review Bot

// Automatically review pull requests
const files = await getChangedFiles(pr);
const reviews = await aiCodeReview(client, files);
await postReviewComments(pr, reviews);

Protocol Compliance

• Version: MCP v2024-11-05
• Transport: HTTP/1.1 (JSON-RPC 2.0)
• Capabilities:
  • ✅ Tools (19 tools)
  • ✅ Resources (planned)
  • ✅ Prompts (planned)
  • ✅ Logging
  • ❌ Sampling (not applicable)

Error Handling

All tools follow consistent error patterns:

{
  "code": -32602,
  "message": "Path does not exist: /invalid/path",
  "data": {
    "path": "/invalid/path",
    "suggestion": "Please provide a valid file or directory path"
  }
}

Error Codes:

• -32700: Parse error
• -32600: Invalid request
• -32601: Method not found
• -32602: Invalid parameters
• -32603: Internal error

Next Steps

• MCP Server Setup - Learn how to configure and run the MCP server
• Available Tools - Explore the complete catalog of 19 MCP tools
• Claude Integration - Integrate with Claude Desktop and AI agents
• Chapter 15: Complete MCP Tools Reference - Advanced workflows and integration patterns

MCP Server Setup

Chapter Status: ✅ 100% Working

Last updated: 2025-10-19 PMAT version: pmat 2.213.1

Overview

This chapter covers setting up and configuring the PMAT MCP server for AI-assisted development workflows. The MCP server provides 19 tools accessible via standardized JSON-RPC protocol.

Quick Start

Start the Server

# Start with default configuration (localhost:3000)
pmat mcp-server

# Start with custom bind address
pmat mcp-server --bind 127.0.0.1:8080

# Enable verbose logging
RUST_LOG=debug pmat mcp-server

Verify Server is Running

# Check server health
curl http://localhost:3000/health

# List available tools
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

Server Configuration

Default Configuration

The server uses the following defaults (from server/src/mcp_integration/server.rs:31):

#![allow(unused)]
fn main() {
ServerConfig {
    name: "PMAT MCP Server",
    version: env!("CARGO_PKG_VERSION"),
    bind_address: "127.0.0.1:3000",
    unix_socket: None,
    max_connections: 100,
    request_timeout: Duration::from_secs(30),
    enable_logging: true,

    // Semantic search (local embeddings - no API key required)
    semantic_enabled: false,
    semantic_db_path: Some("~/.pmat/embeddings.db"),
    semantic_workspace: Some(cwd),
}
}

Environment Variables

# Enable semantic search tools
export PMAT_SEMANTIC_ENABLED=true
export PMAT_VECTOR_DB_PATH="~/.pmat/embeddings.db"
export PMAT_WORKSPACE="/path/to/workspace"

# Logging configuration
export RUST_LOG=info  # Options: error, warn, info, debug, trace

Custom Configuration

# Custom bind address
pmat mcp-server --bind 0.0.0.0:8080

# Unix socket (for local IPC)
pmat mcp-server --unix-socket /tmp/pmat.sock

# Enable verbose logging
RUST_LOG=debug pmat mcp-server

Connection Examples

TypeScript/JavaScript Client

import { McpClient } from '@modelcontextprotocol/sdk';

async function connectToPMAT() {
  const client = new McpClient({
    endpoint: 'http://localhost:3000',
    protocolVersion: '2024-11-05',
    timeout: 30000 // 30 seconds
  });

  try {
    await client.connect();

    // Initialize the connection
    const initResponse = await client.initialize({
      clientInfo: {
        name: "my-ai-agent",
        version: "1.0.0"
      }
    });

    console.log('Connected to PMAT MCP Server:', initResponse.serverInfo);

    return client;
  } catch (error) {
    console.error('Connection failed:', error);
    throw error;
  }
}

Python Client

from mcp import Client

async def connect_to_pmat():
    client = Client(
        endpoint="http://localhost:3000",
        protocol_version="2024-11-05",
        timeout=30.0
    )

    await client.connect()

    # Initialize
    init_response = await client.initialize({
        "clientInfo": {
            "name": "my-ai-agent",
            "version": "1.0.0"
        }
    })

    print(f"Connected to: {init_response['serverInfo']['name']}")

    return client

Authentication

Current Status: No authentication required for local connections.

Future Considerations (when deploying to production):

• API key authentication
• OAuth 2.0
• mTLS for service-to-service

Troubleshooting

Server Won’t Start

# Check if port is already in use
lsof -i :3000

# Check logs
RUST_LOG=debug pmat mcp-server

# Check firewall
sudo ufw status

Connection Timeouts

// Increase timeout for slow operations
const client = new McpClient({
  endpoint: 'http://localhost:3000',
  timeout: 120000 // 2 minutes for large projects
});

Semantic Search Not Available

# Enable semantic search in config
pmat config --set semantic.enabled=true

# Or via environment variable
export PMAT_SEMANTIC_ENABLED=true

# Check server logs for semantic tool registration
RUST_LOG=info pmat mcp-server | grep semantic

Note: Semantic search uses local TF-IDF embeddings via the aprender library. No API keys required.

Best Practices

1. Connection Management

// Use connection pooling for multiple requests
class PMATClient {
  constructor(endpoint) {
    this.endpoint = endpoint;
    this.client = null;
  }

  async connect() {
    if (!this.client) {
      this.client = new McpClient({ endpoint: this.endpoint });
      await this.client.connect();
      await this.client.initialize({
        clientInfo: { name: "pmat-client", version: "1.0.0" }
      });
    }
    return this.client;
  }

  async disconnect() {
    if (this.client) {
      await this.client.disconnect();
      this.client = null;
    }
  }
}

2. Health Checks

async function checkServerHealth(client) {
  try {
    // List tools as a health check
    const tools = await client.listTools();
    return {
      healthy: true,
      toolCount: tools.tools.length,
      timestamp: new Date().toISOString()
    };
  } catch (error) {
    return {
      healthy: false,
      error: error.message,
      timestamp: new Date().toISOString()
    };
  }
}

3. Logging and Monitoring

// Wrap client calls with logging
async function loggedToolCall(client, toolName, params) {
  const startTime = Date.now();

  try {
    console.log(`[MCP] Calling ${toolName}...`);
    const result = await client.callTool(toolName, params);
    const duration = Date.now() - startTime;
    console.log(`[MCP] ${toolName} completed in ${duration}ms`);
    return result;
  } catch (error) {
    const duration = Date.now() - startTime;
    console.error(`[MCP] ${toolName} failed after ${duration}ms:`, error.message);
    throw error;
  }
}

Production Deployment Considerations

Note: The current MCP server is designed for local development. For production deployment, consider:

1. Security: Add authentication and authorization
2. Scalability: Use load balancing and horizontal scaling
3. Monitoring: Implement comprehensive logging and metrics
4. Resource Limits: Configure request timeouts and rate limiting
5. High Availability: Deploy redundant instances with health checks

Next Steps

• Available Tools - Explore the 19 MCP tools
• Claude Integration - Connect with Claude Desktop
• Chapter 15: Complete Reference - Advanced workflows and patterns

MCP Tools

Chapter Status: Working (25/25 tools documented)

Last updated: 2026-02-04 PMAT version: pmat 2.215.0

Overview

PMAT provides 25 MCP tools across 8 categories for comprehensive code analysis, quality assessment, and AI-assisted development. All tools use standardized JSON-RPC 2.0 protocol.

Tool Categories

Documentation Quality (2 tools)

Tools for validating documentation accuracy and preventing hallucinations.

validate_documentation

Validate documentation against codebase to prevent hallucinations, broken references, and 404 errors.

Input Schema:

{
  "documentation_path": "README.md",
  "deep_context_path": "deep_context.md",
  "similarity_threshold": 0.7,
  "fail_on_error": true
}

Output:

{
  "summary": {
    "pass": true,
    "total_claims": 45,
    "verified": 42,
    "unverified": 2,
    "contradictions": 1,
    "broken_references": 0,
    "http_errors": 0
  },
  "issues": [
    {
      "line": 42,
      "claim": "PMAT can compile Rust code",
      "status": "Contradiction",
      "confidence": 0.12,
      "evidence": "PMAT analyzes but does not compile"
    }
  ]
}

Use Cases:

• Pre-commit hooks for documentation validation
• CI/CD gates for preventing bad docs
• Automated documentation quality checks

check_claim

Verify a single documentation claim against the codebase.

Input Schema:

{
  "claim": "PMAT can analyze TypeScript complexity",
  "deep_context_path": "deep_context.md",
  "similarity_threshold": 0.7
}

Output:

{
  "status": "Verified",
  "confidence": 0.94,
  "evidence": "server/src/cli/language_analyzer.rs:150"
}

Code Quality (2 tools)

Technical Debt Grading (TDG) analysis and actionable recommendations.

analyze_technical_debt

Comprehensive TDG quality analysis with A+ to F grading.

Input Schema:

{
  "path": "src/main.rs",
  "include_penalties": true
}

Output:

{
  "score": {
    "total": 82.5,
    "grade": "B+",
    "complexity": 88.0,
    "duplication": 75.0,
    "size": 85.0
  },
  "penalties": [
    {
      "type": "high_complexity",
      "function": "process_data",
      "file": "src/main.rs",
      "line": 45,
      "impact": -5.0
    }
  ]
}

get_quality_recommendations

Get actionable refactoring suggestions prioritized by impact.

Input Schema:

{
  "path": "src/complex_module.rs",
  "max_recommendations": 10,
  "min_severity": "high"
}

Output:

{
  "recommendations": [
    {
      "severity": "high",
      "category": "complexity",
      "issue": "Function 'calculate' has cyclomatic complexity of 15",
      "suggestion": "Extract validation logic into separate function",
      "impact": 8.5,
      "file": "src/complex_module.rs",
      "line": 120
    }
  ]
}

Agent-Based Analysis (5 tools)

Multi-agent workflows for comprehensive code analysis and transformation.

analyze

Comprehensive code analysis using specialized agents.

Input Schema:

{
  "path": "src/",
  "agent_type": "complexity_analyzer",
  "config": {
    "threshold": 10,
    "include_tests": false
  }
}

transform

Code transformation and refactoring using AI agents.

Input Schema:

{
  "path": "src/legacy_code.rs",
  "transformation_type": "modernize",
  "preserve_behavior": true
}

validate

Code validation and verification using formal methods.

Input Schema:

{
  "path": "src/auth.rs",
  "validation_type": "security",
  "strict": true
}

orchestrate

Multi-agent workflow orchestration.

Input Schema:

{
  "workflow": "full_analysis",
  "path": "src/",
  "agents": ["complexity", "security", "maintainability"]
}

quality_gate

Comprehensive quality checks for CI/CD integration.

Input Schema:

{
  "path": "src/",
  "min_grade": "B",
  "checks": ["complexity", "security", "duplication"]
}

Deep WASM Analysis (5 tools)

Bytecode-level WebAssembly analysis and optimization.

deep_wasm_analyze

Bytecode-level WASM analysis.

Input Schema:

{
  "wasm_file": "output.wasm",
  "analysis_level": "deep"
}

deep_wasm_query_mapping

Source-to-bytecode mapping queries.

Input Schema:

{
  "wasm_file": "output.wasm",
  "source_line": 45
}

deep_wasm_trace_execution

Execution path tracing through bytecode.

Input Schema:

{
  "wasm_file": "output.wasm",
  "function": "calculate",
  "max_depth": 100
}

deep_wasm_compare_optimizations

Compare optimization levels.

Input Schema:

{
  "wasm_file_1": "output_O0.wasm",
  "wasm_file_2": "output_O3.wasm"
}

deep_wasm_detect_issues

Detect performance and security issues.

Input Schema:

{
  "wasm_file": "output.wasm",
  "check_security": true,
  "check_performance": true
}

Agent Context (4 tools)

RAG-powered semantic code search with quality annotations. No API keys required - works completely offline.

pmat_query_code

Semantic search for code by intent. Returns quality-ranked results with TDG scores, complexity, and Big-O estimates.

Input Schema:

{
  "query": "error handling in API layer",
  "limit": 5,
  "min_grade": "B",
  "max_complexity": 15,
  "path": "src/"
}

Output:

{
  "results": [
    {
      "id": "src/api/error.rs::handle_api_error",
      "name": "handle_api_error",
      "file": "src/api/error.rs",
      "line": 42,
      "signature": "pub fn handle_api_error(err: ApiError) -> Response",
      "tdg_grade": "A",
      "complexity": 8,
      "big_o": "O(1)",
      "relevance": 0.92
    }
  ]
}

Use Cases:

• Replace grep for AI agents (Claude Code, Cline, Cursor)
• Quality-filtered code discovery
• Pre-refactoring analysis

pmat_get_function

Get full function source with quality metrics by file and function name.

Input Schema:

{
  "file": "src/api/error.rs",
  "function": "handle_api_error",
  "include_callers": false,
  "include_callees": false
}

pmat_find_similar

Find functions similar to a given one for refactoring and deduplication.

Input Schema:

{
  "file": "src/api/error.rs",
  "function": "handle_api_error",
  "limit": 5,
  "min_similarity": 0.7
}

pmat_index_stats

Check agent context index health and statistics.

Input Schema:

{}

Output:

{
  "total_functions": 42001,
  "total_files": 1816,
  "avg_tdg_score": 0.3,
  "languages": ["Rust", "TypeScript", "Python"]
}

Semantic Search (4 tools)

Local semantic code search using TF-IDF embeddings (no API key required).

semantic_search

Semantic code search using embeddings.

Input Schema:

{
  "query": "authentication logic with JWT validation",
  "path": "src/",
  "max_results": 10
}

find_similar_code

Find similar code patterns.

Input Schema:

{
  "reference_file": "src/auth.rs",
  "reference_function": "validate_token",
  "similarity_threshold": 0.8
}

cluster_code

Cluster code by semantic similarity.

Input Schema:

{
  "path": "src/",
  "num_clusters": 5
}

analyze_topics

Topic analysis and extraction.

Input Schema:

{
  "path": "src/",
  "num_topics": 10
}

JVM Language Analysis (2 tools)

Full AST-based analysis for Java and Scala (Sprint 51).

analyze_java

Analyze Java source code with full AST parsing for complexity, structure, and quality metrics.

Input Schema:

{
  "path": "src/main/java/",
  "max_depth": 3,
  "include_metrics": true,
  "include_ast": false
}

Output:

{
  "summary": {
    "total_files": 45,
    "total_classes": 38,
    "total_methods": 287,
    "avg_complexity": 3.2,
    "max_complexity": 15
  },
  "files": [
    {
      "path": "src/main/java/com/example/Service.java",
      "classes": 2,
      "methods": 18,
      "lines": 342,
      "complexity": {
        "cyclomatic": 5.2,
        "cognitive": 4.1
      }
    }
  ]
}

Use Cases:

• Analyze Java enterprise applications
• Track complexity trends in Spring/Jakarta EE projects
• Identify refactoring opportunities in JVM codebases
• Generate quality reports for Java microservices

analyze_scala

Analyze Scala source code with full AST parsing for complexity, structure, and quality metrics.

Input Schema:

{
  "path": "src/main/scala/",
  "max_depth": 3,
  "include_metrics": true,
  "include_ast": false
}

Output:

{
  "summary": {
    "total_files": 28,
    "total_classes": 15,
    "total_case_classes": 22,
    "total_objects": 12,
    "total_traits": 8,
    "total_methods": 156,
    "avg_complexity": 2.8,
    "max_complexity": 12
  },
  "files": [
    {
      "path": "src/main/scala/com/example/Service.scala",
      "case_classes": 3,
      "objects": 1,
      "methods": 14,
      "lines": 287,
      "complexity": {
        "cyclomatic": 3.8,
        "cognitive": 3.2
      }
    }
  ]
}

Use Cases:

• Analyze Scala functional codebases
• Track quality in Akka/Play Framework applications
• Identify complex pattern matching expressions
• Generate reports for Scala microservices

Testing (1 tool)

Mutation testing for test suite quality assessment.

mutation_test

Run mutation testing to measure test effectiveness.

Input Schema:

{
  "path": "src/",
  "target_file": "src/main.rs",
  "timeout": 60
}

Output:

{
  "total_mutants": 45,
  "caught": 40,
  "missed": 5,
  "timeout": 0,
  "score": 88.9
}

Common Workflows

Workflow 1: Documentation Validation

// Step 1: Generate deep context
await runCommand('pmat context --output deep_context.md');

// Step 2: Validate documentation
const result = await client.callTool('validate_documentation', {
  documentation_path: 'README.md',
  deep_context_path: 'deep_context.md',
  similarity_threshold: 0.7,
  fail_on_error: true
});

if (!result.summary.pass) {
  console.error('Documentation validation failed!');
  process.exit(1);
}

Workflow 2: Code Quality Check

// Analyze technical debt
const analysis = await client.callTool('analyze_technical_debt', {
  path: 'src/',
  include_penalties: true
});

// Get recommendations if score is low
if (analysis.score.total < 70) {
  const recommendations = await client.callTool('get_quality_recommendations', {
    path: 'src/',
    max_recommendations: 10,
    min_severity: 'high'
  });

  console.log('Quality issues found:', recommendations.recommendations);
}

Workflow 3: WASM Optimization Analysis

// Analyze WASM bytecode
const analysis = await client.callTool('deep_wasm_analyze', {
  wasm_file: 'output.wasm',
  analysis_level: 'deep'
});

// Compare optimizations
const comparison = await client.callTool('deep_wasm_compare_optimizations', {
  wasm_file_1: 'output_O0.wasm',
  wasm_file_2: 'output_O3.wasm'
});

// Detect issues
const issues = await client.callTool('deep_wasm_detect_issues', {
  wasm_file: 'output.wasm',
  check_security: true,
  check_performance: true
});

Workflow 4: Agent Context Search

// Step 1: Search for relevant code by intent
const results = await client.callTool('pmat_query_code', {
  query: 'error handling in API layer',
  min_grade: 'B',
  limit: 5
});

// Step 2: Get full function details
for (const result of results) {
  const details = await client.callTool('pmat_get_function', {
    file: result.file,
    function: result.name
  });
  console.log(`${result.name}: TDG ${result.tdg_grade}, Complexity ${result.complexity}`);
}

// Step 3: Find similar functions for refactoring
const similar = await client.callTool('pmat_find_similar', {
  file: results[0].file,
  function: results[0].name,
  limit: 3
});

Error Handling

All tools return consistent error formats:

{
  "code": -32602,
  "message": "Path does not exist: /invalid/path",
  "data": {
    "path": "/invalid/path",
    "suggestion": "Please provide a valid file or directory path"
  }
}

Error Codes:

• -32700: Parse error
• -32600: Invalid request
• -32601: Method not found
• -32602: Invalid parameters
• -32603: Internal error

Next Steps

• Claude Integration - Connect with Claude Desktop
• Chapter 15: Complete MCP Tools Reference - Advanced workflows and detailed schemas

Claude Code Integration

Chapter Status: ✅ 100% Working

Last updated: 2025-10-19 PMAT version: pmat 2.213.1

Overview

This chapter covers integrating PMAT MCP tools with Claude Desktop for AI-assisted code analysis and quality improvement.

Claude Desktop Configuration

Configuration File Location

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Basic Configuration

{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["mcp-server"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Advanced Configuration

{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["mcp-server", "--bind", "127.0.0.1:3000"],
      "env": {
        "RUST_LOG": "info",
        "PMAT_MCP_LOG_LEVEL": "info",
        "PMAT_MCP_CACHE_ENABLED": "true",
        "PMAT_MCP_MAX_CONCURRENT": "4"
      }
    },
    "pmat-semantic": {
      "command": "pmat",
      "args": ["mcp-server", "--bind", "127.0.0.1:3001"],
      "env": {
        "PMAT_SEMANTIC_ENABLED": "true",
        "PMAT_VECTOR_DB_PATH": "~/.pmat/embeddings.db",
        "RUST_LOG": "info"
      }
    }
  }
}

Using PMAT Tools with Claude

Documentation Validation

Prompt:

I need to validate my README.md against the actual codebase. Can you use PMAT
to check for hallucinations, broken references, and contradictions?

Claude will:

1. Generate deep context: pmat context --output deep_context.md
2. Call validate_documentation tool
3. Report validation results with specific issues

Example Output:

I've validated your README.md against the codebase. Here are the results:

✅ Pass: 42/45 claims verified (93.3%)

Issues Found:

1. Line 42: Contradiction
   Claim: "PMAT can compile Rust code"
   Evidence: PMAT analyzes but does not compile code
   Confidence: 88%

2. Line 67: Unverified
   Claim: "Supports analysis of 15+ languages"
   Status: Could not verify exact count
   Confidence: 65%

Recommendations:
- Update line 42 to accurately reflect PMAT's analysis capabilities
- Verify and document the exact language count

Code Quality Analysis

Prompt:

Can you analyze the code quality of src/main.rs and give me recommendations
for improving it?

Claude will:

1. Call analyze_technical_debt for TDG grading
2. Call get_quality_recommendations for specific suggestions
3. Prioritize recommendations by impact

Example Output:

I've analyzed src/main.rs. Current quality grade: B+ (82.5/100)

High-Priority Recommendations:

1. Complexity Reduction (Impact: 8.5 points)
   Function: calculate_total (line 120)
   Issue: Cyclomatic complexity of 15
   Suggestion: Extract validation logic into separate function

2. Duplication Elimination (Impact: 6.2 points)
   Lines: 45-60 similar to lines 200-215
   Suggestion: Create shared utility function

3. Documentation (Impact: 4.1 points)
   Functions missing doc comments: 5
   Suggestion: Add comprehensive documentation

Would you like me to help implement these improvements?

WASM Analysis

Prompt:

I have a WASM file at output.wasm. Can you analyze it for performance issues
and compare it with an optimized version at output_O3.wasm?

Claude will:

1. Call deep_wasm_analyze for bytecode analysis
2. Call deep_wasm_compare_optimizations for comparison
3. Call deep_wasm_detect_issues for issue detection

Multi-Agent Workflow

Prompt:

Can you run a comprehensive quality check on my project at src/ and create
a quality gate report?

Claude will:

1. Call orchestrate to coordinate multiple agents
2. Run complexity, security, and maintainability analysis
3. Call quality_gate with thresholds
4. Generate comprehensive report

Common Use Cases

Use Case 1: Pre-Commit Documentation Check

Prompt:

I'm about to commit changes to README.md. Can you validate it against the
codebase to ensure there are no hallucinations or broken references?

Result: Claude validates documentation and prevents bad commits.

Use Case 2: Code Review Assistance

Prompt:

I have a pull request with changes in src/auth.rs. Can you review it for
quality issues and security concerns?

Result: Claude performs automated code review with TDG analysis and security checks.

Use Case 3: Refactoring Guidance

Prompt:

The quality of src/legacy_code.rs is poor. Can you analyze it and guide me
through refactoring to improve the grade to A-?

Result: Claude provides step-by-step refactoring recommendations with impact analysis.

Use Case 4: Mutation Testing

Prompt:

I want to check the quality of my test suite for src/calculator.rs. Can you
run mutation testing and tell me how effective my tests are?

Result: Claude runs mutation testing and reports test effectiveness with specific gaps.

Integration Patterns

Pattern 1: Documentation Accuracy Enforcement

Setup:
1. Configure Claude with PMAT MCP server
2. Create pre-commit hook that asks Claude to validate docs

Workflow:
- Developer modifies README.md
- Pre-commit hook triggers
- Claude validates via PMAT
- Commit blocked if validation fails

Pattern 2: AI-Assisted Code Review

Setup:
1. Configure Claude with PMAT MCP server
2. Configure GitHub Actions to post Claude reviews

Workflow:
- Developer opens pull request
- GitHub Action triggers
- Claude analyzes changes via PMAT
- Claude posts review comments with specific recommendations

Pattern 3: Continuous Quality Monitoring

Setup:
1. Configure Claude with PMAT MCP server
2. Schedule daily quality reports

Workflow:
- Cron job triggers daily
- Claude analyzes entire codebase via PMAT
- Claude generates quality report
- Report sent to team via Slack/Email

Troubleshooting

Claude Can’t Find PMAT Tools

Symptoms:

• Claude says “I don’t have access to PMAT tools”
• Tools not showing in Claude’s tool list

Solutions:

1. Verify pmat binary is in PATH:

   which pmat
   

2. Check Claude Desktop config:

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

3. Restart Claude Desktop

4. Check PMAT server logs:

   RUST_LOG=debug pmat mcp-server
   

Tools Timing Out

Symptoms:

• Claude reports “Tool call timed out”

Solutions:

1. Increase timeout in config:

   {
     "mcpServers": {
       "pmat": {
         "command": "pmat",
         "args": ["mcp-server"],
         "timeout": 120000
       }
     }
   }
   

2. Reduce analysis scope:

   • Analyze specific files instead of entire project
   • Exclude large directories (node_modules, target, etc.)

Semantic Search Not Working

Symptoms:

• Claude says semantic search tools unavailable

Solutions:

1. Enable semantic search via config:

   pmat config --set semantic.enabled=true
   

2. Or add to Claude config:

   {
     "mcpServers": {
       "pmat": {
         "env": {
           "PMAT_SEMANTIC_ENABLED": "true"
         }
       }
     }
   }
   

Note: PMAT uses local TF-IDF embeddings via the aprender library. No external API keys are required.

Best Practices

1. Be Specific in Prompts

Good:

Analyze src/auth.rs for security issues and high complexity functions.
Focus on functions with cyclomatic complexity > 10.

Bad:

Check my code.

2. Use Iterative Analysis

Approach:

1. Start with high-level analysis (TDG grading)
2. Dive deeper into specific issues
3. Request targeted recommendations
4. Implement and re-analyze

3. Combine Multiple Tools

Example:

Can you:
1. Validate README.md against the codebase
2. Analyze code quality of src/
3. Run mutation testing on src/calculator.rs
4. Generate a comprehensive quality report

4. Leverage Context

Example:

I'm working on improving code quality from B to A-. The previous analysis
showed high complexity in src/main.rs. Can you analyze it again and show
me if the refactoring improved the grade?

Next Steps

• Chapter 15: Complete MCP Tools Reference - Advanced workflows and detailed tool schemas
• Explore integration with other AI assistants (ChatGPT, Copilot)
• Set up automated quality gates in CI/CD pipelines

Chapter 3.4: Three Surfaces — CLI, MCP stdio, and MCP over HTTP

Chapter Status: ✅ 100% Working (28/28 automated assertions)

Last updated: 2026-08-25 PMAT version: pmat 3.32.0

The Problem

One pmat binary answers to three different callers, and the three do not look alike from the outside:

• a human at a shell,
• an agent that spawns a child process and speaks JSON-RPC down its pipes,
• an agent on another machine (or in another container) that can only reach you over a socket.

Older editions of this book treated the first as “pmat” and the second as “MCP mode”, and described the third as a stub that printed a banner and bound nothing. As of pmat 3.32.0 all three are real, they are served from the same binary, and — the part worth internalising — the two MCP surfaces expose a tool set that is identical down to the JSON schema. This chapter is the map: how to start each surface, how to talk to it with nothing but curl, exactly which error you get when you hold it wrong, and how to choose.

The Three Surfaces at a Glance

Two things are true of every row and are worth stating before the details:

1. The two MCP rows serve the same tools. Not “similar” — the same, proved by diff later in this chapter.
2. The --transport flag has exactly one implemented value. http works. web-socket, http-sse, both and all exit 2 with a message saying so. There is no stdio value; stdio is not a transport of serve, it is what --mode mcp gives you.

The examples below all use one tiny fixture. Create it once:

mkdir -p /tmp/pmat-mcp-demo/src && cd /tmp/pmat-mcp-demo
cat > src/main.rs << 'EOF'
// TODO: replace this hand-rolled grader with the real one
fn grade(score: u32, strict: bool) -> &'static str {
    if strict {
        if score > 90 { "A" } else if score > 80 { "B" } else { "C" }
    } else if score > 70 {
        "pass"
    } else {
        "fail"
    }
}

fn main() {
    println!("{}", grade(85, true));
}
EOF

One file, one TODO. Every surface below is asked the same question about it, so you can see the answers line up.

Surface 1: The CLI

pmat analyze satd --path src/main.rs

🔍 Analyzing Self-Admitted Technical Debt (SATD)...
SATD Analysis Summary

Found 1 SATD violations in 1 files

Total violations:  1

Severity Distribution
  Critical: 0
  High: 0
  Medium: 0
  Low: 1

Top Violations
  1. src/main.rs:1 - Requirement Low

Formatted for a person, exit code for a script. Nothing about MCP is involved. This is the surface the rest of the book documents command by command; it is in this chapter only so the other two have something to be compared against.

Surface 2: MCP over stdio

An MCP client that can spawn a process wants a command, not a URL. pmat gives it one:

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null | head -1

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"paiml-mcp-agent-toolkit","version":"3.32.0"}}}

There are three spellings of this one server, and they are interchangeable:

pmat --mode mcp and MCP_VERSION=1 pmat are verified in this book’s test suite to return a byte-identical tools/list.

A correction to older editions. Earlier printings said MCP mode was auto-detected from the shape of stdin and that pmat --mode mcp did not work. Both halves are now false. Piping JSON-RPC into a bare pmat prints the help text and exits 2 — it does not enter MCP mode. Use --mode mcp or MCP_VERSION=1.

Registering the stdio server

pmat init writes the registration for you rather than making you copy JSON out of a book:

pmat init --target claude --path /tmp/pmat-mcp-demo

pmat init — target: claude
root: /tmp/pmat-mcp-demo

  created  .agents/hooks/pmat-quality-feedback.sh       shared pre-write quality hook (FEEDBACK, not a gate — see AGENTS.md)
  created  AGENTS.md                                    root rules file, read by Claude Code and Antigravity alike
  created  .claude/settings.json                        PreToolUse hook via $CLAUDE_PROJECT_DIR (no cwd hazard)
  created  .mcp.json                                    MCP server registration — `pmat --mode mcp`, spawn-tested
  created  .claude/skills/pmat-quality/SKILL.md         skill with pinned `effort` frontmatter (the path CB-1650 reads)

5 written, 0 already current, 0 kept, 0 refused

next: install pmat on PATH (`cargo install pmat`), then verify the MCP
registration with:  pmat --mode mcp <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

The .mcp.json it writes is the canonical shape:

{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["--mode", "mcp"],
      "env": {}
    }
  }
}

Note args. A registration with "args": [] — which older editions of this book printed — no longer starts an MCP server.

Surface 3: MCP over Streamable HTTP

New in 3.32.0: --transport http is implemented, it binds a real socket, and it is in the default feature set. Before this release you had to build with --features mcp-http; a stock cargo install pmat now has it.

Quickstart

PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789' \
  pmat serve --transport http --port 8823

pmat MCP (streamable HTTP) listening on http://127.0.0.1:8823/
  auth: Bearer, from PMAT_MCP_HTTP_TOKEN; unauthenticated requests get 401
  tools: 16

Three facts are packed into that banner, and each is load-bearing:

1. The URL ends in /. MCP is served at the root path. There is no /mcp, no /health, no /api/v1; those are 404s (see Failure Modes).
2. A bearer token is mandatory. pmat serve refuses to start without PMAT_MCP_HTTP_TOKEN, and refuses tokens shorter than 16 characters. The underlying pmcp transport serves every request when no auth provider is wired, so “no token” has to mean “no server” — there is no unauthenticated mode to fall into by accident.
3. The tool count is a property of your build, not of this book. Read it from the banner, or count it yourself (below).

It binds 127.0.0.1 unless you pass --host. If you widen that, the bearer token is the only thing between the port and the full tool surface — pick a real secret, not the demo string above.

Wiring it into Claude Code

claude mcp add --scope user --transport http pmat-http http://127.0.0.1:8823/ \
  --header "Authorization: Bearer pmat-mcp-demo-token-0123456789"

Added HTTP MCP server pmat-http with URL: http://127.0.0.1:8823 to user config
Headers: {
  "Authorization": "[REDACTED]"
}
File modified: /home/noah/.claude.json

claude mcp list

Checking MCP server health…

pmat-http: http://127.0.0.1:8823/ (HTTP) - ✔ Connected

(Any other servers you have registered are listed alongside it; only the pmat-http line is shown here.)

✔ Connected is the whole acceptance test. If you get ✘ Failed to connect, jump to Failure Modes — the message is specific enough to name the cause.

To remove it again:

claude mcp remove --scope user pmat-http

Removed MCP server pmat-http from user config
File modified: /home/noah/.claude.json

Talking to It With curl

You do not need an MCP client to exercise the HTTP surface, and doing it by hand once is the fastest way to understand what your client is doing. Two headers are non-negotiable:

• Authorization: Bearer <PMAT_MCP_HTTP_TOKEN>
• Accept: application/json, text/event-stream — the streamable transport rejects a request that does not accept both.

initialize

curl -s -D - -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

HTTP/1.1 200 OK
content-type: application/json
mcp-protocol-version: 2024-11-05
x-content-type-options: nosniff
x-frame-options: DENY
cache-control: no-store
vary: origin
access-control-expose-headers: mcp-session-id,mcp-protocol-version
content-length: 179

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"paiml-mcp-agent-toolkit","version":"3.32.0"}}}

Look at what is not in those headers: there is no Mcp-Session-Id. This server does not issue one and does not require one. tools/call works immediately, and works even if you never sent initialize at all.

tools/call

curl -s -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"analyze_satd","arguments":{"paths":["/tmp/pmat-mcp-demo/src/main.rs"]}}}' \
  | jq -r '.result.content[0].text' | jq .

{
  "status": "completed",
  "message": "SATD analysis completed",
  "results": {
    "total_satd": 1,
    "files": [
      {
        "file": "/tmp/pmat-mcp-demo/src/main.rs",
        "satd_count": 1,
        "debts": [
          {
            "line": 1,
            "category": "Requirement",
            "severity": "Low",
            "text": "TODO: replace this hand-rolled grader with the real one"
          }
        ]
      }
    ],
    "files_read": 1,
    "files_not_read": {
      "total": 0,
      "tests": 0,
      "examples_demo_fuzz_generated": 0,
      "minified_or_vendor": 0,
      "too_large": 0,
      "unreadable": 0
    },
    "violations_truncated": false
  }
}

The MCP envelope is a content array whose single text entry is a stringified JSON report — hence the double jq. Same one TODO the CLI found, same line number, now machine-readable.

The paths belong to the server, not to you

The tool arguments are filesystem paths, and they are resolved by the server process. Run the server in /tmp/pmat-mcp-demo and curl from anywhere else:

cd /home/noah/src/pmat-book   # a completely different directory
curl -s -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"analyze_satd","arguments":{"paths":["src/main.rs"]}}}' \
  | jq -r '.result.content[0].text' | jq -c '.results.files[0].file'

"src/main.rs"

That resolved against the server’s working directory. A path relative to the client’s directory is simply not there:

curl -s -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"analyze_satd","arguments":{"paths":["src/ch03-00-mcp-protocol.md"]}}}' \
  | jq -c .error

{"code":-32603,"message":"Validation error: path(s) not found: src/ch03-00-mcp-protocol.md. Analysing a nonexistent path would report zero findings, which is indistinguishable from a clean result."}

Note that pmat refuses rather than returning a clean-looking zero. Over HTTP, send absolute paths unless you are certain where the server was started.

The Two MCP Surfaces Are One Surface

This is the claim that makes the HTTP transport safe to adopt: nothing about your tool usage changes when you move a client from stdio to HTTP. Prove it locally — ask both surfaces for their tool list, sort, and diff:

TOKEN='pmat-mcp-demo-token-0123456789'
INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'
LIST='{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

printf '%s\n%s\n' "$INIT" "$LIST" | pmat --mode mcp 2>/dev/null \
  | sed -n 2p | jq -S '.result.tools | sort_by(.name)' > /tmp/tools-stdio.json

curl -s -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d "$LIST" | jq -S '.result.tools | sort_by(.name)' > /tmp/tools-http.json

diff /tmp/tools-stdio.json /tmp/tools-http.json && echo "identical: $(jq length /tmp/tools-http.json) tools"

identical: 16 tools

diff is silent: same names, same descriptions, same inputSchema for every tool. The sort_by(.name) matters — the two surfaces build the same set but do not promise the same array order, so compare them as sets.

The names, on the build used for this chapter:

jq -r '.[].name' /tmp/tools-http.json

analyze_big_o
analyze_complexity
analyze_dag
analyze_dead_code
analyze_deep_context
analyze_satd
generate_context
git_operation
pdmt_deterministic_todos
pmat_find_similar
pmat_get_function
pmat_index_stats
pmat_query_code
quality_gate
quality_proxy
scaffold_project

Count the tools; do not quote them

The number above is 16, and it is not a fact about “pmat 3.32.0”. Tools are added within a release line, so a binary reporting the same version string can serve more of them: the 3.32.0 build this chapter was written against (commit 583ea9ac) serves 16, while a 3.32.0 build from commit 90767deb serves 19 — it adds analyze_hardcoded_paths, analyze_reachability and analyze_vacuous_tests. Both builds pass the identity check above unchanged.

So read the count from your own binary rather than from a book:

pmat --version | head -1
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null | sed -n 2p | jq '.result.tools | length'

pmat 3.32.0
16

The HTTP banner’s tools: N line reports the same number, and this book’s test suite asserts that the banner and tools/list agree.

Failure Modes

These are ordered by how often you will hit them. Each message below is the verbatim output of the command above it.

The token is too short — the server refuses to start

PMAT_MCP_HTTP_TOKEN='too-short-123' pmat serve --transport http --port 8823

Error: PMAT_MCP_HTTP_TOKEN must be at least 16 characters; got 13

Exit code 1. No socket is bound. The minimum is 16 characters.

No token at all — also refuses to start

env -u PMAT_MCP_HTTP_TOKEN pmat serve --transport http --port 8823

Error: PMAT_MCP_HTTP_TOKEN is not set. `pmat serve` will not start an unauthenticated MCP endpoint: pmcp serves every request when no auth provider is configured, so starting without a token would publish the full tool surface to anyone who can reach the port.

Exit code 4. This is deliberate: an unauthenticated MCP endpoint would hand anyone who can reach the port the ability to read your source tree, so the failure is loud and at startup rather than silent and at request time.

Missing Accept header — 406

curl -s -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'

{"jsonrpc":"2.0","error":{"code":-32700,"message":"Accept header must include application/json or text/event-stream"},"id":null}

HTTP 406. Beware of hiding this from yourself: curl -f turns it into an empty body and exit status 22, with no message at all —

curl -sf -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'
echo "curl -f exit=$?"

curl -f exit=22

— which is why the header requirement is worth committing to memory. Health checks written with curl -f are the classic way to make this bug invisible.

No credentials — 401

curl -s -X POST http://127.0.0.1:8823/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'

{"jsonrpc":"2.0","error":{"code":-32003,"message":"Authentication failed: Internal error: missing Authorization header"},"id":null}

Wrong token — 401

curl -s -X POST http://127.0.0.1:8823/ \
  -H "Authorization: Bearer wrong-token-but-long-enough-xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'

{"jsonrpc":"2.0","error":{"code":-32003,"message":"Authentication failed: Internal error: invalid bearer token"},"id":null}

Both are HTTP 401 with JSON-RPC code -32003, and the two messages tell you which mistake you made.

Right server, wrong path — 404

MCP lives at /. Every path a REST habit reaches for is a 404:

for p in /mcp /health /api/v1; do
  printf '%-8s ' "$p"
  curl -s -o /dev/null -w 'HTTP %{http_code}\n' -X POST "http://127.0.0.1:8823$p" \
    -H "Authorization: Bearer pmat-mcp-demo-token-0123456789" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}'
done

/mcp     HTTP 404
/health  HTTP 404
/api/v1  HTTP 404

There is no health endpoint. To check liveness, POST a real initialize to / and look for a 200 — or watch for the listening banner on startup.

A 400 is never an authentication problem

The request body is parsed before credentials are checked, so a malformed body returns 400 even with no Authorization header at all:

curl -s -o /dev/null -w 'HTTP %{http_code}\n' -X POST http://127.0.0.1:8823/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d 'not json at all'
curl -s -X POST http://127.0.0.1:8823/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d 'not json at all'

HTTP 400
{"jsonrpc":"2.0","error":{"code":-32700,"message":"Invalid JSON: Transport error: Invalid message format: Invalid JSON: expected ident at line 1 column 2"},"id":null}

If you see 400, fix your JSON; if you see 401, fix your token. They are never the same problem.

The port is taken

PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789' pmat serve --transport http --port 8823

Error: starting the streamable-HTTP MCP server failed: Transport error: IO error: Address already in use (os error 98)

Exit code 1 — including when the thing already holding the port is your own earlier pmat serve.

claude mcp add without --header

Registering the HTTP server and forgetting the bearer header does not produce a 401 in the client UI. It produces this:

pmat-http-noauth: http://127.0.0.1:8823/ (HTTP) - ✘ Failed to connect — Dynamic Client Registration rejected (HTTP 404):

The client tried to negotiate OAuth, found no registration endpoint (correctly — there is none), and reported that instead of the underlying auth failure. If you see “Dynamic Client Registration”, you forgot --header.

The other transports

PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789' pmat serve --transport web-socket --port 8899

error: pmat serve --transport websocket is not yet implemented
  requested: transport=websocket host=127.0.0.1 port=8899
hint: `--transport http` works — build with `--features mcp-http` and set PMAT_MCP_HTTP_TOKEN
hint: use stdio MCP today — `MCP_VERSION=1 pmat` (serves the analysis tools over stdio)
hint: follow KAIZEN-0191 for the HTTP/WebSocket/SSE wiring

Exit code 2, and the same for http-sse, both and all. The refusal names the transport, the host and the port it was asked for — it fails at startup instead of printing a success banner and binding nothing, which is what these flags used to do. (The first hint is vestigial: mcp-http has been a default feature since 3.32.0, so there is nothing to rebuild.)

stdio is not a value of --transport at all:

pmat serve --transport stdio

error: invalid value 'stdio' for '--transport <TRANSPORT>'
  [possible values: http, web-socket, http-sse, both, all]

For more information, try '--help'.

Exit code 2, from the argument parser. For stdio, use --mode mcp.

One more piece of --help text to read sceptically: --transport http is described there as “HTTP transport (REST API)”. It is not a REST API. It is MCP JSON-RPC over streamable HTTP, at the root path, and nothing on the server answers a GET.

Choosing a Surface

The default answer for a coding agent is stdio. It has no port to secure, no token to leak, and the client owns the process lifetime. Reach for HTTP when a process boundary makes stdio impossible — and then remember that the token is the entire security model.

Troubleshooting

Testing This Chapter

Every command above is executed by tests/ch03/test_04_mcp_transports.sh, which is wired into make test-ch03:

make test-ch03

The script covers all three surfaces: it runs the CLI against the fixture, drives both stdio entry points, starts a real HTTP server on a free port in 18810–18840, and asserts every status code, exit code and error string quoted in this chapter — including the byte-identical tools/list diff and the agreement between the startup banner’s tool count and tools/list. It is deliberately count-agnostic, so it passes unchanged on the 16-tool and 19-tool builds described above.

Missing pmat, curl or jq makes the script print SKIPPED: … this run verified NOTHING and exit 0. That wording is chosen on purpose: a skipped test is not a passing test.

Summary

• One binary, three surfaces: CLI, MCP over stdio, MCP over HTTP.
• stdio: pmat --mode mcp, MCP_VERSION=1 pmat, or pmat serve --mode mcp. A bare pmat with JSON-RPC on stdin does not enter MCP mode.
• HTTP: pmat serve --transport http, implemented and in the default feature set as of 3.32.0. It serves MCP at the root path — /mcp, /health and /api/v1 are 404s.
• PMAT_MCP_HTTP_TOKEN is mandatory and must be ≥16 characters; the server refuses to start otherwise, because the transport underneath it would otherwise serve everyone.
• Every RPC needs both Authorization: Bearer … and Accept: application/json, text/event-stream. No session id is required.
• The stdio and HTTP tool surfaces are identical, schemas included — verify it with the diff recipe rather than trusting this sentence.
• The tool count belongs to your build, not to the version string. Count it.
• --transport web-socket, http-sse, both and all exit 2; stdio is not a --transport value at all.

Cross-references:

• Chapter 3 (ch03-00-mcp-protocol.md) — MCP protocol overview
• Chapter 3.1 (ch03-01-mcp-setup.md) — MCP server setup
• Chapter 3.3 (ch03-03-claude-integration.md) — Claude Code integration
• Chapter 15 (ch15-00-mcp-tools.md) — per-tool reference
• Chapter 64 (ch64-00-mcp-mode.md) — historical: MCP mode as of 3.14.0
• Chapter 65 (ch65-00-http-server.md) — historical: the HTTP stub, now closed

Chapter 4.1: Technical Debt Grading (TDG)

Chapter Status: ✅ 100% Working (9/9 examples)

Last updated: 2025-10-28 PMAT version: pmat 2.213.1 Test-Driven: All examples validated in tests/ch04/test_tdg.sh New in v2.179.0: Git-commit correlation for quality archaeology

Understanding Technical Debt Grading

Technical Debt Grading (TDG) is PMAT’s flagship feature for comprehensive code quality assessment. Introduced in version 2.68.0, TDG provides a multi-dimensional analysis that goes beyond simple metrics to deliver actionable insights about code maintainability.

What is TDG?

TDG is a composite score ranging from 0.0 to 5.0 that quantifies technical debt by analyzing five orthogonal components:

1. Complexity Factor (30% weight) - Cyclomatic and cognitive complexity
2. Churn Factor (35% weight) - Code change frequency and magnitude
3. Coupling Factor (15% weight) - Dependencies and architectural entanglement
4. Duplication Factor (10% weight) - Code clones and similarity
5. Domain Risk Factor (10% weight) - Business criticality and security considerations

These components combine to produce both a numerical score and a letter grade (A+ through F), making it easy to communicate code quality to both technical and non-technical stakeholders.

TDG Scoring System

Score Ranges and Severity

Known Defects v2.1: Critical Defects Auto-Fail

Starting in PMAT v2.200.0, TDG implements Critical Defects Auto-Fail - a zero-tolerance policy for production-breaking defect patterns.

Auto-Fail Behavior:

• If a file contains critical defects, TDG automatically assigns:
  • Score: 0.0/100
  • Grade: F
  • Exit Code: 1 (for CI/CD integration)

Critical Defect Patterns:

1. .unwrap() Calls (Severity: Critical)

   • Why Critical: Causes immediate panic in production
   • Evidence: Cloudflare outage 2025-11-18 (3+ hours of global network disruption)
   • Fix: Use .expect() with descriptive messages or proper error handling with ?

   #![allow(unused)]
   fn main() {
   // ❌ CRITICAL DEFECT - Auto-fails TDG
   let result = some_operation().unwrap();
   
   // ✅ CORRECT - Descriptive error handling
   let result = some_operation()
       .expect("Bot feature file must be valid");
   
   // ✅ CORRECT - Propagate errors
   let result = some_operation()?;
   }

Example TDG Output with Critical Defects:

🔴 CRITICAL DEFECTS DETECTED
===========================

Critical Defects: 2
Status: AUTO-FAIL (Score: 0.0, Grade: F)

Run 'pmat analyze defects' for detailed defect report.

Test Code Exclusion:

• Defects in test code (tests/, benches/, #[cfg(test)]) are not flagged
• Production code standards apply only to production code

See Also:

• pmat analyze defects - Detailed defect report with multiple output formats
• Chapter 5: Analyze Suite - Full documentation of defect detection
• rust-project-score - Known Defects category scoring

The Five Components Explained

1. Complexity Factor (30%)

Measures both cyclomatic and cognitive complexity:

• Cyclomatic Complexity: Number of linearly independent paths
• Cognitive Complexity: Mental effort required to understand code
• Nested Depth: Levels of control flow nesting

2. Churn Factor (35%)

Analyzes code volatility over time:

• Change Frequency: How often the code changes
• Change Magnitude: Size of changes
• Author Count: Number of different contributors
• Hot Spot Detection: Frequently modified complex code

3. Coupling Factor (15%)

Evaluates dependencies and architectural health:

• Afferent Coupling: Incoming dependencies
• Efferent Coupling: Outgoing dependencies
• Instability Index: Ratio of efferent to total coupling
• Circular Dependencies: Cyclic relationships

4. Duplication Factor (10%)

Identifies code clones and repetition:

• Type 1: Exact duplicates
• Type 2: Renamed/parameterized duplicates
• Type 3: Modified duplicates
• Type 4: Semantic duplicates

5. Domain Risk Factor (10%)

Assesses business and security criticality:

• Security Patterns: Authentication, encryption, validation
• Business Critical Paths: Payment, user data, compliance
• External Integrations: Third-party API dependencies
• Error Handling: Exception management quality

Basic TDG Analysis

Command Line Usage

# Basic TDG analysis of current directory
pmat analyze tdg -p .

# Analyze specific path
pmat analyze tdg -p src/

# Show only critical files (TDG > 2.5)
pmat analyze tdg -p . --critical-only

# Custom threshold filtering
pmat analyze tdg -p . --threshold 2.0

# Include component breakdown
pmat analyze tdg -p . --include-components

# Limit to top 10 files
pmat analyze tdg -p . --top-files 10

# ML-based scoring (GH-97)
pmat analyze tdg -p . --ml

--ml is accepted but does nothing, and says so. On pmat analyze tdg it exits 1 with:

Error: --ml is not implemented: TDG scores are still computed by the heuristic
formulas, so this flag would relabel them without changing them. Re-run
`analyze tdg` without --ml (see GH-97).

That refusal is the feature: the flag will not quietly relabel heuristic scores as model output. On the top-level pmat tdg . --ml the flag is silently ignored and you get the ordinary heuristic grade. Do not build a workflow on either form until GH-97 lands.

Example Output

📊 Technical Debt Grading Analysis
═══════════════════════════════════════════════════════════════════

Project: my-application
Files Analyzed: 247
Average TDG: 1.42 (Grade: B+)

Top Files by TDG Score:
┌──────────────────────────────────┬──────┬───────┬──────────────┐
│ File                             │ TDG  │ Grade │ Severity     │
├──────────────────────────────────┼──────┼───────┼──────────────┤
│ src/legacy/payment_processor.py │ 3.8  │ F     │ Critical     │
│ src/utils/data_transformer.py   │ 2.9  │ D     │ Critical     │
│ src/api/complex_handler.py      │ 2.4  │ C     │ Warning      │
│ src/models/user_validator.py    │ 1.8  │ B     │ Normal       │
│ src/services/email_service.py   │ 1.2  │ B+    │ Normal       │
└──────────────────────────────────┴──────┴───────┴──────────────┘

Distribution:
  A+ (0.0-0.5):  45 files (18.2%)  ████████
  A  (0.5-1.0):  82 files (33.2%)  ██████████████
  B+ (1.0-1.5):  67 files (27.1%)  ███████████
  B  (1.5-2.0):  35 files (14.2%)  ██████
  C  (2.0-2.5):  12 files (4.9%)   ██
  D  (2.5-3.0):  4 files (1.6%)    █
  F  (3.0+):     2 files (0.8%)    ▌

Component Breakdown Analysis

Understanding individual components helps target specific improvements:

# Show detailed component breakdown
pmat analyze tdg -p . --include-components --format json

Example Component Output

{
  "file": "src/legacy/payment_processor.py",
  "tdg_score": 3.8,
  "grade": "F",
  "severity": "critical",
  "components": {
    "complexity": {
      "value": 2.4,
      "cyclomatic": 45,
      "cognitive": 62,
      "max_depth": 8,
      "contribution": "63.2%"
    },
    "churn": {
      "value": 0.8,
      "changes_last_30d": 15,
      "unique_authors": 6,
      "contribution": "21.1%"
    },
    "coupling": {
      "value": 0.3,
      "afferent": 12,
      "efferent": 28,
      "instability": 0.7,
      "contribution": "7.9%"
    },
    "duplication": {
      "value": 0.2,
      "clone_percentage": 18.5,
      "similar_blocks": 4,
      "contribution": "5.3%"
    },
    "domain_risk": {
      "value": 0.1,
      "risk_patterns": ["payment", "pii_data"],
      "contribution": "2.6%"
    }
  },
  "recommendations": [
    "Extract complex nested logic into separate functions",
    "Implement proper error handling patterns",
    "Reduce coupling by introducing interfaces",
    "Consolidate duplicate payment validation logic"
  ]
}

Configuration

Project Configuration

# pmat.toml
[tdg]
enabled = true
critical_threshold = 2.5
warning_threshold = 1.5

[tdg.weights]
complexity = 0.30
churn = 0.35
coupling = 0.15
duplication = 0.10
domain_risk = 0.10

[tdg.output]
include_components = true
show_percentiles = true
top_files = 10
grade_system = true

[tdg.analysis]
parallel = true
cache_enabled = true
incremental = true

[tdg.thresholds]
max_cyclomatic_complexity = 10
max_cognitive_complexity = 15
max_nesting_depth = 4
max_coupling = 20
duplication_threshold = 0.15

Custom Domain Risk Patterns

# .pmat/domain-risk.yaml
high_risk_patterns:
  - pattern: "payment|billing|charge"
    risk_score: 1.0
    category: "financial"
    
  - pattern: "password|auth|token|secret"
    risk_score: 0.9
    category: "security"
    
  - pattern: "user_data|personal_info|pii"
    risk_score: 0.8
    category: "privacy"
    
  - pattern: "export|report|analytics"
    risk_score: 0.5
    category: "business"

critical_paths:
  - "src/payments/**"
  - "src/auth/**"
  - "src/user/personal/**"

Advanced Features

Transactional Hashed TDG System

PMAT 2.68+ includes enterprise-grade features for large-scale analysis:

Not available in pmat 3.32.0. --storage-backend, --priority, --incremental and --cache-enabled are not flags on pmat analyze tdg; each exits 2 with error: unexpected argument found. Storage is managed through the top-level pmat tdg command instead, which is a separate command tree with its own subcommands:

pmat tdg storage --help       # storage backend management
pmat tdg config --help        # configuration, single source of truth
pmat tdg diagnostics --help   # system health

The complete flag list for the analyser is pmat analyze tdg --help: -p/--path, -t/--threshold, -n/--top-files, -f/--format, --include-components, --critical-only, --ml, -o/--output, and the global logging flags. Nothing else.

MCP Integration

TDG is fully integrated with the Model Context Protocol:

{
  "name": "tdg_analyze_with_storage",
  "arguments": {
    "paths": ["src/", "lib/"],
    "storage_backend": "rocksdb",
    "priority": "critical",
    "include_components": true
  }
}

Performance Profiling

# Profile TDG analysis performance
pmat tdg performance-profile . --duration 30

# Generate flame graphs
pmat tdg flame-graph . --output tdg-flame.svg

CI/CD Integration

GitHub Actions

name: TDG Analysis

on:
  pull_request:
  push:
    branches: [main]

jobs:
  tdg-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install PMAT
        run: cargo install pmat
        
      - name: Run TDG Analysis
        run: |
          pmat analyze tdg -p . \
            --format json \
            --output tdg-report.json
            
      - name: Check TDG Thresholds
        run: |
          # Fail if any file has TDG > 3.0
          pmat analyze tdg -p . --threshold 3.0 || exit 1
          
      - name: Generate TDG Report
        run: |
          pmat analyze tdg -p . \
            --include-components \
            --format markdown > tdg-report.md
            
      - name: Comment PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('tdg-report.md', 'utf8');
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 📊 TDG Analysis Results\n\n${report}`
            });

Quality Gates

# Enforce quality gates in CI/CD
pmat quality-gate \
  --tdg-threshold 2.0 \
  --min-grade B \
  --fail-on-regression

Real-World Examples

Example 1: Legacy Code Assessment

# Analyze legacy module
pmat analyze tdg -p src/legacy/ --include-components

# Output
File: src/legacy/order_processor.py
  TDG Score: 3.2 (Grade: F)
  Components:
    Complexity: 1.8 (56%) - Cyclomatic: 42, Cognitive: 58
    Churn: 0.9 (28%) - 23 changes in 30 days
    Coupling: 0.3 (9%) - 35 dependencies
    Duplication: 0.15 (5%) - 22% duplicate code
    Domain Risk: 0.05 (2%) - Contains payment logic
    
  Critical Issues:
    - Deeply nested conditional logic (max depth: 7)
    - Multiple responsibilities in single class
    - Hardcoded business rules
    
  Recommendations:
    1. Extract payment validation to separate service
    2. Implement strategy pattern for order types
    3. Add comprehensive error handling
    4. Increase test coverage (current: 12%)

Example 2: Microservice Analysis

# Analyze microservices with custom config
cat > tdg-micro.toml << EOF
[tdg.weights]
complexity = 0.25
churn = 0.30
coupling = 0.25  # Higher weight for microservices
duplication = 0.10
domain_risk = 0.10
EOF

pmat analyze tdg -p services/

Not available in pmat 3.32.0. pmat analyze tdg has no --config flag, so the weights file above is not read by it. TDG configuration lives behind pmat tdg config — run pmat tdg config --help for the shape it expects.

Example 3: Hotspot Detection

# Find the files that lost the most points on structure or duplication.
# Every component is a score OUT OF its own maximum — higher is better — so a
# hotspot is a LOW component score, not a high one.
pmat analyze tdg -p . \
  --include-components \
  --format json | \
  jq -c '.files[] |
    select(.structural_complexity < 25 or .duplication_ratio < 20) |
    {file: .file_path, tdg: .total, grade: .grade}'

Sample output:

{"file":"./src/validate.py","tdg":91.5,"grade":"A"}
{"file":"./src/payment_processor.py","tdg":98.420006,"grade":"A+"}

The per-file keys are structural_complexity, semantic_complexity, duplication_ratio, coupling_score, doc_coverage, consistency_score, entropy_score, total, grade, file_path, language, penalties_applied, critical_defects_count. There is no nested components object, no path, no tdg_score, and no churn component in this document — churn is its own analyser (pmat analyze churn -p .).

Interpreting TDG Results

Action Priority Matrix

Improvement Strategies

For High Complexity:

• Extract methods to reduce cyclomatic complexity
• Simplify conditional logic
• Apply design patterns (Strategy, Chain of Responsibility)
• Reduce nesting depth

For High Churn:

• Stabilize requirements
• Improve test coverage
• Add documentation
• Consider architectural changes

For High Coupling:

• Introduce interfaces/protocols
• Apply Dependency Inversion Principle
• Use dependency injection
• Implement facade pattern

For High Duplication:

• Extract common functionality
• Create shared libraries
• Use template patterns
• Implement DRY principle

Best Practices

1. Baseline Establishment

# Create baseline for tracking
pmat analyze tdg -p . --format json > tdg-baseline.json

Not available in pmat 3.32.0. There is no --compare-baseline flag on pmat analyze tdg. Baselines and regression checks are their own subcommands of the top-level pmat tdg command:

pmat tdg baseline --help          # manage baselines
pmat tdg compare --help           # compare two files or directories
pmat tdg check-regression --help  # check for regressions against a baseline

2. Incremental Improvement

# Focus on worst files first
pmat analyze tdg -p . --top-files 5 --critical-only

Not available in pmat 3.32.0. --trend and --period are not flags on pmat analyze tdg. History over time is pmat tdg history — run pmat tdg history --help.

3. Team Standards

# team-standards.toml
[tdg.quality_gates]
new_code_max_tdg = 1.5
legacy_code_max_tdg = 3.0
pr_regression_tolerance = 0.1

[tdg.requirements]
min_grade_for_production = "B"
min_grade_for_release = "B+"

Troubleshooting

Common Issues

High TDG Despite Simple Code

• Check for high churn (frequent changes)
• Review domain risk patterns
• Verify weight configuration

Inconsistent Scores

• Enable caching: --cache-enabled
• Use storage backend for persistence
• Check for concurrent modifications

Performance Issues

• Use incremental analysis: --incremental
• Enable parallel processing: --parallel
• Limit scope: --top-files 20

Git-Commit Correlation (v2.179.0+)

Track TDG scores at specific git commits for “quality archaeology” workflows. Discover which commits affected code quality and track quality trends over time.

Basic Usage

Analyze with Git Context

# Analyze file and store git metadata
pmat tdg src/lib.rs --with-git-context

# Analysis output shows TDG score
# Git context stored in ~/.pmat/ for history queries

Query TDG History

# Query specific commit (by SHA or tag)
pmat tdg history --commit abc123
pmat tdg history --commit v2.178.0

# History since reference
pmat tdg history --since HEAD~10
pmat tdg history --since v2.177.0

# Commit range
pmat tdg history --range HEAD~10..HEAD
pmat tdg history --range v2.177.0..v2.178.0

# Filter by file path
pmat tdg history --path src/lib.rs --since HEAD~5

Output Formats

Table Format (Default)

pmat tdg history --commit HEAD

Output:

╭──────────────────────────────────────────────────────────────────────────╮
│  TDG History                                                             │
├──────────────────────────────────────────────────────────────────────────┤
│  📝 f0fb3af - A+ (95.5)                                                  │
│  ├─ Branch:  main                                                        │
│  ├─ Author:  Alice Developer                                             │
│  ├─ Date:    2025-10-28 18:43                                            │
│  └─ File:    src/lib.rs                                                  │
│                                                                          │
╰──────────────────────────────────────────────────────────────────────────╯

JSON Format (For Automation)

pmat tdg history --commit HEAD --format json | jq .

Output:

{
  "history": [
    {
      "file_path": "src/lib.rs",
      "score": {
        "total": 95.5,
        "grade": "A+",
        "structural_complexity": 12.5,
        "semantic_complexity": 8.3,
        "duplication_ratio": 0.02,
        "coupling_score": 15.0,
        "doc_coverage": 92.0,
        "consistency_score": 98.0,
        "entropy_score": 7.2
      },
      "git_context": {
        "commit_sha": "f0fb3af0469e620368b53cc1c560cc4b46bd4075",
        "commit_sha_short": "f0fb3af",
        "branch": "main",
        "author_name": "Alice Developer",
        "author_email": "alice@example.com",
        "commit_timestamp": "2025-10-28T18:43:27Z",
        "commit_message": "Refactor authentication module",
        "tags": ["v2.1.0"]
      }
    }
  ]
}

Quality Archaeology Workflows

Find Quality Regressions

# Find commits where quality dropped below B+
pmat tdg history --since HEAD~50 --format json | \
  jq '.history[] | select(.score.grade | test("C|D|F"))'

Compare Quality Between Releases

# Quality delta between releases
pmat tdg history --range v2.177.0..v2.178.0

# Focus on specific file
pmat tdg history --path src/auth.rs --range v1.0.0..v2.0.0

Track Per-File Quality Trends

# See how a file's quality evolved
pmat tdg history --path src/database.rs --since HEAD~20

# Export for visualization
pmat tdg history --path src/api.rs --since HEAD~50 --format json > quality-trend.json

CI/CD Quality Gates

#!/bin/bash
# quality-gate.sh - Block commits that degrade quality

# Analyze current commit
pmat tdg src/ --with-git-context

# Get previous commit's quality
PREV_GRADE=$(pmat tdg history --commit HEAD~1 --format json | jq -r '.history[0].score.grade')

# Get current quality
CURR_GRADE=$(pmat tdg history --commit HEAD --format json | jq -r '.history[0].score.grade')

if [[ "$CURR_GRADE" < "$PREV_GRADE" ]]; then
  echo "❌ Quality regression detected: $PREV_GRADE → $CURR_GRADE"
  exit 1
fi

echo "✅ Quality maintained or improved"

Use Cases

1. Quality Attribution

Track which developer commits affected code quality:

# Find author of quality regression
pmat tdg history --since HEAD~20 --format json | \
  jq '.history[] | select(.score.total < 80) | .git_context.author_name'

2. Release Quality Reports

Generate quality reports for releases:

# Quality summary between releases
pmat tdg history --range v2.0.0..v2.1.0 --format json | \
  jq '{
    files: .history | length,
    avg_score: (.history | map(.score.total) | add / length),
    grades: (.history | group_by(.score.grade) |
      map({grade: .[0].score.grade, count: length}))
  }'

3. Hotspot Analysis

Identify files with frequent quality issues:

# Files with most quality fluctuation
pmat tdg history --since HEAD~100 --format json | \
  jq -r '.history[] | .file_path' | sort | uniq -c | sort -rn | head -10

Best Practices

1. Regular Analysis

# Analyze on every commit (git hook)
cat > .git/hooks/post-commit << 'EOF'
#!/bin/bash
pmat tdg . --with-git-context
EOF
chmod +x .git/hooks/post-commit

2. Baseline Establishment

# Create baseline at release
git tag v1.0.0
pmat tdg . --with-git-context

# Compare future changes
pmat tdg history --range v1.0.0..HEAD

3. Storage Location

• Git context stored in ~/.pmat/tdg-warm/ (recent)
• Archived to ~/.pmat/tdg-cold/ after 30 days
• Use --storage-path to customize location

Limitations

• Git context only stored when using --with-git-context flag
• History queries only show files analyzed with git context
• Storage grows with analysis frequency (~100 bytes per file per commit)
• Requires git repository (returns None for non-git directories)

MCP Integration

Git-commit correlation works seamlessly with MCP:

{
  "tool": "analyze.tdg",
  "arguments": {
    "paths": ["src/lib.rs"],
    "with_git_context": true
  }
}

Query history via MCP:

{
  "tool": "tdg.history",
  "arguments": {
    "commit": "HEAD",
    "format": "json"
  }
}

Summary

Technical Debt Grading provides:

• Comprehensive Assessment: Five orthogonal metrics for complete picture
• Actionable Insights: Specific recommendations for improvement
• Grade System: Easy communication with stakeholders
• Enterprise Features: Scalable to large codebases
• CI/CD Integration: Automated quality gates
• Trend Analysis: Track improvement over time

TDG transforms code quality from abstract concept to measurable, manageable metric.

Next Steps

• Chapter 4.2: Code Similarity Detection
• Chapter 4.3: Multi-Language Support
• Chapter 5: CLI Mastery

Chapter 4.2: TDG Enforcement System

Chapter Status: ✅ 100% Working (v2.180.1)

Last updated: 2025-10-29 PMAT version: pmat 2.213.1 Test-Driven: Validated through Sprint 67 dogfooding on PMAT codebase New in v2.180.0: Zero-regression quality enforcement system

Introduction

The TDG Enforcement System provides automated zero-regression quality guarantees for your codebase. Introduced in v2.180.0 and validated through Sprint 67 dogfooding, this system ensures that code quality never degrades through baseline tracking, quality gates, git hooks, and CI/CD integration.

Key Capabilities:

• Baseline Tracking: Snapshot your codebase quality at any point in time
• Regression Detection: Automatically detect quality degradations
• Quality Gates: Enforce minimum quality standards for new code
• Git Hooks: Pre-commit and post-commit quality checks
• CI/CD Integration: Automated enforcement in GitHub Actions, GitLab CI, Jenkins
• Zero-Regression Enforcement: Block commits/PRs that degrade quality

Sprint 67 Results (PMAT Dogfooding):

• 851 files analyzed across PMAT codebase
• 93.0 average score (A grade)
• 83.9% of files score A- or higher
• < 10 minutes to create baseline
• < 5 seconds per pre-commit check

Core Concepts

1. Quality Baselines

A baseline is a snapshot of your codebase’s quality at a specific point in time. Baselines use Blake3 content-hash deduplication for efficient storage and fast comparisons.

Baseline Structure:

{
  "metadata": {
    "created_at": "2025-10-29T12:00:00Z",
    "pmat_version": "2.180.1",
    "total_files": 851,
    "avg_score": 93.0
  },
  "summary": {
    "grade_distribution": {
      "APLus": 409,
      "A": 305,
      "AMinus": 37,
      "BPlus": 41,
      "B": 38,
      "BMinus": 16,
      "CPlus": 4,
      "C": 1
    },
    "languages": {
      "Rust": 848,
      "JavaScript": 1,
      "TypeScript": 1,
      "Python": 1
    }
  },
  "files": [
    {
      "path": "server/src/lib.rs",
      "content_hash": "blake3:a1b2c3d4...",
      "score": 95.5,
      "grade": "A+",
      "language": "Rust"
    }
    // ... 850 more files
  ]
}

2. Quality Gates

Quality Gates enforce minimum standards:

1. RegressionGate: Prevents quality score drops

   • Configurable threshold (e.g., max 5-point drop)
   • Detects degradation via baseline comparison

2. MinimumGradeGate: Enforces minimum quality for new code

   • Language-specific thresholds (e.g., Rust: B+, Python: A)
   • Blocks commits below threshold

3. NewFileGate: Special handling for new files

   • Stricter standards for greenfield code
   • Encourages quality from day one

3. Enforcement Modes

Strict Mode (Production):

• Blocks commits/PRs that violate gates
• Exit code 1 on violation
• Used in CI/CD and git hooks

Warning Mode (Learning):

• Shows violations but allows commits
• Exit code 0 (success)
• Used during team adjustment period

Disabled Mode:

• No enforcement
• Analysis only

Quick Start

Step 1: Create Initial Baseline

cd /path/to/your/project
pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/

# Optionally label the baseline (v3.18.1+; round-trips through save/load,
# shown in `tdg baseline list --format json`, preserved by `baseline update`)
pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/ --name pre-refactor

Expected Output:

✅ Baseline created successfully!
   Files analyzed: 247
   Average score: 91.5
   Grade distribution:
     A+ : 45 files (18.2%)
     A  : 82 files (33.2%)
     B+ : 67 files (27.1%)
     B  : 35 files (14.2%)
     C  : 12 files (4.9%)
     D  :  4 files (1.6%)
     F  :  2 files (0.8%)

   Baseline saved to: .pmat/tdg-baseline.json

Performance:

• Small projects (< 100 files): < 1 minute
• Medium projects (100-500 files): 1-5 minutes
• Large projects (500-2000 files): 5-15 minutes
• PMAT-scale (851 files): ~10 minutes

Concurrency & determinism (v3.18.1+):

• Baseline JSON is deterministic — files, grade_distribution, and languages serialize with sorted keys, so two runs on the same tree are byte-identical modulo created_at. Pre-3.18.1 baselines load unchanged.
• baseline create/update writes are atomic (scratch-then-rename), so a concurrent reader never observes a partial baseline.
• check-regression, baseline compare, and check-quality use process-unique ephemeral paths; concurrent pmat invocations on one machine no longer overwrite each other’s in-flight comparison state.
• (v3.18.2+) --format json stdout is exactly one jq-parseable document for baseline list, baseline compare, check-regression, and check-quality — decoration goes to stderr. check-quality emits a single combined {"gate": ..., "f_grade_gate": ..., "passed": ...} document (previously two concatenated documents when F-grade violations existed).

Step 2: Install Git Hooks

pmat hooks install --tdg-enforcement

What this installs:

• .git/hooks/pre-commit - Quality checks before commit
• .git/hooks/post-commit - Baseline auto-update (optional)
• .pmat/tdg-rules.toml - Configuration file

Pre-commit Hook Behavior:

1. Runs regression check (current vs baseline)
2. Runs quality check on staged files
3. Blocks commit if violations found (strict mode)
4. Shows warnings but allows commit (warning mode)

Step 3: Configure Quality Thresholds

Edit .pmat/tdg-rules.toml:

[quality_gates]
# Minimum grade for new code (A+, A, A-, B+, B, B-, C+, C, D, F)
rust_min_grade = "B+"
python_min_grade = "A"
javascript_min_grade = "B+"
typescript_min_grade = "A-"

# Maximum allowed score drop (0.0 = no regressions allowed)
max_score_drop = 5.0

# Enforcement mode: "strict", "warning", "disabled"
mode = "warning"  # Start in warning mode

[baseline]
# Path to baseline file
baseline_path = ".pmat/tdg-baseline.json"

# Auto-update baseline on main branch commits
auto_update_on_main = true

# Retention policy
retention_days = 90

Recommended Thresholds:

• Strict Projects: min_grade = "A", max_score_drop = 3.0
• Balanced Projects: min_grade = "B+", max_score_drop = 5.0
• Legacy Projects: min_grade = "B", max_score_drop = 7.0

Step 4: Test the System

# Check for regressions against baseline
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path .

# Expected output (no regressions):
✅ No quality regressions detected
   Files analyzed: 247
   Unchanged: 247
   Improved: 0
   Regressed: 0

# Analyze specific files
pmat tdg src/new_feature.rs --baseline .pmat/tdg-baseline.json

# Expected output (new file):
📊 TDG Analysis
   File: src/new_feature.rs
   Score: 92.0
   Grade: A
   Status: NEW FILE ✨

   Quality Gate: ✅ PASS (exceeds B+ minimum)

Git Hook Integration

Pre-commit Hook

The pre-commit hook runs two checks:

1. Regression Check:

# Compares current state vs baseline
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path .

2. Quality Check:

# Checks staged files meet minimum grade
pmat tdg check-quality --files $(git diff --cached --name-only)

Example Output (Warning Mode):

⚠️  Quality Gate Warnings:

   File: src/utils/helper.rs
   Current Grade: B (Score: 82.0)
   Required Grade: B+ (Score: 85.0+)
   Gap: -3.0 points

   File: src/api/handler.rs
   Regression Detected: -6.2 points
   Previous: A (92.5) → Current: B+ (86.3)
   Max Allowed Drop: 5.0 points

   Mode: WARNING (commit allowed)
   To enforce: Set mode = "strict" in .pmat/tdg-rules.toml

Example Output (Strict Mode):

❌ Quality Gate Failed!

   src/utils/helper.rs: B (82.0) < B+ (85.0) required
   src/api/handler.rs: Regression -6.2 > -5.0 threshold

   Commit blocked. Fix quality issues or use:
   git commit --no-verify (NOT RECOMMENDED)

Post-commit Hook

The post-commit hook optionally updates the baseline:

# Update baseline after successful commit (main branch only)
if [[ $(git branch --show-current) == "main" ]]; then
  pmat tdg baseline update --baseline .pmat/tdg-baseline.json --path .
fi

Behavior:

• Only runs on main/master branch (configurable)
• Incremental update (only changed files re-analyzed)
• Keeps baseline synchronized with codebase

Hook Bypass (Emergency Only)

# Bypass pre-commit hook (NOT RECOMMENDED)
git commit --no-verify -m "Emergency hotfix"

# Then fix quality issues immediately:
pmat tdg src/emergency_fix.rs
# Refactor to meet standards
git add src/emergency_fix.rs
git commit -m "refactor: Fix quality issues in emergency hotfix"

CI/CD Integration

GitHub Actions

Create .github/workflows/tdg-quality.yml:

name: TDG Quality Enforcement

on:
  pull_request:
    branches: [main, master]
  push:
    branches: [main, master]

jobs:
  tdg-enforcement:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for baseline comparison

      - name: Install PMAT
        run: |
          cargo install pmat --version 2.180.1
          pmat --version

      - name: Load baseline
        run: |
          # Baseline should be committed to repo
          if [[ ! -f .pmat/tdg-baseline.json ]]; then
            echo "❌ No baseline found. Run: pmat tdg baseline create"
            exit 1
          fi

      - name: Check for regressions
        run: |
          pmat tdg check-regression \
            --baseline .pmat/tdg-baseline.json \
            --path . \
            --fail-on-regression

      - name: Check new file quality
        run: |
          # Get changed files
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

          if [[ -n "$CHANGED_FILES" ]]; then
            pmat tdg check-quality \
              --files $CHANGED_FILES \
              --min-grade B+ \
              --fail-on-violation
          fi

      - name: Generate quality report
        if: github.event_name == 'pull_request'
        run: |
          pmat tdg . \
            --include-components \
            --format markdown > tdg-report.md

      - name: Comment PR with results
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('tdg-report.md', 'utf8');

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 📊 TDG Quality Report\n\n${report}`
            });

      - name: Update baseline (main branch only)
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: |
          pmat tdg baseline update \
            --baseline .pmat/tdg-baseline.json \
            --path .

          # Commit updated baseline
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add .pmat/tdg-baseline.json
          git commit -m "chore: Update TDG baseline [skip ci]" || true
          git push

Example PR Comment:

## 📊 TDG Quality Report

✅ No regressions detected
✅ All new files meet B+ minimum

### Files Analyzed: 5

| File | Score | Grade | Status |
|------|-------|-------|--------|
| src/parser/new_feature.rs | 94.0 | A | NEW ✨ |
| src/lib.rs | 95.5 | A+ | UNCHANGED |
| src/utils/helper.rs | 87.0 | B+ | IMPROVED (+2.5) |
| tests/integration_test.rs | 98.0 | A+ | NEW ✨ |
| README.md | - | - | SKIPPED (doc) |

### Summary
- **Average Score**: 93.6 (A grade)
- **Grade Distribution**: 3× A+, 1× A, 1× B+
- **Quality Gate**: ✅ PASS

GitLab CI

Create .gitlab-ci.yml:

stages:
  - quality

tdg-enforcement:
  stage: quality
  image: rust:latest

  before_script:
    - cargo install pmat --version 2.180.1

  script:
    # Regression check
    - pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path . --fail-on-regression

    # Quality check on changed files
    - |
      CHANGED_FILES=$(git diff --name-only $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD)
      if [[ -n "$CHANGED_FILES" ]]; then
        pmat tdg check-quality --files $CHANGED_FILES --min-grade B+ --fail-on-violation
      fi

  artifacts:
    reports:
      junit: tdg-report.xml

  only:
    - merge_requests
    - main

Jenkins Pipeline

Create Jenkinsfile:

pipeline {
  agent any

  stages {
    stage('TDG Enforcement') {
      steps {
        sh 'cargo install pmat --version 2.180.1'

        sh '''
          pmat tdg check-regression \
            --baseline .pmat/tdg-baseline.json \
            --path . \
            --fail-on-regression
        '''

        script {
          def changedFiles = sh(
            script: 'git diff --name-only origin/main...HEAD',
            returnStdout: true
          ).trim()

          if (changedFiles) {
            sh """
              pmat tdg check-quality \
                --files ${changedFiles} \
                --min-grade B+ \
                --fail-on-violation
            """
          }
        }
      }
    }
  }

  post {
    always {
      archiveArtifacts artifacts: 'tdg-report.json', allowEmptyArchive: true
    }
  }
}

Baseline Management

Creating Baselines

# Create initial baseline
pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/

# Create baseline for specific languages
pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/ --languages rust,python

# Create baseline with custom config
pmat tdg baseline create \
  --output .pmat/tdg-baseline.json \
  --path src/ \
  --config .pmat/tdg-rules.toml

# Create baseline and commit to git
pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/
git add .pmat/tdg-baseline.json
git commit -m "chore: Create TDG quality baseline"
git push

Updating Baselines

# Incremental update (only changed files)
pmat tdg baseline update --baseline .pmat/tdg-baseline.json --path .

# Full re-analysis (all files)
pmat tdg baseline update --baseline .pmat/tdg-baseline.json --path . --full

# Update specific files
pmat tdg baseline update \
  --baseline .pmat/tdg-baseline.json \
  --files src/lib.rs src/parser.rs

Comparing Baselines

# Compare current state vs baseline
pmat tdg baseline compare \
  --baseline .pmat/tdg-baseline.json \
  --path . \
  --format table

# Output:
╭──────────────────────────────────────────────────────────────╮
│  Baseline Comparison                                         │
├──────────────────────────────────────────────────────────────┤
│  Files analyzed: 247                                         │
│  Unchanged: 240 (97.2%)                                      │
│  Improved: 5 (2.0%)                                          │
│  Regressed: 2 (0.8%)                                         │
│                                                              │
│  Regressed Files:                                            │
│    src/api/handler.rs: A (92.5) → B+ (86.3) [-6.2]          │
│    src/utils/helper.rs: B+ (85.5) → B (82.0) [-3.5]         │
│                                                              │
│  Improved Files:                                             │
│    src/parser/lexer.rs: B (80.0) → B+ (88.0) [+8.0]         │
│    src/ast/visitor.rs: B+ (87.0) → A (91.5) [+4.5]          │
│    src/lib.rs: A (93.0) → A+ (96.0) [+3.0]                  │
╰──────────────────────────────────────────────────────────────╯

# Compare two baselines
pmat tdg baseline compare \
  --baseline1 .pmat/tdg-baseline-v1.json \
  --baseline2 .pmat/tdg-baseline-v2.json

# JSON output for automation
pmat tdg baseline compare \
  --baseline .pmat/tdg-baseline.json \
  --path . \
  --format json > comparison.json

Baseline Archaeology

# Track quality over time via git history
git log --all --oneline --format="%H %s" -- .pmat/tdg-baseline.json

# Checkout baseline from specific release
git show v2.0.0:.pmat/tdg-baseline.json > baseline-v2.0.0.json

# Compare releases
pmat tdg baseline compare \
  --baseline1 baseline-v1.0.0.json \
  --baseline2 baseline-v2.0.0.json

Regression Detection

Automatic Regression Detection

# Check for any regressions
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path .

# Strict mode (fail on any regression)
pmat tdg check-regression \
  --baseline .pmat/tdg-baseline.json \
  --path . \
  --fail-on-regression

# Custom threshold
pmat tdg check-regression \
  --baseline .pmat/tdg-baseline.json \
  --path . \
  --max-drop 3.0  # Fail if > 3 point drop

Regression Analysis

# Detailed regression report
pmat tdg check-regression \
  --baseline .pmat/tdg-baseline.json \
  --path . \
  --verbose \
  --format json

# Output:
{
  "summary": {
    "total_files": 247,
    "unchanged": 240,
    "improved": 5,
    "regressed": 2,
    "regression_rate": 0.8
  },
  "regressions": [
    {
      "file": "src/api/handler.rs",
      "baseline_score": 92.5,
      "current_score": 86.3,
      "delta": -6.2,
      "baseline_grade": "A",
      "current_grade": "B+",
      "severity": "critical"
    }
  ],
  "improvements": [
    {
      "file": "src/parser/lexer.rs",
      "baseline_score": 80.0,
      "current_score": 88.0,
      "delta": 8.0,
      "baseline_grade": "B",
      "current_grade": "B+"
    }
  ]
}

Regression Root Cause Analysis

# Analyze why a file regressed
pmat tdg src/api/handler.rs --include-components --verbose

# Output shows component breakdown:
File: src/api/handler.rs
  TDG Score: 86.3 (B+) [was 92.5 A]

  Component Breakdown:
    Complexity: 25.0 [was 18.5] ⚠️ +6.5 points
      - Cyclomatic: 42 [was 28] ⚠️
      - Cognitive: 58 [was 35] ⚠️
      - Nesting: 6 [was 4] ⚠️

    Churn: 12.0 [was 15.0] ✅ -3.0 points
      - Changes (30d): 8 [was 12] ✅

    Coupling: 8.0 [was 8.0] → No change
    Duplication: 5.3 [was 5.0] → Minimal change
    Domain Risk: 2.0 [was 2.0] → No change

  Root Cause: Increased complexity (+6.5 points)

  Recommendations:
    1. Refactor nested conditional logic (reduce nesting 6 → 4)
    2. Extract complex validation to separate functions
    3. Simplify error handling paths

Quality Gate Configuration

Language-Specific Thresholds

# .pmat/tdg-rules.toml
[quality_gates]
# Different standards for different languages
rust_min_grade = "A"      # Rust is strict
python_min_grade = "B+"   # Python moderate
javascript_min_grade = "B+"
typescript_min_grade = "A-"
c_min_grade = "B"
cpp_min_grade = "B"

# Global fallback
default_min_grade = "B+"

Module-Specific Thresholds (Planned)

# Future feature (not yet implemented)
[quality_gates.modules]
"src/core/**" = { min_grade = "A+", max_drop = 2.0 }
"src/api/**" = { min_grade = "A", max_drop = 5.0 }
"src/utils/**" = { min_grade = "B+", max_drop = 7.0 }
"tests/**" = { min_grade = "B", max_drop = 10.0 }

Grace Periods

[quality_gates]
# Allow temporary violations during refactoring
grace_period_days = 7

# Grace period tracking
[grace_periods]
"src/legacy/old_module.rs" = { expires = "2025-11-05", reason = "Refactoring in progress" }

Real-World Examples

Example 1: Sprint 67 - PMAT Dogfooding

Scenario: Apply TDG enforcement to PMAT itself

# Step 1: Create baseline
cd ~/src/paiml-mcp-agent-toolkit
pmat tdg baseline create --output .pmat/tdg-baseline.json --path server/src

# Result: 851 files, avg 93.0 (A grade)

# Step 2: Install hooks
pmat hooks install --tdg-enforcement

# Step 3: Configure (warning mode initially)
cat > .pmat/tdg-rules.toml << EOF
[quality_gates]
rust_min_grade = "B+"
max_score_drop = 5.0
mode = "warning"

[baseline]
baseline_path = ".pmat/tdg-baseline.json"
auto_update_on_main = true
EOF

# Step 4: Test regression check
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path .

# Result: ✅ No regressions (851 files unchanged)

Outcome:

• Found critical v2.180.0 bug during dogfooding
• Fixed and released v2.180.1 within 4 hours
• Validated system works on real-world codebase
• Created reference implementation for users

Example 2: Open Source Project Integration

Scenario: Add TDG enforcement to open source Rust project

# 1. Create baseline at release tag
git checkout v1.0.0
pmat tdg baseline create --output .pmat/tdg-baseline-v1.0.0.json --path src/
git checkout main

# 2. Install hooks (warning mode for contributors)
pmat hooks install --tdg-enforcement

# 3. Configure for open source (permissive)
cat > .pmat/tdg-rules.toml << EOF
[quality_gates]
rust_min_grade = "B"      # Permissive for contributors
max_score_drop = 10.0     # Allow some flexibility
mode = "warning"          # Don't block contributors

[baseline]
baseline_path = ".pmat/tdg-baseline-v1.0.0.json"
auto_update_on_main = false  # Manual baseline updates
EOF

# 4. Add GitHub Actions (strict for maintainers)
# .github/workflows/tdg-quality.yml
# (see CI/CD Integration section above)

# 5. Document in CONTRIBUTING.md
cat >> CONTRIBUTING.md << EOF

## Code Quality Standards

This project uses PMAT TDG enforcement to maintain code quality:

- Minimum grade for new code: B
- Please run 'pmat tdg <file>' before submitting PR
- CI will check for quality regressions
- See .pmat/tdg-rules.toml for configuration
EOF

# 6. Commit configuration
git add .pmat/ .github/workflows/tdg-quality.yml CONTRIBUTING.md
git commit -m "chore: Add TDG quality enforcement"
git push

Example 3: Enterprise Microservices

Scenario: Enforce quality across 20 microservices

# 1. Create shared quality standard
# shared-quality-standard.toml (in shared repo)
cat > shared-quality-standard.toml << EOF
[quality_gates]
rust_min_grade = "A"
python_min_grade = "A-"
max_score_drop = 3.0
mode = "strict"

[quality_gates.modules]
# Critical services get stricter standards
"services/auth/**" = { min_grade = "A+", max_drop = 2.0 }
"services/payment/**" = { min_grade = "A+", max_drop = 2.0 }
"services/user-data/**" = { min_grade = "A", max_drop = 3.0 }

# Supporting services more flexible
"services/notification/**" = { min_grade = "B+", max_drop = 5.0 }
"services/analytics/**" = { min_grade = "B", max_drop = 7.0 }
EOF

# 2. Deploy to each microservice
for service in services/*; do
  cd $service

  # Copy shared standard
  cp ../../shared-quality-standard.toml .pmat/tdg-rules.toml

  # Create baseline
  pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/

  # Install hooks
  pmat hooks install --tdg-enforcement

  # Commit
  git add .pmat/
  git commit -m "chore: Add TDG enforcement"
  git push

  cd ../..
done

# 3. Monitor quality across all services
# quality-dashboard.sh
for service in services/*; do
  echo "=== $service ==="
  cd $service
  pmat tdg baseline compare --baseline .pmat/tdg-baseline.json --path . --format table
  cd ../..
done

Best Practices

1. Establish Baseline at Stable Points

# Create baseline at releases
git tag v1.0.0
pmat tdg baseline create --output .pmat/tdg-baseline-v1.0.0.json --path src/
git add .pmat/tdg-baseline-v1.0.0.json
git commit -m "chore: TDG baseline for v1.0.0"

# Update baseline periodically (e.g., monthly)
pmat tdg baseline update --baseline .pmat/tdg-baseline.json --path . --full
git add .pmat/tdg-baseline.json
git commit -m "chore: Monthly TDG baseline update"

2. Start with Warning Mode

[quality_gates]
mode = "warning"  # Week 1-2: Learning phase

After 2-4 weeks:

[quality_gates]
mode = "strict"  # Production enforcement

3. Gradual Threshold Tightening

Phase 1 (Weeks 1-4):

rust_min_grade = "C+"  # Very permissive
max_score_drop = 15.0

Phase 2 (Weeks 5-8):

rust_min_grade = "B"   # Moderate
max_score_drop = 10.0

Phase 3 (Week 9+):

rust_min_grade = "B+"  # Production standard
max_score_drop = 5.0

4. Commit Baselines to Git

# Baselines should be version controlled
git add .pmat/tdg-baseline.json
git commit -m "chore: Update TDG baseline"

# Tag baselines at releases
git tag -a v1.0.0-baseline -m "Quality baseline for v1.0.0"
git push --tags

5. Document Quality Standards

# QUALITY.md

## Code Quality Standards

This project maintains quality via PMAT TDG enforcement:

- **Minimum Grade**: B+ for all new code
- **Regression Tolerance**: Maximum 5-point drop
- **Enforcement**: Strict mode in CI/CD, warning mode locally
- **Baseline**: Updated monthly or at major releases

### Running Quality Checks

```bash
# Check your changes
pmat tdg <file> --baseline .pmat/tdg-baseline.json

# Check for regressions
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path .

Quality Gate Failures

If CI fails due to quality gate:

1. Run pmat tdg <file> --verbose to see what’s wrong
2. Refactor to improve quality (extract functions, reduce complexity)
3. Re-run checks until passing
4. If needed, discuss with team (grace period possible)

---

## Troubleshooting

### Issue: Baseline Creation Fails

**Symptom**: `pmat tdg baseline create` fails with error

**Diagnosis**:
```bash
# Check path exists
ls -la src/

# Run with verbose logging
pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/ --verbose

# Check for permissions
ls -la .pmat/

Solution:

# Create .pmat directory if missing
mkdir -p .pmat

# Ensure write permissions
chmod 755 .pmat

Issue: Pre-commit Hook Blocks Legitimate Commits

Symptom: Hook blocks commit even though quality is acceptable

Diagnosis:

# Check what's failing
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path . --verbose

# Check configuration
cat .pmat/tdg-rules.toml

Solution:

# Option 1: Adjust thresholds in .pmat/tdg-rules.toml
max_score_drop = 7.0  # Increase from 5.0

# Option 2: Switch to warning mode temporarily
mode = "warning"

# Option 3: Emergency bypass (NOT RECOMMENDED)
git commit --no-verify

Issue: False Positive Regressions

Symptom: Files marked as regressed but no functional changes

Diagnosis:

# Check file hash
pmat tdg src/file.rs --include-hash

# Compare with baseline
jq '.files[] | select(.path == "src/file.rs")' .pmat/tdg-baseline.json

Solution:

# Update baseline to include recent improvements
pmat tdg baseline update --baseline .pmat/tdg-baseline.json --path .

# Or increase sensitivity threshold
max_score_drop = 7.0

Issue: CI/CD Performance Slow

Symptom: TDG analysis takes too long in CI/CD

Diagnosis:

# Time the analysis
time pmat tdg baseline create --output test.json --path src/

Solution:

# 1. Use incremental analysis
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path . --incremental

# 2. Analyze only changed files in CI
CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
pmat tdg check-quality --files $CHANGED_FILES

# 3. Cache PMAT installation in CI
# (see CI/CD Integration section for caching examples)

# 4. Use parallel analysis (automatic in v2.180.1)

Performance Characteristics

Baseline Creation

Regression Checks

Storage Requirements

Optimization: Baselines use Blake3 content-hash deduplication, so identical files are stored once.

Migration Guide

Migrating from No Enforcement

Week 1: Establish Baseline

pmat tdg baseline create --output .pmat/tdg-baseline.json --path src/
git add .pmat/tdg-baseline.json
git commit -m "chore: Establish TDG quality baseline"

Week 2: Install Hooks (Warning Mode)

pmat hooks install --tdg-enforcement
# Edit .pmat/tdg-rules.toml: mode = "warning"
git add .pmat/ .git/hooks/
git commit -m "chore: Add TDG hooks in warning mode"

Week 3: Add CI/CD (Warning Mode)

# Copy GitHub Actions template
# Set mode = "warning" in workflow
git add .github/workflows/tdg-quality.yml
git commit -m "chore: Add TDG CI/CD in warning mode"

Week 4: Review Results, Adjust Thresholds

# Analyze violations
pmat tdg check-regression --baseline .pmat/tdg-baseline.json --path . --verbose

# Adjust thresholds if needed
# Update .pmat/tdg-rules.toml

Week 5+: Enable Strict Mode

# Edit .pmat/tdg-rules.toml: mode = "strict"
git add .pmat/tdg-rules.toml
git commit -m "chore: Enable strict TDG enforcement"

Migrating Between PMAT Versions

# Backup old baseline
cp .pmat/tdg-baseline.json .pmat/tdg-baseline-backup.json

# Re-create baseline with new version
pmat tdg baseline create --output .pmat/tdg-baseline-new.json --path src/

# Compare results
pmat tdg baseline compare \
  --baseline1 .pmat/tdg-baseline-backup.json \
  --baseline2 .pmat/tdg-baseline-new.json

# If acceptable, replace baseline
mv .pmat/tdg-baseline-new.json .pmat/tdg-baseline.json
git add .pmat/tdg-baseline.json
git commit -m "chore: Update baseline for PMAT v2.180.1"

Summary

The TDG Enforcement System provides:

✅ Zero-Regression Guarantees: Prevent quality degradation automatically ✅ Baseline Tracking: Quality archaeology via git-versioned baselines ✅ Git Hook Integration: Catch quality issues before they enter the repo ✅ CI/CD Enforcement: Automated quality gates in GitHub Actions, GitLab CI, Jenkins ✅ Configurable Thresholds: Language-specific and module-specific standards ✅ Performance: Sub-second regression checks, minute-scale baseline creation ✅ Battle-Tested: Validated through Sprint 67 dogfooding on PMAT itself (851 files, 93.0 avg score)

Recommendation: Start with warning mode for 2-4 weeks, then enable strict enforcement. Your future self will thank you.

Next Steps

• Chapter 5: The Analyze Command Suite
• Chapter 7: Quality Gates
• Chapter 9: Pre-commit Hooks Management

Chapter Status: ✅ Ready for Production (v2.180.1) Last Updated: 2025-10-29 Validated: Sprint 67 Dogfooding (851 files, 93.0 avg score)

Chapter 5: The Analyze Command Suite

Chapter Status: ✅ 100% Working (8/8 examples)

Last updated: 2026-03-08 PMAT version: pmat 3.6.1 Test-Driven: All examples validated in tests/ch05/test_analyze.sh

Comprehensive Code Analysis

The pmat analyze command suite provides deep insights into your codebase through multiple specialized analyzers. Each analyzer focuses on a specific aspect of code quality, helping you maintain high standards and identify improvement opportunities.

Basic Analysis

pmat analyze is a parent command: on its own it has nothing to run, and pmat analyze . fails with error: unrecognized subcommand. The subcommand that runs every analyser at once is comprehensive, and it takes the project path through -p/--path, never as a positional argument:

# Analyze current directory (--path defaults to `.`, so this is the short form)
pmat analyze comprehensive

# Analyze specific directory
pmat analyze comprehensive -p src/

# Analyze with detailed output
pmat analyze comprehensive -p . --format detailed

# Save analysis to file
pmat analyze comprehensive -p . --output analysis-report.txt

pmat analyze --help lists the other thirty-odd subcommands; the rest of this chapter walks the ones you will reach for most.

Example Output

Run against a four-file Python/JavaScript project with one deliberately gnarly function and three TODO/FIXME/HACK comments, pmat analyze comprehensive -p . prints this (progress lines on stderr, report on stdout):

🔍 Running comprehensive analysis...
Warning: dead_code analysis failed: Cargo check failed: error: could not find `Cargo.toml` in /path/to/project

ℹ️  Duplicate detection is not part of comprehensive analysis; run `pmat analyze duplicates` for clone results.
🐛 Predicting defects...
✓ Comprehensive analysis completed
Comprehensive Code Analysis Report

Executive Summary

  Project analysis completed with 4 total files analyzed.

  Quality Score: 90.0%
  Total Files:   4
  Total Issues:  4
  Critical:      4

  Key Recommendations

    - Consider refactoring high-complexity functions
    - Address technical debt items (TODO/FIXME comments)

Complexity Analysis

  Files Analyzed:     4
  Average Complexity: 4.3
  Max Complexity:     39
  Violations:         1

  Top Complexity Violations

    1. ./src/payment_processor.py - process (complexity: 39)

Technical Debt (SATD) Analysis

  Files Analyzed: 2
  Violations:     3

  SATD Violations

    1. ./src/payment_processor.py:1 - Requirement (Low)
    2. ./src/payment_processor.py:14 - Defect (High)
    3. ./web/app.js:1 - Design (Medium)

Two things in that transcript are worth reading carefully rather than skipping:

• Dead-code analysis is Rust-only. On a non-Cargo project it does not silently report zero — it says why it could not run. A metric that reads 0 because it never executed is worse than no metric at all.
• Duplicate detection is not included. comprehensive says so on stderr and points you at pmat analyze duplicates, which is a separate pass.

Complexity Analysis

Measure and track code complexity to maintain readability:

# Basic complexity analysis
pmat analyze complexity

# Set thresholds (there is no --threshold; there are two, one per metric)
pmat analyze complexity --max-cyclomatic 10
pmat analyze complexity --max-cognitive 15

# Analyze a specific directory (path goes through -p/--path, never positionally)
pmat analyze complexity -p src/

# Analyze one file
pmat analyze complexity --file src/parser.rs

# Output formats: summary (default), full, json, sarif. There is no csv.
pmat analyze complexity --format json

# CI/CD mode
pmat analyze complexity --max-cyclomatic 5 --fail-on-violation

The full option list is -p/--path, --file, --files, --toolchain, --format <summary|full|json|sarif>, -o/--output, --max-cyclomatic, --max-cognitive, --include, --watch, --top-files, --fail-on-violation, --timeout and --ml. Note the three that earlier editions of this chapter used and that do not exist: --threshold, --detailed and --cognitive. Cognitive complexity is always computed; it is a column, not a mode.

--ml is not implemented

The flag parses, and refuses to pretend:

pmat analyze complexity --ml

Error: --ml is not implemented: complexity scores are still computed by the heuristic formulas, so this flag would relabel them without changing them. Re-run `analyze complexity` without --ml (see GH-97).

Exit code 1. Its --help entry reads NOT IMPLEMENTED: ML-based scoring (aprender LinearRegression). There is no ML scoring in pmat 3.32.0, and the “Benefits” list an earlier edition of this chapter attached to it described a model that never ran.

Understanding Complexity Metrics

Run against a four-file Rust crate whose src/parser.rs holds one deliberately branchy function:

pmat analyze complexity

⏰ Analysis timeout set to 300 seconds
🔍 Analyzing rust project complexity (all languages)...
✅ Successfully analyzed 4 file(s)
   1 of 5 file(s) were not analyzed
   no complexity analyzer for: .toml (1)
Complexity Analysis Summary

  Files analyzed: 4
  Total functions: 8

Complexity Metrics

  Median Cyclomatic: 1.5
  Median Cognitive: 0.5
  Max Cyclomatic: 9
  Max Cognitive: 13
  90th Percentile Cyclomatic: 9
  90th Percentile Cognitive: 13

Top Files by Complexity

  1. src/parser.rs - Cyclomatic: 16, Cognitive: 19, Functions: 4
  2. src/lib.rs - Cyclomatic: 2, Cognitive: 1, Functions: 1
  3. src/util.rs - Cyclomatic: 2, Cognitive: 0, Functions: 2
  4. src/main.rs - Cyclomatic: 1, Cognitive: 0, Functions: 1

Two things the header lines earn their place by saying: 4 of 5 files were analysed, and the fifth was Cargo.toml, for which there is no analyser. A tool that printed “4 files analyzed” alone would leave you unable to tell a skipped file from an absent one.

Note also that a file’s Cyclomatic (16 for parser.rs) is the sum over its functions, while Max Cyclomatic: 9 is the largest single function. Do not compare the two columns.

Per-function detail

--file expands one file into its functions:

pmat analyze complexity --file src/parser.rs

  1. src/parser.rs - Cyclomatic: 16, Cognitive: 19, Functions: 4

Functions in File

  1. depth (line 2-14) - Cyclomatic: 9, Cognitive: 13
  2. copy_a (line 16-16) - Cyclomatic: 3, Cognitive: 3
  3. copy_b (line 17-17) - Cyclomatic: 3, Cognitive: 3
  4. never_called (line 19-19) - Cyclomatic: 1, Cognitive: 0

Setting a threshold below the maximum turns the run into a gate:

pmat analyze complexity --max-cyclomatic 5 --fail-on-violation

Top Complexity Hotspots

  1. depth src/parser.rs:2 - cyclomatic complexity: 9


❌ Complexity violations found

Exit code 1.

Note: In the terminal, headers appear bold+underlined, labels are bold, numbers are bold white, and file paths are cyan. Use --format json for machine-readable output without colors.

Dead Code Detection

Identify and remove unused code to reduce maintenance burden:

# Find all dead code
pmat analyze dead-code

# Check a specific directory
pmat analyze dead-code -p src/

# Write the report to a file (there is no --export)
pmat analyze dead-code -o dead-code-list.txt

# Machine-readable
pmat analyze dead-code -f json

The option list is -p/--path, -f/--format <summary|json|sarif|markdown>, -t/--top-files, -u/--include-unreachable, --min-dead-lines, --include-tests, -o/--output, --fail-on-violation and --max-percentage (default 15.0). --export and --safe-only never existed; there is no safe-to-remove classification.

Dead Code Report

pmat analyze dead-code

☠️ Analyzing dead code in project...
⏰ Analysis timeout set to 900 seconds
📊 Analysis complete: 4 files analyzed, 1 with dead code
Dead Code Analysis Summary

  Files analyzed: 4
  Files with dead code: 1
  Total dead lines: 5
  Dead code percentage: 14.7%

  Library target: library — cargo: .../Cargo.toml declares package `analyzedemo`, which has a library target, and rustc's dead-code pass treats its public API as reachable

  Compiler scan: full (compiler-lint-ran) — cargo check ran against the existing lockfile; rustc's dead-code lint contributed to these findings

Dead Code by Type

  Dead functions: 1
  Dead classes: 0
  Dead modules: 0
  Other (fields, constants, statics): 0

The two prose lines in the middle are the ones to read before acting on this report. Library target: library means every pub item is treated as reachable, so a crate that exposes a large public API will show almost no dead code — pub fn unused_util in the fixture above is not counted, while the private fn never_called is. Compiler scan: full (compiler-lint-ran) means rustc’s own lint contributed; if it reads otherwise, the findings are heuristic only and weaker.

Gate on a percentage with --max-percentage:

pmat analyze dead-code --max-percentage 10 --fail-on-violation

SATD Analysis

Self-Admitted Technical Debt (SATD) tracks developer-annotated issues:

# Find all SATD markers
pmat analyze satd

# Extended mode - detect euphemisms (NEW in v2.217.0)
pmat analyze satd --extended

# Filter by severity (there is no --priority)
pmat analyze satd --severity high

# Only the critical items
pmat analyze satd --critical-only

# Add the metrics summary (there is no --report)
pmat analyze satd --metrics

# Write a report to a file
pmat analyze satd -f markdown -o satd.md

--categorize, --priority and --report never existed. Categorisation is unconditional — every violation is already labelled by type (Defect, Requirement, …) and severity in the default output.

Run against the same four-file crate:

pmat analyze satd

🔍 Analyzing Self-Admitted Technical Debt (SATD)...
SATD Analysis Summary

Found 2 SATD violations in 2 files (analysed 4 of 4 file(s) walked)

Total violations:  2
Scope:  analysed 4 of 4 file(s) walked

Severity Distribution
  Critical: 0
  High: 1
  Medium: 0
  Low: 1

Top Violations
  1. ./src/parser.rs:1 - Defect High
  2. ./src/lib.rs:4 - Requirement Low

analysed 4 of 4 file(s) walked is the line that makes the count trustworthy: it distinguishes “no debt” from “nothing was read”. Filtering narrows it:

pmat analyze satd --severity high

Found 1 SATD violations in 1 files (analysed 4 of 4 file(s) walked)

And --metrics appends a breakdown:

pmat analyze satd --metrics

📊 SATD Metrics:
  Total files analyzed: 2
  Total violations: 2
  Critical violations: 0
  High violations: 1

  Top violation types:
    - Requirement: 1
    - Defect: 1

Note that Total files analyzed: 2 in the metrics block counts files with violations, while the summary above it says 4 files were walked. The two numbers mean different things.

Extended Mode (Issue #149)

NEW in PMAT v2.217.0: The --extended flag detects euphemisms commonly used by AI coding assistants to bypass traditional SATD detection:

# Standard detection only (89 violations in the `pmat` source tree)
pmat analyze satd --path src/

# Extended detection (441 violations - catches 352 more hidden debt)
pmat analyze satd --extended --path src/

# CI/CD zero-tolerance with extended detection
pmat analyze satd --extended --strict --fail-on-violation

--evolution is not implemented

--evolution and --days parse and then refuse, rather than printing an empty trend:

Error: --evolution is not implemented for `analyze satd`: no debt history is computed, and --days selects nothing. Re-run without it.

Exit code 1. For debt over time, diff two pmat analyze satd -f json runs yourself.

The --extended --strict --fail-on-violation form above exits 1 when it finds anything, which is what you want in CI and is not an error in the command.

Defects Analysis (Known Defects v2.1)

NEW in PMAT v2.200.0: Detect production-breaking defect patterns with zero-tolerance enforcement.

Identify critical defects that cause production failures:

# Scan all Rust files for critical defects
pmat analyze defects

# Scan specific directory
pmat analyze defects -p src/

# Scan single file
pmat analyze defects --file src/main.rs

# Filter by severity
pmat analyze defects --severity Critical
pmat analyze defects --severity High

# Output formats
pmat analyze defects --format text      # Colored terminal (default)
pmat analyze defects --format json      # CI/CD integration
pmat analyze defects --format junit     # Test framework integration

Exit Codes

• 0: No critical defects found
• 1: Critical defects detected (triggers CI/CD failures)

Defect Report Example

🛡️ Known Defects Report - v2.1
══════════════════════════════

📊 Summary:
Total Defects: 249
Critical: 8
High: 42
Medium: 123
Low: 76

Affected Files: 37/152 (24.3%)

🔴 CRITICAL DEFECTS (8)

Pattern: .unwrap() calls
Severity: Critical
Evidence: Cloudflare outage 2025-11-18 (3+ hour global disruption)
Fix: Use .expect() with descriptive messages or ? operator

Instances:
  1. src/services/api.rs:142:18
     Code: let result = operation().unwrap();

  2. src/handlers/auth.rs:89:25
     Code: let token = parse_jwt(raw).unwrap();

  3. src/utils/config.rs:56:32
     Code: let config = load_config().unwrap();

Fix Recommendation:
Replace .unwrap() with explicit error handling:

  // ❌ BEFORE - Causes panic
  let result = operation().unwrap();

  // ✅ AFTER - Descriptive error
  let result = operation()
      .expect("Bot feature file must be valid");

  // ✅ AFTER - Propagate error
  let result = operation()?;

JSON Output (CI/CD Integration)

{
  "summary": {
    "total_defects": 249,
    "critical": 8,
    "high": 42,
    "medium": 123,
    "low": 76,
    "affected_files": 37,
    "total_files": 152
  },
  "patterns": [
    {
      "id": "RUST-UNWRAP-001",
      "name": ".unwrap() calls",
      "severity": "Critical",
      "fix_recommendation": "Use .expect() or ? operator",
      "evidence": {
        "description": "Cloudflare outage 2025-11-18",
        "url": "https://blog.cloudflare.com/2025-01-18-outage"
      },
      "instances": [
        {
          "file": "src/services/api.rs",
          "line": 142,
          "column": 18,
          "snippet": "let result = operation().unwrap();"
        }
      ]
    }
  ]
}

JUnit XML Output (Test Integration)

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="Known Defects Report" tests="1" failures="8">
  <testsuite name="RUST-UNWRAP-001" tests="8" failures="8">
    <testcase name="src/services/api.rs:142" classname="defects.critical">
      <failure message=".unwrap() call detected (Critical severity)">
File: src/services/api.rs
Line: 142
Column: 18
Code: let result = operation().unwrap();

Fix: Use .expect() with descriptive messages or ? operator
Evidence: Cloudflare outage 2025-11-18
      </failure>
    </testcase>
  </testsuite>
</testsuites>

Test Code Exclusion

Defect detection automatically excludes test code:

• tests/ directory
• benches/ directory
• #[cfg(test)] modules

Production code standards apply only to production code.

Integration with TDG

Critical defects trigger TDG auto-fail:

• Score: 0.0/100
• Grade: F
• Exit code: 1

See Chapter 4.1: Known Defects v2.1 for TDG integration details.

Integration with rust-project-score

Defects contribute to the “Known Defects” category scoring in pmat rust-project-score.

Code Similarity Detection

There is no pmat analyze similarity. The subcommand is duplicates, and it does clone detection by MinHash plus AST embeddings:

# Basic duplicate detection
pmat analyze duplicates

# Similarity threshold for semantic clones (0.0-1.0, default 0.85)
pmat analyze duplicates --threshold 0.8

# Detect one clone class (there is no --types 1,2,3)
pmat analyze duplicates --detection-type exact

# Ignore test files
pmat analyze duplicates --exclude "tests/**"

--detection-type takes exact, renamed, gapped, semantic, fuzzy or all (default) — the named equivalents of the Type-1/2/3/4 taxonomy. The other options are -p/--path, --min-lines (default 5), --max-tokens (default 128), -f/--format <summary|detailed|human|json|csv|sarif>, --perf, --include and --exclude.

The default --min-lines will hide short clones

This matters more than any flag on the command. The fixture used throughout this chapter contains copy_a and copy_b, which are character-for-character identical — and the default run finds nothing:

pmat analyze duplicates

Analyzing code similarity...
✓  Found 0 duplicate blocks
  Duplication: 0.0% (0 / 34 lines)

✓ Analysis Complete
Duplicate Code Analysis

Summary
  Total duplicate blocks: 0
  Duplicate lines: 0 / 34
  Duplication percentage: 0.0%

They are one-liners, and --min-lines defaults to 5. Lower it and they appear:

pmat analyze duplicates --min-lines 1

Analyzing code similarity...
✓  Found 2 duplicate blocks
  Duplication: 17.6% (6 / 34 lines)

✓ Analysis Complete
Duplicate Code Analysis

Summary
  Total duplicate blocks: 2
  Duplicate lines: 6 / 34
  Duplication percentage: 17.6%

Top Files by Duplication

  1. src/parser.rs - 21.1% duplication (4 / 19 lines)
  2. src/lib.rs - 16.7% duplication (2 / 12 lines)

0.0% and 17.6% on the same code, from one flag. A zero from this command means “no clone at or above --min-lines”, never “no duplication”.

Finding similarly-named functions

A different question — “what else is called something like this?” — is analyze name-similarity, which takes the name as a positional:

pmat analyze name-similarity depth

🔍 Searching for names similar to 'depth'...
✅ Found 8 names to analyze
Name Similarity Analysis

  Query: depth

  Found: 2 matches out of 8 names searched

1. depth (score: 1.00)
   File: ./src/parser.rs:2
   Type: function
   Edit distance: 0

2. dispatch (score: 0.50)

Dependency Analysis

There is no pmat analyze dependencies. The subcommand is dag, and it renders a Mermaid graph:

# Full dependency graph (the default)
pmat analyze dag

# Pick the graph type
pmat analyze dag --dag-type call-graph
pmat analyze dag --dag-type import-graph
pmat analyze dag --dag-type inheritance

# Write it out
pmat analyze dag -o deps.mmd

pmat analyze dag

🔄 Generating dependency analysis graph...
📁 Analyzed 4 files
📊 full-dependency: rendered 14 nodes and 2 edges
graph TD
    src_lib[lib]
    src_lib_dispatch[dispatch]
    src_lib_parser[parser]
    src_lib_util[util]
    src_main[main]
    src_main_main[main]
    src_parser[parser]
    src_parser_copy_a[copy_a]
    src_parser_copy_b[copy_b]
    src_parser_depth[depth]
    src_parser_never_called[never_called]
    src_util[util]
    src_util_scale[scale]
    src_util_unused_util[unused_util]

The output is Mermaid text on stdout, not an image — there is no --graph flag and no SVG renderer. Pipe it into a Mermaid renderer, or paste it into any Markdown viewer that supports Mermaid.

--dag-type accepts call-graph, import-graph, inheritance and full-dependency (default). Other options: -p/--path, -o/--output, --max-depth, --target-nodes (applies graph reduction above that count), --filter-external, --show-complexity, --include-duplicates, --include-dead-code, --enhanced.

There is no circular-dependency detector and no dependency-vulnerability check in pmat analyze. For cycle and centrality analysis over the same graph, see pmat analyze graph-metrics and Chapter 26. For dependency CVEs, use cargo audit / cargo deny, or pmat deps-audit for the Sovereign-AI-stack migration report.

Architecture Analysis

pmat analyze architecture does not exist and never has. It is not in pmat analyze --help, and every invocation exits 2 with “unrecognized subcommand”. There is no pattern detector for MVC/repository/service, and no --rules architecture.yaml rules engine anywhere in pmat 3.32.0.

The closest real capability is structural, not pattern-based:

Security Analysis

pmat analyze security does not exist either. The real security check lives on the quality gate:

pmat quality-gate --checks security

🔍 Running quality gate checks...

📋 Checks to run:
  ✓ Security vulnerabilities

  ⚠️  No .pmat/context.db found — violations not persisted to SQL
Quality Gate: PASSED
Total violations: 1
Blocking violations: 0

## scope (1 violations)
  - . - the security scan read 0 source file(s) directly under . and did NOT descend into subdirectories, so anything under src/ was not examined — a zero here is the scope's, not the tree's


✅ Quality gate PASSED (1 advisory finding(s), not blocking)

Read that scope violation before trusting the result: the scan did not descend into src/, and pmat reports that as a finding rather than letting a zero-findings result look like a clean bill of health. Point --path at the directory you mean.

There is no secrets scanner (--secrets) and no CVE database (--vulnerabilities) in pmat. Use gitleaks/trufflehog and cargo audit/cargo deny respectively.

Combined Analysis

Run multiple analyzers together:

# Run all analyzers
pmat analyze comprehensive -p .

# Run a specific combination — each analyser is opted in by name
pmat analyze comprehensive -p . --include-complexity --include-dead-code --include-tdg

# Executive summary only, for a build log
pmat analyze comprehensive -p . --executive-summary

Not available in pmat 3.32.0. There is no pmat analyze all, no comma-separated pmat analyze complexity,dead-code,satd, and no --profile. comprehensive is the subcommand that runs the suite, and its --include-* flags are how you pick a subset. Note that duplicate detection is not one of them: run pmat analyze duplicates separately.

Output Formats

pmat analyze comprehensive accepts five: summary (the default), detailed, json, markdown and sarif. There is no csv and no html — --format html exits 2 with a clap error listing the five that exist.

JSON Format

pmat analyze comprehensive -p . --format json > analysis.json

Real output from the same four-file project as above, trimmed only where noted:

{
  "complexity": {
    "total_files": 4,
    "violations": [
      {
        "file_path": "./src/payment_processor.py",
        "function_name": "process",
        "line_number": 4,
        "complexity": 39,
        "complexity_type": "cognitive-complexity"
      }
    ],
    "average_complexity": 4.333333333333333,
    "max_complexity": 39,
    "summary": "Analyzed 4 file(s) in . with 1 violation(s)"
  },
  "dead_code": null,
  "satd": {
    "total_files": 2,
    "violations": [
      {
        "file_path": "./src/payment_processor.py",
        "line_number": 1,
        "violation_type": "Requirement",
        "message": "TODO: extract the fee table into config",
        "severity": "Low"
      },
      {
        "file_path": "./src/payment_processor.py",
        "line_number": 14,
        "violation_type": "Defect",
        "message": "FIXME: unsupported currency silently falls through",
        "severity": "High"
      },
      {
        "file_path": "./web/app.js",
        "line_number": 1,
        "violation_type": "Design",
        "message": "HACK: hardcoded until the config service lands",
        "severity": "Medium"
      }
    ],
    "summary": "Found 3 SATD violations in 2 files (analysed 4 of 4 file(s) walked)",
    "census": {
      "discovered": 4,
      "analyzed": 4,
      "not_read": {
        "tests": 0,
        "out_of_scope": 0,
        "minified_or_vendor": 0,
        "too_large": 0,
        "unreadable": 0
      },
      "oversized": []
    }
  },
  "summary": {
    "total_files": 4,
    "total_issues": 4,
    "critical_issues": 4,
    "quality_score": 90.0,
    "recommendations": [
      "Consider refactoring high-complexity functions",
      "Address technical debt items (TODO/FIXME comments)"
    ]
  },
  "duration_ms": 55
}

"dead_code": null is the JSON spelling of “this analyser did not run” — distinct from a zero. The satd.census block reports what the walk saw versus what it read, so a shrinking violation count cannot be mistaken for progress when it was really a shrinking denominator.

SARIF (for IDEs and code scanning)

pmat analyze comprehensive -p . --format sarif > analysis.sarif

Markdown Report

pmat analyze comprehensive -p . --format markdown > ANALYSIS.md

CI/CD Integration

GitHub Actions

name: Code Quality Analysis

on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install PMAT
        run: cargo install pmat
        
      - name: Run Analysis
        run: |
          pmat analyze comprehensive -p . --format json > analysis.json
          pmat analyze complexity -p . --max-cyclomatic 10
          pmat analyze dead-code -p .
          pmat analyze satd -p . --severity high
          
      - name: Check Quality Gates
        run: |
          complexity=$(jq '.complexity.max_complexity' analysis.json)
          if [ "$complexity" -gt 20 ]; then
            echo "❌ Complexity too high: $complexity"
            exit 1
          fi
          
      - name: Upload Reports
        uses: actions/upload-artifact@v3
        with:
          name: analysis-reports
          path: analysis.json

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run analysis on staged files
staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|js|ts)$')

if [ -n "$staged" ]; then
    echo "Running PMAT analysis..."
    
    # Check complexity. --files takes a comma-separated list, so turn the
    # newline-separated staged list into one.
    if ! pmat analyze complexity --files "$(echo "$staged" | paste -sd,)" \
            --max-cyclomatic 10 --fail-on-violation; then
        echo "❌ Complexity check failed"
        exit 1
    fi

    # Count SATD. There is no --count flag; read the JSON.
    satd=$(pmat analyze satd -f json | jq '.total_violations')
    echo "SATD items: $satd"
fi

Configuration

Analysis Configuration

# .pmat/analyze.toml

[complexity]
threshold = 10
cognitive = true
by_function = true

[dead_code]
safe_only = false
exclude = ["tests/", "*_test.py"]

[satd]
patterns = ["TODO", "FIXME", "HACK", "XXX", "BUG", "REFACTOR"]
priority_keywords = {
    high = ["SECURITY", "CRITICAL", "URGENT"],
    medium = ["IMPORTANT", "SOON"],
    low = ["LATER", "MAYBE"]
}

[similarity]
threshold = 0.8
min_lines = 5
types = [1, 2, 3]

[dependencies]
check_circular = true
check_vulnerabilities = true
max_depth = 5

[output]
format = "detailed"
include_recommendations = true

Best Practices

1. Regular Analysis: Run analysis daily or on every commit
2. Set Thresholds: Define acceptable complexity and duplication levels
3. Track Trends: Monitor metrics over time, not just snapshots
4. Prioritize Fixes: Address high-complexity and security issues first
5. Automate Gates: Fail builds when quality drops below standards
6. Document Debt: When adding SATD, include priority and estimated fix time
7. Refactor Incrementally: Address duplication and complexity gradually

Troubleshooting

Analysis Takes Too Long

# Raise the walk budget (default 300s, reported on stderr)
pmat analyze complexity -p . --timeout 900

# Narrow the walk to the code you care about
pmat analyze comprehensive -p . --include "src/**"

# Exclude large directories
pmat analyze comprehensive -p . --exclude "node_modules/**"

Longer term, put the directories you never want walked into .pmatignore — see Chapter 30. That applies to every analyser at once rather than to a single invocation.

Missing Language Support

# List the analyzers, and the languages each one names
pmat analyze --help

# Restrict a pass to one detected toolchain
pmat analyze complexity -p . --toolchain rust

pmat analyze complexity reports what it could not read as well as what it did — no complexity analyzer for: .yaml (1) — so an unsupported language shows up as an explicit skip line rather than as a quietly smaller file count. If a whole run produces no metrics, it exits non-zero and says so.

Memory Issues

There is no memory cap or chunking flag. The lever that actually exists is scoping the walk: analyse one subtree at a time.

pmat analyze complexity -p src/
pmat analyze complexity --files src/parser.rs,src/util.rs

--files takes a comma-separated list and analyses exactly those files.

Not available in pmat 3.32.0. Earlier printings of this section showed --parallel, --incremental, --generic, --max-memory and --chunk-size on pmat analyze, plus a bare pmat analyze --languages. None of those flags exist, and pmat analyze needs a subcommand before any flag is even parsed.

Summary

The pmat analyze suite provides comprehensive insights into:

• Code Complexity: Identify hard-to-maintain code
• Dead Code: Find and remove unused code
• Technical Debt: Track and manage SATD
• Duplication: Detect and refactor similar code
• Dependencies: Understand coupling and vulnerabilities
• Architecture: Validate patterns and structure

Master these tools to maintain high code quality and reduce technical debt systematically.

Next Steps

• Chapter 6: Pre-commit Hooks - Automate quality checks
• Chapter 4: Technical Debt Grading - Advanced debt metrics
• Chapter 9: Quality-Driven Development - Quality-first coding

Chapter 6: The Scaffold Command - Project and Agent Generation

Chapter Status: ✅ 100% Working (8/8 examples)

Last updated: 2025-09-09
PMAT version: pmat 2.213.1
Test-Driven: All examples validated in tests/ch06/test_scaffold.sh

Automated Project and Agent Generation

The pmat scaffold command provides powerful scaffolding capabilities for creating complete projects and sophisticated MCP agents. It automates the tedious setup process while ensuring best practices, proper structure, and production-ready code.

Project Scaffolding

Basic Project Setup

Generate complete project structures with toolchain-specific templates:

# Scaffold a Rust project
pmat scaffold project rust

# Scaffold with specific templates
pmat scaffold project rust --templates=makefile,readme,gitignore

# Scaffold with parameters
pmat scaffold project rust \
    --templates=cli,lib \
    --param name=my-tool \
    --param author="Your Name"

Supported Toolchains

PMAT supports multiple development toolchains:

# Rust projects
pmat scaffold project rust --templates=cli,lib,makefile

# Deno/TypeScript projects  
pmat scaffold project deno --templates=api,frontend,makefile

# Python with uv package manager
pmat scaffold project python-uv --templates=cli,lib,requirements

Available Templates

Each toolchain provides specialized templates:

Rust Templates:

• cli - Command-line application with clap
• lib - Library crate with proper structure
• makefile - Comprehensive build automation
• readme - Documentation with examples
• gitignore - Rust-specific ignore patterns

Deno Templates:

• api - RESTful API server
• frontend - Web frontend application
• makefile - Deno-specific build tasks
• readme - TypeScript project documentation

Python Templates:

• cli - Click-based command-line tool
• lib - Package with proper structure
• requirements - Dependency management
• makefile - Python development tasks

Example: Full Rust Project

pmat scaffold project rust \
    --templates=cli,makefile,readme,gitignore \
    --param name=code-analyzer \
    --param author="Development Team" \
    --param description="Static code analysis tool"

Generated Structure:

code-analyzer/
├── Cargo.toml
├── src/
│   └── main.rs
├── Makefile
├── README.md
├── .gitignore
└── tests/
    └── cli_tests.rs

Generated Cargo.toml:

[package]
name = "code-analyzer"
version = "0.1.0"
edition = "2021"
authors = ["Development Team"]
description = "Static code analysis tool"

[dependencies]
clap = { version = "4.0", features = ["derive"] }
anyhow = "1.0"
tokio = { version = "1.0", features = ["full"] }

Parallel Generation

For large projects, use parallel processing:

# Use all CPU cores
pmat scaffold project rust --templates=cli,lib,api,frontend --parallel 8

# Automatic detection
pmat scaffold project rust --templates=cli,lib,api,frontend
# Automatically uses available CPU cores

Agent Scaffolding

MCP Agent Types

PMAT can generate sophisticated MCP agents with different architectures:

# List available agent templates
pmat scaffold list-templates

Output:

📦 Available Agent Templates:

  • mcp-server - Basic MCP server with tools and prompts
  • state-machine - Deterministic state machine agent
  • hybrid - Hybrid agent with deterministic core  
  • calculator - Example calculator agent
  • custom - Custom template from path

Total: 5 templates available

Basic MCP Agent

Generate a standard MCP server agent:

# Basic MCP agent
pmat scaffold agent \
    --name payment-processor \
    --template mcp-server \
    --features logging,monitoring

# With specific output directory
pmat scaffold agent \
    --name payment-processor \
    --template mcp-server \
    --output ./agents/payment \
    --force

Generated Structure:

payment-processor/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── tools/
│   │   ├── mod.rs
│   │   ├── validate.rs
│   │   └── process.rs
│   ├── prompts/
│   │   ├── mod.rs
│   │   └── payment.rs
│   └── lib.rs
├── tests/
│   ├── integration.rs
│   └── tools/
├── README.md
└── .gitignore

State Machine Agent

For deterministic behavior, use state machine agents:

pmat scaffold agent \
    --name order-processor \
    --template state-machine \
    --features logging,persistence,monitoring \
    --quality extreme

Key Features:

• Deterministic state transitions
• Formal verification support
• Property-based testing
• Comprehensive error handling
• Event sourcing capabilities

Generated State Machine:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq)]
pub enum OrderState {
    Pending,
    Validated,
    Processing,
    Fulfilled,
    Failed,
}

#[derive(Debug, Clone)]
pub enum OrderEvent {
    Validate(OrderData),
    Process,
    Fulfill,
    Fail(String),
}

impl StateMachine for OrderProcessor {
    type State = OrderState;
    type Event = OrderEvent;
    type Error = ProcessingError;

    fn transition(&self, state: &Self::State, event: Self::Event) 
        -> Result<Self::State, Self::Error> {
        match (state, event) {
            (OrderState::Pending, OrderEvent::Validate(_)) => {
                Ok(OrderState::Validated)
            }
            (OrderState::Validated, OrderEvent::Process) => {
                Ok(OrderState::Processing)
            }
            // ... more transitions
        }
    }
}
}

Hybrid Agents

Combine deterministic cores with AI capabilities:

pmat scaffold agent \
    --name smart-assistant \
    --template hybrid \
    --deterministic-core state-machine \
    --quality extreme \
    --features logging,monitoring,ai-integration

Architecture:

Smart Assistant (Hybrid Agent)
├── Deterministic Core (State Machine)
│   ├── Input validation
│   ├── State management
│   ├── Error handling
│   └── Safety guarantees
└── AI Wrapper (LLM Integration)
    ├── Natural language processing
    ├── Context understanding
    ├── Response generation
    └── Learning adaptation

Agent Features

Customize agents with specific features:

Available Features:

• logging - Structured logging with tracing
• monitoring - Metrics and health checks
• persistence - State persistence layer
• ai-integration - LLM integration capabilities
• testing - Property-based test generation
• documentation - Auto-generated docs

# Full-featured agent
pmat scaffold agent \
    --name production-agent \
    --template hybrid \
    --features logging,monitoring,persistence,testing \
    --quality extreme

Quality Levels

Set quality standards for generated code:

# Quality levels: standard, strict, extreme
pmat scaffold agent \
    --name critical-system \
    --template state-machine \
    --quality extreme

Quality Level Comparison:

Dry Run Mode

Preview generated code without creating files:

pmat scaffold agent \
    --name preview-agent \
    --template mcp-server \
    --features logging,monitoring \
    --dry-run

Output:

🔍 Dry Run: Would generate MCP agent 'preview-agent'

Template: mcp-server
Features: logging, monitoring  
Quality Level: strict

Files that would be generated:
  📄 src/main.rs (325 lines)
  📄 Cargo.toml (45 lines)
  📄 src/tools/mod.rs (125 lines)
  📄 src/prompts/mod.rs (89 lines)
  📄 tests/integration.rs (156 lines)
  📄 README.md (234 lines)
  📄 .gitignore (23 lines)

Total: 7 files, 997 lines

Quality Checks:
  ✅ Error handling: Comprehensive
  ✅ Testing: Property-based
  ✅ Documentation: Complete
  ✅ Performance: Optimized

Interactive Mode

Guided Agent Creation

Use interactive mode for step-by-step guidance:

pmat scaffold agent --interactive

Interactive Flow:

🎯 Interactive Agent Scaffolding

? Agent name: payment-processor
? Template type: 
  ❯ mcp-server
    state-machine  
    hybrid
    calculator
    custom

? Features (multi-select):
  ✅ logging
  ✅ monitoring
  ❯ persistence
    ai-integration
    testing

? Quality level:
    standard
  ❯ strict
    extreme

? Output directory: ./payment-processor

Preview:
- Template: mcp-server
- Features: logging, monitoring, persistence
- Quality: strict
- Files: 12 files, 1,456 lines

? Continue? (Y/n) y

✅ Agent 'payment-processor' generated successfully!

Custom Templates

Use your own templates:

# From local path
pmat scaffold agent \
    --name custom-agent \
    --template custom:/path/to/template

# From URL (future feature)
pmat scaffold agent \
    --name custom-agent \
    --template custom:https://github.com/user/agent-template

Template Validation

Validate Existing Templates

Ensure template quality before using:

# Validate a template file
pmat scaffold validate-template path/to/template.json

# Validate all templates in directory
pmat scaffold validate-template templates/

Validation Output:

✅ Template Validation Report

Template: advanced-mcp-server
Format: Valid JSON
Schema: Compliant with v2.0 spec

Structure Checks:
  ✅ Required fields present
  ✅ File templates valid
  ✅ Dependencies resolvable
  ✅ Feature compatibility

Quality Checks:
  ✅ Code patterns follow best practices
  ✅ Error handling comprehensive
  ✅ Tests included
  ✅ Documentation complete

Warnings: 0
Errors: 0

Rating: A+ (Production Ready)

Advanced Scaffolding

Multi-Agent Systems

Generate multiple coordinated agents:

# Generate coordinator
pmat scaffold agent \
    --name system-coordinator \
    --template state-machine \
    --features coordination,monitoring

# Generate worker agents
pmat scaffold agent \
    --name data-processor \
    --template mcp-server \
    --features processing,persistence

pmat scaffold agent \
    --name notification-sender \
    --template mcp-server \
    --features messaging,logging

Configuration-Driven Scaffolding

Use configuration files for complex setups:

# scaffold-config.yaml
project:
  name: "enterprise-system"
  toolchain: "rust"
  
agents:
  - name: "api-gateway"
    template: "hybrid"
    features: ["logging", "monitoring", "rate-limiting"]
    quality: "extreme"
    
  - name: "data-processor" 
    template: "state-machine"
    features: ["persistence", "monitoring"]
    quality: "strict"
    
templates:
  - "makefile"
  - "readme"
  - "docker"
  - "ci-cd"

pmat scaffold --config scaffold-config.yaml

Integration with Development Workflow

Git Integration

Scaffolded projects include proper Git setup:

# Projects include .gitignore
pmat scaffold project rust --templates=gitignore

# Automatic git initialization
pmat scaffold project rust --git-init

# Initial commit
pmat scaffold project rust --git-init --initial-commit

CI/CD Integration

Generated projects include workflow files:

# Include GitHub Actions
pmat scaffold project rust --templates=github-actions

# Include GitLab CI
pmat scaffold project rust --templates=gitlab-ci

# Include Jenkins pipeline
pmat scaffold project rust --templates=jenkins

Generated GitHub Actions:

name: CI/CD Pipeline

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Run tests
        run: cargo test
      - name: Check formatting
        run: cargo fmt -- --check
      - name: Run clippy
        run: cargo clippy -- -D warnings

IDE Configuration

Include IDE-specific configurations:

# VS Code configuration
pmat scaffold project rust --templates=vscode

# IntelliJ/CLion configuration  
pmat scaffold project rust --templates=intellij

Best Practices

Project Structure

1. Consistent Layout: Use standard directory structures
2. Clear Separation: Separate concerns (lib vs binary, tests vs src)
3. Documentation: Always include README and inline docs
4. Testing: Include test framework and example tests

Agent Development

1. Start Simple: Begin with basic MCP server template
2. Add Features Gradually: Enable features as needed
3. Test Early: Use property-based testing for reliability
4. Monitor Always: Include logging and monitoring from start

Template Management

1. Validate Templates: Always validate before using
2. Version Control: Keep templates in version control
3. Test Generation: Test generated code regularly
4. Document Changes: Track template modifications

Troubleshooting

Common Issues

Permission Errors

# Fix permissions
pmat scaffold agent --name test --template mcp-server --force

# Use different output directory
pmat scaffold agent --name test --template mcp-server --output ~/agents/test

Template Not Found

# List available templates
pmat scaffold list-templates

# Update template registry
pmat scaffold --update-templates

# Use absolute path for custom templates
pmat scaffold agent --template custom:/absolute/path/to/template

Generation Failures

# Use dry-run to debug
pmat scaffold agent --name debug --template mcp-server --dry-run

# Check template validation
pmat scaffold validate-template path/to/template

# Enable verbose output
pmat --verbose scaffold agent --name debug --template mcp-server

Configuration

Global Configuration

# ~/.pmat/scaffold.toml

[defaults]
quality_level = "strict"
author = "Your Name"
email = "your.email@domain.com"

[templates]
registry_path = "~/.pmat/templates"
auto_update = true
custom_paths = [
    "~/my-templates",
    "/company/shared-templates"
]

[generation]
parallel_jobs = 8
backup_existing = true
format_generated = true

Project Configuration

# .pmat/scaffold.toml (in project root)

[project]
name = "my-project"
toolchain = "rust"
default_templates = ["makefile", "readme", "gitignore"]

[agents]
default_features = ["logging", "monitoring"]
default_quality = "strict"
output_directory = "./agents"

Summary

The pmat scaffold command transforms development workflow by automating:

• Project Setup: Complete project structures with best practices
• Agent Generation: Sophisticated MCP agents with various architectures
• Template Management: Validation and customization of generation templates
• Quality Assurance: Built-in quality levels and testing frameworks
• Integration: Seamless CI/CD and IDE configuration

Use scaffolding to:

1. Accelerate Development: Skip repetitive setup tasks
2. Ensure Consistency: Standardize project structures
3. Improve Quality: Include testing and monitoring from start
4. Enable Innovation: Focus on business logic, not boilerplate

Next Steps

• Chapter 7: Quality Gates - Automate quality enforcement
• Chapter 4: Technical Debt Grading - Quality measurement
• Chapter 5: Analyze Suite - Code analysis tools

Chapter 7: Quality Gates - Automated Quality Enforcement

Chapter Status: ✅ 100% Working (10/10 examples)

Last updated: 2026-02-17 PMAT version: pmat 3.3.0 Test-Driven: All examples validated in tests/ch07/test_quality_gate.sh

Automated Quality Enforcement

Quality gates are automated checkpoints that enforce code quality standards across your project. PMAT’s quality gate system provides comprehensive analysis and configurable thresholds to maintain high-quality codebases consistently.

Basic Quality Gate Analysis

Run All Quality Checks

Start with a comprehensive quality assessment:

# Analyze current project (default)
pmat quality-gate

# Analyze specific directory
pmat quality-gate --project-path src/

# Analyze specific file
pmat quality-gate --file src/main.rs

# Run with verbose output
pmat quality-gate --verbose

Example Output (Summary Format)

Quality Gate: FAILED
Total violations: 348

## complexity (266 violations)
  - ./src/parser.rs:135 - parse_expression: cognitive-complexity -
    Cognitive complexity of 21 exceeds recommended complexity of 20
    (complexity: 21, threshold: 20)
  - ./src/handler.rs:262 - handle_request: cyclomatic-complexity -
    Cyclomatic complexity of 33 exceeds maximum allowed complexity of 30
    (complexity: 33, threshold: 30)

## satd (58 violations)
  - ./src/agents/mod.rs:106 - Requirement: TODO: Properly implement
    agent system initialization (at column 5)

## entropy (21 violations)
  - ./src/services/github_client.rs - ApiCall pattern repeated 10 times
    (saves 302 lines) - Fix: Create API client abstraction

## sections (3 violations)
  - README.md - Missing required section: Installation

Available Quality Checks

PMAT’s quality gate includes 9 check types, selectable via --checks:

# Run specific checks
pmat quality-gate --checks complexity,satd,entropy

# All checks (default)
pmat quality-gate --checks all

Available checks: complexity, satd, dead-code, coverage, sections, provability, entropy, security, duplicates

Complexity Analysis

Monitor both cyclomatic and cognitive complexity:

# Focus on complexity only
pmat quality-gate --checks complexity

Complexity Thresholds (built-in):

• Cyclomatic: Recommended ≤ 25, Maximum ≤ 30
• Cognitive: Recommended ≤ 20, Maximum ≤ 25

Technical Debt Detection (SATD)

Track Self-Admitted Technical Debt markers:

# Check technical debt
pmat quality-gate --checks satd

Detected Markers:

• TODO - Future improvements
• FIXME - Known bugs or issues
• HACK - Temporary solutions
• XXX - Critical concerns
• BUG - Confirmed defects

Dead Code Detection

Identify unused code that increases maintenance burden:

pmat quality-gate --checks dead-code

Entropy Analysis

Detect repetitive code patterns that could be abstracted:

pmat quality-gate --checks entropy

Entropy analysis finds structurally identical code patterns and estimates how many lines could be saved by refactoring. Patterns are grouped by structural hash — code is normalized (identifiers replaced with placeholders, literals removed) so that only truly duplicated logic is flagged. This eliminates false positives where different validation checks happen to use the same API (e.g., .is_empty()).

Note: The calculate_pattern_variations() function was removed because it was overriding structural hash results with its own variation scoring, which diluted the accuracy of structural deduplication. Structural hashing alone provides more precise duplicate detection.

The following paths are excluded from entropy analysis by default:

• tests/ directory and *.test.rs files
• Test files matching *_tests.rs and *tests_part*.rs patterns
• examples/ and benches/ directories

Each violation includes:

• Pattern type (ApiCall, ErrorHandling, ResourceManagement, etc.)
• Repetition count (≥3 structurally identical matches required) and estimated LOC reduction
• Affected files and example code
• Fix suggestion (e.g., “Create API client abstraction”)

Configure via .pmat-gates.toml:

[entropy]
enabled = true
min_pattern_diversity = 0.30
exclude = ["examples/**", "benches/**"]

Provability Analysis

Score how amenable your code is to formal verification:

pmat quality-gate --checks provability

Provability analysis reads actual function source code and scores each function on:

• Bounds checking - Array/index safety (no unchecked indexing or .unwrap()); the ? operator is recognized as proper error propagation and does not penalize the score
• Memory safety - Ownership and lifetime correctness (no unsafe, no raw pointers)
• No aliasing - Absence of mutable aliasing; &mut is correctly treated as an exclusive borrow (Rust’s ownership model guarantees NoAlias for &mut references, so their presence does not reduce the score)
• Null safety - Rust type system guarantees (non-unsafe code is null-safe)
• Pure functions - Side-effect-free logic (no I/O, no mutation, no loops)

Scores are differentiated per function (0.2 to 1.0), not a single fallback value. The provability gate passes when the project-wide average score meets the minimum threshold (>= 0.60). When it fails, violations include the worst-scoring functions and verified property counts:

Provability score 0.55 is below minimum 0.60
  Functions: main (20%), handle_request (33%)
  Verified: bounds_check 25/50, memory_safety 30/50, null_safety 40/50,
            no_aliasing 35/50, pure_function 15/50

Test Coverage

Monitor test coverage levels (reads from .pmat/coverage-cache.json):

pmat quality-gate --checks coverage

Section Validation

Check that README.md contains required sections:

pmat quality-gate --checks sections

Output Formats

PMAT supports 6 output formats: summary (default), human, json, detailed, junit, markdown.

Summary Format (Default)

Concise list grouped by check type:

pmat quality-gate --format=summary

Quality Gate: FAILED
Total violations: 348

## complexity (266 violations)
  - ./src/parser.rs:135 - parse_expression: cognitive-complexity -
    Cognitive complexity of 21 exceeds recommended complexity of 20

## satd (58 violations)
  - ./src/agents/mod.rs:106 - Requirement: TODO: Properly implement
    agent system initialization

## entropy (21 violations)
  - ./src/services/github_client.rs - ApiCall pattern repeated 10 times
    (saves 302 lines) - Fix: Create API client abstraction

## sections (3 violations)
  - README.md - Missing required section: Installation

Human-Readable Format

Same content as summary with additional detail per violation:

pmat quality-gate --format=human

JSON Format

Machine-readable output for CI/CD integration. Progress messages go to stderr; clean JSON goes to stdout.

# Pipe-friendly: only JSON on stdout
pmat quality-gate --format=json > report.json

# Suppress progress entirely
pmat quality-gate --format=json --quiet

JSON Structure:

{
  "results": {
    "passed": false,
    "total_violations": 348,
    "complexity_violations": 266,
    "dead_code_violations": 0,
    "satd_violations": 58,
    "entropy_violations": 21,
    "security_violations": 0,
    "duplicate_violations": 0,
    "coverage_violations": 0,
    "section_violations": 3,
    "provability_violations": 0,
    "provability_score": null,
    "violations": []
  },
  "violations": [
    {
      "check_type": "complexity",
      "severity": "warning",
      "file": "./src/parser.rs",
      "line": 135,
      "message": "parse_expression: cognitive-complexity - Cognitive complexity of 21 exceeds recommended complexity of 20 (complexity: 21, threshold: 20)"
    },
    {
      "check_type": "satd",
      "severity": "info",
      "file": "./src/agents/mod.rs",
      "line": 106,
      "message": "Requirement: TODO: Properly implement agent system initialization (at column 5)"
    },
    {
      "check_type": "entropy",
      "severity": "warning",
      "file": "./src/services/github_client.rs",
      "line": null,
      "message": "ApiCall pattern repeated 10 times (saves 302 lines) - Fix: Create API client abstraction",
      "details": {
        "affected_files": ["./src/services/github_client.rs"],
        "example_code": "let resp = client.post(\"/endpoint\", body).await",
        "fix_suggestion": "Create API client abstraction",
        "score_factors": [
          "pattern_type: ApiCall",
          "repetitions: 10",
          "variation_score: 0.00 (structurally identical)"
        ]
      }
    }
  ]
}

Key fields:

• results.passed - Overall pass/fail boolean
• results.*_violations - Count per check type
• violations[] - Flat array of all violations
• violations[].details - Present for entropy and provability violations with explainability data (affected files, fix suggestions, score breakdown)
• violations[].line - Line number (null for file-level or project-level violations)

JUnit Format

For CI systems that consume JUnit XML:

pmat quality-gate --format=junit

Markdown Format

For embedding in pull request comments:

pmat quality-gate --format=markdown

Configurable Thresholds

Thresholds are configured in .pmat-gates.toml (project root). CLI flags override config values.

Complexity Thresholds

Built-in complexity thresholds (not currently CLI-configurable):

• Cyclomatic: Recommended ≤ 25, Maximum ≤ 30
• Cognitive: Recommended ≤ 20, Maximum ≤ 25

Dead Code Threshold

# .pmat-gates.toml
[dead_code]
# Library crates need higher threshold for public APIs
max_dead_code_pct = 30.0

Entropy Configuration

# .pmat-gates.toml
[entropy]
enabled = true
# Files below this pattern diversity score are flagged (0.0-1.0)
min_pattern_diversity = 0.30
# Paths excluded from entropy analysis
exclude = ["examples/**", "benches/**"]

Selective Check Execution

# Run only complexity and entropy
pmat quality-gate --checks complexity,entropy

# Run everything except duplicates
pmat quality-gate --checks complexity,satd,dead-code,entropy,coverage,sections,provability,security

# Fail CI if quality gate fails
pmat quality-gate --fail-on-violation --format json

Single File Analysis

Analyze individual files for focused quality assessment:

# Analyze specific file
pmat quality-gate --file src/payment.rs

# With JSON output
pmat quality-gate --file src/payment.rs --format json

Single file analysis runs the same checks but scoped to one file. The output format is identical to project-wide analysis, with violations filtered to the target file.

CI/CD Integration

Fail on Quality Gate Violations

Use quality gates as build gates in CI/CD pipelines:

# Fail build if quality gate fails (exit code 1)
pmat quality-gate --fail-on-violation

# Specific checks only
pmat quality-gate --fail-on-violation --checks complexity,satd,entropy

Exit Codes

Quality gates return meaningful exit codes:

• 0: All checks passed (or --fail-on-violation not set)
• 1: Quality gate violations found
• 2: Analysis failed (tool error)

GitHub Actions Integration

name: Quality Gate

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install PMAT
        run: cargo install pmat

      - name: Run Quality Gate
        run: |
          pmat quality-gate \
            --format json \
            --fail-on-violation \
            --checks complexity,satd,entropy,provability \
            > quality-report.json

      - name: Upload Quality Report
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: quality-report
          path: quality-report.json

GitLab CI Integration

quality_gate:
  stage: test
  script:
    - pmat quality-gate --format junit --fail-on-violation > quality-report.xml
  artifacts:
    reports:
      junit: quality-report.xml
    expire_in: 1 week
  allow_failure: false

Advanced Features

SQL Querying of Quality Data

Quality gate data is stored in SQLite tables alongside the function index. Use pmat sql to query violations directly:

# Query entropy violations sorted by repetition count
pmat sql entropy-violations

# Query low-provability functions
pmat sql low-provability

Entropy violations table schema:

CREATE TABLE entropy_violations (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,
    pattern_type TEXT NOT NULL,
    pattern_hash TEXT NOT NULL,
    repetitions INTEGER NOT NULL,
    variation_score REAL NOT NULL,
    estimated_loc_reduction INTEGER NOT NULL,
    severity TEXT NOT NULL,
    example_code TEXT,
    UNIQUE(file_path, pattern_hash)
);

Provability scores table schema:

CREATE TABLE provability_scores (
    id INTEGER PRIMARY KEY,
    function_id INTEGER,
    file_path TEXT NOT NULL,
    function_name TEXT NOT NULL,
    provability_score REAL NOT NULL,
    verified_properties INTEGER DEFAULT 0,
    FOREIGN KEY (function_id) REFERENCES functions(id)
);

Violation Explainability (Details)

Entropy and provability violations include a details field in JSON output with:

• affected_files - Which files contain the violation
• example_code - Code snippet demonstrating the pattern
• fix_suggestion - Actionable recommendation
• score_factors - Breakdown of how the score was computed

This enables automated triaging: parse the JSON, sort by impact, and generate fix suggestions programmatically.

Custom Check Selection

Run only specific quality checks:

# Code structure checks only
pmat quality-gate --checks complexity,dead-code

# Code quality checks only
pmat quality-gate --checks satd,entropy,provability

# Security-focused
pmat quality-gate --checks security,provability

Configuration Reference

.pmat-gates.toml (Project Configuration)

The primary configuration file lives in the project root:

# .pmat-gates.toml - Quality Gate Configuration

[gates]
run_clippy = true
clippy_strict = true
run_tests = true
test_timeout = 300
check_coverage = true
min_coverage = 80.0
check_complexity = true
max_complexity = 10

[exclude]
# Paths excluded from quality gate checks
paths = [
    "tests/**",
    "examples/**",
    "benches/**",
    "**/target/**",
]

[entropy]
enabled = true
# Minimum pattern diversity score (0.0-1.0)
min_pattern_diversity = 0.30
exclude = ["examples/**", "benches/**"]

[dead_code]
# Library crates: public APIs count as "dead" since they aren't called internally
max_dead_code_pct = 30.0

[tdg]
# Exclude non-production code from TDG grade gate
exclude = [
    "examples/**",
    "scripts/**",
    "benches/**",
]

[comply]
# Secret detector false positive exclusions
yaml_secret_exclude_paths = [
    "contracts/**/*.yaml",
]

Troubleshooting

Common Issues

Analysis Takes Too Long

# Run only fast checks (skip entropy/provability)
pmat quality-gate --checks complexity,satd,dead-code

# Analyze single file
pmat quality-gate --file src/main.rs

False Positives in Entropy

Entropy analysis uses structural code hashing — code is normalized (identifiers and literals replaced with placeholders) before comparison, so only ≥3 structurally identical code blocks are flagged. This eliminates false positives where different logic happens to use the same API (e.g., multiple unrelated .is_empty() checks). Test files (*_tests.rs, *tests_part*.rs, *.test.rs, and the tests/ directory) as well as examples/ and benches/ directories are excluded by default.

If you still see false positives, exclude additional paths:

# Exclude paths in .pmat-gates.toml
# [entropy]
# exclude = ["examples/**", "benches/**", "generated/**"]

Coverage Shows 0%

Coverage reads from .pmat/coverage-cache.json. Run make coverage first to populate the cache.

Best Practices

Development Workflow

1. Pre-commit Checks: Run quick quality gates before committing
2. Feature Branch Gates: Full analysis on feature branches
3. Integration Gates: Strict quality gates on main branch
4. Release Gates: Comprehensive quality assessment before release

Quality Standards

1. Set Realistic Thresholds: Start with current baseline, improve gradually
2. Focus on Trends: Monitor quality trends over time
3. Prioritize Violations: Address high-impact issues first
4. Regular Reviews: Review and adjust thresholds periodically

Team Adoption

1. Start Gradually: Begin with warnings, move to enforcement
2. Educate Team: Ensure everyone understands quality standards
3. Automate Everything: Integrate quality gates into all workflows
4. Provide Tools: Give developers tools to meet quality standards

Integration Examples

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running quality gate checks..."

if ! pmat quality-gate --fail-on-violation --checks complexity,satd,entropy; then
    echo "Quality gate failed. Commit rejected."
    echo "Fix quality issues before committing."
    exit 1
fi

echo "Quality gate passed. Proceeding with commit."

Makefile Integration

.PHONY: quality-gate quality-report

quality-gate:
	@echo "Running quality gate..."
	@pmat quality-gate --fail-on-violation

quality-report:
	@echo "Generating quality report..."
	@pmat quality-gate --format json > quality-report.json
	@pmat quality-gate --format markdown > quality-report.md
	@echo "Reports generated: quality-report.json, quality-report.md"

ci-quality: quality-gate
	@echo "CI quality checks passed"

Summary

PMAT’s quality gates provide comprehensive automated quality enforcement:

• 9 Check Types: Complexity, SATD, dead code, coverage, entropy, provability, security, duplicates, sections
• Explainable Violations: Entropy and provability violations include details with affected files, fix suggestions, and score breakdowns
• 6 Output Formats: Summary, human, JSON, detailed, JUnit, Markdown
• SQL Queryable: Quality data stored in SQLite tables for ad-hoc analysis
• Configurable: .pmat-gates.toml for project-specific thresholds
• CI/CD Ready: --fail-on-violation flag with meaningful exit codes

Use quality gates to:

1. Enforce Standards: Maintain consistent code quality across teams
2. Prevent Regression: Catch quality degradation early in CI/CD
3. Guide Refactoring: Entropy analysis identifies DRY violations with LOC savings estimates
4. Prove Safety: Provability scores track formal verification amenability
5. Query History: SQL tables enable trend analysis across builds

Next Steps

• Chapter 4: Technical Debt Grading - Advanced quality metrics
• Chapter 5: Analyze Suite - Detailed code analysis
• Chapter 6: Scaffold Command - Generate quality-focused projects

Chapter 8: Interactive Demo and Reporting

Chapter Status: ⚠️ The command exists but cannot run in a cargo install pmat build

Last updated: 2026-08-25 PMAT version: pmat 3.32.0

⚠️ Historical, as of pmat 3.32.0 (2026-08-25). pmat demo does not run in the build you get from cargo install pmat.

This chapter described pmat 2.213.1 and presented 55 working examples. All 55 fail against 3.32.0, for two independent reasons:

• pmat demo takes no positional path. Forty of the examples were written as pmat demo .; clap rejects that with “unexpected argument found” and exits 2. The path goes in -p / --path.
• The demo is behind a non-default Cargo feature. Even with the path corrected, every invocation — --cli, --protocol mcp, the web server, all of them — exits 1 with Error: Demo feature not enabled. Build with --features demo. pmat demo --help still prints, which is why this chapter passes the book’s command-existence gate while none of it works.

The dashboards, JSON payloads and tables the old chapter pasted cannot be reproduced from an installed pmat. They have been removed rather than reprinted as if verified. What remains is the invocation form, the real error, and where to go instead.

For code analysis with output you can actually get today, read Chapter 5 (pmat analyze) and Chapter 9 (pmat report).

What pmat demo Was For

pmat demo bundles pmat’s analyses into a presentation: a CLI summary, an interactive web dashboard, or a scripted walk through the MCP tool surface. It exists to show what pmat can do without asking the viewer to learn the subcommands first.

It is a demonstration harness, not an analysis command. Nothing it reports is unavailable from pmat analyze and pmat report, which is why shipping it behind a feature flag costs installed users nothing but this chapter.

Verified: What Happens When You Run It

pmat demo -p . --cli

Error: Demo feature not enabled. Build with --features demo

Exit code 1. The same for every mode:

pmat demo -p . --cli -f json
pmat demo --repo gh:owner/repository
pmat demo --url https://github.com/owner/repository.git

Error: Demo feature not enabled. Build with --features demo

The help text is candid about it — pmat demo --help opens with:

cargo install pmat produces a build in which every demo mode (including --cli) exits 1 with “Demo feature not enabled”, so all the flags below are inert.

Enabling It

The demo feature does exist in the published crate. cargo add --dry-run pmat --features demo resolves cleanly against pmat 3.32.0 (76 activated features rather than the default 69), so this is the supported route:

cargo install pmat --features demo

That build has not been exercised for this chapter, and no output from it is reproduced here. If you build it and the behaviour differs from the flag reference below, the flag reference is what --help printed, not what the demo did.

Flag Reference

These are the flags pmat demo --help lists in 3.32.0. They all parse; none of them does anything in the default build. The path is -p, never positional.

Correct invocation forms, for when you have a build that supports them:

pmat demo -p . --cli
pmat demo -p . --cli -f json
pmat demo -p . --port 3000 --no-browser
pmat demo -p . --protocol mcp --show-api
pmat demo -p . --cli --target-nodes 20 --centrality-threshold 0.2
pmat demo --repo gh:rust-lang/rustlings --cli

Each of these exits 1 in the default build. They are printed as forms, not as worked examples.

What to Use Instead

Everything the demo displayed has a first-class command that works in the build you already have:

pmat serve is a real, compiled-in HTTP server, but it serves the MCP tool surface, not a dashboard. It is not a drop-in replacement for the demo’s web UI; there is no HTML dashboard in the default build.

Summary

pmat demo is a feature-gated presentation tool. In cargo install pmat it resolves, prints help, and refuses to run.

Key takeaways:

• -p, not a positional path. That alone broke 40 of this chapter’s 55 examples even before the feature gate.
• Every mode exits 1 with Demo feature not enabled in the default build.
• cargo install pmat --features demo is the documented route; the demo feature is real in the published 3.32.0 crate.
• No demo output is reproduced in this chapter, because none of it can be produced from an installed pmat.

Chapter 9: Enhanced Analysis Reports

Chapter Status: ✅ Verified against pmat 3.32.0

Last updated: 2026-08-25 PMAT version: pmat 3.32.0

What changed in this rewrite. Every example in the 2025 edition was written as pmat report . — a positional path. pmat report does not take a positional argument; clap rejects it with “unexpected argument found” and exits 2. Thirty-nine of this chapter’s forty commands failed on that single mistake. The path goes in -p / --project-path.

Three further corrections, because the old text asserted the opposite:

• pmat report reports self-admitted technical debt, and nothing else. The old chapter showed complexity findings, duplication clusters, dead-code listings, maintainability indices and quality trends. None of those appear. A function with a cyclomatic complexity over 20 produces zero defects from this command; see “What the report actually contains”.
• --analyses and --confidence-threshold parse but change nothing. All six --analyses values return byte-identical output, as do --confidence-threshold 0 and 100. Measured, below.
• --stream, --parallel-jobs, --max-file-size, --template, --list-templates and --exclude do not exist. Those examples are gone rather than guessed at.

What pmat report Is

pmat report runs one analysis pass over a project and serialises the findings as JSON, CSV, Markdown or plain text. It is a format command: the value it adds over pmat analyze satd is the report envelope — metadata, a severity histogram, hotspot ranking and a file index — not extra analysis.

Read the next section before you build anything on it.

What the Report Actually Contains

The worked example below is a two-file Rust crate. src/lib.rs carries a TODO on line 1, a FIXME on line 12, a function with six branches, and an unused pub fn unused_helper:

pmat report -p .

{
  "metadata": {
    "tool": "pmat",
    "version": "3.32.0",
    "generated_at": "2026-08-25T20:40:28.798408392Z",
    "project_root": ".",
    "total_files_analyzed": 1,
    "analysis_duration_ms": 14
  },
  "defects": [
    {
      "id": "SATD-0001",
      "severity": "low",
      "category": "technical_debt",
      "file_path": "./src/lib.rs",
      "line_start": 1,
      "line_end": null,
      "column_start": 1,
      "column_end": null,
      "message": "Requirement: TODO: validate the input range before shipping",
      "rule_id": "satd-requirement",
      "fix_suggestion": "Complete the missing requirement implementation",
      "metrics": {
        "debt_category": 0.0
      }
    },
    {
      "id": "SATD-0002",
      "severity": "high",
      "category": "technical_debt",
      "file_path": "./src/lib.rs",
      "line_start": 12,
      "line_end": null,
      "column_start": 9,
      "column_end": null,
      "message": "Defect: FIXME: this branch was never reviewed",
      "rule_id": "satd-defect",
      "fix_suggestion": "Fix the known defect or bug",
      "metrics": {
        "debt_category": 0.0
      }
    }
  ],
  "summary": {
    "total_defects": 2,
    "by_severity": {
      "high": 1,
      "low": 1
    },
    "by_category": {
      "TechnicalDebt": 2
    },
    "hotspot_files": [
      {
        "path": "./src/lib.rs",
        "defect_count": 2,
        "severity_score": 6.0
      }
    ]
  },
  "file_index": {
    "./src/lib.rs": [
      "SATD-0001",
      "SATD-0002"
    ]
  }
}

Two comment markers, two defects. Note what is not there:

• No complexity finding, though classify has six branches. Adding a function with cyclomatic complexity well over 20 to this crate changes the output not at all — still exactly the two SATD entries.
• No dead-code finding, though unused_helper is never called.
• No duplication, no maintainability index, no trends.

by_category has held only TechnicalDebt in every run. If you need complexity, dead code or duplication, run pmat analyze complexity, pmat analyze dead-code or pmat analyze duplicates — the report command does not aggregate them.

total_files_analyzed counts files that produced findings, not files scanned. The crate above has two .rs files and the field reads 1. Adding a TODO to src/main.rs makes it read 2. Do not use it as a project size metric.

Choosing a Format

The default is JSON. Three shorthand flags cover the rest, and each has a long form via -f / --output-format (aliased as --format):

pmat report -p .                    # JSON (default)
pmat report -p . --md               # same as -f markdown
pmat report -p . --csv              # same as -f csv
pmat report -p . --txt              # same as -f text
pmat report -p . -f json

Markdown

pmat report -p . --md

# Code Quality Report

Generated: 2026-08-25 20:40:28 UTC

## Executive Summary

- **Total Defects**: 2
- **Files Analyzed**: 1
- **Analysis Duration**: 13ms

### Severity Distribution

```
high     ██████████░░░░░░░░░░ 1 (50.0%)
low      ██████████░░░░░░░░░░ 1 (50.0%)
```

### Top 10 Hotspot Files

| Rank | File | Defects | Severity Score |
|------|------|---------|----------------|
| 1 | ./src/lib.rs | 2 | 6.0 |

## Detailed Findings

### Technical Debt (2 issues)

#### ./src/lib.rs:1-1

**Low** - Requirement: TODO: validate the input range before shipping

> 💡 **Suggestion**: Complete the missing requirement implementation

#### ./src/lib.rs:12-12

**High** - Defect: FIXME: this branch was never reviewed

> 💡 **Suggestion**: Fix the known defect or bug

The executive summary is always present. See “Flags that parse but do nothing” for why --include-executive-summary cannot turn it off.

CSV

pmat report -p . --csv

id,severity,category,file_path,line_start,line_end,message,rule_id,cyclomatic,cognitive
SATD-0001,low,TechnicalDebt,./src/lib.rs,1,,Requirement: TODO: validate the input range before shipping,satd-requirement,,
SATD-0002,high,TechnicalDebt,./src/lib.rs,12,,Defect: FIXME: this branch was never reviewed,satd-defect,,

The cyclomatic and cognitive columns are declared in the header and empty in every row. They stay empty even for a deliberately hairy function — consistent with the command emitting only SATD defects. Budget for them being blank if you import this into a spreadsheet.

Plain text

pmat report -p . --txt

CODE QUALITY REPORT
===================

Generated: 2026-08-25 20:40:38 UTC
Project: .
Total Defects: 2
Files Analyzed: 1

SEVERITY BREAKDOWN
------------------
high       1
low        1

CATEGORY BREAKDOWN
------------------
TechnicalDebt        2

TOP HOTSPOT FILES
-----------------
1. ./src/lib.rs (2 defects, score: 6.0)

DEFECTS
-------
[Low] Technical Debt - ./src/lib.rs:1
  Requirement: TODO: validate the input range before shipping

Writing to a File

-o / --output takes a path. Without it the report goes to stdout and no file is created:

pmat report -p . --md -o R.md

📄 Report saved to: R.md

Piping works as you would expect, since stdout carries only the report:

pmat report -p . -f json | gzip > report.json.gz
pmat report -p . -f json | jq '.summary.total_defects'

Timing

--perf appends two lines after the report body:

pmat report -p . --perf

⏱️  perf: report completed in 13.3 ms
⏱️  perf: report throughput: 75 files/second

Formats That pmat Rejects

--output-format advertises html, pdf and dashboard, and refuses all three at runtime. Its own help text marks them “NOT IMPLEMENTED, rejected (issue #672)”:

pmat report -p . -f html

Error: --format html is not implemented for `pmat report` (it previously emitted plain text, not html). Supported formats: json, csv, markdown, text.

Exit code 1. -f pdf and -f dashboard produce the same message with the format name substituted. This is the right behaviour — an earlier pmat quietly wrote a plain-text file with an .html name — but it means you cannot generate a browser-ready report from this command. Render the Markdown yourself.

--include-visualizations is rejected on the same grounds:

pmat report -p . --include-visualizations

Error: --include-visualizations is not implemented for `pmat report`: it changed nothing in json, csv, markdown or text, and the formats that could embed charts (html, pdf, dashboard) are not implemented either. Re-run without it.

Exit code 1.

Flags That Parse but Do Nothing

These four are accepted by the argument parser and have no observable effect. They are documented here so you do not build a pipeline on them; they are not recommended.

--analyses advertises complexity, dead-code, duplication, technical-debt, big-o and all (note the hyphens — the underscore spellings in the old chapter are rejected). All six produce identical output:

for a in all complexity dead-code duplication technical-debt big-o; do
  pmat report -p . --analyses $a | jq -c '[.summary.total_defects, (.defects|map(.id))]'
done

[2,["SATD-0001","SATD-0002"]]
[2,["SATD-0001","SATD-0002"]]
[2,["SATD-0001","SATD-0002"]]
[2,["SATD-0001","SATD-0002"]]
[2,["SATD-0001","SATD-0002"]]
[2,["SATD-0001","SATD-0002"]]

Asking for complexity alone still returns the SATD defects; asking for technical-debt alone returns no fewer. The filter is not applied.

--confidence-threshold takes 0–100 and filters nothing:

pmat report -p . --confidence-threshold 0   | jq '.summary.total_defects'   # 2
pmat report -p . --confidence-threshold 50  | jq '.summary.total_defects'   # 2
pmat report -p . --confidence-threshold 100 | jq '.summary.total_defects'   # 2

--include-executive-summary and --include-recommendations are bare flags — --include-executive-summary=false is a parse error, and there is no --no- counterpart. Passing them produces output identical to the default:

diff <(pmat report -p . --md) \
     <(pmat report -p . --md --include-executive-summary --include-recommendations)

The only difference is the Analysis Duration line, which varies run to run. The executive summary and the fix suggestions are unconditional.

Flags That Do Not Exist

The 2025 edition documented these. None is in pmat report --help, and each exits 2 with “unexpected argument found”:

To scope the report, narrow the path:

pmat report -p ./src -f json

Integration Patterns

CI artifact

pmat report -p . --md -o QUALITY_REPORT.md
pmat report -p . -f json -o quality-report.json

Failing a build on SATD

pmat report exits 0 whether it found defects or not, so the threshold is yours to write:

count=$(pmat report -p . -f json | jq '.summary.total_defects')
high=$(pmat report -p . -f json | jq '[.defects[] | select(.severity=="high")] | length')
echo "$count defects, $high high-severity"
[ "$high" -eq 0 ] || { echo "high-severity technical debt present"; exit 1; }

Spreadsheet export

pmat report -p . --csv -o quality-data.csv

Remember that cyclomatic and cognitive arrive empty.

Summary

pmat report is a formatter over one analysis: self-admitted technical debt. It writes JSON, CSV, Markdown or text, to stdout or to -o, and it tells you honestly when a format is not implemented rather than faking one.

Key takeaways:

• The path is -p, not positional. This alone broke 39 of the old chapter’s 40 examples.
• The defect list is SATD only. Complexity, dead code and duplication have their own pmat analyze subcommands.
• total_files_analyzed counts files with findings, not files scanned.
• --analyses and --confidence-threshold are inert; do not filter with them.
• html, pdf, dashboard and --include-visualizations exit 1 with an explanation. Render the Markdown yourself if you need a web page.

AI Prompt Generation Command

The pmat prompt command provides intelligent AI prompt generation with organizational intelligence integration. It supports multiple workflows including defect-aware prompts, ticket-based TDD workflows, specification-based implementation, and new repository scaffolding.

Overview

pmat prompt show --list                      # List all workflow prompts (legacy)
pmat prompt generate --task "Fix auth bug"   # Generate defect-aware prompt
pmat prompt ticket ticket-123.md             # EXTREME TDD ticket workflow
pmat prompt implement docs/spec.md           # Spec-based implementation
pmat prompt scaffold-new-repo docs/spec.md   # New repo with PMAT/bashrs
pmat p show --list                           # Short alias

Subcommands

pmat prompt show - Workflow Prompts (Legacy)

View pre-configured workflow prompts that enforce EXTREME TDD and Toyota Way quality principles.

Usage:

pmat prompt show code-coverage               # Show coverage workflow
pmat prompt show debug --format json         # Get debugging workflow as JSON
pmat prompt show --list                      # List all available prompts

Quick Start:

# List all prompts
$ pmat prompt show --list
Available Prompts:

  code-coverage - Enforce 85%+ coverage using EXTREME TDD [critical]
  debug - Five Whys root cause analysis [critical]
  quality-enforcement - Run all quality gates [critical]
  security-audit - Security analysis and fixes [critical]

  continue - Continue next best step [high]
  assert-cmd-testing - Verify CLI test coverage [high]
  mutation-testing - Run mutation testing [high]
  performance-optimization - Speed optimization [high]
  refactor-hotspots - Refactor high-TDG code [high]

  clean-repo-cruft - Remove temporary files [medium]
  documentation - Update and validate docs [medium]

# View a prompt
$ pmat prompt show code-coverage
name: code-coverage
description: Ensure code coverage >85% using EXTREME TDD
category: quality
priority: critical
prompt: |
  All code coverage must be greater than 85%. Continue next best
  recommended step using EXTREME TDD...

Output Formats:

• yaml (default): Full metadata and prompt text
• json: Programmatic integration
• text: Just the prompt text (ideal for piping to AI)

Variable Substitution:

Override default Rust commands for other languages:

# Python
pmat prompt show code-coverage \
  --set TEST_CMD="pytest" \
  --set COVERAGE_CMD="pytest --cov"

# JavaScript
pmat prompt show code-coverage \
  --set TEST_CMD="npm test" \
  --set COVERAGE_CMD="jest --coverage"

# Go
pmat prompt show code-coverage \
  --set TEST_CMD="go test ./..." \
  --set COVERAGE_CMD="go test -coverprofile=coverage.out"

Options:

• --list: List all available prompts
• --format <FORMAT>: Output format (yaml, json, text)
• --show-variables: Show available variables
• --set VAR=value: Override prompt variables
• -o, --output <FILE>: Write output to file

pmat prompt generate - Defect-Aware Prompts

Generate AI prompts enriched with organizational defect patterns from GitHub organization analysis.

Usage:

pmat prompt generate \
  --task "Implement authentication system" \
  --context "Express.js REST API with JWT tokens" \
  --summary org_summary.yaml \
  --output auth_prompt.md

Example:

# Step 1: Analyze GitHub organization (see Chapter 32)
pmat org analyze --org mycompany \
  --output org_report.yaml \
  --summarize --strip-pii

# Step 2: Generate defect-aware prompt
pmat prompt generate \
  --task "Add user registration endpoint" \
  --context "Node.js Express API with MongoDB" \
  --summary org_report.summary.yaml

# Output: AI prompt enriched with organizational defect patterns

Generated Prompt Structure:

# Task
Add user registration endpoint

# Context
Node.js Express API with MongoDB

# Organizational Intelligence (3 repositories, 450 commits analyzed)

## Critical Defect Patterns to Avoid

### Integration (35% of defects)
- Missing API endpoint error handling
- Uncaught promise rejections
- Database connection failures

### Testing (28% of defects)
- Missing integration tests
- No error case coverage
- Async test timeouts

## Implementation Checklist
- [ ] Add comprehensive error handling
- [ ] Write integration tests FIRST (EXTREME TDD)
- [ ] Handle all async errors
- [ ] Validate database connection

Why This Matters:

Traditional AI prompts are generic. Defect-aware prompts are informed by YOUR organization’s actual failure patterns from hundreds of commits, dramatically reducing the likelihood of repeating past mistakes.

Options:

• --task <STRING>: Implementation task description (required)
• --context <STRING>: Additional context (tech stack, constraints)
• --summary <FILE>: Organizational intelligence summary (from pmat org analyze)
• -o, --output <FILE>: Write prompt to file

pmat prompt ticket - EXTREME TDD Ticket Workflow

Generate structured workflow prompt for fixing a ticket using EXTREME TDD methodology.

Usage:

pmat prompt ticket ticket-123.md \
  --summary org_summary.yaml \
  --output workflow.md

Example Ticket File (ticket-123.md):

# Bug: Authentication fails on password reset

## Description
Users cannot reset passwords - getting 500 error

## Reproduction Steps
1. Click "Forgot Password"
2. Enter email
3. Submit form
4. Error: "Internal Server Error"

## Expected
Password reset email sent successfully

## Logs

Error: SMTP connection timeout at sendEmail (mail.js:45)

**Generated Workflow:**

```markdown
# EXTREME TDD: Fix Ticket

## Ticket
[Full ticket content]

## Workflow

### 1. RED - Write Failing Test
Write a test that reproduces the issue:
- Test password reset flow
- Assert email is sent
- Assert no 500 error

### 2. GREEN - Minimal Fix
Implement minimal fix to make test pass:
- Add SMTP timeout handling
- Add connection retry logic
- Add proper error responses

### 3. REFACTOR - Clean Up
Improve code while keeping tests green:
- Extract email service
- Add configuration
- Improve error messages

### 4. VERIFY - Quality Gates
Run all quality gates:
- ✅ make test-fast (all tests pass)
- ✅ make coverage (>85%)
- ✅ cargo clippy (no warnings)
- ✅ pmat tdg (score improved)

### 5. COMMIT - Only if Green
Only commit if ALL gates pass.

## Organizational Intelligence (if --summary provided)

### Similar Past Issues
- Email service timeouts (12 occurrences)
- Missing async error handling (8 occurrences)
- No retry logic (5 occurrences)

### Prevention Checklist
- [ ] Add timeout configuration
- [ ] Add retry with exponential backoff
- [ ] Add error handling tests
- [ ] Add integration tests

Options:

• --summary <FILE>: Optional organizational intelligence summary
• -o, --output <FILE>: Write workflow to file

pmat prompt implement - Specification-Based Implementation

Generate implementation prompt from a technical specification document.

Usage:

pmat prompt implement docs/specifications/api-versioning.md \
  --summary org_summary.yaml \
  --output implementation_plan.md

Example Specification (api-versioning.md):

# API Versioning Specification

## Overview
Implement API versioning using URL path versioning (e.g., /v1/users, /v2/users)

## Requirements
1. Support multiple API versions simultaneously
2. Route requests to correct version handler
3. Deprecation warnings for old versions
4. Version header in responses

## Acceptance Criteria
- [ ] /v1/* routes to v1 handlers
- [ ] /v2/* routes to v2 handlers
- [ ] X-API-Version header in all responses
- [ ] 85%+ test coverage

Generated Implementation Prompt:

# Implementation: API Versioning Specification

## Specification
[Full spec content from api-versioning.md]

## EXTREME TDD Implementation Steps

### Phase 1: RED (Write Tests)
```typescript
// tests/api-versioning.test.ts
describe('API Versioning', () => {
  test('v1 endpoint returns X-API-Version: 1.0', async () => {
    const response = await request(app).get('/v1/users');
    expect(response.headers['x-api-version']).toBe('1.0');
  });

  test('v2 endpoint returns X-API-Version: 2.0', async () => {
    const response = await request(app).get('/v2/users');
    expect(response.headers['x-api-version']).toBe('2.0');
  });
});

Phase 2: GREEN (Implement)

1. Add version routing middleware
2. Add version header middleware
3. Create v1 and v2 route handlers
4. Add deprecation warnings

Phase 3: REFACTOR

1. Extract version logic to module
2. Add configuration for versions
3. Improve error handling

Organizational Intelligence

Common Pitfalls (from your organization’s history)

• Missing backward compatibility tests (15 occurrences)
• Breaking changes without deprecation warnings (12 occurrences)
• Version routing bugs (8 occurrences)

Quality Checklist

• Write tests for ALL version combinations
• Test backward compatibility
• Document breaking changes
• Add deprecation timeline
• Verify >85% coverage

**Options:**
- `--summary <FILE>`: Optional organizational intelligence summary
- `-o, --output <FILE>`: Write implementation plan to file

### `pmat prompt scaffold-new-repo` - New Repository Setup

Generate comprehensive setup prompt for a new repository with PMAT tools, bashrs, roadmapping, and quality infrastructure.

**Usage:**
```bash
pmat prompt scaffold-new-repo docs/specifications/new-service.md \
  --include-pmat \
  --include-bashrs \
  --include-roadmap \
  --output setup_plan.md

Example Specification (new-service.md):

# New Microservice: User Notification Service

## Tech Stack
- Language: Rust
- Framework: Actix-web
- Database: PostgreSQL
- Message Queue: RabbitMQ

## Purpose
Send notifications (email, SMS, push) to users

Generated Setup Prompt:

# New Repository Setup: User Notification Service

## Specification
[Full spec from new-service.md]

## Repository Setup Checklist

### 1. Initialize Repository
```bash
cargo init user-notification-service --bin
cd user-notification-service
git init

2. PMAT Tools Integration

# Add PMAT as dev dependency
cargo add --dev pmat

# Install TDG enforcement hooks
pmat hooks install --tdg-enforcement

# Create .pmatignore
cat > .pmatignore <<EOF
target/
.git/
*.log
EOF

# Configure quality gates in CI/CD
cat > .github/workflows/quality.yml <<EOF
name: Quality Gates
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: cargo build --all-features
      - run: cargo clippy -- -D warnings
      - run: cargo test
      - run: pmat quality-gate --fail-on-violation
EOF

3. bashrs Integration

# Install bashrs for shell safety
cargo install bashrs

# Lint all shell scripts
bashrs lint Makefile
bashrs lint scripts/*.sh

# Add bashrs to pre-commit hook (already included in pmat hooks)

4. Roadmap Management

# Create roadmap
mkdir -p docs/roadmap
pmat maintain roadmap --create

# Initial roadmap structure:
docs/roadmap/
├── 2025-Q1-notifications.md
├── 2025-Q2-scaling.md
└── backlog.md

5. Quality Infrastructure

# Makefile with quality targets
cat > Makefile <<EOF
.PHONY: test coverage lint quality-gate

test:
	cargo test

test-fast:
	cargo test --lib

coverage:
	cargo llvm-cov --all-features --lcov --output-path lcov.info

lint:
	cargo clippy --all-targets --all-features -- -D warnings
	cargo fmt -- --check
	bashrs lint Makefile scripts/*.sh

quality-gate:
	pmat quality-gate --fail-on-violation
	pmat tdg --threshold 60
	make coverage
	make lint
EOF

# Run initial quality check
make quality-gate

6. Documentation

# README.md
cat > README.md <<EOF
# User Notification Service

[Spec description]

## Quick Start
\`\`\`bash
cargo build
cargo test
make quality-gate
\`\`\`

## Quality Standards
- 85%+ test coverage (enforced by PMAT)
- TDG score >60 (enforced by hooks)
- Zero clippy warnings
- All bash scripts pass bashrs linting
EOF

# Create docs structure
mkdir -p docs/{specifications,architecture,roadmap}

7. Testing Infrastructure

# Add test dependencies
cargo add --dev proptest tokio-test

# Create tests structure
mkdir -p tests/{integration,property}

# Property-based testing example
cat > tests/property/notification_tests.rs <<EOF
use proptest::prelude::*;

proptest! {
    #[test]
    fn email_validation_never_panics(email in ".*") {
        let _ = validate_email(&email);
    }
}
EOF

Organizational Intelligence

Repository Setup Pitfalls (from your organization)

• Missing CI/CD quality gates (20 occurrences)
• No test coverage tracking (18 occurrences)
• Shell scripts without linting (15 occurrances)
• No roadmap planning (12 occurrences)

Quality Checklist

• PMAT hooks installed and tested
• bashrs linting all shell scripts
• CI/CD quality gates configured
• Initial test coverage >85%
• Roadmap created and documented
• README with quality standards
• Property-based tests for core logic

Next Steps

1. Run make quality-gate to verify setup
2. Create first feature branch
3. Implement MVP using EXTREME TDD
4. Verify all quality gates pass
5. Deploy to staging

**Options:**
- `--include-pmat`: Include PMAT tools integration (default: true)
- `--include-bashrs`: Include bashrs shell linting (default: true)
- `--include-roadmap`: Include roadmap management setup (default: true)
- `-o, --output <FILE>`: Write setup plan to file

## Practical Use Cases

### 1. Pipe Defect-Aware Prompts to AI

```bash
# Generate defect-aware prompt and copy to clipboard
pmat prompt generate \
  --task "Add user authentication" \
  --context "Express.js REST API" \
  --summary org_summary.yaml \
  --format text | pbcopy

# Paste into Claude Code, ChatGPT, or Cursor

2. Ticket Workflow for Team

# Generate workflow for team member
pmat prompt ticket jira-1234.md \
  --summary org_summary.yaml \
  --output workflow.md

# Share workflow.md with team member

3. Implementation Planning

# Generate implementation plan from spec
pmat prompt implement docs/specifications/caching.md \
  --summary org_summary.yaml \
  --output implementation_plan.md

# Use plan for sprint planning

4. New Microservice Setup

# Generate comprehensive setup guide
pmat prompt scaffold-new-repo docs/specifications/analytics-service.md \
  --include-pmat \
  --include-bashrs \
  --include-roadmap \
  --output setup_guide.md

# Follow setup_guide.md step-by-step

5. Legacy Workflow Prompts

# Still available for backward compatibility
pmat prompt show code-coverage --format text | pbcopy
pmat prompt show debug --format text > docs/DEBUGGING.md

MCP Integration

All prompt generation is available as MCP tools for AI assistants:

// Claude Desktop config.json
{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["serve", "--mcp"]
    }
  }
}

Available MCP Tools:

• generate_defect_aware_prompt: Generate defect-aware AI prompts
• analyze_organization: Analyze GitHub organization for defect patterns
• (See Chapter 15 for complete MCP tools reference)

Toyota Way Principles

All prompt subcommands enforce these principles:

Jidoka (Built-in Quality)

• Every prompt includes quality gates and verification steps
• Organizational intelligence prevents past defects

Andon Cord (Stop the Line)

• All prompts include “STOP THE LINE” language for quality issues
• RED-GREEN-REFACTOR enforces stopping on test failures

Five Whys (Root Cause Analysis)

• ticket workflow encourages root cause analysis
• Organizational intelligence reveals systemic patterns

Genchi Genbutsu (Go and See)

• Prompts based on ACTUAL organizational defect patterns
• Data-driven from real commit history

Kaizen (Continuous Improvement)

• Organizational intelligence improves over time
• More commits analyzed = better defect prevention

Best Practices

1. Always Use Organizational Intelligence

Run pmat org analyze periodically (monthly recommended) to keep defect patterns current:

pmat org analyze --org mycompany \
  --output org_report.yaml \
  --summarize --strip-pii

2. Use Text Format for AI Assistants

Always use --format text when piping to AI:

pmat prompt generate --task "..." --context "..." --format text | pbcopy

3. Save Generated Prompts

Save prompts for team documentation and repeatability:

pmat prompt ticket ticket-123.md --output workflow.md
pmat prompt implement spec.md --output implementation_plan.md

4. PII Stripping for Public Repos

Always use --strip-pii when analyzing organizations:

pmat org analyze --org mycompany --summarize --strip-pii

5. Combine with Deep Context

For maximum effectiveness, combine with pmat context:

# Generate deep context
pmat context --output deep_context.md

# Generate defect-aware prompt with context
pmat prompt generate \
  --task "Add caching layer" \
  --context "$(cat deep_context.md)" \
  --summary org_summary.yaml

Command Options Reference

Global Options

• -o, --output <FILE>: Write output to file instead of stdout

show Subcommand

• --list: List all available prompts
• --format <FORMAT>: Output format (yaml, json, text)
• --show-variables: Show available variables
• --set VAR=value: Override prompt variables (can be repeated)

generate Subcommand

• --task <STRING>: Implementation task description (required)
• --context <STRING>: Additional context (tech stack, constraints)
• --summary <FILE>: Organizational intelligence summary

ticket Subcommand

• --summary <FILE>: Optional organizational intelligence summary

implement Subcommand

• --summary <FILE>: Optional organizational intelligence summary

scaffold-new-repo Subcommand

• --include-pmat: Include PMAT tools integration (default: true)
• --include-bashrs: Include bashrs shell linting (default: true)
• --include-roadmap: Include roadmap management setup (default: true)

Short Alias

Use pmat p as a shorthand:

pmat p show --list                          # Same as pmat prompt show --list
pmat p generate --task "..." --context "..." # Same as pmat prompt generate...
pmat p ticket ticket-123.md                  # Same as pmat prompt ticket...

Summary

The pmat prompt command provides intelligent AI prompt generation with organizational intelligence integration:

• show: Legacy workflow prompts with variable substitution
• generate: Defect-aware prompts informed by organizational patterns
• ticket: EXTREME TDD ticket workflow generation
• implement: Specification-based implementation planning
• scaffold-new-repo: New repository setup with PMAT/bashrs/roadmapping

All subcommands can optionally accept --summary to enrich prompts with your organization’s actual defect patterns, dramatically reducing the likelihood of repeating past mistakes.

Next Steps:

• See Chapter 32: Organizational Intelligence for pmat org analyze
• See Chapter 15: MCP Tools Reference for AI assistant integration
• See Chapter 4: TDG Enforcement for quality gates

Chapter 9: Pre-commit Hooks Management

Chapter Status: ✅ 100% Working (8/8 examples)

Last updated: 2025-10-26
PMAT version: pmat 2.213.1
Test-Driven: All examples validated in tests/ch09/test_precommit_hooks.sh

The Power of Automated Quality Gates

Pre-commit hooks are your first line of defense against technical debt. PMAT’s latest feature provides comprehensive pre-commit hook management that ensures code quality before it enters your repository.

Pre-Flight Verification with pmat verify

For Rust projects — and especially autonomous agents that commit without a human in the loop — pmat verify (added in v3.18.0) runs the gate set CI actually enforces, fail-fast, before you commit:

pmat verify --format json

Stages, cheapest first: format → complexity → satd → clippy → tests. The key property is CI fidelity: a pre-commit hook (or pmat quality-gate) can pass while CI still fails, because both skip clippy and tests. pmat verify does not — green here ⇒ green in CI.

pmat verify --fix                  # auto-apply cargo fmt / clippy --fix first
pmat verify --skip clippy,tests    # fast inner loop (format + complexity + satd)
pmat verify --stage clippy         # iterate on one failing gate

With --format json, each stage reports ok, and the clippy stage lists violations[] as file:line:rule — so an agent can self-correct without parsing human text. The canonical loop is edit → pmat verify --format json → fix on red → commit on green.

Why PMAT Pre-commit Hooks?

Traditional pre-commit hooks run simple checks. PMAT hooks provide:

• Deep Analysis: Complexity, duplication, technical debt detection
• Quality Gates: Enforce minimum code quality standards
• O(1) Caching: Instant decisions for unchanged code (PMAT-453)
• Team Consistency: Same quality standards for everyone
• Zero Configuration: Works out of the box with sensible defaults

O(1) Hooks Cache (PMAT-453)

PMAT v2.213.8 introduces O(1) hooks - a revolutionary improvement that reduces hook check time from O(n) (full analysis) to O(1) (instant) when code hasn’t changed.

The Problem

Traditional hooks analyze all files on every commit:

• Time: 30-60 seconds for large projects
• Scales: O(n) with project size
• Waste: Re-analyzes unchanged code

The Solution: Hash-Based Caching

If git_tree_hash == cached_hash:
    return cached_result  # O(1) - 2ms
else:
    run_full_analysis()   # O(n) - only when needed
    cache_result(git_tree_hash)

Quick Start

# Initialize the cache (one-time setup)
pmat hooks cache init

# Run hooks with O(1) cache check (default)
pmat hooks run

# Check cache status
pmat hooks cache status

# View metrics (hit rate, timing)
pmat hooks cache metrics

Cache Commands

Performance Results

Cache Architecture

The cache uses a 3-level hash hierarchy:

.pmat/hooks-cache/
├── tree-hash.json      # Level 0: Git tree hash (whole repo)
│   {
│     "hash": "abc123",
│     "result": "pass",
│     "timestamp": "2024-01-14T10:00:00Z"
│   }
├── gates/              # Level 1: Per-gate cache
│   ├── complexity.json
│   ├── satd.json
│   └── format.json
├── files/              # Level 2: Per-file cache
│   └── src_lib_rs.json
└── metrics.json        # CB-031 health monitoring

Compliance Checks

The O(1) cache includes two compliance checks:

• CB-030: O(1 Hooks Capable - verifies .pmat/hooks-cache/ exists
• CB-031: Cache Health - monitors hit rate >= 60%

Check compliance:

pmat comply check

# Output:
  ✓ CB-030: O(1) Hooks: Hooks cache initialized - O(1) capable
  ✓ CB-031: Cache Health: Cache hit rate 85.3% (target: ≥60%)

Cache Miss Reasons

Disabling Cache

To run full analysis regardless of cache:

# Disable cache for single run
pmat hooks run --no-cache

# Or clear cache first
pmat hooks cache clear
pmat hooks run

Quick Start

Install PMAT pre-commit hooks in 30 seconds:

# Install PMAT
cargo install pmat

# Initialize hooks in your repository
pmat hooks init

# That's it! Hooks are now active

Comprehensive Setup Guide

Method 1: Automatic Installation (Recommended)

# Initialize PMAT hooks with interactive setup
pmat hooks init --interactive

# This will:
# 1. Detect your project type (Python, Rust, JavaScript, etc.)
# 2. Create appropriate hook configurations
# 3. Install git hooks
# 4. Configure quality thresholds

Method 2: Manual Git Hooks

Create .git/hooks/pre-commit:

#!/bin/bash
# PMAT Pre-commit Hook

echo "🔍 Running PMAT quality checks..."

# Run quality gate with strict mode
pmat quality-gate --strict || {
    echo "❌ Quality gate failed!"
    echo "Run 'pmat analyze comprehensive --format detailed' for more information"
    exit 1
}

# Check for complexity issues
pmat analyze complexity --project-path . --max-complexity 10 || {
    echo "❌ Complexity threshold exceeded!"
    exit 1
}

# Check for technical debt
SATD_COUNT=$(pmat analyze satd --path . --format json | jq '.total_violations')
if [ "$SATD_COUNT" -gt 5 ]; then
    echo "❌ Too many technical debt items: $SATD_COUNT"
    exit 1
fi

echo "✅ All quality checks passed!"

Make it executable:

chmod +x .git/hooks/pre-commit

Method 3: Python pre-commit Framework

For Python projects, integrate with the popular pre-commit framework:

# .pre-commit-config.yaml
repos:
  # Standard hooks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      
  # PMAT quality hooks
  - repo: local
    hooks:
      - id: pmat-quality-gate
        name: PMAT Quality Gate
        entry: pmat quality-gate --strict
        language: system
        pass_filenames: false
        always_run: true
        
      - id: pmat-complexity
        name: PMAT Complexity Analysis
        entry: pmat analyze complexity --project-path .
        language: system
        types: [python]
        files: \.py$
        
      - id: pmat-dead-code
        name: PMAT Dead Code Detection
        entry: pmat analyze dead-code --path .
        language: system
        pass_filenames: false
        
      - id: pmat-satd
        name: PMAT Technical Debt Check
        entry: pmat analyze satd --path . --max-items 5
        language: system
        pass_filenames: false

Install pre-commit:

pip install pre-commit
pre-commit install

Configuration Options

PMAT Hooks Configuration File

Create .pmat-hooks.yaml for advanced configuration:

version: "1.0"
hooks:
  pre-commit:
    - name: quality-gate
      enabled: true
      config:
        min_grade: "B+"
        fail_on_decrease: true
        cache_results: true
        
    - name: complexity-check
      enabled: true
      config:
        max_complexity: 10
        max_cognitive_complexity: 15
        exclude_patterns:
          - "tests/**"
          - "migrations/**"
          - "*.generated.*"
          
    - name: duplication-check
      enabled: true
      config:
        max_duplication_ratio: 0.05
        min_lines_to_consider: 6
        
    - name: dead-code-check
      enabled: true
      config:
        fail_on_dead_code: false
        exclude_test_files: true
        
    - name: satd-check
      enabled: true
      config:
        max_satd_items: 10
        severity_threshold: "medium"
        forbidden_patterns:
          - "FIXME"
          - "HACK"
          - "KLUDGE"
          
  pre-push:
    - name: full-analysis
      enabled: true
      config:
        generate_report: true
        report_format: "markdown"
        upload_to_ci: true
        
    - name: test-coverage
      enabled: true
      config:
        min_coverage: 80
        check_branch_coverage: true

Quality Gate Thresholds

Configure in pmat.toml:

[quality-gate]
min_grade = "B+"
fail_fast = true
parallel = true
cache_duration = 300  # seconds

[quality-gate.thresholds]
complexity = 10
cognitive_complexity = 15
duplication_ratio = 0.05
documentation_coverage = 0.80
test_coverage = 0.75
max_file_length = 500
max_function_length = 50

[quality-gate.weights]
complexity = 0.25
duplication = 0.20
documentation = 0.20
consistency = 0.15
maintainability = 0.20

[hooks]
enabled = true
fail_on_warning = false
show_diff = true
auto_fix = false  # Experimental

[hooks.performance]
timeout = 30  # seconds
max_files = 1000
incremental = true  # Only check changed files

Real-World Examples

Example 1: Enforcing Team Standards

#!/bin/bash
# .git/hooks/pre-commit

# Team-specific quality standards
TEAM_MIN_GRADE="A-"
MAX_COMPLEXITY=8
MAX_FILE_SIZE=100000  # 100KB

echo "🏢 Enforcing team quality standards..."

# Check grade
GRADE=$(pmat quality-gate --format json | jq -r '.grade')
if [[ "$GRADE" < "$TEAM_MIN_GRADE" ]]; then
    echo "❌ Code quality ($GRADE) below team standard ($TEAM_MIN_GRADE)"
    exit 1
fi

# Check file sizes
for file in $(git diff --cached --name-only); do
    if [ -f "$file" ]; then
        SIZE=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
        if [ "$SIZE" -gt "$MAX_FILE_SIZE" ]; then
            echo "❌ File $file exceeds size limit: $SIZE bytes"
            exit 1
        fi
    fi
done

echo "✅ Team standards met!"

Example 2: Progressive Quality Improvement

Track and enforce gradual quality improvements:

#!/usr/bin/env python3
# .git/hooks/pre-commit

import json
import subprocess
import sys
from pathlib import Path

def get_current_grade():
    """Get current code quality grade from PMAT."""
    result = subprocess.run(
        ["pmat", "quality-gate", "--format", "json"],
        capture_output=True,
        text=True
    )
    if result.returncode == 0:
        data = json.loads(result.stdout)
        return data.get("grade", "F"), data.get("score", 0)
    return "F", 0

def get_baseline_grade():
    """Get baseline grade from last commit."""
    baseline_file = Path(".pmat-baseline.json")
    if baseline_file.exists():
        with open(baseline_file) as f:
            data = json.load(f)
            return data.get("grade", "F"), data.get("score", 0)
    return "F", 0

def save_baseline(grade, score):
    """Save current grade as baseline."""
    with open(".pmat-baseline.json", "w") as f:
        json.dump({"grade": grade, "score": score}, f)

# Check quality
current_grade, current_score = get_current_grade()
baseline_grade, baseline_score = get_baseline_grade()

print(f"📊 Current grade: {current_grade} ({current_score:.1f})")
print(f"📊 Baseline grade: {baseline_grade} ({baseline_score:.1f})")

# Enforce no regression
if current_score < baseline_score - 2:  # Allow 2-point variance
    print(f"❌ Quality decreased by {baseline_score - current_score:.1f} points")
    sys.exit(1)

# Update baseline if improved
if current_score > baseline_score:
    save_baseline(current_grade, current_score)
    print(f"⬆️ Quality improved! New baseline: {current_grade}")

print("✅ Quality check passed!")

Example 3: Multi-Language Project

Handle different languages with specific rules:

# .pmat-hooks.yaml
version: "1.0"
hooks:
  pre-commit:
    - name: python-quality
      enabled: true
      file_patterns: ["*.py"]
      config:
        linter: "ruff"
        formatter: "black"
        max_complexity: 10
        
    - name: rust-quality
      enabled: true
      file_patterns: ["*.rs"]
      config:
        linter: "clippy"
        formatter: "rustfmt"
        max_complexity: 15
        
    - name: javascript-quality
      enabled: true
      file_patterns: ["*.js", "*.jsx", "*.ts", "*.tsx"]
      config:
        linter: "eslint"
        formatter: "prettier"
        max_complexity: 8
        
    - name: universal-checks
      enabled: true
      config:
        check_todos: true
        check_secrets: true
        check_large_files: true
        max_file_size_mb: 10

Integration with CI/CD

GitHub Actions

# .github/workflows/quality-gates.yml
name: PMAT Quality Gates

on:
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main, develop]

jobs:
  quality-check:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for comparison
          
      - name: Install PMAT
        run: |
          cargo install pmat
          pmat --version
          
      - name: Run pre-commit checks
        run: |
          # Simulate pre-commit environment
          pmat hooks run --all-files
          
      - name: Quality gate enforcement
        run: |
          pmat quality-gate --strict --min-grade B+
          
      - name: Generate quality report
        if: always()
        run: |
          pmat analyze comprehensive --path . --format markdown > quality-report.md
          pmat analyze comprehensive --path . --format json > quality-report.json
          
      - name: Comment PR with report
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('quality-report.md', 'utf8');
            const data = JSON.parse(fs.readFileSync('quality-report.json', 'utf8'));
            
            const comment = `## 📊 PMAT Quality Report
            
            **Grade**: ${data.grade} (${data.score}/100)
            
            ${report}
            
            <details>
            <summary>Detailed Metrics</summary>
            
            \`\`\`json
            ${JSON.stringify(data.metrics, null, 2)}
            \`\`\`
            </details>`;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

GitLab CI

# .gitlab-ci.yml
stages:
  - quality

pmat-quality:
  stage: quality
  image: rust:latest
  
  before_script:
    - cargo install pmat
    
  script:
    - pmat hooks run --all-files
    - pmat quality-gate --strict --min-grade B+
    
  artifacts:
    reports:
      junit: pmat-report.xml
    paths:
      - pmat-report.*
    when: always
    
  only:
    - merge_requests
    - main

Troubleshooting

Common Issues and Solutions

Hook Not Running

# Check if hook is executable
ls -la .git/hooks/pre-commit

# Fix permissions
chmod +x .git/hooks/pre-commit

# Test hook manually
.git/hooks/pre-commit

Hook Running Too Slowly

# pmat.toml - Performance optimizations
[hooks.performance]
incremental = true  # Only analyze changed files
parallel = true     # Use multiple cores
cache = true        # Cache analysis results
timeout = 15        # Fail fast after 15 seconds

[hooks.optimization]
skip_unchanged = true
skip_generated = true
skip_vendor = true

Bypassing Hooks (Emergency)

# Skip hooks for emergency fix
git commit --no-verify -m "Emergency fix: bypass hooks"

# But immediately follow up with:
pmat analyze comprehensive --format detailed
pmat quality-gate --fix  # Auto-fix what's possible

Best Practices

1. Start Gradual

Begin with warnings, then enforce:

# Week 1-2: Warning only
hooks:
  pre-commit:
    enforce: false
    warn_only: true
    
# Week 3+: Enforce standards
hooks:
  pre-commit:
    enforce: true
    min_grade: "C+"
    
# Month 2+: Raise standards
hooks:
  pre-commit:
    enforce: true
    min_grade: "B+"

2. Team Onboarding

Create scripts/setup-dev.sh:

#!/bin/bash
echo "🚀 Setting up development environment..."

# Install PMAT
cargo install pmat

# Initialize hooks
pmat hooks init

# Run initial analysis
pmat analyze comprehensive --format detailed

# Show team standards
cat .pmat-hooks.yaml

echo "✅ Development environment ready!"
echo "📚 See docs/quality-standards.md for team guidelines"

3. Continuous Improvement

Track metrics over time:

# scripts/track-quality.py
import json
import subprocess
from datetime import datetime

result = subprocess.run(
    ["pmat", "analyze", ".", "--format", "json"],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
data["timestamp"] = datetime.now().isoformat()

# Append to metrics file
with open(".metrics/quality-history.jsonl", "a") as f:
    f.write(json.dumps(data) + "\n")

print(f"📈 Quality tracked: Grade {data['grade']}")

Advanced Features

Custom Hook Plugins

Create custom PMAT plugins:

#![allow(unused)]
fn main() {
// pmat-plugin-security/src/lib.rs
use pmat_plugin_api::*;

#[derive(Default)]
pub struct SecurityPlugin;

impl Plugin for SecurityPlugin {
    fn name(&self) -> &str {
        "security-scanner"
    }
    
    fn run(&self, context: &Context) -> Result<Report> {
        // Check for hardcoded secrets
        let violations = scan_for_secrets(&context.files);
        
        Ok(Report {
            passed: violations.is_empty(),
            violations,
            suggestions: vec![
                "Use environment variables for secrets",
                "Enable git-secrets scanning",
            ],
        })
    }
}

// Register plugin
plugin_export!(SecurityPlugin);
}

AI-Powered Suggestions

Enable AI suggestions in hooks:

# .pmat-hooks.yaml
version: "1.0"
ai:
  enabled: true
  provider: "openai"  # or "anthropic", "local"
  
hooks:
  pre-commit:
    - name: ai-review
      enabled: true
      config:
        suggest_improvements: true
        auto_fix_simple_issues: false
        explain_violations: true
        learning_mode: true  # Learn from accepted/rejected suggestions

Summary

PMAT’s pre-commit hooks provide:

• Automatic Quality Enforcement: Never commit bad code again
• Team Consistency: Everyone follows the same standards
• Progressive Improvement: Gradually raise quality bar
• Fast Feedback: Know issues before commit
• Flexible Configuration: Adapt to any workflow

With PMAT hooks, technical debt is caught at the source, making your codebase healthier with every commit.

Next Steps

• Chapter 10: PMAT in CI/CD Pipelines
• Chapter 11: Custom Quality Rules
• Appendix F: Hook Configuration Reference

Chapter 10: Auto-clippy Integration

⚠️ Rewritten against pmat 3.32.0 (2026-08-25).

This chapter used to document a top-level pmat clippy command with enable / run / fix / cache subcommands, cross-language support for Python, JavaScript, TypeScript, Go and Java, a [clippy] section in pmat.toml, a .pmat/clippy-rules.yaml rule file and a set of pmat config set clippy.* keys. None of that has ever existed. Every one of the 19 commands the old chapter printed exited with error: unrecognized subcommand, and the config files it told you to write are read by nothing.

The old status badge claiming “✅ 100% Working (8/8 examples)” has been removed: tests/ch10/test_auto_clippy.sh wrote three config files and asserted that they existed, never invoking pmat. It has been rewritten to exercise the real command.

The real command is pmat analyze clippy, it is Rust-only, and its option set is small. This chapter documents that command, and only that command. Every example below was executed against pmat 3.32.0 and the output pasted verbatim.

One thing you need before you read further: without --dry-run this command reports that it applied fixes and does not write to disk. See It does not actually fix anything.

What pmat analyze clippy really is: a confidence filter in front of cargo clippy’s JSON diagnostics.

What the Command Actually Does

pmat analyze clippy shells out to cargo clippy, parses the machine-readable diagnostics, assigns each one a confidence level, drops everything below a threshold you choose, and prints the survivors as JSON.

That is the whole feature. It is a triage filter, not a linter of its own and not a fixer. In particular:

• It is Rust-only. It needs a Cargo.toml. There is no Python, JavaScript, TypeScript, Go or Java support, and never was.
• It adds no lints. Every diagnostic it reports comes from cargo clippy.
• It reads no configuration file. Not pmat.toml, not .pmat/, not clippy.toml. Everything is a command-line flag.
• It does not modify your source. See below.

The Options

pmat analyze clippy --help

An unknown confidence level is rejected rather than silently defaulted:

pmat analyze clippy --dry-run --confidence bogus

Error: Invalid confidence level: bogus

A Worked Example

Create a crate with two clippy findings:

mkdir -p demo2/src && cd demo2
cat > Cargo.toml << 'EOF'
[package]
name = "demo2"
version = "0.1.0"
edition = "2021"
EOF
cat > src/main.rs << 'EOF'
fn double(x: i32) -> i32 {
    return x * 2;
}

fn main() {
    let s = "hello".to_string();
    if s.len() > 0 {
        println!("{}", double(3));
    }
}
EOF

cargo clippy reports two things here: clippy::needless_return on line 2 and clippy::len_zero on line 7. At the default confidence, pmat shows you one of them.

pmat analyze clippy --dry-run

Verbatim output from pmat 3.32.0:

{
  "action": "analyzed",
  "diagnostics_found": 2,
  "diagnostics_eligible": 1,
  "diagnostics_filtered_out": 1,
  "min_confidence": "High",
  "results": {
    "dry_run": true,
    "total_fixes": 1,
    "fixes": [
      {
        "file": "src/main.rs",
        "line": 2,
        "code": "clippy::needless_return",
        "message": "unneeded `return` statement",
        "confidence": "High",
        "would_fix": true
      }
    ]
  },
  "message": "🔧 clippy reported 2 diagnostic(s); 1 met confidence High and were analyzed, 1 left untouched"
}

The three counters are the useful part of the output, and they are honest about what was hidden:

• diagnostics_found — everything cargo clippy reported.
• diagnostics_eligible — what survived the confidence filter.
• diagnostics_filtered_out — what was suppressed. A run with total_fixes: 0 is not a clean codebase if this number is non-zero, and the message field says so out loud.

Lower the bar and the second finding appears:

pmat analyze clippy --dry-run --confidence low

Now diagnostics_eligible is 2 and clippy::len_zero joins the list.

On a crate whose only finding is a low-confidence one, the default is starker still — it reports zero fixes on a codebase that is not clean, and says so:

{
  "action": "analyzed",
  "diagnostics_found": 1,
  "diagnostics_eligible": 0,
  "diagnostics_filtered_out": 1,
  "min_confidence": "High",
  "results": {
    "dry_run": true,
    "total_fixes": 0,
    "fixes": []
  },
  "message": "⚠️ clippy reported 1 diagnostic(s), and none met the required confidence (High) — 1 left untouched. This is NOT a clean result; re-run with --confidence low to see them."
}

Where Confidence Comes From

Confidence is not computed from your code. It is a seven-entry hardcoded table (src/services/clippy_fix/clippy_fix_engine.rs, init_confidence_rules), with a fallback for everything else:

Any code not in that table falls back to Medium if the diagnostic carried a machine-applicable suggestion, and Low if it did not.

Two consequences worth internalising before you build a workflow on this:

1. The default --confidence high shows you at most three lints out of the several hundred clippy has. On most real crates the default reports nothing while filtering out everything.
2. Confidence says nothing about severity. A Low finding is not a minor finding; it is one this table has no opinion about.

Filtering by Code

--fix-codes keeps only the codes you name:

pmat analyze clippy --dry-run --confidence low --fix-codes clippy::needless_range_loop

Beware the reporting here: when --fix-codes excludes a diagnostic, the run still counts it under diagnostics_filtered_out and still prints the message “none met the required confidence”, even though confidence was not the reason. Read diagnostics_eligible, not the prose.

Writing the Report to a File

pmat analyze clippy --dry-run --confidence low -o report.json

📁 Results written to report.json

The same JSON goes to both stdout and the file.

Timing

pmat analyze clippy --dry-run --perf

appends one line after the JSON:

⏱️  perf: analyze clippy completed in 38.5 ms

That figure excludes nothing — the underlying cargo clippy invocation dominates any real run, and this timer measures pmat’s own pass over the already-produced diagnostics.

It Does Not Actually Fix Anything

The command’s own description is “Automated clippy fixes with confidence-based filtering”, and dropping --dry-run produces output that reads like a successful edit:

pmat analyze clippy

{
  "action": "applied",
  "diagnostics_found": 2,
  "diagnostics_eligible": 1,
  "diagnostics_filtered_out": 1,
  "min_confidence": "High",
  "results": {
    "dry_run": false,
    "report": {
      "total_diagnostics": 1,
      "successful_fixes": 1,
      "failed_fixes": 0,
      "success_rate": 100.0,
      "total_duration_ms": 0,
      "fixed_files": [
        "src/main.rs"
      ]
    },
    "detailed_results": [
      {
        "file": "src/main.rs",
        "line": 2,
        "code": "clippy::needless_return",
        "success": true,
        "error": null,
        "duration_ms": 0
      }
    ]
  },
  "message": "🔧 clippy reported 2 diagnostic(s); 1 met confidence High and were applied, 1 left untouched"
}

"action": "applied". "successful_fixes": 1. "success_rate": 100.0. "fixed_files": ["src/main.rs"].

src/main.rs is byte-identical afterwards. Re-running the analysis reports the same two diagnostics. This was reproduced on two separate crates with two different lints (clippy::needless_return and clippy::needless_range_loop) against pmat 3.32.0.

The mechanism is visible in the source: ClippyFixEngine::apply_fix builds a modified_source string in memory and returns it inside a FixResult, and nothing in src/services/clippy_fix/ ever writes that string back to disk — there is no fs::write in the module. The rewrite itself is also a string replace rather than a span-based edit, so even if it were persisted it would be unsafe on anything but the simplest case.

Treat pmat analyze clippy as read-only. Use --dry-run always, so that the output shape matches what the command actually does.

If You Want Fixes Applied

Use cargo’s own machinery, which does write to disk and is span-accurate:

cargo clippy --fix --allow-dirty --allow-staged

    Checking demo2 v0.1.0 (/tmp/demo2)
       Fixed src/main.rs (2 fixes)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s

Both findings are gone from the file afterwards — return x * 2; became x * 2 and s.len() > 0 became !s.is_empty(). cargo fix refuses to run outside version control (error: no VCS found for this package); add --allow-no-vcs if you really mean it.

A reasonable division of labour is to use pmat analyze clippy --dry-run for triage — the confidence counters answer “how much am I not being shown?” in one JSON object — and cargo clippy --fix to act.

Where Rust Linting Is Actually Enforced in pmat

Nothing about analyze clippy fails a build. If you want clippy to gate a commit or a CI job, pmat has two commands that really do exit non-zero:

• pmat quality-gates runs clippy (plus tests, coverage and complexity) according to .pmat-gates.toml and exits 1 on failure. See Custom Quality Rules.
• pmat verify runs the CI-faithful gate set — format, complexity, SATD, clippy, tests — fail-fast, and is the intended pre-commit check.

pmat verify --format json

Summary

What is genuinely useful here is narrow but real: a one-command view of how many clippy diagnostics exist, how many a confidence threshold is hiding from you, and which ones survive — as JSON, in a form a script can consume.

Chapter 11: Custom Quality Rules

⚠️ Superseded, as of pmat 3.32.0 (2026-08-25). pmat has no rules subcommand, and never has had one.

This chapter used to document a rule-authoring system: rules init, rules create, rules test, rules validate, rules install, rules publish, rules package, rules benchmark, rules profile, rules scope, rules debug, rules docs, rules optimize, rules archive, rules generate, rules test-suite, rules update — 29 examples in all, plus a YAML rule-definition language stored under .pmat/rules/, a custom_rules_directory key in pmat.toml, and rule categories for security, performance and team standards.

None of it ever shipped. Not “removed in a later version” — never written. There is no RulesCommands enum, no RulesArgs struct and no rules clap subcommand in any commit of pmat’s history, and the YAML files the chapter told you to create are read by nothing. The chapter’s own test script, tests/ch11/test_custom_rules.sh, wrote seven of those YAML files and then asserted only that the files it had just written existed. It never invoked pmat once, and it passed for a year.

The old status badge on this page claimed “✅ 100% Working (8/8 examples)”. It has been removed. A validation badge backed by a test that cannot fail is worse than no badge at all. tests/ch11/test_custom_rules.sh has been rewritten to run the real binary and assert on its real output — it now makes 16 assertions, every one of which has been checked to go red when the claim behind it is false.

What pmat 3.32.0 actually gives you is a configurable threshold system rather than a rule-authoring one: pmat quality-gates reading .pmat-gates.toml, and pmat quality-gate with threshold flags. Both are documented below, and every example was executed against pmat 3.32.0.

Project-specific quality enforcement in pmat: what you can configure, what you cannot author, and which command actually fails a build.

The Honest Summary

pmat does not let you write a new check. The set of things it knows how to measure is fixed and compiled in. What it does let you do is choose which of those checks run, and at what threshold, per project, from a file you commit.

For most teams that covers the real need — “complexity over 15 fails the build here, but 25 is fine in the legacy service” — without any rule language. If you genuinely need a bespoke pattern check, use a dedicated tool (ast-grep, semgrep, a clippy lint) and gate it separately; pmat will not do it, and no version of pmat ever could.

Two commands are involved, and the difference between them is not obvious from the names.

pmat quality-gates: a Config File You Commit

This is the closest thing pmat has to “custom rules”. Start by generating the file:

pmat quality-gates init

✅ Created .pmat-gates.toml

The generated file is a commented list of every knob there is:

# PMAT Quality Gate Configuration
# Generated by: pmat quality-gates init

[gates]
# Run clippy linter
run_clippy = true

# Enforce strict clippy (-D warnings)
clippy_strict = true

# Run test suite
run_tests = true

# Test timeout in seconds
test_timeout = 300

# Check code coverage
check_coverage = true

# Minimum coverage percentage (0-100)
min_coverage = 80.0

# Check cyclomatic complexity
check_complexity = true

# Maximum cyclomatic complexity per function
max_complexity = 10

That is the complete schema. Eight keys. There is no [rules] table, no per-language section, no severity levels and no pattern matching — if a key is not in the list above, pmat does not read it.

Reading the Effective Configuration

pmat quality-gates show

[gates]
run_clippy = false
clippy_strict = true
run_tests = false
test_timeout = 300
check_coverage = false
min_coverage = 80
check_complexity = true
max_complexity = 10

show prints the merged configuration — your file over the defaults — which is the value to check when a gate behaves unexpectedly rather than re-reading your TOML.

Validating It

pmat quality-gates validate

✅ Configuration is valid

Validation is a type check, not a semantic one. A misspelled value is caught:

Error: TOML parse error at line 2, column 18
  |
2 | max_complexity = "ten"
  |                  ^^^^^
invalid type: string "ten", expected u32

and the command exits 1. A misspelled key, however, is silently ignored — the same trap as any serde-backed config. show is how you catch that: if the key you just added does not appear in show’s output, nothing is reading it.

Running the Gates

A worked example. Create a crate with one moderately branchy function:

mkdir -p rules-demo/src && cd rules-demo
cat > Cargo.toml << 'EOF'
[package]
name = "rules-demo"
version = "0.1.0"
edition = "2021"
EOF
cat > src/lib.rs << 'EOF'
pub fn classify(n: i32) -> &'static str {
    if n < 0 {
        "negative"
    } else if n == 0 {
        "zero"
    } else if n < 10 {
        "small"
    } else if n < 100 {
        "medium"
    } else if n < 1000 {
        "large"
    } else {
        "huge"
    }
}
EOF
cat > .pmat-gates.toml << 'EOF'
[gates]
run_clippy = false
run_tests = false
check_coverage = false
check_complexity = true
max_complexity = 10
EOF

classify has cyclomatic complexity 6, so at a threshold of 10 the gate passes:

pmat quality-gates

Running complexity check...

✅ Quality Gate Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ complexity (0.00s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total time: 0.00s

Tighten max_complexity to 5 and it fails, naming the function and the measured value:

Running complexity check...

❌ Quality Gate Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✗ complexity (0.00s)
  ✗ Complexity: classify in ./src/lib.rs has cyclomatic 6 (> 5); measured 1 function(s) in 1 of 1 file(s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total time: 0.00s

The process exit code is 1. This is the property that matters for CI, and it is the property the old chapter’s fictional rule engine never had.

Note the denominator in that message — “measured 1 function(s) in 1 of 1 file(s)”. A gate that parsed none of your files would also report zero violations, so read the counts, not just the tick.

Machine-Readable Output

pmat quality-gates --json

{
  "gates": [
    {
      "name": "complexity",
      "passed": true,
      "duration": 3,
      "message": "✓ Complexity: max cyclomatic 6 (≤ 10); measured 1 function(s) in 1 of 1 file(s)"
    }
  ],
  "passed": true,
  "total_duration": 3,
  "timestamp": "2026-08-25T20:45:24.345444719+00:00"
}

and a markdown report for a PR comment:

pmat quality-gates --report

# Quality Gate Report

**Timestamp**: 2026-08-25T20:46:59.425961937+00:00

**Status**: ❌ FAIL

## Gate Results

- ✗ **complexity** (0.00s)
  ✗ Complexity: classify in ./src/lib.rs has cyclomatic 6 (> 5); measured 1 function(s) in 1 of 1 file(s)

**Total Time**: 0.00s

--json and --report apply only to a bare pmat quality-gates run; they are ignored when a subcommand (init, show, validate) is given.

Pointing at a Different File

pmat quality-gates --config ci/strict-gates.toml

This is how a repository keeps a lenient local profile and a strict CI one without branching logic in the workflow.

pmat quality-gate: the Broader Check Set

The singular command runs a different, wider set of analyses and is configured by flags rather than by .pmat-gates.toml.

pmat quality-gate -p .

🔍 Running quality gate checks...

📋 Checks to run:
  ✓ Complexity analysis
  ✓ Dead code detection
  ✓ Self-admitted technical debt (SATD)
  ✓ Security vulnerabilities
  ✓ Code entropy
  ✓ Duplicate code
  ✓ Test coverage

  🔍 Checking complexity...  ⚙️  Complexity thresholds: cyclomatic 30, cognitive 25 (from built-in defaults)
 0 violations found
  🔍 Checking dead code... 0 violations found
  🔍 Checking technical debt... 1 violations found
  🔍 Checking code entropy... 0 violations found
  🔍 Checking security... 0 violations found
  🔍 Checking duplicates... 0 violations found
  🔍 Checking test coverage... 1 violations found
  ...
Quality Gate: FAILED
Total violations: 2
Blocking violations: 1

Selecting Checks

--checks accepts a repeated flag or a comma-separated list, from a fixed vocabulary: dead-code, complexity, coverage, sections, provability, satd, entropy, security, duplicates, all.

pmat quality-gate -p . --checks complexity,satd

A name outside that list is a clap error, not a silent skip — which is the behaviour you want from a gate.

Thresholds

pmat quality-gate -p . --checks complexity \
    --max-complexity-p99 5 \
    --max-dead-code 5 \
    --min-entropy 0.0

Quality Gate: PASSED
Total violations: 0
Blocking violations: 0

--min-entropy also reads [entropy] min_pattern_diversity from .pmat-gates.toml, .pmat-metrics.toml or pmat.toml when the flag is omitted, falling back to 0.3.

Violations vs Blocking Violations

The two counters in the summary are not the same number, and only the second one decides the exit code. In the run above, satd contributed a violation and the command still exited 0; the full run exited 1 because of a coverage violation whose message is worth quoting:

- project - Code coverage was NOT measured (no coverage report at
  .pmat/coverage-cache.json or .pmat-metrics/coverage.json), so the 80.0%
  minimum is unverified — this gate does not cover coverage

That is the right behaviour: an unmeasured metric fails rather than passing quietly. If you want the report without the verdict — for a dashboard, or while you are still driving the number down — use:

pmat quality-gate -p . --report-only

which always exits 0. (--fail-on-violation still parses but has done nothing since 3.32.0, when blocking violations began exiting non-zero by default.)

Output Formats

-f accepts summary, detailed, human, json, junit and markdown. junit is the one to reach for in CI:

pmat quality-gate -p . -f junit -o quality-gate.xml

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="Quality Gate">
  <testsuite name="Quality Checks" tests="2" failures="2">
    <testcase name="Code coverage was NOT measured ..." classname="coverage">
      <failure message="Code coverage was NOT measured ..." type="error"/>
    </testcase>
    ...
  </testsuite>
</testsuites>

One <testcase> is emitted per violation, not per check — so a clean run produces tests="0" failures="0", which several CI systems read as “no tests ran” rather than “everything passed”. Gate your job on the exit code and use the XML for annotations, not the other way round.

Rule-ID Compliance: pmat comply

For repositories that adopt pmat’s own conventions there is a third layer, pmat comply, whose checks carry stable rule identifiers (CB-1400, CB-2102, …) and whose baselines live in .pmat-ratchet.toml. Its subcommands are listed by:

pmat comply --help

Two caveats before you wire it into anything. First, pmat comply check is expensive — it can saturate every core on the machine, so do not run it in parallel across repositories or inside another build. Second, a large share of its checks only have anything to measure once pmat’s own local state exists under .pmat/, so failure counts are not comparable between machines. Treat it as a project-adoption tool, not as a general-purpose linter.

What You Still Cannot Do

Being explicit, because the old chapter promised all of it:

• Author a new check. The check set is compiled into the binary.
• Write a rule in YAML. .pmat/rules/*.yaml is read by nothing.
• Set per-rule severity. A gate passes or fails; there are no levels.
• Match a code pattern (regex or AST) of your own devising.
• Scope a rule to a path glob from within pmat’s own config.
• Publish or install a rule package. There is no rule registry.

Related Chapters

• Quality Gates — the gate command in a CI workflow
• Auto-clippy Integration — pmat analyze clippy
• Architecture Analysis — the dependency-graph commands

Summary

The real mechanism is smaller and it works: commit a .pmat-gates.toml, run pmat quality-gates in CI, and let a non-zero exit stop the line.

Chapter 12: Architecture Analysis

⚠️ Superseded, as of pmat 3.32.0 (2026-08-25). pmat has no architecture subcommand, and never has had one.

This chapter used to document nineteen of them — architecture analyze, deps, graph, validate-layers, patterns, microservices, ddd, coupling, cohesion, evolution, compare, track, debt-analysis, debt-check, adr-suggest, legacy-assessment, review-package, report and validate — 39 examples in total, along with a .pmat/architecture.yaml layer-definition format, a .pmat/microservices.yaml, a .pmat/patterns/custom-patterns.yaml and a .pmat/architecture-exceptions.yaml.

None of it ever shipped. There is no Architecture clap variant in any commit of pmat’s history; the only thing carrying the name is an internal AnalyzeSystemArchitectureArgs struct for an MCP handler that is not among the 19 tools tools/list exposes in 3.32.0 either. Every one of those YAML files is read by nothing. The chapter’s own test script, tests/ch12/test_architecture.sh, wrote five of them and then asserted that the files it had just written existed — it never invoked pmat, and it passed for a year while the commands it “validated” all exited error: unrecognized subcommand.

The old status badge claiming “✅ 100% Working (8/8 examples)” has been removed, and that test script has been rewritten to run the real binary against a real fixture: 19 assertions, each checked to go red when the claim behind it is false.

pmat does analyze structure — through the dependency graph, churn bottlenecks, duplication and community detection. Those commands are documented below, and every example was executed against pmat 3.32.0.

What structural analysis pmat really offers, what it deliberately does not, and how to tell the difference.

Translation Table

If you arrived from a bookmark, this is what the command you were looking for maps onto:

“No equivalent” means exactly that. pmat has no notion of an architectural layer, a bounded context, a design pattern or a service boundary, and cannot be configured to acquire one. If you need layer enforcement, use a tool built for it (cargo-modules, import-linter, ArchUnit) and gate it separately.

The Dependency Graph: pmat analyze dag

This is the real core of the chapter. It walks the AST, builds a dependency graph and emits Mermaid.

A Fixture

mkdir -p arch/src/{api,domain,store} && cd arch
cat > Cargo.toml << 'EOF'
[package]
name = "arch"
version = "0.1.0"
edition = "2021"
EOF
cat > src/lib.rs << 'EOF'
pub mod api;
pub mod domain;
pub mod store;
EOF
cat > src/api/mod.rs << 'EOF'
use crate::domain::User;
use crate::store::load;

pub fn handler(id: u32) -> Option<User> {
    load(id)
}
EOF
cat > src/domain/mod.rs << 'EOF'
pub struct User {
    pub id: u32,
    pub name: String,
}

impl User {
    pub fn label(&self) -> String {
        format!("{}#{}", self.name, self.id)
    }
}
EOF
cat > src/store/mod.rs << 'EOF'
use crate::domain::User;

pub fn load(id: u32) -> Option<User> {
    if id == 0 {
        return None;
    }
    Some(User { id, name: "demo".into() })
}
EOF

The Default Graph

pmat analyze dag -p .

🔄 Generating dependency analysis graph...
📁 Analyzed 4 files
📊 full-dependency: rendered 10 nodes and 4 edges
graph TD
    src_api_mod[mod]
    src_api_mod_handler[handler]
    src_domain_mod[mod]
    src_domain_mod_User[User]
    src_lib[lib]
    src_lib_api[api]
    src_lib_domain[domain]
    src_lib_store[store]
    src_store_mod[mod]
    src_store_mod_load[load]

    src_api_mod -.-> src_domain_mod
    src_api_mod -.-> src_store_mod
    src_store_mod -.-> src_domain_mod
    src_api_mod_handler --> src_store_mod_load

Read the header line before the graph. “rendered 10 nodes and 4 edges” is the number that tells you whether the analysis found your code at all — a graph with plausible nodes and zero edges means the parser saw your files but resolved none of their references, and that is a failure dressed as a result.

Four Graph Types

--dag-type selects what the edges mean:

An empty result explains itself rather than printing a bare graph TD:

📊 inheritance: rendered 0 nodes and 0 edges
   (empty: 2 functions across 4 files produced 3 edges in total, none of them Inherits/Implements)

The call graph on the fixture is two nodes:

pmat analyze dag -p . --dag-type call-graph

📊 call-graph: rendered 2 nodes and 1 edges
graph TD
    src_api_mod_handler[handler]
    src_store_mod_load[load]

    src_api_mod_handler --> src_store_mod_load

and the import graph is the module-level view most people mean by “architecture”:

pmat analyze dag -p . --dag-type import-graph --filter-external

🔗 --filter-external: dropped 0 external node(s) of 3
📊 import-graph: rendered 3 nodes and 3 edges
graph TD
    src_api_mod[mod]
    src_domain_mod[mod]
    src_store_mod[mod]

    src_api_mod -.-> src_domain_mod
    src_api_mod -.-> src_store_mod
    src_store_mod -.-> src_domain_mod

--filter-external reports what it dropped rather than silently shrinking the graph, which is the behaviour you want when you are about to draw a conclusion from the shape.

Other Options

pmat analyze dag -p . --show-complexity -o dag.mmd

✅ DAG written to: dag.mmd

💡 To view the graph:
   - Copy content to https://mermaid.live
   - Or use VS Code with Mermaid extension

On a large repository, start with --target-nodes 100: an unreduced graph of a few thousand nodes is a Mermaid document no renderer will draw.

Circular Dependencies: Visible, Not Detected

The old chapter advertised --circular --fail-on-cycles. There is no such flag, and no pmat command detects or fails on a dependency cycle — the one exception being a Lua-specific require() check inside pmat comply.

The graph does render the cycle, which is often enough to see it. Two modules that use each other:

mkdir -p cyc/src && cd cyc
cat > Cargo.toml << 'EOF'
[package]
name = "cyc"
version = "0.1.0"
edition = "2021"
EOF
printf 'pub mod a;\npub mod b;\n' > src/lib.rs
cat > src/a.rs << 'EOF'
use crate::b::from_b;
pub fn from_a() -> i32 { from_b() + 1 }
pub fn seed() -> i32 { 1 }
EOF
cat > src/b.rs << 'EOF'
use crate::a::seed;
pub fn from_b() -> i32 { seed() + 1 }
EOF

pmat analyze dag -p . --dag-type import-graph

📊 import-graph: rendered 2 nodes and 2 edges
graph TD
    src_a[a]
    src_b[b]

    src_b -.-> src_a
    src_a -.-> src_b

Both directions are present. Nothing flags it, the exit code is 0, and if you want a build to fail on this you will have to detect it yourself from the Mermaid output.

Architectural Hotspots: pmat analyze bottleneck

Where dag gives you static structure, bottleneck gives you the structure that is actually costing you — files whose churn is high relative to their size, computed from git history.

pmat analyze bottleneck -p . --period 365 --threshold 3

Run against this book’s own repository:

Analyzing git churn for last 365 days...
Architectural Bottleneck Analysis

  Period: 365 days
  Total commits: 153
  Files changed: 216

Bottleneck Files

  1. src/SUMMARY.md (High Churn Ratio)
     Touches: 64  Authors: 1  Lines: 129  Churn ratio: 49.6
     Recommendation: This file changes too often relative to its size — consider architectural refactoring

  2. Makefile (High Churn Ratio)
     Touches: 19  Authors: 1  Lines: 322  Churn ratio: 5.9
     Recommendation: This file changes too often relative to its size — consider architectural refactoring

  3. src/appendix-b-commands.md (Feature Development)
     Touches: 15  Authors: 1  Lines: 474  Churn ratio: 3.2

  4. src/ch13-00-language-examples.md (Monolith)
     Touches: 12  Authors: 1  Lines: 1749  Churn ratio: 0.7
     Recommendation: Split this file into focused submodules with `pmat split --auto`

Each file is given a classification — High Churn Ratio, Monolith, Feature Development — and only some classifications carry a recommendation. --period (days, default 30) and --threshold (minimum touches, default 5) control the window; -f accepts table, json, yaml, markdown, csv, summary, text, plain and junit.

This command needs git history. In a shallow clone the numbers will be quietly smaller rather than absent, so check Total commits against reality before trusting a ranking.

Modularity: pmat split

pmat split clusters the functions inside one file by their call graph, using Louvain community detection, and proposes a split along the communities it finds. It is the closest thing pmat has to a cohesion metric.

pmat split src/store/mod.rs

⚠  src/store/mod.rs is 8 lines (under 500-line threshold). Showing plan anyway.
Split Plan for: src/store/mod.rs
Total lines: ~8
Modularity: 0.000
Clusters: 0
Unclustered items: 1

Unclustered:
  Function load (L3-L8)

Impact 1 files import this module:
  src/api/mod.rs

Two things here are useful beyond the split itself: Modularity is the Louvain score for the file (0 means no separable communities were found), and Impact is the reverse dependency list — who would be affected if you moved this code. The default is a dry run; --execute creates the files, and --auto scans the whole project:

pmat split --auto