Lean Package Validator Laravel Package

Product Decisions This Supports

• Lean Package Development Roadmap: Accelerates adoption of "lean package" principles by automating .gitattributes validation, reducing release artifact bloat (e.g., dev files, IDE configs, caches). Aligns with trends toward minimal, dependency-light packages (e.g., micro-libraries, CLI tools).
• Build vs. Buy: Buy for teams already using Git/PHP ecosystems. Avoid reinventing validation logic for .gitattributes or manual checks. Build only if needing custom artifact exclusion rules beyond PHP presets (e.g., multi-language repos).
• CI/CD Pipeline Integration: Enables pre-release validation to block bloated artifacts from entering distribution channels (Packagist, GitHub Releases). Reduces post-release cleanup (e.g., removing vendor/, .idea/ from published packages).
• Open-Source Compliance: Ensures license files (e.g., LICENSE.md) are excluded by default unless explicitly kept, mitigating legal risks in automated releases.
• Developer Experience (DX): Reduces cognitive load for maintainers by:
  • Auto-generating .gitattributes via init/create commands.
  • Visual diffs (--diff) to debug misconfigurations.
  • Agentic-friendly JSON output for CI/CD tooling (e.g., GitHub Actions, custom scripts).
• Multi-Language Support: Extends beyond PHP with presets for Python, Rust, JavaScript, and Go, supporting polyglot teams or monorepos.
• Security: Proactively blocks sensitive files (e.g., .env, composer.lock) from accidental inclusion in releases, aligning with secrets management best practices.

When to Consider This Package

• Avoid if:
  • Your team uses non-Git version control (e.g., Mercurial, SVN).
  • You need fine-grained control over excluded files (e.g., conditional rules based on environment variables). This package uses static glob patterns.
  • Your project does not use Composer (PHP) or equivalent package managers (e.g., npm, pip). The tool is PHP-centric in design.
  • You require dynamic validation (e.g., checking artifacts at runtime vs. build time). This is a pre-release tool.
  • Your artifacts are already minimal (e.g., single-file scripts) and don’t need .gitattributes management.
• Look elsewhere if:
  • You need binary artifact validation (e.g., Docker images, compiled binaries). This tool focuses on source code/repo artifacts.
  • Your workflow relies on custom build systems (e.g., Bazel, custom Makefiles) that handle exclusions differently.
  • You require audit trails for excluded files (e.g., tracking why a file was ignored). This tool doesn’t log decisions.
• Consider alternatives:
  • GitHub Actions: For custom validation logic (e.g., git archive --list + manual checks).
  • Pre-commit hooks: For real-time feedback on .gitattributes changes (e.g., pre-commit + custom script).
  • Packagist/PyPI validation: If your package manager has built-in artifact checks (e.g., Packagist’s exclude-files config).

How to Pitch It (Stakeholders)

For Executives (Business/Strategy)

*"This tool automates the enforcement of 'lean package' principles—reducing the size and complexity of our released artifacts by excluding dev files (e.g., IDE configs, test caches) from distribution. For example, it can cut a PHP package’s release size by 30–50% by omitting vendor/, .idea/, and node_modules/. This aligns with our goals to:

• Improve download speeds for end users (especially critical for CLI tools or libraries).
• Reduce storage costs in package registries (e.g., Packagist, GitHub Packages).
• Minimize security risks by preventing accidental inclusion of sensitive files (e.g., .env, composer.lock).
• Simplify maintenance by auto-generating and validating .gitattributes files, saving engineering time.

It’s a low-effort, high-impact fix for a common pain point in open-source and internal package management. The PHP ecosystem already uses it; we can adopt it as a standard step in our CI/CD pipeline."*

For Engineering (Technical)

*"Problem: Our released packages often include unnecessary files (e.g., vendor/, .phpunit.result.cache), bloating downloads and increasing support overhead for users who accidentally include dev dependencies.

Solution: stolt/lean-package-validator is a CLI tool that:

1. Validates .gitattributes files to ensure standard dev artifacts are excluded from releases.
2. Auto-generates or updates .gitattributes with best-practice rules (e.g., ignore bin/, .github/, tests/).
3. Integrates seamlessly into CI/CD via:
   • Composer scripts (composer validate-gitattributes).
   • GitHub Actions (dedicated action available).
   • Agentic JSON output for programmatic use.

Why now?

• Zero maintenance: MIT-licensed, actively developed (last release: 2026-04-03).
• Multi-language support: Presets for PHP, Python, Rust, JS, Go.
• Proactive security: Blocks accidental inclusion of composer.lock, .env, etc.
• DX win: Reduces manual checks and post-release cleanup.

Proposal:

1. Add to project composer.json as a dev dependency:

   "scripts": {
     "validate-gitattributes": "lean-package-validator validate"
   }
   

2. Run in CI (e.g., GitHub Actions) to block bloated releases:

   - name: Validate lean package
     run: composer validate-gitattributes
   

3. Use lpv init to standardize .gitattributes across repos.

Impact: Faster releases, smaller artifacts, and fewer user complaints about ‘unexpected files.’"*

For Developers (Hands-On)

*"Tired of manually editing .gitattributes or discovering vendor/ in your published package? Lean Package Validator (LPV) automates this with a few commands:

• Validate: Check if your .gitattributes excludes the right files:

  lpv validate
  

• Fix it: Auto-generate or update .gitattributes:

  lpv create  # New file
  lpv update  # Overwrite existing
  

• Debug: See what’s wrong with a diff:

  lpv validate --diff
  

• Customize: Use presets (PHP, Python, etc.) or define your own glob patterns:

  lpv init --preset=Python
  

Pro Tip: Add to your composer.json to run on every release:

"scripts": {
  "post-release": "lpv validate --validate-git-archive"
}

This ensures your git archive matches your .gitattributes—no surprises!"*