distyll 0.1.0

package/src/formatter.ts

@@ -0,0 +1,79 @@
+import chalk from 'chalk';
+import type { ScanSummary, Finding, Severity } from './types';
+
+const SEVERITY_COLORS: Record<Severity, (s: string) => string> = {
+  info: chalk.blue,
+  warning: chalk.yellow,
+  error: chalk.red,
+};
+
+const SEVERITY_ICONS: Record<Severity, string> = {
+  info: 'i',
+  warning: '!',
+  error: 'x',
+};
+
+function formatFinding(finding: Finding): string {
+  const color = SEVERITY_COLORS[finding.severity];
+  const icon = SEVERITY_ICONS[finding.severity];
+  const location = chalk.gray(`${finding.file}:${finding.line}:${finding.column}`);
+  const rule = chalk.gray(`(${finding.rule})`);
+  let line = `  ${color(icon)} ${location} ${finding.message} ${rule}`;
+  if (finding.fix) {
+    line += `\n    ${chalk.cyan('Fix:')} ${finding.fix.description}`;
+  }
+  return line;
+}
+
+export function formatText(summary: ScanSummary): string {
+  const lines: string[] = [];
+
+  for (const result of summary.results) {
+    if (result.findings.length === 0) continue;
+    lines.push('');
+    lines.push(chalk.underline(result.file));
+    for (const finding of result.findings) {
+      lines.push(formatFinding(finding));
+    }
+  }
+
+  lines.push('');
+  lines.push(formatScoreLine(summary.score));
+  lines.push(
+    chalk.gray(
+      `${summary.totalFindings} finding${summary.totalFindings === 1 ? '' : 's'} across ${summary.results.length} file${summary.results.length === 1 ? '' : 's'}`
+    )
+  );
+
+  return lines.join('\n');
+}
+
+function formatScoreLine(score: number): string {
+  const label = 'Slop Score';
+  if (score <= 20) return chalk.green(`${label}: ${score}/100 - Clean`);
+  if (score <= 50) return chalk.yellow(`${label}: ${score}/100 - Moderate`);
+  return chalk.red(`${label}: ${score}/100 - High`);
+}
+
+export function formatJson(summary: ScanSummary): string {
+  return JSON.stringify(
+    {
+      score: summary.score,
+      totalFindings: summary.totalFindings,
+      files: summary.results.map((r) => ({
+        file: r.file,
+        loc: r.loc,
+        findings: r.findings.map((f) => ({
+          line: f.line,
+          column: f.column,
+          rule: f.rule,
+          severity: f.severity,
+          message: f.message,
+          ...(f.fix ? { fix: { description: f.fix.description, replacement: f.fix.replacement } } : {}),
+        })),
+      })),
+    },
+    null,
+    2
+  );
+}

package/src/git.ts

