@joshuafolkken/kit 1.872.0

package/scripts/git/changed-file-scope.ts

@@ -0,0 +1,209 @@
+import path from 'node:path'
+import { changed_paths } from './changed-paths'
+import { git_command } from './git-command'
+
+// The narrowing every scoped re-check shares: which files a check was narrowed by, or why it could
+// not be narrowed at all.
+//
+// joshuafolkken/kit#1257 gave the unit suite this shape and joshuafolkken/kit#1298 gave lint the
+// same one. The two differ only in which extensions they can read and in the words they print;
+// everything else — where the changed files come from, dropping what the tree no longer holds,
+// telling an unreadable change list apart from one that narrowed to nothing, and listing what was
+// narrowed by — was identical, so it lives here once rather than in each command.
+//
+// **A narrowed run is added in front of the whole check, never in place of it.** Both fallbacks
+// therefore end at the whole check, and each says which of the two it was: the one thing this must
+// never do is answer "nothing to run" quietly.
+
+type ScopeMode = 'all' | 'related'
+
+interface ChangedFileScope {
+	mode: ScopeMode
+	files: ReadonlyArray<string>
+	reason: string
+}
+
+// What a scoped command prints around its decision. Kept as data so the shared branch below reads
+// the same for every command, and only the words differ.
+interface ScopeVocabulary {
+	label: string
+	fallback_suffix: string
+	narrowed_suffix: string
+}
+
+interface ScopeInputs {
+	is_present: (file_path: string) => boolean
+	is_selectable: (file_path: string) => boolean
+	nothing_reason: string
+}
+
+// Bundled rather than passed one by one: the resolution needs four inputs, and a fourth positional
+// parameter is where the project's own limit sits.
+interface ScopeRequest {
+	command_arguments: ReadonlyArray<string>
+	root: string
+	inputs: ScopeInputs
+}
+
+const UNREADABLE_REASON = 'the changed files could not be read'
+
+// Long enough to read a normal change at a glance, short enough that a branch-wide diff does not
+// bury the line that says what is about to run.
+const LISTED_FILE_LIMIT = 10
+
+// The root is resolved once and used for both the paths and the line that prints them: relativizing
+// the printed list against `process.cwd()` instead would name a file in this repository as
+// `../scripts/thing.ts` for anyone running from a subdirectory. Where git cannot answer, `cwd` is
+// the honest fallback — the reading below will fail too, and the run falls back to the whole check.
+async function repository_root_or_cwd(): Promise<string> {
+	try {
+		return await git_command.repository_root()
+	} catch {
+		return process.cwd()
+	}
+}
+
+// The same reading `josh review:level` and `josh review:brief` decide from — the
+// branch diff plus the untracked files — so what these commands narrow by is what those commands
+// call the change, rather than a further definition of it.
+//
+// **Paths are joined onto the repository root, never onto `process.cwd()`.** Both halves of that
+// reading print repository-root-relative paths, so a command typed in a subdirectory would
+// otherwise resolve every one of them to a file that does not exist, and the presence filter would
+// drop the whole set: a fall back to the whole check that looks exactly like a change with nothing
+// to narrow by.
+//
+// A failure answers `undefined` rather than an empty list: the two are opposite inputs to
+// `resolve_scope`, and only one of them means "could not tell".
+async function read_changed_files(root: string): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		const relative_paths = await changed_paths.read_changed_paths(false)
+
+		return relative_paths.map((relative) => path.join(root, relative))
+	} catch {
+		return undefined
+	}
+}
+
+// A path the change lists but the tree no longer holds — deleted, or renamed away — has nothing for
+// a check to read. Left in, it would count towards the narrowed set while contributing nothing to
+// it, which is how a run that checked zero files reports success.
+function select_files(
+	paths: ReadonlyArray<string>,
+	inputs: Pick<ScopeInputs, 'is_present' | 'is_selectable'>,
+): Array<string> {
+	return paths.filter(
+		(file_path) => inputs.is_selectable(file_path) && inputs.is_present(file_path),
+	)
+}
+
+function all_scope(reason: string): ChangedFileScope {
+	return { mode: 'all', files: [], reason }
+}
+
+// `undefined` and `[]` are deliberately different inputs. The first says the change could not be
+// read; the second says it was read and held nothing this check can narrow by.
+function resolve_scope(
+	paths: ReadonlyArray<string> | undefined,
+	inputs: ScopeInputs,
+): ChangedFileScope {
+	if (paths === undefined) return all_scope(UNREADABLE_REASON)
+
+	const files = select_files(paths, inputs)
+
+	if (files.length === 0) return all_scope(inputs.nothing_reason)
+
+	return { mode: 'related', files, reason: `${String(files.length)} changed file(s)` }
+}
+
+function format_file_list(files: ReadonlyArray<string>, root: string): string {
+	const listed = files.slice(0, LISTED_FILE_LIMIT).map((file) => `  - ${path.relative(root, file)}`)
+	const hidden = files.length - listed.length
+
+	if (hidden > 0) listed.push(`  … and ${String(hidden)} more`)
+
+	return listed.join('\n')
+}
+
+// What makes the narrowing readable rather than merely applied: the line names which branch was
+// taken, why, and — when it narrowed — every file it narrowed by.
+function describe_scope(
+	scope: ChangedFileScope,
+	root: string,
+	vocabulary: ScopeVocabulary,
+): string {
+	if (scope.mode === 'all') {
+		return `${vocabulary.label}: ${scope.reason} — ${vocabulary.fallback_suffix}.`
+	}
+
+	return `${vocabulary.label}: ${scope.reason} — ${vocabulary.narrowed_suffix}.\n${format_file_list(scope.files, root)}`
+}
+
+// `process.argv` is [runner, script, ...arguments].
+const ARGV_START = 2
+const FLAG_PREFIX = '-'
+
+function is_flag(argument: string): boolean {
+	return argument.startsWith(FLAG_PREFIX)
+}
+
+function explicit_files_of(command_arguments: ReadonlyArray<string>): Array<string> {
+	return command_arguments.filter((argument) => !is_flag(argument))
+}
+
+function flags_of(command_arguments: ReadonlyArray<string>): Array<string> {
+	return command_arguments.filter((argument) => is_flag(argument))
+}
+
+// Explicit file arguments win over the git reading, which is what makes the narrowing testable by
+// hand and usable from a hook that already knows which file it just wrote.
+async function resolve_command_scope(request: ScopeRequest): Promise<ChangedFileScope> {
+	const explicit_files = explicit_files_of(request.command_arguments)
+
+	if (explicit_files.length === 0) {
+		return resolve_scope(await read_changed_files(request.root), request.inputs)
+	}
+
+	return resolve_scope(
+		explicit_files.map((file) => path.resolve(file)),
+		request.inputs,
+	)
+}
+
+// A file the caller named by hand and this could not use is a mistake worth saying out loud. The
+// git-derived set falls back silently on purpose — a change with no file this check reads is
+// ordinary — but a typed path that resolves to nothing would otherwise be answered with a reason
+// describing a set the caller never handed over.
+function report_unusable_arguments(
+	command_arguments: ReadonlyArray<string>,
+	scope: ChangedFileScope,
+	label: string,
+): void {
+	const narrowed = new Set(scope.files)
+	const unusable = explicit_files_of(command_arguments).filter(
+		(file) => !narrowed.has(path.resolve(file)),
+	)
+
+	if (unusable.length === 0) return
+
+	process.stdout.write(`${label}: ignored — not a file this check reads: ${unusable.join(' ')}\n`)
+}
+
+const changed_file_scope = {
+	ARGV_START,
+	LISTED_FILE_LIMIT,
+	UNREADABLE_REASON,
+	describe_scope,
+	explicit_files_of,
+	flags_of,
+	is_flag,
+	read_changed_files,
+	report_unusable_arguments,
+	repository_root_or_cwd,
+	resolve_command_scope,
+	resolve_scope,
+	select_files,
+}
+
+export type { ChangedFileScope, ScopeInputs, ScopeMode, ScopeRequest, ScopeVocabulary }
+export { changed_file_scope }

