@bespokeagentics/microdots-host 0.1.0

package/src/placementChecks.test.ts

@@ -0,0 +1,593 @@
+import { Option } from 'effect'
+import { describe, expect, test } from 'vitest'
+
+import type { ManifestAttribute, MicroDotManifest } from '@bespokeagentics/microdots-element'
+
+import {
+  type PlacementCheckContext,
+  type PlacementCheckId,
+  type PlacementCheckReport,
+  checkPlacements,
+} from './placementChecks.ts'
+import { type ResolvedPlacement, resolvePlacements } from './rules.ts'
+import type { HostSlotManifest } from './slots.ts'
+import type { HostTopology } from './wire.ts'
+
+/* ============================================================
+   Fixture builders. A resolved placement defaults to active/unconditioned
+   in the declared `hero-slot`; a manifest defaults to a 10 KB bundle with
+   no deployed URL and no attributes. Each test overrides exactly the axis
+   its check reads.
+   ============================================================ */
+
+const KB = 1024
+
+const placed = (
+  id: string,
+  tag: string,
+  slotId: string,
+  overrides: Partial<ResolvedPlacement> = {},
+): ResolvedPlacement => ({
+  id,
+  tag,
+  slotId,
+  source: { _tag: 'route' },
+  condition: { who: 'any', device: 'any', locale: 'any' },
+  envs: ['dev', 'preview', 'prod'],
+  values: {},
+  span: Option.none(),
+  order: Option.none(),
+  state: 'active',
+  overriddenBy: [],
+  ...overrides,
+})
+
+type ManifestOptions = {
+  readonly gzipBytes?: number
+  readonly deployedApiUrl?: string
+  readonly attributes?: ReadonlyArray<ManifestAttribute>
+}
+
+const manifestOf = (
+  name: string,
+  tags: ReadonlyArray<string>,
+  options: ManifestOptions = {},
+): MicroDotManifest => ({
+  name,
+  build: `${name}-build`,
+  bundle: {
+    file: `${name}.js`,
+    hashedFile: `${name}.abc12345.js`,
+    bytes: (options.gzipBytes ?? 10 * KB) * 3,
+    gzipBytes: options.gzipBytes ?? 10 * KB,
+  },
+  service: {
+    localPort: 3101,
+    ...(options.deployedApiUrl === undefined
+      ? {}
+      : { deployedApiUrl: options.deployedApiUrl }),
+  },
+  tags: tags.map(tag => ({
+    tag,
+    attributes: options.attributes ?? [],
+    events: [],
+  })),
+})
+
+const requiredAttribute = (
+  name: string,
+  ownership: ManifestAttribute['ownership'],
+): ManifestAttribute => ({
+  name,
+  type: 'string',
+  required: true,
+  live: true,
+  ownership,
+})
+
+const SLOT_MANIFEST: HostSlotManifest = {
+  theme: { name: '@bespokeagentics/microdots-theme', version: '1.4.0' },
+  slots: [
+    { id: 'hero-slot', kind: 'band', row: 0 },
+    { id: 'side-slot', kind: 'rail', row: 1, width: '280px' },
+  ],
+}
+
+const contextOf = (
+  manifests: ReadonlyArray<MicroDotManifest>,
+  overrides: Partial<PlacementCheckContext> = {},
+): PlacementCheckContext => ({
+  manifests,
+  slotManifest: SLOT_MANIFEST,
+  env: 'dev',
+  ...overrides,
+})
+
+const issuesFor = (report: PlacementCheckReport, check: PlacementCheckId) =>
+  report.issues.filter(issue => issue.check === check)
+
+// The failure mode: a dot whose build stops at dev, placed on a preview or
+// prod route, resolves to nothing and the slot collapses — and nothing says
+// so until a user hits the page. Reachability is the recorded approximation:
+// dev always reachable, preview/prod iff the manifest carries
+// `service.deployedApiUrl` (refined by Phase 7).
+describe('checkPlacements — check 1: not deployed to this environment', () => {
+  test('fires an error in preview for a placement whose manifest has no deployed URL', () => {
+    const report = checkPlacements(
+      [placed('p1', 'workbench-brief', 'hero-slot')],
+      contextOf([manifestOf('workbench', ['workbench-brief'])], {
+        env: 'preview',
+      }),
+    )
+    expect(issuesFor(report, 'not-deployed')).toEqual([
+      {
+        check: 'not-deployed',
+        severity: 'error',
+        placementId: 'p1',
+        consequence: expect.stringContaining(
+          'Build workbench-build stops at dev',
+        ),
+        action: 'Open build workbench-build',
+      },
+    ])
+  })
+
+  test('does not fire in dev — the local service exists by construction', () => {
+    const report = checkPlacements(
+      [placed('p1', 'workbench-brief', 'hero-slot')],
+      contextOf([manifestOf('workbench', ['workbench-brief'])]),
+    )
+    expect(report.issues).toEqual([])
+    expect(report.unverifiable).toEqual([])
+  })
+
+  test('does not fire in prod when the manifest carries a deployed URL', () => {
+    const report = checkPlacements(
+      [placed('p1', 'workbench-brief', 'hero-slot')],
+      contextOf(
+        [
+          manifestOf('workbench', ['workbench-brief'], {
+            deployedApiUrl: 'https://workbench.example.workers.dev',
+          }),
+        ],
+        { env: 'prod' },
+      ),
+    )
+    expect(issuesFor(report, 'not-deployed')).toEqual([])
+  })
+})
+
+// The failure mode: a placement whose slot the current theme no longer
+// declares renders nowhere, and without the manifest's `theme@version` in
+// the message nobody can say the spec's sentence — "it was valid in an
+// earlier theme version" — about why it used to work.
+describe('checkPlacements — check 2: slot not in the theme', () => {
+  test('fires an error naming theme@version for a slot the manifest does not declare', () => {
+    const report = checkPlacements(
+      [placed('p1', 'promo-banner', 'ghost-slot')],
+      contextOf([manifestOf('promo', ['promo-banner'])]),
+    )
+    expect(issuesFor(report, 'slot-not-in-theme')).toEqual([
+      {
+        check: 'slot-not-in-theme',
+        severity: 'error',
+        placementId: 'p1',
+        consequence: expect.stringContaining(
+          'Slot ghost-slot is not in @bespokeagentics/microdots-theme@1.4.0',
+        ),
+        action: 'Move it to a declared slot',
+      },
+    ])
+  })
+
+  test('does not fire for a declared slot', () => {
+    const report = checkPlacements(
+      [placed('p1', 'promo-banner', 'side-slot')],
+      contextOf([manifestOf('promo', ['promo-banner'])]),
+    )
+    expect(issuesFor(report, 'slot-not-in-theme')).toEqual([])
+  })
+
+  test('degrades honestly when the topology has no slot manifest — skipped, not passed', () => {
+    // No `slotManifest` key at all (a Phase-4 topology). Under
+    // exactOptionalPropertyTypes the absence is the fixture, so the context
+    // is built literally rather than through `contextOf`.
+    const report = checkPlacements(
+      [placed('p1', 'promo-banner', 'hero-slot')],
+      {
+        manifests: [manifestOf('promo', ['promo-banner'])],
+        env: 'dev',
+      },
+    )
+    expect(issuesFor(report, 'slot-not-in-theme')).toEqual([])
+    expect(report.unverifiable).toEqual([
+      {
+        check: 'slot-not-in-theme',
+        reason: expect.stringContaining('slot checks skipped, not passed'),
+      },
+    ])
+  })
+})
+
+// The failure mode: a manifest-required attribute nobody sets means the
+// element mounts and errors on first render — in production, where the
+// missing value was invisible in every local run that happened to set it.
+describe('checkPlacements — check 3: required attribute unset', () => {
+  test('warns when a required dot-owned attribute has no supplied value', () => {
+    const report = checkPlacements(
+      [placed('p1', 'price-ticker', 'hero-slot')],
+      contextOf([
+        manifestOf('price', ['price-ticker'], {
+          attributes: [requiredAttribute('symbol', 'dot')],
+        }),
+      ]),
+    )
+    expect(issuesFor(report, 'required-attribute-unset')).toEqual([
+      {
+        check: 'required-attribute-unset',
+        severity: 'warning',
+        placementId: 'p1',
+        consequence: expect.stringContaining('symbol is unset'),
+        action: 'Set a value above',
+      },
+    ])
+  })
+
+  test('does not warn when the resolved placement supplies the value', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'price-ticker', 'hero-slot', {
+          values: { symbol: 'FOLD' },
+        }),
+      ],
+      contextOf([
+        manifestOf('price', ['price-ticker'], {
+          attributes: [requiredAttribute('symbol', 'dot')],
+        }),
+      ]),
+    )
+    expect(issuesFor(report, 'required-attribute-unset')).toEqual([])
+  })
+
+  test('exempts environment- and host-owned attributes — the loader and the host supply those', () => {
+    const report = checkPlacements(
+      [placed('p1', 'price-ticker', 'hero-slot')],
+      contextOf([
+        manifestOf('price', ['price-ticker'], {
+          attributes: [
+            requiredAttribute('api-url', 'environment'),
+            requiredAttribute('interview-id', 'host-input'),
+          ],
+        }),
+      ]),
+    )
+    expect(issuesFor(report, 'required-attribute-unset')).toEqual([])
+  })
+})
+
+// The failure mode: the same dot placed twice with overlapping conditions is
+// two live instances side by side (check 4) — while disjoint conditions are
+// legitimate variant work that must NOT read as a mistake (check 7). Both are
+// computed over the RESOLUTION's output, so reading B's cross-level twins
+// fire too.
+describe('checkPlacements — checks 4 and 7: the same dot twice', () => {
+  const PROMO_MANIFESTS = [manifestOf('promo', ['promo-banner'])]
+
+  test('warns on both members when conditions overlap — two instances run side by side', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'promo-banner', 'hero-slot'),
+        placed('p2', 'promo-banner', 'side-slot', {
+          condition: { who: 'any', device: 'mobile', locale: 'any' },
+        }),
+      ],
+      contextOf(PROMO_MANIFESTS),
+    )
+    expect(issuesFor(report, 'mounts-twice-overlapping')).toEqual([
+      {
+        check: 'mounts-twice-overlapping',
+        severity: 'warning',
+        placementId: 'p1',
+        consequence: expect.stringContaining('also placed in side-slot'),
+        action: 'Narrow one condition',
+      },
+      {
+        check: 'mounts-twice-overlapping',
+        severity: 'warning',
+        placementId: 'p2',
+        consequence: expect.stringContaining('also placed in hero-slot'),
+        action: 'Narrow one condition',
+      },
+    ])
+  })
+
+  test('does not warn when the twin conditions are disjoint', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'promo-banner', 'hero-slot', {
+          condition: { who: 'any', device: 'any', locale: 'fr' },
+        }),
+        placed('p2', 'promo-banner', 'side-slot', {
+          condition: { who: 'any', device: 'any', locale: 'en' },
+        }),
+      ],
+      contextOf(PROMO_MANIFESTS),
+    )
+    expect(issuesFor(report, 'mounts-twice-overlapping')).toEqual([])
+  })
+
+  test('notes disjoint twins as legitimate variant work', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'promo-banner', 'hero-slot', {
+          condition: { who: 'any', device: 'any', locale: 'fr' },
+        }),
+        placed('p2', 'promo-banner', 'side-slot', {
+          condition: { who: 'any', device: 'any', locale: 'en' },
+        }),
+      ],
+      contextOf(PROMO_MANIFESTS),
+    )
+    expect(issuesFor(report, 'placed-twice-disjoint')).toEqual([
+      {
+        check: 'placed-twice-disjoint',
+        severity: 'note',
+        placementId: 'p1',
+        consequence: expect.stringContaining('legitimate variant work'),
+        action: 'No action needed',
+      },
+      {
+        check: 'placed-twice-disjoint',
+        severity: 'note',
+        placementId: 'p2',
+        consequence: expect.stringContaining('legitimate variant work'),
+        action: 'No action needed',
+      },
+    ])
+  })
+
+  test('raises no twin issues for a lone placement', () => {
+    const report = checkPlacements(
+      [placed('p1', 'promo-banner', 'hero-slot')],
+      contextOf(PROMO_MANIFESTS),
+    )
+    expect(issuesFor(report, 'mounts-twice-overlapping')).toEqual([])
+    expect(issuesFor(report, 'placed-twice-disjoint')).toEqual([])
+  })
+})
+
+// The failure mode: the fixture's per-placement sum double-counts a shared
+// bundle — the workbench's three tags are ONE fetch, because `loadMicroDot`
+// dedupes it — so a naive check 6 cries over-budget on routes that are fine,
+// and the warning gets ignored on the route that is not.
+describe('checkPlacements — check 6: over the page-weight budget', () => {
+  test('sums each distinct bundle once — a shared bundle mounted twice does not double-count', () => {
+    // Distinct sum: 100 + 70 = 170 KB ≤ 180. The per-placement sum would be
+    // 100 + 100 + 70 = 270 KB and fire — this fixture is the double-count
+    // kill.
+    const report = checkPlacements(
+      [
+        placed('p1', 'workbench-app-list', 'hero-slot'),
+        placed('p2', 'workbench-brief', 'side-slot'),
+        placed('p3', 'wiring-canvas', 'side-slot'),
+      ],
+      contextOf([
+        manifestOf('workbench', ['workbench-app-list', 'workbench-brief'], {
+          gzipBytes: 100 * KB,
+        }),
+        manifestOf('wiring', ['wiring-canvas'], { gzipBytes: 70 * KB }),
+      ]),
+    )
+    expect(issuesFor(report, 'over-weight-budget')).toEqual([])
+  })
+
+  test('warns once over budget, naming the total and the largest bundle', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'workbench-app-list', 'hero-slot'),
+        placed('p2', 'workbench-brief', 'side-slot'),
+        placed('p3', 'wiring-canvas', 'side-slot'),
+      ],
+      contextOf([
+        manifestOf('workbench', ['workbench-app-list', 'workbench-brief'], {
+          gzipBytes: 100 * KB,
+        }),
+        manifestOf('wiring', ['wiring-canvas'], { gzipBytes: 90 * KB }),
+      ]),
+    )
+    expect(issuesFor(report, 'over-weight-budget')).toEqual([
+      {
+        check: 'over-weight-budget',
+        severity: 'warning',
+        placementId: 'p1',
+        consequence:
+          'Total bundle weight of everything mounting on this route is 190 KB gzipped against a 180 KB budget. The largest is workbench at 100 KB.',
+        action: 'Remove or split workbench, or raise the budget',
+      },
+    ])
+  })
+})
+
+// The failure mode: an unverifiable entry is a fact about a TAG — "no
+// manifest was emitted for it" — not about a placement. Emitted per placement
+// it repeats itself: three placements of one manifest-less tag on a route
+// produced three byte-identical lines from checks 1 and 3 while check 6, which
+// deduped from the start, produced one. A panel that says the same thing three
+// times reads as three separate gaps and buries the checks that only said
+// theirs once.
+describe('checkPlacements — unverifiable checks are deduped by tag', () => {
+  test('three placements of one manifest-less tag report each check ONCE', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'ghost-dot', 'hero-slot'),
+        placed('p2', 'ghost-dot', 'side-slot'),
+        placed('p3', 'ghost-dot', 'hero-slot'),
+      ],
+      // `preview`, so check 1 actually runs — in dev it short-circuits before
+      // it can report anything.
+      contextOf([], { env: 'preview' }),
+    )
+
+    expect(report.unverifiable.map(entry => entry.check)).toEqual([
+      'not-deployed',
+      'required-attribute-unset',
+      'over-weight-budget',
+    ])
+    expect(
+      new Set(
+        report.unverifiable.map(entry => `${entry.check}|${entry.reason}`),
+      ).size,
+    ).toBe(report.unverifiable.length)
+  })
+
+  test('two DIFFERENT manifest-less tags are still two facts, not one', () => {
+    const report = checkPlacements(
+      [
+        placed('p1', 'ghost-dot', 'hero-slot'),
+        placed('p2', 'ghost-dot', 'side-slot'),
+        placed('p3', 'other-ghost', 'side-slot'),
+      ],
+      contextOf([], { env: 'preview' }),
+    )
+
+    // Deduping must not collapse distinct tags: checks 1 and 3 name one tag
+    // per sentence, so each unverified tag keeps its own line.
+    expect(
+      report.unverifiable
+        .filter(entry => entry.check === 'required-attribute-unset')
+        .map(entry => entry.reason),
+    ).toEqual([
+      'no manifest for ghost-dot — its required attributes cannot be verified',
+      'no manifest for other-ghost — its required attributes cannot be verified',
+    ])
+  })
+})
+
+// The failure mode: `overridePair` decides a same-tag pair is already resolved
+// by the contest — and therefore raises no duplicate warning — by matching
+// `winnerId === other.id`. When two placements share an id that match fires
+// for a pair that never contested, and a REAL check-4 warning disappears. The
+// resolution's id uniqueness is the only thing standing between a duplicated
+// `id` in a topology file and a silently unchecked page.
+describe('checkPlacements — over a resolution whose ids collide in the source', () => {
+  const COLLIDING_TOPOLOGY: HostTopology = {
+    host: { id: 'test-host', label: 'Test host', ownedInputs: [] },
+    routes: [
+      {
+        path: '/home',
+        label: '/home',
+        title: '/home',
+        sectionIds: [],
+        mounts: [
+          // Partially overrides the rule's placement (same slot, narrower
+          // condition) …
+          {
+            id: 'dup',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            condition: { locale: 'fr' },
+          },
+          // … while this one is a genuine unresolved twin of it: same tag,
+          // DIFFERENT slot, so no contest — check 4's exact subject.
+          { id: 'dup', tag: 'promo-banner', slotId: 'side-slot' },
+        ],
+      },
+    ],
+    rules: [
+      {
+        id: 'r1',
+        kind: 'pattern',
+        label: 'Rule r1',
+        pattern: '/*',
+        placements: [{ id: 'dup', tag: 'promo-banner', slotId: 'hero-slot' }],
+      },
+    ],
+    wires: [],
+    watch: [],
+  }
+
+  test('the rule-carried placement still gets its duplicate warning', () => {
+    const resolved = resolvePlacements(COLLIDING_TOPOLOGY, '/home', 'dev')
+    const inherited = resolved.find(item => item.source._tag === 'rule')
+    if (inherited === undefined) {
+      throw new Error('the rule placement did not resolve')
+    }
+    expect(inherited.state).toBe('partially-overridden')
+
+    const report = checkPlacements(
+      resolved,
+      contextOf([manifestOf('promo', ['promo-banner'])]),
+    )
+
+    // All three still render for somebody, and each has an un-contested twin,
+    // so each raises the warning. With colliding ids the inherited one raises
+    // nothing: its `overriddenBy.winnerId` matches the id of the placement it
+    // never contested, and `overridePair` reads that as already-resolved.
+    const flagged = issuesFor(report, 'mounts-twice-overlapping').map(
+      issue => issue.placementId,
+    )
+    expect(flagged).toContain(inherited.id)
+    expect(flagged.length).toBe(3)
+    expect(new Set(flagged).size).toBe(3)
+  })
+})
+
+// The failure mode: reading B's qualifier. A placement overridden ENTIRELY
+// renders for nobody, so flagging its problems is noise that trains people to
+// ignore the panel — while a PARTIALLY overridden one still renders for
+// somebody, so silencing it hides a real break.
+describe('checkPlacements — the reading-B override qualifier', () => {
+  test('a fully overridden placement raises no issues however broken it is', () => {
+    // The loser sits in an undeclared slot AND omits a required attribute —
+    // two firing conditions, zero issues, because it renders for nobody.
+    const report = checkPlacements(
+      [
+        placed('loser', 'price-ticker', 'ghost-slot', {
+          state: 'overridden',
+          overriddenBy: [
+            {
+              by: { _tag: 'route' },
+              winnerId: 'winner',
+              where: { who: 'any', device: 'any', locale: 'any' },
+              entire: true,
+            },
+          ],
+        }),
+        placed('winner', 'price-ticker', 'hero-slot', {
+          values: { symbol: 'FOLD' },
+        }),
+      ],
+      contextOf([
+        manifestOf('price', ['price-ticker'], {
+          attributes: [requiredAttribute('symbol', 'dot')],
+        }),
+      ]),
+    )
+    expect(report.issues).toEqual([])
+  })
+
+  test('a partially overridden placement is still checked — it still renders for somebody', () => {
+    const report = checkPlacements(
+      [
+        placed('loser', 'price-ticker', 'ghost-slot', {
+          state: 'partially-overridden',
+          overriddenBy: [
+            {
+              by: { _tag: 'route' },
+              winnerId: 'winner',
+              where: { who: 'any', device: 'any', locale: 'fr' },
+              entire: false,
+            },
+          ],
+        }),
+        placed('winner', 'price-ticker', 'hero-slot', {
+          condition: { who: 'any', device: 'any', locale: 'fr' },
+        }),
+      ],
+      contextOf([manifestOf('price', ['price-ticker'])]),
+    )
+    expect(
+      issuesFor(report, 'slot-not-in-theme').map(issue => issue.placementId),
+    ).toEqual(['loser'])
+  })
+})