@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/gate/verification-inputs.ts

@@ -0,0 +1,250 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { lint_related_scope } from '#scripts/lint/lint-related-scope'
+import { gate_plan } from './gate-plan'
+import { input_fingerprint } from './input-fingerprint'
+import { toolchain_inputs } from './toolchain-inputs'
+
+// **What each verification depends on, declared once** (joshuafolkken/kit#4495). Every reuse of a
+// verdict — the whole gate (`gate-skip.ts`), one check (`check-reuse.ts`), a scoped record
+// (`scoped-green.ts`) and the since-green narrowing (`since-green.ts`) — answers from the declaration
+// here — the paths through `check-inputs.ts`, the tools and environment through `fingerprint` — so a
+// new reuse picks a declaration rather than writing its own invalidation.
+//
+// A declaration names:
+// - `is_input` — whether a path is a content input; `undefined` leaves it to `reads`.
+// - `reads` — `matched`: the inputs are the paths `is_input` accepts. `recorded`: the inputs are the
+//   files a run read, as the run recorded them — the test-read map (joshuafolkken/kit#4314), whose
+//   file digests are `input-fingerprint.ts`'s — so a path is an input only when some recorded test
+//   reads it.
+// - `is_config` — the files that configure the check: one that moves invalidates the verdict whatever
+//   else moved, and stops the since-green narrowing.
+// - `tools` — the packages whose installed version runs the check.
+// - `env` — the environment variables whose value changes the verdict.
+//
+// **A check with no declaration always runs**: `cspell` reads every text file and `behavior` reads a
+// transcript outside the tree. Naming inputs for either would be a guess, and a wrong guess is a check
+// reported green without having run. **The declarations over-approximate, never under**: a path in
+// doubt is an input. `metrics` reads the scripts it counts, the approvals under
+// `.josh/metrics-accepted/` (JSON) and the Markdown it measures (joshuafolkken/kit#4085). `lint` is
+// prettier plus eslint, so its inputs are the sources plus every file prettier formats, less what
+// prettier's own ignore files leave out — prettier answers that itself (`check-inputs.ts`).
+
+const GIT_IGNORE = '.gitignore'
+const PRETTIER_IGNORE = '.prettierignore'
+const PRETTIER_IGNORE_FILES = [GIT_IGNORE, PRETTIER_IGNORE] as const
+
+// A manifest or lock file moves the installed tools (`toolchain-inputs.ts`, the list every kept result
+// shares), and an ignore or editor file moves what prettier formats — a configuration of every
+// declared check.
+const MANIFEST = 'package.json'
+
+const TOOLCHAIN_FILES: ReadonlySet<string> = new Set([
+	...toolchain_inputs.PACKAGE_FILES.map((relative) => path.basename(relative)),
+	'.editorconfig',
+	...PRETTIER_IGNORE_FILES,
+])
+
+const PRETTIER_CONFIG_PREFIX = '.prettierrc'
+
+// A file name starting with one of these configures the TypeScript program a check compiles, and the
+// test runner for the unit step.
+const COMPILER_CONFIG_PREFIXES = ['tsconfig', 'svelte.config.'] as const
+const TEST_CONFIG_PREFIXES = [...COMPILER_CONFIG_PREFIXES, 'vitest.config.', 'vite.config.']
+
+// A file name starting with one of these, or a path under one of the directories, configures prettier,
+// eslint or the TypeScript program its type-aware rules read. Prettier keys its cache on the options
+// too, so a changed `prettier.config.*` re-checks every file the whole-tree run reads.
+const LINT_CONFIG_PREFIXES = ['eslint.config.', 'prettier.config.', ...COMPILER_CONFIG_PREFIXES]
+const LINT_CONFIG_DIRECTORIES: ReadonlySet<string> = new Set(['eslint', 'prettier', 'tsconfig'])
+
+const SOURCE_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.vue',
+	'.json',
+	'.jsonc',
+])
+
+const MARKDOWN_EXTENSION = '.md'
+// `NODE_OPTIONS` is left out: package managers and hooks set it differently around the same check,
+// and it tunes the runtime rather than what a check answers.
+const COMMON_ENV = ['NODE_ENV'] as const
+const ABSENT = 'absent'
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+// 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 FileTest = (relative: string, is_ignored: PrettierIgnored) => Promise<boolean>
+
+type InputReads = 'matched' | 'recorded'
+
+interface InputDeclaration {
+	readonly is_input: FileTest | undefined
+	readonly reads: InputReads
+	readonly is_config: (relative: string) => boolean
+	readonly tools: ReadonlyArray<string>
+	readonly env: ReadonlyArray<string>
+}
+
+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)
+}
+
+async function is_metrics_input(relative: string): Promise<boolean> {
+	return is_source(relative) || path.extname(relative) === MARKDOWN_EXTENSION
+}
+
+function configures_toolchain(relative: string): boolean {
+	const name = path.basename(relative)
+
+	return TOOLCHAIN_FILES.has(name) || name.startsWith(PRETTIER_CONFIG_PREFIX)
+}
+
+function names_any(relative: string, prefixes: ReadonlyArray<string>): boolean {
+	const name = path.basename(relative)
+
+	return configures_toolchain(relative) || prefixes.some((prefix) => name.startsWith(prefix))
+}
+
+function configures_compiler(relative: string): boolean {
+	return names_any(relative, COMPILER_CONFIG_PREFIXES)
+}
+
+function configures_tests(relative: string): boolean {
+	return names_any(relative, TEST_CONFIG_PREFIXES)
+}
+
+function configures_lint(relative: string): boolean {
+	const [top = ''] = relative.split('/', 1)
+
+	return LINT_CONFIG_DIRECTORIES.has(top) || names_any(relative, LINT_CONFIG_PREFIXES)
+}
+
+const LINT: InputDeclaration = {
+	is_input: is_lint_input,
+	reads: 'matched',
+	is_config: configures_lint,
+	tools: ['prettier', 'eslint', 'typescript'],
+	env: COMMON_ENV,
+}
+
+const UNIT: InputDeclaration = {
+	is_input: undefined,
+	reads: 'recorded',
+	is_config: configures_tests,
+	tools: ['vitest', 'typescript'],
+	env: [...COMMON_ENV, 'TZ'],
+}
+
+function compiled(is_input: FileTest): InputDeclaration {
+	return {
+		is_input,
+		reads: 'matched',
+		is_config: configures_compiler,
+		tools: ['typescript'],
+		env: COMMON_ENV,
+	}
+}
+
+const DECLARATIONS: ReadonlyMap<string, InputDeclaration> = new Map([
+	[gate_plan.LINT_LABEL, LINT],
+	[gate_plan.TYPE_CHECK_LABEL, compiled(is_source_input)],
+	[gate_plan.EXPORTS_LABEL, compiled(is_source_input)],
+	[gate_plan.METRICS_LABEL, compiled(is_metrics_input)],
+	[gate_plan.UNIT_LABEL, UNIT],
+])
+
+function declaration_of(label: string): InputDeclaration | undefined {
+	return DECLARATIONS.get(label)
+}
+
+function is_declared(label: string): boolean {
+	return DECLARATIONS.has(label)
+}
+
+// Whether any of `relatives` (repository-root relative) configures the check `label` — `true` for an
+// undeclared one, which no narrowing can read past.
+function configures(label: string, relatives: ReadonlyArray<string>): boolean {
+	const declaration = DECLARATIONS.get(label)
+
+	return declaration === undefined || relatives.some((relative) => declaration.is_config(relative))
+}
+
+function tool_version(root: string, tool: string): string {
+	try {
+		const manifest: unknown = JSON.parse(
+			readFileSync(path.join(root, 'node_modules', tool, MANIFEST), 'utf8'),
+		)
+
+		return typeof manifest === 'object' && manifest !== null && 'version' in manifest
+			? String(manifest.version)
+			: ABSENT
+	} catch {
+		return ABSENT
+	}
+}
+
+function entries_of(
+	declaration: InputDeclaration,
+	root: string,
+	environment: Environment,
+): ReadonlyArray<string> {
+	return [
+		...declaration.tools.map((tool) => `tool:${tool}=${tool_version(root, tool)}`),
+		...declaration.env.map((name) => `env:${name}=${environment[name] ?? ABSENT}`),
+	]
+}
+
+// **The fingerprint of what the checks `labels` read beside the files**: the installed version of every
+// declared tool and the value of every declared environment variable, sorted into one digest. The
+// file contents are the record's own file map (`file-map-stamp.ts`) and the merge base its `base`, so a
+// reuse matches all three. One label answers a check's record; every declared label the whole gate's.
+function fingerprint(
+	labels: ReadonlyArray<string>,
+	root: string = PROJECT_ROOT,
+	environment: Environment = process.env,
+): string {
+	const declarations = labels.flatMap((label) => DECLARATIONS.get(label) ?? [])
+	const entries = new Set(
+		declarations.flatMap((declaration) => entries_of(declaration, root, environment)),
+	)
+
+	return input_fingerprint.of_entries(entries)
+}
+
+const DECLARED_LABELS: ReadonlyArray<string> = [...DECLARATIONS.keys()]
+
+const verification_inputs = {
+	configures,
+	declaration_of,
+	DECLARED_LABELS,
+	fingerprint,
+	is_declared,
+	PRETTIER_IGNORE_FILES,
+}
+
+export type { InputDeclaration, InputReads, PrettierIgnored }
+export { verification_inputs }

