apcore-js 0.3.0 → 0.5.0

package/tests/schema/test-ref-resolver.test.ts

@@ -1,6 +1,9 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { RefResolver } from '../../src/schema/ref-resolver.js';
-import { SchemaCircularRefError, SchemaNotFoundError } from '../../src/errors.js';
+import { SchemaCircularRefError, SchemaNotFoundError, SchemaParseError } from '../../src/errors.js';
 
 describe('RefResolver', () => {
   it('resolves local $ref', () => {
@@ -103,3 +106,425 @@ describe('RefResolver', () => {
     expect(resolved).toEqual(schema);
   });
 });
+
+describe('RefResolver - apcore:// URI resolution', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'apcore-ref-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('resolves apcore:// URI to schema file and JSON pointer', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(
+      join(schemasDir, 'foo.schema.yaml'),
+      'type: object\nproperties:\n  name:\n    type: string\n',
+    );
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        field: { $ref: 'apcore://foo/properties/name' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, unknown>;
+    expect(props['field']).toEqual({ type: 'string' });
+  });
+
+  it('resolves apcore:// URI without pointer to full document', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(
+      join(schemasDir, 'bar.schema.yaml'),
+      'type: string\ndescription: a bar\n',
+    );
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'apcore://bar' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, unknown>;
+    expect(props['x']).toEqual({ type: 'string', description: 'a bar' });
+  });
+});
+
+describe('RefResolver - array element ref resolution', () => {
+  it('resolves $ref inside array elements', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      definitions: {
+        Tag: { type: 'string' },
+      },
+      type: 'object',
+      properties: {
+        tags: {
+          type: 'array',
+          items: [
+            { $ref: '#/definitions/Tag' },
+            { $ref: '#/definitions/Tag' },
+          ],
+        },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    const items = props['tags']['items'] as Record<string, unknown>[];
+    expect(items[0]).toEqual({ type: 'string' });
+    expect(items[1]).toEqual({ type: 'string' });
+  });
+
+  it('resolves $ref inside oneOf array', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      definitions: {
+        Str: { type: 'string' },
+        Num: { type: 'number' },
+      },
+      type: 'object',
+      properties: {
+        value: {
+          oneOf: [
+            { $ref: '#/definitions/Str' },
+            { $ref: '#/definitions/Num' },
+          ],
+        },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    const oneOf = props['value']['oneOf'] as Record<string, unknown>[];
+    expect(oneOf[0]).toEqual({ type: 'string' });
+    expect(oneOf[1]).toEqual({ type: 'number' });
+  });
+});
+
+describe('RefResolver - file loading edge cases', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'apcore-ref-load-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('handles empty YAML files gracefully', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(join(schemasDir, 'empty.schema.yaml'), '');
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'empty.schema.yaml' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, unknown>;
+    expect(props['x']).toEqual({});
+  });
+
+  it('handles YAML file with only whitespace', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(join(schemasDir, 'whitespace.schema.yaml'), '   \n  \n  ');
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'whitespace.schema.yaml' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, unknown>;
+    expect(props['x']).toEqual({});
+  });
+
+  it('throws SchemaParseError for invalid YAML', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(join(schemasDir, 'bad.schema.yaml'), ':\n  - :\n    :\n  invalid: [}');
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'bad.schema.yaml' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaParseError);
+  });
+
+  it('throws SchemaParseError when YAML file is a scalar not a mapping', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(join(schemasDir, 'scalar.schema.yaml'), '"just a string"');
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'scalar.schema.yaml' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaParseError);
+  });
+
+  it('throws SchemaParseError when YAML file is a list not a mapping', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(join(schemasDir, 'list.schema.yaml'), '- one\n- two\n');
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'list.schema.yaml' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaParseError);
+  });
+
+  it('throws SchemaNotFoundError for missing file', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'nonexistent.yaml' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaNotFoundError);
+  });
+});
+
+describe('RefResolver - path traversal guard', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'apcore-ref-guard-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('throws SchemaNotFoundError when ref resolves outside schemas dir', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: '../../etc/passwd' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaNotFoundError);
+    expect(() => resolver.resolve(schema)).toThrow(/resolves outside schemas directory/);
+  });
+
+  it('throws SchemaNotFoundError for file#pointer ref outside schemas dir', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: '../outside.yaml#/foo' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaNotFoundError);
+    expect(() => resolver.resolve(schema)).toThrow(/resolves outside schemas directory/);
+  });
+});
+
+describe('RefResolver - clearCache', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'apcore-ref-cache-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('clears cached file content so subsequent resolve re-reads files', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(join(schemasDir, 'mutable.schema.yaml'), 'type: string\n');
+
+    const resolver = new RefResolver(schemasDir);
+
+    const schema1 = { type: 'object', properties: { x: { $ref: 'mutable.schema.yaml' } } };
+    const resolved1 = resolver.resolve(schema1);
+    const props1 = resolved1['properties'] as Record<string, Record<string, unknown>>;
+    expect(props1['x']['type']).toBe('string');
+
+    writeFileSync(join(schemasDir, 'mutable.schema.yaml'), 'type: integer\n');
+
+    // Without clearing cache, old value is served
+    const schema2 = { type: 'object', properties: { x: { $ref: 'mutable.schema.yaml' } } };
+    const resolvedCached = resolver.resolve(schema2);
+    const propsCached = resolvedCached['properties'] as Record<string, Record<string, unknown>>;
+    expect(propsCached['x']['type']).toBe('string');
+
+    // After clearing, new value is read
+    resolver.clearCache();
+    const schema3 = { type: 'object', properties: { x: { $ref: 'mutable.schema.yaml' } } };
+    const resolvedFresh = resolver.resolve(schema3);
+    const propsFresh = resolvedFresh['properties'] as Record<string, Record<string, unknown>>;
+    expect(propsFresh['x']['type']).toBe('integer');
+  });
+});
+
+describe('RefResolver - nested $ref resolution', () => {
+  it('resolves a $ref that points to another $ref (chain)', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      definitions: {
+        Alias: { $ref: '#/definitions/Actual' },
+        Actual: { type: 'number' },
+      },
+      type: 'object',
+      properties: {
+        val: { $ref: '#/definitions/Alias' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['val']).toEqual({ type: 'number' });
+  });
+
+  it('resolves sibling keys alongside $ref', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      definitions: {
+        Base: { type: 'string' },
+      },
+      type: 'object',
+      properties: {
+        val: { $ref: '#/definitions/Base', description: 'overridden' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['val']['type']).toBe('string');
+    expect(props['val']['description']).toBe('overridden');
+  });
+});
+
+describe('RefResolver - cross-file $ref', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'apcore-ref-cross-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('resolves file.yaml#/pointer format', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(
+      join(schemasDir, 'shared.yaml'),
+      'definitions:\n  Email:\n    type: string\n    format: email\n',
+    );
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        email: { $ref: 'shared.yaml#/definitions/Email' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['email']).toEqual({ type: 'string', format: 'email' });
+  });
+
+  it('resolves file.yaml without pointer to full document', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    writeFileSync(
+      join(schemasDir, 'simple.yaml'),
+      'type: boolean\n',
+    );
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        flag: { $ref: 'simple.yaml' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['flag']).toEqual({ type: 'boolean' });
+  });
+
+  it('resolves cross-file ref with currentFile context', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    const subDir = join(schemasDir, 'sub');
+    mkdirSync(subDir, { recursive: true });
+    writeFileSync(
+      join(schemasDir, 'types.yaml'),
+      'definitions:\n  Id:\n    type: integer\n',
+    );
+    writeFileSync(
+      join(subDir, 'model.yaml'),
+      'type: object\nproperties:\n  id:\n    $ref: "../types.yaml#/definitions/Id"\n',
+    );
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        model: { $ref: 'sub/model.yaml' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, Record<string, unknown>>;
+    const model = props['model'] as Record<string, unknown>;
+    const modelProps = model['properties'] as Record<string, Record<string, unknown>>;
+    expect(modelProps['id']).toEqual({ type: 'integer' });
+  });
+
+  it('resolves YAML with null-parsed content as empty object', () => {
+    const schemasDir = join(tmpDir, 'schemas');
+    mkdirSync(schemasDir, { recursive: true });
+    // YAML "null" keyword parses to null
+    writeFileSync(join(schemasDir, 'nulldoc.yaml'), 'null\n');
+
+    const resolver = new RefResolver(schemasDir);
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: 'nulldoc.yaml' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const props = resolved['properties'] as Record<string, unknown>;
+    expect(props['x']).toEqual({});
+  });
+});

