|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +import { describe, it, expect } from 'vitest'; |
| 4 | +import { ObjectSchema, ObjectExtensionSchema } from './object.zod'; |
| 5 | +import { FieldSchema } from './field.zod'; |
| 6 | +import { classifyDottedFilterHead } from './filter-dotted-head'; |
| 7 | + |
| 8 | +// --------------------------------------------------------------------------- |
| 9 | +// [#14892] A `tree` field's `reference`, when present, must name the declaring |
| 10 | +// object — maintainer ruling 2026-09-05, option A. Four surfaces used to answer |
| 11 | +// "what does a tree's `reference` mean" four different ways and nothing read or |
| 12 | +// refused any of them; this file pins the ONE answer at the door that can judge |
| 13 | +// it (the object schema, where the own name is known) and the shape it leaves |
| 14 | +// alone (the field schema, which never sees a name). |
| 15 | +// |
| 16 | +// The pins bear weight in three directions: the two accepted shapes (self, and |
| 17 | +// absent — absent stays `relation` and still materialises `deleteBehavior`, the |
| 18 | +// fifth reading the ruling folds in), the refused shape with its located issue, |
| 19 | +// and the field-level door that deliberately does NOT refuse. |
| 20 | +// --------------------------------------------------------------------------- |
| 21 | + |
| 22 | +const zoo = (reference?: string) => ({ |
| 23 | + name: 'showcase_field_zoo', |
| 24 | + fields: { |
| 25 | + name: { type: 'text', label: 'Name' }, |
| 26 | + f_tree: { type: 'tree', label: 'Tree', ...(reference === undefined ? {} : { reference }) }, |
| 27 | + }, |
| 28 | +}); |
| 29 | + |
| 30 | +const firstSentence = (message: string): string => message.split(/\.\s/)[0]; |
| 31 | + |
| 32 | +describe('[#14892] a `tree` field\'s `reference` must name the declaring object', () => { |
| 33 | + it('accepts a self-reference through the object schema, and through create()', () => { |
| 34 | + const parsed = ObjectSchema.safeParse(zoo('showcase_field_zoo')); |
| 35 | + expect(parsed.success, parsed.success ? '' : JSON.stringify(parsed.error.issues)).toBe(true); |
| 36 | + if (!parsed.success) return; |
| 37 | + expect(parsed.data.fields.f_tree.reference).toBe('showcase_field_zoo'); |
| 38 | + // The relational family's delete semantics: a self-referential hierarchy |
| 39 | + // is a relation and its cascade default is exactly the intended meaning. |
| 40 | + expect(parsed.data.fields.f_tree.deleteBehavior).toBe('set_null'); |
| 41 | + |
| 42 | + const created = ObjectSchema.create(zoo('showcase_field_zoo') as never); |
| 43 | + expect(created.fields.f_tree.reference).toBe('showcase_field_zoo'); |
| 44 | + }); |
| 45 | + |
| 46 | + it('accepts an ABSENT reference — a redundant self-annotation may be omitted — and it is still a relation', () => { |
| 47 | + const parsed = ObjectSchema.safeParse(zoo()); |
| 48 | + expect(parsed.success, parsed.success ? '' : JSON.stringify(parsed.error.issues)).toBe(true); |
| 49 | + if (!parsed.success) return; |
| 50 | + expect(parsed.data.fields.f_tree.reference).toBeUndefined(); |
| 51 | + // The fifth reading (folded from #13928): a reference-less `tree` is |
| 52 | + // classified `relation` and still materialises `deleteBehavior` beside |
| 53 | + // `lookup` — coherent under this rule, because the hierarchy it declares |
| 54 | + // is self-referential by definition. |
| 55 | + expect(parsed.data.fields.f_tree.deleteBehavior).toBe('set_null'); |
| 56 | + expect(classifyDottedFilterHead({ type: 'tree' })).toBe('relation'); |
| 57 | + }); |
| 58 | + |
| 59 | + it('refuses a `tree` naming ANOTHER object, at the field\'s `reference`, naming both objects', () => { |
| 60 | + const parsed = ObjectSchema.safeParse(zoo('showcase_category')); |
| 61 | + expect(parsed.success).toBe(false); |
| 62 | + if (parsed.success) return; |
| 63 | + expect(parsed.error.issues).toHaveLength(1); |
| 64 | + const [issue] = parsed.error.issues; |
| 65 | + expect(issue.code).toBe('custom'); |
| 66 | + expect(issue.path).toEqual(['fields', 'f_tree', 'reference']); |
| 67 | + // The message's first sentence names the declaring object AND the object |
| 68 | + // the field wrongly points at — the envelope an author greps for. |
| 69 | + const first = firstSentence(issue.message); |
| 70 | + expect(first).toContain('`showcase_field_zoo`'); |
| 71 | + expect(first).toContain('`showcase_category`'); |
| 72 | + expect(first).toContain('`f_tree`'); |
| 73 | + // The remedy travels with the refusal: drop it, self-reference, or lookup. |
| 74 | + expect(issue.message).toContain("'showcase_field_zoo'"); |
| 75 | + expect(issue.message).toContain('`lookup`'); |
| 76 | + |
| 77 | + // The authoring door throws the same located issue. |
| 78 | + expect(() => ObjectSchema.create(zoo('showcase_category') as never)).toThrow(/showcase_category/); |
| 79 | + }); |
| 80 | + |
| 81 | + it('judges each `tree` field on its own: one foreign pointer beside a self-reference is one issue', () => { |
| 82 | + const parsed = ObjectSchema.safeParse({ |
| 83 | + name: 'category', |
| 84 | + fields: { |
| 85 | + name: { type: 'text', label: 'Name' }, |
| 86 | + parent: { type: 'tree', label: 'Parent', reference: 'category' }, |
| 87 | + stray: { type: 'tree', label: 'Stray', reference: 'department' }, |
| 88 | + }, |
| 89 | + }); |
| 90 | + expect(parsed.success).toBe(false); |
| 91 | + if (parsed.success) return; |
| 92 | + expect(parsed.error.issues.map((i) => i.path)).toEqual([['fields', 'stray', 'reference']]); |
| 93 | + }); |
| 94 | + |
| 95 | + it('is scoped to `tree`: a lookup / master_detail to another object is untouched (control)', () => { |
| 96 | + const parsed = ObjectSchema.safeParse({ |
| 97 | + name: 'showcase_field_zoo', |
| 98 | + fields: { |
| 99 | + name: { type: 'text', label: 'Name' }, |
| 100 | + f_lookup: { type: 'lookup', label: 'Account', reference: 'showcase_account' }, |
| 101 | + f_master_detail: { type: 'master_detail', label: 'Project', reference: 'showcase_project' }, |
| 102 | + }, |
| 103 | + }); |
| 104 | + expect(parsed.success, parsed.success ? '' : JSON.stringify(parsed.error.issues)).toBe(true); |
| 105 | + }); |
| 106 | + |
| 107 | + it('the field schema alone does NOT refuse — it never learns the declaring object\'s name', () => { |
| 108 | + // Where the rule lives is part of the contract: `FieldSchema` cannot judge |
| 109 | + // a foreign target, so `field.test.ts`'s field-level tree fixtures keep |
| 110 | + // parsing and the refusal is the object door's alone. |
| 111 | + const parsed = FieldSchema.safeParse({ name: 'parent_id', label: 'Parent', type: 'tree', reference: 'category' }); |
| 112 | + expect(parsed.success).toBe(true); |
| 113 | + }); |
| 114 | + |
| 115 | + it('the extension door judges against the object it extends', () => { |
| 116 | + const self = ObjectExtensionSchema.safeParse({ |
| 117 | + extend: 'contact', |
| 118 | + fields: { parent_contact: { type: 'tree', label: 'Parent', reference: 'contact' } }, |
| 119 | + }); |
| 120 | + expect(self.success, self.success ? '' : JSON.stringify(self.error.issues)).toBe(true); |
| 121 | + |
| 122 | + const foreign = ObjectExtensionSchema.safeParse({ |
| 123 | + extend: 'contact', |
| 124 | + fields: { parent_contact: { type: 'tree', label: 'Parent', reference: 'company' } }, |
| 125 | + }); |
| 126 | + expect(foreign.success).toBe(false); |
| 127 | + if (foreign.success) return; |
| 128 | + expect(foreign.error.issues.map((i) => i.path)).toEqual([['fields', 'parent_contact', 'reference']]); |
| 129 | + expect(firstSentence(foreign.error.issues[0].message)).toContain('`contact`'); |
| 130 | + expect(firstSentence(foreign.error.issues[0].message)).toContain('`company`'); |
| 131 | + }); |
| 132 | +}); |
0 commit comments