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

package/server-managed/import-triage.ts

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto'
+import type { ManagedDb } from './db-methods.ts'
+import type { ManagedComment } from '../common/managed/comments.ts'
+import type { TriageEntryPatch } from '../common/managed/triage.ts'
+import { triageWireEntry } from './triage-response.ts'
+
+export interface ImportTriageSnapshot {
+  entry: TriageEntryPatch | null
+  comments: ManagedComment[]
+  version: string
+}
+export interface ImportTriageStore {
+  getImportTriage(ids: readonly string[]): Promise<Record<string, ImportTriageSnapshot>>
+  importTriage(entries: [string, TriageEntryPatch | null][], expected: Record<string, string>, actor: { id: string; login: string }, reportId: string, now: number): Promise<boolean>
+}
+
+// Raw store methods share one transaction for comparison, triage, and comments.
+export function importTriageMethods(store: Pick<ManagedDb, 'getReport' | 'listTriage' | 'listComments' | 'setTriageEntries' | 'createComment'>): ImportTriageStore {
+  async function snapshot(ids: readonly string[]) {
+    const rows = new Map((await store.listTriage(ids)).map(row => [row.findingId, row]))
+    const comments = await store.listComments(ids)
+    return Object.fromEntries(ids.map(id => {
+      const row = rows.get(id)
+      const entry = row ? triageWireEntry(row) : null
+      const own = comments.filter(comment => comment.findingId === id)
+      const version = createHash('sha256').update(JSON.stringify([entry, row?.updatedAt, own])).digest('hex')
+      return [id, { entry, comments: own, version }]
+    }))
+  }
+  return {
+    getImportTriage: snapshot,
+    async importTriage(entries, expected, actor, reportId, now) {
+      // A report deleted after the HTTP membership check must not leave newly
+      // imported annotations behind. Check existence in the write transaction.
+      if (!reportId || !(await store.getReport(reportId))) return false
+      const current = await snapshot(entries.map(([id]) => id))
+      if (entries.some(([id]) => current[id]!.version !== expected[id])) return false
+      const changes: [string, TriageEntryPatch | null][] = []
+      for (const [id, value] of entries) {
+        const { comment, ...entry } = value ?? {}
+        changes.push([id, Object.keys(entry).length > 0 ? entry : null])
+        if (comment && !current[id]!.comments.some(existing => existing.body === comment)) {
+          await store.createComment({ findingId: id, body: comment, authorId: null, authorLogin: null,
+            actor, createdAt: null, updatedAt: null, reportId }, now)
+        }
+      }
+      await store.setTriageEntries(changes, actor.id, actor.login, now, reportId)
+      return true
+    },
+  }
+}

package/server-managed/index.ts

