distyll 0.1.0

package/src/rules/over-defensive-nulls.ts

@@ -0,0 +1,137 @@
+import type Parser from 'tree-sitter';
+import { walkTree, findNodesMulti } from '../parser';
+import type { Finding, Rule } from '../types';
+
+/**
+ * Detects patterns where code checks for null/undefined on values that
+ * were just assigned or are non-nullable by context. Focuses on clearly
+ * unnecessary checks to minimize false positives.
+ *
+ * Patterns detected:
+ * - Null check immediately after non-nullable assignment: `const x = 5; if (x != null) ...`
+ * - Double null checks: `if (x != null) { if (x != null) ... }`
+ * - Typeof check on known values: `const x = []; if (typeof x !== 'undefined') ...`
+ */
+
+const LITERAL_TYPES = new Set([
+  'number', 'string', 'true', 'false', 'template_string',
+  'array', 'object', 'regex',
+  // Python
+  'integer', 'float', 'list', 'dictionary', 'set', 'tuple',
+]);
+
+const NULL_CHECK_PATTERNS = new Set([
+  '!= null', '!== null', '!= undefined', '!== undefined',
+  '!= None', 'is not None',
+]);
+
+function isNullCheck(node: Parser.SyntaxNode): boolean {
+  const text = node.text.replace(/\s+/g, ' ').trim();
+  for (const pattern of NULL_CHECK_PATTERNS) {
+    if (text.includes(pattern)) return true;
+  }
+  // typeof x !== 'undefined'
+  if (text.includes('typeof') && text.includes('undefined')) return true;
+  return false;
+}
+
+function isLiteralAssignment(node: Parser.SyntaxNode): boolean {
+  // Check if the right side of an assignment is a literal
+  const value = node.childForFieldName('value') ?? node.childForFieldName('right');
+  if (!value) return false;
+  return LITERAL_TYPES.has(value.type);
+}
+
+function getAssignedName(node: Parser.SyntaxNode): string | null {
+  const nameNode = node.childForFieldName('name') ?? node.childForFieldName('left');
+  if (!nameNode) return null;
+  return nameNode.text;
+}
+
+export const overDefensiveNulls: Rule = {
+  name: 'over-defensive-nulls',
+  description: 'Flags null/undefined checks on values that are clearly non-nullable',
+  severity: 'info',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+
+    // Strategy: find variable declarations with literal values, then check if
+    // the very next sibling is a null check on that variable
+    const declarations = findNodesMulti(tree.rootNode, [
+      'lexical_declaration', 'variable_declaration',
+      // Python
+      'assignment',
+    ]);
+
+    for (const decl of declarations) {
+      let assignedName: string | null = null;
+
+      // For JS/TS: const x = literal
+      if (decl.type === 'lexical_declaration' || decl.type === 'variable_declaration') {
+        for (const child of decl.namedChildren) {
+          if (child.type === 'variable_declarator' && isLiteralAssignment(child)) {
+            assignedName = getAssignedName(child);
+          }
+        }
+      }
+      // For Python: x = literal
+      if (decl.type === 'assignment' && isLiteralAssignment(decl)) {
+        assignedName = getAssignedName(decl);
+      }
+
+      if (!assignedName) continue;
+
+      // Check the next sibling statement for a null check on this variable
+      const nextSibling = decl.nextNamedSibling;
+      if (!nextSibling) continue;
+
+      if (nextSibling.type === 'if_statement' || nextSibling.type === 'expression_statement') {
+        const condition = nextSibling.childForFieldName('condition') ?? nextSibling;
+        if (isNullCheck(condition) && condition.text.includes(assignedName)) {
+          findings.push({
+            file: filePath,
+            line: nextSibling.startPosition.row + 1,
+            column: nextSibling.startPosition.column + 1,
+            endLine: nextSibling.endPosition.row + 1,
+            endColumn: nextSibling.endPosition.column + 1,
+            rule: 'over-defensive-nulls',
+            severity: 'info',
+            message: `Null check on '${assignedName}' is unnecessary — it was just assigned a non-nullable value on line ${decl.startPosition.row + 1}`,
+          });
+        }
+      }
+    }
+
+    // Detect nested duplicate null checks
+    const ifStatements = findNodesMulti(tree.rootNode, ['if_statement']);
+    for (const ifStmt of ifStatements) {
+      const condition = ifStmt.childForFieldName('condition');
+      if (!condition || !isNullCheck(condition)) continue;
+
+      const consequence = ifStmt.childForFieldName('consequence') ?? ifStmt.childForFieldName('body');
+      if (!consequence) continue;
+
+      // Look for nested if with the same null check
+      walkTree(consequence, (inner) => {
+        if (inner.type === 'if_statement' && inner !== ifStmt) {
+          const innerCond = inner.childForFieldName('condition');
+          if (innerCond && isNullCheck(innerCond) && innerCond.text === condition.text) {
+            findings.push({
+              file: filePath,
+              line: inner.startPosition.row + 1,
+              column: inner.startPosition.column + 1,
+              endLine: inner.endPosition.row + 1,
+              endColumn: inner.endPosition.column + 1,
+              rule: 'over-defensive-nulls',
+              severity: 'info',
+              message: `Duplicate null check — '${innerCond.text}' is already checked on line ${ifStmt.startPosition.row + 1}`,
+            });
+          }
+        }
+      });
+    }
+
+    return findings;
+  },
+};

