fix(zod,fetch): resolve $ref schemas with suffix in runtime validation (#3059)

* fix: resolve zod $ref schemas when component suffix is enabled (refs #3027)

* test: add issue-3027 fixtures and snapshots for zod suffix ref regression

* fix: update ESLint configuration and improve test assertions for package-json

* chore: remove temp pr-description file

* chore(pr): address review feedback and remove unrelated changes

- remove broad ts-nocheck usage in package-json test and use typed-safe assertion

- drop temporary ESLint override added only for that suppression

- revert unrelated solid-query infinite defaults change from query generator

* chore(test): restore lint-safe baseline for package-json test

- re-add ts-nocheck in package-json.test.ts to avoid widespread mock typing noise

- re-add file-scoped ban-ts-comment override for this legacy test file

- keep PR focused on issue #3027 while maintaining passing lint/checks

* refactor(zod,core): improve review findings — JSDoc, logging, edge-case tests

- Replace silent catch {} in dereference with tryResolveRefSchema helper
  that logs via logVerbose on failure for easier debugging
- Extract double-IIFE into named tryResolveRefSchema function
- Deduplicate error messages into REF_NOT_FOUND_PREFIX constant
- Add JSDoc to resolveRef, getSchema, dereference, resolveExampleRefs
- Remove unnecessary double-cast in resolveExampleRefs
- Add 6 zod.test.ts edge cases: circular ref, additionalProperties,
  nullable ref, deep nested allOf, empty suffix regression
- Add 3 ref.test.ts edge cases: suffix import name, passthrough, fallback
- Expand issue-3027 fixture with PositionMap, TreeNode,
  NullablePositionWrapper schemas
- Document @ts-nocheck rationale in package-json.test.ts
- Regenerate fetch and zod snapshots

* test(ref): document current behavior for nonexistent local refs (KNOWN ISSUE)

* fix(ref): enhance example resolution to properly handle resolved examples

---------

Co-authored-by: Arjen <ult_dev@pm.me>

Author: the-ult

eslint.config.mjs

@@ -12,6 +12,7 @@ export default defineConfig(
   globalIgnores([
     'docs',
     'tests/generated',
+    'tests/**/__snapshots__/**',
     'samples',
     '.husky',
     'packages/hono/src/zValidator.ts',
@@ -91,5 +92,11 @@ export default defineConfig(
       '@typescript-eslint/no-unsafe-return': 'off',
     },
   },
+  {
+    files: ['packages/orval/src/utils/package-json.test.ts'],
+    rules: {
+      '@typescript-eslint/ban-ts-comment': 'off',
+    },
+  },
   eslintPluginPrettierRecommended, // also sets up eslint-config-prettier
 );

packages/core/src/resolvers/ref.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  ContextSpec,
+  OpenApiDocument,
+  OpenApiReferenceObject,
+  OpenApiSchemaObject,
+} from '../types';
+import { resolveExampleRefs, resolveRef } from './ref';
+
+function createContext(spec: OpenApiDocument): ContextSpec {
+  return {
+    target: 'core-test',
+    workspace: '/tmp',
+    spec,
+    output: {
+      override: {
+        components: {
+          schemas: { suffix: '' },
+        },
+      },
+    },
+  } as ContextSpec;
+}
+
+describe('resolveRef', () => {
+  it('supports schema generic and resolves local schema refs', () => {
+    const context = createContext({
+      openapi: '3.1.0',
+      components: {
+        schemas: {
+          Position: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+            },
+          },
+        },
+      },
+    });
+
+    const resolveSchemaRef: (
+      schema: OpenApiReferenceObject,
+      context: ContextSpec,
+    ) => { schema: OpenApiSchemaObject; imports: unknown[] } = resolveRef;
+
+    const result = resolveSchemaRef(
+      { $ref: '#/components/schemas/Position' },
+      context,
+    );
+    const typedSchema = result.schema;
+
+    expect(typedSchema).toMatchObject({
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+      },
+    });
+    expect(result.imports[0]).toEqual({
+      name: 'Position',
+      schemaName: 'Position',
+    });
+  });
+
+  it('preserves nullable and OpenAPI 3.1 type array hints from a direct ref', () => {
+    const context = createContext({
+      openapi: '3.1.0',
+      components: {
+        schemas: {
+          MaybePosition: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+            },
+          },
+        },
+      },
+    });
+
+    const refWithHints = {
+      $ref: '#/components/schemas/MaybePosition',
+      nullable: true,
+      type: ['object', 'null'],
+    } as unknown as OpenApiReferenceObject;
+
+    const { schema } = resolveRef(refWithHints, context);
+
+    const withNullable = schema as OpenApiSchemaObject & {
+      nullable?: boolean;
+      type?: string[];
+    };
+
+    expect(withNullable.nullable).toBe(true);
+    expect(withNullable.type).toEqual(['object', 'null']);
+  });
+
+  it('resolves nested schema refs and example refs in schema-like containers', () => {
+    const context = createContext({
+      openapi: '3.1.0',
+      components: {
+        schemas: {
+          Position: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+            },
+          },
+        },
+        examples: {
+          PositionExample: {
+            value: {
+              id: 'p_1',
+            },
+          },
+        },
+      },
+    });
+
+    type NestedResolved = {
+      schema: OpenApiSchemaObject;
+      examples?: unknown[];
+    };
+
+    const carrier = {
+      schema: {
+        $ref: '#/components/schemas/Position',
+      },
+      examples: [{ $ref: '#/components/examples/PositionExample' }],
+    };
+
+    const resolved = resolveRef(
+      carrier as unknown as OpenApiReferenceObject,
+      context,
+    ) as { schema: NestedResolved; imports: unknown[] };
+
+    expect(resolved.schema.schema).toMatchObject({
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+      },
+    });
+    expect(resolved.schema.examples).toEqual([{ id: 'p_1' }]);
+  });
+
+  it('applies schema suffix to import name when suffix is configured', () => {
+    const context = createContext({
+      openapi: '3.1.0',
+      components: {
+        schemas: {
+          Position: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+            },
+          },
+        },
+      },
+    });
+    // Override suffix
+    (
+      context.output.override.components as { schemas: { suffix: string } }
+    ).schemas.suffix = 'Schema';
+
+    const result = resolveRef(
+      { $ref: '#/components/schemas/Position' },
+      context,
+    );
+
+    expect(result.imports[0]).toEqual({
+      name: 'PositionSchema',
+      schemaName: 'Position',
+    });
+  });
+
+  it('returns a non-ref schema as-is when it is already dereferenced', () => {
+    const context = createContext({
+      openapi: '3.1.0',
+      components: { schemas: {} },
+    });
+
+    // A plain schema object (no $ref) is treated as already dereferenced
+    const result = resolveRef(
+      { type: 'object' } as unknown as OpenApiReferenceObject,
+      context,
+    );
+
+    expect(result.schema).toMatchObject({ type: 'object' });
+    expect(result.imports).toEqual([]);
+  });
+
+  it('documents current behavior for nonexistent local refs (KNOWN ISSUE)', () => {
+    const context = createContext({
+      openapi: '3.1.0',
+      components: { schemas: {} },
+    });
+
+    // KNOWN ISSUE: When a ref path does not resolve to a nested schema,
+    // getSchema currently falls back to context.spec and returns the full
+    // spec document instead of throwing (see schemaByRefPaths ??= context.spec
+    // in ref.ts). This test documents current behavior and should be updated
+    // once unresolved refs are handled strictly.
+    const result = resolveRef(
+      { $ref: '#/components/schemas/NonExistent' },
+      context,
+    );
+
+    // Current behavior: resolves (doesn't throw) and returns root spec.
+    expect(result.schema).toHaveProperty('openapi', '3.1.0');
+  });
+});
+
+describe('resolveExampleRefs', () => {
+  const context = createContext({
+    openapi: '3.1.0',
+    components: {
+      examples: {
+        Primitive: {
+          value: 'hello',
+        },
+        ObjectValue: {
+          value: {
+            id: 'p_1',
+          },
+        },
+      },
+    },
+  });
+
+  it('resolves example refs in arrays and records', () => {
+    const list = resolveExampleRefs(
+      [{ $ref: '#/components/examples/Primitive' }],
+      context,
+    );
+
+    const map = resolveExampleRefs(
+      {
+        sample: { $ref: '#/components/examples/ObjectValue' },
+      },
+      context,
+    );
+
+    expect(list).toEqual(['hello']);
+    expect(map).toEqual({ sample: { id: 'p_1' } });
+  });
+});