@webpieces/ai-hook-rules 0.0.1

package/src/core/build-context.ts

@@ -0,0 +1,96 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { stripTsNoise } from './strip-ts-noise';
+import { createIsLineDisabled } from './disable-directives';
+import {
+    ToolKind, NormalizedToolInput, NormalizedEdit,
+    EditContext, FileContext, BashContext,
+} from './types';
+
+export class BuiltContexts {
+    readonly fileContext: FileContext;
+    readonly editContexts: readonly EditContext[];
+
+    constructor(fileContext: FileContext, editContexts: readonly EditContext[]) {
+        this.fileContext = fileContext;
+        this.editContexts = editContexts;
+    }
+}
+
+export function buildContexts(
+    toolKind: ToolKind,
+    input: NormalizedToolInput,
+    workspaceRoot: string,
+): BuiltContexts {
+    const filePath = input.filePath;
+    const relativePath = path.relative(workspaceRoot, filePath);
+    const edits = input.edits;
+
+    const currentFileLines = readCurrentFileLines(filePath);
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    for (const e of edits) {
+        linesAdded += countLines(e.newString);
+        linesRemoved += countLines(e.oldString);
+    }
+
+    const projectedFileLines =
+        toolKind === 'Write'
+            ? countLines(edits.length > 0 ? edits[0].newString : '')
+            : currentFileLines + linesAdded - linesRemoved;
+
+    const fileContext = new FileContext(
+        toolKind,
+        filePath,
+        relativePath,
+        workspaceRoot,
+        currentFileLines,
+        linesAdded,
+        linesRemoved,
+        projectedFileLines,
+    );
+
+    const editContexts = edits.map((e, idx) => {
+        const addedContent = e.newString;
+        const stripped = stripTsNoise(addedContent);
+        const isLineDisabled = createIsLineDisabled(addedContent);
+        return new EditContext(
+            toolKind,
+            idx,
+            edits.length,
+            filePath,
+            relativePath,
+            workspaceRoot,
+            addedContent,
+            stripped,
+            addedContent.split('\n'),
+            stripped.split('\n'),
+            e.oldString,
+            isLineDisabled,
+        );
+    });
+
+    return new BuiltContexts(fileContext, editContexts);
+}
+
+export function buildBashContext(command: string, workspaceRoot: string): BashContext {
+    return new BashContext(command, workspaceRoot);
+}
+
+function readCurrentFileLines(filePath: string): number {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        return countLines(content);
+    } catch (err: unknown) {
+        // eslint-disable-next-line @webpieces/catch-error-pattern -- file-not-found is expected for new Write targets
+        void err;
+        return 0;
+    }
+}
+
+function countLines(s: string): number {
+    if (!s) return 0;
+    return s.split('\n').length;
+}

package/src/core/configs/default.ts

@@ -0,0 +1,19 @@
+// webpieces-disable no-any-unknown -- rule options are opaque at framework level
+export const defaultRules: Record<string, Record<string, unknown>> = {
+    'no-any-unknown': { enabled: true },
+    'max-file-lines': { enabled: true, limit: 900 },
+    'file-location': {
+        enabled: true,
+        allowedRootFiles: ['jest.setup.ts'],
+        excludePaths: [
+            'node_modules', 'dist', '.nx', '.git',
+            'architecture', 'tmp', 'scripts',
+        ],
+    },
+    'no-destructure': { enabled: true, allowTopLevel: true },
+    'require-return-type': { enabled: true },
+    'no-unmanaged-exceptions': { enabled: true },
+    'catch-error-pattern': { enabled: true },
+};
+
+export const defaultRulesDir: readonly string[] = [];

package/src/core/disable-directives.ts

