feat(plugins): import tracking, options bag, and preload coordination

[exo-nikita]

Summary

Three stacked changes, on top of the now-merged Config refactor (#30) and the multi-State groundwork (#31).

1. StasisWebpack: record imports and entry status

Migrated to webpack's modern compiler.hooks.normalModuleFactory.tap / nmf.hooks.afterResolve.tap API. afterResolve derives isEntry = !issuer and records both state.addImport(parentURL, rawRequest, url) for every non-entry edge and state.addFile(url, { isEntry }) once per file. New fixtures (webpack-full, webpack-nm) and a spawning helper.

2. Both plugins accept a constructor options bag

new StasisWebpack({ lock, bundle, bundleFile, scope, debug }) and new StasisEsbuild({ ... }) accept the same keys as the CLI flags. Validation goes through validatePluginOptions from #30.

3. Plugin↔preload coordination rules

The plugin used to assert "stasis preload is not active" which blocked the standalone use case. We now codify a richer contract via a new resolvePluginState(label, options, cwd) helper:

#	Scenario	Behavior
1	Plugin asks for any lock other than none/ignore, no preload	Hard throw — lockfile would silently miss the bundler's own deps
2	Plugin lock disagrees with preload lock	Throw
3	Plugin lock agrees with preload	Reuse the preload State (single, unified lockfile)
4	Preload has bundle on, plugin can't disable	Throw on bundle: 'none' / 'ignore'
5	Plugin bundleFile unset or matches preload's	Reuse the preload State
6	Plugin bundleFile differs from preload's	Sidecar State — shares hashes/entries/modules with preload by reference (unified lockfile), has its own sources/formats/imports/resources and writes only its own bundle file
7	Plugin says lock: 'none' AND bundle: 'none' with no preload	Noop — useful for env/flag-controlled builds

Sidecar State is enabled by the new parent: preload option on the State constructor (mutually exclusive with preload: true); write() on a sidecar emits the bundle but skips the lockfile (the preload owns it).

The plugin's setup/apply short-circuits when state === null (rule 7), registering no hooks.

Depends on

• feat(config): accept options bag matching CLI flags #30 (merged) — Config options bag + validatePluginOptions / assertOptionsMatchConfig
• feat(state): allow multiple State instances; expose State.preload #31 (merged) — State.preload and multi-State support

Test plan

• node --run lint — clean
• node --run test — 275/275 pass
• tests/state-sidecar.test.js — sidecar mechanics: shared hashes/entries/modules, independent sources, sidecar write() emits bundle but not lockfile, rule-2/4/5/6 paths of resolvePluginState
• tests/state-resolve-no-preload.test.js — rule 1 (hard throw across add/frozen/replace) + rule 7 (noop)
• tests/{webpack,esbuild}.test.js — rule 1 + rule 7 end-to-end through the actual bundler harness; existing plugin tests adapted to run under an auto-preload (helpers now construct a preload by default; STASIS_TEST_PRELOAD=0 opts out)
• Manual: tampered bundle is rejected on the next run with lock=frozen, bundle=load
• Manual: EXODUS_STASIS_LOCK=frozen and new StasisWebpack({ lock: 'add' }) together raise Config options can not override stasis env

[Copilot]

Pull request overview

Adds a comprehensive node:test suite for the Stasis webpack plugin (lock add/frozen/replace/ignore, bundle add/replace, scope variants, config conflicts, tamper detection) along with two fixture projects, and modernizes src/webpack.js to use the hooks.tap() API with node:assert/strict, recording imports via state.addImport and tagging entries via addFile(..., { isEntry }).

Changes:

• Rewrite src/webpack.js to use compiler.hooks.normalModuleFactory / nmf.hooks.afterResolve taps, track isEntry, and call state.addImport(parentURL, rawRequest, url).
• Add tests/webpack.test.js and tests/webpack-run.helper.js running webpack in a child process with a fresh State per test.
• Add webpack-full and webpack-nm fixtures (with committed stasis.config.json and stasis.lock.json).

Reviewed changes

Copilot reviewed 13 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/webpack.js	Switch from legacy plugin() callbacks to hooks.tap(), record imports and entry flag
tests/webpack.test.js	New 300+ line test suite covering lock modes, bundle, tampering, scopes, conflicts
tests/webpack-run.helper.js	Child-process helper that constructs State, runs webpack with the plugin, then writes state
tests/fixtures/webpack-full/*	Full-scope fixture: entry, hello, package.json, committed config & lockfile, pnpm-workspace marker
tests/fixtures/webpack-nm/*	node_modules-scope fixture: entry/helper, fake-cjs-pkg under node_modules, committed config & lockfile

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.