@eddacraft/anvil-core 0.1.0

package/dist/antipattern/patterns.js

@@ -0,0 +1,301 @@
+/**
+ * Anti-pattern Catalogue
+ *
+ * Defines the built-in anti-patterns that Anvil detects. Each pattern has:
+ * - ID: Unique identifier (AP-001, AP-002, etc.)
+ * - Detection: Regex or AST-based detection method
+ * - Messaging: Title, explanation, and suggestion for warnings
+ * - Configuration: Severity, confidence, allowlist, threshold, etc.
+ *
+ * @module antipattern/patterns
+ */
+import { HTML_PATTERNS } from './patterns-html.js';
+import { CSS_PATTERNS } from './patterns-css.js';
+// =============================================================================
+// Pattern Definitions
+// =============================================================================
+/**
+ * AP-001: Broad eslint-disable (file-level or block without rule)
+ *
+ * Detects `eslint-disable` comments that disable all rules, which:
+ * - Silences all linting errors in scope
+ * - Makes code review harder
+ * - Often masks multiple issues
+ */
+const AP001_BROAD_ESLINT_DISABLE = {
+    id: 'AP-001',
+    name: 'Broad eslint-disable',
+    category: 'escape-hatch',
+    severity: 'warning',
+    confidence: 'high',
+    detection: {
+        type: 'regex',
+        // Matches /* eslint-disable */ without specific rules
+        // Does NOT match eslint-disable-next-line or eslint-disable-line
+        pattern: String.raw `/\*\s*eslint-disable\s*\*/|//\s*eslint-disable(?!-next-line|-line)\s*$`,
+    },
+    title: 'Broad eslint-disable added',
+    explanation: 'Disabling all ESLint rules hides legitimate issues and makes code harder to maintain. ' +
+        'This pattern indicates technical debt that should be addressed.',
+    suggestion: 'Disable specific rules with /* eslint-disable rule-name */ or fix the underlying issues.',
+    nudge: "Don't disable all linting rules. Identify which specific rule is failing and " +
+        'either fix the underlying issue or disable only that one rule with ' +
+        '`/* eslint-disable specific-rule */`. Blanket disables hide real problems.',
+    enabled: true,
+    optIn: false,
+};
+/**
+ * AP-002: Rule-specific eslint-disable
+ *
+ * Detects `eslint-disable rule-name` comments. These are less problematic than
+ * broad disables but still warrant attention during review.
+ */
+const AP002_RULE_SPECIFIC_ESLINT_DISABLE = {
+    id: 'AP-002',
+    name: 'Rule-specific eslint-disable',
+    category: 'escape-hatch',
+    severity: 'info',
+    confidence: 'high',
+    detection: {
+        type: 'regex',
+        // Matches eslint-disable with specific rule(s)
+        // e.g., /* eslint-disable @typescript-eslint/no-explicit-any */
+        // or eslint-disable-next-line no-console
+        pattern: String.raw `eslint-disable(?:-next-line|-line)?\s+[\w@/-]+`,
+    },
+    title: 'Rule-specific eslint-disable',
+    explanation: 'While better than disabling all rules, targeted disables still indicate code that violates linting standards. ' +
+        'Consider if the disable is necessary or if the code can be improved.',
+    suggestion: 'Add a comment explaining why this rule needs to be disabled here.',
+    nudge: 'Before disabling this rule, try to fix the code so it passes. If the disable ' +
+        'is genuinely necessary, add a comment explaining why this specific case ' +
+        "can't follow the rule.",
+    enabled: true,
+    optIn: true, // Noisy - opt-in only
+};
+/**
+ * AP-003: Explicit `any` type usage
+ *
+ * Detects explicit use of `any` type in TypeScript. This bypasses type checking
+ * and can hide bugs.
+ */
+const AP003_ANY_TYPE = {
+    id: 'AP-003',
+    name: 'Explicit any type',
+    category: 'type-safety',
+    severity: 'warning',
+    confidence: 'high',
+    detection: {
+        type: 'regex',
+        // Matches `: any`, `as any`, `<any>` type assertions
+        // Careful to avoid matching words containing "any" like "company"
+        pattern: String.raw `:\s*any\b|as\s+any\b|<any>`,
+    },
+    title: 'Explicit any type usage',
+    explanation: 'Using `any` defeats the purpose of TypeScript by disabling type checking. ' +
+        'This can hide bugs and makes refactoring harder.',
+    suggestion: 'Use `unknown` for truly unknown types, or define a proper interface/type. ' +
+        'For third-party libraries, consider using or creating type definitions.',
+    nudge: "Don't use `any` here. Think about what type this value actually holds and " +
+        'declare it explicitly. If it comes from an API, define an interface for the ' +
+        'response shape. If the type is truly unknown, use `unknown` and narrow it ' +
+        'with type guards before use.',
+    enabled: true,
+    optIn: false,
+    allowlist: ['*.d.ts', '**/__mocks__/**', '**/test/**/*.ts', '**/__tests__/**'],
+};
+/**
+ * AP-004: @ts-ignore directive
+ *
+ * Detects `@ts-ignore` which suppresses ALL TypeScript errors on the next line.
+ */
+const AP004_TS_IGNORE = {
+    id: 'AP-004',
+    name: '@ts-ignore directive',
+    category: 'type-safety',
+    severity: 'warning',
+    confidence: 'high',
+    detection: {
+        type: 'regex',
+        pattern: String.raw `@ts-ignore`,
+    },
+    title: '@ts-ignore suppresses all errors',
+    explanation: '@ts-ignore suppresses ALL TypeScript errors on the next line, including legitimate issues. ' +
+        'This can hide bugs introduced by code changes.',
+    suggestion: 'Use @ts-expect-error with a description instead, which fails if the expected error disappears. ' +
+        'Better yet, fix the underlying type issue.',
+    nudge: "Don't suppress this TypeScript error — fix it. If you must suppress, use " +
+        '`@ts-expect-error` instead so it fails when the underlying issue is ' +
+        'resolved. But first, read the actual error message and address the type ' +
+        'mismatch directly.',
+    enabled: true,
+    optIn: false,
+    allowlist: ['**/*.test.ts', '**/*.spec.ts', '**/__tests__/**'],
+};
+/**
+ * AP-005: @ts-expect-error directive
+ *
+ * Detects `@ts-expect-error` which is safer than @ts-ignore but still indicates
+ * intentional type issues.
+ */
+const AP005_TS_EXPECT_ERROR = {
+    id: 'AP-005',
+    name: '@ts-expect-error directive',
+    category: 'type-safety',
+    severity: 'info',
+    confidence: 'high',
+    detection: {
+        type: 'regex',
+        pattern: String.raw `@ts-expect-error`,
+    },
+    title: '@ts-expect-error used',
+    explanation: '@ts-expect-error is safer than @ts-ignore as it fails when the error disappears. ' +
+        'However, it still indicates intentional type system workarounds.',
+    suggestion: 'Consider if the underlying type issue can be fixed. ' +
+        'If not, ensure the @ts-expect-error comment explains why.',
+    nudge: 'This type error is being suppressed rather than fixed. Read the error ' +
+        'message and resolve the type mismatch. If it is a genuine limitation of the ' +
+        'type system, keep the `@ts-expect-error` but ensure the comment explains ' +
+        'exactly why.',
+    enabled: true,
+    optIn: true, // Often legitimate in tests
+    allowlist: ['**/*.test.ts', '**/*.spec.ts', '**/__tests__/**'],
+};
+/**
+ * AP-006: Empty catch block
+ *
+ * Detects catch blocks that swallow errors without handling them.
+ */
+const AP006_EMPTY_CATCH = {
+    id: 'AP-006',
+    name: 'Empty catch block',
+    category: 'error-handling',
+    severity: 'warning',
+    confidence: 'medium',
+    detection: {
+        type: 'regex',
+        // Matches catch blocks with only whitespace/comments inside
+        pattern: String.raw `catch\s*\([^)]*\)\s*\{\s*(?://[^\n]*\s*)?\}`,
+    },
+    title: 'Empty catch block swallows errors',
+    explanation: 'Empty catch blocks silently swallow errors, making debugging difficult. ' +
+        'Errors should be logged, re-thrown, or explicitly handled.',
+    suggestion: 'At minimum, log the error for debugging. Consider if the error should be re-thrown ' +
+        'or if specific recovery logic is needed.',
+    nudge: "Don't swallow this error silently. At minimum, log it so failures are " +
+        'visible. Better: decide whether this error is recoverable (handle it) or ' +
+        'not (re-throw it). Silent catch blocks make debugging impossible.',
+    enabled: true,
+    optIn: false,
+};
+/**
+ * AP-007: Console usage in production code
+ *
+ * Detects console.log, console.warn, etc. in production code.
+ */
+const AP007_CONSOLE_IN_PROD = {
+    id: 'AP-007',
+    name: 'Console in production code',
+    category: 'code-quality',
+    severity: 'info',
+    confidence: 'medium',
+    detection: {
+        type: 'regex',
+        pattern: String.raw `console\.(log|warn|info|debug)\s*\(`,
+    },
+    title: 'Console statement in production code',
+    explanation: 'Console statements should not appear in production code. They can leak sensitive information, ' +
+        'clutter the console, and indicate incomplete debugging.',
+    suggestion: 'Use a proper logging library with log levels, or remove the console statement. ' +
+        'console.error is acceptable for actual error conditions.',
+    nudge: 'Remove this console statement or replace it with a proper logger that ' +
+        'supports log levels. Console output in production leaks information and ' +
+        'clutters output. If this is intentional debugging, wrap it in a ' +
+        'development-only check.',
+    enabled: true,
+    optIn: true, // Noisy in development
+    allowlist: ['**/*.test.ts', '**/*.spec.ts', '**/scripts/**', '**/cli/**'],
+};
+// =============================================================================
+// Pattern Registry
+// =============================================================================
+/**
+ * All built-in anti-patterns
+ */
+export const PATTERNS = [
+    AP001_BROAD_ESLINT_DISABLE,
+    AP002_RULE_SPECIFIC_ESLINT_DISABLE,
+    AP003_ANY_TYPE,
+    AP004_TS_IGNORE,
+    AP005_TS_EXPECT_ERROR,
+    AP006_EMPTY_CATCH,
+    AP007_CONSOLE_IN_PROD,
+    ...HTML_PATTERNS,
+    ...CSS_PATTERNS,
+];
+// =============================================================================
+// Lookup Functions
+// =============================================================================
+/**
+ * Get a pattern by ID
+ *
+ * @param id - Pattern ID (e.g., 'AP-001')
+ * @returns The pattern definition, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const pattern = getPattern('AP-001');
+ * console.log(pattern?.name); // 'Broad eslint-disable'
+ * ```
+ */
+export function getPattern(id) {
+    return PATTERNS.find((p) => p.id === id);
+}
+/**
+ * Get all patterns in a category
+ *
+ * @param category - The category to filter by
+ * @returns Array of patterns in that category
+ *
+ * @example
+ * ```ts
+ * const escapeHatches = getPatternsByCategory('escape-hatch');
+ * console.log(escapeHatches.map(p => p.id)); // ['AP-001', 'AP-002']
+ * ```
+ */
+export function getPatternsByCategory(category) {
+    return PATTERNS.filter((p) => p.category === category);
+}
+/**
+ * Get all enabled patterns (respects enabled flag, not optIn)
+ *
+ * @returns Array of enabled patterns
+ */
+export function getEnabledPatterns() {
+    return PATTERNS.filter((p) => p.enabled);
+}
+/**
+ * Get all default patterns (enabled and not opt-in)
+ *
+ * @returns Array of patterns that are enabled by default
+ */
+export function getDefaultPatterns() {
+    return PATTERNS.filter((p) => p.enabled && !p.optIn);
+}
+/**
+ * Get pattern IDs for all patterns
+ *
+ * @returns Array of pattern IDs
+ */
+export function getPatternIds() {
+    return PATTERNS.map((p) => p.id);
+}
+/**
+ * Check if a pattern ID is valid
+ *
+ * @param id - Pattern ID to check
+ * @returns true if the ID exists in the catalogue
+ */
+export function isValidPatternId(id) {
+    return PATTERNS.some((p) => p.id === id);
+}