@@ -0,0 +1,90 @@
+import type { IsLineDisabled } from './types';
+
+const DIRECTIVE_RE =
+    /\/\/\s*(?:ai-hook-disable|webpieces-disable)(?:-(next|file|all))?(?:\s+([\w\-*,\s]+?))?(?:\s*--\s*(.*))?\s*$/;
+
+export class DirectiveIndex {
+    private readonly lineDisables: Map<number, Set<string>>;
+    private readonly fileDisables: Set<string>;
+
+    constructor(lineDisables: Map<number, Set<string>>, fileDisables: Set<string>) {
+        this.lineDisables = lineDisables;
+        this.fileDisables = fileDisables;
+    }
+
+    isLineDisabled(lineNum: number, ruleName: string): boolean {
+        if (this.fileDisables.has('*') || this.fileDisables.has(ruleName)) return true;
+        const set = this.lineDisables.get(lineNum);
+        if (!set) return false;
+        return set.has('*') || set.has(ruleName);
+    }
+}
+
+function parseRuleList(raw: string | undefined): readonly string[] {
+    if (!raw || raw.trim() === '' || raw.trim() === '*') return ['*'];
+    return raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+function nextTargetLine(lines: readonly string[], lineIdx: number): number | null {
+    for (let j = lineIdx + 1; j < lines.length; j += 1) {
+        const trimmed = lines[j].trim();
+        if (trimmed === '') continue;
+        if (/^\/\/\s*(?:ai-hook-disable|webpieces-disable)/.test(trimmed)) continue;
+        return j + 1;
+    }
+    return null;
+}
+
+function addDisable(map: Map<number, Set<string>>, lineNum: number, rules: readonly string[]): void {
+    if (!map.has(lineNum)) map.set(lineNum, new Set<string>());
+    const set = map.get(lineNum)!;
+    for (const r of rules) set.add(r);
+}
+
+function resolveTarget(
+    line: string, lines: readonly string[], i: number,
+    map: Map<number, Set<string>>, rules: readonly string[],
+): void {
+    const beforeComment = line.slice(0, line.indexOf('//')).trim();
+    if (beforeComment !== '') {
+        addDisable(map, i + 1, rules);
+    } else {
+        const target = nextTargetLine(lines, i);
+        if (target !== null) addDisable(map, target, rules);
+    }
+}
+
+export function parseDirectives(source: string): DirectiveIndex {
+    const lines = source.split('\n');
+    const lineDisables = new Map<number, Set<string>>();
+    const fileDisables = new Set<string>();
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const match = line.match(DIRECTIVE_RE);
+        if (!match) continue;
+        const variant = match[1] || null;
+        const rules = parseRuleList(match[2] || '');
+
+        if (variant === 'file') {
+            if (i < 20) { for (const r of rules) fileDisables.add(r); }
+            continue;
+        }
+        if (variant === 'next') {
+            const target = nextTargetLine(lines, i);
+            if (target !== null) addDisable(lineDisables, target, rules);
+            continue;
+        }
+        if (variant === 'all') {
+            resolveTarget(line, lines, i, lineDisables, ['*']);
+            continue;
+        }
+        resolveTarget(line, lines, i, lineDisables, rules);
+    }
+    return new DirectiveIndex(lineDisables, fileDisables);
+}
+
+export function createIsLineDisabled(source: string): IsLineDisabled {
+    const index = parseDirectives(source);
+    return (lineNum: number, ruleName: string): boolean => index.isLineDisabled(lineNum, ruleName);
+}

package/src/core/instruct-ai-writer.ts

@@ -0,0 +1,15 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const INSTRUCT_DIR = '.webpieces/instruct-ai';
+
+export function writeTemplateIfMissing(workspaceRoot: string, templateName: string): void {
+    const dir = path.join(workspaceRoot, INSTRUCT_DIR);
+    const filePath = path.join(dir, templateName);
+    if (fs.existsSync(filePath)) return;
+
+    const templatePath = path.join(__dirname, '..', '..', 'templates', templateName);
+    const content = fs.readFileSync(templatePath, 'utf-8');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, content);
+}

package/src/core/load-config.ts

@@ -0,0 +1,3 @@
+// Re-export the shared workspace config loader so ai-hooks and the Nx
+// validate-code executor use the same webpieces.config.json.
+export { loadConfig, findConfigFile, CONFIG_FILENAME } from '@webpieces/rules-config';

package/src/core/load-rules.ts

