@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.41

package/common/bundle-compare-inputs.js

@@ -0,0 +1,65 @@
+import { bundleFilesAsMap } from './bundle-sources.js'
+
+// Use the union of named trees. A tree absent from one stasis bundle contains
+// no files there; falling back to all files would invent additions/removals.
+// A bundle that names no trees (a sourcemap) is compared whole under any of
+// them. Unlike a single-bundle graph, retain a scope that includes every file
+// on one side.
+export function bundleCompareScopes(...details) {
+  const names = new Set()
+  for (const item of details) {
+    const files = bundleFilesAsMap(item)
+    for (const [name, paths] of Object.entries(item?.bundle?.reason ?? {})) {
+      if (Array.isArray(paths) && paths.some(path => files.has(path))) names.add(name)
+    }
+  }
+  // A scope is only useful as a filter if it changes the files compared on
+  // some side. Keep every scope when at least one does, otherwise hide the
+  // selector, as single-bundle views do (see common/bundle-reasons.js).
+  const narrows = name => details.some(item => {
+    if (item?.kind !== 'stasis') return false
+    const files = bundleFilesAsMap(item)
+    const paths = item?.bundle?.reason?.[name]
+    return new Set(Array.isArray(paths) ? paths.filter(path => files.has(path)) : []).size < files.size
+  })
+  if (![...names].some(narrows)) return []
+  return [...names].toSorted().map(name => ({ id: `reason:${name}`, label: name }))
+}
+
+export function bundleCompareFiles(details, scope = '') {
+  const files = bundleFilesAsMap(details)
+  if (!scope || details?.kind !== 'stasis') return files
+  const paths = details?.bundle?.reason?.[scope.replace(/^reason:/u, '')]
+  const selected = new Set(Array.isArray(paths) ? paths : [])
+  return new Map([...files].filter(([path]) => selected.has(path)))
+}
+
+// A resolution's identity: its importer, specifier, conditions (import
+// attributes included), and Metro platform.
+export function resolutionKey(parent, specifier, conditions, platform) {
+  return JSON.stringify([parent, specifier, conditions, platform])
+}
+
+// Keep the full resolution identity: collapsing to graph edges would lose
+// specifier, condition/import-attribute, and Metro platform changes.
+export function bundleCompareResolutions(details, scope = '') {
+  const result = new Map()
+  if (details?.kind !== 'stasis' || !details.bundle) return result
+  const files = scope ? bundleFilesAsMap(details) : null
+  const selected = scope ? bundleCompareFiles(details, scope) : null
+  for (const [conditions, byParent] of details.bundle.imports) {
+    for (const [parent, specifiers] of byParent) {
+      for (const [specifier, resolved] of specifiers) {
+        const targets = typeof resolved === 'string' ? [[null, resolved]] : resolved
+        for (const [platform, target] of targets) {
+          // Include imports from scoped files, plus imports into the scope
+          // from uncaptured parents (e.g. an app in a dependencies-only bundle).
+          if (selected && !selected.has(parent) && (files.has(parent) || !selected.has(target))) continue
+          const key = resolutionKey(parent, specifier, conditions, platform)
+          result.set(key, { key, parent, specifier, conditions, platform, target })
+        }
+      }
+    }
+  }
+  return result
+}

package/common/bundle-metadata.d.ts

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

package/common/bundle-metadata.js

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

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

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

package/common/bundle-pkg-of.js

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

package/common/bundle-reasons.d.ts

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

package/common/bundle-reasons.js

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

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

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

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)
+}