@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.51

package/common/bundle-compare-versions.js

@@ -0,0 +1,172 @@
+// Dependency versions two bundles record, compared: sorting versions as
+// semver orders them, which way a package moved, and the Overview's package
+// rows from computeBundleDiff's sizes. No @preventive/compare here, so a view
+// that only orders versions loads none of the comparison's pairing.
+
+// The Overview's package rows: each package that differs, once, from its
+// sizes (computeBundleDiff's `packages`) and the versions each bundle
+// records for it (`bundlePackageVersions`). A package only one side has is
+// removed or added, with its size and versions there; one both have is
+// changed when its size or its versions moved, with both sides of each —
+// own source and workspace modules carry sizes alone.
+export function comparePackages(packages, baseVersions, otherVersions) {
+  const sizes = new Map()
+  for (const r of packages.onlyBase) sizes.set(r.pkg, { base: r.bytes, other: null })
+  for (const r of packages.onlyOther) sizes.set(r.pkg, { base: null, other: r.bytes })
+  for (const r of packages.changed) sizes.set(r.pkg, { base: r.baseBytes, other: r.otherBytes })
+  for (const r of packages.unchanged ?? []) sizes.set(r.pkg, { base: r.bytes, other: r.bytes })
+  const versionsOf = (map, pkg) => [...map.get(pkg) ?? []].toSorted(compareSemver)
+  const moved = new Set([...packages.onlyBase, ...packages.onlyOther, ...packages.changed].map(r => r.pkg))
+  for (const pkg of new Set([...baseVersions.keys(), ...otherVersions.keys()])) {
+    if (!sameVersions(versionsOf(baseVersions, pkg), versionsOf(otherVersions, pkg))) moved.add(pkg)
+  }
+  const added = [], changed = [], removed = []
+  for (const pkg of moved) {
+    const size = sizes.get(pkg) ?? { base: null, other: null }
+    const after = versionsOf(otherVersions, pkg), before = versionsOf(baseVersions, pkg)
+    const onBase = size.base !== null || before.length > 0
+    const onOther = size.other !== null || after.length > 0
+    if (onBase && !onOther) removed.push({ pkg, bytes: size.base, versions: before })
+    else if (onOther && !onBase) added.push({ pkg, bytes: size.other, versions: after })
+    else {
+      changed.push({
+        pkg, baseBytes: size.base, otherBytes: size.other,
+        delta: size.base !== null && size.other !== null ? size.other - size.base : null,
+        baseVersions: before, otherVersions: after,
+        direction: before.length > 0 && after.length > 0 && !sameVersions(before, after) ? versionDirection(before, after) : null,
+      })
+    }
+  }
+  const byPkg = (a, b) => a.pkg.localeCompare(b.pkg)
+  return { removed: removed.toSorted(byPkg), added: added.toSorted(byPkg), changed: changed.toSorted(byPkg) }
+}
+
+// Split a version into its dotted-numeric core and its prerelease tail,
+// dropping any `+build` metadata (semver ignores it for precedence).
+// `1.2.3-rc.1+sha` → { core: '1.2.3', pre: 'rc.1' }.
+function splitVersion(v) {
+  const s = String(v).trim()
+  const noBuild = s.split('+', 1)[0]
+  const dash = noBuild.indexOf('-')
+  return dash === -1
+    ? { core: noBuild, pre: '' }
+    : { core: noBuild.slice(0, dash), pre: noBuild.slice(dash + 1) }
+}
+
+// Lightweight semver-ish comparison, enough to sort versions ascending
+// and label an update ↑/↓. Compares the dotted-numeric core part by
+// part (a missing part counts as 0); on an equal core a release ranks
+// above a prerelease (`1.0.0` > `1.0.0-rc.1`) and two prereleases
+// compare by their dot identifiers (numeric where both are numeric,
+// else lexical) per the semver precedence rules. NOT a full
+// implementation — a non-numeric core segment falls back to a string
+// compare of the whole version so ordering stays total and stable.
+export function compareSemver(a, b) {
+  if (a === b) return 0
+  const A = splitVersion(a)
+  const B = splitVersion(b)
+  const ap = A.core.split('.')
+  const bp = B.core.split('.')
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const x = Number(ap[i] ?? 0)
+    const y = Number(bp[i] ?? 0)
+    if (Number.isNaN(x) || Number.isNaN(y)) return a < b ? -1 : 1
+    if (x !== y) return x < y ? -1 : 1
+  }
+  if (A.pre === B.pre) return 0
+  // A core with no prerelease is the higher (released) version.
+  if (!A.pre) return 1
+  if (!B.pre) return -1
+  const ai = A.pre.split('.')
+  const bi = B.pre.split('.')
+  for (let i = 0; i < Math.max(ai.length, bi.length); i++) {
+    const x = ai[i]
+    const y = bi[i]
+    if (x === undefined) return -1
+    if (y === undefined) return 1
+    if (x === y) continue
+    const xNum = /^\d+$/u.test(x)
+    const yNum = /^\d+$/u.test(y)
+    // Numeric identifiers always rank below non-numeric ones (semver),
+    // and compare numerically against each other.
+    if (xNum && yNum) return Number(x) < Number(y) ? -1 : 1
+    if (xNum !== yNum) return xNum ? -1 : 1
+    return x < y ? -1 : 1
+  }
+  return 0
+}
+
+// True when two ascending-sorted version arrays hold the same members.
+function sameVersions(a, b) {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
+  return true
+}
+
+// Direction of a version move, from the versions dropped and the versions
+// taken on: 'up' when everything dropped is older than everything taken
+// on (`1.0.0` → `2.0.0`), or, with only drops or only additions, than the
+// versions kept (`1.0.0, 2.0.0` → `2.0.0` drops the older copy, and a newer
+// copy added beside the old is up too); 'down' the other way round; and
+// 'changed' when the moves fall between (`1.0.0, 1.2.0, 2.0.0` → `1.0.0,
+// 2.0.0`).
+export function versionDirection(baseVersions, otherVersions) {
+  const dropped = baseVersions.filter(v => !otherVersions.includes(v)).toSorted(compareSemver)
+  const taken = otherVersions.filter(v => !baseVersions.includes(v)).toSorted(compareSemver)
+  const kept = baseVersions.filter(v => otherVersions.includes(v)).toSorted(compareSemver)
+  const [from, to] = dropped.length > 0 && taken.length > 0 ? [dropped, taken]
+    : dropped.length > 0 ? [dropped, kept] : [kept, taken]
+  if (from.length === 0 || to.length === 0) return 'changed'
+  // Every version of `a` older than every version of `b`.
+  const before = (a, b) => compareSemver(a.at(-1), b[0]) < 0
+  return before(from, to) ? 'up' : before(to, from) ? 'down' : 'changed'
+}
+
+// Diff two `Map<packageName, Set<version>>` inventories (as
+// `bundlePackageVersions` returns for each bundle) into the dependency
+// version changes between them. Mirrors the file/package diff framing:
+// `base` is the open bundle, `other` the one compared against.
+//
+//   {
+//     updated: [{ pkg, baseVersions: [...], otherVersions: [...],
+//                 direction: 'up' | 'down' | 'changed' }],
+//     added:   [{ pkg, versions: [...] }],   // dependency only in other
+//     removed: [{ pkg, versions: [...] }],   // dependency only in base
+//     totals:  { baseDeps, otherDeps },      // distinct package counts
+//   }
+//
+// `updated` is the headline — a package present on BOTH sides whose set
+// of versions changed (the "what did this bump pull in?" answer);
+// packages whose versions are byte-for-byte the same are dropped.
+// Version arrays are sorted ascending; the three lists are sorted by
+// package name so the dependency list reads alphabetically.
+export function computeVersionUpdates(baseVersions, otherVersions) {
+  const updated = []
+  const added = []
+  const removed = []
+  const names = new Set([...baseVersions.keys(), ...otherVersions.keys()])
+  for (const pkg of names) {
+    const bSet = baseVersions.get(pkg)
+    const oSet = otherVersions.get(pkg)
+    if (bSet && oSet) {
+      const b = [...bSet].toSorted(compareSemver)
+      const o = [...oSet].toSorted(compareSemver)
+      if (sameVersions(b, o)) continue
+      updated.push({ pkg, baseVersions: b, otherVersions: o, direction: versionDirection(b, o) })
+    } else if (bSet) {
+      removed.push({ pkg, versions: [...bSet].toSorted(compareSemver) })
+    } else {
+      added.push({ pkg, versions: [...oSet].toSorted(compareSemver) })
+    }
+  }
+  const byPkg = (a, b) => a.pkg.localeCompare(b.pkg)
+  updated.sort(byPkg)
+  added.sort(byPkg)
+  removed.sort(byPkg)
+  return {
+    updated,
+    added,
+    removed,
+    totals: { baseDeps: baseVersions.size, otherDeps: otherVersions.size },
+  }
+}

