slopfighter 0.1.0

package/src/rules/commented-out-code.mjs

@@ -0,0 +1,61 @@
+import { lineCol } from './_util.mjs';
+
+// Blocks of 2+ consecutive `//` lines whose stripped content parses like
+// code (has `=`, `;`, `(`, `{`, etc.) → classic AI artifact left after
+// "let me also try" iterations.
+const MIN_BLOCK = 2;
+const CODE_TOKENS = /[=;(){}[\]]|=>|\?\?|::|<-/;
+
+export default {
+  id: 'commented-out-code',
+  severity: 'warn',
+  description: 'Blocks of commented-out code left after AI iterations',
+  check(ctx) {
+    const { source, sourceFile } = ctx;
+    const findings = [];
+    const lines = source.split(/\r?\n/);
+
+    let blockStart = -1;
+    let blockLines = 0;
+    let blockCodeLines = 0;
+    let blockEndPos = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim();
+      const isComment = trimmed.startsWith('//');
+      const stripped = isComment ? trimmed.replace(/^\/\/+\s?/, '').trim() : '';
+      const looksLikeCode = isComment && stripped.length > 0 && CODE_TOKENS.test(stripped);
+      // commented-out import/export/return/etc. → also code-like
+      const looksLikeKeyword = isComment && /^(import|export|return|if|else|for|while|const|let|var|function|class|throw)\b/.test(stripped);
+
+      if (isComment && (looksLikeCode || looksLikeKeyword)) {
+        if (blockStart === -1) blockStart = i;
+        blockLines++;
+        blockCodeLines++;
+      } else if (isComment) {
+        // ordinary comment line — extend block but don't count as code
+        if (blockStart !== -1) blockLines++;
+      } else {
+        flush(i - 1);
+        blockStart = -1;
+        blockLines = 0;
+        blockCodeLines = 0;
+      }
+    }
+    flush(lines.length - 1);
+    return findings;
+
+    function flush(endLine) {
+      if (blockStart === -1) return;
+      if (blockCodeLines >= MIN_BLOCK) {
+        findings.push({
+          message: `${blockCodeLines}-line commented-out code block — remove or restore`,
+          line: blockStart + 1,
+          column: 1,
+          endLine: endLine + 1,
+          endColumn: 1,
+        });
+      }
+    }
+  },
+};

package/src/rules/const-string-concat.mjs

@@ -0,0 +1,37 @@
+import { walk, nodeRange } from './_util.mjs';
+
+// `"foo" + "bar"` — two string literals concatenated. Either it should
+// be a single literal, or a template if it's going to grow. AI often
+// fragments strings for readability and forgets to merge.
+export default {
+  id: 'const-string-concat',
+  severity: 'info',
+  description: 'Two adjacent string literals joined with `+` — merge them',
+  check(ctx) {
+    const { sourceFile, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.BinaryExpression) return;
+      if (node.operatorToken.kind !== ts.SyntaxKind.PlusToken) return;
+      if (!isStringLit(node.left, ts)) return;
+      if (!isStringLit(node.right, ts)) return;
+
+      const range = nodeRange(sourceFile, node);
+      findings.push({
+        message: 'two string literals joined with `+` — write a single literal or template',
+        line: range.line,
+        column: range.column,
+      });
+    });
+    return findings;
+  },
+};
+
+function isStringLit(n, ts) {
+  if (!n) return false;
+  return (
+    n.kind === ts.SyntaxKind.StringLiteral ||
+    n.kind === ts.SyntaxKind.NoSubstitutionTemplateLiteral
+  );
+}

package/src/rules/dead-imports.mjs

