@joshuafolkken/kit 1.872.0

package/scripts/lines/line-budget.ts

@@ -0,0 +1,404 @@
+import { createHash } from 'node:crypto'
+import { statSync } from 'node:fs'
+import path from 'node:path'
+import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { execa } from 'execa'
+import { z } from 'zod'
+import { effective_limit, type LineRuleOptions } from './effective-limit'
+
+// joshuafolkken/kit#1425: the file line limit was only ever reported *after* the writing was done.
+// Measured by hand from run #1406's transcript (PR #1422, 45.8 minutes), 19.8% of the whole run —
+// 543 seconds — went on reacting to `max-lines` once the implementation was already finished:
+// `pnpm josh gate` five times and `pnpm josh lint` four, of which 115 seconds was tool execution and
+// the remaining 353 was model time in between. The splitting itself was correct work; what was wrong
+// is that it was decided after the fact rather than at design time.
+//
+// **The limit is not changed here, and nothing in this file counts lines its own way.** That is the
+// trap a headroom report walks into: a second counting method becomes a way to satisfy the limit by
+// counting differently, and `CLAUDE.md` treats reinterpreting a verification gate as a prohibited
+// workaround. So the number is not computed — it is *asked of the project's own eslint*, the same
+// invocation `pnpm josh lint` reaches, with `max-lines` lowered to 0 so the rule reports
+// unconditionally and its message carries the count it would have compared against the real limit.
+//
+// **Running ESLint in process instead was tried first and is wrong.** `new Linter().verify(...)` and
+// `new ESLint().lintFiles(...)` both answer **one line lower than the `eslint` CLI on any file that
+// starts with `#!`** — measured on eslint 10.10.0 with this repository's own config, `301` from the
+// CLI against `300` from either API for the same file. Every `scripts/*.ts` entry point has a
+// hashbang, so an in-process count would have been quietly wrong for most of this package while the
+// gate went on failing at a number the report never showed. Spawning costs a process; agreeing with
+// the gate is the whole point of the report.
+//
+// **joshuafolkken/kit#1454: the limit and the counting options come from the same place the count
+// does.** They used to be read from kit's own `eslint/rules/code-quality.js` while the count was asked
+// of the project's eslint — identical in kit, and two different rules in a consumer that overrides
+// `max-lines` after `create_base_config`. `effective-limit.ts` resolves the entry the project's own
+// eslint applies **to each file**, and nothing in this file reads kit's copy any more. Where no entry
+// can be resolved there is no budget, and the count is reported without one: falling back to kit's
+// number would restore the defect and do it silently.
+
+const MAX_LINES_RULE = 'max-lines'
+// The rule reports when the count is **greater than** `max`, and 0 is the lowest value its own schema
+// accepts — so at `max: 0` every file reports except one whose counted code lines are exactly 0. That
+// is not only the empty file: with `skipBlankLines` and `skipComments` on, a comments-and-blank-lines
+// module counts 0 too. `count_or_zero` below is what keeps that case an answer rather than a shrug —
+// and `--no-inline-config` is what keeps a silenced rule from being mistaken for one of those files.
+const PROBE_MAX = 0
+const PROBE_SEVERITY = 'error'
+// The boundary between having headroom and being over the limit. Deliberately *not* `PROBE_MAX`, which
+// they happen to share the value of today: one is the value handed to the rule and the other is a
+// property of a budget, and reading the two as one constant means raising either silently moves the
+// other.
+const NO_HEADROOM = 0
+// A file eslint linted but said nothing about under this rule has exactly this many code lines.
+const NO_CODE_LINES = 0
+// `File has too many lines (229). Maximum allowed is 0.` — the first parenthesised number is the
+// count. Pinned by a test that feeds the number back as the real limit and checks that the gate's own
+// verdict flips at exactly that boundary, so a reworded message fails there rather than reporting a
+// wrong number quietly.
+const COUNT_PATTERN = /\((\d+)\)/u
+const COUNT_GROUP = 1
+
+// **Why 85%, and how it lines up with joshuafolkken/kit#1249.** That issue asks for the same shape
+// for a distributed document's resident budget and is still open with nothing settled, so there is no
+// number there to copy; what it and joshuafolkken/kit#951 settle is the *form* — a margin that turns
+// "at the limit" into a warning while there is still room to write the fix. Matching the resident
+// reserve's fraction instead (2,000 of 60,000 bytes, 3.3%) would leave 10 lines of margin, less than
+// one function is allowed to be, which is a warning arriving with nowhere left to go. 45 lines is a
+// little under two functions at the 25-line function limit — enough to write the split into.
+const NEAR_LIMIT_FRACTION = 0.85
+const PERCENT = 100
+
+const ESLINT_BIN = 'eslint'
+const PNPM = 'pnpm'
+const PNPM_EXEC = 'exec'
+// `--no-inline-config` is not tidiness: a `/* eslint-disable max-lines */` at the top of a file
+// silences the rule, an inline directive beats the `--rule` override, and the probe would then see no
+// message and read the file as 0 code lines — printing `300 to spare` for a 500-line file, which is
+// the most dangerous direction this report can be wrong in. With inline configuration off, the count
+// is always the rule's own.
+const FORMAT_FLAGS: ReadonlyArray<string> = ['--format', 'json', '--no-inline-config']
+const RULE_FLAG = '--rule'
+// **No `--cache`, and a `--cache-location` all the same.** An eslint run started *without* `--cache`
+// deletes whatever `--cache-location` names, which is how the edit hook once wiped the gate's cache
+// (joshuafolkken/kit#1332) — so the flag has to be here, pointed somewhere harmless, even though this
+// probe keeps no cache. It keeps none because the only key available is the checkout, and two
+// `josh lines` calls at once in one repository — routine with parallel agents here — would then be two
+// unsynchronized writers of one file. A cold run is a couple of seconds against the 543 this report
+// exists to save, so the cache is not worth a shared-state hazard.
+//
+// **The path is per probe, not per call** (joshuafolkken/kit#1454). Since the counting method decides
+// how many probes one call starts, two of them can now run concurrently — and each deletes whatever
+// `--cache-location` names as it starts, so one shared path would have them racing to unlink the file
+// the other just made. The option set's own key is folded into the name, which makes the paths
+// distinct exactly when the probes are.
+const CACHE_PREFIX = 'josh-lines-eslint-cache-'
+const CACHE_LOCATION_FLAG = '--cache-location'
+const CACHE_KEY_LENGTH = 8
+// Bounded so a hung child ends the call rather than holding it open. A cold type-aware lint of a few
+// files is seconds; this is two orders of magnitude beyond that.
+const PROCESS_TIMEOUT_MS = 180_000
+
+// Only the two fields this reads. `ruleId` is nullable on a parse error or an ignore warning, and
+// both of those are answers — "no count for this path" — rather than failures.
+const message_schema = z.object({ ruleId: z.string().nullish(), message: z.string() })
+const results_schema = z.array(
+	z.object({ filePath: z.string(), messages: z.array(message_schema) }),
+)
+
+interface LineBudget {
+	code_lines: number
+	limit: number
+	headroom: number
+	is_near_limit: boolean
+}
+
+// `limit` is carried beside the budget, and it is not the same thing as `budget.limit`: a path this
+// project enforces no `max-lines` on has no limit at all, and the caller has to be able to say that
+// rather than say the count failed (joshuafolkken/kit#1454).
+interface FileBudget {
+	file_path: string
+	limit: number | undefined
+	budget: LineBudget | undefined
+}
+
+// The paths that share one counting method, and therefore one eslint run. `key` identifies that
+// method — it is what the paths were grouped by, and what keeps two concurrent probes off one cache
+// path.
+interface ProbeGroup {
+	key: string
+	options: LineRuleOptions
+	paths: Array<string>
+}
+
+function near_limit_threshold(limit: number): number {
+	return Math.ceil(limit * NEAR_LIMIT_FRACTION)
+}
+
+// The share of the limit at which "near the limit" begins, for a report that has no single limit to
+// state the boundary as a line count against.
+function near_limit_percent(): number {
+	return Math.round(NEAR_LIMIT_FRACTION * PERCENT)
+}
+
+function budget_of(code_lines: number, limit: number): LineBudget {
+	return {
+		code_lines,
+		limit,
+		headroom: limit - code_lines,
+		is_near_limit: code_lines >= near_limit_threshold(limit),
+	}
+}
+
+// The counting options are the project's own, so a consumer that turns `skipComments` off is counted
+// its way. Lowering `max` is the only change the probe makes.
+function probe_rule(options: LineRuleOptions): string {
+	return JSON.stringify({
+		[MAX_LINES_RULE]: [PROBE_SEVERITY, { ...options, max: PROBE_MAX }],
+	})
+}
+
+function cache_prefix(key: string): string {
+	const digest = createHash('sha256').update(key).digest('hex').slice(0, CACHE_KEY_LENGTH)
+
+	return `${CACHE_PREFIX}${digest}-`
+}
+
+function probe_arguments(group: ProbeGroup, project_root: string): Array<string> {
+	return [
+		...FORMAT_FLAGS,
+		RULE_FLAG,
+		probe_rule(group.options),
+		CACHE_LOCATION_FLAG,
+		stamp_file.stamp_path(cache_prefix(group.key), project_root),
+		...group.paths,
+	]
+}
+
+// The project's own eslint, through its own shim when there is one and `pnpm exec` when there is not
+// — the same two routes every other command in this package reaches a local binary by. The lookup
+// **walks up** from the given directory, because pnpm does: resolving only the directory the command
+// was invoked in would disagree with the very binary it spawns, which is joshuafolkken/kit#934 and the
+// reason `local-bin.ts` ships this variant.
+function probe_command(project_root: string, probe_args: ReadonlyArray<string>): Array<string> {
+	const shim = find_local_bin_upwards(project_root, ESLINT_BIN)
+
+	return shim === undefined ? [PNPM, PNPM_EXEC, ESLINT_BIN, ...probe_args] : [shim, ...probe_args]
+}
+
+// `execa` directly rather than through `buffered-process.ts`: that helper merges stderr into stdout
+// and forces color, both of which a JSON reader cannot use.
+async function run_probe(group: ProbeGroup, project_root: string): Promise<string | undefined> {
+	const [bin, ...command_arguments] = probe_command(
+		project_root,
+		probe_arguments(group, project_root),
+	)
+
+	try {
+		const result = await execa(bin ?? PNPM, command_arguments, {
+			cwd: project_root,
+			reject: false,
+			stdout: 'pipe',
+			stderr: 'ignore',
+			timeout: PROCESS_TIMEOUT_MS,
+		})
+
+		return result.stdout
+	} catch {
+		return undefined
+	}
+}
+
+function count_in_message(message: string): number | undefined {
+	const raw = COUNT_PATTERN.exec(message)?.[COUNT_GROUP]
+
+	return raw === undefined ? undefined : Number(raw)
+}
+
+function count_in(messages: ReadonlyArray<z.infer<typeof message_schema>>): number | undefined {
+	const reported = messages.find((message) => message.ruleId === MAX_LINES_RULE)
+
+	return reported === undefined ? undefined : count_in_message(reported.message)
+}
+
+// **No `max-lines` message is two different answers, and they must not be merged.** A file eslint
+// refused — ignored, covered by no configuration, unparseable — carries a message with no `ruleId`,
+// and that one has no count. A file eslint linted and this rule did not fire on has exactly 0 code
+// lines, which is a number and is reported as one.
+function count_or_zero(
+	messages: ReadonlyArray<z.infer<typeof message_schema>>,
+): number | undefined {
+	const counted = count_in(messages)
+
+	if (counted !== undefined) return counted
+
+	const is_refused = messages.some((message) => message.ruleId === null)
+
+	return is_refused ? undefined : NO_CODE_LINES
+}
+
+// Keyed by the absolute path eslint reports, so the caller's spelling of a path does not have to
+// match it. A path eslint refused is simply absent, and the caller reports that rather than a number.
+function counts_in(raw_output: string | undefined): ReadonlyMap<string, number> {
+	const counts = new Map<string, number>()
+	const parsed = results_schema.safeParse(JSON.parse(raw_output ?? 'null'))
+
+	if (!parsed.success) return counts
+
+	for (const result of parsed.data) {
+		const code_lines = count_or_zero(result.messages)
+
+		if (code_lines !== undefined) counts.set(path.resolve(result.filePath), code_lines)
+	}
+
+	return counts
+}
+
+// The safe entry point, and the only one exported: eslint's output can be empty or truncated, and
+// `JSON.parse` throws on both.
+function parse_counts(raw_output: string | undefined): ReadonlyMap<string, number> {
+	try {
+		return counts_in(raw_output)
+	} catch {
+		return new Map<string, number>()
+	}
+}
+
+// **Only regular files are passed to eslint, and this is not tidiness.** One argument eslint cannot
+// match — a path that is gone, or a directory whose every entry is ignored — makes it exit with no
+// JSON at all, and because this sends every path in one run to keep the cost at one process start,
+// that single bad argument would leave every *other* path unanswered.
+// `throwIfNoEntry: false` covers a path that is not there and nothing else — an unreadable parent
+// directory raises `EACCES`, which would leave this call with no answer at all rather than one bad
+// row, taking every other path in the same invocation with it.
+function is_lintable_path(file_path: string): boolean {
+	try {
+		return statSync(file_path, { throwIfNoEntry: false })?.isFile() === true
+	} catch {
+		return false
+	}
+}
+
+function lintable_paths(file_paths: ReadonlyArray<string>): ReadonlyArray<string> {
+	return file_paths.filter((file_path) => is_lintable_path(file_path))
+}
+
+// One eslint run per *distinct counting method*, rather than one per path. The cost of this report is
+// a process start, so the number of paths is the one thing that must not multiply it — and the number
+// of distinct `max-lines` option sets in one project is one, in every configuration that does not
+// deliberately count two groups of files differently (joshuafolkken/kit#1454).
+// The keys are sorted before they are written out, so two config blocks that state the same options in
+// a different order are one group rather than two. Unsorted, a purely cosmetic difference would split
+// the probe in two and cost a second eslint process for nothing.
+function options_key(options: LineRuleOptions): string {
+	return JSON.stringify(
+		options,
+		Object.keys(options).toSorted((left, right) => left.localeCompare(right)),
+	)
+}
+
+function grouped(
+	options_by_path: ReadonlyMap<string, LineRuleOptions>,
+): ReadonlyMap<string, ProbeGroup> {
+	const groups = new Map<string, ProbeGroup>()
+
+	for (const [file_path, options] of options_by_path) {
+		const key = options_key(options)
+		const group = groups.get(key) ?? { key, options, paths: [] }
+
+		group.paths.push(file_path)
+		groups.set(key, group)
+	}
+
+	return groups
+}
+
+async function counts_for(
+	options_by_path: ReadonlyMap<string, LineRuleOptions>,
+	project_root: string,
+): Promise<ReadonlyMap<string, number>> {
+	const groups: Array<ProbeGroup> = []
+
+	for (const [, group] of grouped(options_by_path)) groups.push(group)
+
+	const outputs = await Promise.all(
+		groups.map(async (group) => await run_probe(group, project_root)),
+	)
+	const counts = new Map<string, number>()
+
+	for (const output of outputs) {
+		for (const [file_path, code_lines] of parse_counts(output)) counts.set(file_path, code_lines)
+	}
+
+	return counts
+}
+
+function budget_for(
+	code_lines: number | undefined,
+	limit: number | undefined,
+): LineBudget | undefined {
+	if (code_lines === undefined || limit === undefined) return undefined
+
+	return budget_of(code_lines, limit)
+}
+
+// A path is counted only where its limit is known, because a count with nothing to compare it against
+// is reported as a bare number rather than as a budget — so probing it would buy nothing.
+async function budgets_for(
+	file_paths: ReadonlyArray<string>,
+	project_root: string,
+): Promise<ReadonlyArray<FileBudget>> {
+	const options = await effective_limit.options_for(lintable_paths(file_paths), project_root)
+	const counts = await counts_for(options, project_root)
+
+	return file_paths.map((file_path) => {
+		const resolved = path.resolve(file_path)
+		const code_lines = counts.get(resolved)
+		const limit = options.get(resolved)?.max
+
+		return { file_path, limit, budget: budget_for(code_lines, limit) }
+	})
+}
+
+// `268/300 code lines (89%), 32 to spare` — the one phrasing every reader of this budget prints, so
+// two of them can never describe the same file differently.
+// The share is floored rather than rounded, so it cannot print a number the advice disagrees with:
+// rounded, 254/300 reads `85%` while `near_limit_threshold` is 255 and no advice follows it — and the
+// documentation tells the reader that 85% is where "near the limit" begins.
+function describe(budget: LineBudget): string {
+	const share = Math.floor((budget.code_lines / budget.limit) * PERCENT)
+	const remaining =
+		budget.headroom < NO_HEADROOM
+			? `${String(-budget.headroom)} over`
+			: `${String(budget.headroom)} to spare`
+	const counted = `${String(budget.code_lines)}/${String(budget.limit)}`
+
+	return `${counted} code lines (${String(share)}%), ${remaining}`
+}
+
+// What to do about it, and nothing when there is nothing to do. Over the limit the gate will report
+// it anyway; near it, the decision is the one Step 0 is supposed to make before the writing starts.
+function advice(budget: LineBudget): string | undefined {
+	if (budget.headroom < NO_HEADROOM) return 'over the limit: split it before the gate reports it'
+	if (!budget.is_near_limit) return undefined
+
+	return 'near the limit: declare the splitting plan in Step 0 before writing into it'
+}
+
+const line_budget = {
+	advice,
+	budget_of,
+	budgets_for,
+	describe,
+	is_lintable_path,
+	near_limit_percent,
+	near_limit_threshold,
+	parse_counts,
+	probe_arguments,
+	probe_command,
+	probe_rule,
+	NEAR_LIMIT_FRACTION,
+}
+
+export { line_budget }
+export type { FileBudget, LineBudget }

