@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/epic/epic-bundle-evidence.ts

@@ -1,4 +1,5 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
+import type { SignalSection } from './epic-audit'
 import { epic_bundle, type BacklogIssue } from './epic-bundle'
 
 // The facts the bundle decision was already made from, printed beside the order it prints.
@@ -20,10 +21,26 @@ import { epic_bundle, type BacklogIssue } from './epic-bundle'
 type EvidenceKind = 'dependency' | 'reference'
 
 // One fact, and the order it points to. `first` is the issue the fact puts ahead of `second`.
+// `section` is where a reference was read, so the reader sees it was the acceptance criteria or the
+// parent line that counted, not a mention elsewhere in the body.
 interface OrderingEvidence {
 	kind: EvidenceKind
 	first: number
 	second: number
+	section?: SignalSection
+}
+
+// What one directed test found: nothing, or the fact with whatever detail it carries.
+type EvidenceFound = Pick<OrderingEvidence, 'section'> | undefined
+
+function blocker_found(from: BacklogIssue, to: BacklogIssue): EvidenceFound {
+	return epic_bundle.names_as_blocker(from, to) ? {} : undefined
+}
+
+function reference_found(from: BacklogIssue, to: BacklogIssue): EvidenceFound {
+	const section = epic_bundle.reference_section(from, to)
+
+	return section === undefined ? undefined : { section }
 }
 
 // The two readings, each written as a directed test of one issue against another. Both are