@@ -0,0 +1,192 @@
+// Managed HTTP app and standalone boot. The combined launcher mounts this
+// same app on e2e's listener; storage, routing and cleanup stay here.
+import { randomUUID } from 'node:crypto'
+import { type Server, createServer } from 'node:http'
+import { fileURLToPath } from 'node:url'
+import { createOriginGate } from '../server-common/origin.ts'
+import { managedStorageLines } from '../server-common/storage-log.ts'
+import { runReapers, withReap } from '../server-common/reap.ts'
+import { startServer } from '../server-common/standalone.ts'
+import { initializeApp } from '../server-common/initialize.ts'
+import { type ManagedConfig, loadManagedConfig } from './config.ts'
+import { type ManagedHttpDeps, createManagedRequestHandler } from './http.ts'
+import { setNpmTarballCache } from './npm-loads.ts'
+import { assembledReviewedDependencies } from './reviewed-dependencies.ts'
+import { setNpmDocumentCache } from './npm-packages.ts'
+import { loadManagedStatic } from './static.ts'
+import { openManagedStorage } from './storage.ts'
+import { setCacheDir } from '@preventive/upstream/npm.js'
+
+// Housekeeping runs on ordinary traffic too, including serverless instances
+// without a timer or cron. Failed sweeps retry on later traffic after a minute.
+const REAP_INTERVAL_MS = 3_600_000
+const REAP_RETRY_MS = 60_000
+
+// `ui: false` serves only the API: `out/` is never read.
+type ManagedAppOptions = Partial<Pick<ManagedHttpDeps, 'next' | 'serverInfo' | 'isShuttingDown' | 'reviewedDependencies'>> & { ui?: boolean }
+
+export async function createManagedApp(config: ManagedConfig, options: ManagedAppOptions = {}) {
+  // Audits keep upstream's records on disk where the config has a cache
+  // directory; bundle builds set it in their own worker. The npm viewer
+  // keeps the tarballs it downloads there too, beside theirs, and public
+  // packages' whole documents (npm-packages.ts).
+  setCacheDir(config.upstreamCacheDir ?? false)
+  setNpmTarballCache(config.upstreamCacheDir ?? null)
+  setNpmDocumentCache(config.upstreamCacheDir ?? null)
+  // Load the optional peer only for serverless managed deployments. Embedding
+  // hosts can discard listener promises, so retain maintenance inside the app.
+  const waitUntil = config.serverless ? (await import('@vercel/functions')).waitUntil : undefined
+  // The host's reviewed dependencies, registered before; none after.
+  const reviewedDependencies = assembledReviewedDependencies()
+  const assembled = { ...options, ...reviewedDependencies ? { reviewedDependencies } : {} }
+  return await initializeApp(rollback => assembleManagedApp(config, assembled, rollback, waitUntil))
+}
+
+async function assembleManagedApp(config: ManagedConfig, { ui = true, ...options }: ManagedAppOptions, rollback: AsyncDisposableStack, waitUntil?: (promise: Promise<unknown>) => void) {
+  const storage = await openManagedStorage(config)
+  const { db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache, prettyCache, npmCacheStorage, repositoryCodeStorage } = storage
+  rollback.defer(() => db.close())
+  const originGate = createOriginGate(config.host, config.trustProxyEnv)
+
+  let shuttingDown = false
+  const isShuttingDown = () => shuttingDown || options.isShuttingDown?.() === true
+  const inFlight = new Set<Promise<unknown>>()
+  function track(p: Promise<unknown>): void {
+    inFlight.add(p)
+    p.finally(() => inFlight.delete(p)).catch(() => {})
+  }
+
+  const serveStatic = ui ? loadManagedStatic(fileURLToPath(new URL('../out/', import.meta.url)), {
+    indexOnly: options.next != null, scanServer: options.serverInfo?.deepviewScanServer ?? null,
+  }) : () => false
+  const routeRequest = createManagedRequestHandler({
+    ...options, config, db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache, prettyCache, npmCacheStorage, repositoryCodeStorage, originGate, serveStatic,
+    ...(storage.uploadStore ? { uploadStore: storage.uploadStore } : {}), ...(waitUntil ? { waitUntil } : {}),
+    isShuttingDown, track,
+  })
+
+  let cleanup: Promise<void> | undefined, nextCleanupAt = 0
+  const maintenance = new AbortController()
+  function reap(automatic = false): Promise<void> {
+    if (cleanup) return cleanup
+    if (isShuttingDown()) return Promise.resolve()
+    const startedAt = Date.now()
+    nextCleanupAt = startedAt + REAP_INTERVAL_MS
+    let sessions = 0, uploads = 0
+    cleanup = (async () => {
+      const owner = automatic && config.serverless ? randomUUID() : null
+      if (owner && !await db.claimMaintenanceLease(owner, startedAt, startedAt + Math.max(300_000, (config.storageEncryptionMigrateMaxMs ?? 0) + 60_000), config.storageEncryptionMigrate)) return false
+      let succeeded = false
+      try {
+        await runReapers({
+          sessions: async () => { sessions = await db.deleteExpiredSessions(Date.now()) },
+          ...(storage.reapUploads ? { uploads: async () => { uploads = await storage.reapUploads!(maintenance.signal) } } : {}),
+          ...('reapPrettyCopies' in storage ? { prettyCopies: () => storage.reapPrettyCopies(maintenance.signal) } : {}),
+          ...('reapStorage' in storage ? { storage: () => storage.reapStorage(maintenance.signal) } : {}),
+        })
+        succeeded = true
+        return true
+      } finally {
+        if (owner) await db.finishMaintenanceLease(owner, Date.now() + (succeeded ? REAP_INTERVAL_MS : REAP_RETRY_MS))
+      }
+    })().then(ran => {
+      nextCleanupAt = Date.now() + REAP_INTERVAL_MS
+      if (!ran) return
+      return console.info(`managed-reaper: removed ${sessions} expired session(s), ${uploads} stale upload part(s) in ${Date.now() - startedAt}ms`)
+    }, err => {
+      nextCleanupAt = Date.now() + REAP_RETRY_MS
+      throw err
+    }).finally(() => { cleanup = undefined })
+    track(cleanup)
+    return cleanup
+  }
+  function automaticReap(): Promise<void> {
+    if (isShuttingDown() || cleanup || Date.now() < nextCleanupAt) return Promise.resolve()
+    return reap(true).catch(err => console.warn('managed-reaper: cleanup failed:', err))
+  }
+  async function handleRequest(req: Parameters<typeof routeRequest>[0], res: Parameters<typeof routeRequest>[1]): Promise<void> {
+    // Register before routing can end the response, including when init()'s
+    // listener is mounted in Fastify rather than using api/managed.ts.
+    const pendingMaintenance = automaticReap(); waitUntil?.(pendingMaintenance)
+    try { await routeRequest(req, res) }
+    finally { await pendingMaintenance }
+  }
+  const gcTimer = config.serverless ? null : setInterval(() => {
+    void automaticReap()
+  }, REAP_INTERVAL_MS)
+  rollback.defer(stop)
+
+  function stop(): void {
+    shuttingDown = true
+    maintenance.abort()
+    if (gcTimer) clearInterval(gcTimer)
+  }
+
+  async function close(): Promise<void> {
+    stop()
+    if (inFlight.size > 0) await Promise.allSettled([...inFlight])
+    await db.close()
+  }
+  return { handleRequest, reap, isShuttingDown, stop, close }
+}
+
+export function logManagedStartup(config: ManagedConfig, port: number, mode = 'managed'): void {
+  console.log([
+    `DeepView managed server (${mode}):`,
+    `  HTTP: http://${config.host}:${port}/`,
+    ...managedStorageLines(config),
+  ].join('\n'))
+}
+
+export async function init(config = loadManagedConfig(), options: Pick<ManagedAppOptions, 'ui'> = {}): Promise<Server> {
+  const app = await createManagedApp(config, options)
+  const server = createServer(withReap(app.handleRequest, { managed: app.reap }, { isShuttingDown: app.isShuttingDown }))
+  let disposal: Promise<void> | undefined
+  function dispose(): Promise<void> {
+    if (!disposal) {
+      app.stop()
+      disposal = (async () => {
+        try {
+          if (server.listening) {
+            await new Promise<void>((resolve, reject) => {
+              server.close(err => { if (err) reject(err); else resolve() })
+            })
+          }
+        } finally {
+          try { await app.close() }
+          finally {
+            server.off('error', onError)
+            server.off('close', onClose)
+            server.off('listening', onListening)
+          }
+        }
+      })()
+    }
+    return disposal
+  }
+  // Embedding hosts can await full cleanup even when they only copied the
+  // request listener and never bound this server. Repeated disposal is safe.
+  server[Symbol.asyncDispose] = dispose
+
+  function onError(): void { onClose() }
+  function onClose(): void {
+    if (!disposal) void dispose().catch(err => { console.error('Managed server cleanup failed:', err) })
+  }
+  function onListening(): void {
+    const address = server.address()
+    const port = typeof address === 'object' && address ? address.port : config.port
+    logManagedStartup(config, port)
+  }
+  server.on('error', onError)
+  server.once('close', onClose)
+  server.on('listening', onListening)
+  return server
+}
+
+export async function start(): Promise<void> {
+  const config = loadManagedConfig()
+  const server = await init(config)
+  startServer(server, config)
+}
+
+if (import.meta.main) await start()

