magento2-linter

Magento 2 Linter

This skill runs automated code quality checks to verify Magento 2 coding standards compliance.

Related Skills

REQUIRED BACKGROUND: Load magento2-dev-core first — this skill validates code against the coding/security standards that skill defines, and its patterns are what you fix findings with.

Part of the QA trio with magento2-security-scan (deeper vulnerability scanning) and magento2-performance-audit (runtime/infrastructure checks) — run all three before a release. Fix findings using the patterns in magento2-dev-core (or the relevant frontend/backend/Hyvä skill).

Govard-Native Lint Audit Is the Real Gate

govard audit run --checks lint is Govard's persistent, native lint gate for Magento 2 projects and modules, and running it for real is a required step before telling a user a branch is "verified" or "ready to push" — not an optional nice-to-have. Govard v1.64.0 implements two audit checks: lint (PHPCS + PHPStan + the pub/media PHP guard) and profiler (captures the Magento stock profiler CSV through the project's own web server — see "The lint run's pub/media PHP guard" below for the guard, and step 2 for the profiler command); any other --checks value is rejected. A bare local vendor/bin/phpcs/ phpstan invocation (see "Scoping" below) is a fast pre-check to catch obvious problems early — it is not proof the branch is clean, because it can diverge from the native toolchain run in either direction (see "Local Bare-Tool Runs Can Diverge from the Native Toolchain" below). Never substitute a bare-tool "0 errors" for a real govard audit run, and never present local-only results as if they were the real gate having passed.

Work through the audit in this order:

1. Resolve target. --mode (auto, project, module_in_project, or standalone) picks what gets analyzed; auto (the default) classifies the current directory itself — no flag needed for the common case:
   • project: current directory is a Magento project root (bin/magento plus a Magento Composer requirement) with no enclosing module — the whole project is analyzed.
   • module_in_project: current directory is a module (etc/module.xml, or a Composer package of type magento2-module) inside a Magento project — only the module is analyzed, with the whole project mounted read only so its autoloader resolves correctly.
   • standalone: current directory is a module with no Magento project anywhere above it — only the module is analyzed, with its dependencies installed into a scratch worktree. --mode project / --mode module_in_project / --mode standalone all force that classification and fail outright when the directory doesn't support it — useful to catch a misresolved auto guess rather than silently linting the wrong scope.
2. Run it: govard audit run --checks lint (lint is already the default --checks value, so plain govard audit run is equivalent). Add ,profiler plus a --url to also capture a page-profile artifact — govard audit run --checks lint,profiler --url https://<domain>/ — and note that a bare govard audit rerun --session <id> repeats the latest run's check selection, profiler URL included. In --format text (the default) Docker logs stream live (phase start/end, cache state, glint: php X.Y analyzed) and findings are colorized + uncapped on a TTY (piped stays plain + capped at 10); in --format json stdout is a single machine-clean object, diagnostics go to stderr -- keep json for agents, text for humans. A FAILED/CANCELLED run still prints the full summary before exiting non-zero.
3. For standalone iteration only, optionally narrow the PHP matrix with --php 8.1,8.4. --php on project/module_in_project targets is only accepted when it repeats the project's own active stack.php_version — it can't widen or narrow those targets' single-version run.
4. Treat these outcomes distinctly — none of them means "clean code" except the last:
   • unsupported_php — the requested PHP version isn't valid for this target (see "PHP versions" below); no container ran.
   • infra_error — a pull/build/Docker/dependency-resolution/report-schema failure. The run never produced a real lint result; never present this as "no findings." For a standalone target, a dependency-resolution failure while pulling a private Git/Composer dependency is a common cause — see "Standalone Composer Packages Need Isolated Verification" below for the --allow-lint-ssh-agent remedy.
   • cancelled — the run was stopped before completing; not a pass.
   • lint findings — PHPCS/PHPStan findings on an otherwise-completed run. This is the actual signal to act on. Only a completed run with zero findings is a clean result.
5. If the team has configured an external provider (audit.lint.external_providers in the project config), run it explicitly as an additional policy gate, not a substitute for the native run: govard audit run --lint-provider team-ci — team-ci here is just an example name; --lint-provider takes the provider's name directly, and that name and its definition come entirely from the project's own config (there's no bundled vendor-specific provider, and no separate flag for it). An external provider is never inferred and never a fallback for the native backend: an unknown --lint-provider name is an error, and a native failure stays a native failure. A standalone target has no project configuration to source audit.lint.external_providers from, so govard is the only provider available there.
6. Never describe a host-project approximation as standalone matrix proof. Running bare vendor/bin/phpcs/phpstan against a module nested inside a large host project is a fast local pre-check, not evidence of what an isolated standalone matrix run would find — the host project's own vendor//generated/ can hide or fabricate results in either direction (see the isolation notes under "Standalone Composer Packages" below). If the module qualifies as standalone, govard audit run is the authoritative check; fall back to a manual isolated install only when Govard itself isn't available.