package/scripts/git/changed-paths.ts

@@ -0,0 +1,30 @@
+import { git_command } from './git-command'
+
+// The set of changed paths a mechanical, path-driven decision is made from.
+//
+// `josh review:level` asks this same question of the same tree (which level to review at), and a
+// second copy would let a caller disagree about what "changed" means. joshuafolkken/kit#907: sharing
+// this reading is the moment it stopped being one command's private helper.
+
+function to_paths(raw: string): Array<string> {
+	return raw
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line !== '')
+}
+
+// The branch diff **plus** the untracked files. `git diff` lists neither, so a change that adds a
+// new module and edits one inert file looked like an inert-only change and was handed `low`. The
+// staged form needs no such addition: a file staged for addition is already in the cached diff.
+async function read_changed_paths(is_staged: boolean): Promise<Array<string>> {
+	if (is_staged) return to_paths(await git_command.diff_cached_names())
+
+	const tracked = to_paths(await git_command.diff_main_names())
+	const untracked = to_paths(await git_command.untracked_names())
+
+	return [...tracked, ...untracked]
+}
+
+const changed_paths = { read_changed_paths, to_paths }
+
+export { changed_paths }

package/scripts/git/constants.ts

@@ -0,0 +1,41 @@
+import { platform } from 'node:os'
+
+const REQUIRED_STATUS_LENGTH = 2
+const STAGED_STATUS_INDEX = 1
+const UNTRACKED_FILE_PREFIX = '??'
+const SEPARATOR_LINE = '────────────────────────────────────────'
+const GIT_COMMAND_UNIX = '/usr/bin/git'
+// git's machine-readable output, asked for by the readers that parse rather than display. It lives
+// here rather than beside either of them because `status` and `worktree_list` now sit in different
+// modules (joshuafolkken/kit#1640) and a copy in each is a second answer to one question.
+const PORCELAIN_FLAG = '--porcelain'
+
+function get_git_command(): string {
+	if (platform() === 'win32') {
+		return String.raw`"C:\Program Files\Git\cmd\git.exe"`
+	}
+
+	return GIT_COMMAND_UNIX
+}
+
+function get_git_command_for_spawn(): string {
+	if (platform() === 'win32') {
+		return String.raw`C:\Program Files\Git\cmd\git.exe`
+	}
+
+	return GIT_COMMAND_UNIX
+}
+
+const git_utilities = {
+	get_git_command,
+	get_git_command_for_spawn,
+}
+
+export {
+	REQUIRED_STATUS_LENGTH,
+	STAGED_STATUS_INDEX,
+	UNTRACKED_FILE_PREFIX,
+	SEPARATOR_LINE,
+	PORCELAIN_FLAG,
+	git_utilities,
+}

