@joshuafolkken/kit 1.1514.0 → 1.2114.0

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 }

package/scripts/review/review-lint.ts

@@ -0,0 +1,221 @@
+import { markdown_shape } from '#scripts/report/markdown-shape'
+import { review_lint_findings } from './review-lint-findings'
+import { review_lint_sections, type ReviewSection } from './review-lint-sections'
+
+// `prompts/review-rubric.md` states every requirement of a review's output in a form a machine can
+// read, yet only the next round or a person ever checked one. This checks them: the heading set and
+// its order, a verdict under every heading, the trace behind a `No issues` on category 1, the 2–3
+// assumptions, the Confidence floor's banned answers, and each finding's citation and severity. Whether
+// a finding is right stays the judgement half.
+
+const BUG_RISKS = 'Bug risks & logic errors'
+const ASSUMPTIONS = 'Assumptions audit'
+const CONFIDENCE_FLOOR = 'Confidence floor'
+const SUMMARY = 'Summary'
+const FIRST_ROUND_FINDINGS = 'First-round findings'
+const NEW_FINDINGS = 'New findings in the fix delta'
+const SECOND_ROUND = 2
+
+const SECURITY = 'Security'
+const PERFORMANCE = 'Performance'
+const I18N = 'i18n'
+const COMMENTS = 'Comments & content'
+
+// "Review categories" in its order; the first seven carry findings, the last two their own shape.
+const FINDING_CATEGORIES = [
+	BUG_RISKS,
+	SECURITY,
+	PERFORMANCE,
+	'Project conventions',
+	I18N,
+	'Tests',
+	COMMENTS,
+]
+const FINDING_CATEGORY_SET: ReadonlySet<string> = new Set(FINDING_CATEGORIES)
+const ROUND_ONE_HEADINGS = [...FINDING_CATEGORIES, ASSUMPTIONS, CONFIDENCE_FLOOR, SUMMARY]
+// The categories the rubric lets answer a bare `No issues` when nothing was there to check.
+const BARE_NO_ISSUES_ALLOWED: ReadonlySet<string> = new Set([SECURITY, PERFORMANCE, I18N, COMMENTS])
+// Round 2 reads category 1 and the categories its fix delta touches, so no category heading is
+// required there: its template is these three headings alone.
+const ROUND_TWO_HEADINGS = [FIRST_ROUND_FINDINGS, NEW_FINDINGS, SUMMARY]
+const BARE_NO_ISSUES = /^No issues\.?$/u
+const NO_ISSUES = /\bNo issues\b/u
+const TRACE = /Traced .+ → .+ — (?:confirmed|flagged) because \S/u
+const MIN_ASSUMPTIONS = 2
+const MAX_ASSUMPTIONS = 3
+// The banned answers stand alone; a sentence that only opens with "Nothing" names something.
+const BANNED_FLOOR = /^(?:Nothing|No concerns)\.?$/iu
+const TARGET_MISMATCH = 'REVIEW TARGET MISMATCH'
+const RUBRIC = 'prompts/review-rubric.md'
+const ROUND_ONE_SECTION = 'Review output format'
+const ROUND_TWO_SECTION = 'The second round is a verification pass, not a second full review'
+
+function section_named(
+	sections: ReadonlyArray<ReviewSection>,
+	heading: string,
+): ReviewSection | undefined {
+	return sections.find((section) => section.heading === heading)
+}
+
+function missing_heading_violations(
+	headings: ReadonlyArray<string>,
+	expected: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return expected
+		.filter((heading) => !headings.includes(heading))
+		.map((heading) => `✖ missing heading: ### ${heading}`)
+}
+
+function unexpected_heading_violations(
+	headings: ReadonlyArray<string>,
+	expected: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	return headings
+		.filter((heading) => !expected.includes(heading))
+		.map((heading) => `✖ unexpected heading: ### ${heading}`)
+}
+
+// The known headings, as written, must read as the expected list with the missing ones left out — a
+// swap or a repeat breaks that, a missing heading alone does not.
+function order_violation(
+	headings: ReadonlyArray<string>,
+	expected: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const written = headings.filter((heading) => expected.includes(heading)).join(' → ')
+	if (written === expected.filter((heading) => headings.includes(heading)).join(' → ')) return []
+
+	return [`✖ headings out of order or repeated — expected: ${expected.join(' → ')}`]
+}
+
+function heading_violations(
+	sections: ReadonlyArray<ReviewSection>,
+	expected: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const headings = sections.map((section) => section.heading)
+
+	return [
+		...missing_heading_violations(headings, expected),
+		...unexpected_heading_violations(headings, expected),
+		...order_violation(headings, expected),
+	]
+}
+
+function verdict_violations(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	return sections
+		.filter((section) => !review_lint_sections.has_content(section))
+		.map((section) => `✖ no verdict under ### ${section.heading}`)
+}
+
+function bare_no_issues_violations(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	return sections
+		.filter((section) => FINDING_CATEGORY_SET.has(section.heading))
+		.filter((section) => !BARE_NO_ISSUES_ALLOWED.has(section.heading))
+		.filter((section) => BARE_NO_ISSUES.test(review_lint_sections.body_text(section)))
+		.map((section) => `✖ bare "No issues" under ### ${section.heading} — say what was checked`)
+}
+
+function trace_violation(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	const section = section_named(sections, BUG_RISKS)
+	if (section === undefined || review_lint_findings.finding_blocks(section).length > 0) return []
+
+	const body = review_lint_sections.body_text(section)
+	if (!NO_ISSUES.test(body) || TRACE.test(body)) return []
+
+	return [
+		`✖ "No issues" under ### ${BUG_RISKS} without a trace — Traced <input> → <result> — confirmed/flagged because <reason>`,
+	]
+}
+
+function assumptions_violation(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	const section = section_named(sections, ASSUMPTIONS)
+	if (section === undefined) return []
+
+	const count = review_lint_sections.item_blocks(section.lines).length
+	if (count >= MIN_ASSUMPTIONS && count <= MAX_ASSUMPTIONS) return []
+
+	return [
+		`✖ ### ${ASSUMPTIONS} lists ${String(count)} assumptions — it needs ${String(MIN_ASSUMPTIONS)}–${String(MAX_ASSUMPTIONS)}`,
+	]
+}
+
+function confidence_floor_violation(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	const section = section_named(sections, CONFIDENCE_FLOOR)
+
+	if (section === undefined || !BANNED_FLOOR.test(review_lint_sections.body_text(section))) {
+		return []
+	}
+
+	return [`✖ ### ${CONFIDENCE_FLOOR} answers "Nothing" or "No concerns" — name one concrete thing`]
+}
+
+function category_finding_violations(
+	sections: ReadonlyArray<ReviewSection>,
+): ReadonlyArray<string> {
+	return sections
+		.filter((section) => FINDING_CATEGORY_SET.has(section.heading))
+		.flatMap((section) => review_lint_findings.finding_violations(section))
+}
+
+function round_one_violations(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	return [
+		...heading_violations(sections, ROUND_ONE_HEADINGS),
+		...verdict_violations(sections),
+		...bare_no_issues_violations(sections),
+		...trace_violation(sections),
+		...assumptions_violation(sections),
+		...confidence_floor_violation(sections),
+		...category_finding_violations(sections),
+	]
+}
+
+function delta_violations(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	const first_round = section_named(sections, FIRST_ROUND_FINDINGS)
+	const delta = section_named(sections, NEW_FINDINGS)
+
+	return [
+		...(first_round === undefined ? [] : review_lint_findings.first_round_violations(first_round)),
+		...(delta === undefined ? [] : review_lint_findings.finding_violations(delta)),
+	]
+}
+
+function round_two_violations(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	return [
+		...heading_violations(sections, ROUND_TWO_HEADINGS),
+		...verdict_violations(sections),
+		...delta_violations(sections),
+	]
+}
+
+// The stop condition's reply is the phrase alone: a heading beside it is a verdict it must not carry.
+function mismatch_violations(sections: ReadonlyArray<ReviewSection>): ReadonlyArray<string> {
+	if (sections.length === 0) return []
+
+	return [`✖ a ${TARGET_MISMATCH} reply carries no findings and no verdict — drop the headings`]
+}
+
+// Every violation, in a fixed order; an empty array is a clean review.
+function lint_review(review: string, round: number): ReadonlyArray<string> {
+	const sections = review_lint_sections.parse_sections(review)
+
+	if (markdown_shape.first_content_line(review).includes(TARGET_MISMATCH)) {
+		return mismatch_violations(sections)
+	}
+
+	const shape = round === SECOND_ROUND ? round_two_violations : round_one_violations
+
+	return [...markdown_shape.fence_violation(review, 'review'), ...shape(sections)]
+}
+
+// The violations followed by one line naming the rubric section that shapes the round's output; a
+// clean review stays empty, so `ok` is still the only output of a pass.
+function with_reference(violations: ReadonlyArray<string>, round: number): ReadonlyArray<string> {
+	if (violations.length === 0) return violations
+
+	const section = round === SECOND_ROUND ? ROUND_TWO_SECTION : ROUND_ONE_SECTION
+
+	return [...violations, `→ the format: ${RUBRIC} → "${section}"`]
+}
+
+const review_lint = { lint_review, with_reference }
+
+export { review_lint }

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