@@ -0,0 +1,130 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { Rule, ResolvedConfig } from './types';
+import { toError } from './to-error';
+
+const REQUIRED_FIELDS: readonly string[] = ['name', 'description', 'scope', 'files', 'check'];
+const VALID_SCOPES = new Set(['edit', 'file', 'bash']);
+
+export function loadRules(config: ResolvedConfig, workspaceRoot: string): readonly Rule[] {
+    const builtIns = loadBuiltInRules();
+    const custom = loadCustomRules(config.rulesDir, workspaceRoot);
+    const all = [...builtIns, ...custom];
+    return all.filter((rule) => validateRule(rule));
+}
+
+function loadBuiltInRules(): Rule[] {
+    const registry: readonly string[] = require('./rules/index').builtInRuleNames;
+    const modules: Rule[] = [];
+    for (const name of registry) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const mod = require(`./rules/${name}`);
+            modules.push(mod.default || mod);
+        } catch (err: unknown) {
+            const error = toError(err);
+            process.stderr.write(`[ai-hooks] failed to load built-in rule ${name}: ${error.message}\n`);
+        }
+    }
+    return modules;
+}
+
+function loadCustomRules(rulesDirs: readonly string[], workspaceRoot: string): Rule[] {
+    const modules: Rule[] = [];
+    for (const dir of rulesDirs) {
+        const absDir = path.isAbsolute(dir) ? dir : path.join(workspaceRoot, dir);
+        if (!fs.existsSync(absDir)) {
+            process.stderr.write(`[ai-hooks] rulesDir not found: ${absDir}\n`);
+            continue;
+        }
+        let entries: string[];
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            entries = fs.readdirSync(absDir).filter((e) => e.endsWith('.js'));
+        } catch (err: unknown) {
+            const error = toError(err);
+            process.stderr.write(`[ai-hooks] cannot read rulesDir ${absDir}: ${error.message}\n`);
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(absDir, entry);
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+            try {
+                const mod = require(full);
+                modules.push(mod.default || mod);
+            } catch (err: unknown) {
+                const error = toError(err);
+                process.stderr.write(`[ai-hooks] failed to load custom rule ${full}: ${error.message}\n`);
+            }
+        }
+    }
+    return modules;
+}
+
+// webpieces-disable no-any-unknown -- validates untrusted require() output at system boundary
+function validateRule(rule: unknown): rule is Rule {
+    if (!rule || typeof rule !== 'object') {
+        process.stderr.write('[ai-hooks] rule is not an object, skipping\n');
+        return false;
+    }
+    // webpieces-disable no-any-unknown -- narrowing from unknown at system boundary
+    const obj = rule as Record<string, unknown>;
+    for (const field of REQUIRED_FIELDS) {
+        if (obj[field] === undefined) {
+            const name = typeof obj['name'] === 'string' ? obj['name'] : '<unnamed>';
+            process.stderr.write(`[ai-hooks] rule "${name}" missing required field: ${field}\n`);
+            return false;
+        }
+    }
+    if (!VALID_SCOPES.has(obj['scope'] as string)) {
+        process.stderr.write(`[ai-hooks] rule "${obj['name']}" has invalid scope: ${String(obj['scope'])}\n`);
+        return false;
+    }
+    if (!Array.isArray(obj['files'])) {
+        process.stderr.write(`[ai-hooks] rule "${obj['name']}" files must be an array\n`);
+        return false;
+    }
+    if (typeof obj['check'] !== 'function') {
+        process.stderr.write(`[ai-hooks] rule "${obj['name']}" check must be a function\n`);
+        return false;
+    }
+    return true;
+}
+
+export function globMatches(pattern: string, filePath: string): boolean {
+    const regex = globToRegex(pattern);
+    return regex.test(filePath);
+}
+
+function globToRegex(pattern: string): RegExp {
+    let re = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                re += '.*';
+                i += 2;
+                if (pattern[i] === '/') i += 1;
+                continue;
+            }
+            re += '[^/]*';
+            i += 1;
+            continue;
+        }
+        if (ch === '?') {
+            re += '[^/]';
+            i += 1;
+            continue;
+        }
+        if ('.+^$(){}|[]\\'.includes(ch)) {
+            re += '\\' + ch;
+            i += 1;
+            continue;
+        }
+        re += ch;
+        i += 1;
+    }
+    return new RegExp('^' + re + '$');
+}

package/src/core/rejection-log.ts