package/server-managed/kept-briefly.ts

@@ -0,0 +1,37 @@
+// What was lately worked out, kept a little while in memory for whoever asks
+// for it next, by key: each for `keptMs` from when it was kept, the least
+// lately read going first past `maxEntries` of them or `maxBytes` between
+// them, and one that alone takes more than `maxBytes` not kept at all.
+// Whoever reads one is the caller's to check, as they would one worked out.
+export function keptBriefly<T>({ keptMs, maxBytes, maxEntries = Infinity }: { keptMs: number; maxBytes: number; maxEntries?: number }) {
+  const held = new Map<string, { value: T; bytes: number; timer: ReturnType<typeof setTimeout> }>()
+  let heldBytes = 0
+  const forget = (key: string) => {
+    const entry = held.get(key)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    held.delete(key)
+    heldBytes -= entry.bytes
+  }
+  return {
+    get(key: string): T | undefined {
+      const entry = held.get(key)
+      if (!entry) return undefined
+      held.delete(key)
+      held.set(key, entry)
+      return entry.value
+    },
+    keep(key: string, value: T, bytes: number) {
+      if (bytes > maxBytes) return
+      forget(key)
+      for (const old of held.keys()) {
+        if (held.size < maxEntries && heldBytes + bytes <= maxBytes) break
+        forget(old)
+      }
+      const timer = setTimeout(() => { forget(key) }, keptMs)
+      timer.unref()
+      held.set(key, { value, bytes, timer })
+      heldBytes += bytes
+    },
+  }
+}

package/server-managed/kept.ts