@@ -0,0 +1,58 @@
+import { walk, lineCol } from './_util.mjs';
+
+// Heuristic: an imported name is dead if it appears only once in the file
+// (its own import statement). Cheap, no scope tracking, false-positive-low
+// for typical AI code.
+export default {
+  id: 'dead-imports',
+  severity: 'warn',
+  description: 'Imported names that are never referenced in the file',
+  check(ctx) {
+    const { sourceFile, source, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.ImportDeclaration) return;
+      const clause = node.importClause;
+      if (!clause) return; // side-effect import
+
+      const names = [];
+      // default import:  import Foo from 'x'
+      if (clause.name) names.push(clause.name);
+      // named bindings: import { a, b as c } from 'x'  OR  import * as ns from 'x'
+      const nb = clause.namedBindings;
+      if (nb) {
+        if (nb.kind === ts.SyntaxKind.NamespaceImport) {
+          names.push(nb.name);
+        } else if (nb.kind === ts.SyntaxKind.NamedImports) {
+          for (const el of nb.elements) names.push(el.name);
+        }
+      }
+
+      for (const id of names) {
+        const text = id.text;
+        const re = new RegExp(`\\b${escapeRegex(text)}\\b`, 'g');
+        let count = 0;
+        let m;
+        while ((m = re.exec(source)) !== null) {
+          count++;
+          if (count > 1) break;
+        }
+        if (count <= 1) {
+          const pos = id.getStart(sourceFile);
+          const loc = lineCol(sourceFile, pos);
+          findings.push({
+            message: `import "${text}" is never used in this file`,
+            line: loc.line,
+            column: loc.column,
+          });
+        }
+      }
+    });
+    return findings;
+  },
+};
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/rules/else-after-return.mjs

@@ -0,0 +1,43 @@
+import { walk, nodeRange } from './_util.mjs';
+
+// `if (x) { return a; } else { return b; }` — the `else` is dead because
+// the `if` branch already returned. Flatten it.
+// Also catches `if (x) return; else doThing();`.
+export default {
+  id: 'else-after-return',
+  severity: 'info',
+  description: 'else-block after a returning if-block — unnecessary nesting',
+  check(ctx) {
+    const { sourceFile, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.IfStatement) return;
+      if (!node.elseStatement) return;
+      if (!alwaysExits(node.thenStatement, ts)) return;
+
+      const range = nodeRange(sourceFile, node.elseStatement);
+      findings.push({
+        message: '`else` after a returning `if` — drop the else and unindent',
+        line: range.line,
+        column: range.column,
+      });
+    });
+    return findings;
+  },
+};
+
+function alwaysExits(stmt, ts) {
+  if (!stmt) return false;
+  const k = stmt.kind;
+  if (k === ts.SyntaxKind.ReturnStatement) return true;
+  if (k === ts.SyntaxKind.ThrowStatement) return true;
+  if (k === ts.SyntaxKind.ContinueStatement) return true;
+  if (k === ts.SyntaxKind.BreakStatement) return true;
+  if (k === ts.SyntaxKind.Block) {
+    const stmts = stmt.statements;
+    if (stmts.length === 0) return false;
+    return alwaysExits(stmts[stmts.length - 1], ts);
+  }
+  return false;
+}

package/src/rules/excessive-jsdoc.mjs

