@preventive/triage 1.0.0-alpha.2 → 1.0.0-alpha.21

package/api/reap.ts

@@ -0,0 +1,17 @@
+// E2e-only Vercel deployment: no persistent relay is running in this function.
+// The managed deployment routes /api/reap through its top-level app instead.
+import { createReapHandler } from '../server-common/reap.ts'
+import { databaseUrls } from '../server-common/database-config.ts'
+import { reapOrphans } from '../server-e2e/objstore/reaper.ts'
+import { openNeonObjstore } from '../server-e2e/objstore/store-neon.ts'
+import { openVercelBlobBackend } from '../server-e2e/objstore/blob-vercel.ts'
+
+const handler = createReapHandler({ e2e: async () => {
+  const url = databaseUrls().e2e
+  const token = process.env['BLOB_READ_WRITE_TOKEN']
+  if (!url || !token) throw new Error('E2e cron requires DATABASE_URL or E2E_DATABASE_URL, plus BLOB_READ_WRITE_TOKEN')
+  const blob = await openVercelBlobBackend({ token })
+  // Stateless Neon HTTP handle: nothing to close, no relay listener or timer.
+  await reapOrphans(await openNeonObjstore(url, blob))
+} })
+export default handler

package/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import './strip-types-loader.js'
+
+// Load TypeScript only after the stripping hook is registered.
+const { start } = await import('./server.ts')
+await start()

package/client/finding-link.js

