@webpieces/ai-hook-rules 0.0.1

package/src/core/runner.ts

@@ -0,0 +1,205 @@
+import * as path from 'path';
+
+import { buildContexts, buildBashContext } from './build-context';
+import { loadConfig } from './load-config';
+import { loadRules, globMatches } from './load-rules';
+import { toError } from './to-error';
+import { formatReport } from './report';
+import {
+    ToolKind, NormalizedToolInput, BlockedResult,
+    Rule, EditRule, FileRule, BashRule, Violation, RuleGroup,
+    EditContext, FileContext, BashContext,
+    ResolvedConfig, ResolvedRuleConfig, RuleOptions,
+} from './types';
+
+export function run(
+    toolKind: ToolKind,
+    input: NormalizedToolInput,
+    cwd: string,
+): BlockedResult | null {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return runInternal(toolKind, input, cwd);
+    } catch (err: unknown) {
+        const error = toError(err);
+        console.error(`[ai-hooks] runner crashed (failing open): ${error.message}`);
+        return null;
+    }
+}
+
+function runInternal(
+    toolKind: ToolKind,
+    input: NormalizedToolInput,
+    cwd: string,
+): BlockedResult | null {
+    const config = loadConfig(cwd);
+    if (!config.configPath) return null;
+
+    const workspaceRoot = path.dirname(config.configPath);
+    const rules = loadRules(config, workspaceRoot);
+    if (rules.length === 0) return null;
+
+    const contexts = buildContexts(toolKind, input, workspaceRoot);
+    const relativePath = path.relative(workspaceRoot, input.filePath);
+
+    const editGroups = runEditRules(rules, contexts.editContexts, config);
+    const fileGroups = runFileRules(rules, contexts.fileContext, config);
+    const allGroups = [...editGroups, ...fileGroups];
+
+    if (allGroups.length === 0) return null;
+
+    const report = formatReport(relativePath, allGroups);
+    return new BlockedResult(report);
+}
+
+export function runBash(command: string, cwd: string): BlockedResult | null {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return runBashInternal(command, cwd);
+    } catch (err: unknown) {
+        const error = toError(err);
+        console.error(`[ai-hooks] bash runner crashed (failing open): ${error.message}`);
+        return null;
+    }
+}
+
+function runBashInternal(command: string, cwd: string): BlockedResult | null {
+    const config = loadConfig(cwd);
+    if (!config.configPath) return null;
+
+    const workspaceRoot = path.dirname(config.configPath);
+    const rules = loadRules(config, workspaceRoot);
+    if (rules.length === 0) return null;
+
+    const ctx = buildBashContext(command, workspaceRoot);
+    const groups = runBashRules(rules, ctx, config);
+    if (groups.length === 0) return null;
+
+    const report = formatReport('<bash>', groups);
+    return new BlockedResult(report);
+}
+
+function safeCheckBash(rule: BashRule, ctx: BashContext): readonly Violation[] {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return rule.check(ctx);
+    } catch (err: unknown) {
+        const error = toError(err);
+        process.stderr.write(`[ai-hooks] rule ${rule.name} crashed: ${error.message}\n`);
+        return [];
+    }
+}
+
+function runBashRules(
+    rules: readonly Rule[],
+    bashContext: BashContext,
+    config: ResolvedConfig,
+): readonly RuleGroup[] {
+    const groups: RuleGroup[] = [];
+    for (const rule of rules) {
+        if (rule.scope !== 'bash') continue;
+        const ruleConfig = config.rules.get(rule.name);
+        if (!ruleConfig || ruleConfig.enabled === false) continue;
+        bashContext.options = mergeOptions(rule.defaultOptions, ruleConfig);
+        const vs = safeCheckBash(rule as BashRule, bashContext);
+        if (vs.length > 0) {
+            groups.push(new RuleGroup(
+                rule.name, rule.description, [...rule.fixHint], [...vs],
+            ));
+        }
+    }
+    return groups;
+}
+
+function ruleMatchesFile(rule: Rule, relativePath: string): boolean {
+    for (const pattern of rule.files) {
+        if (globMatches(pattern, relativePath)) return true;
+    }
+    return false;
+}
+
+function mergeOptions(defaultOptions: RuleOptions, ruleConfig: ResolvedRuleConfig): RuleOptions {
+    // webpieces-disable no-any-unknown -- building an options bag from opaque RuleOptions
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(defaultOptions)) out[key] = defaultOptions[key];
+    for (const key of Object.keys(ruleConfig.options)) {
+        if (key === 'enabled') continue;
+        out[key] = ruleConfig.options[key];
+    }
+    return out;
+}
+
+function safeCheckEdit(rule: EditRule, ctx: EditContext): readonly Violation[] {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return rule.check(ctx);
+    } catch (err: unknown) {
+        const error = toError(err);
+        process.stderr.write(`[ai-hooks] rule ${rule.name} crashed: ${error.message}\n`);
+        return [];
+    }
+}
+
+function safeCheckFile(rule: FileRule, ctx: FileContext): readonly Violation[] {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        return rule.check(ctx);
+    } catch (err: unknown) {
+        const error = toError(err);
+        process.stderr.write(`[ai-hooks] rule ${rule.name} crashed: ${error.message}\n`);
+        return [];
+    }
+}
+
+function runEditRules(
+    rules: readonly Rule[],
+    editContexts: readonly EditContext[],
+    config: ResolvedConfig,
+): readonly RuleGroup[] {
+    const groups: RuleGroup[] = [];
+    for (const rule of rules) {
+        if (rule.scope !== 'edit') continue;
+        const ruleConfig = config.rules.get(rule.name);
+        if (!ruleConfig || ruleConfig.enabled === false) continue;
+        const allViolations: Violation[] = [];
+        for (const ctx of editContexts) {
+            if (!ruleMatchesFile(rule, ctx.relativePath)) continue;
+            ctx.options = mergeOptions(rule.defaultOptions, ruleConfig);
+            const vs = safeCheckEdit(rule as EditRule, ctx);
+            for (const v of vs) {
+                const copy = new Violation(v.line, v.snippet, v.message);
+                copy.editIndex = ctx.editIndex;
+                copy.editCount = ctx.editCount;
+                allViolations.push(copy);
+            }
+        }
+        if (allViolations.length > 0) {
+            groups.push(new RuleGroup(
+                rule.name, rule.description, [...rule.fixHint], allViolations,
+            ));
+        }
+    }
+    return groups;
+}
+
+function runFileRules(
+    rules: readonly Rule[],
+    fileContext: FileContext,
+    config: ResolvedConfig,
+): readonly RuleGroup[] {
+    const groups: RuleGroup[] = [];
+    for (const rule of rules) {
+        if (rule.scope !== 'file') continue;
+        const ruleConfig = config.rules.get(rule.name);
+        if (!ruleConfig || ruleConfig.enabled === false) continue;
+        if (!ruleMatchesFile(rule, fileContext.relativePath)) continue;
+        fileContext.options = mergeOptions(rule.defaultOptions, ruleConfig);
+        const vs = safeCheckFile(rule as FileRule, fileContext);
+        if (vs.length > 0) {
+            groups.push(new RuleGroup(
+                rule.name, rule.description, [...rule.fixHint], [...vs],
+            ));
+        }
+    }
+    return groups;
+}

