@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/run/ship/run-ship-overlap.ts

@@ -0,0 +1,232 @@
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_diff_reads } from '#scripts/git/git-diff-reads'
+import { git_merge_conflicts } from '#scripts/git/git-merge-conflicts'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { main_merge_regenerate } from '#scripts/git/main-merge-regenerate'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_handoff } from '#scripts/lane/lane-handoff'
+import { lane_ledger, type OverlapRecord } from '#scripts/lane/lane-ledger'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { poll } from '#scripts/lib/poll'
+
+// The wait in front of `josh ship`'s sync (joshuafolkken/kit#3901). `backlog-overlap.ts` keeps lanes
+// apart only on the paths their issue bodies declare, so two lanes that both edit an undeclared file
+// were found out only when the later pull request turned `DIRTY` — after its gate and its CI wait,
+// often as a `conflict` stop its child no longer had the context for.
+//
+// **The later ship waits for the earlier one rather than anything being pushed into a lane.** A lane
+// whose actual change conflicts with this one's and whose pull request is already open (its branch pushed,
+// its detached ship still running) is waited on until that ship ends, merged or stopped; the sync that
+// follows then merges a default branch that already holds it, so a conflict surfaces before this
+// lane's gate rather than after its CI. Merging into the other lane's tree instead could not work: a
+// lane mid-gate would have its record moved under it, and a lane still implementing holds the
+// overlapping paths uncommitted, which `main:merge`'s guard refuses.
+//
+// **Only a ship launched before this one is waited on**, so two ships never wait on each other — a
+// re-ship after a stop already has a pushed branch, so "pushed" alone could not order two re-ships in
+// their sync. A ship run in an agent's own turn has no launch record and counts as the latest; equal
+// launch times fall to the lower issue number. The wait is bounded — a ship that hangs never holds
+// another past `MAX_WAIT_ATTEMPTS`, after which the sync goes ahead as it always did.
+
+const WAIT_INTERVAL_MS = 30_000
+const MAX_WAIT_ATTEMPTS = 60
+// Unquoted like `read_changed_paths`, so a non-ASCII path compares equal on both sides.
+const NAME_ONLY_ARGUMENTS = [
+	'-c',
+	'core.quotePath=false',
+	'diff',
+	'--name-only',
+	'--no-relative',
+	'--no-renames',
+]
+const REGENERATED_PATHS: ReadonlySet<string> = new Set(
+	main_merge_regenerate.REGENERATED_FILES.map((entry) => entry.path),
+)
+
+interface OverlapOptions {
+	sleeper?: (duration_ms: number) => Promise<void>
+	ledger?: string
+}
+
+interface Overlap {
+	lanes: ReadonlyArray<LaneInfo>
+	paths: ReadonlyArray<string>
+}
+
+function to_paths(raw: string): Array<string> {
+	return changed_paths.to_paths(raw)
+}
+
+async function has_upstream(directory: string): Promise<boolean> {
+	try {
+		await git_spawn.read(['-C', directory, 'rev-parse', '--verify', '--quiet', '@{upstream}'])
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// A lane's change as its pushed branch carries it: everything its commits changed since it left the
+// default branch. Read in its own tree, so the other lane's uncommitted edits — not yet on its pull
+// request — are not counted.
+async function lane_paths(directory: string): Promise<ReadonlyArray<string>> {
+	const base = await git_diff_reads.default_branch_reference()
+
+	try {
+		return to_paths(
+			await git_spawn.read(['-C', directory, ...NAME_ONLY_ARGUMENTS, `${base}...HEAD`, '--']),
+		)
+	} catch {
+		return []
+	}
+}
+
+interface Launch {
+	issue: string
+	since: number
+}
+
+function own_launch(issue: string): Launch {
+	const since = lane_handoff.ship_running_since(issue, process.cwd())
+
+	return { issue, since: since ?? Infinity }
+}
+
+function is_launched_before(lane: LaneInfo, own: Launch): boolean {
+	const since = lane_handoff.ship_running_since(lane.issue, lane.directory)
+
+	if (since === undefined) return false
+
+	return since < own.since || (since === own.since && Number(lane.issue) < Number(own.issue))
+}
+
+async function is_open_ship(lane: LaneInfo, own: Launch): Promise<boolean> {
+	if (!is_launched_before(lane, own)) return false
+
+	return await has_upstream(lane.directory)
+}
+
+async function lane_head(directory: string): Promise<string | undefined> {
+	try {
+		return await git_spawn.read(['-C', directory, 'rev-parse', 'HEAD'])
+	} catch {
+		return undefined
+	}
+}
+
+// Of the paths both lanes change, the ones merging the other lane's head into this lane's working
+// tree would actually stop on (joshuafolkken/kit#4348) — the working tree, since this lane's change is
+// not committed until after the sync: an identical addition merges cleanly, so only a real conflict
+// is waited on. Only a shared path is tried: a lane forked from an older default branch also
+// conflicts on files the default branch changed since, which this lane's sync takes from the default
+// branch, not from that lane. A file `main:merge` regenerates is resolved by the sync either way, so
+// it never counts. A merge that could not be tried falls back to every shared path, as the wait was
+// decided before.
+async function conflicting_paths(
+	lane: LaneInfo,
+	shared: ReadonlyArray<string>,
+): Promise<Array<string>> {
+	const theirs = await lane_head(lane.directory)
+	const conflicted =
+		theirs === undefined
+			? undefined
+			: git_merge_conflicts.working_tree_conflicts(theirs, shared, process.cwd())
+
+	return (conflicted ?? shared).filter((file_path) => !REGENERATED_PATHS.has(file_path))
+}
+
+async function shared_paths(
+	lane: LaneInfo,
+	launch: Launch,
+	own: ReadonlySet<string>,
+): Promise<Array<string>> {
+	if (!(await is_open_ship(lane, launch))) return []
+
+	const paths = await lane_paths(lane.directory)
+	const shared = paths.filter((file_path) => own.has(file_path))
+
+	if (shared.length === 0) return []
+
+	return await conflicting_paths(lane, shared)
+}
+
+async function other_lanes(issue: string): Promise<ReadonlyArray<LaneInfo>> {
+	const lanes = await lane_registry.list_lanes()
+
+	return lanes.filter((lane) => lane.issue !== issue && !lane.is_stranded)
+}
+
+// Every other lane whose open pull request, shipped before this one, conflicts with this lane's change,
+// with the conflicting paths.
+async function find_overlap(issue: string): Promise<Overlap> {
+	const own = new Set(await changed_paths.read_changed_paths(false))
+	const launch = own_launch(issue)
+	const others = await other_lanes(issue)
+	const shared = await Promise.all(
+		others.map(async (lane) => await shared_paths(lane, launch, own)),
+	)
+
+	return {
+		lanes: others.filter((_lane, index) => (shared[index] ?? []).length > 0),
+		paths: [...new Set(shared.flat())].toSorted((left, right) => left.localeCompare(right)),
+	}
+}
+
+async function read_overlap(issue: string): Promise<Overlap> {
+	try {
+		return await find_overlap(issue)
+	} catch {
+		return { lanes: [], paths: [] }
+	}
+}
+
+function is_settled(lanes: ReadonlyArray<LaneInfo>): boolean {
+	return lanes.every((lane) => !lane_handoff.is_ship_running(lane.issue, lane.directory))
+}
+
+async function wait_for(lanes: ReadonlyArray<LaneInfo>, options: OverlapOptions): Promise<boolean> {
+	return await poll.poll_until(async () => is_settled(lanes), {
+		attempts: MAX_WAIT_ATTEMPTS,
+		interval_ms: WAIT_INTERVAL_MS,
+		sleeper: options.sleeper ?? poll.sleep,
+	})
+}
+
+// Waits out every overlapping open ship and records the decision, returning what was recorded; a lane
+// that overlaps nothing returns `undefined` at once and writes nothing. Best-effort: an overlap that
+// could not be read is no overlap, so the sync is never blocked by the check that only exists to make
+// it land cleaner.
+async function await_overlap(
+	issue: string,
+	options: OverlapOptions = {},
+): Promise<OverlapRecord | undefined> {
+	const overlap = await read_overlap(issue)
+
+	if (overlap.lanes.length === 0) return undefined
+
+	const started = Date.now()
+	const is_cleared = await wait_for(overlap.lanes, options)
+	const lanes = overlap.lanes.map((lane) => Number(lane.issue))
+	const waited_ms = Date.now() - started
+	const record = { issue: Number(issue), lanes, paths: [...overlap.paths], waited_ms, is_cleared }
+
+	await lane_ledger.record_overlap(record, options.ledger)
+
+	return record
+}
+
+// The line the sync stage prints for a recorded wait, or `''` where nothing overlapped.
+function note(record: OverlapRecord | undefined): string {
+	if (record === undefined) return ''
+
+	const lanes = record.lanes.map((lane) => session_cite.issue(lane)).join(', ')
+	const outcome = record.is_cleared ? 'waited for' : 'gave up waiting for'
+
+	return `${outcome} ${lanes}, whose open pull requests conflict on: ${record.paths.join(', ')}`
+}
+
+const run_ship_overlap = { MAX_WAIT_ATTEMPTS, await_overlap, note }
+
+export type { OverlapOptions }
+export { run_ship_overlap }

package/scripts/run/ship/run-ship-place.ts

@@ -0,0 +1,96 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+import { backlog_ready } from '#scripts/backlog/backlog-ready'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { lane_handoff } from '#scripts/lane/lane-handoff'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { run_ship_stage, type Stage } from './run-ship-stage'
+
+// **A followup stop past the lane limit waits for a place, then relaunches**: its lane held no place
+// while it waited (`backlog-occupied.ts`), so the next launch may have taken it, and a child started at
+// once would run past the limit (joshuafolkken/kit#4466). The stopped lane counts again while this
+// supervisor waits, so the driver launches nothing into the place it waits for. An unreadable limit or
+// lane count relaunches at once, and so does a place that does not free within the wait.
+//
+// **Waiters queue in issue order rather than block each other**: every waiter counts in the lane use,
+// so three of them past a limit of two would each see the lanes full and wait out the hour together. A
+// waiter leaves out the waiters behind it, so the first ones that fit relaunch and the rest wait on them.
+// The mark is the ship stage record's (`run_ship_stage.mark_place_waiting`), read only while the ship
+// runs, so a dead supervisor's mark queues nobody.
+
+// An hour of lane counts, half a minute apart: about two lanes' median run (`lane:stats`).
+const PLACE_POLL_MS = 30_000
+const PLACE_POLLS = 120
+
+function is_behind(lane: LaneInfo, issue: string): boolean {
+	return lane.issue.localeCompare(issue, undefined, { numeric: true }) > 0
+}
+
+async function waiters_behind(issue: string): Promise<number> {
+	const lanes = await lane_registry.list_lanes()
+
+	return lanes.filter(
+		(lane) => is_behind(lane, issue) && lane_handoff.is_place_waiting(lane.issue, lane.directory),
+	).length
+}
+
+async function is_over_limit(issue: string): Promise<boolean> {
+	const limit = await lane_capacity.lane_limit()
+
+	if (limit.kind !== 'limit') return false
+
+	const use = await backlog_ready.lane_use()
+	const behind = await waiters_behind(issue)
+
+	return use.occupied - behind > lane_capacity.seated_limit(limit.limit)
+}
+
+async function is_place_taken(issue: string): Promise<boolean> {
+	try {
+		return await is_over_limit(issue)
+	} catch {
+		return false
+	}
+}
+
+// Best-effort: a mark that could not be written leaves this waiter counted by the others, as before.
+function mark(lane: LaneInfo, is_waiting: boolean): void {
+	const repository = git_common_directory.repository(lane.directory)
+
+	if (repository === undefined) return
+
+	try {
+		run_ship_stage.mark_place_waiting(
+			run_ship_stage.record_path(repository, lane.issue),
+			is_waiting,
+		)
+	} catch {
+		// The queue only orders waiters; an unmarked one still waits on the lane count.
+	}
+}
+
+async function poll(issue: string): Promise<void> {
+	for (let polled = 0; polled < PLACE_POLLS; polled += 1) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each check waits on a lane the previous one saw busy
+		if (!(await is_place_taken(issue))) return
+
+		// eslint-disable-next-line no-await-in-loop -- polling: the wait between two lane counts
+		await sleep(PLACE_POLL_MS)
+	}
+}
+
+async function await_place(lane: LaneInfo, stage: Stage): Promise<void> {
+	if (stage !== run_ship_stage.STAGE.FOLLOWUP) return
+
+	mark(lane, true)
+
+	try {
+		await poll(lane.issue)
+	} finally {
+		mark(lane, false)
+	}
+}
+
+const run_ship_place = { await_place }
+
+export { run_ship_place }

package/scripts/run/ship/run-ship-pre-detach-timed.ts

@@ -0,0 +1,43 @@
+import type { JoshResult } from '#scripts/josh/josh-run'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_ship_pre_detach } from './run-ship-pre-detach'
+import { run_ship_stage, type Phase } from './run-ship-stage'
+
+// The pre-detach checks, timed into the lane ledger and marked on the event stream as a ship stage
+// is, so their minutes are no longer folded into the lane's implementation time
+// (joshuafolkken/kit#4382). They are not a `Stage`: nothing resumes past them, and `run:board` draws no
+// phase from a word it does not know.
+
+const SUCCESS_EXIT_CODE = 0
+const { PHASE } = run_ship_stage
+
+async function emit_phase(issue: string, phase: Phase): Promise<void> {
+	const text = run_ship_stage.event_text(issue, lane_ledger.PRE_DETACH_STAGE, phase)
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STAGE, text)
+}
+
+async function checks(
+	issue: string,
+	run: () => Promise<JoshResult> = run_ship_pre_detach.checks,
+): Promise<JoshResult> {
+	await emit_phase(issue, PHASE.START)
+	const started_ms = performance.now()
+	const result = await run()
+	const elapsed_ms = performance.now() - started_ms
+
+	await lane_ledger.record_stage({
+		stage: lane_ledger.PRE_DETACH_STAGE,
+		elapsed_ms,
+		issue: Number(issue),
+	})
+	await emit_phase(issue, result.code === SUCCESS_EXIT_CODE ? PHASE.DONE : PHASE.FAILED)
+
+	return result
+}
+
+const run_ship_pre_detach_timed = { checks }
+
+export { run_ship_pre_detach_timed }

