@joshuafolkken/kit 1.1514.0 → 1.1784.0

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))
 

package/scripts/review/review-round2.ts

@@ -1,5 +1,7 @@
 import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { path_decision } from '#scripts/josh/path-decision'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
 import { review_level } from './review-level'
 
 // Whether the second review round runs at all.
@@ -22,6 +24,28 @@ type RoundTwoVerdict = 'required' | 'skip'
 
 const REQUIRED_VERDICT: RoundTwoVerdict = 'required'
 const SKIPPED_VERDICT: RoundTwoVerdict = 'skip'
+const VERDICTS = [REQUIRED_VERDICT, SKIPPED_VERDICT] as const
+
+// One stable code per branch of `decide`, so a decision can be counted by why it fell where it did —
+// the reason sentences carry paths and timestamps and cannot be (joshuafolkken/kit#4064).
+const CODE = {
+	EMPTY: 'empty',
+	INERT: 'inert',
+	OPEN_FINDING: 'open-finding',
+	NO_SNAPSHOT: 'no-snapshot',
+	BASE_MOVED: 'base-moved',
+	LIVE: 'live',
+} as const
+
+type RoundTwoCode = (typeof CODE)[keyof typeof CODE]
+
+// The key `josh review:round2 --json` prints its verdict under, read back by `josh ship`.
+const JSON_KEY = 'round2'
+const json_schema = z.object({
+	[JSON_KEY]: z.enum(VERDICTS),
+	code: z.enum(Object.values(CODE)),
+	reason: z.string(),
+})
 
 // **The default is `required`, and every uncertainty resolves to it.** A command that answered `skip`
 // on a missing record would be the cheapest possible run and the most dangerous — the direction
@@ -39,7 +63,7 @@ const DOCUMENTATION_PREFIX = 'docs/'
 const MARKDOWN_EXTENSION = '.md'
 const PROMPTS_PREFIX = 'prompts/'
 const BASE_MOVED_REASON =