package/common/bundle-comparison.d.ts

@@ -0,0 +1,8 @@
+import type { Root } from '@preventive/compare'
+import type { BundleDetails } from './bundle-metadata.js'
+// A comparison as Compare and Review read it; `files.basePaths` maps every
+// base file to how it reads as the other side lays its files out.
+export interface Comparison extends Record<string, unknown> {
+  files: Record<string, unknown> & { root: Root | null; basePaths: Map<string, string> }
+}
+export function prepareComparison(base: BundleDetails, other: BundleDetails, scope?: string | null): Comparison

package/common/bundle-comparison.js

@@ -0,0 +1,62 @@
+// One comparison model for Compare and Review: bytes, metadata, resolutions,
+// dependency versions and line counts, its files paired by
+// @preventive/compare (computeBundleDiff, treeLayout). Worked out by the
+// server for two managed bundles or two versions of a package
+// (server-managed/comparison.ts), and by the viewer only for bundles it opened
+// itself, which no server holds (ui/view/bundle-comparison.js): a managed
+// viewer loads none of it.
+import { layoutPackageDirs, treeLayout } from '@preventive/compare'
+import { bundlePkgOf } from './bundle-pkg-of.js'
+import { bundlePackageDirs, bundlePackageVersions } from './bundle-sources.js'
+import { bundleFileMeta, computeBundleDiff, computeResolutionDiff } from './bundle-compare-diff.js'
+import { comparePackages, computeVersionUpdates } from './bundle-compare-versions.js'
+import { bundleCompareFiles, bundleCompareResolutions } from './bundle-compare-inputs.js'
+import { bundleLineCounts } from './bundle-metadata.js'
+
+export function prepareComparison(base, other, scope = null) {
+  // Every file each side mounts, resources included: a diff of
+  // source alone would call two bundles identical when only their
+  // images differ, and total less than the Overview does.
+  // From the bundle picked to the open one.
+  const [from, to] = [base, other]
+  const baseSources = bundleCompareFiles(from, scope)
+  const otherSources = bundleCompareFiles(to, scope)
+  // Classify original paths and preserve recorded Stasis package
+  // boundaries from either side, as the open one lays its files out
+  // where their roots differ. Own source has one identity.
+  const layout = treeLayout(baseSources.keys(), otherSources.keys())
+  const packageDirs = layoutPackageDirs(bundlePackageDirs(from), bundlePackageDirs(to), layout)
+  const pkgOf = (p) => bundlePkgOf(p, { packageDir: packageDirs?.get(p) })
+  const diff = computeBundleDiff(baseSources, otherSources, pkgOf, layout, [bundleFileMeta(from), bundleFileMeta(to)])
+  // Each side's lines of code (bundleLineCounts), on its rows and in
+  // the totals; a file that isn't text has none.
+  const baseLines = bundleLineCounts(from), otherLines = bundleLineCounts(to)
+  const linesOf = (lines, paths) => { let total = 0; for (const path of paths) total += lines.get(path) ?? 0; return total }
+  Object.assign(diff.totals, { baseLines: linesOf(baseLines, baseSources.keys()), otherLines: linesOf(otherLines, otherSources.keys()) })
+  for (const row of diff.files.onlyBase) row.lines = baseLines.get(row.basePath ?? row.path) ?? 0
+  for (const row of diff.files.onlyOther) row.lines = otherLines.get(row.path) ?? 0
+  for (const row of diff.files.changed) Object.assign(row, { baseLines: baseLines.get(row.basePath ?? row.path) ?? 0, otherLines: otherLines.get(row.path) ?? 0 })
+  diff.resolutions = computeResolutionDiff(
+    bundleCompareResolutions(from, scope),
+    bundleCompareResolutions(to, scope),
+    new Map(diff.files.changed.filter(row => row.renamedFrom != null).map(row => [row.basePath, row.path])),
+    diff.files.basePaths,
+    diff.files.root,
+  )
+  // Dependency versions come from the stasis per-module `{ name,
+  // version }` metadata, not the path/byte walk above, so they're
+  // computed alongside and hung off the same memo: the package rows
+  // join them to the sizes, the summary counts them. Empty for
+  // sourcemap / v0 pairs (no version metadata), whose rows carry sizes
+  // alone.
+  // Keyed by install directory, as the sizes are (`bundlePkgOf`).
+  const versionKey = dir => bundlePkgOf('', { packageDir: dir })
+  const baseVersions = bundlePackageVersions(from, scope ? baseSources.keys() : null, versionKey)
+  const otherVersions = bundlePackageVersions(to, scope ? otherSources.keys() : null, versionKey)
+  diff.versionUpdates = computeVersionUpdates(baseVersions, otherVersions)
+  diff.packageRows = comparePackages(diff.packages, baseVersions, otherVersions)
+  // The reason scope its files are within, for what the server works out of
+  // them alike (rename-diff.js, type-only.js).
+  diff.scope = scope ?? ''
+  return diff
+}

