@apidiff/core 1.0.0

package/test/integration/stripe-v1.yaml

@@ -0,0 +1,36 @@
+openapi: 3.0.0
+info:
+  title: Stripe Example API
+  version: "2020-08-27"
+paths:
+  /v1/charges:
+    post:
+      summary: Create a charge
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [amount, currency]
+              properties:
+                amount:
+                  type: integer
+                currency:
+                  type: string
+                source:
+                  type: string
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  amount:
+                    type: integer
+                  currency:
+                    type: string

package/test/integration/stripe-v2.yaml

@@ -0,0 +1,35 @@
+openapi: 3.0.0
+info:
+  title: Stripe Example API
+  version: "2022-11-15"
+paths:
+  /v1/charges:
+    post:
+      summary: Create a charge
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [amount, currency]
+              properties:
+                amount:
+                  type: integer
+                currency:
+                  type: string
+                source:
+                  type: string
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  amount:
+                    type: integer
+                  # currency property removed!

package/tests/ast.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { parseSpec } from '../src/parsers/index.js';
+import { semanticHash } from '../src/ast/hash.js';
+
+describe('Phase 1: AST and Parsing', () => {
+  it('should parse and hash basic OpenAPI spec', async () => {
+    const raw = {
+      content: JSON.stringify({
+        openapi: '3.0.0',
+        info: { title: 'Test API', version: '1.0' },
+        paths: {
+          '/test': {
+            get: {
+              operationId: 'getTest',
+              responses: {
+                '200': { description: 'OK' }
+              }
+            }
+          }
+        }
+      }),
+      format: 'openapi3' as const
+    };
+    
+    const ast = await parseSpec(raw);
+    expect(ast.meta.title).toBe('Test API');
+    expect(ast.endpoints).toHaveLength(1);
+    expect(ast.endpoints[0].id).toBe('GET:/test');
+    
+    const hash = semanticHash(ast);
+    expect(typeof hash).toBe('string');
+    expect(hash.length).toBeGreaterThan(0);
+  });
+
+  it('hashes consistently', () => {
+    const a = semanticHash({ a: 1, b: 2 });
+    const b = semanticHash({ b: 2, a: 1 });
+    expect(a).toBe(b);
+  });
+
+  it('handles null and undefined', () => {
+    const a = semanticHash(null);
+    const b = semanticHash(undefined);
+    expect(a).toBe(b); // both should return semantic hash of null
+  });
+
+  it('handles arrays', () => {
+    const a = semanticHash([1, 2, 3]);
+    const b = semanticHash([1, 2, 3]);
+    expect(a).toBe(b);
+    const c = semanticHash([3, 2, 1]);
+    expect(a).not.toBe(c);
+  });
+
+  it('handles primitive values', () => {
+    const a = semanticHash('test');
+    const b = semanticHash('test');
+    expect(a).toBe(b);
+  });
+});

package/tests/config.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi } from 'vitest';
+import { loadConfig, DEFAULT_CONFIG } from '../src/config/index.js';
+import * as fs from 'node:fs';
+
+vi.mock('node:fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn()
+}));
+
+describe('Config Loader', () => {
+  it('returns default config', async () => {
+    const config = await loadConfig({});
+    expect(config).toEqual(DEFAULT_CONFIG);
+  });
+
+  it('loads from file', async () => {
+    vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+    vi.mocked(fs.readFileSync).mockReturnValueOnce('{"failOn":"warning","output":{"format":"json"}}');
+    const config = await loadConfig({ config: 'apidiff.json' });
+    expect(config.failOn).toBe('warning');
+    expect(config.output.format).toBe('json');
+  });
+
+  it('overrides with cli options', async () => {
+    vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+    vi.mocked(fs.readFileSync).mockReturnValueOnce('{"failOn":"warning","output":{"format":"json"}}');
+    const config = await loadConfig({ config: 'apidiff.json', format: 'markdown', failOn: 'info', ignorePath: ['/test'] });
+    expect(config.failOn).toBe('info');
+    expect(config.output.format).toBe('markdown');
+    expect(config.ignorePaths).toContain('/test');
+  });
+
+  it('throws on not found', async () => {
+    vi.mocked(fs.existsSync).mockReturnValueOnce(false);
+    await expect(loadConfig({ config: 'does-not-exist.json' })).rejects.toThrow('Config file not found');
+  });
+
+  it('throws on invalid json', async () => {
+    vi.mocked(fs.existsSync).mockReturnValueOnce(true);
+    vi.mocked(fs.readFileSync).mockReturnValueOnce('invalid');
+    await expect(loadConfig({ config: 'invalid.json' })).rejects.toThrow('Failed to parse config file');
+  });
+});

