@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.31

package/common/bundle-metadata.d.ts

@@ -0,0 +1,10 @@
+export const BUNDLE_METADATA_VERSION: number
+export interface BundleIdentity { integrity: string; kind: string | null; size: number }
+export interface BundleDetails extends BundleIdentity { bundle?: unknown; json?: unknown }
+export function parseBundleContents(text: string, identity: BundleIdentity): BundleDetails
+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 createBundleSummary(details: BundleDetails, metadata?: BundleMetadata): { files: number; codeFiles: number; lines: number; commit?: string }

package/common/bundle-metadata.js

@@ -0,0 +1,182 @@
+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'
+
+// 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.
+export const BUNDLE_METADATA_VERSION = 3
+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)
+}
+
+// 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 source lines without charging a trailing newline as an extra line.
+// 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' || content.length === 0) return 0
+  const breaks = content.match(/\r\n|\r|\n/gu)?.length ?? 0
+  return breaks + (/[\r\n]$/u.test(content) ? 0 : 1)
+}
+
+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 = details.lineCounts ??= new Map([...bundleSourcesAsMap(details)]
+    .map(([path, content]) => [path, bundleSourceLineCount(content)]))
+  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, sources = [], sourcesContent = [] } = details.json
+    result.json = { version, file, sourceRoot, sources }
+    // Sourcemaps can repeat a path with different/absent content. Keep the
+    // Overview's positional inventory, alongside the path-keyed graph index.
+    result.sourceSizes = sources.map((_, i) => typeof sourcesContent[i] === 'string' ? utf8ByteLength(sourcesContent[i]) : null)
+    result.namesCount = names?.length ?? null
+  } 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,
+          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 } : {}) }
+}
+
+// `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, 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' || !/^sha512-[A-Za-z0-9+/]{86}==$/u.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.parse(JSON.stringify(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
+  }
+  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
+}
+
+// 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')
+  const json = JSON.parse(text)
+  if (!Array.isArray(json?.sources) || json.sources.some(path => typeof path !== 'string')
+      || (json.sourcesContent !== undefined && (!Array.isArray(json.sourcesContent) || json.sourcesContent.some(content => content !== null && typeof content !== 'string')))) throw new Error('Invalid sourcemap')
+  return { integrity, kind, size, json }
+}

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,5 @@
+import type { BundleDetails } from './bundle-metadata.js'
+
+export function bundleSourceImports(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): (specifier: string) => string | null
+export function bundleSourceLinkResolver(details: BundleDetails, parent: string): (specifier: string) => string | null

package/common/bundle-source-links.js

@@ -0,0 +1,82 @@
+import { bundleSourcesAsMap } from './bundle-sources.js'
+
+const indexes = 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
+}
+
+// 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.
+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)
+        }
+      }
+    }
+  }
+  return imports
+}
+
+export function sourceLinkResolver(sources, parent, imports = null) {
+  let index = indexes.get(sources)
+  if (!index) { index = buildIndex(sources); indexes.set(sources, index) }
+  const recorded = imports?.get(parent)
+  const directory = parent.slice(0, parent.lastIndexOf('/') + 1)
+  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('./') && !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 bundleImports = new WeakMap()
+
+export function bundleSourceLinkResolver(details, parent) {
+  const sources = bundleSourcesAsMap(details)
+  let imports = bundleImports.get(sources)
+  if (!imports) { imports = bundleSourceImports(details, sources); bundleImports.set(sources, imports) }
+  return sourceLinkResolver(sources, parent, imports)
+}

package/common/bundle-sources.d.ts

@@ -0,0 +1,3 @@
+import type { BundleDetails } from './bundle-metadata.js'
+export function bundleSourcesAsMap(details: BundleDetails): Map<string, string>
+export function bundlePackageVersions(details: BundleDetails, paths?: Iterable<string> | null): Map<string, Set<string>>

package/common/bundle-sources.js

@@ -0,0 +1,284 @@
+// 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
+// split them across parallel `sources` / `sourcesContent` arrays on
+// the raw .map JSON. 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 { 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') {
+    if (!details.json) return result
+    const srcs = details.json.sources ?? []
+    const contents = details.json.sourcesContent ?? []
+    for (let i = 0; i < srcs.length; i++) {
+      if (typeof contents[i] === 'string') result.set(srcs[i], contents[i])
+    }
+  }
+  if (key) sourcesCache.set(key, result)
+  return result
+}
+
+// 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.
+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))
+  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)
+  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?.json?.sources
+  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
+    kinds.set(path, Bundle.isResourceFormat(formats?.get(path)) ? 'resource' : 'source')
+  }
+  kindsCache.set(sizes, kinds)
+  return kinds
+}
+
+// `bundleFileSizes` narrowed to source: a resource's size is nulled, as a
+// directory capture's already is. The import graph draws this, and stays
+// source-only: an image or a font imports nothing and carries no finding.
+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) result.set(path, Bundle.isResourceFormat(formats.get(path)) ? null : 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 buckets everything else by
+// top-level dir — collapsing sibling workspace packages under their
+// shared parent (`vendor/aws/aws-crt-php` + `vendor/aws/aws-sdk-php`
+// both fall under `vendor`). Feeding each path's dir 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.
+export function bundlePackageDirs(details) {
+  if (details?.kind !== 'stasis' || !details.bundle?.modules) return null
+  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)
+    }
+  }
+  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.
+export function bundlePackageVersions(details, paths = null) {
+  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
+    let set = versions.get(info.name)
+    if (!set) { set = new Set(); versions.set(info.name, set) }
+    set.add(info.version)
+  }
+  return versions
+}

