@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/build/build-commands.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env tsx
+import { rmSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { COMMAND_MAP } from '#scripts/josh/josh-command-map'
+import { BUNDLED_COMMAND_DIRECTORY, josh_in_process } from '#scripts/josh/josh-in-process'
+import { error_text } from '#scripts/lib/error-message'
+import { build } from 'esbuild'
+
+const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const OUT_DIR = path.join(PACKAGE_DIR, BUNDLED_COMMAND_DIRECTORY)
+
+// Each `is_bundled` command is pre-built to its own `dist/commands/<script basename>.js`, so a
+// consumer's `dist/josh.js` imports it under plain node instead of spawning tsx for its `.ts`
+// (joshuafolkken/kit#3328, `docs/maintainers/runtime-bundling.md`).
+//
+// **No code splitting, and that is why the import closure is checked.** Every entry is one
+// self-contained file, so every module it imports shares the entry's `import.meta.url`; a second
+// `process.argv[1] === fileURLToPath(import.meta.url)` guard inside the closure would fire with the
+// entry's own. `build-commands.test.ts` refuses a bundled command whose closure carries one.
+//
+// The bundle sits two levels under the package root, exactly as its source does under `scripts/`,
+// so a module that finds the package from its own `import.meta.url` resolves the same directory.
+function bundled_scripts(): Array<string> {
+	return Object.values(COMMAND_MAP)
+		.filter((entry) => entry.is_bundled === true)
+		.map((entry) => entry.script ?? '')
+}
+
+function entry_point(script: string): { in: string; out: string } {
+	const out = path.basename(josh_in_process.bundled_script_path(PACKAGE_DIR, script), '.js')
+
+	return { in: path.join(PACKAGE_DIR, script), out }
+}
+
+// Nothing in this checkout launches `dist/commands/` (kit's own `pnpm josh` runs the source), so the
+// directory is emptied first rather than pruned after, which drops the output of a command no longer
+// bundled.
+async function build_commands(out_directory: string = OUT_DIR): Promise<string> {
+	rmSync(out_directory, { recursive: true, force: true })
+	await build({
+		absWorkingDir: PACKAGE_DIR,
+		entryPoints: bundled_scripts().map((script) => entry_point(script)),
+		outdir: out_directory,
+		bundle: true,
+		platform: 'node',
+		format: 'esm',
+		target: 'node22',
+		packages: 'external',
+	})
+
+	return out_directory
+}
+
+async function main(): Promise<void> {
+	try {
+		console.info(`  ✔ ${await build_commands()} built`)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { build_commands, bundled_scripts, OUT_DIR }

package/scripts/build/build-hooks.ts

@@ -49,7 +49,7 @@ interface HookBundle {
 	out: string
 }
 
-// The three settings.json hooks, the Codex input adapter, and the three guards `pretool-guard`
+// The settings.json hooks (the session-start audit provisioner among them), the Codex input adapter, and the three guards `pretool-guard`
 // composes: `batch-guard`, `investigation-guard` and `duplicate-read-guard` each self-invoke, so they
 // must be their own entries to keep their `import.meta.url` out of `pretool-guard`'s file.
 // `delivered-rules` (the fourth guard) has no self-invoke, so it stays inlined.
@@ -59,6 +59,7 @@ const HOOK_BUNDLES: ReadonlyArray<HookBundle> = [
 	{ source: 'scripts/hooks/stop-guard.ts', out: 'stop-guard' },
 	{ source: 'scripts/hooks/format-edited-cli.ts', out: 'format-edited' },
 	{ source: 'scripts/josh/session-language-cli.ts', out: 'session-lang' },
+	{ source: 'scripts/security/security-audit-provision.ts', out: 'audit-provision' },
 	{ source: 'scripts/hooks/batch-guard.ts', out: 'batch-guard' },
 	{ source: 'scripts/delegation/investigation-guard.ts', out: 'investigation-guard' },
 	{ source: 'scripts/delegation/duplicate-read-guard.ts', out: 'duplicate-read-guard' },

package/scripts/build/build-library.ts

@@ -7,6 +7,13 @@ import { dts } from 'rollup-plugin-dts'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const SCRIPTS_IMPORT_PREFIX = '#scripts/'
+// Every public library `pnpm build` bundles — each one a `./<name>` export in package.json.
+const PUBLIC_LIBRARIES: ReadonlyArray<string> = [
+	'version',
+	'config-merge',
+	'managed-marker',
+	'self-sync-guard',
+]
 
 interface LibraryPaths {
 	entry_point: string
@@ -73,11 +80,13 @@ async function build_library_dts(entry_point: string, dts_file: string): Promise
 async function build_library(name: string): Promise<LibraryPaths> {
 	const paths = library_paths(name)
 
-	await build_library_js(paths.entry_point, paths.outfile)
-	await build_library_dts(paths.entry_point, paths.dts_file)
+	await Promise.all([
+		build_library_js(paths.entry_point, paths.outfile),
+		build_library_dts(paths.entry_point, paths.dts_file),
+	])
 
 	return paths
 }
 
 export type { LibraryPaths }
-export { build_library, library_paths }
+export { build_library, library_paths, PUBLIC_LIBRARIES }

package/scripts/build/build.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { error_text } from '#scripts/lib/error-message'
+import { OUTFILE as BIN_OUTFILE, build_bin } from './build-bin'
+import { build_claude_md } from './build-claude-md'
+import { build_commands } from './build-commands'
+import { build_hooks, OUT_DIR as HOOKS_OUT_DIR } from './build-hooks'
+import { build_library, PUBLIC_LIBRARIES } from './build-library'
+
+interface BuildStep {
+	name: string
+	run: () => Promise<string>
+}
+
+async function bin_step(): Promise<string> {
+	await build_bin()
+
+	return BIN_OUTFILE
+}
+
+async function hooks_step(): Promise<string> {
+	await build_hooks()
+
+	return HOOKS_OUT_DIR
+}
+
+async function library_step(name: string): Promise<string> {
+	const { outfile } = await build_library(name)
+
+	return outfile
+}
+
+async function claude_md_step(): Promise<string> {
+	return build_claude_md()
+}
+
+// Every step `pnpm build` runs (joshuafolkken/kit#3324). The steps write disjoint paths under
+// `dist/`, so they run concurrently from this one entry instead of eight serial `tsx` launches.
+// Nothing here writes a git-tracked file: `.codex/hooks.json` is regenerated by hand with
+// `tsx scripts/build/build-codex-hooks.ts`, and `codex-project-config.test.ts` fails the gate when
+// the committed copy drifts from `.claude/settings.json`.
+function build_steps(): ReadonlyArray<BuildStep> {
+	return [
+		{ name: 'bin', run: bin_step },
+		{ name: 'hooks', run: hooks_step },
+		{ name: 'commands', run: async () => await build_commands() },
+		...PUBLIC_LIBRARIES.map((name) => ({ name, run: async () => await library_step(name) })),
+		{ name: 'claude-md', run: claude_md_step },
+	]
+}
+
+async function build_all(): Promise<ReadonlyArray<string>> {
+	return await Promise.all(build_steps().map(async (step) => await step.run()))
+}
+
+async function main(): Promise<void> {
+	try {
+		const outputs = await build_all()
+
+		for (const output of outputs) console.info(`  ✔ ${output} built`)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+		process.exit(1)
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export type { BuildStep }
+export { build_all, build_steps }

package/scripts/build/local-bin.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { package_bin_schema } from '#scripts/lib/schemas'
 
 const NODE_MODULES = 'node_modules'
@@ -27,20 +28,9 @@ function resolve_local_bin(project_root: string, bin_name: string): string {
 // in `src/lib` would miss the toolkit its sibling checks resolve fine (joshuafolkken/kit#934).
 // Ascending for the shim itself, rather than for a `package.json` first, is what keeps the two in
 // step: a nested manifest that owns no `node_modules` is not where pnpm would stop either.
-function ancestor_directories(start_directory: string): ReadonlyArray<string> {
-	const directories: Array<string> = []
-	let current = start_directory
-
-	while (!directories.includes(current)) {
-		directories.push(current)
-		current = path.dirname(current)
-	}
-
-	return directories
-}
-
 function find_local_bin_upwards(start_directory: string, bin_name: string): string | undefined {
-	return ancestor_directories(start_directory)
+	return ancestor_directories
+		.list(start_directory)
 		.map((directory) => resolve_local_bin(directory, bin_name))
 		.find((candidate) => existsSync(candidate))
 }

package/scripts/delegation/investigation-reads.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import { cost_blocks } from '#scripts/cost-runtime/cost-blocks'
 import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { capped_print_part } from '#scripts/document/capped-print-part'
 import { hook_decision, type GuardRun } from '#scripts/josh/hook-decision'
 import { time_batch_guard, type GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_bundle_call } from '#scripts/time-runtime/time-bundle-call'
@@ -212,7 +213,8 @@ function is_session_artifact(target: string): boolean {
 
 	return (
 		segments.some((_segment, index) => has_state_root(segments, index)) ||
-		is_harness_output(segments)
+		is_harness_output(segments) ||
+		capped_print_part.is_part_file(absolute)
 	)
 }
 

package/scripts/discovery/repo-origin.ts

@@ -111,12 +111,12 @@ function origin_section_lines(lines: ReadonlyArray<string>): Array<string> {
 	return end === NOT_FOUND ? rest : rest.slice(0, end)
 }
 
-// The value of a `key = value` entry, or nothing when the line declares a different key. Split on
+// The value of a `url = value` entry, or nothing when the line declares a different key. Split on
 // the first separator rather than matched, for the reason `parse_scp_like` is split by hand.
-function entry_value(line: string, key: string): string | undefined {
+function url_value(line: string): string | undefined {
 	const separator = line.indexOf('=')
 	if (separator === NOT_FOUND) return undefined
-	if (line.slice(0, separator).trim() !== key) return undefined
+	if (line.slice(0, separator).trim() !== URL_KEY) return undefined
 
 	return line.slice(separator + 1).trim()
 }
@@ -129,7 +129,7 @@ function parse_origin_from_config(content: string): string | undefined {
 	const lines = content.split('\n').map((line) => line.trim())
 
 	return origin_section_lines(lines)
-		.map((line) => entry_value(line, URL_KEY))
+		.map((line) => url_value(line))
 		.find((url) => url !== undefined)
 }
 
@@ -153,7 +153,7 @@ function parse_remote_urls_from_config(content: string): Array<string> {
 
 	return section_groups(lines)
 		.filter((group) => REMOTE_SECTION.test(group[0] ?? ''))
-		.flatMap((group) => group.map((line) => entry_value(line, URL_KEY)))
+		.flatMap((group) => group.map((line) => url_value(line)))
 		.filter((url) => url !== undefined)
 }
 

package/scripts/doctor/doctor-consumer.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { json_value } from '#scripts/lib/json-value'
 import { file_reader } from '#scripts/lib/read-file'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
 import { z } from 'zod'
 
@@ -20,7 +21,6 @@ const PLUGIN_ID = 'kit@kit'
 // full document, so this pointer is also what tells a consumer repository apart from kit itself.
 const CLAUDE_MD_POINTER = `@${NODE_MODULES}/${KIT_PACKAGE_NAME}/dist/${CLAUDE_MD}`
 const SECRETLINT_BIN = path.join(NODE_MODULES, '.bin', 'secretlint')
-const GIT_TIMEOUT_MS = 2000
 
 const manifest_schema = z.object({
 	name: z.string().optional(),
@@ -77,7 +77,7 @@ function is_plugin_declared(root: string): boolean {
 // from installing kit's git hooks — the failure is silent but for one stderr line.
 function configured_hooks_path(root: string): string | undefined {
 	const value = git_spawn_sync.read(['-C', root, 'config', '--get', 'core.hooksPath'], {
-		timeout: GIT_TIMEOUT_MS,
+		timeout: PROBE_TIMEOUT_MS,
 	})
 
 	return value === '' ? undefined : value

package/scripts/doctor/doctor-io.ts

@@ -2,11 +2,11 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
 const JOSH_BIN = 'josh'
-const GIT_TIMEOUT_MS = 2000
 const NOT_A_REPOSITORY_MESSAGE = 'not a git repository'
 const NPM_VERSION_UPDATES_DISABLED = 'open-pull-requests-limit: 0'
 const DEPENDABOT_CONFIG_PATH = '.github/dependabot.yml'
@@ -72,7 +72,7 @@ function classify_git_failure(exit_code: number | undefined, stderr: string): Gi
 function resolve_git_top_level(): GitTopLevel {
 	// The C locale `toplevel` asks under is what keeps the stderr match below from failing on a
 	// translated message and bringing the spurious warning back.
-	const result = git_spawn_sync.toplevel(GIT_TIMEOUT_MS)
+	const result = git_spawn_sync.toplevel(PROBE_TIMEOUT_MS)
 
 	if (result.exit_code === 0) return classify_top_level(result.stdout.trim())
 
@@ -194,7 +194,6 @@ type GitTopLevel =
 	{ state: 'inside'; top_level: string } | { state: 'outside' } | { state: 'undetermined' }
 
 const doctor_io = {
-	GIT_TIMEOUT_MS,
 	resolve_path_josh,
 	resolve_pnpm_global_josh,
 	has_distributed_dependabot_config,

package/scripts/document/capped-print-part.ts

@@ -0,0 +1,30 @@
+import path from 'node:path'
+
+// Where `capped-print.ts` writes the parts of an over-cap output, and how a path is recognized as one
+// of them (joshuafolkken/kit#3332). Both halves live here so the writer and the investigation guard,
+// which must not count a read of a part as reading the Issue's subject, share one spelling of the
+// shape — kept free of the writer's own imports, since the guard runs as a hook on every tool call.
+
+const DIRECTORY_PREFIX = 'josh-capped-print-'
+const PART_PREFIX = 'part-'
+const PART_SUFFIX = '.md'
+// A part is `part-<N>.md` and nothing else, so a run's own file that happens to sit beside one is not
+// mistaken for it.
+const PART_PATTERN = /^part-[1-9]\d*\.md$/u
+
+function part_name(index: number): string {
+	return `${PART_PREFIX}${String(index + 1)}${PART_SUFFIX}`
+}
+
+// **The file's own parent, and the file's own name, both have to match.** A directory prefix alone
+// would exempt anything a run unpacked under a similarly named directory; the caller also requires the
+// path to lie outside the checkout, so no repository file is ever exempted by its name.
+function is_part_file(absolute: string): boolean {
+	const parent = path.basename(path.dirname(absolute))
+
+	return parent.startsWith(DIRECTORY_PREFIX) && PART_PATTERN.test(path.basename(absolute))
+}
+
+const capped_print_part = { DIRECTORY_PREFIX, part_name, is_part_file }
+
+export { capped_print_part }

package/scripts/document/capped-print.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { review_diff_parts } from '#scripts/review/review-diff-parts'
 import { bash_output_cap_reader } from './bash-output-cap'
+import { capped_print_part } from './capped-print-part'
 
 // Prints a command's output whole when it fits under the Bash output cap, and as part files when it
 // does not (joshuafolkken/kit#3143). Past `BASH_MAX_OUTPUT_LENGTH` Claude Code saves the output and
@@ -17,9 +18,7 @@ import { bash_output_cap_reader } from './bash-output-cap'
 // in one turn, and a shared directory replaced on every call would delete one call's parts while
 // another call's listing still names them.
 
-const DIRECTORY_PREFIX = 'josh-capped-print-'
 const FILE_MODE = 0o600
-const PART_SUFFIX = '.md'
 const LINE_BREAK = '\n'
 // What else shares the Bash result with this output: the launcher line, a script banner, a few
 // stderr lines. Measured at about 80 characters for `pnpm josh doc:section` in kit, so 512 holds the
@@ -27,10 +26,10 @@ const LINE_BREAK = '\n'
 const HEADROOM_CHARS = 512
 
 function write_parts(label: string, text: string, cap: number): Array<string> {
-	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, DIRECTORY_PREFIX))
+	const directory = mkdtempSync(path.join(PLATFORM_TEMP_ROOT, capped_print_part.DIRECTORY_PREFIX))
 
 	return review_diff_parts.part_texts(label, text, cap).map((part, index) => {
-		const file = path.join(directory, `part-${String(index + 1)}${PART_SUFFIX}`)
+		const file = path.join(directory, capped_print_part.part_name(index))
 
 		writeFileSync(file, part, { flag: 'wx', mode: FILE_MODE })
 

package/scripts/document/document-byte-budget.ts

@@ -88,8 +88,17 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	// joshuafolkken/kit#2998 split the reference: the developer commands stay, the rest moved out.
 	// joshuafolkken/kit#3175 raised it: the supervisor, provider-table and answer-to-budget prose moved
 	// here out of `backlogrun-steps.md`, so a run reads it only when it asks about those commands.
-	{ path: 'docs/josh-commands-automation.md', bytes: 159_744 },
-	{ path: 'docs/josh-commands.md', bytes: 36_864 },
+	// joshuafolkken/kit#3277 moved the run, lane and session commands to `docs/josh-commands-run.md`.
+	// joshuafolkken/kit#3280 moved the issue, epic, backlog and review commands to
+	// `docs/josh-commands-backlog.md`.
+	// joshuafolkken/kit#3278 moved `josh latest` and `josh overrides` — commands a person types — from
+	// the automation page to `docs/josh-commands.md`, which grew one block and the automation page shrank one.
+	{ path: 'docs/josh-commands-automation.md', bytes: 49_152 },
+	{ path: 'docs/josh-commands-run.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
+	{ path: 'docs/josh-commands.md', bytes: 40_960 },
+	// joshuafolkken/kit#3279 moved the label sections here out of `docs/josh-commands-backlog.md`.
+	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow/file-edits.md', bytes: 12_288 },

package/scripts/document/document-scan.ts

@@ -0,0 +1,117 @@
+// Pulling machine-checkable references out of the distributed documents, so a few structural scans
+// can replace the ~140 per-phrase marker suites the documents used to carry (joshuafolkken/kit#1923).
+// Every function here is a pure string extractor: it takes document text and returns the references
+// it names, which is what lets the scans that call it be checked on a synthetic string with a
+// deliberately broken reference in it.
+
+// A command reference, only inside a code span. `` `pnpm josh gate` `` and `` `josh review:brief` ``
+// are the copy-and-paste form; the leading backtick keeps prose like "josh will decide" out, which
+// would otherwise read "will" as a command name.
+const COMMAND_PATTERN = /`(?:pnpm )?josh ([a-z][a-z0-9:-]+)/gu
+
+// A label the documents operate on — applied (`labels[]=…`), removed (`…/labels/<name>`) or created
+// (`labels -f name=…`). Prose that merely names a label is not scanned; a mistyped name only breaks
+// where a command carries it.
+const LABEL_PATTERN = /(?:labels\[\]=|\/labels\/|labels -f name=)([a-z][a-z0-9:_-]*)/gu
+
+// A section reference: a markdown file, an arrow, and the cited heading in straight or Japanese
+// quotes — `` `backlogrun-progress.md` → "The hand-off" ``. The code span is optional and a section
+// number may sit between the arrow and the heading (`` `SKILL.md` → §1, "…" ``): both forms are in
+// the documents, as is a name linked to its file (`` [`residency.md`](./residency.md) →「…」 ``), and a
+// pattern that skipped them let a broken reference of each form through (joshuafolkken/kit#3076).
+// The backreference pairs the code span's backticks, and the lookbehind keeps a bare name from
+// starting mid-path — inside a URL or after an unpaired backtick.
+const SECTION_PATTERN =
+	/(?<![\w./:`-])(?<tick>`?)(?<file>[\w./-]+\.md)\k<tick>\s*→\s*(?:§\w+,\s*)?["「](?<heading>[^"」]+)["」]/gu
+
+// A markdown link's `(target)`, dropped before the section scan so a linked name sits right before its
+// arrow — the link text already carries the file the reference names.
+const LINK_TARGET_PATTERN = /\]\([^)\s]*\)/gu
+
+// A relative markdown link target, with an optional `#anchor`. External `https://…` links carry no
+// `.md`, so the pattern never matches them.
+const LINK_PATTERN = /\]\(([\w./-]+\.md)(?:#[\w-]+)?\)/gu
+
+// Filenames that appear in the documents as illustrations of the reference form itself, never as real
+// targets — the doc-section explanation cites `` `path.md` → "Heading" `` and `` `X.md` → "Heading" ``.
+const PLACEHOLDER_FILES: ReadonlySet<string> = new Set(['x.md', 'foo.md', 'file.md', 'path.md'])
+
+function matches(text: string, pattern: RegExp): Array<RegExpMatchArray> {
+	return [...text.matchAll(pattern)]
+}
+
+// A trailing colon is a placeholder for the sub-command that follows — `` `josh epic:` `` stands for
+// `epic:audit`, `epic:next` and the rest — so it names no command of its own.
+function command_references(text: string): Array<string> {
+	return matches(text, COMMAND_PATTERN)
+		.map((match) => match[1] ?? '')
+		.filter((name) => !name.endsWith(':'))
+}
+
+// A `<placeholder>` inside a command, and `depth:<n>` after the char class stops at `<`, both leave a
+// token that is not a real label. Real labels never end in a colon and never carry angle brackets.
+function is_real_label(token: string): boolean {
+	return token.length > 0 && !token.endsWith(':') && !token.includes('<')
+}
+
+function label_references(text: string): Array<string> {
+	return matches(text, LABEL_PATTERN)
+		.map((match) => match[1] ?? '')
+		.filter((token) => is_real_label(token))
+}
+
+function base_name(path: string): string {
+	return path.split('/').at(-1) ?? path
+}
+
+function is_placeholder_file(name: string): boolean {
+	return name.includes('<') || PLACEHOLDER_FILES.has(base_name(name).toLowerCase())
+}
+
+interface SectionReference {
+	file: string
+	heading: string
+}
+
+function section_references(text: string): Array<SectionReference> {
+	return matches(text.replaceAll(LINK_TARGET_PATTERN, ''), SECTION_PATTERN)
+		.map(({ groups }) => ({ file: groups?.['file'] ?? '', heading: groups?.['heading'] ?? '' }))
+		.filter((reference) => !is_placeholder_file(reference.file))
+}
+
+function link_targets(text: string): Array<string> {
+	return matches(text, LINK_PATTERN)
+		.map((match) => match[1] ?? '')
+		.filter((file) => !is_placeholder_file(file))
+}
+
+// A cited heading and the heading it names are compared with backticks dropped and whitespace
+// collapsed, because a reference wraps at the column the prose wraps at — sometimes across a
+// blockquote `> ` continuation — while the heading it points at is one unbroken line.
+function normalize_reference(heading: string): string {
+	return heading
+		.replaceAll('`', '')
+		.split(/\s+/u)
+		.filter((word) => word !== '>')
+		.join(' ')
+}
+
+// The two forms a heading can be cited by: with its leading number (`2b. Delegating…`) and without
+// (`Delegating…`), since a document's own numbering is a prefix a reference may or may not carry.
+function reference_forms(title: string): Array<string> {
+	const normalized = normalize_reference(title)
+
+	return [normalized, normalized.replace(/^\d+[a-z]?\. /u, '')]
+}
+
+const document_scan = {
+	command_references,
+	label_references,
+	link_targets,
+	normalize_reference,
+	reference_forms,
+	section_references,
+}
+
+export type { SectionReference }
+export { document_scan }