@@ -0,0 +1,163 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { ToolKind, NormalizedToolInput, BlockedResult } from './types';
+
+const HOOKS_DIR = '.webpieces/hooks';
+const LOG_FILE = 'hook-rejection.log';
+const LOG_FILE_PREV = 'hook-rejection.1.log';
+const MAX_LOG_BYTES = 512 * 1024; // 512 KB — rotate when exceeded
+const MAX_AGE_DAYS = 7;
+
+const RULE_NAME_RE = /^\[([^\]]+)\] \(/gm;
+
+export function logRejection(
+    toolKind: ToolKind,
+    input: NormalizedToolInput,
+    result: BlockedResult,
+    cwd: string,
+): void {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const now = new Date();
+        const timestamp = now.toISOString();
+        const epochMs = String(now.getTime());
+        const dateStr = timestamp.slice(0, 10);
+
+        const hooksDir = path.join(cwd, HOOKS_DIR);
+        const dayDir = path.join(hooksDir, dateStr);
+        fs.mkdirSync(dayDir, { recursive: true });
+
+        const relativePath = computeRelativePath(input.filePath, cwd);
+        const ruleNames = extractRuleNames(result.report);
+        const detailFileName = `writeInfo-${epochMs}.md`;
+        const detailRelPath = `${dateStr}/${detailFileName}`;
+
+        const detail = buildDetailContent(timestamp, toolKind, relativePath, ruleNames, result.report, input);
+        fs.writeFileSync(path.join(dayDir, detailFileName), detail);
+
+        const logPath = path.join(hooksDir, LOG_FILE);
+        rotateLogFile(logPath, path.join(hooksDir, LOG_FILE_PREV));
+
+        const logLine = `[${timestamp}]\t${toolKind}\t${relativePath}\t[${ruleNames.join(',')}]\t${detailRelPath}\n`;
+        fs.appendFileSync(logPath, logLine);
+
+        rotateOldDays(hooksDir, MAX_AGE_DAYS);
+    } catch (err: unknown) {
+        //const error = toError(err);
+        void err;
+    }
+}
+
+function computeRelativePath(filePath: string, cwd: string): string {
+    if (filePath.startsWith(cwd)) {
+        const rel = filePath.slice(cwd.length);
+        if (rel.startsWith('/')) return rel.slice(1);
+        return rel;
+    }
+    return filePath;
+}
+
+function extractRuleNames(report: string): string[] {
+    const names: string[] = [];
+    let match = RULE_NAME_RE.exec(report);
+    while (match !== null) {
+        names.push(match[1]);
+        match = RULE_NAME_RE.exec(report);
+    }
+    RULE_NAME_RE.lastIndex = 0;
+    return names;
+}
+
+function buildDetailContent(
+    timestamp: string,
+    toolKind: ToolKind,
+    relativePath: string,
+    ruleNames: string[],
+    report: string,
+    input: NormalizedToolInput,
+): string {
+    const lines: string[] = [];
+    lines.push('# Hook Rejection Detail');
+    lines.push('');
+    lines.push(`- **Timestamp:** ${timestamp}`);
+    lines.push(`- **Tool:** ${toolKind}`);
+    lines.push(`- **File:** ${relativePath}`);
+    lines.push(`- **Rules violated:** ${ruleNames.join(', ')}`);
+    lines.push('');
+    lines.push('## Report');
+    lines.push('');
+    lines.push('```');
+    lines.push(report.trimEnd());
+    lines.push('```');
+    lines.push('');
+    lines.push('## Content Being Written');
+    lines.push('');
+
+    if (toolKind === 'Write') {
+        const content = input.edits.length > 0 ? input.edits[0].newString : '';
+        lines.push('```typescript');
+        lines.push(content.trimEnd());
+        lines.push('```');
+    } else {
+        for (let i = 0; i < input.edits.length; i += 1) {
+            const edit = input.edits[i];
+            lines.push(`### Edit ${String(i + 1)} of ${String(input.edits.length)}`);
+            lines.push('');
+            lines.push('**old_string:**');
+            lines.push('```typescript');
+            lines.push(edit.oldString.trimEnd());
+            lines.push('```');
+            lines.push('');
+            lines.push('**new_string:**');
+            lines.push('```typescript');
+            lines.push(edit.newString.trimEnd());
+            lines.push('```');
+            lines.push('');
+        }
+    }
+
+    return lines.join('\n') + '\n';
+}
+
+function rotateLogFile(logPath: string, prevPath: string): void {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size > MAX_LOG_BYTES) {
+            if (fs.existsSync(prevPath)) fs.unlinkSync(prevPath);
+            fs.renameSync(logPath, prevPath);
+        }
+    } catch (err: unknown) {
+        //const error = toError(err);
+        void err;
+    }
+}
+
+function rotateOldDays(hooksDir: string, maxAgeDays: number): void {
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    let entries: string[];
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        entries = fs.readdirSync(hooksDir);
+    } catch (err: unknown) {
+        //const error = toError(err);
+        void err;
+        return;
+    }
+
+    for (const entry of entries) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(entry)) continue;
+        const dirDate = new Date(entry + 'T00:00:00Z');
+        if (isNaN(dirDate.getTime())) continue;
+        if (dirDate.getTime() < cutoff) {
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+            try {
+                fs.rmSync(path.join(hooksDir, entry), { recursive: true, force: true });
+            } catch (err: unknown) {
+                //const error = toError(err);
+                void err;
+            }
+        }
+    }
+}