package/src/rules/redundant-else-return.ts

@@ -0,0 +1,61 @@
+import type Parser from 'tree-sitter';
+import { findNodes } from '../parser';
+import type { Finding, Rule } from '../types';
+
+function blockEndsWithReturn(block: Parser.SyntaxNode): boolean {
+  const children = block.namedChildren;
+  if (children.length === 0) return false;
+  const last = children[children.length - 1];
+  return last.type === 'return_statement' || last.type === 'throw_statement';
+}
+
+export const redundantElseReturn: Rule = {
+  name: 'redundant-else-return',
+  description: 'Flags else blocks after if blocks that end with return/throw',
+  severity: 'info',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const ifStatements = findNodes(tree.rootNode, 'if_statement');
+
+    for (const ifNode of ifStatements) {
+      const consequence = ifNode.childForFieldName('consequence');
+      const alternative = ifNode.childForFieldName('alternative');
+
+      if (!consequence || !alternative) continue;
+
+      // Skip if the alternative is another if statement (else if chains are fine)
+      if (alternative.type === 'if_statement') continue;
+
+      // For else_clause, check the inner block
+      let altBlock = alternative;
+      if (alternative.type === 'else_clause') {
+        const inner = alternative.namedChildren[0];
+        if (!inner || inner.type === 'if_statement') continue;
+        altBlock = inner;
+      }
+
+      // Check if the if-block ends with return or throw
+      let ifBlock = consequence;
+      if (consequence.type === 'statement_block') {
+        ifBlock = consequence;
+      }
+
+      if (!blockEndsWithReturn(ifBlock)) continue;
+
+      // The else block is redundant — the code inside could be un-indented
+      findings.push({
+        file: filePath,
+        line: alternative.startPosition.row + 1,
+        column: alternative.startPosition.column + 1,
+        endLine: alternative.endPosition.row + 1,
+        endColumn: alternative.endPosition.column + 1,
+        rule: 'redundant-else-return',
+        severity: 'info',
+        message: 'else block is unnecessary after return/throw — un-indent and remove the else',
+      });
+    }
+
+    return findings;
+  },
+};

package/src/rules/single-option-object.ts

