@joshuafolkken/kit 1.2114.0 → 1.3000.0

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

@@ -134,16 +134,24 @@ function sides_of(relative: string, readings: Readings): Sides {
 	}
 }
 
+// A path's carry: `true` where it reproduces the file now, `false` where it differs, `undefined` where
+// git cannot make it — a conflict, or a side that does not hold the path.
+function carried_answer(relative: string, readings: Readings, root: string): boolean | undefined {
+	const carried = carried_blob(sides_of(relative, readings), root)
+
+	return carried === undefined ? undefined : carried === readings.now[relative]
+}
+
 function differing(
 	paths: ReadonlyArray<string>,
 	readings: Readings,
 	root: string,
 ): ReadonlyArray<string> | undefined {
-	const carried = paths.map((relative) => carried_blob(sides_of(relative, readings), root))
+	const answers = paths.map((relative) => carried_answer(relative, readings, root))
 
-	if (carried.includes(undefined)) return undefined
+	if (answers.includes(undefined)) return undefined
 
-	return paths.filter((relative, index) => carried[index] !== readings.now[relative])
+	return paths.filter((_relative, index) => answers[index] === false)
 }
 
 function read_readings(
@@ -172,15 +180,41 @@ function delta_of(input: Carry, root: string): ReadonlyArray<string> | undefined
 	return readings === undefined ? undefined : differing(paths, readings, root)
 }
 
+function carry_of({ blobs, from, to, paths }: CarryInput): Carry | undefined {
+	if (blobs === undefined || from === undefined || to === undefined) return undefined
+
+	return { blobs, from, to, paths }
+}
+
 function carried_delta(input: CarryInput): ReadonlyArray<string> | undefined {
-	const { blobs, from, to } = input
+	const carry = carry_of(input)
 	const root = repository_root()
 
-	if (root === undefined || blobs === undefined || from === undefined || to === undefined) {
-		return undefined
-	}
+	return carry === undefined || root === undefined ? undefined : delta_of(carry, root)
+}
+
+type CarryAnswers = Readonly<Record<string, boolean | undefined>>
+
+function answers_of(carry: Carry, root: string): CarryAnswers | undefined {
+	const { paths } = carry
+	const readings = paths.length === 0 ? undefined : read_readings(carry, paths, root)
+
+	if (paths.length === 0) return {}
+	if (readings === undefined) return undefined
+
+	return Object.fromEntries(
+		paths.map((relative) => [relative, carried_answer(relative, readings, root)]),
+	)
+}
+
+// **Each path's carry on its own** (joshuafolkken/kit#5791): a path git cannot carry answers
+// `undefined` for itself, never for the paths beside it, as `carried_delta` does over the whole record.
+// `undefined` overall only where there is nothing to carry from or git cannot read the sides.
+function carried_each(input: CarryInput): CarryAnswers | undefined {
+	const carry = carry_of(input)
+	const root = repository_root()
 
-	return delta_of({ blobs, from, to, paths: input.paths }, root)
+	return carry === undefined || root === undefined ? undefined : answers_of(carry, root)
 }
 
 function unmoved_between(
@@ -216,6 +250,6 @@ function capture(paths: ReadonlyArray<string>): Record<string, string> | undefin
 	return root === undefined ? undefined : hash_paths(root, paths, WRITE_FLAGS)
 }
 
-const review_round_one_blobs = { capture, carried_delta, unmoved }
+const review_round_one_blobs = { capture, carried_delta, carried_each, unmoved }
 
 export { review_round_one_blobs }

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

