@joshuafolkken/kit 1.1035.0 → 1.1094.0

package/scripts/{bytes → lines}/bytes-command.ts

@@ -170,10 +170,8 @@ const bytes_command = {
 	entry_row,
 	entry_rows,
 	near_ceiling_statuses,
-	run_bytes,
 	scan_lines,
 	status_row,
-	NONE_NEAR,
 	NOT_A_FILE,
 	NOT_BUDGETED,
 }

package/scripts/lines/lines-command.ts

@@ -161,7 +161,6 @@ const lines_command = {
 	header,
 	near_limit_budgets,
 	not_counted_reason,
-	render,
 	row,
 	rows_for,
 	run_lines,

package/scripts/lint/lint-related-scope.ts

@@ -116,7 +116,6 @@ function eslint_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
 
 const lint_related_scope = {
 	COMMAND_LABEL,
-	COMMAND_NAME,
 	NOTHING_LINTABLE_REASON,
 	describe_scope,
 	eslint_arguments,

package/scripts/lint/lint-related.ts

@@ -99,6 +99,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_related_lint(process.argv.slice(changed_file_scope.ARGV_START))
 }
 
-const lint_related = { report_ignored_flags, run_related_lint }
+const lint_related = { run_related_lint }
 
 export { lint_related }

package/scripts/{git → notify}/telegram-notify.ts

@@ -1,4 +1,5 @@
 import { gh_spawn } from '#scripts/gh/gh-spawn'
+import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
 
 const TELEGRAM_API_BASE = 'https://api.telegram.org'
@@ -193,7 +194,7 @@ function build_text(input: TelegramSendInput): string {
 
 async function post_message(config: TelegramConfig, text: string): Promise<void> {
 	const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`
-	const response = await fetch(url, {
+	const response = await timed_fetch(url, {
 		method: 'POST',
 		headers: { 'Content-Type': 'application/json' },
 		body: JSON.stringify({ chat_id: config.chat_id, text }),
@@ -412,7 +413,6 @@ async function stranded(input: StrandedInput): Promise<boolean> {
 }
 
 const telegram_notify = {
-	REPO_LOOKUP_TIMEOUT_MS,
 	confirm,
 	send,
 	send_or_report,

package/scripts/{git → notify}/telegram-test.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_gh_repo } from '#scripts/gh/git-gh-repo'
+import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
+import { git_error } from '#scripts/git/git-error'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
-import { git_error } from './git-error'
-import { git_gh_issue_read } from './git-gh-issue-read'
-import { git_gh_repo } from './git-gh-repo'
-import { github_issue_url, type IssueUrlTarget } from './github-issue-url'
 import { telegram_notify } from './telegram-notify'
 import { telegram_test_logic, type CliValues, type ResolvedContext } from './telegram-test-logic'
 

package/scripts/observations/observation-ledger-home.ts

@@ -115,7 +115,6 @@ async function append(target: string, lines: ReadonlyArray<string>): Promise<voi
 const observation_ledger_home = {
 	append,
 	issue_path,
-	ledger_directory,
 	ledger_root,
 	read,
 	writer_path,

package/scripts/observations/observation-ledger-line.ts

@@ -96,7 +96,6 @@ function missing_lines(candidates: ReadonlyArray<string>, ledger: string): Array
 const observation_ledger_line = {
 	broken_ledger_lines,
 	is_ledger_entry_line,
-	line_reason,
 	missing_lines,
 }
 

package/scripts/observations/observation-ledger-migrate.ts

@@ -146,6 +146,6 @@ function migrate(root: string): boolean {
 	).some(Boolean)
 }
 
-const observation_ledger_migrate = { claim_path, migrate }
+const observation_ledger_migrate = { migrate }
 
 export { observation_ledger_migrate }

package/scripts/observations/observations-flush-landing.ts

@@ -1,6 +1,6 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
-import type { OpenPull } from '#scripts/git/git-gh-pr-auto-merge'
-import { git_pr_checks } from '#scripts/git/git-pr-checks'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { OpenPull } from '#scripts/gh/git-gh-pr-auto-merge'
+import { git_pr_checks } from '#scripts/gh/git-pr-checks'
 import { error_text } from '#scripts/lib/error-message'
 
 // **A flush pull request lands whether or not the flush that opened it is still alive**

package/scripts/observations/observations-flush.ts

@@ -1,5 +1,5 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_command } from '#scripts/git/git-command'
-import { git_gh_command } from '#scripts/git/git-gh-command'
 import { main_sync } from '#scripts/git/main-sync'
 import { error_text } from '#scripts/lib/error-message'
 import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
@@ -308,6 +308,7 @@ async function stage_ledger(): Promise<void> {
 	const ledger_paths = observation_ledger.ledger_paths(await git_command.status())
 
 	for (const file_path of ledger_paths) {
+		// eslint-disable-next-line no-await-in-loop -- git add holds the index lock, so two at once fail
 		await git_command.add_path(file_path)
 	}
 }
@@ -423,7 +424,6 @@ const observations_flush = {
 	broken_lines_message,
 	CLEAN_MESSAGE,
 	COMMIT_MESSAGE,
-	empty_flush_message,
 	flush,
 	flush_branch_message,
 	has_ledger_change,

package/scripts/overrides/lockfile-overrides.ts

@@ -1,4 +1,4 @@
-import { yaml_document } from '#scripts/yaml/yaml-document'
+import { yaml_document } from '#scripts/lib/yaml-document'
 import { overrides_check } from './overrides-logic'
 import { lockfile_importers_schema, type LockfileImporter } from './schemas'
 

package/scripts/overrides/overrides-logic.ts

@@ -1,4 +1,4 @@
-import { yaml_document } from '#scripts/yaml/yaml-document'
+import { yaml_document } from '#scripts/lib/yaml-document'
 import {
 	package_pnpm_schema,
 	package_with_deps_schema,

package/scripts/package/package-scout-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
 import {
 	package_scout,
@@ -23,7 +24,6 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const DEFAULT_SIZE = 10
-const FETCH_TIMEOUT_MS = 10_000
 const REGISTRY = 'https://registry.npmjs.org'
 const DOWNLOADS_API = 'https://api.npmjs.org/downloads/point/last-week'
 const USAGE = 'Usage: josh pkg:scout <keywords> [--size <n>]'
@@ -51,7 +51,7 @@ type Latest = z.infer<typeof latest_schema>
 
 async function fetch_json<T>(url: string, schema: z.ZodType<T>): Promise<T | undefined> {
 	try {
-		const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+		const response = await timed_fetch(url)
 		if (!response.ok) return undefined
 
 		return schema.parse(await response.json())
@@ -172,14 +172,9 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 
 const package_scout_cli = {
 	USAGE,
-	SEARCH_FAILED_MESSAGE,
 	DEFAULT_SIZE,
 	read_arguments,
-	facts_of,
-	license_of,
-	to_candidate,
 	run,
-	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/package/package-scout.ts

@@ -112,8 +112,6 @@ const package_scout = {
 	NEAR_TIE_THRESHOLD,
 	to_metrics,
 	rank,
-	tie_gap,
-	verdict_of,
 	build_table,
 }
 

package/scripts/propagate/propagate-git-failure.ts

@@ -178,7 +178,6 @@ const propagate_git_failure = {
 	NO_COMMIT,
 	NOT_OPENED,
 	PUSH_FAILED,
-	TAIL_LINE_COUNT,
 	UNCOMMITTED,
 	attribute,
 	describe_failure,

package/scripts/propagate/propagate-git.ts

@@ -207,7 +207,6 @@ function return_to_default_branch(repository_path: string): boolean {
 
 const propagate_git = {
 	default_branch,
-	fetch_branch,
 	return_to_default_branch,
 	current_branch,
 	commit_ahead,
@@ -215,7 +214,6 @@ const propagate_git = {
 	has_pre_push_hook,
 	can_push_without_hooks,
 	is_clean,
-	is_up_to_date,
 	decide_tree_state,
 	tree_state,
 }

package/scripts/propagate/propagate-plan.ts

@@ -0,0 +1,185 @@
+import { adopt_toolkits } from '#scripts/adopt/adopt-toolkits'
+import { propagate_run, type RunStep, type StepResult } from './propagate-run'
+import { propagate_steps, type Release, type ReleasePlan } from './propagate-steps'
+import { propagate_targets, type Manifest, type PropagateTarget } from './propagate-targets'
+
+// What one `josh propagate` run carries, decided from the repository it runs in (joshuafolkken/kit#2879).
+//
+// The supplier is kit or any toolkit built on it — app-kit, game-kit — and a toolkit's propagation
+// carries the base packages under it too, at the versions that toolkit itself has installed and was
+// verified with rather than at the base's newest. Each consumer is delivered by the topmost toolkit
+// it installs: a lower supplier skips it, because syncing only the base would write the overlay's
+// paths back to the base's originals (`docs/sync.md` → base first, overlay after), and would hand the
+// consumer a base the toolkit above it never verified. Discovery, ordering and the CLI name are
+// `josh adopt`'s own reads (`scripts/adopt/adopt-toolkits.ts`), not a second copy of them.
+
+const REFUSAL_PREFIX = 'Refusing to propagate:'
+const SUPPLIER_REFUSAL = [
+	`${REFUSAL_PREFIX} this is not a ${adopt_toolkits.TOOLKIT_SCOPE} toolkit's own repository.`,
+	'Propagation carries a published release outward, so it runs from the toolkit that published it',
+	'— kit, or a toolkit built on it that ships a CLI. Run it from that checkout instead.',
+].join('\n')
+const UNRESOLVED_CAUSE =
+	'declared here but not installed with a runnable CLI, so the consumers would receive this toolkit without it. Run `pnpm install`.'
+const MISPLACED_CAUSE =
+	'declared under `dependencies`, which leaves it out of the plan. Move it to `devDependencies`.'
+const ARROW = ' → '
+const LIST_SEPARATOR = ', '
+
+interface Supplier {
+	package_name: string
+	bin_name: string
+}
+
+interface SupplierResolution {
+	supplier?: Supplier
+	refusal?: string
+}
+
+interface BaseResolution {
+	bases?: Array<Release>
+	cause?: string
+}
+
+interface PlanResolution {
+	plan?: ReleasePlan
+	refusal?: string
+}
+
+// A toolkit is a scoped package that ships a CLI — the same reading `josh adopt` applies to an
+// installed one, applied here to the repository's own manifest.
+function toolkit_name(manifest: Manifest): string | undefined {
+	const { name } = manifest
+
+	return name !== undefined && adopt_toolkits.is_toolkit_package(name) ? name : undefined
+}
+
+function supplier_of(manifest: Manifest | undefined): Supplier | undefined {
+	const package_name = manifest === undefined ? undefined : toolkit_name(manifest)
+	if (manifest === undefined || package_name === undefined) return undefined
+	const bin_name = adopt_toolkits.bin_name_of(package_name, manifest)
+
+	return bin_name === undefined ? undefined : { package_name, bin_name }
+}
+
+function resolve_supplier(project_root: string): SupplierResolution {
+	const supplier = supplier_of(propagate_targets.read_manifest(project_root))
+
+	return supplier === undefined ? { refusal: SUPPLIER_REFUSAL } : { supplier }
+}
+
+// A base toolkit pinned to the version installed in the supplier's own checkout — the one the
+// supplier's verification gate ran against.
+function pin_installed(project_root: string, release: Release): Release | undefined {
+	const version = propagate_targets.installed_version(project_root, release.package_name)
+
+	return version === undefined ? undefined : { ...release, version }
+}
+
+// Why a declared base toolkit would fall out of the plan, naming it — either way `josh adopt` refuses
+// one for (joshuafolkken/kit#1540). A base left out is not merely left behind: every consumer that
+// installs it would then read it as a toolkit above this one and be skipped.
+function incomplete_cause(project_root: string): string | undefined {
+	const misplaced = adopt_toolkits.misplaced_toolkits(project_root)
+	if (misplaced.length > 0) return `${misplaced.join(LIST_SEPARATOR)} — ${MISPLACED_CAUSE}`
+	const unresolved = adopt_toolkits.unresolved_toolkits(project_root)
+
+	return unresolved.length === 0
+		? undefined
+		: `${unresolved.join(LIST_SEPARATOR)} — ${UNRESOLVED_CAUSE}`
+}
+
+// The supplier's base toolkits, base first, or the names that cannot be carried.
+function base_releases(project_root: string, supplier: Supplier): BaseResolution {
+	const cause = incomplete_cause(project_root)
+	if (cause !== undefined) return { cause }
+
+	const bases = adopt_toolkits
+		.discover_toolkits(project_root)
+		.filter((release) => release.package_name !== supplier.package_name)
+		.map((release) => pin_installed(project_root, release))
+
+	return bases.every((release) => release !== undefined) ? { bases } : { cause: UNRESOLVED_CAUSE }
+}
+
+// The releases one run carries: the base toolkits first, then the supplier at its own version, so the
+// sync runs base first and the supplier's overlay is written last.
+function build_plan(project_root: string, version: string): PlanResolution {
+	const { supplier, refusal } = resolve_supplier(project_root)
+	if (supplier === undefined) return { refusal: refusal ?? SUPPLIER_REFUSAL }
+	const { bases, cause } = base_releases(project_root, supplier)
+	if (bases === undefined) return { refusal: `${REFUSAL_PREFIX} ${cause ?? UNRESOLVED_CAUSE}` }
+	const releases = [...bases, { ...supplier, version }]
+
+	return { plan: { releases, origin: propagate_steps.PROPAGATE_ORIGIN } }
+}
+
+// The package the run publishes and waits for — by construction the plan's last release.
+function supplier_name(plan: ReleasePlan): string {
+	return plan.releases.at(-1)?.package_name ?? ''
+}
+
+// A declared scoped package counts as a toolkit unless it is demonstrably a library: installed, and
+// shipping no CLI. One that is not installed yet cannot be told apart, and treating it as a toolkit
+// errs toward leaving the consumer to the propagation above rather than reverting its overlay.
+function may_be_toolkit(repository_path: string, package_name: string): boolean {
+	if (adopt_toolkits.read_bin_name(repository_path, package_name) !== undefined) return true
+
+	return adopt_toolkits.is_unreachable_toolkit(repository_path, package_name)
+}
+
+function carriers_of(target: PropagateTarget, plan: ReleasePlan): Array<string> {
+	const carried = new Set(plan.releases.map((release) => release.package_name))
+
+	return adopt_toolkits
+		.all_declared_toolkits(target.path)
+		.filter((name) => !carried.has(name) && may_be_toolkit(target.path, name))
+}
+
+// A consumer that installs a toolkit this run does not carry is left to that toolkit's propagation.
+// Only a candidate that would otherwise be processed or reported current is re-classified.
+function mark_carried(target: PropagateTarget, plan: ReleasePlan): PropagateTarget {
+	if (target.state !== 'ready' && target.state !== 'up_to_date') return target
+	const carriers = carriers_of(target, plan)
+
+	return carriers.length === 0 ? target : { ...target, state: 'carried_above', carriers }
+}
+
+// What the dry run prints for the two steps that repeat per release: the versions each package is
+// pinned to, and the sync order.
+function plan_details(plan: ReleasePlan): Readonly<Record<string, string>> {
+	return {
+		[propagate_run.STEP_UPGRADE]: plan.releases
+			.map((release) => `${release.package_name}@${release.version}`)
+			.join(LIST_SEPARATOR),
+		[propagate_run.STEP_SYNC]: propagate_steps
+			.sync_commands(plan)
+			.map(({ command }) => command.join(' '))
+			.join(ARROW),
+	}
+}
+
+// The dry-run runner: it reports what each step would do and touches nothing.
+function create_step_describer(plan: ReleasePlan): RunStep {
+	const details = plan_details(plan)
+
+	return (target: PropagateTarget, step: string): StepResult => {
+		const detail = details[step]
+		const suffix = detail === undefined ? '' : `: ${detail}`
+
+		console.info(`  ${target.repo}: would run ${step}${suffix}`)
+
+		return { step, is_ok: true }
+	}
+}
+
+const propagate_plan = {
+	resolve_supplier,
+	build_plan,
+	supplier_name,
+	mark_carried,
+	create_step_describer,
+}
+
+export type { Supplier }
+export { propagate_plan }

package/scripts/propagate/propagate-publish.ts

@@ -1,4 +1,4 @@
-import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { poll } from '#scripts/lib/poll'
 import { with_page_size } from '#scripts/version/version-remote'
 
@@ -161,6 +161,7 @@ async function wait_for_publish(
 		const { state } = probe_once(resolved, versions_endpoint, target_version, progress)
 
 		if (state !== undefined) return finish(state, target_version, progress.attempts)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await resolved.sleep(resolved.interval_ms)
 	}
 
@@ -168,8 +169,6 @@ async function wait_for_publish(
 }
 
 const propagate_publish = {
-	DEFAULT_TIMEOUT_MS,
-	DEFAULT_INTERVAL_MS,
 	UNREADABLE_THRESHOLD,
 	is_version_published,
 	should_keep_waiting,

package/scripts/propagate/propagate-run.ts

@@ -65,13 +65,17 @@ const SKIP_REASONS: Readonly<Record<string, string>> = {
 	missing_checkout: 'no local checkout at the mapped path — reported, not cloned',
 	unreadable: 'package.json could not be read',
 	not_selected: 'not the repository --target named',
+	carried_above: 'delivered by the propagation of a toolkit above this one',
 }
 
 // The reason text for a candidate that is not going to be processed. A missing local checkout is
 // reported rather than cloned: propagation writes to a working tree, and creating one nobody asked
 // for is not a step this command may take on its own.
 function skip_reason(target: PropagateTarget): string {
-	return SKIP_REASONS[target.state] ?? 'not eligible'
+	const reason = SKIP_REASONS[target.state] ?? 'not eligible'
+	if (target.carriers === undefined) return reason
+
+	return `${reason}: ${target.carriers.join(', ')}`
 }
 
 const LEFTOVER_NOTE = 'upgrade/sync changes left uncommitted'
@@ -185,8 +189,6 @@ function format_report(results: ReadonlyArray<TargetResult>): string {
 const propagate_run = {
 	PROPAGATED_REASON,
 	LEFTOVER_NOTE,
-	has_leftover_changes,
-	leftover_of,
 	STEP_RETURN,
 	STEP_PRECHECK,
 	STEP_ISSUE,

package/scripts/propagate/propagate-steps.ts

@@ -1,7 +1,7 @@
 import { pr_classification } from '#scripts/ci/pr-classification'
-import { git_gh_exec } from '#scripts/git/git-gh-exec'
-import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
-import { OTHER_CHANGE_LABEL } from '#scripts/git/issue-labels'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { OTHER_CHANGE_LABEL } from '#scripts/issue/issue-labels'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { error_text } from '#scripts/lib/error-message'
 import { build_upgrade_shell_command } from '#scripts/version/upgrade-shell-command'
@@ -88,13 +88,28 @@ function release_names(releases: ReadonlyArray<Release>): string {
 	return `${names.slice(0, -1).join(NAME_SEPARATOR)}${LAST_SEPARATOR}${last}`
 }
 
+// Each release with its own version, for a plan whose releases disagree on one — a toolkit's
+// propagation carries the base packages at the versions that toolkit was verified with
+// (joshuafolkken/kit#2879), so one shared "to <version>" would name a version most of them are not.
+function versioned_names(releases: ReadonlyArray<Release>): string {
+	const named = releases.map((release) => ({
+		...release,
+		package_name: `${release.package_name} to ${release.version}`,
+	}))
+
+	return `Upgrade ${release_names(named)}`
+}
+
 // One release reproduces `issue_title` exactly, which is what keeps a `propagate` run's issue title
 // unchanged by the generalization.
 function plan_title(releases: ReadonlyArray<Release>): string {
 	const [first] = releases
 	if (first === undefined) return EMPTY_PLAN_TITLE
+	const is_one_version = releases.every((release) => release.version === first.version)
 
-	return issue_title(release_names(releases), first.version)
+	return is_one_version
+		? issue_title(release_names(releases), first.version)
+		: versioned_names(releases)
 }
 
 function plan_body(plan: ReleasePlan): string {
@@ -413,14 +428,12 @@ function describe_step(target: PropagateTarget, step: string): StepResult {
 }
 
 const propagate_steps = {
-	STEP_COMMANDS,
 	JOSH_BIN,
 	PROPAGATE_ORIGIN,
 	sync_command,
 	upgrade_command,
 	upgrade_commands,
 	sync_commands,
-	return_step,
 	VERIFY_SCRIPT,
 	issue_title,
 	issue_body,

package/scripts/propagate/propagate-targets.ts

@@ -20,9 +20,17 @@ const MANIFEST_NAME = 'package.json'
 const NODE_MODULES = 'node_modules'
 
 // Why a candidate is not going to be processed, or that it is. `not_selected` is the one state set
-// after classification: a candidate `--target` left out (joshuafolkken/kit#2755).
+// after classification: a candidate `--target` left out (joshuafolkken/kit#2755). `carried_above` is
+// the other: a consumer that installs a toolkit above the supplier, which that toolkit's own
+// propagation delivers instead (joshuafolkken/kit#2879).
 type TargetState =
-	'ready' | 'up_to_date' | 'not_downstream' | 'missing_checkout' | 'unreadable' | 'not_selected'
+	| 'ready'
+	| 'up_to_date'
+	| 'not_downstream'
+	| 'missing_checkout'
+	| 'unreadable'
+	| 'not_selected'
+	| 'carried_above'
 
 interface PropagateTarget {
 	repo: string
@@ -31,6 +39,9 @@ interface PropagateTarget {
 	// The range the consumer currently declares, when it declares one at all. Reported so a skip can
 	// say what it skipped rather than only that it did.
 	declared_range?: string
+	// The toolkits above the supplier this consumer installs, when it is `carried_above` — named in
+	// the skip so the report says which propagation will deliver it.
+	carriers?: ReadonlyArray<string>
 }
 
 // Only the fields propagation reads. `passthrough` is deliberate — a consumer manifest carries far
@@ -148,11 +159,7 @@ function resolve_targets(
 }
 
 const propagate_targets = {
-	has_checkout,
 	read_manifest,
-	classify_manifest_absence,
-	classify_before_dependency,
-	declared_range,
 	installed_version,
 	classify_target,
 	resolve_targets,