@joshuafolkken/kit 1.872.0

package/scripts/refactor/refactor-scan.ts

@@ -0,0 +1,124 @@
+import { line_targets } from '#scripts/lines/line-targets'
+import { import_graph } from './import-graph'
+import { refactor_lint, type CategoryResult } from './refactor-lint'
+import { refactor_targets } from './refactor-targets'
+
+// `josh refactor:scan` — the command `prompts/refactoring.md` §4.1–§4.3 now point to instead of
+// describing the search by hand (joshuafolkken/kit#2180). It selects the target files, expands the
+// scope along the import graph, asks the project's own eslint which refactoring candidates the scope
+// holds, and answers whether any high- or medium-priority candidate remains.
+//
+// **It reports and never fails**, like `josh lines`: a candidate is work to do, not a gate to break,
+// so the exit code stays 0 and the answer is the printed verdict token. Convergence counts the high-
+// and medium-priority categories only; the one low-priority category (unused code) is reported but
+// never counted, so `clear` means the scope is empty of high/medium candidates.
+
+// The convergence vocabulary. `clear` is what §4.3's self-reported "no high- or medium-priority
+// candidate left" loop exit becomes once a command answers it: a token a caller can read, not a claim.
+// `error` is the third answer (joshuafolkken/kit#2180): the eslint run itself did not complete, so the
+// scope's state is unknown — kept distinct from `clear` so a failed scan is never read as converged.
+const CLEAR = 'clear'
+const CANDIDATES = 'candidates'
+const ERROR = 'error'
+
+interface ScanResult {
+	seed_count: number
+	scope_count: number
+	categories: ReadonlyArray<CategoryResult>
+	verdict: string
+}
+
+// Convergence counts high- and medium-priority candidates only: a low-priority finding (unused code)
+// is reported but auto-implemented by nobody, so it never keeps the loop from reading `clear`.
+function convergence_candidates(categories: ReadonlyArray<CategoryResult>): number {
+	return categories
+		.filter((category) => category.priority !== refactor_lint.LOW)
+		.reduce((sum, category) => sum + category.candidates.length, 0)
+}
+
+function verdict_token(categories: ReadonlyArray<CategoryResult>): string {
+	return convergence_candidates(categories) === 0 ? CLEAR : CANDIDATES
+}
+
+function scope_line(seed_count: number, scope_count: number): string {
+	return `scope: ${String(scope_count)} files (seed ${String(seed_count)}, expanded via import graph, max ${String(import_graph.MAX_STAGES)} stages)`
+}
+
+function category_header(category: CategoryResult): string {
+	return `${category.priority}  ${category.label}: ${String(category.candidates.length)}`
+}
+
+function candidate_lines(category: CategoryResult): ReadonlyArray<string> {
+	return category.candidates.map((candidate) => `    ${candidate.location} (${candidate.rule})`)
+}
+
+function category_block(category: CategoryResult): string {
+	return [category_header(category), ...candidate_lines(category)].join('\n')
+}
+
+function verdict_line(categories: ReadonlyArray<CategoryResult>): string {
+	const total = convergence_candidates(categories)
+
+	return total === 0 ? `verdict: ${CLEAR}` : `verdict: ${CANDIDATES} (${String(total)} high/medium)`
+}
+
+function render(
+	categories: ReadonlyArray<CategoryResult>,
+	seed_count: number,
+	scope_count: number,
+): string {
+	const blocks = categories.map((category) => category_block(category))
+
+	return [scope_line(seed_count, scope_count), ...blocks, verdict_line(categories)].join('\n')
+}
+
+// The failure report: the scope line and an `error` verdict, so a scan that could not run says so
+// rather than printing empty categories that would read as `clear`.
+function error_output(seed_count: number, scope_count: number): string {
+	return [scope_line(seed_count, scope_count), `verdict: ${ERROR} (scan could not run)`].join('\n')
+}
+
+function render_result(result: ScanResult): string {
+	if (result.verdict === ERROR) return error_output(result.seed_count, result.scope_count)
+
+	return render(result.categories, result.seed_count, result.scope_count)
+}
+
+async function scan(root: string): Promise<ScanResult> {
+	const seed = await refactor_targets.collect_targets(root)
+	const universe = await line_targets.lint_target_files(root)
+	const scope = [...import_graph.expand_scope(seed, universe, root)]
+	const categories = await refactor_lint.scan_categories(scope, root)
+	const counts = { seed_count: seed.length, scope_count: scope.length }
+
+	if (categories === undefined) return { ...counts, categories: [], verdict: ERROR }
+
+	return { ...counts, categories, verdict: verdict_token(categories) }
+}
+
+async function run_scan(): Promise<number> {
+	const root = await line_targets.repo_root()
+	const result = await scan(root)
+
+	process.stdout.write(`${render_result(result)}\n`)
+
+	return 0
+}
+
+const refactor_scan = {
+	category_block,
+	error_output,
+	render,
+	render_result,
+	run_scan,
+	scan,
+	convergence_candidates,
+	verdict_line,
+	verdict_token,
+	CANDIDATES,
+	CLEAR,
+	ERROR,
+}
+
+export type { ScanResult }
+export { refactor_scan }