package/tests/diff/auth-differ.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { diffSecuritySchemes, diffSecurityRequirements } from '../../src/diff/auth-differ.js';
+import type { SecurityScheme, SecurityRequirement, FieldChange } from '../../src/types/index.js';
+
+describe('Auth Differ', () => {
+  it('diffSecuritySchemes detects added schemes', () => {
+    const oldSchemes: SecurityScheme[] = [];
+    const newSchemes: SecurityScheme[] = [{ id: 'ApiKey', type: 'apiKey', in: 'header', name: 'X-API-Key' }];
+    const diffs = diffSecuritySchemes(oldSchemes, newSchemes);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].changeType).toBe('added');
+    expect(diffs[0].schemeId).toBe('ApiKey');
+  });
+
+  it('diffSecuritySchemes detects removed schemes', () => {
+    const oldSchemes: SecurityScheme[] = [{ id: 'ApiKey', type: 'apiKey', in: 'header', name: 'X-API-Key' }];
+    const newSchemes: SecurityScheme[] = [];
+    const diffs = diffSecuritySchemes(oldSchemes, newSchemes);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].changeType).toBe('removed');
+    expect(diffs[0].schemeId).toBe('ApiKey');
+  });
+
+  it('diffSecuritySchemes detects changed schemes', () => {
+    const oldSchemes: SecurityScheme[] = [{ id: 'Auth', type: 'http', scheme: 'basic' }];
+    const newSchemes: SecurityScheme[] = [{ id: 'Auth', type: 'http', scheme: 'bearer' }];
+    const diffs = diffSecuritySchemes(oldSchemes, newSchemes);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].changeType).toBe('changed');
+    expect(diffs[0].fieldChanges).toHaveLength(1);
+    expect(diffs[0].fieldChanges[0].fieldPath).toEqual(['scheme']);
+    expect(diffs[0].fieldChanges[0].oldValue).toBe('basic');
+    expect(diffs[0].fieldChanges[0].newValue).toBe('bearer');
+  });
+
+  it('diffSecurityRequirements detects added/removed/changed scopes', () => {
+    const oldReqs: SecurityRequirement[] = [{ schemeId: 'OAuth', scopes: ['read'] }];
+    const newReqs: SecurityRequirement[] = [{ schemeId: 'OAuth', scopes: ['read', 'write'] }, { schemeId: 'ApiKey', scopes: [] }];
+    const changes: FieldChange[] = [];
+    
+    diffSecurityRequirements(oldReqs, newReqs, ['security'], changes);
+    
+    expect(changes).toContainEqual({ fieldPath: ['security', 'ApiKey'], changeType: 'added', newValue: 'ApiKey' });
+    expect(changes).toContainEqual({ fieldPath: ['security', 'OAuth', 'scopes', 'write'], changeType: 'added', newValue: 'write' });
+  });
+
+  it('diffSecurityRequirements detects removed requirements', () => {
+    const oldReqs: SecurityRequirement[] = [{ schemeId: 'ApiKey', scopes: [] }];
+    const newReqs: SecurityRequirement[] = [];
+    const changes: FieldChange[] = [];
+    
+    diffSecurityRequirements(oldReqs, newReqs, ['security'], changes);
+    expect(changes).toContainEqual({ fieldPath: ['security', 'ApiKey'], changeType: 'removed', oldValue: 'ApiKey' });
+  });
+});

