@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/review/review-record-cli.ts

@@ -1,11 +1,10 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
 import { review_comment_round } from './review-comment-round'
-import { review_finding_ledger, type Finding } from './review-finding-ledger'
+import { review_finding_ledger, type Finding, type LineKind } from './review-finding-ledger'
+import { review_interaction } from './review-interaction'
 import { review_record, type RecordVerdict } from './review-record'
 
 // `josh review:record --issue <N> [<category>:<severity>:<file> ...]` — the one write path for a
@@ -23,16 +22,21 @@ import { review_record, type RecordVerdict } from './review-record'
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
 // merges: `ok` / `not-required` exit zero, `missing` exits non-zero so the
 // merge is refused until the round is recorded. It mirrors `josh review:attest --check`.
+//
+// **`--interaction` records and checks the interaction review's pass instead** (`review-interaction.ts`):
+// the same grammar under `- ri:`. It takes no `--comment` — the pass runs before the pull request, and
+// a pass kept only on the issue would leave the merge gate reading it as missing.
 
-const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh review:record --issue <N> [--comment] [<category>:<severity>:<file> ...] | josh review:record --check --issue <N>'
+	'Usage: josh review:record --issue <N> [--comment | --interaction] [<category>:<severity>:<file> ...] | josh review:record --check [--interaction] --issue <N>'
 const FILE_HINT = '  <file>: the cited path, optionally with :line'
-const CHECK_USAGE = 'Usage: josh review:record --check --issue <N>'
+const CHECK_USAGE = 'Usage: josh review:record --check [--interaction] --issue <N>'
 const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
 const NOT_REQUIRED_LINE =
 	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
+const INTERACTION_NOT_REQUIRED_LINE =
+	'No interaction review is due: the change touches no run tooling, or this checkout keeps no ledger.'
 const CARRIED_LINE =
 	'review-finding line(s) recorded on closed issues after their pull requests opened into the ledger.'
 const CARRY_FAILED_LINE =
