@webpieces/eslint-rules 0.0.1

package/src/rules/no-mat-cell-def.ts

@@ -0,0 +1,62 @@
+/**
+ * ESLint rule: no-mat-cell-def
+ *
+ * Bans *matCellDef and *matHeaderCellDef in Angular HTML templates.
+ * New files should use the div-grid table pattern instead of mat-table.
+ *
+ * Works with @angular-eslint/template-parser AST where structural directives
+ * (*matCellDef) are desugared into Template nodes with templateAttrs[].
+ *
+ * NOTE: This rule only works when files are parsed with @angular-eslint/template-parser.
+ * It is intended for Angular HTML template files (**.html).
+ */
+
+import type { Rule } from 'eslint';
+
+// webpieces-disable no-any-unknown -- Angular template AST node interfaces
+// These interfaces represent the Template node shape from @angular-eslint/template-parser.
+// We define them inline since the parser is not a dependency of this plugin.
+interface AngularTemplateNode {
+    templateAttrs?: Array<{ name: string }>;
+    // webpieces-disable no-any-unknown -- ESTree AST index signature
+    [key: string]: any;
+}
+
+const BANNED_DIRECTIVES = ['matCellDef', 'matHeaderCellDef'];
+
+const rule: Rule.RuleModule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Ban *matCellDef and *matHeaderCellDef — use div-grid tables instead',
+        },
+        messages: {
+            noMatCellDef:
+                '*{{ directive }} is banned in new files. Use the div-grid table pattern instead. ' +
+                'Div-grid tables are inherently type-safe with @for loops + strictTemplates.',
+        },
+        schema: [],
+    },
+    create(context: Rule.RuleContext): Rule.RuleListener {
+        return {
+            Template(node: AngularTemplateNode): void {
+                // Structural directives (*matCellDef) are desugared into Template nodes.
+                // The directive name appears in node.templateAttrs as either a
+                // BoundAttribute or TextAttribute.
+                const attrs = node.templateAttrs || [];
+                for (const attr of attrs) {
+                    if (BANNED_DIRECTIVES.includes(attr.name)) {
+                        context.report({
+                            // webpieces-disable no-any-unknown -- ESTree AST cast for ESLint report
+                            node: node as unknown as Rule.Node,
+                            messageId: 'noMatCellDef',
+                            data: { directive: attr.name },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+
+export = rule;

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

@@ -0,0 +1,194 @@
+/**
+ * ESLint rule to discourage try-catch blocks outside test files
+ *
+ * Works alongside catch-error-pattern rule:
+ * - catch-error-pattern: Enforces HOW to handle exceptions (with toError())
+ * - no-unmanaged-exceptions: Enforces WHERE try-catch is allowed (tests only by default)
+ *
+ * Philosophy: Exceptions should bubble to global error handlers where they are logged
+ * with traceId and stored for debugging via /debugLocal and /debugCloud endpoints.
+ * Local try-catch blocks break this architecture and create blind spots in production.
+ *
+ * Auto-allowed in:
+ * - Test files (.test.ts, .spec.ts, __tests__/)
+ *
+ * Requires eslint-disable comment in:
+ * - Retry loops with exponential backoff
+ * - Batch processing where partial failure is expected
+ * - Resource cleanup (with approval)
+ */
+
+import type { Rule } from 'eslint';
+import * as fs from 'fs';
+import * as path from 'path';
+import { toError } from '../toError';
+
+// webpieces-disable no-any-unknown -- ESTree AST node interface
+interface TryStatementNode {
+    handler?: unknown;
+}
+
+/**
+ * Determines if a file is a test file based on naming conventions
+ * Test files are auto-allowed to use try-catch blocks
+ */
+function isTestFile(filename: string): boolean {
+    const normalizedPath = filename.toLowerCase();
+
+    // Check file extensions
+    if (normalizedPath.endsWith('.test.ts') || normalizedPath.endsWith('.spec.ts')) {
+        return true;
+    }
+
+    // Check directory names (cross-platform)
+    if (normalizedPath.includes('/__tests__/') || normalizedPath.includes('\\__tests__\\')) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Finds the workspace root by walking up the directory tree
+ * Looks for package.json with workspaces or name === 'webpieces-ts'
+ */
+function getWorkspaceRoot(context: Rule.RuleContext): string {
+    const filename = context.filename || context.getFilename();
+    let dir = path.dirname(filename);
+
+    // Walk up directory tree
+    for (let i = 0; i < 10; i++) {
+        const pkgPath = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                // Check if this is the root workspace
+                if (pkg.workspaces || pkg.name === 'webpieces-ts') {
+                    return dir;
+                }
+            } catch (err: unknown) {
+                //const error = toError(err);
+                void err; // Invalid JSON, keep searching
+            }
+        }
+
+        const parentDir = path.dirname(dir);
+        if (parentDir === dir) break; // Reached filesystem root
+        dir = parentDir;
+    }
+
+    // Fallback: return current directory
+    return process.cwd();
+}
+
+/**
+ * Ensures a documentation file exists at the given path
+ * Creates parent directories if needed
+ */
+function ensureDocFile(docPath: string, content: string): boolean {
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        const dir = path.dirname(docPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+
+        // Only write if file doesn't exist or is empty
+        if (!fs.existsSync(docPath) || fs.readFileSync(docPath, 'utf-8').trim() === '') {
+            fs.writeFileSync(docPath, content, 'utf-8');
+        }
+
+        return true;
+    } catch (err: unknown) {
+        //const error = toError(err);
+        void err; // Silently fail - don't break linting if file creation fails
+        return false;
+    }
+}
+
+/**
+ * Ensures the exception documentation markdown file exists
+ * Only creates file once per lint run using module-level flag
+ *
+ * Reads from the template file packaged with @webpieces/webpieces-rules
+ * and copies it to .webpieces/instruct-ai/ for AI agents to read.
+ */
+function ensureExceptionDoc(context: Rule.RuleContext): void {
+    if (exceptionDocCreated) return;
+
+    const workspaceRoot = getWorkspaceRoot(context);
+    const docPath = path.join(workspaceRoot, '.webpieces', 'instruct-ai', 'webpieces.exceptions.md');
+
+    // Read from the template file packaged with the npm module
+    // Path: from eslint-plugin/rules/ -> ../../templates/
+    const templatePath = path.join(__dirname, '..', '..', 'templates', 'webpieces.exceptions.md');
+
+    let content: string;
+    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+    try {
+        content = fs.readFileSync(templatePath, 'utf-8');
+    } catch (err: unknown) {
+        //const error = toError(err);
+        void err;
+        // Fallback message if template not found (shouldn't happen in published package)
+        content = `# Exception Documentation Not Found\n\nTemplate file not found at: ${templatePath}\n\nPlease ensure @webpieces/webpieces-rules is properly installed.`;
+    }
+
+    if (ensureDocFile(docPath, content)) {
+        exceptionDocCreated = true;
+    }
+}
+
+// Module-level flag to prevent redundant markdown file creation
+let exceptionDocCreated = false;
+
+// NOTE: Documentation content moved to templates/webpieces.exceptions.md
+// The ensureExceptionDoc function reads from that file at runtime.
+
+const rule: Rule.RuleModule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Discourage try-catch blocks outside test files - use global error handlers',
+            category: 'Best Practices',
+            recommended: true,
+            url: 'https://github.com/deanhiller/webpieces-ts/blob/main/CLAUDE.md#exception-handling-philosophy',
+        },
+        messages: {
+            noUnmanagedExceptions:
+                'AI Agent: READ .webpieces/instruct-ai/webpieces.exceptions.md for context. Try-catch blocks are discouraged - use global error handlers instead. Only allowed in test files or with eslint-disable comment.',
+        },
+        fixable: undefined,
+        schema: [],
+    },
+
+    create(context: Rule.RuleContext): Rule.RuleListener {
+        return {
+            // webpieces-disable no-any-unknown -- ESLint visitor callback parameter type
+            TryStatement(node: unknown): void {
+                // Skip try..finally blocks (no catch handler, no exception handling)
+                // webpieces-disable no-any-unknown -- ESTree AST node type assertion
+                if (!(node as TryStatementNode).handler) {
+                    return;
+                }
+
+                // Auto-allow in test files
+                const filename = context.filename || context.getFilename();
+                if (isTestFile(filename)) {
+                    return;
+                }
+
+                // Has catch block outside test file - report violation
+                ensureExceptionDoc(context);
+                context.report({
+                    node: node as Rule.Node,
+                    messageId: 'noUnmanagedExceptions',
+                });
+            },
+        };
+    },
+};
+
+export = rule;
+

package/src/rules/require-typed-template.ts

@@ -0,0 +1,80 @@
+/**
+ * ESLint rule: require-typed-template
+ *
+ * Enforces that every <ng-template> with let- variables also has [templateClassType]
+ * to preserve type safety via TypedTemplateOutletDirective.
+ *
+ * Works with @angular-eslint/template-parser AST where:
+ *   - ng-template variables (let-xxx) appear in node.variables[]
+ *   - bound inputs ([templateClassType]) appear in node.inputs[]
+ *   - static attributes appear in node.attributes[]
+ *
+ * NOTE: This rule only works when files are parsed with @angular-eslint/template-parser.
+ * It is intended for Angular HTML template files (**.html).
+ */
+
+import type { Rule } from 'eslint';
+
+// webpieces-disable no-any-unknown -- Angular template AST node interfaces
+// These interfaces represent the Template node shape from @angular-eslint/template-parser.
+// We define them inline since the parser is not a dependency of this plugin.
+interface AngularTemplateNode {
+    tagName?: string;
+    variables?: Array<{ name: string }>;
+    inputs?: Array<{ name: string }>;
+    attributes?: Array<{ name: string }>;
+    // webpieces-disable no-any-unknown -- ESTree AST index signature
+    [key: string]: any;
+}
+
+const rule: Rule.RuleModule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description:
+                'Require [templateClassType] on ng-template elements that use let- variables',
+        },
+        messages: {
+            missingTypedTemplate:
+                'ng-template with let- variables must include ' +
+                '[templateClassType]="YourDtoClass" to preserve type safety. ' +
+                'Fix: (1) Add [templateClassType]="YourDtoClass" to this ng-template, ' +
+                '(2) Add TypedTemplateOutletDirective to component imports array, ' +
+                '(3) Expose the DTO class: protected readonly YourDtoClass = YourDtoClass. ' +
+                'See @fuse/directives/typed-template-outlet/.',
+        },
+        schema: [],
+    },
+    create(context: Rule.RuleContext): Rule.RuleListener {
+        return {
+            Template(node: AngularTemplateNode): void {
+                // Only match explicit <ng-template>, not desugared structural directives
+                // (*ngFor, *ngIf, etc.) which also produce Template AST nodes
+                if (node.tagName !== 'ng-template') {
+                    return;
+                }
+
+                const hasLetVariables = node.variables && node.variables.length > 0;
+                if (!hasLetVariables) {
+                    return;
+                }
+
+                const hasTemplateClassType =
+                    (node.inputs &&
+                        node.inputs.some((input) => input.name === 'templateClassType')) ||
+                    (node.attributes &&
+                        node.attributes.some((attr) => attr.name === 'templateClassType'));
+
+                if (!hasTemplateClassType) {
+                    context.report({
+                        // webpieces-disable no-any-unknown -- ESTree AST cast for ESLint report
+                        node: node as unknown as Rule.Node,
+                        messageId: 'missingTypedTemplate',
+                    });
+                }
+            },
+        };
+    },
+};
+
+export = rule;