package/scripts/refactor/refactor-targets.ts

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { line_targets } from '#scripts/lines/line-targets'
+
+// The target-file selection of `josh refactor:scan` — the priority `prompts/refactoring.md` §4.1
+// used to spell out in prose (joshuafolkken/kit#2180). The scope is the same reading every scoped
+// command decides from — the branch diff plus the untracked files (`changed-paths.ts`) — and only
+// when that is empty does it fall back to `scripts/`, so a run on a clean `main` still has something
+// to scan rather than reporting nothing.
+
+// The `scripts/` fallback lives under this directory, root-relative — the same spelling
+// `line-targets.ts` resolves against the repository root.
+const SCRIPTS_DIR = 'scripts'
+// The three exclusions §4.1 names: demo material, the story routes, and any file that opts out at its
+// top. Refactoring a demo or a story would change an example rather than the code it illustrates.
+const DEMO_MARKER = 'demo'
+const STORIES_DIR = 'src/routes/stories'
+// The opt-out marker, matched at the very top of the file so a mention of it lower down is not read
+// as one. `CLAUDE.md` documents it as the file-level refactoring exclusion.
+const REFACTOR_IGNORE_MARKER = '/* @refactor-ignore */'
+
+// A path segment named `demo`, or a filename that carries it, is demo material. Split on the forward
+// slash git prints, so a directory named `demo` and a file `foo.demo.ts` are both caught.
+function is_path_excluded(relative_path: string): boolean {
+	const segments = relative_path.split('/')
+
+	if (segments.some((segment) => segment.includes(DEMO_MARKER))) return true
+
+	return relative_path.includes(STORIES_DIR)
+}
+
+// The file-level opt-out is read from the file's own head rather than its path: `trimStart` lets a
+// leading blank line or shebang-free preamble still count, and a marker deeper in the file is ignored.
+function has_ignore_marker(source: string): boolean {
+	return source.trimStart().startsWith(REFACTOR_IGNORE_MARKER)
+}
+
+// A path that is gone or unreadable is not something to scan, so it is treated as opted out rather
+// than crashing the whole scan on one bad entry.
+function is_ignored_file(absolute_path: string): boolean {
+	try {
+		return has_ignore_marker(readFileSync(absolute_path, 'utf8'))
+	} catch {
+		return true
+	}
+}
+
+// The changed set wins; the `scripts/` fallback is used only when nothing changed. `undefined` and an
+// empty array are the same answer here — both mean "no change to scan" — because a scan of nothing is
+// never the intended result, unlike a scoped re-check where it means "narrowed to nothing".
+function select_scope(
+	changed: ReadonlyArray<string>,
+	fallback_files: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return changed.length > 0 ? changed : fallback_files
+}
+
+// Only lint-target source files, only those neither path-excluded nor opted out.
+function keep_target(root: string, absolute_path: string): boolean {
+	const relative_path = path.relative(root, absolute_path)
+
+	if (!line_targets.is_lint_target(relative_path) || is_path_excluded(relative_path)) return false
+
+	return !is_ignored_file(absolute_path)
+}
+
+function scripts_files(root: string, all_files: ReadonlyArray<string>): ReadonlyArray<string> {
+	const scripts_root = path.resolve(root, SCRIPTS_DIR)
+
+	return all_files.filter((file) => file.startsWith(`${scripts_root}${path.sep}`))
+}
+
+async function changed_absolute(root: string): Promise<ReadonlyArray<string>> {
+	try {
+		const relative = await changed_paths.read_changed_paths(false)
+
+		return relative.map((name) => path.resolve(root, name))
+	} catch {
+		return []
+	}
+}
+
+// The seed set §4.3 expands from: the changed files, or `scripts/` when nothing changed, filtered to
+// lint-target source files that are not excluded.
+async function collect_targets(root: string): Promise<ReadonlyArray<string>> {
+	const changed = await changed_absolute(root)
+	const all_files = await line_targets.lint_target_files(root)
+	const scope = select_scope(changed, scripts_files(root, all_files))
+
+	return scope.filter((absolute_path) => keep_target(root, absolute_path))
+}
+
+const refactor_targets = {
+	collect_targets,
+	has_ignore_marker,
+	is_path_excluded,
+	keep_target,
+	scripts_files,
+	select_scope,
+}
+
+export { refactor_targets }