package/scripts/run/ship/run-ship-pre-detach.ts

@@ -1,72 +1,126 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { check_reuse, type CheckRecords } from '#scripts/gate/check-reuse'
+import { gate_plan } from '#scripts/gate/gate-plan'
+import type { GateStepResult } from '#scripts/gate/gate-report'
+import { gate_tree } from '#scripts/gate/gate-tree'
 import { project_checks } from '#scripts/gate/project-checks'
 import { type_check_step } from '#scripts/gate/type-check-step'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 
-// The fast checks a detached `josh ship` runs in the agent's own turn, after the preflight and before
-// the hand-off: a type error in a file the related-only checks never touched, or a document test (a
-// SKILL.md pointer, a byte budget, the command list) that only the full suite runs, would otherwise
-// first surface after the detach and cost a relaunched session. These two answer in seconds, so the
-// same session fixes what they find and ships again. **Nothing moves out of the gate**: the
-// supervised gate stage still runs every check, these included.
+// The fast checks a detached `josh ship` runs in the agent's own turn, after the preflight (whatever it
+// answered) and before the hand-off:a type error in a file the related-only checks never touched, an export nothing reads,
+// an unknown word, or a guard test (a SKILL.md pointer, a byte budget, the command list, a source with
+// no colocated test, a bare issue citation) that only the full suite runs, would otherwise first
+// surface after the detach and cost a relaunched session. They answer in seconds, so the same session
+// fixes what they find and ships again.
 //
