|
| 1 | +/** |
| 2 | + * ObjectUI |
| 3 | + * Copyright (c) 2024-present ObjectStack Inc. |
| 4 | + * |
| 5 | + * This source code is licensed under the MIT license found in the |
| 6 | + * LICENSE file in the root directory of this source tree. |
| 7 | + */ |
| 8 | + |
| 9 | +/** |
| 10 | + * `publish` and `publishDraft` hit ONE route and must hold ONE belief about |
| 11 | + * its wire shape (objectui#6962). |
| 12 | + * |
| 13 | + * ## What was measured, because this card forbids inferring it |
| 14 | + * |
| 15 | + * The card's own triage refused to act on `PublishMetaItemResponseSchema` |
| 16 | + * alone — "an inference from the declaration, not a measurement of the |
| 17 | + * server". So the producer was read instead, in the framework checkout: |
| 18 | + * |
| 19 | + * - `POST /api/v1/meta/:type/:name/publish` is mounted in exactly one place, |
| 20 | + * `packages/rest/src/rest-server.ts`, and that handler ends |
| 21 | + * `res.json(await p.publishMetaItem(publishRequest))` — the protocol's own |
| 22 | + * object, verbatim, with no envelope branch on any arm. The ADR-0006 |
| 23 | + * project-scoped base re-mounts the same handler. |
| 24 | + * - The `{ success, data }` envelope has ONE producer, `HttpDispatcher` |
| 25 | + * (`runtime/src/http-dispatcher.ts`, `success()` → `{ success, data, meta }`), |
| 26 | + * and it does not serve this route. `runtime/src/domains/meta.ts` has no |
| 27 | + * publish branch — its three-segment arm matches `/published` on GET only — |
| 28 | + * and `runtime/src/route-ledger.ts` carries no row for a publish POST, so a |
| 29 | + * dispatcher-fronted host answers this path with `routeNotFound`, never with |
| 30 | + * a payload. That holds for the dispatcher-only Hono adapter |
| 31 | + * (`adapters/hono`, whose `${prefix}/*` catch-all IS `dispatch()`) as much |
| 32 | + * as for a full `rest` + `plugin-hono-server` boot, where the REST mount |
| 33 | + * shadows that catch-all. |
| 34 | + * - `packages/spec` declares the split explicitly rather than by omission: |
| 35 | + * `PublishMetaItemResponseSchema` documents "the FULL body" of this route, |
| 36 | + * while its batch sibling `PublishPackageDraftsResponseSchema` documents a |
| 37 | + * body answered "inside the dispatcher's `{ success, data }` envelope". |
| 38 | + * |
| 39 | + * ⇒ The route never envelopes, so the tolerance `publishDraft` carried was a |
| 40 | + * dialect with no producer, and Commandment #0.1 says it goes. |
| 41 | + * |
| 42 | + * ## Why these pins use an envelope-shaped INPUT, and why that is the point |
| 43 | + * |
| 44 | + * A pin asserting only "publish returns the body" is worthless here: it passes |
| 45 | + * on a method that returns the body AND on one that would have unwrapped an |
| 46 | + * envelope it never receives. Those two spellings differ on exactly one input, |
| 47 | + * so that input is what gets driven. `expect(result).toEqual(ENVELOPED)` goes |
| 48 | + * RED the moment either method starts unwrapping again — which is the whole |
| 49 | + * caricature this card has to exclude (both unwrap, or the two disagree). |
| 50 | + * |
| 51 | + * ⚠️ Read the assertions as pinning ONE ANSWER FOR TWO METHODS, not as a |
| 52 | + * blessing of the enveloped body. Nothing serves it. If a server ever does, |
| 53 | + * that is a producer defect to file upstream — the answer is not a second |
| 54 | + * unwrapping site here, and the `version` assertion below says why: unwrapping |
| 55 | + * would let a body this door never served read as a successful promotion. |
| 56 | + */ |
| 57 | + |
| 58 | +import { describe, it, expect, vi } from 'vitest'; |
| 59 | +import { PublishMetaItemResponseSchema } from '@objectstack/spec/api'; |
| 60 | +import { MetadataClient, type MetadataSaveAdvisoryEvent } from './metadata-client'; |
| 61 | + |
| 62 | +/** The three keys `PublishMetaItemResponseSchema` states as REQUIRED, plus its receipt. */ |
| 63 | +const BARE_BODY = { |
| 64 | + success: true, |
| 65 | + version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0', |
| 66 | + seq: 7, |
| 67 | + message: 'Published draft — type=view, name=cases [seq=7]', |
| 68 | +}; |
| 69 | + |
| 70 | +/** |
| 71 | + * The discriminating input: the dispatcher-shaped envelope nobody serves on |
| 72 | + * this route. Deliberately carries the SAME payload as {@link BARE_BODY} one |
| 73 | + * level down, so an unwrapping method and a verbatim one return values that |
| 74 | + * differ only in the nesting — which is precisely what the pins read. |
| 75 | + */ |
| 76 | +const ENVELOPED_BODY = { success: true, data: { ...BARE_BODY } }; |
| 77 | + |
| 78 | +function response(body: unknown): Response { |
| 79 | + return new Response(JSON.stringify(body), { |
| 80 | + status: 200, |
| 81 | + headers: { 'content-type': 'application/json' }, |
| 82 | + }); |
| 83 | +} |
| 84 | + |
| 85 | +function clientWith(body: unknown, onSaveAdvisory?: (ev: MetadataSaveAdvisoryEvent) => void) { |
| 86 | + return new MetadataClient({ |
| 87 | + baseUrl: 'http://test.local', |
| 88 | + fetch: vi.fn(async () => response(body)) as unknown as typeof fetch, |
| 89 | + ...(onSaveAdvisory ? { onSaveAdvisory } : {}), |
| 90 | + }); |
| 91 | +} |
| 92 | + |
| 93 | +/** |
| 94 | + * The premise, asserted against the INSTALLED spec rather than quoted from the |
| 95 | + * card: the declared body carries its keys at the TOP LEVEL and declares no |
| 96 | + * envelope, so `data` is not a member a conformant publish response can have. |
| 97 | + * |
| 98 | + * The reverse probe is what makes it a reading rather than a restatement: the |
| 99 | + * enveloped shape must be REJECTED by the same schema, or "the bare shape |
| 100 | + * parses" would prove only that the schema accepts anything. |
| 101 | + */ |
| 102 | +describe('the declared publish body (objectstack#7294), read off the installed spec', () => { |
| 103 | + it('declares `success` / `version` / `seq` at the top level, with no envelope', () => { |
| 104 | + const bare = PublishMetaItemResponseSchema.safeParse(BARE_BODY); |
| 105 | + expect(bare.success).toBe(true); |
| 106 | + expect(bare.success && bare.data.version).toBe(BARE_BODY.version); |
| 107 | + // `data` is not a declared member, so an object schema STRIPS it — the |
| 108 | + // discriminating reading is that it does not survive the parse. |
| 109 | + const withData = PublishMetaItemResponseSchema.safeParse({ ...BARE_BODY, data: { seq: 99 } }); |
| 110 | + expect(withData.success && Object.prototype.hasOwnProperty.call(withData.data, 'data')).toBe( |
| 111 | + false, |
| 112 | + ); |
| 113 | + }); |
| 114 | + |
| 115 | + it('refuses the enveloped shape outright — `version` and `seq` are missing from it', () => { |
| 116 | + const enveloped = PublishMetaItemResponseSchema.safeParse(ENVELOPED_BODY); |
| 117 | + expect(enveloped.success).toBe(false); |
| 118 | + }); |
| 119 | +}); |
| 120 | + |
| 121 | +/** |
| 122 | + * THE CARD. One route, one spelling — driven on the only input that can tell |
| 123 | + * the two spellings apart. |
| 124 | + */ |
| 125 | +describe('publish and publishDraft answer the same route the same way (#6962)', () => { |
| 126 | + it('publishDraft returns an envelope-shaped body VERBATIM — it no longer unwraps', async () => { |
| 127 | + const result = await clientWith(ENVELOPED_BODY).publishDraft('view', 'cases'); |
| 128 | + |
| 129 | + // The whole assertion: the envelope is still an envelope on the way out. |
| 130 | + expect(result).toEqual(ENVELOPED_BODY); |
| 131 | + // Spelled out, because `toEqual` on a two-key object is easy to misread: |
| 132 | + // the payload stays NESTED and is not hoisted to the top level. |
| 133 | + expect((result as { data?: unknown }).data).toEqual(BARE_BODY); |
| 134 | + expect((result as { version?: unknown }).version).toBeUndefined(); |
| 135 | + expect((result as { seq?: unknown }).seq).toBeUndefined(); |
| 136 | + }); |
| 137 | + |
| 138 | + it('publish returns the same envelope-shaped body verbatim, as it always did', async () => { |
| 139 | + const result = await clientWith(ENVELOPED_BODY).publish<Record<string, unknown>>('view', 'cases'); |
| 140 | + |
| 141 | + expect(result).toEqual(ENVELOPED_BODY); |
| 142 | + expect(result.version).toBeUndefined(); |
| 143 | + }); |
| 144 | + |
| 145 | + it('the two methods return DEEP-EQUAL values for one response — the disagreement is gone', async () => { |
| 146 | + // The card itself: same route, same bytes, two methods. Compared as |
| 147 | + // values rather than asserted twice, so a future edit that changes one |
| 148 | + // method's shape cannot leave the other silently behind. |
| 149 | + const viaPublish = await clientWith(ENVELOPED_BODY).publish('view', 'cases'); |
| 150 | + const viaDraft = await clientWith(ENVELOPED_BODY).publishDraft('view', 'cases'); |
| 151 | + expect(viaDraft).toEqual(viaPublish); |
| 152 | + |
| 153 | + const bareViaPublish = await clientWith(BARE_BODY).publish('view', 'cases'); |
| 154 | + const bareViaDraft = await clientWith(BARE_BODY).publishDraft('view', 'cases'); |
| 155 | + expect(bareViaDraft).toEqual(bareViaPublish); |
| 156 | + }); |
| 157 | + |
| 158 | + /** |
| 159 | + * ⚠️ The `undefined === undefined` trap this card is actually about. |
| 160 | + * |
| 161 | + * `version` reading `undefined` IS the failure mode under investigation, so |
| 162 | + * a pin that merely compared it to `undefined` would prove nothing. Both |
| 163 | + * legs below therefore assert a CONCRETE token, and the enveloped leg above |
| 164 | + * asserts the absence separately — the two together are what separate "the |
| 165 | + * OCC token is readable" from "both sides are blank". |
| 166 | + */ |
| 167 | + it('keeps the ADR-0008 `version` / `seq` readable off BOTH methods on a normal response', async () => { |
| 168 | + const viaPublish = await clientWith(BARE_BODY).publish<typeof BARE_BODY>('view', 'cases'); |
| 169 | + const viaDraft = await clientWith(BARE_BODY).publishDraft('view', 'cases'); |
| 170 | + |
| 171 | + expect(viaPublish.version).toBe(BARE_BODY.version); |
| 172 | + expect((viaDraft as { version?: string }).version).toBe(BARE_BODY.version); |
| 173 | + expect(viaPublish.seq).toBe(7); |
| 174 | + expect((viaDraft as { seq?: number }).seq).toBe(7); |
| 175 | + }); |
| 176 | + |
| 177 | + it('leaves the unenveloped path — the one every server actually serves — untouched', async () => { |
| 178 | + // The non-regression axis: the plausible WRONG fix over-tightens and |
| 179 | + // breaks the shape existing callers read. `usePublishAllDrafts` reads |
| 180 | + // `seedApplied` off `publishDraft`'s return, so the whole body must |
| 181 | + // survive, not just the three required keys. |
| 182 | + const withSeed = { ...BARE_BODY, seedApplied: { success: false, inserted: 0, updated: 0, error: 'no rows' } }; |
| 183 | + const result = await clientWith(withSeed).publishDraft('seed', 'demo_rows'); |
| 184 | + |
| 185 | + expect(result).toEqual(withSeed); |
| 186 | + expect(result.seedApplied).toEqual({ success: false, inserted: 0, updated: 0, error: 'no rows' }); |
| 187 | + }); |
| 188 | +}); |
| 189 | + |
| 190 | +/** |
| 191 | + * The advisory channel follows the same object, on both doors — PR #6961's |
| 192 | + * presentation reads whatever each method treats as the response, so it stays |
| 193 | + * correct without a second decision (the scope fence this card adopted). |
| 194 | + */ |
| 195 | +describe('advisory reporting reads the same object both methods return (#6962)', () => { |
| 196 | + /** |
| 197 | + * FULLY shaped, and that is load-bearing rather than tidy: `readSaveAdvisories` |
| 198 | + * requires all six string keys and silently DROPS a finding missing any of |
| 199 | + * them. A half-shaped fixture would make the "reports NOTHING" case below |
| 200 | + * pass for the wrong reason — an empty sink proving only that the fixture was |
| 201 | + * malformed. Measured: with three keys, the positive control below went red |
| 202 | + * (`expected [] to have a length of 1`) while the absence case stayed green. |
| 203 | + */ |
| 204 | + const ADVISORY = { |
| 205 | + severity: 'warning' as const, |
| 206 | + rule: 'flow/delete-without-filter', |
| 207 | + where: 'flow "nightly_purge" · node "purge old rows"', |
| 208 | + path: 'flows[0].nodes[2].config.filters', |
| 209 | + message: 'this delete_record node sets multi: true with no filter', |
| 210 | + hint: 'add a filter, or set multi: false to delete a single record', |
| 211 | + }; |
| 212 | + |
| 213 | + it('reports top-level advisories through both doors', async () => { |
| 214 | + const body = { ...BARE_BODY, advisories: [ADVISORY] }; |
| 215 | + |
| 216 | + const viaPublish: MetadataSaveAdvisoryEvent[] = []; |
| 217 | + await clientWith(body, (e) => viaPublish.push(e)).publish('flow', 'nightly_purge'); |
| 218 | + const viaDraft: MetadataSaveAdvisoryEvent[] = []; |
| 219 | + await clientWith(body, (e) => viaDraft.push(e)).publishDraft('flow', 'nightly_purge'); |
| 220 | + |
| 221 | + expect(viaPublish).toHaveLength(1); |
| 222 | + expect(viaDraft).toEqual(viaPublish); |
| 223 | + expect(viaDraft[0]!.advisories).toEqual([ADVISORY]); |
| 224 | + }); |
| 225 | + |
| 226 | + it('reports NOTHING for an enveloped body — through both doors, identically', async () => { |
| 227 | + // The honest consequence of the ruling, pinned rather than left implicit: |
| 228 | + // advisories are declared at the top level, an enveloped body has none |
| 229 | + // there, and neither door goes hunting one level down for them. Pinned as |
| 230 | + // an absence so a "helpful" traversal cannot be re-added silently. |
| 231 | + const enveloped = { success: true, data: { ...BARE_BODY, advisories: [ADVISORY] } }; |
| 232 | + |
| 233 | + const viaPublish: MetadataSaveAdvisoryEvent[] = []; |
| 234 | + await clientWith(enveloped, (e) => viaPublish.push(e)).publish('flow', 'nightly_purge'); |
| 235 | + const viaDraft: MetadataSaveAdvisoryEvent[] = []; |
| 236 | + await clientWith(enveloped, (e) => viaDraft.push(e)).publishDraft('flow', 'nightly_purge'); |
| 237 | + |
| 238 | + expect(viaPublish).toEqual([]); |
| 239 | + expect(viaDraft).toEqual([]); |
| 240 | + }); |
| 241 | +}); |
0 commit comments