distyll 0.1.0

package/src/rules/excessive-comments.ts

@@ -0,0 +1,94 @@
+import type Parser from 'tree-sitter';
+import type { Finding, Rule } from '../types';
+
+const COMMENT_DENSITY_THRESHOLD = 0.5; // >50% of lines have trailing comments
+const MIN_LINES_TO_CHECK = 10; // Don't flag very short files
+
+export const excessiveComments: Rule = {
+  name: 'excessive-comments',
+  description: 'Flags files or functions with excessive inline comment density (>50% of lines)',
+  severity: 'info',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const lines = source.split('\n');
+
+    if (lines.length < MIN_LINES_TO_CHECK) return findings;
+
+    // Count lines that have trailing inline comments (not standalone comment lines)
+    let codeLines = 0;
+    let trailingCommentLines = 0;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+
+      // Skip standalone comment lines — those are fine
+      if (trimmed.startsWith('//') || trimmed.startsWith('#') || trimmed.startsWith('/*') || trimmed.startsWith('*')) {
+        continue;
+      }
+
+      codeLines++;
+
+      // Check for trailing comments on code lines
+      // This is a heuristic — we look for // or # after code content
+      // Being careful to not match // inside strings
+      if (hasTrailingComment(trimmed)) {
+        trailingCommentLines++;
+      }
+    }
+
+    if (codeLines < MIN_LINES_TO_CHECK) return findings;
+
+    const density = trailingCommentLines / codeLines;
+    if (density > COMMENT_DENSITY_THRESHOLD) {
+      findings.push({
+        file: filePath,
+        line: 1,
+        column: 1,
+        endLine: lines.length,
+        endColumn: 1,
+        rule: 'excessive-comments',
+        severity: 'info',
+        message: `${Math.round(density * 100)}% of code lines have trailing comments (${trailingCommentLines}/${codeLines}) — high comment density is a common AI code pattern`,
+      });
+    }
+
+    return findings;
+  },
+};
+
+function hasTrailingComment(line: string): boolean {
+  // Simple heuristic: look for // or # that's not inside a string
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let inTemplate = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    const prev = i > 0 ? line[i - 1] : '';
+
+    if (prev === '\\') continue;
+
+    if (ch === "'" && !inDoubleQuote && !inTemplate) inSingleQuote = !inSingleQuote;
+    if (ch === '"' && !inSingleQuote && !inTemplate) inDoubleQuote = !inDoubleQuote;
+    if (ch === '`' && !inSingleQuote && !inDoubleQuote) inTemplate = !inTemplate;
+
+    if (inSingleQuote || inDoubleQuote || inTemplate) continue;
+
+    // JS/TS trailing comment
+    if (ch === '/' && i + 1 < line.length && line[i + 1] === '/') {
+      // Make sure there's actual code before the comment
+      const before = line.slice(0, i).trim();
+      if (before.length > 0) return true;
+    }
+
+    // Python trailing comment
+    if (ch === '#') {
+      const before = line.slice(0, i).trim();
+      if (before.length > 0) return true;
+    }
+  }
+
+  return false;
+}

package/src/rules/hallucinated-imports.ts

