Lean Package Validator Laravel Package

Product Decisions This Supports

• Build vs. buy for release hygiene. The problem it solves — keeping tests, CI configs, IDE files, and docs out of dist archives — is real but low-differentiation. This package is a ready-made, MIT-licensed answer that costs one composer require --dev line. It removes a "we should write a linter for this someday" item from the backlog.
• Dist-size and install-footprint roadmap. Every byte in a published archive is downloaded by every consumer. This package gives you a measurable lever (archive contents before/after) to justify trimming release artifacts, which is otherwise an invisible, never-prioritized improvement.
• Supply-chain and IP surface reduction. Excluding .env samples, CI secrets templates, internal docs, and test fixtures from shipped archives is a security and compliance argument, not just a tidiness one. The --keep-license flag also encodes a licensing policy decision (license file must ship) as an enforceable rule rather than a code-review convention.
• CI gating policy. --validate-git-archive inspects an actual temporary archive built from Git HEAD, which turns "don't let this regress" into a pass/fail signal. This is the difference between a documented convention and an enforced one — a decision worth making explicitly for any package with external consumers.
• Monorepo / polyglot standardization. Presets for PHP, Python, Rust, JavaScript, and Go plus custom glob patterns mean one policy tool can cover several repos rather than one bespoke script per ecosystem. Relevant if the roadmap includes non-PHP services or SDKs.
• Scope and positioning of internal micro-packages. The tool ships a tree --src / --dist-package view, which is a cheap way to show stakeholders what a package actually ships — useful evidence when deciding whether an internal package should be published at all.
• DX and onboarding investment. The create, update, and reformat commands plus a composer validate-gitattributes script mean contributors get a fix command, not a lecture. That's a deliberate choice to reduce review friction over an aesthetic concern.
• Tooling consolidation. It ships a GitHub Action, Composer script integration, cpx support, a PHAR, and Homebrew — so adoption doesn't force a CI provider or install-method decision.
• AI-assisted maintenance readiness. Bundled agent skills for create/update/validate mean the workflow can be delegated to coding assistants without the assistant inventing .gitattributes conventions. Relevant if you're standardizing repo automation for AI contributors.

When to Consider This Package

Adopt when most of the following hold:

• You publish at least one Composer (or other ecosystem) package to a public or shared registry, and consumers install from dist archives.
• Archive contents are currently governed by an ad-hoc, hand-maintained .gitattributes that no automation checks.
• You have CI on GitHub Actions, or can invoke a CLI in CI — the --validate-git-archive mode is the strongest reason to adopt.
• Your team has already had at least one "why is tests/ in the release?" or "why is this internal doc public?" incident.
• You want one policy across multiple languages (presets for PHP/Python/Rust/JS/Go, or a .lpv glob file).
• You need a license-file-ships rule encoded (--keep-license) for compliance reasons.

Look elsewhere or defer when:

• You don't ship archives. Internal applications deployed from a Git checkout gain nothing.
• You need runtime integration. This is a CLI/dev dependency. It has no Laravel service provider, config, or runtime API to build product features on — treat any "Laravel 13 ready" badge as compatibility, not capability.
• Your vendor-risk threshold is strict. 19 stars, zero dependents, and a single maintainer is thin for a hard CI dependency. Mitigations: install as --dev, pin with a lockfile, or use the standalone PHAR/Homebrew channel so it isn't in your dependency graph at all. If your policy forbids single-maintainer dev tools, this fails that gate.
• You need a monorepo splitter. git subtree split / Composer's archive configuration solve a different problem; this validates the result, it doesn't create the split.
• You require enterprise support, SLAs, or a security response process. MIT + one maintainer means you own the failure mode.
• Your archive pipeline isn't Git-based. The --validate-git-archive mode builds from Git HEAD; tarball pipelines built elsewhere need the plain validate mode only.
• Your team won't run it. A validation tool with no CI enforcement is documentation, and you already have documentation.

How to Pitch It (Stakeholders)

For executives (30 seconds). We ship PHP packages whose release archives currently include test suites, CI configuration, and internal documentation. That inflates what every customer and partner downloads and puts files into public artifacts that were never meant to be public. This is a free, MIT-licensed CLI that checks release contents and can fail our build if unwanted files sneak in. Cost is roughly an afternoon of setup, no runtime dependency, and no licensing exposure. The upside is smaller downloads, a smaller public surface, and one fewer manual step that only a senior engineer remembers.

For engineering (the operational case). stolt/lean-package-validator validates .gitattributes export-ignore rules against a preset of common repository artifacts, and can create, update, and reformat that file so nobody hand-edits it. Three things make it worth the slot:

1. --validate-git-archive builds a temp archive from Git HEAD and asserts nothing unwanted is inside — that's a real end-to-end check, not a config-shape check.
2. --diff and --report-stale-export-ignores make failures self-serviceable: you get the expected content and a list of rules pointing at files that no longer exist, so the file can't rot silently.
3. --stdin-input, .lpv config files, and the --preset option mean it fits a pipeline without a bespoke wrapper.

Recommended rollout. Install as a dev dependency (or globally via PHAR/Homebrew so it's not in the dependency graph at all), add "validate-gitattributes": "lean-package-validator validate" to composer.json, then add validate --validate-git-archive to CI as a non-blocking job for one sprint before making it required. Run create on the two or three highest-traffic packages first and measure archive size before and after — that delta is the number to report.

Risks to accept explicitly. Low adoption (19 stars, no dependents) and a single maintainer make this a low-blast-radius but unsupported tool. It is a dev-only CLI, so a breakage blocks CI, not production; pinning the version and having the .gitattributes file itself as the durable artifact (the file is useful with or without the tool) keeps the exit cost near zero. If it's ever abandoned, the rules it generated still work and a 30-line script can replace the check.