package/common/bundle-stats.js

@@ -0,0 +1,41 @@
+import { langForPath } from './code-language.js'
+
+const BUNDLE_LANGUAGE_LABELS = Object.freeze({
+  javascript: 'JavaScript', jsx: 'JSX', typescript: 'TypeScript', tsx: 'TSX',
+  json: 'JSON', css: 'CSS', markup: 'HTML', yaml: 'YAML', bash: 'Shell',
+  markdown: 'Markdown', solidity: 'Solidity', php: 'PHP', rust: 'Rust',
+  ruby: 'Ruby', java: 'Java', cpp: 'C++', c: 'C', objectivec: 'Objective-C',
+  python: 'Python', go: 'Go', kotlin: 'Kotlin', swift: 'Swift', dart: 'Dart',
+  sql: 'SQL', lua: 'Lua', csharp: 'C#', scala: 'Scala', vue: 'Vue', svelte: 'Svelte',
+})
+const BUNDLE_EXTENSION_LANGUAGES = Object.freeze({
+  py: 'python', pyw: 'python', go: 'go', kt: 'kotlin', kts: 'kotlin', swift: 'swift',
+  dart: 'dart', sql: 'sql', lua: 'lua', cs: 'csharp', scala: 'scala', sc: 'scala',
+  vue: 'vue', svelte: 'svelte',
+})
+
+function bundleLanguageOf(path) {
+  const basename = typeof path === 'string' ? path.slice(path.lastIndexOf('/') + 1) : ''
+  const dot = basename.lastIndexOf('.')
+  const ext = dot > 0 ? basename.slice(dot + 1).trim().toLowerCase() : ''
+  const lang = langForPath(path) ?? BUNDLE_EXTENSION_LANGUAGES[ext]
+  if (lang) return { key: lang, label: BUNDLE_LANGUAGE_LABELS[lang] ?? lang }
+  return ext ? { key: `extension:${ext}`, label: `.${ext}` } : { key: 'other', label: 'Other' }
+}
+
+export function bundleCodeStats(lineCounts, fileSizes) {
+  const languages = new Map()
+  let bytes = 0, lines = 0
+  for (const [path, count] of lineCounts) {
+    const language = bundleLanguageOf(path)
+    const stat = languages.get(language.key) ?? { ...language, files: 0, lines: 0, bytes: 0 }
+    stat.files++
+    stat.lines += count
+    stat.bytes += fileSizes.get(path) ?? 0
+    languages.set(language.key, stat)
+    lines += count
+    bytes += fileSizes.get(path) ?? 0
+  }
+  return { files: lineCounts.size, lines, bytes, languages: [...languages.values()]
+    .toSorted((a, b) => b.lines - a.lines || a.label.localeCompare(b.label)) }
+}

package/common/bundle-tabs.js

@@ -0,0 +1 @@
+export const BUNDLE_TABS = new Set(['overview', 'graph', 'treemap', 'compare', 'advisories', 'issues', 'code', 'search', 'terminal'])