@@ -0,0 +1,115 @@
+import simpleGit, { SimpleGit } from 'simple-git';
+import * as path from 'path';
+
+export interface DiffHunk {
+  file: string;
+  addedLines: number[];
+}
+
+export interface GitContext {
+  git: SimpleGit;
+  root: string;
+}
+
+export async function getGitContext(cwd?: string): Promise<GitContext> {
+  const git = simpleGit(cwd ?? process.cwd());
+
+  let root: string;
+  try {
+    root = (await git.revparse(['--show-toplevel'])).trim();
+  } catch {
+    throw new Error(
+      'Not a git repository. Run this command from inside a git repo, or use "distyll scan" instead.'
+    );
+  }
+
+  return { git, root };
+}
+
+export async function getDiffFiles(
+  ctx: GitContext,
+  options: { staged?: boolean; ref?: string }
+): Promise<DiffHunk[]> {
+  const args = ['--no-color', '-U0', '--diff-filter=ACMR'];
+
+  if (options.staged) {
+    args.push('--cached');
+  } else if (options.ref) {
+    args.push(options.ref);
+  }
+
+  const diffOutput = await ctx.git.diff(args);
+  return parseDiff(diffOutput, ctx.root);
+}
+
+export function parseDiff(diffOutput: string, repoRoot: string): DiffHunk[] {
+  const hunks: DiffHunk[] = [];
+  const lines = diffOutput.split('\n');
+
+  let currentFile: string | null = null;
+  let addedLines: number[] = [];
+
+  for (const line of lines) {
+    // Match file header: +++ b/path/to/file
+    if (line.startsWith('+++ b/')) {
+      if (currentFile && addedLines.length > 0) {
+        hunks.push({ file: currentFile, addedLines: [...addedLines] });
+      }
+      currentFile = path.resolve(repoRoot, line.slice(6));
+      addedLines = [];
+      continue;
+    }
+
+    // Match hunk header: @@ -old,count +new,count @@
+    const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (hunkMatch && currentFile) {
+      const start = parseInt(hunkMatch[1], 10);
+      const count = hunkMatch[2] !== undefined ? parseInt(hunkMatch[2], 10) : 1;
+      for (let i = 0; i < count; i++) {
+        addedLines.push(start + i);
+      }
+    }
+  }
+
+  // Push last file
+  if (currentFile && addedLines.length > 0) {
+    hunks.push({ file: currentFile, addedLines: [...addedLines] });
+  }
+
+  return hunks;
+}
+
+export async function getChangedFiles(
+  ctx: GitContext,
+  options: { staged?: boolean; ref?: string }
+): Promise<string[]> {
+  const args = ['--name-only', '--diff-filter=ACMR'];
+
+  if (options.staged) {
+    args.push('--cached');
+  } else if (options.ref) {
+    args.push(options.ref);
+  }
+
+  const output = await ctx.git.diff(args);
+  return output
+    .split('\n')
+    .filter((f) => f.trim().length > 0)
+    .map((f) => path.resolve(ctx.root, f.trim()));
+}
+
+export async function getCurrentBranch(ctx: GitContext): Promise<string> {
+  try {
+    return (await ctx.git.revparse(['--abbrev-ref', 'HEAD'])).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+export async function getHeadRef(ctx: GitContext): Promise<string | null> {
+  try {
+    return (await ctx.git.revparse(['HEAD'])).trim();
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { scanPaths, scanFile } from './scanner';
+export { allRules, getRuleByName } from './rules';
+export { computeScore } from './scorer';
+export { loadConfig } from './config';
+export { getGitContext, getDiffFiles, parseDiff, getChangedFiles } from './git';
+export { loadCache, saveScore, getTrend } from './cache';
+export { analyzeCodebase } from './fingerprint/analyzer';
+export { saveProfile, loadProfile } from './fingerprint/profile';
+export { compareFileToProfile } from './fingerprint/comparator';
+export { attachFixes } from './fixes';
+export { DistyllError, NotAGitRepoError, UnsupportedLanguageError, FileAccessError, isBinaryBuffer, safeReadFile, formatError } from './errors';
+export type { Finding, Rule, ScanResult, ScanSummary, Severity, Language, StyleProfile, FixSuggestion } from './types';
+export type { DistyllConfig } from './config';
+export type { DiffHunk, GitContext } from './git';
+export type { TrendSummary } from './cache';

package/src/languages/index.ts

@@ -0,0 +1,50 @@
+import type { Language } from '../types';
+import { jsLanguages, jsExtensions, JS_STDLIB_MODULES } from './javascript';
+import { pythonLanguages, pythonExtensions, PYTHON_STDLIB_MODULES } from './python';
+
+/** Map from Language to tree-sitter grammar */
+const grammars: Record<string, any> = {
+  ...jsLanguages,
+  ...pythonLanguages,
+};
+
+/** Map from file extension to Language */
+const extensionMap: Record<string, Language> = {
+  ...jsExtensions,
+  ...pythonExtensions,
+};
+
+/** Map from Language to set of known standard library module names */
+const stdlibModules: Partial<Record<Language, Set<string>>> = {
+  javascript: JS_STDLIB_MODULES,
+  typescript: JS_STDLIB_MODULES,
+  tsx: JS_STDLIB_MODULES,
+  python: PYTHON_STDLIB_MODULES,
+};
+
+export function getGrammar(language: Language): any {
+  const grammar = grammars[language];
+  if (!grammar) throw new Error(`Unsupported language: ${language}`);
+  return grammar;
+}
+
+export function detectLanguageFromExt(filePath: string): Language | null {
+  const ext = filePath.slice(filePath.lastIndexOf('.'));
+  return extensionMap[ext] ?? null;
+}
+
+export function getStdlibModules(language: Language): Set<string> {
+  return stdlibModules[language] ?? new Set();
+}
+
+export function getSupportedExtensions(): string[] {
+  return Object.keys(extensionMap).map((ext) => ext.slice(1));
+}
+
+export function isJSLike(language: Language): boolean {
+  return language === 'javascript' || language === 'typescript' || language === 'tsx';
+}
+
+export function isPython(language: Language): boolean {
+  return language === 'python';
+}

package/src/languages/javascript.ts

@@ -0,0 +1,36 @@
+import JavaScript from 'tree-sitter-javascript';
+import TypeScriptLang from 'tree-sitter-typescript';
+import type { Language } from '../types';
+
+export const jsLanguages: Record<string, any> = {
+  javascript: JavaScript,
+  typescript: TypeScriptLang.typescript,
+  tsx: TypeScriptLang.tsx,
+};
+
+export const jsExtensions: Record<string, Language> = {
+  '.js': 'javascript',
+  '.jsx': 'javascript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.ts': 'typescript',
+  '.tsx': 'tsx',
+};
+
+/** Known Node.js / browser built-in modules */
+export const JS_STDLIB_MODULES = new Set([
+  'fs', 'path', 'os', 'http', 'https', 'url', 'util', 'stream', 'events',
+  'buffer', 'crypto', 'child_process', 'cluster', 'dgram', 'dns', 'domain',
+  'net', 'readline', 'repl', 'tls', 'tty', 'v8', 'vm', 'zlib',
+  'assert', 'async_hooks', 'console', 'constants', 'diagnostics_channel',
+  'inspector', 'module', 'perf_hooks', 'process', 'punycode', 'querystring',
+  'string_decoder', 'timers', 'trace_events', 'worker_threads', 'wasi',
+  'node:fs', 'node:path', 'node:os', 'node:http', 'node:https', 'node:url',
+  'node:util', 'node:stream', 'node:events', 'node:buffer', 'node:crypto',
+  'node:child_process', 'node:cluster', 'node:dgram', 'node:dns', 'node:net',
+  'node:readline', 'node:repl', 'node:tls', 'node:tty', 'node:v8', 'node:vm',
+  'node:zlib', 'node:assert', 'node:async_hooks', 'node:console',
+  'node:diagnostics_channel', 'node:inspector', 'node:module',
+  'node:perf_hooks', 'node:process', 'node:querystring', 'node:string_decoder',
+  'node:timers', 'node:trace_events', 'node:worker_threads', 'node:test',
+]);

package/src/languages/python.ts

@@ -0,0 +1,47 @@
+import PythonLang from 'tree-sitter-python';
+import type { Language } from '../types';
+
+export const pythonLanguages: Record<string, any> = {
+  python: PythonLang,
+};
+
+export const pythonExtensions: Record<string, Language> = {
+  '.py': 'python',
+  '.pyi': 'python',
+};
+
+/** Python standard library module names (3.10+) */
+export const PYTHON_STDLIB_MODULES = new Set([
+  'abc', 'aifc', 'argparse', 'array', 'ast', 'asynchat', 'asyncio',
+  'asyncore', 'atexit', 'audioop', 'base64', 'bdb', 'binascii', 'binhex',
+  'bisect', 'builtins', 'bz2', 'calendar', 'cgi', 'cgitb', 'chunk',
+  'cmath', 'cmd', 'code', 'codecs', 'codeop', 'collections', 'colorsys',
+  'compileall', 'concurrent', 'configparser', 'contextlib', 'contextvars',
+  'copy', 'copyreg', 'cProfile', 'crypt', 'csv', 'ctypes', 'curses',
+  'dataclasses', 'datetime', 'dbm', 'decimal', 'difflib', 'dis',
+  'distutils', 'doctest', 'email', 'encodings', 'enum', 'errno',
+  'faulthandler', 'fcntl', 'filecmp', 'fileinput', 'fnmatch', 'fractions',
+  'ftplib', 'functools', 'gc', 'getopt', 'getpass', 'gettext', 'glob',
+  'graphlib', 'grp', 'gzip', 'hashlib', 'heapq', 'hmac', 'html', 'http',
+  'idlelib', 'imaplib', 'imghdr', 'imp', 'importlib', 'inspect', 'io',
+  'ipaddress', 'itertools', 'json', 'keyword', 'lib2to3', 'linecache',
+  'locale', 'logging', 'lzma', 'mailbox', 'mailcap', 'marshal', 'math',
+  'mimetypes', 'mmap', 'modulefinder', 'multiprocessing', 'netrc', 'nis',
+  'nntplib', 'numbers', 'operator', 'optparse', 'os', 'ossaudiodev',
+  'pathlib', 'pdb', 'pickle', 'pickletools', 'pipes', 'pkgutil',
+  'platform', 'plistlib', 'poplib', 'posix', 'posixpath', 'pprint',
+  'profile', 'pstats', 'pty', 'pwd', 'py_compile', 'pyclbr',
+  'pydoc', 'queue', 'quopri', 'random', 're', 'readline', 'reprlib',
+  'resource', 'rlcompleter', 'runpy', 'sched', 'secrets', 'select',
+  'selectors', 'shelve', 'shlex', 'shutil', 'signal', 'site', 'smtpd',
+  'smtplib', 'sndhdr', 'socket', 'socketserver', 'sqlite3', 'ssl',
+  'stat', 'statistics', 'string', 'stringprep', 'struct', 'subprocess',
+  'sunau', 'symtable', 'sys', 'sysconfig', 'syslog', 'tabnanny',
+  'tarfile', 'telnetlib', 'tempfile', 'termios', 'test', 'textwrap',
+  'threading', 'time', 'timeit', 'tkinter', 'token', 'tokenize',
+  'tomllib', 'trace', 'traceback', 'tracemalloc', 'tty', 'turtle',
+  'turtledemo', 'types', 'typing', 'unicodedata', 'unittest', 'urllib',
+  'uu', 'uuid', 'venv', 'warnings', 'wave', 'weakref', 'webbrowser',
+  'winreg', 'winsound', 'wsgiref', 'xdrlib', 'xml', 'xmlrpc',
+  'zipapp', 'zipfile', 'zipimport', 'zlib', '_thread',
+]);

package/src/parser.ts

@@ -0,0 +1,52 @@
+import Parser from 'tree-sitter';
+import type { Language } from './types';
+import { getGrammar, detectLanguageFromExt } from './languages';
+
+const parsers = new Map<Language, Parser>();
+
+function getParser(language: Language): Parser {
+  let parser = parsers.get(language);
+  if (parser) return parser;
+
+  parser = new Parser();
+  parser.setLanguage(getGrammar(language));
+  parsers.set(language, parser);
+  return parser;
+}
+
+export function parse(source: string, language: Language): Parser.Tree {
+  const parser = getParser(language);
+  return parser.parse(source);
+}
+
+export function detectLanguage(filePath: string): Language | null {
+  return detectLanguageFromExt(filePath);
+}
+
+export function walkTree(node: Parser.SyntaxNode, callback: (node: Parser.SyntaxNode) => void): void {
+  callback(node);
+  for (const child of node.children) {
+    walkTree(child, callback);
+  }
+}
+
+export function findNodes(root: Parser.SyntaxNode, type: string): Parser.SyntaxNode[] {
+  const results: Parser.SyntaxNode[] = [];
+  walkTree(root, (node) => {
+    if (node.type === type) {
+      results.push(node);
+    }
+  });
+  return results;
+}
+
+export function findNodesMulti(root: Parser.SyntaxNode, types: string[]): Parser.SyntaxNode[] {
+  const typeSet = new Set(types);
+  const results: Parser.SyntaxNode[] = [];
+  walkTree(root, (node) => {
+    if (typeSet.has(node.type)) {
+      results.push(node);
+    }
+  });
+  return results;
+}

package/src/reporters/github.ts

@@ -0,0 +1,75 @@
+import type { ScanSummary, Severity, Finding } from '../types';
+
+const SEVERITY_MAP: Record<Severity, string> = {
+  info: 'notice',
+  warning: 'warning',
+  error: 'error',
+};
+
+export function formatGitHubAnnotations(summary: ScanSummary): string {
+  const lines: string[] = [];
+
+  for (const result of summary.results) {
+    for (const finding of result.findings) {
+      const level = SEVERITY_MAP[finding.severity];
+      const file = finding.file;
+      const line = finding.line;
+      lines.push(`::${level} file=${file},line=${line}::${finding.message} (${finding.rule})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function formatGitHubSummary(summary: ScanSummary): string {
+  const lines: string[] = [];
+
+  lines.push('## Distyll Slop Report');
+  lines.push('');
+
+  const emoji = summary.score <= 20 ? '🟢' : summary.score <= 50 ? '🟡' : '🔴';
+  lines.push(`**Slop Score: ${emoji} ${summary.score}/100**`);
+  lines.push('');
+
+  const findingCount = summary.totalFindings;
+  const fileCount = summary.results.filter((r) => r.findings.length > 0).length;
+  lines.push(`Found ${findingCount} issue${findingCount === 1 ? '' : 's'} across ${fileCount} file${fileCount === 1 ? '' : 's'}.`);
+  lines.push('');
+
+  // Group findings by severity
+  const allFindings = summary.results.flatMap((r) => r.findings);
+  const errors = allFindings.filter((f) => f.severity === 'error').length;
+  const warnings = allFindings.filter((f) => f.severity === 'warning').length;
+  const infos = allFindings.filter((f) => f.severity === 'info').length;
+
+  if (errors > 0 || warnings > 0 || infos > 0) {
+    lines.push('| Severity | Count |');
+    lines.push('|----------|-------|');
+    if (errors > 0) lines.push(`| 🔴 Error | ${errors} |`);
+    if (warnings > 0) lines.push(`| 🟡 Warning | ${warnings} |`);
+    if (infos > 0) lines.push(`| 🔵 Info | ${infos} |`);
+    lines.push('');
+  }
+
+  // List top findings (max 20)
+  const topFindings = allFindings.slice(0, 20);
+  if (topFindings.length > 0) {
+    lines.push('<details>');
+    lines.push('<summary>Findings</summary>');
+    lines.push('');
+    lines.push('| File | Line | Rule | Message |');
+    lines.push('|------|------|------|---------|');
+    for (const f of topFindings) {
+      const shortFile = f.file.replace(/.*\//, '');
+      lines.push(`| \`${shortFile}\` | ${f.line} | ${f.rule} | ${f.message} |`);
+    }
+    if (allFindings.length > 20) {
+      lines.push('');
+      lines.push(`_...and ${allFindings.length - 20} more findings._`);
+    }
+    lines.push('');
+    lines.push('</details>');
+  }
+
+  return lines.join('\n');
+}

package/src/reporters/terminal.ts

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import type { ScanSummary, Severity } from '../types';
+import type { TrendSummary } from '../cache';
+
+const SEVERITY_COLORS: Record<Severity, (s: string) => string> = {
+  info: chalk.blue,
+  warning: chalk.yellow,
+  error: chalk.red,
+};
+
+const SEVERITY_ICONS: Record<Severity, string> = {
+  info: 'i',
+  warning: '!',
+  error: 'x',
+};
+
+export function formatTerminalReport(summary: ScanSummary, trend?: TrendSummary): string {
+  const lines: string[] = [];
+
+  for (const result of summary.results) {
+    if (result.findings.length === 0) continue;
+    lines.push('');
+    lines.push(chalk.underline(result.file));
+    for (const finding of result.findings) {
+      const color = SEVERITY_COLORS[finding.severity];
+      const icon = SEVERITY_ICONS[finding.severity];
+      const location = chalk.gray(`${finding.file}:${finding.line}:${finding.column}`);
+      const rule = chalk.gray(`(${finding.rule})`);
+      lines.push(`  ${color(icon)} ${location} ${finding.message} ${rule}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(formatScoreLine(summary.score));
+  lines.push(
+    chalk.gray(
+      `${summary.totalFindings} finding${summary.totalFindings === 1 ? '' : 's'} across ${summary.results.length} file${summary.results.length === 1 ? '' : 's'}`
+    )
+  );
+
+  if (trend) {
+    lines.push(formatTrendLine(trend));
+  }
+
+  return lines.join('\n');
+}
+
+function formatScoreLine(score: number): string {
+  const label = 'Slop Score';
+  if (score <= 20) return chalk.green(`${label}: ${score}/100 - Clean`);
+  if (score <= 50) return chalk.yellow(`${label}: ${score}/100 - Moderate`);
+  return chalk.red(`${label}: ${score}/100 - High`);
+}
+
+function formatTrendLine(trend: TrendSummary): string {
+  if (trend.direction === 'first-scan') {
+    return chalk.gray('First scan — no trend data yet.');
+  }
+
+  const arrow =
+    trend.direction === 'improving' ? chalk.green('↓') :
+    trend.direction === 'worsening' ? chalk.red('↑') :
+    chalk.gray('→');
+
+  const delta = trend.delta !== null ? (trend.delta > 0 ? `+${trend.delta}` : `${trend.delta}`) : '';
+  return `${arrow} Trend: ${delta} from previous score of ${trend.previous}`;
+}

package/src/rules/dead-code-paths.ts

@@ -0,0 +1,62 @@
+import type Parser from 'tree-sitter';
+import { walkTree } from '../parser';
+import type { Finding, Rule } from '../types';
+
+const TERMINATING_STATEMENTS = new Set([
+  'return_statement',
+  'throw_statement',
+  'break_statement',
+  'continue_statement',
+]);
+
+function isBlockLike(node: Parser.SyntaxNode): boolean {
+  return node.type === 'statement_block' || node.type === 'block';
+}
+
+export const deadCodePaths: Rule = {
+  name: 'dead-code-paths',
+  description: 'Flags unreachable code after unconditional return, throw, break, or continue statements',
+  severity: 'warning',
+
+  check(tree: Parser.Tree, source: string, filePath: string): Finding[] {
+    const findings: Finding[] = [];
+    const flagged = new Set<number>();
+
+    walkTree(tree.rootNode, (node) => {
+      if (!isBlockLike(node)) return;
+
+      const children = node.namedChildren;
+      for (let i = 0; i < children.length - 1; i++) {
+        const stmt = children[i];
+
+        // Check if this statement is a terminating statement
+        if (!TERMINATING_STATEMENTS.has(stmt.type)) continue;
+
+        // Everything after a terminating statement in the same block is dead code
+        for (let j = i + 1; j < children.length; j++) {
+          const dead = children[j];
+          // Skip comments — they're not executable code
+          if (dead.type === 'comment') continue;
+
+          const lineKey = dead.startPosition.row;
+          if (flagged.has(lineKey)) continue;
+          flagged.add(lineKey);
+
+          findings.push({
+            file: filePath,
+            line: dead.startPosition.row + 1,
+            column: dead.startPosition.column + 1,
+            endLine: dead.endPosition.row + 1,
+            endColumn: dead.endPosition.column + 1,
+            rule: 'dead-code-paths',
+            severity: 'warning',
+            message: `Unreachable code after ${stmt.type.replace('_statement', '')} on line ${stmt.startPosition.row + 1}`,
+          });
+        }
+        break; // No need to check further in this block
+      }
+    });
+
+    return findings;
+  },
+};