@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/contract/state.ts

@@ -11,25 +11,47 @@ export const ChatThreadSchema = z.object({
 
 export type ChatThread = z.infer<typeof ChatThreadSchema>
 
-export const PrStateSchema = z.object({
-  version: z.literal(1),
-  /**
-   * Counts the writes to this file. The page uses it to tell a newer answer from an older one
-   * when two of its requests overlap. Absent in state files of older tool versions.
-   */
-  rev: z.number().int().nonnegative().optional(),
-  reviewed: z.record(z.string(), z.literal(true)),
-  /**
-   * The commit the reviewed marks describe. A canvas for another commit describes other code,
-   * so the marks start again when the head moves. Absent in state files of older tool versions.
-   */
-  reviewedHeadSha: z.string().optional(),
-  hiddenThreads: z.record(z.string(), z.object({ at: z.string() })),
-  posted: z.array(z.object({ commentId: z.number().int(), pointFingerprint: z.string().optional(), at: z.string() })),
-  dismissed: z.record(z.string(), z.object({ at: z.string(), reason: z.string().optional() })),
-  chat: z.object({ threads: z.array(ChatThreadSchema), activeThread: z.string().optional() }),
-  updatedAt: z.string(),
-})
+/**
+ * State files written before the marks were keyed to the canvas carry `reviewedHeadSha`, which
+ * held the same commit under its older name. The old key is read when the new one is absent, so
+ * a reviewer's marks survive the upgrade; the next write stores the new name.
+ */
+const withRenamedMarksKey = (raw: unknown): unknown => {
+  if (raw === null || typeof raw !== 'object') {
+    return raw
+  }
+  const { reviewedHeadSha, ...rest } = raw as Record<string, unknown>
+  if (reviewedHeadSha === undefined || 'reviewedCanvasSha' in rest) {
+    return raw
+  }
+  return { ...rest, reviewedCanvasSha: reviewedHeadSha }
+}
+
+export const PrStateSchema = z.preprocess(
+  withRenamedMarksKey,
+  z.object({
+    version: z.literal(1),
+    /**
+     * Counts the writes to this file. The page uses it to tell a newer answer from an older one
+     * when two of its requests overlap. Absent in state files of older tool versions.
+     */
+    rev: z.number().int().nonnegative().optional(),
+    reviewed: z.record(z.string(), z.literal(true)),
+    /**
+     * The commit of the canvas the reviewed marks were made on: the head, or the commit a carried-over
+     * canvas was generated for. A canvas for another commit describes other code, so the marks start
+     * again with it. Absent in state files of older tool versions.
+     */
+    reviewedCanvasSha: z.string().optional(),
+    hiddenThreads: z.record(z.string(), z.object({ at: z.string() })),
+    posted: z.array(
+      z.object({ commentId: z.number().int(), pointFingerprint: z.string().optional(), at: z.string() })
+    ),
+    dismissed: z.record(z.string(), z.object({ at: z.string(), reason: z.string().optional() })),
+    chat: z.object({ threads: z.array(ChatThreadSchema), activeThread: z.string().optional() }),
+    updatedAt: z.string(),
+  })
+)
 export type PrState = z.infer<typeof PrStateSchema>
 
 export function emptyState(updatedAt: string): PrState {

package/src/git/diff-collector.ts

@@ -79,7 +79,8 @@ export function parseBlock(lines: string[]): Omit<CollectedFile, 'key'> | null {
     return null
   }
 
-  const isBinary = header.some(l => l.startsWith('Binary files ')) || header.some(l => l === 'GIT binary patch')
+  const isBinary =
+    header.some(l => l.startsWith('Binary files ')) || header.some(l => l === 'GIT binary patch')
   let status: FileStatus
   if (renameFrom !== null) {
     status = 'renamed'

package/src/git/environment.mjs

@@ -0,0 +1,27 @@
+// Remove hook repository pointers so cwd selects the repository. Keep configuration,
+// credentials, and discovery limits: callers may rely on relocated config files, inline
+// config, SSH agents, proxies, or filesystem discovery fences.
+export const REPO_ENV_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+]
+
+/**
+ * `env` without those variables. Everything else is kept, so ssh agents, credential helpers,
+ * proxies, and PATH still reach `fetch`.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function envWithoutRepo(env = process.env) {
+  const clean = { ...env }
+  for (const name of REPO_ENV_VARS) {
+    delete clean[name]
+  }
+  return clean
+}

package/src/git/git.ts

@@ -1,4 +1,6 @@
 import { execFile } from 'node:child_process'
+import path from 'node:path'
+import { envWithoutRepo } from './environment.mjs'
 
 /**
  * The git operations the tool needs. Routes, stores, and the CLI receive an implementation
@@ -26,8 +28,56 @@ export interface Git {
   topLevel(): Promise<string>
   commonDir(): Promise<string>
   remoteUrl(name: string): Promise<string | null>
+  /** The checked-out branch, or null on a detached HEAD. */
+  currentBranch(): Promise<string | null>
+  /** The first of `refs` that resolves, or null when none of them do. */
+  firstExistingRef(refs: readonly string[]): Promise<string | null>
+  /** What a symbolic ref points at, in its short form; null when it is not one. */
+  symbolicRef(name: string): Promise<string | null>
+  /** `git config user.name`, the person this clone commits as; null when it is unset. */
+  configuredUser(): Promise<string | null>
+  /**
+   * A commit that holds the working tree as it is right now, or null when it matches HEAD.
+   * Nothing the user staged is touched: the snapshot is built in an index of this tool's own.
+   */
+  snapshotWorktree(): Promise<string | null>
+  /** Keeps `sha` reachable for good, whatever the working tree does next. */
+  anchorCommit(sha: string): Promise<void>
 }
 
+/**
+ * The index `snapshotWorktree` stages into, inside this worktree's own git directory rather than
+ * the one every worktree shares. It is kept between runs so git's stat cache spares a rehash of
+ * the whole tree, and `git worktree remove` takes it away with the worktree it belongs to.
+ */
+export const SNAPSHOT_INDEX = 'pr-review-canvas.index'
+
+/**
+ * Where the newest snapshot commit is anchored, so `git gc` cannot collect it between `prepare`
+ * and `publish`. `refs/worktree/` is git's own per-worktree namespace: two worktrees of one clone
+ * each keep their own snapshot instead of overwriting the single ref they would otherwise share.
+ *
+ * It moves with the working tree, so it protects one commit only. A canvas outlives the tree it
+ * was drawn from, and `anchorCommit` gives each published one an anchor of its own.
+ */
+export const SNAPSHOT_REF = 'refs/worktree/pr-review-snapshot'
+
+/** One ref per published snapshot canvas, under the same per-worktree namespace. */
+export const CANVAS_ANCHOR_PREFIX = 'refs/worktree/pr-review-canvas'
+
+/**
+ * A fixed identity and time, so the same working tree always hashes to the same commit: preparing
+ * twice without an edit lands on the canvas that already exists instead of making a second one.
+ */
+const SNAPSHOT_ENV = {
+  GIT_AUTHOR_NAME: 'pr-review',
+  GIT_AUTHOR_EMAIL: 'pr-review@localhost',
+  GIT_AUTHOR_DATE: '1970-01-01T00:00:00+0000',
+  GIT_COMMITTER_NAME: 'pr-review',
+  GIT_COMMITTER_EMAIL: 'pr-review@localhost',
+  GIT_COMMITTER_DATE: '1970-01-01T00:00:00+0000',
+} as const
+
 export const STDERR_MESSAGE_MAX = 300
 
 /**
@@ -59,21 +109,31 @@ interface ExecResult {
   code: number
 }
 
-/** Runs git with an argument array; never a shell. */
-export function execGit(cwd: string, args: string[]): Promise<ExecResult> {
+/** Runs git with an argument array; never a shell. `extra` puts back the few repo variables a
+ * command needs, such as the snapshot index. */
+export function execGit(
+  cwd: string,
+  args: string[],
+  extra: Readonly<Record<string, string>> = {}
+): Promise<ExecResult> {
   return new Promise(resolve => {
-    execFile('git', args, { cwd, encoding: 'buffer', maxBuffer: 256 * 1024 * 1024 }, (error, stdout, stderr) => {
-      const code = error && typeof error.code === 'number' ? error.code : error ? 1 : 0
-      resolve({ stdout, stderr: stderr.toString('utf8'), code })
-    })
+    execFile(
+      'git',
+      args,
+      { cwd, env: { ...envWithoutRepo(), ...extra }, encoding: 'buffer', maxBuffer: 256 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        const code = error && typeof error.code === 'number' ? error.code : error ? 1 : 0
+        resolve({ stdout, stderr: stderr.toString('utf8'), code })
+      }
+    )
   })
 }
 
 export type GitExec = typeof execGit
 
 export function createGit(cwd: string, exec: GitExec = execGit): Git {
-  async function run(args: string[]): Promise<string> {
-    const r = await exec(cwd, args)
+  async function run(args: string[], env: Readonly<Record<string, string>> = {}): Promise<string> {
+    const r = await exec(cwd, args, env)
     if (r.code !== 0) {
       throw new GitError(args, r.stderr, r.code)
     }
@@ -96,12 +156,12 @@ export function createGit(cwd: string, exec: GitExec = execGit): Git {
     fetch: async (remote, refspecs) => {
       await run(['fetch', '--no-tags', '--quiet', remote, ...refspecs])
     },
-    show: async (ref, path) => {
-      const r = await exec(cwd, ['show', `${ref}:${path}`])
+    show: async (ref, file) => {
+      const r = await exec(cwd, ['show', `${ref}:${file}`])
       return r.code === 0 ? r.stdout : null
     },
-    blobSize: async (ref, path) => {
-      const r = await exec(cwd, ['cat-file', '-s', `${ref}:${path}`])
+    blobSize: async (ref, file) => {
+      const r = await exec(cwd, ['cat-file', '-s', `${ref}:${file}`])
       return r.code === 0 ? Number(r.stdout.toString('utf8').trim()) : null
     },
     commitAuthor: ref => run(['log', '-1', '--format=%an', ref]),
@@ -111,5 +171,50 @@ export function createGit(cwd: string, exec: GitExec = execGit): Git {
       const r = await exec(cwd, ['remote', 'get-url', name])
       return r.code === 0 ? r.stdout.toString('utf8').trim() : null
     },
+    currentBranch: async () => {
+      const r = await exec(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+      return r.code === 0 ? r.stdout.toString('utf8').trim() : null
+    },
+    symbolicRef: async name => {
+      const r = await exec(cwd, ['symbolic-ref', '--quiet', '--short', name])
+      return r.code === 0 ? r.stdout.toString('utf8').trim() : null
+    },
+    configuredUser: async () => {
+      const r = await exec(cwd, ['config', '--get', 'user.name'])
+      const value = r.code === 0 ? r.stdout.toString('utf8').trim() : ''
+      return value === '' ? null : value
+    },
+    firstExistingRef: async refs => {
+      for (const ref of refs) {
+        const r = await exec(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+        if (r.code === 0) {
+          return ref
+        }
+      }
+      return null
+    },
+    snapshotWorktree: async () => {
+      const indexEnv = {
+        GIT_INDEX_FILE: path.join(
+          await run(['rev-parse', '--path-format=absolute', '--git-dir']),
+          SNAPSHOT_INDEX
+        ),
+      }
+      // `:/` stages the whole repository whatever the cwd is; ignored files stay out of it.
+      await run(['add', '-A', '--', ':/'], indexEnv)
+      const tree = await run(['write-tree'], indexEnv)
+      if (tree === (await run(['rev-parse', 'HEAD^{tree}']))) {
+        return null
+      }
+      const sha = await run(
+        ['commit-tree', tree, '-p', 'HEAD', '-m', 'pr-review: working tree snapshot'],
+        SNAPSHOT_ENV
+      )
+      await run(['update-ref', SNAPSHOT_REF, sha])
+      return sha
+    },
+    anchorCommit: async sha => {
+      await run(['update-ref', `${CANVAS_ANCHOR_PREFIX}/${sha}`, sha])
+    },
   }
 }

package/src/git/local-target.ts

@@ -0,0 +1,138 @@
+// Where a review of work that has no pull request yet takes its two commits from: the branch the
+// change will be opened against, and either the tip of the current branch or a snapshot of the
+// working tree as it stands.
+import type { Pr, Repo } from '../contract/review-artifact.js'
+import type { LocalKey } from '../contract/review-key.js'
+import { type Git, GitError } from './git.js'
+
+/** Tried in order when the user names no base: the remote's default branch first. */
+export const BASE_CANDIDATES = ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master'] as const
+
+/** `origin/HEAD` is a pointer, and a canvas that says `origin/main` reads better than one that
+ * says the pointer's name. */
+const ORIGIN_HEAD = 'origin/HEAD'
+
+export class LocalTargetError extends Error {
+  readonly hint: string
+
+  constructor(message: string, hint: string) {
+    super(message)
+    this.name = 'LocalTargetError'
+    this.hint = hint
+  }
+}
+
+/**
+ * The branch the current work will be opened against. `origin/HEAD` is the remote's own answer,
+ * so it is preferred over guessing at names; a repository that never fetched it falls back to the
+ * two usual ones.
+ */
+export async function resolveLocalBase(git: Git, override?: string | undefined): Promise<string> {
+  if (override !== undefined && override !== '') {
+    return override
+  }
+  const found = await git.firstExistingRef(BASE_CANDIDATES)
+  if (found === null) {
+    throw new LocalTargetError(
+      'no default branch to compare against',
+      'pass --base <ref>, or fetch origin so origin/HEAD resolves'
+    )
+  }
+  if (found !== ORIGIN_HEAD) {
+    return found
+  }
+  return (await git.symbolicRef(`refs/remotes/${ORIGIN_HEAD}`)) ?? ORIGIN_HEAD
+}
+
+export interface LocalHead {
+  headSha: string
+  /** The checked-out branch, or null on a detached HEAD. */
+  branch: string | null
+  /** True when the head is a snapshot of the working tree rather than a commit on the branch. */
+  uncommitted: boolean
+}
+
+/**
+ * Who the local work belongs to. Uncommitted edits are nobody's commit yet, so the name this
+ * clone commits as says more than the author of whatever HEAD happens to be.
+ */
+export async function localAuthor(git: Git, uncommitted: boolean): Promise<string> {
+  if (uncommitted) {
+    const configured = await git.configuredUser()
+    if (configured !== null) {
+      return configured
+    }
+  }
+  return git.commitAuthor('HEAD')
+}
+
+export interface DescribeLocalOptions {
+  base: string
+  source: LocalKey
+  repo: Repo
+  now: () => Date
+}
+
+/**
+ * The local work in the shape the rest of the tool reads a pull request in. `prepare` writes it to
+ * `prs/<branch|uncommitted>/pr.json` and the page resolves it again on a refresh, so both have to
+ * agree on the head, the title, and the words the header shows; they are decided here, once.
+ *
+ * The line counts are left at zero: only the collected diff knows them, and `prepare` fills them
+ * in once it has one.
+ */
+export async function describeLocalWork(git: Git, opts: DescribeLocalOptions): Promise<Pr> {
+  const head = await resolveLocalHead(git, opts.source)
+  const branch = head.branch ?? 'HEAD'
+  return {
+    number: null,
+    title: head.uncommitted ? `Uncommitted work on ${branch}` : branch,
+    body: '',
+    author: await localAuthor(git, head.uncommitted),
+    // Nothing is pushed yet, so there is no page on the forge to link to.
+    url: '',
+    state: head.uncommitted ? UNCOMMITTED_STATE : BRANCH_STATE,
+    draft: false,
+    updatedAt: opts.now().toISOString(),
+    baseRef: opts.base,
+    headRef: branch,
+    headSha: head.headSha,
+    mergeBaseSha: await git.mergeBase(opts.base, head.headSha),
+    additions: 0,
+    deletions: 0,
+    changedFiles: 0,
+    repo: opts.repo,
+  }
+}
+
+/** What `pr.state` reads for each local review. One word, because the header paints it as a pill. */
+export const BRANCH_STATE = 'branch'
+export const UNCOMMITTED_STATE = 'uncommitted'
+
+/**
+ * The commit a local review describes. The `uncommitted` review snapshots the edits and the
+ * untracked files into a commit of their own; when there are none, and for the `branch` review
+ * always, that is the tip of the current branch.
+ */
+export async function resolveLocalHead(git: Git, source: LocalKey): Promise<LocalHead> {
+  const branch = await git.currentBranch()
+  let head: string
+  try {
+    head = await git.revParse('HEAD')
+  } catch (err) {
+    if (err instanceof GitError) {
+      throw new LocalTargetError(
+        'this branch has no commits yet, so there is nothing to compare against',
+        'make one commit first, then run the review again'
+      )
+    }
+    throw err
+  }
+  if (source === 'branch') {
+    return { headSha: head, branch, uncommitted: false }
+  }
+  const snapshot = await git.snapshotWorktree()
+  return snapshot === null
+    ? { headSha: head, branch, uncommitted: false }
+    : { headSha: snapshot, branch, uncommitted: true }
+}

package/src/git/patch-lines.ts

@@ -1,8 +1,8 @@
 // The header parser and the line lookup live in static/js/hunks.js so the browser can load them
 // without a bundler; the server imports the same code here.
-import { parseHunkHeader } from '../../static/js/hunks.js'
+import { hunkForLine, parseHunkHeader } from '../../static/js/hunks.js'
 import { hunkId } from '../contract/keys.js'
-import type { Hunk } from '../contract/review-artifact.js'
+import type { FileEntry, Hunk, Side } from '../contract/review-artifact.js'
 
 export { hunkForLine, hunkLineRanges, parseHunkHeader } from '../../static/js/hunks.js'
 
@@ -58,3 +58,35 @@ export function labelPatch(key: string, patch: string): string {
     .map((h, i) => [`### hunk ${hunkId(key, i + 1)}`, h.header, ...h.lines].join('\n'))
     .join('\n')
 }
+
+export interface InlineTarget {
+  path: string
+  line: number
+  side: Side
+  startLine?: number | undefined
+}
+
+/**
+ * Whether a comment targets lines in the local diff: the file is in the diff, and the whole
+ * range sits inside one hunk on that side. Returns the reason when it will not, so the route can
+ * refuse before the request leaves the machine.
+ */
+export function checkInlineTarget(files: ReadonlyArray<FileEntry>, target: InlineTarget): string | null {
+  const file = files.find(f => f.path === target.path)
+  if (file === undefined) {
+    return `${target.path} is not in the diff`
+  }
+  const hunk = hunkForLine(file.hunks, target.side, target.line)
+  if (hunk === null) {
+    return `${target.path}:${target.line} (${target.side}) is not in the diff`
+  }
+  if (target.startLine !== undefined) {
+    if (target.startLine > target.line) {
+      return `the first line of the range must come before ${target.line}`
+    }
+    if (hunkForLine(file.hunks, target.side, target.startLine) !== hunk) {
+      return `${target.path}:${target.startLine}-${target.line} (${target.side}) spans more than one chunk`
+    }
+  }
+  return null
+}

package/src/git/pr-refs.ts

@@ -0,0 +1,36 @@
+import type { Git } from './git.js'
+import type { Host } from '../host/host.js'
+import type { PrMeta } from '../host/pr.js'
+
+export function prHeadRef(number: number): string {
+  return `refs/pr/${number}/head`
+}
+
+export function prBaseRef(number: number): string {
+  return `refs/pr/${number}/base`
+}
+
+/**
+ * Fetches the review's head and base into local refs and resolves the two commits the diff needs.
+ * The local refs are the ones the prior-art skill used, so an existing clone keeps working, and
+ * they are the same for both hosts; only the remote ref that holds the head differs.
+ *
+ * A merged PR is diffed against the base as it was at merge time: the merge commit's first
+ * parent (a merge commit, a squash, or the last rebased commit all sit on the base branch, so
+ * it is local once the base was fetched). Today's base tip would contain the PR and give an
+ * empty diff.
+ */
+export async function fetchPrRefs(
+  git: Git,
+  host: Host,
+  meta: PrMeta
+): Promise<{ headSha: string; mergeBaseSha: string }> {
+  await git.fetch('origin', [
+    `+${host.remoteHeadRef(meta.number)}:${prHeadRef(meta.number)}`,
+    `+refs/heads/${meta.baseRef}:${prBaseRef(meta.number)}`,
+  ])
+  const headSha = await git.revParse(prHeadRef(meta.number))
+  const base = meta.mergeCommitSha === null ? prBaseRef(meta.number) : `${meta.mergeCommitSha}^1`
+  const mergeBaseSha = await git.mergeBase(base, headSha)
+  return { headSha, mergeBaseSha }
+}