package/scripts/lines/line-targets.ts

@@ -0,0 +1,80 @@
+import path from 'node:path'
+import { git_spawn } from '#scripts/git/git-spawn'
+
+// The no-argument half of joshuafolkken/kit#1809. `josh lines <path>` answers for a file someone
+// already named; a file near the limit that nobody has named yet is invisible until the gate reports
+// it. This enumerates the repository's own lint-target files so the no-argument scan can report every
+// one of them near the limit at once, before the first edit rather than after it.
+//
+// **The list is git's, not a filesystem walk, and it is not this file's own idea of a source file.**
+// `git ls-files --cached --others --exclude-standard` is exactly what git would consider tracked plus
+// what is new and not ignored — so a fresh file near the limit shows up and a build artifact under a
+// gitignore does not, with no ignore parser of this module's own to drift from `.gitignore`. The
+// extension filter is only a pre-filter that keeps the eslint probe from being handed thousands of
+// non-source paths: whether a path actually has a `max-lines` budget is still `budgets_for`'s to
+// decide from the project's own eslint, and a path with none is dropped from the report there.
+
+const LINT_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+])
+
+// `--full-name` and the `:/` pathspec print repository-root-relative paths for the whole tree
+// wherever the command runs, matching the spelling every other reading in this package resolves
+// against the root; `-z` separates them with NUL so a path with an unusual character is never quoted
+// or escaped, which removes any need for `core.quotePath=false`.
+const WHOLE_TREE_PATHSPEC = ':/'
+const LS_FILES_FLAGS: ReadonlyArray<string> = [
+	'ls-files',
+	'--cached',
+	'--others',
+	'--exclude-standard',
+	'--full-name',
+	'-z',
+]
+const NUL = '\0'
+// `--show-toplevel` prints the absolute repository (or worktree) root from anywhere inside it, so the
+// root-relative names `--full-name` returns resolve to the right absolute paths wherever the command
+// was invoked.
+const SHOW_TOPLEVEL: ReadonlyArray<string> = ['rev-parse', '--show-toplevel']
+
+function is_lint_target(relative_path: string): boolean {
+	return LINT_EXTENSIONS.has(path.extname(relative_path))
+}
+
+function split_names(output: string): ReadonlyArray<string> {
+	return output.split(NUL).filter((name) => name.length > 0)
+}
+
+// `git_spawn.read` is the one place ordinary git commands are spawned from, so this reuses it rather
+// than growing a second spawn site (joshuafolkken/kit#1640).
+async function repo_root(): Promise<string> {
+	return await git_spawn.read([...SHOW_TOPLEVEL])
+}
+
+// The names resolve against the repository `root`, never the process cwd: `--full-name` prints them
+// relative to the root wherever the command runs, so resolving against cwd would double the prefix
+// and drop every file when the command is invoked from a subdirectory.
+async function lint_target_files(root: string): Promise<ReadonlyArray<string>> {
+	const output = await git_spawn.read([...LS_FILES_FLAGS, WHOLE_TREE_PATHSPEC])
+
+	return split_names(output)
+		.filter((name) => is_lint_target(name))
+		.map((name) => path.resolve(root, name))
+}
+
+const line_targets = {
+	is_lint_target,
+	lint_target_files,
+	repo_root,
+	split_names,
+}
+
+export { line_targets }

