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

package/server-managed/release-commits.ts

@@ -0,0 +1,84 @@
+// The commits that release a repository, for its Pulse (repository-pulse.ts
+// commitStats): one a tag names that changes no code, only package.json
+// files (at least one, in any directory), the lockfiles beside them
+// (RELEASE_LOCKFILES) and changelogs written in Markdown (RELEASE_CHANGELOG,
+// a changeset's file among them), as `npm version` and a release's tooling
+// leave one. What each commit changes is read as Replay reads it, kept by
+// the commit (repository-changes.ts repositoryChanges).
+import { type ChangesStore, type CommitChanges, repositoryChanges } from './repository-changes.ts'
+import { githubGraphql } from './repository-history.ts'
+
+// The tags read, a page a query, the latest commits' first, as many pages as
+// TAG_PAGES; of the commits they name, as many as RELEASES_READ have their
+// files read.
+const TAG_PAGE = 100
+const TAG_PAGES = 5
+const RELEASES_READ = 200
+// An annotated tag's target, its own target in turn, through as many as
+// TAG_DEPTH annotated tags.
+const TAG_DEPTH = 3
+const SHA = /^[a-f\d]{40}$/u
+const RELEASE_LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'])
+const RELEASE_CHANGELOG = /^(?:changelog|changes|history|news|releases?)(?:[._-][^/]*)?\.(?:md|markdown)$/iu
+const CHANGESET = /(?:^|\/)\.changeset\/[^/]+\.md$/iu
+
+const tagTarget = (depth: number): string => `target { __typename oid ... on Commit { committedDate }${depth > 0 ? ` ... on Tag { ${tagTarget(depth - 1)} }` : ''} }`
+const TAGS_QUERY = `query($owner: String!, $name: String!, $after: String) {
+  repository(owner: $owner, name: $name) {
+    refs(refPrefix: "refs/tags/", first: ${TAG_PAGE}, after: $after, orderBy: { field: TAG_COMMIT_DATE, direction: DESC }) {
+      pageInfo { hasNextPage endCursor }
+      nodes { ${tagTarget(TAG_DEPTH)} }
+    }
+  }
+}`
+type TagTarget = { __typename?: unknown; oid?: unknown; committedDate?: unknown; target?: TagTarget | null } | null | undefined
+type TagsPage = { repository?: { refs?: { pageInfo?: { hasNextPage?: unknown; endCursor?: unknown }; nodes?: ({ target?: TagTarget } | null)[] } | null } | null }
+
+// The commit a tag names, through its annotated tags, and when it was
+// committed; null for one naming no commit (a tree, a blob).
+function taggedCommit(target: TagTarget, depth = TAG_DEPTH): { oid: string; at: number } | null {
+  if (target?.__typename === 'Tag' && depth > 0) return taggedCommit(target.target, depth - 1)
+  const at = typeof target?.committedDate === 'string' ? Date.parse(target.committedDate) : Number.NaN
+  return target?.__typename === 'Commit' && typeof target.oid === 'string' && SHA.test(target.oid) && Number.isSafeInteger(at) ? { oid: target.oid, at } : null
+}
+
+// The commits the repository's tags name committed since `since`, the
+// latest first, as many pages of them as TAG_PAGES.
+export async function taggedCommits(fullName: string, token: string, since: number, fetchImpl: typeof fetch = globalThis.fetch): Promise<Set<string>> {
+  const [owner, name] = fullName.split('/') as [string, string]
+  const tagged = new Set<string>()
+  let after: string | null = null
+  for (let pages = 0; pages < TAG_PAGES; pages++) {
+    const page = await githubGraphql(TAGS_QUERY, { owner, name, after }, token, fetchImpl) as TagsPage | null
+    const refs = page?.repository?.refs
+    const commits = (refs?.nodes ?? []).flatMap(node => taggedCommit(node?.target) ?? [])
+    for (const commit of commits) if (commit.at >= since) tagged.add(commit.oid)
+    if (refs?.pageInfo?.hasNextPage !== true || typeof refs.pageInfo.endCursor !== 'string' || commits.some(commit => commit.at < since)) break
+    after = refs.pageInfo.endCursor
+  }
+  return tagged
+}
+
+// Whether a path is one a release changes: a package.json, a lockfile beside
+// one, or a changelog in Markdown.
+const releaseFile = (path: string) => {
+  const base = path.slice(path.lastIndexOf('/') + 1)
+  return base === 'package.json' || RELEASE_LOCKFILES.has(base) || RELEASE_CHANGELOG.test(base) || CHANGESET.test(path)
+}
+
+// Whether what a commit changes is a release's: a package.json at least, and
+// nothing a release changes none of, a rename's both paths alike; one
+// GitHub listed only some files of, not.
+export function releaseChanges({ files, more }: CommitChanges): boolean {
+  const paths = files.flatMap(([path, status, from]) => status === 'R' ? [path, from] : [path])
+  return !more && paths.some(path => path.slice(path.lastIndexOf('/') + 1) === 'package.json') && paths.every(releaseFile)
+}
+
+// The commits since `since` that release the repository: those its tags
+// name whose changes are a release's, each read as Replay reads it (`kept`),
+// as many as RELEASES_READ, sorted.
+export async function releaseCommits(fullName: string, token: string, since: number, kept: ChangesStore, fetchImpl: typeof fetch = globalThis.fetch): Promise<string[]> {
+  const tagged = [...await taggedCommits(fullName, token, since, fetchImpl)].slice(0, RELEASES_READ)
+  const changes = await repositoryChanges(fullName, token, tagged, kept, fetchImpl)
+  return tagged.filter(sha => { const read = changes.get(sha); return read ? releaseChanges(read) : false }).toSorted()
+}