@@ -0,0 +1,72 @@
+import { git_branch } from '#scripts/git/git-branch'
+import { git_command } from '#scripts/git/git-command'
+import { issue_declared_size } from '#scripts/issue/issue-declared-size'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { split_measure } from '#scripts/split/split-measure'
+import { review_comment_round } from './review-comment-round'
+import { review_finding_ledger, type LineKind } from './review-finding-ledger'
+import { review_gate_mode } from './review-gate-mode'
+import { review_round } from './review-round'
+
+const NOTE = 'round1: skipped-in-size'
+const BLOCKING = new Set(['high', 'medium'])
+const KINDS: ReadonlyArray<LineKind> = ['code', 'interaction']
+
+async function is_in_size(issue: number): Promise<boolean> {
+	const declared = await issue_declared_size.read(String(issue))
+
+	if (declared === undefined || Math.min(declared.files, declared.lines) <= 0) return false
+	const actual = await split_measure.read_branch()
+
+	return actual.files <= declared.files && actual.lines <= declared.lines
+}
+
+async function is_eligible(issue: number): Promise<boolean> {
+	if (!(await is_in_size(issue))) return false
+	const content = await observation_ledger_home.read(undefined, true)
+
+	if (content === undefined) return false
+	const comments = await review_comment_round.issue_lines(issue)
+	const history = [content, ...comments].join('\n')
+
+	return KINDS.every((kind) =>
+		review_finding_ledger
+			.issue_dispositions(history, issue, kind)
+			.every((line) => !BLOCKING.has(line.severity)),
+	)
+}
+
+// Every uncertainty keeps round one; only a complete history and measurement can omit it.
+async function eligible_issue(): Promise<number | undefined> {
+	if (review_gate_mode.read() !== 'local') return undefined
+
+	try {
+		const issue = git_branch.issue_from_branch(await git_command.branch())
+
+		return issue !== undefined && (await is_eligible(issue)) ? issue : undefined
+	} catch {
+		return undefined
+	}
+}
+
+async function record(issue: number): Promise<void> {
+	await lane_ledger_write.record_round_one({ issue, verdict: 'skipped' })
+	process.stderr.write(`${NOTE}\n`)
+}
+
+async function run(
+	issue: number | undefined,
+	review: (round: number, is_full_change: boolean) => Promise<number>,
+): Promise<number> {
+	const is_skipped = issue !== undefined
+	const result = await review(is_skipped ? review_round.SECOND_ROUND : 1, is_skipped)
+
+	if (result === 0 && issue !== undefined) await record(issue)
+
+	return result
+}
+
+const review_round_one_skip = { eligible_issue, record, run, NOTE }
+
+export { review_round_one_skip }

package/scripts/review/review-round-reuse.ts

@@ -29,23 +29,29 @@ type Reuse = (typeof REUSE)[keyof typeof REUSE]
 const { MOVEMENT } = review_reviewed_tree
 
 // The reuse, and on `again` why (joshuafolkken/kit#4941): `review:record --check` prints it, so a lane
-// reads which condition re-runs round 1 rather than a list of every condition that could.
+// reads which condition re-runs round 1 rather than a list of every condition that could. On a reuse,
+// `note` names the moves no round reads that it passed over (joshuafolkken/kit#5662).
 interface ReuseAnswer {
 	reuse: Reuse
 	cause?: string | undefined
+	note?: string | undefined
 }
 
 const STALE_CAUSE = "the issue changed after the recorded round's brief"
 const UNRECORDED_CAUSE = 'no review round is recorded for this issue'
 
+function reused_with(kind: Reuse, note: string | undefined): ReuseAnswer {
+	return note === undefined ? { reuse: kind } : { reuse: kind, note }
+}
+
 async function recorded_answer(issue: number): Promise<ReuseAnswer> {
-	const { movement, cause } = await review_reviewed_tree.standing_here()
+	const { movement, cause, note } = await review_reviewed_tree.standing_here()
 
-	if (movement === MOVEMENT.HELD) return { reuse: REUSE.HELD }
+	if (movement === MOVEMENT.HELD) return reused_with(REUSE.HELD, note)
 
 	const is_delta = movement === MOVEMENT.DELTA || review_reviewed_tree.is_stopped_on(issue)
 
-	return is_delta ? { reuse: REUSE.DELTA } : { reuse: REUSE.AGAIN, cause }
+	return is_delta ? reused_with(REUSE.DELTA, note) : { reuse: REUSE.AGAIN, cause }
 }
 
 // **A recorded round 1 is reused while the tree it was recorded on holds still** — a lane's review