@@ -0,0 +1,50 @@
+import { walk, lineCol } from './_util.mjs';
+
+// 8+ line JSDoc over a trivial getter / setter / one-line function is
+// almost always AI padding. Threshold tuned to not flag genuine API docs
+// for non-trivial functions.
+const MIN_JSDOC_LINES = 6;
+const MAX_BODY_LINES = 3;
+
+export default {
+  id: 'excessive-jsdoc',
+  severity: 'info',
+  description: 'JSDoc blocks longer than the function body itself',
+  check(ctx) {
+    const { sourceFile, source, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (
+        node.kind !== ts.SyntaxKind.FunctionDeclaration &&
+        node.kind !== ts.SyntaxKind.MethodDeclaration &&
+        node.kind !== ts.SyntaxKind.ArrowFunction
+      ) return;
+
+      const leading = ts.getLeadingCommentRanges(source, node.getFullStart()) || [];
+      const jsdoc = leading.find(
+        (c) => c.kind === ts.SyntaxKind.MultiLineCommentTrivia && source.slice(c.pos, c.pos + 3) === '/**'
+      );
+      if (!jsdoc) return;
+
+      const docText = source.slice(jsdoc.pos, jsdoc.end);
+      const docLines = docText.split(/\r?\n/).length;
+      if (docLines < MIN_JSDOC_LINES) return;
+
+      const body = node.body;
+      if (!body) return;
+      const bodyStart = lineCol(sourceFile, body.getStart(sourceFile)).line;
+      const bodyEnd = lineCol(sourceFile, body.getEnd()).line;
+      const bodyLines = bodyEnd - bodyStart;
+      if (bodyLines > MAX_BODY_LINES) return;
+
+      const loc = lineCol(sourceFile, jsdoc.pos);
+      findings.push({
+        message: `${docLines}-line JSDoc for ${bodyLines}-line body — trim or drop`,
+        line: loc.line,
+        column: loc.column,
+      });
+    });
+    return findings;
+  },
+};

package/src/rules/explicit-any.mjs

@@ -0,0 +1,30 @@
+import { walk, lineCol } from './_util.mjs';
+
+// Explicit `: any` is almost always AI-generated laziness when a more
+// specific type was knowable. Skipped if there's a `// eslint-disable` /
+// `// slopfighter-disable` style comment on the same line.
+export default {
+  id: 'explicit-any',
+  severity: 'warn',
+  description: 'Explicit `any` type annotations',
+  check(ctx) {
+    const { sourceFile, source, ts } = ctx;
+    if (!sourceFile.fileName.match(/\.(ts|tsx)$/)) return [];
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.AnyKeyword) return;
+      const pos = node.getStart(sourceFile);
+      const loc = lineCol(sourceFile, pos);
+      // skip if the line has a disable marker
+      const lineText = source.split(/\r?\n/)[loc.line - 1] || '';
+      if (/slopfighter-disable|eslint-disable|@ts-ignore|@ts-expect-error/.test(lineText)) return;
+      findings.push({
+        message: 'avoid `any` — pick a real type or use `unknown`',
+        line: loc.line,
+        column: loc.column,
+      });
+    });
+    return findings;
+  },
+};

package/src/rules/future-proof-naming.mjs

@@ -0,0 +1,46 @@
+import { walk, nodeRange } from './_util.mjs';
+
+// Manager/Helper/Utils/Service-suffixed class with <= 1 real method is a
+// premature abstraction. Common AI tic: wraps a single function in a class
+// "for future expansion".
+const SUFFIXES = ['Manager', 'Helper', 'Utils', 'Util', 'Handler', 'Wrapper', 'Provider'];
+
+export default {
+  id: 'future-proof-naming',
+  severity: 'warn',
+  description: 'Manager/Helper/Utils-class with only one method — just use a function',
+  check(ctx) {
+    const { sourceFile, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.ClassDeclaration) return;
+      if (!node.name) return;
+      // implements/extends → polymorphic, the suffix is meaningful
+      if (node.heritageClauses && node.heritageClauses.length > 0) return;
+      const name = node.name.text;
+      const suffix = SUFFIXES.find((s) => name.endsWith(s));
+      if (!suffix) return;
+
+      const members = node.members || [];
+      const methods = members.filter(
+        (m) => m.kind === ts.SyntaxKind.MethodDeclaration || m.kind === ts.SyntaxKind.PropertyDeclaration
+      );
+      const realMethods = methods.filter((m) => m.kind === ts.SyntaxKind.MethodDeclaration);
+      if (realMethods.length > 1) return;
+      // ignore if it has stored state (multiple property declarations)
+      const props = methods.filter((m) => m.kind === ts.SyntaxKind.PropertyDeclaration);
+      if (props.length >= 2) return;
+
+      const range = nodeRange(sourceFile, node);
+      findings.push({
+        message: `class "${name}" has ${realMethods.length} method(s) — convert to a plain function`,
+        line: range.line,
+        column: range.column,
+        endLine: range.endLine,
+        endColumn: range.endColumn,
+      });
+    });
+    return findings;
+  },
+};

