@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/lane/lane-resolve-hunks.ts

@@ -0,0 +1,63 @@
+// The base lines one side of a merge rewrote, read off `git diff -U0 <base> <side>` hunks
+// (joshuafolkken/kit#5837). Step-back condition 2 of `backlogrun-recovery.md` — both sides rewrote the
+// same lines, overlapping rather than adjacent — is then a range intersection, with no reading of the
+// conflict's content. A pure insertion (`-a,0`) rewrites no base line, so it never overlaps; a hunk
+// both sides made alike is one git merges cleanly, so it never overlaps either.
+
+const HUNK_HEADER = /^@@ -(?<start>\d+)(?:,(?<count>\d+))? \+/u
+const HUNK_START = /^(?=@@ )/mu
+const DEFAULT_COUNT = '1'
+const LINE_BREAK = '\n'
+
+// Half-open: `[start, end)` in base line numbers; `change` is the hunk's removed and added lines.
+interface BaseRange {
+	start: number
+	end: number
+	change: string
+}
+
+function header_groups(header: string): Record<string, string | undefined> | undefined {
+	return HUNK_HEADER.exec(header)?.groups
+}
+
+function range_of(hunk: string): BaseRange | undefined {
+	const [header = '', ...lines] = hunk.trimEnd().split(LINE_BREAK)
+	const groups = header_groups(header)
+	if (groups?.['start'] === undefined) return undefined
+	const start = Number(groups['start'])
+	const end = start + Number(groups['count'] ?? DEFAULT_COUNT)
+
+	return { start, end, change: lines.join(LINE_BREAK) }
+}
+
+function is_rewrite(range: BaseRange | undefined): range is BaseRange {
+	return range !== undefined && range.end > range.start
+}
+
+function rewritten_ranges(diff: string): ReadonlyArray<BaseRange> {
+	return diff
+		.split(HUNK_START)
+		.map((hunk) => range_of(hunk))
+		.filter((range) => is_rewrite(range))
+}
+
+function is_same_change(left: BaseRange, right: BaseRange): boolean {
+	return left.start === right.start && left.end === right.end && left.change === right.change
+}
+
+function intersects(left: BaseRange, right: BaseRange): boolean {
+	if (is_same_change(left, right)) return false
+
+	return left.start < right.end && right.start < left.end
+}
+
+function overlaps(ours_diff: string, theirs_diff: string): boolean {
+	const theirs = rewritten_ranges(theirs_diff)
+
+	return rewritten_ranges(ours_diff).some((ours) => theirs.some((range) => intersects(ours, range)))
+}
+
+const lane_resolve_hunks = { rewritten_ranges, overlaps }
+
+export { lane_resolve_hunks }
+export type { BaseRange }

package/scripts/lane/lane-resolve-record.ts