package/tests/diff/endpoint-differ.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { diffEndpoints } from '../../src/diff/endpoint-differ.js';
+import type { Endpoint } from '../../src/types/index.js';
+
+describe('Endpoint Differ', () => {
+  it('detects added endpoint', () => {
+    const oldEndpoints: Endpoint[] = [];
+    const newEndpoints: Endpoint[] = [{ id: 'GET:/', path: '/', method: 'GET', summary: '', description: '', tags: [], deprecated: false, security: [], parameters: [], responses: [] }];
+    const diffs = diffEndpoints(oldEndpoints, newEndpoints);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].type).toBe('added');
+    expect(diffs[0].endpointId).toBe('GET:/');
+  });
+
+  it('detects removed endpoint', () => {
+    const oldEndpoints: Endpoint[] = [{ id: 'GET:/', path: '/', method: 'GET', summary: '', description: '', tags: [], deprecated: false, security: [], parameters: [], responses: [] }];
+    const newEndpoints: Endpoint[] = [];
+    const diffs = diffEndpoints(oldEndpoints, newEndpoints);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].type).toBe('removed');
+  });
+
+  it('detects changed endpoint fields', () => {
+    const oldEndpoints: Endpoint[] = [{ id: 'GET:/', path: '/', method: 'GET', summary: '', description: '', tags: [], deprecated: false, security: [], parameters: [], responses: [] }];
+    const newEndpoints: Endpoint[] = [{ id: 'GET:/', path: '/', method: 'GET', summary: 'new', description: '', tags: [], deprecated: true, security: [], parameters: [], responses: [] }];
+    const diffs = diffEndpoints(oldEndpoints, newEndpoints);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].type).toBe('changed');
+    expect(diffs[0].fieldChanges).toContainEqual({ fieldPath: ['deprecated'], changeType: 'changed', oldValue: false, newValue: true });
+  });
+
+  it('diffs parameters', () => {
+    const oldEndpoints: Endpoint[] = [{ id: 'GET:/', path: '/', method: 'GET', summary: '', description: '', tags: [], deprecated: false, security: [], parameters: [
+      { name: 'p1', in: 'query', required: false }
+    ], responses: [] }];
+    const newEndpoints: Endpoint[] = [{ id: 'GET:/', path: '/', method: 'GET', summary: '', description: '', tags: [], deprecated: false, security: [], parameters: [
+      { name: 'p1', in: 'query', required: true }
+    ], responses: [] }];
+    const diffs = diffEndpoints(oldEndpoints, newEndpoints);
+    expect(diffs[0].fieldChanges).toContainEqual({ fieldPath: ['parameters', 'p1:query', 'required'], changeType: 'changed', oldValue: false, newValue: true });
+  });
+});

package/tests/diff/schema-differ.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { diffSchema } from '../../src/diff/schema-differ.js';
+import type { Schema, FieldChange } from '../../src/types/index.js';
+
+describe('Schema Differ', () => {
+  it('detects type change', () => {
+    const oldSchema: Schema = { type: 'string' };
+    const newSchema: Schema = { type: 'number' };
+    const changes: FieldChange[] = [];
+    diffSchema(oldSchema, newSchema, ['schema'], changes);
+    expect(changes).toContainEqual({ fieldPath: ['schema', 'type'], changeType: 'changed', oldValue: 'string', newValue: 'number' });
+  });
+
+  it('detects added property', () => {
+    const oldSchema: Schema = { type: 'object', properties: {} };
+    const newSchema: Schema = { type: 'object', properties: { newProp: { type: 'string' } } };
+    const changes: FieldChange[] = [];
+    diffSchema(oldSchema, newSchema, ['schema'], changes);
+    expect(changes).toContainEqual({ fieldPath: ['schema', 'properties', 'newProp'], changeType: 'added', newValue: { type: 'string' } });
+  });
+
+  it('detects removed property', () => {
+    const oldSchema: Schema = { type: 'object', properties: { oldProp: { type: 'string' } } };
+    const newSchema: Schema = { type: 'object', properties: {} };
+    const changes: FieldChange[] = [];
+    diffSchema(oldSchema, newSchema, ['schema'], changes);
+    expect(changes).toContainEqual({ fieldPath: ['schema', 'properties', 'oldProp'], changeType: 'removed', oldValue: { type: 'string' } });
+  });
+
+  it('detects required added/removed', () => {
+    const oldSchema: Schema = { type: 'object', required: ['oldReq'] };
+    const newSchema: Schema = { type: 'object', required: ['newReq'] };
+    const changes: FieldChange[] = [];
+    diffSchema(oldSchema, newSchema, ['schema'], changes);
+    expect(changes).toContainEqual({ fieldPath: ['schema', 'required', 'newReq'], changeType: 'added', newValue: 'newReq' });
+    expect(changes).toContainEqual({ fieldPath: ['schema', 'required', 'oldReq'], changeType: 'removed', oldValue: 'oldReq' });
+  });
+
+  it('detects nested schema differences', () => {
+    const oldSchema: Schema = { type: 'object', properties: { nested: { type: 'object', properties: { field: { type: 'string' } } } } };
+    const newSchema: Schema = { type: 'object', properties: { nested: { type: 'object', properties: { field: { type: 'number' } } } } };
+    const changes: FieldChange[] = [];
+    diffSchema(oldSchema, newSchema, ['schema'], changes);
+    expect(changes).toContainEqual({ fieldPath: ['schema', 'properties', 'nested', 'properties', 'field', 'type'], changeType: 'changed', oldValue: 'string', newValue: 'number' });
+  });
+});

