@joshuafolkken/kit 1.1435.0 → 1.1455.0

package/scripts/init/start-dry-run.ts

@@ -0,0 +1,70 @@
+import path from 'node:path'
+import { repository_labels } from '#scripts/repo/repository-labels'
+import { init_dry_run } from './init-dry-run'
+import type { ProjectProfile } from './project-profile'
+import type { StartStep } from './start-plan'
+import type { Choices } from './start-prompt'
+import { start_setup_pr } from './start-setup-pr'
+import { workflow_mark } from './workflow-mark'
+
+// What `josh start --dry-run` adds to the plan `josh start` prints: what each GitHub step would
+// create, and what its setup step would write. Nothing here creates, pushes or writes (#3830).
+
+const TITLE = 'josh start --dry-run — nothing was written. Its setup step would:'
+const NONE = '(none)'
+const UNREAD_LABELS =
+	'add the workflow labels it lacks — the repository’s labels could not be read to name them'
+
+// The labels are read from the repository when it already exists — the same listing the real step
+// compares against — and a repository this run would create has none.
+function label_line(steps: ReadonlyArray<StartStep>): string {
+	const repo = steps.includes('repository') ? undefined : '{owner}/{repo}'
+	const labels = repository_labels.planned_labels(repo)
+
+	if (labels === undefined) return UNREAD_LABELS
+
+	return `add the labels it lacks: ${labels.length === 0 ? NONE : labels.join(', ')}`
+}
+
+function github_lines({ steps, root, options }: Choices): Array<string> {
+	const lines: Readonly<Partial<Record<StartStep, string | undefined>>> = {
+		repository: `create the ${options.visibility} repository ${path.basename(root)} as origin, and push main`,
+		labels: steps.includes('labels') ? label_line(steps) : undefined,
+		setup_pr: `open the Issue "${start_setup_pr.SETUP_TITLE}" (or reuse the open one), push a branch named after it, and open a pull request into main`,
+	}
+
+	return steps.map((step) => lines[step]).filter((line) => line !== undefined)
+}
+
+function github_report(choices: Choices): string {
+	const lines = github_lines(choices).map((line) => `  ${line}`)
+
+	return ['GitHub:', ...(lines.length === 0 ? [`  ${NONE}`] : lines)].join('\n')
+}
+
+// A caller's setup command writes files kit cannot name, so it is named rather than simulated. Kit's
+// own setup runs on a scratch copy, told it sets up the GitHub workflow as the real step tells it,
+// with the repository the run would have created by then.
+function setup_report({ steps, root, options, shape }: Choices): string | undefined {
+	if (!steps.includes('initialize')) return undefined
+	const profile: ProjectProfile = options.profile ?? shape.profile
+
+	if (options.init_command !== undefined) {
+		return `The setup step would run ${options.init_command} --profile ${profile}, which is not simulated.`
+	}
+
+	workflow_mark.request()
+	const has_git = shape.has_git || steps.includes('git_init')
+
+	return init_dry_run.plan_report({ root, profile, has_git, is_install: true }, TITLE)
+}
+
+function report(choices: Choices): string {
+	const setup = setup_report(choices)
+	const sections = [github_report(choices), ...(setup === undefined ? [] : [setup])]
+
+	return `\n${sections.join('\n\n')}`
+}
+
+const start_dry_run = { report }
+export { start_dry_run }

package/scripts/init/start-plan.ts

