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

package/server-managed/team-npm-scopes.ts

@@ -0,0 +1,106 @@
+// npm scopes a team lists: its members, whatever their role, may read that
+// scope's private packages in the npm viewer (npm-packages.ts), as admins and
+// managers may read any. Hidden teams grant nothing, as for their content.
+import { MAX_TEAM_NPM_SCOPES, normalizeNpmScope } from '../common/managed/npm-packages.js'
+import type { Role } from '../common/managed/roles.ts'
+import { gathered, reviewsIn } from './dependency-reviews.ts'
+import { ManagedMutationError } from './management.ts'
+import type { ManagedSql } from './sql.ts'
+
+export const TEAM_NPM_SCOPE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_team_npm_scope (
+  team_id TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+  scope   TEXT NOT NULL,
+  PRIMARY KEY (team_id, scope)
+) STRICT;
+`
+
+export interface TeamNpmScopeStore {
+  // Every team's scopes, sorted, keyed by team id; teams without any are absent.
+  listTeamNpmScopes(): Promise<Record<string, string[]>>
+  // Replaces a team's scopes; admin only. Answers what changed, or null for no team.
+  setTeamNpmScopes(sessionId: string, teamId: string, scopes: unknown): Promise<{ added: string[]; removed: string[] } | null>
+  // The scopes a user's visible teams list.
+  listUserNpmScopes(userId: string): Promise<string[]>
+  // Whether any visible team lists the scope: whoever reads its packages,
+  // they are the instance's own, whose new releases aren't flagged (http.ts).
+  hasTeamNpmScope(scope: string): Promise<boolean>
+  // Who session `sessionId` names now, as readSession reads it, their own
+  // or, where `viewerSessionId` names an admin's own one, a view of it: their
+  // role, the scopes their teams list (listUserNpmScopes), and whether they
+  // read the dependency reviews published to team `teamId`
+  // (dependency-reviews.ts reviewsIn); in one statement, as a list of a
+  // team's reviews asks again once npm is read. Null where it names none.
+  getNpmReviewReader(sessionId: string, viewerSessionId: string | null, now: number, teamId: string): Promise<NpmReviewReader | null>
+}
+export interface NpmReviewReader { id: string; role: Role; scopes: string[]; readsTeam: boolean }
+
+// Each distinct scope, normalized; a list with one npm could not publish
+// under, or too many, is refused whole.
+export function parseTeamNpmScopes(input: unknown): string[] {
+  if (!Array.isArray(input)) throw new ManagedMutationError(400, 'bad-scopes')
+  const scopes = new Set<string>()
+  for (const value of input) {
+    const scope = normalizeNpmScope(value)
+    if (scope === null) throw new ManagedMutationError(400, 'bad-scope')
+    scopes.add(scope)
+  }
+  if (scopes.size > MAX_TEAM_NPM_SCOPES) throw new ManagedMutationError(400, 'too-many-scopes')
+  return [...scopes].toSorted()
+}
+
+export function teamNpmScopeMethods(db: ManagedSql): TeamNpmScopeStore {
+  return {
+    async listTeamNpmScopes() {
+      const rows = await db.prepare('SELECT team_id AS teamId, scope FROM managed_team_npm_scope ORDER BY team_id, scope').all() as { teamId: string; scope: string }[]
+      const result: Record<string, string[]> = {}
+      for (const { teamId, scope } of rows) (result[teamId] ??= []).push(scope)
+      return result
+    },
+    async setTeamNpmScopes(sessionId, teamId, input) {
+      const user = await db.prepare(`SELECT u.role FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+        WHERE s.id = ? AND s.expires_at > ?`).get(sessionId, Date.now()) as { role: string } | undefined
+      if (!user) throw new ManagedMutationError(401, 'unauthenticated')
+      if (user.role !== 'admin') throw new ManagedMutationError(403, 'forbidden')
+      const scopes = parseTeamNpmScopes(input)
+      if (!await db.prepare('SELECT id FROM managed_team WHERE id = ?').get(teamId)) return null
+      const current = (await db.prepare('SELECT scope FROM managed_team_npm_scope WHERE team_id = ?').all(teamId) as { scope: string }[]).map(row => row.scope)
+      const removed = current.filter(scope => !scopes.includes(scope)).toSorted()
+      const added = scopes.filter(scope => !current.includes(scope))
+      for (const scope of removed) await db.prepare('DELETE FROM managed_team_npm_scope WHERE team_id = ? AND scope = ?').run(teamId, scope)
+      for (const scope of added) await db.prepare('INSERT INTO managed_team_npm_scope (team_id, scope) VALUES (?, ?)').run(teamId, scope)
+      return { added, removed }
+    },
+    async listUserNpmScopes(userId) {
+      const rows = await db.prepare(`SELECT DISTINCT ns.scope FROM managed_team_user tu
+        JOIN managed_team t ON t.id = tu.team_id AND t.hidden = 0
+        JOIN managed_team_npm_scope ns ON ns.team_id = tu.team_id
+        WHERE tu.user_id = ? ORDER BY ns.scope`).all(userId) as { scope: string }[]
+      return rows.map(row => row.scope)
+    },
+    getNpmReviewReader: (sessionId, viewerSessionId, now, teamId) => npmReviewReader(db, sessionId, viewerSessionId, now, teamId),
+    async hasTeamNpmScope(scope) {
+      return !!await db.prepare(`SELECT 1 AS listed FROM managed_team_npm_scope ns
+        JOIN managed_team t ON t.id = ns.team_id AND t.hidden = 0
+        WHERE ns.scope = ? LIMIT 1`).get(scope)
+    },
+  }
+}
+
+// getNpmReviewReader's statement, its session held to what readSession's
+// own are (db-methods.ts selectOwnSessionStmt, selectViewSessionStmt).
+async function npmReviewReader(db: ManagedSql, sessionId: string, viewerSessionId: string | null, now: number, teamId: string): Promise<NpmReviewReader | null> {
+  const row = await db.prepare(`WITH reader AS (
+      SELECT u.id AS id, u.role AS role FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+      WHERE s.id = ? AND s.expires_at > ? AND ((? IS NULL AND s.viewer_session IS NULL) OR (s.viewer_session = ? AND EXISTS (
+        SELECT 1 FROM managed_session p JOIN managed_user a ON a.id = p.user_id
+        WHERE p.id = s.viewer_session AND p.expires_at > ? AND p.viewer_session IS NULL AND a.role = 'admin')))
+    )
+    SELECT v.id AS id, v.role AS role,
+      (SELECT json_group_array(x.scope ORDER BY x.scope) FROM (SELECT DISTINCT ns.scope AS scope FROM managed_team_user tu
+        JOIN managed_team t ON t.id = tu.team_id AND t.hidden = 0 JOIN managed_team_npm_scope ns ON ns.team_id = tu.team_id
+        WHERE tu.user_id = v.id) x) AS scopes,
+      CASE WHEN EXISTS (SELECT 1 FROM managed_team t JOIN managed_user u ON u.id = v.id WHERE t.id = ? AND ${reviewsIn(false)}) THEN 1 ELSE 0 END AS readsTeam
+    FROM reader v`).get(sessionId, now, viewerSessionId, viewerSessionId, now, teamId) as { id: string; role: Role; scopes: unknown; readsTeam: unknown } | undefined
+  return row ? { id: row.id, role: row.role, scopes: gathered<string>(row.scopes), readsTeam: Number(row.readsTeam) === 1 } : null
+}

package/server-managed/team-reports.ts

@@ -0,0 +1,319 @@
+// Team content is filtered as one workspace, with separate report envelopes.
+// Bounded snapshots retain filtered content and visibility for repeated reads.
+import { mergeLinkGroups } from './link-reports.ts'
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { backfillFindingIds, reportEntries, stampSecurityGroups } from '@preventive/report'
+import { managedFindingSourcePaths, readManagedReport } from '../common/managed/report-content.ts'
+import { filterReportData, projectFinding } from '../common/managed/report-filter.ts'
+import { revalidationLinks, securityLinks } from '../common/security-links.js'
+import { treeDependencyDirectory } from '../client/dependency-paths.js'
+import { liteWorkspace } from '../common/managed/finding-detail.js'
+import type { BlobStore } from './blob-store.ts'
+import type { ManagedDb, TeamReportAccessSnapshot } from './db.ts'
+import { triageWireEntry } from './triage-response.ts'
+import { visibleManagedIssues } from './managed-issues.ts'
+import { MAX_REPORT_QUERY_BYTES, MAX_REPORT_QUERY_COUNT } from './report-query.ts'
+
+type Finding = Record<string, unknown>
+type TeamReport = { id: string; filename: string; data: unknown; repo: { github: string | null; directory: string } }
+type ReportVisibility = { ids: Set<string>; sourcePaths: Set<string> }
+type Visibility = Map<string, ReportVisibility>
+const VISIBILITY_CACHE_MAX_ITEMS = 250_000
+const VISIBILITY_CACHE_MAX_SNAPSHOTS = 32
+const caches = new WeakMap<ManagedDb, Map<string, Visibility>>()
+const REPORT_CACHE_BYTES = 16 * 1024 * 1024
+// A workspace's encoded reports, the same without their findings' detail for
+// the board (`lite`), and its reports' file trees apart.
+type EncodedWorkspace = { reports: Buffer; lite: Buffer; trees: Buffer }
+export type TeamResponsePart = keyof EncodedWorkspace
+// The part a team's `reports` or `trees` route asks for.
+export const teamResponsePart = (route: string, url: URL): TeamResponsePart =>
+  route === 'trees' ? 'trees' : url.searchParams.get('lite') === '1' ? 'lite' : 'reports'
+const reportCaches = new WeakMap<ManagedDb, Map<string, EncodedWorkspace>>()
+const encodedBytes = ({ reports, lite, trees }: EncodedWorkspace) => reports.length + lite.length + trees.length
+// A workspace's report reads at once. Its reports' sizes are bounded together
+// before any is read, and each is held parsed till the build ends, so more at
+// once costs only the raw bytes in flight: a cold build of a team's reports
+// is so many storage round trips one after another.
+const WORKSPACE_READS_AT_ONCE = 16
+function retainReports(db: ManagedDb, key: string, encoded: EncodedWorkspace) {
+  if (encodedBytes(encoded) > REPORT_CACHE_BYTES) return
+  let cache = reportCaches.get(db)
+  if (!cache) { cache = new Map(); reportCaches.set(db, cache) }
+  cache.delete(key)
+  let total = encodedBytes(encoded) + [...cache.values()].reduce((sum, value) => sum + encodedBytes(value), 0)
+  for (const [oldest, value] of cache) {
+    if (total <= REPORT_CACHE_BYTES && cache.size < VISIBILITY_CACHE_MAX_SNAPSHOTS) break
+    cache.delete(oldest); total -= encodedBytes(value)
+  }
+  cache.set(key, encoded)
+}
+function visibilityWeight(visible: Visibility): number {
+  return [...visible.values()].reduce((sum, v) => sum + v.ids.size + v.sourcePaths.size, 0)
+}
+function retainVisibility(db: ManagedDb, key: string, visible: Visibility): void {
+  let cache = caches.get(db)
+  // Replacement contributes its weight once and does not evict a peer merely
+  // because the cache already holds the maximum number of snapshots.
+  cache?.delete(key)
+  const incoming = visibilityWeight(visible)
+  if (incoming > VISIBILITY_CACHE_MAX_ITEMS) return
+  if (!cache) { cache = new Map(); caches.set(db, cache) }
+  let total = incoming + [...cache.values()].reduce((sum, entry) => sum + visibilityWeight(entry), 0)
+  for (const [oldest, entry] of cache) {
+    if (cache.size < VISIBILITY_CACHE_MAX_SNAPSHOTS && total <= VISIBILITY_CACHE_MAX_ITEMS) break
+    cache.delete(oldest)
+    total -= visibilityWeight(entry)
+  }
+  cache.set(key, visible)
+}
+export class TeamReportsError extends Error {
+  status: number
+  constructor(status: number, error: string) { super(error); this.status = status }
+}
+export function teamSnapshotKey(snapshot: TeamReportAccessSnapshot): string {
+  return JSON.stringify([snapshot.user.id, snapshot.user.role, snapshot.teamId, snapshot.hiddenReportId ?? null, snapshot.reports, snapshot.repositories, snapshot.linkRevision])
+}
+// What a built workspace is kept by: everything its build reads, and nothing
+// of who asked. A user's role and grants decide which reports (and which
+// hidden preview) their snapshot holds and each one's permissions, all of it
+// in the key, so members whose snapshots agree share one build.
+function workspaceKey(snapshot: TeamReportAccessSnapshot): string {
+  return JSON.stringify([snapshot.teamId, snapshot.hiddenReportId ?? null, snapshot.reports, snapshot.repositories, snapshot.linkRevision])
+}
+export async function teamSnapshot(db: ManagedDb, sessionId: string, teamId: string, reportId: string | null = null): Promise<TeamReportAccessSnapshot> {
+  const snapshot = await db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId, reportId)
+  if (!snapshot) throw new TeamReportsError(401, 'unauthenticated')
+  if (!snapshot.teamId) throw new TeamReportsError(404, 'no-team')
+  if (reportId !== null && !snapshot.reports.some(report => report.id === reportId)) throw new TeamReportsError(404, 'no-report')
+  return snapshot
+}
+export async function recheckTeam(db: ManagedDb, sessionId: string, snapshot: TeamReportAccessSnapshot): Promise<void> {
+  if (teamSnapshotKey(await teamSnapshot(db, sessionId, snapshot.teamId!, snapshot.reportId)) !== teamSnapshotKey(snapshot)) throw new TeamReportsError(404, 'workspace-changed')
+}
+function groupsOf(data: unknown): Finding[][] {
+  return (reportEntries(data) ?? []).map(entry => (Array.isArray(entry) ? entry : [entry]).filter(
+    (finding): finding is Finding => finding !== null && typeof finding === 'object' && !Array.isArray(finding),
+  ))
+}
+function linksOf(data: unknown): string[][] | null {
+  const record = data as { source?: string; links?: string[][] }
+  if (record?.source !== 'links' || !Array.isArray(record.links)) return null
+  if (!record.links.every(ids => Array.isArray(ids) && ids.every(id => typeof id === 'string'))) throw new TeamReportsError(422, 'unreadable-links')
+  return record.links
+}
+// A report's file tree goes apart, asked for by its graph or Files alone
+// (loadTeamTreesResponse). The report tells in its place how many files it
+// holds (`treeFiles`) and the dependency directory it names
+// (`treeDependencies`), which classifies findings as the tree itself would
+// (client/dependency-paths.js). Each file's is sent without the hash of its
+// tree (`treeHash`), which no team view reads.
+function withoutTree(report: TeamReport): string | null {
+  const tree = (report.data as { tree?: unknown } | null)?.tree
+  if (!tree || typeof tree !== 'object' || Array.isArray(tree)) return null
+  const { tree: _tree, ...data } = report.data as Finding
+  const named = treeDependencyDirectory(tree)
+  report.data = { ...data, treeFiles: Object.keys(tree).length, ...(named ? { treeDependencies: named } : {}) }
+  const files = Object.entries(tree).map(([file, entry]) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return [file, entry]
+    const { treeHash: _treeHash, ...kept } = entry as Finding
+    return [file, kept]
+  })
+  return `${JSON.stringify(report.id)}:${JSON.stringify(Object.fromEntries(files))}`
+}
+async function buildTeamWorkspace(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<EncodedWorkspace & { visible: Visibility }> {
+  if (snapshot.reports.length > MAX_REPORT_QUERY_COUNT || snapshot.reports.reduce((n, r) => n + r.byteSize, 0) > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+  const reports: TeamReport[] = []
+  let inputBytes = 0, next = 0
+  // Bound both remote reads and raw buffers, retaining stable report order for
+  // the cross-report classification that follows. Finish workers on failure.
+  const results = await Promise.allSettled(Array.from({ length: Math.min(WORKSPACE_READS_AT_ONCE, snapshot.reports.length) }, async () => {
+    while (next < snapshot.reports.length) {
+      const index = next++
+      const access = snapshot.reports[index]!
+
+      const bytes = await store.get(access.id)
+      if (!bytes) throw new TeamReportsError(503, 'unavailable')
+      inputBytes += bytes.length
+      if (inputBytes > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+      const parsed = readManagedReport(bytes.toString('utf8'), access.filename)
+      if (!parsed.data) throw new TeamReportsError(422, 'unreadable-report')
+      // Backfill before filtering so links, annotations and the client agree on
+      // IDs even when hiding a component would change the original row shape.
+      await backfillFindingIds(groupsOf(parsed.data).flat())
+      reports[index] = { id: access.id, filename: access.filename, data: parsed.data, repo: access.repo }
+    }
+  }))
+  for (const result of results) if (result.status === 'rejected') throw result.reason
+  const globalLinks = snapshot.linkRevision ? await db.getEnabledLinkGroups(snapshot.linkRevision) : []
+  const groups = reports.flatMap(report => groupsOf(report.data).map(group => group.map(f => projectFinding(f, report.data as Finding)!)))
+  // Unknown IDs can connect known findings. App findings link to the inputs
+  // they revalidated in other reports, as the App view counts them.
+  stampSecurityGroups(groups, { linkedIds: securityLinks([
+    ...globalLinks, ...reports.flatMap(report => linksOf(report.data) ?? []), ...revalidationLinks(groups.flat()),
+  ]).linkedIds })
+  const securityIds = new Set(groups.flat().filter(f => f['isSecurity'] === true).map(f => String(f['id'])))
+  const allIds = new Set<string>(), visible: Visibility = new Map()
+  for (let i = 0; i < reports.length; i++) {
+    const access = snapshot.reports[i]!, report = reports[i]!
+    report.data = filterReportData(report.data, access.permissions, access.repo, securityIds)
+    if (report.data && typeof report.data === 'object' && 'think' in report.data) {
+      const { think: _think, ...data } = report.data as Finding
+      report.data = data
+    }
+    const ids = new Set<string>()
+    for (const finding of groupsOf(report.data).flat()) {
+      // Preserve linked security classification for the UI lens, including a
+      // linked component that a dependency permission will hide from the UI.
+      finding['isSecurity'] = securityIds.has(String(finding['id']))
+      // The hash of its file's tree, the fingerprint its ID was derived from
+      // and whether its run thought, which nothing a team view reads, nor an
+      // export (@preventive/report write-md-finding.js) writes.
+      delete finding['treeHash']
+      delete finding['_idBasis']
+      delete finding['think']
+      if (typeof finding['id'] === 'string') { ids.add(finding['id']); allIds.add(finding['id']) }
+    }
+    visible.set(report.id, { ids, sourcePaths: managedFindingSourcePaths(groupsOf(report.data).flat()) })
+  }
+  for (const report of reports) {
+    const links = linksOf(report.data)
+    // Hidden previews are independently authorized; preserve a hidden links
+    // document even though its referenced findings are outside this response.
+    if (links && !snapshot.hiddenReportId) report.data = { source: 'links', findings: [], links: links.map(ids => [...new Set(ids.filter(id => allIds.has(id)))]).filter(ids => ids.length >= 2) }
+  }
+  const trees = Buffer.from(`{"trees":{${reports.map(withoutTree).filter(tree => tree !== null).join(',')}}}`)
+  const links = mergeLinkGroups(globalLinks, allIds)
+  // The board's: its findings without their detail, and in App mode its rows
+  // as the App view shows them (common/managed/finding-detail.js).
+  const lite = liteWorkspace(reports, links)
+  const encoded = {
+    // Bounded together, as when the trees were sent with their reports.
+    reports: encodeReports(reports, links, trees.length),
+    lite: encodeReports(lite.reports, links, 0, lite.folded),
+    trees,
+  }
+  retainVisibility(db, workspaceKey(snapshot), visible)
+  retainReports(db, workspaceKey(snapshot), encoded)
+  return { ...encoded, visible }
+}
+// `{ reports, links }` as a response sends them, `spent` bytes already
+// counted against the bound; `folded` where the board's copy left out rows
+// App mode does not show (common/managed/finding-detail.js).
+function encodeReports(reports: readonly TeamReport[], links: readonly string[][], spent: number, folded = false): Buffer {
+  let outputBytes = spent + 14
+  const parts = [Buffer.from('{"reports":[')]
+  for (const [index, report] of reports.entries()) {
+    const bytes = Buffer.from(JSON.stringify(report))
+    outputBytes += bytes.length + 1
+    if (outputBytes > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+    if (index) parts.push(Buffer.from(','))
+    parts.push(bytes)
+  }
+  const tail = JSON.stringify({ ...links.length > 0 ? { links } : {}, ...folded ? { folded } : {} })
+  const suffix = Buffer.from(tail === '{}' ? ']}' : `],${tail.slice(1)}`)
+  if (outputBytes + suffix.length > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+  parts.push(suffix)
+  return Buffer.concat(parts)
+}
+const pendingWorkspaces = new WeakMap<ManagedDb, Map<string, ReturnType<typeof buildTeamWorkspace>>>()
+async function loadTeamWorkspace(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot) {
+  let pending = pendingWorkspaces.get(db)
+  if (!pending) { pending = new Map(); pendingWorkspaces.set(db, pending) }
+  const key = workspaceKey(snapshot)
+  const existing = pending.get(key)
+  if (existing) return existing
+  const job = buildTeamWorkspace(db, store, snapshot)
+  pending.set(key, job)
+  try { return await job } finally { pending.delete(key) }
+}
+// Treat the encoded body as immutable and recheck access before sending it.
+// Warm HTTP reads need neither a parsed copy nor another serialization pass.
+// Its `lite` reports and its `trees`, by report ID (withoutTree), are of the
+// same snapshot and take the same recheck.
+export async function loadTeamReportsResponse(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot,
+  part: TeamResponsePart = 'reports'): Promise<Buffer> {
+  const cached = reportCaches.get(db)?.get(workspaceKey(snapshot))
+  return cached?.[part] ?? (await loadTeamWorkspace(db, store, snapshot))[part]
+}
+export async function loadTeamReports(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<TeamReport[]> {
+  // Object consumers get their own copy, including when sharing a cold load.
+  const body = await loadTeamReportsResponse(db, store, snapshot)
+  return (JSON.parse(body.toString('utf8')) as { reports: TeamReport[] }).reports
+}
+async function teamVisibility(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Visibility> {
+  let visible = caches.get(db)?.get(workspaceKey(snapshot))
+  if (!visible) {
+    // A large snapshot may deliberately remain uncached, or be evicted by
+    // another request. Authorization uses this load's result in either case.
+    visible = (await loadTeamWorkspace(db, store, snapshot)).visible
+  }
+  return visible
+}
+export async function teamWorkspaceFindingIds(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Set<string>> {
+  const ids = new Set<string>()
+  for (const report of (await teamVisibility(db, store, snapshot)).values()) for (const id of report.ids) ids.add(id)
+  return ids
+}
+
+// What a focused team's annotations are at, for the snapshot reading them, as
+// its feed tells it (team-feed.ts serveUserTeamFeed) and its annotations
+// answer it (loadTeamAnnotations): the snapshot's key and the revision of
+// every visible finding's annotations (getAnnotationRevision), its workspace's
+// findings being `ids` (teamWorkspaceFindingIds).
+export async function teamAnnotationRevision(db: ManagedDb, snapshot: TeamReportAccessSnapshot, ids: readonly string[]): Promise<string> {
+  return JSON.stringify([teamSnapshotKey(snapshot), await db.getAnnotationRevision(ids)])
+}
+
+// A revision as the client is told it: a digest, telling only whether what it
+// covers changed, none of the finding IDs, batches or issues it is read from.
+export const annotationRevisionDigest = (revision: string): string => createHash('sha256').update(revision).digest('base64url')
+export async function teamReportVisibility(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot, reportId: string): Promise<ReportVisibility> {
+  if (!snapshot.reports.some(r => r.id === reportId)) throw new TeamReportsError(404, 'no-report')
+  const visible = await teamVisibility(db, store, snapshot)
+  return visible.get(reportId)!
+}
+// A report's visibility for the session's current snapshot. A workspace built
+// (or waited for) here outlives that snapshot's read, so the team's access is
+// read again after it; one kept is answered with no read in between, which
+// leaves nothing for another snapshot read to guard.
+async function sessionReportVisibility(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<ReportVisibility> {
+  const snapshot = await teamSnapshot(db, sessionId, teamId, reportId)
+  const kept = caches.get(db)?.get(workspaceKey(snapshot))?.get(reportId)
+  if (kept) return kept
+  const visible = await teamReportVisibility(db, store, snapshot, reportId)
+  await recheckTeam(db, sessionId, snapshot)
+  return visible
+}
+export async function teamFindingIds(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<Set<string>> {
+  return (await sessionReportVisibility(db, store, sessionId, teamId, reportId)).ids
+}
+export async function teamSourcePaths(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<Set<string>> {
+  return (await sessionReportVisibility(db, store, sessionId, teamId, reportId)).sourcePaths
+}
+
+// Serialize shared annotation bodies once. Reports carry only the annotated
+// finding IDs visible in that report; callers revalidate access before sending.
+// With them, the digest of the revision the whole workspace's are at, as the
+// team's feed tells it (`revision`), read before them: a write between leaves
+// it older than what is sent, so the feed's next differs and the client reads
+// again, never the reverse.
+export async function loadTeamAnnotations(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot, reportId: string | null = null) {
+  // Restrict annotation reads only after classifying the complete workspace:
+  // links and findings in other reports can affect this report's visibility.
+  if (reportId !== null && !snapshot.reports.some(r => r.id === reportId)) throw new TeamReportsError(404, 'no-report')
+  const workspace = await teamVisibility(db, store, snapshot)
+  const visible = reportId === null ? workspace : new Map([[reportId, workspace.get(reportId)!]])
+  const all = new Set<string>(), ids = new Set<string>()
+  for (const report of visible.values()) for (const id of report.ids) ids.add(id)
+  for (const report of workspace.values()) for (const id of report.ids) all.add(id)
+  const revision = await teamAnnotationRevision(db, snapshot, [...all])
+  const { triage, comments, issues: savedIssues } = await db.getAnnotations([...ids])
+  const issues = Object.fromEntries(visibleManagedIssues(savedIssues, snapshot)
+    .map(issue => [issue.findingId, { url: issue.issueUrl!, autoFix: issue.autoFixUrl }]))
+  const entries = Object.fromEntries(triage.map(row => [row.findingId, triageWireEntry(row)]))
+  const annotated = new Set([...triage.map(row => row.findingId), ...comments.map(comment => comment.findingId), ...Object.keys(issues)])
+  const reports = Object.fromEntries([...visible].map(([id, report]) => [id, [...report.ids].filter(finding => annotated.has(finding))]))
+  return { reports, entries, comments, issues, revision: annotationRevisionDigest(revision) }
+}

package/server-managed/triage-response.ts

@@ -0,0 +1,16 @@
+import type { TriageRow } from './db.ts'
+import { type TriageEntryPatch, isTriageBucket } from '../common/managed/triage.ts'
+
+// A stored triage row (current state or a trail event) → its wire entry: only
+// set fields present, `false` kept for flagged (the explicit un-flag tombstone
+// must round-trip), and null for the row of a cleared entry (every field
+// null) — the reader adopts the clear.
+export function triageWireEntry(row: Pick<TriageRow, 'color' | 'triage' | 'comment' | 'fix' | 'flagged'>, legacyHistory = false): TriageEntryPatch | null {
+  const e: TriageEntryPatch = {}
+  if (row.color != null) e.color = row.color
+  if (isTriageBucket(row.triage)) e.triage = row.triage
+  if (legacyHistory && row.comment != null) e.comment = row.comment
+  if (row.fix != null) e.fix = row.fix
+  if (row.flagged != null) e.flagged = row.flagged
+  return Object.keys(e).length > 0 ? e : null
+}

package/server-managed/type-only-worker.js

@@ -0,0 +1,19 @@
+// Which of a comparison's pairs of files changed in types alone (type-only.ts),
+// as @preventive/compare's compareTrees stamps a change `typeOnly`, off the
+// server's event loop: each pair a tree of a file a side, a side not there
+// none, its paths as they are, which say what a file is. Two paths pair as one
+// change wherever compareTrees takes them for a rename at all; where it
+// doesn't, the pair is types only where each of its two changes is: the file
+// gone erasing whole, and the one come erasing whole or leaving a single bare
+// `export {}`, which nothing loaded before. `[true, false, ...]` by pair.
+import { parentPort, workerData } from 'node:worker_threads'
+import { compareTrees } from '@preventive/compare'
+
+const tree = file => (file ? [{ name: file.path, data: file.text }] : [])
+const answer = workerData.pairs.map(([from, to]) => {
+  const changes = compareTrees(tree(from), tree(to), { paths: 'keys', lines: false, renames: Number.MIN_VALUE })
+  return changes.length > 0 && changes.every(change => change.typeOnly === true)
+})
+// Node worker messages have no browser target origin.
+// oxlint-disable-next-line unicorn/require-post-message-target-origin
+parentPort.postMessage(answer)

package/server-managed/type-only.ts

@@ -0,0 +1,105 @@
+// Compare's changes to TypeScript declaration files in types alone (GET
+// /api/bundles/:id/type-only?other=, GET /api/npm/type-only): every file
+// that changed between a comparison's two sides, added and removed ones too,
+// paired as its viewer pairs them (rename-diff.ts comparedFiles), whose
+// change @preventive/compare's compareTrees stamps
+// `typeOnly` -- each side there a file named as a declaration file and
+// proven to hold types alone but for a runtime, the module loads and
+// `export {}` its stripping leaves, that the change leaves as it was, an
+// added one's empty or a single bare `export {}` (proveTypeOnly) -- and
+// nothing else. Proven in a worker, off the event loop, a comparison at a
+// time per process, for at most a minute; told a line each, `{ path, hash,
+// otherPath, otherHash }`, a side not there null, which the viewer checks
+// name the files it shows. Access is the caller's to check.
+import { Worker } from 'node:worker_threads'
+import { type ComparedSide, PrettyError, type PrettyRequest } from './pretty-print.ts'
+import { comparedFiles } from './rename-diff.ts'
+
+// TypeScript files, by extension as the pretty-print cache reads them: none
+// other is asked about.
+const TYPESCRIPT = new Set(['ts', 'mts', 'cts'])
+// Comparisons proven at once per process, and those waiting their turn past
+// them, any more refused; the longest one may take, its wait included.
+const MAX_ACTIVE_PROOFS = 1
+const MAX_WAITING_PROOFS = 16
+const PROOF_TIMEOUT_MS = 60_000
+
+type File = PrettyRequest & { text: string }
+export interface TypeOnlyLine { path: string | null; hash: string | null; otherPath: string | null; otherHash: string | null }
+
+let active = 0
+const waiting: Array<() => void> = []
+
+async function turn(deadline: number): Promise<void> {
+  if (active < MAX_ACTIVE_PROOFS) { active++; return }
+  if (waiting.length >= MAX_WAITING_PROOFS) throw new PrettyError(429, 'proof-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, 'proof-timeout'))
+    }, deadline - Date.now())
+    waiting.push(next)
+  })
+}
+function done() {
+  const next = waiting.shift()
+  if (next) next()
+  else active--
+}
+
+// Which of `pairs` compareTrees stamps types only, by index, in a worker
+// settled once it is gone; none where it fails, as no proof should.
+function proven(pairs: Array<[File | null, File | null]>, deadline: number): Promise<boolean[]> {
+  let worker: Worker
+  try {
+    worker = new Worker(new URL('./type-only-worker.js', import.meta.url), {
+      workerData: { pairs: pairs.map(sides => sides.map(file => file && { path: file.path, text: file.text })) },
+      // Node's type stripping, which the proof holds oxc's tree to, warns it is experimental.
+      execArgv: ['--disable-warning=ExperimentalWarning'], resourceLimits: { maxOldGenerationSizeMb: 1024 },
+    })
+  } catch (err) {
+    console.warn('managed: a type-only proof could not start:', err)
+    throw new PrettyError(503, 'unavailable')
+  }
+  return new Promise((resolve, reject) => {
+    let answer: boolean[] | null = null, failure = new PrettyError(422, 'unproven')
+    const timer = setTimeout(() => { failure = new PrettyError(504, 'proof-timeout'); void worker.terminate() }, deadline - Date.now())
+    worker.once('message', (told: unknown) => {
+      if (Array.isArray(told) && told.length === pairs.length && told.every(one => typeof one === 'boolean')) answer = told
+      void worker.terminate()
+    })
+    worker.once('error', err => { console.warn('managed: a type-only proof failed:', err) })
+    worker.once('exit', () => {
+      clearTimeout(timer)
+      if (answer) resolve(answer)
+      else reject(failure)
+    })
+  })
+}
+
+// The files that changed between a comparison's two sides in types alone,
+// as the viewer pairs them, a line each once all are proven, in path order.
+export function typeOnlyFiles([base, other]: readonly [ComparedSide, ComparedSide]): AsyncGenerator<TypeOnlyLine> {
+  const typescript = ({ files }: ComparedSide) => new Map(files.filter(file => TYPESCRIPT.has(file.extension)).map(file => [file.path, file]))
+  const [olds, news] = [typescript(base), typescript(other)]
+  const { changed, onlyBase, onlyOther } = comparedFiles([base, other])
+  // A side there not a TypeScript file this reads leaves its pair out; one not there is null.
+  const pairs = [...changed.map(({ path, basePath = path }) => [olds.get(basePath), news.get(path)]),
+    ...onlyBase.map(({ path, basePath = path }) => [olds.get(basePath), null]), ...onlyOther.map(({ path }) => [null, news.get(path)])]
+    .filter((sides): sides is [File | null, File | null] => sides.every(file => file !== undefined) && sides.some(file => file !== null) && sides[0]?.hash !== sides[1]?.hash)
+    .toSorted(([a, b], [c, d]) => {
+      const [x, y] = [(b ?? a)!.path, (d ?? c)!.path]
+      return x < y ? -1 : x > y ? 1 : 0
+    })
+  return (async function* () {
+    if (pairs.length === 0) return
+    const deadline = Date.now() + PROOF_TIMEOUT_MS
+    await turn(deadline)
+    let stamped
+    try { stamped = await proven(pairs, deadline) } finally { done() }
+    for (const [i, [from, to]] of pairs.entries()) {
+      if (stamped[i]) yield { path: from?.path ?? null, hash: from?.hash ?? null, otherPath: to?.path ?? null, otherHash: to?.hash ?? null }
+    }
+  })()
+}