@@ -53,8 +59,9 @@ async function recorded_answer(issue: number): Promise<ReuseAnswer> {
 // (joshuafolkken/kit#4878): round 2 reads that delta from the round-1 brief's stamp after the commit, so
 // round 1 run again would read it twice. **The ship's own round 1 that stopped on a finding** is reused
 // however the lane's fix moved the tree, for the same reason. A High-cited file's fix is such a move
-// where round 2's delta holds it (joshuafolkken/kit#4941). Any other move — a doc, a revert — is
-// reviewed again, from that record (`review-reviewed-tree.ts`). An issue that changed after that
+// where round 2's delta holds it (joshuafolkken/kit#4941), and a doc, a prompt or an inert path no
+// round executes is passed over (joshuafolkken/kit#5662). Any other move — a revert — is reviewed
+// again, from that record (`review-reviewed-tree.ts`). An issue that changed after that
 // round's brief is never reused: the recorded round never read it, and `josh followup` refuses the merge on it
 // (joshuafolkken/kit#4221).
 async function answer(issue: number, is_stale: boolean): Promise<ReuseAnswer> {

package/scripts/review/review-round.ts

@@ -0,0 +1,57 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_attest } from './review-attest'
+
+type Round = '1' | '2'
+const FULL_CHANGE_FLAG = '--full-change'
+const FINAL_LINE = 'Review round: 2 — final, whole change, read only.'
+const SECOND_ROUND = 2
+const ROUND_ARGUMENT_COUNT = 2
+const ROUND_PREFIX = 'josh-review-round-'
+
+function numbered_round(argv: ReadonlyArray<string>): number | undefined {
+	if (argv.length !== ROUND_ARGUMENT_COUNT || argv[0] !== '--round') return undefined
+	const round = Number(argv[1])
+
+	return round === 1 || round === SECOND_ROUND ? round : undefined
+}
+
+function parse_round(argv: ReadonlyArray<string>): number | undefined {
+	if (argv.length === 0) return 1
+	if (argv.length === 1) return argv[0] === FULL_CHANGE_FLAG ? SECOND_ROUND : undefined
+
+	return numbered_round(argv)
+}
+
+function from_brief(brief: string, fallback: Round = '1'): Round {
+	return brief.split('\n').includes(FINAL_LINE) ? '2' : fallback
+}
+
+function record(round: number, root?: string): void {
+	const pointer = review_attest.read_pointer(root)
+
+	if (pointer === undefined) return
+	stamp_file.write_text_stamp(stamp_file.stamp_path(ROUND_PREFIX, pointer.nonce), String(round))
+}
+
+function current(root?: string): Round {
+	const pointer = review_attest.read_pointer(root)
+	const text =
+		pointer === undefined
+			? undefined
+			: stamp_file.read_stamp_text(stamp_file.stamp_path(ROUND_PREFIX, pointer.nonce))
+
+	return text === '2' ? '2' : '1'
+}
+
+const review_round = {
+	current,
+	from_brief,
+	record,
+	parse_round,
+	FINAL_LINE,
+	FULL_CHANGE_FLAG,
+	SECOND_ROUND,
+}
+
+export type { Round }
+export { review_round }

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

@@ -7,11 +7,13 @@ import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 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_level } from './review-level'
 import { review_reviewed_tree } from './review-reviewed-tree'
 import { review_round_one_blobs } from './review-round-one-blobs'
 import { review_round_one_closure } from './review-round-one-closure'
 import { review_round2, type RoundTwoAnswer } from './review-round2'
 import { review_round2_skip_comment } from './review-round2-skip-comment'
+import { review_size } from './review-size'
 import { review_stamps } from './review-stamps'
 import { review_tree } from './review-tree'
 
