diff options
| author | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
|---|---|---|
| committer | Claude <noreply@anthropic.com> | 2026-11-06 00:54:48 +0000 |
| commit | 7aba3deae3ff17d032c37e07d2929d1426b34278 (patch) | |
| tree | 9c482f9acda1599bd2f9bed95a6a46b75e634e80 /plugins/code-modernization/hooks/review | |
| parent | 5472f5f56e0070feeeb464318b316714fe3e9105 (diff) | |
| parent | b8331dd69ab3e132bbf8cd6e89b5d8c1747e21b1 (diff) | |
Merge remote-tracking branch 'origin/main' into add-plugin/xcodeadd-plugin/xcode
Diffstat (limited to 'plugins/code-modernization/hooks/review')
| -rw-r--r-- | plugins/code-modernization/hooks/review/deck.ts | 127 | ||||
| -rw-r--r-- | plugins/code-modernization/hooks/review/ledger.ts | 78 |
2 files changed, 205 insertions, 0 deletions
diff --git a/plugins/code-modernization/hooks/review/deck.ts b/plugins/code-modernization/hooks/review/deck.ts new file mode 100644 index 00000000..b03739ea --- /dev/null +++ b/plugins/code-modernization/hooks/review/deck.ts @@ -0,0 +1,127 @@ +import type { ReviewLedger, ReviewVerdict } from '../reader/progress' +import { needsReview, type Rule, type RuleSet } from '../reader/rules' + +/** + * The rule review deck: the rules a person should look at, in the order they + * matter, and the ledger of what that person decided. The ledger is a file + * of its own beside the rules (`RULE_REVIEWS.json`, with a readable + * `RULE_REVIEWS.md`), so the agent-written rules file is never edited. + */ + +export type DeckScope = 'flagged' | 'p0' | 'all' + +const weight = (rule: Rule): number => + (rule.priority === 'P0' ? 0 : rule.priority === 'P1' ? 10 : 20) + + (rule.sme !== undefined ? 0 : 2) + + (rule.defect !== undefined ? 0 : 1) + + (rule.confidence !== undefined && rule.confidence !== 'High' ? 0 : 1) + +/** The rules to review under `scope`, optionally only those citing a file or under a domain. */ +export function queueOf(rules: RuleSet, scope: DeckScope, filter = ''): Rule[] { + const wanted = filter.trim().toLowerCase() + + return rules.rules + .filter(rule => { + if (scope === 'flagged' && !(rule.priority === 'P0' && needsReview(rule))) { + return false + } + + if (scope === 'p0' && rule.priority !== 'P0') { + return false + } + + if (wanted === '') { + return true + } + + return ( + rule.id.toLowerCase() === wanted || + (rule.domain ?? '').toLowerCase().includes(wanted) || + rule.title.toLowerCase().includes(wanted) || + rule.citations.some(citation => citation.base.includes(wanted)) || + // What the rule says and what is suspected of it: "truncat" finds the rounding defect whatever its title. + [rule.statement, rule.then, rule.defect].some(text => (text ?? '').toLowerCase().includes(wanted)) + ) + }) + .map((rule, index) => ({ rule, index })) + .sort((a, b) => weight(a.rule) - weight(b.rule) || a.index - b.index) + .map(entry => entry.rule) +} + +/** The first card at or after `from` that has no verdict yet; `from` itself when all have. */ +export function nextUnreviewed(queue: readonly Rule[], ledger: ReviewLedger, from: number): number { + for (let step = 0; step < queue.length; step += 1) { + const index = (from + step) % queue.length + const rule = queue[index] + + if (rule !== undefined && ledger[rule.id] === undefined) { + return index + } + } + + return Math.min(Math.max(0, from), Math.max(0, queue.length - 1)) +} + +/** `ledger` with `rule` decided. */ +export function decide( + ledger: ReviewLedger, + rule: Rule, + verdict: ReviewVerdict, + atIso: string, +): ReviewLedger { + // The reviewer's own words on the rule stay through a new verdict: the deck decides, it does not rewrite what was said. + const note = ledger[rule.id]?.note + + return { ...ledger, [rule.id]: { verdict, at: atIso, title: rule.title, ...(note !== undefined && { note }) } } +} + +/** `ledger` with `rule`'s verdict taken back. */ +export function undecide(ledger: ReviewLedger, ruleId: string): ReviewLedger { + const { [ruleId]: _gone, ...rest } = ledger + + return rest +} + +export const tallyOf = (queue: readonly Rule[], ledger: ReviewLedger) => ({ + total: queue.length, + confirmed: queue.filter(rule => ledger[rule.id]?.verdict === 'confirmed').length, + wrong: queue.filter(rule => ledger[rule.id]?.verdict === 'wrong').length, + discuss: queue.filter(rule => ledger[rule.id]?.verdict === 'discuss').length, + open: queue.filter(rule => ledger[rule.id] === undefined).length, +}) + +/** The ledger as `RULE_REVIEWS.json` stores it. */ +export function ledgerJson(system: string, ledger: ReviewLedger): string { + return `${JSON.stringify({ system, version: 1, reviews: ledger }, null, 2)}\n` +} + +const VERDICT_WORDS: Record<ReviewVerdict, string> = { + confirmed: 'Confirmed', + wrong: 'Wrong', + discuss: 'Needs discussion', +} + +/** One table cell: one line, no pipe that would end it. */ +const cell = (text: string | undefined): string => (text ?? '').replace(/\s+/g, ' ').replace(/\\/g, '\\\\').replace(/\|/g, '\\|').trim() + +/** The ledger as a page a person or a model reads: `RULE_REVIEWS.md`. */ +export function ledgerMarkdown(system: string, ledger: ReviewLedger): string { + const entries = Object.entries(ledger).sort((a, b) => a[0].localeCompare(b[0], 'en', { numeric: true })) + const count = (verdict: ReviewVerdict) => entries.filter(([, entry]) => entry.verdict === verdict).length + + return [ + `# Rule reviews: ${system}`, + '', + `A person's verdict on individual business rules in \`BUSINESS_RULES.md\`, recorded from the review deck. ${count('confirmed')} confirmed, ${count('wrong')} wrong, ${count('discuss')} needing discussion.`, + '', + 'A rule marked **Wrong** or **Needs discussion** is not settled: do not build on it until it is resolved. A rule with no row here has not been reviewed.', + '', + '| Rule | Verdict | When | Title | Note |', + '|---|---|---|---|---|', + ...entries.map( + ([id, entry]) => + `| ${id} | ${VERDICT_WORDS[entry.verdict]} | ${entry.at.slice(0, 10)} | ${cell(entry.title)} | ${cell(entry.note)} |`, + ), + '', + ].join('\n') +} diff --git a/plugins/code-modernization/hooks/review/ledger.ts b/plugins/code-modernization/hooks/review/ledger.ts new file mode 100644 index 00000000..4ebc3b0f --- /dev/null +++ b/plugins/code-modernization/hooks/review/ledger.ts @@ -0,0 +1,78 @@ +import { plain } from '../text' +import type { ReviewLedger, ReviewVerdict } from '../reader/progress' + +/** + * `RULE_REVIEWS.json`, read without trusting it. Two writers keep it: this deck, and the `modernize-review` command + * for people who work without the pane. Each entry is `{ verdict, at, title?, note? }`, the note being the reviewer's + * own words. The file sits in a workspace anyone may have edited, and a model may have written it, so every value is + * checked: a verdict is one of three exact words, a rule id is one plain token, a title or a note is cut to one short + * plain line, and anything else in an entry is dropped. + */ + +const VERDICTS: readonly string[] = ['confirmed', 'wrong', 'discuss'] + +/** What a note may hold: a reviewer's sentence or two, not a document. */ +export const MAX_NOTE = 500 +const MAX_TITLE = 120 +const MAX_ENTRIES = 5_000 +const RULE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/ +const FORBIDDEN_ID = new Set(['__proto__', 'constructor', 'prototype']) + +const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value) + +/** The ledger a file's text holds; empty when it is not one. */ +export function parseLedger(text: string | null): ReviewLedger { + if (text === null || text.length > 4_000_000) { + return {} + } + + let raw: unknown + + try { + raw = JSON.parse(text) + } catch { + return {} + } + + if (!isRecord(raw) || !isRecord(raw.reviews)) { + return {} + } + + const ledger: ReviewLedger = {} + + for (const [id, item] of Object.entries(raw.reviews).slice(0, MAX_ENTRIES)) { + if (!RULE_ID.test(id) || FORBIDDEN_ID.has(id) || !isRecord(item) || typeof item.verdict !== 'string' || !VERDICTS.includes(item.verdict)) { + continue + } + + const title = typeof item.title === 'string' ? plain(item.title, MAX_TITLE) : '' + const note = typeof item.note === 'string' ? plain(item.note, MAX_NOTE) : '' + // A time is kept only when it is one: the page shows its date. + const at = typeof item.at === 'string' && /^\d{4}-\d{2}-\d{2}/.test(item.at) ? item.at.slice(0, 40) : '' + + ledger[id] = { verdict: item.verdict as ReviewVerdict, at, ...(title !== '' && { title }), ...(note !== '' && { note }) } + } + + return ledger +} + +/** + * The file's ledger with this session's decisions on top. `edits` maps a rule id to what the deck set it to, or null when the + * deck took its verdict back. What the other writer put in the file meanwhile stays, and a note the deck did not write is + * kept on a rule the deck decided again. + */ +export function mergeLedger(onDisk: ReviewLedger, edits: ReadonlyMap<string, ReviewLedger[string] | null>): ReviewLedger { + const merged: ReviewLedger = { ...onDisk } + + for (const [id, edit] of edits) { + if (edit === null) { + delete merged[id] + } else { + const note = edit.note ?? onDisk[id]?.note + + merged[id] = { ...edit, ...(note !== undefined && { note }) } + } + } + + return merged +} |
