distyll 0.1.0

package/src/errors.ts

@@ -0,0 +1,105 @@
+import * as fs from 'fs';
+
+export class DistyllError extends Error {
+  constructor(
+    message: string,
+    public readonly hint?: string
+  ) {
+    super(message);
+    this.name = 'DistyllError';
+  }
+}
+
+export class NotAGitRepoError extends DistyllError {
+  constructor() {
+    super(
+      'Not a git repository.',
+      'Run this command from inside a git repo, or use "distyll scan" instead.'
+    );
+    this.name = 'NotAGitRepoError';
+  }
+}
+
+export class UnsupportedLanguageError extends DistyllError {
+  constructor(filePath: string) {
+    super(
+      `Unsupported language for file: ${filePath}`,
+      'Distyll currently supports JavaScript, TypeScript, and Python files.'
+    );
+    this.name = 'UnsupportedLanguageError';
+  }
+}
+
+export class FileAccessError extends DistyllError {
+  constructor(filePath: string, reason: string) {
+    super(
+      `Cannot read file: ${filePath} (${reason})`,
+      'Check file permissions and ensure the file exists.'
+    );
+    this.name = 'FileAccessError';
+  }
+}
+
+/**
+ * Check if a buffer contains binary content (null bytes in first 1024 bytes).
+ */
+export function isBinaryBuffer(buffer: Buffer): boolean {
+  const checkLength = Math.min(buffer.length, 1024);
+  for (let i = 0; i < checkLength; i++) {
+    if (buffer[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Safely read a source file, returning null for binary/empty/inaccessible files.
+ * When verbose is true, logs skip reasons to stderr.
+ */
+export function safeReadFile(
+  filePath: string,
+  verbose = false
+): { source: string; buffer: Buffer } | null {
+  let buffer: Buffer;
+  try {
+    buffer = fs.readFileSync(filePath);
+  } catch (err) {
+    if (verbose) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'EACCES') {
+        console.error(`  [skip] ${filePath}: permission denied`);
+      } else if (code === 'ENOENT') {
+        console.error(`  [skip] ${filePath}: file not found`);
+      } else {
+        console.error(`  [skip] ${filePath}: ${(err as Error).message}`);
+      }
+    }
+    return null;
+  }
+
+  if (buffer.length === 0) {
+    if (verbose) console.error(`  [skip] ${filePath}: empty file`);
+    return null;
+  }
+
+  if (isBinaryBuffer(buffer)) {
+    if (verbose) console.error(`  [skip] ${filePath}: binary file`);
+    return null;
+  }
+
+  return { source: buffer.toString('utf-8'), buffer };
+}
+
+/**
+ * Format an error for user-facing display.
+ */
+export function formatError(err: unknown): string {
+  if (err instanceof DistyllError) {
+    let msg = `Error: ${err.message}`;
+    if (err.hint) msg += `\nHint: ${err.hint}`;
+    return msg;
+  }
+  if (err instanceof Error) {
+    return `Error: ${err.message}`;
+  }
+  return `Error: ${String(err)}`;
+}

package/src/fingerprint/analyzer.ts

@@ -0,0 +1,214 @@
+import type Parser from 'tree-sitter';
+import { parse, detectLanguage, walkTree, findNodes } from '../parser';
+import { resolveFiles } from '../scanner';
+import type { StyleProfile, Language } from '../types';
+import * as fs from 'fs';
+
+interface FileMetrics {
+  functionLengths: number[];
+  identifierNames: string[];
+  commentLines: number;
+  codeLines: number;
+  nestingDepths: number[];
+  tryCatchCount: number;
+  importCount: number;
+  loc: number;
+}
+
+function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') count++;
+  }
+  return count;
+}
+
+function getNestingDepth(node: Parser.SyntaxNode): number {
+  let depth = 0;
+  let current: Parser.SyntaxNode | null = node.parent;
+  const blockTypes = new Set([
+    'statement_block', 'block', 'if_statement', 'for_statement',
+    'while_statement', 'for_in_statement', 'switch_statement',
+    'try_statement', 'with_statement',
+  ]);
+  while (current) {
+    if (blockTypes.has(current.type)) depth++;
+    current = current.parent;
+  }
+  return depth;
+}
+
+const FUNCTION_TYPES = new Set([
+  'function_declaration', 'method_definition', 'arrow_function',
+  'function', 'function_definition',
+]);
+
+const IMPORT_TYPES = new Set([
+  'import_statement', 'import_declaration',
+  'import_from_statement',
+]);
+
+function classifyName(name: string): 'camelCase' | 'snake_case' | 'PascalCase' | 'other' {
+  if (/^[A-Z][a-zA-Z0-9]*$/.test(name)) return 'PascalCase';
+  if (/^[a-z][a-zA-Z0-9]*$/.test(name) && /[A-Z]/.test(name)) return 'camelCase';
+  if (/^[a-z][a-z0-9_]*$/.test(name) && name.includes('_')) return 'snake_case';
+  if (/^[a-z][a-z0-9]*$/.test(name)) return 'camelCase'; // single-word lowercase defaults to camelCase
+  return 'other';
+}
+
+function analyzeFileAST(tree: Parser.Tree, source: string): FileMetrics {
+  const metrics: FileMetrics = {
+    functionLengths: [],
+    identifierNames: [],
+    commentLines: 0,
+    codeLines: 0,
+    nestingDepths: [],
+    tryCatchCount: 0,
+    importCount: 0,
+    loc: countLines(source),
+  };
+
+  walkTree(tree.rootNode, (node) => {
+    // Function lengths
+    if (FUNCTION_TYPES.has(node.type)) {
+      const body = node.childForFieldName('body');
+      if (body) {
+        const fnLines = countLines(body.text);
+        metrics.functionLengths.push(fnLines);
+        metrics.nestingDepths.push(getNestingDepth(body));
+      }
+    }
+
+    // Identifier names (function declarations and variable declarations)
+    if (node.type === 'function_declaration' || node.type === 'function_definition') {
+      const nameNode = node.childForFieldName('name');
+      if (nameNode) metrics.identifierNames.push(nameNode.text);
+    }
+    if (node.type === 'variable_declarator') {
+      const nameNode = node.childForFieldName('name');
+      if (nameNode && nameNode.type === 'identifier') {
+        metrics.identifierNames.push(nameNode.text);
+      }
+    }
+
+    // Comments
+    if (node.type === 'comment') {
+      metrics.commentLines += countLines(node.text);
+    }
+
+    // Try-catch
+    if (node.type === 'try_statement') {
+      metrics.tryCatchCount++;
+    }
+
+    // Imports
+    if (IMPORT_TYPES.has(node.type)) {
+      metrics.importCount++;
+    }
+  });
+
+  // Code lines = total lines minus comment lines (rough estimate)
+  metrics.codeLines = Math.max(1, metrics.loc - metrics.commentLines);
+
+  return metrics;
+}
+
+function median(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) {
+    return (sorted[mid - 1] + sorted[mid]) / 2;
+  }
+  return sorted[mid];
+}
+
+function average(values: number[]): number {
+  if (values.length === 0) return 0;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+export async function analyzeCodebase(paths: string[]): Promise<StyleProfile> {
+  const files = await resolveFiles(paths);
+  const allMetrics: FileMetrics[] = [];
+
+  for (const filePath of files) {
+    const language = detectLanguage(filePath);
+    if (!language) continue;
+
+    let source: string;
+    try {
+      const buffer = fs.readFileSync(filePath);
+      if (buffer.length === 0) continue;
+      // Skip binary files
+      const checkLength = Math.min(buffer.length, 1024);
+      let isBinary = false;
+      for (let i = 0; i < checkLength; i++) {
+        if (buffer[i] === 0) { isBinary = true; break; }
+      }
+      if (isBinary) continue;
+      source = buffer.toString('utf-8');
+    } catch {
+      continue;
+    }
+
+    let tree;
+    try {
+      tree = parse(source, language);
+    } catch {
+      continue;
+    }
+
+    allMetrics.push(analyzeFileAST(tree, source));
+  }
+
+  return buildProfile(allMetrics, files.length);
+}
+
+function buildProfile(allMetrics: FileMetrics[], fileCount: number): StyleProfile {
+  const allFunctionLengths = allMetrics.flatMap((m) => m.functionLengths);
+  const allIdentifiers = allMetrics.flatMap((m) => m.identifierNames);
+  const allNestingDepths = allMetrics.flatMap((m) => m.nestingDepths);
+
+  const totalCommentLines = allMetrics.reduce((s, m) => s + m.commentLines, 0);
+  const totalCodeLines = allMetrics.reduce((s, m) => s + m.codeLines, 0);
+  const totalTryCatch = allMetrics.reduce((s, m) => s + m.tryCatchCount, 0);
+  const totalLoc = allMetrics.reduce((s, m) => s + m.loc, 0);
+  const totalImports = allMetrics.reduce((s, m) => s + m.importCount, 0);
+
+  const namingConventions = { camelCase: 0, snake_case: 0, PascalCase: 0, other: 0 };
+  for (const name of allIdentifiers) {
+    const category = classifyName(name);
+    namingConventions[category]++;
+  }
+
+  // Normalize naming conventions to percentages
+  const totalNames = Math.max(1, allIdentifiers.length);
+  namingConventions.camelCase = Math.round((namingConventions.camelCase / totalNames) * 100);
+  namingConventions.snake_case = Math.round((namingConventions.snake_case / totalNames) * 100);
+  namingConventions.PascalCase = Math.round((namingConventions.PascalCase / totalNames) * 100);
+  namingConventions.other = Math.round((namingConventions.other / totalNames) * 100);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    fileCount,
+    totalLoc,
+    metrics: {
+      medianFunctionLength: Math.round(median(allFunctionLengths) * 10) / 10,
+      averageFunctionLength: Math.round(average(allFunctionLengths) * 10) / 10,
+      maxFunctionLength: allFunctionLengths.length > 0 ? Math.max(...allFunctionLengths) : 0,
+      namingConventions,
+      commentToCodeRatio: totalCodeLines > 0
+        ? Math.round((totalCommentLines / totalCodeLines) * 100) / 100
+        : 0,
+      averageNestingDepth: Math.round(average(allNestingDepths) * 10) / 10,
+      tryCatchDensity: totalLoc > 0
+        ? Math.round((totalTryCatch / (totalLoc / 100)) * 100) / 100
+        : 0,
+      averageImportsPerFile: fileCount > 0
+        ? Math.round((totalImports / fileCount) * 10) / 10
+        : 0,
+    },
+  };
+}