package/dist/antipattern/scanner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Anti-pattern scanner
+ *
+ * Scans source files for anti-patterns using regex-based detection.
+ */
+import type { Warning } from './types.js';
+export interface ScanOptions {
+    /** Pattern IDs to check (default: all default patterns) */
+    patterns?: string[];
+    /** Include opt-in patterns (default: false) */
+    includeOptIn?: boolean;
+}
+export interface ScanResult {
+    /** File path that was scanned */
+    file: string;
+    /** Warnings found in the file */
+    warnings: Warning[];
+    /** Pattern IDs that were checked */
+    patternsChecked: string[];
+}
+/**
+ * Scan a file's content for anti-patterns
+ */
+export declare function scanFile(filePath: string, content: string, options?: ScanOptions): ScanResult;
+/**
+ * Scan multiple files for anti-patterns
+ */
+export declare function scanFiles(files: Array<{
+    path: string;
+    content: string;
+}>, options?: ScanOptions): ScanResult[];
+//# sourceMappingURL=scanner.d.ts.map

package/dist/antipattern/scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/antipattern/scanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,YAAY,CAAC;AAGvD,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oCAAoC;IACpC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAkDD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,UAAU,CAwC7F;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,OAAO,CAAC,EAAE,WAAW,GACpB,UAAU,EAAE,CAEd"}

