Cognitive Code Analysis Laravel Package

Product Decisions This Supports

• Establishing an objective code-quality gate for PHP/Laravel repositories. Cognitive complexity is a more actionable metric for maintainability risk than raw line counts, and this release makes it practical to enforce thresholds in CI without custom scripting.
• Build vs. buy for PR quality tooling. The new Phauthentic/cognitive-code-analysis-github-action@v1 removes the main reason teams would build bespoke complexity-checking workflows. Adopt the action rather than maintaining shell pipelines.
• Roadmap input for technical-debt and refactoring initiatives. Runtime config feedback, threshold-focused defaults, and SARIF/artifact outputs give engineering leadership repeatable evidence of where complexity concentrates and whether refactoring investment is paying down.
• Standardizing developer tooling across repositories. The move to a single canonical phpcca.yaml filename with auto-discovery and init scaffolding supports a consistent, committed configuration story across projects — a precondition for org-wide rollout.
• CI platform strategy. New documented GitHub Actions and GitLab CI integration paths (PR comments, merge-request notes, Code Quality widget, SARIF) let the team choose based on existing pipeline investment rather than tooling constraints.
• Deciding how much PR-time feedback to surface. Configurable annotations, comments, artifacts, and optional threshold-failure behavior let product and engineering agree on whether complexity is advisory or blocking.

When to Consider This Package

Consider adoption when:

• The codebase is PHP/Laravel and the team wants a maintainability signal that complements — not replaces — PHPStan/Psalm or linting.
• CI is already in place (GitHub Actions or GitLab CI) and the team wants low-friction PR feedback with annotations or comments.
• You need a single-binary/PHAR-friendly tool that is easy to pin and run in ephemeral CI runners.
• You want to analyze only changed files in pull requests and produce Markdown or SARIF reports for dashboards or security/code-scanning surfaces.
• You are prepared to commit a phpcca.yaml and treat threshold configuration as a reviewed engineering standard.

Look elsewhere or deprioritize when:

• The primary need is security scanning, type checking, or multi-language coverage — this tool addresses cognitive complexity, not those concerns.
• The organization requires commercial support, SLAs, or vendor-managed hosting.
• Teams will not act on complexity findings; without a remediation workflow, the signal becomes noise.
• You require deep IDE integration or real-time in-editor feedback rather than CI-time reporting.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, high-leverage quality control. The new GitHub Action gives us one-line CI setup for cognitive complexity checks on pull requests, with no bespoke scripts or vendor lock-in. It produces evidence we can use to prioritize refactoring and reduce long-term maintenance cost.

For engineering leadership: 1.11.1 makes the tool operationally credible: a supported GitHub Action, documented GitHub and GitLab CI recipes, a canonical phpcca.yaml with auto-discovery, and startup output showing which config and cache state are active. Defaults now filter to methods exceeding the threshold, so reports are quieter and more actionable. Migration from 1.11.0 is low-risk — rename the config file, note the new init output, and be aware of the default filtering change — and there are no breaking CLI changes.

For engineering teams: Adopt via bin/phpcca init, commit phpcca.yaml, and wire the GitHub Action with post-comment, emit-annotations, and optional artifact upload. Start advisory, then promote to a blocking threshold once the baseline is understood. Use SARIF where code-scanning dashboards already exist.