package/src/rules/index.mjs

@@ -0,0 +1,39 @@
+import paddingComments from './padding-comments.mjs';
+import uselessTryCatch from './useless-try-catch.mjs';
+import deadImports from './dead-imports.mjs';
+import explicitAny from './explicit-any.mjs';
+import futureProofNaming from './future-proof-naming.mjs';
+import alwaysTrueConditional from './always-true-conditional.mjs';
+import excessiveJsdoc from './excessive-jsdoc.mjs';
+import redundantErrorRethrow from './redundant-error-rethrow.mjs';
+import singleMethodClass from './single-method-class.mjs';
+import overDefensiveNullCheck from './over-defensive-null-check.mjs';
+import commentedOutCode from './commented-out-code.mjs';
+import unnecessaryAsync from './unnecessary-async.mjs';
+import trivialArrowWrapper from './trivial-arrow-wrapper.mjs';
+import redundantAwait from './redundant-await.mjs';
+import returnUndefined from './return-undefined.mjs';
+import elseAfterReturn from './else-after-return.mjs';
+import redundantBooleanCast from './redundant-boolean-cast.mjs';
+import constStringConcat from './const-string-concat.mjs';
+
+export const allRules = [
+  paddingComments,
+  uselessTryCatch,
+  deadImports,
+  explicitAny,
+  futureProofNaming,
+  alwaysTrueConditional,
+  excessiveJsdoc,
+  redundantErrorRethrow,
+  singleMethodClass,
+  overDefensiveNullCheck,
+  commentedOutCode,
+  unnecessaryAsync,
+  trivialArrowWrapper,
+  redundantAwait,
+  returnUndefined,
+  elseAfterReturn,
+  redundantBooleanCast,
+  constStringConcat,
+];

package/src/rules/over-defensive-null-check.mjs

@@ -0,0 +1,81 @@
+import { walk, nodeRange } from './_util.mjs';
+
+// `if (x !== null && x !== undefined && x)` — three checks where one
+// suffices. Or `if (x != null) { if (x !== undefined) {...} }` — nested
+// nullish guards.  AI loves these.
+export default {
+  id: 'over-defensive-null-check',
+  severity: 'info',
+  description: 'Redundant null/undefined checks chained or nested',
+  check(ctx) {
+    const { sourceFile, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.IfStatement) return;
+      const cond = node.expression;
+      const nullishOps = countNullishOps(cond, ts);
+      if (nullishOps.identifiers.size === 1 && nullishOps.count >= 3) {
+        const range = nodeRange(sourceFile, cond);
+        findings.push({
+          message: `triple nullish check on the same identifier — \`if (${[...nullishOps.identifiers][0]} != null)\` is enough`,
+          line: range.line,
+          column: range.column,
+        });
+      }
+    });
+    return findings;
+  },
+};
+
+function countNullishOps(node, ts) {
+  const idents = new Set();
+  let count = 0;
+  visit(node);
+  return { count, identifiers: idents };
+
+  function visit(n) {
+    if (!n) return;
+    if (n.kind === ts.SyntaxKind.BinaryExpression) {
+      const op = n.operatorToken.kind;
+      if (
+        op === ts.SyntaxKind.AmpersandAmpersandToken ||
+        op === ts.SyntaxKind.BarBarToken
+      ) {
+        visit(n.left); visit(n.right);
+        return;
+      }
+      if (
+        op === ts.SyntaxKind.EqualsEqualsToken ||
+        op === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+        op === ts.SyntaxKind.ExclamationEqualsToken ||
+        op === ts.SyntaxKind.ExclamationEqualsEqualsToken
+      ) {
+        const ident = pickIdent(n, ts);
+        const literal = pickNullishLiteral(n, ts);
+        if (ident && literal) {
+          idents.add(ident);
+          count++;
+        }
+      }
+      return;
+    }
+    // bare identifier as truthiness check on same var counts as one extra
+    if (n.kind === ts.SyntaxKind.Identifier) {
+      idents.add(n.text);
+      count++;
+    }
+  }
+}
+
+function pickIdent(bin, ts) {
+  if (bin.left.kind === ts.SyntaxKind.Identifier) return bin.left.text;
+  if (bin.right.kind === ts.SyntaxKind.Identifier) return bin.right.text;
+  return null;
+}
+function pickNullishLiteral(bin, ts) {
+  const isNullish = (n) =>
+    n.kind === ts.SyntaxKind.NullKeyword ||
+    (n.kind === ts.SyntaxKind.Identifier && n.text === 'undefined');
+  return isNullish(bin.left) || isNullish(bin.right);
+}

