@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -0,0 +1,129 @@
+import { lane_ledger, type HeldEntry, type LedgerEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// How long a free lane stayed empty, and why: the ledger's `held` entries of one period reduced to one
+// row per reason, printed by `josh lane:stats` so the idle capacity a backlog stall episode reported
+// is split by cause — an offer that started nothing apart from a driver waiting on its session
+// (joshuafolkken/kit#3995).
+//
+// **A hold lasts until the next `held`, `released` or `dispatch` entry**: the driver writes one on every
+// offered pass that started nothing, so consecutive entries tile the wait and the last one ends at the
+// dispatch — or at the release a full pool or a finished run writes.
+// A hold nothing followed is counted under `not ended`, kept out of the minutes, whose time has no end;
+// one past `MAX_HOLD_MS` is a driver nobody restarted, read as ended at the cap.
+
+const COLUMNS = [
+	'held by',
+	'total (min)',
+	'median (min)',
+	'max (min)',
+	'holds',
+	'not ended',
+] as const
+const MS_PER_HOUR = 3_600_000
+const MAX_HOLD_MS = MS_PER_HOUR
+const { NOT_MEASURED } = lane_stage_stats
+// A period with no hold: the table still prints, so a reader sees zero holds rather than no table.
+const NONE_ROW = ['none', NOT_MEASURED, NOT_MEASURED, NOT_MEASURED, '0', '0']
+const { is_dispatch, is_number } = lane_stage_stats
+
+interface Hold {
+	reason: string
+	wait_ms: number | undefined
+}
+
+function is_held(entry: LedgerEntry): entry is HeldEntry {
+	return entry.kind === lane_ledger.KIND.HELD
+}
+
+function is_hold_end(entry: LedgerEntry): boolean {
+	return is_held(entry) || is_dispatch(entry) || entry.kind === lane_ledger.KIND.RELEASED
+}
+
+// Every instant a hold can end at, parsed and sorted once: holds come once a minute, so re-reading the
+// whole ledger per hold made a week's `lane:stats` take seconds.
+function end_times(entries: ReadonlyArray<LedgerEntry>): Array<number> {
+	return entries
+		.filter((entry) => is_hold_end(entry))
+		.map((entry) => Date.parse(entry.at))
+		.filter((at) => Number.isFinite(at))
+		.toSorted((left, right) => left - right)
+}
+
+function wait_ms(held: HeldEntry, ends: ReadonlyArray<number>): number | undefined {
+	const from_ms = Date.parse(held.at)
+	const end_ms = ends.find((at) => at > from_ms)
+
+	return end_ms === undefined ? undefined : Math.min(end_ms - from_ms, MAX_HOLD_MS)
+}
+
+function holds_of(entries: ReadonlyArray<LedgerEntry>): Array<Hold> {
+	const ends = end_times(entries)
+
+	return entries
+		.filter(is_held)
+		.map((held) => ({ reason: held.reason, wait_ms: wait_ms(held, ends) }))
+}
+
+function total(values: ReadonlyArray<number>): number {
+	return values.reduce((sum, value) => sum + value, 0)
+}
+
+function ended_of(holds: ReadonlyArray<Hold>, reason: string): Array<number> {
+	return holds
+		.filter((hold) => hold.reason === reason)
+		.map((hold) => hold.wait_ms)
+		.filter((value) => is_number(value))
+}
+
+function reason_row(reason: string, holds: ReadonlyArray<Hold>): string {
+	const ended = ended_of(holds, reason)
+	const count = holds.filter((hold) => hold.reason === reason).length
+
+	return lane_stats.to_row([
+		reason,
+		lane_stage_stats.cell(ended.length === 0 ? undefined : total(ended)),
+		lane_stage_stats.cell(lane_stats.median(ended)),
+		lane_stage_stats.cell(lane_stats.peak(ended)),
+		String(count),
+		String(count - ended.length),
+	])
+}
+
+// The reasons the period saw, the longest total first, so the cause worth removing next leads.
+function reasons_of(holds: ReadonlyArray<Hold>): Array<string> {
+	const reasons = [...new Set(holds.map((hold) => hold.reason))]
+
+	return reasons.toSorted(
+		(left, right) => total(ended_of(holds, right)) - total(ended_of(holds, left)),
+	)
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const holds = holds_of(lane_stats.in_window(entries, window))
+	const rows = reasons_of(holds).map((reason) => reason_row(reason, holds))
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...(rows.length === 0 ? [lane_stats.to_row(NONE_ROW)] : rows),
+	].join('\n')
+}
+
+function is_open_at(held: HeldEntry, now_ms: number): boolean {
+	return now_ms - Date.parse(held.at) < MAX_HOLD_MS
+}
+
+// The reason of the hold still open at the ledger's end, or `undefined` where the last one has ended —
+// or is past `MAX_HOLD_MS`, a driver killed while held that wrote no hand-back.
+function open_reason(entries: ReadonlyArray<LedgerEntry>, now_ms: number): string | undefined {
+	const last = entries.findLast((entry) => is_hold_end(entry))
+
+	return last !== undefined && is_held(last) && is_open_at(last, now_ms) ? last.reason : undefined
+}
+
+const lane_held_stats = { open_reason, table }
+
+export { lane_held_stats }

