ci: coverage/knip

2026-07-24 00:56:29 +08:00
parent 76b25f6c65
commit a7699cdeb1
7 changed files with 333 additions and 9 deletions
@@ -0,0 +1,305 @@
+// @vitest-environment jsdom
+/**
+ * ClientModuleLoaderImpl behavior: lazy CJS arrival (bundle execution only
+ * registers the factory), materialization on first import/require with
+ * memoization and recursive self-sequencing, the resolution branch order,
+ * shared in-flight arrival, invalidate-refetch (HMR), style claiming, the
+ * default transport seams, and the loud failure modes (duplicate
+ * registration, cycles, table misses, double boot).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  ClientModuleLoaderImpl, createClientModuleLoader,
+  type ClientModuleLoader, type ClientPluginHandoff, type DshWindow, type WebBootEntry,
+} from '../src/index.ts'
+
+const win = globalThis as DshWindow
+
+type Factory = ClientPluginHandoff['factory']
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  delete win.__ModuleLoader__
+  delete (document as unknown as Record<string, unknown>).__realmBridge
+  for (const el of document.querySelectorAll('style, script')) el.remove()
+})
+
+const row = (id: string): WebBootEntry => ({ id, url: `/plugins/${id}/client.js?rev=0` })
+
+interface Bench {
+  loader: ClientModuleLoader
+  fetched: string[]
+  gates: Map<string, () => void>
+}
+
+/**
+ * Loader over scripted bundles: fetch resolves to the row url (optionally
+ * gated on a release callback); execute registers the scripted factory
+ * through the window sink (`null` scripts a bundle that never calls load).
+ */
+function bench(
+  entries: WebBootEntry[],
+  bundles: Record<string, Factory | null> = {},
+  opts: { seed?: Record<string, unknown>; gated?: string[] } = {},
+): Bench {
+  const fetched: string[] = []
+  const gates = new Map<string, () => void>()
+  const loader = createClientModuleLoader({
+    graph: { rev: 'test', entries },
+    staticModules: opts.seed ?? {},
+    fetchBundle: (url) => {
+      fetched.push(url)
+      if (opts.gated?.includes(url) === true) {
+        return new Promise((resolve) => { gates.set(url, () => { resolve(url) }) })
+      }
+      return Promise.resolve(url)
+    },
+    executeBundle: (code) => {
+      const id = /\/plugins\/(.+)\/client\.js/.exec(code)?.[1]
+      const factory = id === undefined ? undefined : bundles[id]
+      if (factory == null || id === undefined) return
+      win.__ModuleLoader__?.load({ id, factory })
+    },
+  })
+  return { loader, fetched, gates }
+}
+
+describe('lazy CJS arrival', () => {
+  it('prefetch fetches and executes but does not run the factory', async () => {
+    const ran: string[] = []
+    const b = bench([row('a')], { a: () => { ran.push('a'); return {} } })
+    await b.loader.prefetch('a')
+    expect(b.fetched).toEqual(['/plugins/a/client.js?rev=0'])
+    expect(ran).toEqual([])
+    expect(b.loader.loadCache.size).toBe(0)
+  })
+
+  it('import materializes once and memoizes the export surface', async () => {
+    const ran: string[] = []
+    const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } })
+    const first = await b.loader.import('a', '', {})
+    const second = await b.loader.import('a', '', {})
+    expect(first).toBe(second)
+    expect((first as { marker: string }).marker).toBe('a')
+    expect(ran).toEqual(['a'])
+    expect(b.loader.loadCache.get('a')?.id).toBe('a')
+  })
+
+  it('import without prefetch fetches, executes, and materializes in one call', async () => {
+    const b = bench([row('a')], { a: () => ({ marker: 'direct' }) })
+    const surface = await b.loader.import('a', '', {})
+    expect((surface as { marker: string }).marker).toBe('direct')
+    expect(b.fetched).toHaveLength(1)
+  })
+
+  it('concurrent callers share one in-flight arrival and materialize once', async () => {
+    const ran: string[] = []
+    const url = '/plugins/a/client.js?rev=0'
+    const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } }, { gated: [url] })
+    const first = b.loader.import('a', '', {})
+    const second = b.loader.import('a', '', {})
+    const third = b.loader.prefetch('a')
+    b.gates.get(url)?.()
+    const [s1, s2] = await Promise.all([first, second, third])
+    expect(s1).toBe(s2)
+    expect(b.fetched).toEqual([url])
+    expect(ran).toEqual(['a'])
+  })
+
+  it('prefetch after registration is a no-op without invalidate', async () => {
+    const b = bench([row('a')], { a: () => ({}) })
+    await b.loader.prefetch('a')
+    await b.loader.prefetch('a')
+    expect(b.fetched).toHaveLength(1)
+  })
+})
+
+describe('require resolution', () => {
+  it('a factory requiring a registered-but-unmaterialized module materializes it recursively', async () => {
+    const order: string[] = []
+    const b = bench([row('a'), row('b')], {
+      a: (req) => {
+        order.push('a')
+        const dep = req('b/client') as { helper: string }
+        return { got: dep.helper }
+      },
+      b: () => { order.push('b'); return { helper: 'from-b' } },
+    })
+    await b.loader.prefetch('a')
+    await b.loader.prefetch('b')
+    const surface = await b.loader.import('a', '', {})
+    expect((surface as { got: string }).got).toBe('from-b')
+    expect(order).toEqual(['a', 'b'])
+    expect(b.loader.loadCache.get('a')?.edges.has('b/client')).toBe(true)
+    expect(b.loader.loadCache.has('b')).toBe(true)
+  })
+
+  it('require prefers the platform seed word over the module table', async () => {
+    const react = { marker: 'react' }
+    const b = bench([row('a')], {
+      a: (req) => ({ dep: req('react') }),
+    }, { seed: { react } })
+    const surface = await b.loader.import('a', '', {})
+    expect((surface as { dep: unknown }).dep).toBe(react)
+    expect(await b.loader.import('react', '', {})).toBe(react)
+    expect(b.loader.loadCache.has('react')).toBe(false)
+  })
+
+  it('require answers an already-materialized module from the cache', async () => {
+    let built = 0
+    const b = bench([row('a'), row('c')], {
+      a: (req) => ({ dep: req('c') }),
+      c: () => { built += 1; return { marker: 'c' } },
+    })
+    const c = await b.loader.import('c', '', {})
+    const a = await b.loader.import('a', '', {})
+    expect((a as { dep: unknown }).dep).toBe(c)
+    expect(built).toBe(1)
+  })
+
+  it('a require that misses the module table is loud', async () => {
+    const b = bench([row('a')], { a: (req) => ({ dep: req('ghost') }) })
+    await expect(b.loader.import('a', '', {})).rejects.toThrow('require("ghost") missed the module table')
+  })
+
+  it('a require cycle is fatal', async () => {
+    const b = bench([row('a'), row('b')], {
+      a: (req) => ({ dep: req('b') }),
+      b: (req) => ({ dep: req('a') }),
+    })
+    await b.loader.prefetch('b')
+    await expect(b.loader.import('a', '', {})).rejects.toThrow('require cycle through "a"')
+  })
+})
+
+describe('static registry', () => {
+  it('serves shell-own modules to import and require without any fetch', async () => {
+    const shell = { marker: 'app-shell' }
+    const b = bench([row('a'), { id: 'app-shell' }], {
+      a: (req) => ({ dep: req('app-shell') }),
+    })
+    b.loader.registerStatic('app-shell', shell)
+    await b.loader.prefetch('app-shell')
+    expect(await b.loader.import('app-shell', '', {})).toBe(shell)
+    expect(b.loader.loadCache.get('app-shell')?.styles).toEqual([])
+    expect((await b.loader.import('a', '', {}) as { dep: unknown }).dep).toBe(shell)
+    expect(b.fetched).toEqual(['/plugins/a/client.js?rev=0'])
+  })
+
+  it('duplicate static registration is loud', () => {
+    const b = bench([])
+    b.loader.registerStatic('app-shell', {})
+    expect(() => { b.loader.registerStatic('app-shell', {}) }).toThrow('registered twice')
+  })
+})
+
+describe('failure modes', () => {
+  it('duplicate factory registration is loud', () => {
+    bench([])
+    win.__ModuleLoader__?.load({ id: 'x', factory: () => ({}) })
+    expect(() => win.__ModuleLoader__?.load({ id: 'x', factory: () => ({}) }))
+      .toThrow('duplicate factory registration for "x"')
+  })
+
+  it('a bundle that never registers its id is loud', async () => {
+    const b = bench([row('a')], { a: null })
+    await expect(b.loader.import('a', '', {})).rejects.toThrow('without registering "a"')
+  })
+
+  it('an unknown import specifier is loud', async () => {
+    const b = bench([])
+    await expect(b.loader.import('nope', '', {})).rejects.toThrow('cannot resolve "nope"')
+  })
+
+  it('an unknown prefetch id is loud', async () => {
+    const b = bench([])
+    await expect(b.loader.prefetch('nope')).rejects.toThrow('prefetch("nope") — not a graph entry')
+  })
+
+  it('a graph row with no url and no static registration is loud', async () => {
+    const b = bench([{ id: 'ghost' }])
+    await expect(b.loader.import('ghost', '', {})).rejects.toThrow('no bundle url and no static registration')
+  })
+
+  it('a duplicate graph entry is loud at construction', () => {
+    expect(() => bench([row('a'), row('a')])).toThrow('duplicate graph entry "a"')
+  })
+
+  it('double boot is loud', () => {
+    bench([])
+    expect(() => new ClientModuleLoaderImpl({ graph: { rev: 't', entries: [] }, staticModules: {} }))
+      .toThrow('already installed (double boot?)')
+  })
+})
+
+describe('HMR reset', () => {
+  it('invalidate drops the factory and record so the module refetches and re-registers', async () => {
+    let generation = 0
+    const b = bench([row('a')], { a: () => ({ generation: ++generation }) })
+    const first = await b.loader.import('a', '', {})
+    b.loader.invalidate('a')
+    expect(b.loader.loadCache.has('a')).toBe(false)
+    await b.loader.prefetch('a')
+    const second = await b.loader.import('a', '', {})
+    expect(b.fetched).toHaveLength(2)
+    expect((first as { generation: number }).generation).toBe(1)
+    expect((second as { generation: number }).generation).toBe(2)
+  })
+})
+
+describe('style claiming', () => {
+  it('claims untagged style tags for the materializing plugin and inventories owned css ids', async () => {
+    const foreign = document.createElement('style')
+    foreign.setAttribute('data-plugin', 'other')
+    document.head.appendChild(foreign)
+    const b = bench([row('a')], {
+      a: () => {
+        document.head.appendChild(document.createElement('style'))
+        const tagged = document.createElement('style')
+        tagged.setAttribute('data-plugin', 'a')
+        tagged.setAttribute('data-plugin-css', 'sheet-1')
+        document.head.appendChild(tagged)
+        return {}
+      },
+    })
+    await b.loader.import('a', '', {})
+    expect(b.loader.loadCache.get('a')?.styles).toEqual(['a', 'sheet-1'])
+    expect(document.querySelectorAll('style[data-plugin="a"]')).toHaveLength(2)
+    expect(foreign.getAttribute('data-plugin')).toBe('other')
+  })
+
+  it('materialization without a document skips the style inventory', async () => {
+    const b = bench([row('a')], { a: () => ({}) })
+    vi.stubGlobal('document', undefined)
+    try {
+      await b.loader.import('a', '', {})
+    } finally {
+      vi.unstubAllGlobals()
+    }
+    expect(b.loader.loadCache.get('a')?.styles).toEqual([])
+  })
+})
+
+describe('default transport seams', () => {
+  it('fetches same-origin and executes through an inline script tag', async () => {
+    // In a browser the loader's globalThis IS the page window; vitest's jsdom
+    // evaluates <script> in a separate realm that shares only the document,
+    // so the fixture bundle restores the sink from a document bridge before
+    // using the normal calling convention.
+    const code = 'window.__ModuleLoader__ = document.__realmBridge;\n'
+      + 'window.__ModuleLoader__.load({ id: "dee", factory: function () { return { marker: "via-script" } } })'
+    vi.stubGlobal('fetch', async () => ({ ok: true, text: async () => code }))
+    const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
+    ;(document as unknown as Record<string, unknown>).__realmBridge = win.__ModuleLoader__
+    const surface = await loader.import('dee', '', {})
+    expect((surface as { marker: string }).marker).toBe('via-script')
+    const script = [...document.querySelectorAll('script')].at(-1)
+    expect(script?.textContent).toContain('//# sourceURL=/plugins/dee/client.js?rev=0')
+  })
+
+  it('a non-ok bundle response is loud with the status', async () => {
+    vi.stubGlobal('fetch', async () => ({ ok: false, status: 404 }))
+    const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
+    await expect(loader.prefetch('dee')).rejects.toThrow('answered 404')
+  })
+})