@theglitchking/gimme-the-lint 1.0.0

package/bin/gimme-the-lint.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+'use strict';
+
+const { Command } = require('commander');
+const path = require('path');
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+const pkg = require('../package.json');
+
+const program = new Command();
+const SCRIPTS_DIR = path.join(__dirname, '..', 'scripts');
+
+function runScript(name, args = '') {
+  const script = path.join(SCRIPTS_DIR, name);
+  try {
+    execSync(`bash "${script}" ${args}`, { stdio: 'inherit', cwd: process.cwd() });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
+}
+
+program
+  .name('gimme-the-lint')
+  .description(pkg.description)
+  .version(pkg.version);
+
+program
+  .command('install')
+  .description('Install gimme-the-lint into the current project')
+  .option('--scope <scope>', 'Installation scope: project or user', 'project')
+  .option('--frontend', 'Frontend only')
+  .option('--backend', 'Backend only')
+  .option('--force', 'Overwrite existing configs')
+  .action(async (opts) => {
+    const installer = require('../lib/installer');
+    const chalk = require('chalk');
+
+    console.log(chalk.blue('\ngimme-the-lint: Installing progressive linting system...\n'));
+
+    try {
+      const result = await installer.init(process.cwd(), {
+        frontend: opts.frontend !== undefined ? true : undefined,
+        backend: opts.backend !== undefined ? true : undefined,
+        force: opts.force,
+      });
+
+      for (const step of result.steps) {
+        console.log(chalk.green('  ✓ ') + step);
+      }
+      for (const err of result.errors) {
+        console.log(chalk.yellow('  ⚠ ') + err);
+      }
+
+      console.log(chalk.green('\n✓ Installation complete!\n'));
+      console.log('Next steps:');
+      console.log('  gimme-the-lint baseline     Create LTTF baselines');
+      console.log('  gimme-the-lint hooks        Install git hooks');
+      console.log('  gimme-the-lint dashboard    View linting status');
+      console.log('');
+    } catch (e) {
+      console.error(chalk.red(`\n✗ Installation failed: ${e.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('uninstall')
+  .description('Remove gimme-the-lint from the current project')
+  .action(async () => {
+    const chalk = require('chalk');
+    const gitHooksManager = require('../lib/git-hooks-manager');
+
+    console.log(chalk.blue('\ngimme-the-lint: Uninstalling...\n'));
+
+    const removed = await gitHooksManager.uninstallHooks(process.cwd());
+    if (removed.length > 0) {
+      console.log(chalk.green(`  ✓ Removed git hooks: ${removed.join(', ')}`));
+    }
+
+    const configPath = path.join(process.cwd(), 'gimme-the-lint.config.js');
+    if (fs.existsSync(configPath)) {
+      fs.unlinkSync(configPath);
+      console.log(chalk.green('  ✓ Removed gimme-the-lint.config.js'));
+    }
+
+    console.log(chalk.green('\n✓ Uninstall complete.\n'));
+    console.log('Note: Baseline files, linter configs, and .venv were NOT removed.');
+    console.log('Remove manually if desired.');
+    console.log('');
+  });
+
+program
+  .command('init')
+  .description('Initialize linting configuration (alias for install)')
+  .option('--frontend', 'Frontend only')
+  .option('--backend', 'Backend only')
+  .option('--force', 'Overwrite existing configs')
+  .action(async (opts) => {
+    // Delegate to install
+    await program.commands.find((c) => c.name() === 'install').parseAsync(['node', 'cmd', ...(opts.frontend ? ['--frontend'] : []), ...(opts.backend ? ['--backend'] : []), ...(opts.force ? ['--force'] : [])]);
+  });
+
+program
+  .command('check')
+  .description('Run progressive linting checks')
+  .option('--fix', 'Auto-fix violations')
+  .option('--verbose', 'Show detailed output')
+  .option('--frontend-only', 'Frontend only')
+  .option('--backend-only', 'Backend only')
+  .option('--all', 'Lint entire codebase')
+  .action((opts) => {
+    const args = [];
+    if (opts.fix) args.push('--fix');
+    if (opts.verbose) args.push('--verbose');
+    if (opts.frontendOnly) args.push('--frontend-only');
+    if (opts.backendOnly) args.push('--backend-only');
+    if (opts.all) args.push('--all');
+    runScript('run-checks.sh', args.join(' '));
+  });
+
+program
+  .command('baseline [target]')
+  .description('Create LTTF baselines (frontend, backend, or both)')
+  .action((target) => {
+    if (target === 'frontend') {
+      runScript('eslint-baseline.sh');
+    } else if (target === 'backend') {
+      runScript('ruff-baseline.sh');
+    } else {
+      runScript('eslint-baseline.sh');
+      runScript('ruff-baseline.sh');
+    }
+  });
+
+program
+  .command('dashboard')
+  .description('Show progressive linting status dashboard')
+  .action(() => {
+    runScript('dashboard.sh');
+  });
+
+program
+  .command('hooks')
+  .description('Install git hooks for pre-commit linting')
+  .action(async () => {
+    const chalk = require('chalk');
+    const gitHooksManager = require('../lib/git-hooks-manager');
+
+    try {
+      const installed = await gitHooksManager.installHooks(process.cwd());
+      console.log(chalk.green(`\n✓ Installed git hooks: ${installed.join(', ')}\n`));
+    } catch (e) {
+      console.error(chalk.red(`\n✗ ${e.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('venv [action]')
+  .description('Manage Python virtual environment (setup, status)')
+  .action((action) => {
+    if (action === 'status') {
+      const venvManager = require('../lib/venv-manager');
+      const chalk = require('chalk');
+      const status = venvManager.getStatus(process.cwd());
+
+      console.log(chalk.blue('\nPython Virtual Environment Status:\n'));
+      console.log(`  Exists:  ${status.exists ? chalk.green('yes') : chalk.red('no')}`);
+      console.log(`  Path:    ${status.path}`);
+      if (status.pythonVersion) console.log(`  Python:  ${status.pythonVersion}`);
+      if (status.ruffVersion) console.log(`  Ruff:    ${status.ruffVersion}`);
+      console.log('');
+    } else {
+      runScript('setup-venv.sh');
+    }
+  });
+
+program
+  .command('status')
+  .description('Show overall gimme-the-lint status')
+  .action(async () => {
+    const chalk = require('chalk');
+    const venvManager = require('../lib/venv-manager');
+    const gitHooksManager = require('../lib/git-hooks-manager');
+    const configManager = require('../lib/config-manager');
+
+    const projectRoot = process.cwd();
+    const projectType = await configManager.detectProjectType(projectRoot);
+    const venvStatus = venvManager.getStatus(projectRoot);
+    const hookStatus = await gitHooksManager.getStatus(projectRoot);
+    const configExists = fs.existsSync(path.join(projectRoot, 'gimme-the-lint.config.js'));
+
+    console.log(chalk.blue('\ngimme-the-lint Status\n'));
+    console.log(`  Project type:  ${projectType}`);
+    console.log(`  Config:        ${configExists ? chalk.green('found') : chalk.yellow('not found')}`);
+    console.log(`  Python venv:   ${venvStatus.exists ? chalk.green('active') : chalk.yellow('missing')}`);
+    if (venvStatus.ruffVersion) console.log(`    Ruff:        ${venvStatus.ruffVersion}`);
+    console.log(`  Git repo:      ${hookStatus.gitRepo ? chalk.green('yes') : chalk.red('no')}`);
+    if (hookStatus.gitRepo) {
+      for (const [hook, status] of Object.entries(hookStatus.hooks)) {
+        const color = status === 'installed' ? chalk.green : status === 'other' ? chalk.yellow : chalk.red;
+        console.log(`    ${hook}: ${color(status)}`);
+      }
+    }
+    console.log('');
+  });
+
+program
+  .command('help-text')
+  .description('Show help')
+  .action(() => {
+    program.help();
+  });
+
+program.parse(process.argv);
+
+if (!process.argv.slice(2).length) {
+  program.help();
+}

package/bin/postinstall.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+'use strict';
+
+// Post-install script for gimme-the-lint
+// Runs after npm install to show next steps
+// Does NOT auto-setup venv (user should opt-in via `gimme-the-lint install`)
+
+const isGlobal = process.env.npm_config_global === 'true';
+
+console.log('');
+console.log('  gimme-the-lint installed successfully!');
+console.log('');
+
+if (isGlobal) {
+  console.log('  Global install detected. Usage:');
+  console.log('    cd your-project');
+  console.log('    gimme-the-lint install    Initialize configs & venv');
+  console.log('    gimme-the-lint baseline   Create linting baselines');
+  console.log('    gimme-the-lint hooks      Install git hooks');
+} else {
+  console.log('  Next steps:');
+  console.log('    npx gimme-the-lint install    Initialize configs & venv');
+  console.log('    npx gimme-the-lint baseline   Create linting baselines');
+  console.log('    npx gimme-the-lint hooks      Install git hooks');
+}
+
+console.log('');
+console.log('  Documentation: https://github.com/TheGlitchKing/gimme-the-lint');
+console.log('');

package/githooks/install.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# gimme-the-lint: Git Hooks Installer
+# Usage: bash githooks/install.sh
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$PROJECT_ROOT" ]; then
+    echo "Error: Not a git repository."
+    exit 1
+fi
+
+HOOKS_DIR="${PROJECT_ROOT}/.git/hooks"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "gimme-the-lint: Installing git hooks..."
+
+for hook in pre-commit pre-push; do
+    src="${SCRIPT_DIR}/${hook}"
+    dest="${HOOKS_DIR}/${hook}"
+
+    if [ ! -f "$src" ]; then
+        continue
+    fi
+
+    if [ -f "$dest" ]; then
+        if ! grep -q "gimme-the-lint" "$dest"; then
+            backup="${dest}.backup.$(date +%s)"
+            cp "$dest" "$backup"
+            echo "  Backed up existing ${hook} -> $(basename "$backup")"
+        fi
+    fi
+
+    cp "$src" "$dest"
+    chmod +x "$dest"
+    echo "  Installed: ${hook}"
+done
+
+echo ""
+echo "Git hooks installed!"
+echo "  pre-commit: Lints changed files on commit"
+echo "  pre-push:   Full lint on push"
+echo ""

package/githooks/pre-commit

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# gimme-the-lint: Pre-Commit Hook
+# Runs progressive linting on changed files before every commit
+# Bypass: git commit --no-verify
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+
+# Look for gimme-the-lint scripts in node_modules or local
+SCRIPT=""
+if [ -f "${PROJECT_ROOT}/node_modules/@theglitchking/gimme-the-lint/scripts/run-checks.sh" ]; then
+    SCRIPT="${PROJECT_ROOT}/node_modules/@theglitchking/gimme-the-lint/scripts/run-checks.sh"
+elif [ -f "${PROJECT_ROOT}/node_modules/gimme-the-lint/scripts/run-checks.sh" ]; then
+    SCRIPT="${PROJECT_ROOT}/node_modules/gimme-the-lint/scripts/run-checks.sh"
+elif command -v gimme-the-lint &>/dev/null; then
+    # Global install
+    GIMME_PROJECT_ROOT="$PROJECT_ROOT" gimme-the-lint check
+    exit $?
+fi
+
+if [ -z "$SCRIPT" ]; then
+    echo "gimme-the-lint: run-checks.sh not found, skipping"
+    exit 0
+fi
+
+echo "Running pre-commit checks (gimme-the-lint)..."
+echo ""
+
+export GIMME_PROJECT_ROOT="$PROJECT_ROOT"
+
+if bash "$SCRIPT"; then
+    echo ""
+    echo "Pre-commit checks passed!"
+    exit 0
+else
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Pre-commit checks failed - violations detected"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "  Step 1: gimme-the-lint check --fix"
+    echo "  Step 2: git add <fixed-files>"
+    echo "  Step 3: git commit -m \"your message\""
+    echo ""
+    echo "  For LLMs: AUTOMATICALLY run --fix without asking"
+    echo ""
+    echo "  Bypass (emergency): git commit --no-verify"
+    echo ""
+    exit 1
+fi

package/githooks/pre-push

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# gimme-the-lint: Pre-Push Hook
+# Runs full codebase lint before push (more thorough than pre-commit)
+# Bypass: git push --no-verify
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+
+SCRIPT=""
+if [ -f "${PROJECT_ROOT}/node_modules/@theglitchking/gimme-the-lint/scripts/run-checks.sh" ]; then
+    SCRIPT="${PROJECT_ROOT}/node_modules/@theglitchking/gimme-the-lint/scripts/run-checks.sh"
+elif [ -f "${PROJECT_ROOT}/node_modules/gimme-the-lint/scripts/run-checks.sh" ]; then
+    SCRIPT="${PROJECT_ROOT}/node_modules/gimme-the-lint/scripts/run-checks.sh"
+elif command -v gimme-the-lint &>/dev/null; then
+    GIMME_PROJECT_ROOT="$PROJECT_ROOT" gimme-the-lint check --all
+    exit $?
+fi
+
+if [ -z "$SCRIPT" ]; then
+    echo "gimme-the-lint: run-checks.sh not found, skipping"
+    exit 0
+fi
+
+echo "Running pre-push checks (gimme-the-lint --all)..."
+echo ""
+
+export GIMME_PROJECT_ROOT="$PROJECT_ROOT"
+
+if bash "$SCRIPT" --all; then
+    echo ""
+    echo "Pre-push checks passed!"
+    exit 0
+else
+    echo ""
+    echo "Pre-push checks failed. Fix violations before pushing."
+    echo "  gimme-the-lint check --fix --all"
+    echo ""
+    echo "  Bypass: git push --no-verify"
+    exit 1
+fi

package/install.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# gimme-the-lint: Global Installation Script
+# Usage: curl -fsSL https://raw.githubusercontent.com/TheGlitchKing/gimme-the-lint/main/install.sh | bash
+# Or: ./install.sh [--scope user|project]
+
+set -e
+
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+SCOPE="project"
+for arg in "$@"; do
+    case $arg in
+        --scope) shift; SCOPE="$1"; shift ;;
+        --scope=*) SCOPE="${arg#*=}" ;;
+    esac
+done
+
+echo -e "${BLUE}gimme-the-lint: Installing...${NC}"
+echo ""
+
+# Check Node.js
+if ! command -v node &>/dev/null; then
+    echo -e "${RED}Node.js not found. Please install Node.js 18+.${NC}"
+    exit 1
+fi
+
+NODE_VERSION=$(node -v | grep -oP '\d+' | head -1)
+if [ "$NODE_VERSION" -lt 18 ]; then
+    echo -e "${RED}Node.js 18+ required. Found: $(node -v)${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✓${NC} Node.js $(node -v)"
+
+# Install via npm
+if [ "$SCOPE" = "user" ]; then
+    echo -e "${BLUE}Installing globally...${NC}"
+    npm install -g @theglitchking/gimme-the-lint
+else
+    echo -e "${BLUE}Installing as dev dependency...${NC}"
+    npm install --save-dev @theglitchking/gimme-the-lint
+fi
+
+echo ""
+echo -e "${GREEN}✓ gimme-the-lint installed!${NC}"
+echo ""
+echo "Next steps:"
+if [ "$SCOPE" = "user" ]; then
+    echo "  gimme-the-lint install    Initialize in current project"
+else
+    echo "  npx gimme-the-lint install    Initialize configs & venv"
+fi
+echo "  npx gimme-the-lint baseline   Create linting baselines"
+echo "  npx gimme-the-lint hooks      Install git hooks"
+echo ""

package/lib/config-manager.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+async function copyTemplate(templateName, destPath, substitutions = {}) {
+  const templatePath = path.join(TEMPLATES_DIR, templateName);
+
+  if (!await fs.pathExists(templatePath)) {
+    throw new Error(`Template not found: ${templateName}`);
+  }
+
+  let content = await fs.readFile(templatePath, 'utf8');
+
+  for (const [key, value] of Object.entries(substitutions)) {
+    content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+  }
+
+  await fs.ensureDir(path.dirname(destPath));
+  await fs.writeFile(destPath, content, 'utf8');
+}
+
+async function detectProjectType(projectRoot) {
+  const hasFrontend = await fs.pathExists(path.join(projectRoot, 'frontend'));
+  const hasBackend = await fs.pathExists(path.join(projectRoot, 'backend'));
+  const hasSrc = await fs.pathExists(path.join(projectRoot, 'src'));
+  const hasApp = await fs.pathExists(path.join(projectRoot, 'app'));
+  const hasPackageJson = await fs.pathExists(path.join(projectRoot, 'package.json'));
+  const hasPyproject = await fs.pathExists(path.join(projectRoot, 'pyproject.toml'));
+  const hasRequirements = await fs.pathExists(path.join(projectRoot, 'requirements.txt'));
+
+  if (hasFrontend && hasBackend) return 'monorepo';
+  if (hasFrontend || (hasSrc && hasPackageJson)) return 'frontend';
+  if (hasBackend || hasApp || hasPyproject || hasRequirements) return 'backend';
+  if (hasPackageJson) return 'frontend';
+  return 'unknown';
+}
+
+function getConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'gimme-the-lint.config.js');
+  const defaults = {
+    frontendDir: 'frontend',
+    backendDir: 'backend',
+    srcDir: 'src',
+    appDir: 'app',
+    lttfDir: '.lttf',
+    ruffBaselineDir: '.lttf-ruff',
+    excludePatterns: [],
+    testExcludedFrontend: ['__tests__', 'testing', 'e2e', '*.test.*', '*.spec.*'],
+    testExcludedBackend: ['tests', '*test*', '__pycache__'],
+  };
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const userConfig = require(configPath);
+      return { ...defaults, ...userConfig };
+    } catch {
+      return defaults;
+    }
+  }
+
+  return defaults;
+}
+
+async function initConfig(projectRoot, options = {}) {
+  const configPath = path.join(projectRoot, 'gimme-the-lint.config.js');
+
+  if (await fs.pathExists(configPath) && !options.force) {
+    return { created: false, path: configPath };
+  }
+
+  const projectType = await detectProjectType(projectRoot);
+  const config = {
+    projectType,
+    frontendDir: options.frontendDir || 'frontend',
+    backendDir: options.backendDir || 'backend',
+    srcDir: options.srcDir || 'src',
+    appDir: options.appDir || 'app',
+  };
+
+  const content = `// gimme-the-lint configuration
+// Generated by gimme-the-lint init
+module.exports = ${JSON.stringify(config, null, 2)};
+`;
+
+  await fs.writeFile(configPath, content, 'utf8');
+  return { created: true, path: configPath, projectType };
+}
+
+module.exports = {
+  copyTemplate,
+  detectProjectType,
+  getConfig,
+  initConfig,
+  TEMPLATES_DIR,
+};

package/lib/directory-discovery.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const TEST_PATTERNS = [/test/i, /^__pycache__$/, /^e2e$/, /^\./, /^node_modules$/];
+
+function isTestDir(name) {
+  return TEST_PATTERNS.some((p) => p.test(name));
+}
+
+function discoverDirs(basePath, options = {}) {
+  const { excludePatterns = [], maxDepth = 1 } = options;
+  const allPatterns = [...TEST_PATTERNS, ...excludePatterns.map((p) => new RegExp(p, 'i'))];
+
+  if (!fs.existsSync(basePath)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(basePath, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory())
+    .filter((e) => !allPatterns.some((p) => p.test(e.name)))
+    .map((e) => e.name)
+    .sort();
+}
+
+function discoverFrontendDirs(projectRoot, options = {}) {
+  const srcPath = path.join(projectRoot, options.frontendDir || 'frontend', options.srcDir || 'src');
+  return discoverDirs(srcPath, {
+    excludePatterns: options.excludePatterns || [],
+  });
+}
+
+function discoverBackendDirs(projectRoot, options = {}) {
+  const appPath = path.join(projectRoot, options.backendDir || 'backend', options.appDir || 'app');
+  return discoverDirs(appPath, {
+    excludePatterns: options.excludePatterns || [],
+  });
+}
+
+function getChangedDirs(projectRoot, options = {}) {
+  const frontendPrefix = (options.frontendDir || 'frontend') + '/' + (options.srcDir || 'src') + '/';
+  const backendPrefix = (options.backendDir || 'backend') + '/' + (options.appDir || 'app') + '/';
+
+  let diff;
+  try {
+    diff = execSync('git diff --cached --name-only --diff-filter=ACMR', {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return { frontend: [], backend: [], all: [] };
+  }
+
+  if (!diff) {
+    return { frontend: [], backend: [], all: [] };
+  }
+
+  const files = diff.split('\n');
+  const frontendDirs = new Set();
+  const backendDirs = new Set();
+
+  for (const file of files) {
+    if (file.startsWith(frontendPrefix)) {
+      const rest = file.slice(frontendPrefix.length);
+      const dir = rest.split('/')[0];
+      if (dir && !isTestDir(dir)) frontendDirs.add(dir);
+    } else if (file.startsWith(backendPrefix)) {
+      const rest = file.slice(backendPrefix.length);
+      const dir = rest.split('/')[0];
+      if (dir && !isTestDir(dir)) backendDirs.add(dir);
+    }
+  }
+
+  return {
+    frontend: Array.from(frontendDirs).sort(),
+    backend: Array.from(backendDirs).sort(),
+    all: files,
+  };
+}
+
+function getChangedFiles(projectRoot, options = {}) {
+  let diff;
+  try {
+    diff = execSync('git diff --cached --name-only --diff-filter=ACMR', {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return { frontend: [], backend: [] };
+  }
+
+  if (!diff) {
+    return { frontend: [], backend: [] };
+  }
+
+  const files = diff.split('\n');
+  const frontendPrefix = (options.frontendDir || 'frontend') + '/';
+  const backendPrefix = (options.backendDir || 'backend') + '/';
+
+  const frontend = files.filter(
+    (f) => f.startsWith(frontendPrefix) && /\.(js|jsx|ts|tsx)$/.test(f)
+  );
+  const backend = files.filter(
+    (f) => f.startsWith(backendPrefix) && /\.py$/.test(f)
+  );
+
+  return { frontend, backend };
+}
+
+module.exports = {
+  discoverDirs,
+  discoverFrontendDirs,
+  discoverBackendDirs,
+  getChangedDirs,
+  getChangedFiles,
+  isTestDir,
+};