fix(oas:sync): resolve path-item $refs so sync stops deleting pages

[cursor]

🚦 Resolves
Data loss: oas:sync / lint --fix deleted valid reference pages when the spec used path-item $refs

🪄 Changes

extractOperations walked the raw OpenAPI document and only counted HTTP methods sitting directly on each path item. A path-level $ref — including the OAS 3.1 components.pathItems form — therefore contributed zero operations.

syncOneOas then treated every existing page for that spec as orphaned and deleted it. Same path for readme lint --fix (via the oas-reference validator).

Concrete trigger: a repo with reference/openapi.json like:

openapi: 3.1.0
paths:
  /pets:
    $ref: '#/components/pathItems/Pets'
components:
  pathItems:
    Pets:
      get:
        operationId: listPets

and a page reference/.../listPets.md with custom body. One readme oas:sync or readme lint --fix permanently deletes that page.

Fix:

• Resolve internal JSON Pointer $refs (#/components/pathItems/…, #/paths/~1pets, operation-level pointers) before collecting operations.
• Skip the delete pass when a $ref still cannot be inlined (e.g. a split spec pointing at ./paths/pets.yaml), so "we couldn't see the operation" is not treated as "the operation was removed".

No change to add/skip-on-collision behavior, path sanitization, or webhook handling (still covered by #43).

🧬 QA & Testing

• Reproduced the deletion against an OAS 3.1 pathItems spec on unmodified main (page gone; changes.deleted = ['Pets/Other/listPets.md']).
• After the fix, the same spec keeps the custom page, creates the missing sibling operation page, and the oas-reference validator no longer reports Operation not found.
• Added regression tests in test/oas-sync.test.js (resolution, no-deletion for internal and external $refs) and test/oas-reference.test.js (no false missing-operation).
• Full suite: 160/160 passing (npm test).

  

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/commands/oas-sync.js	Replaces raw operation walking with reference-aware extraction, overlays path-item siblings, and disables destructive deletion when operation visibility is incomplete.
test/oas-sync.test.js	Adds regression coverage for internal, external, cyclic, inherited-property, sibling, non-object-target, and operation-level reference cases.
test/oas-reference.test.js	Verifies that operations supplied through OAS 3.1 path-item references are recognized by cross-file validation.
package.json	Adds the oas package used by the new extraction implementation.
package-lock.json	Locks the new oas dependency and its transitive dependency graph.

_{Reviews (4): Last reviewed commit: "refactor(oas:sync): use the oas library ..." | Re-trigger Greptile}