mago

name	mago
description	Use when the user mentions Mago, asks to fix Mago errors, or when Mago diagnostic output (patterns like error[lint:...] or warning[analysis:...]) appears in conversation. Guides interpreting PHP linter and analyzer issues and fixing them by category priority.

Mago PHP Linter & Analyzer

Interpret Mago output and fix issues based on category priority. Mago is a high-performance PHP toolchain (linter + analyzer) written in Rust.

Scope: Linter (9 rule categories) and Analyzer (type/semantic checks). Does not cover Formatter, Guard, or Lexer/Parser.

Category Priority

When multiple issues are reported, process them in this danger order:

1. Security — XSS, tainted data, insecure comparisons, literal passwords
2. Safety — eval, FFI, error suppression, shell execution, unsafe finally
3. Correctness — assignment in conditions, missing strict_types, switch/continue bugs
4. Deprecation — deprecated casts, implicit nullable, deprecated syntax
5. BestPractices — loop issues, controller patterns, framework idioms
6. Maintainability — complexity, nesting depth, parameter count, metrics
7. Clarity — empty(), isset(), nested ternary, variable variables
8. Consistency — naming conventions, keyword casing, alternative syntax
9. Redundancy — unused code, self-assignment, redundant modifiers

Analyzer issues (type mismatches, null pointer risks, missing returns, undefined methods/properties) are treated at the same priority level as Correctness (#3).

Within the same category, process by severity: error > warning > note > help.

Fix Strategy

Security / Safety

Fix immediately. Explain the vulnerability or risk to the user. Never auto-suppress without asking.

Correctness / Analyzer

Fix immediately. Explain what the bug would cause at runtime. For analyzer issues, explain what the type system detected and why it's a problem. Common fixes include adding null checks, correcting return types, adding type annotations, or handling missing cases.

Deprecation

Fix immediately. Explain what PHP version deprecated the feature and what the modern replacement is.

BestPractices

Fix, but consider project context. Framework-specific rules only apply when Mago's plugins are enabled — do not infer framework context from the project structure yourself; act on framework-named diagnostics only when Mago reports them. If a rule seems inapplicable, ask the user.

Maintainability

Fix where possible (extract methods, reduce parameters). For metric-based rules (cyclomatic complexity, Halstead, kan defect), explain the metric and suggest refactoring directions rather than applying a single "correct" fix.

Clarity

Fix by rewriting to the clearer form. These improve readability.

Consistency

For auto-fixable rules, suggest mago lint --fix. For non-auto-fixable ones (e.g., naming conventions), apply the fix manually.

Redundancy

Almost all rules are auto-fixable. Suggest mago lint --fix first. For rules where auto-fix is marked as unsafe (e.g., self-assignment with object properties), fix manually with care.

Auto-Fix Protocol

Both linter and analyzer support --fix. Before suggesting auto-fix:

1. Check git staging: run git status --porcelain
2. If dirty: warn the user and suggest committing or stashing first to avoid losing changes
3. If dirty but user explicitly acknowledges the risk: proceed; otherwise wait
4. If clean (or user confirmed): run mago lint --fix and/or mago analyze --fix — run both if issues span linter and analyzer
5. For issues without auto-fix: edit code manually

Suppression Protocol

When an issue might be intentional or the user disagrees with a rule:

1. Never suppress without asking — always present the fix first
2. If the user wants to suppress, explain both options:
   • @mago-expect (strict, recommended) — warns if the issue disappears later, keeping suppressions honest
   • @mago-ignore (lenient) — only emits a note if the suppression becomes unused
3. Format: // @mago-expect lint:rule-name or // @mago-expect analysis:diagnostic-name
4. Multiple issues: // @mago-expect lint:rule-a,rule-b
5. Block-level: place before a function/class to cover the entire block
6. Category aliases: lint (alias: linter), analysis (alias: analyzer, analyser)

Recommend @mago-expect over @mago-ignore by default.

Reference

• Documentation: https://mago.carthage.software/
• Linter rules and categories: https://mago.carthage.software/tools/linter/rules-and-categories
• Analyzer overview: https://mago.carthage.software/tools/analyzer/overview
• Suppressing issues: https://mago.carthage.software/fundamentals/suppressing-issues
• Configuration: https://mago.carthage.software/guide/configuration