-	'the change base moved since round 1 was recorded, so the two file maps do not cover the same set of paths and their difference is not the fix delta — the round runs rather than reading that difference as one'
+	"the change base moved since round 1 was recorded and round 1's tree could not be carried onto the new one — no recorded round-1 blobs, or the carry conflicts — so the fix delta cannot be named and the round runs"
 
 interface RoundTwoInput {
 	// **The commit the tree above is a diff against**. This decision reads the
@@ -58,11 +82,18 @@ interface RoundTwoInput {
 	// The paths whose code round 1's fixes left as it was (`review_code_tree.comment_only`). Absent is
 	// none, which is what a run without a code record pays.
 	comment_only?: ReadonlyArray<string>
+	// Asked only when the base moved: round 1's tree carried onto the current base, diffed against the
+	// tree now (`review-round-one-blobs.ts`). `undefined`, or no reader at all, is the moved-base refusal.
+	carried_delta?: (snapshot: FileMapStamp) => ReadonlyArray<string> | undefined
 }
 
-interface RoundTwoDecision {
+interface RoundTwoAnswer {
 	verdict: RoundTwoVerdict
+	code: RoundTwoCode
 	reason: string
+}
+
+interface RoundTwoDecision extends RoundTwoAnswer {
 	// The paths round 1's fixes changed. Returned even on `required` so the caller can name them, and
 	// on a `skip` so the record the run leaves behind says what went unreviewed.
 	delta: ReadonlyArray<string>
@@ -109,43 +140,80 @@ function verdict_for_delta(
 	delta: ReadonlyArray<string>,
 	taken_at: string,
 	comment_only: ReadonlyArray<string> = [],
-): { verdict: RoundTwoVerdict; reason: string } {
-	if (delta.length === 0) return { verdict: SKIPPED_VERDICT, reason: empty_reason(taken_at) }
+): RoundTwoAnswer {
+	if (delta.length === 0) {
+		return { verdict: SKIPPED_VERDICT, code: CODE.EMPTY, reason: empty_reason(taken_at) }
+	}
 
 	const deciding = delta.filter((relative) => !is_unexecuted(relative, comment_only))
 
-	if (deciding.length === 0) return { verdict: SKIPPED_VERDICT, reason: inert_reason(delta) }
+	if (deciding.length === 0) {
+		return { verdict: SKIPPED_VERDICT, code: CODE.INERT, reason: inert_reason(delta) }
+	}
 
-	return { verdict: REQUIRED_VERDICT, reason: live_reason(deciding) }
+	return { verdict: REQUIRED_VERDICT, code: CODE.LIVE, reason: live_reason(deciding) }
 }
 
-function required(reason: string): RoundTwoDecision {
-	return { verdict: REQUIRED_VERDICT, reason, delta: [] }
+function required(code: RoundTwoCode, reason: string): RoundTwoDecision {
+	return { verdict: REQUIRED_VERDICT, code, reason, delta: [] }
+}
+
+// On a moved base the digest comparison is a set difference, not the fix delta, so the carried
+// reading replaces it and every later rule is the same one an unmoved base gets.
+function fix_delta(
+	input: RoundTwoInput,
+	snapshot: FileMapStamp,
+): ReadonlyArray<string> | undefined {
+	if (file_map_stamp.describes_base(snapshot, input.base)) {
+		return file_map_stamp.changed_since(snapshot, input.tree)
+	}
+
+	return input.carried_delta?.(snapshot)
 }
 
 function decide(input: RoundTwoInput): RoundTwoDecision {
-	if (!input.is_round_one_closed) return required(OPEN_FINDING_REASON)
-	if (input.snapshot === undefined) return required(NO_SNAPSHOT_REASON)
-	if (!file_map_stamp.describes_base(input.snapshot, input.base)) return required(BASE_MOVED_REASON)
+	if (!input.is_round_one_closed) return required(CODE.OPEN_FINDING, OPEN_FINDING_REASON)
+	if (input.snapshot === undefined) return required(CODE.NO_SNAPSHOT, NO_SNAPSHOT_REASON)
+
+	const delta = fix_delta(input, input.snapshot)
 
-	const delta = file_map_stamp.changed_since(input.snapshot, input.tree)
+	if (delta === undefined) return required(CODE.BASE_MOVED, BASE_MOVED_REASON)
 
 	return { ...verdict_for_delta(delta, input.snapshot.taken_at, input.comment_only), delta }
 }
 
+function to_json(answer: RoundTwoAnswer): string {
+	return JSON.stringify({ [JSON_KEY]: answer.verdict, code: answer.code, reason: answer.reason })
+}
+
+// The answer `to_json` printed, or `undefined` for any other output — read by the one caller that
+// records it, which must not guess a verdict from text it cannot parse.
+function parse_json(text: string): RoundTwoAnswer | undefined {
+	const parsed = json_schema.safeParse(json_value.parse_or_undefined(text.trim())).data
+
+	return parsed === undefined
+		? undefined
+		: { verdict: parsed[JSON_KEY], code: parsed.code, reason: parsed.reason }
+}
+
 const review_round2 = {
 	BASE_MOVED_REASON,
+	CODE,
 	decide,
 	EMPTY_DELTA_REASON_PREFIX,
 	empty_reason,
 	INERT_DELTA_REASON_PREFIX,
 	inert_reason,
+	JSON_KEY,
 	live_reason,
 	NO_SNAPSHOT_REASON,
 	OPEN_FINDING_REASON,
+	parse_json,
 	REQUIRED_VERDICT,
 	SKIPPED_VERDICT,
+	to_json,
 	verdict_for_delta,
 }
 
+export type { RoundTwoAnswer, RoundTwoCode, RoundTwoVerdict }
 export { review_round2 }

package/scripts/review/review-stamps.ts

@@ -1,3 +1,5 @@
+import { gate_plan } from '#scripts/gate/gate-plan'
+import { verification_inputs } from '#scripts/gate/verification-inputs'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
 
@@ -9,6 +11,8 @@ import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-
 // The scoped stamps claim less than the gate stamp (changed files, two checks), so they stay separate.
 const LINT_RELATED_PREFIX = 'josh-lint-related-stamp-'
 const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
+// `josh test:e2e` answered green — a run or a printed skip — on this tree (`test-e2e-stamp.ts`).
+const E2E_PREFIX = 'josh-e2e-stamp-'
 
 const GATE_PREFIX = 'josh-gate-stamp-'
 const IN_FLIGHT_PREFIX = 'josh-gate-running-'
@@ -16,7 +20,17 @@ const ROUND_ONE_PREFIX = 'josh-review-round1-'
 const ROUND_ONE_CODE_PREFIX = 'josh-review-round1-code-'
 const BRIEFED_PREFIX = 'josh-review-briefed-'
 
-const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
+// The records that vouch for a check carry the fingerprint of its declared inputs
+// (`verification-inputs.ts`): the gate's every declared check, a scoped record its own.
+function inputs_of(labels: ReadonlyArray<string>): () => string {
+	return () => verification_inputs.fingerprint(labels)
+}
+
+const gate_stamp: FileMapStampAccess = file_map_stamp.create(
+	GATE_PREFIX,
+	PROJECT_ROOT,
+	inputs_of(verification_inputs.DECLARED_LABELS),
+)
 const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
 const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
 // Written beside the round-1 snapshot: the comment-free digest of each source file (`review-code-tree.ts`).
@@ -29,11 +43,14 @@ const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX,
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	LINT_RELATED_PREFIX,
 	PROJECT_ROOT,
+	inputs_of([gate_plan.LINT_LABEL]),
 )
 const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	TEST_RELATED_PREFIX,
 	PROJECT_ROOT,
+	inputs_of([gate_plan.UNIT_LABEL]),
 )
+const e2e_stamp: FileMapStampAccess = file_map_stamp.create(E2E_PREFIX, PROJECT_ROOT)
 
 // Swallowed: a code record left behind only ever sits beside an older snapshot, which the next
 // round-1 brief replaces together with it.
@@ -61,6 +78,7 @@ const review_stamps = {
 	briefed_stamp,
 	clear_round_one,
 	clear_round_one_code,
+	e2e_stamp,
 	GATE_PREFIX,
 	gate_stamp,
 	IN_FLIGHT_PREFIX,

package/scripts/review/review-stop-log.ts

@@ -0,0 +1,96 @@
+import { mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { json_value } from '#scripts/lib/json-value'
+import type { StopFinding } from '#scripts/run/ship/run-ship-review'
+import { z } from 'zod'
+
+// The durable record of every review finding that stopped a `josh ship` — one JSON line per finding,
+// with its kind, the `<file>[:<line>]` it cites and its first sentence, read back by
+// `josh review:stops` (joshuafolkken/kit#4519). The lane ledger's stop line keeps only the kinds, and
+// the finding's text was only in the ship log in the temp root, which a reboot clears.
+//
+// **It lives in the git common directory**, beside the test-read map: every lane worktree of one clone
+// appends to the same file, and a reboot keeps it. Appended with the lane ledger's `append`, so
+// concurrent lanes never lose each other's lines.
+//
+// **A test run writes nothing** unless it passes its own path, the lane ledger's rule: the writer sits on
+// the ship's stop path, which many suites exercise.
+
+const LOG_DIRECTORY = 'josh'
+const LOG_FILE = 'review-stops.jsonl'
+const LINE_SEPARATOR = '\n'
+
+const stop_line_schema = z.object({
+	at: z.string(),
+	issue: z.number(),
+	stage: z.string(),
+	kind: z.string(),
+	location: z.string(),
+	sentence: z.string(),
+})
+
+type StopLine = z.infer<typeof stop_line_schema>
+
+// One stopped review: the issue, the stage that stopped and the findings that decided it.
+interface ReviewStop {
+	issue: number
+	stage: string
+	findings: ReadonlyArray<StopFinding>
+}
+
+function target(): string | undefined {
+	if (process.env['VITEST'] !== undefined) return undefined
+
+	const common = git_common_directory.repository()
+
+	return common === undefined ? undefined : path.join(common, LOG_DIRECTORY, LOG_FILE)
+}
+
+function write(destination: string, stop: ReviewStop): void {
+	const at = new Date().toISOString()
+
+	mkdirSync(path.dirname(destination), { recursive: true })
+
+	for (const finding of stop.findings) {
+		lane_ledger.append(destination, { at, issue: stop.issue, stage: stop.stage, ...finding })
+	}
+}
+
+// Best-effort, as the lane ledger is: a record must never fail the stop it records.
+function record(stop: ReviewStop, log_path: string | undefined = target()): void {
+	if (log_path === undefined || stop.findings.length === 0) return
+
+	try {
+		write(log_path, stop)
+	} catch {
+		// Recording is best-effort: a failed append is dropped rather than raised into the ship's stop.
+	}
+}
+
+function parse_line(line: string): StopLine | undefined {
+	return stop_line_schema.safeParse(json_value.parse_or_undefined(line)).data
+}
+
+function is_present(line: StopLine | undefined): line is StopLine {
+	return line !== undefined
+}
+
+// Every recorded finding, oldest first; a malformed line — a write cut short — is skipped.
+function read(log_path: string | undefined = target()): ReadonlyArray<StopLine> {
+	const raw = log_path === undefined ? undefined : stamp_file.read_stamp_text(log_path)
+
+	if (raw === undefined) return []
+
+	return raw
+		.split(LINE_SEPARATOR)
+		.map((line) => parse_line(line.trim()))
+		.filter(is_present)
+}
+
+const review_stop_log = { read, record, target }
+
+export type { ReviewStop, StopLine }
+export { review_stop_log }

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_stats } from '#scripts/lane/lane-stats'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { review_stop_log, type StopLine } from './review-stop-log'
+
+// `josh review:stops [--period <days>]` — every review finding that stopped a `josh ship` in the last
+// `<days>` (7 by default), one line each, ordered by kind and then file so the findings of one kind and
+// one place sit together for classification (joshuafolkken/kit#4519). The write half is
+// `review-stop-log.ts`, called on every ship stop.
+
+const OPTIONS = { period: { type: 'string' } } as const
+const DEFAULT_PERIOD_DAYS = 7
+const USAGE = 'usage: josh review:stops [--period <days>]'
+const NO_SENTENCE = '(no sentence)'
+const DATE_LENGTH = 10
+// `process.argv` holds the runtime and the script before the command's own arguments.
+const FIRST_ARGUMENT = 2
+
+interface StopsContext {
+	log_path?: string | undefined
+	now_ms?: number
+}
+
+// An unknown flag or a period that is not a positive whole number of days is refused, never defaulted.
+function period_of(argv: ReadonlyArray<string>): number | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	if (values === undefined) return undefined
+
+	return cli_flags.to_positive(values.period ?? String(DEFAULT_PERIOD_DAYS))
+}
+
+function compare(left: StopLine, right: StopLine): number {
+	const by_kind = left.kind.localeCompare(right.kind)
+
+	if (by_kind !== 0) return by_kind
+
+	return left.location.localeCompare(right.location) || left.at.localeCompare(right.at)
+}
+
+function line_of(stop: StopLine): string {
+	const sentence = stop.sentence === '' ? NO_SENTENCE : stop.sentence
+	const where = `${session_cite.issue(stop.issue)} ${stop.stage} ${stop.at.slice(0, DATE_LENGTH)}`
+
+	return `${stop.kind}  ${stop.location}  ${where} — ${sentence}`
+}
+
+function format_report(stops: ReadonlyArray<StopLine>, period_days: number): string {
+	const period = `the last ${String(period_days)} day(s)`
+
+	if (stops.length === 0) return `no review stop findings recorded in ${period}`
+
+	const body = stops.toSorted(compare).map((stop) => line_of(stop))
+
+	return [`review stop findings in ${period} (${String(stops.length)}):`, ...body].join('\n')
+}
+
+function run(argv: ReadonlyArray<string>, context: StopsContext = {}): number {
+	const period_days = period_of(argv)
+
+	if (period_days === undefined) {
+		console.error(USAGE)
+
+		return 1
+	}
+
+	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
+	const stops = lane_stats.in_window(review_stop_log.read(context.log_path), window)
+
+	console.info(format_report(stops, period_days))
+
+	return 0
+}
+
+function main(): void {
+	process.exitCode = run(process.argv.slice(FIRST_ARGUMENT))
+}
+
+const review_stops_cli = { format_report, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { review_stops_cli }

package/scripts/review/review-tree.ts

@@ -1,8 +1,6 @@
-import { readFileSync } from 'node:fs'
-import path from 'node:path'
+import { input_fingerprint } from '#scripts/gate/input-fingerprint'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
-import { stamp_file } from '#scripts/josh/stamp-file'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
 
 // The tree `josh review:brief` records: every path the change touches, and the digest of its content.
@@ -18,15 +16,7 @@ import { observation_ledger } from '#scripts/observations/observation-ledger'
 // A path the change lists but the working tree does not hold — deleted, or renamed away. Recorded
 // rather than dropped: a delete applied by a fix is part of the fix delta, and a dropped entry would
 // read as "unchanged" on the comparison.
-const ABSENT_DIGEST = 'absent'
-
-function digest_of(root: string, relative: string): string {
-	try {
-		return stamp_file.digest(readFileSync(path.join(root, relative)))
-	} catch {
-		return ABSENT_DIGEST
-	}
-}
+const ABSENT_DIGEST = input_fingerprint.ABSENT
 
 // Sorted so two readings of one tree produce the same record byte for byte, which is what lets a
 // stored stamp be compared against a fresh reading without a normalization step in between.
@@ -39,11 +29,10 @@ function digest_of(root: string, relative: string): string {
 // undo then moved the tree under both. Filtered here, every reader of the map
 // — the gate's record, both hooks, the brief and the round-2 fix delta — agrees on it.
 function tree_of(root: string, paths: ReadonlyArray<string>): Record<string, string> {
-	const sorted = paths
-		.filter((relative) => !observation_ledger.is_ledger_path(relative))
-		.toSorted((left, right) => left.localeCompare(right))
-
-	return Object.fromEntries(sorted.map((relative) => [relative, digest_of(root, relative)]))
+	return input_fingerprint.of_files(
+		root,
+		paths.filter((relative) => !observation_ledger.is_ledger_path(relative)),
+	)
 }
 
 // **The root is asked of git, never taken from `process.cwd()` — nor from `PROJECT_ROOT`, which is