@@ -0,0 +1,97 @@
+import type Parser from 'tree-sitter';
+import { findNodesMulti } from '../parser';
+import type { Finding, Rule } from '../types';
+
+function getDestructuredParams(node: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  const params = node.childForFieldName('parameters');
+  if (!params) return [];
+
+  return params.namedChildren.filter((p) => {
+    // Destructured object parameter: function({ foo }) {}
+    if (p.type === 'object_pattern') return true;
+    // TypeScript: function({ foo }: Options) {}
+    if (p.type === 'required_parameter' || p.type === 'optional_parameter') {
+      const pattern = p.childForFieldName('pattern');
+      if (pattern?.type === 'object_pattern') return true;
+    }
+    return false;
+  });
+}
+
+function getObjectPatternPropertyCount(node: Parser.SyntaxNode): number {
+  let objectPattern = node;
+  if (node.type === 'required_parameter' || node.type === 'optional_parameter') {
+    const pattern = node.childForFieldName('pattern');
+    if (pattern?.type === 'object_pattern') objectPattern = pattern;
+    else return 0;
+  }
+  if (objectPattern.type !== 'object_pattern') return 0;
+
+  // Count actual properties (not rest elements)
+  return objectPattern.namedChildren.filter(
+    (c) =>
+      c.type === 'shorthand_property_identifier_pattern' ||
+      c.type === 'pair_pattern' ||
+      c.type === 'object_assignment_pattern' ||
+      c.type === 'assignment_pattern'
+  ).length;
+}
+
+function getFunctionName(node: Parser.SyntaxNode): string | null {
+  if (node.type === 'function_declaration' || node.type === 'method_definition') {
+    return node.childForFieldName('name')?.text ?? null;
+  }
+  if (node.parent?.type === 'variable_declarator') {
+    return node.parent.childForFieldName('name')?.text ?? null;
+  }
+  return null;
+}
+
+export const singleOptionObject: Rule = {
+  name: 'single-option-object',
+  description: 'Flags function parameters that destructure an object with only one property',
+  severity: 'info',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+
+    const functions = findNodesMulti(tree.rootNode, [
+      'function_declaration',
+      'arrow_function',
+      'function',
+      'method_definition',
+    ]);
+
+    for (const fn of functions) {
+      const destructuredParams = getDestructuredParams(fn);
+
+      for (const param of destructuredParams) {
+        const propCount = getObjectPatternPropertyCount(param);
+
+        if (propCount === 1) {
+          // Skip if function has only this one parameter and it's a callback
+          const parent = fn.parent;
+          if (parent?.type === 'arguments' || parent?.type === 'call_expression') {
+            continue;
+          }
+
+          const name = getFunctionName(fn);
+          const label = name ? `Function '${name}'` : 'Function';
+
+          findings.push({
+            file: filePath,
+            line: param.startPosition.row + 1,
+            column: param.startPosition.column + 1,
+            endLine: param.endPosition.row + 1,
+            endColumn: param.endPosition.column + 1,
+            rule: 'single-option-object',
+            severity: 'info',
+            message: `${label} destructures an options object with only 1 property — use a plain parameter instead`,
+          });
+        }
+      }
+    }
+
+    return findings;
+  },
+};

package/src/rules/single-use-wrapper.ts