package/common/bundle-metadata.d.ts

@@ -0,0 +1,15 @@
+import type { SourceMap } from '@preventive/sourcemap'
+import type { SourcemapEdge } from './bundle-sourcemap.js'
+export const BUNDLE_METADATA_VERSION: number
+export const FILE_HASH: RegExp
+export interface BundleIdentity { integrity: string; kind: string | null; size: number }
+export interface BundleDetails extends BundleIdentity { bundle?: unknown; json?: unknown; map?: SourceMap; edges?: readonly SourcemapEdge[] }
+export function parseBundleContents(text: string, identity: BundleIdentity): BundleDetails
+export function computeBundleFileHashes(details: BundleDetails): Promise<Map<string, string>>
+export interface BundleMetadata extends Record<string, unknown> {
+  files: [string, number | null, string | null, number | null][]
+  codeStats: { files: number; lines: number; bytes: number }
+}
+export function createBundleMetadata(details: BundleDetails): Promise<BundleMetadata>
+export function parseBundleMetadata(data: unknown, integrity: string): BundleDetails
+export function createBundleSummary(details: BundleDetails, metadata?: BundleMetadata): { files: number; codeFiles: number; lines: number; commit?: string; stasisVersion?: number }

package/common/bundle-metadata.js

@@ -0,0 +1,226 @@
+import { bundleCodeStats } from './bundle-stats.js'
+import { bundleCommitHash } from './bundle-commit.js'
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { computeFileHash } from '@preventive/report'
+import { utf8ByteLength } from './utf8.js'
+import { bundleFileSizes, bundleSourcesAsMap, bundleUnsizedFiles } from './bundle-sources.js'
+import { bundleSourcemapEdges, parseSourcemap, sourcemapEntries } from './bundle-sourcemap.js'
+
+// Version 2 sizes every file by its bytes, resources included. A version 1
+// index sized by what the source map held when it was written: before the
+// map asked each entry's format, that took a directory capture for a file
+// and a base64 resource for its spelling; after, it left every resource
+// out. Either way its sizes are not file sizes, so it is read for its
+// hashes alone and rebuilt on open.
+// Version 3 also retains the bundle's repository and package origin metadata.
+// Version 4 retains dependency repositories as well.
+// Version 5 counts lines of code, leaving blank lines out.
+// Version 6 reads a sourcemap whole (bundle-sourcemap.js): an index map's
+// files too, each once, keyed with `sourceRoot` in front, and the edges
+// between them.
+export const BUNDLE_METADATA_VERSION = 6
+const INDEX_VERSION = BUNDLE_METADATA_VERSION
+const hashJobs = new WeakMap()
+const SOURCE_TABS = new Set(['terminal', 'code', 'search', 'compare'])
+
+export function bundleNeedsSources(tab, sourceFile = null) {
+  return Boolean(sourceFile) || SOURCE_TABS.has(tab)
+}
+
+// A file's hash as metadata names it: computeFileHash's sha512 of its text.
+export const FILE_HASH = /^sha512-[A-Za-z0-9+/]{86}==$/u
+
+// Bound outstanding WebCrypto jobs: serial awaits incur one task round-trip
+// per file, while an unbounded Promise.all holds every encoded body at once.
+export function computeBundleFileHashes(details) {
+  if (details.fileHashes) return Promise.resolve(details.fileHashes)
+  if (hashJobs.has(details)) return hashJobs.get(details)
+  const job = (async () => {
+    const entries = [...bundleSourcesAsMap(details)]
+    const result = new Map()
+    for (let i = 0; i < entries.length; i += 32) {
+      const hashes = await Promise.all(entries.slice(i, i + 32).map(async ([file, content]) => [file, await computeFileHash(content)]))
+      for (const [file, hash] of hashes) result.set(file, hash)
+    }
+    details.fileHashes = result
+    return result
+  })()
+  hashJobs.set(details, job)
+  job.catch(() => hashJobs.delete(details))
+  return job
+}
+
+// Count lines of code: lines with anything but whitespace on them, comments
+// included for now, split at \r\n, \r or \n. Each such line is counted at
+// its first non-whitespace character, its rest passed over to the next line
+// break: no match runs a line's length, which past some 9 million characters
+// (a bundled payload's one line, as Shai-Hulud's 10 MB bun_environment.js)
+// overflows the stack a Unicode regular expression backtracks with in a
+// string holding any character past U+00FF.
+// The source map intentionally excludes non-text resources, so a null entry
+// remains the metadata marker for images, fonts, and other binary payloads.
+export function bundleSourceLineCount(content) {
+  if (typeof content !== 'string') return 0
+  const code = /\S/gu, end = /[\r\n]/gu
+  let lines = 0
+  while (code.test(content)) {
+    lines++
+    end.lastIndex = code.lastIndex
+    if (!end.test(content)) break
+    code.lastIndex = end.lastIndex
+  }
+  return lines
+}
+
+// Each source's lines of code, by path: the index's where `details` has them,
+// else counted once and kept on it. `bundleSourcesAsMap` holds only textual
+// sources: Stasis resources (images, fonts, and other binary payloads) have
+// no lines, so they cannot distort the language shares.
+export function bundleLineCounts(details) {
+  return details.lineCounts ??= new Map([...bundleSourcesAsMap(details)].map(([path, content]) => [path, bundleSourceLineCount(content)]))
+}
+
+function mapObject(value) {
+  return value instanceof Map ? Object.fromEntries([...value].map(([key, v]) => [key, mapObject(v)])) : value
+}
+
+// A private, versioned derivative of the bundle, not a Stasis lock. Source
+// bodies are omitted; file sizes and hashes keep metadata views self-contained.
+// A row is `[path, bytes, hash, lines]`: a resource has bytes but no hash or
+// lines, since it is no source; a directory capture has none of the three.
+// `unsized` names the mounted files with no bytes to give (a base64 spelling
+// that does not decode), which a null size alone cannot tell from no file.
+export async function createBundleMetadata(details) {
+  const hashes = await computeBundleFileHashes(details)
+  const sizes = bundleFileSizes(details)
+  const sourceLines = bundleLineCounts(details)
+  const result = { version: INDEX_VERSION, integrity: details.integrity, kind: details.kind, size: details.size, codeStats: bundleCodeStats(sourceLines, sizes),
+    files: [...sizes].map(([path, size]) => [path, size, hashes.get(path) ?? null, sourceLines.get(path) ?? null]) }
+  const unsized = bundleUnsizedFiles(details)
+  if (unsized.size > 0) result.unsized = [...unsized]
+  if (details.kind === 'sourcemap') {
+    const { version, file, sourceRoot, names } = details.json
+    const entries = sourcemapEntries(details)
+    result.json = { version, file, sourceRoot, sources: entries.map(([path]) => path) }
+    // A map's arrays as written can repeat a path with different/absent
+    // content. Keep the Overview's positional inventory, alongside the
+    // path-keyed graph index.
+    result.sourceSizes = entries.map(([, content]) => typeof content === 'string' ? utf8ByteLength(content) : null)
+    result.namesCount = details.namesCount ?? names?.length ?? null
+    // `[from, to]` or `[from, to, specifier]`, `from` and `to` rows of `files`.
+    const rows = new Map(result.files.map(([path], i) => [path, i]))
+    result.edges = bundleSourcemapEdges(details).map(([from, to, ...specifier]) => [rows.get(from), rows.get(to), ...specifier])
+  } else {
+    const b = details.bundle
+    const bundle = { version: b.version, config: b.config, repo: b.repo, package: b.package, formats: mapObject(b.formats), imports: mapObject(b.imports), reason: b.reason, executable: [...b.executable] }
+    if (b.version === 0) {
+      bundle.sources = Object.fromEntries([...sizes.keys()].map((path) => [path, null]))
+    } else {
+      const modules = {}, sources = {}
+      for (const [dir, info] of b.modules) {
+        const target = dir.split('/').includes('node_modules') ? modules : sources
+        Object.defineProperty(target, dir, { enumerable: true, value: {
+          name: info.name, version: info.version, ecosystem: info.ecosystem, repo: info.repo,
+          files: Object.fromEntries(Object.keys(info.files).map((path) => [path, null])),
+        } })
+      }
+      bundle.modules = modules
+      if (b.config.scope === 'full') { bundle.sources = sources; bundle.entries = [...b.entries] }
+    }
+    result.bundle = bundle
+  }
+  return result
+}
+
+// Catalogs need counts without the per-file inventory. Match scan inputs:
+// textual resources count as files (with zero LoC); binary resources do not
+// count as Code inputs, and missing source bodies/directories are not files.
+export function createBundleSummary(details, metadata) {
+  const files = (metadata?.files ?? [...bundleFileSizes(details)]).filter(([, size]) => size !== null)
+  const formats = details.kind === 'stasis' ? details.bundle.formats : null
+  const lines = metadata?.codeStats.lines ?? [...bundleSourcesAsMap(details).values()].reduce((sum, source) => sum + bundleSourceLineCount(source), 0)
+  const commit = details.kind === 'stasis' ? bundleCommitHash(details.bundle.repo?.commit) : null
+  return { files: files.length, lines,
+    codeFiles: files.filter(([path]) => !['resource:base64', 'directory'].includes(formats?.get(path))).length,
+    ...(commit ? { commit } : {}),
+    // The Stasis format version: 0 for legacy bundles, which record no package versions.
+    ...(details.kind === 'stasis' ? { stasisVersion: details.bundle.version } : {}) }
+}
+
+// `stale` marks an index this version did not write: its hashes still
+// answer report lookups, but an open rebuilds it for current sizes, line
+// counts and origin metadata.
+export function parseBundleMetadata(data, integrity) {
+  if (![1, 2, 3, 4, 5, INDEX_VERSION].includes(data?.version) || data.integrity !== integrity || !['stasis', 'sourcemap'].includes(data.kind)
+      || !Number.isSafeInteger(data.size) || data.size < 0 || !Array.isArray(data.files)) throw new Error('Invalid bundle metadata')
+  const stale = data.version !== INDEX_VERSION
+  const legacySizes = data.version === 1
+  const fileHashes = new Map(), fileSizes = new Map(), lineCounts = new Map()
+  for (const row of data.files) {
+    // Version 1 rows predate the line count, and gave every sized entry a hash.
+    if (!Array.isArray(row) || (row.length !== 4 && !(legacySizes && row.length === 3))) throw new Error('Invalid bundle metadata file')
+    const [path, size, hash, lines] = row
+    if (typeof path !== 'string' || fileSizes.has(path) || (size !== null && (!Number.isSafeInteger(size) || size < 0))
+        || (hash !== null && (typeof hash !== 'string' || !FILE_HASH.test(hash)))
+        || (size === null && hash !== null) || (legacySizes && size !== null && hash === null)
+        || (lines !== undefined && lines !== null && (!Number.isSafeInteger(lines) || lines < 0))) throw new Error('Invalid bundle metadata file')
+    fileSizes.set(path, size)
+    if (hash !== null) fileHashes.set(path, hash)
+    if (lines !== undefined && lines !== null) lineCounts.set(path, lines)
+  }
+  // Only a sizeless row can name a mounted file with no size, and only once.
+  const unsized = new Set(data.unsized ?? [])
+  if ((data.unsized !== undefined && (legacySizes || !Array.isArray(data.unsized) || unsized.size !== data.unsized.length))
+      || [...unsized].some((path) => typeof path !== 'string' || !fileSizes.has(path) || fileSizes.get(path) !== null)) throw new Error('Invalid bundle metadata')
+  const details = { integrity, kind: data.kind, size: data.size, metadataOnly: true, fileSizes, fileHashes, lineCounts, unsizedFiles: unsized, stale }
+  if (data.kind === 'stasis') {
+    details.bundle = Bundle.fromJSON(data.bundle)
+    const paths = details.bundle.sources
+    if (paths.size !== fileSizes.size || [...paths.keys()].some((path) => !fileSizes.has(path))) throw new Error('Invalid bundle metadata inventory')
+    // A file is hashed exactly when it is source: a resource has bytes and
+    // no hash. And only a base64 resource can be mounted without a size.
+    // Both are checked against the formats, which only the bundle carries.
+    const formats = details.bundle.formats
+    if (!legacySizes && [...fileSizes].some(([path, size]) => fileHashes.has(path) !== (size !== null && !Bundle.isResourceFormat(formats.get(path))))) {
+      throw new Error('Invalid bundle metadata inventory')
+    }
+    if ([...unsized].some((path) => formats.get(path) !== 'resource:base64')) throw new Error('Invalid bundle metadata inventory')
+  } else {
+    if (!data.json || typeof data.json !== 'object' || ![null, undefined].includes(data.namesCount) && (!Number.isSafeInteger(data.namesCount) || data.namesCount < 0)) throw new Error('Invalid sourcemap metadata')
+    if (!Array.isArray(data.json.sources) || data.json.sources.some((path) => !fileSizes.has(path))
+        || !Array.isArray(data.sourceSizes) || data.sourceSizes.length !== data.json.sources.length
+        || data.sourceSizes.some((size) => size !== null && (!Number.isSafeInteger(size) || size < 0))
+        || [...fileSizes].some(([path, size]) => fileHashes.has(path) !== (size !== null)) || unsized.size > 0) throw new Error('Invalid sourcemap inventory')
+    details.json = data.json
+    details.sourceSizes = data.sourceSizes
+    details.namesCount = data.namesCount
+    // An index before version 6 has none: the view reads no edges for it.
+    if (data.edges !== undefined) details.edges = parseSourcemapEdges(data.edges, data.files)
+  }
+  if (data.codeStats === undefined) details.codeStats = bundleCodeStats(lineCounts, fileSizes)
+  else {
+    const stats = data.codeStats
+    const validCount = value => Number.isSafeInteger(value) && value >= 0
+    if (!stats || ![stats.files, stats.lines, stats.bytes].every(validCount) || !Array.isArray(stats.languages)
+        || stats.languages.some(row => !row || typeof row.key !== 'string' || typeof row.label !== 'string'
+          || ![row.files, row.lines, row.bytes].every(validCount))) throw new Error('Invalid bundle code stats')
+    details.codeStats = stats
+  }
+  return details
+}
+
+function parseSourcemapEdges(rows, files) {
+  if (!Array.isArray(rows)) throw new Error('Invalid sourcemap edges')
+  return rows.map((row) => {
+    if (!Array.isArray(row) || ![2, 3].includes(row.length) || row[0] === row[1] || (row.length === 3 && typeof row[2] !== 'string')
+        || row.slice(0, 2).some((i) => !Number.isSafeInteger(i) || i < 0 || i >= files.length)) throw new Error('Invalid sourcemap edges')
+    return [files[row[0]][0], files[row[1]][0], ...row.slice(2)]
+  })
+}
+
+// HTTP content encoding handles compression before this shared JSON parser.
+export function parseBundleContents(text, { integrity, kind, size }) {
+  if (kind === 'stasis') return { integrity, kind, size, bundle: Bundle.parse(text) }
+  if (kind !== 'sourcemap') throw new Error('Unsupported bundle format')
+  return { integrity, kind, size, ...parseSourcemap(text) }
+}

