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

package/server-managed/http.ts

@@ -101,12 +101,15 @@
 //   POST /api/admin/teams/{set,remove}-member → admin links/unlinks a user (+perms) | 401/403/404
 //   POST /api/admin/teams/set-dependency-review → admin toggles dependency review publication for a team | 400/401/403/404
 //   POST /api/admin/teams/set-npm-scopes → admin replaces a team's npm scopes | 400/401/403/404
-//   GET/POST /api/npm/reviews → read private/team reviews; save, publish, revoke or continue a set | 400/401/403/404/409
+//   GET/POST /api/npm/reviews → read private/team reviews; save, publish, revoke or continue a set; a patched version's
+//        (patchHash) changed with where its patch is (patchRepoId, patchCommit, patchPath) | 400/401/403/404/409/422
 //   POST /api/npm/reviews/discard → author discards an unpublished review and its file rows | 400/401/403/409
 //   GET /api/npm/reviews/latest → latest own review for exact target bytes, across all bases | 400/401/403
 //   GET /api/npm/reviews/team?teamId=&beforeTime=&beforeId= → the reviews published to a team, the latest first, for one who
 //        reads them there | 400/401/404
 //   GET  /api/npm/package?name=&version= → a published version's manifest and files | 400/401/404/413/429/502
+//   GET  /api/npm/package?name=&version=&patchHash=&patchRepoId=&patchCommit=&patchPath= → its files as a pnpm patch of a
+//        repository the reader reads all of changes them | 400/401/403/404/409/413/422/429/502
 //   GET  /api/npm/versions?name= → its dist-tags, versions, when each was published and its first was, and whether a team lists its scope | 400/401/404/429/502
 //   GET  /api/npm/download?name=&version= → its tarball | 400/401/404/413/429/502
 //   GET  /api/npm/stats?name= → its downloads over the last year and its GitHub repository's figures | 400/401/404/429/502
@@ -135,8 +138,8 @@ import { mergeLinkGroups } from './link-reports.ts'
 import { backfillFindingIds, reportEntries } from '@preventive/report'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { pipeline } from 'node:stream/promises'