@@ -0,0 +1,184 @@
+import type Parser from 'tree-sitter';
+import { findNodesMulti } from '../parser';
+import type { Finding, Rule } from '../types';
+
+function getFunctionBody(node: Parser.SyntaxNode): Parser.SyntaxNode | null {
+  return node.childForFieldName('body');
+}
+
+function getFunctionName(node: Parser.SyntaxNode): string | null {
+  if (node.type === 'function_declaration' || node.type === 'method_definition') {
+    const nameNode = node.childForFieldName('name');
+    return nameNode?.text ?? null;
+  }
+  if (node.type === 'variable_declarator') {
+    const nameNode = node.childForFieldName('name');
+    return nameNode?.text ?? null;
+  }
+  return null;
+}
+
+function getStatements(body: Parser.SyntaxNode): Parser.SyntaxNode[] {
+  if (body.type === 'statement_block') {
+    return body.namedChildren;
+  }
+  return [];
+}
+
+const COMPLEX_ARG_TYPES = new Set([
+  'arrow_function', 'function', 'object', 'array',
+  'template_string', 'binary_expression', 'new_expression',
+  'ternary_expression', 'conditional_expression',
+  'unary_expression', 'update_expression', 'assignment_expression',
+  'augmented_assignment_expression', 'yield_expression',
+  'spread_element', 'regex', 'class',
+]);
+
+function isSimpleNode(node: Parser.SyntaxNode): boolean {
+  if (node.type === 'identifier' || node.type === 'this' ||
+      node.type === 'string' || node.type === 'number' ||
+      node.type === 'true' || node.type === 'false' ||
+      node.type === 'null' || node.type === 'undefined') {
+    return true;
+  }
+  // Simple member_expression like a.b (not computed a[b])
+  if (node.type === 'member_expression') {
+    const computed = node.children.some(c => c.type === '[');
+    return !computed;
+  }
+  return false;
+}
+
+function hasOnlySimpleArguments(callExpr: Parser.SyntaxNode): boolean {
+  // Check if callee involves complex expressions (e.g. new Foo().method())
+  const callee = callExpr.childForFieldName('function');
+  if (callee?.type === 'member_expression') {
+    const object = callee.childForFieldName('object');
+    if (object && COMPLEX_ARG_TYPES.has(object.type)) return false;
+    // Also check for chained calls with complex args: foo(complex).bar(simple)
+    if (object?.type === 'call_expression') {
+      if (!hasOnlySimpleArguments(object)) return false;
+    }
+  }
+
+  const args = callExpr.childForFieldName('arguments');
+  if (!args) return true;
+
+  for (const arg of args.namedChildren) {
+    if (isSimpleNode(arg)) continue;
+    // Known complex types
+    if (COMPLEX_ARG_TYPES.has(arg.type)) return false;
+    // Anything else unexpected — be conservative, treat as complex
+    return false;
+  }
+  return true;
+}
+
+function extractCallExpression(node: Parser.SyntaxNode): Parser.SyntaxNode | null {
+  if (node.type === 'call_expression') return node;
+  // Parenthesized expression wrapping a call
+  if (node.type === 'parenthesized_expression' && node.namedChildren.length === 1) {
+    return extractCallExpression(node.namedChildren[0]);
+  }
+  return null;
+}
+
+function isSimpleDelegatingFunction(body: Parser.SyntaxNode): boolean {
+  // For arrow functions with expression body (no braces)
+  if (body.type === 'call_expression') {
+    return hasOnlySimpleArguments(body);
+  }
+
+  const stmts = getStatements(body);
+  if (stmts.length !== 1) return false;
+
+  const stmt = stmts[0];
+
+  // Single return statement with a function call
+  if (stmt.type === 'return_statement') {
+    const returnValue = stmt.namedChildren[0];
+    if (!returnValue) return false;
+    const call = extractCallExpression(returnValue);
+    if (!call) return false;
+    return hasOnlySimpleArguments(call);
+  }
+
+  // Single expression statement that is a function call (void wrapper)
+  if (stmt.type === 'expression_statement') {
+    const expr = stmt.namedChildren[0];
+    if (!expr) return false;
+    const call = extractCallExpression(expr);
+    if (!call) return false;
+    return hasOnlySimpleArguments(call);
+  }
+
+  return false;
+}
+
+function getParameterCount(node: Parser.SyntaxNode): number {
+  const params = node.childForFieldName('parameters');
+  if (!params) return 0;
+  return params.namedChildren.filter(c =>
+    c.type === 'identifier' ||
+    c.type === 'required_parameter' ||
+    c.type === 'optional_parameter' ||
+    c.type === 'rest_parameter' ||
+    c.type === 'assignment_pattern'
+  ).length;
+}
+
+export const singleUseWrapper: Rule = {
+  name: 'single-use-wrapper',
+  description: 'Flags functions that merely delegate to another function without adding logic',
+  severity: 'warning',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+
+    const functionNodes = findNodesMulti(tree.rootNode, [
+      'function_declaration',
+      'arrow_function',
+      'function',
+    ]);
+
+    for (const fn of functionNodes) {
+      const body = getFunctionBody(fn);
+      if (!body) continue;
+
+      if (!isSimpleDelegatingFunction(body)) continue;
+
+      // Skip if function has more than 3 parameters (likely an intentional adapter)
+      if (getParameterCount(fn) > 3) continue;
+
+      // Skip anonymous functions passed as callbacks — those are idiomatic
+      if (fn.type === 'arrow_function' || fn.type === 'function') {
+        const parent = fn.parent;
+        if (parent?.type === 'arguments' || parent?.type === 'call_expression' ||
+            parent?.type === 'array' || parent?.type === 'pair') {
+          continue;
+        }
+      }
+
+      // Try to get the function name for the message
+      let name = getFunctionName(fn);
+      if (!name && fn.parent?.type === 'variable_declarator') {
+        name = getFunctionName(fn.parent);
+      }
+
+      const label = name ? `Function '${name}'` : 'Function';
+
+      findings.push({
+        file: filePath,
+        line: fn.startPosition.row + 1,
+        column: fn.startPosition.column + 1,
+        endLine: fn.endPosition.row + 1,
+        endColumn: fn.endPosition.column + 1,
+        rule: 'single-use-wrapper',
+        severity: 'warning',
+        message: `${label} only delegates to another function — consider inlining it`,
+      });
+    }
+
+    return findings;
+  },
+};

