@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/review/review-brief.ts

@@ -1,7 +1,10 @@
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { removed_tests } from './removed-tests'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
 import { review_diff_parts, type DiffParts } from './review-diff-parts'
+import { review_interaction } from './review-interaction'
+import { review_untouched_readers, type ReadersRead } from './review-untouched-readers'
 
 // The text `josh review:brief` prints — the `/code-review` invocation, composed from what the run
 // already knows.
@@ -414,6 +417,14 @@ interface BriefInput {
 	// The change written as parts under the Bash output cap. Absent when the
 	// write failed, and the target line alone then names the change.
 	diff?: { parts: DiffParts; cap: number } | undefined
+	// The tests the change removes, listed for the reviewer to account for. Absent or empty, no section.
+	removed_tests?: ReadonlyArray<string> | undefined
+	// The run-tooling paths an interaction review is briefed on (joshuafolkken/kit#4276). Absent, the
+	// brief is `/code-review`'s alone.
+	interaction?: ReadonlyArray<string> | undefined
+	// The readers outside the diff of each exported name it edits (joshuafolkken/kit#4515). A failed
+	// read is printed as one; absent or empty, no section.
+	readers?: ReadersRead | undefined
 }
 
 const SECOND_ROUND = 2
@@ -437,16 +448,30 @@ function target_block(input: BriefInput): string {
 // code that narrowing exists to keep out of scope. Decided by the target actually printed, not by
 // the round: every round that cannot narrow widens through `whole_change_target`, and that round
 // needs the parts as much as a first one does.
-function diff_block(input: BriefInput, target: string): ReadonlyArray<string> {
-	const is_whole_change = target.includes(whole_change_target(input.checkout.root, input.base))
+function is_whole_change(input: BriefInput, target: string): boolean {
+	return target.includes(whole_change_target(input.checkout.root, input.base))
+}
 
-	if (!is_whole_change || input.diff === undefined) return []
+function diff_block(input: BriefInput, target: string): ReadonlyArray<string> {
+	if (!is_whole_change(input, target) || input.diff === undefined) return []
 
 	return ['', review_diff_parts.reading_block(input.diff.parts, input.diff.cap)]
 }
 
+// Beside a whole-change target only, for the reason `diff_block` gives: a narrowed round keeps the
+// rest of the change, and so its readers, out of scope.
+function readers_block(input: BriefInput, target: string): ReadonlyArray<string> {
+	if (!is_whole_change(input, target)) return []
+
+	return review_untouched_readers.brief_block(input.readers)
+}
+
 // The level alone on the first line, because the level-only mode's contract — a caller reading the
 // answer with `$(...)` — is the one thing a brief must not break.
+function interaction_block(targets: ReadonlyArray<string> | undefined): ReadonlyArray<string> {
+	return targets === undefined ? [] : ['', review_interaction.brief_block(targets)]
+}
+
 function compose(input: BriefInput): string {
 	const profile = input.profile ?? agent_role_profile.DEFAULT_PROFILES.reviewer
 	const target = target_block(input)
@@ -465,6 +490,9 @@ function compose(input: BriefInput): string {
 		'',
 		target,
 		...diff_block(input, target),
+		...readers_block(input, target),
+		...removed_tests.brief_block(input.removed_tests ?? []),
+		...interaction_block(input.interaction),
 	].join('\n')
 }
 

package/scripts/review/review-code-tree.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { git_command } from '#scripts/git/git-command'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { comment_ranges, type TypeScriptApi } from './comment-ranges'
 import { review_stamps } from './review-stamps'
 
@@ -26,7 +27,6 @@ const SCRIPT_EXTENSIONS: ReadonlyArray<string> = ['.ts', '.js']
 const SVELTE_EXTENSION = '.svelte'
 const EXCLUDED_PREFIX = '.claude/'
 const TYPESCRIPT_MODULE = 'typescript'
-const PACKAGE_JSON = 'package.json'
 
 function is_svelte(relative: string): boolean {
 	return relative.endsWith(SVELTE_EXTENSION)
@@ -100,20 +100,24 @@ async function record(
 }
 
 // The paths whose code round 1's fixes left as it was — whose difference, if any, is in comments.
-// Nothing qualifies against a record taken on another base, for the reason the round-1 snapshot is
-// refused on one.
+// Against a record taken on another base only `unmoved` qualifies — the paths the move left alone
+// (`review_round_one_blobs.unmoved`), where the carried file is round 1's own and equal code digests
+// still mean a comment-only fix (joshuafolkken/kit#4165).
 function comment_only(
 	snapshot: FileMapStamp | undefined,
 	tree: Record<string, string>,
 	base: string | undefined,
+	unmoved: ReadonlyArray<string> = [],
 ): ReadonlyArray<string> {
-	if (snapshot === undefined || base === undefined || snapshot.base !== base) return []
+	if (snapshot === undefined || base === undefined) return []
+	const is_same_base = snapshot.base === base
 
 	return Object.keys(snapshot.files).filter(
-		(relative) => snapshot.files[relative] === tree[relative],
+		(relative) =>
+			snapshot.files[relative] === tree[relative] && (is_same_base || unmoved.includes(relative)),
 	)
 }
 
-const review_code_tree = { comment_only, read, record, tree_of }
+const review_code_tree = { comment_only, load_typescript, read, record, tree_of }
 
 export { review_code_tree }

package/scripts/review/review-comment-round.ts

@@ -33,12 +33,14 @@ const PER_PAGE = '100'
 const UNNAMED_REPOSITORY = 'Could not name this repository from `git remote`.'
 const UNREAD_SEARCH = 'Could not read the search for closed issues with a comment round.'
 const UNREAD_COMMENTS = 'Could not read the comments of'
+const UNREAD_PERMISSION = 'Could not read the write permission of'
 
 const search_item_schema = z.object({ number: z.number() })
 const search_schema = z.object({ items: z.array(search_item_schema) })
 const comment_schema = z.object({
 	body: z.string().nullish(),
 	author_association: z.string().nullish(),
+	user: z.looseObject({ login: z.string() }).nullish(),
 })
 
 type IssueComment = z.infer<typeof comment_schema>
@@ -50,13 +52,29 @@ function body_of(lines: ReadonlyArray<string>): string {
 // The ledger lines of every comment round among one issue's comments, oldest first; any other
 // comment, one that only quotes the heading among them, carries none — nor does one whose author
 // cannot write to the repository: anyone can comment on a public issue, and the carried lines ride
-// the run's commit unreviewed.
-function lines_of(comments: ReadonlyArray<IssueComment>): Array<string> {
-	return comments
-		.filter((comment) => gh_author_association.is_trusted(comment.author_association))
-		.map((comment) => comment.body ?? '')
-		.filter((body) => body.startsWith(COMMENT_HEADING))
-		.flatMap((body) => body.split('\n'))
+// the run's commit unreviewed. A permission lookup that failed throws instead: the carried file is
+// written once, so a round dropped on a transient failure would never be carried.
+async function is_trusted_comment(comment: IssueComment): Promise<boolean> {
+	const login = comment.user?.login
+	const is_trusted = await gh_author_association.trust_of({
+		login,
+		association: comment.author_association,
+	})
+
+	if (is_trusted === undefined) throw new Error(`${UNREAD_PERMISSION} ${login ?? ''}`)
+
+	return is_trusted
+}
+
+async function lines_of(comments: ReadonlyArray<IssueComment>): Promise<Array<string>> {
+	const rounds = comments.filter((comment) => (comment.body ?? '').startsWith(COMMENT_HEADING))
+	const trusted = await Promise.all(
+		rounds.map(async (comment) => await is_trusted_comment(comment)),
+	)
+
+	return rounds
+		.filter((_comment, index) => trusted[index] === true)
+		.flatMap((comment) => (comment.body ?? '').split('\n'))
 		.filter((line) => review_finding_ledger.is_finding_line(line))
 }
 
@@ -93,7 +111,7 @@ async function carry_issue(issue: number, root: string): Promise<number> {
 
 	if (raw === undefined) throw new Error(`${UNREAD_COMMENTS} ${session_cite.issue(issue)}`)
 
-	const lines = lines_of(parse_json_array_safe(raw, comment_schema))
+	const lines = await lines_of(parse_json_array_safe(raw, comment_schema))
 
 	await observation_ledger_home.append(carried_path(issue, root), lines)
 

package/scripts/review/review-finding-ledger.ts

@@ -7,7 +7,10 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 // prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
 // one commit path, a second line *type* rather than a second ledger.
 
-const FINDING_PREFIX = '- rf:'
+// **The interaction review writes the same grammar under its own prefix** (joshuafolkken/kit#4276), so
+// its round is told apart from `/code-review`'s by the merge gate, and its findings stay out of the
+// `/code-review` tally a reader compares rounds by.
+const PREFIX = { code: '- rf:', interaction: '- ri:' } as const
 const FIELD_SEPARATOR = ' | '
 const FIELD_COUNT = 5
 
@@ -34,6 +37,7 @@ const NO_FILE = '-'
 
 type Category = (typeof CATEGORIES)[number]
 type Severity = (typeof SEVERITIES)[number]
+type LineKind = keyof typeof PREFIX
 
 interface Finding {
 	category: Category
@@ -65,27 +69,36 @@ function issue_field(issue: number): string {
 	return issue_cite.plain(issue)
 }
 
-function line_of(fields: ReadonlyArray<string>): string {
-	return `${FINDING_PREFIX}${fields.join(FIELD_SEPARATOR)}`
+function line_of(fields: ReadonlyArray<string>, kind: LineKind): string {
+	return `${PREFIX[kind]}${fields.join(FIELD_SEPARATOR)}`
 }
 
-function finding_line(finding: Finding, date: string, issue: number): string {
-	return line_of([finding.category, finding.severity, finding.file, date, issue_field(issue)])
+function finding_line(
+	finding: Finding,
+	date: string,
+	issue: number,
+	kind: LineKind = 'code',
+): string {
+	return line_of([finding.category, finding.severity, finding.file, date, issue_field(issue)], kind)
 }
 
 // **A zero-finding round records `none`, not nothing.** Reading its absence as "no findings" would
 // merge the round that found nothing with the round nobody recorded, which is the exact confusion the
 // ledger exists to end.
-function zero_round_line(date: string, issue: number): string {
-	return line_of([NONE, NONE, NO_FILE, date, issue_field(issue)])
+function zero_round_line(date: string, issue: number, kind: LineKind = 'code'): string {
+	return line_of([NONE, NONE, NO_FILE, date, issue_field(issue)], kind)
 }
 
-function is_finding_line(line: string): boolean {
-	return line.trimStart().startsWith(FINDING_PREFIX)
+function is_finding_line(line: string, kind: LineKind = 'code'): boolean {
+	return line.trimStart().startsWith(PREFIX[kind])
+}
+
+function fields_of(line: string, kind: LineKind = 'code'): ReadonlyArray<string> {
+	return line.trimStart().slice(PREFIX[kind].length).split(FIELD_SEPARATOR)
 }
 
 function category_of(line: string): string | undefined {
-	const fields = line.trimStart().slice(FINDING_PREFIX.length).split(FIELD_SEPARATOR)
+	const fields = fields_of(line)
 
 	return fields.length === FIELD_COUNT ? fields[0] : undefined
 }
@@ -135,8 +148,8 @@ function zero_round_count(content: string): number {
 // The issue a finding line is keyed to — its fifth field, the `#<N>` token — or `undefined` for a
 // non-finding or malformed line. The record check reads this to ask whether a given issue's round was
 // recorded at all.
-function issue_of(line: string): string | undefined {
-	const fields = line.trimStart().slice(FINDING_PREFIX.length).split(FIELD_SEPARATOR)
+function issue_of(line: string, kind: LineKind): string | undefined {
+	const fields = fields_of(line, kind)
 
 	return fields.length === FIELD_COUNT ? fields[FIELD_COUNT - 1] : undefined
 }
@@ -145,10 +158,12 @@ function issue_of(line: string): string | undefined {
 // asks whether the round was recorded, not whether it found anything — reading the issue field, which
 // a zero-finding line carries too, is what keeps a clean round's single line from reading as "nobody
 // recorded this".
-function has_issue_record(content: string, issue: number): boolean {
+function has_issue_record(content: string, issue: number, kind: LineKind = 'code'): boolean {
 	const target = issue_field(issue)
 
-	return content.split('\n').some((line) => is_finding_line(line) && issue_of(line) === target)
+	return content
+		.split('\n')
+		.some((line) => is_finding_line(line, kind) && issue_of(line, kind) === target)
 }
 
 const review_finding_ledger = {
@@ -165,5 +180,5 @@ const review_finding_ledger = {
 	zero_round_line,
 }
 
-export type { CategoryCount, Finding }
+export type { CategoryCount, Finding, LineKind }
 export { review_finding_ledger }

package/scripts/review/review-interaction.ts

@@ -0,0 +1,94 @@
+import { project_checks } from '#scripts/gate/project-checks'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { session_cite } from '#scripts/issue/session-cite'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// The interaction review — one adversarial pass after `/code-review`, over a change to the run
+// tooling (joshuafolkken/kit#4276).
+//
+// **`/code-review` reads the diff for its own correctness, and the defects came from elsewhere**: most
+// of them were a new mechanism meeting an existing one — a pause meeting the next run, a count meeting
+// the per-second repaint. This pass is given one role, to find the existing features the change
+// breaks, and is due only where those meetings happen: the four directories below, in the kit
+// repository alone — a consumer's own `scripts/run/` is not kit's run tooling.
+//
+// **Its round is its own ledger line, `- ri:`**, so the merge gate tells it apart from `/code-review`'s
+// and `josh followup` refuses a due change that has none. The verdicts mirror `review_record.check`'s:
+// `not-required` covers both a change outside the directories and a checkout that keeps no ledger.
+
+const TARGET_DIRECTORIES = ['scripts/run/', 'scripts/lane/', 'scripts/backlog/', 'scripts/hooks/']
+
+const NOT_DUE_LINE =
+	'Interaction review not due: this is not the kit repository, or the change touches none of scripts/run/, scripts/lane/, scripts/backlog/ or scripts/hooks/.'
+
+const ROLE_LINES = [
+	'## Interaction review',
+	'This pass is not a second `/code-review`: do not hunt for bugs inside the diff — the round before it did. Your role is to find three existing features this change breaks. Check only these three:',
+	'1. Every state, command, label, file or process this change adds or gives a new meaning to — who else reads or writes it? Search the repository outside the diff for each. Where the plan has a `### 影響を受ける既存の利用者` section, check it names them all.',
+	'2. Does each of those readers and writers still behave correctly when the new state or value reaches it (for example, a paused lane counted as running)?',
+	'3. Does the change add heavy or synchronous work to a path called repeatedly — every second, every Bash call, every edit?',
+	"Report each break with the reader's `file:line` and the change's, rated by the rubric's severities; it is disposed of by `prompts/review.md` → \"Interaction review\".",
+]
+
+type InteractionStatus = 'ok' | 'missing' | 'not-required'
+
+function due_paths(
+	paths: ReadonlyArray<string>,
+	checkout: string = process.cwd(),
+): ReadonlyArray<string> {
+	if (!project_checks.is_kit_repository(checkout)) return []
+
+	return paths.filter((file) => TARGET_DIRECTORIES.some((directory) => file.startsWith(directory)))
+}
+
+function brief_block(targets: ReadonlyArray<string>): string {
+	const listed = targets.map((file) => `- ${file}`)
+
+	return [...ROLE_LINES, 'Changed in the run tooling:', ...listed].join('\n')
+}
+
+async function status_of(
+	issue: number,
+	paths: ReadonlyArray<string>,
+	root: string = observation_ledger_home.ledger_root(),
+): Promise<InteractionStatus> {
+	const content = due_paths(paths).length > 0 ? await observation_ledger_home.read(root) : undefined
+
+	if (content === undefined) return 'not-required'
+
+	return review_finding_ledger.has_issue_record(content, issue, 'interaction') ? 'ok' : 'missing'
+}
+
+// The status over this checkout's change — the reading `review:brief` takes.
+async function status(issue: number, root?: string): Promise<InteractionStatus> {
+	return await status_of(issue, await changed_paths.read_changed_paths(false), root)
+}
+
+const MISSING_REASON =
+	'This change touches the run tooling, and no interaction review is recorded for its issue — the pass that looks for the existing features a change breaks, which `/code-review` does not (joshuafolkken/kit#4276).'
+
+const REMEDY =
+	'Run it from `pnpm josh review:brief --interaction`, then record it with `pnpm josh review:record --interaction --issue <N> [<category>:<severity>:<file> ...]` — a clean pass is a call with no findings — and reissue the merge.'
+
+function refusal_message(issue: number): string {
+	return [MISSING_REASON, `Issue: ${session_cite.issue(issue)}`, REMEDY].join('\n')
+}
+
+// The merge gate's half: the refusal for a due change with no recorded pass, else `undefined`.
+async function refusal(issue: number, root?: string): Promise<string | undefined> {
+	return (await status(issue, root)) === 'missing' ? refusal_message(issue) : undefined
+}
+
+const review_interaction = {
+	brief_block,
+	due_paths,
+	NOT_DUE_LINE,
+	refusal,
+	refusal_message,
+	status,
+	status_of,
+}
+
+export type { InteractionStatus }
+export { review_interaction }

package/scripts/review/review-readers-scan.ts

@@ -0,0 +1,163 @@
+// The exported names a diff edits, read from one file's `git diff -U0` and its new text
+// (joshuafolkken/kit#4515). Pure: `review-untouched-readers.ts` reads the diff and searches each name.
+//
+// **A name is edited when a changed line falls inside its top-level declaration** — from the
+// declaration's first line to the line before the next one. Only a name another module can reach is
+// returned, spelled the way a reader writes it: a direct export as itself, a member of an exported
+// namespace object (`export { issue_merged }`) as `issue_merged.read_merged`. The namespace object
+// itself is skipped — a member added to it changes none of its readers.
+
+const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(?<start>\d+)(?:,(?<count>\d+))? @@/u
+const DECLARATION =
+	/^(?:export\s+)?(?:async\s+)?(?:function\*?|const|let|class|type|interface|enum)\s+(?<name>\w+)/u
+const EXPORT_LIST = /^export\s+(?:type\s+)?\{(?<names>[^}]*)\}/gmu
+const IDENTIFIER = /^(?:type\s+)?(?<name>\w+)/u
+const DIRECT_EXPORT = /^export\s/u
+const LIST_SEPARATOR = ','
+// A blank line or a comment line — `//`, `/*`, or a block comment's ` *` continuation.
+const PREAMBLE = /^(?:\s*$|\s*\/[/*]|\s+\*)/u
+// From a 1-based line number to the index of the line above it.
+const TWO = 2
+
+interface Declaration {
+	name: string
+	line: number
+	is_exported: boolean
+}
+
+interface Edited {
+	// The spelling a reader uses — `name` or `namespace.member`.
+	target: string
+	line: number
+}
+
+function to_range(start: number, count: number): Array<number> {
+	return Array.from({ length: count }, (_unused, offset) => start + offset)
+}
+
+// A pure deletion (`+c,0`) is placed on the line before it, which still lies inside the declaration
+// it was cut from.
+function hunk_lines(header: string): Array<number> {
+	const groups = HUNK_HEADER.exec(header)?.groups
+
+	if (groups === undefined) return []
+
+	const start = Number(groups['start'])
+	const count = groups['count'] === undefined ? 1 : Number(groups['count'])
+
+	return count === 0 ? [start] : to_range(start, count)
+}
+
+function changed_lines(diff: string): Array<number> {
+	return diff.split('\n').flatMap((line) => hunk_lines(line))
+}
+
+function to_declaration(text: string, index: number): Declaration | undefined {
+	const name = DECLARATION.exec(text)?.groups?.['name']
+
+	if (name === undefined) return undefined
+
+	return { name, line: index + 1, is_exported: DIRECT_EXPORT.test(text) }
+}
+
+function declarations(source: string): Array<Declaration> {
+	const found = source.split('\n').map((text, index) => to_declaration(text, index))
+
+	return found.filter((entry): entry is Declaration => entry !== undefined)
+}
+
+function first_identifier(entry: string): string | undefined {
+	return IDENTIFIER.exec(entry.trim())?.groups?.['name']
+}
+
+function list_names(list: string): Array<string> {
+	const names = list.split(LIST_SEPARATOR).map((entry) => first_identifier(entry))
+
+	return names.filter((name): name is string => name !== undefined)
+}
+
+function exported_names(source: string): Set<string> {
+	const lists = [...source.matchAll(EXPORT_LIST)].map((match) => match.groups?.['names'] ?? '')
+
+	return new Set(lists.flatMap((list) => list_names(list)))
+}
+
+// The members of `const <name> = { … }`, or `undefined` where `name` is not an object literal. `name`
+// is a `\w+` match, so it carries no pattern syntax.
+function namespace_members(source: string, name: string): Array<string> | undefined {
+	const literal = new RegExp(String.raw`^const\s+${name}\s*=\s*\{(?<body>[^}]*)\}`, 'mu')
+	const body = literal.exec(source)?.groups?.['body']
+
+	return body === undefined ? undefined : list_names(body)
+}
+
+function namespaces(source: string, exported: ReadonlySet<string>): Map<string, Array<string>> {
+	const entries = [...exported].map((name) => [name, namespace_members(source, name)] as const)
+
+	return new Map(
+		entries.filter((entry): entry is [string, Array<string>] => entry[1] !== undefined),
+	)
+}
+
+// The line after a declaration's own text: the next declaration's line, moved back past the blank and
+// comment lines that introduce it — a comment edited above `b` edits `b`, not the `a` before it.
+function range_end(texts: ReadonlyArray<string>, next: number | undefined): number {
+	if (next === undefined) return Infinity
+
+	let end = next
+
+	while (end > 1 && PREAMBLE.test(texts[end - TWO] ?? '')) end -= 1
+
+	return end
+}
+
+function touched(source: string, lines: ReadonlySet<number>): Array<Declaration> {
+	const found = declarations(source)
+	const texts = source.split('\n')
+
+	return found.filter((declaration, index) => {
+		const end = range_end(texts, found[index + 1]?.line)
+
+		return [...lines].some((line) => line >= declaration.line && line < end)
+	})
+}
+
+function namespace_of(
+	name: string,
+	spaces: ReadonlyMap<string, ReadonlyArray<string>>,
+): string | undefined {
+	return [...spaces].find(([, members]) => members.includes(name))?.[0]
+}
+
+interface ExportView {
+	exported: ReadonlySet<string>
+	spaces: ReadonlyMap<string, ReadonlyArray<string>>
+}
+
+function target_of(declaration: Declaration, view: ExportView): string | undefined {
+	const { name } = declaration
+
+	if (view.spaces.has(name)) return undefined
+	if (declaration.is_exported || view.exported.has(name)) return name
+
+	const space = namespace_of(name, view.spaces)
+
+	return space === undefined ? undefined : `${space}.${name}`
+}
+
+function edited(source: string, diff: string): Array<Edited> {
+	const exported = exported_names(source)
+	const view = { exported, spaces: namespaces(source, exported) }
+	const edited_declarations = touched(source, new Set(changed_lines(diff)))
+	const found_targets = edited_declarations.map((declaration) => ({
+		target: target_of(declaration, view),
+		line: declaration.line,
+	}))
+
+	return found_targets.filter((entry): entry is Edited => entry.target !== undefined)
+}
+
+const review_readers_scan = { changed_lines, edited }
+
+export type { Edited }
+export { review_readers_scan }