v0.3.0

gruff-php 0.3.0 - changed-code gates

analyse can now check the code a change touched or introduced. CI can block new problems while old baseline debt stays visible.

Highlights

• Changed-code scans. analyse now supports --changed-ranges, --since, bare --diff, --diff -, and --changed-scope=symbol|hunk. JSON adds suppressedCount when findings are outside the changed region.
• Ignore rules are easier to debug. paths.ignore now applies to directory scans, explicit files, diff scans, and changed-region scans. JSON adds ignoredPathDetails, and check-ignore explains why a path was skipped.
• Baselines show movement. Baseline reports now split findings into new, unchanged, and resolved. Use --baseline-include-absent when you want resolved entries in the rendered output.
• CI can fail only on new debt. failureConditions: sets count caps, and --fail-on-new fails only findings introduced by the current branch, baseline comparison, or both.
• Configs can inherit presets. extends: gruff.recommended, gruff.starter, gruff.strict, or another YAML file can replace most of a large .gruff-php.yaml.

Breaking Changes

1. complexity.npath is retired

The rule was noisy and overlapped with cognitive, cyclomatic, and nesting checks. Configs that still reference it now fail with an unknown rule id.

# Remove this block
rules:
  complexity.npath:
    enabled: true

Refresh baselines if they contain complexity.npath findings:

vendor/bin/gruff-php analyse --generate-baseline --fail-on none

2. Synthetic design.god-method findings are retired

gruff no longer adds a second design finding when size and complexity rules flag the same method. The original size and complexity findings still appear. There is no config block to remove; refresh baselines if they contain design.god-method.

Other Changes

• 132 rules across 11 pillars. The catalogue drops complexity.npath but adds new dead-code, security, sensitive-data, documentation, and test-quality checks.
• Complexity now focuses on readability. Cognitive complexity errors at 20, nesting depth errors at 4, cyclomatic complexity is a warning, and Halstead plus maintainability index are advisory.
• One root cause gets one score penalty. A method that is long, nested, and cyclomatically complex still shows every finding, but the score no longer charges three times for the same method.
• Fake-green tests now fail error gates. test-quality.no-assertions, test-quality.sut-not-called, and test-quality.tautological-type-assertion are now error.
• More dead-code and secret checks. New rules cover unused internal classes/functions/constants, GCP service-account JSON, and HTTP(S) URLs with embedded credentials.
• Fewer forced public renames. rules.naming.boolean-prefix.options.acceptedBooleanNames lets teams allow names like valid() when changing callers would be too costly.
• Documentation rules are clearer. docs.return-comment now checks useful @return text, docs.missing-param-tag covers documented non-public code, and array<string, mixed>|null JSON bags no longer trigger phpdoc-mixed-overuse.
• Some scans can reuse cached results. .gruff-cache/ stores unchanged-file results for runs without project-wide rules. Use --no-cache to disable it.
• The mission is explicit. README, docs/mission.md, agent instructions, and ADR-017 now tie rule choices to making AI-generated code easier for humans to review.

Upgrade

# 1. Update Composer
composer update blundergoat/gruff-php --with-dependencies

# 2. Confirm the binary version
vendor/bin/gruff-php --version
# gruff-php 0.3.0

# 3. Remove retired rules if present
grep -n "complexity.npath" .gruff-php.yaml || true

# 4. Inspect the new finding and score surface
vendor/bin/gruff-php analyse --fail-on none
vendor/bin/gruff-php summary

If you use a baseline:

vendor/bin/gruff-php analyse --baseline=gruff-baseline.json --fail-on none
vendor/bin/gruff-php analyse --generate-baseline --fail-on none

For pull-request gates:

vendor/bin/gruff-php analyse --diff-vs=origin/main --baseline=gruff-baseline.json --fail-on-new
vendor/bin/gruff-php check-ignore --format=json path/to/file.php

To try presets:

schemaVersion: gruff-php.config.v0.1
extends: gruff.recommended

rules:
  size.method-length:
    threshold: 80

Troubleshooting

Symptom	Fix
Unknown rule id "complexity.npath"	Delete the rules.complexity.npath block.
Baseline mentions complexity.npath or design.god-method	Regenerate the baseline or remove those entries.
--fail-on-new exits during setup	Pass --diff-vs <ref>, --baseline <file>, or both.
A path is skipped even when passed directly	Check paths.ignore; confirm with check-ignore.
CI prints Failed: ... with a threshold message	Fix findings, raise the cap, or baseline reviewed debt.