@webpieces/ai-hook-rules 0.0.1

package/src/core/rules/file-location.ts

@@ -0,0 +1,87 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { FileRule, FileContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+const DEFAULT_EXCLUDE_PATHS = [
+    'node_modules', 'dist', '.nx', '.git',
+    'architecture', 'tmp', 'scripts',
+];
+const DEFAULT_ALLOWED_ROOT_FILES = ['jest.setup.ts'];
+
+function isNodeModulesDir(name: string): boolean {
+    return name === 'node_modules' || name.startsWith('node_modules_');
+}
+
+function shouldSkipDir(name: string, excludePaths: readonly string[]): boolean {
+    if (isNodeModulesDir(name)) return true;
+    return excludePaths.indexOf(name) >= 0;
+}
+
+function findProjectRoot(filePath: string, workspaceRoot: string): string | null {
+    let dir = path.dirname(filePath);
+    while (dir !== workspaceRoot && dir.startsWith(workspaceRoot)) {
+        if (fs.existsSync(path.join(dir, 'project.json'))) return dir;
+        dir = path.dirname(dir);
+    }
+    return null;
+}
+
+const fileLocationRule: FileRule = {
+    name: 'file-location',
+    description: 'Every .ts file must belong to a project\'s src/ directory.',
+    scope: 'file',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: {
+        excludePaths: DEFAULT_EXCLUDE_PATHS,
+        allowedRootFiles: DEFAULT_ALLOWED_ROOT_FILES,
+    },
+    fixHint: [
+        'Move the file into an existing project\'s src/ directory, or create a new project with project.json that owns the directory.',
+        'Add the dir to file-location.excludePaths in webpieces.ai-hooks.json',
+    ],
+
+    check(ctx: FileContext): readonly Violation[] {
+        if (ctx.tool !== 'Write') return [];
+
+        const excludePaths = Array.isArray(ctx.options['excludePaths'])
+            ? ctx.options['excludePaths'] as string[]
+            : DEFAULT_EXCLUDE_PATHS;
+        const allowedRootFiles = Array.isArray(ctx.options['allowedRootFiles'])
+            ? ctx.options['allowedRootFiles'] as string[]
+            : DEFAULT_ALLOWED_ROOT_FILES;
+
+        const relParts = ctx.relativePath.split(path.sep);
+        const topDir = relParts[0];
+
+        if (topDir && shouldSkipDir(topDir, excludePaths)) return [];
+        if (relParts.length === 1 && allowedRootFiles.indexOf(relParts[0]) >= 0) return [];
+
+        const projectRoot = findProjectRoot(ctx.filePath, ctx.workspaceRoot);
+
+        if (!projectRoot) {
+            return [new V(
+                1,
+                ctx.relativePath,
+                'File is not inside any Nx project. Move it into a project\'s src/ directory.',
+            )];
+        }
+
+        const relToProject = path.relative(projectRoot, ctx.filePath);
+        const fileName = path.basename(ctx.filePath);
+        if (fileName === 'jest.config.ts') return [];
+        if (!relToProject.startsWith('src' + path.sep) && relToProject !== 'src') {
+            const projectName = path.relative(ctx.workspaceRoot, projectRoot);
+            return [new V(
+                1,
+                ctx.relativePath,
+                `File is inside project \`${projectName}\` but outside its src/ directory. Move it into src/.`,
+            )];
+        }
+
+        return [];
+    },
+};
+
+export default fileLocationRule;

package/src/core/rules/index.ts

@@ -0,0 +1,11 @@
+export const builtInRuleNames: readonly string[] = [
+    'no-any-unknown',
+    'no-implicit-any',
+    'max-file-lines',
+    'file-location',
+    'no-destructure',
+    'require-return-type',
+    'no-unmanaged-exceptions',
+    'catch-error-pattern',
+    'no-shell-substitution',
+];

package/src/core/rules/max-file-lines.ts

@@ -0,0 +1,137 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { FileRule, FileContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+const DEFAULT_LIMIT = 900;
+const INSTRUCT_DIR = '.webpieces/instruct-ai';
+const INSTRUCT_FILE = 'webpieces.filesize.md';
+
+const maxFileLinesRule: FileRule = {
+    name: 'max-file-lines',
+    description: 'Cap file length at a configured line limit.',
+    scope: 'file',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: { limit: DEFAULT_LIMIT },
+    fixHint: [
+        'READ .webpieces/instruct-ai/webpieces.filesize.md for step-by-step refactoring guidance.',
+        '// eslint-disable-next-line @webpieces/max-file-lines  (also suppresses the eslint rule)',
+    ],
+
+    check(ctx: FileContext): readonly Violation[] {
+        const limit = typeof ctx.options['limit'] === 'number'
+            ? ctx.options['limit'] as number
+            : DEFAULT_LIMIT;
+        if (ctx.projectedFileLines <= limit) return [];
+        writeInstructionFile(ctx.workspaceRoot);
+        return [new V(
+            1,
+            `(projected ${String(ctx.projectedFileLines)} lines)`,
+            `File will be ${String(ctx.projectedFileLines)} lines, exceeding the ${String(limit)}-line limit. See .webpieces/instruct-ai/webpieces.filesize.md for detailed refactoring instructions.`,
+        )];
+    },
+};
+
+function writeInstructionFile(workspaceRoot: string): void {
+    const dir = path.join(workspaceRoot, INSTRUCT_DIR);
+    const filePath = path.join(dir, INSTRUCT_FILE);
+    if (fs.existsSync(filePath)) return;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, FILESIZE_DOC_CONTENT);
+}
+
+// eslint-disable-next-line @webpieces/max-file-lines
+const FILESIZE_DOC_CONTENT = `# AI Agent Instructions: File Too Long
+
+**READ THIS FILE to fix files that are too long**
+
+## Core Principle
+
+With **stateless systems + dependency injection, refactor is trivial**.
+Pick a method or a few and move to new class XXXXX, then inject XXXXX
+into all users of those methods via the constructor.
+Delete those methods from original class.
+
+**99% of files can be less than the configured max lines of code.**
+
+Files should contain a SINGLE COHESIVE UNIT.
+- One class per file (Java convention)
+- If class is too large, extract child responsibilities
+- Use dependency injection to compose functionality
+
+## Command: Reduce File Size
+
+### Step 1: Check for Multiple Classes
+If the file contains multiple classes, **SEPARATE each class into its own file**.
+
+### Step 2: Extract Child Responsibilities (if single class is too large)
+
+#### Pattern: Create New Service Class with Dependency Injection
+
+\`\`\`typescript
+// BAD: UserController.ts (800 lines, single class)
+@provideSingleton()
+@Controller()
+export class UserController {
+  // 200 lines: CRUD operations
+  // 300 lines: validation logic
+  // 200 lines: notification logic
+}
+
+// GOOD: Extract validation service
+// 1. Create UserValidationService.ts
+@provideSingleton()
+export class UserValidationService {
+  validateUserData(data: UserData): ValidationResult { /* ... */ }
+  validateEmail(email: string): boolean { /* ... */ }
+}
+
+// 2. Inject into UserController.ts
+@provideSingleton()
+@Controller()
+export class UserController {
+  constructor(
+    @inject(TYPES.UserValidationService)
+    private validator: UserValidationService
+  ) {}
+}
+\`\`\`
+
+## AI Agent Action Steps
+
+1. **ANALYZE** the file structure:
+   - Count classes (if >1, separate immediately)
+   - Identify logical responsibilities within single class
+
+2. **IDENTIFY** "child code" to extract:
+   - Validation logic -> ValidationService
+   - Notification logic -> NotificationService
+   - Data transformation -> TransformerService
+   - External API calls -> ApiService
+   - Business rules -> RulesEngine
+
+3. **CREATE** new service file(s):
+   - Add \`@provideSingleton()\` decorator
+   - Move child methods to new class
+
+4. **UPDATE** dependency injection:
+   - Inject new service into original class constructor
+   - Replace direct method calls with \`this.serviceName.method()\`
+
+5. **VERIFY** file sizes:
+   - Original file should now be under the limit
+   - Each extracted file should be under the limit
+
+## Escape Hatch
+
+If refactoring is genuinely not feasible, add a disable comment:
+
+\`\`\`typescript
+// eslint-disable-next-line @webpieces/max-file-lines
+\`\`\`
+
+Remember: Find the "child code" and pull it down into a new class. Once moved, the code's purpose becomes clear, making it easy to rename to a logical name.
+`;
+
+export default maxFileLinesRule;

package/src/core/rules/no-any-unknown.ts

@@ -0,0 +1,35 @@
+import type { EditRule, EditContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+const ANY_PATTERN =
+    /(?::\s*any\b|\bas\s+any\b|<any>|any\[\]|Array<any>|Promise<any>|Map<[^,<>]+,\s*any\s*>|Record<[^,<>]+,\s*any\s*>|Set<any>)/;
+
+const noAnyRule: EditRule = {
+    name: 'no-any-unknown',
+    description: 'Disallow the `any` keyword. Use concrete types or interfaces.',
+    scope: 'edit',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: {},
+    fixHint: [
+        'Prefer: interface MyData { ... }   or   class MyData { ... }',
+        '// webpieces-disable no-any-unknown -- <one-line reason>',
+    ],
+
+    check(ctx: EditContext): readonly Violation[] {
+        const violations: V[] = [];
+        for (let i = 0; i < ctx.strippedLines.length; i += 1) {
+            const stripped = ctx.strippedLines[i];
+            if (!ANY_PATTERN.test(stripped)) continue;
+            const lineNum = i + 1;
+            if (ctx.isLineDisabled(lineNum, 'no-any-unknown')) continue;
+            violations.push(new V(
+                lineNum,
+                ctx.lines[i].trim(),
+                '`any` erases type information. Use a concrete type, an interface, or `unknown` with type guards.',
+            ));
+        }
+        return violations;
+    },
+};
+
+export default noAnyRule;

package/src/core/rules/no-destructure.ts

@@ -0,0 +1,34 @@
+import type { EditRule, EditContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+const VARIABLE_DESTRUCTURE = /\b(?:const|let|var)\s*\{/;
+
+const noDestructureRule: EditRule = {
+    name: 'no-destructure',
+    description: 'Disallow destructuring patterns. Assign the whole result and pass it around or access properties explicitly.',
+    scope: 'edit',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: { allowTopLevel: true },
+    fixHint: [
+        'Instead of: const { x, y } = methodCall(); prefer const obj = methodCall(); then pass obj to other methods or use obj.x',
+        '// webpieces-disable no-destructure -- <reason>',
+    ],
+
+    check(ctx: EditContext): readonly Violation[] {
+        const violations: V[] = [];
+        for (let i = 0; i < ctx.strippedLines.length; i += 1) {
+            const stripped = ctx.strippedLines[i];
+            if (!VARIABLE_DESTRUCTURE.test(stripped)) continue;
+            const lineNum = i + 1;
+            if (ctx.isLineDisabled(lineNum, 'no-destructure')) continue;
+            violations.push(new V(
+                lineNum,
+                ctx.lines[i].trim(),
+                'Destructuring pattern. Assign the whole result instead: const obj = methodCall(); then pass obj around or use obj.x',
+            ));
+        }
+        return violations;
+    },
+};
+
+export default noDestructureRule;

package/src/core/rules/no-implicit-any.ts

@@ -0,0 +1,67 @@
+import type { EditRule, EditContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+const ARROW_PARAMS_RE = /\(([^()]*)\)\s*=>/g;
+const FN_DECL_PARAMS_RE = /\bfunction\s*[\w$]*\s*\(([^()]*)\)/g;
+
+function firstUntypedParam(paramsStr: string): string | null {
+    if (paramsStr.includes('{') || paramsStr.includes('[')) return null;
+    const parts = paramsStr.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+    for (const part of parts) {
+        if (part.startsWith('...')) continue;
+        if (part.includes(':')) continue;
+        if (part.includes('=')) continue;
+        if (part === 'this') continue;
+        if (/^[a-zA-Z_$][\w$]*$/.test(part)) return part;
+    }
+    return null;
+}
+
+function findOffender(line: string): string | null {
+    ARROW_PARAMS_RE.lastIndex = 0;
+    let m: RegExpExecArray | null = ARROW_PARAMS_RE.exec(line);
+    while (m !== null) {
+        const bad = firstUntypedParam(m[1]);
+        if (bad) return bad;
+        m = ARROW_PARAMS_RE.exec(line);
+    }
+    FN_DECL_PARAMS_RE.lastIndex = 0;
+    m = FN_DECL_PARAMS_RE.exec(line);
+    while (m !== null) {
+        const bad = firstUntypedParam(m[1]);
+        if (bad) return bad;
+        m = FN_DECL_PARAMS_RE.exec(line);
+    }
+    return null;
+}
+
+const noImplicitAnyRule: EditRule = {
+    name: 'no-implicit-any',
+    description: 'Disallow function parameters without explicit type annotations (implicit-any).',
+    scope: 'edit',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: {},
+    fixHint: [
+        'Add explicit types: (x: string) => ...   or   function foo(x: number)',
+        '// webpieces-disable no-implicit-any -- <one-line reason>',
+    ],
+
+    check(ctx: EditContext): readonly Violation[] {
+        const violations: V[] = [];
+        for (let i = 0; i < ctx.strippedLines.length; i += 1) {
+            const stripped = ctx.strippedLines[i];
+            const lineNum = i + 1;
+            if (ctx.isLineDisabled(lineNum, 'no-implicit-any')) continue;
+            const offender = findOffender(stripped);
+            if (!offender) continue;
+            violations.push(new V(
+                lineNum,
+                ctx.lines[i].trim(),
+                `Parameter "${offender}" has no type annotation. Add an explicit type to avoid implicit-any.`,
+            ));
+        }
+        return violations;
+    },
+};
+
+export default noImplicitAnyRule;

package/src/core/rules/no-shell-substitution.ts

@@ -0,0 +1,71 @@
+import type { BashRule, BashContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+const FIX_HINT: readonly string[] = [
+    'Shell substitutions trigger Claude Code "simple_expansion" permission prompts that interrupt the user.',
+    'Instead:',
+    '  • Build payload files with Write, then: node script.js < /path/to/payload',
+    '  • Use Read, Grep, or Glob instead of piping shell output through $(...)',
+    '  • Write a small script file with Write and execute it: bash /path/to/script.sh',
+];
+
+const noShellSubstitutionRule: BashRule = {
+    name: 'no-shell-substitution',
+    description: 'Reject Bash commands containing shell substitutions ($(...), backticks, $VAR).',
+    scope: 'bash',
+    files: [],
+    defaultOptions: {},
+    fixHint: FIX_HINT,
+
+    check(ctx: BashContext): readonly Violation[] {
+        const scanned = stripSingleQuoted(ctx.command);
+        const violations: Violation[] = [];
+
+        if (/\$\(/.test(scanned)) {
+            violations.push(new V(
+                1,
+                truncate(ctx.command),
+                'Command contains `$(...)` command substitution.',
+            ));
+        }
+        if (hasUnescapedBacktick(scanned)) {
+            violations.push(new V(
+                1,
+                truncate(ctx.command),
+                'Command contains backtick command substitution.',
+            ));
+        }
+        if (/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(scanned) || hasBareVarExpansion(scanned)) {
+            violations.push(new V(
+                1,
+                truncate(ctx.command),
+                'Command contains `$VAR` or `${VAR}` variable expansion.',
+            ));
+        }
+        return violations;
+    },
+};
+
+function stripSingleQuoted(cmd: string): string {
+    return cmd.replace(/'[^']*'/g, "''");
+}
+
+function hasUnescapedBacktick(cmd: string): boolean {
+    for (let i = 0; i < cmd.length; i += 1) {
+        if (cmd[i] === '`' && (i === 0 || cmd[i - 1] !== '\\')) return true;
+    }
+    return false;
+}
+
+function hasBareVarExpansion(cmd: string): boolean {
+    const re = /(^|[^\\])\$([A-Za-z_][A-Za-z0-9_]*)/g;
+    return re.test(cmd);
+}
+
+function truncate(s: string): string {
+    const MAX = 120;
+    if (s.length <= MAX) return s;
+    return s.slice(0, MAX) + '…';
+}
+
+export default noShellSubstitutionRule;

package/src/core/rules/no-unmanaged-exceptions.ts

@@ -0,0 +1,48 @@
+import type { EditRule, EditContext, Violation } from '../types';
+import { Violation as V } from '../types';
+import { writeTemplateIfMissing } from '../instruct-ai-writer';
+
+const TRY_PATTERN = /\btry\s*\{/;
+
+// Both webpieces-disable and the existing ESLint directive suppress this rule
+const DISABLE_PATTERN = /@webpieces\/no-unmanaged-exceptions|webpieces-disable\s+(?:[\w-]+,\s*)*no-unmanaged-exceptions/;
+
+const noUnmanagedExceptionsRule: EditRule = {
+    name: 'no-unmanaged-exceptions',
+    description: 'try/catch is generally not allowed. Only allowed in chokepoints (filter, globalErrorHandler) or other rare locations.',
+    scope: 'edit',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: {},
+    fixHint: [
+        'VERY IMPORTANT: READ .webpieces/instruct-ai/webpieces.exceptions.md to understand why and how to fix this!',
+        'Exceptions should bubble to a chokepoint (filter in node.js, globalErrorHandler in Angular). Most code should NOT catch exceptions.',
+        '// webpieces-disable no-unmanaged-exceptions -- <reason>',
+        'When try/catch IS used (after disabling), the catch block MUST use: catch (err: unknown) { const error = toError(err); ... } or //const error = toError(err); to explicitly ignore.',
+    ],
+
+    check(ctx: EditContext): readonly Violation[] {
+        const violations: V[] = [];
+        for (let i = 0; i < ctx.strippedLines.length; i += 1) {
+            const stripped = ctx.strippedLines[i];
+            if (!TRY_PATTERN.test(stripped)) continue;
+            const lineNum = i + 1;
+            if (ctx.isLineDisabled(lineNum, 'no-unmanaged-exceptions')) continue;
+            if (hasPrecedingDisable(ctx.lines, i)) continue;
+            violations.push(new V(
+                lineNum,
+                ctx.lines[i].trim(),
+                'try/catch is generally not allowed. It is only allowed in chokepoints (filter, globalErrorHandler) or other rare locations.',
+            ));
+        }
+        if (violations.length > 0) writeTemplateIfMissing(ctx.workspaceRoot, 'webpieces.exceptions.md');
+        return violations;
+    },
+};
+
+function hasPrecedingDisable(lines: readonly string[], idx: number): boolean {
+    if (idx === 0) return false;
+    const prevLine = lines[idx - 1];
+    return DISABLE_PATTERN.test(prevLine);
+}
+
+export default noUnmanagedExceptionsRule;

package/src/core/rules/require-return-type.ts

@@ -0,0 +1,59 @@
+import type { EditRule, EditContext, Violation } from '../types';
+import { Violation as V } from '../types';
+
+// Matches function/method signatures that don't have `: ReturnType` before the `{` body opener.
+// Pattern: function name(<params>) { — missing `: Type` between `)` and `{`
+const FUNC_DECL_MISSING = /\bfunction\s+\w+\s*(?:<[^>]*>)?\s*\([^)]*\)\s*\{/;
+
+// Matches class method signatures: indented, optional async, name(<params>) {
+const METHOD_MISSING = /^\s{2,}(?:async\s+)?\w+\s*(?:<[^>]*>)?\s*\([^)]*\)\s*\{/;
+
+// Arrow function: const name = (async)? (<params>) => — missing `: Type` before `=>`
+const ARROW_MISSING = /\bconst\s+\w+\s*=\s*(?:async\s+)?(?:<[^>]*>)?\s*\([^)]*\)\s*=>/;
+
+// Lines that have ): ReturnType before { or => — these are COMPLIANT
+const HAS_RETURN_TYPE = /\)\s*:\s*\S/;
+
+// Skip constructors, getters, setters, and control flow keywords
+const SKIP_PATTERN = /\b(?:constructor|get\s+\w+|set\s+\w+|if|else|while|for|switch|catch|return)\s*\(/;
+
+const requireReturnTypeRule: EditRule = {
+    name: 'require-return-type',
+    description: 'Every function and method must declare its return type.',
+    scope: 'edit',
+    files: ['**/*.ts', '**/*.tsx'],
+    defaultOptions: {},
+    fixHint: [
+        'Add return type: function foo(x: T): ReturnType { ... }',
+        '// webpieces-disable require-return-type -- <reason>',
+    ],
+
+    check(ctx: EditContext): readonly Violation[] {
+        const violations: V[] = [];
+        for (let i = 0; i < ctx.strippedLines.length; i += 1) {
+            const stripped = ctx.strippedLines[i];
+            if (!isMissingReturnType(stripped)) continue;
+            const lineNum = i + 1;
+            if (ctx.isLineDisabled(lineNum, 'require-return-type')) continue;
+            violations.push(new V(
+                lineNum,
+                ctx.lines[i].trim(),
+                'Missing return type annotation.',
+            ));
+        }
+        return violations;
+    },
+};
+
+function isMissingReturnType(line: string): boolean {
+    if (SKIP_PATTERN.test(line)) return false;
+    const isFuncLike =
+        FUNC_DECL_MISSING.test(line) ||
+        METHOD_MISSING.test(line) ||
+        ARROW_MISSING.test(line);
+    if (!isFuncLike) return false;
+    if (HAS_RETURN_TYPE.test(line)) return false;
+    return true;
+}
+
+export default requireReturnTypeRule;