package/scripts/release/release-cli.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_command } from '#scripts/git/git-command'
+import { release_history } from './release-history'
+import { release_plan, type ReleasePlan } from './release-plan'
+import { release_publish } from './release-publish'
+
+// `pnpm josh release` — the one place that decides a version (joshuafolkken/kit#1169).
+//
+// It does three things and no more: count the merges main has taken since the version last changed,
+// report and stop when that count is zero, and otherwise raise the version by that many minors, open
+// a pull request, merge it and watch for the tag.
+//
+// **It never touches the root checkout** (joshuafolkken/kit#2411). The count is read from
+// `origin/<default>`, and the version bump / commit / push happen in a dedicated work tree
+// `release_publish` cuts for the release — so a release can run beside a `backlogrun` (which keeps the
+// root on the default branch) and can start even when the root is dirty or on another branch.
+
+const DRY_RUN_FLAG = '--dry-run'
+const ARGUMENT_START = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+// **The remote-tracking ref is the tip everything is read from**, so the release measures against
+// main's latest rather than whatever the root checkout is sitting on. The fetch refreshes that ref;
+// a dry run skips it because a rehearsal writes nothing (a fetch updates refs), reporting on the ref
+// the checkout already has.
+async function origin_tip(is_dry_run: boolean): Promise<string> {
+	const default_branch = await git_command.get_default_branch()
+
+	if (!is_dry_run) await git_command.fetch_branch(default_branch)
+
+	return `origin/${default_branch}`
+}
+
+async function build_plan(tip: string): Promise<ReleasePlan> {
+	const current_version = await release_history.read_current_version(tip)
+
+	if (current_version === undefined) {
+		throw new Error(`Could not read a version from \`${tip}\`'s package.json.`)
+	}
+
+	const plan = await release_history.read_release_plan(current_version, undefined, tip)
+
+	if (plan === undefined) {
+		throw new Error(
+			`Could not find the commit that last changed the version within the last ${String(release_history.BASE_SEARCH_LIMIT)} commits that touched package.json.`,
+		)
+	}
+
+	return plan
+}
+
+async function run(is_dry_run: boolean): Promise<number> {
+	const tip = await origin_tip(is_dry_run)
+	const plan = await build_plan(tip)
+
+	if (plan.pending === 0) {
+		console.info(release_plan.format_nothing_to_release(plan.base))
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	console.info(release_plan.format_plan(plan))
+
+	if (is_dry_run) return SUCCESS_EXIT_CODE
+
+	return await release_publish.publish(plan)
+}
+
+function is_dry_run_requested(argv: ReadonlyArray<string>): boolean {
+	return argv.slice(ARGUMENT_START).includes(DRY_RUN_FLAG)
+}
+
+async function main(): Promise<void> {
+	try {
+		process.exit(await run(is_dry_run_requested(process.argv)))
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error))
+		process.exit(FAILURE_EXIT_CODE)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) void main()
+
+const release_cli = { is_dry_run_requested, run, DRY_RUN_FLAG }
+
+export { release_cli }

package/scripts/release/release-history.ts

