feat(bundle): Bundle.fromJSON with a contents-free mode, and Bundle.fileKeyAt

[exo-nikita]

This PR holds the stasis-core part of #184, split out so it can be reviewed and merged on its own. It adds what a streaming bundle reader needs from Bundle. The reader itself stays in #184 (@exodus/stasis/bundle-reader).

Changes

Bundle.fromJSON(json, { contents = true })

• This is Bundle.parse on a value that is already parsed; parse now just calls fromJSON(JSON.parse(text)).
• With contents: false, the result is contents-free:
  • Every file value must be a symbol placeholder, left where the reader took that file's contents out. A file that still holds anything else is rejected.
  • Each bucket's files becomes a frozen, null-prototype object whose keys still list the files, but every value is a getter that throws.
  • As a result sources, serialize() and merge() also throw, because they read file contents. Metadata stays readable (hasCode, the SBOM components, and so on).
• The placeholder rule also rejects every bundle in which the reader and fromJSON could disagree about which strings are files. Examples are a v0 bundle with modules, an array where an object belongs, and non-string contents. Bundle.parse itself is unchanged.

Bundle.fileKeyAt(path)

• Takes a key path in the bundle JSON (v1 sources|modules.<dir>.files.<rel>, v0 sources.<path>).
• Returns the flat key, as sources keys it, of the file whose contents sit there. Any other position returns undefined.
• A non-canonical key throws. The check is the same canonicalFileKey that fromJSON applies through flatFileKeys.

Root-key fix

• Only the root listing (rel '') may use the flat key '.'. A file named '.' was a second spelling of it; both Bundle.parse and Lockfile.parse now reject it. The check is the new canonicalFileKey in artifact-util, which flatFileKeys now uses.
• In v0, the root listing is spelled '' or '.', matching how formats already treats them. Both map to rel '', and a v0 bundle with both is rejected.

Docs: a short "Contents-free bundles" section in doc/file-formats.md.

Tests

• New tests/bundle-contents.test.js, which goes through the reader's real flow: replace each string fileKeyAt locates with a placeholder, then call fromJSON(…, { contents: false }). It checks:
  • every field, file list and SBOM component is kept, and reading contents, sources, serialize() and merge() throw;
  • any file the reader didn't take out is rejected, including the shapes where fileKeyAt and fromJSON disagree;
  • walking every string with fileKeyAt gives exactly bundle.sources; non-file positions give undefined; non-canonical keys throw.
• tests/public-exports.test.js: the root-key and v0-alias cases.
• Local runs: node --run lint is clean and node --run test passes all 72 suites.

Once this merges, #184 will be rebased so it only adds the reader, which will call fromJSON(tree, { contents: false }).

🤖 Generated with Claude Code

https://claude.ai/code/session_01FinLHpaKeRRjstqzMnwj6u