Download the PHP package blundergoat/gruff-php without Composer

gruff-php

gruff-php is an opinionated PHP code-quality analyzer. It scans PHP projects, scores findings across quality pillars, and emits reports for terminals, CI annotations, SARIF consumers, static HTML, and a local dashboard. It is heuristic static analysis; run it beside PHPStan, Psalm, PHPUnit, PHP-CS-Fixer, PHPCS, security scanners, and code review, not instead of them.

Mission

gruff-php exists to make AI-generated code safe for a human to sign off on. When a coding agent writes the code, someone who didn't write it still has to read, review, and trust it — and agents routinely produce code that superficially works while quietly misunderstanding the requirement. gruff governs that code so a reviewer can actually verify it does what was asked:

• Legible enough to verify. Complexity and nesting are capped, and every method — public or private — must carry an intent-bearing doc comment that states what it is for, what it returns at the edges, and what the caller must satisfy. The comment gives the reviewer a plain-English contract to check the code against; a doc comment that contradicts the implementation is a signal the change needs a deeper look.
• Secure where the eye fails. Security and sensitive-data rules catch the classes of mistake a human reviewer skims past.
• Tested for real, not padded. Test-quality rules reward genuine assertions and flag low-signal ceremony, so a green suite means the behaviour is actually exercised rather than mocked into a tautology.

Wired into a coding agent's loop — as a pre-commit hook, a CI gate (--fail-on), or the agent's own verification step — gruff pushes the agent to keep producing code a human can confidently approve, not just code that compiles and passes. See docs/mission.md for the full rationale.

Status At A Glance

Requirements

• PHP 8.3+.
• Composer for dependency installation.
• Git only for diff and branch-review modes.
• Infection only when mutation-analysis flags are used.

Runtime dependencies are nikic/php-parser plus Symfony Console, Finder, Process, and Yaml.

Install

Install as a project dev dependency:

From a source checkout:

Quick Start

Commands

Output Formats

analyse --format <fmt> accepts:

report --format <fmt> accepts html and json.

Exit Codes

analyse defaults to --fail-on error.

CI Usage

Generic CI command:

GitHub Actions SARIF jobs can install dependencies, run the analyzer, then upload gruff-php.sarif:

Security-focused gates can bypass adoption baselines:

Configuration

Place .gruff-php.yaml in the project root. analyse, report, and dashboard auto-load it unless --config <path> or --no-config is supplied. Legacy .gruff.yaml files are still auto-loaded when .gruff-php.yaml is absent. Unknown keys and unsupported rule options fail closed.

Use vendor/bin/gruff-php list-rules --format json to inspect supported thresholds and options.

Rules And Pillars

The v0.1 catalogue contains 118 registry rules:

Some dead-code pillar rules keep a waste.* rule-id prefix for historical continuity. Filter by the pillar field from list-rules --format json when the pillar matters more than the rule-id prefix.

Baselines And Changed-Code Scans

Baselines suppress reviewed findings by fingerprint:

Changed-code scans can filter to symbol-aware changed regions and report how many findings were suppressed as out of scope:

Bare --diff compares the working tree to HEAD. --changed-scope=symbol is the default and keeps findings whose own location or enclosing declaration overlaps a changed hunk; use --changed-scope=hunk for strict line-span filtering. JSON output includes top-level suppressedCount when changed-region mode is active.

Branch review compares against a base ref:

Display filters such as --min-severity, --include-pillar, and --exclude-rule reduce rendered output without changing which rules execute.

Mutation Analysis

Mutation analysis is optional. gruff-php can ingest an Infection JSON report or run Infection before ingesting the report path you provide:

The dashboard does not run mutation analysis.

Dashboard

The dashboard serves a local control page and refresh endpoint. It has no authentication and is intended for local development; keep it on loopback unless the network is trusted.

In polyglot repositories, remember that gruff-go, gruff-php, and gruff-py all default to port 8765; use --port when running multiple dashboards at the same time.

Trust Boundary

Default scans are local source inspections. gruff-php parses PHP files and selected project metadata; it does not execute target application code, run tests, query vulnerability feeds, or contact package registries. Git is used only for explicit diff modes. External processes are used for explicitly requested features such as Infection runs. Sensitive-data previews are redacted before they reach terminal, JSON, SARIF, GitHub, Markdown, or HTML output.

Stability Contract

The 0.1.x line treats rule IDs, finding fingerprints, baseline identity, gruff.analysis.v2, gruff.baseline.v1, SARIF rendering, and CLI exit semantics as compatibility-sensitive. Breaking changes should be tagged as a future minor release and recorded in CHANGELOG.md.

How It Compares

Development

Performance checks are available with composer perf; mutation workflows live in scripts/mutation-test-diff.sh and scripts/mutation-test-full.sh. Release steps belong in the release checklist and scripts/bump-version.sh.

Documentation

• Mission
• Changelog
• Contributing
• Security
• Support
• Summary command
• Agent instructions
• Branch review
• Naming conventions

Author

Built by Matthew Hansen.

License

MIT