@@ -0,0 +1,59 @@
+import { existsSync } from 'node:fs'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_command } from '#scripts/git/git-command'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { git_worktree } from '#scripts/git/git-worktree'
+import { lane_resolve } from './lane-resolve'
+
+// `josh lane:resolve <issue> --record [<path>...]` — step 4 of `backlogrun-recovery.md`'s
+// merge-conflict path as a command (joshuafolkken/kit#5922). The resolution comment is what step-back
+// condition 3 counts, so it is posted only once the concluded merge is on origin: a comment for a
+// resolution that never left this checkout would park the child's next conflict for nothing.
+
+type RecordOutcome = { kind: 'recorded'; url: string } | { kind: 'refused'; message: string }
+
+const ABSENT = 'absent'
+
+function body_of(paths: ReadonlyArray<string>): string {
+	const lines = paths.map((path) => `- \`${path}\``)
+
+	return [lane_resolve.RESOLUTION_HEADING, '', ...lines].join('\n').trimEnd()
+}
+
+// An unconcluded merge still sits on the pushed commit, so HEAD alone would read it as pushed.
+async function is_merging(): Promise<boolean> {
+	return existsSync(await git_spawn.read(['rev-parse', '--git-path', 'MERGE_HEAD']))
+}
+
+async function origin_commit(branch: string): Promise<string> {
+	const line = await git_worktree.ls_remote_branch(branch)
+	const [commit] = line.split('\t', 1)
+
+	return commit === undefined || commit === '' ? ABSENT : commit
+}
+
+async function unpushed(issue: string): Promise<string | undefined> {
+	if (await is_merging()) return 'the merge is not concluded — conclude and push it first'
+	const branch = `${issue}${lane_resolve.LANE_BRANCH_SUFFIX}`
+	const [head, origin] = await Promise.all([git_command.head_commit(), origin_commit(branch)])
+
+	if (head === origin) return undefined
+
+	return `${branch} is not pushed: HEAD ${head}, origin ${origin} — push it with \`pnpm josh git -y\` first`
+}
+
+async function record(issue: string, paths: ReadonlyArray<string>): Promise<RecordOutcome> {
+	const wrong = await lane_resolve.wrong_branch(issue)
+
+	if (wrong?.kind === 'refused') return wrong
+	const message = await unpushed(issue)
+
+	if (message !== undefined) return { kind: 'refused', message }
+
+	return { kind: 'recorded', url: await git_gh_command.issue_comment(issue, body_of(paths)) }
+}
+
+const lane_resolve_record = { record }
+
+export { lane_resolve_record }
+export type { RecordOutcome }

package/scripts/lane/lane-resolve.ts

@@ -0,0 +1,122 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_command } from '#scripts/git/git-command'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { main_merge } from '#scripts/git/main-merge'
+import { issue_read, type IssueComment } from '#scripts/issue/issue-read'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_resolve_hunks } from './lane-resolve-hunks'
+
+// `josh lane:resolve <issue>` — the merge-conflict path of `backlogrun-recovery.md` as one verdict
+// (joshuafolkken/kit#5837). The step-back conditions a command can read without judgement are judged
+// here: condition 3 off the Issue's resolution comments, before any merge starts, and condition 2 off
+// the hunk structure of each conflicted path. Conditions 1 and 4 stay the run's: one is a
+// specification question, the other the gate and the review that follow a resolution.
+
+const RESOLUTION_HEADING = '## Lane conflict resolved'
+const OVERLAP_CONDITION = 2
+const REPEAT_CONDITION = 3
+const HEAD = 'HEAD'
+const MERGE_HEAD = 'MERGE_HEAD'
+const LANE_BRANCH_SUFFIX = '-lane'
+
+type ResolveOutcome =
+	| { kind: 'resolved' }
+	| { kind: 'conflict'; files: ReadonlyArray<string> }
+	| { kind: 'step-back'; condition: number; files: ReadonlyArray<string> }
+	| { kind: 'refused'; message: string }
+
+// A resolution is counted only off a trusted author, so a person quoting the heading counts nothing.
+function is_resolution(comment: IssueComment): boolean {
+	return comment.is_trusted === true && comment.body.trimStart().startsWith(RESOLUTION_HEADING)
+}
+
+async function resolution_count(issue: string): Promise<number | undefined> {
+	const json = await git_gh_issue_read.issue_list_comments(issue)
+	const comments = await issue_read.parse_comments(json)
+
+	return comments?.filter((comment) => is_resolution(comment)).length
+}
+
+async function side_diff(base: string, side: string, file: string): Promise<string> {
+	return await git_spawn.read(['diff', '--unified=0', base, side, '--', file])
+}
+
+async function is_overlapping(base: string, file: string): Promise<boolean> {
+	const [ours, theirs] = await Promise.all([
+		side_diff(base, HEAD, file),
+		side_diff(base, MERGE_HEAD, file),
+	])
+
+	return lane_resolve_hunks.overlaps(ours, theirs)
+}
+
+async function overlapping_files(files: ReadonlyArray<string>): Promise<ReadonlyArray<string>> {
+	const base = await git_spawn.read(['merge-base', HEAD, MERGE_HEAD])
+	const verdicts = await Promise.all(files.map(async (file) => await is_overlapping(base, file)))
+
+	return files.filter((_file, index) => verdicts[index] === true)
+}
+
+// Condition 2 parks the child, and a park leaves the tree clean, so the merge is aborted here.
+async function judge_conflict(files: ReadonlyArray<string>): Promise<ResolveOutcome> {
+	const overlapping = await overlapping_files(files)
+
+	if (overlapping.length === 0) return { kind: 'conflict', files }
+
+	await git_spawn.read(['merge', '--abort'])
+
+	return { kind: 'step-back', condition: OVERLAP_CONDITION, files: overlapping }
+}
+
+async function judge_merge(): Promise<ResolveOutcome> {
+	const outcome = await main_merge.merge()
+
+	if (outcome.kind === 'conflict') return await judge_conflict(outcome.files)
+	if (outcome.kind === 'refused') return outcome
+
+	return { kind: 'resolved' }
+}
+
+// The issue names both the thread condition 3 reads and the branch the merge lands on, so a run in
+// another checkout is refused rather than judged against one issue and merged into another.
+async function wrong_branch(issue: string): Promise<ResolveOutcome | undefined> {
+	const branch = await git_command.branch()
+	const expected = `${issue}${LANE_BRANCH_SUFFIX}`
+
+	if (branch === expected) return undefined
+
+	return { kind: 'refused', message: `lane:resolve runs on ${expected}, not ${branch}` }
+}
+
+async function judge(issue: string): Promise<ResolveOutcome> {
+	const count = await resolution_count(issue)
+
+	if (count === undefined) {
+		return {
+			kind: 'refused',
+			message: `the comments of ${session_cite.issue(issue)} could not be read`,
+		}
+	}
+
+	if (count > 0) return { kind: 'step-back', condition: REPEAT_CONDITION, files: [] }
+
+	return await judge_merge()
+}
+
+async function resolve(issue: string): Promise<ResolveOutcome> {
+	return (await wrong_branch(issue)) ?? (await judge(issue))
+}
+
+// The one line the run branches on: `resolved`, `conflict <paths>` or `step-back <condition> [<paths>]`.
+function verdict_line(outcome: Exclude<ResolveOutcome, { kind: 'refused' }>): string {
+	if (outcome.kind === 'resolved') return outcome.kind
+	const words =
+		outcome.kind === 'conflict' ? [outcome.kind] : [outcome.kind, String(outcome.condition)]
+
+	return [...words, ...outcome.files].join(' ')
+}
+
+const lane_resolve = { RESOLUTION_HEADING, LANE_BRANCH_SUFFIX, resolve, verdict_line, wrong_branch }
+
+export { lane_resolve }
+export type { ResolveOutcome }

package/scripts/lane/lane-restart.ts

@@ -65,7 +65,7 @@ function end_carried_cut(lane: LaneInfo): void {
 async function record_restart(issue: string): Promise<void> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.RESTART,
-		`${issue_cite.plain(issue)} restarted in a fresh session by a person`,
+		`${issue_cite.plain_for('program', issue)} restarted in a fresh session by a person`,
 	)
 }
 

package/scripts/lane/lane-room.ts

@@ -0,0 +1,58 @@
+import { backlog_occupied } from '#scripts/backlog/backlog-occupied'
+import { lane_process_table, type TableRead } from './lane-process-table'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_snapshot_trace } from './lane-snapshot-trace'
+import { lane_spent } from './lane-spent'
+import { lane_state } from './lane-state'
+
+interface LaneUse {
+	occupied: number
+	seated: number
+	unknown: ReadonlyArray<string>
+}
+
+interface LaneRoom {
+	occupied: ReadonlyArray<LaneInfo>
+	idle: ReadonlyArray<string>
+	unknown: ReadonlyArray<string>
+	use: LaneUse
+}
+
+// One process snapshot supplies execution occupancy, idle lanes and merge waits for every caller.
+async function occupancy_of(
+	open: ReadonlyArray<LaneInfo>,
+	table: TableRead,
+): Promise<Omit<LaneRoom, 'use'>> {
+	const rows = await table()
+	const issues = open.map((lane) => lane.issue)
+	const trace = { process_trace: await lane_snapshot_trace.traces_of(issues, rows) }
+	const records = await lane_state.read_states(issues)
+	const is_merge_waiting = await lane_snapshot_trace.merge_waits_of(issues, rows)
+	const occupied = backlog_occupied.occupied_lanes(
+		open,
+		(live) => lane_spent.idle_lanes(live, trace),
+		records,
+		is_merge_waiting,
+	)
+	const unknown = backlog_occupied.unknown_lanes(open, records)
+
+	return { occupied, idle: lane_spent.idle_lanes(open, trace), unknown }
+}
+
+// Execution places and port ownership are independent; a saved tree alone occupies neither seat.
+async function read(
+	lanes?: ReadonlyArray<LaneInfo>,
+	table: TableRead = lane_process_table.read_table,
+): Promise<LaneRoom> {
+	const open = lanes ?? (await lane_registry.list_lanes())
+	const occupancy = await occupancy_of(open, table)
+	const seated = lane_registry.used_seats(open).length
+	const use = { occupied: occupancy.occupied.length, seated, unknown: occupancy.unknown }
+
+	return { ...occupancy, use }
+}
+
+const lane_room = { read }
+
+export { lane_room }
+export type { LaneRoom, LaneUse }

package/scripts/lane/lane-round-one-stats.ts

@@ -5,7 +5,7 @@ import { lane_stats, type StatsWindow } from './lane-stats'
 // verdict, with each reviewed verdict's share of the rounds the ship ran. The `clean` share is the rate
 // a ship-time round 1 passed with no fix — the number the "CI beside the review" break-even of
 // `docs/maintainers/lane-limit-measurement.md` is read against (joshuafolkken/kit#4620). A `reused`
-// round never ran, so it has a count and no share.
+// or skipped round never ran, so it has a count and no share.
 
 const COLUMNS = ['round 1', 'rounds', 'share'] as const
 const VERDICTS = ['clean', 'fixed', 'blocking'] as const
@@ -43,6 +43,7 @@ function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string
 		lane_stats.to_row(COLUMNS.map(() => '---')),
 		...rows,
 		lane_stats.to_row([REUSED, String(count_of(rounds, REUSED)), NO_SHARE]),
+		lane_stats.to_row(['skipped', String(count_of(rounds, 'skipped')), NO_SHARE]),
 	].join('\n')
 }
 

package/scripts/lane/lane-sampler.ts

@@ -1,3 +1,5 @@
+import { lane_ledger } from './lane-ledger'
+import type { LoadEntry } from './lane-ledger-schema'
 import { lane_ledger_write } from './lane-ledger-write'
 import { lane_load } from './lane-load'
 import type { LaneSpan } from './lane-net-time'
@@ -24,10 +26,45 @@ interface MeasureContext {
 	now_ms?: number
 }
 
-async function take(context: MeasureContext = {}): Promise<void> {
+async function take(context: MeasureContext = {}): Promise<LoadEntry> {
 	const at = new Date(context.now_ms ?? Date.now()).toISOString()
+	const entry = await lane_load.sample(at)
 
-	await lane_ledger_write.record(await lane_load.sample(at), context.ledger_path)
+	await lane_ledger_write.record(entry, context.ledger_path)
+
+	return entry
+}
+
+async function newest_load(ledger_path?: string): Promise<LoadEntry | undefined> {
+	const path = ledger_path ?? (await lane_ledger.target())
+
+	if (path === undefined) return undefined
+
+	return lane_ledger
+		.read_entries(path)
+		.findLast((entry): entry is LoadEntry => entry.kind === lane_ledger.KIND.LOAD)
+}
+
+// How far the host's sleep counter (`lane-load.ts`) grew from `previous` to `current`; an absent
+// counter, or a reboot between the two (the boot instant moved), reads as no growth.
+function counter_growth(previous: LoadEntry, current: LoadEntry): number {
+	if (previous.booted_ms !== current.booted_ms) return 0
+
+	return (current.slept_ms ?? 0) - (previous.slept_ms ?? Infinity)
+}
+
+// The sleep between `previous` and `current`, ending at the host's last wake (the sampler may start long
+// after it) and starting no earlier than `previous`; a counter grown by less than a tick reads as none.
+function sleep_since(previous: LoadEntry | undefined, current: LoadEntry): LaneSpan | undefined {
+	if (previous === undefined) return undefined
+
+	const slept_ms = counter_growth(previous, current)
+
+	if (slept_ms < SAMPLE_INTERVAL_MS) return undefined
+
+	const to_ms = Math.min(Date.parse(current.at), current.woke_ms ?? Infinity)
+
+	return { from_ms: Math.max(Date.parse(previous.at), to_ms - slept_ms), to_ms }
 }
 
 // A timer tick has no caller to raise into, and a sample that could not be read must never end the run
@@ -49,11 +86,24 @@ async function record_quietly(span: LaneSpan, context: MeasureContext): Promise<
 	}
 }
 
+// A sleep between two samplers (joshuafolkken/kit#7026): each drive starts its own, so a late tick never
+// shows a lid closed while no drive ran — the gap to the ledger's newest sample is read by the counter.
+async function take_first(context: MeasureContext): Promise<void> {
+	try {
+		const previous = await newest_load(context.ledger_path)
+		const slept = sleep_since(previous, await take(context))
+
+		if (slept !== undefined) await record_quietly(slept, context)
+	} catch {
+		// Best-effort, as `take_quietly`.
+	}
+}
+
 /** Sample now and then every minute, recording a tick the host slept through; the returned function stops it. */
 function start(context: MeasureContext = {}): () => void {
 	let last_ms = Date.now()
 
-	void take_quietly(context)
+	void take_first(context)
 	const timer = setInterval(() => {
 		const now_ms = Date.now()
 		const slept = lane_sleep.gap_of(last_ms, now_ms, SAMPLE_INTERVAL_MS)

package/scripts/lane/lane-seat-ownership.ts

@@ -0,0 +1,57 @@
+import { PROCESS_ALIVE } from '#scripts/run/run-liveness'
+import { lane_listening_ports } from './lane-listening-ports'
+import { lane_process_table } from './lane-process-table'
+import type { LaneInfo } from './lane-registry'
+import { lane_snapshot_trace } from './lane-snapshot-trace'
+
+interface SeatSnapshot {
+	running: ReadonlySet<string>
+	ports: ReadonlySet<number>
+}
+
+const UNREADABLE =
+	'Cannot read lane process ownership or listening ports (process or socket probe failed).'
+
+async function snapshot(issues: ReadonlyArray<string> = []): Promise<SeatSnapshot | undefined> {
+	const [ports, rows] = await Promise.all([
+		lane_listening_ports.read_ports(),
+		lane_process_table.read_table(),
+	])
+	if (ports === undefined || rows === undefined) return undefined
+	const trace = await lane_snapshot_trace.traces_of(issues, rows)
+
+	return { running: new Set(issues.filter((issue) => trace(issue) === PROCESS_ALIVE)), ports }
+}
+
+function ports_held(
+	lane: Pick<LaneInfo, 'development_port' | 'preview_port'>,
+	ports: ReadonlySet<number>,
+): boolean {
+	return [lane.development_port, lane.preview_port].some(
+		(port) => port !== undefined && ports.has(port),
+	)
+}
+
+function ownership(lane: LaneInfo, reading: SeatSnapshot | undefined): LaneInfo {
+	if (lane.is_stranded) return { ...lane, seat_held: false }
+	if (reading === undefined) return { ...lane, seat_held: true, seat_problem: UNREADABLE }
+	const is_running = reading.running.has(lane.issue)
+
+	return {
+		...lane,
+		seat_owned: is_running,
+		seat_held: is_running || ports_held(lane, reading.ports),
+	}
+}
+
+function measure(
+	lanes: ReadonlyArray<LaneInfo>,
+	reading: SeatSnapshot | undefined,
+): Array<LaneInfo> {
+	return lanes.map((lane) => ownership(lane, reading))
+}
+
+const lane_seat_ownership = { measure, ports_held, snapshot, UNREADABLE }
+
+export { lane_seat_ownership }
+export type { SeatSnapshot }

package/scripts/lane/lane-seat-start.ts

@@ -0,0 +1,52 @@
+import { LANE_SEAT_KEY, PORT_SEED_KEY } from '#ports'
+import { lane_environment } from './lane-environment'
+import { lane_paths } from './lane-paths'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_seat } from './lane-seat'
+
+function update(lane: LaneInfo, seat: number): LaneInfo {
+	const content = lane_registry.read_environment(lane.directory)
+	if (content === undefined) throw new Error(`Cannot read lane environment: ${lane.directory}`)
+	const updated = lane_environment.lane_file_content(content, seat)
+	const ports = lane_environment.read_lane_ports(updated)
+
+	lane_registry.write_environment(lane.directory, updated)
+
+	return {
+		...lane,
+		seat,
+		development_port: ports.development,
+		preview_port: ports.preview,
+		seat_held: true,
+	}
+}
+
+async function start<T>(lane: LaneInfo, launch: (seated: LaneInfo) => Promise<T>): Promise<T> {
+	const root = lane_paths.lane_root(await lane_registry.main_repository_root())
+	const reservation = await lane_seat.reserve(root, lane.issue)
+	if (reservation === undefined) throw new Error('No free port seat is available for this lane.')
+
+	try {
+		return await launch(update(lane, reservation.seat))
+	} finally {
+		lane_seat.release(reservation)
+	}
+}
+
+function environment(lane: LaneInfo): Record<string, string> {
+	if (lane.seat === undefined) {
+		throw new Error('Cannot launch a lane without an allocated port seat.')
+	}
+
+	const content = lane_registry.read_environment(lane.directory)
+	if (content === undefined) throw new Error(`Cannot read lane environment: ${lane.directory}`)
+
+	return {
+		[LANE_SEAT_KEY]: String(lane.seat),
+		[PORT_SEED_KEY]: String(lane_environment.read_root_seed(content)),
+	}
+}
+
+const lane_seat_start = { environment, start }
+
+export { lane_seat_start }

package/scripts/lane/lane-seat-stop.ts

@@ -0,0 +1,20 @@
+import { lane_reap } from './lane-reap'
+import { lane_reap_settle } from './lane-reap-settle'
+import { lane_registry } from './lane-registry'
+import { lane_residents } from './lane-residents'
+
+async function stop(issue: string): Promise<void> {
+	const lane = await lane_registry.lane_location(issue)
+	const reaped = lane_reap.reap_child(lane)
+
+	lane_residents.end_residents(lane, reaped)
+	const survivors = await lane_reap_settle.settle(lane)
+	if (survivors?.length === 0) return
+	const details = lane_reap_settle.survivor_texts(survivors).join(', ')
+
+	throw new Error(`Lane ${issue} port ownership has not settled: ${details}`)
+}
+
+const lane_seat_stop = { stop }
+
+export { lane_seat_stop }