|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [#24332] A navigation entry may declare ONE API data source — the page |
| 5 | + * element's `ElementApiDataSourceSchema`, BY REFERENCE — and its `visible` |
| 6 | + * reads the bound value as `data` (shape 1 of the card, the spec half of the |
| 7 | + * objectstack-ai/cloud#3002 letter A sidebar row). |
| 8 | + * |
| 9 | + * What is pinned here is the SHAPE half: |
| 10 | + * |
| 11 | + * 1. the binding parses on every branch that spreads the shared nav base, and |
| 12 | + * on a `group`'s child, beside a `visible` that reads `data.*`; |
| 13 | + * 2. it is the page element's binding and not a restatement of it: the nav |
| 14 | + * door refuses an unknown key, an off-origin `read.url`, a credential key |
| 15 | + * and the object binding at the nav item's own path, with the very issue |
| 16 | + * the page element's binding raises for the same value; |
| 17 | + * 3. a separator refuses the key with its own prescription; |
| 18 | + * 4. the key is PLANNED: its describe carries the marker and its liveness row |
| 19 | + * is `planned`, never `live`, until the navigation renderer reads it. |
| 20 | + * |
| 21 | + * The refusal sentences are the binding's own and are deliberately not pinned |
| 22 | + * as text: each refusal is compared with the page element's answer for the |
| 23 | + * same input, which is the claim (one binding, one set of refusals). |
| 24 | + */ |
| 25 | +import fs from 'node:fs'; |
| 26 | + |
| 27 | +import { describe, it, expect } from 'vitest'; |
| 28 | + |
| 29 | +import { AppSchema, NavigationItemSchema, ObjectNavItemSchema } from './app.zod'; |
| 30 | +import { ElementApiDataSourceSchema } from './page.zod'; |
| 31 | + |
| 32 | +const API_BINDING = { provider: 'api', read: { url: '/api/v1/cloud/home' }, path: 'data.environments' } as const; |
| 33 | + |
| 34 | +/** One entry per branch that spreads the shared nav base — every `type` but `separator`. */ |
| 35 | +const BRANCHES: ReadonlyArray<[string, Record<string, unknown>]> = [ |
| 36 | + ['object', { type: 'object', objectName: 'sys_environment' }], |
| 37 | + ['dashboard', { type: 'dashboard', dashboardName: 'ops' }], |
| 38 | + ['page', { type: 'page', pageName: 'environment_home' }], |
| 39 | + ['url', { type: 'url', url: '/apps/cloud' }], |
| 40 | + ['report', { type: 'report', reportName: 'usage' }], |
| 41 | + ['action', { type: 'action', actionDef: { actionName: 'create_environment' } }], |
| 42 | + ['component', { type: 'component', componentRef: 'metadata:directory' }], |
| 43 | + ['doc', { type: 'doc', book: 'cloud_manual' }], |
| 44 | + ['group', { type: 'group', children: [] }], |
| 45 | +]; |
| 46 | + |
| 47 | +const withNav = (navigation: unknown[]) => ({ name: 'cloud_console', label: 'Cloud', navigation }); |
| 48 | + |
| 49 | +/** The page element binding's own issues for `value`, re-rooted at `prefix`. */ |
| 50 | +const bindingIssues = (value: unknown, prefix: PropertyKey[]) => { |
| 51 | + const r = ElementApiDataSourceSchema.safeParse(value); |
| 52 | + expect(r.success, 'control: the page element binding must refuse this value too').toBe(false); |
| 53 | + return r.error!.issues.map((i) => ({ code: i.code, path: [...prefix, ...i.path], message: i.message })); |
| 54 | +}; |
| 55 | + |
| 56 | +const navIssues = (item: Record<string, unknown>) => { |
| 57 | + const r = NavigationItemSchema.safeParse(item); |
| 58 | + expect(r.success).toBe(false); |
| 59 | + return r.error!.issues.map((i) => ({ code: i.code, path: i.path, message: i.message })); |
| 60 | +}; |
| 61 | + |
| 62 | +describe('navigation item `dataSource` — accepted on every branch that spreads the base', () => { |
| 63 | + it.each(BRANCHES)('a `%s` entry parses with the API binding and a `visible` reading `data`', (_name, target) => { |
| 64 | + const item = { id: 'nav_environments', label: 'Environments', visible: 'data.total == 1', dataSource: API_BINDING, ...target }; |
| 65 | + const r = NavigationItemSchema.safeParse(item); |
| 66 | + expect(r.success, JSON.stringify(r.error?.issues)).toBe(true); |
| 67 | + expect((r.data as { dataSource?: unknown }).dataSource).toEqual(API_BINDING); |
| 68 | + }); |
| 69 | + |
| 70 | + it('parses through the app door, on a top-level entry and on a group\'s child', () => { |
| 71 | + const r = AppSchema.safeParse(withNav([ |
| 72 | + { id: 'nav_environments', type: 'object', objectName: 'sys_environment', visible: 'data.total != 1', dataSource: API_BINDING }, |
| 73 | + { |
| 74 | + id: 'grp_tenancy', type: 'group', label: 'Tenancy', |
| 75 | + children: [{ id: 'nav_environment_home', type: 'page', pageName: 'environment_home', visible: 'data.total == 1', dataSource: API_BINDING }], |
| 76 | + }, |
| 77 | + ])); |
| 78 | + expect(r.success, JSON.stringify(r.error?.issues)).toBe(true); |
| 79 | + }); |
| 80 | + |
| 81 | + it('accepts the bare binding: `path` and `read.method` stay optional, and `GET` is the one method', () => { |
| 82 | + for (const dataSource of [ |
| 83 | + { provider: 'api', read: { url: '/api/v1/cloud/home' } }, |
| 84 | + { provider: 'api', read: { url: '/api/v1/cloud/home', method: 'GET' } }, |
| 85 | + ]) { |
| 86 | + const r = ObjectNavItemSchema.safeParse({ id: 'nav_environments', type: 'object', objectName: 'sys_environment', dataSource }); |
| 87 | + expect(r.success, JSON.stringify(r.error?.issues)).toBe(true); |
| 88 | + } |
| 89 | + }); |
| 90 | +}); |
| 91 | + |
| 92 | +describe('navigation item `dataSource` — the page element binding\'s refusals, at the nav item\'s path', () => { |
| 93 | + const entry = (dataSource: unknown) => ({ id: 'nav_environments', type: 'object', objectName: 'sys_environment', dataSource }); |
| 94 | + |
| 95 | + it('refuses an unknown key on the binding, not drops it', () => { |
| 96 | + const value = { ...API_BINDING, refresh: 30 }; |
| 97 | + const issues = navIssues(entry(value)); |
| 98 | + expect(issues).toEqual(bindingIssues(value, ['dataSource'])); |
| 99 | + expect(issues[0]).toMatchObject({ code: 'unrecognized_keys', path: ['dataSource'] }); |
| 100 | + }); |
| 101 | + |
| 102 | + it('refuses an off-origin `read.url` at `dataSource.read.url`', () => { |
| 103 | + for (const url of ['https://api.example.com/v1/home', '//evil.example/home', 'api/v1/home']) { |
| 104 | + const value = { provider: 'api', read: { url } }; |
| 105 | + const issues = navIssues(entry(value)); |
| 106 | + expect(issues, url).toEqual(bindingIssues(value, ['dataSource'])); |
| 107 | + expect(issues[0], url).toMatchObject({ code: 'invalid_format', path: ['dataSource', 'read', 'url'] }); |
| 108 | + } |
| 109 | + }); |
| 110 | + |
| 111 | + it('refuses a credential key inside the read request', () => { |
| 112 | + const value = { provider: 'api', read: { url: '/api/v1/cloud/home', headers: { authorization: 'Bearer x' } } }; |
| 113 | + const issues = navIssues(entry(value)); |
| 114 | + expect(issues).toEqual(bindingIssues(value, ['dataSource'])); |
| 115 | + expect(issues[0]).toMatchObject({ code: 'unrecognized_keys', path: ['dataSource', 'read'] }); |
| 116 | + }); |
| 117 | + |
| 118 | + it('refuses a method other than `GET`', () => { |
| 119 | + const value = { provider: 'api', read: { url: '/api/v1/cloud/home', method: 'POST' } }; |
| 120 | + const issues = navIssues(entry(value)); |
| 121 | + expect(issues).toEqual(bindingIssues(value, ['dataSource'])); |
| 122 | + expect(issues[0]).toMatchObject({ code: 'invalid_value', path: ['dataSource', 'read', 'method'] }); |
| 123 | + }); |
| 124 | + |
| 125 | + it('does not admit the page element\'s OBJECT binding — a nav entry binds an API answer only', () => { |
| 126 | + const value = { object: 'sys_environment', limit: 1 }; |
| 127 | + const issues = navIssues(entry(value)); |
| 128 | + expect(issues).toEqual(bindingIssues(value, ['dataSource'])); |
| 129 | + expect(issues.every((i) => i.path[0] === 'dataSource'), JSON.stringify(issues)).toBe(true); |
| 130 | + }); |
| 131 | +}); |
| 132 | + |
| 133 | +describe('a separator refuses `dataSource` with its own prescription', () => { |
| 134 | + it('answers with the separator guidance, not a bare unknown key', () => { |
| 135 | + const r = NavigationItemSchema.safeParse({ type: 'separator', id: 'sep_1', dataSource: API_BINDING }); |
| 136 | + expect(r.success).toBe(false); |
| 137 | + const issue = r.error!.issues[0]; |
| 138 | + expect(issue).toMatchObject({ code: 'unrecognized_keys', path: [] }); |
| 139 | + expect(issue.message).toContain('`dataSource` is not a separator key'); |
| 140 | + }); |
| 141 | +}); |
| 142 | + |
| 143 | +describe('navigation item `dataSource` is PLANNED — declared, not yet rendered', () => { |
| 144 | + it('its describe carries the planned marker', () => { |
| 145 | + const shape = (ObjectNavItemSchema as unknown as { shape: Record<string, { description?: string }> }).shape; |
| 146 | + expect(shape.dataSource.description).toMatch(/^\[PLANNED — not yet rendered\] /); |
| 147 | + }); |
| 148 | + |
| 149 | + it('its liveness row is `planned` with an author warning, never `live`', () => { |
| 150 | + const ledger = JSON.parse(fs.readFileSync(new URL('../../liveness/app.json', import.meta.url), 'utf8')); |
| 151 | + const row = ledger.props.navigation.children.dataSource; |
| 152 | + expect(row, 'liveness/app.json navigation.children.dataSource must exist').toBeDefined(); |
| 153 | + expect(row.status).toBe('planned'); |
| 154 | + expect(row.authorWarn).toBe(true); |
| 155 | + }); |
| 156 | +}); |
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
0 commit comments