package/src/fingerprint/comparator.ts

@@ -0,0 +1,93 @@
+import type Parser from 'tree-sitter';
+import { parse, detectLanguage, walkTree } from '../parser';
+import type { Finding, StyleProfile, Language } from '../types';
+import * as fs from 'fs';
+
+const FUNCTION_TYPES = new Set([
+  'function_declaration', 'method_definition', 'arrow_function',
+  'function', 'function_definition',
+]);
+
+function countLines(text: string): number {
+  if (text.length === 0) return 0;
+  let count = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') count++;
+  }
+  return count;
+}
+
+export function compareFileToProfile(
+  filePath: string,
+  source: string,
+  tree: Parser.Tree,
+  profile: StyleProfile,
+): Finding[] {
+  const findings: Finding[] = [];
+  const { metrics } = profile;
+
+  // Check function lengths against profile
+  const maxAcceptable = Math.max(
+    metrics.averageFunctionLength * 4,
+    metrics.medianFunctionLength * 5,
+    30, // absolute minimum threshold
+  );
+
+  walkTree(tree.rootNode, (node) => {
+    if (!FUNCTION_TYPES.has(node.type)) return;
+
+    const body = node.childForFieldName('body');
+    if (!body) return;
+
+    const fnLines = countLines(body.text);
+
+    if (fnLines > maxAcceptable) {
+      const nameNode = node.childForFieldName('name');
+      let parentName: string | undefined;
+      if (!nameNode && node.parent?.type === 'variable_declarator') {
+        const pn = node.parent.childForFieldName('name');
+        if (pn) parentName = pn.text;
+      }
+      const name = nameNode?.text ?? parentName ?? 'anonymous';
+
+      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: 'style-function-length',
+        severity: 'warning',
+        message: `Function '${name}' is ${fnLines} lines — project median is ${metrics.medianFunctionLength}, average is ${metrics.averageFunctionLength}`,
+      });
+    }
+  });
+
+  // Check comment density against profile
+  let commentLines = 0;
+  let codeLines = 0;
+  walkTree(tree.rootNode, (node) => {
+    if (node.type === 'comment') {
+      commentLines += countLines(node.text);
+    }
+  });
+  const totalLines = countLines(source);
+  codeLines = Math.max(1, totalLines - commentLines);
+  const fileRatio = commentLines / codeLines;
+
+  // Flag if comment density is 3x+ the project average (overly commented, likely AI slop)
+  if (metrics.commentToCodeRatio > 0 && fileRatio > metrics.commentToCodeRatio * 3 && commentLines > 5) {
+    findings.push({
+      file: filePath,
+      line: 1,
+      column: 1,
+      endLine: 1,
+      endColumn: 1,
+      rule: 'style-comment-density',
+      severity: 'info',
+      message: `Comment density (${Math.round(fileRatio * 100)}%) is much higher than project average (${Math.round(metrics.commentToCodeRatio * 100)}%)`,
+    });
+  }
+
+  return findings;
+}

