Gitignore Laravel Package

Technical Evaluation

Architecture fit. civicrm/gitignore is a narrowly scoped, single-responsibility parser for the .gitignore pattern grammar (also usable for sparse-checkout manifests and similar ignore-style files). As a Composer-installable PHP library it slots into a Laravel app with essentially zero architectural ceremony — no service container coupling, no framework assumptions, no runtime dependencies expected beyond standard PHP. That is attractive for a TPM because it means low blast radius: we can consume it inside a service provider, a console command, or a build tool without shaping our app around it. The concern is the inverse of that strength — the package does one thing, so we must confirm it does that one thing correctly, because gitignore semantics (negation ordering, ** globs, trailing-slash directory-only rules, anchoring, escaping) are deceptively hard and are exactly where small parsers fail.

Integration feasibility. Mechanically trivial: composer require, autoload, call. The real feasibility question is packaging hygiene. We need to confirm it is published on Packagist with tagged semver releases, declares a supported PHP range (ideally ^8.1+), and has CI green. A repo under the CiviCRM org with 0 stars and 0 dependents is not disqualifying — CiviCRM is a legitimate, long-lived OSS project — but it signals the package has not been stress-tested by external consumers. We should treat it as "internally maintained utility extracted for reuse," not as a community-vetted library.

Technical risk. Three risks dominate:

1. License (NOASSERTION). This is a hard blocker for a commercial Laravel product. We cannot ship a dependency whose license GitHub cannot classify without legal review. Resolve this first — read LICENSE/composer.json directly; if it is AGPL (plausible given CiviCRM's GPL/AGPL lineage), it may be incompatible with our distribution model entirely.
2. Correctness vs. git. The only acceptable acceptance criterion is behavioral parity with git check-ignore. We need evidence of a test suite derived from git's own ignore-rule test cases; absent that, we own the validation burden.
3. Bus factor / longevity. Likely 1–2 maintainers, release cadence unknown. Mitigated by the code being small enough to vendor or fork, but that must be an explicit contingency, not a surprise.

Key questions.

• What is the actual license, and is it compatible with our distribution?
• Is there a tagged release on Packagist, and what PHP versions are declared?
• Does the parser handle negation ordering, **, directory-only patterns, and escaped #/! identically to git? Is there a golden-file test suite proving it?
• Does it support sparse-checkout cone mode semantics, or only the non-cone pattern list? (These differ materially.)
• Is it a fork/derivative of an existing parser (Symfony Finder's Gitignore, mtdowling), and if so, which one and how far has it diverged?
• Does it expose pattern compilation separately from matching, so we can cache compiled rules?

Integration Approach

Stack fit. Clean fit for a Composer/Laravel stack. There is no Laravel service provider shipped, which is fine — we would write a thin adapter (e.g., GitIgnoreMatcher contract with a CivicrmGitIgnoreAdapter) and bind it in a provider. That adapter boundary is the single most important design decision here: it lets us swap the implementation (or a fork) without touching call sites, which is precisely the insurance a low-adoption dependency requires.

Migration path. Before adopting, audit what we already have. Laravel's Filesystem and symfony/finder both ship ignore-style filtering; if our use case is "respect .gitignore when scanning a directory," we may already have a weaker but sufficient capability. The decision is therefore wrap vs. replace: adopt civicrm/gitignore only where we need precise gitignore semantics (deploy artifact filtering, sparse-checkout tooling, monorepo path selection), and keep it behind the adapter so an existing Finder-based path is a one-class rollback.

Compatibility. Verify the declared PHP constraint against our matrix and confirm no transitive dependency conflicts. Because the surface is small, a worst-case incompatibility is patchable in a fork in hours rather than days. Confirm PSR-4 autoloading and that the public API is stable (i.e., not @internal-marked or pre-1.0 with breaking churn).

Sequencing.

1. License and packaging gate (day 1) — legal sign-off and Packagist/tag verification. Do not proceed past this.
2. Correctness spike (days 2–4) — build a golden-file harness that runs a corpus of path/pattern fixtures through both the package and git check-ignore; measure divergence rate. This is the go/no-go.
3. Adapter + POC (week 2) — implement the contract and wire one real use case (e.g., build artifact exclusion).
4. Promotion decision — adopt, fork-and-vendor, or build in-house, informed by the divergence data.

Operational Impact

Maintenance. Low surface area, low ongoing effort — but unowned upstream effort is the risk. Operating model should assume we may need to fork: pin an exact version, keep the adapter boundary, and record a fork runbook. Because the codebase is small, forking is a realistic, low-cost fallback rather than a crisis.

Support. No commercial support and a thin community. That is acceptable only because the domain is bounded and verifiable — we can validate behavior ourselves against git, which is the authoritative oracle. Escalation path is effectively "fix it upstream via PR, or fork." Budget a small amount of engineering ownership rather than assuming passive consumption.

Scaling. Pure CPU-bound string matching: O(patterns × paths) per scan. Fine for CLI/build/deploy tooling and background jobs; unsuitable for per-request hot paths over large trees. Mitigate by compiling and caching pattern sets once per process and short-circuiting on first match.

Failure modes. The dangerous failure is silent misclassification — a path wrongly treated as ignored (dropped from a deploy, skipped in a scan) or wrongly included (secrets committed, unintended files shipped). This is a correctness failure that surfaces downstream, not an exception we can catch. Secondary failures: license ambiguity blocking a release, and unmaintained upstream drifting from git's evolving semantics. Instrument the matcher with parity tests in CI so drift is caught at build time, not in production.

Ramp-up. Very low for consuming the API; moderate for validating it. Engineers must understand gitignore edge cases to judge the golden-file results, so allocate a day of ramp-up on gitignore semantics plus the test harness. Net: cheap to try, cheap to abandon — which is exactly the profile that justifies a bounded, timeboxed evaluation rather than an open-ended commitment.