@@ -7,6 +7,7 @@ interface StartOptions {
 	profile: ProjectProfile | undefined
 	is_yes: boolean
 	is_github: boolean
+	is_dry_run: boolean
 	visibility: Visibility
 	init_command: string | undefined
 	push_preflight_command: string | undefined
@@ -120,8 +121,9 @@ function has_commit(steps: ReadonlyArray<StartStep>): boolean {
 	return steps.some((step) => COMMIT_STEPS.has(step))
 }
 
+// A dry run asks nothing and changes nothing, so it needs neither a terminal nor `--yes`.
 function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interaction> {
-	if (options.is_yes) return { value: 'unattended', refusal: undefined }
+	if (options.is_yes || options.is_dry_run) return { value: 'unattended', refusal: undefined }
 	if (is_tty) return { value: 'interactive', refusal: undefined }
 
 	return {
@@ -133,13 +135,16 @@ function interaction_of(options: StartOptions, is_tty: boolean): Verdict<Interac
 
 // `--yes` accepts the detected defaults, never the creation of a public-facing resource: an
 // unattended run creates a repository, pushes, or opens the setup Issue and pull request only when
-// `--github` asks for it by name.
+// `--github` asks for it by name. A dry run writes to GitHub no more than it writes anywhere else, so
+// it lists the GitHub steps without that consent.
 function github_consent(
 	steps: ReadonlyArray<StartStep>,
 	options: StartOptions,
 	interaction: Interaction,
 ): Verdict<Consent> {
-	if (!has_push(steps) || options.is_github) return { value: 'granted', refusal: undefined }
+	const is_consented = options.is_github || options.is_dry_run
+
+	if (is_consented || !has_push(steps)) return { value: 'granted', refusal: undefined }
 	if (interaction === 'interactive') return { value: 'ask', refusal: undefined }
 
 	return {

package/scripts/init/start-setup-pr.ts

@@ -9,28 +9,19 @@ import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { kit_written_paths } from './kit-written-paths'
 import { start_exec } from './start-exec'
+import { working_tree } from './working-tree'
 
 const SETUP_TITLE = `Set up ${KIT_PACKAGE_NAME}`
 const SETUP_BODY = [
 	`Adds the files \`josh start\` wrote while setting up ${KIT_PACKAGE_NAME}, so main carries the`,
 	'rules, settings and workflows every later Issue is run with. Only the files the setup wrote are in',
-	'the pull request; anything else in the working tree is left as it was.',
+	'the pull request: `josh start` runs only on a working tree with nothing uncommitted.',
 ].join('\n')
 const NAME_ONLY = '--name-only'
 const NOTHING_TO_COMMIT = 'The kit setup has no changes to commit, so no pull request was opened.'
 const OPEN_SETUP_ISSUES_QUERY = `?state=open&labels=${IGNORE_FOR_RELEASE_LABEL}&per_page=100`
 const FIRST_SETUP_ISSUE_FILTER = `[.[] | select(.title == "${SETUP_TITLE}") | .number][0] // empty`
 
-// Listings are read NUL-separated (`-z`), so a path is never quoted — a name a caller's initialize
-// command wrote need not be ASCII the way kit's own are (#2872).
-function paths_of(output: string | undefined = ''): Array<string> {
-	return output.split('\0').filter((listed) => listed.length > 0)
-}
-
-function listing(args: ReadonlyArray<string>, root: string): Array<string> {
-	return paths_of(start_exec.git_read([...args, '-z'], root))
-}
-
 function setup_issue(issue_number: string): IssueInfo {
 	return git_issue.parse(`${SETUP_TITLE} ${issue_cite.plain(issue_number)}`)
 }
@@ -49,19 +40,10 @@ function is_setup_branch(branch: string | undefined): boolean {
 	return setup_branch_number(branch) !== undefined
 }
 
-// Untracked files the ignore rules let through, plus tracked files the setup changed — two plain
-// listings, so nothing has to be parsed out of `git status`.
-function changed_paths(root: string): Array<string> {
-	const untracked = listing(['ls-files', '--others', '--exclude-standard'], root)
-	const modified = listing(['diff', NAME_ONLY, 'HEAD'], root)
-
-	return [...untracked, ...modified]
-}
-
 // On the setup branch a failed commit left, that run's `git add` already staged its files, so they
 // read as changed before this run's command ran — the staged ones count as setup output (#2872).
 function carried_paths(root: string, current: string | undefined): Array<string> {
-	return is_setup_branch(current) ? listing(['diff', NAME_ONLY, '--cached'], root) : []
+	return is_setup_branch(current) ? working_tree.listing(['diff', NAME_ONLY, '--cached'], root) : []
 }
 
 // The Issue carries the release classification the pull request is opened with, so the PR step finds
@@ -124,13 +106,15 @@ function commit_kit_paths(paths: ReadonlyArray<string>, issue: IssueInfo, root:
 
 // A caller's initialize command writes files kit cannot name, so with a `baseline` — what was already
 // changed before that command ran — everything changed since joins kit's own files, while a change
-// the user had made before the run still stays out (#2872).
+// the user had made before the run still stays out (#2872). `josh start` refuses a dirty tree on
+// `main` (#3835), so the baseline there is empty; it still keeps the two apart on the setup branch a
+// failed commit left, where the re-run starts with that run's output uncommitted.
 function setup_paths(
 	root: string,
 	baseline: ReadonlyArray<string> | undefined,
 	current: string | undefined,
 ): Array<string> {
-	const changed = changed_paths(root)
+	const changed = working_tree.changed_paths(root)
 	const kit_paths = kit_written_paths.select(changed)
 
 	if (baseline === undefined) return kit_paths
@@ -161,6 +145,11 @@ async function open(root: string, baseline?: ReadonlyArray<string>): Promise<voi
 	await git_pr.create_with_issue_info(issue)
 }
 
-const start_setup_pr = { open, changed_paths, is_setup_branch }
+const start_setup_pr = {
+	SETUP_TITLE,
+	open,
+	changed_paths: working_tree.changed_paths,
+	is_setup_branch,
+}
 
 export { start_setup_pr }

package/scripts/init/start-steps.ts

@@ -15,6 +15,7 @@ import { start_exec } from './start-exec'
 import { start_plan, type GitState, type StartStep, type Visibility } from './start-plan'
 import { start_setup_pr } from './start-setup-pr'
 import { workflow_mark } from './workflow-mark'
+import { working_tree } from './working-tree'
 
 interface StepContext {
 	root: string
@@ -83,6 +84,17 @@ function git_identity_refusal(steps: ReadonlyArray<StartStep>, root: string): st
 		: undefined
 }
 
+// A repository with a history receives the setup as a commit, and the user's own uncommitted change to
+// a file kit also writes would land in it, so the tree must be clean before the first write (#3835).
+// The setup branch a failed commit or push left checked out is the exception: what is uncommitted
+// there is that run's own output, which the re-run resumes with. Without a commit there is nothing to
+// keep apart — the initial commit takes every file.
+function uncommitted_refusal(root: string, state: GitState): string | undefined {
+	if (!state.has_commits || start_setup_pr.is_setup_branch(state.branch)) return undefined
+
+	return working_tree.dirty_tree_refusal(root, 'josh start')
+}
+
 // `josh init` refuses to run inside the kit source repository by printing and setting the exit code
 // rather than throwing, so its step would pass and the later steps would commit and publish the
 // source repository. The same check is raised before the first write instead.
@@ -141,7 +153,9 @@ async function open_setup_pull_request(context: RunContext): Promise<void> {
 // What was already changed before the setup ran, read whenever a setup pull request will follow, so
 // it can tell the setup's files from the user's own (#2872). Kit's own `josh init` needs it as much as
 // a caller's command: its `josh format` rewrites the project's own sources, which kit cannot name, and
-// leaving them out failed the pull request's Prettier check.
+// leaving them out failed the pull request's Prettier check. On `main` it is empty, since a dirty tree
+// is refused there (#3835); it is kept for the setup branch a failed commit left, where the earlier
+// run's output is already uncommitted when the re-run starts.
 function baseline_of(
 	steps: ReadonlyArray<StartStep>,
 	context: StepContext,
@@ -239,6 +253,7 @@ const start_steps = {
 	github_cli_refusal,
 	git_identity_refusal,
 	self_run_refusal,
+	uncommitted_refusal,
 	run_steps,
 }
 export { start_steps }

package/scripts/init/start.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { error_text } from '#scripts/lib/error-message'
-import { project_profile, type ProjectProfile } from './project-profile'
+import { init_dry_run } from './init-dry-run'
+import { project_profile, type ProjectProfile, type ProjectShape } from './project-profile'
+import { start_dry_run } from './start-dry-run'
 import {
 	start_plan,
 	type Consent,
@@ -15,13 +17,14 @@ import { start_steps } from './start-steps'
 const ARGUMENT_START_INDEX = 2
 const READY_MESSAGE = 'GitHub workflow ready. Use kickoff new in your assistant to plan an Issue.'
 const START_USAGE =
-	'josh start [--profile basic|full] [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]'
+	'josh start [--profile basic|full] [--yes] [--github] [--public] [--dry-run] [--init-command <command>] [--push-preflight-command <command>]'
 const INIT_COMMAND_FLAG = '--init-command'
 const PUSH_PREFLIGHT_COMMAND_FLAG = '--push-preflight-command'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
-const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG])
+const { DRY_RUN_FLAG } = init_dry_run
+const SWITCHES: ReadonlySet<string> = new Set([YES_FLAG, GITHUB_FLAG, PUBLIC_FLAG, DRY_RUN_FLAG])
 
 interface Prepared {
 	steps: ReadonlyArray<StartStep>
@@ -67,6 +70,7 @@ function parse_start_options(args: ReadonlyArray<string>): StartOptions {
 		profile: project_profile.requested_profile(profile_args, START_USAGE),
 		is_yes: rest.includes(YES_FLAG),
 		is_github: rest.includes(GITHUB_FLAG),
+		is_dry_run: rest.includes(DRY_RUN_FLAG),
 		visibility: rest.includes(PUBLIC_FLAG) ? 'public' : 'private',
 		init_command: init.command,
 		push_preflight_command,
@@ -94,34 +98,34 @@ async function resolve_profile(
 	return await start_prompt.confirm_choices(choices)
 }
 
+function planned_steps(root: string, shape: ProjectShape): ReadonlyArray<StartStep> {
+	const state = start_steps.read_git_state(root, shape)
+	const plan = start_plan.plan_steps(state)
+
+	stop_on(plan.refusal)
+	stop_on(start_steps.uncommitted_refusal(root, state))
+
+	return plan.steps
+}
+
 // Every refusal is raised here, before the first write, so a run that stops here changed nothing.
 function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Prepared {
 	stop_on(start_steps.self_run_refusal(root))
 	const options = parse_start_options(args)
 	const interaction = settle(start_plan.interaction_of(options, is_tty))
 	const shape = project_profile.inspect_project(root, options.profile)
-	const plan = start_plan.plan_steps(start_steps.read_git_state(root, shape))
-
-	stop_on(plan.refusal)
-	const consent: Consent = settle(start_plan.github_consent(plan.steps, options, interaction))
+	const steps = planned_steps(root, shape)
+	const consent: Consent = settle(start_plan.github_consent(steps, options, interaction))
 
 	stop_on(start_steps.github_cli_refusal(root))
-	stop_on(start_steps.git_identity_refusal(plan.steps, root))
+	stop_on(start_steps.git_identity_refusal(steps, root))
 
-	return {
-		steps: plan.steps,
-		interaction,
-		choices: { options, shape, consent, root, steps: plan.steps },
-	}
+	return { steps, interaction, choices: { options, shape, consent, root, steps } }
 }
 
-async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
-	const { steps, interaction, choices } = prepare(args, is_tty, process.cwd())
-
+async function run_steps({ steps, interaction, choices }: Prepared): Promise<void> {
 	const { root, options } = choices
 	const { visibility, init_command, push_preflight_command } = options
-
-	console.info(start_plan.plan_summary(steps, start_plan.step_labels(init_command)))
 	const profile = await resolve_profile(choices, interaction)
 	const context = { root, profile, visibility, init_command, push_preflight_command }
 
@@ -129,6 +133,22 @@ async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void>
 	console.info(`\n${READY_MESSAGE}`)
 }
 
+// A dry run stops after the plan, adding what each step would create, before the first write.
+async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
+	const prepared = prepare(args, is_tty, process.cwd())
+	const { steps, choices } = prepared
+
+	console.info(start_plan.plan_summary(steps, start_plan.step_labels(choices.options.init_command)))
+
+	if (choices.options.is_dry_run) {
+		console.info(start_dry_run.report(choices))
+
+		return
+	}
+
+	await run_steps(prepared)
+}
+
 async function run(args: ReadonlyArray<string>, is_tty: boolean): Promise<number> {
 	try {
 		await main(args, is_tty)

package/scripts/init/working-tree.ts

@@ -0,0 +1,116 @@
+import { git_location_environment } from '#scripts/git/git-location-environment'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { start_exec } from './start-exec'
+
+const UNTRACKED_ARGUMENTS = ['ls-files', '--others', '--exclude-standard']
+// `--relative` keeps the listing to the project and its paths relative to it, the way `ls-files`
+// already reads them, for a project that sits below its repository's top level.
+const MODIFIED_ARGUMENTS = ['diff', '--name-only', '--relative', 'HEAD']
+// Under an unborn HEAD every indexed file is uncommitted, so the index itself is the listing.
+const INDEXED_ARGUMENTS = ['ls-files', '--cached']
+const HISTORY_ARGUMENTS = ['rev-list', '--max-count=1', '--all']
+const UNBORN_HEAD_EXIT_CODE = 1
+const NOT_A_REPOSITORY = 'not a git repository'
+
+// What a project's working tree holds that is not committed, read one way for every setup command:
+// the setup pull request tells the setup's files from the user's own with it, and `josh init` refuses
+// to write over it.
+
+// Listings are read NUL-separated (`-z`), so a path is never quoted — a name a caller's initialize
+// command wrote need not be ASCII the way kit's own are (#2872).
+function paths_of(output: string | undefined = ''): Array<string> {
+	return output.split('\0').filter((listed) => listed.length > 0)
+}
+
+function listing(args: ReadonlyArray<string>, root: string): Array<string> {
+	return paths_of(start_exec.git_read([...args, '-z'], root))
+}
+
+// Untracked files the ignore rules let through, plus tracked files changed since HEAD, staged or not
+// — two plain listings, so nothing has to be parsed out of `git status`.
+function changed_paths(root: string): Array<string> {
+	const untracked = listing(UNTRACKED_ARGUMENTS, root)
+	const modified = listing(MODIFIED_ARGUMENTS, root)
+
+	return [...untracked, ...modified]
+}
+
+// A read that failed is thrown rather than read as an empty listing: the refusal guards the user's
+// work, so a git that did not answer must never pass for a clean tree.
+function strict_listing(args: ReadonlyArray<string>, root: string): Array<string> {
+	const output = start_exec.git_read([...args, '-z'], root)
+
+	if (output === undefined) throw new Error(`git ${args.join(' ')} failed in ${root}`)
+
+	return paths_of(output)
+}
+
+type HeadState = 'born' | 'unborn' | 'absent'
+
+// Asked of git rather than of a `.git` beside the project, so a project below its repository's top
+// level is still found. `--verify --quiet` exits 1 for an unborn HEAD, and only `not a git repository`
+// (read under the C locale) proves there is no repository; any other failure is an unanswered
+// question, not a missing commit.
+function head_state(root: string): HeadState {
+	const { exit_code, stderr } = git_spawn_sync.run(['rev-parse', '--verify', '--quiet', 'HEAD'], {
+		cwd: root,
+		env: { ...git_spawn_sync.C_LOCALE, ...git_location_environment.location_free_environment() },
+	})
+
+	if (exit_code === 0) return 'born'
+	if (stderr.includes(NOT_A_REPOSITORY)) return 'absent'
+	if (exit_code === UNBORN_HEAD_EXIT_CODE) return 'unborn'
+	throw new Error(`git rev-parse could not read HEAD in ${root}`)
+}
+
+// An unborn HEAD is either the repository `josh start` has yet to make its first commit in, or an
+// orphan branch (`git checkout --orphan`) whose index still holds another branch's files — told
+// apart by whether any ref reaches a commit.
+function has_history(root: string): boolean {
+	const output = start_exec.git_read(HISTORY_ARGUMENTS, root)
+
+	if (output === undefined) throw new Error(`git ${HISTORY_ARGUMENTS.join(' ')} failed in ${root}`)
+
+	return output.trim().length > 0
+}
+
+// What the tracked files are compared with, or undefined when there is nothing to tell the user's
+// work from — a directory outside any repository, or a repository without any commit.
+function tracked_arguments(root: string): ReadonlyArray<string> | undefined {
+	const state = head_state(root)
+
+	if (state === 'born') return MODIFIED_ARGUMENTS
+	if (state === 'unborn' && has_history(root)) return INDEXED_ARGUMENTS
+
+	return undefined
+}
+
+function uncommitted_paths(root: string): Array<string> {
+	const tracked = tracked_arguments(root)
+
+	if (tracked === undefined) return []
+
+	const untracked = strict_listing(UNTRACKED_ARGUMENTS, root)
+	const modified = strict_listing(tracked, root)
+
+	return [...untracked, ...modified]
+}
+
+// The refusal a setup command stops with before its first write, or undefined when nothing is
+// uncommitted: what kit then writes would land in the same files as the user's own work, and
+// `git diff` could no longer tell the two apart.
+function dirty_tree_refusal(root: string, command: string): string | undefined {
+	const paths = uncommitted_paths(root)
+
+	if (paths.length === 0) return undefined
+
+	return [
+		`${command} refuses to run: the working tree has uncommitted changes.`,
+		...paths.map((listed) => `  ${listed}`),
+		`Commit them, or stash them with \`git stash push -u -- .\`, then run ${command} again.`,
+	].join('\n')
+}
+
+const working_tree = { listing, changed_paths, uncommitted_paths, dirty_tree_refusal }
+
+export { working_tree }