package/src/fingerprint/profile.ts

@@ -0,0 +1,32 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { StyleProfile } from '../types';
+
+const PROFILE_DIR = '.distyll';
+const PROFILE_FILE = 'profile.json';
+
+export function getProfilePath(baseDir: string): string {
+  return path.join(baseDir, PROFILE_DIR, PROFILE_FILE);
+}
+
+export function saveProfile(profile: StyleProfile, baseDir: string): string {
+  const dir = path.join(baseDir, PROFILE_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const filePath = getProfilePath(baseDir);
+  fs.writeFileSync(filePath, JSON.stringify(profile, null, 2) + '\n', 'utf-8');
+  return filePath;
+}
+
+export function loadProfile(baseDir: string): StyleProfile | null {
+  const filePath = getProfilePath(baseDir);
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !parsed.metrics) return null;
+    return parsed as StyleProfile;
+  } catch {
+    return null;
+  }
+}

package/src/fixes/index.ts

@@ -0,0 +1,58 @@
+import type Parser from 'tree-sitter';
+import type { Finding, FixSuggestion } from '../types';
+import { fixUnnecessaryTryCatch } from './unnecessary-try-catch';
+import { fixSingleUseWrapper } from './single-use-wrapper';
+import { fixVerboseComment } from './verbose-comments';
+import { fixUnusedImport } from './unused-imports';
+
+type FixGenerator = (
+  tree: Parser.Tree,
+  source: string,
+  line: number,
+  context?: string,
+) => FixSuggestion | null;
+
+const fixGenerators: Record<string, FixGenerator> = {
+  'unnecessary-try-catch': fixUnnecessaryTryCatch,
+  'single-use-wrapper': fixSingleUseWrapper,
+  'verbose-comments': fixVerboseComment,
+  'unused-imports': (tree, source, line, context) =>
+    fixUnusedImport(tree, source, line, context ?? ''),
+};
+
+/**
+ * Attempt to generate a fix suggestion for a finding.
+ * Returns the finding with the fix attached if successful.
+ */
+export function attachFix(
+  finding: Finding,
+  tree: Parser.Tree,
+  source: string,
+): Finding {
+  const generator = fixGenerators[finding.rule];
+  if (!generator) return finding;
+
+  // Extract context from the finding message for unused-imports
+  let context: string | undefined;
+  if (finding.rule === 'unused-imports') {
+    const match = finding.message.match(/'([^']+)'/);
+    if (match) context = match[1];
+  }
+
+  const fix = generator(tree, source, finding.line, context);
+  if (fix) {
+    return { ...finding, fix };
+  }
+  return finding;
+}
+
+/**
+ * Attach fix suggestions to all findings for a file.
+ */
+export function attachFixes(
+  findings: Finding[],
+  tree: Parser.Tree,
+  source: string,
+): Finding[] {
+  return findings.map((f) => attachFix(f, tree, source));
+}

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

