feature: openapi processor

[miguelramos]

Summary by CodeRabbit

• New Features

  • Enhanced OpenAPI processing: bundling, automatic upgrade to OpenAPI 3.1, full reference dereferencing, and stricter validation
  • Improved error reporting with explicit processing-step context for failures

• Tests

  • Comprehensive new test coverage and fixtures exercising empty inputs, Swagger upgrades, dereferencing, file inputs, and error scenarios

• Documentation

  • Updated technical specification describing processing steps and error semantics

• Chores

  • Test tooling excludes temporary dirs and recorded a package patch changeset

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Implements a full OpenAPI processing pipeline: bundling external refs, upgrading to OpenAPI 3.1, dereferencing $ref pointers, and validating the final document. Adds step-aware ProcessorError, new test fixtures, comprehensive tests, and a changeset; adjusts Vitest exclude patterns.

Changes

Cohort / File(s)	Summary
Changeset & Package config .changesets/feature-task-1-2-openapi-processor.json, packages/core/package.json, vitest.config.ts	Added changeset recording a patch bump for @websublime/vite-open-api-core; minor package.json formatting; excluded **/temp/** from Vitest typecheck/test discovery.
Test Fixtures packages/core/src/parser/__tests__/fixtures/minimal.yaml, packages/core/src/parser/__tests__/fixtures/swagger2.json, packages/core/src/parser/__tests__/fixtures/with-refs.yaml	Added fixtures: minimal OpenAPI 3.0 YAML, Swagger 2.0 JSON, and OpenAPI 3.0 YAML with internal $ref schemas for parser tests.
Processor Implementation packages/core/src/parser/processor.ts	New pipeline with bundleDocument, upgradeDocument, dereferenceDocument, and validateDocument. Added ProcessorStep type and extended ProcessorError(message, step) with step property. processOpenApiDocument now accepts `string
Processor Tests packages/core/src/parser/__tests__/processor.test.ts	Comprehensive tests covering empty inputs, array/error handling, Swagger 2.0→3.1 upgrade, dereferencing internal refs, file-based inputs, non-existent file errors (with step metadata), and ProcessorError behavior.
Docs / Spec history/TECHNICAL-SPECIFICATION.md	Documents ProcessorStep additions and ProcessorError step-aware constructor/property changes.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Processor
    participant Bundler
    participant Upgrader
    participant Dereferencer
    participant Validator

    Client->>Processor: processOpenApiDocument(input)
    activate Processor

    alt Empty input (null/undefined/empty)
        Processor->>Processor: createEmptyDocument()
        Processor-->>Client: minimal OpenAPI 3.1 document
    else Non-empty input
        Processor->>Bundler: bundleDocument(input)
        activate Bundler
        Bundler-->>Processor: bundled document
        deactivate Bundler

        Processor->>Upgrader: upgradeDocument(bundled)
        activate Upgrader
        Upgrader-->>Processor: upgraded OpenAPI 3.1 doc
        deactivate Upgrader

        Processor->>Dereferencer: dereferenceDocument(upgraded)
        activate Dereferencer
        Dereferencer-->>Processor: fully dereferenced doc
        deactivate Dereferencer

        Processor->>Validator: validateDocument(dereferenced)
        activate Validator
        Validator-->>Processor: validated document
        deactivate Validator

        Processor-->>Client: final OpenAPI 3.1 document
    else Error during step
        Processor-->>Client: ProcessorError(message, step)
    end

    deactivate Processor

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐇 I hopped through refs, from bundle to end,
I nudged old Swagger to 3.1, my friend,
I inlined each schema, made docs shine bright,
Now validated specs dance in the night ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'feature: openapi processor' is vague and generic. It uses non-descriptive terms that don't convey meaningful information about the specific changes—such as adding a complete OpenAPI processing pipeline with bundling, upgrading, and dereferencing steps.	Use a more descriptive title that highlights the main implementation detail, such as 'feature: implement openapi processor pipeline with bundle, upgrade, and dereference steps' or 'feature: add openapi document processing with version upgrade and reference dereferencing'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@packages/core/src/parser/processor.ts`:
- Around line 77-92: The current isEmptyInput function treats the string '[]' as
empty; instead, stop treating '[]' as a benign empty document and surface it as
malformed by throwing a ProcessorError with step 'validation' (use the existing
ProcessorError class) when input === '[]' is detected; update isEmptyInput (or
the caller that currently relies on it) to throw new ProcessorError('Invalid
OpenAPI document: array literal "[]" is not a valid document', 'validation')
rather than returning true, or if you intentionally want to accept it add a
brief inline comment explaining why '[]' is treated as empty.
- Around line 121-128: The function processOpenApiDocument currently accepts and
handles undefined/null but its parameter type is declared as string |
Record<string, unknown>; update the function signature to include null and
undefined (e.g., input: string | Record<string, unknown> | null | undefined) so
the type matches runtime behavior, and adjust any exported types or callers that
rely on the old signature (search for processOpenApiDocument references) to
ensure callers compile with the new union type.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/core/src/parser/processor.ts`:
- Around line 119-141: In isEmptyInput, arrays should be treated as invalid
OpenAPI documents, not as empty objects: add an Array.isArray(input) check
(before the typeof input === 'object' branch) and throw a ProcessorError with a
validation type (e.g., 'Invalid OpenAPI document: array literal is not a valid
document') similar to the existing '[]' string case so array inputs do not fall
through and return a minimal doc.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Treat array inputs as invalid, not empty.

An empty array currently falls through the object branch and returns a minimal doc; arrays aren’t valid OpenAPI documents. Mirror the '[]' string handling by throwing a validation error for array inputs.

🐛 Proposed fix

 function isEmptyInput(input: string | Record<string, unknown> | undefined | null): boolean {
+  if (Array.isArray(input)) {
+    throw new ProcessorError(
+      'Invalid OpenAPI document: array input is not a valid document',
+      'validation',
+    );
+  }
   if (!input) {
     return true;
   }

🤖 Prompt for AI Agents

In `@packages/core/src/parser/processor.ts` around lines 119 - 141, In
isEmptyInput, arrays should be treated as invalid OpenAPI documents, not as
empty objects: add an Array.isArray(input) check (before the typeof input ===
'object' branch) and throw a ProcessorError with a validation type (e.g.,
'Invalid OpenAPI document: array literal is not a valid document') similar to
the existing '[]' string case so array inputs do not fall through and return a
minimal doc.