fix(server)!: resolve a $ref to a non-object alias component in the response type (#171)

[benjamineckstein]

Closes #171.

The bug

A component that is a bare type: array (or a scalar, or a union) is a type alias, not a Data class, so ModelGenerator deliberately skips it (isNonObjectAlias() -> continue) and it never enters the registry. OperationCollector::responseType() checked the registry only, so a $ref to such a component fell through to the JsonResponse fallback, while the same schema written inline produced DataCollection<int, XData>.

# degraded to JsonResponse                    # typed as DataCollection<int, PetData>
responses:                                    responses:
  "200":                                        "200":
    content:                                      content:
      application/json:                             application/json:
        schema:                                       schema:
          $ref: "#/components/schemas/PetList"          type: array
                                                        items:
components:                                               $ref: "#/components/schemas/Pet"
  schemas:
    PetList:
      type: array
      items:
        $ref: "#/components/schemas/Pet"

Naming the list is the more idiomatic spec, and it was the one that lost its typing.

Why it matters

A JsonResponse return enforces nothing about the body. The scaffold exists so the abstract signature pins the documented shape; when it silently degrades, an implementation can return anything and still satisfy the generated contract.

This was found in the field: a Laravel API generated from a spec whose list endpoints all use named array components returned a paginated envelope ({data, links, meta}) where the spec declared a bare array. Nothing in the chain objected. The generated signature said JsonResponse, so it could not object, and no warning was emitted, so openapi-laravel.unsupported.json reported "unsupported": [].

The fix

1. Resolve the alias. ModelGenerator::aliasSchemaFor() exposes the existing alias machinery (referencedAliasSchema + terminalAliasSchema, which already back property-level rule derivation). responseType() resolves a $ref to a non-object alias to its terminal schema, following an allOf: [{$ref}] chain, then runs the existing shape checks on it. Named array components now type as DataCollection<int, XData> and named union components as a Data-class union.

2. Stop degrading silently. A response whose schema could not be typed, and a success response that does not resolve at all, now reach the diagnostics channel (issue 1.0.0: every silent degradation to mixed or Request must hit the warnings channel #67). The class docblock already promised "every such fallback is surfaced through the warnings channel"; the response path was the case where that was not true. A response declaring no schema stays silent by design: the spec promised no shape, so nothing is lost.

Corpus impact

35 specs rebaseline, each audited in READER_BASELINE_REBASELINED_171 with its measured change. Six gain typed returns:

spec	change
circleci.json	6 array-alias responses -> DataCollection
soundcloud.json	4 array-alias responses -> DataCollection
redocly-museum.yaml	2 array-alias responses -> DataCollection
stripe.json	12 union-alias responses -> Data-class union
dnd5e.json	1 union-alias response -> Data-class union

The other 29 move only because previously silent degradations are now reported. No signature moves the other way - the change can only add typing where JsonResponse stood. The before/after was computed with the frozen baseline recipe and diffed per operation, so each entry is measured rather than estimated.

Gate

composer test (2315 passed, 0 failed), stan (no errors), lint (262 files), deptrac (0 violations), test:type (100%).

Breaking

An operation whose success response $refs a named array or union component changes its generated abstract signature from JsonResponse to DataCollection<int, XData> or a Data-class union. Concrete controllers implementing the old signature must be updated.

Important

Do not merge before the 0.16.0 release PR (#178) lands, or release-please will fold this into 0.16.0. This is intended for 0.17.0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CqTZBkmVyV8QkyzgmpoFNR

[coderabbitai]

Warning

Review limit reached

@benjamineckstein, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 26 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 14faa506-9478-4fbb-9a68-4a37d0e075a9

📥 Commits

Reviewing files that changed from the base of the PR and between b935356 and 7cf2234.

📒 Files selected for processing (7)

• docs/src/content/docs/guides/request-response-bodies.mdx
• src/Emitter/ModelGenerator.php
• src/Emitter/Server/OperationCollector.php
• tests/Corpus/ReaderCorpusBaselineTest.php
• tests/Fixtures/corpus-baseline-v0.11.0.json
• tests/Unit/Emitter/Server/AliasArrayResponseTest.php
• tests/Unit/Emitter/Server/ComponentResponseTest.php

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}