Fix lockfiles lost across processes, review findings - #8

…ix for Next.js and hand-configured plugins (#10)

* webpack: graceful-fs in any copy is the real disk (Next.js, plugin in the config)

onDisk() knew webpack 5's graceful-fs only as the copy resolved next to the
Compiler module. Next.js bundles its own copy, and a BundleLockfilePlugin
configured by hand does not know where webpack is: their lockfiles were
treated as in-memory output - emitted as a webpack asset, without the lock,
not shared with other processes (the race fixed in #8, still there for
them). graceful-fs is now known by its gracefulify(); Node's fs counts too;
memfs (webpack-dev-middleware) still does not.

Found with a real Next.js 16 build and a hand-configured webpack 5 config:
both outputFileSystems are graceful-fs objects the old check did not match.

Tests: the on-disk unit test also with a graceful-fs-shaped file system and
Node's fs (fails on main); a matrix case with the plugin in the config of two
webpack processes writing one directory in parallel.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* README: every statement checked against code, tests and sources; architecture diagrams

Each statement was checked against the code, a test that exercises it, or a
primary source for other tools (package tarballs, upstream source and issues).

Corrected:
- only Vite/Rollup/Rolldown lockfiles record output hashes: a webpack-built
  bundle bundled by another build is not attributed
- keys are relative to the working directory for Vite/Rollup/Rolldown, not
  webpack's context
- vite build --watch on Vite 8 (Rolldown's watch()) lists no CSS @import
  packages
- webpack versions: shutdown hook since 5.17 (not 5.20), "#" cut since 5.104
  (not 5.105), also in code comments and test names; inlineExports inlines
  constants of up to 6 bytes
- syft, Yarn 2 and nodejs/node#60380 details; tests: cases without an oracle
  and packages oracles cannot see

Added: the Vite/Rollup plugin for a config (matrix cases on Vite 7 and 8),
the exact limits (recorded files and hashes, scanned entries, file size, lock
timeouts), warnings, the module.register deprecation, and "How it works":
mermaid diagrams of how bundle-lockfile gets into each build system, a webpack
and a Rollup/Vite build's hook timeline, files to packages, and several
writers of one lockfile.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* README: fixes from an independent audit against the code

- install from the repository, not v0.0.2 (which lacks the graceful-fs fix
  the README describes)
- the [fullhash] case tests separate directories, not a shared one
- Vite installers as tested: Vite 8 with npm, npx, pnpm 10, yarn 1, yarn 4
  and bun, Vite 7 with npm and yarn 4 Plug'n'Play
- only the ESM hook is limited to bundler processes on Node < 24.12; Rollup's
  CommonJS build is hooked everywhere; rolldown-vite counts too
- Sass partials and style @imports, copies by another process: Vite, Rollup
  and Rolldown only
- the d3 re-export claim scoped to what was observed (GitLab, LibreChat)
- the 2 s timestamp slack, the 20 MiB limit's exception, the in-memory write
  conditions, debug lines, warnings, writer ids (kind, entry template if a
  string), the example lockfile, BUNDLE_LOCKFILE_FILE in nested lookups,
  esmPackages for new adapters, diagram details, conditions of test claims

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>