package/tests/diff/server-differ.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { diffServers } from '../../src/diff/server-differ.js';
+import type { Server } from '../../src/types/index.js';
+
+describe('Server Differ', () => {
+  it('detects added servers', () => {
+    const oldServers: Server[] = [];
+    const newServers: Server[] = [{ url: 'http://test.com', description: '' }];
+    const diffs = diffServers(oldServers, newServers);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].changeType).toBe('added');
+    expect(diffs[0].newServer?.url).toBe('http://test.com');
+  });
+
+  it('detects removed servers', () => {
+    const oldServers: Server[] = [{ url: 'http://test.com', description: '' }];
+    const newServers: Server[] = [];
+    const diffs = diffServers(oldServers, newServers);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].changeType).toBe('removed');
+    expect(diffs[0].oldServer?.url).toBe('http://test.com');
+  });
+});

package/tests/diff.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { diffEndpoints } from '../src/diff/endpoint-differ.js';
+import { diffServers } from '../src/diff/server-differ.js';
+import { diffSchema } from '../src/diff/schema-differ.js';
+import type { Endpoint, Server, Schema, FieldChange } from '../src/types/index.js';
+
+describe('Differ Coverage', () => {
+  it('diffEndpoints - coverage', () => {
+    const oldE: Endpoint = {
+      id: 'test',
+      method: 'GET',
+      path: '/test',
+      security: [],
+      parameters: [{ name: 'p', in: 'query', schema: {}, required: true, deprecated: false }],
+      requestBody: {
+        required: true,
+        content: { 'app/json': { schema: {} } }
+      },
+      responses: [
+        {
+          statusCode: '200',
+          description: 'ok',
+          content: { 'app/json': { schema: {} } },
+          headers: { 'X-RateLimit': { schema: {}, required: true, description: '' } }
+        }
+      ],
+      tags: [],
+      deprecated: false,
+      extensions: {}
+    };
+
+    const newE: Endpoint = {
+      id: 'test',
+      method: 'POST',
+      path: '/test2',
+      security: [],
+      parameters: [{ name: 'p', in: 'query', schema: {}, required: false, deprecated: true }],
+      requestBody: {
+        required: false,
+        content: { 'text/plain': { schema: {} } }
+      },
+      responses: [
+        {
+          statusCode: '200',
+          description: 'ok',
+          content: { 'text/plain': { schema: {} } },
+          headers: { 'X-RateLimit': { schema: {}, required: false, description: '' } }
+        }
+      ],
+      tags: [],
+      deprecated: true,
+      extensions: {}
+    };
+
+    const diffs = diffEndpoints([oldE], [newE]);
+    expect(diffs).toHaveLength(1);
+    expect(diffs[0].type).toBe('changed');
+    
+    // Check old missing request body to new request body
+    const diffs2 = diffEndpoints(
+      [{ ...oldE, requestBody: undefined }],
+      [{ ...newE, requestBody: { required: false, content: {} } }]
+    );
+    expect(diffs2).toBeDefined();
+
+    // Check old request body to missing
+    const diffs3 = diffEndpoints(
+      [{ ...oldE, requestBody: { required: false, content: {} } }],
+      [{ ...newE, requestBody: undefined }]
+    );
+    expect(diffs3).toBeDefined();
+  });
+
+  it('diffServers - coverage', () => {
+    const changes = diffServers(
+      [{ url: 'http://old' }],
+      [{ url: 'http://new' }]
+    );
+    expect(changes).toBeDefined();
+
+    const changes2 = diffServers(
+      [{ url: 'http://same', description: 'old' }],
+      [{ url: 'http://same', description: 'new' }]
+    );
+    expect(changes2).toBeDefined();
+  });
+
+  it('diffSchema - coverage', () => {
+    const changes: FieldChange[] = [];
+    diffSchema(undefined, { type: 'string' }, ['root'], changes);
+    diffSchema({ type: 'string' }, undefined, ['root'], changes);
+
+    const oldS: Schema = {
+      type: 'object',
+      properties: { a: { type: 'string' }, b: { type: 'number' } },
+      required: ['a'],
+      enum: ['x'],
+      allOf: [{ type: 'object' }],
+      oneOf: [{ type: 'object' }],
+      anyOf: [{ type: 'object' }]
+    };
+
+    const newS: Schema = {
+      type: 'object',
+      properties: { b: { type: 'string' }, c: { type: 'number' } },
+      required: ['b'],
+      enum: ['y'],
+      allOf: [{ type: 'string' }],
+      oneOf: [{ type: 'string' }],
+      anyOf: [{ type: 'string' }]
+    };
+
+    diffSchema(oldS, newS, ['schema'], changes);
+    expect(changes.length).toBeGreaterThan(0);
+  });
+});