package/server-managed/rename-diff-worker.js

@@ -0,0 +1,26 @@
+// Compare's diff with renamed names hidden (rename-diff.ts), worked out off the
+// server's event loop by @preventive/compare's renamedDiffs: the old side given
+// the new side's names, not formatted again (each line where the old side's was),
+// diffed with whitespace changes shown and hidden, and the blocks checked to
+// take it to the new side. `{ before, blocks, reason, reads, marks,
+// ignoringWhitespace }`: the old side as diffed, the change blocks, why the
+// old side is as it was where its names could not be given safely, the
+// properties through which either side reads names (a view marks renamed
+// lines rather than hiding them where any are read, as a rename may then
+// change what the code does), and the blocks of the diff of the files as they
+// are that differ in renamed names alone; `ignoringWhitespace` the blocks and
+// those marked with whitespace changes hidden, as diff -b hides them. Blocks
+// that would not take the old side to the new are thrown, and so answer
+// nothing.
+import { parentPort, workerData } from 'node:worker_threads'
+import { renamedDiffs } from '@preventive/compare/names.js'
+
+const { before, after, extension, otherExtension } = workerData
+const diff = await renamedDiffs(before, after, { extension, otherExtension, whitespace: ['none', 'change'] })
+// A check that should never fail did, or a step gave way: told, the file shown with its names.
+for (const warning of diff.warnings) console.warn(`managed: rename diff: ${warning}`)
+const [shown, hidden] = diff.diffs
+const answer = { before: diff.before, blocks: shown.blocks, reason: diff.reason, reads: diff.reads, marks: shown.marks, ignoringWhitespace: { blocks: hidden.blocks, marks: hidden.marks } }
+// Node worker messages have no browser target origin.
+// oxlint-disable-next-line unicorn/require-post-message-target-origin
+parentPort.postMessage(answer)

package/server-managed/rename-diff.ts