-// The test targets are the directories such failures land in. A consumer has none of them, so only
-// the ones present run, and a consumer meets the type check alone.
+// **Nothing moves out of the gate, and the gate reuses what these already answered**: a check that is
+// the gate's own check passed silently here is recorded with the gate's per-check record
+// (`check-reuse.ts`), so the supervised gate stage reuses it while its declared inputs have not moved
+// and runs it again when they have. The record, its judgment and its inputs are the gate's; only the
+// type check (`check`) and `exports:unused` (`exports`) carry a gate label. The rest stay unrecorded:
+// `cspell:dot` declares no inputs and runs every gate (`verification-inputs.ts`), the guard tests are a
+// slice of the unit suite and do not answer for the gate's `test:unit`, and the metrics totals leave
+// out the durations the gate's `metrics` holds.
+//
+// joshuafolkken/kit#3924: nine of ten ship gate stops were `exports:unused`, `cspell:dot` or a
+// repository-wide guard test failing on the child's own code — none a check `test:related` selects,
+// since a guard test imports no changed file.
+//
+// The test targets are where such failures land. A consumer has none of them, so only the ones
+// present run, and a consumer meets the static checks alone.
 //
 // In kit the metrics ratchet's totals join them: a feature grows a total almost every time, and here
 // the session that grew the total writes the reason itself rather than a relaunched one. The
 // durations are left out: they read the gate ledger, stale before the detach, so they stay with the
 // supervised gate.
 
