Fix IR.Context and IR.ReferenceObject self-referencing types

[Copilot]

After v0.86, the DTS bundler (rolldown-plugin-dts) generates self-referencing type aliases in the IR namespace, causing TypeScript to resolve IR.Context and IR.ReferenceObject as any.

Root cause: The bundler incorrectly resolves IRContext (imported as alias) to Context within the namespace scope, creating circular references:

// Before (generated)
declare namespace IR$1 {
  export type Context<Spec extends Record<string, any> = any> = Context<Spec>;  // self-reference → any
  export type ReferenceObject = ReferenceObject;  // self-reference → any (source bug)
}

Changes:

• Restructured imports to avoid bundler confusion: import type { Context as IRContext } → import type { Context } with explicit alias type IRContext<Spec> = Context<Spec>
• Imported ReferenceObject from OpenAPI spec types and created alias type IRReferenceObject = ReferenceObject
• Updated namespace exports to reference the aliases

Result:

// After (generated)
type IRContext<Spec$1 extends Record<string, any> = any> = Context<Spec$1>;
type IRReferenceObject = ReferenceObject;

declare namespace IR$1 {
  export type Context<Spec extends Record<string, any> = any> = IRContext<Spec>;  // proper type
  export type ReferenceObject = IRReferenceObject;  // proper type
}

Side effect: Proper typing exposed existing bug in debug/ir.ts where optional operation.operationId was accessed without null check. Fixed with ?? operation.id fallback.

Related: sxzz/rolldown-plugin-dts#115

Original prompt

---

This section details on the original issue you should resolve

<issue_title>IR.Context is incorrectly typed with recursive any after 0.86</issue_title>
<issue_description>### Description

This is similar to #2896. Before 0.86, the generated type for IR$1.Context was:

declare namespace IR$1 {
  ...
  export type Context<Spec extends Record<string, any> = any> = IRContext<Spec>;
  ...
}

After 0.86, it becomes:

declare namespace IR$1 {
  ...
  export type Context<Spec extends Record<string, any> = any> = Context<Spec>;
  ...
}

which makes the type of Context to the type of itself, and thus TypeScript evaluates it to any.

Reproducible example or configuration

function f(schema: IR.SchemaObject, plugin: MyPlugin["Instance"]) {
  plugin.context.resolveIrRef(schema.$ref)
}

TypeScript now yells unsafe access to context which is any type.

OpenAPI specification (optional)

No response

System information (optional)

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

@mrlubos I think these are all a side effect of https://github.com/sxzz/rolldown-plugin-dts/issues/115

• Fixes IR.Context is incorrectly typed with recursive any after 0.86 #2904

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4ab83a3

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

[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	Oct 31, 2025 3:47pm