@@ -0,0 +1,305 @@
+// Deep links to a single finding — pure logic side. Encodes the
+// finding's id plus a "where does it live" hint into the URL hash
+// (`#finding=<id>&v=<hints>`) and parses the same back on the receiving
+// side, so "look at THIS issue" is a link you can paste into a chat
+// instead of a screenshot plus directions.
+//
+// Sibling of `workspace-share-link.js`, and deliberately unlike it in
+// one respect: the id here is NOT a secret. A share link carries the
+// workspace's private key and is therefore encrypted; a finding id is
+// meaningless without the report the recipient must already have, so it
+// rides in the clear and the link stays legible in a chat client.
+//
+// The two LOCATION hints are a different matter. A report filename
+// ("acme-corp-pentest-2024.json") and a workspace id are the sender's
+// own metadata, and a URL is the most-forwarded, most-logged, most-
+// screenshotted string there is — so they ship as 3-byte digests
+// (4 base64url chars) rather than plaintext. That is a fingerprint, not
+// a sealed box: 24 bits only narrows the field, and anyone holding a
+// candidate name can confirm it by hashing. What it does buy is that
+// the name itself never appears in the URL, and a recipient who does
+// NOT hold the report learns nothing from the link but its length.
+//
+// Cheap on the receiving side too: matching a hint means hashing the
+// names already on disk, not reading a single file (see
+// `finding-locate.js`).
+//
+// The hint is a HINT, not an address. The receiver tries the named report
+// or workspace, then a scan of everything stored locally (see
+// `ui/view/finding-link-nav.js`) — so a link built in a workspace still
+// lands for a recipient who only has the single report, and a stale
+// hint costs a scan rather than the finding.
+//
+// Param names live in the same `&`-joined fragment namespace as
+// `share=`, and the parser has the same shape as `extractShareEncoded`
+// — a fragment can therefore only ever be one kind of link, and adding
+// a fourth param later doesn't disturb either.
+
+import { encodeUtf8 } from '../common/utf8.js'
+import { managedRoutePath, parseManagedRoute } from '../common/managed/routes.js'
+import { MAX_FINDING_ID_LENGTH, isLinkableFindingId } from '../common/finding-id.js'
+export { isLinkableFindingId } from '../common/finding-id.js'
+
+// ── location hints ───────────────────────────────────────────────────
+
+// 3 bytes → exactly 4 base64url characters, no padding. Sized to keep
+// the fragment short while still being selective enough that a hint
+// usually names one report out of a user's collection: with 16.7M
+// values, a library of 100 reports has a ~0.03% chance of any collision
+// at all, and a collision costs only a wrong first guess (the receiver
+// re-checks that the finding is actually there, then scans).
+const HINT_BYTES = 3
+const HINT_CHARS = 4
+const HINT_RE = /^[\w-]{4}$/u
+
+// Both hints travel as ONE `v=` parameter: 6 bytes, 8 base64url
+// characters, report half first. Workspace-only links use `w` followed
+// by their 3-byte / 4-character hint. Purely a length decision — two named
+// params spend 20 characters (`&report=aB3-&ws=x_9Z`) to carry 8
+// characters of payload, and a link is something people paste into
+// chat, tickets and commit messages.
+//
+// Concatenating the two 4-character tokens IS the base64 of the 6-byte
+// buffer: 3 bytes is exactly one base64 group, so nothing carries
+// across the halves and either framing produces identical text. That's
+// what lets the packing be a string join and the unpacking a slice,
+// with no encode / decode round trip.
+//
+// `AAAA` (3 zero bytes) marks a half that isn't known — a single-file
+// view has no workspace, and a report whose hint hasn't been hashed yet
+// omits its own. A genuine digest of `AAAA` therefore reads as absent,
+// once per 16.7M values per half; the cost is that the receiver skips
+// straight to the scan, which is where an unmatched hint lands anyway.
+const COMBINED_RE = /^[\w-]{8}$/u
+const NO_HINT = 'AAAA'
+
+// Domain-separated per kind so the same string can't produce a hint
+// that matches in the other namespace — a workspace whose id happened
+// to equal a report's filename would otherwise cross-resolve. Same
+// convention as `workspace-id.js`'s derivation domain.
+const HINT_DOMAINS = {
+  report: 'deepview/finding-link/report/v1\n',
+  workspace: 'deepview/finding-link/workspace/v1\n',
+}
+
+// `${kind}\0${value}` → token. Memoised because the LINK BUILDER must
+// be synchronous: the Link button writes to the clipboard inside the
+// click handler, and Safari drops the clipboard grant if the write
+// happens after an await. Ingest primes this cache for every report it
+// loads (and `switchToWorkspace` for the workspace), so by the time a
+// card is on screen its hint is already here. A cold entry is not a
+// failure — the link is simply built without that hint, and the
+// receiver falls back to the scan.
+const hintCache = new Map()
+
+function hintKey(kind, value) { return `${kind}\0${value}` }
+
+// Whether a value is a well-formed hint token, i.e. something
+// `computeLinkHint` could have produced.
+export function isLinkHint(value) {
+  return typeof value === 'string' && HINT_RE.test(value)
+}
+
+// Derive (and memoise) the hint token for a report filename or a
+// workspace id. Resolves to null — never throws — when the kind is
+// unknown, the value is empty, or `crypto.subtle` is unavailable (some
+// `file://` setups): a missing hint degrades the link, it doesn't break
+// it, so the caller shouldn't have to guard.
+export async function computeLinkHint(kind, value) {
+  const domain = HINT_DOMAINS[kind]
+  if (!domain || typeof value !== 'string' || !value) return null
+  const key = hintKey(kind, value)
+  const cached = hintCache.get(key)
+  if (cached !== undefined) return cached
+  let token
+  try {
+    const digest = await crypto.subtle.digest('SHA-256', encodeUtf8(domain + value))
+    token = new Uint8Array(digest).slice(0, HINT_BYTES)
+      .toBase64({ alphabet: 'base64url', omitPadding: true })
+  } catch {
+    // Not cached: an environment without crypto.subtle stays broken,
+    // but a one-off failure (a lone surrogate in a filename tripping
+    // encodeUtf8) shouldn't poison the entry forever.
+    return null
+  }
+  hintCache.set(key, token)
+  return token
+}
+
+// Synchronous companion — the memoised token, or null if it hasn't been
+// computed yet. The link builder uses this; see `hintCache` above for
+// why it can't just await.
+export function knownLinkHint(kind, value) {
+  if (typeof value !== 'string' || !value) return null
+  return hintCache.get(hintKey(kind, value)) ?? null
+}
+
+// Pack both hints into the `v=` value, or null when neither is known
+// (in which case the param is omitted entirely rather than shipping
+// eight characters of "nothing"). Throws on a non-empty value that
+// isn't a token, so a caller passing a raw filename finds out
+// immediately instead of shipping a hint-less link.
+function packLinkHints(report, workspace) {
+  const halves = []
+  for (const [what, hint] of [['report', report], ['workspace', workspace]]) {
+    if (hint === null || hint === undefined || hint === '') { halves.push(NO_HINT); continue }
+    if (!isLinkHint(hint)) {
+      throw new TypeError(`encodeFindingRef: ${what} must be a link hint token, not a name`)
+    }
+    halves.push(hint)
+  }
+  if (halves.every((h) => h === NO_HINT)) return null
+  // Workspace → finding needs only the workspace half. Report links
+  // retain their original six-byte / eight-character encoding.
+  if (halves[0] === NO_HINT) return `w${halves[1]}`
+  return halves.join('')
+}
+
+// Split a validated `v=` value back into its two halves, mapping the
+// `AAAA` filler to null.
+function unpackLinkHints(value) {
+  const halves = [value.slice(0, HINT_CHARS), value.slice(HINT_CHARS)]
+    .map((h) => (h === NO_HINT ? null : h))
+  return { report: halves[0], workspace: halves[1] }
+}
+
+// ── fragment codec ───────────────────────────────────────────────────
+
+// Build the fragment body (no leading '#') for a finding reference.
+// `report` / `workspace` are hint TOKENS (from `computeLinkHint` /
+// `knownLinkHint`), not names; they leave as the single packed `v=`
+// param: `w` + four characters for a workspace, eight for a report with its
+// optional workspace. Omitted when neither is known.
+//
+// The id is percent-encoded: usually a uuid with nothing to escape, but
+// the codex importer's finding-URL ids carry `/`, `:`, `?` and —
+// decisively — `&` and `=`, which would otherwise split into phantom
+// params on the way back. The packed hints need no encoding (base64url
+// is already fragment-safe) and are emitted verbatim.
+export function encodeFindingRef({ id, report, workspace } = {}) {
+  if (!isLinkableFindingId(id)) {
+    throw new TypeError('encodeFindingRef: a persistent finding id is required')
+  }
+  const parts = [`finding=${encodeURIComponent(id)}`]
+  const packed = packLinkHints(report, workspace)
+  if (packed) parts.push(`v=${packed}`)
+  return parts.join('&')
+}
+
+// Full shareable URL for the current page origin + pathname, mirroring
+// `buildShareUrl`. `location.search` is dropped for the same reason it
+// is there: the target page takes no query params, so dragging the
+// sender's current `?foo=bar` into the recipient's URL would be a
+// surprising leak.
+export function buildFindingUrl(ref, pathname) {
+  const encoded = encodeFindingRef(ref)
+  if (typeof location === 'undefined') return `${pathname ?? ''}#${encoded}`
+  return `${location.origin}${pathname ?? location.pathname}#${encoded}`
+}
+
+// Extract `{ id, report, workspace }` from a hash string (or
+// `location.hash` when called with no argument), unpacking `v=` back
+// into the two hint tokens. Returns null when the fragment carries no
+// usable `finding=` param — a share link, an in-page anchor, an empty
+// hash, or a payload that fails validation.
+//
+// HASH ONLY, matching `extractShareEncoded`. The id isn't secret, so the
+// Referer-leak argument that motivates it there doesn't apply; the
+// reason is uniformity — one place in the app reads deep links, and a
+// caller that reached for `?finding=` would quietly bypass it.
+//
+// A malformed `v=` drops both hints rather than the whole ref: the id is
+// what identifies the finding, and the receiver's scan can still land
+// it. That also covers a link from an older build, whose separate
+// `report=` / `ws=` params simply go unread. An un-decodable ID, on the
+// other hand, fails the whole parse — there is nothing left to look up.
+export function extractFindingRef(hash) {
+  const raw = typeof hash === 'string' ? hash : (typeof location === 'undefined' ? '' : location.hash)
+  if (!raw) return null
+  const stripped = raw.replace(/^#/u, '')
+  if (!stripped) return null
+  const found = { id: null, report: null, workspace: null }
+  for (const part of stripped.split('&')) {
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const key = part.slice(0, eq)
+    const rawValue = part.slice(eq + 1)
+    if (!rawValue) continue
+    // The packed hints are one workspace token or a token pair — validated
+    // verbatim rather than decoded, since base64url has nothing
+    // `encodeURIComponent` would have touched. Anything else is a link
+    // from another era or a mangled paste; drop it and let the scan
+    // take over.
+    if (key === 'v') {
+      if (rawValue.length === 5 && rawValue[0] === 'w' && isLinkHint(rawValue.slice(1))) {
+        const workspace = rawValue.slice(1)
+        Object.assign(found, { report: null, workspace: workspace === NO_HINT ? null : workspace })
+        continue
+      }
+      if (!COMBINED_RE.test(rawValue)) continue
+      Object.assign(found, unpackLinkHints(rawValue))
+      continue
+    }
+    if (key !== 'finding') continue
+    // Cheap length bound BEFORE decoding: percent-encoding expands at
+    // most 3:1, so nothing under this cap can decode to something over
+    // MAX_FINDING_ID_LENGTH, and a megabyte fragment never reaches
+    // decodeURIComponent. `isLinkableFindingId` re-checks the decoded
+    // length, so this is a guard, not the rule.
+    if (rawValue.length > MAX_FINDING_ID_LENGTH * 3) continue
+    let value
+    // decodeURIComponent throws URIError on a truncated / invalid escape
+    // (`%`, `%zz`) — common when a chat client mangles a pasted link.
+    try { value = decodeURIComponent(rawValue) } catch { continue }
+    if (isLinkableFindingId(value)) found.id = value
+  }
+  if (!found.id) return null
+  return found
+}
+
+// Recognise a finding deep link pasted into free text — the reverse of
+// `buildFindingUrl`, used to linkify comments (see `parseCommentRefs` in
+// `ui/view/format.js`). Returns `{ id, fragment, path }` with the E2E fragment
+// re-emitted canonically and a managed destination URL, or null
+// for anything that isn't one of OUR links.
+//
+// "Ours" means the CURRENT host, scheme included. A finding id resolves
+// only against the reader's available reports, so a link to some other
+// deployment couldn't be followed usefully even if it were offered — and
+// a same-name look-alike on another host is exactly what a linkifier
+// must not present as the real thing. Credentials are refused for the
+// same reason (`https://user@triage.space/…` reads as ours but isn't
+// something the app ever emits).
+//
+// Managed team/report paths are preserved to identify the intended copy.
+// E2E entry links resolve from `/` in managed mode, without inheriting
+// the current report. E2E consumers use just the fragment to stay on their
+// current deployment, including `/index.html` and subpaths.
+//
+// The anti-mutation guard is the one from `githubRefToken`: `new URL`
+// silently rewrites its input (resolving `..`, lower-casing, punycoding
+// IDN homographs, dropping a default port), any of which can let a
+// look-alike round up into a passing link. A candidate that isn't
+// already canonical is refused rather than linkified. Every link this
+// app emits round-trips unchanged, since `buildFindingUrl` builds from
+// `location` itself.
+export function parseFindingUrl(candidate, { managed = false } = {}) {
+  if (typeof location === 'undefined') return null
+  let u
+  try { u = new URL(candidate) } catch { return null }
+  if (u.href !== candidate) return null
+  if (u.protocol !== location.protocol) return null
+  if (u.host !== location.host) return null
+  if (u.username || u.password) return null
+  const route = parseManagedRoute(u)
+  if (route?.finding) {
+    return { id: route.finding.id, fragment: encodeFindingRef(route.finding), path: managedRoutePath(route) }
+  }
+  // Only E2E entry pages carry finding hashes. Unknown managed page URLs
+  // must not turn into a search for another accessible copy of the finding.
+  if (managed && route?.view !== 'home' && !/\/(?:index|view)\.html$/u.test(u.pathname)) return null
+  const ref = extractFindingRef(u.hash)
+  if (!ref) return null
+  const fragment = encodeFindingRef(ref)
+  return { id: ref.id, fragment, path: `/#${fragment}` }
+}

package/client/linked-findings.d.ts

@@ -0,0 +1 @@
+export function parseLinkedFindings(content: string): { groups: string[][]; skipped: number } | null

package/client/linked-findings.js

@@ -0,0 +1,111 @@
+// The "links" file — a small JSON document that says which findings
+// are the SAME finding, reported twice:
+//
+//   [[{"id":"a"},{"id":"b"}], [{"id":"c"},{"id":"d"},{"id":"e"}]]
+//
+// One inner array per link. Every finding named in it is a duplicate
+// of every other one in that array, and the file says nothing else:
+// no severity, no title, no file, no prose. That is the whole format.
+//
+// It is NOT a report, and this module deliberately sits outside
+// `report/` because of it. A report carries findings; a links file
+// carries only ids of findings that must already live in reports the
+// reader holds. So it never reaches `ingestReport` / `state.reports`,
+// it has its own view (`ui/view/render-links.js`) that points at the
+// findings. It also supplies the "Duplicates:" row on finding cards
+// and groups explicitly linked rows in workspace App view.
+//
+// Pure — no storage, no DOM, no app state. `linked-findings-index.js`
+// beside this file is the OPFS-wide store built on top; everything
+// here is text in, data out, so the recognition rules are testable on
+// their own.
+
+import { isLinkableFindingId } from './finding-link.js'
+
+// The `source` marker a links file is filed under — the same slot a
+// report's producer ('deepsec', 'piolium', …) occupies in the counts
+// cache, so `getKind(name)` answers "what kind of file is this" for
+// links and reports alike and the sidebar can bucket both from one
+// lookup. No report format can collide with it: this value comes from
+// here, never from a document's own content.
+export const LINKS_KIND = 'links'
+
+// Is this one entry of an inner array — `{"id": "…"}` — as the format
+// spells it? Extra fields are allowed and ignored: an exporter that
+// writes the title or the report alongside the id is writing a
+// superset of this format, not a different one.
+function entryId(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
+  const { id } = entry
+  return typeof id === 'string' && id.length > 0 ? id : null
+}
+
+// Recognise `content` as a links file and normalise it.
+//
+// Returns `{ groups, skipped }` — `groups` is one `string[]` of finding
+// ids per link, and `skipped` counts ids the app could never follow (a
+// session-local numeric id, a control character, something absurdly
+// long — `isLinkableFindingId` draws the same line the per-finding Link
+// button draws). Returns null when the text isn't this format at all.
+//
+// Recognition is on SHAPE, and it is strict, because this parser runs
+// against every dropped file before the report readers get their turn:
+// a top-level array, holding only arrays, holding only objects with a
+// string `id`. Nothing else this app reads is a bare JSON array, so
+// nothing else can be mistaken for one — and an empty top-level array
+// is refused rather than claimed, since `[]` is every empty JSON list
+// in the world, not distinctively a links file.
+//
+// Normalisation drops what carries no information: ids repeated inside
+// one link, ids that can't be linked, and then any link left naming
+// fewer than two findings — a "link" to a single finding links nothing.
+// A file whose every link normalises away is still a links file; it
+// just has no links, which its view says plainly.
+export function parseLinkedFindings(content) {
+  let data
+  try { data = JSON.parse(content) } catch { return null }
+  if (!Array.isArray(data) || data.length === 0) return null
+  const groups = []
+  let skipped = 0
+  for (const raw of data) {
+    if (!Array.isArray(raw)) return null
+    const ids = new Set()
+    for (const entry of raw) {
+      const id = entryId(entry)
+      if (id === null) return null
+      if (isLinkableFindingId(id)) ids.add(id)
+      else skipped++
+    }
+    if (ids.size > 1) groups.push([...ids])
+  }
+  return { groups, skipped }
+}
+
+// How many findings the links in `groups` name, counted once each — a
+// finding named by two links is one linked finding. What the sidebar
+// badge and the view's header report alongside the link count.
+export function countLinkedIds(groups) {
+  const ids = new Set()
+  for (const group of groups) for (const id of group) ids.add(id)
+  return ids.size
+}
+
+// Fold links into `index` (a `Map<id, Set<id>>`): every id in a link
+// gains every OTHER id in it as a duplicate. Called once per links
+// file, so an id linked by two files ends up with the union of what
+// both said about it.
+//
+// Union, NOT transitive closure. If one file links a↔b and another
+// links b↔c, then b has two duplicates and a has one — a and c were
+// never said to be the same finding, and inferring it would put a
+// claim in the reader's card that no file they dropped ever made.
+export function collectDuplicates(groups, index) {
+  for (const group of groups) {
+    for (const id of group) {
+      let set = index.get(id)
+      if (!set) index.set(id, set = new Set())
+      for (const other of group) if (other !== id) set.add(other)
+    }
+  }
+  return index
+}

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 }

package/common/bundle-metadata.js

@@ -0,0 +1,177 @@
+import { bundleCodeStats } from './bundle-stats.js'
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { computeFileHash } from '../report/index.js'
+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.
+export const BUNDLE_METADATA_VERSION = 2
+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, 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)
+  return { files: files.length, lines,
+    codeFiles: files.filter(([path]) => !['resource:base64', 'directory'].includes(formats?.get(path))).length }
+}
+
+// `stale` marks an index this version did not write: its hashes still
+// answer report lookups, but its sizes and line counts are not trusted,
+// and an open rebuilds it.
+export function parseBundleMetadata(data, integrity) {
+  if ((data?.version !== 1 && data?.version !== INDEX_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 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 && !(stale && 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) || (stale && 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 && (stale || !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 (!stale && [...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
+}
+