Cli Json Lint Laravel Package

Technical Evaluation

Architecture fit. owlcorp/cli-json-lint is not a Laravel package in the conventional sense — there is no service provider, config file, facade, or event surface to bind into the framework. It is a standalone Composer-distributed PHP CLI (Symfony-Console-style) that lints JSON files and returns non-zero exit codes. That means the integration points are process-level: composer.json scripts, CI job steps, Git hooks, and Makefiles. The assessment-pm template's criteria (service provider integration, escape hatch via database/interface contracts, 1.0 API stability signal) largely don't map; the relevant surface is CLI ergonomics and exit-code contract. Treat it as a dev-tooling dependency, not an application dependency — that distinction dominates every risk below.

Integration feasibility. High and low-effort. It installs with composer require --dev, invokes via vendor/bin/..., and has no Laravel, PHP, or framework version coupling beyond the CLI's PHP floor. No application code changes, no migrations, no config publishing. This is essentially the same operational shape as php -l, phpstan, or php-cs-fixer.

Technical risk. The material risks are not integration complexity but ecosystem signals:

• Adoption signal is absent. 0 GitHub stars and an aggregate score of 0.3 mean no meaningful community validation — no third-party blog posts, no Stack Overflow footprint, no peer-production evidence. We would be an early adopter whether we want to be or not.
• Maintainer concentration. No visible multi-contributor pattern in the supplied materials; assume a bus factor of one until verified. For a dev-only tool the blast radius is bounded — worst case is a broken lint step we remove in an afternoon — but the maintenance tax still lands on whoever owns CI.
• Scope ambiguity in "JSON". The single highest-value question: does it accept JSONC (comments, trailing commas), JSON5, or only RFC 8259 strict JSON? Laravel's composer.json, tsconfig.json, and .vscode/*.json are common JSONC offenders. If the linter rejects JSONC, it will be noisy on real repositories, and the "zero-config" pitch erodes quickly.
• Overlap with commodity tooling. json_decode one-liners, jq, ajv, prettier --check, composer validate, and IDE/format-on-save all cover adjacent ground. The package's differentiation is a PHP-native, zero-Node, zero-JQ CI story — that is a real but narrow wedge.
• Security posture. Any lint tool that walks directories and reads files needs predictable path handling (symlink following, ignored directories, working-directory behavior). With 0 stars there is no external scrutiny; read the source before wiring it into untrusted PR CI.

Key questions to answer before adoption:

1. Supported PHP versions and minimum Symfony Console version; is there a stated support policy?
2. Does it parse JSONC/JSON5, and can that be toggled off?
3. Exit-code contract: is 1 used uniformly for lint failure, and are tool errors (bad path, permission) distinguishable from lint failures?
4. File selection semantics: globbing, --ignore support, traversal of node_modules/vendor, symlink behavior.
5. Error message stability — will a minor version change output format and break any log parsers or CI annotations we build on top?
6. Is there a JSON Schema validation mode, or is this strictly syntax only?
7. Release cadence and issue-response history over the last two quarters; who is the successor maintainer if the primary is unavailable?

Integration Approach

Stack fit. Correct fit is dev-dependency plus CI/script invocation. Concretely:

• composer.json require-dev, pinned to a compatible constraint, with the binary invoked from a scripts.lint-json entry.
• A CI step in the existing lint job, alongside php -l, phpstan, and composer validate.
• An optional pre-commit hook, but gate this behind the pilot — hooks that fire on every commit and are wrong about JSONC will be disabled by developers within a week, which is worse than not having them.

It is the wrong fit for runtime use, API request/response validation, or any workflow that needs the linter programmatically from PHP. There is no PHP API surface to call; if we need syntax validation inside application code, use json_decode with JSON_THROW_ON_ERROR.

Migration path. There is no migration — there is nothing to migrate from. The relevant decision is substitution: replace ad-hoc shell checks (grep-based brace counting, jq invocations in CI, per-repo bespoke scripts) with a uniform lint step. Adopt per-repository, not platform-wide, until the pilot returns signal. The exit path is equally trivial — remove the dev dependency and the script entry — which is the main reason this is a low-stakes experiment.

Compatibility. No framework coupling. Any PHP 8.x service or monorepo can consume it, including non-Laravel projects. This is actually an advantage over package-specific alternatives if we want one lint step across polyglot repos: the requirement is only PHP, which we already have.

Sequencing.

1. Pilot (one sprint). Add to a single repo with the messiest JSON surface — the highest-signal test of JSONC handling, globbing, and noise level.
2. CI template change (next sprint, conditional). If the pilot is clean, fold the invocation into the shared CI template for all PHP services, keeping the existing jq/prettier steps until confidence is established. 3.Standardize or roll back (one release cycle). Review upgrade effort and incident count, then either bless it in the platform tooling inventory or remove it and document why.
3. Do not sequence this ahead of any committed roadmap item. It is a quality-of-life improvement, not a delivery unblocker; it should never displace feature work in a planning cycle.

Operational Impact

Maintenance. Low absolute cost, non-zero attribution cost. Someone must own: dependency bumps in composer.json, watching for upstream abandonment (0 stars makes this a realistic near-term outcome), and verifying on a PHP minor upgrade that the binary still runs. Because it is dev-only, a stale version cannot affect production traffic — that materially lowers the priority of remediation.

Support. Self-support is the working assumption. No vendor SLA, no commercial tier, no paid escalation path. Documentation appears thin (the description is a marketing paragraph, not a reference), so the pilot owner should write a short internal README: exact invocation, exit-code semantics, and the JSONC decision. That README is the actual asset — it is what makes the tool safe for other squads to self-serve.

Scaling. Batch mode across directories is the advertised use. Runtime is linear in file count and file size; for typical Laravel repos (hundreds of JSON files, mostly small) this is a sub-second CI step. Watch two edge cases at scale: large fixtures directories containing intentionally malformed JSON (test corpora, snapshot testdata) which will need explicit exclusion, and monorepo traversal into node_modules/vendor if default ignore rules are weak. Verify ignore behavior in the pilot before applying to the monorepo.

Failure modes.

• False positives on JSONC — the most likely cause of abandonment. Mitigate by checking support in the pilot and excluding .vscode/, tsconfig.json, and known JSONC files if unsupported.
• Silent success on bad paths — if a glob matches nothing and the tool exits 0, CI goes green with zero coverage. Confirm behavior and, if needed, wrap with a file-count assertion.
• Exit-code drift across versions — a minor release that changes failure semantics can turn a red build green. Pin to a major and review releases before bumping.
• Security/path traversal — directory-walking tools on untrusted PRs warrant a source read; assume no guarantees until verified.
• Maintainer abandonment — low impact but should be a standing review item, since a dev tool that stops receiving PHP compatibility patches becomes a blocking upgrade chore on the next PHP major.

Ramp-up. Trivial for individual contributors — one command, one documented invocation. The real ramp-up cost is organizational, not technical: getting squads to add the step consistently, agreeing on exclusions, and resisting the urge for each repo to wrap it in a custom script. Keep the invocation identical across repos or the standardization benefit evaporates.

Bottom line for the decision record. This is a small, permissively licensed, narrowly scoped dev tool with a real but modest niche (PHP-native JSON linting without a Node/JQ dependency). It is not a Laravel package, it is not a v1.0-stability bet in the sense the template assumes, and the build-vs-buy question is really a pick-one-commodity-tool question — we should not build a JSON linter, and we should not standardize on a 0-star project either. Recommend a one-repo, one-release-cycle pilot with an explicit rollback criterion (any JSONC false positive that cannot be excluded, or evidence of upstream stagnation) and no roadmap displacement.