package/tests/schema/test-strict.test.ts

@@ -103,6 +103,202 @@ describe('applyLlmDescriptions', () => {
   });
 });
 
+describe('toStrictSchema - definitions and combinators', () => {
+  it('recurses into definitions block', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+      required: ['name'],
+      definitions: {
+        Address: {
+          type: 'object',
+          properties: {
+            city: { type: 'string' },
+            zip: { type: 'string' },
+          },
+          required: ['city'],
+        },
+      },
+    };
+    const strict = toStrictSchema(schema);
+    const defs = strict['definitions'] as Record<string, Record<string, unknown>>;
+    expect(defs['Address']['additionalProperties']).toBe(false);
+    const addrProps = defs['Address']['properties'] as Record<string, Record<string, unknown>>;
+    expect(addrProps['zip']['type']).toEqual(['string', 'null']);
+  });
+
+  it('recurses into $defs block', () => {
+    const schema = {
+      type: 'object',
+      properties: { x: { type: 'string' } },
+      $defs: {
+        Inner: {
+          type: 'object',
+          properties: {
+            a: { type: 'integer' },
+            b: { type: 'string' },
+          },
+          required: ['a'],
+        },
+      },
+    };
+    const strict = toStrictSchema(schema);
+    const defs = strict['$defs'] as Record<string, Record<string, unknown>>;
+    expect(defs['Inner']['additionalProperties']).toBe(false);
+    const innerProps = defs['Inner']['properties'] as Record<string, Record<string, unknown>>;
+    expect(innerProps['b']['type']).toEqual(['string', 'null']);
+  });
+
+  it('recurses into oneOf/anyOf/allOf variants', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        value: {
+          oneOf: [
+            {
+              type: 'object',
+              properties: { a: { type: 'string' } },
+            },
+          ],
+        },
+      },
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    const oneOf = props['value']['oneOf'] as Record<string, unknown>[];
+    expect(oneOf[0]['additionalProperties']).toBe(false);
+  });
+
+  it('appends null to existing oneOf for optional property', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        value: {
+          oneOf: [
+            { type: 'string' },
+            { type: 'number' },
+          ],
+        },
+      },
+      required: [],
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    const oneOf = props['value']['oneOf'] as Record<string, unknown>[];
+    expect(oneOf).toHaveLength(3);
+    expect(oneOf[2]).toEqual({ type: 'null' });
+  });
+
+  it('appends null to existing anyOf for optional property', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        value: {
+          anyOf: [
+            { type: 'string' },
+            { type: 'integer' },
+          ],
+        },
+      },
+      required: [],
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    const anyOf = props['value']['anyOf'] as Record<string, unknown>[];
+    expect(anyOf).toHaveLength(3);
+    expect(anyOf[2]).toEqual({ type: 'null' });
+  });
+
+  it('does not double-add null to oneOf that already has null', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        value: {
+          oneOf: [
+            { type: 'string' },
+            { type: 'null' },
+          ],
+        },
+      },
+      required: [],
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    const oneOf = props['value']['oneOf'] as Record<string, unknown>[];
+    expect(oneOf).toHaveLength(2);
+  });
+
+  it('does not add null to already-nullable type array', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        value: { type: ['string', 'null'] },
+      },
+      required: [],
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['value']['type']).toEqual(['string', 'null']);
+  });
+});
+
+describe('applyLlmDescriptions - definitions and combinators', () => {
+  it('recurses into definitions block', () => {
+    const schema: Record<string, unknown> = {
+      definitions: {
+        Foo: { description: 'old', 'x-llm-description': 'new' },
+      },
+    };
+    applyLlmDescriptions(schema);
+    const defs = schema['definitions'] as Record<string, Record<string, unknown>>;
+    expect(defs['Foo']['description']).toBe('new');
+  });
+
+  it('recurses into $defs block', () => {
+    const schema: Record<string, unknown> = {
+      $defs: {
+        Bar: { description: 'old', 'x-llm-description': 'updated' },
+      },
+    };
+    applyLlmDescriptions(schema);
+    const defs = schema['$defs'] as Record<string, Record<string, unknown>>;
+    expect(defs['Bar']['description']).toBe('updated');
+  });
+
+  it('recurses into items', () => {
+    const schema: Record<string, unknown> = {
+      type: 'array',
+      items: { 'x-llm-description': 'item desc' },
+    };
+    applyLlmDescriptions(schema);
+    const items = schema['items'] as Record<string, unknown>;
+    expect(items['description']).toBe('item desc');
+  });
+
+  it('recurses into oneOf/anyOf/allOf', () => {
+    const schema: Record<string, unknown> = {
+      oneOf: [
+        { 'x-llm-description': 'variant A' },
+        { 'x-llm-description': 'variant B' },
+      ],
+    };
+    applyLlmDescriptions(schema);
+    const oneOf = schema['oneOf'] as Record<string, unknown>[];
+    expect(oneOf[0]['description']).toBe('variant A');
+    expect(oneOf[1]['description']).toBe('variant B');
+  });
+
+  it('sets description even when no prior description exists', () => {
+    const schema: Record<string, unknown> = {
+      'x-llm-description': 'brand new',
+    };
+    applyLlmDescriptions(schema);
+    expect(schema['description']).toBe('brand new');
+  });
+});
+
 describe('stripExtensions', () => {
   it('removes x- prefixed keys', () => {
     const schema: Record<string, unknown> = {
@@ -136,4 +332,17 @@ describe('stripExtensions', () => {
     const props = schema['properties'] as Record<string, Record<string, unknown>>;
     expect(props['name']['x-sensitive']).toBeUndefined();
   });
+
+  it('recurses into arrays', () => {
+    const schema: Record<string, unknown> = {
+      oneOf: [
+        { type: 'string', 'x-remove': true },
+        { type: 'number', default: 0 },
+      ],
+    };
+    stripExtensions(schema);
+    const oneOf = schema['oneOf'] as Record<string, unknown>[];
+    expect(oneOf[0]['x-remove']).toBeUndefined();
+    expect(oneOf[1]['default']).toBeUndefined();
+  });
 });