@@ -0,0 +1,28 @@
+// Answers kept for an hour, by what they answer (npm-insights.ts,
+// npm-provenance.ts), at most `max` of them, the oldest asked going first;
+// one still being asked for is shared, and one that failed, or that `whole`
+// says is partial, is dropped once it is answered. `peek` gives one already
+// answered, asking for nothing; undefined where none is.
+const KEPT_MS = 60 * 60_000
+
+export function kept<T>(max: number, whole: (value: T) => boolean = () => true) {
+  const answers = new Map<string, { at: number; value: Promise<T>; answered?: { value: T } }>()
+  const get = (key: string, ask: () => Promise<T>): Promise<T> => {
+    const now = Date.now()
+    const hit = answers.get(key)
+    if (hit && now - hit.at < KEPT_MS) return hit.value
+    const value = ask()
+    const entry: { at: number; value: Promise<T>; answered?: { value: T } } = { at: now, value }
+    answers.delete(key)
+    answers.set(key, entry)
+    while (answers.size > max) answers.delete(answers.keys().next().value!)
+    const drop = () => { if (answers.get(key) === entry) answers.delete(key) }
+    value.then(answer => { if (whole(answer)) entry.answered = { value: answer }; else drop(); return answer }, drop)
+    return value
+  }
+  const peek = (key: string): T | undefined => {
+    const hit = answers.get(key)
+    return hit?.answered && Date.now() - hit.at < KEPT_MS ? hit.answered.value : undefined
+  }
+  return Object.assign(get, { peek })
+}

package/server-managed/link-reports.ts

