Rule Doc Generator Contracts Laravel Package

Product Decisions This Supports

• Enables consistent, automated documentation for custom static analysis rules (e.g., Rector, PHP-CS-Fixer), reducing manual doc maintenance by 30-50% and ensuring alignment across teams.
• Supports "build vs buy" decision: Adopting this contract-based approach avoids reinventing interfaces for rule metadata, leveraging a proven standard instead of custom code.
• Critical for projects needing internal rule catalogs, IDE integrations, or CI-driven documentation pipelines where structured rule metadata (title, description, code samples) must be programmatically accessible.

When to Consider This Package

• ✅ Adopt when: Building custom rules for Rector/PHP-CS-Fixer and needing auto-generated documentation; requiring framework-agnostic, dependency-minimal interfaces for rule metadata; or integrating with existing doc generators (e.g., custom CI scripts).
• ❌ Look elsewhere when: No existing rule documentation workflow (e.g., manual docs suffice); your project doesn’t use static analysis tools requiring rule metadata; or if you need a full-featured documentation generator (this package only provides contracts, not implementation).
• ⚠️ Note: Low GitHub engagement (17 stars) but minimal impact—safe for dev-only use. Verify downstream tooling (e.g., symplify/rule-doc-generator) is maintained if full automation is needed.

How to Pitch It (Stakeholders)

• Executives: "This lightweight package standardizes rule documentation across our static analysis tools, cutting manual documentation effort by up to 50% while ensuring consistency. It integrates seamlessly with Rector and PHP-CS-Fixer, requiring no runtime overhead—just minimal setup to auto-generate accurate, up-to-date docs for our developers."
• Engineering: "Add it as a require-dev dependency to implement standardized interfaces for your custom rules. By defining metadata like titles and code samples in your rule classes, you can plug into existing doc generators to auto-populate internal wikis or IDE tooltips. Zero dependencies, safe to adopt, and eliminates inconsistent documentation across teams."