@joshuafolkken/kit 1.978.0 → 1.998.0

package/scripts/init/start.ts

@@ -13,7 +13,7 @@ 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 static|node] [--yes] [--github] [--public]'
+const START_USAGE = 'josh start [--profile basic|full] [--yes] [--github] [--public]'
 const YES_FLAG = '--yes'
 const GITHUB_FLAG = '--github'
 const PUBLIC_FLAG = '--public'
@@ -72,7 +72,11 @@ function prepare(args: ReadonlyArray<string>, is_tty: boolean, root: string): Pr
 
 	stop_on(start_steps.github_cli_refusal(root))
 
-	return { steps: plan.steps, interaction, choices: { options, shape, consent, root } }
+	return {
+		steps: plan.steps,
+		interaction,
+		choices: { options, shape, consent, root, steps: plan.steps },
+	}
 }
 
 async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void> {
@@ -82,7 +86,7 @@ async function main(args: ReadonlyArray<string>, is_tty: boolean): Promise<void>
 	const profile = await resolve_profile(choices, interaction)
 	const { root, options } = choices
 
-	start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
+	await start_steps.run_steps(steps, { root, profile, visibility: options.visibility })
 	console.info(`\n${READY_MESSAGE}`)
 }
 

package/scripts/issue/issue-file-cli.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { repo_party } from '#scripts/discovery/repo-party'
+import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { issue_file, type FileArguments } from './issue-file'
+import { issue_lint_cli } from './issue-lint-cli'
+import { issue_scout_cli } from './issue-scout-cli'
+
+// `josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>]…
+// [--repo <owner/repo>] [--distinct <N,…>]` — file an Issue with every filing step run in order
+// (joshuafolkken/kit#2808): the third-party refusal, the body lint, the `## Origin` check for another
+// repository, the duplicate scout, the create call carrying every label, and `epic:bundle` after it.
+// A direct `gh api …/issues` filing is refused by the `direct-filing` delivered rule and pointed here.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE =
+	'Usage: josh issue:file "<title>" --body-file <path> --depth <0|1|2> [--route <tier-a|split|interrupt|review-cap>] [--label <name>]… [--repo <owner/repo>] [--distinct <N,…>]'
+const UNKNOWN_REPO_MESSAGE =
+	'Could not read this repository from `git remote`, so the filing has no repository to compare against — check `gh auth status`.'
+const THIRD_PARTY_MESSAGE =
+	'✖ third-party target: a tracker we do not own is Tier C — draft the Issue for a person to post instead (`CLAUDE.md` → "Third-party repositories are Tier C").'
+// `GH_REPO` is the variable `gh` reads `{owner}/{repo}` from, so setting it points every listing the
+// scout and `epic:bundle` make at the target repository rather than at this checkout.
+const GH_REPO_VARIABLE = 'GH_REPO'
+
+interface Filing {
+	args: FileArguments
+	body: string
+	target: string
+	current: string
+}
+
+async function read_body(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function is_third_party(target: string): boolean {
+	const party = repo_party.classify(repo_party.current_owner(), repo_party.target_owner(target))
+
+	return party === repo_party.THIRD_PARTY
+}
+
+// Every refusal the filing can meet before a request is sent, in the order the steps run — `[]` when
+// the filing may go on to the scout.
+function refusals_of(filing: Filing): ReadonlyArray<string> {
+	if (is_third_party(filing.target)) return [THIRD_PARTY_MESSAGE]
+	const problems = issue_lint_cli.problems(filing.body).map((problem) => `✖ ${problem}`)
+	const origin = issue_file.origin_problem(filing.body, filing.target, filing.current)
+
+	return origin === undefined ? problems : [...problems, `✖ ${origin}`]
+}
+
+function unacknowledged_message(numbers: ReadonlyArray<number>): string {
+	const listed = numbers.map(String).join(',')
+
+	return `✖ duplicate candidate(s) ${listed} not declared separate — read each (\`issue-fold-existing.md\`); fold into a duplicate, or reissue with \`--distinct ${listed}\` when each is a separate deliverable.`
+}
+
+// Set before the scout and left set for `epic:bundle`, so both read the target's backlog.
+function point_listings_at(filing: Filing): void {
+	if (issue_file.is_same_repository(filing.target, filing.current)) return
+
+	process.env[GH_REPO_VARIABLE] = filing.target
+}
+
+// The scout's report is printed whatever it finds, and the filing is held until every candidate it
+// names is declared separate.
+async function is_scout_clear(filing: Filing): Promise<boolean> {
+	point_listings_at(filing)
+	const outcome = await issue_scout_cli.scout(
+		{ title: filing.args.title, body: filing.body },
+		filing.target,
+	)
+
+	if (outcome === undefined) return false
+	console.info(outcome.report)
+	const open = issue_file.unacknowledged(outcome.candidates, filing.args.distinct)
+
+	if (open.length > 0) console.error(unacknowledged_message(open))
+
+	return open.length === 0
+}
+
+// `undefined` when the create call failed. `gh`'s standard error is captured into the thrown error
+// rather than printed, so it is printed here — otherwise the filing fails with no reason given.
+async function create(filing: Filing): Promise<string | undefined> {
+	const request = git_gh_issue_write.issue_create_request({
+		title: filing.args.title,
+		body: filing.body,
+		labels: issue_file.labels_of(filing.args, filing.body),
+		repo: filing.target,
+	})
+
+	try {
+		return await git_gh_exec.exec_gh_api(request)
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+
+		console.error(`✖ the create call failed: ${reason}`)
+
+		return undefined
+	}
+}
+
+// The Issue exists once `create` returns, so a failed placement is reported rather than failed: a
+// non-zero exit would read as "not filed" and invite the second filing the scout exists to stop.
+async function place(url: string, target: string): Promise<void> {
+	const issue_number = Number(github_issue_url.parse(url)?.issue_number)
+	const exit_code = Number.isSafeInteger(issue_number)
+		? await epic_bundle_cli.report_for(issue_number, target)
+		: FAILURE_EXIT_CODE
+
+	if (exit_code !== SUCCESS_EXIT_CODE) {
+		console.error(`⚠ epic:bundle did not answer for ${url} — run \`pnpm josh epic:bundle <N>\`.`)
+	}
+}
+
+async function file(filing: Filing): Promise<number> {
+	const refusals = refusals_of(filing)
+
+	if (refusals.length > 0) {
+		console.error(refusals.join('\n'))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	if (!(await is_scout_clear(filing))) return FAILURE_EXIT_CODE
+	const url = await create(filing)
+
+	if (url === undefined) return FAILURE_EXIT_CODE
+	console.info(url)
+	await place(url, filing.target)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function filing_of(args: FileArguments): Promise<Filing | string> {
+	const body = await read_body(args.body_file)
+
+	if (body === undefined) return `Could not read the body file ${args.body_file}.`
+	const current = await git_gh_command.repo_get_name_with_owner()
+
+	if (current === undefined) return UNKNOWN_REPO_MESSAGE
+
+	return { args, body, target: args.repo ?? current, current }
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const args = issue_file.parse(argv)
+
+	if (args === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const filing = await filing_of(args)
+
+	if (typeof filing === 'string') {
+		console.error(filing)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await file(filing)
+}
+
+// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_file_cli = { USAGE, THIRD_PARTY_MESSAGE, UNKNOWN_REPO_MESSAGE, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_file_cli }

package/scripts/issue/issue-file.ts

@@ -0,0 +1,192 @@
+import { parseArgs } from 'node:util'
+import { epic_issue } from '#scripts/epic/epic-issue'
+import { github_issue_url } from '#scripts/git/github-issue-url'
+import { DEPTH_LABEL_ORDER, FILING_ROUTE_LABELS, has_label_name } from '#scripts/git/issue-labels'
+import { issue_backlinks } from './issue-backlinks'
+import { issue_classification } from './issue-classification'
+import { markdown_section } from './markdown-section'
+
+// The decisions behind `josh issue:file` (joshuafolkken/kit#2808), kept apart from the command that
+// reads the network so each one is a pure answer a test can pin. Every filing used to be a hand-built
+// `gh api …/issues` call beside five steps spread over as many documents, and joshuafolkken/kit#2805
+// ran two of them and skipped the lint and the labels. Here the steps are the command's arguments:
+// a label the filing owes is a required option rather than a line to remember.
+
+const DEPTH_PREFIX = 'depth:'
+const ROUTE_PREFIX = 'route:'
+const LIST_SEPARATOR = ','
+const WORD_SEPARATOR = /\s+/u
+const CODE_SPAN = /`/gu
+// Prose written against a reference with no space — `(owner/repo#N)`, `owner/repo#N。`, Japanese text
+// after the number — is trimmed off, so the anchored parsers below still see the reference itself.
+const LEADING_NON_WORD = /^[^\w]+/u
+const DIGIT = /\d/u
+
+interface FileArguments {
+	title: string
+	body_file: string
+	depth: string
+	route: string | undefined
+	labels: ReadonlyArray<string>
+	repo: string | undefined
+	distinct: ReadonlyArray<number>
+}
+
+const OPTIONS = {
+	'body-file': { type: 'string' },
+	depth: { type: 'string' },
+	route: { type: 'string' },
+	label: { type: 'string', multiple: true },
+	repo: { type: 'string' },
+	distinct: { type: 'string', multiple: true },
+} as const
+
+// The label a `--depth` / `--route` value names, or `undefined` when it names none — read against the
+// label sets `issue-labels.ts` defines, so the command cannot apply a depth or route nobody provisions.
+function label_of(
+	prefix: string,
+	value: string | undefined,
+	known: ReadonlyArray<string>,
+): string | undefined {
+	if (value === undefined) return undefined
+	const label = value.startsWith(prefix) ? value : `${prefix}${value}`
+
+	return known.includes(label) ? label : undefined
+}
+
+const ROUTE_NAMES: ReadonlyArray<string> = FILING_ROUTE_LABELS.map((label) => label.name)
+
+// `--distinct 12,34 --distinct 56` → `[12, 34, 56]`; `undefined` when any entry is not an issue number,
+// so a typo is refused rather than read as an acknowledgement of nothing.
+function distinct_numbers(values: ReadonlyArray<string>): ReadonlyArray<number> | undefined {
+	const numbers = values
+		.flatMap((value) => value.split(LIST_SEPARATOR))
+		.map((raw) => {
+			return Number(raw.trim().replace('#', ''))
+		})
+
+	return numbers.every((number) => Number.isSafeInteger(number) && number > 0) ? numbers : undefined
+}
+
+type ParsedValues = ReturnType<typeof parseArgs<{ options: typeof OPTIONS }>>['values']
+
+function route_of(values: ParsedValues): string | undefined | false {
+	if (values.route === undefined) return undefined
+
+	return label_of(ROUTE_PREFIX, values.route, ROUTE_NAMES) ?? false
+}
+
+function has_text(value: string | undefined): value is string {
+	return value !== undefined && value.trim() !== ''
+}
+
+// The labelled half of the arguments, or `undefined` when a depth, route or `--distinct` entry is not
+// one the command knows.
+function labelled_of(
+	values: ParsedValues,
+): Pick<FileArguments, 'depth' | 'route' | 'distinct'> | undefined {
+	const depth = label_of(DEPTH_PREFIX, values.depth, DEPTH_LABEL_ORDER)
+	const route = route_of(values)
+	const distinct = distinct_numbers(values.distinct ?? [])
+
+	if (route === false || depth === undefined || distinct === undefined) return undefined
+
+	return { depth, route, distinct }
+}
+
+function arguments_of(values: ParsedValues, title: string | undefined): FileArguments | undefined {
+	const labelled = labelled_of(values)
+	const body_file = values['body-file']
+
+	if (labelled === undefined || !has_text(title) || !has_text(body_file)) return undefined
+
+	return { title, body_file, ...labelled, labels: values.label ?? [], repo: values.repo }
+}
+
+// An unknown flag makes `parseArgs` throw; caught so the answer is the usage line, not a stack trace.
+function parse(argv: ReadonlyArray<string>): FileArguments | undefined {
+	try {
+		const { values, positionals } = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			allowPositionals: true,
+		})
+
+		return arguments_of(values, positionals[0])
+	} catch {
+		return undefined
+	}
+}
+
+// A classification label is the body's to declare, so an extra `--label` naming one the body does not
+// declare is dropped rather than applied — the label then always matches what `issue:lint` reads.
+function is_undeclared_classification(label: string, body: string): boolean {
+	const is_classification = has_label_name(issue_classification.CLASSIFICATION_LABELS, label)
+
+	return is_classification && !has_label_name(issue_classification.required_labels(body), label)
+}
+
+// Every label the filing carries: the depth, the route when there is one, the classification labels
+// the body declares (`issue_classification.labels_for`, which merges case-insensitively), then any
+// extra `--label`. One request applies them all, so no label is a separate step to forget.
+function labels_of(args: FileArguments, body: string): ReadonlyArray<string> {
+	const extra = args.labels.filter((label) => !is_undeclared_classification(label, body))
+	const declared = [args.depth, ...(args.route === undefined ? [] : [args.route]), ...extra]
+
+	return issue_classification.labels_for(body, declared)
+}
+
+function is_same_repository(target: string, current: string): boolean {
+	return target.toLowerCase() === current.toLowerCase()
+}
+
+// `owner/repo#N` or a github.com issue URL — the qualified forms the issue template's backlink section
+// requires, never a bare `#N`, which resolves to whichever repository renders it. Read through the
+// parsers that already know both forms rather than a third pattern.
+function without_trailing_prose(text: string): string {
+	let end = text.length
+
+	while (end > 0 && !DIGIT.test(text.charAt(end - 1))) end -= 1
+
+	return text.slice(0, end)
+}
+
+function is_qualified_reference(word: string): boolean {
+	const bare = without_trailing_prose(word.replaceAll(CODE_SPAN, '').replace(LEADING_NON_WORD, ''))
+
+	return (
+		epic_issue.parse_epic_reference(bare)?.repo !== undefined ||
+		github_issue_url.parse(bare) !== undefined
+	)
+}
+
+function cites_origin(line: string): boolean {
+	return line.split(WORD_SEPARATOR).some((word) => is_qualified_reference(word))
+}
+
+// Why a cross-repository filing is refused, or `undefined` when it is not refused. A filing into the
+// session's own repository owes no `## Origin`; one into another repository owes the section with a
+// qualified reference back to the Issue that found it (`issue-template.md`, the backlink section).
+function origin_problem(body: string, target: string, current: string): string | undefined {
+	if (is_same_repository(target, current)) return undefined
+	const lines = markdown_section.section_lines(body, issue_backlinks.ORIGIN_HEADING)
+
+	if (lines.some((line) => cites_origin(line))) return undefined
+
+	return `filing into ${target} from ${current} needs a \`${issue_backlinks.ORIGIN_HEADING}\` section citing the originating Issue as \`owner/repo#N\` or its URL`
+}
+
+// The duplicate candidates the caller has not declared separate. The scan cannot tell a duplicate from
+// a neighbor — that is a reading of each candidate (`issue-fold-existing.md`) — so the command holds
+// the filing until every candidate it printed is named back with `--distinct`.
+function unacknowledged(
+	candidates: ReadonlyArray<number>,
+	distinct: ReadonlyArray<number>,
+): ReadonlyArray<number> {
+	return candidates.filter((candidate) => !distinct.includes(candidate))
+}
+
+const issue_file = { parse, labels_of, origin_problem, unacknowledged, is_same_repository }
+
+export type { FileArguments }
+export { issue_file }

package/scripts/issue/issue-lint-cli.ts

@@ -58,7 +58,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv[0])
 }
 
-const issue_lint_cli = { run, OK_MESSAGE, USAGE }
+const issue_lint_cli = { problems, run, OK_MESSAGE, USAGE }
 
 const ARGV_OFFSET = 2
 

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

@@ -7,18 +7,17 @@ import { epic_bundle, type BacklogIssue, type BundleDecision } from '#scripts/ep
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
 import { git_gh_command } from '#scripts/git/git-gh-command'
-import { EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
-import { PAGE_CEILING_CAUSE } from '#scripts/git/listing-cutoff'
-import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
-import { issue_label_schema } from '#scripts/git/schemas'
 import { issue_citation } from '#scripts/rules/issue-citation'
-import { z } from 'zod'
 import {
 	issue_scout,
 	type DuplicateCandidate,
 	type DuplicateSearch,
 	type ScoutIssue,
 } from './issue-scout'
+import { issue_scout_closed, type ClosedScan } from './issue-scout-closed'
+
+const { CLOSED_CEILING_LINE, CLOSED_UNREADABLE_LINE, read_recently_closed, warn_about_closed } =
+	issue_scout_closed
 
 // `josh issue:scout "<title>" [--body "<summary>"]` — before an issue is filed, answer the two
 // questions every `new` entry point asks first: has this already been filed, and which epic does it
@@ -44,87 +43,6 @@ const UNKNOWN_REPO_MESSAGE =
 // to be one. Zero is not a valid issue number, so it collides with nothing in the listing.
 const DRAFT_NUMBER = 0
 
-// How far back the closed half of the scan reaches (joshuafolkken/kit#1679). One page: the duplicate
-// this half exists to catch closed hours ago, not months, and the listing is ordered by update so
-// the newest hundred already covers a run's own day several times over.
-//
-// **It is a window, not a cut, which is why reaching it is not warned about.** Every other listing in
-// this command reports its `limit` as a gap, because there the caller wanted the whole backlog and
-// got part of it; here the hundredth-most-recently-updated closed issue is where the question itself
-// stops. A warning printed on every invocation in any repository with a hundred closed issues would
-// carry no signal and would train a reader past the gap lines beside it that do. **The page ceiling
-// is still reported**, and `ClosedScan` below says why the two are not the same event.
-const CLOSED_LIMIT = 100
-
-// Read through `has_any_label` rather than compared directly, for the casing reason
-// `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
-const EPIC_LABELS: ReadonlySet<string> = new Set([EPIC_LABEL])
-
-// The listing's own label shape, not a second spelling of it: a copy here would be the drift the
-// shared schema module exists to prevent.
-const closed_labels_schema = z.array(issue_label_schema).optional()
-
-const closed_row_schema = z.object({
-	number: z.number(),
-	title: z.string().nullable(),
-	labels: closed_labels_schema,
-})
-
-type ClosedRow = z.infer<typeof closed_row_schema>
-
-// `rows` is `undefined` — never `[]` — when the listing failed: "nothing closed recently" is the
-// answer that sends a run straight on to file the duplicate, which is the failure this half was
-// added to prevent.
-function to_closed_row(row: ClosedRow): ScoutIssue {
-	return {
-		number: row.number,
-		title: row.title ?? '',
-		is_closed: true,
-		// A closed epic is still a container, and `epic_bundle_cli`'s marking cannot reach it: that one
-		// is built from the *open* epic listing. Reported as a duplicate it reads as "this work is
-		// already done" against an epic that never had an implementation of its own.
-		is_epic: has_any_label(row.labels, EPIC_LABELS),
-	}
-}
-
-function to_closed_rows(json: string): Array<ScoutIssue> | undefined {
-	const rows = parse_json_array_or_undefined(json, closed_row_schema)
-
-	return rows?.map((row) => to_closed_row(row))
-}
-
-// The rows, and whether the **page ceiling** stopped the paging short of the window. That is a
-// different thing from the `limit` above, which is the window itself: pull requests are filtered out
-// client-side, so a repository whose recent closures are mostly merged pull requests can select
-// fewer than `CLOSED_LIMIT` issue rows while the listing still has more to give. The scan then covers
-// less than it was asked for, which `git-gh-issue.ts`'s disposition table records as a warning.
-interface ClosedScan {
-	rows: Array<ScoutIssue> | undefined
-	is_capped: boolean
-}
-
-async function read_recently_closed(): Promise<ClosedScan> {
-	const { json, is_capped } = await git_gh_command.issue_list_recently_closed(CLOSED_LIMIT)
-
-	return { rows: json === undefined ? undefined : to_closed_rows(json), is_capped }
-}
-
-// The open half already ran, so both of these are gaps in the answer rather than failures of it —
-// the same disposition every other truncated listing in this command takes.
-const CLOSED_UNREADABLE_LINE =
-	'⚠ The recently closed issues could not be read, so the scan below covers open issues only — work that finished hours ago will not appear in it.'
-const CLOSED_CEILING_LINE = `⚠ The recently closed listing ${PAGE_CEILING_CAUSE}, so a duplicate that closed inside the window may not be below.`
-
-function warn_about_closed(scan: ClosedScan): void {
-	if (scan.rows === undefined) {
-		console.error(CLOSED_UNREADABLE_LINE)
-
-		return
-	}
-
-	if (scan.is_capped) console.error(CLOSED_CEILING_LINE)
-}
-
 interface ScoutArguments {
 	title: string
 	body: string
@@ -333,28 +251,32 @@ function format_epic_answer(
 // are still being worked on, and a closed one can neither gain a sibling nor be recommended as an
 // epic — so widening the placement pool with them would answer a different question from the one it
 // was asked (joshuafolkken/kit#1679).
+function duplicates_of(
+	draft: BacklogIssue,
+	issues: ReadonlyArray<BacklogIssue>,
+	closed: ReadonlyArray<ScoutIssue>,
+): DuplicateSearch {
+	const references = epic_audit_logic.parse_references(draft.body, draft.repo)
+
+	return issue_scout.find_duplicates(draft.title ?? '', [...issues, ...closed], references)
+}
+
 function format_report(
 	draft: BacklogIssue,
 	issues: ReadonlyArray<BacklogIssue>,
 	is_membership_established: boolean,
 	closed: ReadonlyArray<ScoutIssue> = [],
 ): string {
-	const references = epic_audit_logic.parse_references(draft.body, draft.repo)
-	const duplicates = issue_scout.find_duplicates(
-		draft.title ?? '',
-		[...issues, ...closed],
-		references,
-	)
 	const decision = epic_bundle.decide_bundle(draft, issues)
 
 	return [
-		format_duplicates(duplicates),
+		format_duplicates(duplicates_of(draft, issues, closed)),
 		format_epic_answer(draft, decision, issues, is_membership_established),
 	].join('\n')
 }
 
 type Widened = Awaited<ReturnType<typeof epic_bundle_cli.widen_with_referenced>>
-type ClosedListing = Awaited<ReturnType<typeof read_recently_closed>>
+type ClosedListing = ClosedScan
 
 function is_duplicate_scan_incomplete(widened: Widened, closed: ClosedListing): boolean {
 	const has_open_gap = widened.cutoff !== undefined && widened.cutoff !== 'none'
@@ -397,16 +319,23 @@ function linkified_report(
 	return issue_citation.linkify(qualified, repo)
 }
 
+// The scan's answer in both shapes it is read in: the report a person reads, and the candidate numbers
+// `issue:file` holds a filing to (joshuafolkken/kit#2808).
+interface ScoutOutcome {
+	report: string
+	candidates: ReadonlyArray<number>
+}
+
 // The backlog is read without its `blocked-by` relations: a draft has no number, so no recorded
 // dependency can name it and it declares none — the reads cannot change either half of the answer,
 // and skipping them takes one request per open issue off the command a run makes before every filing.
-async function report(args: ScoutArguments, repo: string): Promise<number> {
+async function scout(args: ScoutArguments, repo: string): Promise<ScoutOutcome | undefined> {
 	const backlog = await epic_bundle_cli.read_backlog(repo, { include_relations: false })
 
 	if (!backlog.is_readable) {
 		console.error(epic_bundle_cli.unreadable_backlog_message(backlog))
 
-		return FAILURE_EXIT_CODE
+		return undefined
 	}
 
 	const draft = draft_of(args, repo)
@@ -420,9 +349,22 @@ async function report(args: ScoutArguments, repo: string): Promise<number> {
 
 	epic_bundle_cli.warn_about_gaps(widened)
 	warn_about_closed(closed)
+	const duplicates = duplicates_of(draft, widened.issues, closed.rows ?? [])
+
 	// The same cut `warn_about_gaps` reports on standard error, read once more so standard output is
 	// held to it too — a ⚠ beside an executable instruction is not what stops a run acting on it.
-	console.info(linkified_report(draft, widened, closed, repo))
+	return {
+		report: linkified_report(draft, widened, closed, repo),
+		candidates: duplicates.candidates.map((candidate) => candidate.number),
+	}
+}
+
+async function report(args: ScoutArguments, repo: string): Promise<number> {
+	const outcome = await scout(args, repo)
+
+	if (outcome === undefined) return FAILURE_EXIT_CODE
+
+	console.info(outcome.report)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -473,10 +415,12 @@ const issue_scout_cli = {
 	format_duplicates,
 	format_epic_decision,
 	format_report,
+	scout,
 	run,
 	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
+export type { ScoutArguments, ScoutOutcome }
 export { issue_scout_cli }