@@ -41,6 +45,7 @@ const OPTIONS = {
 	issue: { type: 'string' },
 	check: { type: 'boolean' },
 	comment: { type: 'boolean' },
+	interaction: { type: 'boolean' },
 } as const
 
 interface Request {
@@ -51,6 +56,7 @@ interface Request {
 interface Parsed {
 	check: boolean
 	comment: boolean
+	interaction: boolean
 	issue: string | undefined
 	positionals: ReadonlyArray<string>
 }
@@ -99,6 +105,7 @@ function parse_argv(argv: ReadonlyArray<string>): Parsed | undefined {
 	return {
 		check: parsed.values.check === true,
 		comment: parsed.values.comment === true,
+		interaction: parsed.values.interaction === true,
 		issue: parsed.values.issue,
 		positionals: parsed.positionals,
 	}
@@ -129,13 +136,17 @@ function usage_text(): string {
 	].join('\n')
 }
 
-function build_lines(request: Request, date: string): ReadonlyArray<string> {
+function build_lines(
+	request: Request,
+	date: string,
+	kind: LineKind = 'code',
+): ReadonlyArray<string> {
 	if (request.findings.length === 0) {
-		return [review_finding_ledger.zero_round_line(date, request.issue)]
+		return [review_finding_ledger.zero_round_line(date, request.issue, kind)]
 	}
 
 	return request.findings.map((finding) =>
-		review_finding_ledger.finding_line(finding, date, request.issue),
+		review_finding_ledger.finding_line(finding, date, request.issue, kind),
 	)
 }
 
@@ -143,28 +154,62 @@ function confirmation(count: number, ledger_path: string): string {
 	return `Recorded ${String(count)} review-finding line(s) in ${ledger_path}.`
 }
 
-function check_line(verdict: RecordVerdict): string {
-	return verdict.status === 'ok' ? RECORDED_LINE : NOT_REQUIRED_LINE
+type CheckStatus = RecordVerdict['status']
+
+interface CheckMode {
+	status: (issue: number, root: string) => Promise<CheckStatus>
+	refusal: (issue: number) => string
+	not_required: string
 }
 
-async function run_check(issue: string | undefined, root: string): Promise<number> {
-	if (issue === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) {
-		console.error(CHECK_USAGE)
+async function code_status(issue: number, root: string): Promise<CheckStatus> {
+	const verdict = await review_record.check(issue, root)
+
+	return verdict.status
+}
+
+// The two rounds a check reads, each with its own ledger line, refusal and quiet answer.
+const CHECK_MODES: Record<LineKind, CheckMode> = {
+	code: {
+		status: code_status,
+		refusal: review_record.refusal_message,
+		not_required: NOT_REQUIRED_LINE,
+	},
+	interaction: {
+		status: review_interaction.status,
+		refusal: review_interaction.refusal_message,
+		not_required: INTERACTION_NOT_REQUIRED_LINE,
+	},
+}
+
+function kind_of(parsed: Parsed): LineKind {
+	return parsed.interaction ? 'interaction' : 'code'
+}
+
+async function report_check(issue: number, mode: CheckMode, root: string): Promise<number> {
+	const status = await mode.status(issue, root)
+
+	if (status === 'missing') {
+		console.error(mode.refusal(issue))
 
 		return FAILURE_EXIT_CODE
 	}
 
-	const verdict = await review_record.check(Number(issue), root)
+	console.info(status === 'ok' ? RECORDED_LINE : mode.not_required)
 
-	if (verdict.status === 'ok' || verdict.status === 'not-required') {
-		console.info(check_line(verdict))
+	return 0
+}
 
-		return 0
-	}
+async function run_check(parsed: Parsed, root: string): Promise<number> {
+	const { issue } = parsed
+
+	if (issue === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) {
+		console.error(CHECK_USAGE)
 
-	console.error(review_record.refusal_message(Number(issue)))
+		return FAILURE_EXIT_CODE
+	}
 
-	return FAILURE_EXIT_CODE
+	return await report_check(Number(issue), CHECK_MODES[kind_of(parsed)], root)
 }
 
 // **A comment that could not be posted fails the record**: it is the round's only copy, so a
@@ -216,7 +261,7 @@ async function append_round(
 }
 
 async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
-	const request = to_request(parsed)
+	const request = parsed.comment && parsed.interaction ? undefined : to_request(parsed)
 
 	if (request === undefined) {
 		console.error(usage_text())
@@ -224,7 +269,7 @@ async function run_record(parsed: Parsed, now: Date, root: string): Promise<numb
 		return FAILURE_EXIT_CODE
 	}
 
-	const lines = build_lines(request, observation_ledger_home.ledger_date(now))
+	const lines = build_lines(request, observation_ledger_home.ledger_date(now), kind_of(parsed))
 
 	if (parsed.comment) return await post_comment(request.issue, lines)
 
@@ -247,15 +292,11 @@ async function run(
 		return FAILURE_EXIT_CODE
 	}
 
-	if (parsed.check) return await run_check(parsed.issue, root)
+	if (parsed.check) return await run_check(parsed, root)
 
 	return await run_record(parsed, now, root)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv, new Date())
-}
-
 const review_record_cli = {
 	accepted_values,
 	build_lines,
@@ -264,6 +305,4 @@ const review_record_cli = {
 	usage_text,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { review_record_cli }

package/scripts/review/review-record-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { review_record_cli } from './review-record-cli'
+
+// The `josh review:record` entry, kept apart from `review-record-cli.ts` because `run-ship-review.ts`
+// imports that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await review_record_cli.run(process.argv.slice(ARGV_OFFSET), new Date())
+}

package/scripts/review/review-round-one-blobs.ts

@@ -0,0 +1,221 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { review_tree } from './review-tree'
+
+// Round 1's files as git blobs, so round 2 can still name the fix delta after the change base moved
+// (joshuafolkken/kit#4165).
+//
+// **A lane merges the default branch between the rounds**, which moves the base, and the round-1 file
+// map then covers a different set of paths from the one read now. Its digests cannot be carried onto
+// the new base; blobs can. `capture` writes each round-1 path into the object store — nothing else:
+// no index, no commit, no ref. `carried_delta` then carries each path three ways — the old base, round
+// 1, the new base — and names the paths whose carried content differs from the working tree now. A
+// path the default branch alone changed carries to exactly what the merge left, so it drops out; what
+// is left is round 1's fixes.
+//
+// **Every failure answers `undefined`**, which round 2 reads as the moved-base refusal it gave before:
+// no recorded blobs, a carry that conflicts, or a git that cannot run one of the reads.
+
+// A path the working tree or a commit does not hold.
+const ABSENT = review_tree.ABSENT_DIGEST
+const SUCCESS_EXIT_CODE = 0
+const NUL = '\0'
+const NEWLINE = '\n'
+const TAB = '\t'
+const SPACE = ' '
+const OID_FIELD = 2
+const WRITE_FLAGS: ReadonlyArray<string> = ['-w']
+const READ_FLAGS: ReadonlyArray<string> = []
+
+interface Move {
+	// The base round 1 was read against, and the base now.
+	from: string | undefined
+	to: string | undefined
+	// The paths to read: for a carry, those changed against the base now.
+	paths: ReadonlyArray<string>
+}
+
+interface CarryInput extends Move {
+	// Round 1's blobs, from the snapshot.
+	blobs: Record<string, string> | undefined
+}
+
+interface Carry {
+	blobs: Record<string, string>
+	from: string
+	to: string
+	paths: ReadonlyArray<string>
+}
+
+interface Readings {
+	blobs: Record<string, string>
+	before: Record<string, string>
+	after: Record<string, string>
+	now: Record<string, string>
+}
+
+interface Sides {
+	base: string
+	round_one: string
+	moved: string
+}
+
+// git's paths are root-relative, so every command runs from the root rather than the caller's cwd.
+function repository_root(): string | undefined {
+	return git_spawn_sync.read(['rev-parse', '--show-toplevel'])
+}
+
+function hash_paths(
+	root: string,
+	paths: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): Record<string, string> | undefined {
+	const present = paths.filter((relative) => existsSync(path.join(root, relative)))
+	const output =
+		present.length === 0
+			? ''
+			: git_spawn_sync.read(['hash-object', ...flags, '--', ...present], { cwd: root })
+
+	if (output === undefined) return undefined
+
+	const hashes = output.split(NEWLINE)
+	const hashed = new Map(present.map((relative, index) => [relative, hashes[index] ?? ABSENT]))
+
+	return Object.fromEntries(paths.map((relative) => [relative, hashed.get(relative) ?? ABSENT]))
+}
+
+// `<mode> <type> <oid>\t<path>`.
+function parse_entry(entry: string): [string, string] {
+	const tab = entry.indexOf(TAB)
+
+	return [entry.slice(tab + 1), entry.slice(0, tab).split(SPACE)[OID_FIELD] ?? ABSENT]
+}
+
+function blobs_at(
+	commit: string,
+	paths: ReadonlyArray<string>,
+	root: string,
+): Record<string, string> | undefined {
+	const result = git_spawn_sync.run(['ls-tree', '-r', '-z', commit, '--', ...paths], { cwd: root })
+
+	if (result.exit_code !== SUCCESS_EXIT_CODE) return undefined
+
+	return Object.fromEntries(
+		result.stdout
+			.split(NUL)
+			.filter((entry) => entry !== '')
+			.map((entry) => parse_entry(entry)),
+	)
+}
+
+// `git merge-file` exits with the number of conflicts, so only a clean merge answers an oid.
+function merged_blob({ base, round_one, moved }: Sides, root: string): string | undefined {
+	if ([base, round_one, moved].includes(ABSENT)) return undefined
+
+	return git_spawn_sync.read(['merge-file', '--object-id', round_one, base, moved], { cwd: root })
+}
+
+function carried_blob(sides: Sides, root: string): string | undefined {
+	if (sides.round_one === sides.base) return sides.moved
+	if (sides.moved === sides.base || sides.moved === sides.round_one) return sides.round_one
+
+	return merged_blob(sides, root)
+}
+
+// A path round 1 did not list was unchanged against its base, so round 1 held the base's blob.
+function sides_of(relative: string, readings: Readings): Sides {
+	const base = readings.before[relative] ?? ABSENT
+
+	return {
+		base,
+		round_one: readings.blobs[relative] ?? base,
+		moved: readings.after[relative] ?? ABSENT,
+	}
+}
+
+function differing(
+	paths: ReadonlyArray<string>,
+	readings: Readings,
+	root: string,
+): ReadonlyArray<string> | undefined {
+	const carried = paths.map((relative) => carried_blob(sides_of(relative, readings), root))
+
+	if (carried.includes(undefined)) return undefined
+
+	return paths.filter((relative, index) => carried[index] !== readings.now[relative])
+}
+
+function read_readings(
+	input: Carry,
+	paths: ReadonlyArray<string>,
+	root: string,
+): Readings | undefined {
+	const before = blobs_at(input.from, paths, root)
+	const after = blobs_at(input.to, paths, root)
+	const now = hash_paths(root, paths, READ_FLAGS)
+
+	if (before === undefined || after === undefined || now === undefined) return undefined
+
+	return { blobs: input.blobs, before, after, now }
+}
+
+// No paths at all is an empty delta: `ls-tree` given none would list the whole tree.
+function delta_of(input: Carry, root: string): ReadonlyArray<string> | undefined {
+	const paths = [...new Set([...Object.keys(input.blobs), ...input.paths])].toSorted(
+		(left, right) => left.localeCompare(right),
+	)
+	const readings = paths.length === 0 ? undefined : read_readings(input, paths, root)
+
+	if (paths.length === 0) return []
+
+	return readings === undefined ? undefined : differing(paths, readings, root)
+}
+
+function carried_delta(input: CarryInput): ReadonlyArray<string> | undefined {
+	const { blobs, from, to } = input
+	const root = repository_root()
+
+	if (root === undefined || blobs === undefined || from === undefined || to === undefined) {
+		return undefined
+	}
+
+	return delta_of({ blobs, from, to, paths: input.paths }, root)
+}
+
+function unmoved_between(
+	from: string,
+	to: string,
+	paths: ReadonlyArray<string>,
+	root: string,
+): ReadonlyArray<string> | undefined {
+	if (from === to || paths.length === 0) return paths
+	const before = blobs_at(from, paths, root)
+	const after = blobs_at(to, paths, root)
+
+	if (before === undefined || after === undefined) return undefined
+
+	return paths.filter((relative) => (before[relative] ?? ABSENT) === (after[relative] ?? ABSENT))
+}
+
+// The paths the base move left alone: there the carry reproduces round 1's file, so the fix delta on
+// them is round 1 against the working tree, as on an unmoved base. `undefined` when git cannot say.
+function unmoved({ from, to, paths }: Move): ReadonlyArray<string> | undefined {
+	const root = repository_root()
+
+	if (root === undefined || from === undefined || to === undefined) return undefined
+
+	return unmoved_between(from, to, paths, root)
+}
+
+// Each path's blob, written into the object store so a later carry can merge it; `undefined` when git
+// cannot answer, which the record then omits.
+function capture(paths: ReadonlyArray<string>): Record<string, string> | undefined {
+	const root = repository_root()
+
+	return root === undefined ? undefined : hash_paths(root, paths, WRITE_FLAGS)
+}
+
+const review_round_one_blobs = { capture, carried_delta, unmoved }
+
+export { review_round_one_blobs }

package/scripts/review/review-round2-cli.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { change_base } from '#scripts/git/change-base'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { path_decision } from '#scripts/josh/path-decision'
 import { review_code_tree } from './review-code-tree'
-import { review_round2 } from './review-round2'
+import { review_round_one_blobs } from './review-round-one-blobs'
+import { review_round2, type RoundTwoAnswer } from './review-round2'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
 
@@ -17,7 +19,6 @@ import { review_tree } from './review-tree'
 
 const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh review:round2 [--round-1-closed] [--json]'
-const JSON_KEY = 'round2'
 const FAILURE_EXIT_CODE = 1
 
 // The one input no command can read for itself, so the caller states it: every round-1 High/Medium
@@ -48,9 +49,37 @@ function parse_options(argv: ReadonlyArray<string>): Options | undefined {
 // Only the paths the code record covers are re-read, so a run without one parses nothing.
 async function read_comment_only(base: string | undefined): Promise<ReadonlyArray<string>> {
 	const snapshot = review_stamps.round_one_code_stamp.read()
-	const tree = await review_code_tree.read(Object.keys(snapshot?.files ?? {}))
+	const paths = Object.keys(snapshot?.files ?? {})
+	const tree = await review_code_tree.read(paths)
+	const unmoved = review_round_one_blobs.unmoved({ from: snapshot?.base, to: base, paths })
 
-	return review_code_tree.comment_only(snapshot, tree, base)
+	return review_code_tree.comment_only(snapshot, tree, base, unmoved)
+}
+
+// The carry over every path changed now, not only round 1's: a file the fix added after the merge is
+// in no round-1 record and has to be named all the same.
+function carried_reader(
+	base: string | undefined,
+	tree: Record<string, string>,
+): (snapshot: FileMapStamp) => ReadonlyArray<string> | undefined {
+	return (snapshot) =>
+		review_round_one_blobs.carried_delta({
+			blobs: snapshot.blobs,
+			from: snapshot.base,
+			to: base,
+			paths: Object.keys(tree),
+		})
+}
+
+// `--json` carries the reason code as well, the field `josh ship` records in the lane ledger.
+function print(answer: RoundTwoAnswer, is_json: boolean): void {
+	if (is_json) {
+		console.info(review_round2.to_json(answer))
+
+		return
+	}
+
+	path_decision.print_decision(review_round2.JSON_KEY, answer.verdict, answer.reason, is_json)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -66,19 +95,20 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	// against a different one — and the resolved commit rather than `git_command.change_base`, whose
 	// fallback is a ref name that moves and would compare equal to itself.
 	const base = await change_base.resolved()
-	const { verdict, reason } = review_round2.decide({
+	// No paths argument: `read_changed_tree` reads them itself, from the one definition of "changed"
+	// `josh review:level` and `josh review:brief` all decide from. Passing our own reading would be a
+	// second definition, which is the drift that module exists to prevent.
+	const tree = await review_tree.read_changed_tree()
+	const decision = review_round2.decide({
 		base,
+		carried_delta: carried_reader(base, tree),
 		comment_only: await read_comment_only(base),
 		is_round_one_closed: options.is_round_one_closed,
 		snapshot: review_stamps.round_one_stamp.read(),
-		// No paths argument: `read_changed_tree` reads them itself, from the one definition of
-		// "changed" `josh review:level` and `josh review:brief` all decide from.
-		// Passing our own reading would be a second definition, which is the drift that module exists
-		// to prevent.
-		tree: await review_tree.read_changed_tree(),
+		tree,
 	})
 
-	path_decision.print_decision(JSON_KEY, verdict, reason, options.is_json)
+	print(decision, options.is_json)
 
 	return 0
 }
@@ -87,7 +117,14 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const review_round2_cli = { CLOSED_FLAG, parse_options, read_comment_only, run }
+const review_round2_cli = {
+	CLOSED_FLAG,
+	carried_reader,
+	parse_options,
+	print,
+	read_comment_only,
+	run,
+}
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))