package/src/core/report.ts

@@ -0,0 +1,35 @@
+import type { RuleGroup, Violation } from './types';
+
+export function formatReport(relativePath: string, ruleGroups: readonly RuleGroup[]): string {
+    const lines: string[] = [];
+    lines.push(`\u274c webpieces ai-hooks blocked this write: ${relativePath}`);
+    lines.push('');
+
+    for (const group of ruleGroups) {
+        const count = group.violations.length;
+        const label = count === 1 ? '1 violation' : `${count} violations`;
+        lines.push(`[${group.ruleName}] (${label})`);
+        for (const v of group.violations) {
+            const editPrefix = formatEditPrefix(v);
+            lines.push(`  ${editPrefix}L${String(v.line)}:  ${v.snippet}`);
+            lines.push(`    \u2192 ${v.message}`);
+        }
+        if (group.fixHint.length > 0) {
+            for (let i = 0; i < group.fixHint.length; i += 1) {
+                lines.push(`  Fix Option ${String(i + 1)}: ${group.fixHint[i]}`);
+            }
+        }
+        lines.push('');
+    }
+
+    lines.push('This is a pre-write check. Fix and retry the Write/Edit.');
+    lines.push('');
+    return lines.join('\n');
+}
+
+function formatEditPrefix(v: Violation): string {
+    if (v.editIndex !== undefined && v.editCount !== undefined && v.editCount > 1) {
+        return `edit ${String(v.editIndex + 1)}/${String(v.editCount)} `;
+    }
+    return '';
+}

package/src/core/rules/catch-error-pattern.ts

