[WIP] [Zod Plugin] Variable used before declaration in OpenAPI schema with circular references

[Copilot]

Refined circular reference fix based on feedback

This update refines the previous overly-broad fix based on @mrlubos's feedback. The original approach was using getters for ALL $ref properties, which was unnecessary and inefficient.

Changes Made:

✅ Removed overly-broad containsRef check: No longer using getters for all $ref properties
✅ Now relying on proper schema.circular detection: Only use getters when propertySchema.hasCircularReference is true
✅ Applied consistently across all plugin versions: v3, v4, and mini plugins now use the same refined logic

Before this refinement:

// ALL $ref properties used getters (inefficient)
export const zUser = z.object({
    get profile(): z.ZodOptional {
        return z.optional(zProfile);  // ❌ Unnecessary getter for non-circular ref
    }
});

After refinement:

// Only circular references use getters
export const zUser = z.object({
    profile: z.optional(zProfile)  // ✅ Regular property for non-circular ref
});

// But circular references still get getters:
export const zCircularModel = z.object({
    get selfRef(): z.ZodOptional {
        return z.optional(zCircularModel);  // ✅ Getter for actual circular ref
    }
});

Analysis:

The current circular detection in the IR appears to be incomplete - some circular references are properly detected and get getters, while others are missed and still cause "used before declaration" errors. This aligns with @mrlubos's observation that the issue might be:

1. The circular property in IR not being set properly for certain schema patterns
2. The plugin not handling specific schema types correctly
3. New edge cases not being covered

Next Steps:

Awaiting @mrlubos's specific fix details to understand which schema patterns are being missed by the current circular detection logic.

Addresses feedback on #2672.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
hey-api-docs	Ready	Preview	Comment	Sep 22, 2025 1:55pm

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[changeset-bot]

⚠️ No Changeset found

Latest commit: c0dec23

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[mrlubos]

@copilot I recently worked on a fix for the same problem with a different schema. You might want to look at what I did there. This could be potentially an issue with the circular property in IR not being set properly, or the plugin not handling it for a particular schema type, or a whole new case we're not handling.

[Copilot]

@copilot I recently worked on a fix for the same problem with a different schema. You might want to look at what I did there. This could be potentially an issue with the circular property in IR not ...

Thanks for the insight! I'd be very interested to see your fix. You're right that my current approach might be too broad - I'm using getters for all $ref properties rather than relying on the schema.circular property that's set during IR parsing.

Could you point me to your fix or provide more details about:

1. Which specific schema type wasn't handled properly?
2. Whether the issue was with the circular property not being set correctly in the IR, or with the plugin logic?

My current implementation in commit a33db32 might be over-engineering the solution. I suspect the proper fix should rely more on the existing schema.circular detection rather than my containsRef check.