Linearavel Laravel Package

Technical Evaluation

Architecture fit. This package is a schema-derived client for Linear's GraphQL API, regenerated wholesale from the upstream schema snapshot dated 2026-10-16. It sits in the "external SaaS integration" layer of a Laravel application — not in the domain core — so it should be treated as an anti-corruption boundary: wrap it behind an application-owned interface (a LinearClient port with DTOs) rather than letting generated types leak into controllers, jobs, or Eloquent models. Because generated code is disposable and version-coupled, the wrapper is what makes future version bumps a one-file change instead of a codebase-wide refactor.

Integration feasibility. Low friction. Release 0.2.9 is purely additive and non-breaking: three new optional input fields (inlineAnchorFrom and inlineAnchorTo on CommentCreateInput, origin on IntegrationSettingsInput) and four new enum members (addedToMergeQueue and removedFromMergeQueue on WorkflowTrigger; comment and view on DocumentShareRole). Optional input fields require no consumer changes whatsoever — existing mutation payloads remain valid. Enum widening is also backward compatible at the wire level. The realistic integration effort is near zero; the meaningful work is in the enum-consuming paths (see risk below).

Technical risk. Two risks dominate, neither severe:

1. Enum exhaustiveness. Additive enum members are API-compatible but not always code-compatible. Any match expression, switch, or enum-mapping layer in our codebase that enumerates WorkflowTrigger or DocumentShareRole without a default arm will now throw \UnhandledMatchError or silently fall through when Linear returns addedToMergeQueue or view. This is the single most likely production incident from this upgrade, and it is caused by our code, not the package.
2. Schema drift and pre-1.0 churn. At 0.2.x the package makes no stability guarantees beyond minor-version semantics, and each release is a full regeneration. That means we inherit Linear's schema evolution on the package author's cadence, not ours. A future regeneration could remove or rename fields with the same "rebuild" changelog framing — this release's notes happen to be additive, but the release mechanism is a wholesale schema swap, which is a removal vector.

Notably absent from the notes are any deprecations, removals, or type narrowings — a good signal, but the notes are terse and do not state whether the schema regeneration touched anything outside the listed delta. Verify against the diff rather than trusting the summary.

Key questions.

• Does the package generate native PHP enums, backed enums, or plain string constants? This determines whether enum widening is a compile-time, runtime, or non-event.
• Are the generated types committed to the package, or produced at install time against a live schema? The latter would make builds non-reproducible.
• What is the package's documented cadence and policy for breaking schema changes, and is there a changelog outside these release notes?
• Who owns the schema snapshot date — is 2026-10-16 the latest Linear schema, or is the package already behind?
• Do we currently send CommentCreateInput payloads where inlineAnchorFrom/inlineAnchorTo would materially improve comment anchoring quality (inline review comments), or is this capability we would not use?

Integration Approach

Stack fit. Standard Composer dependency for a Laravel app; no framework-version coupling is implied by the release notes. The relevant fit question is not Laravel compatibility but GraphQL transport: confirm the package's HTTP layer (Guzzle vs. Laravel Http, retry/backoff, timeout config) matches our existing outbound-integration conventions, and that authentication (Linear API keys / OAuth tokens) flows through our existing secrets management rather than package-local config.

Migration path. There is nothing to migrate. Install/upgrade to 0.2.9, then run the two containment checks: (a) grep for exhaustive match/switch over WorkflowTrigger and DocumentShareRole, and (b) confirm the new optional inputs are opt-in only and not defaulted to non-null values that would alter existing mutation behavior. If we do not yet consume WorkflowTrigger (merge-queue events) or DocumentShareRole (document sharing), the upgrade is a no-op and can ride the next routine dependency bump.

Compatibility. Backward compatible with all prior 0.2.x consumers. Forward compatibility is conditional: pin the minor version (^0.2.9 is acceptable; ^0.2 risks absorbing a future regeneration with removals) and treat 0.3.0 as a reviewed upgrade rather than an automatic one.

Sequencing.

1. Land the dependency bump behind the existing client wrapper; no feature work bundled.
2. Add defensive default arms (or an explicit "unknown enum member" passthrough) to all enum-mapping code before enabling any feature that reads WorkflowTrigger or DocumentShareRole.
3. Only then evaluate the new capabilities — merge-queue workflow triggers and document sharing roles — as product surface, with origin on IntegrationSettingsInput as a low-priority nicety for integration attribution.
4. Re-baseline the schema snapshot date in our integration runbook so we can detect drift on the next release.

Operational Impact

Maintenance. The package is a generated artifact, so maintenance cost concentrates in upgrade cadence, not in code we own. Budget a recurring review per release: diff the schema delta, re-run the enum exhaustiveness check, re-verify the wrapper contract. This is cheap (minutes) as long as step 2 above is in place, and expensive (production error paths) if it is not. Because we do not control the upstream schema, schedule these reviews on the package's releases rather than on a calendar.

Support. Support burden is asymmetric: Linear's GraphQL API can begin returning a new enum member or field before we upgrade, and our deserialization layer will fail on values it does not recognize. Mitigation is client-side tolerance — never hard-fail on unknown enum members; map them to an Unknown case and log. The package cannot provide this for us; it is a wrapper responsibility. Internally, designate one owner for the Linear integration so that "package bumped, enum broke" has a clear first responder.

Scaling. GraphQL integrations scale on request shape and rate limits, not on the package. Two practical concerns: query complexity/cost if we fan out per-record calls, and Linear's rate-limit headers. Ensure the package surfaces HTTP status and rate-limit metadata so our jobs can implement backoff and queue-level throttling. If merge-queue triggers (addedToMergeQueue/removedFromMergeQueue) become a webhook-driven feature, the scaling profile shifts from polling to event handling — a meaningfully different operational shape worth planning before adoption.

Failure modes.

• Enum drift on unupgraded clients — highest likelihood, medium impact; mitigated by tolerant deserialization.
• Exhaustive-match crash after upgrade — medium likelihood, high impact (hard failure at runtime); mitigated by default arms.
• Silent field absence — generated models omitting newly added fields until the package is bumped; low impact, degrades feature completeness only.
• Future regeneration with removals — low likelihood per release, high impact when it lands; mitigated by minor-version pinning and a pre-upgrade schema diff.
• Schema snapshot lag — package pinned to 2026-10-16 while Linear's live schema advances; manifests as the first failure mode, not as a distinct one.

Ramp-up. Minimal for any Laravel developer already comfortable with GraphQL clients, but there is a real learning step in the generated-code idiom: which classes are safe to touch, which are regenerated and must never be hand-edited, and where the wrapper boundary sits. Document that boundary explicitly — one page in the integration runbook covering the wrapper interface, the enum-tolerance rule, the upgrade checklist, and the schema snapshot date. Without it, the first engineer to hit an enum crash will patch the generated code and create a merge conflict with the next release.