F/auto update openapi paths

[fernando-aviles]

Greptile Summary

This PR enhances the OpenAPI path auto-update feature to intelligently repoint references when entries move between spec files. The implementation adds a new specHasMatch() helper function and extends the resolveSpec() function to detect when an explicitly referenced spec no longer contains a required operation/webhook/schema, then searches for alternatives. When exactly one alternative is found, it automatically repoints the reference with a warning; when multiple alternatives or none exist, it gracefully skips localization. The feature is well-tested with a new comprehensive test case covering the spec-switching scenario. This improves developer experience by automatically correcting stale OpenAPI references in frontmatter when documentation schemas evolve.

Confidence Score: 5/5

• This PR is safe to merge with no critical issues identified. Changes are well-tested, logically sound, and maintain backward compatibility.
• Score reflects: (1) Feature is well-designed with clear separation of concerns through the new specHasMatch() helper; (2) Comprehensive test coverage with a new test case validating the spec-repointing behavior; (3) Robust error handling with appropriate warnings for edge cases (missing entries, multiple matches, no matches); (4) No breaking changes to existing logic - new behavior only triggers when explicit specs don't contain referenced entries; (5) Code quality is high with proper type safety and documentation.
• No files require special attention

Important Files Changed

Filename	Overview
packages/cli/src/utils/processOpenApi.ts	Added logic to auto-update OpenAPI spec paths in frontmatter when referenced entries move between specs. New helper function specHasMatch checks if a spec contains operations, webhooks, or schemas. Enhanced resolveSpec function now handles spec changes: single alternative repoints, multiple alternatives skip with warning, no alternatives skip with warning. Code quality is high with proper error handling and warnings.
packages/cli/src/utils/tests/processOpenApi.test.ts	Added comprehensive test case for spec path repointing behavior. Test 'repoints explicit spec paths when entry moves to another spec' validates that when an entry is found in a different spec than explicitly referenced, the path is correctly updated to the new spec location in both source and localized files.

Sequence Diagram

sequenceDiagram
    participant MD as Markdown File
    participant PR as processOpenApi()
    participant RS as resolveSpec()
    participant SM as specHasMatch()
    participant FM as fileMapping

    MD->>PR: Start processing file
    PR->>RS: Resolve explicit spec path
    RS->>SM: Check if spec contains entry
    SM-->>RS: Entry not in spec
    RS->>RS: Find alternatives in other specs
    RS->>SM: Check each alternative
    SM-->>RS: Found in spec-b only
    RS->>FM: Resolve localized path for spec-b
    FM-->>RS: Return locale-specific path
    RS->>PR: Return alternative spec
    PR->>MD: Update frontmatter with new spec path
    Note over PR: Warnings logged for reference changes

Loading