diff options
Diffstat (limited to 'plugins/code-modernization/hooks/reader/rules.ts')
| -rw-r--r-- | plugins/code-modernization/hooks/reader/rules.ts | 438 |
1 files changed, 438 insertions, 0 deletions
diff --git a/plugins/code-modernization/hooks/reader/rules.ts b/plugins/code-modernization/hooks/reader/rules.ts new file mode 100644 index 00000000..080edab8 --- /dev/null +++ b/plugins/code-modernization/hooks/reader/rules.ts @@ -0,0 +1,438 @@ +import { baseName } from '../paths' +import { linesOf } from '../text' + +/** + * `analysis/<system>/BUSINESS_RULES.md`, read into rule cards. + * + * The file is written by an agent, and the agent's layout varies between models and + * runs. Three shapes are read: a card per rule under a `### <ID> · <title>` heading with + * a header line (`P0 · Calculation · confidence High · file:line`), the same heading with + * labelled fields (`**Category:**`, `**Priority:**`, `**Plain English:**`, a fenced + * Given/When/Then block, `**Edge cases handled:**`, `**Suspected defect:**`), and table + * rows for the lower priorities. Anything else is skipped, never thrown on. + */ + +export type Citation = { + /** The path as written (`legacy/x/app/cbl/A.cbl`, `A.cbl`, `app/cpy/B.cpy`). */ + path: string + /** Lower-cased base name, the key the x-ray matches a read file by. */ + base: string + from: number + to: number +} + +export type Rule = { + /** `P0-052`, or `R-<hash>` of the title for a table row that carries no id. */ + id: string + title: string + /** `P0`, `P1`, `P2`, or `''` when the file does not say. */ + priority: string + category?: string + confidence?: string + /** The rule's one-paragraph statement. */ + statement: string + given?: string + when?: string + then?: string + edgeCases: string[] + defect?: string + sme?: string + /** Every `file:line` the card names; the first is the rule's own source. */ + citations: Citation[] + /** The domain heading (`## D6 Interest & Fees`) the rule sits under. */ + domain?: string +} + +export type RuleSet = { + rules: Rule[] + byId: Map<string, Rule> + /** Lower-cased base name of a cited file, to the rules citing it. */ + byFileBase: Map<string, Rule[]> +} + +const CITATION = + /([A-Za-z0-9_][A-Za-z0-9_./-]*\.[A-Za-z][A-Za-z0-9]{0,7}):(\d+)(?:\s*[-–]\s*(\d+))?/g + +/** `P0-052`, `RULE-001`, `BR-D7-09`: letters, optional segments (a domain), then the number. */ +const ID = '[A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)*-\\d+[a-z]?' + +const CARD_HEADING = new RegExp(`^#{3,4}\\s+(${ID})\\s*[·:\\-–—]\\s*(.+?)\\s*$`) + +/** Sections that describe or summarise the rules rather than hold them: a legend, a panel summary, appendices, provenance. */ +const SKIPPED_SECTION = + /\b(?:index|appendix|open questions|rejected|refuted|how to read|p0 confirmation|provenance)\b/i + +const DOMAIN_HEADING = /^##\s+(.+?)\s*$/ + +const clean = (text: string) => + text + .replace(/\*\*/g, '') + .replace(/<br\s*\/?>(\s*)/gi, ' ') + .replace(/\s+/g, ' ') + .trim() + +/** Every `file:line[-line]` in `text`, in order, without duplicates. */ +export function citationsIn(text: string): Citation[] { + const seen = new Set<string>() + const out: Citation[] = [] + + for (const match of text.matchAll(CITATION)) { + const path = match[1] ?? '' + const from = Number(match[2]) + const to = match[3] !== undefined ? Number(match[3]) : from + const key = `${path}:${from}-${to}` + + if (path === '' || !Number.isFinite(from) || seen.has(key)) { + continue + } + + seen.add(key) + + out.push({ + path, + base: baseName(path).toLowerCase(), + from, + to: Math.max(from, to), + }) + } + + return out +} + +const priorityOf = (id: string, body: string): string => { + const fromId = /^(P\d)\b/.exec(id)?.[1] + + if (fromId !== undefined) { + return fromId + } + + const fromLabel = /\bPriority:?\s*\**\s*(P\d)\b/i.exec(body)?.[1]?.toUpperCase() + + if (fromLabel !== undefined) { + return fromLabel + } + + // `P0` · Calculation · confidence High · `app/cbl/A.cbl:10-20` + const header = linesOf(body).find(line => line.trim() !== '') ?? '' + + return /^\s*`?\**(P\d)\**`?\s*(?:·|$)/.exec(header)?.[1] ?? '' +} + +const gwtOf = (body: string, word: string): string | undefined => { + const match = new RegExp( + `\\*\\*${word}\\*\\*\\s*([\\s\\S]*?)(?=\\n[ \\t]*(?:[-*][ \\t]+)?>?\\s*\\*\\*(?:Given|When|Then)\\*\\*|\\n\\s*\\n|$)`, + 'i', + ).exec(body) + + const text = + match?.[1] !== undefined + ? clean(match[1].replace(/\n>\s?/g, ' ')).replace(/^[—–:-]\s*/, '') + : '' + + return text === '' ? undefined : text +} + +const markedOf = (body: string, marker: RegExp): string | undefined => { + for (const line of linesOf(body)) { + if (marker.test(line)) { + const text = clean(line.replace(/^>\s*/, '').replace(marker, '')) + .replace(/^[—–-]\s*/, '') + .trim() + + return text === '' ? undefined : text + } + } + + return undefined +} + +/** The text after `**Name:**` (or `**Name**:`) on its own line, for the labelled-fields layout. */ +const labelledOf = (body: string, name: string): string | undefined => { + const match = new RegExp(`^[ \\t]*\\*\\*${name}:?\\*\\*:?[ \\t]*(.*)$`, 'im').exec(body) + const text = match?.[1] !== undefined ? clean(match[1]) : '' + + return text === '' ? undefined : text +} + +/** + * Given/When/Then written as lines (`Given …`, `When …`, `Then …`, `And …`), usually inside a + * fenced block under `**Specification:**`. `And` lines continue the clause before them. + */ +const specOf = (body: string): { given?: string; when?: string; then?: string } => { + const block = /\*\*Specification:?\*\*:?\s*([\s\S]*?)(?=\n[ \t]*\*\*[A-Za-z][^*\n]*\*\*|$)/i.exec(body)?.[1] ?? '' + const clauses: Record<'given' | 'when' | 'then', string[]> = { given: [], when: [], then: [] } + let current: 'given' | 'when' | 'then' | undefined + + for (const raw of linesOf(block)) { + const line = raw.trim().replace(/^```\w*$/, '').replace(/^[-*]\s+/, '') + const match = /^(Given|When|Then|And)\s+(.*)$/.exec(line) + + if (match === null) { + continue + } + + const word = match[1] ?? '' + const rest = clean(match[2] ?? '') + + if (word === 'And') { + if (current !== undefined) { + clauses[current].push(rest) + } + + continue + } + + current = word.toLowerCase() as 'given' | 'when' | 'then' + clauses[current].push(rest) + } + + const join = (parts: string[]) => (parts.length === 0 ? undefined : parts.join(' · ')) + + return { given: join(clauses.given), when: join(clauses.when), then: join(clauses.then) } +} + +function cardOf( + id: string, + title: string, + body: string, + domain: string | undefined, +): Rule { + const lines = linesOf(body) + const header = lines.find(line => line.trim() !== '') ?? '' + const headerParts = header.split('·').map(part => clean(part)) + + const category = + headerParts + .slice(1) + .find(part => part !== '' && !/confidence/i.test(part) && !/`/.test(part)) ?? labelledOf(body, 'Category') + + const confidence = + /confidence\s*:?\s*\**\s*(High|Medium|Low)\b/i.exec(body)?.[1] ?? undefined + + const statement = + labelledOf(body, 'Plain English') ?? + lines + .slice(lines.indexOf(header) + 1) + .map(line => line.trim()) + .find( + line => + line !== '' && + !line.startsWith('>') && + !line.startsWith('|') && + !line.startsWith('**') && + !line.startsWith('-') && + !line.startsWith('#') && + !line.startsWith('`'), + ) ?? '' + + const edgeStart = lines.findIndex(line => /^\*\*Edge cases?[^*]*\*\*/i.test(line.trim())) + + const edgeCases: string[] = [] + + if (edgeStart >= 0) { + for (const line of lines.slice(edgeStart + 1)) { + const trimmed = line.trim() + + if (trimmed.startsWith('- ')) { + edgeCases.push(clean(trimmed.slice(2))) + } else if (trimmed !== '' && edgeCases.length > 0) { + break + } + } + } + + const spec = specOf(body) + const given = gwtOf(body, 'Given') ?? spec.given + const when = gwtOf(body, 'When') ?? spec.when + const then = gwtOf(body, 'Then') ?? spec.then + const defect = markedOf(body, /(?:⚠️?\s*\**\s*Suspected defect\**|^\s*\*\*Suspected defect:?\*\*:?)/i) + + // `❓ **SME question** — …`, or `**Confidence:** Medium — SME question: …` on the confidence line. + const smeInline = /\bSME questions?\s*:\s*(.+)$/im.exec(body)?.[1] + + const sme = + markedOf(body, /❓\s*\**\s*SME(?:\s+questions?)?\**/i) ?? + (smeInline !== undefined && clean(smeInline) !== '' ? clean(smeInline) : undefined) + + return { + id, + title: clean(title), + priority: priorityOf(id, body), + ...(category !== undefined && { category }), + ...(confidence !== undefined && { + confidence: confidence[0]?.toUpperCase() + confidence.slice(1).toLowerCase(), + }), + statement: clean(statement), + ...(given !== undefined && { given }), + ...(when !== undefined && { when }), + ...(then !== undefined && { then }), + edgeCases, + ...(defect !== undefined && { defect }), + ...(sme !== undefined && { sme }), + citations: citationsIn(body), + ...(domain !== undefined && { domain }), + } +} + +/** A short stable id for a rule that carries none: a hash of its title, so a verdict survives the table being rewritten in another order. */ +export function idOfTitle(title: string): string { + let hash = 2166136261 + + for (const char of title.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim()) { + hash = Math.imul(hash ^ char.charCodeAt(0), 16777619) + } + + return `R-${(hash >>> 0).toString(16).padStart(8, '0').slice(0, 6)}` +} + +function rowOf( + line: string, + domain: string | undefined, +): Rule | null { + const cells = line + .split('|') + .slice(1, -1) + .map(cell => cell.trim()) + + const first = cells[0] ?? '' + const titleMatch = /\*\*(.+?)\*\*/.exec(first) + + if (cells.length < 2 || titleMatch === null || /^-+$/.test(first)) { + return null + } + + const title = clean(titleMatch[1] ?? '') + + if (title === '' || /^rule$/i.test(title)) { + return null + } + + const idInTitle = new RegExp(`^(${ID})\\b`).exec(title)?.[1] + const category = clean(first.replace(titleMatch[0], '').replace(/<br\s*\/?>/gi, ' ')) + const gwt = cells[1] ?? '' + const part = (tag: string) => + clean(new RegExp(`\\*\\*${tag}\\*\\*\\s*(.*?)(?=\\*\\*[GWT]\\*\\*|$)`).exec(gwt)?.[1] ?? '') + + const given = part('G') + const when = part('W') + const then = part('T') + const flags = cells.slice(3).join(' ') + const priority = /\b(P\d)\b/.exec(`${flags} ${first}`)?.[1] ?? '' + + return { + id: idInTitle ?? idOfTitle(title), + title, + priority, + ...(category !== '' && { category }), + statement: '', + ...(given !== '' && { given }), + ...(when !== '' && { when }), + ...(then !== '' && { then }), + edgeCases: [], + ...(/⚠|defect/i.test(flags) && { defect: clean(flags) }), + ...(/❓|SME/i.test(flags) && { sme: clean(flags) }), + citations: citationsIn(line), + ...(domain !== undefined && { domain }), + } +} + +/** Parses BUSINESS_RULES.md. Never throws; an unreadable file is no rules. */ +export function parseRules(text: string): RuleSet { + const lines = linesOf(text) + const rules: Rule[] = [] + let domain: string | undefined + /** Set by a top-level heading: `# P1 rules` gives its rows a priority, an index or appendix is skipped. */ + let sectionPriority = '' + let isTopSkipped = false + let isSectionSkipped = false + + let open: { id: string; title: string; start: number; domain: string | undefined } | null = + null + + const close = (end: number) => { + if (open !== null) { + rules.push( + cardOf(open.id, open.title, lines.slice(open.start, end).join('\n'), open.domain), + ) + + open = null + } + } + + lines.forEach((line, index) => { + const isSkipped = isTopSkipped || isSectionSkipped + const card = isSkipped ? null : CARD_HEADING.exec(line) + + if (card !== null) { + close(index) + open = { id: card[1] ?? '', title: card[2] ?? '', start: index + 1, domain } + + return + } + + const top = /^#\s+(.+?)\s*$/.exec(line) + + if (top !== null) { + close(index) + sectionPriority = /\b(P\d)\b/.exec(top[1] ?? '')?.[1] ?? '' + isTopSkipped = SKIPPED_SECTION.test(top[1] ?? '') + isSectionSkipped = false + domain = undefined + + return + } + + const heading = DOMAIN_HEADING.exec(line) + + if (heading !== null && !line.startsWith('###')) { + close(index) + domain = clean(heading[1] ?? '') + isSectionSkipped = SKIPPED_SECTION.test(heading[1] ?? '') + + return + } + + if (/^#{1,4}\s/.test(line)) { + close(index) + + return + } + + if (open === null && !(isTopSkipped || isSectionSkipped) && line.startsWith('|')) { + const row = rowOf(line, domain) + + if (row !== null) { + rules.push(row.priority === '' ? { ...row, priority: sectionPriority } : row) + } + } + }) + + close(lines.length) + + const byId = new Map<string, Rule>() + const byFileBase = new Map<string, Rule[]>() + + for (const rule of rules) { + if (!byId.has(rule.id)) { + byId.set(rule.id, rule) + } + + for (const base of new Set(rule.citations.map(citation => citation.base))) { + const bucket = byFileBase.get(base) ?? [] + + bucket.push(rule) + byFileBase.set(base, bucket) + } + } + + return { rules, byId, byFileBase } +} + +/** The rules that need a person: a suspected defect, an SME note, or less than High confidence. */ +export function needsReview(rule: Rule): boolean { + return ( + rule.sme !== undefined || + rule.defect !== undefined || + (rule.confidence !== undefined && rule.confidence !== 'High') + ) +} |