@@ -0,0 +1,132 @@
+import { git_command } from '#scripts/git/git-command'
+import { package_with_version_schema } from '#scripts/lib/schemas'
+import { version_targets } from '#scripts/version/version-targets'
+import { release_plan, type ReleasePlan, type VersionedCommit } from './release-plan'
+
+// Reading main's history for the two numbers a release is made of: where the version last changed,
+// and how many merges have landed since (joshuafolkken/kit#1169).
+
+const { PACKAGE_JSON } = version_targets
+
+// How far back the search for "the commit that last changed the version" goes, counted in commits
+// that touched `package.json`. Once children stop bumping (joshuafolkken/kit#1486) that file still
+// changes for every dependency update, so the base can sit several entries down — but a repository
+// that has taken thirty `package.json` commits without a single release has a different problem, and
+// guessing past that point would be worse than saying so.
+const BASE_SEARCH_LIMIT = 30
+
+// **Which ref the history is read from.** `josh release` runs on a pulled default branch, so `HEAD`
+// is main there and the default is right. A caller on a feature branch names the ref it means —
+// `origin/main` — because `--first-parent` from a branch tip walks that branch rather than main, and
+// the count would silently omit every merge main took after the branch was cut
+// (joshuafolkken/kit#1486).
+const DEFAULT_TIP = 'HEAD'
+
+// The reads this module makes, named so a test can answer them without a git repository. Production
+// callers take the default and never pass one.
+interface HistoryReader {
+	log_first_parent: (limit: number, file_path: string, tip: string) => Promise<Array<string>>
+	show_file: (spec: string) => Promise<string>
+	count_merges: (range: string) => Promise<number>
+}
+
+const git_reader: HistoryReader = {
+	log_first_parent: git_command.log_first_parent,
+	show_file: git_command.show_file,
+	count_merges: git_command.count_merges,
+}
+
+// **Undefined rather than a throw for a `package.json` that cannot be read as one.** A revision where
+// the file is absent or malformed is not a version change, and the comparison above wants that
+// expressed as "no version here" rather than as an exception that ends the search.
+function parse_version(content: string | undefined): string | undefined {
+	if (content === undefined) return undefined
+
+	try {
+		return package_with_version_schema.parse(JSON.parse(content)).version
+	} catch {
+		return undefined
+	}
+}
+
+async function read_version_at(
+	reader: HistoryReader,
+	reference: string,
+): Promise<string | undefined> {
+	try {
+		// `./` is not decoration. `git show <sha>:package.json` resolves against the **repository
+		// root**, while the `git log -- package.json` that produced these revisions resolves against
+		// **cwd** — so run from a workspace sub-package the two halves would be comparing different
+		// files, and every version comparison would be against the wrong one. `./` makes `show`
+		// cwd-relative too, which is also what `read_workspace_version(process.cwd())` reads.
+		return parse_version(await reader.show_file(`${reference}:./${PACKAGE_JSON}`))
+	} catch {
+		return undefined
+	}
+}
+
+async function read_versioned_commits(
+	reader: HistoryReader,
+	tip: string,
+): Promise<Array<VersionedCommit>> {
+	const shas = await reader.log_first_parent(BASE_SEARCH_LIMIT, PACKAGE_JSON, tip)
+
+	return await Promise.all(
+		shas.map(async (sha) => ({ sha, version: await read_version_at(reader, sha) })),
+	)
+}
+
+async function read_base(
+	reader: HistoryReader = git_reader,
+	tip: string = DEFAULT_TIP,
+): Promise<string | undefined> {
+	const commits = await read_versioned_commits(reader, tip)
+	const oldest = commits.at(-1)
+	const oldest_parent_version =
+		oldest === undefined ? undefined : await read_version_at(reader, `${oldest.sha}^`)
+
+	return release_plan.find_version_base(commits, oldest_parent_version)
+}
+
+// The version `package.json` carries at a git revision. `josh release` reads it from
+// `origin/<default>` rather than from the checkout's own `package.json`, so the number it raises is
+// main's latest even when the run happens in a work tree cut for the release (joshuafolkken/kit#2411).
+async function read_current_version(
+	tip: string = DEFAULT_TIP,
+	reader: HistoryReader = git_reader,
+): Promise<string | undefined> {
+	return await read_version_at(reader, tip)
+}
+
+// **Undefined means the base could not be found**, never "there is nothing to release" — the two have
+// to stay distinguishable, because one is a report and the other is a failure.
+async function read_release_plan(
+	current_version: string,
+	reader: HistoryReader = git_reader,
+	tip: string = DEFAULT_TIP,
+): Promise<ReleasePlan | undefined> {
+	const base = await read_base(reader, tip)
+
+	if (base === undefined) return undefined
+
+	const pending = await reader.count_merges(`${base}..${tip}`)
+
+	return {
+		base,
+		pending,
+		current_version,
+		next_version: release_plan.next_version(current_version, pending),
+	}
+}
+
+const release_history = {
+	parse_version,
+	read_base,
+	read_current_version,
+	read_release_plan,
+	BASE_SEARCH_LIMIT,
+	DEFAULT_TIP,
+}
+
+export { release_history }
+export type { HistoryReader }

package/scripts/release/release-plan.ts