package/scripts/gh/gh-author-association.ts

@@ -1,14 +1,101 @@
-// Whose words kit acts on: the `author_association` REST reports with an issue or a comment, and the
-// ones that can write to the repository. On a public repository anyone can file an issue or comment,
-// so a body kit runs (`josh measure:rerun`) or copies into the ledger (`review:record`) is taken only
-// from an author with write access — and an unknown author is not a trusted one.
-const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
-const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
 
-function is_trusted(association: string | null | undefined): boolean {
-	return typeof association === 'string' && TRUSTED_ASSOCIATIONS.has(association)
+// Whose words kit acts on: the author of an issue or a comment who can write to the repository. On a
+// public repository anyone can file an issue or comment, so a body kit runs (`josh measure:rerun`) or
+// copies into the ledger (`review:record`) is taken only from an author with write access — and an
+// unknown author is not a trusted one.
+//
+// **`author_association` alone does not say "can write"** (joshuafolkken/kit#4037). `OWNER` does, so it
+// is trusted without a request. `MEMBER` is any member of the owning org, whatever their access to this
+// repository, and `COLLABORATOR` includes outside collaborators with read or triage access only — so
+// those two are asked of the collaborator-permission endpoint, once per login per process, and trusted
+// only on a write role. A lookup that fails is not trust.
+const OWNER = 'OWNER'
+const ASKED_ASSOCIATIONS: ReadonlySet<string> = new Set(['MEMBER', 'COLLABORATOR'])
+const WRITE_ROLES: ReadonlySet<string> = new Set(['admin', 'maintain', 'write'])
+// A GitHub user login, an Enterprise Managed User's `name_shortcode` included — it is placed in a REST
+// path, so anything else (a `[bot]` login, a slash) is refused before a request is made.
+const LOGIN_PATTERN = /^[\da-z](?:[\w-]*[\da-z])?$/iu
+const TRUSTED_LIST = 'OWNER, or MEMBER / COLLABORATOR with write access'
+
+const permission_schema = z.looseObject({
+	permission: z.string().nullish(),
+	role_name: z.string().nullish(),
+})
+
+// `timeout_ms` bounds the lookup for a caller inside a hook's own timeout (`issue-watch`).
+interface Author {
+	login: string | undefined
+	association: string | null | undefined
+	timeout_ms?: number | undefined
+}
+
+const answers = new Map<string, Promise<boolean | undefined>>()
+
+function permission_path(login: string): string {
+	return `${git_gh_api_path.repo_api_path()}/collaborators/${login}/permission`
+}
+
+// `role_name` names `maintain` exactly; `permission` folds it into `write`, so either answers.
+function has_write_role(raw: string): boolean {
+	const parsed = parse_json.parse_json_object_or_undefined(raw, permission_schema)
+	const roles = [parsed?.role_name, parsed?.permission]
+
+	return roles.some((role) => typeof role === 'string' && WRITE_ROLES.has(role))
+}
+
+// `undefined` for a lookup that failed, which is not an answer.
+async function ask_permission(login: string, timeout_ms?: number): Promise<boolean | undefined> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({ path: permission_path(login), timeout_ms })
+
+		return has_write_role(raw)
+	} catch {
+		return undefined
+	}
+}
+
+// A failed lookup is not remembered: the backlog driver keeps one process for hours, so one dropped
+// request would otherwise leave that author unanswered until it restarts. Only the caller's own
+// request is evicted, never a newer one another caller has stored since.
+async function can_write(login: string, timeout_ms?: number): Promise<boolean | undefined> {
+	const asked = answers.get(login) ?? ask_permission(login, timeout_ms)
+
+	answers.set(login, asked)
+
+	const has_write = await asked
+
+	if (has_write === undefined && answers.get(login) === asked) answers.delete(login)
+
+	return has_write
+}
+
+function is_user_login(login: string | undefined): login is string {
+	return login !== undefined && LOGIN_PATTERN.test(login)
+}
+
+function is_asked(author: Author): boolean {
+	return ASKED_ASSOCIATIONS.has(author.association ?? '') && is_user_login(author.login)
+}
+
+// `undefined` when the lookup failed: neither trusted nor refused, for a caller that must not settle a
+// permanent answer on it (`review-comment-round`).
+async function trust_of(author: Author): Promise<boolean | undefined> {
+	if (author.association === OWNER) return true
+	if (author.login === undefined || !is_asked(author)) return false
+
+	return await can_write(author.login, author.timeout_ms)
+}
+
+// A lookup that failed is not trust.
+async function is_trusted(author: Author): Promise<boolean> {
+	return (await trust_of(author)) === true
 }
 