package/dist/antipattern/scanner.js

@@ -0,0 +1,89 @@
+/**
+ * Anti-pattern scanner
+ *
+ * Scans source files for anti-patterns using regex-based detection.
+ */
+import { minimatch } from 'minimatch';
+import { getDefaultPatterns, getEnabledPatterns, getPattern } from './patterns.js';
+function getPatternsToCheck(options = {}) {
+    const { patterns: patternIds, includeOptIn = false } = options;
+    if (patternIds && patternIds.length > 0) {
+        return patternIds.map((id) => getPattern(id)).filter((p) => p !== undefined);
+    }
+    return includeOptIn ? getEnabledPatterns() : getDefaultPatterns();
+}
+/** Default file extensions for legacy patterns that predate HTML/CSS support */
+const LEGACY_JS_TS_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+function matchesFileExtension(filePath, fileExtensions) {
+    const ext = filePath.substring(filePath.lastIndexOf('.'));
+    return fileExtensions.includes(ext.toLowerCase());
+}
+function isFileAllowlisted(filePath, allowlist) {
+    if (!allowlist || allowlist.length === 0)
+        return false;
+    return allowlist.some((pattern) => minimatch(filePath, pattern, { matchBase: true }));
+}
+function createWarningFromMatch(pattern, filePath, line, column) {
+    return {
+        id: pattern.id,
+        category: 'anti-pattern',
+        severity: pattern.severity,
+        confidence: pattern.confidence,
+        title: pattern.title,
+        message: `Found ${pattern.name} at line ${line}`,
+        explanation: pattern.explanation,
+        suggestion: pattern.suggestion,
+        ...(pattern.nudge ? { nudge: pattern.nudge } : {}),
+        location: {
+            file: filePath,
+            line,
+            column,
+        },
+        pattern: pattern.id,
+    };
+}
+/**
+ * Scan a file's content for anti-patterns
+ */
+export function scanFile(filePath, content, options) {
+    const patterns = getPatternsToCheck(options);
+    const warnings = [];
+    const lines = content.split('\n');
+    for (const pattern of patterns) {
+        if (pattern.detection.type !== 'regex')
+            continue;
+        // File extension matching:
+        // - If fileExtensions is set, use it explicitly
+        // - If allFileTypes is true, skip extension check (matches everything)
+        // - Otherwise, default to JS/TS extensions (legacy behavior prevents false positives on HTML/CSS)
+        const effectiveExtensions = pattern.fileExtensions ?? (pattern.allFileTypes ? undefined : LEGACY_JS_TS_EXTENSIONS);
+        if (effectiveExtensions && !matchesFileExtension(filePath, effectiveExtensions))
+            continue;
+        if (isFileAllowlisted(filePath, pattern.allowlist))
+            continue;
+        const regexPattern = pattern.detection.pattern;
+        if (!regexPattern)
+            continue;
+        const regex = new RegExp(regexPattern, 'g');
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+            const line = lines[lineIndex];
+            const lineNumber = lineIndex + 1;
+            let match;
+            regex.lastIndex = 0;
+            while ((match = regex.exec(line)) !== null) {
+                warnings.push(createWarningFromMatch(pattern, filePath, lineNumber, match.index));
+            }
+        }
+    }
+    return {
+        file: filePath,
+        warnings,
+        patternsChecked: patterns.map((p) => p.id),
+    };
+}
+/**
+ * Scan multiple files for anti-patterns
+ */
+export function scanFiles(files, options) {
+    return files.map((file) => scanFile(file.path, file.content, options));
+}