package/scripts/lines/lines-command.ts

@@ -0,0 +1,174 @@
+#!/usr/bin/env tsx
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { line_budget, type FileBudget, type LineBudget } from './line-budget'
+import { line_targets } from './line-targets'
+
+// `josh lines` — the ask-before-writing half of joshuafolkken/kit#1425. `pnpm josh lint` reports the
+// file line limit only once it has been broken, and by then the writing is finished and the splitting
+// that follows is rework. This answers the same question before the first edit: how many code lines
+// each target file already has, and how many are left.
+//
+// **It reports and never fails.** The limit is lint's to enforce, and a second command exiting
+// non-zero on the same condition would be a second enforcement point for it — which is how a headroom
+// report turns into a way to reinterpret the gate. A non-zero exit here means the arguments were
+// unusable, never that a file is large.
+
+const ARGV_START = 2
+const ROW_GAP = '  '
+// The no-argument scan's answer when nothing is near the limit — a defined "none" rather than a
+// failure, so an empty result reads as "the repository is clear" instead of "the command broke".
+const NONE_NEAR = 'no files near the limit'
+
+// Why a path carries no number, said in the row rather than left blank — a blank would read as zero
+// code lines, which is the one answer this command must never appear to give.
+//
+// **Three reasons, and none claims more than it knows.** A path that is not a regular file — a typo,
+// or a directory — is never sent to eslint at all, so quoting eslint's verdict for it would answer a
+// question nobody asked, and a reader would take a typo for a real file eslint declined to count. A
+// path this project sets no `max-lines` on has nothing to be counted *against*, which is `NO_LIMIT`
+// below. The last covers everything that reached the probe without coming back with a number: a path
+// eslint ignores, one no configuration covers, one it could not parse, and a probe that could not run
+// at all. It deliberately does not name eslint, because the last of those is not eslint's doing.
+const NOT_A_FILE = 'not counted: not a regular file'
+const NOT_COUNTED = 'not counted: no line count for this path'
+// The third reason, and the one that replaced a wrong number (joshuafolkken/kit#1454). This project's
+// eslint enforces no `max-lines` here, so there is nothing to report a budget against — and the
+// alternative to saying so is quoting kit's limit for someone else's project, which is the defect. It
+// names no cause because there are several: the rule is turned off for this path, no configuration
+// covers it with a `max`, or the project's eslint could not be loaded at all. The row would otherwise
+// assert whichever of them it guessed.
+const NO_LIMIT = 'not counted: no max-lines limit for this path'
+
+function not_counted_reason(entry: FileBudget): string {
+	if (!line_budget.is_lintable_path(entry.file_path)) return NOT_A_FILE
+
+	return entry.limit === undefined ? NO_LIMIT : NOT_COUNTED
+}
+
+function budgeted(budget: NonNullable<FileBudget['budget']>): string {
+	const note = line_budget.advice(budget)
+	const suffix = note === undefined ? '' : ` — ${note}`
+
+	return `${line_budget.describe(budget)}${suffix}`
+}
+
+function row(relative_path: string, entry: FileBudget): string {
+	const body = entry.budget === undefined ? not_counted_reason(entry) : budgeted(entry.budget)
+
+	return `${relative_path}${ROW_GAP}${body}`
+}
+
+// The threshold is printed with the rows rather than left implicit: a reader who sees "near the limit"
+// on one file and nothing on the next needs the boundary to know which side a third one is on.
+//
+// **It is read off the budgets rather than from a limit of this command's own** (joshuafolkken/kit#1454).
+// Each file's limit is whatever that project's eslint enforces for it, so there is a line count to
+// print here only where every counted file agrees on one; where they do not — or where none was
+// resolved — the boundary is stated as the share it has always been, and each row carries its own
+// limit beside its own percentage.
+function header(budgets: ReadonlyArray<FileBudget>): string {
+	const limits = [...new Set(budgets.map((entry) => entry.limit))].filter(
+		(limit) => limit !== undefined,
+	)
+	const [only] = limits
+
+	if (only === undefined || limits.length !== 1) {
+		return `near from ${String(line_budget.near_limit_percent())}% of each file's own limit`
+	}
+
+	return `limit ${String(only)} code lines · near from ${String(line_budget.near_limit_threshold(only))}`
+}
+
+function rows_for(budgets: ReadonlyArray<FileBudget>, project_root: string): ReadonlyArray<string> {
+	return budgets.map((entry) => row(path.relative(project_root, entry.file_path), entry))
+}
+
+// A budget that reached the "near the limit" threshold, narrowed so the sort below can read
+// `headroom` without a non-null assertion — the filter is what proves `budget` is present.
+function is_near(entry: FileBudget): entry is FileBudget & { budget: LineBudget } {
+	return entry.budget?.is_near_limit === true
+}
+
+// The no-argument scan reports only what is near the limit, least headroom first, so an over-limit
+// file — negative headroom — sorts ahead of one that merely has little room left.
+function near_limit_budgets(budgets: ReadonlyArray<FileBudget>): ReadonlyArray<FileBudget> {
+	return budgets
+		.filter(is_near)
+		.toSorted((left, right) => left.budget.headroom - right.budget.headroom)
+}
+
+async function scan_budgets(root: string): Promise<ReadonlyArray<FileBudget>> {
+	const targets = await line_targets.lint_target_files(root)
+	const budgets = await line_budget.budgets_for(targets, root)
+
+	return near_limit_budgets(budgets)
+}
+
+async function argument_budgets(
+	command_arguments: ReadonlyArray<string>,
+	project_root: string,
+): Promise<ReadonlyArray<FileBudget>> {
+	const targets = command_arguments.map((argument) => path.resolve(project_root, argument))
+
+	return await line_budget.budgets_for(targets, project_root)
+}
+
+// Only the scan can be empty — a path argument always yields a row, even a "not counted" one — so the
+// none-line is the scan's defined answer and never a path run's.
+function render(budgets: ReadonlyArray<FileBudget>, project_root: string): string {
+	if (budgets.length === 0) return NONE_NEAR
+
+	return [header(budgets), ...rows_for(budgets, project_root)].join('\n')
+}
+
+// The scan resolves the repository root first — `budgets_for` and the row display both key off it — so
+// a run started from a subdirectory reports the same files as one started from the root.
+async function run_scan(): Promise<number> {
+	const root = await line_targets.repo_root()
+	const budgets = await scan_budgets(root)
+
+	process.stdout.write(`${render(budgets, root)}\n`)
+
+	return 0
+}
+
+async function run_arguments(
+	command_arguments: ReadonlyArray<string>,
+	project_root: string,
+): Promise<number> {
+	const budgets = await argument_budgets(command_arguments, project_root)
+
+	process.stdout.write(`${render(budgets, project_root)}\n`)
+
+	return 0
+}
+
+async function run_lines(
+	command_arguments: ReadonlyArray<string>,
+	project_root: string,
+): Promise<number> {
+	return command_arguments.length === 0
+		? await run_scan()
+		: await run_arguments(command_arguments, project_root)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_lines(process.argv.slice(ARGV_START), process.cwd())
+}
+
+const lines_command = {
+	header,
+	near_limit_budgets,
+	not_counted_reason,
+	render,
+	row,
+	rows_for,
+	run_lines,
+	NONE_NEAR,
+	NOT_A_FILE,
+	NO_LIMIT,
+	NOT_COUNTED,
+}
+
+export { lines_command }