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

[exo-nikita]

Summary

Three threads of work, now sitting as a single commit on top of post-restructure main.

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, { source, isEntry, isBinary }) once per file. Uses data.resourceResolveData.path (not data.resource) so query strings, inline loaders, data: URIs, and null-loader outputs don't crash. 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 the existing validatePluginOptions / assertOptionsMatchConfig helpers in stasis-core/config.

3. Plugin↔preload coordination rules

The plugin used to assert "Stasis preload is not active" at module import, which blocked the standalone use case entirely. We now codify a richer contract via a new resolvePluginState(label, options, cwd) helper in stasis-core/state:

#	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 a 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). Both plugins also wire compiler.hooks.done / build.onEnd to call state.write() for non-preload State (skipping on build failure to avoid clobbering).

Hardening that came out of review

• Both plugins filter to isTrackedPath (js/mjs/cjs/ts/jsx/tsx/json/mts/cts) before addFile/addImport — untracked extensions (.css, .wasm, asset modules) compile but stay out of the lockfile, since the lockfile/loader semantics can't round-trip them.
• StasisEsbuild now accepts the type import attribute (with { type: 'json' }), tolerates benign warnings from sibling plugins, and falls back to the default loader for unknown extensions instead of asserting.
• resolvePluginState validates scope and debug against the preload (previously it silently dropped plugin values on the sidecar paths).

Test plan

• node --run lint — clean
• node --run test — 770/770 pass (excluding 26 pre-existing failures in popular-npm-modules.test.js, unrelated)
• stasis/tests/state-sidecar.test.js — sidecar mechanics + rules 2/4/5/6 of resolvePluginState
• stasis/tests/state-resolve-no-preload.test.js — rule 1 (hard throw across add/frozen/replace) + rule 7 (noop)
• stasis/tests/state-resolve-nobundle-preload.test.js — preload-with-no-bundle reuse and sidecar paths (incl. bundle: 'ignore' regression)
• stasis/tests/{webpack,esbuild}.test.js — env-driven, plugin-option, rule-1, rule-7, untracked-extension, failed-build-no-clobber, and rule-6 sidecar coverage end-to-end through the actual bundler harness
• STASIS_TEST_PRELOAD=0 opts a test out of the helper's auto-preload to exercise standalone paths
• STASIS_TEST_PRELOAD_OPTIONS lets a test point preload and plugin at different bundleFile paths (for the sidecar test)

[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.