@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/review/review-finding-ledger.ts

@@ -13,6 +13,16 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 const PREFIX = { code: '- rf:', interaction: '- ri:' } as const
 const FIELD_SEPARATOR = ' | '
 const FIELD_COUNT = 5
+// **The disposition is a sixth field, written only when given** (joshuafolkken/kit#5286): a line
+// written before it existed keeps its five and reads as a finding with no disposition.
+const DISPOSED_FIELD_COUNT = FIELD_COUNT + 1
+const ISSUE_FIELD_INDEX = FIELD_COUNT - 1
+const SEVERITY_FIELD_INDEX = 1
+// **A code round written to the issue's file opens with a boundary line** (joshuafolkken/kit#5359):
+// the ledger is append-only, so a stopped round's unfixed lines stay, and `josh review:round2` reads
+// only the lines after the issue's last boundary. Its own prefix keeps it out of every `- rf:` reader.
+const ROUND_PREFIX = '- rb:'
+const ROUND_ISSUE_FIELD_INDEX = 1
 
 // The nine review-rubric categories, as slugs (`prompts/review-rubric.md` → "Review categories"). A
 // finding's category must be one of these so the aggregate stays countable rather than free text.
@@ -30,6 +40,12 @@ const CATEGORIES = [
 
 const SEVERITIES = ['high', 'medium', 'low'] as const
 
+// What became of a finding: fixed in this tree, a verified false positive, or left to another issue.
+// Only the first two close it for `josh review:round2`.
+const CLOSING_DISPOSITIONS = ['fixed', 'false-positive'] as const
+const DISPOSITION_PATTERN = /^(?:fixed|false-positive|(?:filed|deferred):#[1-9]\d*)$/u
+const DISPOSITION_SEPARATOR = ' '
+
 // The sentinel a zero-finding round writes, so "a round ran and found nothing" is a recorded line
 // rather than an absent one — the count's denominator survives.
 const NONE = 'none'
@@ -43,6 +59,12 @@ interface Finding {
 	category: Category
 	severity: Severity
 	file: string
+	disposition?: string
+}
+
+interface DisposedSpec {
+	disposition: string | undefined
+	spec: string
 }
 
 interface CategoryCount {
@@ -65,6 +87,25 @@ function is_valid_file(file: string): boolean {
 	return file.length > 0 && !file.includes(FIELD_SEPARATOR)
 }
 
+function is_disposition(value: string): boolean {
+	return DISPOSITION_PATTERN.test(value)
+}
+
+function is_closing(disposition: string | undefined): boolean {
+	return (CLOSING_DISPOSITIONS as ReadonlyArray<string | undefined>).includes(disposition)
+}
+
+// A positional's leading disposition — `fixed <spec>`, `filed:#12 <spec>` — split from the spec it
+// marks. The token the reviewer already writes before a finding it fixed, so one grammar serves both.
+function split_disposition(positional: string): DisposedSpec {
+	const end = positional.indexOf(DISPOSITION_SEPARATOR)
+	const head = end === -1 ? '' : positional.slice(0, end)
+
+	if (!is_disposition(head)) return { disposition: undefined, spec: positional }
+
+	return { disposition: head, spec: positional.slice(end + DISPOSITION_SEPARATOR.length) }
+}
+
 function issue_field(issue: number): string {
 	return issue_cite.plain(issue)
 }
@@ -79,7 +120,12 @@ function finding_line(
 	issue: number,
 	kind: LineKind = 'code',
 ): string {
-	return line_of([finding.category, finding.severity, finding.file, date, issue_field(issue)], kind)
+	const fields = [finding.category, finding.severity, finding.file, date, issue_field(issue)]
+
+	return line_of(
+		finding.disposition === undefined ? fields : [...fields, finding.disposition],
+		kind,
+	)
 }
 
 // **A zero-finding round records `none`, not nothing.** Reading its absence as "no findings" would
@@ -97,10 +143,20 @@ function fields_of(line: string, kind: LineKind = 'code'): ReadonlyArray<string>
 	return line.trimStart().slice(PREFIX[kind].length).split(FIELD_SEPARATOR)
 }
 
-function category_of(line: string): string | undefined {
-	const fields = fields_of(line)
+// The line's fields, or `undefined` for a malformed one — five, or six with a disposition.
+function well_formed_fields(
+	line: string,
+	kind: LineKind = 'code',
+): ReadonlyArray<string> | undefined {
+	const fields = fields_of(line, kind)
 
-	return fields.length === FIELD_COUNT ? fields[0] : undefined
+	return fields.length === FIELD_COUNT || fields.length === DISPOSED_FIELD_COUNT
+		? fields
+		: undefined
+}
+
+function category_of(line: string): string | undefined {
+	return well_formed_fields(line)?.[0]
 }
 
 function increment(counts: Map<string, number>, category: string): void {
@@ -149,9 +205,50 @@ function zero_round_count(content: string): number {
 // non-finding or malformed line. The record check reads this to ask whether a given issue's round was
 // recorded at all.
 function issue_of(line: string, kind: LineKind): string | undefined {
-	const fields = fields_of(line, kind)
+	return well_formed_fields(line, kind)?.[ISSUE_FIELD_INDEX]
+}
+
+interface DisposedLine {
+	severity: string
+	disposition: string | undefined
+}
+
+// One issue's `- rf:` lines, each with its severity and disposition — `undefined` disposition for a
+// line written without one. `josh review:round2` reads round 1's closure from this.
+function issue_dispositions(content: string, issue: number): ReadonlyArray<DisposedLine> {
+	const target = issue_field(issue)
+
+	return content
+		.split('\n')
+		.filter((line) => is_finding_line(line) && issue_of(line, 'code') === target)
+		.map((line) => well_formed_fields(line) ?? [])
+		.map((fields) => ({
+			severity: fields[SEVERITY_FIELD_INDEX] ?? NONE,
+			disposition: fields[FIELD_COUNT],
+		}))
+}
+
+function round_line(date: string, issue: number): string {
+	return `${ROUND_PREFIX}${[date, issue_field(issue)].join(FIELD_SEPARATOR)}`
+}
+
+function is_round_line(line: string, target: string): boolean {
+	const trimmed = line.trimStart()
+
+	if (!trimmed.startsWith(ROUND_PREFIX)) return false
+
+	const fields = trimmed.slice(ROUND_PREFIX.length).split(FIELD_SEPARATOR)
+
+	return fields[ROUND_ISSUE_FIELD_INDEX] === target
+}
+
+// The content after the issue's last round boundary — the whole content when it has none, as a ledger
+// written before the boundary existed does.
+function latest_round(content: string, issue: number): string {
+	const target = issue_field(issue)
+	const lines = content.split('\n')
 
-	return fields.length === FIELD_COUNT ? fields[FIELD_COUNT - 1] : undefined
+	return lines.slice(lines.findLastIndex((line) => is_round_line(line, target)) + 1).join('\n')
 }
 
 // **A `none` zero-round line counts as recorded, exactly like a real finding line does.** The gate
@@ -172,13 +269,18 @@ const review_finding_ledger = {
 	finding_line,
 	has_issue_record,
 	is_category,
+	is_closing,
 	is_finding_line,
 	is_severity,
 	is_valid_file,
+	issue_dispositions,
+	latest_round,
+	round_line,
 	SEVERITIES,
+	split_disposition,
 	zero_round_count,
 	zero_round_line,
 }
 
-export type { CategoryCount, Finding, LineKind }
+export type { CategoryCount, DisposedLine, Finding, LineKind }
 export { review_finding_ledger }

package/scripts/review/review-finding-text.ts

@@ -0,0 +1,43 @@
+// A finding written in the `review:record` grammar with its reason after it — `<spec> — <sentence>` —
+// split into the two halves, the one place both its writers read it: a ship reviewer's findings file
+// (`run-ship-review.ts`) and an agent's own `review:record` round (`review-record-cli.ts`). The spec is
+// what the ledger keeps; the first sentence of the reason is what the durable stop log keeps.
+
+// What a finding line carries after its spec: one sentence saying what is wrong, so a stopped ship's
+// log tells the resumed lane child the defect rather than only its location.
+const DESCRIPTION_SEPARATOR = ' — '
+// Where the spec ends on read: a reviewer that types the dash as `-`, `--` or `–` still ends it there,
+// so its sentence never lands in the ledger's file field.
+const DESCRIPTION_BOUNDARY = / [—–-]{1,2} /u
+// Where a description's first sentence ends, and the cap that keeps a run-on one a line. Japanese
+// sets no space after `。`, so it ends a sentence on its own.
+const SENTENCE_END = /(?<=[.!?])\s|(?<=。)/u
+const SENTENCE_LIMIT = 200
+const ELLIPSIS = '…'
+
+function split_description(unmarked: string): { spec: string; description: string } {
+	const boundary = DESCRIPTION_BOUNDARY.exec(unmarked)
+
+	if (boundary === null) return { spec: unmarked.trim(), description: '' }
+
+	const rest = unmarked.slice(boundary.index + boundary[0].length)
+
+	return { spec: unmarked.slice(0, boundary.index).trim(), description: rest.trim() }
+}
+
+function first_sentence(description: string): string {
+	const [sentence = ''] = description.split(SENTENCE_END, 1)
+
+	if (sentence.length <= SENTENCE_LIMIT) return sentence
+
+	return `${sentence.slice(0, SENTENCE_LIMIT - ELLIPSIS.length)}${ELLIPSIS}`
+}
+
+const review_finding_text = {
+	DESCRIPTION_SEPARATOR,
+	SENTENCE_LIMIT,
+	first_sentence,
+	split_description,
+}
+
+export { review_finding_text }

package/scripts/review/review-interaction.ts

@@ -2,6 +2,7 @@ import { project_checks } from '#scripts/gate/project-checks'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_attest, type ReviewSlot } from './review-attest'
 import { review_finding_ledger } from './review-finding-ledger'
 
 // The interaction review — one adversarial pass after `/code-review`, over a change to the run
@@ -65,6 +66,15 @@ async function status(issue: number, root?: string): Promise<InteractionStatus>
 	return await status_of(issue, await changed_paths.read_changed_paths(false), root)
 }
 
+// **Round 1's slots — the interaction review beside `/code-review`'s where it is due and not yet
+// recorded** (joshuafolkken/kit#4672, joshuafolkken/kit#4802), so it takes round 1's wait and stop.
+// `josh ship` and `josh run:review` both open round 1 from it.
+function round_one_slots(answer: InteractionStatus | undefined): ReadonlyArray<ReviewSlot> {
+	const { CODE, INTERACTION } = review_attest.REVIEW_SLOT
+
+	return answer === 'missing' ? [CODE, INTERACTION] : [CODE]
+}
+
 const MISSING_REASON =
 	'This change touches the run tooling, and no interaction review is recorded for its issue — the pass that looks for the existing features a change breaks, which `/code-review` does not (joshuafolkken/kit#4276).'
 
@@ -86,6 +96,7 @@ const review_interaction = {
 	NOT_DUE_LINE,
 	refusal,
 	refusal_message,
+	round_one_slots,
 	status,
 	status_of,
 }

package/scripts/review/review-lane-handover.ts

@@ -0,0 +1,68 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { session_cite } from '#scripts/issue/session-cite'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
+import { review_round_reuse, type ReuseAnswer } from './review-round-reuse'
+
+// joshuafolkken/kit#4850: once a lane child has recorded round 1 on a tree `josh ship` reuses, round 2
+// is the ship's. The rule stood in `chain-rule.md` step 0 as prose alone (joshuafolkken/kit#4830), and
+// the next lane reopened `run:review` after reading it, running a round 2 the ship then ran again. So
+// `run:review` refuses that reopen and `review:record` names the ship as the next step.
+//
+// **A round the ship would review again is not handed over**: `review:record --check` then tells the
+// lane to run round 1 itself, so `run:review` stays open for it.
+
+const SHIP_STEP = 'pnpm josh ship --detach --review "<title> #<N>"'
+const NEXT_STEP_LINE = `Next: hand over to \`${SHIP_STEP}\` — round 2 is the ship's; never reopen \`run:review\` (chain-rule.md step 0).`
+
+// A reuse question git could not answer reads as not reused: the lane then reviews the round itself,
+// which costs one review, rather than leaving it to a ship that may review it again detached.
+// The stale read inside it fails open in `review_round_reuse.is_stale_here`, as the ship's probe reads it.
+const UNANSWERED_CAUSE = 'git could not answer the reuse question'
+
+async function answer_here(issue: number): Promise<ReuseAnswer> {
+	try {
+		return await review_round_reuse.answer_here(issue)
+	} catch (error) {
+		error_text.trace_swallowed('review_lane_handover.answer_here', error)
+
+		return { reuse: review_round_reuse.REUSE.AGAIN, cause: UNANSWERED_CAUSE }
+	}
+}
+
+async function is_reused_here(issue: number): Promise<boolean> {
+	const answer = await answer_here(issue)
+
+	return answer.reuse !== review_round_reuse.REUSE.AGAIN
+}
+
+// The mark must name this issue as well as this checkout, so a person's run — or a branch whose issue
+// is not the lane's — is never refused.
+function is_lane_child_of(issue: number): boolean {
+	if (lane_child_marker.marked_issue() !== String(issue)) return false
+
+	return lane_child_marker.is_child_of(PROJECT_ROOT)
+}
+
+// Reuse already requires the recorded round (`review_round_reuse.is_reusable`), so it answers both.
+async function is_handed_over(issue: number): Promise<boolean> {
+	if (!is_lane_child_of(issue)) return false
+
+	return await is_reused_here(issue)
+}
+
+function refusal(issue: number): string {
+	return (
+		`⛔ run:review: round 1 of ${session_cite.issue(issue)} is recorded and josh ship reuses it, and this is a ` +
+		`dispatched lane child (\`${lane_child_marker.KEY}\`), so no brief is minted. ${NEXT_STEP_LINE}`
+	)
+}
+
+const review_lane_handover = {
+	NEXT_STEP_LINE,
+	answer_here,
+	is_handed_over,
+	refusal,
+}
+
+export { review_lane_handover }

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

@@ -0,0 +1,57 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { review_brief_cli } from './review-brief-cli'
+import { review_lint } from './review-lint'
+
+// `josh review:lint` — read a review's markdown from stdin and print `ok`, or the rubric's format
+// violations one per line, exiting non-zero so the reviewer runs it before returning its findings.
+// `--round 2` checks the verification pass's shape instead of the full template.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const OK_MESSAGE = 'ok'
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh review:lint [--round <1|2>] < review.md'
+const NO_INPUT_MESSAGE =
+	'✖ nothing on stdin — pipe the review in, e.g. `pnpm josh review:lint < review.md`'
+
+// The lines to print on failure — a usage error, no input, or the violations — empty on a pass.
+function failure_lines(review: string, argv: ReadonlyArray<string>): ReadonlyArray<string> {
+	const round = review_brief_cli.parse_round(argv)
+	if (round === undefined) return [USAGE]
+	if (review.trim().length === 0) return [NO_INPUT_MESSAGE]
+
+	return review_lint.with_reference(review_lint.lint_review(review, round), round)
+}
+
+function run(review: string, argv: ReadonlyArray<string>): number {
+	const failures = failure_lines(review, argv)
+
+	if (failures.length > 0) {
+		console.error(failures.join('\n'))
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(OK_MESSAGE)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function read_and_run(): Promise<number> {
+	const argv = process.argv.slice(ARGV_OFFSET)
+	if (process.stdin.isTTY) return run('', argv)
+
+	return run(await text(process.stdin), argv)
+}
+
+async function main(): Promise<void> {
+	process.exitCode = await read_and_run()
+}
+
+const review_lint_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { review_lint_cli }

package/scripts/review/review-lint-findings.ts

@@ -0,0 +1,92 @@
+import { review_lint_sections, type ReviewSection } from './review-lint-sections'
+
+// The finding-line checks of `review:lint` (`prompts/review-rubric.md` → "Review output format"): every
+// finding cites `file_path:line_number` and a severity, and a `low` carries its
+// `no failure scenario — <what you tried>` line. A round-2 first-round line cites the severity it
+// had (`(was high)`) and its resolution instead.
+
+interface ItemRule {
+	readonly holds: (block: string) => boolean
+	readonly message: string
+}
+
+const FILE_LINE = /`[^`\s]+:\d+(?:-\d+)?`/u
+const SEVERITY = /\((?:high|medium|low)\)/u
+const LOW_MARKER = '(low)'
+const NO_FAILURE_SCENARIO = 'no failure scenario —'
+const PRIOR_SEVERITY = /\(was (?:high|medium|low)\)/u
+const RESOLUTION = /\bresolved\b/u
+// An item that is a trace, a `No issues` proof or an empty section's `None` is the verdict, not a finding.
+const VERDICT_ITEM = /^(?:Traced\b|No issues|None\b)/u
+
+function cites_file_line(block: string): boolean {
+	return FILE_LINE.test(block)
+}
+
+function states_severity(block: string): boolean {
+	return SEVERITY.test(block)
+}
+
+// The finding's own severity is its first one; a `(low)` later in its prose is not a severity.
+function low_has_scenario_line(block: string): boolean {
+	return SEVERITY.exec(block)?.[0] !== LOW_MARKER || block.includes(NO_FAILURE_SCENARIO)
+}
+
+function states_prior_severity(block: string): boolean {
+	return PRIOR_SEVERITY.test(block)
+}
+
+function states_resolution(block: string): boolean {
+	return RESOLUTION.test(block)
+}
+
+const FINDING_RULES: ReadonlyArray<ItemRule> = [
+	{ holds: cites_file_line, message: 'finding without a `file:line` citation' },
+	{ holds: states_severity, message: 'finding without a severity (high|medium|low)' },
+	{
+		holds: low_has_scenario_line,
+		message: `low finding without "${NO_FAILURE_SCENARIO} <what you tried>"`,
+	},
+]
+
+const FIRST_ROUND_RULES: ReadonlyArray<ItemRule> = [
+	{ holds: cites_file_line, message: 'first-round line without a `file:line` citation' },
+	{ holds: states_prior_severity, message: 'first-round line without "(was <severity>)"' },
+	{ holds: states_resolution, message: 'first-round line without "resolved" or "not resolved"' },
+]
+
+function first_line(block: string): string {
+	return block.split('\n', 1)[0]?.trim() ?? ''
+}
+
+function rule_violations(
+	block: string,
+	heading: string,
+	rules: ReadonlyArray<ItemRule>,
+): ReadonlyArray<string> {
+	const where = `under ### ${heading}: ${first_line(block)}`
+
+	return rules.filter((rule) => !rule.holds(block)).map((rule) => `✖ ${rule.message} ${where}`)
+}
+
+function finding_blocks(section: ReviewSection): ReadonlyArray<string> {
+	return review_lint_sections
+		.item_blocks(section.lines)
+		.filter((block) => !VERDICT_ITEM.test(review_lint_sections.item_text(block)))
+}
+
+function finding_violations(section: ReviewSection): ReadonlyArray<string> {
+	return finding_blocks(section).flatMap((block) =>
+		rule_violations(block, section.heading, FINDING_RULES),
+	)
+}
+
+function first_round_violations(section: ReviewSection): ReadonlyArray<string> {
+	return review_lint_sections
+		.item_blocks(section.lines)
+		.flatMap((block) => rule_violations(block, section.heading, FIRST_ROUND_RULES))
+}
+
+const review_lint_findings = { finding_blocks, finding_violations, first_round_violations }
+
+export { review_lint_findings }

package/scripts/review/review-lint-sections.ts

@@ -0,0 +1,80 @@
+import { document_section } from '#scripts/document/document-section'
+
+// The parsing half of `review:lint`: a review's markdown split into its `###` sections, and a
+// section's list items grouped with their indented continuation lines. The checks live in
+// `review-lint.ts` and `review-lint-findings.ts`; nothing here judges what it reads.
+
+interface ReviewSection {
+	readonly heading: string
+	readonly lines: ReadonlyArray<string>
+}
+
+const HEADING_PREFIX = '### '
+// `### 1. Bug risks & logic errors` and `### Project conventions (`CLAUDE.md`)` are the rubric's own
+// category headings, so the number and a trailing parenthetical are dropped before the name is read.
+const NUMBER_PREFIX = /^\d+\.\s+/u
+const TRAILING_NOTE = / \([^)]*\)$/u
+// A list item at column 0; an indented one is a continuation of the item above it.
+const TOP_LEVEL_ITEM = /^(?:[-*]|\d+\.)\s+/u
+const CONTINUATION = /^\s+\S/u
+
+function heading_name(line: string): string {
+	return line
+		.slice(HEADING_PREFIX.length)
+		.trim()
+		.replace(NUMBER_PREFIX, '')
+		.replace(TRAILING_NOTE, '')
+		.trim()
+}
+
+// Lines before the first heading belong to no section and are not read; a `###` line inside a code
+// fence is quoted text, not a heading.
+function parse_sections(review: string): ReadonlyArray<ReviewSection> {
+	const lines = review.split('\n')
+	const fenced = document_section.fenced_flags(lines)
+	const heading_flags = lines.map(
+		(line, index) => fenced[index] !== true && line.startsWith(HEADING_PREFIX),
+	)
+	const sections: Array<{ heading: string; lines: Array<string> }> = []
+
+	for (const [index, line] of lines.entries()) {
+		if (heading_flags[index] === true) sections.push({ heading: heading_name(line), lines: [] })
+		else sections.at(-1)?.lines.push(line)
+	}
+
+	return sections
+}
+
+function has_content(section: ReviewSection): boolean {
+	return section.lines.some((line) => line.trim().length > 0)
+}
+
+function body_text(section: ReviewSection): string {
+	return section.lines.join('\n').trim()
+}
+
+// A line extends the block above it only when indented; any other non-blank line opens a new block —
+// an item's own, or a closed one for prose, which closes the item above it and takes no continuation.
+function add_line(blocks: Array<Array<string> | undefined>, line: string): void {
+	if (CONTINUATION.test(line)) blocks.at(-1)?.push(line)
+	else if (line.trim().length > 0) blocks.push(TOP_LEVEL_ITEM.test(line) ? [line] : undefined)
+}
+
+// Each top-level item with its indented continuation lines, joined; a sentence after a list is never
+// read as part of its last item.
+function item_blocks(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+	const blocks: Array<Array<string> | undefined> = []
+
+	for (const line of lines) add_line(blocks, line)
+
+	return blocks.filter((block) => block !== undefined).map((block) => block.join('\n'))
+}
+
+function item_text(block: string): string {
+	return block.replace(TOP_LEVEL_ITEM, '')
+}
+
+const review_lint_sections = { parse_sections, has_content, body_text, item_blocks, item_text }
+
+export type { ReviewSection }
+export { review_lint_sections }