package/scripts/git/git-ai-review-scan.ts

@@ -0,0 +1,154 @@
+// cspell:words coderabbit coderabbitai
+
+type FindingKind = 'blocker' | 'info' | 'none'
+
+interface ReviewComment {
+	body: string
+	author_login: string
+	url: string | undefined
+}
+
+interface ClassifiedFinding {
+	author_login: string
+	url: string | undefined
+	summary: string
+	kind: FindingKind
+}
+
+interface ClassifiedFindings {
+	blockers: ReadonlyArray<ClassifiedFinding>
+	infos: ReadonlyArray<ClassifiedFinding>
+}
+
+const CLAUDE_AUTHORS: ReadonlySet<string> = new Set(['claude', 'claude[bot]'])
+const CODERABBIT_AUTHORS: ReadonlySet<string> = new Set(['coderabbitai', 'coderabbitai[bot]'])
+
+const CLAUDE_BLOCKER_HEADINGS: ReadonlyArray<RegExp> = [
+	/^#{2,4}\s+Issues\b/mu,
+	/^#{2,4}\s+Problem\b/mu,
+	/^#{3,4}\s+Logic bug\b/imu,
+	/^#{3,4}\s+\d+\.\s+/mu,
+]
+
+const CODERABBIT_ACTIONABLE_PATTERN = /Actionable comments posted:\s*(\d+)/iu
+const CODERABBIT_RATE_LIMIT_PATTERNS: ReadonlyArray<RegExp> = [
+	/rate limited by coderabbit\.ai/iu,
+	/Rate limit exceeded/iu,
+]
+
+const HEADING_PREFIX_PATTERN = /^#{2,4}\s+/u
+const NEWLINE_CHAR = '\n'
+const NOT_FOUND_INDEX = -1
+const EMPTY_COUNT = 0
+const CLAUDE_DEFAULT_SUMMARY = 'Claude Review finding'
+
+function is_claude_author(login: string): boolean {
+	return CLAUDE_AUTHORS.has(login)
+}
+
+function is_coderabbit_author(login: string): boolean {
+	return CODERABBIT_AUTHORS.has(login)
+}
+
+function is_claude_blocker(body: string): boolean {
+	return CLAUDE_BLOCKER_HEADINGS.some((pattern) => pattern.test(body))
+}
+
+function parse_coderabbit_actionable(body: string): number {
+	const match = CODERABBIT_ACTIONABLE_PATTERN.exec(body)
+	const raw = match?.[1]
+	if (raw === undefined) return EMPTY_COUNT
+	const count = Number(raw)
+
+	return Number.isFinite(count) ? count : EMPTY_COUNT
+}
+
+function is_coderabbit_rate_limit(body: string): boolean {
+	return CODERABBIT_RATE_LIMIT_PATTERNS.some((pattern) => pattern.test(body))
+}
+
+function slice_line_at(body: string, start_index: number): string {
+	const line_end = body.indexOf(NEWLINE_CHAR, start_index)
+
+	return line_end === NOT_FOUND_INDEX ? body.slice(start_index) : body.slice(start_index, line_end)
+}
+
+function extract_heading_text(body: string, pattern: RegExp): string | undefined {
+	const match = pattern.exec(body)
+	if (match === null) return undefined
+	const line = slice_line_at(body, match.index)
+
+	return line.replace(HEADING_PREFIX_PATTERN, '').trim()
+}
+
+function extract_blocker_heading(body: string): string {
+	for (const pattern of CLAUDE_BLOCKER_HEADINGS) {
+		const heading = extract_heading_text(body, pattern)
+		if (heading !== undefined) return heading
+	}
+
+	return ''
+}
+
+function build_none_finding(comment: ReviewComment): ClassifiedFinding {
+	return { author_login: comment.author_login, url: comment.url, kind: 'none', summary: '' }
+}
+
+function claude_summary(body: string): string {
+	const heading = extract_blocker_heading(body)
+
+	return heading.length > 0 ? heading : CLAUDE_DEFAULT_SUMMARY
+}
+
+function classify_claude_comment(comment: ReviewComment): ClassifiedFinding {
+	if (!is_claude_blocker(comment.body)) return build_none_finding(comment)
+
+	return {
+		author_login: comment.author_login,
+		url: comment.url,
+		kind: 'blocker',
+		summary: claude_summary(comment.body),
+	}
+}
+
+// Temporary (kit#753): CodeRabbit actionable comments are informational, never blockers, so a
+// slow CodeRabbit review cannot stall the merge gate. Revert together with kit#752.
+function build_coderabbit_info(comment: ReviewComment, count: number): ClassifiedFinding {
+	return {
+		author_login: comment.author_login,
+		url: comment.url,
+		kind: 'info',
+		summary: `CodeRabbit actionable comments posted: ${String(count)}`,
+	}
+}
+
+function classify_coderabbit_comment(comment: ReviewComment): ClassifiedFinding {
+	if (is_coderabbit_rate_limit(comment.body)) return build_none_finding(comment)
+	const count = parse_coderabbit_actionable(comment.body)
+	if (count === EMPTY_COUNT) return build_none_finding(comment)
+
+	return build_coderabbit_info(comment, count)
+}
+
+function classify_comment(comment: ReviewComment): ClassifiedFinding {
+	if (is_claude_author(comment.author_login)) return classify_claude_comment(comment)
+	if (is_coderabbit_author(comment.author_login)) return classify_coderabbit_comment(comment)
+
+	return build_none_finding(comment)
+}
+
+function classify_ai_review_comments(comments: ReadonlyArray<ReviewComment>): ClassifiedFindings {
+	const classified = comments.map((comment) => classify_comment(comment))
+
+	return {
+		blockers: classified.filter((entry) => entry.kind === 'blocker'),
+		infos: classified.filter((entry) => entry.kind === 'info'),
+	}
+}
+
+const git_ai_review_scan = {
+	classify_ai_review_comments,
+}
+
+export { git_ai_review_scan, classify_ai_review_comments }
+export type { ReviewComment, ClassifiedFinding, ClassifiedFindings, FindingKind }

