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

package/common/bundle-source-links.js

@@ -0,0 +1,216 @@
+import { bundleFilesAsMap, bundlePackageDirs, bundleSourcesAsMap } from './bundle-sources.js'
+import { bundleSourcemapSpecifiers } from './bundle-sourcemap.js'
+
+const indexes = new WeakMap()
+const manifests = new WeakMap()
+
+// Normalize only path segments. Keep sourcemap URL roots (webpack:/// etc.)
+// and leading ../ segments, and never guess extensions or basename matches.
+function normalizePath(path) {
+  const match = /^([a-z][a-z\d+.-]*:\/\/[^/]*)(.*)$/iu.exec(path)
+  const prefix = match?.[1] ?? ''
+  const rest = match?.[2] ?? path
+  const absolute = rest.startsWith('/')
+  const parts = []
+  for (const part of rest.split('/')) {
+    if (!part || part === '.') continue
+    if (part === '..' && parts.length > 0 && parts.at(-1) !== '..') parts.pop()
+    else if (part === '..' && absolute && parts.length === 0) return null
+    else parts.push(part)
+  }
+  return prefix + (absolute ? '/' : '') + parts.join('/')
+}
+
+function buildIndex(sources) {
+  const paths = new Map()
+  for (const path of sources.keys()) {
+    const normalized = normalizePath(path)
+    if (normalized === null) continue
+    // Distinct source keys with the same normalized path are ambiguous.
+    paths.set(normalized, paths.has(normalized) ? null : path)
+  }
+  return paths
+}
+
+function packageScope(sources, index, parent, packageDir) {
+  const normalized = normalizePath(parent)
+  if (normalized === null) return null
+  const boundary = typeof packageDir === 'string' ? normalizePath(`${packageDir}/package.json`) : null
+  let directory = normalized.slice(0, normalized.lastIndexOf('/') + 1)
+  let cache = manifests.get(sources)
+  if (!cache) { cache = new Map(); manifests.set(sources, cache) }
+  for (;;) {
+    // A dependency without a captured manifest cannot inherit the app's imports.
+    if (directory.endsWith('node_modules/')) return null
+    const path = `${directory}package.json`
+    if (index.has(path)) {
+      if (!cache.has(path)) {
+        const content = sources.get(index.get(path))
+        let imports = null
+        try { imports = typeof content === 'string' ? JSON.parse(content.replace(/^\uFEFF/u, ''))?.imports ?? null : null } catch {}
+        cache.set(path, imports && typeof imports === 'object' && !Array.isArray(imports) ? imports : null)
+      }
+      // The nearest package defines the scope, including absent/invalid imports.
+      return { directory, imports: cache.get(path) }
+    }
+    // Recorded module roots are package boundaries even without a manifest.
+    if (path === boundary) return null
+    if (!directory || directory === '/' || directory.endsWith('../') || /^[a-z][a-z\d+.-]*:\/\/[^/]*\/?$/iu.test(directory)) return null
+    const trimmed = directory.slice(0, -1)
+    directory = trimmed.slice(0, trimmed.lastIndexOf('/') + 1)
+  }
+}
+
+function importMapping(imports, specifier) {
+  if (!imports) return null
+  if (Object.hasOwn(imports, specifier) && !specifier.includes('*')) return { value: imports[specifier], wildcard: null }
+  let best = null
+  for (const pattern of Object.keys(imports)) {
+    const star = pattern.indexOf('*')
+    if (!pattern.startsWith('#') || star === -1 || pattern.indexOf('*', star + 1) !== -1) continue
+    const prefix = pattern.slice(0, star), suffix = pattern.slice(star + 1)
+    if (specifier.length <= prefix.length + suffix.length || !specifier.startsWith(prefix) || !specifier.endsWith(suffix)) continue
+    // Node's pattern precedence: longest prefix, then longest complete key.
+    if (!best || star > best.star || star === best.star && pattern.length > best.pattern.length) best = { pattern, star, suffix }
+  }
+  return best ? { value: imports[best.pattern], wildcard: specifier.slice(best.star, specifier.length - best.suffix.length) } : null
+}
+
+function importTargets(value, wildcard, depth = 0) {
+  if (depth > 16) return [null]
+  if (typeof value === 'string') return [wildcard === null ? value : value.replaceAll('*', wildcard)]
+  // The viewer combines recorded conditions. Conditional/array mappings link
+  // only when every possible target agrees; a blocked branch stays blocked.
+  if (value && typeof value === 'object') return Object.values(value).flatMap(target => importTargets(target, wildcard, depth + 1))
+  return [null]
+}
+
+function mappedSource(target, scope, sources, index, recorded, directory) {
+  if (typeof target !== 'string' || /[\\\p{Cc}]/u.test(target) || /%2f|%5c/iu.test(target)) return null
+  const relative = target.startsWith('./')
+  let file = null
+  if (relative) {
+    let decoded
+    try { decoded = decodeURIComponent(target.slice(2)) } catch { return null }
+    if (/[\\\p{Cc}]/u.test(decoded) || decoded.split('/').some(part => ['.', '..', 'node_modules'].includes(part.toLowerCase()))) return null
+    file = normalizePath(scope.directory + decoded)
+  } else if (target.startsWith('../') || target.startsWith('/') || target.startsWith('#') || target.includes(':')) return null
+  const keys = new Set([target])
+  // Captures may retain the package-relative rewritten spelling or express
+  // that same path relative to a nested importing file.
+  if (relative) {
+    for (const key of recorded?.keys() ?? []) {
+      if ((key.startsWith('./') || key.startsWith('../')) && normalizePath(directory + key) === file) keys.add(key)
+    }
+  }
+  let found = false, resolved = null
+  for (const key of keys) {
+    if (!recorded?.has(key)) continue
+    const current = recorded.get(key)
+    if (typeof current !== 'string' || !sources.has(current) || found && current !== resolved) return null
+    found = true
+    resolved = current
+  }
+  // Exact captured files are useful too, but never guess an extension/index.
+  return found ? resolved : relative ? index.get(file) ?? null : null
+}
+
+function resolvePackageImport(scope, specifier, sources, index, recorded, directory) {
+  const mapping = importMapping(scope?.imports, specifier)
+  if (!mapping) return null
+  const targets = importTargets(mapping.value, mapping.wildcard)
+  let result = null
+  for (const target of targets) {
+    const resolved = mappedSource(target, scope, sources, index, recorded, directory)
+    if (!resolved || result && resolved !== result) return null
+    result = resolved
+  }
+  return result
+}
+
+// Merge conditions before linking. When exporting a restricted source set,
+// include only visible parents and replace every unavailable target with null:
+// its path must not leak, and relative fallback must still remain blocked.
+// A sourcemap's are what its edges say each specifier names (bundle-sourcemap.js).
+export function bundleSourceImports(details, sources = bundleSourcesAsMap(details)) {
+  const imports = new Map()
+  if (details?.kind === 'stasis') {
+    for (const byParent of details.bundle?.imports?.values() ?? []) {
+      for (const [parent, specifiers] of byParent) {
+        if (!sources.has(parent)) continue
+        if (!imports.has(parent)) imports.set(parent, new Map())
+        const merged = imports.get(parent)
+        for (const [specifier, target] of specifiers) {
+          const resolved = typeof target === 'string' && sources.has(target) ? target : null
+          // A platform object, missing file, or disagreement under any
+          // condition permanently blocks this specifier, including fallback.
+          merged.set(specifier, merged.has(specifier) && merged.get(specifier) !== resolved ? null : resolved)
+        }
+      }
+    }
+  } else if (details?.kind === 'sourcemap') {
+    for (const [parent, specifiers] of bundleSourcemapSpecifiers(details)) {
+      if (!sources.has(parent)) continue
+      imports.set(parent, new Map([...specifiers].map(([specifier, target]) => [specifier, sources.has(target) ? target : null])))
+    }
+  }
+  return imports
+}
+
+// Managed previews receive only report-selected bodies, often without the
+// owning manifest. Resolve their quoted # aliases using the full manifest
+// inventory, but export only visible targets (or null), never manifest data.
+// These are candidate strings; Prism still decides which tokens become links.
+export function bundleSourceLinkImports(details, sources = bundleSourcesAsMap(details)) {
+  const imports = bundleSourceImports(details, sources)
+  if (details?.kind !== 'stasis') return imports
+  const packageDirs = bundlePackageDirs(details), packageFiles = bundleFilesAsMap(details)
+  for (const [parent, content] of sources) {
+    const resolve = sourceLinkResolver(sources, parent, imports, packageFiles, packageDirs)
+    let targets = imports.get(parent)
+    // Look ahead so a template containing a quoted alias cannot hide that
+    // inner candidate. Escaped/multiline strings are not portable paths.
+    for (const [, , specifier] of content.matchAll(/(?=(["'`])(#[^\\\r\n]*?)\1)/gu)) {
+      if (targets?.has(specifier)) continue
+      const target = resolve(specifier)
+      if (!targets) { targets = new Map(); imports.set(parent, targets) }
+      targets.set(specifier, target)
+    }
+  }
+  return imports
+}
+
+export function sourceLinkResolver(sources, parent, imports = null, packageFiles = sources, packageDirs = null) {
+  let index = indexes.get(sources)
+  if (!index) { index = buildIndex(sources); indexes.set(sources, index) }
+  let packageIndex = indexes.get(packageFiles)
+  if (!packageIndex) { packageIndex = buildIndex(packageFiles); indexes.set(packageFiles, packageIndex) }
+  const recorded = imports?.get(parent)
+  const directory = parent.slice(0, parent.lastIndexOf('/') + 1)
+  const scope = imports ? packageScope(packageFiles, packageIndex, parent, packageDirs?.get(parent)) : null
+  return (specifier) => {
+    if (typeof specifier !== 'string' || /\p{Cc}/u.test(specifier)) return null
+    if (recorded?.has(specifier)) {
+      const target = recorded.get(specifier)
+      return typeof target === 'string' && sources.has(target) ? target : null
+    }
+    if (specifier.startsWith('#')) return resolvePackageImport(scope, specifier, sources, index, recorded, directory)
+    if (!specifier.startsWith('./') && !specifier.startsWith('../')) return null
+    const name = specifier.slice(specifier.lastIndexOf('/') + 1)
+    const dot = name.lastIndexOf('.')
+    if (dot <= 0 || dot === name.length - 1) return null
+    return index.get(normalizePath(directory + specifier)) ?? null
+  }
+}
+
+const bundleLinks = new WeakMap()
+
+export function bundleSourceLinkResolver(details, parent) {
+  const sources = bundleSourcesAsMap(details)
+  let links = bundleLinks.get(sources)
+  if (!links) {
+    links = { imports: bundleSourceImports(details, sources), packageDirs: bundlePackageDirs(details) }
+    bundleLinks.set(sources, links)
+  }
+  return sourceLinkResolver(sources, parent, links.imports, bundleFilesAsMap(details), links.packageDirs)
+}

package/common/bundle-sourcemap.d.ts

@@ -0,0 +1,10 @@
+import type { SourceMap } from '@preventive/sourcemap'
+import type { Edge } from '@preventive/sourcemap/edges.js'
+import type { BundleDetails } from './bundle-metadata.js'
+export function parseSourcemap(text: string): { json: { version: unknown; file: unknown; sourceRoot: unknown }; map: SourceMap; namesCount: number | null }
+export function sourcemapEntries(details: BundleDetails): [string, string | null][]
+export type SourcemapEdge = [from: string, to: string] | [from: string, to: string, specifier: string]
+export function sourcemapEdges(map: SourceMap, read: (map: SourceMap) => { edges: Edge[] }): SourcemapEdge[]
+export function bundleSourcemapEdges(details: BundleDetails): readonly SourcemapEdge[]
+export function bundleSourcemapImports(details: BundleDetails): Map<string, Set<string>>
+export function bundleSourcemapSpecifiers(details: BundleDetails): Map<string, Map<string, string>>

package/common/bundle-sourcemap.js

@@ -0,0 +1,100 @@
+// A sourcemap bundle as @preventive/sourcemap reads it: plain or indexed,
+// each file once, with the edges between its files, which the graph draws
+// and Code links follow by the specifier of each import. A file keeps the key
+// it had before the package read it, the spelling the map lists it under
+// (`sourceRoot` in front), so Code links, hashes and reports that name one
+// still find it.
+//
+// Edges take a parser for most maps. The client goes without one: it reads
+// them with edges-lite.js, which knows Metro's maps alone. The server reads
+// every map's with oxc-parser (server-managed/bundle-cache.ts) and keeps
+// them in the bundle's metadata, which a client takes over its own.
+import { readSourceMap } from '@preventive/sourcemap'
+import { bundleEdges as metroEdges } from '@preventive/sourcemap/edges-lite.js'
+
+// The map as read, and what the Overview shows of the JSON: its header,
+// and how many names it maps. The JSON itself is not kept, its mappings
+// read and its sources the map's files.
+export function parseSourcemap(text) {
+  // The `)]}'` line that guards a map against being run, which readSourceMap
+  // skips in text it parses itself.
+  const json = JSON.parse(text.replace(/^\)\]\}'[^\n]*\n/u, ''))
+  const map = readSourceMap(json)
+  const namesCount = json.sections
+    ? json.sections.reduce((count, section) => count + (section.map.names?.length ?? 0), 0)
+    : json.names?.length ?? null
+  return { json: { version: json.version, file: json.file, sourceRoot: json.sourceRoot }, map, namesCount }
+}
+
+// The map's files as `[key, content or null]`, in its order. Details with
+// no map read (the npm viewer's, a map's arrays as written) list what their
+// `sources` does, a repeated path repeated.
+export function sourcemapEntries(details) {
+  if (details.map) return details.map.files.flatMap((file) => file.source === null ? [] : [[file.source, file.content]])
+  const contents = details.json?.sourcesContent ?? []
+  return (details.json?.sources ?? []).map((path, i) => [path, contents[i] ?? null])
+}
+
+// `read`'s edges between files of the map, as rows by key: `[from, to]`,
+// and `[from, to, specifier]` for an import its specifier names. An edge to
+// no file of it (a package left out, a builtin) leads nowhere here, and one
+// to its own file is none, which metadata refuses to hold.
+export function sourcemapEdges(map, read) {
+  const rows = new Map()
+  for (const { from, to, specifier } of read(map).edges) {
+    if (from.source === null || to?.source == null || to.source === from.source) continue
+    const row = typeof specifier === 'string' ? [from.source, to.source, specifier] : [from.source, to.source]
+    rows.set(row.join('\0'), row)
+  }
+  return [...rows.values()]
+}
+
+// edges-lite.js throws for a map that is not Metro's, or one with no
+// sourcesContent to read: one with no edges the client can tell.
+function liteEdges(map) {
+  try { return metroEdges(map) } catch { return { edges: [] } }
+}
+
+const NO_EDGES = Object.freeze([])
+
+// The edges a view reads: those the metadata carries, else what the client
+// reads of its own map. None without a map.
+export function bundleSourcemapEdges(details) {
+  if (details?.edges) return details.edges
+  if (!details?.map) return NO_EDGES
+  details.edges = sourcemapEdges(details.map, liteEdges)
+  return details.edges
+}
+
+const importsCache = new WeakMap()
+const specifiersCache = new WeakMap()
+
+// The graph's: `Map<from, Set<to>>`.
+export function bundleSourcemapImports(details) {
+  const rows = bundleSourcemapEdges(details)
+  if (!importsCache.has(rows)) {
+    const imports = new Map()
+    for (const [from, to] of rows) {
+      if (!imports.has(from)) imports.set(from, new Set())
+      imports.get(from).add(to)
+    }
+    importsCache.set(rows, imports)
+  }
+  return importsCache.get(rows)
+}
+
+// Code links': the file each import's specifier names, `Map<from,
+// Map<specifier, to>>`.
+export function bundleSourcemapSpecifiers(details) {
+  const rows = bundleSourcemapEdges(details)
+  if (!specifiersCache.has(rows)) {
+    const specifiers = new Map()
+    for (const [from, to, specifier] of rows) {
+      if (specifier === undefined) continue
+      if (!specifiers.has(from)) specifiers.set(from, new Map())
+      specifiers.get(from).set(specifier, to)
+    }
+    specifiersCache.set(rows, specifiers)
+  }
+  return specifiersCache.get(rows)
+}

package/common/bundle-sources.d.ts

@@ -0,0 +1,7 @@
+import type { BundleDetails } from './bundle-metadata.js'
+export function bundleSourcesAsMap(details: BundleDetails): Map<string, string>
+export function bundleSourceLines(content: string): number
+export function bundleSourceOrder(sources: Map<string, string>): { paths: string[]; numbers: Map<string, number> }
+export function bundleFilesAsMap(details: BundleDetails): Map<string, string | { format: 'base64'; data: string }>
+export function bundlePackageDirs(details: BundleDetails): Map<string, string> | null
+export function bundlePackageVersions(details: BundleDetails, paths?: Iterable<string> | null, keyOf?: (dir: string, info: { name: string; version: string }) => string): Map<string, Set<string>>

package/common/bundle-sources.js

@@ -0,0 +1,333 @@
+// Shared helper: given a parsed bundle `details`, return a
+// Map<file, content-string> of its source files. Stasis bundles
+// expose sources via `@exodus/stasis-core`'s `Bundle.sources` getter
+// (flat Map<projectRelPath, content> from `.modules`); sourcemaps list
+// their files as bundle-sourcemap.js reads them. Sourcemap sources whose
+// `sourcesContent[i]` was omitted are skipped.
+//
+// What a stasis bundle records is not all source: `Bundle.formats`
+// marks each entry, and three of those formats are files only in the
+// sense that they occupy a path. `Bundle.sources` hands back the raw
+// stored content for every one of them, so the format is what has to
+// be asked — the content's JS type cannot tell them apart:
+//
+//   directory        a readdir capture, content `["a.js","b.js"]`
+//   resource:base64  an image or font, content its base64 text
+//   resource         raw bytes, the one case not a string already
+//
+// A directory capture is the one that does real damage, because it
+// claims a path a directory also occupies: hand it to the terminal
+// and `ls` lists the name twice and stops listing what is under it.
+// The base64 resources are quieter but equally wrong — a PNG read as
+// a wall of text, counted toward the language shares that
+// render-bundle.js says resources are kept out of.
+//
+// Own module so `render-bundle.js` (Code tab, finding tree, graph
+// data) and `terminal-attach.js` (in-shell FS) read one definition —
+// a new bundle kind or field handled here is visible to both.
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { sourcemapEntries } from './bundle-sourcemap.js'
+import { utf8ByteLength } from './utf8.js'
+
+const sourcesCache = new WeakMap()
+const filesCache = new WeakMap()
+const sizesCache = new WeakMap()
+const sourceSizesCache = new WeakMap()
+const kindsCache = new WeakMap()
+const unsizedCache = new WeakMap()
+
+export function bundleSourcesAsMap(details) {
+  if (details?.metadataOnly) return new Map()
+  const key = details?.bundle ?? details?.json
+  if (key && sourcesCache.has(key)) return sourcesCache.get(key)
+  const result = new Map()
+  if (!details) return result
+  if (details.kind === 'stasis') {
+    if (!details.bundle) return result
+    const formats = details.bundle.formats
+    for (const [file, content] of details.bundle.sources) {
+      if (typeof content !== 'string') continue
+      // `isResourceFormat` is the package's own list, so a format it
+      // adds later is excluded here without this needing to know. A v0
+      // bundle records no formats at all: `get` returns undefined,
+      // which is not a resource format, and every entry is kept as
+      // before.
+      if (Bundle.isResourceFormat(formats?.get(file))) continue
+      result.set(file, content)
+    }
+  } else if (details.kind === 'sourcemap') {
+    for (const [path, content] of sourcemapEntries(details)) {
+      if (typeof content === 'string') result.set(path, content)
+    }
+  }
+  if (key) sourcesCache.set(key, result)
+  return result
+}
+
+// A source's lines as the viewer numbers them: one more than its newlines.
+export function bundleSourceLines(content) {
+  let lines = 1
+  for (let at = content.indexOf('\n'); at !== -1; at = content.indexOf('\n', at + 1)) lines++
+  return lines
+}
+
+// A bundle's sources in path order, and each one's number in it from 1: how a
+// managed Code link names a file. The content hash that names a bundle fixes
+// its sources, so the numbers stay put.
+const sourceOrders = new WeakMap()
+export function bundleSourceOrder(sources) {
+  let order = sourceOrders.get(sources)
+  if (!order) {
+    const paths = [...sources.keys()].toSorted()
+    order = { paths, numbers: new Map(paths.map((path, index) => [path, index + 1])) }
+    sourceOrders.set(sources, order)
+  }
+  return order
+}
+
+// Every file the bundle carries, for a reader that wants the filesystem
+// rather than the source: what `bundleSourcesAsMap` returns, plus the
+// resources it leaves out, each in the form that is true to it.
+//
+// The two resource formats are not two encodings of the same thing.
+// Stasis picks between them by whether the bytes are valid UTF-8:
+// `resource` is that text, stored verbatim, so it stays a string and a
+// reader sees the SVG or the licence file it is. `resource:base64` is
+// the other case — bytes no string spells — and it is handed over
+// still spelt that way, as `{ format: 'base64', data }`. The terminal
+// takes that form since 2.0 and decodes it the first time the file is
+// read, so a bundle carrying a hundred images costs a hundred strings
+// rather than a hundred decoded buffers, and pays for the one that is
+// opened. Either way it knows what it is holding: `ls -l` and `wc -c`
+// report the real byte count rather than the length of the base64, and
+// `cat` declines instead of printing mojibake.
+//
+// Decoding there also puts the diagnostic where the file is named: a
+// spelling that does not decode is reported by the command that read
+// it, under the detail `base64 source`. Decoding here could only drop
+// the file and say nothing.
+//
+// Directory captures stay out. They are the one entry that is not a
+// file in any encoding, and mounting one puts a second `lib` beside
+// the directory it names.
+// Files as the managed server reads a tarball's (server-managed/npm-packages.ts
+// npmFileRows), `[path, bytes, text]` or `[path, bytes, null, digest]`, as
+// details of `entry` in the shape of a sourcemap carrying its sources: one
+// source per file, text inline, and every file's size from its bytes, so a
+// file that is not text still lists with its size. Those carry a digest of
+// their bytes instead (`npmBinaries`), which Compare compares them by. An npm
+// version's files come so (view/npm-package.js), and a repository
+// directory's (view/repository-code.js).
+export function fileRowDetails(entry, rows) {
+  const files = Array.isArray(rows) ? rows : []
+  return {
+    integrity: entry.integrity, kind: 'sourcemap', size: entry.size,
+    json: { version: 3, sources: files.map(([path]) => path), sourcesContent: files.map(([, , text]) => typeof text === 'string' ? text : null) },
+    fileSizes: new Map(files.map(([path, size]) => [path, size])),
+    npmBinaries: new Map(files.filter(([, , text, digest]) => typeof text !== 'string' && typeof digest === 'string')
+      .map(([path, size, , digest]) => [path, { size, digest }])),
+  }
+}
+
+export function bundleFilesAsMap(details) {
+  const key = details?.bundle ?? details?.json
+  if (key && filesCache.has(key)) return filesCache.get(key)
+  const files = new Map(bundleSourcesAsMap(details))
+  // An npm package's files that are not text (fileRowDetails) carry
+  // their size and digest alone: enough for Compare to tell a changed one
+  // from an unchanged one, as `{ format: 'digest', size, digest }`.
+  for (const [path, file] of details?.npmBinaries ?? []) files.set(path, { format: 'digest', ...file })
+  if (details?.kind === 'stasis' && details.bundle) {
+    const formats = details.bundle.formats
+    for (const [file, content] of details.bundle.sources) {
+      if (typeof content !== 'string') continue
+      const format = formats?.get(file)
+      if (format === 'resource') files.set(file, content)
+      else if (format === 'resource:base64') files.set(file, { format: 'base64', data: content })
+    }
+  }
+  if (key) filesCache.set(key, files)
+  return files
+}
+
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+// The length of the bytes a base64 spelling decodes to — three for every
+// four characters, less what the padding stands for — or null when it
+// decodes to none. The terminal decodes strictly (`@exodus/bytes`): RFC
+// 4648's alphabet, no whitespace, padding present or left off but never
+// wrong, and no stray bits in the last character. A spelling it refuses is
+// a file `wc -c` cannot read, so it gets no size here rather than an
+// invented one. Checked without decoding: a bundle's images are not worth
+// a buffer each just to be weighed.
+function base64ByteLength(text) {
+  const padded = text.endsWith('=')
+  if (padded ? text.length % 4 !== 0 || text.at(-3) === '=' : text.length % 4 === 1) return null
+  const data = padded ? text.slice(0, text.endsWith('==') ? -2 : -1) : text
+  if (/[^A-Za-z0-9+/]/u.test(data)) return null
+  // A trailing group of 2 or 3 characters spells 1 or 2 bytes; the bits of
+  // its last character past those bytes must be zero.
+  const tail = data.length % 4
+  if (tail > 1 && BASE64_ALPHABET.indexOf(data.at(-1)) & (tail === 2 ? 0x0f : 0x03)) return null
+  return Math.floor(data.length * 3 / 4)
+}
+
+// The byte size of one entry of `bundleFilesAsMap`, as `wc -c` reports it
+// in the terminal: text weighs the UTF-8 it encodes to, and a base64
+// declaration the bytes it decodes to — null when it decodes to none.
+// Anything else is no file, and null too. The Compare tab sizes both
+// bundles' files by this, so its totals are the Overview's.
+export function bundleFileByteLength(content) {
+  if (typeof content === 'string') return utf8ByteLength(content)
+  if (content?.format === 'digest') return content.size
+  return content?.format === 'base64' ? base64ByteLength(content.data) : null
+}
+
+// Every path the bundle records, keyed to the byte size of the file it
+// holds — the size `wc -c` reports for it in the terminal, which is to
+// say the size of the entry in `bundleFilesAsMap`: a source or `resource`
+// weighs the UTF-8 its text encodes to, a `resource:base64` the bytes its
+// base64 decodes to. Null is a path with no size to give: a directory
+// capture, which is no file; a sourcemap source whose body was left out;
+// or a `resource:base64` whose spelling does not decode.
+//
+// The Overview and the Treemap weigh a bundle by this, so what they show
+// adds up to what `du` does. Neither the source-only view nor the base64
+// text will do: the first drops every image and font, the second
+// inflates them by a third.
+//
+// Metadata views need byte sizes and paths, never the bodies. The
+// persistent index supplies this map directly; full parses compute it once.
+export function bundleFileSizes(details) {
+  if (details?.fileSizes) return details.fileSizes
+  const key = details?.bundle ?? details?.json
+  if (key && sizesCache.has(key)) return sizesCache.get(key)
+  const sizes = new Map()
+  const files = bundleFilesAsMap(details)
+  const paths = details?.kind === 'stasis' ? details.bundle?.sources.keys() : details && sourcemapEntries(details).map(([path]) => path)
+  for (const path of paths ?? []) sizes.set(path, bundleFileByteLength(files.get(path)))
+  if (key) sizesCache.set(key, sizes)
+  return sizes
+}
+
+// The files the terminal mounts that have no size: a `resource:base64`
+// whose spelling does not decode. The terminal lists such a file, and says
+// why it cannot read it when asked, so the views list it too — but a null
+// size alone cannot tell it from an entry that is no file at all, so it is
+// named here. A metadata-only open reads the set from the index, which is
+// the one thing a size and a format cannot say about a path.
+export function bundleUnsizedFiles(details) {
+  if (details?.metadataOnly) return details.unsizedFiles ?? new Set()
+  const sizes = bundleFileSizes(details)
+  if (unsizedCache.has(sizes)) return unsizedCache.get(sizes)
+  const unsized = new Set()
+  for (const path of bundleFilesAsMap(details).keys()) if (sizes.get(path) === null) unsized.add(path)
+  unsizedCache.set(sizes, unsized)
+  return unsized
+}
+
+// What each file the terminal mounts is, for a view that lists files:
+// 'source', or 'resource' for an image, font or other asset — a file, sized
+// like any other, but none the source viewer can show. Its keys are
+// `bundleFilesAsMap`'s, and nothing else: a directory capture, or an entry
+// with no body to mount (a sourcemap source whose `sourcesContent` was left
+// out, a body that is no string), is no file and is absent. It reads sizes
+// and formats, not bodies, so it answers for a metadata-only open as it
+// does for a parsed one: a sized path is a mounted file, and so is one
+// `bundleUnsizedFiles` names.
+export function bundleFileKinds(details) {
+  const sizes = bundleFileSizes(details)
+  if (kindsCache.has(sizes)) return kindsCache.get(sizes)
+  const unsized = bundleUnsizedFiles(details)
+  const formats = details?.kind === 'stasis' ? details.bundle?.formats : null
+  const kinds = new Map()
+  for (const [path, size] of sizes) {
+    if (size === null && !unsized.has(path)) continue
+    // An npm package's file that is not text is a resource too: no source to view.
+    kinds.set(path, Bundle.isResourceFormat(formats?.get(path)) || details?.npmBinaries?.has(path) ? 'resource' : 'source')
+  }
+  kindsCache.set(sizes, kinds)
+  return kinds
+}
+
+// Source paths and their recorded byte sizes. Keep null for a source whose
+// body is missing, but omit resources and directory captures entirely so
+// graph consumers can distinguish unknown source bytes from non-source.
+export function bundleSourceSizes(details) {
+  const sizes = bundleFileSizes(details)
+  const formats = details?.kind === 'stasis' ? details.bundle?.formats : null
+  if (!formats || formats.size === 0) return sizes
+  if (sourceSizesCache.has(sizes)) return sourceSizesCache.get(sizes)
+  const result = new Map()
+  for (const [path, size] of sizes) if (!Bundle.isResourceFormat(formats.get(path))) result.set(path, size)
+  sourceSizesCache.set(sizes, result)
+  return result
+}
+
+// Map each stasis bundle source path to the package directory that
+// owns it. A stasis `Bundle` already records authoritative package
+// boundaries in `.modules` (a `Map<dir, { name, version, files }>`
+// covering both `node_modules` deps and workspace packages — the
+// PHP `vendor/<vendor>/<pkg>` case, monorepo workspaces, etc.); this
+// mirrors the `Bundle.sources` getter's path construction (`dir/rel`,
+// or just `rel` for the `.` root) so the returned keys line up exactly
+// with `bundleSourcesAsMap`'s.
+//
+// The package views (overview, treemap, graph) otherwise classify
+// paths with `bundlePkgOf`'s string heuristic, which only knows
+// `node_modules/`/`dependencies/` and treats everything else as own
+// source. Feeding each path's recorded module directory into
+// `bundlePkgOf` (`packageDir` option) keeps those packages separate.
+//
+// Returns null for sourcemap bundles (and anything without parsed
+// modules) — they carry no package metadata, so callers fall back to
+// the path heuristic alone. Kept by the bundle, as its sources are:
+// callers only read it.
+const packageDirsCache = new WeakMap()
+export function bundlePackageDirs(details) {
+  if (details?.kind !== 'stasis' || !details.bundle?.modules) return null
+  if (packageDirsCache.has(details.bundle)) return packageDirsCache.get(details.bundle)
+  const map = new Map()
+  for (const [dir, info] of details.bundle.modules) {
+    for (const rel of Object.keys(info.files)) {
+      map.set(dir === '.' ? rel : `${dir}/${rel}`, dir)
+    }
+  }
+  packageDirsCache.set(details.bundle, map)
+  return map
+}
+
+// Map each named npm dependency a (stasis) bundle carries to the set of
+// concrete versions present for it: `Map<name, Set<version>>`. Only
+// `node_modules/...` modules that carry both a name and a non-empty
+// version string count — stasis v1 `scope: 'full'` bundles merge
+// workspace / own-source entries into the same `Bundle.modules` Map
+// (often `version: '0.0.0'` or null), and those aren't upstream
+// dependencies, so they're filtered out by the directory key. A package
+// can map to more than one version (pnpm keeps duplicate majors side by
+// side), hence the Set.
+//
+// Shared by the Advisories tab (a bulk registry lookup keyed on these
+// pairs) and the Compare slide (the dependency version-update diff).
+// Returns an empty Map for sourcemaps and v0 stasis bundles — neither
+// carries per-module version metadata. `keyOf(dir, info)` names each
+// entry, the recorded name by default; Compare keys by install directory,
+// as its sizes are, so an npm alias (`node_modules/alias` recording
+// `actual-package`) joins its own sizes.
+export function bundlePackageVersions(details, paths = null, keyOf = (_dir, info) => info.name) {
+  const versions = new Map()
+  if (details?.kind !== 'stasis' || !details.bundle?.modules) return versions
+  const packageDirs = paths === null ? null : bundlePackageDirs(details)
+  const selectedDirs = paths === null ? null : new Set([...paths].map(path => packageDirs?.get(path)))
+  for (const [dir, info] of details.bundle.modules) {
+    if (selectedDirs && !selectedDirs.has(dir)) continue
+    if (!dir.includes('node_modules')) continue
+    if (!info?.name || typeof info.version !== 'string' || !info.version) continue
+    const key = keyOf(dir, info)
+    let set = versions.get(key)
+    if (!set) { set = new Set(); versions.set(key, set) }
+    set.add(info.version)
+  }
+  return versions
+}