@joshuafolkken/kit 1.872.0

package/scripts/overrides/overrides-check.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env tsx
+/**
+ * Check dependency overrides for unexpected changes.
+ *
+ * Checks effective overrides in pnpm-workspace.yaml and reports ignored package.json entries.
+ *
+ * Usage:
+ *   tsx scripts/overrides/overrides-check.ts --save      # save current overrides as snapshot
+ *   tsx scripts/overrides/overrides-check.ts              # compare current overrides against snapshot
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { overrides_snapshot_schema } from '#scripts/lib/schemas'
+import { overrides_files } from './overrides-files'
+import { overrides_check, type OverridesDiff } from './overrides-logic'
+
+function is_file_not_found(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+function load_snapshot(): Record<string, string> {
+	try {
+		return overrides_snapshot_schema.parse(
+			JSON.parse(readFileSync(overrides_check.SNAPSHOT_PATH, 'utf8')),
+		)
+	} catch (error) {
+		if (is_file_not_found(error)) {
+			console.error(`✖ Snapshot not found: ${overrides_check.SNAPSHOT_PATH}`)
+			console.error('  Run with --save first to create a snapshot.')
+		} else {
+			console.error(`✖ Invalid snapshot JSON: ${overrides_check.SNAPSHOT_PATH}`)
+		}
+
+		throw new Error('Failed to load snapshot', { cause: error })
+	}
+}
+
+function print_diff(diff: OverridesDiff, sources_summary: string): never {
+	console.error(`✖ overrides changed unexpectedly (${sources_summary}):`)
+
+	for (const line of overrides_check.format_diff_lines(diff)) {
+		console.error(line)
+	}
+
+	return process.exit(1)
+}
+
+function save_snapshot(current: Record<string, string>, sources_summary: string): never {
+	writeFileSync(overrides_check.SNAPSHOT_PATH, `${JSON.stringify(current, undefined, '\t')}\n`)
+	console.info(
+		`✔ Overrides snapshot saved to ${overrides_check.SNAPSHOT_PATH} (${sources_summary})`,
+	)
+
+	return process.exit(0)
+}
+
+function run_overrides_check(should_save: boolean): void {
+	const sources = overrides_files.read_current_sources()
+	const summary = overrides_check.describe_sources(sources)
+	const current = overrides_check.read_overrides(sources)
+
+	if (should_save) save_snapshot(current, summary)
+
+	const snapshot = load_snapshot()
+	const diff = overrides_check.compare(snapshot, current)
+
+	if (diff.is_changed) print_diff(diff, summary)
+
+	console.info(`✔ overrides unchanged (${summary}).`)
+}
+
+function main(): void {
+	const { values } = parseArgs({
+		options: { save: { type: 'boolean', default: false } },
+		strict: true,
+	})
+
+	run_overrides_check(values.save)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { run_overrides_check }

package/scripts/overrides/overrides-files.ts

@@ -0,0 +1,19 @@
+import { file_reader } from '#scripts/lib/read-file'
+import { overrides_check, type OverridesSources } from './overrides-logic'
+
+// A project may carry either source file and not the other — app-kit's package.json has no `pnpm`
+// field at all — so a missing file reads as an empty document rather than aborting the check.
+function read_current_sources(): OverridesSources {
+	return {
+		package_json: file_reader.read_file_or_empty(overrides_check.PACKAGE_JSON_PATH),
+		workspace_yaml: file_reader.read_file_or_empty(overrides_check.WORKSPACE_YAML_PATH),
+	}
+}
+
+function read_current_overrides(): Record<string, string> {
+	return overrides_check.read_overrides(read_current_sources())
+}
+
+const overrides_files = { read_current_sources, read_current_overrides }
+
+export { overrides_files }

package/scripts/overrides/overrides-logic.ts

@@ -0,0 +1,211 @@
+import { yaml_document } from '#scripts/yaml/yaml-document'
+import {
+	package_pnpm_schema,
+	package_with_deps_schema,
+	workspace_overrides_schema,
+} from './schemas'
+
+interface AddedEntry {
+	key: string
+	value: string
+}
+
+interface RemovedEntry {
+	key: string
+	value: string
+}
+
+interface ModifiedEntry {
+	key: string
+	old_value: string
+	new_value: string
+}
+
+interface OverridesDiff {
+	is_changed: boolean
+	added: Array<AddedEntry>
+	removed: Array<RemovedEntry>
+	modified: Array<ModifiedEntry>
+}
+
+function find_added(
+	snapshot_keys: Set<string>,
+	current: Record<string, string>,
+): Array<AddedEntry> {
+	return Object.entries(current)
+		.filter(([key]) => !snapshot_keys.has(key))
+		.map(([key, value]) => ({ key, value }))
+}
+
+function find_removed(
+	current_keys: Set<string>,
+	snapshot: Record<string, string>,
+): Array<RemovedEntry> {
+	return Object.entries(snapshot)
+		.filter(([key]) => !current_keys.has(key))
+		.map(([key, value]) => ({ key, value }))
+}
+
+function find_modified(
+	snapshot: Record<string, string>,
+	current: Record<string, string>,
+): Array<ModifiedEntry> {
+	return Object.entries(snapshot)
+		.filter(([key]) => Object.hasOwn(current, key) && snapshot[key] !== current[key])
+		.map(([key, old_value]) => ({ key, old_value, new_value: current[key] ?? '' }))
+}
+
+function compare(snapshot: Record<string, string>, current: Record<string, string>): OverridesDiff {
+	const snapshot_keys = new Set(Object.keys(snapshot))
+	const current_keys = new Set(Object.keys(current))
+
+	const added = find_added(snapshot_keys, current)
+	const removed = find_removed(current_keys, snapshot)
+	const modified = find_modified(snapshot, current)
+	const is_changed = added.length > 0 || removed.length > 0 || modified.length > 0
+
+	return { is_changed, added, removed, modified }
+}
+
+const SNAPSHOT_PATH = '.overrides-snapshot.json'
+const PACKAGE_JSON_PATH = 'package.json'
+const WORKSPACE_YAML_PATH = 'pnpm-workspace.yaml'
+
+// Both source files are optional and either may be absent from a project entirely, so an empty
+// string stands for "file not present" rather than being an error.
+interface OverridesSources {
+	package_json: string
+	workspace_yaml: string
+}
+
+function read_overrides_from_package(package_json_content: string): Record<string, string> {
+	if (package_json_content.trim().length === 0) return {}
+	const parsed = package_pnpm_schema.parse(JSON.parse(package_json_content))
+
+	return parsed.pnpm?.overrides ?? {}
+}
+
+function read_overrides_from_workspace(workspace_yaml_content: string): Record<string, string> {
+	const parsed = workspace_overrides_schema.parse(yaml_document.parse_yaml(workspace_yaml_content))
+
+	return parsed.overrides ?? {}
+}
+
+// pnpm 11+ ignores package.json's `pnpm.overrides`; only workspace overrides affect resolution.
+// Keep reading the old field for diagnostics, but never treat it as an effective override.
+function read_overrides(sources: OverridesSources): Record<string, string> {
+	return read_overrides_from_workspace(sources.workspace_yaml)
+}
+
+function count_entry(path: string, overrides: Record<string, string>): Array<string> {
+	const count = Object.keys(overrides).length
+
+	return count === 0 ? [] : [`${String(count)} from ${path}`]
+}
+
+// Printed next to every verdict so a vacuous run is visible: "no overrides found in …" names the
+// files that were actually read, which is the signal missing when the check passed on an empty
+// `package.json` while pnpm-workspace.yaml held the real entries.
+function describe_sources(sources: OverridesSources): string {
+	const counts = [
+		...count_entry(WORKSPACE_YAML_PATH, read_overrides_from_workspace(sources.workspace_yaml)),
+		...count_entry(PACKAGE_JSON_PATH, read_overrides_from_package(sources.package_json)).map(
+			(entry) => `${entry} (ignored by pnpm)`,
+		),
+	]
+
+	if (counts.length === 0) {
+		return `no overrides found in ${WORKSPACE_YAML_PATH} or ${PACKAGE_JSON_PATH}`
+	}
+
+	return counts.join(', ')
+}
+
+function format_diff_lines(diff: OverridesDiff): Array<string> {
+	return [
+		...diff.added.map((entry) => `  + added:   ${entry.key} → ${entry.value}`),
+		...diff.removed.map((entry) => `  - removed: ${entry.key} (was ${entry.value})`),
+		...diff.modified.map(
+			(entry) => `  ~ changed: ${entry.key}: ${entry.old_value} → ${entry.new_value}`,
+		),
+	]
+}
+
+function find_version_separator(key: string): number {
+	const scope_offset = key.startsWith('@') ? 1 : 0
+
+	return key.indexOf('@', scope_offset)
+}
+
+function extract_package_name(key: string): string {
+	const separator = find_version_separator(key)
+
+	if (separator === -1) return key
+
+	return key.slice(0, separator)
+}
+
+// Every overridden package, whether the key carries a version selector (`pkg@>=5`) or not
+// (`pkg: ^5.55.7`). An override declares the resolution the project has chosen for that package, so
+// `pnpm update --latest` must not rewrite its declared range: past a cap the tree stops resolving,
+// and for a plain override pnpm writes the raw package.json range into the lockfile importer instead
+// of the override-applied one, producing a lockfile that fails CI's frozen-lockfile install
+// (kit #744). Both failures have the same cause, so both take the same exclusion.
+function extract_overridden_package_names(overrides: Record<string, string>): Array<string> {
+	return Object.keys(overrides).map((key) => extract_package_name(key))
+}
+
+// Packages always held back from `pnpm update --latest`, regardless of overrides.
+// `typescript`: 7.x is the native (Go) port whose `require('typescript')` returns a stub with no
+// `SyntaxKind`, crashing the type-aware ESLint stack (typescript-eslint, eslint-plugin-sonarjs,
+// ts-api-utils) at rule-load time. Hold at 6.x until that stack supports the native API, then
+// remove this entry to fix forward (kit #658).
+const HELD_BACK_PACKAGE_NAMES: Array<string> = ['typescript']
+
+// The union of built-in held-back packages and every overridden package — the dependency names
+// `pnpm update --latest` must skip. Deduped so a package that is both held back and overridden is
+// listed once (used both to build the update command and to log what was skipped).
+function list_excluded_package_names(overrides: Record<string, string>): Array<string> {
+	return [...new Set([...HELD_BACK_PACKAGE_NAMES, ...extract_overridden_package_names(overrides)])]
+}
+
+function read_dependency_names(package_json_content: string): Array<string> {
+	const parsed = package_with_deps_schema.parse(JSON.parse(package_json_content))
+
+	return [...Object.keys(parsed.dependencies ?? {}), ...Object.keys(parsed.devDependencies ?? {})]
+}
+
+const PNPM_UPDATE_LATEST_ARGS = ['pnpm', 'update', '--latest']
+
+function build_update_command(
+	overrides: Record<string, string>,
+	package_json_content: string,
+): Array<string> | undefined {
+	const excluded_set = new Set(list_excluded_package_names(overrides))
+	const all_names = read_dependency_names(package_json_content)
+	const targets = all_names.filter((name) => !excluded_set.has(name))
+
+	if (targets.length === 0) return undefined
+
+	return [...PNPM_UPDATE_LATEST_ARGS, ...targets]
+}
+
+const overrides_check = {
+	compare,
+	read_overrides_from_package,
+	read_overrides_from_workspace,
+	read_overrides,
+	describe_sources,
+	format_diff_lines,
+	extract_package_name,
+	extract_overridden_package_names,
+	list_excluded_package_names,
+	read_dependency_names,
+	build_update_command,
+	PACKAGE_JSON_PATH,
+	WORKSPACE_YAML_PATH,
+	SNAPSHOT_PATH,
+}
+
+export type { OverridesDiff, OverridesSources }
+export { overrides_check }

package/scripts/overrides/schemas.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+
+const optional_string_record_schema = z.record(z.string(), z.string()).optional()
+
+const package_pnpm_schema = z.object({
+	pnpm: z
+		.object({
+			overrides: optional_string_record_schema,
+		})
+		.optional(),
+})
+
+const package_with_deps_schema = z.object({
+	dependencies: optional_string_record_schema,
+	devDependencies: optional_string_record_schema,
+})
+
+// pnpm 11+ reads workspace-level settings — `overrides` among them — from pnpm-workspace.yaml.
+// Loose so the unrelated keys that share the file (`allowBuilds`, `minimumReleaseAgeExclude`, …)
+// pass through untouched.
+const workspace_overrides_schema = z.looseObject({
+	overrides: optional_string_record_schema,
+})
+
+// pnpm-lock.yaml importer entries. Loose at every level so the sibling keys that share the
+// document (`packages`, `snapshots`, per-importer `configDependencies`, …) pass through untouched.
+const lockfile_dependency_schema = z.looseObject({ specifier: z.string() })
+
+const optional_dependency_group_schema = z.record(z.string(), lockfile_dependency_schema).optional()
+
+const lockfile_importer_schema = z.looseObject({
+	dependencies: optional_dependency_group_schema,
+	devDependencies: optional_dependency_group_schema,
+	optionalDependencies: optional_dependency_group_schema,
+})
+
+const lockfile_importers_schema = z.looseObject({
+	importers: z.record(z.string(), lockfile_importer_schema).optional(),
+})
+
+type LockfileImporter = z.infer<typeof lockfile_importer_schema>
+
+export type { LockfileImporter }
+export {
+	package_pnpm_schema,
+	package_with_deps_schema,
+	workspace_overrides_schema,
+	lockfile_importers_schema,
+}

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

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { z } from 'zod'
+import {
+	package_scout,
+	type PackageMetrics,
+	type RegistryFacts,
+	type SearchCandidate,
+} from './package-scout'
+import { package_scout_format } from './package-scout-format'
+
+// `josh pkg:scout <keywords> [--size <n>]` — before the Package-First tier decision, rank the
+// candidate packages by measured metrics so "clearly best (Tier A)" and "genuine toss-up (Tier B)"
+// are read off the output rather than judged (joshuafolkken/kit#2216).
+//
+// The registry answers in three reads: one search for the candidates, then per candidate a downloads
+// point and the latest version metadata (bundled types, license, unpacked size). A per-candidate read
+// that fails leaves that metric blank rather than dropping the row — the ranking still stands on the
+// search score, which is the one signal every candidate carries.
+
+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>]'
+const SEARCH_FAILED_MESSAGE =
+	'Could not read the npm registry search, so no candidates can be ranked — check the network and try again.'
+
+const search_object_schema = z.object({
+	package: z.object({ name: z.string(), version: z.string(), date: z.string().optional() }),
+	score: z.object({ final: z.number() }),
+})
+const search_response_schema = z.object({ objects: z.array(search_object_schema) })
+const downloads_schema = z.object({ downloads: z.number() })
+// The published `license` is a string on current packages and a `{ type }` object on old ones; both
+// are read, anything else is left blank. `looseObject` so the fields not read here never fail parsing.
+const license_schema = z.union([z.string(), z.object({ type: z.string() })]).optional()
+const latest_schema = z.looseObject({
+	types: z.string().optional(),
+	typings: z.string().optional(),
+	license: license_schema,
+	dist: z.looseObject({ unpackedSize: z.number().optional() }).optional(),
+})
+
+type SearchObject = z.infer<typeof search_object_schema>
+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) })
+		if (!response.ok) return undefined
+
+		return schema.parse(await response.json())
+	} catch {
+		return undefined
+	}
+}
+
+function to_candidate(object: SearchObject): SearchCandidate {
+	return {
+		name: object.package.name,
+		version: object.package.version,
+		score: object.score.final,
+		last_publish: object.package.date,
+	}
+}
+
+function license_of(license: Latest['license']): string | undefined {
+	if (typeof license === 'string') return license
+
+	return license?.type
+}
+
+const NO_FACTS: RegistryFacts = {
+	has_bundled_types: false,
+	license: undefined,
+	install_size_bytes: undefined,
+}
+
+function facts_of(latest: Latest | undefined): RegistryFacts {
+	if (latest === undefined) return NO_FACTS
+
+	return {
+		has_bundled_types: latest.types !== undefined || latest.typings !== undefined,
+		license: license_of(latest.license),
+		install_size_bytes: latest.dist?.unpackedSize,
+	}
+}
+
+// One candidate's two per-package reads, run together: the version metadata for the facts and the
+// downloads point. Neither depends on the other, so they go out in one round trip.
+async function gather(candidate: SearchCandidate): Promise<PackageMetrics> {
+	const [latest, downloads] = await Promise.all([
+		fetch_json(`${REGISTRY}/${candidate.name}/latest`, latest_schema),
+		fetch_json(`${DOWNLOADS_API}/${candidate.name}`, downloads_schema),
+	])
+
+	return package_scout.to_metrics(candidate, facts_of(latest), downloads?.downloads)
+}
+
+async function search(keywords: string, size: number): Promise<Array<SearchCandidate> | undefined> {
+	const url = `${REGISTRY}/-/v1/search?text=${encodeURIComponent(keywords)}&size=${String(size)}`
+	const response = await fetch_json(url, search_response_schema)
+
+	return response?.objects.map((object) => to_candidate(object))
+}
+
+interface ScoutArguments {
+	keywords: string
+	size: number
+}
+
+function parse_size(raw: string | undefined): number {
+	const parsed = Number(raw)
+
+	return raw === undefined || !Number.isSafeInteger(parsed) || parsed <= 0 ? DEFAULT_SIZE : parsed
+}
+
+function parse_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
+	const { values, positionals } = parseArgs({
+		args: [...argv],
+		options: { size: { type: 'string' } },
+		allowPositionals: true,
+	})
+	const keywords = positionals.join(' ').trim()
+
+	if (keywords === '') return undefined
+
+	return { keywords, size: parse_size(values.size) }
+}
+
+// An unknown flag makes `parseArgs` throw. Caught so the answer is the usage line rather than a stack
+// trace, on a command whose output a workflow reads.
+function read_arguments(argv: ReadonlyArray<string>): ScoutArguments | undefined {
+	try {
+		return parse_arguments(argv)
+	} catch {
+		return undefined
+	}
+}
+
+async function report(args: ScoutArguments): Promise<number> {
+	const candidates = await search(args.keywords, args.size)
+
+	if (candidates === undefined) {
+		console.error(SEARCH_FAILED_MESSAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const metrics = await Promise.all(candidates.map(async (candidate) => await gather(candidate)))
+
+	console.info(`Candidates for "${args.keywords}" (ranked by npm score):`)
+	console.info(package_scout_format.format_table(package_scout.build_table(metrics)))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const args = read_arguments(argv)
+
+	if (args === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await report(args)
+}
+
+// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
+// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+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))
+
+export { package_scout_cli }