package/common/bundle-pkg-of.d.ts

@@ -0,0 +1 @@
+export function bundlePkgOf(path: string, options?: { packageDir?: string | null | undefined }): string

package/common/bundle-pkg-of.js

@@ -0,0 +1,90 @@
+// Package classifier for bundle paths. Pulled out of
+// `render-bundle.js` (which drags in lit + the source-viewer + a
+// circular `render.js` import, none of which this pure string logic
+// needs) so it's a DOM-free leaf the bundle graph / treemap / compare
+// views — and the test suite — can import on its own, and the server pair a
+// comparison's files as Compare does (server-managed/rename-diff.ts).
+
+// Bucket a bundle source path into a "package":
+//   - files under `node_modules/<pkg>/...` return `<pkg>` (scoped names
+//     included), as do Solidity files under Soldeer's
+//     `dependencies/<pkg>/...`, the one ecosystem installing there;
+//   - own (first-party) source returns the single `__own__` bucket: an
+//     ordinary `dependencies/` folder of anything else is own code.
+//
+// pnpm wraps each install in
+// `node_modules/.pnpm/<name>@<version>/node_modules/<name>/...` —
+// matching the first occurrence would bucket every dep under `.pnpm`,
+// so when we hit that synthetic dir we walk past it to the inner
+// `node_modules/<pkg>` segment that names the actual package.
+//
+// `packageDir` is this path's authoritative stasis package directory
+// (from `bundlePackageDirs` in bundle-sources.js), when one is known.
+// It takes precedence over path heuristics: a module can contain its own
+// `dependencies/` directory without those files becoming new packages.
+// Recorded `node_modules/<pkg>` directories use the bare package name;
+// other named module directories stay separate under their full dir, and
+// `.` identifies own source. Only bundles without this metadata use
+// the path heuristic.
+//
+// The result is the package's identity — what files, sizes and edges are
+// grouped by — so a vendored package keeps its dir here: Cargo's
+// `vendor/log` is not npm's `log`, and one bundle can carry both. It is
+// `pkgLabel` that shows it by name.
+export function bundlePkgOf(path, { packageDir = null } = {}) {
+  if (packageDir) {
+    if (packageDir !== '.') {
+      const npm = packageDir.match(/(?:^|\/)node_modules\/(@[^/]+\/[^/]+|[^/]+)$/u)
+      return npm && npm[1] !== '.pnpm' ? npm[1] : packageDir
+    }
+  } else {
+    const re = /\.sol$/iu.test(path)
+      ? /(?:^|\/)(?:node_modules\/(@[^/]+\/[^/]+|[^/]+)|dependencies\/(@[^/]+\/[^/]+|[^/]+)\/)/gu
+      : /(?:^|\/)node_modules\/(@[^/]+\/[^/]+|[^/]+)/gu
+    let m
+    while ((m = re.exec(path)) !== null) {
+      const name = m[1] ?? m[2]
+      if (name !== '.pnpm') return name
+    }
+  }
+  return '__own__'
+}
+
+// First-party code: own source, and named workspace modules (a recorded
+// package dir outside `node_modules/`, `dependencies/` and `vendor/`).
+// Workspace modules stay separate packages in `bundlePkgOf`, but are
+// own code even when another workspace imports them.
+export function isOwnSourcePath(path, packageDir = null) {
+  return bundlePkgOf(path, { packageDir }) === '__own__'
+    || Boolean(packageDir) && !/(?:^|\/)(?:node_modules|dependencies|vendor)(?:\/|$)/u.test(packageDir)
+}
+
+// Search order for the bundle Code rail and Search tab: own code
+// first, then dependencies, each keeping the order `paths` came in.
+// Matches in the bundle's own code are usually what a search is after,
+// and package code shouldn't push them past the result caps.
+// `packageDirs` is `bundlePackageDirs` output, or null for the path
+// heuristic alone.
+export function ownSourceFirst(paths, packageDirs = null) {
+  const own = []
+  const deps = []
+  for (const path of paths) (isOwnSourcePath(path, packageDirs?.get(path)) ? own : deps).push(path)
+  return [...own, ...deps]
+}
+
+// Display label for a package bucket: `__own__` is the sentinel for
+// own-source (non-dependency) files, spelled out as "Own source" in
+// package lists and tooltips.
+//
+// A vendored package is shown by the path after the (last) `vendor/`,
+// which in each vendoring layout is what the package is called: `cargo
+// vendor` puts a crate at `vendor/<crate>`, Composer a package at
+// `vendor/<vendor>/<pkg>`, Go a module at `vendor/<module path>`. Only
+// the label is shortened; the bucket keeps the dir (see `bundlePkgOf`).
+// Anything but a package key (the graph asks with no package focused)
+// passes through as it came.
+export function pkgLabel(pkg) {
+  if (pkg === '__own__') return 'Own source'
+  if (typeof pkg !== 'string') return pkg
+  return pkg.match(/^(?:.*\/)?vendor\/(.+)$/u)?.[1] ?? pkg
+}