package/src/core/strip-ts-noise.ts

@@ -0,0 +1,103 @@
+interface StackFrame {
+    readonly state: string;
+    readonly braceDepth: number;
+}
+
+class StripState {
+    readonly source: string;
+    readonly len: number;
+    readonly out: string[];
+    readonly stack: StackFrame[];
+    state: string;
+    braceDepth: number;
+    i: number;
+
+    constructor(source: string) {
+        this.source = source;
+        this.len = source.length;
+        this.out = new Array<string>(source.length);
+        this.stack = [];
+        this.state = 'code';
+        this.braceDepth = 0;
+        this.i = 0;
+    }
+
+    ch(): string { return this.source[this.i]; }
+    next(): string { return this.i + 1 < this.len ? this.source[this.i + 1] : ''; }
+    emit(idx: number, ch: string): void { this.out[idx] = ch; }
+    blank(idx: number, ch: string): void { this.out[idx] = ch === '\n' ? '\n' : ' '; }
+
+    pushState(newState: string): void {
+        this.stack.push({ state: this.state, braceDepth: this.braceDepth });
+        this.state = newState;
+    }
+
+    popState(): void {
+        const frame = this.stack.pop()!;
+        this.state = frame.state;
+        this.braceDepth = frame.braceDepth;
+    }
+}
+
+function handleCodeOrInterp(s: StripState): void {
+    const ch = s.ch();
+    const next = s.next();
+
+    if (s.state === 'templateInterp') {
+        if (ch === '{') { s.braceDepth += 1; s.emit(s.i, ch); s.i += 1; return; }
+        if (ch === '}') {
+            if (s.braceDepth === 0) { s.emit(s.i, ch); s.i += 1; s.popState(); return; }
+            s.braceDepth -= 1; s.emit(s.i, ch); s.i += 1; return;
+        }
+    }
+    if (ch === '/' && next === '/') { s.emit(s.i, '/'); s.emit(s.i + 1, '/'); s.i += 2; s.pushState('lineComment'); return; }
+    if (ch === '/' && next === '*') { s.emit(s.i, '/'); s.emit(s.i + 1, '*'); s.i += 2; s.pushState('blockComment'); return; }
+    if (ch === '"') { s.emit(s.i, '"'); s.i += 1; s.pushState('dquote'); return; }
+    if (ch === "'") { s.emit(s.i, "'"); s.i += 1; s.pushState('squote'); return; }
+    if (ch === '`') { s.emit(s.i, '`'); s.i += 1; s.pushState('template'); return; }
+    s.emit(s.i, ch); s.i += 1;
+}
+
+function handleLineComment(s: StripState): void {
+    if (s.ch() === '\n') { s.emit(s.i, '\n'); s.i += 1; s.popState(); return; }
+    s.blank(s.i, s.ch()); s.i += 1;
+}
+
+function handleBlockComment(s: StripState): void {
+    if (s.ch() === '*' && s.next() === '/') { s.emit(s.i, '*'); s.emit(s.i + 1, '/'); s.i += 2; s.popState(); return; }
+    s.blank(s.i, s.ch()); s.i += 1;
+}
+
+function handleStringLiteral(s: StripState, quoteChar: string): void {
+    const ch = s.ch();
+    if (ch === '\\' && s.i + 1 < s.len) { s.blank(s.i, ch); s.blank(s.i + 1, s.source[s.i + 1]); s.i += 2; return; }
+    if (ch === quoteChar) { s.emit(s.i, quoteChar); s.i += 1; s.popState(); return; }
+    s.blank(s.i, ch); s.i += 1;
+}
+
+function handleTemplate(s: StripState): void {
+    const ch = s.ch();
+    if (ch === '\\' && s.i + 1 < s.len) { s.blank(s.i, ch); s.blank(s.i + 1, s.source[s.i + 1]); s.i += 2; return; }
+    if (ch === '`') { s.emit(s.i, '`'); s.i += 1; s.popState(); return; }
+    if (ch === '$' && s.next() === '{') {
+        s.emit(s.i, '$'); s.emit(s.i + 1, '{'); s.i += 2;
+        s.stack.push({ state: 'template', braceDepth: 0 });
+        s.state = 'templateInterp'; s.braceDepth = 0;
+        return;
+    }
+    s.blank(s.i, ch); s.i += 1;
+}
+
+export function stripTsNoise(source: string): string {
+    const s = new StripState(source);
+    while (s.i < s.len) {
+        if (s.state === 'code' || s.state === 'templateInterp') { handleCodeOrInterp(s); }
+        else if (s.state === 'lineComment') { handleLineComment(s); }
+        else if (s.state === 'blockComment') { handleBlockComment(s); }
+        else if (s.state === 'dquote') { handleStringLiteral(s, '"'); }
+        else if (s.state === 'squote') { handleStringLiteral(s, "'"); }
+        else if (s.state === 'template') { handleTemplate(s); }
+        else { s.emit(s.i, s.ch()); s.i += 1; }
+    }
+    return s.out.join('');
+}