package/tests/fixtures/openapi3/auth-added/v1.yaml

@@ -0,0 +1,11 @@
+openapi: 3.0.0
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: Get users
+      responses:
+        '200':
+          description: OK

package/tests/fixtures/openapi3/auth-added/v2.yaml

@@ -0,0 +1,18 @@
+openapi: 3.0.0
+info:
+  title: Test API
+  version: 2.0.0
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+paths:
+  /users:
+    get:
+      summary: Get users
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: OK

package/tests/integration.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'node:path';
+import { run } from '../src/index.js';
+
+describe('Integration Tests: Real World Scenarios', () => {
+  it('Stripe API Versioning (v1 to v2)', async () => {
+    const oldPath = resolve(__dirname, '../test/integration/stripe-v1.yaml');
+    const newPath = resolve(__dirname, '../test/integration/stripe-v2.yaml');
+
+    const result = await run(oldPath, newPath);
+
+    expect(result.stats.total).toBeGreaterThan(0);
+    expect(result.stats.breaking).toBeGreaterThan(0);
+
+    const changes = result.changes;
+    // We expect RESPONSE_FIELD_REMOVED for currency
+    const fieldRemoved = changes.find(c => c.ruleId === 'RESPONSE_FIELD_REMOVED' && c.message.includes('currency'));
+    expect(fieldRemoved).toBeDefined();
+    expect(fieldRemoved?.severity).toBe('breaking');
+  });
+});