-const gh_author_association = { TRUSTED_LIST, is_trusted }
+const gh_author_association = { TRUSTED_LIST, is_trusted, trust_of }
 
+export type { Author }
 export { gh_author_association }

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

@@ -20,8 +20,10 @@ interface ClassifiedFindings {
 	infos: ReadonlyArray<ClassifiedFinding>
 }
 
-const CLAUDE_AUTHORS: ReadonlySet<string> = new Set(['claude', 'claude[bot]'])
-const CODERABBIT_AUTHORS: ReadonlySet<string> = new Set(['coderabbitai', 'coderabbitai[bot]'])
+// Only the app accounts (`type: Bot`): a bare `claude` / `coderabbitai` is an ordinary user login
+// anyone could register, and its comment is not an AI review.
+const CLAUDE_AUTHORS: ReadonlySet<string> = new Set(['claude[bot]'])
+const CODERABBIT_AUTHORS: ReadonlySet<string> = new Set(['coderabbitai[bot]'])
 
 const CLAUDE_BLOCKER_HEADINGS: ReadonlyArray<RegExp> = [
 	/^#{2,4}\s+Issues\b/mu,

package/scripts/gh/git-gh-api-path.ts

@@ -28,6 +28,13 @@ function issue_api_path(issue_number: string, repo?: string): string {
 	return `${issues_api_path(repo)}/${issue_number}`
 }
 
+// One issue's labels — a pull request is an issue to this endpoint. Named here because the label
+// writes and reads in `git-gh-issue-write.ts` and the CI classification read in `pr-classification.ts`
+// all address it.
+function issue_labels_api_path(issue_number: string, repo?: string): string {
+	return `${issue_api_path(issue_number, repo)}/labels`
+}
+
 // The dependency relations, which REST serves from their own endpoint rather than inside the issue.
 // Named here because three call sites address it — the read in `git-gh-issue-read.ts` and both
 // writes in `git-gh-issue-write.ts`.
@@ -90,6 +97,12 @@ function commit_status_api_path(commit_sha: string, repo?: string): string {
 	return `${commit_api_path(commit_sha, repo)}/status`
 }
 
+// The rules that apply to one branch, from every ruleset that targets it — readable without the
+// admin access the classic branch protection endpoint needs.
+function branch_rules_api_path(branch_name: string, repo?: string): string {
+	return `${repo_api_path(repo)}/rules/branches/${branch_name}`
+}
+
 // A single tag reference. REST answers 404 when the tag does not exist, which is the whole of the
 // question the release command's tag watch asks.
 function tag_reference_api_path(tag: string, repo?: string): string {
@@ -109,6 +122,7 @@ const git_gh_api_path = {
 	release_by_tag_api_path,
 	issues_api_path,
 	issue_api_path,
+	issue_labels_api_path,
 	blocked_by_api_path,
 	issue_comments_api_path,
 	pulls_api_path,
@@ -119,6 +133,7 @@ const git_gh_api_path = {
 	commit_api_path,
 	commit_check_runs_api_path,
 	commit_status_api_path,
+	branch_rules_api_path,
 }
 
 export { git_gh_api_path, FULL_PAGE_QUERY }

package/scripts/gh/git-gh-branch-rules.ts

@@ -0,0 +1,73 @@
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+
+// The status check contexts the base branch's rules require, which is what lets the merge gate tell
+// a pull request held only by a slow optional check — GitHub's default-setup `CodeQL` — from one
+// still waiting on a check that guards the merge (joshuafolkken/kit#4351).
+//
+// **An empty answer keeps the gate strict, so every gap folds into it.** With no required context
+// known, `git-pr-checks-eval.ts` waits for `CLEAN` exactly as it did before, so a repository with no
+// ruleset, a token the endpoint answers 403 to, or a rate limit costs the wait time it always did and
+// never a merge past a check nobody declared optional.
+
+const REQUIRED_STATUS_CHECKS_RULE = 'required_status_checks'
+
+const required_check_schema = z.looseObject({ context: z.string() })
+
+const rule_parameters_schema = z.looseObject({
+	required_status_checks: z.array(required_check_schema).optional(),
+})
+
+const branch_rule_schema = z.looseObject({
+	type: z.string(),
+	parameters: rule_parameters_schema.nullish(),
+})
+
+type BranchRule = z.infer<typeof branch_rule_schema>
+
+// A branch's rules do not change while one command waits on a pull request, so a read is remembered
+// for the life of the command; one that failed is not, and the next poll asks again.
+const required_contexts_by_branch = new Map<string, Array<string>>()
+
+function forget_branch_rules(): void {
+	required_contexts_by_branch.clear()
+}
+
+function to_required_contexts(rules: ReadonlyArray<BranchRule>): Array<string> {
+	return rules
+		.filter((rule) => rule.type === REQUIRED_STATUS_CHECKS_RULE)
+		.flatMap((rule) => rule.parameters?.required_status_checks ?? [])
+		.map((check) => check.context)
+}
+
+async function fetch_required_contexts(branch_name: string): Promise<Array<string> | undefined> {
+	const raw_json = await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.branch_rules_api_path(branch_name)}${FULL_PAGE_QUERY}`,
+		should_paginate: true,
+	})
+	const rules = parse_json_array_or_undefined(raw_json, branch_rule_schema)
+
+	return rules === undefined ? undefined : to_required_contexts(rules)
+}
+
+async function read_required_contexts(branch_name: string | undefined): Promise<Array<string>> {
+	if (branch_name === undefined) return []
+	const cached = required_contexts_by_branch.get(branch_name)
+	if (cached !== undefined) return cached
+
+	try {
+		const contexts = await fetch_required_contexts(branch_name)
+		if (contexts === undefined) return []
+		required_contexts_by_branch.set(branch_name, contexts)
+
+		return contexts
+	} catch {
+		return []
+	}
+}
+
+const git_gh_branch_rules = { read_required_contexts }
+
+export { git_gh_branch_rules, read_required_contexts, forget_branch_rules }

package/scripts/gh/git-gh-conditional.ts

@@ -19,7 +19,8 @@ const ETAG_HEADER = /^etag: *(?<etag>[^\r\n]+)/imu
 type ConditionalRead =
 	| { kind: 'unchanged' }
 	| { kind: 'changed'; etag: string | undefined; body: string }
-	| { kind: 'unreadable' }
+	// `cause` is gh's own failure where there was one, for a caller that reports it.
+	| { kind: 'unreadable'; cause?: unknown }
 
 const UNCHANGED: ConditionalRead = { kind: 'unchanged' }
 const UNREADABLE: ConditionalRead = { kind: 'unreadable' }
@@ -56,7 +57,9 @@ async function read_conditional(
 	try {
 		return to_read(await git_gh_exec.exec_gh_command(to_args(path, etag), timeout_ms))
 	} catch (error) {
-		return failure_status(error) === NOT_MODIFIED_STATUS ? UNCHANGED : UNREADABLE
+		return failure_status(error) === NOT_MODIFIED_STATUS
+			? UNCHANGED
+			: { kind: 'unreadable', cause: error }
 	}
 }
 

package/scripts/gh/git-gh-issue-read.ts

@@ -281,7 +281,11 @@ async function issue_view_json(
 // `repo` reads a child in another repository. Cross-repository children are read this way rather
 // than from a local checkout: their state is a GitHub fact, and requiring a clone to learn it is
 // what kept the auto-close from ever running on such an epic.
-const STATE_AND_RELATIONS_FIELDS = 'number,state,labels,blockedBy'
+//
+// `body` rides along because `epic:next` holds a child until its declared start time
+// (joshuafolkken/kit#4007); the REST issue endpoint answers it in the same response, so it costs no
+// request.
+const STATE_AND_RELATIONS_FIELDS = 'number,state,labels,blockedBy,body'
 
 async function issue_get_state_and_relations(
 	issue_number: string,