package/src/core/to-error.ts

@@ -0,0 +1,35 @@
+// ai-hook-disable-file require-return-type -- toError is a utility copied from dev-config; function return type is on line 6
+/**
+ * Lightweight duplicate of @webpieces/core-util toError.
+ * ai-hooks is a standalone package and cannot depend on core-util or dev-config.
+ */
+// webpieces-disable no-any-unknown -- toError intentionally accepts unknown to safely convert any thrown value to Error
+export function toError(err: unknown): Error {
+    if (err instanceof Error) {
+        return err;
+    }
+
+    if (err && typeof err === 'object') {
+        if ('message' in err) {
+            const error = new Error(String(err.message));
+            if ('stack' in err && typeof err.stack === 'string') {
+                error.stack = err.stack;
+            }
+            if ('name' in err && typeof err.name === 'string') {
+                error.name = err.name;
+            }
+            return error;
+        }
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return new Error(`Non-Error object thrown: ${JSON.stringify(err)}`);
+        } catch (err: unknown) {
+            //const error = toError(err);
+            void err;
+            return new Error('Non-Error object thrown (unable to stringify)');
+        }
+    }
+
+    const message = err == null ? 'Null or undefined thrown' : String(err);
+    return new Error(message);
+}

package/src/core/types.ts

@@ -0,0 +1,196 @@
+// ResolvedConfig / ResolvedRuleConfig / RuleOptions now live in @webpieces/rules-config
+// so ai-hooks and the Nx validate-code executor share one loader and one config file.
+import { RuleOptions } from '@webpieces/rules-config';
+export { ResolvedConfig, ResolvedRuleConfig, RuleOptions } from '@webpieces/rules-config';
+
+export type ToolKind = 'Write' | 'Edit' | 'MultiEdit';
+export type RuleScope = 'edit' | 'file' | 'bash';
+export type IsLineDisabled = (lineNum: number, ruleName: string) => boolean;
+
+export class Violation {
+    readonly line: number;
+    readonly snippet: string;
+    readonly message: string;
+    editIndex: number | undefined;
+    editCount: number | undefined;
+
+    constructor(line: number, snippet: string, message: string) {
+        this.line = line;
+        this.snippet = snippet;
+        this.message = message;
+        this.editIndex = undefined;
+        this.editCount = undefined;
+    }
+}
+
+export class NormalizedEdit {
+    readonly oldString: string;
+    readonly newString: string;
+
+    constructor(oldString: string, newString: string) {
+        this.oldString = oldString;
+        this.newString = newString;
+    }
+}
+
+export class NormalizedToolInput {
+    readonly filePath: string;
+    readonly edits: readonly NormalizedEdit[];
+
+    constructor(filePath: string, edits: readonly NormalizedEdit[]) {
+        this.filePath = filePath;
+        this.edits = edits;
+    }
+}
+
+export class NormalizedBashInput {
+    readonly command: string;
+
+    constructor(command: string) {
+        this.command = command;
+    }
+}
+
+export class EditContext {
+    readonly tool: ToolKind;
+    readonly editIndex: number;
+    readonly editCount: number;
+    readonly filePath: string;
+    readonly relativePath: string;
+    readonly workspaceRoot: string;
+    readonly addedContent: string;
+    readonly strippedContent: string;
+    readonly lines: readonly string[];
+    readonly strippedLines: readonly string[];
+    readonly removedContent: string;
+    readonly isLineDisabled: IsLineDisabled;
+    options: RuleOptions;
+
+    constructor(
+        tool: ToolKind,
+        editIndex: number,
+        editCount: number,
+        filePath: string,
+        relativePath: string,
+        workspaceRoot: string,
+        addedContent: string,
+        strippedContent: string,
+        lines: readonly string[],
+        strippedLines: readonly string[],
+        removedContent: string,
+        isLineDisabled: IsLineDisabled,
+    ) {
+        this.tool = tool;
+        this.editIndex = editIndex;
+        this.editCount = editCount;
+        this.filePath = filePath;
+        this.relativePath = relativePath;
+        this.workspaceRoot = workspaceRoot;
+        this.addedContent = addedContent;
+        this.strippedContent = strippedContent;
+        this.lines = lines;
+        this.strippedLines = strippedLines;
+        this.removedContent = removedContent;
+        this.isLineDisabled = isLineDisabled;
+        this.options = {};
+    }
+}
+
+export class BashContext {
+    readonly tool: 'Bash';
+    readonly command: string;
+    readonly workspaceRoot: string;
+    options: RuleOptions;
+
+    constructor(command: string, workspaceRoot: string) {
+        this.tool = 'Bash';
+        this.command = command;
+        this.workspaceRoot = workspaceRoot;
+        this.options = {};
+    }
+}
+
+export class FileContext {
+    readonly tool: ToolKind;
+    readonly filePath: string;
+    readonly relativePath: string;
+    readonly workspaceRoot: string;
+    readonly currentFileLines: number;
+    readonly linesAdded: number;
+    readonly linesRemoved: number;
+    readonly projectedFileLines: number;
+    options: RuleOptions;
+
+    constructor(
+        tool: ToolKind,
+        filePath: string,
+        relativePath: string,
+        workspaceRoot: string,
+        currentFileLines: number,
+        linesAdded: number,
+        linesRemoved: number,
+        projectedFileLines: number,
+    ) {
+        this.tool = tool;
+        this.filePath = filePath;
+        this.relativePath = relativePath;
+        this.workspaceRoot = workspaceRoot;
+        this.currentFileLines = currentFileLines;
+        this.linesAdded = linesAdded;
+        this.linesRemoved = linesRemoved;
+        this.projectedFileLines = projectedFileLines;
+        this.options = {};
+    }
+}
+
+interface RuleBase {
+    readonly name: string;
+    readonly description: string;
+    readonly files: readonly string[];
+    readonly defaultOptions: RuleOptions;
+    readonly fixHint: readonly string[];
+}
+
+export interface EditRule extends RuleBase {
+    readonly scope: 'edit';
+    check(ctx: EditContext): readonly Violation[];
+}
+
+export interface FileRule extends RuleBase {
+    readonly scope: 'file';
+    check(ctx: FileContext): readonly Violation[];
+}
+
+export interface BashRule extends RuleBase {
+    readonly scope: 'bash';
+    check(ctx: BashContext): readonly Violation[];
+}
+
+export type Rule = EditRule | FileRule | BashRule;
+
+export class RuleGroup {
+    readonly ruleName: string;
+    readonly ruleDescription: string;
+    readonly fixHint: readonly string[];
+    readonly violations: readonly Violation[];
+
+    constructor(
+        ruleName: string,
+        ruleDescription: string,
+        fixHint: readonly string[],
+        violations: readonly Violation[],
+    ) {
+        this.ruleName = ruleName;
+        this.ruleDescription = ruleDescription;
+        this.fixHint = fixHint;
+        this.violations = violations;
+    }
+}
+
+export class BlockedResult {
+    readonly report: string;
+
+    constructor(report: string) {
+        this.report = report;
+    }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Pluggable write-time validation framework for AI coding agents
+export {
+    ToolKind, RuleScope, RuleOptions, IsLineDisabled,
+    Violation, NormalizedEdit, NormalizedToolInput,
+    EditContext, FileContext,
+    Rule, EditRule, FileRule,
+    RuleGroup, BlockedResult,
+    ResolvedConfig, ResolvedRuleConfig,
+} from './core/types';
+
+export { run } from './core/runner';
+export { stripTsNoise } from './core/strip-ts-noise';
+export { parseDirectives, DirectiveIndex, createIsLineDisabled } from './core/disable-directives';
+export { formatReport } from './core/report';

package/templates/claude-settings-hook.json

@@ -0,0 +1,15 @@
+{
+    "hooks": {
+        "PreToolUse": [
+            {
+                "matcher": "Write|Edit|MultiEdit|Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "node .webpieces/ai-hooks/claude-code-hook.js"
+                    }
+                ]
+            }
+        ]
+    }
+}

package/templates/webpieces.ai-hooks.seed.json

@@ -0,0 +1,16 @@
+{
+    "extends": "@webpieces/ai-hook-rules/default",
+    "rules": {
+        "no-any": { "enabled": true },
+        "max-file-lines": { "enabled": true, "limit": 900 },
+        "file-location": {
+            "enabled": true,
+            "allowedRootFiles": ["jest.setup.ts"],
+            "excludePaths": ["scripts", "tmp", "architecture"]
+        },
+        "no-destructure": { "enabled": true },
+        "require-return-type": { "enabled": true },
+        "no-unmanaged-exceptions": { "enabled": true }
+    },
+    "rulesDir": []
+}