@@ -0,0 +1,60 @@
+import type Parser from 'tree-sitter';
+import { findNodesMulti, walkTree } from '../parser';
+import type { FixSuggestion } from '../types';
+
+/**
+ * Generates a fix for single-use wrapper functions: suggests inlining
+ * by showing the delegated call directly.
+ */
+export function fixSingleUseWrapper(
+  tree: Parser.Tree,
+  source: string,
+  line: number,
+): FixSuggestion | null {
+  const functionNodes = findNodesMulti(tree.rootNode, [
+    'function_declaration',
+    'arrow_function',
+    'function',
+  ]);
+
+  for (const fn of functionNodes) {
+    if (fn.startPosition.row + 1 !== line) continue;
+
+    const body = fn.childForFieldName('body');
+    if (!body) return null;
+
+    // For arrow functions with expression body (no braces)
+    if (body.type === 'call_expression') {
+      return {
+        description: `Inline the delegated call: ${body.text}`,
+        replacement: body.text,
+      };
+    }
+
+    // For block body with single return/expression statement
+    const stmts = body.type === 'statement_block' ? body.namedChildren : [];
+    if (stmts.length !== 1) return null;
+
+    const stmt = stmts[0];
+    if (stmt.type === 'return_statement') {
+      const returnValue = stmt.namedChildren[0];
+      if (returnValue) {
+        return {
+          description: `Inline the delegated call: ${returnValue.text}`,
+          replacement: returnValue.text,
+        };
+      }
+    }
+    if (stmt.type === 'expression_statement') {
+      const expr = stmt.namedChildren[0];
+      if (expr) {
+        return {
+          description: `Inline the delegated call: ${expr.text}`,
+          replacement: expr.text,
+        };
+      }
+    }
+  }
+
+  return null;
+}

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

