Lean Package Validator Laravel Package

Technical Evaluation

Architecture fit. This is dev-time release tooling, not runtime code. It has a library API, but the relevant surface for a TPM is the CLI (also distributed as PHAR and Homebrew formula): it validates, creates, updates, and reformats .gitattributes export-ignore entries so that git archive output — which Composer uses for dist package installs — excludes repo artifacts such as tests, CI configs, IDE files, and docs. It never touches the service container, request lifecycle, or application boot, so it sits entirely outside the Laravel application architecture. The "Laravel 13 ready" badge signals framework compatibility; the bundled Boost skills signal usability by AI agents; neither changes the fact that this is pipeline governance, not application code. That means near-zero architectural coupling and near-zero blast radius if removed.

Integration feasibility. High. Install as composer require --dev, expose it as a Composer script (composer validate-gitattributes), invoke it directly in CI, or use the dedicated GitHub Action. Presets cover PHP, Python, Rust, JavaScript, and Go, and custom glob files (.lpv) cover anything else — relevant for polyglot repositories under one standard. There is no service, database, credential, or runtime component to operate.

Technical risk. Low-to-moderate. Low because the only durable artifact is a plain text file under version control and the tool is trivially reversible. Moderate because of ecosystem signals: 19 stars and 0 dependents means it is not validated by peer adoption, and it is a single-maintainer project with bus-factor exposure. PHP 8.2+ is a hard floor, so it cannot gate older branches. Default validation is deliberately non-strict on ordering and alignment, which is good for rollout but means a green result does not guarantee exact formatting. The strongest control, --validate-git-archive, builds a temporary archive from git HEAD and inspects its contents — closest to ground truth, but it adds a git-context requirement to CI. Verify release provenance and the actual available version before pinning.

Key questions.

• Which of our packages ship via git archive/Composer dist, and which travel through pipelines this tool cannot see?
• What is our dist-artifact policy on license, README, and docs (--keep-license, --keep-readme)?
• Who owns .lpv pattern drift when new tooling directories appear across the portfolio?
• Can every CI runner supply the git context required by --validate-git-archive?
• Are we comfortable pinning a low-adoption, single-maintainer dev dependency — and who owns the fallback if upstream stalls?

Integration Approach

Stack fit. It lives cleanly in the dev/CI layer of a standard Composer project with no conflict against PHPUnit/Pest, PHPStan, Pint, or Laravel itself. The output format, .gitattributes, is standardised by git, so there is no proprietary format and no lock-in. Where teams use Laravel Boost or coding agents, the three bundled skills (validate, create, update) give guided flows and lower the human cost of adoption.

Migration path. Non-destructive and incremental. create writes a fresh file, update appends missing export-ignores while preserving existing non-export-ignore rules, reformat normalises an existing file, and validate --diff gives a visual preview. --dry-run and --stdin-input support preview-first workflows. Nothing is rewritten in place unless explicitly requested, so the change can be reviewed like any other config commit.

Compatibility. PHP 8.2+ is the gate — confirm the baseline of every target repo first. Multiple install channels (project dev dependency, global Composer, PHAR, Homebrew, cpx) let developers, CI, and release jobs share one pinned version. Cross-language presets plus custom glob patterns allow one organisational standard across mixed-language repos. With zero published dependents, do not assume output stability across versions; pin and review changelogs on bump.

Sequencing.

1. Baseline read-only: run validate --diff against two or three representative packages; record failures, diffs, and noise level. Commit nothing.
2. Normalise on the lowest-risk package: create or update, review the diff, commit.
3. Tooling: add the dev dependency, add the validate-gitattributes script, document the single command.
4. Non-blocking CI: report-only for a couple of weeks to measure false-positive rate.
5. Blocking CI: promote to required check without strict-order or strict-alignment flags.
6. Release gate: enable --validate-git-archive in release jobs with the license/readme policy applied.
7. Portfolio rollout: extend to all Composer packages; use init/refresh for .lpv where presets don't fit.
8. Steady state: fold validate and periodic .lpv refresh into the release checklist.

Operational Impact

Maintenance. Very low. Version bumps are cheap, there is no runtime to upgrade, and configuration is one .gitattributes plus an optional .lpv. The recurring work is pattern drift: new tooling directories appear and need to be excluded. refresh appends missing preset entries while preserving manual edits, which turns that into a small periodic chore rather than a rewrite. Pin the version and review on major bumps.

Support. No commercial support and a single maintainer. Because the license is MIT and the artifact is human-readable, the fallback cost is trivial — the checks are shell-expressible and a policy document can stand in. Recommendation: assign an internal owner (release engineering) so the team owns the policy and treats the tool as a convenience layer rather than a dependency of record.

Scaling. Effectively unlimited. One invocation per repo, seconds per run, linear in package count. It does not scale with traffic, deploy volume, or runtime load. The real scaling concern is organisational consistency: without a shared .lpv template and a standard script name, patterns will drift package by package.

Failure modes.

• Stale patterns and stale export-ignore entries producing silent false confidence; mitigate with --report-stale-export-ignores plus scheduled refresh.
• Strict-order or strict-alignment options causing avoidable red builds if enabled before the baseline settles.
• --validate-git-archive failing in shallow clones or build contexts without git history.
• Ambiguous policy on --keep-license and --keep-readme causing developers to interpret results differently.
• Local/CI version divergence; pin everywhere.
• Maintainer abandonment; mitigated by reversibility and low replacement cost.
• Coverage gap: it governs git archive/Composer dist tarballs only. Container images, manually zipped exports, and vendored code are out of scope and will be falsely assumed clean.

Ramp-up. Hours, not days. Developers need two facts: run composer validate-gitattributes before pushing, and treat .gitattributes as managed rather than hand-edited. Documentation quality is a strength — every flag is documented in the README, an llms.txt is provided, and the bundled agent skills give step-by-step flows. No new mental model is required beyond understanding that export-ignore decides what the dist archive ships.