package/src/rules/padding-comments.mjs

@@ -0,0 +1,131 @@
+import { walk, lineCol, deCamel } from './_util.mjs';
+
+// A comment is "padding" when its content tokens overlap fully with the
+// following declaration's name (allowing verb-form variation).
+// Classic AI tic: `// Get user name` over `function getUserName()`.
+const STOPWORDS = new Set([
+  'this', 'a', 'an', 'the', 'is', 'are', 'that', 'which', 'to', 'of', 'in', 'on',
+  'and', 'or', 'for', 'with', 'function', 'method', 'class', 'helper', 'simple',
+  'utility', 'just', 'simply', 'used',
+]);
+const VERBS = new Set([
+  'get', 'gets', 'set', 'sets', 'return', 'returns', 'fetch', 'fetches',
+  'retrieve', 'retrieves', 'compute', 'computes', 'calculate', 'calculates',
+  'create', 'creates', 'build', 'builds', 'make', 'makes', 'handle', 'handles',
+  'process', 'processes', 'check', 'checks', 'validate', 'validates',
+  'parse', 'parses', 'load', 'loads', 'save', 'saves', 'read', 'reads',
+  'write', 'writes', 'find', 'finds', 'add', 'adds', 'remove', 'removes',
+]);
+
+export default {
+  id: 'padding-comments',
+  severity: 'warn',
+  description: 'Comments that just restate the function/variable name',
+  check(ctx) {
+    const { sourceFile, source, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      const name = getDeclName(node, ts);
+      if (!name) return;
+
+      const leading = ts.getLeadingCommentRanges(source, node.getFullStart()) || [];
+      for (const c of leading) {
+        const raw = source.slice(c.pos, c.end);
+        // skip JSDoc — excessive-jsdoc covers it
+        if (raw.startsWith('/**')) continue;
+        const inner = stripCommentMarkers(raw);
+        if (!inner) continue;
+        if (looksLikePadding(inner, name)) {
+          const loc = lineCol(sourceFile, c.pos);
+          findings.push({
+            message: `Comment "${truncate(inner, 50)}" just restates "${name}". Drop it.`,
+            line: loc.line,
+            column: loc.column,
+            fix: { start: c.pos, end: c.end + skipTrailingNewline(source, c.end), replacement: '' },
+          });
+        }
+      }
+    });
+    return findings;
+  },
+};
+
+function getDeclName(node, ts) {
+  if (!node) return null;
+  const k = node.kind;
+  if (k === ts.SyntaxKind.FunctionDeclaration && node.name) return node.name.text;
+  if (k === ts.SyntaxKind.ClassDeclaration && node.name) return node.name.text;
+  if (k === ts.SyntaxKind.MethodDeclaration && node.name && node.name.text) return node.name.text;
+  if (k === ts.SyntaxKind.VariableStatement) {
+    // only match `const foo = () => ...` / `const foo = function() ...`,
+    // NOT `const Typescript = { ... }` (section labels in config objects)
+    const decl = node.declarationList?.declarations?.[0];
+    if (!decl || !decl.name || !decl.name.text) return null;
+    const init = decl.initializer;
+    if (!init) return null;
+    if (
+      init.kind === ts.SyntaxKind.ArrowFunction ||
+      init.kind === ts.SyntaxKind.FunctionExpression
+    ) {
+      return decl.name.text;
+    }
+    return null;
+  }
+  return null;
+}
+
+function stripCommentMarkers(text) {
+  return text
+    .replace(/^\/\*+/, '')
+    .replace(/\*+\/$/, '')
+    .replace(/^\/\/+/, '')
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*+\s?/, '').trim())
+    .filter(Boolean)
+    .join(' ')
+    .trim();
+}
+
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]+/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function looksLikePadding(commentText, name) {
+  const cwords = tokenize(commentText);
+  if (cwords.length === 0 || cwords.length > 14) return false;
+
+  const nameWords = tokenize(deCamel(name));
+  const nset = new Set(nameWords.filter((w) => !STOPWORDS.has(w)));
+  const cset = new Set(cwords.filter((w) => !STOPWORDS.has(w)));
+  if (nset.size === 0) return false;
+
+  const commentHasVerb = [...cset].some((w) => VERBS.has(w));
+  for (const w of nset) {
+    if (cset.has(w)) continue;
+    if (cset.has(w + 's')) continue;
+    if (cset.has(w.replace(/s$/, ''))) continue;
+    if (VERBS.has(w) && commentHasVerb) continue;
+    return false; // name token absent → not padding
+  }
+
+  // Comment may add at most a couple of "extra" content words.
+  const extras = [...cset].filter(
+    (c) => !nset.has(c) && !VERBS.has(c) && !nset.has(c.replace(/s$/, ''))
+  );
+  return extras.length <= 2;
+}
+
+function truncate(s, n) {
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+function skipTrailingNewline(source, pos) {
+  if (source[pos] === '\r' && source[pos + 1] === '\n') return 2;
+  if (source[pos] === '\n' || source[pos] === '\r') return 1;
+  return 0;
+}

package/src/rules/redundant-await.mjs

@@ -0,0 +1,51 @@
+import { walk, nodeRange } from './_util.mjs';
+
+// `return await x` outside of a try/catch adds an extra microtask and a
+// useless stack frame. Inside try/catch it's meaningful (catches the
+// rejection), so we exclude that case.
+export default {
+  id: 'redundant-await',
+  severity: 'info',
+  description: '`return await x` outside try — drop the await',
+  check(ctx) {
+    const { sourceFile, ts } = ctx;
+    const findings = [];
+
+    walk(sourceFile, (node) => {
+      if (node.kind !== ts.SyntaxKind.ReturnStatement) return;
+      if (!node.expression || node.expression.kind !== ts.SyntaxKind.AwaitExpression) return;
+      // walk up the parent chain — if any TryStatement contains us inside its tryBlock, skip
+      if (insideTryBlock(node, ts)) return;
+      const range = nodeRange(sourceFile, node);
+      findings.push({
+        message: '`return await x` outside try/catch — just `return x`',
+        line: range.line,
+        column: range.column,
+      });
+    });
+    return findings;
+  },
+};
+
+function insideTryBlock(node, ts) {
+  let p = node.parent;
+  while (p) {
+    if (p.kind === ts.SyntaxKind.TryStatement && p.tryBlock && containsNode(p.tryBlock, node)) {
+      return true;
+    }
+    // stop at function boundary — await is scoped to enclosing fn
+    if (
+      p.kind === ts.SyntaxKind.FunctionDeclaration ||
+      p.kind === ts.SyntaxKind.FunctionExpression ||
+      p.kind === ts.SyntaxKind.ArrowFunction ||
+      p.kind === ts.SyntaxKind.MethodDeclaration
+    ) return false;
+    p = p.parent;
+  }
+  return false;
+}
+
+function containsNode(parent, target) {
+  if (!parent || !target) return false;
+  return target.pos >= parent.pos && target.end <= parent.end;
+}