@@ -0,0 +1,130 @@
+import semver from 'semver'
+
+// What a release is, decided from main's history alone (joshuafolkken/kit#1169).
+//
+// **A version is a property of main's history, not of a branch.** `bump-version.ts` reads the local
+// `package.json` and increments it, so two branches cut from the same version both claim the same
+// next number — and git's three-way merge does not report two branches writing the same line to the
+// same value as a conflict. What surfaces instead is one version carrying two issues, with the other
+// version never existing.
+//
+// The answer is to stop asking a branch. `pending` is how many merges main has taken since the commit
+// that last changed the version, and the release raises the version by that many minors. There is one
+// place that decides, and it looks only at main at the moment it runs — which is why no lock, no
+// reserved number and no queue is needed.
+
+interface VersionedCommit {
+	sha: string
+	version: string | undefined
+}
+
+interface ReleasePlan {
+	base: string
+	pending: number
+	current_version: string
+	next_version: string
+}
+
+const PENDING_ICON = '🚚'
+const SHORT_SHA_LENGTH = 7
+
+// The version immediately before `commits[index]`. `commits` is newest-first and lists only the
+// commits that touched `package.json` along main's own first-parent line, so that version is exactly
+// `commits[index + 1]`'s: by construction nothing between the two changed the file.
+// `oldest_parent_version` closes the list at its far end, where there is no neighbor to compare with.
+//
+// **The fallback belongs to the end of the list and nowhere else.** `read_version_at` answers
+// `undefined` for any revision whose `package.json` could not be read — absent, malformed, or a
+// `git show` that failed — so a `?? oldest_parent_version` written on the neighbor's *version*
+// would fire in the middle of the list too, comparing against a version several commits older and
+// declaring a base far too new. The bounds check asks about the neighbor's existence instead.
+function previous_version_of(
+	commits: ReadonlyArray<VersionedCommit>,
+	index: number,
+	oldest_parent_version: string | undefined,
+): string | undefined {
+	const previous = commits[index + 1]
+
+	return previous === undefined ? oldest_parent_version : previous.version
+}
+
+// **The newest commit whose `package.json` version differs from the version immediately before it.**
+//
+// **A commit that touched `package.json` without moving the version is skipped**, which is what makes
+// this right once children stop bumping (joshuafolkken/kit#1486): a dependency update rewrites the
+// file every time and must not be mistaken for a release.
+//
+// **Both sides have to be readable for this to be a version change.** An unreadable neighbor makes
+// the comparison unanswerable, and the search carries on to older commits rather than declaring one:
+// a base that is too new under-counts the merges since it, and the release then ships fewer minors
+// than issues — silently, which is the one failure this command exists to prevent. Finding no base at
+// all is reported as a failure by the caller, which is the honest end of the same reasoning.
+function find_version_base(
+	commits: ReadonlyArray<VersionedCommit>,
+	oldest_parent_version: string | undefined,
+): string | undefined {
+	const found = commits.find((commit, index) => {
+		const previous = previous_version_of(commits, index, oldest_parent_version)
+
+		return commit.version !== undefined && previous !== undefined && commit.version !== previous
+	})
+
+	return found?.sha
+}
+
+// **Raising the version by `pending` minors.** `semver.inc(v, 'minor')` applied N times zeroes the
+// patch once and adds one to the minor each time, so N applications are a single addition — written
+// as one here rather than as a loop, because the loop would only be re-deriving that identity.
+//
+// **`pending === 0` returns the current version untouched, and that needs its own branch.** The
+// arithmetic zeroes the patch, so `1.339.4` with nothing pending would come back as `1.339.0` — a
+// *downgrade* carried inside every `ReleasePlan`, including the ones whose caller decides not to
+// release at all.
+function next_version(current: string, pending: number): string {
+	const parsed = semver.parse(current)
+
+	if (parsed === null) throw new Error(`Invalid version format: ${current}`)
+
+	if (pending === 0) return parsed.version
+
+	return `${String(parsed.major)}.${String(parsed.minor + pending)}.0`
+}
+
+function short_sha(sha: string): string {
+	return sha.slice(0, SHORT_SHA_LENGTH)
+}
+
+// **The count is the line a person reads**, which is why it is built here rather than at each caller:
+// the release command prints it, and so does anything else that wants to say how much is waiting to
+// ship (joshuafolkken/kit#1169 → "the count of unreleased merges shows somewhere visible").
+function format_pending_line(pending: number): string {
+	return `${PENDING_ICON} unreleased merges on main: ${String(pending)}`
+}
+
+function format_nothing_to_release(base: string): string {
+	return [
+		format_pending_line(0),
+		`  Nothing to release — no merge has landed on main since ${short_sha(base)}, the commit that last changed the version.`,
+	].join('\n')
+}
+
+function format_plan(plan: ReleasePlan): string {
+	return [
+		format_pending_line(plan.pending),
+		`  base ${short_sha(plan.base)} · ${plan.current_version} → ${plan.next_version}`,
+	].join('\n')
+}
+
+const release_plan = {
+	find_version_base,
+	previous_version_of,
+	format_nothing_to_release,
+	format_pending_line,
+	format_plan,
+	next_version,
+	short_sha,
+	PENDING_ICON,
+}
+
+export { release_plan }
+export type { ReleasePlan, VersionedCommit }