@@ -0,0 +1,43 @@
+import type Parser from 'tree-sitter';
+import { findNodes } from '../parser';
+import type { FixSuggestion } from '../types';
+
+/**
+ * Generates a fix for unnecessary try-catch: extracts the try body
+ * and removes the try-catch wrapper.
+ */
+export function fixUnnecessaryTryCatch(
+  tree: Parser.Tree,
+  source: string,
+  line: number,
+): FixSuggestion | null {
+  const tryStatements = findNodes(tree.rootNode, 'try_statement');
+
+  for (const tryNode of tryStatements) {
+    // Match by line (1-indexed)
+    if (tryNode.startPosition.row + 1 !== line) continue;
+
+    const body = tryNode.childForFieldName('body');
+    if (!body) return null;
+
+    // Extract the body statements (strip the outer braces)
+    const bodyText = body.text;
+    // Remove leading { and trailing }
+    const inner = bodyText.replace(/^\s*\{/, '').replace(/\}\s*$/, '');
+    // Dedent one level
+    const lines = inner.split('\n');
+    const dedented = lines
+      .map((l) => l.replace(/^  /, ''))
+      .join('\n')
+      .trim();
+
+    if (!dedented) return null;
+
+    return {
+      description: 'Remove try-catch wrapper and keep the body',
+      replacement: dedented,
+    };
+  }
+
+  return null;
+}

package/src/fixes/unused-imports.ts

@@ -0,0 +1,53 @@
+import type Parser from 'tree-sitter';
+import { findNodes } from '../parser';
+import type { FixSuggestion } from '../types';
+
+/**
+ * Generates a fix for unused imports: suggests removing the import line.
+ */
+export function fixUnusedImport(
+  tree: Parser.Tree,
+  source: string,
+  line: number,
+  importName: string,
+): FixSuggestion | null {
+  const importStatements = findNodes(tree.rootNode, 'import_statement');
+
+  for (const importStmt of importStatements) {
+    // Check if this import statement contains the line
+    const stmtStartLine = importStmt.startPosition.row + 1;
+    const stmtEndLine = importStmt.endPosition.row + 1;
+    if (line < stmtStartLine || line > stmtEndLine) continue;
+
+    // Count how many named imports are in this statement
+    const importClause = importStmt.children.find((c) => c.type === 'import_clause');
+    if (!importClause) continue;
+
+    const namedImports = importClause.descendantsOfType('import_specifier');
+    const defaultImport = importClause.children.find(
+      (c) => c.type === 'identifier'
+    );
+    const namespaceImport = importClause.descendantsOfType('namespace_import');
+
+    const totalImportedNames =
+      namedImports.length +
+      (defaultImport ? 1 : 0) +
+      namespaceImport.length;
+
+    if (totalImportedNames <= 1) {
+      // Only one import in this statement — remove the entire line
+      return {
+        description: `Remove unused import '${importName}'`,
+        replacement: '', // delete entire import statement
+      };
+    }
+
+    // Multiple imports — suggest removing just this specifier
+    return {
+      description: `Remove unused import '${importName}' from this import statement`,
+      replacement: `Remove '${importName}' from the import list`,
+    };
+  }
+
+  return null;
+}

package/src/fixes/verbose-comments.ts

@@ -0,0 +1,35 @@
+import type Parser from 'tree-sitter';
+import { findNodes } from '../parser';
+import type { FixSuggestion } from '../types';
+
+/**
+ * Generates a fix for verbose comments: suggests removing the comment entirely.
+ */
+export function fixVerboseComment(
+  tree: Parser.Tree,
+  source: string,
+  line: number,
+): FixSuggestion | null {
+  const comments = findNodes(tree.rootNode, 'comment');
+
+  for (const comment of comments) {
+    if (comment.startPosition.row + 1 !== line) continue;
+
+    // Provide the code without the comment
+    const lines = source.split('\n');
+    const result = lines
+      .filter((_, i) => {
+        const lineNum = i + 1;
+        return lineNum < comment.startPosition.row + 1 ||
+               lineNum > comment.endPosition.row + 1;
+      });
+
+    // Just suggest removal
+    return {
+      description: 'Remove this comment — it restates the code',
+      replacement: '', // empty = delete
+    };
+  }
+
+  return null;
+}