-import { type KeptStore, REPOSITORY_READ_KEPT_MS, codeHeadStore, codeTreeStore, commitPullStore, historyChangeStore, historyPageStore, historySquashStore, historyTreeStore,
-  lockfileReadStore,
+import { type KeptStore, REPOSITORY_READ_KEPT_MS, authoredCommitStore, branchTipStore, codeHeadStore, codeTreeStore, commitPullStore, historyChangeStore, historyPageStore, historySquashStore, historyTreeStore,
+  issueListStore, lockfileReadStore,
   npmDeltaStore, npmPublishTimeStore, npmVersionStore, ownKeptPrunes, pullDependencyStore, pullListStore, repositoryReadStore, reviewBaselineStore, riskLineStore, scanReadStore } from './npm-kept.ts'
 import { plainObject } from './npm-manifest.ts'
 import { type NpmDelta, keptNpmDeltas, npmDelta } from './npm-delta.ts'
@@ -213,13 +216,14 @@ import { ManagedMutationError, reportReferenceSnapshot } from './management.ts'
 import { BundleBuildError, buildRepositoryBundle, parseBundleBuild, withBundleBuildLease } from './bundle-build.ts'
 import { NpmPackageError, type NpmReader, type NpmVersionDocument, type NpmVersionStore, VERSION_KEPT_MS, canReadPrivateNpm, npmFileRows, npmPublishTime, npmScopesCount, npmTarballFilename, readNpmVersion, readNpmVersions, readTogether } from './npm-packages.ts'
 import { loadNpmFiles, loadNpmPackageBody, loadNpmTarball } from './npm-loads.ts'
+import { type NpmPatch, type PatchedFile, patchedFiles, readPatch, requestedPatch } from './npm-patch.ts'
 import { type RepositoryCodeKept, loadRepositoryCodeBody, repositoryCodeFits, repositoryCodeKept } from './repository-code.ts'
 import { type ChangesStore, type CommitChanges, type CommitTree, TREES_READ, changesAsked, changesWithin, directoryFiles, repositoryChanges } from './repository-changes.ts'
 import { COAUTHORS_READ, coauthorsOf } from './commit-coauthors.ts'
 import { type AllHeads, type HistoryCommit, type HistoryPages, MAX_HISTORY_PAGE, historyFrom, historyStarts, openPullHeads,
   repositoryAllHeads, repositoryAllHistory, repositoryHistory, repositoryRefTips } from './repository-history.ts'
 import { type KnownMerges, type SquashedPull, type Squashes, squashedPulls } from './repository-squashes.ts'
-import { AGENTS_READ_VERSION, COMMITS_CURSOR, type CommitPulls, repositoryAgents } from './repository-agents.ts'
+import { AGENTS_READ_VERSION, type AuthoredCommit, type BranchTip, type BranchTips, COMMITS_CURSOR, type CommitPulls, repositoryAgents } from './repository-agents.ts'
 import { ISSUES_CURSOR, ISSUES_READ_VERSION, repositoryIssues, repositoryItem } from './repository-issues.ts'
 import { type GithubAsked, type ListedLockfile, type LockfileRead, type LockfileStore, MAX_LOCKED, PULL_DEPENDENCIES_READ, type PullCommits, type PullDependencies,
   type PullDependencyStore, eachOf, lockfileFormat, pullDependenciesAt } from './pull-dependencies.ts'
@@ -230,10 +234,12 @@ import { type ReviewBaselineStore, baselineFor, heldDependencies, reviewedDepend
 import { formattedPull, withFormatted } from './dependency-review-comments.ts'
 import type { ReviewedDependencies } from './reviewed-dependencies.ts'
 import { commentReviews } from './pull-comment-reviews.ts'
-import { PULSE_WEEKS, PULSE_YEAR_VERSION, type PulseStats, StatsPending, commitStats, defaultHead, periodStats, pulseSince, repositoryActivity, repositoryLines,
+import { PULSE_WEEKS, PULSE_YEAR_VERSION, type PulseNarrowing, type PulseStats, StatsPending, commitStats, defaultHead, periodStats, pulseSince,
+  repositoryActivity, repositoryLines,
   repositoryStats, withLines, yearCommits } from './repository-pulse.ts'
 import { type AgentMerges, agentCommits, agentMerges, directCommits, sameMerges } from './agent-merges.ts'
-import { PULLS_READ_VERSION, type PullList, pullsReadTo, readPulls } from './repository-pulls.ts'
+import { listedActivity } from './listed-activity.ts'
+import { ISSUES_LIST_READ_VERSION, type IssueList, type Listed, PULLS_READ_VERSION, type PullList, pullsReadTo, readIssues, readPulls } from './repository-pulls.ts'
 import { AGENT_MARKS_READ } from './app-agents.ts'
 import { releaseCommits } from './release-commits.ts'
 import { computeBundleDiff } from '../common/bundle-compare-diff.js'
@@ -246,8 +252,8 @@ import { NpmRiskError } from '../risk/index.js'
 import { type PrettyCache, PrettyError, type PrettyRequest, compared, prettyRequest, prettyText } from './pretty-print.ts'
 import { renameDiffOf, renameDiffRequest, renamedPairs } from './rename-diff.ts'
 import { typeOnlyFiles } from './type-only.ts'
-import { comparisonBody, emptySide, npmComparedSide } from './comparison.ts'
-import { isNpmPackageName, isNpmPackageSpec, npmPackageScope } from '../common/managed/npm-packages.js'
+import { comparisonBody, emptySide, npmComparedSide, patchedVersionBody } from './comparison.ts'
+import { isNpmPackageName, isNpmPackageSpec, isPatchHash, npmPackageScope } from '../common/managed/npm-packages.js'
 
 const SESSION_PATH = '/api/auth/session'
 const PROFILE_PATH = '/api/auth/profile'
@@ -1525,18 +1531,24 @@ type RepositoryReader = Awaited<ReturnType<ReturnType<typeof createRepositoryBro
 type RepositoryContents = Awaited<ReturnType<typeof readRepositoryContents>>
 type RepositoryRefs = Awaited<ReturnType<RepositoryReader['refs']>> & { defaultContents?: RepositoryContents | null }
 
-async function readRepositoryContents(reader: RepositoryReader, ref: string, path: string, virtualEntries: RepositoryEntry[] | null) {
+// A directory's listing at a commit (`reader.directory`), which never changes,
+// as kept by them (repositoryTreesOf `listings`), else read.
+type DirectoryListing = Awaited<ReturnType<RepositoryReader['directory']>>
+type ListedAt = (commit: string, path: string, read: () => Promise<DirectoryListing>) => Promise<DirectoryListing>
+
+async function readRepositoryContents(reader: RepositoryReader, ref: string, path: string, virtualEntries: RepositoryEntry[] | null, listed: ListedAt) {
   const commit = await reader.commit(ref)
-  const contents = virtualEntries ? { entries: virtualEntries, limited: false } : await reader.directory(path, commit)
+  const contents = virtualEntries ? { entries: virtualEntries, limited: false } : await listed(commit, path, () => reader.directory(path, commit))
   return { ...contents, path, commit }
 }
 
-async function readRepositoryRefs(db: ManagedDb, reader: RepositoryReader, repo: SelectedRepo, withDefault: boolean, virtualEntries: RepositoryEntry[] | null): Promise<RepositoryRefs> {
+async function readRepositoryRefs(db: ManagedDb, reader: RepositoryReader, repo: SelectedRepo, withDefault: boolean, virtualEntries: RepositoryEntry[] | null,
+  listed: ListedAt): Promise<RepositoryRefs> {
   // Wait for both, including failures: a deleted cached branch must not prevent
   // a successful live default lookup from recovering the initial directory.
   const [refs, contents] = await Promise.allSettled([
     reader.refs(),
-    withDefault && repo.cachedDefaultBranch ? readRepositoryContents(reader, `heads/${repo.cachedDefaultBranch}`, '', virtualEntries) : Promise.resolve(null),
+    withDefault && repo.cachedDefaultBranch ? readRepositoryContents(reader, `heads/${repo.cachedDefaultBranch}`, '', virtualEntries, listed) : Promise.resolve(null),
   ])
   if (refs.status === 'rejected') throw refs.reason
   const defaultBranch = refs.value.defaultBranch || null
@@ -1544,7 +1556,7 @@ async function readRepositoryRefs(db: ManagedDb, reader: RepositoryReader, repo:
   if (changed) await db.cacheRepoDefaultBranch(repo, defaultBranch)
   if (!withDefault) return refs.value
   if (!defaultBranch) return { ...refs.value, defaultContents: null }
-  if (changed) return { ...refs.value, defaultContents: await readRepositoryContents(reader, `heads/${defaultBranch}`, '', virtualEntries) }
+  if (changed) return { ...refs.value, defaultContents: await readRepositoryContents(reader, `heads/${defaultBranch}`, '', virtualEntries, listed) }
   if (contents.status === 'rejected') throw contents.reason
   return { ...refs.value, defaultContents: contents.value }
 }
@@ -1613,6 +1625,9 @@ async function handleRepositoryBrowser(res: ServerResponse, deps: ManagedHttpDep
   if (!asked) return
   const { repoId, ref } = asked
   const withDefault = refs && query.get('withDefault') === 'true'
+  // The commit alone (`listing=none`), as a view reading none of its entries
+  // opens at.
+  const commitOnly = !refs && query.get('listing') === 'none'
   const path = refs ? '' : asked.path
   const authorize = async (handed = false) => {
     const access = await authorizeRepository(res, deps, cookie, repoId, path, { handed })
@@ -1626,8 +1641,10 @@ async function handleRepositoryBrowser(res: ServerResponse, deps: ManagedHttpDep
     const reader = await browser.reader(access.repo)
     // Microseconds, so overlapping browses practically never share a listing time.
     const observedUs = Math.round((performance.timeOrigin + performance.now()) * 1000)
-    const revisions = refs ? await readRepositoryRefs(deps.db, reader, access.repo, withDefault, access.virtualEntries) : null
-    const contents = refs ? null : await readRepositoryContents(reader, ref, path, access.virtualEntries)
+    const trees = repositoryTreesOf(deps)
+    const listedAt: ListedAt = (commit, at, read) => trees.listing(`${repoId}\0${LISTING_READ}\0${commit}\0${at}`, read)
+    const revisions = refs ? await readRepositoryRefs(deps.db, reader, access.repo, withDefault, access.virtualEntries, listedAt) : null
+    const contents = refs ? null : commitOnly ? { path, commit: await reader.commit(ref) } : await readRepositoryContents(reader, ref, path, access.virtualEntries, listedAt)
     const { tagCommits, tagsComplete, ...listed } = revisions ?? { tagCommits: [], tagsComplete: false }
     // Every refs read (Create a bundle's, and the code viewer's) refreshes the
     // tags bundle catalogs show, and a tag read keeps the one its revision
@@ -1644,7 +1661,7 @@ async function handleRepositoryBrowser(res: ServerResponse, deps: ManagedHttpDep
     if (!sameRepository(current.repo, access.repo)) { sendJson(res, 409, { error: 'repository-changed' }); return }
     sendJson(res, 200, refs ? { ...listed, tagCommits, ...(withDefault ? {
       defaultContents: scopeRepositoryContents(revisions?.defaultContents ?? null, current.virtualEntries),
-    } : {}) } : scopeRepositoryContents(contents, current.virtualEntries))
+    } : {}) } : commitOnly ? contents : scopeRepositoryContents(contents as RepositoryContents, current.virtualEntries))
   } catch (err) {
     if (err instanceof GithubApiError) { sendGithubError(res, err); return }
     throw err
@@ -1669,19 +1686,27 @@ async function handleRepositoryBrowser(res: ServerResponse, deps: ManagedHttpDep
 // the reader's own access has named the commit, as GitHub would have
 // answered them; held by each instance a while, by the database it has, and
 // kept in that database for every instance (npm-kept.ts codeTreeStore).
+// And a directory's listing at a commit (readRepositoryContents), by the
+// repository's id, the rules it is read by (LISTING_READ), the commit and the
+// directory, fewer held, each the larger.
 const REPOSITORY_TREES_KEPT = 4096
+const REPOSITORY_LISTINGS_HELD = 256
+const LISTING_READ = 1
 type TreeFiles = Awaited<ReturnType<typeof repositoryTreeFiles>>
-const repositoryTrees = new WeakMap<ManagedDb, { ids: Lru<string>; files: Lru<TreeFiles> }>()
+const repositoryTrees = new WeakMap<ManagedDb, { ids: Lru<string>; files: Lru<TreeFiles>; listings: Lru<DirectoryListing> }>()
 const treeId = (value: unknown): value is string => typeof value === 'string' && /^[a-f\d]{40}$/u.test(value)
 const treeFiles = (value: unknown): value is TreeFiles => value === null || (plainObject(value)
   && Number.isSafeInteger(value['files']) && (value['files'] as number) >= 0 && Number.isSafeInteger(value['bytes']) && (value['bytes'] as number) >= 0)
+const directoryListing = (value: unknown): value is DirectoryListing => plainObject(value) && Array.isArray(value['entries']) && typeof value['limited'] === 'boolean'
 function repositoryTreesOf(deps: ManagedHttpDeps) {
   let held = repositoryTrees.get(deps.db)
-  if (!held) repositoryTrees.set(deps.db, held = { ids: lru(REPOSITORY_TREES_KEPT), files: lru(REPOSITORY_TREES_KEPT) })
-  const { ids, files } = held
+  if (!held) repositoryTrees.set(deps.db, held = { ids: lru(REPOSITORY_TREES_KEPT), files: lru(REPOSITORY_TREES_KEPT), listings: lru(REPOSITORY_LISTINGS_HELD) })
+  const { ids, files, listings } = held
   return {
     id: (key: string, read: () => Promise<string>) => keptTree(ids, codeTreeStore<string>(deps.db, 'trees', deps.config.debug), key, treeId, read),
     files: (key: string, read: () => Promise<TreeFiles>) => keptTree(files, codeTreeStore<TreeFiles>(deps.db, 'tree-files', deps.config.debug), key, treeFiles, read),
+    listing: (key: string, read: () => Promise<DirectoryListing>) =>
+      keptTree(listings, codeTreeStore<DirectoryListing>(deps.db, 'listings', deps.config.debug), key, directoryListing, read),
   }
 }
 // What `memory` holds by `key`, else what `store` keeps of it as `kept`
@@ -2006,8 +2031,9 @@ const REPOSITORY_READ_FLOOR_MS = 10_000
 // How long a history's answer waits on GitHub looking up the pull requests
 // squashed into its commits (handleRepositoryHistory).
 const SQUASH_WAIT_MS = 1500
-// The repositories' reads being read again, behind a kept answer or as asked
-// for afresh, by key: one at a time, those asking meanwhile answered by it.
+// The repositories' reads being read, first or again, behind a kept answer or
+// as asked for afresh, by key: one at a time, those asking meanwhile
+// answered by it.
 const repositoryRereads = new Map<string, Promise<unknown>>()
 // A read GitHub refused, not failed: its credential or the GitHub App's
 // permission for it withdrawn (Issues, Pull requests, Checks), the
@@ -2023,7 +2049,8 @@ const refusedRead = (err: unknown) => err instanceof GithubApiError
 // deps.waitUntil); `kept` where it was, or where reading it again
 // failed as `keepThrough` lets it. One asked for afresh (`fresh`) is read
 // now, unless it was read REPOSITORY_READ_FLOOR_MS since, what was kept
-// answered where that read fails. One GitHub refuses to read again is no
+// answered where that read fails. Those asking for one not kept while it is
+// read, as a tab's first readers do together, are answered by that read. One GitHub refuses to read again is no
 // longer kept: the next to ask is refused as GitHub refused it. `at` is when
 // what it answers was read.
 async function keptAnswer<T extends object>(deps: ManagedHttpDeps, key: string, read: () => Promise<T>,
@@ -2065,7 +2092,7 @@ async function keptAnswer<T extends object>(deps: ManagedHttpDeps, key: string,
     return { value: held.value as T, kept: true, at: held.at }
   }
   try {
-    return { ...now ? await reread() : await readKept(), kept: false }
+    return { ...await reread(), kept: false }
   } catch (err) {
     if (held && ((now && !refusedRead(err)) || keepThrough(err))) return { value: held.value as T, kept: true, at: held.at }
     throw err
@@ -2117,37 +2144,102 @@ function commitPulls(deps: ManagedHttpDeps, repoId: number): CommitPulls {
   }
 }
 
-// How long repository `repoId`'s pull requests kept (keptPulls) are taken as
-// they are before those updated since are read: less than its readers keep
-// their answers (keptAnswer), that one read of them serves both.
-const PULLS_FRESH_MS = 30_000
-// Each repository's reads of its pull requests, by its id: one at a time,
-// each after those asked before it.
-const pullsReads = new Map<number, Promise<unknown>>()
+// Repository `repoId`'s branches' tips as the Agents tab looks them up
+// (repository-agents.ts BranchTips), kept by the commit and the rules their
+// messages' marks were read by (app-agents.ts AGENT_MARKS_READ).
+function branchTips(deps: ManagedHttpDeps, repoId: number): BranchTips {
+  const store = branchTipStore<BranchTip>(deps.db, deps.config.debug)
+  const keyOf = (sha: string) => `${repoId}\0${AGENT_MARKS_READ}\0${sha}`
+  return {
+    async read(shas) {
+      const kept = await store.readMany(shas.map(keyOf))
+      return new Map(shas.flatMap(sha => { const tip = kept.get(keyOf(sha))?.value; return tip ? [[sha, tip] as const] : [] }))
+    },
+    write: (sha, tip) => store.write(keyOf(sha), tip, Date.now()),
+  }
+}
 
-// Repository `repoId`'s pull requests, as kept (repository-pulls.ts
-// readPulls), read on where they were read PULLS_FRESH_MS ago or longer, or
-// not as far back as `need`: as far back as it, for the Pulse; for the
-// Agents tab (null), as far back as they were read, those updated since read
-// (a read not finished, on), else their first page. One read of a
+// The commits repository `repoId`'s app agents' accounts authored from a
+// head, as the Agents tab reads them (repository-agents.ts AuthoredCommits),
+// kept by it and the rules their messages' marks were read by
+// (AGENT_MARKS_READ).
+function authoredCommits(deps: ManagedHttpDeps, repoId: number) {
+  const store = authoredCommitStore<AuthoredCommit[]>(deps.db, deps.config.debug)
+  const keyOf = (key: string) => `${repoId}\0${AGENT_MARKS_READ}\0${key}`
+  return {
+    read: async (key: string) => { const kept = (await store.read(keyOf(key)))?.value; return Array.isArray(kept) ? kept : null },
+    write: (key: string, commits: AuthoredCommit[]) => store.write(keyOf(key), commits, Date.now()),
+  }
+}
+
+// How long a repository's pull requests or issues kept (keptList) are taken
+// as they are before those updated since are read: less than their readers
+// keep their answers (keptAnswer), that one read of them serves them all.
+const LIST_FRESH_MS = 30_000
+// Each repository's reads of its pull requests, and of its issues, by them
+// and its id: one at a time, each after those asked before it.
+const listReads = new Map<string, Promise<unknown>>()
+
+// A repository's pull requests or issues, as kept in `store` by `key`
+// (repository-pulls.ts readList, `read`), read on where they were read
+// LIST_FRESH_MS ago or longer, or not as far back as `need`: as far back as
+// it, for the Pulse; for the Agents tab (null), as far back as they were
+// read, those updated since read (a read not finished, on), else their
+// first page. Not to be read further back (`further` false): those kept,
+// none where none are, where they are not read as far as `need`, or a read
+// of them is not finished, those updated since read alone. One read of a
 // repository's at a time, the rest after it, from what it kept.
-function keptPulls(deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, need: number | null): Promise<PullList> {
-  const store = pullListStore<PullList>(deps.db, deps.config.debug)
-  const key = `${repoId}\0${PULLS_READ_VERSION}\0${AGENTS_READ_VERSION}\0${PULSE_YEAR_VERSION}`
-  const reading = (pullsReads.get(repoId) ?? Promise.resolve()).catch(() => {}).then(async () => {
+function keptList<L extends Listed<unknown>>(store: KeptStore<L>, key: string, read: (since: number, kept: L | null, need: number) => Promise<L>,
+  need: number | null, further = true): Promise<L | null> {
+  const reading = (listReads.get(key) ?? Promise.resolve()).catch(() => {}).then(async () => {
     const kept = await store.read(key)
     const list = kept?.value ?? null
-    if (list && Date.now() - kept!.at < PULLS_FRESH_MS && (need === null || pullsReadTo(list) <= need)) return list
+    if (list && Date.now() - kept!.at < LIST_FRESH_MS && (need === null || pullsReadTo(list) <= need)) return list
+    if (!further && need !== null && (!list || list.next || pullsReadTo(list) > need)) return list
     const since = pulseSince(52, Date.now())
-    const read = await readPulls(fullName, token, since, list, globalThis.fetch,
-      need ?? (list ? list.next ? since : list.reach ?? since : Date.now()))
-    await store.write(key, read, Date.now())
-    return read
+    const listed = await read(since, list, need ?? (list ? list.next ? since : list.reach ?? since : Date.now()))
+    await store.write(key, listed, Date.now())
+    return listed
   })
-  pullsReads.set(repoId, reading)
-  void reading.catch(() => {}).finally(() => { if (pullsReads.get(repoId) === reading) pullsReads.delete(repoId) })
+  listReads.set(key, reading)
+  void reading.catch(() => {}).finally(() => { if (listReads.get(key) === reading) listReads.delete(key) })
   return reading
 }
+// Repository `repoId`'s pull requests (keptList), kept by how agents are
+// told too; those kept alone, not read further back (`further` false).
+function keptPulls(deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, need: number | null): Promise<PullList>
+function keptPulls(deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, need: number, further: false): Promise<PullList | null>
+function keptPulls(deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, need: number | null, further = true) {
+  return keptList(pullListStore<PullList>(deps.db, deps.config.debug), `${repoId}\0${PULLS_READ_VERSION}\0${AGENTS_READ_VERSION}\0${PULSE_YEAR_VERSION}`,
+    (since, kept, asked) => readPulls(fullName, token, since, kept, globalThis.fetch, asked), need, further)
+}
+// Repository `repoId`'s issues (keptList).
+const keptIssues = (deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, need: number | null) =>
+  keptList(issueListStore<IssueList>(deps.db, deps.config.debug), `${repoId}\0${ISSUES_LIST_READ_VERSION}`,
+    (since, kept, asked) => readIssues(fullName, token, since, kept, globalThis.fetch, asked), need) as Promise<IssueList>
+
+// What is kept by `key` (keptAnswer), read now where it was read
+// REPOSITORY_READ_FRESH_MS ago or longer, not behind: for an answer that is
+// kept as fresh itself, as told of it (the Agents tab's).
+async function currentAnswer<T extends object>(deps: ManagedHttpDeps, key: string, read: () => Promise<T>) {
+  const stored = await repositoryReadStore(deps.db, deps.config.debug).read(key)
+  return keptAnswer(deps, key, read, undefined, !stored || Date.now() - stored.at >= REPOSITORY_READ_FRESH_MS)
+}
+
+// Repository `repoId`'s default branch's head, as its tabs read it: as the
+// Commits tab's branches last told it (`heads`), where they were read
+// fresh, else read alone and kept (`pulse-head`), read now where that is no
+// longer fresh as asked (`current`); whether it was kept (`kept`), GitHub
+// asked for none of it.
+async function defaultTip(deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, current = false): Promise<{ sha: string | null; kept: boolean }> {
+  const heads = await repositoryReadStore(deps.db, deps.config.debug).read(`${repoId}\0heads`)
+  const all = heads && Date.now() - heads.at < REPOSITORY_READ_FRESH_MS ? heads.value as AllHeads : null
+  const tip = all?.heads.find(head => head.name === all.defaultBranch)?.sha
+  if (typeof tip === 'string' && /^[a-f\d]{40}$/u.test(tip)) return { sha: tip, kept: true }
+  const head = async () => ({ sha: await defaultHead(fullName, token) })
+  const read = await (current ? currentAnswer(deps, `${repoId}\0pulse-head`, head) : keptAnswer(deps, `${repoId}\0pulse-head`, head))
+  return { sha: read.value.sha, kept: read.kept }
+}
 
 // What the Pulse keeps of repository `repoId`'s pull requests merged, as
 // it tells by them whose its year's commits are (pulseCommits, agentMerges).
@@ -2264,6 +2356,22 @@ async function readWholeRepositoryOf<T>(deps: ManagedHttpDeps, access: WholeAcce
   }
 }
 
+// The patch `patch` names (npm-patch.ts), read of the whole of its repository
+// as readWholeRepositoryOf reads it, with its reader's own GitHub access, and
+// held to its hash: as kept, else with that access checked again after; else
+// why it was refused. Its failing to read or to apply throws.
+async function npmPatchOf(deps: ManagedHttpDeps, cookie: string | undefined, patch: NpmPatch): Promise<{ files: PatchedFile[] } | Refusal> {
+  const access = await wholeRepositoryAccess(deps, cookie, patch.repoId)
+  if ('error' in access) return access
+  const read = await readWholeRepositoryOf(deps, access, async (fullName, token) => {
+    const asked: GithubAsked = { github: false }
+    return { value: await readPatch(fullName, token, patch, asked), kept: !asked.github }
+  }, () => wholeRepositoryAccess(deps, cookie, patch.repoId))
+  return 'error' in read ? read : { files: read.value }
+}
+// The patch a request's fields name, as npm-patch.ts requestedPatch takes them.
+const patchFields = (field: (key: string) => unknown) => requestedPatch({ hash: field('patchHash'), repoId: field('patchRepoId'), commit: field('patchCommit'), path: field('patchPath') })
+
 // GET /api/admin/repositories/issues: what the code viewer's Issues and Pull
 // requests tabs show (repository-issues.ts): `kind`'s open or closed
 // (`state`), a page at a time, on from the cursor `after` names. They are
@@ -2298,7 +2406,10 @@ async function handleRepositoryAgents(res: ServerResponse, deps: ManagedHttpDeps
     sendJson(res, 400, { error: 'bad-request' }); return
   }
   await readWholeRepository(res, deps, cookie, repoId, (fullName, token) => repositoryAgents(fullName, token, cursors, historyPages(deps, repoId, true, true),
-    commitPulls(deps, repoId), () => keptPulls(deps, repoId, fullName, token, null)),
+    commitPulls(deps, repoId), { pulls: () => keptPulls(deps, repoId, fullName, token, null), issues: () => keptIssues(deps, repoId, fullName, token, null),
+      head: async () => (await defaultTip(deps, repoId, fullName, token, true)).sha,
+      heads: async () => (await currentAnswer<AllHeads>(deps, `${repoId}\0heads`, () => repositoryAllHeads(fullName, token))).value,
+      tips: branchTips(deps, repoId), authored: authoredCommits(deps, repoId) }),
     `agents\0${AGENTS_READ_VERSION}\0${cursors.pulls ?? ''}\0${cursors.commits ?? ''}`)
 }
 
@@ -2416,8 +2527,8 @@ async function handleRepositoryBranchDependencies(res: ServerResponse, deps: Man
 // setting as read already (`known`), where it was.
 async function branchDependencyAnswer(deps: ManagedHttpDeps, fullName: string, token: string, user: StoredUser, repoId: number,
   known?: RepoDependencyReview | null): Promise<{ value: object; kept: boolean }> {
-  const headRead = await keptAnswer(deps, `${repoId}\0pulse-head`, async () => ({ sha: await defaultHead(fullName, token) }))
-  const head = headRead.value.sha
+  const headRead = await defaultTip(deps, repoId, fullName, token)
+  const head = headRead.sha
   if (!head) return { value: { head: null, review: null }, kept: false }
   const asked: GithubAsked = { github: !headRead.kept }
   // Those its review holds to alone read, as many as are read of them.
@@ -2447,7 +2558,7 @@ async function handleRepositoryLockfiles(res: ServerResponse, deps: ManagedHttpD
   const repoId = Number(query.get('repoId'))
   if (!Number.isSafeInteger(repoId) || repoId <= 0) { sendJson(res, 400, { error: 'bad-request' }); return }
   await answerWholeRepository(res, deps, cookie, repoId, async (fullName, token) => {
-    const head = (await keptAnswer(deps, `${repoId}\0pulse-head`, async () => ({ sha: await defaultHead(fullName, token) }))).value.sha
+    const head = (await defaultTip(deps, repoId, fullName, token)).sha
     return { value: { head, lockfiles: head ? (await lockfilesAt(fullName, token, head, lockfileKept(deps, repoId))).map(({ path, format }) => ({ path, format })) : [] }, kept: false }
   })
 }
@@ -2603,18 +2714,19 @@ async function teamOpenPulls(deps: ManagedHttpDeps, repoId: number, fullName: st
 }
 
 // The lines the versions wanting reviews of `answers` change, as their rows
-// show them (npm-delta.js deltaBase), where they are counted already: of
-// public versions alone, those npm answered for in a day (npmVersionStore),
-// their integrities those npmDelta keys them by. `[name, version, base,
-// delta]` each, none counted here.
+// show them (npm-delta.js deltaBase), a patched one's none, where they are
+// counted already: of public versions alone, those npm answered for in a day
+// (npmVersionStore), their integrities those npmDelta keys them by. `[name,
+// version, base, delta]` each, none counted here.
 async function teamDeltas(deps: ManagedHttpDeps, answers: object[]) {
   const asked = new Map<string, [string, string, string]>()
   for (const answer of answers as { lockfiles?: { added?: unknown; unreviewed?: unknown }[]; review?: { required?: number } }[]) {
     const required = answer.review?.required
     if (!Number.isSafeInteger(required)) continue
     for (const pkg of (answer.lockfiles ?? []).flatMap(dir => [...Array.isArray(dir.added) ? dir.added : [], ...Array.isArray(dir.unreviewed) ? dir.unreviewed : []]) as
-      { name?: unknown; version?: unknown; source?: unknown; was?: unknown; reviews?: unknown; rejected?: unknown; baseline?: unknown; reviewed?: unknown; unsupported?: unknown }[]) {
-      if (pkg.source !== 'registry' || typeof pkg.name !== 'string' || typeof pkg.version !== 'string' || !isExactVersion(pkg.version)) continue
+      { name?: unknown; version?: unknown; source?: unknown; was?: unknown; reviews?: unknown; rejected?: unknown; baseline?: unknown; reviewed?: unknown; unsupported?: unknown
+        patch?: unknown }[]) {
+      if (pkg.source !== 'registry' || pkg.patch || typeof pkg.name !== 'string' || typeof pkg.version !== 'string' || !isExactVersion(pkg.version)) continue
       if (pkg.unsupported || pkg.baseline || pkg.reviewed || typeof pkg.reviews !== 'number' || (pkg.reviews >= required! && !pkg.rejected)) continue
       const was = Array.isArray(pkg.was) ? pkg.was.find(prior => typeof prior === 'string' && prior !== pkg.version) as string | undefined : undefined
       asked.set(`${pkg.name}\0${pkg.version}\0${was ?? '(empty)'}`, [pkg.name, pkg.version, was ?? '(empty)'])
@@ -2719,7 +2831,7 @@ async function handleRepositoryPulse(res: ServerResponse, deps: ManagedHttpDeps,
   if (!Number.isSafeInteger(repoId) || repoId <= 0 || !PULSE_WEEKS.includes(weeks)) { sendJson(res, 400, { error: 'bad-request' }); return }
   await answerWholeRepository(res, deps, cookie, repoId, async (fullName, token) => {
     const [period, year] = await Promise.all([
-      keptAnswer(deps, `${repoId}\0pulse\0${weeks}`, () => repositoryActivity(fullName, token, weeks)),
+      keptAnswer(deps, `${repoId}\0pulse\0${weeks}`, () => pulseActivity(deps, repoId, fullName, token, weeks)),
       pulseCommits(deps, repoId, fullName, token, weeks),
     ])
     return { value: { weeks, ...period.value, stats: year.stats && periodStats(year.stats, weeks), reading: year.reading, pulls: year.pulls,
@@ -2761,6 +2873,25 @@ const pulseDay = (value: string | null) => {
   return Number.isSafeInteger(at) ? at : null
 }
 
+// The pull requests and issues of a period of `weeks` weeks, narrowed as
+// asked (`narrowing`), as the Pulse shows them: of those kept
+// (listed-activity.ts listedActivity), where they are read whole as far
+// back as the period before it starts, within the year they are read for:
+// the issues read on as far first; the pull requests as the year's commits
+// read them (pulseCommits), never further for this; else searched for
+// (repositoryActivity), as while they are read.
+async function pulseActivity(deps: ManagedHttpDeps, repoId: number, fullName: string, token: string, weeks: number, narrowing: PulseNarrowing | null = null) {
+  const now = Date.now()
+  // As far back as the period before it starts, and its narrowing's first day.
+  const need = Math.min(pulseSince(2 * weeks, now), narrowing?.from ?? Number.POSITIVE_INFINITY)
+  if (need >= pulseSince(52, now)) {
+    const [pulls, issues] = await Promise.all([keptPulls(deps, repoId, fullName, token, need, false), keptIssues(deps, repoId, fullName, token, need)])
+    const whole = (list: Listed<unknown> | null): list is Listed<unknown> => list !== null && !list.next && pullsReadTo(list) <= need
+    if (whole(pulls) && whole(issues)) return listedActivity(pulls.rows, issues.rows, weeks, now, narrowing)
+  }
+  return repositoryActivity(fullName, token, weeks, now, globalThis.fetch, narrowing)
+}
+
 // GET /api/admin/repositories/pulse/items: the Pulse tab's pull requests and
 // issues narrowed to a picked day or week (`from` to `to`, else on from
 // `from`) and the GitHub accounts a picked contributor committed as
@@ -2777,7 +2908,7 @@ async function handleRepositoryPulseItems(res: ServerResponse, deps: ManagedHttp
   await answerWholeRepository(res, deps, cookie, repoId, async (fullName, token) => {
     const narrowing = { from, to, authors }
     const items = await keptAnswer(deps, `${repoId}\0pulse-items\0${weeks}\0${from}\0${to ?? ''}\0${narrowing.authors.join(',')}`,
-      () => repositoryActivity(fullName, token, weeks, Date.now(), globalThis.fetch, narrowing))
+      () => pulseActivity(deps, repoId, fullName, token, weeks, narrowing))
     return { value: { weeks, ...items.value }, kept: items.kept }
   })
 }
@@ -2789,17 +2920,17 @@ async function pulseCommits(deps: ManagedHttpDeps, repoId: number, fullName: str
   // weeks and as many before them, which it is shown beside; the year's,
   // all of it.
   const need = Math.max(first, pulseSince(2 * weeks, now))
-  const head = await keptAnswer(deps, `${repoId}\0pulse-head`, async () => ({ sha: await defaultHead(fullName, token) }))
-  if (!head.value.sha) return { stats: commitStats([], first), reading: null, pulls: null, pending: false, kept: head.kept }
+  const head = await defaultTip(deps, repoId, fullName, token)
+  if (!head.sha) return { stats: commitStats([], first), reading: null, pulls: null, pending: false, kept: head.kept }
   const store = repositoryReadStore(deps.db, deps.config.debug)
-  const key = `${repoId}\0pulse-year\0${PULSE_YEAR_VERSION}\0${head.value.sha}\0${first}`
+  const key = `${repoId}\0pulse-year\0${PULSE_YEAR_VERSION}\0${head.sha}\0${first}`
   const lastKey = `${repoId}\0pulse-year-last`
   const mergesKey = pulseMergesKey(repoId)
   const last = async () => {
     const kept = (await store.read(lastKey))?.value as { first: number; stats: PulseStats } | undefined
     return kept && first - kept.first <= PULSE_LAST_MS ? kept.stats : null
   }
-  const sha = head.value.sha
+  const sha = head.sha
   // What tells whose the year's commits are, kept as read: the agents' pull
   // requests merged (agentMerges), as the pull requests kept tell, read as
   // far back as `whole` (keptPulls), and the commits that release the
@@ -4343,8 +4474,11 @@ async function npmReviewPublicationLimit(deps: ManagedHttpDeps, reader: NpmReade
 // Reviews are scoped to the bytes actually displayed, including the base:
 // each change but a revocation loads both versions' files, of tarballs held
 // to their integrity and to their shasum where npm tells one (npm-loads.ts),
-// and the review keeps those shasums. Access to both versions is rechecked
-// before returning or saving annotations.
+// and the review keeps those shasums. A patched version's (`patchHash`) are
+// its files as its patch changes them, the patch read where the request says
+// (`patchRepoId`, `patchCommit`, `patchPath`), of the whole of a repository
+// its reader reads (npmPatchOf), which the review keeps. Access to both
+// versions is rechecked before returning or saving annotations.
 async function handleNpmReviews(req: IncomingMessage, res: ServerResponse, deps: ManagedHttpDeps, cookie: string | undefined, params: URLSearchParams): Promise<void> {
   const method = req.method ?? 'GET'
   if (!['GET', 'POST'].includes(method)) { send405(res, 'GET, POST'); return }
@@ -4367,13 +4501,17 @@ async function handleNpmReviews(req: IncomingMessage, res: ServerResponse, deps:
   const basePackage = field('basePackage') ?? null
   const baseVersion = field('baseVersion') ?? null
   const baseIntegrity = field('baseIntegrity') ?? null
+  const patchHash = field('patchHash') ?? null
+  // Where its patch is, where it names that: its hash alone where only listed.
+  const patch = patchFields(field)
   const validIntegrity = (value: unknown): value is string => typeof value === 'string' && value.length > 0 && value.length <= 1024
   if (field('ecosystem') !== 'npm' || !isNpmPackageName(name) || !isNpmPackageSpec(version) || !validIntegrity(integrity)
     || (basePackage !== null || baseVersion !== null || baseIntegrity !== null)
-      && (!isNpmPackageName(basePackage) || !isNpmPackageSpec(baseVersion) || !validIntegrity(baseIntegrity))) {
+      && (!isNpmPackageName(basePackage) || !isNpmPackageSpec(baseVersion) || !validIntegrity(baseIntegrity))
+    || (patchHash !== null && !isPatchHash(patchHash)) || patch === 'invalid') {
     sendJson(res, 400, { error: 'bad-review-context' }); return
   }
-  const context: ReviewContext = { ecosystem: 'npm', package: name, version, integrity,
+  const context: ReviewContext = { ecosystem: 'npm', package: name, version, integrity, patchHash: patchHash as string | null,
     basePackage: basePackage as string | null, baseVersion: baseVersion as string | null, baseIntegrity: baseIntegrity as string | null }
   let change: ReviewChange | null = null
   if (mutation) {
@@ -4409,6 +4547,8 @@ async function handleNpmReviews(req: IncomingMessage, res: ServerResponse, deps:
       change = { action: 'save', reviewId: reviewId as string | null, revision: revision as number | null, entryId: entryId as string | null,
         entry: { file, comment, status: status as ReviewInput['status'] } }
     }
+    // Each change but a revocation reads a patched version's patch.
+    if (patchHash !== null && action !== 'revoke' && !patch) { sendJson(res, 400, { error: 'bad-review-context' }); return }
   }
   const controller = new AbortController()
   const onClose = () => { if (!res.writableEnded) controller.abort() }
@@ -4424,15 +4564,22 @@ async function handleNpmReviews(req: IncomingMessage, res: ServerResponse, deps:
       || (base && (base.version !== baseVersion || base.dist.integrity !== baseIntegrity))) {
       sendJson(res, 409, { error: 'review-content-changed' }); return
     }
-    // Each change but a revocation loads both versions' files; a save or a
-    // publication is held to them.
-    const loads = change && change.action !== 'revoke' ? [doc, ...base ? [base] : []].map(loadNpmFiles) : []
+    // Each change but a revocation loads both versions' files, and a patched
+    // one's patch; a save or a publication is held to them.
+    const reading = change && change.action !== 'revoke'
+    const patchRead = reading && patch ? await npmPatchOf(deps, cookie, patch) : null
+    if (patchRead && 'error' in patchRead) { sendRefusal(res, patchRead); return }
+    const loads = reading ? [doc, ...base ? [base] : []].map(loadNpmFiles) : []
     let tarballs: ReviewedTarballs | undefined
     try {
       const files = await Promise.all(loads.map(load => load.result))
-      if (loads.length > 0) tarballs = { shasum: doc.dist.shasum, baseShasum: base?.dist.shasum ?? null }
+      if (loads.length > 0) {
+        tarballs = { shasum: doc.dist.shasum, baseShasum: base?.dist.shasum ?? null,
+          ...patchRead && patch ? { patch: { repoId: patch.repoId, commit: patch.commit, path: patch.path } } : {} }
+      }
       if (change?.action === 'publish' || change?.action === 'save') {
-        const maps = files.map(list => new Map<string, unknown>(npmFileRows(list).map(([path, size, text, digest]) => [path, text ?? { format: 'digest', size, digest }])))
+        const maps = files.map((list, at) => new Map<string, unknown>(npmFileRows(at === 0 && patchRead ? patchedFiles(list, patchRead.files) : list)
+          .map(([path, size, text, digest]) => [path, text ?? { format: 'digest', size, digest }])))
         const after = maps[0]!, before = maps[1] ?? new Map<string, unknown>()
         const diff = computeBundleDiff(before, after, () => '.')
         const changed: { path: string; basePath?: string }[] = [...diff.files.onlyBase, ...diff.files.onlyOther, ...diff.files.changed]
@@ -4551,6 +4698,12 @@ async function handleNpm(req: IncomingMessage, res: ServerResponse, deps: Manage
   }
   const diffed = path === NPM_RENAME_DIFF_PATH && params.has('path') ? renameDiffRequest(params) : null
   if (path === NPM_RENAME_DIFF_PATH && params.has('path') && !diffed) { sendJson(res, 400, { error: 'bad-file' }); return }
+  // The patch a patched version's files and comparison are of, where named
+  // (`patchHash`, `patchRepoId`, `patchCommit`, `patchPath`), as Review reads them.
+  const patch = patchFields(key => params.get(key))
+  if (patch === 'invalid' || (params.has('patchHash') && !patch) || (patch && path !== NPM_PACKAGE_PATH && path !== NPM_COMPARISON_PATH)) {
+    sendJson(res, 400, { error: 'bad-patch' }); return
+  }
   const reader = await npmReader(deps, cookie, otherName === name ? [name] : [name, otherName], { handed: true })
   if (reader == null) { sendJson(res, 401, { error: 'unauthenticated' }); return }
   const controller = new AbortController()
@@ -4678,15 +4831,20 @@ async function handleNpm(req: IncomingMessage, res: ServerResponse, deps: Manage
     // same package), as Compare and Review pair them, with what their
     // Overview reads beside them (comparison.ts): the version shown against
     // the one compared with, or `(empty)`, none, as Review reads a first
-    // version. Read of both, each package's access checked again once worked out.
+    // version; as `patch` changes its files, where named, the patch read
+    // first (npmPatchOf). Read of both, each package's access checked again
+    // once worked out.
     if (path === NPM_COMPARISON_PATH) {
       const old = otherSpec === '(empty)' ? null : await otherDoc()
+      const patched = patch ? await npmPatchOf(deps, cookie, patch) : null
+      if (patched && 'error' in patched) { sendRefusal(res, patched); return }
       res.setTimeout(NPM_RESPONSE_IDLE_MS, () => res.destroy())
       const loads = [doc, ...old ? [old] : []].map(loadNpmFiles)
       let body
       try {
         const [files, oldFiles] = await Promise.all(loads.map(load => load.result))
-        body = await comparisonBody(old ? npmComparedSide(old.dist.integrity, oldFiles!) : emptySide(), npmComparedSide(doc.dist.integrity, files!))
+        body = await comparisonBody(old ? npmComparedSide(old.dist.integrity, oldFiles!) : emptySide(),
+          npmComparedSide(doc.dist.integrity, patched ? patchedFiles(files!, patched.files) : files!))
       } finally { for (const load of loads) load.release() }
       const current = await npmReader(deps, cookie, otherName === name ? [name] : [name, otherName])
       if (current == null) { body.stream.destroy(); sendJson(res, 401, { error: 'unauthenticated' }); return }
@@ -4744,6 +4902,20 @@ async function handleNpm(req: IncomingMessage, res: ServerResponse, deps: Manage
       await sendEncoded(req, res, diff, 'application/json')
       return
     }
+    // A patched version's files, as its patch changes them (npm-patch.ts),
+    // its patch read first (npmPatchOf), as Review reads them beside the
+    // version's own; none of what is asked beside those.
+    if (patch) {
+      const patched = await npmPatchOf(deps, cookie, patch)
+      if ('error' in patched) { sendRefusal(res, patched); return }
+      const load = loadNpmFiles(doc)
+      let body
+      try { body = await patchedVersionBody(doc, patch, patchedFiles(await load.result, patched.files)) } finally { load.release() }
+      if (!(await recheck(doc.private))) { body.stream.destroy(); return }
+      res.setTimeout(NPM_RESPONSE_IDLE_MS, () => res.destroy())
+      await sendEncoded(req, res, body, 'application/json')
+      return
+    }
     // The load stays held until this response is written or abandoned, and
     // a reader who stops reading it gives it up after a while. One already
     // gone takes none, as its close has passed.
@@ -5240,10 +5412,12 @@ export function createManagedRequestHandler(deps: ManagedHttpDeps): Handler {
       if (method !== 'GET') { send405(res, 'GET'); return }
       const s = workspaceSession!
       const integrity = url.searchParams.get('integrity'), name = url.searchParams.get('package'), version = url.searchParams.get('version')
-      if (!isNpmPackageName(name) || !isNpmPackageSpec(version) || !integrity || integrity.length > 1024) {
+      const patchHash = url.searchParams.get('patchHash')
+      if (!isNpmPackageName(name) || !isNpmPackageSpec(version) || !integrity || integrity.length > 1024
+        || (patchHash !== null && !isPatchHash(patchHash))) {
         sendJson(res, 400, { error: 'bad-review-context' }); return
       }
-      const review = await deps.db.getLatestOwnDependencyReview(s.user.id, { ecosystem: 'npm', package: name, version, integrity })
+      const review = await deps.db.getLatestOwnDependencyReview(s.user.id, { ecosystem: 'npm', package: name, version, integrity, patchHash })
       const visible = await readableNpmReviews(res, deps, cookie, s.user.id, review ? [review] : [], s.user)
       if (visible) sendJson(res, 200, { review: (await withFormatted(deps.reviewedDependencies ?? null, s.user.id, visible))[0] ?? null })
       return