package/common/bundle-reasons.d.ts

@@ -0,0 +1,2 @@
+import type { BundleDetails } from './bundle-metadata.js'
+export function bundleReasons(details: BundleDetails, sourcePaths?: Iterable<string>): Map<string, Set<string>>

package/common/bundle-reasons.js

@@ -0,0 +1,21 @@
+import { bundleFileSizes } from './bundle-sources.js'
+
+// Reason metadata attributes files to consumers (run, build plugins, etc.).
+// It is informational and can be absent on older/single-consumer bundles.
+export function bundleReasons(details, sourcePaths) {
+  const reasons = new Map()
+  const raw = details?.kind === 'stasis' ? details.bundle?.reason : null
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return reasons
+  const paths = new Set(sourcePaths ?? [...bundleFileSizes(details)].filter(([, size]) => size != null).map(([path]) => path))
+  for (const [reason, files] of Object.entries(raw).toSorted(([a], [b]) => a.localeCompare(b))) {
+    if (!reason || !Array.isArray(files)) continue
+    const present = new Set(files.filter((file) => typeof file === 'string' && paths.has(file)))
+    if (present.size > 0) reasons.set(reason, present)
+  }
+  // A reason is only useful as a filter if it changes the set of files.
+  // Keep all named options when at least one differs, otherwise hide the
+  // selector (and discard any stale selection) in every visualization.
+  if (![...reasons.values()].some((files) => files.size < paths.size)) reasons.clear()
+  return reasons
+}
+

package/common/bundle-source-links.d.ts

@@ -0,0 +1,6 @@
+import type { BundleDetails } from './bundle-metadata.js'
+
+export function bundleSourceImports(details: BundleDetails, sources?: Map<string, string>): Map<string, Map<string, string | null>>
+export function bundleSourceLinkImports(details: BundleDetails, sources?: Map<string, string>): Map<string, Map<string, string | null>>
+export function sourceLinkResolver(sources: Map<string, string>, parent: string, imports?: Map<string, Map<string, string | null>> | null, packageFiles?: Map<string, unknown>, packageDirs?: Map<string, string> | null): (specifier: string) => string | null
+export function bundleSourceLinkResolver(details: BundleDetails, parent: string): (specifier: string) => string | null