470
expect(input).toEqual(snapshot);
471
});
472
});
473
+
474
+describe('null acceptance', () => {
475
+ const NULL_BRANCH = { type: 'null' };
476
+ const DIRECTION = { enum: ['asc', null] };
477
+ const wrapped = (schema: unknown) => ({ anyOf: [schema, NULL_BRANCH] });
478
+ const toolSchema = (property: unknown, definitions: unknown = { Direction: DIRECTION }) => ({
479
+ type: 'object',
480
+ properties: { value: property },
481
+ $defs: definitions,
482
+ });
483
+
484
+ it.each<[Record<string, unknown>, Record<string, unknown>]>([
485
+ [{ type: 'string', enum: ['asc', 'desc'] }, wrapped({ type: 'string', enum: ['asc', 'desc'] })],
486
+ [
487
+ { type: ['string', 'null'], enum: ['asc', 'desc'] },
488
+ wrapped({ type: ['string', 'null'], enum: ['asc', 'desc'] }),
489
+ ],
490
+ [{ type: 'string', const: 'asc' }, wrapped({ type: 'string', const: 'asc' })],
491
+ [
492
+ { type: 'integer', enum: [1, 2], description: 'page size' },
493
+ { description: 'page size', ...wrapped({ type: 'integer', enum: [1, 2] }) },
494
+ ],
495
+ [
496
+ { type: 'string', anyOf: [{ minLength: 1 }] },
497
+ wrapped({ type: 'string', anyOf: [{ minLength: 1 }] }),
498
+ ],
499
+ [
500
+ { enum: ['asc'], anyOf: [{ type: 'string' }, NULL_BRANCH] },
501
+ wrapped({ enum: ['asc'], anyOf: [{ type: 'string' }, NULL_BRANCH] }),
502
+ ],
503
+ [
504
+ { $ref: '#/$defs/Direction', type: 'string' },
505
+ wrapped({ $ref: '#/$defs/Direction', type: 'string' }),
506
+ ],
507
+ // Already nullable: left alone.
508
+ [
509
+ { type: ['string', 'null'], enum: ['asc', null] },
510
+ { type: ['string', 'null'], enum: ['asc', null] },
511
+ ],
512
+ [{ $ref: '#/$defs/Direction' }, { $ref: '#/$defs/Direction' }],
513
+ [{ anyOf: [{ type: ['string', 'null'] }] }, { anyOf: [{ type: ['string', 'null'] }] }],
514
+ // `type` or `anyOf` as the only obstacle: widened in place.
515
+ [
516
+ { type: 'string', minLength: 1 },
517
+ { type: ['string', 'null'], minLength: 1 },
518
+ ],
519
+ [
520
+ { anyOf: [{ type: 'string' }], description: 'd' },
521
+ { anyOf: [{ type: 'string' }, NULL_BRANCH], description: 'd' },
522
+ ],
523
+ ])('widening keeps every constraint: %j', (property, expected) => {
524
+ const source = toolSchema(property);
525
+ const snapshot = structuredClone(source);
526
+ const result = toStrictJsonSchema(source);
527
+
528
+ expect(result.unsupported).toEqual([]);
529
+ expect(propertyOf(result.schema, 'value')).toEqual(expected);
530
+ expect(result.schema.required).toEqual(['value']);
531
+ expect(source).toEqual(snapshot);
532
+ const again = toStrictJsonSchema(result.schema);
533
+ expect(again.schema).toEqual(result.schema);
534
+ expect(again.changes).toEqual([]);
535
+ });
536
+
537
+ it.each<[unknown, boolean]>([
538
+ [{ type: ['string', 'null'], enum: ['asc', 'desc'] }, false],
539
+ [{ type: ['string', 'null'], const: 'asc' }, false],
540
+ [{ type: ['string', 'null'], enum: ['asc', null] }, true],
541
+ [{ type: ['string', 'null'], const: null }, true],
542
+ [{ $ref: '#/$defs/Direction' }, true],
543
+ [{ $ref: '#/$defs/Direction', type: 'string' }, false],
544
+ [{ $ref: '#/$defs/Direction', enum: ['asc'] }, false],
545
+ [{ $ref: '#/$defs/Missing' }, false],
546
+ [{ $ref: 1 }, false],
547
+ [{ allOf: [{ type: ['string', 'null'] }, { enum: ['asc'] }] }, false],
548
+ [{ allOf: [{ type: ['string', 'null'] }, DIRECTION] }, true],
549
+ [{ oneOf: [NULL_BRANCH, { type: 'string' }] }, true],
550
+ [{ oneOf: [NULL_BRANCH, { enum: [null] }] }, false],
551
+ [{ not: NULL_BRANCH }, false],
552
+ [{ not: { type: 'string' } }, true],
553
+ [{ if: NULL_BRANCH, then: { type: 'string' } }, false],
554
+ [{ if: { type: 'string' }, then: { type: 'string' } }, true],
555
+ [{ if: { type: 'string' }, else: { type: 'string' } }, false],
556
+ [true, true],
557
+ [false, false],
558
+ ])('null is kept only when every keyword accepts it: %j', (property, kept) => {
559
+ const input = { value: null };
560
+ expect(omitNullToolArguments(input, toolSchema(property))).toEqual(kept ? { value: null } : {});
561
+ expect(input).toEqual({ value: null });
562
+ });
563
+
564
+ it.each<[Record<string, unknown>, boolean]>([
565
+ [{ a: { $ref: '#/$defs/a' } }, false],
566
+ [{ a: { $ref: '#/$defs/b' }, b: { $ref: '#/$defs/a' } }, false],
567
+ [{ a: { anyOf: [{ $ref: '#/$defs/a' }] } }, false],
568
+ [{ a: { type: 'null', oneOf: [{ $ref: '#/$defs/a' }] } }, false],
569
+ [{ a: { anyOf: [{ $ref: '#/$defs/b' }] }, b: { anyOf: [{ $ref: '#/$defs/a' }] } }, false],
570
+ [{ a: { anyOf: [{ $ref: '#/$defs/a' }, NULL_BRANCH] } }, true],
571
+ [{ a: { oneOf: [{ $ref: '#/$defs/a' }, NULL_BRANCH] } }, true],
572
+ ])('reference cycles terminate: %j', (definitions, kept) => {
573
+ const source = toolSchema({ $ref: '#/$defs/a' }, definitions);
574
+ expect(omitNullToolArguments({ value: null }, source)).toEqual(kept ? { value: null } : {});
575
+ expect(toStrictJsonSchema(source).unsupported).toEqual([]);
576
+ });
577
+
578
+ it('checks a node reached twice outside a cycle each time', () => {
579
+ const shared = { anyOf: [NULL_BRANCH] };
580
+ const source = { type: 'object', properties: { value: { allOf: [shared, shared] } } };
581
+ expect(omitNullToolArguments({ value: null }, source)).toEqual({ value: null });
582
+ });
583
+
584
+ /** `a0` is the leaf; every `a(i)` references `a(i-1)` twice, so paths double per level. */
585
+ const diamond = (levels: number, keyword: string, leaf: unknown) => {
586
+ const definitions: Record<string, unknown> = { a0: leaf };
587
+ for (let i = 1; i <= levels; i++) {
588
+ const ref = { $ref: `#/$defs/a${i - 1}` };
589
+ definitions[`a${i}`] = { [keyword]: [ref, ref] };
590
+ }
591
+ return toolSchema({ $ref: `#/$defs/a${levels}` }, definitions);
592
+ };
593
+
594
+ it('evaluates a definition shared by many branches once', () => {
595
+ const rejecting = diamond(20, 'anyOf', { type: 'string' });
596
+ expect(propertyOf(toStrictJsonSchema(rejecting).schema, 'value')).toEqual(
597
+ wrapped({ $ref: '#/$defs/a20' })
598
+ );
599
+ expect(omitNullToolArguments({ value: null }, rejecting)).toEqual({});
600
+
601
+ const accepting = diamond(20, 'allOf', NULL_BRANCH);
602
+ expect(omitNullToolArguments({ value: null }, accepting)).toEqual({ value: null });
603
+ });
604
+
605
+ it('stays bounded when cycles keep answers from being remembered', () => {
606
+ // Every level also points back at the top, so no answer below it is final.
607
+ const levels = 20;
608
+ const definitions: Record<string, unknown> = { a0: { type: 'string' } };
609
+ for (let i = 1; i <= levels; i++) {
610
+ const ref = { $ref: `#/$defs/a${i - 1}` };
611
+ definitions[`a${i}`] = { anyOf: [ref, ref, { $ref: `#/$defs/a${levels}` }] };
612
+ }
613
+ const source = toolSchema({ $ref: `#/$defs/a${levels}` }, definitions);
614
+ expect(omitNullToolArguments({ value: null }, source)).toEqual({});
615
+ expect(propertyOf(toStrictJsonSchema(source).schema, 'value')).toEqual(
616
+ wrapped({ $ref: `#/$defs/a${levels}` })
617
+ );
618
+ });
619
+
620
+ it('does not prove null through a reference chain past the depth bound', () => {
621
+ const definitions: Record<string, unknown> = { a0: NULL_BRANCH };
622
+ for (let i = 1; i <= 100; i++) definitions[`a${i}`] = { $ref: `#/$defs/a${i - 1}` };
623
+ expect(
624
+ omitNullToolArguments({ value: null }, toolSchema({ $ref: '#/$defs/a100' }, definitions))
625
+ ).toEqual({});
626
+ expect(
627
+ omitNullToolArguments({ value: null }, toolSchema({ $ref: '#/$defs/a10' }, definitions))
628
+ ).toEqual({ value: null });
629
+ });
630
+
631
+ it('adds a null branch to a $ref whose target the rewrite types as an object', () => {
632
+ const source = {
633
+ type: 'object',
634
+ properties: { node: { $ref: '#/$defs/Node' } },
635
+ $defs: {
636
+ Node: { properties: { label: { type: 'string' }, child: { $ref: '#/$defs/Node' } } },
637
+ },
638
+ };
639
+ const { schema, unsupported } = toStrictJsonSchema(source);
640
+ const definitions = schema.$defs as Record<string, Record<string, unknown>>;
641
+
642
+ expect(unsupported).toEqual([]);
643
+ expect(propertyOf(schema, 'node')).toEqual(wrapped({ $ref: '#/$defs/Node' }));
644
+ expect(definitions.Node.type).toBe('object');
645
+ expect(propertyOf(definitions.Node, 'child')).toEqual(wrapped({ $ref: '#/$defs/Node' }));
646
+ // The tool's own schema accepts the null, so it is forwarded.
647
+ expect(omitNullToolArguments({ node: null }, source)).toEqual({ node: null });
648
+ });
649
+
650
+ it('reports a $ref into a property that wrapping moved', () => {
651
+ const { unsupported } = toStrictJsonSchema({
652
+ type: 'object',
653
+ properties: {
654
+ value: { type: 'string', enum: ['asc'], $defs: { Text: { type: 'string' } } },
655
+ alias: { $ref: '#/properties/value/$defs/Text' },
656
+ },
657
+ required: ['alias'],
658
+ });
659
+ expect(unsupported.map(({ path, keyword }) => ({ path, keyword }))).toEqual([
660
+ { path: 'properties.alias', keyword: '$ref' },
661
+ ]);
662
+ });
663
+
664
+ it('shares what it learned about a cyclic definition across many properties', () => {
665
+ const levels = 20;
666
+ const top = `#/$defs/a${levels}`;
667
+ const definitions: Record<string, unknown> = { a0: { type: 'string' } };
668
+ for (let i = 1; i <= levels; i++) {
669
+ const lower = `#/$defs/a${i - 1}`;
670
+ definitions[`a${i}`] = { anyOf: [{ $ref: lower }, { $ref: lower }, { $ref: top }] };
671
+ }
672
+ const names = Array.from({ length: 400 }, (_, i) => `p${i}`);
673
+ const source = {
674
+ type: 'object',
675
+ properties: Object.fromEntries(names.map(name => [name, { $ref: top }])),
676
+ $defs: definitions,
677
+ };
678
+ const { schema } = toStrictJsonSchema(source);
679
+ for (const name of names) expect(propertyOf(schema, name)).toEqual(wrapped({ $ref: top }));
680
+ const input = Object.fromEntries(names.map(name => [name, null]));
681
+ expect(omitNullToolArguments(input, source)).toEqual({});
682
+ });
683
+
684
+ it('keeps a check that runs out of budget from affecting the next one', () => {
685
+ const source = {
686
+ type: 'object',
687
+ properties: {
688
+ wide: { anyOf: Array.from({ length: 5000 }, () => ({ type: 'string' })) },
689
+ note: { type: ['string', 'null'] },
690
+ same: { anyOf: [{ type: 'string' }, NULL_BRANCH] },
691
+ },
692
+ };
693
+ expect(omitNullToolArguments({ wide: null, note: null, same: null }, source)).toEqual({
694
+ note: null,
695
+ same: null,
696
+ });
697
+ const { schema } = toStrictJsonSchema(source);
698
+ expect(propertyOf(schema, 'note')).toEqual({ type: ['string', 'null'] });
699
+ expect(propertyOf(schema, 'same')).toEqual({ anyOf: [{ type: 'string' }, NULL_BRANCH] });
700
+ });
701
+
702
+ it('proves nothing in a check that meets a bound', () => {
703
+ // Both branches accept null, so `oneOf` rejects it; the second is only
704
+ // reachable past the depth bound and must not count as a rejection.
705
+ const definitions: Record<string, unknown> = { a0: NULL_BRANCH };
706
+ for (let i = 1; i <= 70; i++) definitions[`a${i}`] = { $ref: `#/$defs/a${i - 1}` };
707
+ const deep = { $ref: '#/$defs/a70' };
708
+ const properties = {
709
+ one: { oneOf: [NULL_BRANCH, deep] },
710
+ negated: { not: deep },
711
+ guarded: { if: deep, else: NULL_BRANCH },
712
+ // Reaches a node the checks above left unproven.
713
+ later: { not: { $ref: '#/$defs/a69' } },
714
+ };
715
+ const source = { type: 'object', properties, $defs: definitions };
716
+ const input = Object.fromEntries(Object.keys(properties).map(name => [name, null]));
717
+ expect(omitNullToolArguments(input, source)).toEqual({});
718
+ });
719
+
720
+ it('does not evaluate an unproven definition again for each property', () => {
721
+ // `top` is cyclic and wider than the budget, so nothing about it settles.
722
+ const top = { $ref: '#/$defs/top' };
723
+ const definitions: Record<string, unknown> = {
724
+ top: { anyOf: Array.from({ length: 3000 }, (_, i) => ({ $ref: `#/$defs/b${i}` })) },
725
+ };
726
+ for (let i = 0; i < 3000; i++) definitions[`b${i}`] = { anyOf: [top, { type: 'string' }] };
727
+ const names = Array.from({ length: 2000 }, (_, i) => `p${i}`);
728
+ const source = {
729
+ type: 'object',
730
+ properties: Object.fromEntries(names.map(name => [name, { ...top }])),
731
+ $defs: definitions,
732
+ };
733
+ const input = Object.fromEntries(names.map(name => [name, null]));
734
+ expect(omitNullToolArguments(input, source)).toEqual({});
735
+ const { schema } = toStrictJsonSchema(source);
736
+ for (const name of names) expect(propertyOf(schema, name)).toEqual(wrapped(top));
737
+ });
738
+});