fix(openapi): resolve x-fern-examples $ref relative to spec file

[devin-ai-integration]

Description

Refs #10297

Fixes x-fern-examples $ref resolution to resolve file paths relative to the OpenAPI spec file directory instead of process.cwd().

Devin session: https://app.devin.ai/sessions/79313c8ac0114e65992c36847cb98eec
Requested by: judah@buildwithfern.com (@jsklan)

Changes Made

• Added documentBaseDir parameter to AbstractConverterContext to track the OpenAPI file's base directory
• Implemented $ref resolution in openapi-to-ir package's FernExamplesExtension:
  • Added helper functions: isCodeReference, maybeResolveCodeReference, resolveCodeSamples
  • Resolves code samples with $ref before validation using readFileSync
• Implemented $ref resolution in openapi-ir-parser package's getExamplesFromExtension:
  • Added identical helper functions for consistency
  • Uses context.source.file to determine base directory via dirname()
• Updated OSSWorkspace.ts to pass documentBaseDir: dirname(absoluteFilepathToSpec) when creating OpenAPIConverterContext
• Added test case and fixtures for x-fern-examples file-linking
• Fixed test fixture to use query-parameters instead of request for GET endpoint (pre-existing validation error)
• Updated README.md generator (N/A)

Testing

• Unit tests added/updated: Added x-fern-examples.test.ts end-to-end test
• Manual testing completed: Verified test passes with pnpm -C packages/cli/ete-tests test x-fern-examples.test.ts

Important Review Notes

Dual Implementation

This fix was required in two separate code paths:

1. openapi-to-ir package (newer conversion pipeline)
2. openapi-ir-parser package (older conversion pipeline that's still used)

Both implementations use identical logic for consistency. Please verify both are correct.

Test Fixture Modification

Changed the test fixture from using request: { limit: 10 } to query-parameters: { limit: 10 } for the GET endpoint. This was necessary because:

• The original fixture had a pre-existing validation error: "Unexpected request in example"
• GET endpoints without a request body should use query-parameters not request in examples
• Verified the same error exists in the original PR feat(openapi): restore x-fern-examples file-linking support #10297

Error Handling Behavior

When a $ref cannot be resolved (file doesn't exist or can't be read), the code sample is silently dropped from the example. This matches the pattern where validation errors are collected but don't block parsing. However, this means incorrect file paths won't produce clear error messages.

File I/O

Uses synchronous readFileSync to avoid making the entire conversion pipeline async. This is consistent with other file operations during the parsing phase but could block for large code sample files.

Human Review Checklist

• Verify both openapi-to-ir and openapi-ir-parser implementations work correctly
• Confirm test fixture change from request to query-parameters is correct
• Check if silent failure on unresolvable $refs is acceptable or should error
• Verify path resolution works for the test case: ../../code_samples/example.php from fern/openapi/openapi.yml

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring