@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lane/lane-test-related-stats.ts

@@ -0,0 +1,127 @@
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { lane_ledger, type LedgerEntry, type TestRelatedEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// What widened a `josh test:related` run (joshuafolkken/kit#4465): one row per scope it settled on —
+// `related`, `none` or the full-suite fallback kind — with the medians of its input (the change
+// itself, what a main sync brought in, what the change since the test-read map's tree joined, the
+// readers the map added), of the test files vitest
+// ran and of its duration. A `related` row whose test files far outrun its input is vitest widening the
+// run on its own.
+
+const DECIMALS = 1
+const RUNS_COLUMN = 'runs'
+const SECONDS_COLUMN = 'median (s)'
+const COLUMNS = [
+	'test:related scope',
+	RUNS_COLUMN,
+	'changed',
+	'synced',
+	'since map',
+	'readers',
+	'test files',
+	SECONDS_COLUMN,
+] as const
+const TRIGGER_COLUMNS = ['test:related whole-suite trigger', RUNS_COLUMN, SECONDS_COLUMN] as const
+
+type CountField = 'changed' | 'synced' | 'since_map' | 'readers'
+
+function is_test_related(entry: LedgerEntry): entry is TestRelatedEntry {
+	return entry.kind === lane_ledger.KIND.TEST_RELATED
+}
+
+function count_cell(values: ReadonlyArray<number>): string {
+	const median = lane_stats.median(values)
+
+	return median === undefined ? lane_stage_stats.NOT_MEASURED : String(median)
+}
+
+function seconds_cell(values: ReadonlyArray<number>): string {
+	const median = lane_stats.median(values)
+
+	return median === undefined
+		? lane_stage_stats.NOT_MEASURED
+		: (median / MS_PER_SECOND).toFixed(DECIMALS)
+}
+
+function median_of(runs: ReadonlyArray<TestRelatedEntry>, field: CountField): string {
+	return count_cell(runs.map((run) => run[field]))
+}
+
+function scope_row(scope: string, entries: ReadonlyArray<TestRelatedEntry>): string {
+	const runs = entries.filter((entry) => entry.scope === scope)
+	const test_files = runs.map((run) => run.test_files).filter((files) => files !== undefined)
+
+	return lane_stats.to_row([
+		scope,
+		String(runs.length),
+		median_of(runs, 'changed'),
+		median_of(runs, 'synced'),
+		median_of(runs, 'since_map'),
+		median_of(runs, 'readers'),
+		count_cell(test_files),
+		seconds_cell(runs.map((run) => run.elapsed_ms)),
+	])
+}
+
+function rows_under(columns: ReadonlyArray<string>, rows: ReadonlyArray<string>): string {
+	return [lane_stats.to_row(columns), lane_stats.to_row(columns.map(() => '---')), ...rows].join(
+		'\n',
+	)
+}
+
+function runs_in(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+): Array<TestRelatedEntry> {
+	return lane_stats.in_window(entries, window).filter(is_test_related)
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const runs = runs_in(entries, window)
+	const scopes = [...new Set(runs.map((run) => run.scope))]
+
+	return rows_under(
+		COLUMNS,
+		scopes.map((scope) => scope_row(scope, runs)),
+	)
+}
+
+interface TriggerRuns {
+	file: string
+	runs: ReadonlyArray<TestRelatedEntry>
+}
+
+function runs_sent_by(file: string, runs: ReadonlyArray<TestRelatedEntry>): TriggerRuns {
+	return { file, runs: runs.filter((run) => run.trigger_files?.includes(file) === true) }
+}
+
+function trigger_row({ file, runs }: TriggerRuns): string {
+	return lane_stats.to_row([
+		file,
+		String(runs.length),
+		seconds_cell(runs.map((run) => run.elapsed_ms)),
+	])
+}
+
+// Which changed file sent a run to the whole suite, most runs first (joshuafolkken/kit#4510): the
+// table `WHOLE_SUITE_FILES` and the test-read map are trimmed from. A row written before the files
+// were recorded names none, and so counts under no file.
+function trigger_table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const runs = runs_in(entries, window)
+	const files = [...new Set(runs.flatMap((run) => run.trigger_files ?? []))]
+	const triggers = files
+		.map((file) => runs_sent_by(file, runs))
+		.toSorted((left, right) => right.runs.length - left.runs.length)
+
+	return rows_under(
+		TRIGGER_COLUMNS,
+		triggers.map((trigger) => trigger_row(trigger)),
+	)
+}
+
+const lane_test_related_stats = { table, trigger_table }
+
+export { lane_test_related_stats }

package/scripts/lane/lane-transcript-calls.ts

@@ -0,0 +1,145 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// One lane session's transcript reduced to its tool calls: each `tool_use` an `assistant` line carries,
+// joined by its id to the `tool_result` a later `user` line carries, so `josh lane:stats` can time a
+// call as the gap between the two lines (joshuafolkken/kit#4418).
+//
+// **A backgrounded call is kept but not timed.** Its result line is the immediate "running in the
+// background" notice, so the gap measures nothing the run waited on; `duration_ms` is `undefined` for
+// it, as for a call whose result never arrived (an interrupted turn).
+
+interface ToolCall {
+	session_id: string
+	started_ms: number
+	duration_ms: number | undefined
+	background: boolean
+	command: string | undefined
+	output: string
+}
+
+interface ToolUse {
+	started_ms: number
+	background: boolean
+	command: string | undefined
+}
+
+interface ToolResult {
+	ended_ms: number
+	output: string
+}
+
+interface TextPart {
+	text?: string | null | undefined
+}
+
+function join_parts(parts: ReadonlyArray<TextPart>): string {
+	return parts.map((part) => part.text ?? '').join('\n')
+}
+
+interface RawInput {
+	command?: unknown
+	run_in_background?: unknown
+}
+
+interface CallInput {
+	background: boolean
+	command: string | undefined
+}
+
+function to_input(input: RawInput | null | undefined): CallInput {
+	const command = input?.command
+
+	return {
+		background: input?.run_in_background === true,
+		command: typeof command === 'string' ? command : undefined,
+	}
+}
+
+const TEXT_PARTS_SCHEMA = z.array(z.object({ text: z.string().nullish() }))
+// A result's text: a string, or the text parts of a block list; anything else reads as no output.
+const RESULT_CONTENT_SCHEMA = z
+	.union([z.string(), TEXT_PARTS_SCHEMA.transform(join_parts)])
+	.catch('')
+const INPUT_SCHEMA = z.object({ command: z.unknown(), run_in_background: z.unknown() }).partial()
+
+const BLOCK_SCHEMA = z.object({
+	type: z.string(),
+	id: z.string().nullish(),
+	input: INPUT_SCHEMA.nullish().transform(to_input),
+	tool_use_id: z.string().nullish(),
+	content: RESULT_CONTENT_SCHEMA.optional(),
+})
+
+type Block = z.infer<typeof BLOCK_SCHEMA>
+
+function blocks_of(message: { content: Array<Block> } | null | undefined): Array<Block> {
+	return message?.content ?? []
+}
+
+// A line that is not JSON, not a message, or carries no readable timestamp fails the parse.
+const LINE_SCHEMA = z.object({
+	timestamp: z.string().transform(Date.parse).pipe(z.number()),
+	message: z
+		.object({ content: z.array(BLOCK_SCHEMA).catch([]) })
+		.nullish()
+		.transform(blocks_of),
+})
+
+interface Pairs {
+	uses: Map<string, ToolUse>
+	results: Map<string, ToolResult>
+}
+
+function record_use(pairs: Pairs, block: Block, started_ms: number): void {
+	if (block.type !== 'tool_use' || !block.id) return
+
+	pairs.uses.set(block.id, { started_ms, ...block.input })
+}
+
+function record_result(pairs: Pairs, block: Block, ended_ms: number): void {
+	if (block.type !== 'tool_result' || !block.tool_use_id) return
+
+	pairs.results.set(block.tool_use_id, { ended_ms, output: block.content ?? '' })
+}
+
+function record_line(pairs: Pairs, line: string): void {
+	const parsed = LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
+
+	if (!parsed.success) return
+
+	const { timestamp, message } = parsed.data
+
+	for (const block of message) {
+		record_use(pairs, block, timestamp)
+		record_result(pairs, block, timestamp)
+	}
+}
+
+function to_call(session_id: string, use: ToolUse, result: ToolResult | undefined): ToolCall {
+	const is_timed = result !== undefined && !use.background
+
+	return {
+		session_id,
+		started_ms: use.started_ms,
+		duration_ms: is_timed ? result.ended_ms - use.started_ms : undefined,
+		background: use.background,
+		command: use.command,
+		output: result?.output ?? '',
+	}
+}
+
+// Every tool call `raw` — one transcript's text — records, in the order the calls were made.
+function parse(session_id: string, raw: string): Array<ToolCall> {
+	const pairs: Pairs = { uses: new Map(), results: new Map() }
+	const lines = raw.split('\n')
+
+	for (const line of lines) record_line(pairs, line)
+
+	return [...pairs.uses].map(([id, use]) => to_call(session_id, use, pairs.results.get(id)))
+}
+
+const lane_transcript_calls = { parse }
+
+export type { ToolCall }
+export { lane_transcript_calls }

package/scripts/lane/lane-transcript-stats.ts

@@ -0,0 +1,168 @@
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_transcript_calls, type ToolCall } from './lane-transcript-calls'
+
+// The lane speed metrics only the lane sessions' transcripts hold, printed by `josh lane:stats` under the
+// ledger's tables so a speed check needs no ad-hoc aggregation (joshuafolkken/kit#4418): tool time per
+// session, the verification calls and the share that waited for the core budget, and the medians of
+// `lint:related` / `test:related`.
+//
+// **A chained call is counted apart from a solo one.** One Bash call that runs two verification
+// commands (`josh lint:related && josh test:related`) has one duration for both, so it would read as
+// either command's time; the per-command medians take solo calls only. **Only a foreground call is
+// timed** — `lane_transcript_calls` leaves a backgrounded one's duration out.
+//
+// **The period is cut at each call's own timestamp**, not a transcript's modification time, so a
+// fractional `--period` (since a merge) counts the same calls whichever session they sit in.
+
+const TIMED_COMMANDS: ReadonlyArray<string> = ['lint:related', 'test:related']
+// **The verification calls split by what ran them** (joshuafolkken/kit#4442): the scoped checks of the
+// implementation loop, a whole `gate` or `metrics` run by hand before the ship, and the `ship` call —
+// whose own gate runs inside it and is the ledger's to count — so a hand-run gate is never hidden in the
+// loop's volume. A call naming two classes counts in each.
+const CALL_CLASSES: ReadonlyArray<readonly [string, ReadonlySet<string>]> = [
+	['verification calls, scoped checks', new Set([...TIMED_COMMANDS, 'cspell:dot'])],
+	['verification calls, gate / metrics by hand', new Set(['gate', 'metrics'])],
+	['verification calls, ship', new Set(['ship'])],
+]
+const VERIFICATION_COMMANDS: ReadonlySet<string> = new Set(
+	CALL_CLASSES.flatMap(([, names]) => [...names]),
+)
+// A command is `josh <name>` at the start of a shell command — after a separator and the shell
+// keywords, then past what `time_shell` skips (env assignments, wrappers with their flags and operands,
+// a `pnpm` / `npx` runner) — so `josh lint:related; josh test:related`, `out=$(pnpm josh gate)` and
+// `CI=1 timeout 600 pnpm josh gate` name their commands. A heredoc body or a quoted string only
+// mentions a command, so `time_shell.unquoted` cuts both, keeping a `"$(…)"` that runs
+// (joshuafolkken/kit#4525).
+const SEPARATOR_PATTERN = /[;&|()\n]/u
+const WORD_PATTERN = /\s+/u
+const KEYWORDS: ReadonlySet<string> = new Set([
+	'if',
+	'elif',
+	'else',
+	'then',
+	'while',
+	'until',
+	'do',
+	'!',
+	'{',
+])
+// `scripts/gate/core-wait.ts` writes this into every wait line it prints.
+const CORE_WAIT_PHRASE = 'waits for the core budget'
+const PERCENT = 100
+const COLUMNS = ['transcript metric', 'value'] as const
+const { NOT_MEASURED } = lane_stage_stats
+
+// The josh command `segment` runs, or `''` when it runs none.
+function segment_command(segment: string): string {
+	const words = segment.trim().split(WORD_PATTERN)
+	const start = words.findIndex((word) => !KEYWORDS.has(word))
+	const named = time_shell.josh_command_of_segment(words.slice(start).join(' '))
+
+	return named.slice(time_shell.JOSH_PREFIX.length)
+}
+
+function verification_commands(command = ''): Array<string> {
+	const spoken = time_shell.unquoted(command)
+	const named = spoken.split(SEPARATOR_PATTERN).map((segment) => segment_command(segment))
+
+	return named.filter((name) => VERIFICATION_COMMANDS.has(name))
+}
+
+function seconds_cell(ms: number | undefined): string {
+	return ms === undefined ? NOT_MEASURED : (ms / MS_PER_SECOND).toFixed(1)
+}
+
+function is_timed(ms: number | undefined): ms is number {
+	return ms !== undefined
+}
+
+function durations(calls: ReadonlyArray<ToolCall>): Array<number> {
+	return calls.map((call) => call.duration_ms).filter((ms) => is_timed(ms))
+}
+
+// Each session's summed foreground tool time, for the sessions that made a call in the period.
+function session_times(calls: ReadonlyArray<ToolCall>): Array<number> {
+	const sessions = [...new Set(calls.map((call) => call.session_id))]
+
+	return sessions.map((session) =>
+		durations(calls.filter((call) => call.session_id === session)).reduce(
+			(sum, value) => sum + value,
+			0,
+		),
+	)
+}
+
+function share_cell(part: number, whole: number): string {
+	if (whole === 0) return NOT_MEASURED
+
+	return `${String(part)} of ${String(whole)} (${((part / whole) * PERCENT).toFixed(1)}%)`
+}
+
+function solo_median_row(verifying: ReadonlyArray<ToolCall>, name: string): Array<string> {
+	const solo = verifying.filter((call) => {
+		const named = verification_commands(call.command)
+
+		return named.length === 1 && named[0] === name
+	})
+
+	return [`${name} median, solo (s)`, seconds_cell(lane_stats.median(durations(solo)))]
+}
+
+function class_rows(verifying: ReadonlyArray<ToolCall>): Array<Array<string>> {
+	return CALL_CLASSES.map(([metric, names]) => {
+		const named = verifying.filter((call) =>
+			verification_commands(call.command).some((name) => names.has(name)),
+		)
+
+		return [metric, String(named.length)]
+	})
+}
+
+function rows_of(calls: ReadonlyArray<ToolCall>): Array<Array<string>> {
+	const times = session_times(calls)
+	const verifying = calls.filter((call) => verification_commands(call.command).length > 0)
+	const chained = verifying.filter((call) => verification_commands(call.command).length > 1)
+	const waited = verifying.filter((call) => call.output.includes(CORE_WAIT_PHRASE))
+
+	return [
+		['lane sessions', String(times.length)],
+		['tool time per session, median (min)', lane_stage_stats.cell(lane_stats.median(times))],
+		['tool time per session, mean (min)', lane_stage_stats.cell(lane_stats.mean(times))],
+		['verification calls, solo', String(verifying.length - chained.length)],
+		['verification calls, chained', String(chained.length)],
+		...class_rows(verifying),
+		['waited for the core budget', share_cell(waited.length, verifying.length)],
+		...TIMED_COMMANDS.map((name) => solo_median_row(verifying, name)),
+	]
+}
+
+// The period's table: `calls` is every lane session's calls, filtered here to `window`.
+function table(calls: ReadonlyArray<ToolCall>, window: StatsWindow): string {
+	const period = calls.filter(
+		(call) => call.started_ms >= window.since_ms && call.started_ms <= window.until_ms,
+	)
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...rows_of(period).map((row) => lane_stats.to_row(row)),
+	].join('\n')
+}
+
+// The tool calls of every lane session under `directories` that was still written to in `window` — a
+// transcript last modified before the period holds no call in it, so it is never read. A delegated
+// unit's transcript is not a lane session, and its time is already inside the parent's wait for it.
+function read_calls(directories: ReadonlyArray<string>, window: StatsWindow): Array<ToolCall> {
+	return cost_transcript
+		.list_sessions_across(directories)
+		.filter((file) => !file.is_delegated && file.modified_ms >= window.since_ms)
+		.flatMap((file) => lane_transcript_calls.parse(file.session_id, cost_transcript.read_raw(file)))
+}
+
+const lane_transcript_stats = { read_calls, table, verification_commands }
+
+export { lane_transcript_stats }