+interface PreDetachCheck {
+	list: ReadonlyArray<string>
+	// The gate check this one answers for, absent where it answers for none.
+	label?: string | undefined
+}
+
+interface PreDetachRun {
+	check: PreDetachCheck
+	result: BufferedProcessResult
+	elapsed_ms: number
+}
+
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const SECTION_SEPARATOR = '\n\n'
 const PASSED = 'pre-detach checks passed'
 const METRICS_TOTALS_COMMAND: ReadonlyArray<string> = ['josh', 'metrics', '--totals-only']
-const DOCUMENT_TEST_TARGETS: ReadonlyArray<string> = [
+const STATIC_CHECKS: ReadonlyArray<PreDetachCheck> = [
+	{ list: ['josh', 'exports:unused'], label: gate_plan.EXPORTS_LABEL },
+	{ list: ['josh', 'cspell:dot'] },
+]
+const GUARD_TEST_TARGETS: ReadonlyArray<string> = [
 	'scripts/document',
 	'scripts/claude',
 	'scripts/rules',
 	'scripts/josh/josh-command-map.test.ts',
+	'scripts/issue/session-cite-scan.test.ts',
+	'tools/test/untested-sources.test.ts',
+	'tools/test/pure-files.test.ts',
 ]
 // A present directory need not hold a test the project's Vitest includes — a consumer's own
 // `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
-const DOCUMENT_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+const GUARD_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
 
 function present_targets(directory: string): ReadonlyArray<string> {
-	return DOCUMENT_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
+	return GUARD_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
 }
 
-function document_tests(directory: string): Array<ReadonlyArray<string>> {
+function guard_tests(directory: string): Array<PreDetachCheck> {
 	const targets = present_targets(directory)
 
-	return targets.length === 0 ? [] : [[...DOCUMENT_TEST_COMMAND, ...targets]]
+	return targets.length === 0 ? [] : [{ list: [...GUARD_TEST_COMMAND, ...targets] }]
 }
 
 // The same kit-only rule as the gate's `is_kit_only` step: a consumer's kit has no `josh metrics`.
-function kit_only(directory: string): Array<ReadonlyArray<string>> {
-	return project_checks.is_kit_repository(directory) ? [METRICS_TOTALS_COMMAND] : []
+function kit_only(directory: string): Array<PreDetachCheck> {
+	return project_checks.is_kit_repository(directory) ? [{ list: METRICS_TOTALS_COMMAND }] : []
 }
 
-async function command_lists(directory: string): Promise<Array<ReadonlyArray<string>>> {
+async function command_lists(directory: string): Promise<Array<PreDetachCheck>> {
 	const type_check = await type_check_step.resolve_type_check_args(directory)
 
-	return [type_check, ...document_tests(directory), ...kit_only(directory)]
+	return [
+		{ list: type_check, label: gate_plan.TYPE_CHECK_LABEL },
+		...STATIC_CHECKS,
+		...guard_tests(directory),
+		...kit_only(directory),
+	]
+}
+
+async function run_in(directory: string, check: PreDetachCheck): Promise<PreDetachRun> {
+	const started = performance.now()
+	const result = await buffered_process.run_buffered_process(check.list, { cwd: directory })
+
+	return { check, result, elapsed_ms: performance.now() - started }
 }
 
-async function run_in(
-	directory: string,
-	list: ReadonlyArray<string>,
-): Promise<BufferedProcessResult> {
-	return await buffered_process.run_buffered_process(list, { cwd: directory })
+interface GateRun extends PreDetachRun {
+	check: { list: ReadonlyArray<string>; label: string }
 }
 
-// Both run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
-async function checks(directory: string = process.cwd()): Promise<JoshResult> {
-	const lists = await command_lists(directory)
-	const results = await Promise.all(lists.map(async (list) => await run_in(directory, list)))
+function is_gate_run(run: PreDetachRun): run is GateRun {
+	return run.check.label !== undefined
+}
+
+function gate_results(runs: ReadonlyArray<PreDetachRun>): Array<GateStepResult> {
+	return runs
+		.filter((run) => is_gate_run(run))
+		.map(({ check, result, elapsed_ms }) => {
+			return { ...result, label: check.label, command: check.list.join(' '), elapsed_ms }
+		})
+}
+
+function verdict(results: ReadonlyArray<BufferedProcessResult>): JoshResult {
 	const failed = results.filter((result) => buffered_process.is_process_failed(result))
 
 	if (failed.length === 0) return { code: SUCCESS_EXIT_CODE, out: PASSED }
@@ -77,6 +131,27 @@ async function checks(directory: string = process.cwd()): Promise<JoshResult> {
 	}
 }
 
-const run_ship_pre_detach = { DOCUMENT_TEST_TARGETS, METRICS_TOTALS_COMMAND, PASSED, checks }
+// All run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
+// The tree is read before they start, so a record is written only for the tree they read.
+async function checks(
+	directory: string = process.cwd(),
+	records: CheckRecords = check_reuse.DEFAULT_RECORDS,
+): Promise<JoshResult> {
+	const [lists, tree] = await Promise.all([command_lists(directory), gate_tree.read_gate_tree()])
+	const runs = await Promise.all(lists.map(async (check) => await run_in(directory, check)))
+
+	await check_reuse.record_green_checks(gate_results(runs), tree, records)
+
+	return verdict(runs.map(({ result }) => result))
+}
+
+const run_ship_pre_detach = {
+	GUARD_TEST_TARGETS,
+	METRICS_TOTALS_COMMAND,
+	PASSED,
+	STATIC_CHECKS,
+	checks,
+}
 
+export type { PreDetachCheck }
 export { run_ship_pre_detach }