package/scripts/lane/lane-install.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
-import path from 'node:path'
+import { core_budget } from '#scripts/gate/core-budget'
 import { buffered_process } from '#scripts/lib/buffered-process'
+import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 
 // Filling the lane, which is the other half of opening one.
@@ -25,16 +26,9 @@ import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 // exactly the lock committed there. A lock the install would rather rewrite is a finding, not
 // something to absorb silently into six parallel lanes.
 const INSTALL_ARGUMENTS = ['install', '--frozen-lockfile']
-// The manifest whose absence is the whole skip condition. A lane cut from a repository that has no
-// `package.json` has nothing to install, so running `pnpm install` there could only fail on a
-// manifest that was never there — which is exactly the fixture a cross-process lane test needs.
-// The condition is strictly "the file does not exist": a manifest that is
-// present but unreadable or broken still runs the install and still fails as before, so a genuinely
-// broken repository is never passed silently.
-const MANIFEST_FILE_NAME = 'package.json'
 // The lane opens with no dependencies installed, and that is the reported state rather than a
 // failure — there was nothing to install, so nothing failed.
-const NO_MANIFEST_OUTPUT = `No ${MANIFEST_FILE_NAME} in the lane, so the dependency install was skipped.`
+const NO_MANIFEST_OUTPUT = `No ${PACKAGE_JSON} in the lane, so the dependency install was skipped.`
 
 interface InstallResult {
 	is_installed: boolean
@@ -50,7 +44,7 @@ interface InstallResult {
 // `existsSync` answers only whether the path is there, never whether its contents parse, so a
 // present-but-broken manifest falls through to the real install and fails there.
 function has_manifest(directory: string): boolean {
-	return existsSync(path.join(directory, MANIFEST_FILE_NAME))
+	return existsSync(package_manifest.manifest_path(directory))
 }
 
 /**
@@ -68,10 +62,17 @@ function has_manifest(directory: string): boolean {
 async function install_dependencies(directory: string): Promise<InstallResult> {
 	if (!has_manifest(directory)) return { is_installed: true, output: NO_MANIFEST_OUTPUT }
 
-	const result = await buffered_process.run_buffered_process(INSTALL_ARGUMENTS, {
-		cwd: directory,
-		timeout_ms: INSTALL_TIMEOUT_MS,
-	})
+	// The install claims its place in the core budget (joshuafolkken/kit#3944): a batch opens its lanes
+	// together, and each install ran beside the other lanes' gates off the ledger.
+	const result = await core_budget.with_command_reservation(
+		core_budget.CORE_WEIGHTS.install,
+		async () =>
+			await buffered_process.run_buffered_process(INSTALL_ARGUMENTS, {
+				cwd: directory,
+				timeout_ms: INSTALL_TIMEOUT_MS,
+			}),
+		{ memory_mb: core_budget.MEMORY_MB.install, command: 'lane install' },
+	)
 
 	return { is_installed: !buffered_process.is_process_failed(result), output: result.output }
 }
@@ -79,4 +80,4 @@ async function install_dependencies(directory: string): Promise<InstallResult> {
 const lane_install = { install_dependencies }
 
 export type { InstallResult }
-export { lane_install, INSTALL_ARGUMENTS, MANIFEST_FILE_NAME, NO_MANIFEST_OUTPUT }
+export { lane_install, INSTALL_ARGUMENTS, NO_MANIFEST_OUTPUT }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
@@ -21,7 +19,6 @@ import { execa } from 'execa'
 // warning. Their explanations stream through to stderr; the child's pid is the one thing on stdout.
 // A lane a park kept is the one `already-open` it steps past — `lane_directory` below.
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const should_forward_stderr = true
@@ -171,13 +168,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await launch(context)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const lane_launch_cli = { launch_lane, read_context, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { LaunchContext, LaunchOutcome }
 export { lane_launch_cli }

package/scripts/lane/lane-launch-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { lane_launch_cli } from './lane-launch-cli'
+
+// The `josh lane:launch` entry, kept apart from `lane-launch-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await lane_launch_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/lane/lane-ledger-schema.ts

@@ -0,0 +1,266 @@
+import { z } from 'zod'
+
+// The shape of each line `lane-ledger.ts` appends and reads back — one schema per entry kind.
+
+const KIND = {
+	MERGE: 'merge',
+	GATE: 'gate',
+	LOAD: 'load',
+	DISPATCH: 'dispatch',
+	STAGE: 'stage',
+	STOP: 'stop',
+	OVERLAP: 'overlap',
+	HELD: 'held',
+	RELEASED: 'released',
+	ROUND_TWO: 'round-two',
+	OFFERABLE: 'offerable',
+	CORE_WAIT: 'core-wait',
+	UNIT_FILES: 'unit-files',
+	TEST_RELATED: 'test-related',
+} as const
+
+const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
+const check_schema = z.object({
+	label: z.string(),
+	elapsed_ms: z.number(),
+	is_passed: z.boolean(),
+	is_reused: z.boolean().optional(),
+	// The CPU milliseconds the check's process tree spent, so a core weight can be re-measured from
+	// the ledger (joshuafolkken/kit#4362). Absent where the gate could not read it (off macOS).
+	cpu_ms: z.number().optional(),
+	// Why the unit leg ran the whole suite instead of the related tests — a stable kind, never the
+	// file it names (joshuafolkken/kit#4397). Absent when it narrowed, and on every other check.
+	fallback: z.string().optional(),
+	// The unit leg's since-green no-op: nothing moved, so it ran no test (joshuafolkken/kit#4457).
+	is_unmoved: z.boolean().optional(),
+	// The width the check asked the core budget for, the width it ran at and how long it waited, so a
+	// unit claim's wait for room is read per run (joshuafolkken/kit#4451). Absent on a check that
+	// claimed none — a reused one, or one inside another gate's claim.
+	claim: z.object({ requested: z.number(), granted: z.number(), waited_ms: z.number() }).optional(),
+})
+const gate_schema = z.object({
+	kind: z.literal(KIND.GATE),
+	at: z.string(),
+	elapsed_ms: z.number(),
+	is_passed: z.boolean(),
+	// The unit suite's own duration, present when this gate ran it — the one
+	// record of a full vitest run `josh metrics` reads, so the suite is never timed twice.
+	unit_ms: z.number().optional(),
+	// The whole cores busy outside this gate, beyond the machine's baseline, at its start or its end —
+	// whichever was higher. Absent when the machine could not be read.
+	external_cores: z.number().optional(),
+	// Each check's own duration and verdict, so `josh lane:stats` can name the check a slow gate waited
+	// on. A reused check started no process: its row says so, and its zero is no timing.
+	checks: z.array(check_schema).optional(),
+	// A gate that reused a green record for this tree and base and started no check: counted, never
+	// timed (joshuafolkken/kit#4397).
+	is_reused: z.boolean().optional(),
+})
+// `available_mb`, `swapped_mb` and `lanes` are optional because each read can fail on its own — a
+// platform with no memory reading, a `git worktree` call that did not answer — and a sample is still
+// worth its load. `swapped_mb` is `machine_capacity`'s counter, every page swapped since boot.
+// Both memory fields were renamed with their meaning (joshuafolkken/kit#3593): an older row's
+// `free_mb` / `swap_mb` are stripped on read, so the two measurements never share a column.
+const process_kind_schema = z.object({
+	kind: z.string(),
+	cpu_percent: z.number(),
+	rss_mb: z.number(),
+	count: z.number(),
+})
+const load_schema = z.object({
+	kind: z.literal(KIND.LOAD),
+	at: z.string(),
+	load: z.number(),
+	available_mb: z.number().optional(),
+	swapped_mb: z.number().optional(),
+	lanes: z.number().optional(),
+	// The heaviest process kinds at the instant of the sample (`lane-process-load.ts`), so the load the
+	// core budget's ledger does not explain can be read back by what made it (joshuafolkken/kit#3874).
+	processes: z.array(process_kind_schema).optional(),
+})
+// A lane child started on `issue` — the instant its implementation is timed from.
+const dispatch_schema = z.object({
+	kind: z.literal(KIND.DISPATCH),
+	at: z.string(),
+	issue: z.number(),
+})
+// One finished stage of a lane's run, passed or failed: `at` is its end and `elapsed_ms` its length, so
+// its start is read from the two. `issue` is absent where the writer does not hold one — `followup`'s
+// CI wait, which is timed on a path that fails before the issue is known.
+const stage_schema = z.object({
+	kind: z.literal(KIND.STAGE),
+	at: z.string(),
+	stage: z.string(),
+	elapsed_ms: z.number(),
+	issue: z.number().optional(),
+})
+// A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the
+// retrospective's stop reason — and `cause` why (`run-ship-stop-cause.ts`), absent on a stop recorded
+// before it had one. `preconditions` names the kinds a preflight stop found unmet (`run-ship-preflight.ts`),
+// with `pre-detach` where a lane child's fast checks went red beside them (joshuafolkken/kit#4478),
+// absent on any other stop and on one recorded before it had them. `findings` names the
+// `<category>:<severity>` of each finding that decided a review or round-2 stop — the blocking ones, else
+// the fixed ones (joshuafolkken/kit#4426),
+// absent where none decided the stop. How long it stayed stopped is derived from the next ship stage, not recorded, so a
+// resumed ship never has to know the stop it ends.
+const stop_schema = z.object({
+	kind: z.literal(KIND.STOP),
+	at: z.string(),
+	issue: z.number(),
+	reason: z.string(),
+	cause: z.string().optional(),
+	preconditions: z.array(z.string()).optional(),
+	findings: z.array(z.string()).optional(),
+})
+// A `josh ship` on `issue` whose actual change overlapped the open pull requests of `lanes` on `paths`
+// before its sync: it waited `waited_ms` for their ships to end, and `is_cleared` is false where the
+// wait ran out first (joshuafolkken/kit#3901).
+const overlap_schema = z.object({
+	kind: z.literal(KIND.OVERLAP),
+	at: z.string(),
+	issue: z.number(),
+	lanes: z.array(z.number()),
+	paths: z.array(z.string()),
+	waited_ms: z.number(),
+	is_cleared: z.boolean(),
+})
+// A `backlog:drive` pass that left a free lane empty: `reason` is why — the offer verdict that started
+// nothing, or the hand-back that stopped the driver. How long the lane stayed empty is derived from the
+// next `held`, `released` or `dispatch` entry, the way a stop's wait is (joshuafolkken/kit#3995).
+// `waiting` names the issues a `chain` / `gate` hold waited on (joshuafolkken/kit#4513).
+const held_schema = z.object({
+	kind: z.literal(KIND.HELD),
+	at: z.string(),
+	reason: z.string(),
+	waiting: z.array(z.number()).optional(),
+})
+// The end of a hold no dispatch ended: every lane taken — one opened outside the driver included — or
+// the run finished, so no free lane is owed a child any more.
+const released_schema = z.object({ kind: z.literal(KIND.RELEASED), at: z.string() })
+// One `review:round2` decision a `josh ship` acted on for `issue`: `verdict` and the stable reason
+// `code` it fell under, so the period's skips and runs are counted by why (joshuafolkken/kit#4064).
+const round_two_schema = z.object({
+	kind: z.literal(KIND.ROUND_TWO),
+	at: z.string(),
+	issue: z.number(),
+	verdict: z.string(),
+	code: z.string(),
+})
+// A stall detector observation, written only when it changes: whether offerable backlog work and a free
+// lane coexisted, so a stall is aged from when both first held rather than from the last launch
+// (joshuafolkken/kit#4349).
+const offerable_schema = z.object({
+	kind: z.literal(KIND.OFFERABLE),
+	at: z.string(),
+	is_offerable: z.boolean(),
+})
+// One claim that waited `waited_ms` for the core budget before `command` could start — written by the
+// command itself, so a wait inside a gate, a scoped check or a ship lands in one record. `issue` is the
+// lane the claim ran in, absent outside a lane (joshuafolkken/kit#4382).
+const core_wait_schema = z.object({
+	kind: z.literal(KIND.CORE_WAIT),
+	at: z.string(),
+	command: z.string(),
+	waited_ms: z.number(),
+	issue: z.number().optional(),
+})
+// One vitest run's slowest test files, each with its wall time from environment setup to its last
+// test, so a unit run whose wall time far outran its CPU names the file it stalled on
+// (joshuafolkken/kit#4451). Written by the run itself (`tools/test/unit-file-reporter.ts`).
+const unit_file_schema = z.object({ file: z.string(), elapsed_ms: z.number() })
+const unit_files_schema = z.object({
+	kind: z.literal(KIND.UNIT_FILES),
+	at: z.string(),
+	files: z.array(unit_file_schema),
+})
+// One `josh test:related` run (joshuafolkken/kit#4465): `scope` is `related`, `none` or the full-suite
+// fallback kind; the four counts are its input — the change itself, what a main sync brought into it,
+// what the change since the test-read map's tree joined to it and the map's readers — and `test_files`
+// how many vitest ran, absent where none reported. `trigger_files` are the changed files that sent a
+// full-suite run there, absent where none did and on rows written before it (joshuafolkken/kit#4510).
+const test_related_schema = z.object({
+	kind: z.literal(KIND.TEST_RELATED),
+	at: z.string(),
+	scope: z.string(),
+	changed: z.number(),
+	synced: z.number(),
+	since_map: z.number(),
+	readers: z.number(),
+	test_files: z.number().optional(),
+	trigger_files: z.array(z.string()).optional(),
+	elapsed_ms: z.number(),
+})
+const entry_schema = z.discriminatedUnion('kind', [
+	merge_schema,
+	gate_schema,
+	load_schema,
+	dispatch_schema,
+	stage_schema,
+	stop_schema,
+	overlap_schema,
+	held_schema,
+	released_schema,
+	round_two_schema,
+	offerable_schema,
+	core_wait_schema,
+	unit_files_schema,
+	test_related_schema,
+])
+
+type LedgerEntry = z.infer<typeof entry_schema>
+type MergeEntry = z.infer<typeof merge_schema>
+type GateEntry = z.infer<typeof gate_schema>
+type LoadEntry = z.infer<typeof load_schema>
+type DispatchEntry = z.infer<typeof dispatch_schema>
+type StageEntry = z.infer<typeof stage_schema>
+type StopEntry = z.infer<typeof stop_schema>
+type OverlapEntry = z.infer<typeof overlap_schema>
+type HeldEntry = z.infer<typeof held_schema>
+type RoundTwoEntry = z.infer<typeof round_two_schema>
+type OfferableEntry = z.infer<typeof offerable_schema>
+type CoreWaitEntry = z.infer<typeof core_wait_schema>
+type CoreWaitRecord = Omit<CoreWaitEntry, 'kind' | 'at'>
+type UnitFilesEntry = z.infer<typeof unit_files_schema>
+type UnitFileRecord = z.infer<typeof unit_file_schema>
+type TestRelatedEntry = z.infer<typeof test_related_schema>
+type TestRelatedRecord = Omit<TestRelatedEntry, 'kind' | 'at'>
+type RoundTwoRecord = Omit<RoundTwoEntry, 'kind' | 'at'>
+// What a finished gate reports; the ledger stamps the kind and the time.
+type GateRecord = Omit<GateEntry, 'kind' | 'at'>
+type GateCheckRecord = z.infer<typeof check_schema>
+type StageRecord = Omit<StageEntry, 'kind' | 'at'>
+type StopRecord = Omit<StopEntry, 'kind' | 'at'>
+type OverlapRecord = Omit<OverlapEntry, 'kind' | 'at'>
+type HeldRecord = Omit<HeldEntry, 'kind' | 'at' | 'waiting'> & {
+	waiting?: ReadonlyArray<number> | undefined
+}
+
+const lane_ledger_schema = { KIND, entry_schema }
+
+export type {
+	CoreWaitEntry,
+	CoreWaitRecord,
+	DispatchEntry,
+	GateCheckRecord,
+	GateEntry,
+	GateRecord,
+	HeldEntry,
+	HeldRecord,
+	LedgerEntry,
+	LoadEntry,
+	MergeEntry,
+	OfferableEntry,
+	OverlapEntry,
+	OverlapRecord,
+	RoundTwoEntry,
+	RoundTwoRecord,
+	StageEntry,
+	StageRecord,
+	StopEntry,
+	StopRecord,
+	TestRelatedEntry,
+	TestRelatedRecord,
+	UnitFileRecord,
+	UnitFilesEntry,
+}
+export { lane_ledger_schema }