@@ -0,0 +1,279 @@
+// Compare's diff of a JavaScript file minified on both sides with the names a
+// minifier renamed alike hidden (GET /api/bundles/:id/rename-diff, GET
+// /api/npm/rename-diff): both sides pretty-printed, as the pretty-print toggle
+// has them (pretty-print.ts), then diffed by @preventive/compare's
+// renamedDiffs in a worker, off the event loop and two at a time per process,
+// with whitespace changes shown and hidden both. Answered as Brotli-encoded
+// JSON, `{ before, blocks, reason, reads, marks, ignoringWhitespace }`
+// (rename-diff-worker.js), the two files' hashes, `hash` and `otherHash`, and
+// those of the two copies diffed, `prettyHash` and `otherPrettyHash`, which
+// the viewer checks are those it asked about and draws: one file's asked for
+// by both its sides' paths and hashes, or every pair a comparison's viewer
+// diffs so, a line each (renamedPairs). The last few answers are kept in
+// memory by both files' hashes, a private npm version's never, each side read
+// again through the pretty-print cache first, which checks that its source
+// holds a file of that hash. Access is the caller's to check.
+import { Buffer } from 'node:buffer'
+import { Readable } from 'node:stream'
+import { promisify } from 'node:util'
+import { Worker } from 'node:worker_threads'
+import { brotliDecompress } from 'node:zlib'
+import { layoutPackageDirs, treeLayout } from '@preventive/compare'
+import { computeFileHash } from '@preventive/report'
+import { FILE_HASH } from '../common/bundle-metadata.js'
+import { computeBundleDiff } from '../common/bundle-compare-diff.js'
+import { bundlePkgOf } from '../common/bundle-pkg-of.js'
+import { needsPrettyPrint, prettyExtension } from '../common/pretty-print.js'
+import { type ChangeBlock, blocksHold, textLines } from '../common/line-diff.js'
+import type { OpenedBlob } from './blob-store.ts'
+import { encodeBrotli } from './brotli.ts'
+import { type ComparedSide, PrettyError, type PrettyRequest, prettyText } from './pretty-print.ts'
+
+// What a minifier renames: JavaScript, as the viewer offers it for.
+const RENAMABLE = new Set(['js', 'mjs', 'cjs'])
+// Diffs worked out at once per process, each in a worker of its own, and
+// those waiting their turn past them (a Diff view asks for all it shows at
+// once), any more refused.
+const MAX_ACTIVE_DIFFS = 2
+const MAX_WAITING_DIFFS = 16
+// The longest a diff may take, its wait for a worker included, and the most
+// text it is asked of: both sides pretty-printed, which the largest files
+// formatted (MAX_PRETTY_BYTES) stay under.
+const DIFF_TIMEOUT_MS = 60_000
+const MAX_DIFF_CHARS = 64 * 1024 * 1024
+// Answers kept, the one read last last: each holds the old side as diffed.
+// As many as a comparison's viewer may ask for beside the pairs it has come
+// (renamedPairs), so that neither is worked out twice.
+const KEPT_DIFFS = 32
+
+// `blocks` and `marks` with whitespace changes shown, `ignoringWhitespace`'s
+// hidden as diff -b hides them.
+export interface RenameDiff {
+  before: string; blocks: ChangeBlock[]; reason: string | null; reads: string[]; marks: ChangeBlock[]
+  ignoringWhitespace: { blocks: ChangeBlock[]; marks: ChangeBlock[] }
+}
+
+export interface RenameDiffRequest { base: PrettyRequest; other: PrettyRequest }
+
+// The two files a request names, a base's `path` and `hash` and the other
+// side's `otherPath` and `otherHash`, or null where either is no JavaScript
+// file named by its hash.
+export function renameDiffRequest(params: URLSearchParams): RenameDiffRequest | null {
+  const side = (path: string, hash: string): PrettyRequest | null => {
+    const extension = prettyExtension(path)
+    return extension !== null && RENAMABLE.has(extension) && FILE_HASH.test(hash) ? { path, hash, extension } : null
+  }
+  const base = side(params.get('path') ?? '', params.get('hash') ?? ''), other = side(params.get('otherPath') ?? '', params.get('otherHash') ?? '')
+  return base && other ? { base, other } : null
+}
+
+let activeDiffs = 0
+const waiting: Array<() => void> = []
+const kept = new Map<string, Buffer>()
+const pending = new Map<string, Promise<Buffer>>()
+
+// A worker's turn, waited for behind those running until `deadline`; given
+// up, it goes to the next one waiting.
+async function turn(deadline: number): Promise<void> {
+  if (activeDiffs < MAX_ACTIVE_DIFFS) { activeDiffs++; return }
+  if (waiting.length >= MAX_WAITING_DIFFS) throw new PrettyError(429, 'diff-busy')
+  await new Promise<void>((resolve, reject) => {
+    const next = () => { clearTimeout(timer); resolve() }
+    const timer = setTimeout(() => {
+      waiting.splice(waiting.indexOf(next), 1)
+      reject(new PrettyError(504, 'diff-timeout'))
+    }, deadline - Date.now())
+    waiting.push(next)
+  })
+}
+function done() {
+  const next = waiting.shift()
+  if (next) next()
+  else activeDiffs--
+}
+async function inTurn<T>(deadline: number, work: () => Promise<T>): Promise<T> {
+  await turn(deadline)
+  try { return await work() } finally { done() }
+}
+
+// Whether a worker's answer is one as rename-diff-worker.js gives it, its
+// blocks taking the old side it answered to the new one asked of, whitespace
+// changes shown and hidden: checked again here, apart from the worker, as an
+// answer that is not would hide a change.
+function answers(diff: unknown, original: string, after: string): diff is RenameDiff {
+  const { before, blocks, reason, reads, marks, ignoringWhitespace } = (diff ?? {}) as Partial<RenameDiff>
+  return typeof before === 'string' && (reason === null || typeof reason === 'string') && Array.isArray(reads) && reads.every(read => typeof read === 'string')
+    && blocksHold(before, after, blocks, false) && marksFit(original, after, marks)
+    && blocksHold(before, after, ignoringWhitespace?.blocks, true) && marksFit(original, after, ignoringWhitespace?.marks)
+}
+
+// Whether marked blocks (rename-diff-worker.js) are blocks of the diff of the
+// two files as they are: in order, apart, within both, each as many lines on
+// either side.
+function marksFit(before: string, after: string, marks: unknown): boolean {
+  if (!Array.isArray(marks)) return false
+  const [olds, news] = [textLines(before).length, textLines(after).length]
+  let i = 0, j = 0
+  for (const mark of marks as Partial<ChangeBlock>[]) {
+    const { a0, a1, b0, b1 } = mark ?? {}
+    if (![a0, a1, b0, b1].every(Number.isInteger)) return false
+    const [x0, x1, y0, y1] = [a0, a1, b0, b1] as [number, number, number, number]
+    if (x0 < i || y0 < j || x1 <= x0 || x1 - x0 !== y1 - y0 || x1 > olds || y1 > news) return false
+    i = x1
+    j = y1
+  }
+  return true
+}
+
+// Settled once the worker is gone, so that its turn is given up only then.
+function inWorker(before: string, after: string, { base, other }: RenameDiffRequest, deadline: number): Promise<RenameDiff> {
+  if (before.length + after.length > MAX_DIFF_CHARS) throw new PrettyError(413, 'diff-too-large')
+  let worker: Worker
+  try {
+    worker = new Worker(new URL('./rename-diff-worker.js', import.meta.url), {
+      workerData: { before, after, extension: base.extension, otherExtension: other.extension }, execArgv: [],
+      resourceLimits: { maxOldGenerationSizeMb: 1024 },
+    })
+  } catch (err) {
+    console.warn('managed: a rename diff could not start:', err)
+    throw new PrettyError(503, 'unavailable')
+  }
+  return new Promise<RenameDiff>((resolve, reject) => {
+    let diff: RenameDiff | null = null, failure = new PrettyError(422, 'undiffable')
+    const timer = setTimeout(() => { failure = new PrettyError(504, 'diff-timeout'); void worker.terminate() }, deadline - Date.now())
+    worker.once('message', (answer: unknown) => {
+      if (answers(answer, before, after)) diff = answer
+      else console.warn('managed: a rename diff answered what does not take its old side to the new')
+      void worker.terminate()
+    })
+    worker.once('error', err => { console.warn('managed: a rename diff failed:', err) })
+    // Gone: answered, run out of memory, or terminated.
+    worker.once('exit', () => {
+      clearTimeout(timer)
+      if (diff) resolve(diff)
+      else reject(failure)
+    })
+  })
+}
+
+// `work` given until `deadline`: past it, answered 504 and left to finish on its own.
+function byDeadline<T>(work: Promise<T>, deadline: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<never>((_, reject) => { timer = setTimeout(() => { reject(new PrettyError(504, 'diff-timeout')) }, deadline - Date.now()) })
+  return Promise.race([work, late]).finally(() => { clearTimeout(timer) })
+}
+
+// An answer as sent, naming the files asked about and the pretty-printed
+// copies of them it was worked out from.
+async function encoded(diff: RenameDiff, { base, other }: RenameDiffRequest, [before, after]: [string, string]): Promise<Buffer> {
+  const [prettyHash, otherPrettyHash] = await Promise.all([computeFileHash(before), computeFileHash(after)])
+  return encodeBrotli(Buffer.from(JSON.stringify({ ...diff, hash: base.hash, otherHash: other.hash, prettyHash, otherPrettyHash })))
+}
+const opened = (body: Buffer): OpenedBlob => ({ size: body.byteLength, stream: Readable.from([body]) })
+
+// The answer for the two files a request names, Brotli-encoded, `texts`
+// reading both sides pretty-printed (and so checking each is its source's):
+// kept by their hashes where `keep`, readers asking for one meanwhile sharing
+// it. A minute for it, its wait for a worker included.
+export async function renameDiffOf(request: RenameDiffRequest, texts: () => Promise<[string, string]>, keep = true): Promise<OpenedBlob> {
+  return opened(await answerOf(request, texts, keep))
+}
+
+// Sides `verified` to be the files the request names (renamedPairs) are read
+// only where no answer is kept or on its way; others are read first, as
+// reading them checks they are.
+async function answerOf(request: RenameDiffRequest, texts: () => Promise<[string, string]>, keep: boolean, verified = false): Promise<Buffer> {
+  // Sides not kept are formatted again for each diff (pretty-print.ts), so
+  // they are read in its turn: the files a Diff view asks for at once wait
+  // here rather than being refused by the formats running. Within its minute
+  // too, its turn not held past it by a version's files still downloading.
+  if (!keep) {
+    const deadline = Date.now() + DIFF_TIMEOUT_MS
+    let sides: [string, string] = ['', '']
+    const diff = await inTurn(deadline, async () => {
+      sides = await byDeadline(texts(), deadline)
+      return inWorker(sides[0], sides[1], request, deadline)
+    })
+    return encoded(diff, request, sides)
+  }
+  // A file's type is part of how it is read: the same text as a script and as a module differ.
+  const key = `${request.base.hash}\0${request.base.extension}\0${request.other.hash}\0${request.other.extension}`
+  const held = () => {
+    const found = kept.get(key)
+    if (found) {
+      kept.delete(key)
+      kept.set(key, found)
+    }
+    return found ?? pending.get(key)
+  }
+  let answer = verified ? held() : undefined
+  if (!answer) {
+    const [before, after] = await texts()
+    answer = held()
+    if (!answer) {
+      const deadline = Date.now() + DIFF_TIMEOUT_MS
+      const job = inTurn(deadline, () => inWorker(before, after, request, deadline)).then(diff => encoded(diff, request, [before, after])).finally(() => pending.delete(key))
+      pending.set(key, answer = job)
+    }
+  }
+  const body = await answer
+  kept.set(key, body)
+  if (kept.size > KEPT_DIFFS) kept.delete(kept.keys().next().value!)
+  return body
+}
+
+const decompress = promisify(brotliDecompress)
+
+// What a minifier renames, by its path's extension.
+const renamable = ({ extension }: PrettyRequest) => RENAMABLE.has(extension)
+
+// One of a comparison's pairs of files (renamedPairs), its sides named as a
+// request names them, with its answer as renameDiffOf sends it, or why it has
+// none, as a PrettyError tells it.
+export type RenamedLine = { path: string; hash: string; otherPath: string; otherHash: string } & (Partial<RenameDiff> | { error: string; status: number })
+
+// The files that changed between a comparison's two sides, as its viewer
+// pairs them (ui/view/bundle-comparison.js prepareComparison): at one path as
+// the other side lays them out, or renamed within a package, as the bundles
+// record their packages; every file there, those that can be formatted by
+// their texts and the rest by their hashes. A file the viewer pairs otherwise
+// (its files are its resources too) it asks about alone.
+export function comparedFiles(sides: readonly [ComparedSide, ComparedSide]) {
+  const [olds, news] = sides.map(({ files, hashes }) => {
+    const texts = new Map(files.map(file => [file.path, file.text]))
+    return new Map<string, unknown>([...hashes].map(([path, hash]) => [path, texts.get(path) ?? { format: 'digest', digest: hash }]))
+  }) as [Map<string, unknown>, Map<string, unknown>]
+  const layout = treeLayout(olds.keys(), news.keys())
+  const packageDirs = layoutPackageDirs(sides[0].packageDirs, sides[1].packageDirs, layout)
+  return computeBundleDiff(olds, news, path => bundlePkgOf(path, { packageDir: packageDirs?.get(path) }), layout).files
+}
+
+// The pairs of JavaScript files minified on both sides that changed between a
+// comparison's two sides, paired as its viewer pairs them (comparedFiles),
+// each diffed as renameDiffOf diffs it, from both sides' copies, kept or
+// made, as they are iterated: in path order, one after another, leaving a
+// worker to the files a viewer asks for alone (a pair it reads otherwise, one
+// it shows first).
+export function renamedPairs([base, other]: readonly [ComparedSide, ComparedSide], keep = true): AsyncGenerator<RenamedLine> {
+  const formattable = ({ files }: ComparedSide) => new Map(files.map(file => [file.path, file]))
+  const [olds, news] = [formattable(base), formattable(other)]
+  const pairs = comparedFiles([base, other]).changed.flatMap(({ path, basePath = path }) => {
+    const [from, to] = [olds.get(basePath), news.get(path)]
+    return from && to && from.hash !== to.hash && [from, to].every(file => renamable(file) && needsPrettyPrint(file.path, file.text)) ? [[from, to] as const] : []
+  }).toSorted(([, a], [, b]) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+  return (async function* () {
+    for (const [from, to] of pairs) {
+      const request = { base: { path: from.path, hash: from.hash, extension: from.extension }, other: { path: to.path, hash: to.hash, extension: to.extension } }
+      const named = { path: from.path, hash: from.hash, otherPath: to.path, otherHash: to.hash }
+      const copy = async (side: ComparedSide, { text, ...file }: typeof from) => prettyText(await side.kept(file) ?? await side.made(file, text))
+      let body
+      try { body = await answerOf(request, async () => [await copy(base, from), await copy(other, to)], keep, true) }
+      catch (err) {
+        if (!(err instanceof PrettyError)) throw err
+        yield { ...named, error: err.message, status: err.status }
+        continue
+      }
+      yield { ...JSON.parse((await decompress(body)).toString('utf8')) as Partial<RenameDiff>, ...named }
+    }
+  })()
+}

package/server-managed/repo-path.ts

@@ -0,0 +1,21 @@
+const MAX_TEAM_PATH = 500
+
+// Canonicalize only equivalent Git paths: '/' separates components and empty
+// or '.' components do not change the directory. Reject ambiguous input rather
+// than deleting characters from directory names used for authorization.
+// `{ ok:false }` makes the handler 400; `{ path:null }` means the whole repo.
+export function normalizeTeamPath(raw: unknown): { ok: true; path: string | null } | { ok: false } {
+  if (typeof raw !== 'string') return { ok: true, path: null }
+  // Spaces and backslashes can be literal parts of Git directory names.
+  // Neither trimming nor treating '\\' as a separator preserves that identity.
+  if (/\p{Cc}/u.test(raw) || raw.includes('\\') || raw !== raw.trim()) return { ok: false }
+  const segments: string[] = []
+  for (const seg of raw.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..' || seg !== seg.trim()) return { ok: false }
+    segments.push(seg)
+  }
+  const path = segments.join('/')
+  if (path.length > MAX_TEAM_PATH) return { ok: false }
+  return { ok: true, path: path === '' ? null : path }
+}

package/server-managed/report-migration.ts

@@ -0,0 +1,35 @@
+// SQLite deployments store report blobs beside the database. Recover location
+// metadata before introducing directory-based team access. Schema and data move
+// together so a missing/corrupt blob leaves the migration retryable after repair.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { DatabaseSync } from 'node:sqlite'
+import { reportRepoGithub } from '@preventive/report'
+import { readManagedReport } from '../common/managed/report-content.ts'
+import { normalizeTeamPath } from './repo-path.ts'
+
+export function migrateReportLocations(db: DatabaseSync, reportDir: string): void {
+  const columns = db.prepare('PRAGMA table_info(managed_report)').all() as { name: string }[]
+  if (columns.some((column) => column.name === 'repo_directory')) return
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec("ALTER TABLE managed_report ADD COLUMN repo_directory TEXT NOT NULL DEFAULT ''")
+    const update = db.prepare('UPDATE managed_report SET repo_directory = ?, repo_embedded = ? WHERE id = ?')
+    const reports = db.prepare('SELECT id, filename FROM managed_report').all() as { id: string, filename: string }[]
+    for (const { id, filename } of reports) {
+      // Same opaque UUID boundary as the blob store; never splice arbitrary
+      // database text into a filesystem path during an upgrade.
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(id)) throw new Error(`Invalid legacy report id: ${id}`)
+      const { data } = readManagedReport(readFileSync(join(reportDir, id), 'utf8'), filename)
+      if (data == null) throw new Error(`Cannot migrate location of unreadable report ${id}`)
+      const embedded = reportRepoGithub(data) != null
+      const directory = normalizeTeamPath(data.repo?.directory)
+      if (!directory.ok) throw new Error(`Cannot migrate invalid directory of report ${id}`)
+      update.run(directory.path ?? '', embedded ? 1 : 0, id)
+    }
+    db.exec('COMMIT')
+  } catch (err) {
+    db.exec('ROLLBACK')
+    throw err
+  }
+}