package/scripts/lane/lane-vacant.ts

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { run_hold } from '#scripts/run/hold/run-hold'
+import { PROCESS_NONE } from '#scripts/run/run-liveness'
 import { lane_await } from './lane-await'
 import type { LaneInfo } from './lane-registry'
 
@@ -9,7 +10,7 @@ import type { LaneInfo } from './lane-registry'
 // refuses it as `already-open` — so the next launch of that issue failed on a lane with nothing in it.
 //
 // **Every unreadable answer is "not vacant"**: `is_tree_dirty` already reads an unreadable status as
-// dirty, and a branch whose commits cannot be counted is kept rather than closed, because closing it
+// dirty, a process probe that could not look reads as occupied, and a branch whose commits cannot be counted is kept rather than closed, because closing it
 // deletes the branch and anything on it.
 async function has_no_commits(lane: LaneInfo): Promise<boolean> {
 	try {
@@ -21,8 +22,10 @@ async function has_no_commits(lane: LaneInfo): Promise<boolean> {
 	}
 }
 
+// Only pgrep's own "no match" clears a lane: a probe that failed or timed out never looked, and a
+// freshly launched child with no commit yet must not read vacant on it (joshuafolkken/kit#4028).
 function is_occupied(lane: LaneInfo): boolean {
-	return lane.is_stranded || lane_await.is_process_running_default(lane.issue)
+	return lane.is_stranded || lane_await.process_trace_default(lane.issue) !== PROCESS_NONE
 }
 
 async function is_vacant(lane: LaneInfo): Promise<boolean> {
@@ -31,6 +34,13 @@ async function is_vacant(lane: LaneInfo): Promise<boolean> {
 	return await has_no_commits(lane)
 }
 
-const lane_vacant = { is_vacant }
+// The issues of the lanes that hold nothing worth keeping, read in parallel.
+async function vacant_issues(lanes: ReadonlyArray<LaneInfo>): Promise<Array<string>> {
+	const answers = await Promise.all(lanes.map(async (lane) => await is_vacant(lane)))
+
+	return lanes.filter((_lane, index) => answers[index] === true).map((lane) => lane.issue)
+}
+
+const lane_vacant = { is_vacant, vacant_issues }
 
 export { lane_vacant }

package/scripts/lane/lane-withdraw-cli.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { lane_withdraw, type WithdrawOutcome } from './lane-withdraw'
+
+// `josh lane:withdraw <issue> --reason <text>` — every explanation on standard error, and anything but a
+// finished withdrawal exits non-zero, so a caller never takes a half-done one as done. The Issue stays
+// open on success.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh lane:withdraw <issue-number> --reason <text>'
+const OPTIONS = { reason: { type: 'string' } } as const
+
+interface Request {
+	issue: string
+	reason: string
+}
+
+function issue_of(positionals: ReadonlyArray<string>): string | undefined {
+	const [issue, ...rest] = positionals
+
+	return rest.length === 0 && issue_number_shape.is_issue_number(issue ?? '') ? issue : undefined
+}
+
+// A reason of only whitespace is no reason: the Issue would carry an empty `Why:` line.
+function reason_of(value: unknown): string | undefined {
+	const reason = cli_flags.string_of(value)?.trim()
+
+	return reason === '' ? undefined : reason
+}
+
+function parse_request(argv: ReadonlyArray<string>): Request | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return undefined
+	const issue = issue_of(parsed.positionals)
+	const reason = reason_of(parsed.values.reason)
+
+	return issue === undefined || reason === undefined ? undefined : { issue, reason }
+}
+
+function exit_code_of(outcome: WithdrawOutcome): number {
+	return outcome.kind === 'withdrawn' ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const outcome = await lane_withdraw.withdraw(request.issue, request.reason)
+
+	console.error(lane_withdraw.describe(outcome, request.issue))
+
+	return exit_code_of(outcome)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_withdraw_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_withdraw_cli }