@@ -0,0 +1,162 @@
+// Global deduplication reports live entirely in SQL. The payload is authenticated
+// ciphertext bound to its row, using the deployment's existing storage key.
+import { Buffer } from 'node:buffer'
+import { createHash, randomUUID } from 'node:crypto'
+import { type StorageKey, unwrapStorageValue, wrapStorageValue } from '../server-common/storage-crypto.ts'
+import { parseLinkedFindings } from '../client/linked-findings.js'
+import type { ManagedSql } from './sql.ts'
+import { ManagedMutationError } from './management.ts'
+
+export const LINK_REPORT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_link_report (
+  id TEXT PRIMARY KEY, filename TEXT NOT NULL, sha256 TEXT NOT NULL UNIQUE,
+  encrypted_groups TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 1,
+  group_count INTEGER NOT NULL, finding_count INTEGER NOT NULL,
+  uploaded_by TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  uploaded_by_login TEXT, uploaded_at INTEGER NOT NULL
+) STRICT;
+`
+export interface LinkReport {
+  id: string; filename: string; enabled: boolean; groupCount: number; findingCount: number
+  uploadedByLogin: string | null; uploadedAt: number
+}
+export interface LinkReportStore {
+  listLegacyLinkReports(): Promise<{ id: string; filename: string }[]>
+  migrateLinkReport(id: string, content: string): Promise<boolean>
+  listLinkReports(): Promise<LinkReport[]>
+  getLinkReport(sessionId: string, id: string): Promise<LinkReport & { groups: string[][] }>
+  getLinkRevision(): Promise<string>
+  getEnabledLinkGroups(revision: string): Promise<string[][]>
+  importLinkReport(sessionId: string, filename: string, content: string): Promise<{ report: LinkReport; reused: boolean }>
+  setLinkReportEnabled(sessionId: string, id: string, enabled: boolean): Promise<void>
+}
+const columns = `id, filename, enabled, group_count AS groupCount, finding_count AS findingCount,
+  uploaded_by_login AS uploadedByLogin, uploaded_at AS uploadedAt`
+const identity = (id: string) => `managed_link_report.encrypted_groups:${id}`
+function decryptGroups(key: StorageKey | null, id: string, payload: string): string[][] {
+  if (!key) throw new ManagedMutationError(503, 'storage-encryption-required')
+  const plain = unwrapStorageValue(key, identity(id), payload)
+  try { return JSON.parse(plain.toString('utf8')) as string[][] } finally { plain.fill(0) }
+}
+export async function linkRevision(db: ManagedSql): Promise<string> {
+  return linkRevisionOf(await db.prepare('SELECT id, sha256 FROM managed_link_report WHERE enabled = 1 ORDER BY id').all())
+}
+// The revision of the enabled link reports' `{ id, sha256 }` rows, by id,
+// however they were read.
+export function linkRevisionOf(rows: unknown[]): string {
+  return rows.length > 0 ? createHash('sha256').update(JSON.stringify(rows)).digest('base64url') : ''
+}
+function parseLinkReport(content: string) {
+  const parsed = parseLinkedFindings(content)
+  if (parsed) return parsed
+  // Older managed exports may carry the normalized links envelope.
+  try {
+    const data = JSON.parse(content)
+    if (data?.source !== 'links' || !Array.isArray(data.links) || !Array.isArray(data.findings) || data.findings.length > 0) return null
+    return data.links.length === 0 ? { groups: [], skipped: 0 } : parseLinkedFindings(JSON.stringify(data.links))
+  } catch { return null }
+}
+export function linkReportMethods(db: ManagedSql, key: StorageKey | null): LinkReportStore {
+  const map = (row: Omit<LinkReport, 'enabled'> & { enabled: number }): LinkReport => ({ ...row, enabled: row.enabled === 1 })
+  async function authorize(sessionId: string) {
+    const user = await db.prepare(`SELECT u.id, u.login, 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 { id: string; login: string; role: string } | undefined
+    if (!user) throw new ManagedMutationError(401, 'unauthenticated')
+    if (user.role !== 'admin') throw new ManagedMutationError(403, 'forbidden')
+    return user
+  }
+  return {
+    async listLegacyLinkReports() {
+      return await db.prepare("SELECT id, filename FROM managed_report WHERE analyzer = 'links' ORDER BY id").all() as { id: string; filename: string }[]
+    },
+    async migrateLinkReport(id, content) {
+      const row = await db.prepare(`SELECT filename, sha256, visible, uploaded_by AS uploadedBy,
+        uploaded_by_login AS uploadedByLogin, uploaded_at AS uploadedAt FROM managed_report WHERE id = ? AND analyzer = 'links'`).get(id) as {
+        filename: string; sha256: string; visible: number; uploadedBy: string | null; uploadedByLogin: string | null; uploadedAt: number
+      } | undefined
+      if (!row) return false
+      if (!key) throw new Error('Managed link reports require MANAGED_STORAGE_ENCRYPTION_KEY')
+      if (createHash('sha256').update(content).digest('base64url') !== row.sha256) throw new Error('Legacy link report content changed')
+      const parsed = parseLinkReport(content)
+      if (!parsed) throw new Error('Invalid legacy link report')
+      const plain = Buffer.from(JSON.stringify(parsed.groups))
+      try {
+        const sha256 = createHash('sha256').update(plain).digest('base64url')
+        await db.prepare(`INSERT INTO managed_link_report
+          (id, filename, sha256, encrypted_groups, enabled, group_count, finding_count, uploaded_by, uploaded_by_login, uploaded_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(sha256) DO NOTHING`).run(
+          id, row.filename, sha256, wrapStorageValue(key, identity(id), plain), row.visible,
+          parsed.groups.length, new Set(parsed.groups.flat()).size, row.uploadedBy, row.uploadedByLogin, row.uploadedAt)
+        await db.prepare('DELETE FROM managed_report WHERE id = ?').run(id)
+      } finally { plain.fill(0) }
+      return true
+    },
+    async listLinkReports() {
+      return (await db.prepare(`SELECT ${columns} FROM managed_link_report ORDER BY uploaded_at DESC, id`).all() as Parameters<typeof map>[0][]).map(map)
+    },
+    async getLinkReport(sessionId, id) {
+      await authorize(sessionId)
+      const row = await db.prepare(`SELECT ${columns}, encrypted_groups AS payload FROM managed_link_report WHERE id = ?`).get(id) as (Parameters<typeof map>[0] & { payload: string }) | undefined
+      if (!row) throw new ManagedMutationError(404, 'no-link-report')
+      const { payload, ...report } = row
+      return { ...map(report), groups: decryptGroups(key, id, payload) }
+    },
+    getLinkRevision: () => linkRevision(db),
+    async getEnabledLinkGroups(revision) {
+      if (await linkRevision(db) !== revision) throw new ManagedMutationError(409, 'deduplication-changed')
+      const rows = await db.prepare('SELECT id, encrypted_groups AS payload FROM managed_link_report WHERE enabled = 1 ORDER BY id').all() as { id: string; payload: string }[]
+      if (rows.length > 0 && !key) throw new Error('Managed link reports require MANAGED_STORAGE_ENCRYPTION_KEY')
+      return rows.flatMap(row => decryptGroups(key, row.id, row.payload))
+    },
+    async importLinkReport(sessionId, filename, content) {
+      const user = await authorize(sessionId)
+      if (!key) throw new ManagedMutationError(503, 'storage-encryption-required')
+      const parsed = parseLinkReport(content)
+      if (!parsed || parsed.skipped) throw new ManagedMutationError(400, 'invalid-link-report')
+      const plain = Buffer.from(JSON.stringify(parsed.groups))
+      const sha256 = createHash('sha256').update(plain).digest('base64url')
+      try {
+        const existing = await db.prepare(`SELECT ${columns} FROM managed_link_report WHERE sha256 = ?`).get(sha256) as Parameters<typeof map>[0] | undefined
+        if (existing) return { report: map(existing), reused: true }
+        const id = randomUUID(), uploadedAt = Date.now()
+        const findingCount = new Set(parsed.groups.flat()).size, groupCount = parsed.groups.length
+        await db.prepare(`INSERT INTO managed_link_report
+          (id, filename, sha256, encrypted_groups, group_count, finding_count, uploaded_by, uploaded_by_login, uploaded_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, filename, sha256, wrapStorageValue(key, identity(id), plain), groupCount, findingCount, user.id, user.login, uploadedAt)
+        return { report: { id, filename, enabled: true, groupCount, findingCount, uploadedByLogin: user.login, uploadedAt }, reused: false }
+      } finally { plain.fill(0) }
+    },
+    async setLinkReportEnabled(sessionId, id, enabled) {
+      await authorize(sessionId)
+      if (!(await db.prepare('UPDATE managed_link_report SET enabled = ? WHERE id = ?').run(+enabled, id)).changes) throw new ManagedMutationError(404, 'no-link-report')
+    },
+  }
+}
+
+// Merge complete components BEFORE projecting them onto the response. An ID
+// absent from every returned report can still bridge two visible findings.
+export function mergeLinkGroups(groups: readonly string[][], present?: ReadonlySet<string>): string[][] {
+  const parents = new Map<string, string>()
+  const root = (id: string): string => {
+    if (!parents.has(id)) parents.set(id, id)
+    let value = id
+    while (parents.get(value) !== value) {
+      parents.set(value, parents.get(parents.get(value)!)!)
+      value = parents.get(value)!
+    }
+    return value
+  }
+  for (const ids of groups) {
+    if (ids.length === 0) continue
+    const first = root(ids[0]!)
+    for (const id of ids.slice(1)) { const other = root(id); if (other !== first) parents.set(other, first) }
+  }
+  const merged = new Map<string, string[]>()
+  for (const id of parents.keys()) {
+    if (present && !present.has(id)) continue
+    const key = root(id)
+    const ids = merged.get(key) ?? []
+    ids.push(id); merged.set(key, ids)
+  }
+  return [...merged.values()].filter(ids => ids.length >= 2)
+}

package/server-managed/locked-packages.ts

@@ -0,0 +1,129 @@
+// The packages a lockfile of npm's ecosystem locks, as @preventive/lockfile
+// reads package-lock.json and npm-shrinkwrap.json of `lockfileVersion: 3`,
+// pnpm-lock.yaml of pnpm 9 to 12 and Yarn 1's yarn.lock, each with where it
+// is installed from and whether only devDependencies need it
+// (repository-risk.ts).
+import { LockfileError, parseNpmLockfile } from '@preventive/lockfile/npm.js'
+import { parsePnpmLockfile } from '@preventive/lockfile/pnpm.js'
+import { parseYarn1Lockfile } from '@preventive/lockfile/yarn1.js'
+import type { LockfileFormat } from '@preventive/upstream/github.js'
+import type { ReviewedLockfile } from './reviewed-dependencies.ts'
+
+export interface LockedPackage {
+  name: string
+  // None for a git dependency whose package.json has none.
+  version: string | null
+  // Where it is installed from: npm's registry, another host's tarball with
+  // an integrity, such as a company's mirror of npm's, a git repository, a
+  // tarball with none, or a file of the project.
+  source: 'registry' | 'mirror' | 'git' | 'tarball' | 'file'
+  // Where one from elsewhere than npm's registry comes from, without any
+  // credentials its URL has.
+  from?: string
+  // As the lockfile has it: a mirror's tarball's, npm's package of its name
+  // and version only where npm's integrity is among it; and, where its
+  // reviews ask (`review`), npm's registry's too.
+  integrity?: string
+  // Where its reviews ask: the sha1 Yarn 1 writes after a tarball's `#`, in
+  // hex (`shasum`); the hash of the patch pnpm applies to it
+  // (`patchHash`, its patchedDependencies'); and the lockfile's format.
+  shasum?: string
+  patchHash?: string
+  lockfile?: ReviewedLockfile
+  // Where only the importers' devDependencies reach it, as npm's `dev` flag
+  // says, and an install of no devDependencies leaves it out: in npm's and
+  // pnpm's lockfiles. Yarn 1's says nothing of it, which only the
+  // package.json files do, and none of its are.
+  dev?: true
+}
+
+// A package as each reader resolves one, its name the one it is published
+// under, and a registry tarball's URL held to its name and version.
+type Resolution =
+  | { type: 'tarball'; tarball: string | undefined; integrity: string | undefined; sha1?: string | undefined; gitHosted?: boolean }
+  | { type: 'git'; repo: string }
+  | { type: 'directory' }
+interface ReadPackage { name: string; version: string | undefined; resolution: Resolution | undefined; dev?: boolean | undefined; patchHash?: string | undefined }
+
+// The packages of a lockfile of `format`, as its reader resolves them.
+// Versions go unchecked against ranges, as only what is locked is asked for.
+function packagesOf(format: LockfileFormat, text: string): ReadPackage[] {
+  if (format === 'npm') return Object.values(parseNpmLockfile(text, { checkVersions: false }).packages)
+  if (format === 'pnpm') {
+    const { lockfile, env } = parsePnpmLockfile(text)
+    return [...Object.values(env?.packages ?? {}), ...Object.values(lockfile?.packages ?? {})]
+  }
+  if (format !== 'yarn') throw new TypeError(`lockedPackages: ${format} lockfiles are not read`)
+  // Yarn 2 and later write another format, which only the text tells apart.
+  if (/^__metadata:/mu.test(text)) throw new LockfileError('a yarn.lock of Yarn 2 or later, which is not read')
+  // Yarn 1 names an alias, `my-q@npm:q@^1.5.1`, by its own name.
+  return Object.values(parseYarn1Lockfile(text, { checkVersions: false }).packages)
+    .map(pkg => ({ ...pkg, name: /@npm:((?:@[^/@]+\/)?[^/@]+)/u.exec(pkg.patterns[0] ?? '')?.[1] ?? pkg.name }))
+}
+
+// npm's registry, by either of its names, and yarn's mirror of it, as
+// @preventive/lockfile holds their tarballs to a package's name and version:
+// its link to one, as it names it, a hash after it alone (Yarn 1's sha1).
+const REGISTRY_HOSTS = new Set(['registry.npmjs.org', 'registry.npmjs.com', 'registry.yarnpkg.com'])
+const isRegistry = (url: URL) => url.protocol === 'https:' && !url.port && !url.username && !url.password && !url.search
+  && REGISTRY_HOSTS.has(url.hostname.replace(/\.+$/u, ''))
+// Where a URL is, as it may be shown: its credentials, query and fragment
+// left out.
+const shown = (url: URL | null) => url ? { from: `${url.protocol}//${url.host}${url.pathname}` } : {}
+
+// Where a package read comes from (LockedPackage), with npm's registry's
+// integrity where `review`; null for one a package bundles, with no
+// resolution, or one of the project's own directories.
+function located({ name, version, resolution }: ReadPackage, review: boolean): LockedPackage | null {
+  const at = { name, version: version ?? null }
+  if (resolution === undefined || resolution.type === 'directory') return null
+  if (resolution.type === 'git') return { ...at, source: 'git', ...shown(URL.parse(resolution.repo)) }
+  const { tarball, integrity } = resolution
+  if (resolution.gitHosted) return { ...at, source: 'git', ...shown(URL.parse(tarball ?? '')) }
+  const registry = { ...at, source: 'registry' as const, ...review && integrity ? { integrity } : {} }
+  if (tarball === undefined) return registry
+  if (tarball.startsWith('file:')) return { ...at, source: 'file' }
+  const url = URL.parse(tarball)
+  if (url && isRegistry(url)) return registry
+  return integrity ? { ...at, ...shown(url), source: 'mirror', integrity } : { ...at, ...shown(url), source: 'tarball' }
+}
+// As above, and with what its reviews ask (LockedPackage `shasum`,
+// `patchHash`, `lockfile`) where `review`.
+function locked(pkg: ReadPackage, format: LockfileFormat, review: boolean): LockedPackage | null {
+  const one = located(pkg, review)
+  if (!one || !review) return one
+  const sha1 = pkg.resolution?.type === 'tarball' ? pkg.resolution.sha1 : undefined
+  return { ...one, ...sha1 ? { shasum: sha1 } : {}, ...pkg.patchHash ? { patchHash: pkg.patchHash } : {}, lockfile: format === 'yarn' ? 'yarn1' : format as ReviewedLockfile }
+}
+
+// The packages a lockfile of `format` (npm, pnpm or yarn, as
+// findRepoLockfiles names them) locks, each once, in the lockfile's order:
+// `dev` only where it is wherever it is installed, at each path of npm's
+// tree, and with each of pnpm's peers; with `review`, each with what its
+// reviews hold it to (LockedPackage `integrity`, `shasum`, `patchHash`),
+// each patch of it apart. Throws the reader's LockfileError or YamlError for
+// one it refuses.
+export function lockedPackages(format: LockfileFormat, text: string, { review = false } = {}): LockedPackage[] {
+  const found = new Map<string, LockedPackage>()
+  for (const pkg of packagesOf(format, text)) {
+    const one = locked(pkg, format, review)
+    if (!one) continue
+    if (pkg.dev === true) one.dev = true
+    const key = `${one.source}\0${one.name}@${one.version ?? ''}\0${one.from ?? ''}\0${one.integrity ?? ''}\0${one.shasum ?? ''}\0${one.patchHash ?? ''}`
+    const had = found.get(key)
+    if (!had) found.set(key, one)
+    else if (had.dev && !one.dev) delete had.dev
+  }
+  return [...found.values()]
+}
+
+// Whether a lockfile at `path` is a test's fixture or example: under a
+// directory of tests (`test`, `tests`, `__tests__` and such), in one of
+// fixtures or examples (`fixture`, `fixtures`, `example`, `examples`) inside
+// it, as a test may keep one its readers refuse on purpose.
+const FIXTURES_DIR = /^(?:fixture|example)s?$/u, TESTS_DIR = /^_*tests?_*$/u
+export function isTestFixture(path: string) {
+  const dirs = path.split('/').slice(0, -1)
+  const tests = dirs.findIndex(dir => TESTS_DIR.test(dir))
+  return tests !== -1 && dirs.slice(tests + 1).some(dir => FIXTURES_DIR.test(dir))
+}

package/server-managed/lockfile-scope.ts

@@ -0,0 +1,49 @@
+// The lockfiles a repository's dependency review holds to, as an admin sets
+// it (repository-dependency-reviews.ts): every one but those it names
+// (`exclude`, naming none for all of them), or those it names alone
+// (`include`). Each is named by its path in the repository, or, ending in
+// `/`, by a directory, every lockfile under it. A directory of a pull
+// request's lockfiles (pull-dependencies.ts) is reviewed where one of its
+// lockfiles is held to; one none of whose are, not at all (`excluded`), nor
+// failing the review where it couldn't be read.
+export interface LockfileScope { mode: 'exclude' | 'include'; paths: string[] }
+export const EVERY_LOCKFILE: LockfileScope = { mode: 'exclude', paths: [] }
+export const MAX_SCOPED_LOCKFILES = 100
+const MAX_PATH = 300
+
+// A path as one is named: relative, of `/`-separated names none of which is
+// empty, `.` or `..`, nor holding a backslash or a control character; a
+// directory's ending in `/`.
+function namedPath(path: unknown): path is string {
+  if (typeof path !== 'string' || path.length === 0 || path.length > MAX_PATH || path.startsWith('/')) return false
+  if (/[\\\p{Cc}]/u.test(path)) return false
+  const names = path.endsWith('/') ? path.slice(0, -1).split('/') : path.split('/')
+  return names.every(name => name !== '' && name !== '.' && name !== '..')
+}
+
+// A scope as a request sends it, each path once, in order; null for one
+// that isn't one.
+export function scopeOf(value: unknown): LockfileScope | null {
+  const { mode, paths } = (value ?? {}) as { mode?: unknown; paths?: unknown }
+  if ((mode !== 'exclude' && mode !== 'include') || !Array.isArray(paths) || paths.length > MAX_SCOPED_LOCKFILES || !paths.every(namedPath)) return null
+  return { mode, paths: [...new Set(paths as string[])].toSorted() }
+}
+
+// A scope as stored (JSON, none for every lockfile), every lockfile where
+// it can't be read.
+export function storedScope(text: string | null): LockfileScope {
+  if (!text) return EVERY_LOCKFILE
+  try { return scopeOf(JSON.parse(text)) ?? EVERY_LOCKFILE } catch { return EVERY_LOCKFILE }
+}
+export const scopeText = (scope: LockfileScope) => isEvery(scope) ? null : JSON.stringify({ mode: scope.mode, paths: scope.paths })
+export const isEvery = (scope: LockfileScope) => scope.mode === 'exclude' && scope.paths.length === 0
+
+const names = (path: string, named: string) => named.endsWith('/') ? path.startsWith(named) : path === named
+// Whether the lockfile at `path` is held to.
+export function heldTo(scope: LockfileScope, path: string) {
+  const named = scope.paths.some(one => names(path, one))
+  return scope.mode === 'include' ? named : !named
+}
+// Whether a directory of lockfiles at `paths` is reviewed: where one is
+// held to, or it names none.
+export const reviewedIn = (scope: LockfileScope, paths: string[]) => paths.length === 0 || paths.some(path => heldTo(scope, path))