fix(zod): correct inline reusable schema emission (missing import + dropped defs)

[z4o4z]

Summary

Two pre-existing bugs in the inline single-file reusable-schema writer (client: 'zod' + override.zod.generateReusableSchemas, with no schemas: directory). Both produce output that does not compile. Found while working on #3467; fixed here independently.

1. Missing import * as zod from 'zod'

The zod client's import is a usage-gated dependency import — emitted only when an operation's generated schema references the zod token. When every operation is a pure-$ref alias, e.g.

export const GetThingResponse = Thing

the client emits no zod import. The inline schema block also skipped it (it keyed off !hasOperations), so the file ended up referencing zod with no import at all.

Now the inline block supplies the import unless an operation actually references zod (mirroring the client's own gate), so there is always exactly one zod import.

2. Dropped definitions for sanitized names

The inline writer seeded reusable refs from builder.schemas, whose name is the sanitized model identifier (__schema0 → _Schema0). The resulting ref #/components/schemas/_Schema0 doesn't exist in components.schemas (the real key is __schema0), so the definition was silently dropped whenever the schema was reachable only from operations — leaving the operation wrapper that references it dangling. (It survived when another component schema referenced it, via transitive expansion, which masked the bug.)

Now it seeds from the raw components.schemas keys, exactly like the per-file writer writeZodSchemasReusable already does (see its comment, added in #3465).

Test plan

• New unit test (write-zod-specs): generateZodSchemasInline emits a schema whose raw name needs sanitizing (__my_data → _MyData)
• New e2e test (generate-spec): a spec whose only operation is a pure-$ref alias yields exactly one from 'zod' import (previously zero)
• Existing inline test (operation that does use zod) still asserts exactly one import — no double-import regression
• Generated output type-checks under strict on zod v3 and v4 for both scenarios
• lint, typecheck, and full orval suite (119 tests) pass

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Ensure Zod import is emitted only when generated operations require it (fixes missing/extra import for pure $ref responses).
  • Fix reusable-schema detection to correctly recognize component schemas from raw spec keys and eliminate leftover reference placeholders.

• Tests

  • Added regression tests for inline schema generation with pure $ref operations and correct Zod import behavior.
  • Added tests for component schema naming edge cases to prevent sentinel markers.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e7211a3b-b184-40ff-8022-88917e480222

📥 Commits

Reviewing files that changed from the base of the PR and between b21c699 and 36cee17.

📒 Files selected for processing (4)

• packages/orval/src/generate-spec.test.ts
• packages/orval/src/write-specs.ts
• packages/orval/src/write-zod-specs.test.ts
• packages/orval/src/write-zod-specs.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• packages/orval/src/write-specs.ts
• packages/orval/src/generate-spec.test.ts
• packages/orval/src/write-zod-specs.ts
• packages/orval/src/write-zod-specs.test.ts

---

📝 Walkthrough

Walkthrough

Seeds reusable Zod schemas from raw spec.components.schemas keys and gates whether the inline import { z as zod } is emitted by scanning operation implementations for a zod token. Adds tests ensuring pure $ref operation responses emit inline component exports, pure-alias response exports, a single zod import, and no __REF_ sentinels.

Changes

Inline Zod Reusable Schemas

Layer / File(s)	Summary
Reusable schema seeding from raw spec components packages/orval/src/write-zod-specs.ts, packages/orval/src/write-zod-specs.test.ts	generateZodSchemasInlineReusable now seeds reusable schemas from raw spec.components.schemas keys (building #/components/schemas/<rawKey> refs) instead of builder.schemas, and returns early only when no component refs exist; test ensures sanitized component names emit expected inline Zod definitions and no __REF_ sentinels remain.
Zod import detection based on operation usage packages/orval/src/write-specs.ts, packages/orval/src/generate-spec.test.ts	writeSpecs now scans operation implementations for a zod token to decide whether the inline zod block should provide the zod binding (avoiding duplicate imports). Adds a regression test verifying inline schema emission, pure-alias operation exports (GetThingResponse = Thing), exactly one from 'zod' import, and absence of __REF_ sentinels.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• orval-labs/orval#3206: Introduced the inline Zod schema generation path that this PR refines further via schema seeding and import logic.
• orval-labs/orval#3465: Modifies the same inline zod generation pipeline and import handling.
• orval-labs/orval#3464: Addresses __REF_ sentinel elimination and emitted imports in Zod reusable-schema writing.

Suggested labels

zod

Suggested reviewers

• melloware
• snebjorn
• soartec-lab

🐰 From raw keys I nibbled through,
Pure $refs hopped and needed glue,
One zod import, no sentinel sight,
Reusable schemas now sleep tight,
Tiny rabbit cheers the fix tonight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically identifies the main fixes: correcting inline reusable schema emission by addressing a missing zod import and dropped definitions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Fixes regressions in inline reusable Zod schema generation by correctly seeding component schema refs from raw OpenAPI keys, and by ensuring the generated output includes exactly one necessary Zod import even when operations are pure $ref aliases.

Changes:

• Seed inline reusable schema refs from raw components.schemas keys to avoid dropping schemas with sanitized identifiers.
• Adjust includeZodImport logic to depend on whether operations actually use the zod identifier.
• Add targeted regression tests for sanitized-name schemas and for pure-$ref operations missing Zod imports.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
packages/orval/src/write-zod-specs.ts	Seeds refs from raw component schema keys to prevent silently dropped schemas.
packages/orval/src/write-zod-specs.test.ts	Adds regression test covering raw-name vs sanitized-name mismatch.
packages/orval/src/write-specs.ts	Makes Zod import emission conditional on whether operations reference zod.
packages/orval/src/generate-spec.test.ts	Adds end-to-end regression test ensuring exactly one zod import for pure-$ref operations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[melloware]

looks like Conflicts now