package/src/rules/unnecessary-try-catch.ts

@@ -0,0 +1,121 @@
+import type Parser from 'tree-sitter';
+import { findNodes, walkTree } from '../parser';
+import type { Finding, Rule } from '../types';
+
+const THROWING_CALL_INDICATORS = new Set([
+  'fetch', 'require', 'import', 'eval',
+  'JSON.parse', 'JSON.stringify',
+  'parseInt', 'parseFloat',
+  'decodeURI', 'decodeURIComponent',
+  'atob', 'btoa',
+]);
+
+function isAwaitExpression(node: Parser.SyntaxNode): boolean {
+  let found = false;
+  walkTree(node, (n) => {
+    if (n.type === 'await_expression') found = true;
+  });
+  return found;
+}
+
+function containsThrowStatement(node: Parser.SyntaxNode): boolean {
+  let found = false;
+  walkTree(node, (n) => {
+    if (n.type === 'throw_statement') found = true;
+  });
+  return found;
+}
+
+function containsFunctionCall(node: Parser.SyntaxNode): boolean {
+  let found = false;
+  walkTree(node, (n) => {
+    if (n.type === 'call_expression') found = true;
+  });
+  return found;
+}
+
+function isPropertyAccess(node: Parser.SyntaxNode): boolean {
+  let found = false;
+  walkTree(node, (n) => {
+    if (n.type === 'member_expression' || n.type === 'subscript_expression') found = true;
+  });
+  return found;
+}
+
+function catchBlockOnlyRethrows(catchClause: Parser.SyntaxNode): boolean {
+  const body = catchClause.childForFieldName('body');
+  if (!body) return false;
+
+  const statements = body.namedChildren;
+  if (statements.length !== 1) return false;
+
+  const stmt = statements[0];
+  if (stmt.type !== 'throw_statement') return false;
+
+  const thrown = stmt.namedChildren[0];
+  if (!thrown) return false;
+
+  const catchParam = catchClause.childForFieldName('parameter');
+  if (!catchParam) return false;
+
+  return thrown.text === catchParam.text;
+}
+
+export const unnecessaryTryCatch: Rule = {
+  name: 'unnecessary-try-catch',
+  description: 'Flags try-catch blocks that wrap code unlikely to throw',
+  severity: 'warning',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const tryStatements = findNodes(tree.rootNode, 'try_statement');
+
+    for (const tryNode of tryStatements) {
+      const body = tryNode.childForFieldName('body');
+      const handler = tryNode.childForFieldName('handler');
+      if (!body || !handler) continue;
+
+      // If catch block only rethrows, that's always useless
+      if (catchBlockOnlyRethrows(handler)) {
+        findings.push({
+          file: filePath,
+          line: tryNode.startPosition.row + 1,
+          column: tryNode.startPosition.column + 1,
+          endLine: tryNode.endPosition.row + 1,
+          endColumn: tryNode.endPosition.column + 1,
+          rule: 'unnecessary-try-catch',
+          severity: 'warning',
+          message: 'try-catch block catches an error only to rethrow it unchanged',
+        });
+        continue;
+      }
+
+      // Skip if the try body contains await (async operations can throw)
+      if (isAwaitExpression(body)) continue;
+
+      // Skip if try body contains throw statements
+      if (containsThrowStatement(body)) continue;
+
+      // Skip if try body contains function calls (they might throw)
+      if (containsFunctionCall(body)) continue;
+
+      // Skip if try body contains property access (might throw on null/undefined)
+      if (isPropertyAccess(body)) continue;
+
+      // If we get here, the try body only contains assignments, returns of
+      // literals/variables, or other purely synchronous non-throwing ops
+      findings.push({
+        file: filePath,
+        line: tryNode.startPosition.row + 1,
+        column: tryNode.startPosition.column + 1,
+        endLine: tryNode.endPosition.row + 1,
+        endColumn: tryNode.endPosition.column + 1,
+        rule: 'unnecessary-try-catch',
+        severity: 'warning',
+        message: 'try-catch wraps code that is unlikely to throw — consider removing the try-catch',
+      });
+    }
+
+    return findings;
+  },
+};