@@ -143,8 +145,11 @@ async function decide_here(options: Options): Promise<RoundTwoAnswer> {
 	// `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 paths = Object.keys(tree)
+	const lines = await review_size.read(paths)
 
 	return review_round2.decide({
+		level: review_level.level_for(paths, lines),
 		base,
 		carried_delta: carried_reader(base, tree),
 		comment_only: await read_comment_only(base),

package/scripts/review/review-round2-skip-comment.ts

@@ -27,7 +27,9 @@ function body_of(answer: RoundTwoAnswer): string {
 }
 
 function is_recorded(comment: IssueComment, body: string): boolean {
-	return comment.is_trusted === true && comment.body.trimStart().startsWith(body)
+	const recorded = comment.body.trimStart()
+
+	return comment.is_trusted === true && (recorded === body || recorded.startsWith(`${body}\n`))
 }
 
 async function read_comments(issue: number): Promise<ReadonlyArray<IssueComment> | undefined> {

package/scripts/review/review-round2.ts

@@ -3,7 +3,7 @@ import { path_decision } from '#scripts/josh/path-decision'
 import { json_value } from '#scripts/lib/json-value'
 import { release_approval_prune } from '#scripts/release/release-approval-prune'
 import { z } from 'zod'
-import { review_level } from './review-level'
+import { review_level, type ReviewLevel } from './review-level'
 
 // Whether the second review round runs at all.
 //
@@ -17,10 +17,8 @@ import { review_level } from './review-level'
 // `prompts/`, `josh metrics` approvals, and source files whose only change is in comments
 // (`review-code-tree.ts`).
 //
-// **Arm B is wider than the review level's inert set, on purpose** (joshuafolkken/kit#3787). Round 1
-// still reviews a documentation or prompt change in full, and the fix to its findings is still made;
-// what goes unread is only that fix. `.claude/**`, `CLAUDE.md`, tests and configuration stay outside:
-// a test fix can weaken the verification it belongs to, and nothing reads that but the review.
+// A low-level change gets one round once its findings close and its snapshot/base can be verified.
+// Medium changes retain the delta rules below, including tests and configuration outside arm B.
 
 type RoundTwoVerdict = 'required' | 'skip'
 
@@ -37,6 +35,7 @@ const CODE = {
 	NO_SNAPSHOT: 'no-snapshot',
 	BASE_MOVED: 'base-moved',
 	LIVE: 'live',
+	LOW: 'low',
 } as const
 
 type RoundTwoCode = (typeof CODE)[keyof typeof CODE]
@@ -68,6 +67,7 @@ const BASE_MOVED_REASON =
 	"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 {
+	level?: ReviewLevel
 	// **The commit the tree above is a diff against**. This decision reads the
 	// same digest comparison the brief's round-2 target does, so it inherits the same failure: taken
 	// against two different bases, the two maps do not cover the same set of paths, and an empty or
@@ -152,7 +152,16 @@ function verdict_for_delta(
 	delta: ReadonlyArray<string>,
 	taken_at: string,
 	comment_only: ReadonlyArray<string> = [],
+	level?: ReviewLevel,
 ): RoundTwoAnswer {
+	if (level === review_level.REDUCED_LEVEL) {
+		return {
+			verdict: SKIPPED_VERDICT,
+			code: CODE.LOW,
+			reason: `low review level has one round: ${delta.join(', ')}`,
+		}
+	}
+
 	if (delta.length === 0) {
 		return { verdict: SKIPPED_VERDICT, code: CODE.EMPTY, reason: empty_reason(taken_at) }
 	}
@@ -194,7 +203,10 @@ function decide(input: RoundTwoInput): RoundTwoDecision {
 
 	if (delta === undefined) return required(CODE.BASE_MOVED, BASE_MOVED_REASON)
 
-	return { ...verdict_for_delta(delta, input.snapshot.taken_at, input.comment_only), delta }
+	return {
+		...verdict_for_delta(delta, input.snapshot.taken_at, input.comment_only, input.level),
+		delta,
+	}
 }
 
 function to_json(answer: RoundTwoAnswer): string {

package/scripts/review/review-size.ts

@@ -0,0 +1,92 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { change_base } from '#scripts/git/change-base'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_command } from '#scripts/git/git-command'
+import { git_path_quoting } from '#scripts/git/git-path-quoting'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { split_assess } from '#scripts/split/split-assess'
+import { split_measure } from '#scripts/split/split-measure'
+
+function tracked_counts(raw: string): Map<string, number> {
+	const rows = raw.split('\n').filter((row) => row !== '')
+
+	if (rows.some((row) => !/^\d+\t\d+\t.+$/u.test(row))) throw new Error('Unknown diff size')
+
+	const changes = split_assess.parse_numstat(raw)
+
+	return new Map(
+		changes.map((change) => [git_path_quoting.unquote(change.path), change.changed_lines]),
+	)
+}
+
+async function tracked_numstat(is_staged: boolean): Promise<string> {
+	if (is_staged) {
+		return await git_spawn.read([
+			'-c',
+			'core.quotePath=false',
+			'diff',
+			'--cached',
+			'--numstat',
+			'--no-relative',
+			'--no-renames',
+			'--',
+		])
+	}
+
+	const base = await change_base.resolved_through_merge()
+
+	if (base === undefined) throw new Error('Unresolved change base')
+
+	return await git_command.diff_numstat_since(base)
+}
+
+async function untracked_count(root: string, file: string): Promise<number> {
+	const content = await readFile(path.join(root, file))
+
+	if (content.includes(0)) throw new Error('Binary diff size')
+
+	return split_measure.line_count(content)
+}
+
+async function counts_here(is_staged: boolean): Promise<Map<string, number>> {
+	const counts = tracked_counts(await tracked_numstat(is_staged))
+
+	if (is_staged) return counts
+	const files = changed_paths.to_paths(await git_command.untracked_names())
+	const root = await git_spawn.read(['rev-parse', '--show-toplevel'])
+	const additions = await Promise.all(
+		files.map(async (file) => {
+			const unquoted = git_path_quoting.unquote(file)
+
+			return [unquoted, await untracked_count(root, unquoted)] as const
+		}),
+	)
+
+	return new Map([...counts, ...additions])
+}
+
+function total_of(counts: Map<string, number>): number {
+	let total = 0
+
+	for (const lines of counts.values()) total += lines
+
+	return total
+}
+
+// Count the entire selected scope, including tests. Any failed measurement stays unknown.
+async function read(paths: ReadonlyArray<string>, is_staged = false): Promise<number | undefined> {
+	try {
+		const counts = await counts_here(is_staged)
+
+		if (paths.some((file) => !counts.has(git_path_quoting.unquote(file)))) return undefined
+
+		return total_of(counts)
+	} catch {
+		return undefined
+	}
+}
+
+const review_size = { read }
+
+export { review_size }

package/scripts/review/review-stamps.ts

@@ -11,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:related` ended red: the tree, and its failed files (`test-related-red.ts`). Never a green.
+const TEST_RELATED_RED_PREFIX = 'josh-test-related-red-'
 // `josh test:e2e` answered green — a run or a printed skip — on this tree (`test-e2e-stamp.ts`).
 const E2E_PREFIX = 'josh-e2e-stamp-'
 
@@ -53,6 +55,11 @@ const test_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	PROJECT_ROOT,
 	inputs_of([gate_labels.UNIT_LABEL]),
 )
+const test_related_red_stamp: FileMapStampAccess = file_map_stamp.create(
+	TEST_RELATED_RED_PREFIX,
+	PROJECT_ROOT,
+	inputs_of([gate_labels.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
@@ -92,6 +99,7 @@ const review_stamps = {
 	ROUND_ONE_PREFIX,
 	round_one_stamp,
 	reviewed_stamp,
+	test_related_red_stamp,
 	test_related_stamp,
 }
 

package/scripts/review/review-submit-args.ts

@@ -0,0 +1,91 @@
+import path from 'node:path'
+import { parseArgs } from 'node:util'
+import { review_attest, type ReviewSlot } from './review-attest'
+import { review_brief_cli } from './review-brief-cli'
+
+// The arguments of `josh review:submit`. `--review <file>` names the reviewer's markdown review, which
+// the submit lints in the same call as it checks the findings (joshuafolkken/kit#5627); `--round`
+// picks the rubric shape it is linted against, so it means nothing without `--review`.
+
+const ROUND_FLAG = '--round'
+const OPTIONS = {
+	interaction: { type: 'boolean' },
+	none: { type: 'boolean' },
+	review: { type: 'string' },
+	round: { type: 'string' },
+} as const
+
+interface SubmitValues {
+	interaction?: boolean
+	none?: boolean
+	review?: string
+	round?: string
+}
+
+interface ReviewToLint {
+	path: string
+	round: number
+}
+
+interface Submission {
+	slot: ReviewSlot
+	is_none: boolean
+	review: ReviewToLint | undefined
+}
+
+// `undefined` on an unknown flag, a positional, a missing value or a flag given twice.
+function values_of(argv: ReadonlyArray<string>): SubmitValues | undefined {
+	try {
+		const { values, tokens } = parseArgs({ args: [...argv], options: OPTIONS, tokens: true })
+		const names = tokens.filter((token) => token.kind === 'option').map((token) => token.name)
+
+		return new Set(names).size === names.length ? values : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// `undefined` on a round the rubric has no shape for.
+function round_of(raw_round: string | undefined): number | undefined {
+	return review_brief_cli.parse_round(raw_round === undefined ? [] : [ROUND_FLAG, raw_round])
+}
+
+// A `--round` without `--review` has nothing to lint, so it is refused rather than ignored.
+function is_valid_round(values: SubmitValues): boolean {
+	if (values.round === undefined) return true
+
+	return values.review !== undefined && round_of(values.round) !== undefined
+}
+
+// **A relative `--review` is refused**: `pnpm josh` runs from the package root, not the directory the
+// reviewer typed it in, so a relative path would read another file or none.
+function is_valid(values: SubmitValues): boolean {
+	const is_absolute_review = values.review === undefined || path.isAbsolute(values.review)
+
+	return is_absolute_review && is_valid_round(values)
+}
+
+function review_of(values: SubmitValues): ReviewToLint | undefined {
+	const round = round_of(values.round)
+	if (round === undefined || values.review === undefined) return undefined
+
+	return { path: values.review, round }
+}
+
+function submission_of(argv: ReadonlyArray<string>): Submission | undefined {
+	const values = values_of(argv)
+	if (values === undefined || !is_valid(values)) return undefined
+
+	const { CODE, INTERACTION } = review_attest.REVIEW_SLOT
+
+	return {
+		slot: values.interaction === true ? INTERACTION : CODE,
+		is_none: values.none === true,
+		review: review_of(values),
+	}
+}
+
+const review_submit_args = { submission_of }
+
+export { review_submit_args }
+export type { Submission }