test(app-shell): pin the metadata advisory sink seam — an emitted event reaches the toast, both doors

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});

.changeset/pin-advisory-sink-seam-6969.md

@@ -0,0 +1,7 @@
+---
+---
+
+Test-only change: pins the metadata advisory sink seam (`useMetadataClient` ->
+`createConsoleMetadataClient` -> `MetadataClient`), so an advisory the server
+returns on a save or a publish is asserted to actually reach the toast. No
+published behaviour changes.

packages/app-shell/src/views/metadata-admin/useMetadataClient.advisorySink.test.tsx

@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * The advisory chain's MIDDLE link: an emitted event actually REACHES the sink
+ * (objectui#6969).
+ *
+ * ## What was missing, and why nothing red said so
+ *
+ * The chain has three links, and before this file only its two ends were
+ * pinned:
+ *
+ * producer MetadataClient.save / .publishDraft emit the event
+ * -> pinned by metadata-client.saveAdvisories.test.ts and
+ * metadata-client.publishAdvisories.test.ts
+ * MIDDLE useMetadataClient hands its toast sink to the client factory,
+ * which hands it to the MetadataClient constructor
+ * -> pinned by NOTHING
+ * renderer emitSaveAdvisories turns an event into the warning
+ * -> pinned by saveAdvisoryToast.test.ts
+ *
+ * The producer suites assert the event is EMITTED, into a sink they construct
+ * themselves. The renderer suite asserts the message is BUILT, over an event it
+ * writes by hand. Neither one ever asserts that the thing emitted and the thing
+ * rendered are connected — so cutting the middle silenced BOTH doors, save and
+ * publish, with every named suite green. Measured before writing this file:
+ * with the `onSaveAdvisory` hand-off deleted from the factory call in
+ * `useMetadata.ts`, 226 test files / 2369 tests stayed green.
+ *
+ * The mechanism of the blind spot is worth naming, because it is not an
+ * oversight anyone could have spotted by reading a coverage number: 51 suites
+ * `vi.mock('./useMetadata')` — legitimately, they are testing pages, not
+ * plumbing — and, before this file, exactly ZERO imported the real
+ * `useMetadataClient`. The seam was mocked away everywhere it appeared.
+ *
+ * ## What is real here, and what is not
+ *
+ * Real: the hook, its `useCallback` sink, the i18n `t` it closes over, the
+ * PreviewModeContext read, `createConsoleMetadataClient`, the authenticated
+ * fetch wrapper, the `MetadataClient` instance, its response parsing, its
+ * `readSaveAdvisories` filter, and `emitSaveAdvisories`.
+ *
+ * Stubbed, and only these two:
+ * - `sonner` — the terminal sink. It is imported directly by the hook (not
+ * injected), so intercepting the module is the only way to observe what
+ * arrives. Everything BETWEEN the producer and it is the real thing, which
+ * is the whole point.
+ * - `globalThis.fetch` — the server. It answers with the response body the
+ * framework's runtime authoring gate actually sends.
+ *
+ * ## Scope — deliberately NOT a bigger test at either end
+ *
+ * This asserts the CONNECTION and nothing else. The tier (warning, never
+ * error), the per-finding formatting and the empty-list drop are the renderer
+ * suite's; `withEnvironment` clone survival and the response-shape filtering
+ * are the producer suites'. Duplicating any of them here would grow the suite
+ * without closing the hole this file exists to close.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, cleanup } from '@testing-library/react';
+
+// The one stub in the middle of the chain — see the module doc. `toast` is
+// imported by `useMetadata.ts` as a module binding, so it cannot be handed over
+// the way `saveAdvisoryToast.test.ts` hands over its sink.
+vi.mock('sonner', () => ({
+ toast: {
+ warning: vi.fn(),
+ error: vi.fn(),
+ success: vi.fn(),
+ info: vi.fn(),
+ message: vi.fn(),
+ },
+}));
+
+import { toast } from 'sonner';
+import { useMetadataClient } from './useMetadata';
+
+/**
+ * The measured `nightly_purge` finding, in the gate's D3 shape. All six keys
+ * are required — `readSaveAdvisories` drops anything half-shaped, so a fixture
+ * missing one would make this file pass for the wrong reason.
+ */
+const PURGE_ADVISORY = {
+ severity: 'warning' as const,
+ rule: 'flow/delete-without-filter',
+ where: 'flow "nightly_purge" · node "purge old rows"',
+ path: 'flows[0].nodes[2].config.filters',
+ message: 'this delete_record node sets multi: true with no filter, so it deletes every row',
+ hint: 'add a filter, or set multi: false to delete a single record',
+};
+
+/** A committed write the gate had something to say about. */
+const ADVISED_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+ advisories: [PURGE_ADVISORY],
+};
+
+/** The same write, clean. The server omits `advisories` entirely. */
+const CLEAN_BODY = {
+ success: true,
+ version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
+ seq: 7,
+};
+
+function jsonResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function serverAnswers(body: unknown) {
+ fetchMock = vi.fn(async () => jsonResponse(body));
+ vi.stubGlobal('fetch', fetchMock);
+}
+
+beforeEach(() => {
+ vi.mocked(toast.warning).mockClear();
+ serverAnswers(ADVISED_BODY);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ cleanup();
+});
+
+/** The `(title, options)` pair the sink was called with. */
+function warningCall(): [string, { description?: string; duration?: number } | undefined] {
+ const calls = vi.mocked(toast.warning).mock.calls;
+ expect(calls).toHaveLength(1);
+ return calls[0] as [string, { description?: string; duration?: number } | undefined];
+}
+
+describe('useMetadataClient — an emitted advisory reaches the toast sink', () => {
+ it('SAVE door: a save whose response carries findings renders them', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+
+ const [title, options] = warningCall();
+ // The verb proves the DOOR discriminator survived the whole seam: it is set
+ // by the producer and read by the renderer, and nothing in between may lose
+ // or rewrite it.
+ expect(title).toMatch(/^Saved\b/);
+ // The finding itself arrived — not merely "something was toasted".
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ expect(options?.description).toContain(PURGE_ADVISORY.rule);
+ });
+
+ it('PUBLISH door: the same client, the same sink, the published verb', async () => {
+ const { result } = renderHook(() => useMetadataClient());
+
+ // `publishDraft` rather than `publish` because it is what the console's own
+ // publish path (`usePublishAllDrafts`) calls through THIS hook.
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ const [title, options] = warningCall();
+ expect(title).toMatch(/^Published\b/);
+ expect(options?.description).toContain(PURGE_ADVISORY.message);
+ });
+
+ it('CONTROL: a clean write says nothing at either door', async () => {
+ serverAnswers(CLEAN_BODY);
+ const { result } = renderHook(() => useMetadataClient());
+
+ await result.current.save('flow', 'nightly_purge', { name: 'nightly_purge' });
+ await result.current.publishDraft('flow', 'nightly_purge');
+
+ // The zero above is only a reading beside a control that MUST hit: both
+ // writes really did travel the chain, so "the sink stayed quiet" is about
+ // the empty advisory list and not about a chain that never ran.
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(toast.warning).not.toHaveBeenCalled();
+ });
+});