package/tests/loader-more.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest';
+import { loadGit } from '../src/loader/git-loader.js';
+import { loadUrl } from '../src/loader/url-loader.js';
+import { loadSpec } from '../src/loader/index.js';
+import * as child_process from 'node:child_process';
+
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn()
+}));
+
+global.fetch = vi.fn();
+
+describe('More Loaders', () => {
+  describe('git-loader', () => {
+    it('throws on invalid source', () => {
+      expect(() => loadGit('git:invalid')).toThrow('invalid git source format');
+    });
+
+    it('loads from git', () => {
+      vi.mocked(child_process.execSync).mockReturnValueOnce('mock_content');
+      const doc = loadGit('git:HEAD:file.yaml');
+      expect(doc.content).toBe('mock_content');
+    });
+
+    it('throws on git error', () => {
+      vi.mocked(child_process.execSync).mockImplementationOnce(() => {
+        const err: any = new Error('Command failed');
+        err.stderr = 'Not a valid object name';
+        throw err;
+      });
+      expect(() => loadGit('git:HEAD:not-found.yaml')).toThrow('git ref or path not found');
+    });
+  });
+
+  describe('url-loader', () => {
+    it('loads from url', async () => {
+      vi.mocked(fetch).mockResolvedValueOnce({
+        ok: true,
+        text: async () => 'mock_content'
+      } as Response);
+      const doc = await loadUrl('https://example.com/api.yaml');
+      expect(doc.content).toBe('mock_content');
+    });
+
+    it('throws on http error', async () => {
+      vi.mocked(fetch).mockResolvedValueOnce({
+        ok: false,
+        status: 404
+      } as Response);
+      await expect(loadUrl('https://example.com/not-found.yaml')).rejects.toThrow('failed to fetch url');
+    });
+
+    it('throws on network error', async () => {
+      vi.mocked(fetch).mockRejectedValueOnce(new Error('Network error'));
+      await expect(loadUrl('https://example.com/api.yaml')).rejects.toThrow('network error fetching url');
+    });
+  });
+
+  describe('index', () => {
+    it('routes url', async () => {
+      vi.mocked(fetch).mockResolvedValueOnce({
+        ok: true,
+        text: async () => 'mock_content'
+      } as Response);
+      const doc = await loadSpec('https://example.com/api.yaml');
+      expect(doc.content).toBe('mock_content');
+    });
+
+    it('routes git', async () => {
+      vi.mocked(child_process.execSync).mockReturnValueOnce('mock_content');
+      const doc = await loadSpec('git:HEAD:file.yaml');
+      expect(doc.content).toBe('mock_content');
+    });
+  });
+});

package/tests/loader.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi } from 'vitest';
+import * as fs from 'node:fs';
+import { resolve } from 'node:path';
+import { loadSpec } from '../src/loader/index.js';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+vi.mock('node:fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs')>();
+  return {
+    ...actual,
+    readFileSync: vi.fn(actual.readFileSync)
+  };
+});
+
+describe('Loader', () => {
+  it('loads valid file', async () => {
+    // Assuming integration.test.ts has valid files we can load
+    const doc = await loadSpec(path.join(__dirname, '../test/integration/stripe-v1.yaml'));
+    expect(doc).toBeDefined();
+  });
+
+  it('throws on invalid file', async () => {
+    await expect(loadSpec('does-not-exist.yaml')).rejects.toThrow();
+  });
+
+  it('throws EACCES on permission denied', async () => {
+    vi.mocked(fs.readFileSync).mockImplementationOnce(() => {
+      const err = new Error('EACCES');
+      (err as any).code = 'EACCES';
+      throw err;
+    });
+    
+    await expect(loadSpec('dummy.yaml')).rejects.toThrow('permission denied');
+  });
+
+  it('throws on generic file error', async () => {
+    vi.mocked(fs.readFileSync).mockImplementationOnce(() => {
+      const err = new Error('Generic error');
+      throw err;
+    });
+    
+    await expect(loadSpec('dummy.yaml')).rejects.toThrow('failed to read file');
+  });
+
+  it('reads from stdin', async () => {
+    vi.mocked(fs.readFileSync).mockReturnValueOnce('mock_stdin_content');
+    const doc = await loadSpec('-');
+    expect(doc.content).toBe('mock_stdin_content');
+    expect(fs.readFileSync).toHaveBeenCalledWith(0, 'utf-8');
+  });
+
+  it('throws on stdin error', async () => {
+    vi.mocked(fs.readFileSync).mockImplementationOnce(() => {
+      throw new Error('stdin error');
+    });
+    await expect(loadSpec('-')).rejects.toThrow('failed to read from stdin');
+  });
+});