@@ -0,0 +1,102 @@
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import type { StopFinding } from '#scripts/run/ship/run-ship-review'
+import { review_stop_log, type StopLine } from './review-stop-log'
+
+// The findings earlier review stops of the same lane recorded, carried into the fix of the next stop and
+// into the next review (joshuafolkken/kit#4780): a fix that saw only the latest finding broke the
+// constraint an earlier one set on the same line, and came back as a new Medium round after round.
+//
+// **The durable stop log is the source** — the one record that keeps a finding's `<file>[:<line>]` and
+// its reason. A ship round that passed on fixes made in place is in it too, marked fixed, and so is an
+// agent's own `review:record` round whose findings carry their reason (joshuafolkken/kit#4817). The
+// ledger keeps only the file, so a finding recorded without a reason is not carried.
+
+const PRIOR_LIMIT = 5
+// Each entry is bounded, so five of them never push a reviewer prompt past `MAX_VALUE_LENGTH`.
+const ENTRY_LENGTH_LIMIT = 400
+const LINE_SUFFIX = /:\d.*$/u
+const KEY_SEPARATOR = ' — '
+const LINE_BREAKS = /[\n\r]+/gu
+
+function file_of(location: string): string {
+	return location.replace(LINE_SUFFIX, '')
+}
+
+function key_of(finding: Pick<StopFinding, 'location' | 'sentence'>): string {
+	return `${finding.location}${KEY_SEPARATOR}${finding.sentence}`
+}
+
+// An entry is one line of a prompt, so it never carries a line break or a control character
+// `is_safe_prompt` refuses. Its parenthetical holds no `; `, the separator the reviewer prompt joins
+// entries with.
+function entry_text(line: StopLine): string {
+	const disposition = line.fixed === true ? 'fixed in place' : 'stopped'
+	const text = `${key_of(line)} (${line.kind}, ${disposition} in the ${line.stage} stage)`
+
+	return agent_role_profile
+		.printable(text.replaceAll(LINE_BREAKS, ' '))
+		.slice(0, ENTRY_LENGTH_LIMIT)
+}
+
+// The latest findings of the lane's issue that `is_kept` admits, oldest first.
+function latest(
+	issue: string,
+	is_kept: (line: StopLine) => boolean,
+	log_path?: string,
+): ReadonlyArray<string> {
+	return review_stop_log
+		.read(log_path)
+		.filter((line) => String(line.issue) === issue && is_kept(line))
+		.slice(-PRIOR_LIMIT)
+		.map((line) => entry_text(line))
+}
+
+// The earlier findings on a file the current stop cites, the current stop's own lines left out — the
+// stop is recorded before it is handed back.
+function on_files(
+	issue: string,
+	current: ReadonlyArray<StopFinding>,
+	log_path?: string,
+): ReadonlyArray<string> {
+	const files = new Set(current.map((finding) => file_of(finding.location)))
+	const own = new Set(current.map((finding) => key_of(finding)))
+
+	return latest(
+		issue,
+		(line) => files.has(file_of(line.location)) && !own.has(key_of(line)),
+		log_path,
+	)
+}
+
+// The lines the stop context prints after the changed files; none when no earlier finding applies.
+function fix_lines(entries: ReadonlyArray<string> | undefined): ReadonlyArray<string> {
+	if (entries === undefined || entries.length === 0) return []
+
+	return [
+		'Earlier review findings on the same files in this lane — confirm the fix still meets each before shipping again:',
+		...entries.map((entry) => `- ${entry}`),
+	]
+}
+
+// One sentence for a reviewer prompt, which stays one line; none when the lane has no earlier stop.
+function prompt_clauses(issue: string, log_path?: string): ReadonlyArray<string> {
+	const entries = latest(issue, () => true, log_path)
+
+	if (entries.length === 0) return []
+
+	return [
+		`Earlier review rounds in this lane recorded these findings: ${entries.join('; ')}.`,
+		'Check that the change still meets each of them, and report a change that breaks one as a finding.',
+	]
+}
+
+const review_prior_findings = {
+	ENTRY_LENGTH_LIMIT,
+	PRIOR_LIMIT,
+	fix_lines,
+	latest,
+	on_files,
+	prompt_clauses,
+}
+
+export { review_prior_findings }