package/scripts/git/git-animation.ts

@@ -0,0 +1,41 @@
+import ora, { type Ora } from 'ora'
+
+const SUCCESS_ICON = '✅'
+
+type AnimationStopFunction = (result?: string, icon?: string) => void
+
+interface AnimationController {
+	stop: AnimationStopFunction
+	pause: () => void
+}
+
+function create_stop_function(spinner: Ora, message: string): AnimationStopFunction {
+	return (result?: string, icon?: string) => {
+		if (result === undefined) {
+			spinner.stop()
+
+			return
+		}
+
+		const symbol = (icon ?? SUCCESS_ICON).trimEnd()
+
+		spinner.stopAndPersist({ symbol, text: `${message} ${result}` })
+	}
+}
+
+function create_animation(message: string): AnimationController {
+	const spinner = ora({ text: message }).start()
+
+	return {
+		stop: create_stop_function(spinner, message),
+		pause: () => {
+			spinner.stop()
+		},
+	}
+}
+
+const git_animation = {
+	create_animation,
+}
+
+export { git_animation }

package/scripts/git/git-branch.ts

@@ -0,0 +1,127 @@
+import {
+	animation_helpers,
+	create_git_operation_config,
+	type AnimationOptions,
+} from './animation-helpers'
+import { git_command } from './git-command'
+import { git_error } from './git-error'
+
+async function current(): Promise<string> {
+	const config: AnimationOptions<string> = {
+		error_message: 'Failed to get current branch',
+	}
+
+	return await animation_helpers.execute_with_animation(
+		'Getting current branch...',
+		git_command.branch,
+		config,
+	)
+}
+
+async function create(branch_name: string): Promise<void> {
+	const config = create_git_operation_config('Failed to create branch')
+
+	await animation_helpers.execute_with_animation(
+		`Creating branch: ${branch_name}...`,
+		async () => {
+			await git_command.checkout_b(branch_name)
+
+			return `Branch created: ${branch_name}`
+		},
+		config,
+	)
+}
+
+async function switch_to(branch_name: string): Promise<void> {
+	const config = create_git_operation_config('Failed to switch branch')
+
+	await animation_helpers.execute_with_animation(
+		`Switching to branch: ${branch_name}...`,
+		async () => {
+			await git_command.checkout(branch_name)
+
+			return `Switched to branch: ${branch_name}`
+		},
+		config,
+	)
+}
+
+async function exists(branch_name: string): Promise<boolean> {
+	const config: AnimationOptions<boolean> = {
+		error_message: 'Failed to check branch existence',
+		result_formatter: (is_exists: boolean) => (is_exists ? 'Exists' : 'Not found'),
+	}
+
+	return await animation_helpers.execute_with_animation(
+		'Checking if branch exists...',
+		async () => {
+			return await git_command.branch_exists(branch_name)
+		},
+		config,
+	)
+}
+
+async function pull_latest(): Promise<void> {
+	const config = create_git_operation_config('Failed to pull latest from remote')
+
+	await animation_helpers.execute_with_animation(
+		'Pulling latest from remote...',
+		async () => {
+			await git_command.pull_fast_forward()
+
+			return 'Pulled latest from remote'
+		},
+		config,
+	)
+}
+
+const ISSUE_PREFIX_PATTERN = /^\d+-/u
+
+function has_same_issue_prefix(branch_a: string, branch_b: string): boolean {
+	const prefix_a = ISSUE_PREFIX_PATTERN.exec(branch_a)?.[0]
+	const prefix_b = ISSUE_PREFIX_PATTERN.exec(branch_b)?.[0]
+
+	return prefix_a !== undefined && prefix_a === prefix_b
+}
+
+async function handle_default_branch(target_branch_name: string): Promise<void> {
+	await pull_latest()
+	const is_branch_exists: boolean = await exists(target_branch_name)
+
+	await (is_branch_exists ? switch_to : create)(target_branch_name)
+}
+
+async function check_and_create_branch(
+	current_branch: string,
+	target_branch_name: string,
+): Promise<string> {
+	const default_branch = await git_command.get_default_branch()
+
+	if (current_branch === default_branch) {
+		await handle_default_branch(target_branch_name)
+
+		return target_branch_name
+	}
+
+	if (current_branch !== target_branch_name) {
+		if (has_same_issue_prefix(current_branch, target_branch_name)) return current_branch
+
+		git_error.display_branch_mismatch_error(current_branch, target_branch_name)
+	}
+
+	return current_branch
+}
+
+const git_branch = {
+	current,
+	create,
+	switch_to,
+	exists,
+	check_and_create_branch,
+	// Exported so a lane's branch name can be checked against the real matcher rather than against a
+	// second copy of the pattern (joshuafolkken/kit#1497). A copy is what let `lane/<N>` ship: nothing
+	// asserted that the name `lane:open` writes is one this function accepts.
+	has_same_issue_prefix,
+}
+
+export { git_branch }