package/src/toError.ts

@@ -0,0 +1,36 @@
+/**
+ * Lightweight duplicate of @webpieces/core-util toError for use in eslint-plugin.
+ * eslint-plugin is Level 0 and cannot depend on core-util (also Level 0).
+ */
+// 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 -- must handle circular references without recursion
+        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/tmp/webpieces/webpieces.exceptions.md

@@ -0,0 +1,5 @@
+# Exception Documentation Not Found
+
+Template file not found at: /Users/deanhiller/workspace/personal/webpieces-ts30/packages/tooling/eslint-plugin/templates/webpieces.exceptions.md
+
+Please ensure @webpieces/dev-config is properly installed.

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "forceConsistentCasingInFileNames": true,
+        "strict": true,
+        "noImplicitOverride": true,
+        "noPropertyAccessFromIndexSignature": true,
+        "noImplicitReturns": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "files": [],
+    "include": [],
+    "references": [
+        {
+            "path": "./tsconfig.lib.json"
+        },
+        {
+            "path": "./tsconfig.spec.json"
+        }
+    ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,10 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../../dist/out-tsc",
+        "declaration": true,
+        "types": ["node"]
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts", "src/__tests__/**/*.ts"]
+}

package/tsconfig.spec.json

@@ -0,0 +1,14 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "../../../dist/out-tsc",
+        "module": "commonjs",
+        "types": ["jest", "node"]
+    },
+    "include": [
+        "jest.config.ts",
+        "src/**/*.test.ts",
+        "src/**/*.spec.ts",
+        "src/__tests__/**/*.ts"
+    ]
+}