@joshuafolkken/kit 1.872.0

package/scripts/sonar/sonar-hotspots-cli.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env tsx
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+import { managed_config_scope } from '#scripts/sync/managed-config-scope'
+import { z } from 'zod'
+import {
+	sonar_hotspots,
+	type ClassifiedHotspot,
+	type HotspotDisposition,
+	type HotspotFetch,
+} from './sonar-hotspots'
+
+// `josh sonar:hotspots <PR>` — fetch the SonarCloud hotspots on a pull request and print the Step B
+// disposition of each (joshuafolkken/kit#2182).
+//
+// The decision itself lives in `sonar-hotspots.ts`; this file is the I/O around it: read the project
+// key from `sonar-project.properties`, fetch the public search API, and answer the upstream-synced
+// axis with `sync:scope`'s own detection — `managed_config_scope.has_managed_path`, so no
+// distribution path list is copied here. A read that fails is printed as `unreadable`, told apart
+// from a success that found no hotspots.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh sonar:hotspots <PR>'
+const SONAR_HOST = 'https://sonarcloud.io'
+const HOTSPOTS_PATH = '/api/hotspots/search'
+const PROPERTIES_FILE = 'sonar-project.properties'
+const PROJECT_KEY_PREFIX = 'sonar.projectKey='
+const FETCH_TIMEOUT_MS = 10_000
+const FAILURE_EXIT_CODE = 1
+const UNKNOWN_LINE = '?'
+
+// `looseObject` so a field SonarCloud adds later does not fail the parse; only the fields the
+// disposition reads are declared. `ruleKey` keeps the API's own spelling.
+const hotspot_schema = z.looseObject({
+	key: z.string(),
+	status: z.string(),
+	component: z.string(),
+	line: z.number().optional(),
+	ruleKey: z.string(),
+	resolution: z.string().optional(),
+})
+const response_schema = z.looseObject({ hotspots: z.array(hotspot_schema).optional() })
+
+function read_project_key(root: string): string | undefined {
+	const file = path.join(root, PROPERTIES_FILE)
+	if (!existsSync(file)) return undefined
+
+	const line = readFileSync(file, 'utf8')
+		.split('\n')
+		.find((entry) => entry.startsWith(PROJECT_KEY_PREFIX))
+
+	return line?.slice(PROJECT_KEY_PREFIX.length).trim()
+}
+
+function hotspots_url(project_key: string, pull_request: string): string {
+	const query = new URLSearchParams({ projectKey: project_key, pullRequest: pull_request })
+
+	return `${SONAR_HOST}${HOTSPOTS_PATH}?${query.toString()}`
+}
+
+async function fetch_hotspots(url: string): Promise<HotspotFetch> {
+	try {
+		const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+		if (!response.ok) return { error: `HTTP ${String(response.status)}` }
+
+		const parsed = response_schema.parse(await response.json())
+
+		return { hotspots: parsed.hotspots ?? [] }
+	} catch (error) {
+		return { error: error instanceof Error ? error.message : String(error) }
+	}
+}
+
+function is_managed(component: string): boolean {
+	return managed_config_scope.has_managed_path([sonar_hotspots.component_path(component)])
+}
+
+function format_hotspot(entry: ClassifiedHotspot): string {
+	const { hotspot, branch } = entry
+	const line = hotspot.line === undefined ? UNKNOWN_LINE : String(hotspot.line)
+
+	return `${hotspot.status}\t${hotspot.component}:${line}\t${hotspot.ruleKey}\t→ ${branch}`
+}
+
+function print_disposition(disposition: HotspotDisposition): void {
+	if ('unreadable' in disposition) {
+		console.info(`${sonar_hotspots.UNREADABLE}: ${disposition.unreadable}`)
+
+		return
+	}
+
+	if (disposition.classified.length === 0) {
+		console.info('no hotspots on this pull request')
+
+		return
+	}
+
+	for (const entry of disposition.classified) console.info(format_hotspot(entry))
+}
+
+async function fetch_and_print(project_key: string, pull_request: string): Promise<void> {
+	const fetched = await fetch_hotspots(hotspots_url(project_key, pull_request))
+
+	print_disposition(sonar_hotspots.classify_fetch(fetched, is_managed))
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [pull_request] = argv
+
+	if (pull_request === undefined || pull_request.startsWith('-')) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const project_key = read_project_key(await git_command.repository_root())
+
+	if (project_key === undefined) {
+		console.error(`no ${PROJECT_KEY_PREFIX} found in ${PROPERTIES_FILE}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	await fetch_and_print(project_key, pull_request)
+
+	return 0
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const sonar_hotspots_cli = {
+	fetch_hotspots,
+	format_hotspot,
+	hotspots_url,
+	is_managed,
+	main,
+	print_disposition,
+	read_project_key,
+	run,
+	USAGE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { sonar_hotspots_cli }

package/scripts/sonar/sonar-hotspots.ts

@@ -0,0 +1,111 @@
+// The Step B disposition for each SonarCloud hotspot on a pull request, computed rather than read by
+// eye (joshuafolkken/kit#2182).
+//
+// `prompts/sonar-hotspot-handling.md` carried Step A and Step B as prose: the reader built the API
+// URL by hand and then walked a decision table whose one mechanical branch key — "is this path
+// upstream-synced?" — is already answered by `josh sync:scope`. This module is the conversion the
+// table describes, so the only judgement left in prose is "is a TO_REVIEW hotspot really a false
+// positive?".
+//
+// The upstream-synced axis is not re-derived here. The CLI passes an `is_managed` predicate built on
+// `managed_config_scope.has_managed_path` — the same detection `josh sync:scope` runs — so no
+// distribution path list is copied into this file.
+
+// A hotspot needing review is a candidate suppression: on an upstream-synced path the suppression
+// belongs in `sonar-project.properties` (`excluded`), on project-local code it is a local ignore
+// (`local`). A hotspot SonarCloud has already reviewed carries its own resolution — a fixed one
+// records a real issue (`fix`), any other resolved state is set aside (`defer`).
+const EXCLUDED_BRANCH = 'excluded'
+const LOCAL_BRANCH = 'local'
+const FIX_BRANCH = 'fix'
+const DEFER_BRANCH = 'defer'
+
+// The fetch could not be read at all — rate-limited, offline, or a non-OK response. Named alongside
+// the four branches so a caller cannot mistake a failed read for "no hotspots" (an empty success).
+const UNREADABLE = 'unreadable'
+
+const HOTSPOT_BRANCHES = [EXCLUDED_BRANCH, LOCAL_BRANCH, FIX_BRANCH, DEFER_BRANCH] as const
+
+type HotspotBranch = (typeof HOTSPOT_BRANCHES)[number]
+
+const TO_REVIEW_STATUS = 'TO_REVIEW'
+const FIXED_RESOLUTION = 'FIXED'
+
+// One hotspot as the public search API returns it. `component` is the SonarCloud component key
+// (`<projectKey>:<path>`), not a bare path, so `component_path` strips the prefix before the managed
+// check reads it.
+// The optional fields carry `| undefined` explicitly: under `exactOptionalPropertyTypes` that is what
+// lets the zod-parsed shape (`z.number().optional()` → `number | undefined`) assign to this type.
+interface Hotspot {
+	key: string
+	status: string
+	component: string
+	line?: number | undefined
+	ruleKey: string
+	resolution?: string | undefined
+}
+
+// The fetch outcome: the hotspots on success, or the reason the read failed. A discriminated union so
+// the unreadable case is a value the caller handles, never an empty array it silently treats as clean.
+type HotspotFetch = { hotspots: ReadonlyArray<Hotspot> } | { error: string }
+
+interface ClassifiedHotspot {
+	hotspot: Hotspot
+	branch: HotspotBranch
+}
+
+// The result of converting a whole fetch: one classified hotspot per entry, or the unreadable marker
+// carrying the failure reason.
+type HotspotDisposition = { classified: ReadonlyArray<ClassifiedHotspot> } | { unreadable: string }
+
+// The repository-root-relative path a managed check reads. A SonarCloud component key is
+// `<projectKey>:<path>`; a key with no colon (some API shapes) is already the path.
+function component_path(component: string): string {
+	const separator_index = component.indexOf(':')
+
+	return separator_index === -1 ? component : component.slice(separator_index + 1)
+}
+
+function classify_hotspot(hotspot: Hotspot, is_managed: boolean): HotspotBranch {
+	if (hotspot.status === TO_REVIEW_STATUS) return is_managed ? EXCLUDED_BRANCH : LOCAL_BRANCH
+
+	return hotspot.resolution === FIXED_RESOLUTION ? FIX_BRANCH : DEFER_BRANCH
+}
+
+function classify_one(
+	hotspot: Hotspot,
+	is_managed: (component: string) => boolean,
+): ClassifiedHotspot {
+	return { hotspot, branch: classify_hotspot(hotspot, is_managed(hotspot.component)) }
+}
+
+// The conversion the whole command exists to perform: a fetch outcome becomes either a disposition
+// per hotspot or the unreadable marker. `is_managed` answers the upstream-synced axis for a component
+// key — the CLI builds it on `sync:scope`'s own detection.
+function classify_fetch(
+	fetch: HotspotFetch,
+	is_managed: (component: string) => boolean,
+): HotspotDisposition {
+	if ('error' in fetch) return { unreadable: fetch.error }
+
+	return { classified: fetch.hotspots.map((hotspot) => classify_one(hotspot, is_managed)) }
+}
+
+const sonar_hotspots = {
+	classify_fetch,
+	classify_hotspot,
+	component_path,
+	HOTSPOT_BRANCHES,
+	UNREADABLE,
+}
+
+export {
+	sonar_hotspots,
+	EXCLUDED_BRANCH,
+	LOCAL_BRANCH,
+	FIX_BRANCH,
+	DEFER_BRANCH,
+	UNREADABLE,
+	HOTSPOT_BRANCHES,
+}
+export type { ClassifiedHotspot, Hotspot, HotspotBranch, HotspotDisposition, HotspotFetch }

package/scripts/split/split-assess-cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+import { path_decision } from '#scripts/josh/path-decision'
+import { split_assess } from './split-assess'
+
+// `josh split:assess` — measure a branch's change size, tests excluded, and answer the size question
+// of the split assessment (joshuafolkken/kit#2218).
+//
+// A command rather than a paragraph for the reason every decision oracle is one: the "about 10 files /
+// 400 lines" guide is a number, but the size behind it was estimated by eye, so no data ever
+// accumulated to test the guide against. This counts the real diff after the fact, and answers
+// `split` / `single` on size alone — separability stays a judgement, said so in the reason line.
+// The question and the counting live in `split-assess.ts`; everything here is the invocation.
+
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh split:assess [--json]'
+const JSON_KEY = 'split'
+const FAILURE_EXIT_CODE = 1
+
+function parse_is_json(argv: ReadonlyArray<string>): boolean | undefined {
+	if (path_decision.has_unknown_flag(argv, [path_decision.JSON_FLAG])) return undefined
+
+	return argv.includes(path_decision.JSON_FLAG)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const is_json = parse_is_json(argv)
+
+	if (is_json === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const measurement = split_assess.assess(await git_command.diff_main_numstat())
+	const reason = split_assess.reason(measurement)
+
+	path_decision.print_decision(JSON_KEY, measurement.verdict, reason, is_json)
+
+	return 0
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const split_assess_cli = { JSON_KEY, USAGE, main, parse_is_json, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { split_assess_cli }

package/scripts/split/split-assess.ts

@@ -0,0 +1,124 @@
+import { test_declared_logic } from '#scripts/test/test-declared-logic'
+
+// The size half of the split assessment, measured rather than estimated (joshuafolkken/kit#2218).
+//
+// `split-assessment.md` → "The question" asks two things, and only the second is mechanical: does the
+// change **clearly exceed** what one verification gate confirms in one pass, the guide being about 10
+// changed files and about 400 changed lines, test files excluded. The first — are there two or more
+// separately-mergeable deliverables — stays a judgement, so this answers the size question alone and
+// never claims to have decided the split.
+//
+// **The counting excludes test files, single-sourced from `test_declared_logic.is_test_file`.** The
+// "test files excluded" clause in the guide and the `*.test.ts` / `*.e2e.ts` spelling are one fact;
+// a second copy here would let the two drift.
+
+type SplitVerdict = 'split' | 'single'
+
+// One file's contribution to the change size: its path, and the lines it added plus the lines it
+// removed. A binary file, which `git diff --numstat` prints as `-`, contributes zero changed lines.
+interface FileChange {
+	path: string
+	changed_lines: number
+}
+
+interface SizeMeasurement {
+	files: number
+	lines: number
+	verdict: SplitVerdict
+}
+
+// The guide from `split-assessment.md`. Strictly greater than: "about 10 changed files" and a change
+// that "lands at 11 files is not thereby a split" put the bar above the round number, not at it.
+const FILE_GUIDE = 10
+const LINE_GUIDE = 400
+
+const SPLIT_VERDICT: SplitVerdict = 'split'
+const SINGLE_VERDICT: SplitVerdict = 'single'
+
+const BINARY_MARKER = '-'
+const NUMSTAT_FIELDS = 3
+
+// A `-` count (binary file), or a missing field, reads as zero; anything else is coerced to a
+// number, and an unparseable field also reads as zero rather than throwing on a row this was not
+// meant to size.
+function parse_count(field: string | undefined): number {
+	if (field === undefined || field === BINARY_MARKER) return 0
+
+	const value = Number(field)
+
+	return Number.isNaN(value) ? 0 : value
+}
+
+// One `added\tdeleted\tpath` row into a `FileChange`, or `undefined` for a row that is not one.
+function parse_row(row: string): FileChange | undefined {
+	const fields = row.split('\t')
+
+	if (fields.length < NUMSTAT_FIELDS) return undefined
+
+	const [added, deleted, ...path_parts] = fields
+
+	return { path: path_parts.join('\t'), changed_lines: parse_count(added) + parse_count(deleted) }
+}
+
+// The raw stdout of `git diff --numstat` into the changes it lists.
+function parse_numstat(raw: string): Array<FileChange> {
+	return raw
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line !== '')
+		.map((row) => parse_row(row))
+		.filter((change): change is FileChange => change !== undefined)
+}
+
+function non_test_changes(changes: ReadonlyArray<FileChange>): Array<FileChange> {
+	return changes.filter((change) => !test_declared_logic.is_test_file(change.path))
+}
+
+// `split` only when **both** guides are exceeded together — the size condition a split has to clear,
+// per `split-assessment.md`'s conservative default. Either one alone leaves the change one Issue.
+function verdict_for(files: number, lines: number): SplitVerdict {
+	return files > FILE_GUIDE && lines > LINE_GUIDE ? SPLIT_VERDICT : SINGLE_VERDICT
+}
+
+function measure(changes: ReadonlyArray<FileChange>): SizeMeasurement {
+	const runtime = non_test_changes(changes)
+	const lines = runtime.reduce((total, change) => total + change.changed_lines, 0)
+
+	return { files: runtime.length, lines, verdict: verdict_for(runtime.length, lines) }
+}
+
+// The size measurement of a raw `git diff --numstat`, the one call the CLI makes.
+function assess(raw: string): SizeMeasurement {
+	return measure(parse_numstat(raw))
+}
+
+const SPLIT_TAIL =
+	'both exceed the guide — the size condition for a split is met (separability is a separate judgement)'
+const SINGLE_TAIL = 'under the guide on at least one axis — one Issue, however separable'
+
+// The sentence printed on stderr: what was counted, against which guide, and what the verdict does
+// and does not mean. Test files are already dropped from the counts, so the reason says so.
+function reason(measurement: SizeMeasurement): string {
+	const counted = `${String(measurement.files)} changed file(s), ${String(measurement.lines)} changed line(s), tests excluded`
+	const guide = `guide ${String(FILE_GUIDE)} files / ${String(LINE_GUIDE)} lines`
+	const tail = measurement.verdict === SPLIT_VERDICT ? SPLIT_TAIL : SINGLE_TAIL
+
+	return `${counted} (${guide}) — ${tail}`
+}
+
+const split_assess = {
+	FILE_GUIDE,
+	LINE_GUIDE,
+	SPLIT_VERDICT,
+	SINGLE_VERDICT,
+	assess,
+	measure,
+	non_test_changes,
+	parse_numstat,
+	parse_row,
+	reason,
+	verdict_for,
+}
+
+export type { FileChange, SizeMeasurement, SplitVerdict }
+export { split_assess }

package/scripts/sync/dependabot-pin-logic.ts

@@ -0,0 +1,135 @@
+import type { PinDrift } from './workflow-pin-logic'
+
+// Orchestration for `josh sync-dependabot-pins`: propagate a Dependabot action
+// bump from .github/workflows into templates/workflows for one or more PRs.
+// All git/gh side effects are injected via DependabotPinOps so the control flow
+// (checkout order, drift-skip, dry-run no-op) is unit-testable without spawning.
+const NO_PR_MESSAGE = 'No PR numbers supplied (e.g. `josh sdp 578 641`)'
+const INVALID_PR_PREFIX = 'Invalid PR number: '
+const DEPENDABOT_BRANCH_PREFIX = 'dependabot/'
+const PR_NUMBER_PATTERN = /^[1-9]\d*$/u
+
+interface DependabotPinOps {
+	get_current_branch: () => Promise<string>
+	get_pr_branch: (pr: number) => Promise<string>
+	checkout_pr: (pr: number) => Promise<void>
+	checkout_branch: (branch: string) => Promise<void>
+	sync_pins: () => Array<PinDrift>
+	stage_templates: () => Promise<void>
+	commit: (message: string) => Promise<void>
+	push: () => Promise<void>
+	log: (message: string) => void
+}
+
+interface SyncOptions {
+	is_dry_run: boolean
+}
+
+interface PrResult {
+	pr: number
+	synced_count: number
+	is_committed: boolean
+}
+
+function build_commit_message(pr: number): string {
+	return `Sync template workflow pins (Dependabot #${String(pr)})`
+}
+
+function parse_pr_number(token: string): number {
+	if (!PR_NUMBER_PATTERN.test(token)) throw new Error(`${INVALID_PR_PREFIX}${token}`)
+
+	const pr = Number(token)
+	if (!Number.isSafeInteger(pr)) throw new Error(`${INVALID_PR_PREFIX}${token}`)
+
+	return pr
+}
+
+function parse_pr_numbers(tokens: ReadonlyArray<string>): Array<number> {
+	if (tokens.length === 0) throw new Error(NO_PR_MESSAGE)
+
+	return tokens.map((token) => parse_pr_number(token))
+}
+
+async function commit_synced_pins(pr: number, ops: DependabotPinOps): Promise<void> {
+	await ops.stage_templates()
+	await ops.commit(build_commit_message(pr))
+	await ops.push()
+}
+
+function skipped_result(pr: number): PrResult {
+	return { pr, synced_count: 0, is_committed: false }
+}
+
+async function checkout_dependabot_pr(pr: number, ops: DependabotPinOps): Promise<boolean> {
+	await ops.checkout_pr(pr)
+	const branch = await ops.get_current_branch()
+
+	if (branch.startsWith(DEPENDABOT_BRANCH_PREFIX)) return true
+
+	ops.log(`#${String(pr)}: ${branch} is not a Dependabot branch — skipped`)
+
+	return false
+}
+
+async function apply_pr(pr: number, ops: DependabotPinOps): Promise<PrResult> {
+	if (!(await checkout_dependabot_pr(pr, ops))) return skipped_result(pr)
+
+	const drifts = ops.sync_pins()
+
+	if (drifts.length === 0) {
+		ops.log(`#${String(pr)}: template pins already in sync — skipped`)
+
+		return skipped_result(pr)
+	}
+
+	await commit_synced_pins(pr, ops)
+	ops.log(`#${String(pr)}: synced ${String(drifts.length)} pin(s) and pushed`)
+
+	return { pr, synced_count: drifts.length, is_committed: true }
+}
+
+async function plan_pr(pr: number, ops: DependabotPinOps): Promise<PrResult> {
+	const branch = await ops.get_pr_branch(pr)
+
+	ops.log(`#${String(pr)} (${branch}): would sync template pins and push if drifted [dry-run]`)
+
+	return skipped_result(pr)
+}
+
+async function process_pr(
+	pr: number,
+	options: SyncOptions,
+	ops: DependabotPinOps,
+): Promise<PrResult> {
+	if (options.is_dry_run) return await plan_pr(pr, ops)
+
+	return await apply_pr(pr, ops)
+}
+
+async function run_sync(
+	prs: ReadonlyArray<number>,
+	options: SyncOptions,
+	ops: DependabotPinOps,
+): Promise<Array<PrResult>> {
+	const start_branch = await ops.get_current_branch()
+	const results: Array<PrResult> = []
+
+	try {
+		for (const pr of prs) {
+			results.push(await process_pr(pr, options, ops))
+		}
+	} finally {
+		if (!options.is_dry_run) await ops.checkout_branch(start_branch)
+	}
+
+	return results
+}
+
+const dependabot_pin_logic = {
+	build_commit_message,
+	parse_pr_numbers,
+	run_sync,
+}
+
+export { dependabot_pin_logic }
+export type { DependabotPinOps }