@@ -0,0 +1,195 @@
+import type Parser from 'tree-sitter';
+import * as fs from 'fs';
+import * as path from 'path';
+import { findNodes, walkTree } from '../parser';
+import { getStdlibModules, isJSLike, isPython } from '../languages';
+import type { Finding, Rule, Language } from '../types';
+
+function getJSImportSources(tree: Parser.Tree): Array<{ source: string; node: Parser.SyntaxNode }> {
+  const imports: Array<{ source: string; node: Parser.SyntaxNode }> = [];
+  const importStmts = findNodes(tree.rootNode, 'import_statement');
+
+  for (const stmt of importStmts) {
+    walkTree(stmt, (node) => {
+      if (node.type === 'string' && node.parent?.type === 'import_statement') {
+        const source = node.text.replace(/['"]/g, '');
+        imports.push({ source, node: stmt });
+      }
+    });
+  }
+
+  // Also check require() calls
+  const callNodes = findNodes(tree.rootNode, 'call_expression');
+  for (const call of callNodes) {
+    const fn = call.childForFieldName('function');
+    if (fn?.text === 'require' && call.childForFieldName('arguments')) {
+      const args = call.childForFieldName('arguments');
+      if (args && args.namedChildren.length === 1) {
+        const arg = args.namedChildren[0];
+        if (arg.type === 'string') {
+          const source = arg.text.replace(/['"]/g, '');
+          imports.push({ source, node: call });
+        }
+      }
+    }
+  }
+
+  return imports;
+}
+
+function getPythonImportModules(tree: Parser.Tree): Array<{ source: string; node: Parser.SyntaxNode }> {
+  const imports: Array<{ source: string; node: Parser.SyntaxNode }> = [];
+
+  // import foo / import foo.bar
+  const importStmts = findNodes(tree.rootNode, 'import_statement');
+  for (const stmt of importStmts) {
+    walkTree(stmt, (node) => {
+      if (node.type === 'dotted_name' && node.parent?.type === 'import_statement') {
+        // Get just the top-level module name
+        const fullName = node.text;
+        const topLevel = fullName.split('.')[0];
+        imports.push({ source: topLevel, node: stmt });
+      }
+    });
+  }
+
+  // from foo import bar / from foo.bar import baz
+  const fromStmts = findNodes(tree.rootNode, 'import_from_statement');
+  for (const stmt of fromStmts) {
+    walkTree(stmt, (node) => {
+      if (node.type === 'dotted_name' && node.parent?.type === 'import_from_statement') {
+        // Only get the module name (first dotted_name child, not imported names)
+        const isModuleName = !node.previousNamedSibling || node.previousNamedSibling.type !== 'dotted_name';
+        if (isModuleName) {
+          const topLevel = node.text.split('.')[0];
+          imports.push({ source: topLevel, node: stmt });
+        }
+      }
+      // relative imports like `from .foo import bar` are always local — skip
+      if (node.type === 'relative_import') {
+        // Mark as safe — no push
+      }
+    });
+  }
+
+  return imports;
+}
+
+function isRelativeImport(source: string): boolean {
+  return source.startsWith('.') || source.startsWith('/');
+}
+
+function isNodeModuleInstalled(source: string, filePath: string): boolean {
+  // Check node_modules from the file's directory up
+  const pkgName = source.startsWith('@') ? source.split('/').slice(0, 2).join('/') : source.split('/')[0];
+  let dir = path.dirname(filePath);
+  for (let i = 0; i < 50; i++) {
+    const candidate = path.join(dir, 'node_modules', pkgName);
+    if (fs.existsSync(candidate)) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return false;
+}
+
+function resolveJSImport(source: string, filePath: string, language: Language): boolean {
+  // Relative imports — check if file exists
+  if (isRelativeImport(source)) {
+    const dir = path.dirname(filePath);
+    const extensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json', ''];
+    for (const ext of extensions) {
+      if (fs.existsSync(path.join(dir, source + ext))) return true;
+      if (fs.existsSync(path.join(dir, source, 'index' + ext))) return true;
+    }
+    return false;
+  }
+
+  const stdlib = getStdlibModules(language);
+  if (stdlib.has(source)) return true;
+  if (isNodeModuleInstalled(source, filePath)) return true;
+
+  return false;
+}
+
+function resolvePythonImport(source: string, filePath: string): boolean {
+  const stdlib = getStdlibModules('python');
+  if (stdlib.has(source)) return true;
+
+  // Check if it's a local file/package in the project
+  const dir = path.dirname(filePath);
+  if (fs.existsSync(path.join(dir, source + '.py'))) return true;
+  if (fs.existsSync(path.join(dir, source)) && fs.existsSync(path.join(dir, source, '__init__.py'))) return true;
+
+  // Check parent directories for the module (common in Python projects)
+  let searchDir = path.dirname(dir);
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(searchDir, source + '.py'))) return true;
+    if (fs.existsSync(path.join(searchDir, source, '__init__.py'))) return true;
+    const parent = path.dirname(searchDir);
+    if (parent === searchDir) break;
+    searchDir = parent;
+  }
+
+  // Can't definitively say it's hallucinated — might be an installed package
+  // Be conservative: only flag if it looks like a plausible hallucination
+  return true; // Default to "resolved" to avoid false positives
+}
+
+export const hallucinatedImports: Rule = {
+  name: 'hallucinated-imports',
+  description: 'Flags imports of modules that do not exist in the project or known standard libraries',
+  severity: 'error',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const language = detectLang(filePath);
+    if (!language) return findings;
+
+    if (isJSLike(language)) {
+      const imports = getJSImportSources(tree);
+      for (const { source: src, node } of imports) {
+        if (!src) continue;
+        if (!resolveJSImport(src, filePath, language)) {
+          findings.push({
+            file: filePath,
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column + 1,
+            endLine: node.endPosition.row + 1,
+            endColumn: node.endPosition.column + 1,
+            rule: 'hallucinated-imports',
+            severity: 'error',
+            message: `Import '${src}' could not be resolved — module not found in project or node_modules`,
+          });
+        }
+      }
+    } else if (isPython(language)) {
+      const imports = getPythonImportModules(tree);
+      for (const { source: src, node } of imports) {
+        if (!src) continue;
+        if (!resolvePythonImport(src, filePath)) {
+          findings.push({
+            file: filePath,
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column + 1,
+            endLine: node.endPosition.row + 1,
+            endColumn: node.endPosition.column + 1,
+            rule: 'hallucinated-imports',
+            severity: 'error',
+            message: `Import '${src}' could not be resolved — module not found in project or standard library`,
+          });
+        }
+      }
+    }
+
+    return findings;
+  },
+};
+
+function detectLang(filePath: string): Language | null {
+  if (filePath.endsWith('.tsx')) return 'tsx';
+  if (filePath.endsWith('.ts')) return 'typescript';
+  if (filePath.endsWith('.js') || filePath.endsWith('.jsx') || filePath.endsWith('.mjs') || filePath.endsWith('.cjs')) return 'javascript';
+  if (filePath.endsWith('.py') || filePath.endsWith('.pyi')) return 'python';
+  return null;
+}

package/src/rules/index.ts

@@ -0,0 +1,32 @@
+import type { Rule } from '../types';
+import { unnecessaryTryCatch } from './unnecessary-try-catch';
+import { singleUseWrapper } from './single-use-wrapper';
+import { verboseComments } from './verbose-comments';
+import { unusedImports } from './unused-imports';
+import { singleOptionObject } from './single-option-object';
+import { redundantElseReturn } from './redundant-else-return';
+import { hallucinatedImports } from './hallucinated-imports';
+import { nearDuplicateFunctions } from './near-duplicate-functions';
+import { overDefensiveNulls } from './over-defensive-nulls';
+import { magicValues } from './magic-values';
+import { deadCodePaths } from './dead-code-paths';
+import { excessiveComments } from './excessive-comments';
+
+export const allRules: Rule[] = [
+  unnecessaryTryCatch,
+  singleUseWrapper,
+  verboseComments,
+  unusedImports,
+  singleOptionObject,
+  redundantElseReturn,
+  hallucinatedImports,
+  nearDuplicateFunctions,
+  overDefensiveNulls,
+  magicValues,
+  deadCodePaths,
+  excessiveComments,
+];
+
+export function getRuleByName(name: string): Rule | undefined {
+  return allRules.find((r) => r.name === name);
+}

package/src/rules/magic-values.ts

@@ -0,0 +1,167 @@
+import type Parser from 'tree-sitter';
+import { walkTree } from '../parser';
+import type { Finding, Rule } from '../types';
+
+// Well-known constants that are NOT magic values — exempted to avoid false positives
+const EXEMPT_NUMBERS = new Set([
+  '0', '1', '-1', '2', '0.5',
+  // HTTP status codes
+  '200', '201', '204', '301', '302', '304', '400', '401', '403', '404', '405', '409', '422', '429', '500', '502', '503', '504',
+  // Common bit/byte values
+  '8', '16', '32', '64', '128', '256', '512', '1024',
+  // Time
+  '24', '60', '100', '1000', '3600',
+]);
+
+const EXEMPT_STRINGS = new Set([
+  '', 'utf-8', 'utf8', 'ascii', 'base64', 'hex', 'binary',
+  'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',
+  'Content-Type', 'Authorization', 'Accept',
+  'application/json', 'text/html', 'text/plain', 'multipart/form-data',
+  'true', 'false', 'null', 'undefined',
+  'development', 'production', 'test', 'staging',
+  'click', 'change', 'submit', 'input', 'keydown', 'keyup',
+  'div', 'span', 'p', 'a', 'button', 'input', 'form',
+]);
+
+const MIN_MAGIC_STRING_LENGTH = 2;
+const MAX_MAGIC_STRING_LENGTH = 50;
+
+function isInConstDeclaration(node: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node;
+  while (current) {
+    // JS/TS: const x = value
+    if (current.type === 'lexical_declaration') {
+      const keyword = current.children[0];
+      if (keyword?.text === 'const') return true;
+    }
+    // Python: UPPER_CASE = value (convention)
+    if (current.type === 'assignment') {
+      const left = current.childForFieldName('left');
+      if (left && /^[A-Z_][A-Z0-9_]*$/.test(left.text)) return true;
+    }
+    // Enum members
+    if (current.type === 'enum_declaration' || current.type === 'enum_body') return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+function isInImportOrExport(node: Parser.SyntaxNode): boolean {
+  let current: Parser.SyntaxNode | null = node;
+  while (current) {
+    if (current.type === 'import_statement' || current.type === 'import_from_statement' ||
+        current.type === 'export_statement') return true;
+    current = current.parent;
+  }
+  return false;
+}
+
+function isObjectKey(node: Parser.SyntaxNode): boolean {
+  if (!node.parent) return false;
+  // String used as object key: { "key": value }
+  if (node.parent.type === 'pair') {
+    const key = node.parent.childForFieldName('key');
+    return key === node;
+  }
+  return false;
+}
+
+function isInComparison(node: Parser.SyntaxNode): boolean {
+  return node.parent?.type === 'binary_expression' || node.parent?.type === 'comparison_operator';
+}
+
+function isReturnValue(node: Parser.SyntaxNode): boolean {
+  return node.parent?.type === 'return_statement';
+}
+
+function isDefaultParam(node: Parser.SyntaxNode): boolean {
+  return node.parent?.type === 'assignment_pattern' || node.parent?.type === 'default_parameter';
+}
+
+function countOccurrences(root: Parser.SyntaxNode, value: string, type: string): number {
+  let count = 0;
+  walkTree(root, (node) => {
+    if (node.type === type && node.text === value) count++;
+  });
+  return count;
+}
+
+export const magicValues: Rule = {
+  name: 'magic-values',
+  description: 'Flags magic numbers and strings that should be named constants',
+  severity: 'info',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const seen = new Set<string>();
+
+    walkTree(tree.rootNode, (node) => {
+      // Magic numbers
+      if (node.type === 'number' || node.type === 'integer' || node.type === 'float') {
+        const value = node.text;
+        if (EXEMPT_NUMBERS.has(value)) return;
+        if (isInConstDeclaration(node)) return;
+        if (isInImportOrExport(node)) return;
+        if (isDefaultParam(node)) return;
+        if (isReturnValue(node)) return;
+
+        // Only flag if the same magic number appears 3+ times
+        const key = `num:${value}`;
+        if (seen.has(key)) return;
+
+        const count = countOccurrences(tree.rootNode, value, node.type);
+        if (count >= 3) {
+          seen.add(key);
+          findings.push({
+            file: filePath,
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column + 1,
+            endLine: node.endPosition.row + 1,
+            endColumn: node.endPosition.column + 1,
+            rule: 'magic-values',
+            severity: 'info',
+            message: `Magic number ${value} appears ${count} times — consider extracting to a named constant`,
+          });
+        }
+      }
+
+      // Magic strings
+      if (node.type === 'string' || node.type === 'string_fragment') {
+        // Get the actual string content (strip quotes)
+        let value = node.text;
+        if (node.type === 'string') {
+          value = value.slice(1, -1);
+        }
+
+        if (value.length < MIN_MAGIC_STRING_LENGTH || value.length > MAX_MAGIC_STRING_LENGTH) return;
+        if (EXEMPT_STRINGS.has(value)) return;
+        if (isInConstDeclaration(node)) return;
+        if (isInImportOrExport(node)) return;
+        if (isObjectKey(node)) return;
+        if (isDefaultParam(node)) return;
+
+        // Only flag strings that appear 3+ times
+        const key = `str:${value}`;
+        if (seen.has(key)) return;
+
+        const count = countOccurrences(tree.rootNode, node.text, node.type);
+        if (count >= 3) {
+          seen.add(key);
+          findings.push({
+            file: filePath,
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column + 1,
+            endLine: node.endPosition.row + 1,
+            endColumn: node.endPosition.column + 1,
+            rule: 'magic-values',
+            severity: 'info',
+            message: `Magic string "${value}" appears ${count} times — consider extracting to a named constant`,
+          });
+        }
+      }
+    });
+
+    return findings;
+  },
+};

package/src/rules/near-duplicate-functions.ts

@@ -0,0 +1,89 @@
+import type Parser from 'tree-sitter';
+import { compareTwoStrings } from 'string-similarity';
+import { findNodesMulti } from '../parser';
+import type { Finding, Rule } from '../types';
+
+const FUNCTION_NODE_TYPES = [
+  'function_declaration',
+  'method_definition',
+  'arrow_function',
+  'function',
+  // Python
+  'function_definition',
+];
+
+const MIN_BODY_LENGTH = 40; // Ignore very short function bodies
+const SIMILARITY_THRESHOLD = 0.85;
+
+function getFunctionName(node: Parser.SyntaxNode): string {
+  const nameNode = node.childForFieldName('name');
+  if (nameNode) return nameNode.text;
+
+  // Arrow functions assigned to variables: const foo = () => ...
+  if (node.type === 'arrow_function' && node.parent?.type === 'variable_declarator') {
+    const varName = node.parent.childForFieldName('name');
+    if (varName) return varName.text;
+  }
+
+  return '<anonymous>';
+}
+
+function getFunctionBody(node: Parser.SyntaxNode): string | null {
+  const body = node.childForFieldName('body');
+  if (!body) return null;
+  return body.text;
+}
+
+interface FunctionInfo {
+  name: string;
+  body: string;
+  node: Parser.SyntaxNode;
+}
+
+export const nearDuplicateFunctions: Rule = {
+  name: 'near-duplicate-functions',
+  description: 'Flags functions with near-identical bodies that suggest copy-paste with subtle variations',
+  severity: 'warning',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const funcNodes = findNodesMulti(tree.rootNode, FUNCTION_NODE_TYPES);
+
+    const functions: FunctionInfo[] = [];
+    for (const node of funcNodes) {
+      const body = getFunctionBody(node);
+      if (!body || body.length < MIN_BODY_LENGTH) continue;
+      functions.push({
+        name: getFunctionName(node),
+        body,
+        node,
+      });
+    }
+
+    // Compare all pairs — O(n^2) but function counts per file are small
+    const flagged = new Set<number>();
+    for (let i = 0; i < functions.length; i++) {
+      for (let j = i + 1; j < functions.length; j++) {
+        if (flagged.has(j)) continue;
+
+        const sim = compareTwoStrings(functions[i].body, functions[j].body);
+        if (sim >= SIMILARITY_THRESHOLD) {
+          flagged.add(j);
+          const nodeJ = functions[j].node;
+          findings.push({
+            file: filePath,
+            line: nodeJ.startPosition.row + 1,
+            column: nodeJ.startPosition.column + 1,
+            endLine: nodeJ.endPosition.row + 1,
+            endColumn: nodeJ.endPosition.column + 1,
+            rule: 'near-duplicate-functions',
+            severity: 'warning',
+            message: `Function '${functions[j].name}' is ${Math.round(sim * 100)}% similar to '${functions[i].name}' (line ${functions[i].node.startPosition.row + 1}) — consider extracting shared logic`,
+          });
+        }
+      }
+    }
+
+    return findings;
+  },
+};