Files
deepseek-harness/packages/boot/hmr/tests/modules.spec.ts
T
Turtle 3f7016a422 feat(config): add volatile schemas and watcher-driven updates (#4579)
* feat(cordis): add volatile config references without remounting

* refactor(cordis): use internal prefix for volatile updates

* fix(schemastery): preserve metadata-free serialized schemas

* refactor(config): move volatile updates into an opt-in Loader plugin

* refactor(config): reuse Loader context patch for volatile updates

* refactor(config): let the volatile watcher commit equal candidates

* refactor(config): separate comparison from volatile reconciliation

* refactor(loader): extract pure entry option diff

* refactor(loader): compare volatile config through schema metadata

* refactor(loader): make volatile comparison policy explicit

* refactor: name config reload and volatile HMR events

* refactor(loader): compare volatile config in one schema walk; declare hmr/volatile-update in volatile-hmr

Replace the mask/project pair in vendor/loader/src/config/diff.ts with one recursive schema-guided comparison. Absent objects now compare as their declared schema default at every object node, not only under volatile ancestors; both inputs resolve to the same validated config, so the one changed assertion (undefined vs {} under a non-volatile object schema) becomes unchanged. The isJsExpr special case is dropped: expression keys fall through to raw comparison.

Move the hmr/volatile-update Events declaration from vendored Cordis core to its producer, packages/boot/volatile-hmr, matching how dsh-hmr declares hmr/change and hmr/reload. Vendored cordis events.ts returns to upstream content; the inherited Cordis API catalog and the event matrix are regenerated, and the tutorial example imports the package types.

* fix(cosmokit): compare sparse array slots in deepEqual; extend volatile diff coverage

Array.prototype.every skipped holes, so deepEqual(Array(1), ['new']) was true in one direction. Compare every index with holes read as undefined.

config/diff.ts treats expression objects as opaque values even when a schema field shares the marker name, and looks up field schemas with Object.hasOwn so unknown keys named after Object prototype members compare raw. Tests cover absent-object defaults, sparse arrays in both directions, prototype-named keys, metadata-free serialized schema nodes, and a runtime remount check in volatile-hmr. READMEs and the architecture note describe the object-default rule.

* test(schemastery): build serialized schema fixtures without unknown casts

verify-no-unknown-casts rejects the two as-unknown assertions in scripts/volatile-config.spec.ts. Parse the serialized nodes from JSON text instead, matching scripts/loader-config-diff.spec.ts.

* docs(volatile-hmr): drop the scope-scan tag from hmr/volatile-update

verify-scoped-events rejects @dshScopeScan on an event that carries no scoped keys. Catalogs and the event matrix are regenerated.

* docs: regenerate module graph for the volatile-hmr dependency edge

verify-module-graph reports the merged docs stale: volatile-hmr now lists its app-boot dependency.

* test(volatile-hmr): watch the real YAML through an exact config watch

The Windows coverage lane lost the whole spec: its vitest worker exited without a report once this test started a chokidar directory watch (root: ['.']), the only real directory watch in the test suite. Register the include file through hmr.watchConfig instead, the pattern the HMR package's own real-file tests run on Windows, and emit loader/config-reload from the refresh callback as the root-watch path does. packages/boot/hmr/tests/coordination.spec.ts already covers that root-watch emission with a mocked watcher; volatile-hmr and hmr sources stay at 100% coverage.

* test(volatile-hmr): pass the Include path as a file URL

On Windows the plain absolute path made the include subtree fail to load, so the profile-patch test found no consumer entry. Other Include fixtures in this spec already pass file URLs.

* refactor(loader): commit volatile config in Entry.update and remove volatile-hmr

loader/config-reload was emitted from two places (app-boot profile reconciliation and the HMR root watch) and by hand in tests, because a separate plugin needed a "configuration applied" signal to run its own pass. Every update path already funnels through Entry.update, which is where the Loader decides to skip a remount for a volatile-only change. Entry._commitVolatile now parses the candidate through the fiber's internal/config hook and schema, commits the new values into the running references when the ordinary effective values still match, and emits loader/volatile-update to the owning fiber. A changed ordinary effective value falls back to the ordinary remount instead of leaving the instance stale; an invalid candidate is logged and keeps the running references, with the raw config retained for the next activation. Forced group updates take the same path.

Remove packages/boot/volatile-hmr, its event, the app-boot loader/config-reload declaration and emit, and the HMR emission. Loader runtime and real-file tests move to scripts/loader-volatile-update.spec.ts. Docs, catalogs, the event matrix, module graph and the architecture note follow.

* test: share the volatile schema fixture between the schema and Loader specs

The duplication gate flagged the identical Config fixture in scripts/volatile-config.spec.ts and scripts/loader-volatile-update.spec.ts.

* refactor(loader): reduce config/diff.ts to equalExceptVolatile

Entry.update now computes the strict raw option changes itself and only asks diff.ts whether two raw configs differ at most in volatile fields. The ignoreVolatile flag, the options object and the "config is the sole change" rule leave diff.ts; they were the Loader's decision and now sit next to the commit they gate. The raw-config deepEqual in the volatile branch is gone because the strict change list already answers it.

* refactor(loader): type the volatile comparison against Schemastery's Schema

config/diff.ts narrows the plugin's Standard Schema to Schemastery's own Schema type instead of a hand-written structural interface, which makes vendor/loader a type-only dependent of @deepseek-ai/schemastery. The rescope codemod treats the vendor identifier comparison like schemastery's own source and renames the import through an exact edit.

* fix(loader): address review findings on the volatile commit path

Entry.update only replaces the fiber's pending raw config for a volatile-only change, so a noSave direct update survives a no-op entry update. _commitVolatile logs at debug level when ordinary effective values changed and the ordinary update applies, dispatches loader/volatile-update with a Context receiver like Cordis' own filtered emits, and isolates a throwing listener. Schemastery reports unsupported volatile values as ValidationError with their path and validates a lazy inner once when it is built. The inherited-event catalog gains internal/config and corrected source lines; the Loader spec imports dsh-hmr by package name and covers the new behaviors. Docs record that class-instance ordinary fields always take the remount path and that .default() accepts the raw input type.
2026-09-21 00:04:06 +08:00

366 lines
16 KiB
TypeScript

/** Module graph replacement through a real Loader and controlled Node cache. */
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { fileURLToPath, pathToFileURL } from 'node:url'
import NodeModule, { createRequire } from 'node:module'
import { Context, type Plugin } from '@deepseek-ai/cordis'
import Loader, { type ModuleJob, type ModuleLoader } from '@deepseek-ai/cordis-plugin-loader'
import Timer from '@deepseek-ai/cordis-plugin-timer'
import z from '@deepseek-ai/schemastery'
import { expect, it, onTestFinished, vi } from 'vitest'
import Hmr from '../src/index.ts'
interface ModuleReload {
internal: ModuleLoader
externals: Set<string>
accepted: Set<string>
declined: Set<string>
stashed: Set<string>
analyzeChanges(): Promise<void>
partialReload(): Promise<void>
}
async function fixture(version: 'v1' | 'v2' = 'v2') {
const dir = mkdtempSync(join(tmpdir(), 'dsh-hmr-graph-'))
const ctx = new Context()
ctx.baseUrl = pathToFileURL(dir).href + '/'
onTestFinished(async () => { await ctx.fiber.dispose(); rmSync(dir, { recursive: true, force: true }) })
await ctx.plugin(Loader)
await ctx.plugin(Timer)
await ctx.plugin(Hmr, { root: [], ignored: [], debounce: 0 })
const cache = new Map<string, ModuleJob>()
const imports = new Map<string, Plugin>()
const resolve = vi.fn((name: string) => ({ url: name }))
// The adapter supplies only the Node loader operations exercised by HMR.
const internal = { version, loadCache: cache, resolve,
resolveSync: (_parent: string, request: { specifier: string }) => resolve(request.specifier),
} as unknown as ModuleLoader
const reload = ctx.hmr as unknown as ModuleReload
reload.internal = internal
reload.externals = new Set()
const imported = vi.spyOn(ctx.loader, 'import').mockImplementation(async (name: string) => {
const plugin = imports.get(name)
if (plugin === undefined) throw new Error(`missing module: ${name}`)
return plugin
})
const url = (name: string) => pathToFileURL(join(dir, name)).href
function module(name: string, plugin?: Plugin, children: ModuleJob[] = []): ModuleJob {
const location = name.startsWith('node:') ? name : url(name)
// ModuleJob's execution methods belong to Node; this fixture owns its graph and namespace.
const job = { url: location, linked: Promise.resolve(children),
module: { url: location, getNamespace: () => plugin },
} as ModuleJob
cache.set(location, job)
if (plugin !== undefined) imports.set(location, plugin)
return job
}
return { ctx, cache, imports, imported, reload, module, url, resolve }
}
it.each(['v1', 'v2'] as const)('replaces a %s module and retains the latest Loader entry configuration', async (version) => {
const { ctx, module, imports, reload } = await fixture(version)
const mounted: string[] = []
const disposed: string[] = []
const before = { apply(ctx: Context, config: { value: string }) {
mounted.push(`before:${config.value}`)
ctx.effect(() => () => { disposed.push('before') })
} }
const after = { apply(ctx: Context, config: { value: string }) {
mounted.push(`after:${config.value}`)
ctx.effect(() => () => { disposed.push('after') })
} }
const job = module('plugin.mjs', before)
const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url, config: { value: 'initial' } }))
await ctx.loader.await()
await entry.update({ config: { value: 'current' } })
await ctx.loader.await()
imports.set(job.url, after)
const event = vi.fn()
ctx.on('hmr/reload', event)
reload.stashed.add(job.url)
await reload.partialReload()
expect(mounted.at(-1)).toBe('after:current')
expect(disposed).toEqual(['before', 'before'])
expect(event).toHaveBeenCalledOnce()
await entry.update({ config: { value: 'next' } })
await ctx.loader.await()
expect(mounted.at(-1)).toBe('after:next')
})
it('replaces volatile references on code HMR after an in-place config update', async () => {
const { ctx, module, imports, reload } = await fixture()
const Config = z.object({ value: z.string().volatile() })
const configs: ReturnType<typeof Config>[] = []
const before = { Config, apply(_ctx: Context, config: ReturnType<typeof Config>) { configs.push(config) } }
const after = { Config, apply(_ctx: Context, config: ReturnType<typeof Config>) { configs.push(config) } }
const job = module('volatile.mjs', before)
const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url, config: { value: 'initial' } }))
await ctx.loader.await()
await entry.update({ config: { value: 'current' } })
await ctx.loader.await()
expect(configs).toHaveLength(1)
const old = configs[0]!.value
expect(old.get()).toBe('current')
imports.set(job.url, after)
reload.stashed.add(job.url)
await reload.partialReload()
expect(configs).toHaveLength(2)
expect(configs[1]!.value).not.toBe(old)
expect(configs[1]!.value.get()).toBe('current')
await entry.update({ config: { value: 'after-reload' } })
expect(configs[1]!.value.get()).toBe('after-reload')
expect(old.get()).toBe('current')
})
it('reactivates a source-replaced consumer after provider and consumer configuration changes', async () => {
const { ctx, module, imports, reload } = await fixture()
const mounted: string[] = []
const provider = module('provider.mjs', { apply(ctx: Context, config: { revision: number }) {
ctx.provide('test.revision', config.revision)
} })
const before = { inject: ['test.revision'], apply() {} }
const after = { inject: ['test.revision'], apply(ctx: Context, config: { value: string }) {
mounted.push(`${config.value}:${ctx.get('test.revision')}`)
} }
const consumer = module('consumer.mjs', before)
const providerEntry = ctx.loader.resolve(await ctx.loader.create({ name: provider.url, config: { revision: 1 } }))
const consumerEntry = ctx.loader.resolve(await ctx.loader.create({ name: consumer.url, config: { value: 'initial' } }))
await ctx.loader.await()
imports.set(consumer.url, after)
reload.stashed.add(consumer.url)
await reload.partialReload()
expect(mounted).toEqual(['initial:1'])
await Promise.all([
providerEntry.update({ config: { revision: 2 } }),
consumerEntry.update({ config: { value: 'updated' } }),
])
await ctx.loader.await()
expect(mounted.at(-1)).toBe('updated:2')
})
it('restores cached modules and keeps the old plugin when replacement import fails', async () => {
const { ctx, module, imported, cache, reload } = await fixture()
const apply = vi.fn()
const job = module('plugin.mjs', { apply })
const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url }))
await ctx.loader.await()
const previous = entry.fiber
imported.mockRejectedValueOnce(new Error('compile failed'))
reload.stashed.add(job.url)
await expect(reload.partialReload()).rejects.toThrow('compile failed')
expect(cache.get(job.url)).toBe(job)
expect(entry.fiber).toBe(previous)
expect(apply).toHaveBeenCalledOnce()
})
it('does not replace a plugin whose dependencies have not changed', async () => {
const { ctx, module, imported, reload } = await fixture()
const job = module('plugin.mjs', { apply() {} })
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
const unrelated = module('unrelated.mjs')
imported.mockClear()
reload.stashed.add(unrelated.url)
await reload.partialReload()
expect(imported).not.toHaveBeenCalled()
})
it('replaces a plugin when a linked dependency changes, excluding framework modules', async () => {
const { ctx, module, imports, reload } = await fixture()
const dependency = module('dependency.mjs')
const framework = module('framework.mjs')
const job = module('plugin.mjs', { apply() {} }, [dependency, framework])
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
const apply = vi.fn()
imports.set(job.url, { apply })
reload.externals.add(framework.url)
reload.stashed.add(dependency.url)
await reload.partialReload()
expect(apply).toHaveBeenCalledOnce()
expect(reload.accepted).toContain(job.url)
expect(reload.accepted).not.toContain(framework.url)
})
it('classifies dependency cycles and excludes builtins and unchanged leaf modules', async () => {
const { module, reload } = await fixture()
const changed = module('changed.mjs')
const cycleA = module('a.mjs')
const cycleB = module('b.mjs', undefined, [cycleA])
cycleA.linked = Promise.resolve([cycleB])
const parent = module('parent.mjs', undefined, [changed])
const leaf = module('leaf.mjs')
const builtin = module('node:fs')
parent.linked = Promise.resolve([builtin, changed])
changed.linked = Promise.resolve([parent, cycleA, leaf, builtin])
reload.stashed.add(changed.url)
await reload.analyzeChanges()
expect(reload.accepted).toEqual(new Set([changed.url, parent.url]))
expect(reload.declined).toEqual(new Set([leaf.url, cycleA.url, cycleB.url]))
})
it('rejects failed replacement activation and restores the prior plugin', async () => {
const { ctx, module, imports, cache, reload } = await fixture()
const mounted: string[] = []
const original = { apply: () => { mounted.push('original') } }
const job = module('plugin.mjs', original)
const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url }))
await ctx.loader.await()
imports.set(job.url, { apply() { throw new Error('activation failed') } })
const event = vi.fn()
ctx.on('hmr/reload', event)
reload.stashed.add(job.url)
await expect(reload.partialReload()).rejects.toThrow('activation failed')
expect(cache.get(job.url)).toBe(job)
expect(mounted).toEqual(['original', 'original'])
expect(entry.fiber?.runtime?.callback).toBe(original.apply)
expect(event).not.toHaveBeenCalled()
})
it('leaves disposed child instances to their replacing parent', async () => {
const { ctx, module, imports, reload } = await fixture()
const seen: string[] = []
const original = { apply(_ctx: Context, config: { value: string }) { seen.push(config.value) } }
const job = module('plugin.mjs', original)
const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url, config: { value: 'entry' } }))
await ctx.loader.await()
await entry.fiber!.ctx.plugin(original, { value: 'child' })
await ctx.plugin(original, { value: 'independent' })
imports.set(job.url, { apply(_ctx: Context, config: { value: string }) { seen.push(`new:${config.value}`) } })
reload.stashed.add(job.url)
await reload.partialReload()
expect(seen).toContain('new:entry')
expect(seen).not.toContain('new:child')
expect(seen).toContain('new:independent')
expect(entry.fiber?._config).toEqual({ value: 'entry' })
})
it('invalidates a disabled module without activating it', async () => {
const { ctx, module, imports, reload } = await fixture()
const job = module('disabled.mjs', { apply() {} })
const id = await ctx.loader.create({ name: job.url, disabled: true })
const apply = vi.fn()
imports.set(job.url, { apply })
reload.stashed.add(job.url)
await reload.partialReload()
expect(ctx.loader.resolve(id).fiber).toBeUndefined()
expect(apply).not.toHaveBeenCalled()
})
it('does not disturb an unchanged runtime after an earlier replacement fails', async () => {
const { ctx, module, imports, reload } = await fixture()
const first = module('first.mjs', { apply() {} })
const untouched = vi.fn()
const second = module('second.mjs', { apply: untouched })
await ctx.loader.root.update([{ id: 'first', name: first.url }, { id: 'second', name: second.url }])
await ctx.loader.await()
imports.set(first.url, { apply() { throw new Error('failed before second') } })
reload.stashed.add(first.url)
reload.stashed.add(second.url)
await expect(reload.partialReload()).rejects.toThrow('failed before second')
expect(untouched).toHaveBeenCalledOnce()
})
it('restores the prior plugin when the replacement does not export a plugin', async () => {
const { ctx, module, imported, reload } = await fixture()
const original = { apply: vi.fn() }
const job = module('plugin.mjs', original)
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
imported.mockResolvedValueOnce({ notAPlugin: true })
reload.stashed.add(job.url)
await expect(reload.partialReload()).rejects.toThrow('invalid plugin')
expect(original.apply).toHaveBeenCalledTimes(2)
})
it('reports a missing entry base URL without changing the running module', async () => {
const { ctx, module, reload } = await fixture()
const job = module('plugin.mjs', { apply() {} })
const entry = ctx.loader.resolve(await ctx.loader.create({ name: job.url }))
await ctx.loader.await()
const missingBase = new Context()
onTestFinished(() => missingBase.fiber.dispose())
entry.parent.tree.ctx = missingBase
reload.stashed.add(job.url)
await expect(reload.partialReload()).rejects.toThrow('no base URL')
})
it('ignores framework entries and reports unresolved entry modules', async () => {
const { ctx, module, resolve, reload } = await fixture()
const framework = module('framework.mjs', { apply() {} })
const uncached = module('uncached.mjs', { apply() {} })
await ctx.loader.create({ name: framework.url })
await ctx.loader.create({ name: uncached.url })
await ctx.loader.await()
reload.externals.add(framework.url)
resolve.mockImplementation((name) => {
if (name === uncached.url) throw new Error('entry gone')
return { url: name }
})
reload.stashed.add(module('dependency.mjs').url)
const warn = vi.spyOn(ctx.logger, 'warn')
await reload.partialReload()
expect(warn).toHaveBeenCalledWith(expect.objectContaining({ message: 'entry gone' }))
expect(await ctx.hmr.getLinked('missing')).toEqual([])
})
it.each(['uncached', 'no-plugin'])('leaves an entry alone when its cache is %s', async (state) => {
const { ctx, module, cache, imported, reload } = await fixture()
const job = module('plugin.mjs', { apply() {} })
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
if (state === 'uncached') cache.delete(job.url)
else job.module!.getNamespace = () => undefined
imported.mockClear()
reload.stashed.add(module('changed.mjs').url)
await reload.partialReload()
expect(imported).not.toHaveBeenCalled()
})
it('restores the CommonJS cache when an ESM replacement import fails', async () => {
const { ctx, module, imported, reload } = await fixture()
const job = module('plugin.cjs', { apply() {} })
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
const require = createRequire(import.meta.url)
const filename = fileURLToPath(job.url)
const cached = new NodeModule(filename)
require.cache[filename] = cached
onTestFinished(() => { Reflect.deleteProperty(require.cache, filename) })
imported.mockRejectedValueOnce(new Error('compile failed'))
reload.stashed.add(job.url)
await expect(reload.partialReload()).rejects.toThrow('compile failed')
expect(require.cache[filename]).toBe(cached)
})
it('can replace a plugin that has an earlier activation failure', async () => {
const { ctx, module, imports, reload } = await fixture()
const job = module('plugin.mjs', { apply() { throw new Error('earlier activation failed') } })
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
const apply = vi.fn()
imports.set(job.url, { apply })
reload.stashed.add(job.url)
await reload.partialReload()
expect(apply).toHaveBeenCalledOnce()
})
it('reports the original replacement failure when restoring the old plugin also fails', async () => {
const { ctx, module, imports, reload } = await fixture()
let restoring = false
const job = module('plugin.mjs', { apply() {
if (restoring) throw new Error('restore failed')
} })
await ctx.loader.create({ name: job.url })
await ctx.loader.await()
restoring = true
imports.set(job.url, { apply() { throw new Error('replacement failed') } })
const warn = vi.spyOn(ctx.logger, 'warn')
reload.stashed.add(job.url)
await expect(reload.partialReload()).rejects.toThrow('replacement failed')
expect(warn).toHaveBeenCalledWith(expect.objectContaining({ message: 'restore failed' }))
})