@@ -0,0 +1,124 @@
+import type { EditRule, EditContext, Violation } from '../types';
+import { Violation as V } from '../types';
+import { writeTemplateIfMissing } from '../instruct-ai-writer';
+
+/**
+ * Matches a catch clause opening: } catch (paramName: typeAnnotation) {
+ * Captures: group 1 = param name, group 2 = type annotation (if present)
+ */
+const CATCH_PATTERN = /\bcatch\s*\(\s*(\w+)(?:\s*:\s*(\w+))?\s*\)/;
+
+/**
+ * Matches the required toError first statement (with or without comment-out).
+ * Group 1 = variable name, group 2 = param passed to toError
+ */
+const TO_ERROR_PATTERN = /^\s*(?:\/\/\s*)?const\s+(\w+)\s*=\s*toError\(\s*(\w+)\s*\)\s*;?\s*$/;
+
+const catchErrorPatternRule: EditRule = {
+    name: 'catch-error-pattern',
+    description: 'Catch blocks must use: catch (err: unknown) { const error = toError(err); }',
+    scope: 'edit',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: {},
+    fixHint: [
+        'VERY IMPORTANT: READ .webpieces/instruct-ai/webpieces.exceptions.md to understand why and how to fix this!',
+        'catch (err: unknown) { const error = toError(err); ... }',
+        'Or to explicitly ignore: catch (err: unknown) { //const error = toError(err); }',
+        'For nested catches: catch (err2: unknown) { const error2 = toError(err2); }',
+        '// webpieces-disable catch-error-pattern -- <reason>',
+    ],
+
+    check(ctx: EditContext): readonly Violation[] {
+        const violations: V[] = [];
+        const lines = ctx.strippedLines;
+
+        for (let i = 0; i < lines.length; i += 1) {
+            const stripped = lines[i];
+            const catchMatch = CATCH_PATTERN.exec(stripped);
+            if (!catchMatch) continue;
+
+            const lineNum = i + 1;
+            if (ctx.isLineDisabled(lineNum, 'catch-error-pattern')) continue;
+
+            const actualParam = catchMatch[1];
+            const typeAnnotation = catchMatch[2];
+
+            // Determine expected names from suffix on the actual param (err, err2, err3...)
+            const suffixMatch = actualParam.match(/^err(\d*)$/);
+            const suffix = suffixMatch ? suffixMatch[1] : '';
+            const expectedParam = 'err' + suffix;
+            const expectedVar = 'error' + suffix;
+
+            // Check parameter name
+            if (actualParam !== expectedParam) {
+                violations.push(new V(
+                    lineNum,
+                    ctx.lines[i].trim(),
+                    `Catch parameter must be named "${expectedParam}" (or "err2", "err3" for nested catches), got "${actualParam}"`,
+                ));
+            }
+
+            // Check type annotation is unknown
+            if (typeAnnotation !== 'unknown') {
+                const msg = typeAnnotation
+                    ? `Catch parameter must be typed as "unknown": catch (${expectedParam}: unknown), got "${typeAnnotation}"`
+                    : `Catch parameter must be typed as "unknown": catch (${expectedParam}: unknown)`;
+                violations.push(new V(lineNum, ctx.lines[i].trim(), msg));
+            }
+
+            // Find next non-blank line after the catch opening to check for toError
+            const toErrorResult = findToErrorStatement(lines, i + 1);
+            if (toErrorResult === 'not-found') {
+                violations.push(new V(
+                    lineNum,
+                    ctx.lines[i].trim(),
+                    `Catch block must call toError(${actualParam}) as first statement: const ${expectedVar} = toError(${actualParam}); or //const ${expectedVar} = toError(${actualParam});`,
+                ));
+            } else if (toErrorResult !== 'end-of-content') {
+                // Validate variable name and param match
+                if (toErrorResult.varName !== expectedVar) {
+                    const toErrorLineNum = toErrorResult.lineIndex + 1;
+                    violations.push(new V(
+                        toErrorLineNum,
+                        ctx.lines[toErrorResult.lineIndex].trim(),
+                        `Error variable must be named "${expectedVar}", got "${toErrorResult.varName}"`,
+                    ));
+                }
+                if (toErrorResult.paramName !== actualParam) {
+                    const toErrorLineNum = toErrorResult.lineIndex + 1;
+                    violations.push(new V(
+                        toErrorLineNum,
+                        ctx.lines[toErrorResult.lineIndex].trim(),
+                        `toError() must be called with "${actualParam}", got "${toErrorResult.paramName}"`,
+                    ));
+                }
+            }
+        }
+        if (violations.length > 0) writeTemplateIfMissing(ctx.workspaceRoot, 'webpieces.exceptions.md');
+        return violations;
+    },
+};
+
+interface ToErrorMatch {
+    varName: string;
+    paramName: string;
+    lineIndex: number;
+}
+
+function findToErrorStatement(lines: readonly string[], startIndex: number): ToErrorMatch | 'not-found' | 'end-of-content' {
+    for (let j = startIndex; j < lines.length; j += 1) {
+        const line = lines[j].trim();
+        if (line === '' || line === '{') continue;
+
+        const match = TO_ERROR_PATTERN.exec(line);
+        if (match) {
+            return { varName: match[1], paramName: match[2], lineIndex: j };
+        }
+        // First non-blank line is not a toError call
+        return 'not-found';
+    }
+    // Ran off the end of the edit content — can't validate further
+    return 'end-of-content';
+}
+
+export default catchErrorPatternRule;