@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/josh/josh-usage-workflow.ts

@@ -1,212 +0,0 @@
-import type { CommandUsage } from './josh-command-types'
-
-// The usage of the commands `docs/josh-commands-automation.md` documents under "Workflow",
-// "Versioning", "Maintenance" and "Git hooks", keyed by command name. The page's usage blocks are
-// generated from this table and `josh help <command>` prints it, so an example or a flag is written
-// once, here (#3939).
-const PR_TITLE = '"PR title #N"'
-const ISSUE_URL = '--issue-url "https://..."'
-const REVIEW_ISSUE = '--issue 2325'
-const CHECK = '--check'
-const JSON_FLAG = '--json'
-const BODY_FILE_NOTE =
-	'(`-` reads stdin); use this whenever the body carries a backtick or `$`. Passing both forms is refused.'
-
-/* eslint-disable @typescript-eslint/naming-convention */
-const WORKFLOW_USAGE: Readonly<Record<string, CommandUsage>> = {
-	followup: {
-		examples: [
-			{ arguments: PR_TITLE, note: 'merges (default)' },
-			{ arguments: String.raw`${PR_TITLE} --notify-message "Implemented X:\n- change 1"` },
-			{ arguments: `${PR_TITLE} --notify-message-file completion.md` },
-			{ arguments: `${PR_TITLE} --ai-review-ignore-reason "false positive"` },
-			{ arguments: `${PR_TITLE} --no-merge`, note: 'do the work, leave the PR open' },
-		],
-		flags: [
-			{
-				names: ['--no-merge'],
-				description:
-					'do the follow-up work but do not merge; leaves the PR open (the only flag that stops the merge). `--merge` is a deprecated no-op. A PR already merged by hand skips the CI wait, the AI-review scan and the merge and runs only the post-merge tail; a completion report already on the Issue is not posted again.',
-			},
-			{
-				names: ['--notify-message'],
-				description: 'inline completion body; `\\n` expands to newlines.',
-			},
-			{
-				names: ['--notify-message-file'],
-				description: `read the completion body from a file ${BODY_FILE_NOTE}`,
-			},
-			{
-				names: ['--ai-review-ignore-reason'],
-				description: 'reason to dismiss an AI-review finding.',
-			},
-		],
-	},
-	notify: {
-		examples: [
-			{ arguments: String.raw`--task-type planning ${ISSUE_URL} --body="- bullet 1\n- bullet 2"` },
-			{
-				arguments: `--task-type confirmation ${ISSUE_URL} --body-file r.md --recommended "Go" --alternative "Wait"`,
-			},
-		],
-		flags: [
-			{
-				names: ['--task-type'],
-				description:
-					'one of `planning` 📋, `completion` ✅, `failure` ❌, `warning` ⚠️, `kickoff_retry` 🔄, `confirmation` ⏸️. Do not send `completion` or `warning` by hand — `josh followup` sends them.',
-			},
-			{
-				names: ['--body', "--body=$'…'"],
-				description: "inline body; use `--body=$'…'` when it starts with `-`.",
-			},
-			{ names: ['--body-file'], description: `read the body from a file ${BODY_FILE_NOTE}` },
-			{
-				names: ['--repo-name', '--issue-url', '--pr-url'],
-				description:
-					'header repository, resolved in that order, then the working directory. The issue title is read from `--issue-url`.',
-			},
-			{
-				names: ['--recommended', '--alternative'],
-				description:
-					'the choices appended under `JOSH_SESSION_LANG` headings; `--recommended` is required for `confirmation`, `--alternative` is repeatable.',
-			},
-		],
-	},
-	'observations:flush': { examples: [{ arguments: '' }] },
-	'measure:rerun': { examples: [{ arguments: '2212' }] },
-	'review:record': {
-		examples: [
-			{ arguments: `${REVIEW_ISSUE} bug-risks:medium:src/foo.ts:42 tests:low:a.test.ts` },
-			{ arguments: REVIEW_ISSUE, note: 'a zero-finding round — records one `none` line' },
-			{
-				arguments: `${REVIEW_ISSUE} --comment`,
-				note: 'a round that passed after the PR opened — an Issue comment, no append',
-			},
-			{ arguments: `${CHECK} ${REVIEW_ISSUE}`, note: 'the merge gate: was it recorded?' },
-		],
-	},
-	bump: { examples: [{ arguments: 'major' }, { arguments: 'minor' }, { arguments: 'patch' }] },
-	release: {
-		examples: [
-			{ arguments: '' },
-			{ arguments: '--dry-run', note: 'count and report, write nothing' },
-		],
-		flags: [
-			{
-				names: ['--dry-run'],
-				description:
-					'count and report only; writes nothing, fetches nothing, and creates no work tree.',
-			},
-			{
-				names: ['--help', '-h'],
-				description:
-					'print the usage line and exit 0 without fetching or releasing. Any other argument is refused with the usage line and a non-zero exit, before anything is fetched.',
-			},
-		],
-	},
-	'release:scope': {
-		examples: [
-			{ arguments: '', note: '→ required | skip | unknown' },
-			{ arguments: '--json', note: '{"scope":"…","reason":"…"} on one line' },
-		],
-	},
-	'ruleset:check': {
-		examples: [
-			{ arguments: '', note: 'report only' },
-			{ arguments: '--apply', note: 'add the missing checks to the existing rule' },
-		],
-		flags: [
-			{
-				names: ['--apply'],
-				description:
-					"append the missing checks to the ruleset's required-checks rule (or to the branch protection's contexts). It never creates a ruleset: with none, create one under Settings → Rules → Rulesets, then rerun. Writing a repository setting needs admin access, so only this flag writes — `josh sync` and `josh doctor` never do.",
-			},
-		],
-	},
-	'audit:provision': {
-		examples: [
-			{ arguments: '', note: 'no-op if a scanner is already present' },
-			{ arguments: '--force', note: 'ignore backoff, allow a longer download' },
-		],
-		flags: [
-			{
-				names: ['--force'],
-				description:
-					'ignore the 6-hour failure backoff and allow a longer download window; the command to run after fixing a network problem.',
-			},
-		],
-	},
-	'reconcile-templates': {
-		examples: [
-			{ arguments: '', note: 'regenerate copy templates + record tripwire hashes' },
-			{ arguments: CHECK, note: 'verify templates are in sync; non-zero on drift' },
-		],
-		flags: [
-			{
-				names: [CHECK],
-				description:
-					'verify only; exits non-zero on drift. A pre-commit hook runs this when a tracked source or copy template is staged.',
-			},
-		],
-	},
-	'pre-push-unit': { examples: [{ arguments: '' }] },
-	'reserved-run': {
-		examples: [
-			{ arguments: '2 -- pnpm install', note: 'hold 2 cores while installing' },
-			{ arguments: '1 -- pnpm josh audit', note: 'hold 1 core while scanning' },
-		],
-	},
-	'pre-commit-type-check': { examples: [{ arguments: '' }] },
-	'pr:classification': {
-		examples: [{ arguments: '', note: 'run by CI on a pull request; fails without one label' }],
-	},
-	'observation:record': {
-		examples: [
-			{ arguments: "flaky-e2e d1 'tests/e2e/login.test.ts' 'times out on CI only'" },
-			{
-				arguments: "flaky-e2e d1 'src/app.ts' 'fails there too' --checkout ~/Development/app",
-				note: "another repository's ledger",
-			},
-		],
-		flags: [
-			{
-				names: ['--checkout <path>'],
-				description: "count and append in that repository's `.josh/observations/` instead.",
-			},
-		],
-	},
-	'release:github': {
-		examples: [
-			{ arguments: '', note: 'run by CI with GH_TOKEN, RELEASE_TAG and GITHUB_REPOSITORY set' },
-		],
-	},
-	'latest:scope': {
-		examples: [
-			{ arguments: '', note: 'required or skip, the reason on stderr' },
-			{ arguments: '--record', note: 'note a finished josh latest run' },
-			{ arguments: JSON_FLAG, note: 'the verdict and the reason as JSON' },
-		],
-		flags: [
-			{ names: ['--record'], description: 'write the completion record `josh latest` ends with.' },
-			{ names: [JSON_FLAG], description: 'emit the verdict and its reason as JSON.' },
-		],
-	},
-	'latest:guard': { examples: [{ arguments: '', note: 'refuses inside a lane' }] },
-	'prevent-main-commit': { examples: [{ arguments: '', note: 'run by the pre-commit hook' }] },
-	'check-commit-message': {
-		examples: [{ arguments: '.git/COMMIT_EDITMSG', note: 'run by the commit-msg hook' }],
-	},
-	'secretlint-scan': {
-		examples: [{ arguments: 'src/app.ts .env.example', note: 'the staged paths' }],
-	},
-	'pre-commit-lint': {
-		examples: [
-			{ arguments: 'cspell src/app.ts' },
-			{ arguments: 'prettier src/app.ts' },
-			{ arguments: 'eslint src/app.ts' },
-		],
-	},
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-
-export { WORKFLOW_USAGE }

package/scripts/lint/cross-file-recheck.ts

@@ -1,155 +0,0 @@
-import { FAIL_EXIT_CODE, type BufferedProcessResult } from '#scripts/lib/buffered-process'
-import type { ESLint } from 'eslint'
-
-// Some rules read other files, and the lint cache keys a verdict on the linted file's own content.
-// So once the other file is fixed, the untouched one keeps its cached error until its own content
-// changes. `import/no-cycle` did it first (joshuafolkken/kit#3641): a cycle closed by editing one
-// side stayed reported on the other. The type-aware rules do it too (joshuafolkken/kit#3667): a call
-// to a function its module did not export yet stays `no-unsafe-call` after the export is added.
-//
-// A red lint run therefore re-reads its cached report: the files reported for a rule that reads
-// other files are linted once more without the cache, and their fresh results replace the cached
-// ones. A green run never reaches this, so the green path costs what it did.
-//
-// Which rules those are is the rule's own statement, never a list kept here: a type-aware rule
-// declares `requiresTypeChecking`, and the `import` plugin's rules resolve the modules they name.
-// That plugin answers to two names: the base config registers it as `import`, and its own preset —
-// whose rules a hand-authored `.js` file keeps — as `import-x`.
-//
-// Only a stale red is re-read. A stale green — the other file broke, the untouched one still
-// answers clean — is not something a report can point at; the type check is what catches it.
-//
-// That holds for a run narrowed to one change's files as much as for the whole tree: the change can
-// hold both files, and the one a later edit leaves alone keeps its cached report.
-//
-// The cached run is asked again through the Node API rather than read off the first run's report:
-// that report is the stylish text, and taking a file out of it means re-deriving its problem
-// counts. The second asking is answered from the cache the first one just wrote.
-const IMPORT_RULE_PATTERN = /^import(?:-x)?\//u
-const FORMATTER = 'stylish'
-const UNCACHED_SUFFIX = '.uncached'
-
-type RulesMeta = ESLint.LintResultData['rulesMeta']
-
-interface Linters {
-	cached: ESLint
-	fresh: ESLint
-}
-
-interface CrossFileRecheckOptions {
-	cache_file: string
-	// What the run linted — the whole tree, or one change's files — so the cached run is asked the
-	// question it was asked the first time.
-	patterns: ReadonlyArray<string>
-	// What the fixture test varies: the directory linted and the configuration it is linted with.
-	eslint_options?: ESLint.Options
-}
-
-// The exit code is eslint's "finished and reported problems", not any failure: a run that could not
-// finish — a configuration that does not load, a rule that threw — exits 2, and asking it again
-// throws the same error here, ahead of both buffered reports.
-function is_red(result: BufferedProcessResult): boolean {
-	return result.exit_code === FAIL_EXIT_CODE
-}
-
-// `requiresTypeChecking` is typescript-eslint's convention, which other type-aware plugins follow;
-// eslint's own type for a rule's docs does not name it.
-function is_type_aware(documentation: object | undefined): boolean {
-	if (documentation === undefined) return false
-
-	return 'requiresTypeChecking' in documentation && documentation.requiresTypeChecking === true
-}
-
-// A problem with no rule is the parser's, about the file itself.
-function reads_other_files(rule_id: string | null, rules_meta: RulesMeta): boolean {
-	if (rule_id === null) return false
-
-	return IMPORT_RULE_PATTERN.test(rule_id) || is_type_aware(rules_meta[rule_id]?.docs)
-}
-
-function suspects_of(linter: ESLint, cached: Array<ESLint.LintResult>): Array<string> {
-	const rules_meta = linter.getRulesMetaForResults(cached)
-
-	return cached
-		.filter((result) =>
-			result.messages.some((message) => reads_other_files(message.ruleId, rules_meta)),
-		)
-		.map((result) => result.filePath)
-}
-
-function cached_options(options: CrossFileRecheckOptions): ESLint.Options {
-	return {
-		...options.eslint_options,
-		cache: true,
-		cacheStrategy: 'content',
-		cacheLocation: options.cache_file,
-	}
-}
-
-// A linter that runs without a cache deletes the cache file it would have used, and that defaults to
-// the very file the lint run keeps. So the uncached linter is pointed at a sibling path nothing
-// ever writes: the re-reading must not cost the next run its whole cache.
-function fresh_options(options: CrossFileRecheckOptions): ESLint.Options {
-	return {
-		...options.eslint_options,
-		cache: false,
-		cacheLocation: `${options.cache_file}${UNCACHED_SUFFIX}`,
-	}
-}
-
-// `eslint` is loaded here, only past a red report: it is an optional peer a basic-profile
-// consumer may not have, and this module is imported by the entry of every `josh lint`, which has to
-// reach its skip notice there.
-async function create_linters(options: CrossFileRecheckOptions): Promise<Linters> {
-	const eslint = await import('eslint')
-
-	return {
-		cached: new eslint.ESLint(cached_options(options)),
-		fresh: new eslint.ESLint(fresh_options(options)),
-	}
-}
-
-async function lint_fresh(
-	linter: ESLint,
-	suspects: Array<string>,
-): Promise<Map<string, ESLint.LintResult>> {
-	const fresh = await linter.lintFiles(suspects)
-
-	return new Map(fresh.map((result) => [result.filePath, result]))
-}
-
-async function report(
-	linter: ESLint,
-	results: Array<ESLint.LintResult>,
-): Promise<Pick<BufferedProcessResult, 'output' | 'exit_code'>> {
-	const formatter = await linter.loadFormatter(FORMATTER)
-	const is_failed = results.some((result) => result.errorCount > 0)
-
-	return { output: await formatter.format(results), exit_code: is_failed ? FAIL_EXIT_CODE : 0 }
-}
-
-// A red about rules that read nothing else is handed back as the run reported it: its cached
-// verdicts are about the files they are keyed on.
-async function verify(
-	result: BufferedProcessResult,
-	options: CrossFileRecheckOptions,
-): Promise<BufferedProcessResult> {
-	if (!is_red(result)) return result
-	const started_at = performance.now()
-	const linters = await create_linters(options)
-	const cached = await linters.cached.lintFiles([...options.patterns])
-	const suspects = suspects_of(linters.cached, cached)
-	if (suspects.length === 0) return result
-	const fresh = await lint_fresh(linters.fresh, suspects)
-	const verified = await report(
-		linters.fresh,
-		cached.map((entry) => fresh.get(entry.filePath) ?? entry),
-	)
-
-	return { ...verified, elapsed_ms: result.elapsed_ms + performance.now() - started_at }
-}
-
-const cross_file_recheck = { verify }
-
-export type { CrossFileRecheckOptions }
-export { cross_file_recheck }

package/scripts/registry-migration/migrate-logic.ts

@@ -1,237 +0,0 @@
-import { fix_gh_packages_logic } from '#scripts/gh/fix-gh-packages-logic'
-
-const SCOPE = '@joshuafolkken'
-const REGISTRY_KEY = `${SCOPE}:registry`
-const PUBLIC_REGISTRY = 'https://registry.npmjs.org/'
-const GITHUB_REGISTRY = 'https://npm.pkg.github.com/'
-const MAPPING = `${REGISTRY_KEY}=${PUBLIC_REGISTRY}`
-const REGISTRY_VALUE_INDEX = 1
-const SPLIT_LIMIT = 2
-
-interface MigrationPlan {
-	content: string
-	packages: ReadonlyArray<string>
-	blocked: ReadonlyArray<string>
-	change: string
-}
-
-type IntegrityPair = readonly [string, string]
-
-function normalized_registry(value: string): string {
-	let normalized = value.trim()
-	while (normalized.endsWith('/')) normalized = normalized.slice(0, -1)
-
-	return `${normalized}/`
-}
-
-function mapping_lines(content: string): ReadonlyArray<string> {
-	return content.split(/\r?\n/u).filter((line) => line.trimStart().startsWith(`${REGISTRY_KEY}=`))
-}
-
-function registry_of(content: string): string | undefined {
-	const lines = mapping_lines(content)
-	if (lines.length !== 1) return undefined
-
-	return normalized_registry(lines[0]?.split('=', SPLIT_LIMIT)[REGISTRY_VALUE_INDEX] ?? '')
-}
-
-function scoped_packages(lockfile: string): ReadonlyArray<string> {
-	const packages = fix_gh_packages_logic.parse_lockfile_packages(lockfile)
-
-	return Object.keys(packages)
-		.filter((key) => key.startsWith(`${SCOPE}/`))
-		.map((key) => fix_gh_packages_logic.package_path_from_key(key))
-		.filter((name, index, names) => names.indexOf(name) === index)
-}
-
-function scoped_versions(lockfile: string): ReadonlyArray<readonly [string, string]> {
-	const packages = fix_gh_packages_logic.parse_lockfile_packages(lockfile)
-
-	return Object.keys(packages)
-		.filter((key) => key.startsWith(`${SCOPE}/`))
-		.map(
-			(key) =>
-				[
-					fix_gh_packages_logic.package_path_from_key(key),
-					fix_gh_packages_logic.package_version_from_key(key),
-				] as const,
-		)
-}
-
-function is_github_tarball(value: string): boolean {
-	try {
-		const url = new URL(value)
-
-		return url.protocol === 'https:' && url.hostname === 'npm.pkg.github.com'
-	} catch {
-		return false
-	}
-}
-
-function github_tarballs(lockfile: string): ReadonlyArray<string> {
-	const packages = fix_gh_packages_logic.parse_lockfile_packages(lockfile)
-
-	return Object.entries(packages)
-		.filter(
-			([key, entry]) =>
-				key.startsWith(`${SCOPE}/`) &&
-				entry.resolution?.tarball !== undefined &&
-				is_github_tarball(entry.resolution.tarball),
-		)
-		.map(([key]) => key)
-}
-
-function remove_flow_tarball(line: string): string {
-	const marker = ', tarball: https://npm.pkg.github.com/'
-	const start = line.indexOf(marker)
-	if (start === -1) return line
-	const end = line.indexOf('}', start)
-	if (end === -1) return line
-
-	return `${line.slice(0, start)}${line.slice(end)}`
-}
-
-function is_package_entry(line: string): boolean {
-	return /^ {2}[^ ]/u.test(line)
-}
-
-function is_github_tarball_line(line: string): boolean {
-	return line.trimStart().startsWith('tarball: https://npm.pkg.github.com/')
-}
-
-// Integrities are keyed by `name@version`, so two scoped packages sharing a version never collide.
-function package_id(key: string): string {
-	const name = fix_gh_packages_logic.package_path_from_key(key)
-
-	return `${name}@${fix_gh_packages_logic.package_version_from_key(key)}`
-}
-
-function clean_scoped_line(
-	line: string,
-	id: string,
-	integrities: ReadonlyMap<string, IntegrityPair>,
-): string | undefined {
-	if (!id) return line
-	if (is_github_tarball_line(line)) return undefined
-	const cleaned = remove_flow_tarball(line)
-	const pair = integrities.get(id)
-	if (pair === undefined) return cleaned
-
-	return cleaned.split(`integrity: ${pair[0]}`).join(`integrity: ${pair[1]}`)
-}
-
-function next_scoped_id(line: string, id: string): string {
-	if (!is_package_entry(line)) return id
-	const prefix = `  '${SCOPE}/`
-	if (!line.startsWith(prefix)) return ''
-
-	return package_id(line.slice("  '".length).split("'", 1)[0] ?? '')
-}
-
-function integrity_pair(
-	old_integrity: string | undefined,
-	npm_integrity: string | undefined,
-): IntegrityPair | undefined {
-	if (old_integrity === undefined || npm_integrity === undefined) return undefined
-
-	return [old_integrity, npm_integrity]
-}
-
-function lock_integrities(
-	lockfile: string,
-	npm_integrities: ReadonlyMap<string, string>,
-): Map<string, IntegrityPair> {
-	const packages = fix_gh_packages_logic.parse_lockfile_packages(lockfile)
-	const pairs = new Map<string, IntegrityPair>()
-	const scoped_entries = Object.entries(packages).filter(([key]) => key.startsWith(`${SCOPE}/`))
-
-	for (const [key, entry] of scoped_entries) {
-		const id = package_id(key)
-		const pair = integrity_pair(entry.resolution?.integrity, npm_integrities.get(id))
-		if (pair !== undefined) pairs.set(id, pair)
-	}
-
-	return pairs
-}
-
-function push_if_defined(lines: Array<string>, cleaned: string | undefined): void {
-	if (cleaned !== undefined) lines.push(cleaned)
-}
-
-function rewrite_scoped_lockfile(
-	lockfile: string,
-	npm_integrities: ReadonlyMap<string, string>,
-): string {
-	let id = ''
-	const lines: Array<string> = []
-	const integrities = lock_integrities(lockfile, npm_integrities)
-
-	for (const line of lockfile.split('\n')) {
-		id = next_scoped_id(line, id)
-		const cleaned = clean_scoped_line(line, id, integrities)
-
-		push_if_defined(lines, cleaned)
-	}
-
-	return lines.join('\n')
-}
-
-function append_mapping(content: string, eol: string): string {
-	const separator = content && !content.endsWith('\n') ? eol : ''
-
-	return `${content}${separator}${MAPPING}${eol}`
-}
-
-function replace_mapping(content: string): string {
-	const lines = mapping_lines(content)
-	const eol = content.includes('\r\n') ? '\r\n' : '\n'
-
-	if (lines.length === 0) return append_mapping(content, eol)
-
-	return content
-		.split(/\r?\n/u)
-		.map((line) => (line === lines[0] ? MAPPING : line))
-		.join(eol)
-}
-
-function unsupported_registry(project_npmrc: string): string | undefined {
-	const registry = registry_of(project_npmrc)
-
-	if (registry === undefined || [GITHUB_REGISTRY, PUBLIC_REGISTRY].includes(registry)) {
-		return undefined
-	}
-
-	return `unsupported project registry: ${registry}`
-}
-
-function has_duplicate_mapping(project_npmrc: string, user_npmrc: string): boolean {
-	return mapping_lines(project_npmrc).length > 1 || mapping_lines(user_npmrc).length > 1
-}
-
-function previous_registry(project_npmrc: string, user_npmrc: string): string {
-	return registry_of(project_npmrc) ?? registry_of(user_npmrc) ?? 'default npm'
-}
-
-function plan(project_npmrc: string, user_npmrc: string, lockfile: string): MigrationPlan {
-	const packages = scoped_packages(lockfile)
-	// Every scoped package may migrate; `migrate` blocks any whose locked version is not on public npm.
-	const blocked: Array<string> = []
-	if (has_duplicate_mapping(project_npmrc, user_npmrc)) blocked.push('duplicate registry mappings')
-	const unsupported = unsupported_registry(project_npmrc)
-	if (unsupported !== undefined) blocked.push(unsupported)
-	const before = previous_registry(project_npmrc, user_npmrc)
-	const change = `${before} → ${PUBLIC_REGISTRY}`
-
-	return { content: replace_mapping(project_npmrc), packages, blocked, change }
-}
-
-const migrate_logic = {
-	plan,
-	github_tarballs,
-	is_github_tarball,
-	rewrite_scoped_lockfile,
-	scoped_versions,
-}
-
-export { migrate_logic }
-export type { MigrationPlan }