@@ -34,14 +51,28 @@ interface OrderingEvidence {
 // `blocked-by` says so outright: the blocker has to land before the issue that declares it. A
 // reference says it by having been written — the issue that names another was drafted with that
 // other one already in existence, so the named one is the earlier of the two.
-const EVIDENCE_TESTS: ReadonlyArray<{
+interface EvidenceTest {
 	kind: EvidenceKind
-	holds: (from: BacklogIssue, to: BacklogIssue) => boolean
-}> = [
-	{ kind: 'dependency', holds: (from, to) => epic_bundle.names_as_blocker(from, to) },
-	{ kind: 'reference', holds: (from, to) => epic_bundle.names_in_body(from, to) },
+	find: (from: BacklogIssue, to: BacklogIssue) => EvidenceFound
+}
+
+const EVIDENCE_TESTS: ReadonlyArray<EvidenceTest> = [
+	{ kind: 'dependency', find: blocker_found },
+	{ kind: 'reference', find: reference_found },
 ]
 
+// One test in one direction: the fact it found, or none.
+function directed_evidence(
+	test: EvidenceTest,
+	from: BacklogIssue,
+	to: BacklogIssue,
+): Array<OrderingEvidence> {
+	const found = test.find(from, to)
+	if (found === undefined) return []
+
+	return [{ kind: test.kind, first: to.number, second: from.number, ...found }]
+}
+
 // Both directions of one pair, because both are facts. Two issues that name each other produce two
 // lines pointing opposite ways, which is the honest report: the reader is the one deciding.
 function pair_evidence(subject: BacklogIssue, other: BacklogIssue): Array<OrderingEvidence> {
@@ -50,10 +81,8 @@ function pair_evidence(subject: BacklogIssue, other: BacklogIssue): Array<Orderi
 		{ from: other, to: subject },
 	]
 
-	return EVIDENCE_TESTS.flatMap(({ kind, holds }) =>
-		directions
-			.filter((pair) => holds(pair.from, pair.to))
-			.map((pair) => ({ kind, first: pair.to.number, second: pair.from.number })),
+	return EVIDENCE_TESTS.flatMap((test) =>
+		directions.flatMap((pair) => directed_evidence(test, pair.from, pair.to)),
 	)
 }
 
@@ -85,8 +114,8 @@ function ordering_evidence(
 	return member_pairs(members).flatMap((pair) => pair_evidence(pair.left, pair.right))
 }
 
-// How each kind reads. `where` says the fact came from prose rather than from a recorded relation,
-// and the two `order_*` halves say how strongly the fact settles the order.
+// How each kind reads. The two `order_*` halves say how strongly the fact settles the order; where a
+// reference was read comes from the fact itself (`section_phrase`).
 //
 // **A recorded dependency states the order; a reference only points at it.** A `blocked-by` says
 // outright that the blocker lands first. A reference says it by having been written — which holds
@@ -95,20 +124,14 @@ function ordering_evidence(
 // the reference line reports the direction it points to and asserts nothing further; deciding is
 // still the reader's.
 const EVIDENCE_WORDING: Readonly<
-	Record<EvidenceKind, { verb: string; where: string; order_prefix: string; order_suffix: string }>
+	Record<EvidenceKind, { verb: string; order_prefix: string; order_suffix: string }>
 > = {
-	dependency: {
-		verb: 'is recorded as blocked by',
-		where: '',
-		order_prefix: '',
-		order_suffix: ' comes first',
-	},
-	reference: {
-		verb: 'names',
-		where: ' in its body',
-		order_prefix: 'that points to ',
-		order_suffix: ' first',
-	},
+	dependency: { verb: 'is recorded as blocked by', order_prefix: '', order_suffix: ' comes first' },
+	reference: { verb: 'names', order_prefix: 'that points to ', order_suffix: ' first' },
+}
+
+function section_phrase(item: OrderingEvidence): string {
+	return item.section === undefined ? '' : ` in its ${item.section}`
 }
 
 const EVIDENCE_HEADING = '  Evidence:'
@@ -117,12 +140,12 @@ const EVIDENCE_INDENT_WIDTH = 4
 const EVIDENCE_INDENT = ' '.repeat(EVIDENCE_INDENT_WIDTH)
 
 function format_one(item: OrderingEvidence): string {
-	const { verb, where, order_prefix, order_suffix } = EVIDENCE_WORDING[item.kind]
+	const { verb, order_prefix, order_suffix } = EVIDENCE_WORDING[item.kind]
 	const first = issue_cite.plain(item.first)
 	const second = issue_cite.plain(item.second)
 	const order = `${order_prefix}${first}${order_suffix}`
 
-	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${where} — ${order}`
+	return `${EVIDENCE_INDENT}${second} ${verb} ${first}${section_phrase(item)} — ${order}`
 }
 
 // The block that goes under `Order:`. Empty when neither reading found anything, which leaves the

package/scripts/epic/epic-bundle-referenced.ts

@@ -44,10 +44,21 @@ interface ReferencedLookups {
 	dropped: Array<number>
 }
 
+// Every number the body names, the ones a bundle signal counts first: the cap below must not leave a
+// signal unread because twenty background mentions came ahead of it in the body.
+function signal_first(subject: BacklogIssue): Array<number> {
+	const signals = epic_audit_logic
+		.signal_references(subject.body, subject.repo)
+		.map((reference) => reference.number)
+	const all = epic_audit_logic.parse_references(subject.body, subject.repo)
+
+	return [...new Set([...signals, ...all])]
+}
+
 function referenced_lookups(subject: BacklogIssue, known: ReadonlySet<number>): ReferencedLookups {
-	const candidates = epic_audit_logic
-		.parse_references(subject.body, subject.repo)
-		.filter((number) => number !== subject.number && !known.has(number))
+	const candidates = signal_first(subject).filter(
+		(number) => number !== subject.number && !known.has(number),
+	)
 
 	return {
 		numbers: candidates.slice(0, REFERENCED_LOOKUP_LIMIT),

package/scripts/epic/epic-bundle.ts

@@ -1,6 +1,6 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { has_label_name, RELEASE_LABEL } from '#scripts/issue/issue-labels'
-import { epic_audit_logic } from './epic-audit'
+import { epic_audit_logic, type SignalSection } from './epic-audit'
 import { epic_graph } from './epic-graph'
 import type { DependencyLink } from './epic-parse'
 import type { IssueReference } from './epic-reference'
@@ -11,9 +11,9 @@ import type { IssueReference } from './epic-reference'
 // not reach the other way in: two issues filed days apart that turn out to be the front and back of
 // one job are executed separately, in whatever order, with the reasoning recorded nowhere.
 //
-// The candidate search reads issue references out of prose — the same reading `epic:audit` does
-// inside one epic. That analysis is imported rather than written a second time; the only
-// difference is what it is pointed at.
+// The candidate search reads issue references out of the acceptance criteria and the `parent: #N`
+// line — the same reading `epic:audit` does inside one epic. That analysis is imported rather than
+// written a second time; the only difference is what it is pointed at.
 
 // An open issue as the search sees it.
 interface BacklogIssue {
@@ -59,11 +59,19 @@ interface BundleDecision {
 	reason: string
 }
 
-// Whether `from`'s body names `to`. One direction of the citation test, because which direction it
-// was is what `epic-bundle-evidence.ts` reports — and the read is single-sourced here rather than
-// written a second time there, so the candidate search and the evidence beside it cannot drift apart.
+// Where `from`'s body names `to` in a place that counts as a relation — its acceptance criteria or
+// its `parent: #N` line — or nothing. One direction of the citation test, because which direction
+// and which section it was is what `epic-bundle-evidence.ts` reports — and the read is single-sourced
+// here rather than written a second time there, so the candidate search and the evidence beside it
+// cannot drift apart. A number written only as the background of a filing is not a relation.
+function reference_section(from: BacklogIssue, to: BacklogIssue): SignalSection | undefined {
+	return epic_audit_logic
+		.signal_references(from.body, from.repo)
+		.find((reference) => reference.number === to.number)?.section
+}
+
 function names_in_body(from: BacklogIssue, to: BacklogIssue): boolean {
-	return epic_audit_logic.parse_references(from.body, from.repo).includes(to.number)
+	return reference_section(from, to) !== undefined
 }
 
 // Whether two issues cite each other, in either direction. A one-way citation is enough: the point
@@ -324,7 +332,7 @@ function bundle_children(
 
 const epic_bundle = {
 	names_as_blocker,
-	names_in_body,
+	reference_section,
 	NO_SIGNAL_REASON,
 	already_tracked_reason,
 	has_recorded_dependency,

package/scripts/followup/git-followup-workflow.ts

@@ -7,6 +7,7 @@ import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { cli_body } from '#scripts/josh/cli-body'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
+import { acceptance_map_check } from '#scripts/review/acceptance-map-check'
 import { live_evidence } from '#scripts/review/live-evidence'
 import { review_attest } from '#scripts/review/review-attest'
 import { review_record } from '#scripts/review/review-record'
@@ -143,7 +144,7 @@ function is_merge_permitted(status: string): boolean {
 	return status === 'ok' || status === 'not-required'
 }
 
-function is_valid_issue(issue_number: string | undefined): boolean {
+function is_valid_issue(issue_number: string | undefined): issue_number is string {
 	return issue_number !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
 }
 
@@ -194,6 +195,21 @@ async function assert_live_evidence(should_merge: boolean, branch_name: string):
 	throw new Error(live_evidence.refusal_message())
 }
 
+// Every acceptance criterion the Issue carries at the merge maps to a row in the pull request body —
+// `acceptance_map` carries the why. Re-read here rather than at the commit, so a criterion added
+// during the review is refused too. A run whose issue it cannot identify has no criteria to read.
+async function assert_acceptance_mapped(
+	should_merge: boolean,
+	issue_number: string | undefined,
+	branch_name: string,
+): Promise<void> {
+	if (!should_merge || !is_valid_issue(issue_number)) return
+
+	const refusal = await acceptance_map_check.refusal(issue_number, branch_name)
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
 // Every pre-merge refusal, in order — each one throws, so nothing merges past the first that fails.
 async function assert_merge_gates(
 	should_merge: boolean,
@@ -203,6 +219,7 @@ async function assert_merge_gates(
 	await assert_review_attested(should_merge)
 	await assert_review_recorded(should_merge, issue_number)
 	await assert_live_evidence(should_merge, branch_name)
+	await assert_acceptance_mapped(should_merge, issue_number, branch_name)
 }
 
 // After the gates, before the CI wait: a line appended since the run's commit rides the pull request
@@ -261,6 +278,7 @@ try {
 }
 
 const git_followup_workflow = {
+	assert_acceptance_mapped,
 	assert_live_evidence,
 	assert_review_attested,
 	assert_review_recorded,

package/scripts/gate/check-inputs.ts

@@ -0,0 +1,129 @@
+import path from 'node:path'
+import { lint_related_scope } from '#scripts/lint/lint-related-scope'
+import { gate_plan } from './gate-plan'
+
+// Which paths each gate check reads, so a gate re-run reuses a check none of whose inputs moved
+// (`check-reuse.ts`). **A check with no scope here always runs**: `cspell` reads every
+// text file, the unit suite reads documents and fixtures as well as code, `behavior` reads a transcript
+// outside the tree and `metrics` reads whatever it measures. Naming a scope for any of them would be a
+// guess, and a wrong guess is a check reported green without having run.
+//
+// **The scopes over-approximate, never under**: a path in doubt is an input. `check` and `exports`
+// read source modules and the JSON they import. `lint` is prettier plus eslint, so its inputs are those
+// sources plus every file prettier formats — the extensions `lint:related` already selects, less what
+// prettier's own ignore files leave out (`.claude/**/*.md`). Prettier answers that itself through
+// `getFileInfo`, so the two ignore files stay the single source.
+//
+// **A configuration file is an input of every scoped check**: a manifest or lock file moves the
+// installed toolchain, and an ignore or editor file moves what prettier reads.
+
+const SOURCE_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.vue',
+	'.json',
+	'.jsonc',
+])
+
+const GIT_IGNORE = '.gitignore'
+const PRETTIER_IGNORE = '.prettierignore'
+const PRETTIER_IGNORE_FILES = [GIT_IGNORE, PRETTIER_IGNORE] as const
+
+const CONFIG_FILES: ReadonlySet<string> = new Set([
+	'package.json',
+	'pnpm-lock.yaml',
+	'pnpm-workspace.yaml',
+	'package-lock.json',
+	'yarn.lock',
+	'bun.lock',
+	'bun.lockb',
+	'.npmrc',
+	'.editorconfig',
+	...PRETTIER_IGNORE_FILES,
+])
+
+const PRETTIER_CONFIG_PREFIX = '.prettierrc'
+
+// Whether prettier would leave `relative` out; `false` when prettier cannot be asked, which keeps the
+// path an input.
+type PrettierIgnored = (relative: string) => Promise<boolean>
+
+type InputTest = (relative: string, is_ignored: PrettierIgnored) => Promise<boolean>
+
+function is_config(relative: string): boolean {
+	const name = path.basename(relative)
+
+	return CONFIG_FILES.has(name) || name.startsWith(PRETTIER_CONFIG_PREFIX)
+}
+
+function is_source(relative: string): boolean {
+	return SOURCE_EXTENSIONS.has(path.extname(relative))
+}
+
+async function is_lint_input(relative: string, is_ignored: PrettierIgnored): Promise<boolean> {
+	if (is_source(relative)) return true
+	if (!lint_related_scope.is_lintable(relative)) return false
+
+	return !(await is_ignored(relative))
+}
+
+async function is_source_input(relative: string): Promise<boolean> {
+	return is_source(relative)
+}
+
+function prettier_ignored(root: string): PrettierIgnored {
+	const ignore_path = PRETTIER_IGNORE_FILES.map((name) => path.join(root, name))
+
+	return async function is_ignored(relative: string): Promise<boolean> {
+		try {
+			const prettier = await import('prettier')
+			const info = await prettier.getFileInfo(path.join(root, relative), {
+				ignorePath: ignore_path,
+			})
+
+			return info.ignored
+		} catch {
+			return false
+		}
+	}
+}
+
+const SCOPES: ReadonlyMap<string, InputTest> = new Map([
+	[gate_plan.LINT_LABEL, is_lint_input],
+	[gate_plan.TYPE_CHECK_LABEL, is_source_input],
+	[gate_plan.EXPORTS_LABEL, is_source_input],
+])
+
+function is_scoped(label: string): boolean {
+	return SCOPES.has(label)
+}
+
+// Whether any of `paths` (repository-root relative) is an input of the check `label`. An unscoped
+// check answers `true` for every set of paths, so the only way to reuse it is never.
+async function touches_inputs(
+	label: string,
+	paths: ReadonlyArray<string>,
+	is_ignored: PrettierIgnored,
+): Promise<boolean> {
+	const scope = SCOPES.get(label)
+
+	if (scope === undefined || paths.some((relative) => is_config(relative))) return true
+
+	const answers = await Promise.all(
+		paths.map(async (relative) => await scope(relative, is_ignored)),
+	)
+
+	return answers.includes(true)
+}
+
+const check_inputs = { is_scoped, prettier_ignored, touches_inputs }
+
+export type { PrettierIgnored }
+export { check_inputs }

package/scripts/gate/check-reuse.ts

@@ -0,0 +1,162 @@
+import { git_command } from '#scripts/git/git-command'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_tree } from '#scripts/review/review-tree'
+import { check_inputs, type PrettierIgnored } from './check-inputs'
+import { gate_report, type GateStepResult } from './gate-report'
+import type { GateTree } from './gate-tree'
+
+// One green record per scoped check, so a gate re-run starts only the checks whose inputs moved
+// (`check-inputs.ts` decides what each reads). The whole-gate record (`gate-skip.ts`) is refused the
+// moment the merge base moves; a main sync that brought in only `.claude/**/*.md` then re-ran lint and
+// the type check over sources neither had a reason to read again.
+//
+// **What moved is the union of two diffs**, and together they are every path whose content can differ
+// from the tree the record was taken on. The changed-file map is a diff against the merge base, so a
+// path absent from both maps holds the merge base's content — and the base's own diff
+// (`git diff <recorded> <current>`) names every path that content moved for. A path in either map whose
+// digest differs is the other half (`file_map_stamp.changed_since`).
+//
+// **A record is reuse of a result, not a check dropped**: no base, an empty changed-file map, an
+// unreadable base diff or no root answers "not reusable", and a check with no scope is never reusable. The records are written and read
+// only where the CLI entry resolved their destination (`CheckRecords`), so a suite driving the gate
+// never plants a green record over the live tree.
+
+const CHECK_PREFIX = 'josh-gate-check-'
+const NAME_SEPARATOR = '\0'
+const BASE_DIFF = ['diff', '--name-only', '--no-renames', '-z'] as const
+
+const check_stamp = file_map_stamp.create(CHECK_PREFIX, PROJECT_ROOT)
+
+// Where each check's record lives — a parameter so a test plants records in a directory of its own.
+type CheckRecords = (label: string) => string
+
+function default_records(label: string): string {
+	return stamp_file.stamp_path(`${CHECK_PREFIX}${label}-`, PROJECT_ROOT)
+}
+
+async function base_diff(from: string, to: string): Promise<ReadonlyArray<string> | undefined> {
+	if (from === to) return []
+
+	try {
+		const names = await git_spawn.read([...BASE_DIFF, from, to])
+
+		return names.split(NAME_SEPARATOR).filter((name) => name !== '')
+	} catch {
+		return undefined
+	}
+}
+
+async function moved_since(
+	stamp: FileMapStamp,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	// An empty map is also what `gate-tree.ts` answers when git could not be read, so it describes no
+	// tree to diff against — the reading `gate_skip.gate_reuse` refuses too.
+	const is_unread = Object.keys(tree.files).length === 0
+
+	if (is_unread || stamp.base === undefined || tree.base === undefined) return undefined
+
+	const moved_base = await base_diff(stamp.base, tree.base)
+
+	if (moved_base === undefined) return undefined
+
+	return [...file_map_stamp.changed_since(stamp, tree.files), ...moved_base]
+}
+
+interface ReuseContext {
+	tree: GateTree
+	records: CheckRecords
+	is_ignored: PrettierIgnored
+}
+
+async function is_stamp_reusable(
+	label: string,
+	stamp: FileMapStamp,
+	context: ReuseContext,
+): Promise<boolean> {
+	const moved = await moved_since(stamp, context.tree)
+
+	if (moved === undefined) return false
+
+	return !(await check_inputs.touches_inputs(label, moved, context.is_ignored))
+}
+
+// The time the check's record was taken, or `undefined` when the check has to run.
+async function reused_at(label: string, context: ReuseContext): Promise<string | undefined> {
+	const stamp = check_inputs.is_scoped(label) ? check_stamp.read(context.records(label)) : undefined
+
+	if (stamp === undefined) return undefined
+
+	return (await is_stamp_reusable(label, stamp, context)) ? stamp.taken_at : undefined
+}
+
+async function read_root(): Promise<string | undefined> {
+	try {
+		return await git_command.repository_root()
+	} catch {
+		return undefined
+	}
+}
+
+// Each reusable check's label, mapped to when it was last green.
+async function reusable_checks(
+	labels: ReadonlyArray<string>,
+	tree: GateTree,
+	records: CheckRecords = default_records,
+): Promise<ReadonlyMap<string, string>> {
+	const root = await read_root()
+
+	if (root === undefined) return new Map()
+
+	const context = { tree, records, is_ignored: check_inputs.prettier_ignored(root) }
+	const answers = await Promise.all(
+		labels.map(async (label) => [label, await reused_at(label, context)] as const),
+	)
+
+	return new Map(answers.flatMap(([label, at]) => (at === undefined ? [] : [[label, at] as const])))
+}
+
+function is_recordable(result: GateStepResult): boolean {
+	return (
+		check_inputs.is_scoped(result.label) &&
+		!gate_report.is_gate_step_failed(result) &&
+		gate_report.has_nothing_to_say(result)
+	)
+}
+
+function write_records(
+	results: ReadonlyArray<GateStepResult>,
+	tree: GateTree,
+	records: CheckRecords,
+): void {
+	const recordable = results.filter((result) => is_recordable(result))
+
+	for (const result of recordable) check_stamp.write(tree.files, records(result.label), tree.base)
+}
+
+// Every scoped check that passed silently, recorded against the tree it read — a red gate's green
+// checks included, since each record answers for its own check alone. Nothing is written when the tree
+// moved while the checks ran, and a failed write leaves no record, the safe direction either way.
+async function record_green_checks(
+	results: ReadonlyArray<GateStepResult>,
+	tree: GateTree,
+	records: CheckRecords = default_records,
+): Promise<void> {
+	try {
+		const after = await review_tree.read_changed_tree()
+
+		if (JSON.stringify(after) !== JSON.stringify(tree.files)) return
+
+		write_records(results, { files: after, base: tree.base }, records)
+	} catch {
+		/* no record is the safe answer */
+	}
+}
+
+const check_reuse = { DEFAULT_RECORDS: default_records, record_green_checks, reusable_checks }
+
+export type { CheckRecords }
+export { check_reuse }