distyll 0.1.0

package/src/cli.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { scanPaths } from './scanner';
+import { formatText, formatJson } from './formatter';
+import { runDiff } from './commands/diff';
+import { installHook, uninstallHook } from './commands/hook';
+import { runCI } from './commands/ci';
+import { runInit } from './commands/init';
+import { runFingerprint } from './commands/fingerprint';
+import { formatError } from './errors';
+
+const program = new Command();
+
+program
+  .name('distyll')
+  .description('Catch AI-generated code slop before it ships')
+  .version('0.1.0');
+
+program
+  .command('scan')
+  .description('Scan files or directories for AI code anti-patterns')
+  .argument('<paths...>', 'Files or directories to scan')
+  .option('-f, --format <format>', 'Output format: text or json', 'text')
+  .option('-t, --threshold <number>', 'Exit with code 1 if slop score exceeds this value', parseInt)
+  .option('-s, --style', 'Compare against project style profile (run "distyll fingerprint" first)')
+  .option('-v, --verbose', 'Show detailed parsing and rule execution info')
+  .option('-q, --quiet', 'Only output the slop score number (useful for scripting)')
+  .action(async (paths: string[], options: {
+    format: string;
+    threshold?: number;
+    style?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+  }) => {
+    try {
+      const summary = await scanPaths(paths, {
+        style: options.style,
+        verbose: options.verbose,
+      });
+
+      if (options.quiet) {
+        console.log(summary.score);
+      } else if (options.format === 'json') {
+        console.log(formatJson(summary));
+      } else {
+        console.log(formatText(summary));
+      }
+
+      if (options.threshold !== undefined && summary.score > options.threshold) {
+        if (!options.quiet) {
+          console.error(
+            `\nSlop score ${summary.score} exceeds threshold of ${options.threshold}`
+          );
+        }
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('diff')
+  .description('Scan only changed lines in a git diff')
+  .option('-s, --staged', 'Scan staged changes only')
+  .option('-r, --ref <ref>', 'Git ref to diff against (e.g., HEAD~1, main)')
+  .option('-f, --format <format>', 'Output format: text or json', 'text')
+  .option('-t, --threshold <number>', 'Exit with code 1 if slop score exceeds this value', parseInt)
+  .option('-v, --verbose', 'Show detailed parsing and rule execution info')
+  .option('-q, --quiet', 'Only output the slop score number')
+  .action(async (options: {
+    staged?: boolean;
+    ref?: string;
+    format?: string;
+    threshold?: number;
+    verbose?: boolean;
+    quiet?: boolean;
+  }) => {
+    try {
+      await runDiff({
+        staged: options.staged,
+        ref: options.ref,
+        format: options.format as 'text' | 'json',
+        threshold: options.threshold,
+        verbose: options.verbose,
+        quiet: options.quiet,
+      });
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+const hookCmd = program
+  .command('hook')
+  .description('Manage git hooks');
+
+hookCmd
+  .command('install')
+  .description('Install a pre-commit hook that runs distyll on staged changes')
+  .option('-t, --threshold <number>', 'Slop score threshold for blocking commits', parseInt)
+  .action(async (options: { threshold?: number }) => {
+    try {
+      await installHook(options.threshold);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+hookCmd
+  .command('uninstall')
+  .description('Remove the distyll pre-commit hook')
+  .action(async () => {
+    try {
+      await uninstallHook();
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('ci')
+  .description('Run in CI mode with GitHub Actions annotations')
+  .option('-r, --ref <ref>', 'Git ref to diff against (default: HEAD~1)')
+  .option('-f, --format <format>', 'Output format: annotations, json, or summary', 'annotations')
+  .option('-t, --threshold <number>', 'Exit with code 1 if slop score exceeds this value', parseInt)
+  .action(async (options: { ref?: string; format?: string; threshold?: number }) => {
+    try {
+      await runCI({
+        ref: options.ref,
+        format: options.format as 'annotations' | 'json' | 'summary',
+        threshold: options.threshold,
+      });
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('init')
+  .description('Initialize distyll configuration in the current directory')
+  .argument('[dir]', 'Directory to initialize (defaults to current directory)')
+  .action((dir?: string) => {
+    try {
+      runInit(dir);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('fingerprint')
+  .description('Analyze codebase to build a style profile for comparison')
+  .argument('[dir]', 'Directory to analyze (defaults to current directory)', '.')
+  .action(async (dir: string) => {
+    try {
+      await runFingerprint(dir);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/commands/ci.ts

@@ -0,0 +1,111 @@
+import { getGitContext, getDiffFiles, getCurrentBranch, getHeadRef } from '../git';
+import { scanFile } from '../scanner';
+import { computeScore } from '../scorer';
+import { loadConfig } from '../config';
+import { allRules } from '../rules';
+import { saveScore } from '../cache';
+import { formatGitHubAnnotations, formatGitHubSummary } from '../reporters/github';
+import { formatJson } from '../formatter';
+import { detectLanguage } from '../parser';
+import type { ScanResult, Rule } from '../types';
+
+export interface CIOptions {
+  ref?: string;
+  format?: 'annotations' | 'json' | 'summary';
+  threshold?: number;
+}
+
+export async function runCI(options: CIOptions): Promise<void> {
+  const ctx = await getGitContext();
+  const config = loadConfig(ctx.root);
+
+  let activeRules: Rule[] = [...allRules];
+  if (config.rules) {
+    activeRules = activeRules.filter((rule) => config.rules?.[rule.name] !== 'off');
+    activeRules = activeRules.map((rule) => {
+      const setting = config.rules?.[rule.name];
+      if (setting === 'warn' || setting === 'error') {
+        return { ...rule, severity: setting === 'warn' ? 'warning' : 'error' };
+      }
+      return rule;
+    });
+  }
+
+  // Determine diff ref: use provided ref, or diff against default branch
+  const diffRef = options.ref ?? 'HEAD~1';
+  const hunks = await getDiffFiles(ctx, { ref: diffRef });
+
+  if (hunks.length === 0) {
+    if (options.format === 'json') {
+      console.log(JSON.stringify({ score: 0, totalFindings: 0, files: [] }, null, 2));
+    } else if (options.format === 'summary') {
+      console.log('## Distyll Slop Report\n\n**Slop Score: 🟢 0/100**\n\nNo changes to analyze.');
+    } else {
+      console.log('No changes detected.');
+    }
+    return;
+  }
+
+  const results: ScanResult[] = [];
+
+  for (const hunk of hunks) {
+    const language = detectLanguage(hunk.file);
+    if (!language) continue;
+
+    const result = scanFile(hunk.file, activeRules);
+    if (!result) continue;
+
+    const addedLineSet = new Set(hunk.addedLines);
+    const filteredFindings = result.findings.filter((f) => addedLineSet.has(f.line));
+
+    if (filteredFindings.length > 0) {
+      results.push({
+        file: result.file,
+        findings: filteredFindings,
+        loc: result.loc,
+      });
+    }
+  }
+
+  const summary = computeScore(results);
+
+  // Cache score
+  try {
+    const branch = await getCurrentBranch(ctx);
+    const ref = await getHeadRef(ctx);
+    saveScore(ctx.root, summary.score, summary.totalFindings, results.length, ref ?? undefined, branch);
+  } catch {
+    // Best-effort
+  }
+
+  // Output based on format
+  const format = options.format ?? 'annotations';
+
+  if (format === 'json') {
+    console.log(formatJson(summary));
+  } else if (format === 'summary') {
+    console.log(formatGitHubSummary(summary));
+  } else {
+    // annotations (default for CI)
+    const annotations = formatGitHubAnnotations(summary);
+    if (annotations) console.log(annotations);
+
+    // Also write a step summary if GITHUB_STEP_SUMMARY is set
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile) {
+      const fs = require('fs');
+      try {
+        fs.appendFileSync(summaryFile, formatGitHubSummary(summary) + '\n');
+      } catch {
+        // Best-effort
+      }
+    }
+
+    console.log(`\nSlop Score: ${summary.score}/100 (${summary.totalFindings} findings)`);
+  }
+
+  if (options.threshold !== undefined && summary.score > options.threshold) {
+    console.error(`\nSlop score ${summary.score} exceeds threshold of ${options.threshold}`);
+    process.exit(1);
+  }
+}

package/src/commands/diff.ts

@@ -0,0 +1,108 @@
+import { getGitContext, getDiffFiles, getCurrentBranch, getHeadRef } from '../git';
+import { scanFile } from '../scanner';
+import { computeScore } from '../scorer';
+import { loadConfig } from '../config';
+import { allRules } from '../rules';
+import { saveScore, getTrend } from '../cache';
+import { formatTerminalReport } from '../reporters/terminal';
+import { formatJson } from '../formatter';
+import { detectLanguage } from '../parser';
+import type { ScanResult, Rule } from '../types';
+
+export interface DiffOptions {
+  staged?: boolean;
+  ref?: string;
+  format?: 'text' | 'json';
+  threshold?: number;
+  verbose?: boolean;
+  quiet?: boolean;
+}
+
+export async function runDiff(options: DiffOptions): Promise<void> {
+  const ctx = await getGitContext();
+  const config = loadConfig(ctx.root);
+
+  let activeRules: Rule[] = [...allRules];
+  if (config.rules) {
+    activeRules = activeRules.filter((rule) => config.rules?.[rule.name] !== 'off');
+    activeRules = activeRules.map((rule) => {
+      const setting = config.rules?.[rule.name];
+      if (setting === 'warn' || setting === 'error') {
+        return { ...rule, severity: setting === 'warn' ? 'warning' : 'error' };
+      }
+      return rule;
+    });
+  }
+
+  const hunks = await getDiffFiles(ctx, { staged: options.staged, ref: options.ref });
+
+  if (hunks.length === 0) {
+    if (options.quiet) {
+      console.log(0);
+    } else if (options.format === 'json') {
+      console.log(JSON.stringify({ score: 0, totalFindings: 0, files: [] }, null, 2));
+    } else {
+      console.log('No changes detected.');
+    }
+    return;
+  }
+
+  if (options.verbose) {
+    console.error(`Scanning ${hunks.length} changed file(s)...`);
+  }
+
+  const results: ScanResult[] = [];
+
+  for (const hunk of hunks) {
+    const language = detectLanguage(hunk.file);
+    if (!language) continue;
+
+    const result = scanFile(hunk.file, activeRules, null, options.verbose);
+    if (!result) continue;
+
+    const addedLineSet = new Set(hunk.addedLines);
+    const filteredFindings = result.findings.filter((f) => addedLineSet.has(f.line));
+
+    if (filteredFindings.length > 0) {
+      results.push({
+        file: result.file,
+        findings: filteredFindings,
+        loc: result.loc,
+      });
+    }
+  }
+
+  const summary = computeScore(results);
+
+  // Cache the score
+  try {
+    const branch = await getCurrentBranch(ctx);
+    const ref = await getHeadRef(ctx);
+    saveScore(ctx.root, summary.score, summary.totalFindings, results.length, ref ?? undefined, branch);
+  } catch {
+    // Caching is best-effort
+  }
+
+  // Get trend info
+  let trend;
+  try {
+    trend = getTrend(ctx.root, summary.score);
+  } catch {
+    // Trend is best-effort
+  }
+
+  if (options.quiet) {
+    console.log(summary.score);
+  } else if (options.format === 'json') {
+    console.log(formatJson(summary));
+  } else {
+    console.log(formatTerminalReport(summary, trend));
+  }
+
+  if (options.threshold !== undefined && summary.score > options.threshold) {
+    if (!options.quiet) {
+      console.error(`\nSlop score ${summary.score} exceeds threshold of ${options.threshold}`);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/fingerprint.ts

@@ -0,0 +1,47 @@
+import chalk from 'chalk';
+import * as path from 'path';
+import { analyzeCodebase } from '../fingerprint/analyzer';
+import { saveProfile } from '../fingerprint/profile';
+
+export async function runFingerprint(dir: string): Promise<void> {
+  const targetDir = path.resolve(dir);
+  console.log(chalk.gray(`Analyzing codebase in ${targetDir}...`));
+
+  const profile = await analyzeCodebase([targetDir]);
+
+  if (profile.fileCount === 0) {
+    console.error(
+      'No supported files found to analyze. Ensure the directory contains .js, .ts, .tsx, or .py files.'
+    );
+    process.exit(1);
+  }
+
+  const savedPath = saveProfile(profile, targetDir);
+
+  console.log('');
+  console.log(chalk.green('Style profile generated successfully.'));
+  console.log(chalk.gray(`Saved to: ${savedPath}`));
+  console.log('');
+  console.log(chalk.bold('Project Style Summary:'));
+  console.log(`  Files analyzed:        ${profile.fileCount}`);
+  console.log(`  Total LOC:             ${profile.totalLoc}`);
+  console.log(`  Median function length: ${profile.metrics.medianFunctionLength} lines`);
+  console.log(`  Avg function length:   ${profile.metrics.averageFunctionLength} lines`);
+  console.log(`  Max function length:   ${profile.metrics.maxFunctionLength} lines`);
+  console.log(`  Comment/code ratio:    ${Math.round(profile.metrics.commentToCodeRatio * 100)}%`);
+  console.log(`  Avg nesting depth:     ${profile.metrics.averageNestingDepth}`);
+  console.log(`  Try-catch density:     ${profile.metrics.tryCatchDensity} per 100 LOC`);
+  console.log(`  Avg imports/file:      ${profile.metrics.averageImportsPerFile}`);
+  console.log('');
+
+  const nc = profile.metrics.namingConventions;
+  console.log(chalk.bold('Naming Conventions:'));
+  console.log(`  camelCase:  ${nc.camelCase}%`);
+  console.log(`  snake_case: ${nc.snake_case}%`);
+  console.log(`  PascalCase: ${nc.PascalCase}%`);
+  console.log(`  other:      ${nc.other}%`);
+  console.log('');
+  console.log(
+    chalk.gray('Run "distyll scan --style <path>" to compare new code against this profile.')
+  );
+}

package/src/commands/hook.ts

@@ -0,0 +1,85 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getGitContext } from '../git';
+
+const HOOK_SCRIPT = `#!/bin/sh
+# Distyll pre-commit hook — blocks commits with high slop scores
+# Installed by: distyll hook install
+# Remove by: distyll hook uninstall
+
+npx distyll diff --staged --threshold 70
+`;
+
+export async function installHook(threshold?: number): Promise<void> {
+  const ctx = await getGitContext();
+  const hooksDir = path.join(ctx.root, '.git', 'hooks');
+
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  const hookPath = path.join(hooksDir, 'pre-commit');
+  const actualThreshold = threshold ?? 70;
+
+  const script = `#!/bin/sh
+# Distyll pre-commit hook — blocks commits with high slop scores
+# Installed by: distyll hook install
+# Remove by: distyll hook uninstall
+
+npx distyll diff --staged --threshold ${actualThreshold}
+`;
+
+  // Check if a pre-commit hook already exists
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf-8');
+    if (existing.includes('distyll')) {
+      // Update existing distyll hook
+      fs.writeFileSync(hookPath, script, { mode: 0o755 });
+      console.log(`Updated pre-commit hook (threshold: ${actualThreshold}).`);
+      return;
+    }
+    // Non-distyll hook exists — append
+    const combined = existing.trimEnd() + '\n\n' + script;
+    fs.writeFileSync(hookPath, combined, { mode: 0o755 });
+    console.log(`Appended distyll to existing pre-commit hook (threshold: ${actualThreshold}).`);
+    return;
+  }
+
+  fs.writeFileSync(hookPath, script, { mode: 0o755 });
+  console.log(`Installed pre-commit hook (threshold: ${actualThreshold}).`);
+}
+
+export async function uninstallHook(): Promise<void> {
+  const ctx = await getGitContext();
+  const hookPath = path.join(ctx.root, '.git', 'hooks', 'pre-commit');
+
+  if (!fs.existsSync(hookPath)) {
+    console.log('No pre-commit hook found.');
+    return;
+  }
+
+  const content = fs.readFileSync(hookPath, 'utf-8');
+  if (!content.includes('distyll')) {
+    console.log('Pre-commit hook exists but was not installed by distyll.');
+    return;
+  }
+
+  // If the hook is entirely distyll, remove the file
+  const lines = content.split('\n');
+  const nonDistyllLines = lines.filter(
+    (line) => !line.includes('distyll') && !line.includes('Distyll') && line.trim() !== ''
+  );
+
+  // Only shebang and blank lines remain — it's all distyll
+  if (nonDistyllLines.length <= 1) {
+    fs.unlinkSync(hookPath);
+    console.log('Removed pre-commit hook.');
+  } else {
+    // Remove distyll section
+    const cleaned = lines
+      .filter((line) => !line.includes('distyll') && !line.includes('Distyll'))
+      .join('\n');
+    fs.writeFileSync(hookPath, cleaned, { mode: 0o755 });
+    console.log('Removed distyll from pre-commit hook.');
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,42 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DEFAULT_CONFIG = {
+  rules: {},
+  threshold: 70,
+  ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/vendor/**'],
+};
+
+export function runInit(dir?: string): void {
+  const targetDir = dir ?? process.cwd();
+  const configPath = path.join(targetDir, '.distyll.json');
+  const gitignorePath = path.join(targetDir, '.gitignore');
+  const distyllDir = path.join(targetDir, '.distyll');
+
+  // Create config file
+  if (fs.existsSync(configPath)) {
+    console.log('.distyll.json already exists — skipping.');
+  } else {
+    fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n', 'utf-8');
+    console.log('Created .distyll.json');
+  }
+
+  // Create .distyll/ directory
+  if (!fs.existsSync(distyllDir)) {
+    fs.mkdirSync(distyllDir, { recursive: true });
+  }
+
+  // Add .distyll/ to .gitignore
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    if (!content.includes('.distyll/')) {
+      fs.appendFileSync(gitignorePath, '\n# Distyll cache\n.distyll/\n');
+      console.log('Added .distyll/ to .gitignore');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, '# Distyll cache\n.distyll/\n', 'utf-8');
+    console.log('Created .gitignore with .distyll/ entry');
+  }
+
+  console.log('\nDistyll initialized. Run "distyll scan ." to check your codebase.');
+}

package/src/config.ts

@@ -0,0 +1,75 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface DistyllConfig {
+  rules?: Record<string, 'off' | 'warn' | 'error'>;
+  threshold?: number;
+  ignore?: string[];
+}
+
+const CONFIG_FILENAME = '.distyll.json';
+
+export function loadConfig(startDir?: string): DistyllConfig {
+  if (!startDir) return {};
+
+  const configPath = findConfigFile(startDir);
+  if (!configPath) return {};
+
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return validateConfig(parsed);
+  } catch {
+    return {};
+  }
+}
+
+function findConfigFile(startDir: string): string | null {
+  let dir = startDir;
+
+  // If startDir is a file, use its parent directory
+  try {
+    if (fs.statSync(dir).isFile()) {
+      dir = path.dirname(dir);
+    }
+  } catch {
+    return null;
+  }
+
+  // Walk up the directory tree looking for .distyll.json
+  for (let i = 0; i < 50; i++) {
+    const candidate = path.join(dir, CONFIG_FILENAME);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function validateConfig(raw: unknown): DistyllConfig {
+  if (typeof raw !== 'object' || raw === null) return {};
+
+  const obj = raw as Record<string, unknown>;
+  const config: DistyllConfig = {};
+
+  if (obj.rules && typeof obj.rules === 'object' && !Array.isArray(obj.rules)) {
+    const rules: Record<string, 'off' | 'warn' | 'error'> = {};
+    for (const [key, val] of Object.entries(obj.rules as Record<string, unknown>)) {
+      if (val === 'off' || val === 'warn' || val === 'error') {
+        rules[key] = val;
+      }
+    }
+    config.rules = rules;
+  }
+
+  if (typeof obj.threshold === 'number' && obj.threshold >= 0 && obj.threshold <= 100) {
+    config.threshold = obj.threshold;
+  }
+
+  if (Array.isArray(obj.ignore)) {
+    config.ignore = obj.ignore.filter((item): item is string => typeof item === 'string');
+  }
+
+  return config;
+}