package/server-managed/report-query.ts

@@ -0,0 +1,10 @@
+// Large workspaces remain a single request. Bound both the stored input and
+// the encoded response, independently of the per-upload size limit.
+export const MAX_REPORT_QUERY_COUNT = 4096
+export const MAX_REPORT_QUERY_BYTES = 1024 * 1024 * 1024
+
+// The import catalog scans a bounded page, not the whole installation. A
+// report larger than the byte target occupies a page by itself; upload limits
+// still bound that single report and the cursor must always make progress.
+export const FINDING_CATALOG_PAGE_COUNT = 128
+export const FINDING_CATALOG_PAGE_BYTES = 32 * 1024 * 1024

package/server-managed/report-response.ts

@@ -0,0 +1,16 @@
+import { MIMEType } from 'node:util'
+
+// The metadata envelope is opt-in. Wildcards keep the legacy raw report;
+// an explicit, acceptable application/json range requests the envelope.
+export function acceptsReportMetadata(accept: string | undefined): boolean {
+  // Commas inside quoted media-type parameters do not separate ranges.
+  for (const range of accept?.match(/(?:[^",]|"(?:\\.|[^"\\])*")+/gu) ?? []) {
+    try {
+      const media = new MIMEType(range.trim())
+      if (media.essence !== 'application/json') continue
+      const quality = media.params.get('q') ?? '1'
+      if (/^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/u.test(quality) && Number(quality) > 0) return true
+    } catch { /* Ignore malformed media ranges. */ }
+  }
+  return false
+}

package/server-managed/report-sources.ts

@@ -0,0 +1,178 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { extname } from 'node:path'
+import { promisify } from 'node:util'
+import { gzip } from 'node:zlib'
+import { bundlePackageDirs, bundleSourcesAsMap } from '../common/bundle-sources.js'
+import { bundleSourceLinkImports } from '../common/bundle-source-links.js'
+import type { BundleDetails } from '../common/bundle-metadata.js'
+import { loadManagedFindings, managedFindingSourcePaths } from '../common/managed/report-content.ts'
+import { type ViewerPermissions, filterReportContent } from '../common/managed/report-filter.ts'
+import { CacheMissError, type CacheStorage } from './cache-storage.ts'
+import { readBundleDetails } from './bundle-cache.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { BundleStore } from './bundle-store.ts'
+import type { ManagedBundle, ManagedDb, ReportRecord } from './db.ts'
+
+const compress = promisify(gzip)
+const reportFormat = (filename: string) => extname(filename).toLowerCase()
+
+function bundleDirectory(id: string) {
+  if (!/^[a-f\d-]{36}$/iu.test(id)) throw new Error('Invalid bundle id')
+  return id
+}
+function reportDirectory(bundleId: string, sha256: string) {
+  return `${bundleDirectory(bundleId)}/v1-${createHash('sha256').update(sha256).digest('hex')}`
+}
+function formatDirectory(bundleId: string, sha256: string, name: string) {
+  return `${reportDirectory(bundleId, sha256)}/${createHash('sha256').update(reportFormat(name)).digest('hex')}`
+}
+function sourceCacheFilename(report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>) {
+  const key = createHash('sha256').update(JSON.stringify([
+    'finding-access-v10', sourcePaths ? [...sourcePaths].toSorted() : null, bundle.integrity, bundle.kind, permissions.dependencies, permissions.security, repo,
+  ])).digest('hex')
+  return `${formatDirectory(bundle.id, report.sha256, report.filename)}/${key}.json.gz`
+}
+
+// Match the report's spelling exactly, then an unambiguous path suffix. Never
+// guess between duplicate basenames or treat a bundle path as a disk pathname.
+function selectSources(sourcePaths: Set<string>, sources: Map<string, string>) {
+  const byBasename = new Map<string, string[]>()
+  for (const file of sources.keys()) {
+    const basename = file.split('/').at(-1)!
+    const candidates = byBasename.get(basename) ?? []
+    candidates.push(file)
+    byBasename.set(basename, candidates)
+  }
+  const files = new Map<string, string>(), paths = new Map<string, string>()
+  function add(path: unknown) {
+    if (typeof path !== 'string' || !path || paths.has(path)) return
+    let file = sources.has(path) ? path : null
+    if (file === null) {
+      const suffix = path.startsWith('/') ? path : `/${path}`
+      const matches = byBasename.get(path.split('/').at(-1)!)?.filter(candidate => candidate.endsWith(suffix)) ?? []
+      if (matches.length === 1) file = matches[0]!
+    }
+    if (file === null) return
+    paths.set(path, file)
+    files.set(file, sources.get(file)!)
+  }
+  for (const path of sourcePaths) add(path)
+  return { files: [...files], paths: [...paths] }
+}
+
+function encodeSources(integrity: string, details: BundleDetails, selection: ReturnType<typeof selectSources>) {
+  const sources = new Map(selection.files)
+  const imports = [...bundleSourceLinkImports(details, sources)].map(([parent, targets]) => [parent, [...targets]])
+  const bundle = details.kind === 'stasis' ? details.bundle as { formats: Map<string, string> } : null
+  const formats = [...(bundle?.formats ?? [])].filter(([file]) => sources.has(file))
+  const packageDirs = [...(bundlePackageDirs(details) ?? [])].filter(([file]) => sources.has(file))
+  return compress(Buffer.from(JSON.stringify({ integrity, ...selection, imports, formats, packageDirs })), { level: 6 })
+}
+
+type SourcemapEdges = (bundle: ManagedBundle) => Promise<BundleDetails['edges']>
+
+// A sourcemap's imports follow the edges its metadata keeps (the bundle
+// cache's `sourcemapEdges`), read with the parser, else what edges-lite.js reads.
+async function lendSourcemapEdges(details: BundleDetails, bundle: ManagedBundle, sourcemapEdges?: SourcemapEdges) {
+  if (details.kind !== 'sourcemap' || !sourcemapEdges) return
+  const edges = await sourcemapEdges(bundle).catch(() => undefined)
+  if (edges) details.edges = edges
+}
+
+// Immutable report hashes share a derivative across duplicate uploads. Bundle
+// identity and visibility are part of the key: a broader viewer's sources must
+// never populate a restricted response. Group derivatives by hash and filename
+// format so each format's permissions can be removed after its last deletion.
+export function createReportSourcesCache(storage: CacheStorage, db: ManagedDb, reports: BlobStore, bundles: BundleStore, sourcemapEdges?: SourcemapEdges) {
+  const pending = new Map<string, { reportId: string; job: Promise<boolean> }>()
+  let queue = Promise.resolve()
+  function enqueue<T>(work: () => Promise<T>): Promise<T> {
+    const job = queue.then(work)
+    queue = job.then(() => undefined, () => undefined)
+    return job
+  }
+  async function referenced(report: ReportRecord, bundle: ManagedBundle) {
+    const names = await db.listReportFilenamesWithBundleHash(bundle.id, report.sha256)
+    return names.some(name => reportFormat(name) === reportFormat(report.filename)) && await db.getBundle(bundle.id) != null
+  }
+  async function build(target: string, report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>) {
+    // Team requests supply paths from their already-filtered members. Reopening
+    // the original report by ID would conflate visible and hidden occurrences.
+    if (!sourcePaths) {
+      const bytes = await reports.get(report.id)
+      if (!bytes) return false
+      const parsed = await loadManagedFindings(filterReportContent(bytes.toString('utf8'), permissions, report.filename, repo), report.filename)
+      if (!parsed) return false
+      sourcePaths = managedFindingSourcePaths(parsed.findings)
+    }
+    const details = await readBundleDetails(bundle, bundles)
+    if (!details) return false
+    await lendSourcemapEdges(details, bundle, sourcemapEdges)
+    const selection = selectSources(sourcePaths, bundleSourcesAsMap(details))
+    const body = await encodeSources(bundle.integrity, details, selection)
+    // A duplicate with the same hash AND format can use these parsed bytes.
+    // Another format must not keep a deleted variant's late build alive.
+    if (!(await referenced(report, bundle))) return false
+    await storage.put(target, body)
+    // Another instance may finish deletion while this write is in flight.
+    // Recheck after publishing so a late builder cannot resurrect its cache.
+    if (!(await referenced(report, bundle))) {
+      await storage.delete(formatDirectory(bundle.id, report.sha256, report.filename))
+      return false
+    }
+    return true
+  }
+  async function ensure(target: string, report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>): Promise<boolean> {
+    const existing = pending.get(target)
+    if (existing) {
+      const ready = await existing.job
+      if (ready || existing.reportId === report.id) return ready
+      // Deletion can also win before the initiator reads its blob. Retry with
+      // this request's row instead of caching that other row's miss as 204.
+      const initiator = await db.getReport(existing.reportId)
+      if (initiator?.bundleId === bundle.id && initiator.sha256 === report.sha256) return false
+      if (pending.get(target) === existing) pending.delete(target)
+      return ensure(target, report, bundle, permissions, repo, sourcePaths)
+    }
+    const job = (async () => {
+      if (await storage.exists(target)) return true
+      // Serial cold builds bound peak decompression/parsing memory.
+      return enqueue(() => build(target, report, bundle, permissions, repo, sourcePaths))
+    })()
+    const entry = { reportId: report.id, job }
+    pending.set(target, entry)
+    try { return await job } finally { if (pending.get(target) === entry) pending.delete(target) }
+  }
+  return {
+    async open(report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, sourcePaths?: Set<string>) {
+      const repo = { github: report.repoId == null ? null : await db.getRepoFullName(report.repoId) }
+      const target = sourceCacheFilename(report, bundle, permissions, repo, sourcePaths)
+      try { return { ...await storage.open(target), repo } }
+      catch (error) { if (!(error instanceof CacheMissError)) throw error }
+      if (!(await ensure(target, report, bundle, permissions, repo, sourcePaths))) return null
+      const opened = await storage.open(target)
+      return { ...opened, repo }
+    },
+    async deleteBundle(id: string) {
+      const prefix = `${bundleDirectory(id)}/`
+      await Promise.allSettled([...pending].filter(([key]) => key.startsWith(prefix)).map(([, entry]) => entry.job))
+      await storage.delete(bundleDirectory(id))
+    },
+    async deleteReport(report: Pick<ReportRecord, 'bundleId' | 'sha256' | 'filename'>) {
+      const { bundleId, sha256 } = report
+      if (bundleId === null) return
+      // Called after metadata deletion. Serialize with builders so a cold
+      // request cannot recreate a derivative after its cleanup has finished.
+      await enqueue(async () => {
+        const names = await db.listReportFilenamesWithBundleHash(bundleId, sha256)
+        if (names.length === 0) {
+          await storage.delete(reportDirectory(bundleId, sha256))
+        } else if (!names.some(name => reportFormat(name) === reportFormat(report.filename))) {
+          await storage.delete(formatDirectory(bundleId, sha256, report.filename))
+        }
+      })
+    },
+  }
+}
+export type ReportSourcesCache = ReturnType<typeof createReportSourcesCache>