@theglitchking/gimme-the-lint 2.3.0 → 2.5.0

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for gimme-the-lint - polyglot progressive linting with per-app baselines and drift detection",
-    "version": "2.3.0"
+    "version": "2.5.0"
   },
   "plugins": [
     {
       "name": "gimme-the-lint",
       "description": "Polyglot progressive linting for monorepos — adapter-driven baselines, per-app drift detection, and idempotent skips across JavaScript/TypeScript, Python, Go, Rust, Terraform, and Ansible.",
-      "version": "2.3.0",
+      "version": "2.5.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gimme-the-lint",
   "description": "Polyglot progressive linting for monorepos — adapter-driven baselines, per-app drift detection, and idempotent skips across JavaScript/TypeScript, Python, Go, Rust, Terraform, and Ansible.",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] - 2026-05-17
+
+### Added
+- **`.gtl/config.js` — consolidated config location.** gimme-the-lint's own
+  config file now lives canonically at `.gtl/config.js` (`.gtl/config.cjs` for
+  ESM projects), so it travels with the committed `.gtl/` baselines rather than
+  sitting loose at the repo root. `install` and `migrate` write new configs
+  there; `config-manager.findConfig()` resolves the location. A repo-root
+  `gimme-the-lint.config.js` is still read as a fallback — existing projects
+  need no change — and `.gtl/` wins when both exist. `uninstall` removes a
+  repo-root config but leaves a `.gtl/` one in place (it is part of the
+  preserved `.gtl/` directory). Linter configs (`eslint.config.js`,
+  `.tflint.hcl`, …) are unaffected: each linter resolves its own config from a
+  fixed location gimme-the-lint does not own.
+
+## [2.4.0] - 2026-05-17
+
+### Fixed
+- **tflint silent-failure on uninitialized ruleset plugins.** When a unit
+  carries a `.tflint.hcl`, tflint requires `tflint --init` before linting; the
+  adapter never ran it, so a failed run was recorded as a clean zero-violation
+  baseline that mis-gated every later commit. Adapters gain an `initCommand()`
+  hook (run once per directory); the tflint adapter runs `tflint --init` when a
+  `.tflint.hcl` is present. `parse()` now takes `(stdout, stderr, code)` — a
+  non-zero exit with no parseable JSON emits a high-severity `tflint-error`
+  violation, never a silent clean pass.
+- **eslint false-positive on a tooling-only `package.json`.** Discovery bound
+  eslint on the filename alone, so a devDependencies-only, source-free
+  `package.json` (one that merely pins a tooling dependency) became an eslint
+  app. `package.json` is now a conditional marker — eslint is bound only when
+  the directory looks like a real JS app (runtime deps / entry-point fields /
+  JS-TS source / an eslint or biome config). `EslintAdapter.detect()` is
+  likewise tightened so a bare `package.json` is insufficient.
+- **tflint `available()` over-reporting.** It returned true even when ruleset
+  plugins a `.tflint.hcl` declared were not installed, disagreeing with
+  `lint()`. It now verifies every declared plugin resolves.
+- **`.terraform.lock.hcl` removed from the tflint manifest files** — it is a
+  provider-lock file written by `terraform init`, not a tflint signal.
+
+### Added
+- **Generic ruleset-plugin version tracking.** `TflintAdapter.rulesetVersions()`
+  parses `tflint --version` into a `{ ruleset: version }` map — no ruleset name
+  is special-cased. A new `ruleset_versions` field is threaded through
+  baselines and the global manifest; drift detection emits a `ruleset` drift
+  entry when a plugin version changes, catching a plugin update under a loose
+  `.tflint.hcl` version constraint that left `config_hash` and `tool_version`
+  untouched.
+- **Rule rename/removal migration.** Per-linter rule-alias maps
+  (`lib/rule-aliases.js`) plus `gimme-the-lint migrate --rules`: re-lints each
+  unit and rewrites a renamed rule's baseline fingerprint old→new (preserving
+  the grandfather count), drops entries for rules that no longer occur, and
+  corrects `total`. A genuinely new violation is never grandfathered.
+
+### Changed
+- **`tflint.parse()` signature** is now `(stdout, stderr, code)`, matching the
+  base adapter contract.
+- **Removed the dead v1 drift path.** `lib/drift-detector.js` (superseded by
+  `lib/drift.js`) is deleted; `lib/manifest-manager.js` is slimmed to its one
+  live function, `hashFile()` — the v2 global manifest is owned by
+  `lib/gtl-manifest.js`.
+
+### Design
+- The tflint adapter never names a cloud provider. The bundled `terraform`
+  ruleset lints any Terraform repo with zero config; provider-specific rulesets
+  are opt-in and owned entirely by the target repo's own `.tflint.hcl`, which
+  the adapter parses generically for whatever `plugin` blocks it declares.
+
 ## [2.3.0] - 2026-05-17
 
 ### Fixed

package/README.md

@@ -173,7 +173,10 @@ git add -A && git commit -m "…" # retry
 ## Configuration
 
 Zero config is the default — apps and their linters are auto-detected. To
-override, add `gimme-the-lint.config.js` at the repo root:
+override, add a config file. The canonical location is **`.gtl/config.js`**
+(it travels with the committed `.gtl/` baselines); a repo-root
+`gimme-the-lint.config.js` is also read, for back-compatibility. `install` and
+`migrate` write new configs to `.gtl/`:
 
 ```js
 module.exports = {

package/bin/gimme-the-lint.js

@@ -86,6 +86,7 @@ program
   .action(async () => {
     const chalk = require('chalk');
     const gitHooksManager = require('../lib/git-hooks-manager');
+    const configManager = require('../lib/config-manager');
 
     console.log(chalk.blue('\ngimme-the-lint: Uninstalling...\n'));
 
@@ -94,10 +95,17 @@ program
       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'));
+    // Remove a repo-root config. A config under .gtl/ is left in place — it is
+    // part of the .gtl/ directory, which uninstall preserves.
+    const cfgPath = configManager.findConfig(process.cwd());
+    if (cfgPath) {
+      const rel = path.relative(process.cwd(), cfgPath);
+      if (rel.startsWith(`.gtl${path.sep}`)) {
+        console.log(chalk.dim(`  · Config kept (${rel} — part of .gtl/)`));
+      } else {
+        fs.unlinkSync(cfgPath);
+        console.log(chalk.green(`  ✓ Removed ${path.basename(cfgPath)}`));
+      }
     }
 
     console.log(chalk.green('\n✓ Uninstall complete.\n'));
@@ -189,9 +197,45 @@ program
   .description('Migrate a v1 (.lttf) project to the v2 .gtl/ layout')
   .option('--strict', 'Fail when a linter is missing for code that is present')
   .option('--allow-incomplete', 'Exit 0 even if some linters could not be baselined')
+  .option('--rules', 'Migrate baselines through rule renames/removals (no layout change)')
   .action(async (opts) => {
     const chalk = require('chalk');
-    const { migrate } = require('../lib/migrate');
+    const { migrate, migrateRules } = require('../lib/migrate');
+
+    // --rules: rewrite baseline fingerprints through the per-linter rule-alias
+    // maps. A standalone mode — it does not touch the .gtl/ layout.
+    if (opts.rules) {
+      try {
+        const result = await migrateRules(process.cwd());
+        if (!result.migrated) {
+          console.log(
+            chalk.yellow('\nNo rule migrations applied — baselines are up to date.\n')
+          );
+          return;
+        }
+        console.log(chalk.green('\n✓ Rule migration applied\n'));
+        for (const u of result.units) {
+          for (const l of u.linters) {
+            const renames = l.renamed
+              .map((r) => `${r.from}→${r.to}`)
+              .join(', ');
+            console.log(
+              `  ${u.app} · ${l.linter}: ` +
+                `${l.renamed.length} renamed${renames ? ` (${renames})` : ''}, ` +
+                `${l.dropped} dropped`
+            );
+          }
+        }
+        console.log('');
+        console.log('Review the updated .gtl/ baselines and commit them.');
+        console.log('');
+      } catch (err) {
+        console.error(chalk.red(`\n✗ Rule migration failed: ${err.message}\n`));
+        process.exit(1);
+      }
+      return;
+    }
+
     try {
       const result = await migrate(process.cwd(), { strict: opts.strict });
       if (!result.migrated) {
@@ -336,7 +380,7 @@ program
     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'));
+    const configExists = Boolean(configManager.findConfig(projectRoot));
 
     console.log(chalk.blue('\ngimme-the-lint Status\n'));
     console.log(`  Project type:  ${projectType}`);

package/lib/adapters/adapter.js

@@ -147,6 +147,33 @@ class LinterAdapter {
     throw new Error(`${this.id}: buildCommand() not implemented`);
   }
 
+  /**
+   * Optional one-time setup command run in a directory BEFORE linting it —
+   * e.g. `tflint --init` to fetch the ruleset plugins a .tflint.hcl declares.
+   * Without it tflint exits non-zero on an uninitialized plugin. Return null
+   * when no setup is needed (the default for every other adapter).
+   * @param {string} cwd  The directory linting will run in.
+   * @returns {{cmd: string, args: string[], env?: object}|null}
+   */
+  // eslint-disable-next-line no-unused-vars
+  initCommand(cwd) {
+    return null;
+  }
+
+  /** Run initCommand() once per directory, before the first lint there. */
+  _ensureInitialized(cwd) {
+    const spec = this.initCommand(cwd);
+    if (!spec) return;
+    if (!this._initialized) this._initialized = new Set();
+    if (this._initialized.has(cwd)) return;
+    this._initialized.add(cwd);
+    spawnSync(spec.cmd, spec.args, {
+      cwd,
+      env: spec.env ? { ...process.env, ...spec.env } : process.env,
+      encoding: 'utf8',
+    });
+  }
+
   // --- override: output parsing ---
   /**
    * @param {string} stdout
@@ -178,6 +205,7 @@ class LinterAdapter {
   lint(targets, opts = {}) {
     const spec = this.buildCommand(targets, opts);
     this._runCwd = spec.cwd || this.projectRoot;
+    this._ensureInitialized(this._runCwd);
     const result = spawnSync(spec.cmd, spec.args, {
       cwd: this._runCwd,
       env: spec.env ? { ...process.env, ...spec.env } : process.env,

package/lib/adapters/eslint.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 const { LinterAdapter } = require('./adapter');
 const { createViolation, SEVERITY } = require('../violation');
@@ -58,6 +59,19 @@ class EslintAdapter extends LinterAdapter {
     return ESLINT_CONFIG_FILES;
   }
 
+  /**
+   * Tighter than the base detect(): a bare `package.json` is NOT sufficient —
+   * a devDependencies-only tooling manifest is not a JS app. Require an ESLint
+   * config file, or actual JS/TS source under the directory.
+   */
+  detect(dir) {
+    if (!dir || !fs.existsSync(dir)) return false;
+    for (const name of ESLINT_CONFIG_FILES) {
+      if (fs.existsSync(path.join(dir, name))) return true;
+    }
+    return this._scanForSource(dir, 5);
+  }
+
   buildCommand(targets, opts = {}) {
     const args = ['--format=json'];
     if (opts.fix) args.push('--fix');

package/lib/adapters/tflint.js

@@ -7,10 +7,17 @@ const { createViolation, SEVERITY } = require('../violation');
 
 // tflint adapter. tflint is the de-facto Terraform/OpenTofu linter; it emits a
 // machine-readable report under `--format json`. Terraform has no manifest
-// file — a directory of *.tf (or *.tofu) IS the module — so detection here is
+// file — a directory of *.tf (or *.tofu) IS the module — so detection is
 // extension-based. tflint is module-scoped: it lints the .tf files of one
-// directory, so the adapter resolves and runs inside that directory, mirroring
-// the crate/module handling in the Clippy and golangci-lint adapters.
+// directory, so the adapter resolves and runs inside that directory.
+//
+// tflint's bundled `terraform` ruleset is a universal, provider-independent
+// baseline — it lints ANY Terraform repo (hyperscaler, on-prem, SaaS, network
+// appliances, local/null/random) with zero config. Provider-specific rulesets
+// (aws/google/azurerm/…) are opt-in and owned entirely by the target repo's
+// own .tflint.hcl. This adapter never names a provider: it always runs core
+// tflint and, when a .tflint.hcl is present, parses it GENERICALLY to drive
+// `--init`, availability checks and ruleset-version tracking.
 
 const TFLINT_CONFIG_FILES = ['.tflint.hcl'];
 
@@ -41,10 +48,12 @@ class TflintAdapter extends LinterAdapter {
     return true;
   }
 
-  // tflint config files double as a detection hint; the real signal is the
-  // presence of *.tf source (see sourceExtensions / project-model.js).
+  // A .tflint.hcl is a hint, not the discovery signal — *.tf source is (see
+  // sourceExtensions / project-model.js). `.terraform.lock.hcl` is NOT listed:
+  // it is a provider-lock file written by `terraform init`, frequently absent,
+  // and no signal that tflint applies.
   get manifestFiles() {
-    return ['.tflint.hcl', '.terraform.lock.hcl'];
+    return ['.tflint.hcl'];
   }
 
   get sourceExtensions() {
@@ -55,6 +64,101 @@ class TflintAdapter extends LinterAdapter {
     return TFLINT_CONFIG_FILES;
   }
 
+  // --- .tflint.hcl introspection (generic — no provider is special-cased) ---
+
+  /** True when the unit directory carries a .tflint.hcl. */
+  _hasConfig(dir) {
+    return fs.existsSync(path.join(dir || this.appRoot, '.tflint.hcl'));
+  }
+
+  /** Enumerate every `plugin "<name>"` block declared in a unit's .tflint.hcl. */
+  _declaredPlugins(dir) {
+    let hcl;
+    try {
+      hcl = fs.readFileSync(path.join(dir || this.appRoot, '.tflint.hcl'), 'utf8');
+    } catch {
+      return [];
+    }
+    const names = [];
+    const re = /plugin\s+"([^"]+)"/g;
+    let m;
+    while ((m = re.exec(hcl)) !== null) names.push(m[1]);
+    return names;
+  }
+
+  /** Cached `tflint --version` output (memoized after any --init has run). */
+  _versionOutput() {
+    if (this._versionOut == null) {
+      const result = this._probe();
+      this._versionOut = `${result.stdout || ''}\n${result.stderr || ''}`;
+      this._versionProbeFailed = Boolean(result.error) || result.status !== 0;
+    }
+    return this._versionOut;
+  }
+
+  // --- init: fetch ruleset plugins a .tflint.hcl declares -------------------
+
+  /**
+   * When the unit carries a .tflint.hcl, tflint requires `tflint --init` to
+   * fetch the declared ruleset plugins before linting — otherwise it exits
+   * non-zero with a plugin error. Run it once per directory (cached by the
+   * base adapter). A repo with no .tflint.hcl gets core linting, no init.
+   */
+  initCommand(cwd) {
+    if (this._hasConfig(cwd)) {
+      return { cmd: this.binary, args: ['--init'] };
+    }
+    return null;
+  }
+
+  // --- availability: agree with what lint() will actually see --------------
+
+  /**
+   * available() must agree with lint(). The binary must run AND every ruleset
+   * plugin the unit's .tflint.hcl declares must resolve. Plugins are fetched
+   * by `tflint --init`, so run it (idempotent, cached) before checking, then
+   * confirm each declared plugin appears in `tflint --version` output. The
+   * bundled `terraform` ruleset ships in the binary and always resolves.
+   */
+  available() {
+    const probe = this._probe();
+    if (probe.error || probe.status !== 0) return false;
+
+    const declared = this._declaredPlugins(this.appRoot).filter(
+      (name) => name !== 'terraform'
+    );
+    if (declared.length === 0) return true;
+
+    this._ensureInitialized(this.appRoot);
+    const installed = this.rulesetVersions();
+    return declared.every((name) => name in installed);
+  }
+
+  // --- version reporting ----------------------------------------------------
+
+  /** The tflint binary version, parsed deliberately from the version line. */
+  version() {
+    const match = this._versionOutput().match(/TFLint version (\d+\.\d+\.\d+)/i);
+    return match ? match[1] : 'unknown';
+  }
+
+  /**
+   * Installed ruleset-plugin versions, as a generic { name: version } map —
+   * one entry per `+ ruleset.<name> (<version>...)` line of `tflint --version`.
+   * No ruleset name is special-cased, so this tracks the bundled `terraform`
+   * ruleset and any provider ruleset a repo opts into, current or future.
+   * @returns {Object<string,string>}
+   */
+  rulesetVersions() {
+    const versions = {};
+    for (const line of this._versionOutput().split('\n')) {
+      // "+ ruleset.terraform (0.7.0, bundled)"  /  "+ ruleset.aws (0.30.0)"
+      const m = line.match(/^\s*\+\s*ruleset\.(\S+)\s*\(\s*([0-9][^,)\s]*)/);
+      if (m) versions[m[1]] = m[2];
+    }
+    return versions;
+  }
+
   buildCommand(targets, opts = {}) {
     const args = ['--format=json'];
     if (opts.fix && this.supportsFix) args.push('--fix');
@@ -77,14 +181,38 @@ class TflintAdapter extends LinterAdapter {
     return { cmd: this.binary, args, cwd };
   }
 
-  parse(stdout) {
+  /**
+   * @param {string} stdout
+   * @param {string} stderr
+   * @param {number|null} code  tflint's exit code.
+   */
+  parse(stdout, stderr, code) {
     const text = (stdout || '').trim();
-    if (!text) return [];
+    let report = null;
+    if (text) {
+      try {
+        report = JSON.parse(text);
+      } catch {
+        report = null;
+      }
+    }
 
-    let report;
-    try {
-      report = JSON.parse(text);
-    } catch {
+    // A non-zero exit with no parseable JSON is a hard failure — an
+    // uninitialized ruleset plugin, a broken config, an unusable binary. It
+    // must be LOUD: emit a synthetic high-severity violation carrying the
+    // stderr text, never let a failed run be recorded as a clean baseline.
+    if (!report) {
+      if (code != null && code !== 0) {
+        return [
+          createViolation({
+            file: '',
+            ruleId: 'tflint-error',
+            severity: SEVERITY.ERROR,
+            message: `tflint exited ${code}: ${(stderr || '').trim() || 'no output'}`,
+            source: 'tflint',
+          }),
+        ];
+      }
       return [];
     }
 

package/lib/baseline-store.js

@@ -65,19 +65,29 @@ function buildFingerprintMap(violations) {
  * @param {string} [meta.toolVersion]
  * @param {string} [meta.configHash]
  * @param {string} [meta.status] One of STATUS; defaults based on violations.
+ * @param {Object<string,string>} [meta.rulesetVersions] Per-ruleset-plugin
+ *   versions (e.g. tflint). A loose .tflint.hcl version constraint lets a
+ *   plugin update without the config text changing, so neither config_hash
+ *   nor tool_version moves — this map is what makes that rule change visible.
  */
 function createLinterSection(violations, meta = {}) {
   const list = violations || [];
   const fingerprints = buildFingerprintMap(list);
   const status =
     meta.status || (list.length > 0 ? STATUS.BASELINED : STATUS.CLEAN);
-  return {
+  const section = {
     tool_version: meta.toolVersion || 'unknown',
     config_hash: meta.configHash || 'unknown',
     status,
     total: list.length,
     fingerprints,
   };
+  // Only present for linters with ruleset plugins — kept off every other
+  // section so the baseline format stays unchanged for them.
+  if (meta.rulesetVersions && Object.keys(meta.rulesetVersions).length) {
+    section.ruleset_versions = meta.rulesetVersions;
+  }
+  return section;
 }
 
 /** A fresh, empty baseline object. */

package/lib/baseline.js

@@ -102,9 +102,16 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
       }
     }
 
+    // Ruleset-plugin versions, when the adapter tracks them (e.g. tflint).
+    const rulesetVersions =
+      typeof adapter.rulesetVersions === 'function'
+        ? adapter.rulesetVersions()
+        : undefined;
+
     const section = baselineStore.createLinterSection(violations, {
       toolVersion: adapter.version(),
       configHash: await configHashFor(projectRoot, unit.root, adapter),
+      rulesetVersions,
       status: opts.noBaseline ? baselineStore.STATUS.CLEAN : undefined,
     });
     baselineStore.setLinterSection(baseline, linterId, section);
@@ -114,6 +121,7 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
       total: section.total,
       toolVersion: section.tool_version,
       configHash: section.config_hash,
+      rulesetVersions: section.ruleset_versions,
     });
   }
 

package/lib/config-manager.js

@@ -38,9 +38,49 @@ async function detectProjectType(projectRoot) {
   return 'unknown';
 }
 
+// Config-file lookup order. The .gtl/ location is canonical — the config
+// travels with the committed .gtl/ baselines and keeps gimme-the-lint's own
+// files in one place. The repo-root location is retained as a fallback so
+// projects created before this layout keep working with no change.
+const CONFIG_CANDIDATES = [
+  ['.gtl', 'config.cjs'],
+  ['.gtl', 'config.js'],
+  ['gimme-the-lint.config.cjs'],
+  ['gimme-the-lint.config.js'],
+];
+
+/** Absolute path of the project's gimme-the-lint config, or null if none. */
+function findConfig(projectRoot) {
+  for (const parts of CONFIG_CANDIDATES) {
+    const candidate = path.join(projectRoot, ...parts);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** Is the target project ESM ("type": "module" in package.json)? */
+async function isESMProject(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (await fs.pathExists(pkgPath)) {
+    try {
+      return JSON.parse(await fs.readFile(pkgPath, 'utf8')).type === 'module';
+    } catch {
+      /* unreadable package.json — treat as CommonJS */
+    }
+  }
+  return false;
+}
+
+/**
+ * Where a NEW config is written — the canonical .gtl/ location. ESM projects
+ * get a .cjs extension so `require()` of the CommonJS config still works.
+ */
+async function newConfigPath(projectRoot) {
+  const esm = await isESMProject(projectRoot);
+  return path.join(projectRoot, '.gtl', esm ? 'config.cjs' : 'config.js');
+}
+
 function getConfig(projectRoot) {
-  const cjsPath = path.join(projectRoot, 'gimme-the-lint.config.cjs');
-  const jsPath = path.join(projectRoot, 'gimme-the-lint.config.js');
   const defaults = {
     frontendDir: 'frontend',
     backendDir: 'backend',
@@ -52,7 +92,7 @@ function getConfig(projectRoot) {
     testExcludedBackend: ['tests', '*test*', '__pycache__'],
   };
 
-  const configPath = fs.existsSync(cjsPath) ? cjsPath : fs.existsSync(jsPath) ? jsPath : null;
+  const configPath = findConfig(projectRoot);
   if (configPath) {
     try {
       const userConfig = require(configPath);
@@ -66,26 +106,19 @@ function getConfig(projectRoot) {
 }
 
 async function initConfig(projectRoot, options = {}) {
-  const cjsPath = path.join(projectRoot, 'gimme-the-lint.config.cjs');
-  const jsPath = path.join(projectRoot, 'gimme-the-lint.config.js');
+  const existing = findConfig(projectRoot);
 
-  // Don't overwrite if either variant already exists
-  if (!options.force && (await fs.pathExists(cjsPath) || await fs.pathExists(jsPath))) {
-    const existing = await fs.pathExists(cjsPath) ? cjsPath : jsPath;
+  // Don't overwrite an existing config (wherever it lives).
+  if (!options.force && existing) {
     return { created: false, path: existing };
   }
 
-  // Detect if the target project uses ESM ("type": "module" in package.json)
-  let isESM = false;
-  const pkgPath = path.join(projectRoot, 'package.json');
-  if (await fs.pathExists(pkgPath)) {
-    try {
-      const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
-      isESM = pkg.type === 'module';
-    } catch {}
-  }
+  // New config → the canonical .gtl/ location. --force overwrites in place,
+  // so a legacy repo-root config is never silently shadowed by a .gtl/ one.
+  const configPath = existing && options.force
+    ? existing
+    : await newConfigPath(projectRoot);
 
-  const configPath = isESM ? cjsPath : jsPath;
   const projectType = await detectProjectType(projectRoot);
   const config = {
     projectType,
@@ -100,36 +133,26 @@ async function initConfig(projectRoot, options = {}) {
 module.exports = ${JSON.stringify(config, null, 2)};
 `;
 
+  await fs.ensureDir(path.dirname(configPath));
   await fs.writeFile(configPath, content, 'utf8');
   return { created: true, path: configPath, projectType };
 }
 
 /**
- * Write an explicit `apps` map into gimme-the-lint.config.js so the discovered
- * app/linter layout is visible and editable instead of silently re-guessed on
- * every run. Never overwrites an existing config.
+ * Write an explicit `apps` map into the gimme-the-lint config so the
+ * discovered app/linter layout is visible and editable instead of silently
+ * re-guessed on every run. Never overwrites an existing config; a new one is
+ * written to the canonical .gtl/ location.
  * @param {string} projectRoot
  * @param {{appPath: string, linters: string[]}[]} apps
  */
 async function writeAppsConfig(projectRoot, apps) {
-  const cjsPath = path.join(projectRoot, 'gimme-the-lint.config.cjs');
-  const jsPath = path.join(projectRoot, 'gimme-the-lint.config.js');
-  if ((await fs.pathExists(cjsPath)) || (await fs.pathExists(jsPath))) {
-    return {
-      created: false,
-      path: (await fs.pathExists(cjsPath)) ? cjsPath : jsPath,
-    };
-  }
-
-  let isESM = false;
-  const pkgPath = path.join(projectRoot, 'package.json');
-  if (await fs.pathExists(pkgPath)) {
-    try {
-      isESM = JSON.parse(await fs.readFile(pkgPath, 'utf8')).type === 'module';
-    } catch {}
+  const existing = findConfig(projectRoot);
+  if (existing) {
+    return { created: false, path: existing };
   }
-  const configPath = isESM ? cjsPath : jsPath;
 
+  const configPath = await newConfigPath(projectRoot);
   const appsObj = {};
   for (const app of apps || []) {
     appsObj[app.appPath] = { linters: app.linters };
@@ -139,6 +162,7 @@ async function writeAppsConfig(projectRoot, apps) {
 // Edit this map to correct any mis-discovered apps or linters.
 module.exports = ${JSON.stringify({ apps: appsObj }, null, 2)};
 `;
+  await fs.ensureDir(path.dirname(configPath));
   await fs.writeFile(configPath, content, 'utf8');
   return { created: true, path: configPath, apps: appsObj };
 }
@@ -146,6 +170,7 @@ module.exports = ${JSON.stringify({ apps: appsObj }, null, 2)};
 module.exports = {
   copyTemplate,
   detectProjectType,
+  findConfig,
   getConfig,
   initConfig,
   writeAppsConfig,

package/lib/drift.js

@@ -89,6 +89,34 @@ async function detectDrift(projectRoot) {
             to: currentVersion,
           });
         }
+
+        // Ruleset-plugin drift — a plugin updated (e.g. `tflint --init` pulled
+        // a newer ruleset under a loose version constraint) without the config
+        // file text or the binary version changing. Generic over plugin names.
+        if (
+          typeof adapter.rulesetVersions === 'function' &&
+          rec.ruleset_versions
+        ) {
+          const current = adapter.rulesetVersions();
+          const names = new Set([
+            ...Object.keys(rec.ruleset_versions),
+            ...Object.keys(current),
+          ]);
+          for (const name of names) {
+            const from = rec.ruleset_versions[name];
+            const to = current[name];
+            if (from !== to) {
+              linterDrift.push({
+                app: app.appPath,
+                linter: linterId,
+                type: 'ruleset',
+                ruleset: name,
+                from: from || 'absent',
+                to: to || 'absent',
+              });
+            }
+          }
+        }
       }
     }
   }
@@ -126,6 +154,10 @@ function formatDriftReport(drift) {
       lines.push(`  ~ ${d.app} · ${d.linter}: config changed`);
     } else if (d.type === 'version') {
       lines.push(`  ~ ${d.app} · ${d.linter}: ${d.from} → ${d.to}`);
+    } else if (d.type === 'ruleset') {
+      lines.push(
+        `  ~ ${d.app} · ${d.linter}: ruleset ${d.ruleset} ${d.from} → ${d.to}`
+      );
     } else if (d.type === 'new-linter') {
       lines.push(`  + ${d.app}: new linter ${d.linter}`);
     }
@@ -133,6 +165,12 @@ function formatDriftReport(drift) {
   if (drift.hasTimeDrift) {
     lines.push(`  ! baseline is ${drift.ageDays} days old (consider refreshing)`);
   }
+  if (drift.linterDrift && drift.linterDrift.some((d) => d.type === 'ruleset')) {
+    lines.push(
+      '  → a ruleset plugin changed; if rules were renamed, run: ' +
+        'gimme-the-lint migrate --rules'
+    );
+  }
   return lines.join('\n');
 }
 

package/lib/gtl-manifest.js

@@ -68,12 +68,18 @@ function buildManifest(unitResults) {
     const linters = {};
     for (const section of unit.sections || []) {
       if (section.status === 'no-code') continue;
-      linters[section.linter] = {
+      const entry = {
         status: section.status,
         tool_version: section.toolVersion || 'unknown',
         config_hash: section.configHash || 'unknown',
         total: section.total || 0,
       };
+      // Carried only for linters with ruleset plugins (e.g. tflint), so drift
+      // detection can see a plugin update that left config_hash untouched.
+      if (section.rulesetVersions) {
+        entry.ruleset_versions = section.rulesetVersions;
+      }
+      linters[section.linter] = entry;
     }
     manifest.apps[unit.appPath] = { linters };
   }

package/lib/index.js

@@ -2,7 +2,6 @@
 
 const directoryDiscovery = require('./directory-discovery');
 const manifestManager = require('./manifest-manager');
-const driftDetector = require('./drift-detector');
 const venvManager = require('./venv-manager');
 const configManager = require('./config-manager');
 const gitHooksManager = require('./git-hooks-manager');
@@ -26,7 +25,6 @@ const migrate = require('./migrate');
 module.exports = {
   directoryDiscovery,
   manifestManager,
-  driftDetector,
   venvManager,
   configManager,
   gitHooksManager,

package/lib/installer.js

@@ -33,7 +33,11 @@ async function init(projectRoot, options = {}) {
     frontendDir: options.frontendDir,
     backendDir: options.backendDir,
   });
-  results.steps.push(configResult.created ? `Created ${path.basename(configResult.path)}` : 'Config already exists');
+  results.steps.push(
+    configResult.created
+      ? `Created ${path.relative(projectRoot, configResult.path)}`
+      : `Config already exists (${path.relative(projectRoot, configResult.path)})`
+  );
 
   // Step 3: Copy ESLint template (frontend)
   if (enableFrontend) {

package/lib/manifest-manager.js

@@ -2,57 +2,21 @@
 
 const fs = require('fs-extra');
 const crypto = require('crypto');
-const path = require('path');
 
+// Retained from v1 for hashFile() ONLY — its live consumer is baseline.js,
+// which hashes each linter's config file to detect config drift. The v1
+// manifest functions (createManifest / readManifest / writeManifest /
+// calculateAge) were removed in the v2.3.0 tflint audit: the v2 global
+// manifest is owned by gtl-manifest.js and drift by drift.js, which supersede
+// the old single-file `.baseline-manifest.json` model entirely.
+
+/** md5 of a file's contents, or "unknown" when the file is absent. */
 async function hashFile(filePath) {
-  if (!await fs.pathExists(filePath)) {
+  if (!(await fs.pathExists(filePath))) {
     return 'unknown';
   }
   const content = await fs.readFile(filePath, 'utf8');
   return crypto.createHash('md5').update(content).digest('hex');
 }
 
-function calculateAge(createdAt) {
-  const created = new Date(createdAt);
-  const now = new Date();
-  return Math.floor((now - created) / (1000 * 60 * 60 * 24));
-}
-
-async function createManifest({ tool, version, directories, violations, configPath, testExcluded }) {
-  const configHash = await hashFile(configPath);
-
-  return {
-    created_at: new Date().toISOString(),
-    tool,
-    version,
-    directories_baselined: directories,
-    total_directories: directories.length,
-    total_violations: violations,
-    config_hash: configHash,
-    test_excluded: testExcluded || [],
-  };
-}
-
-async function readManifest(manifestPath) {
-  if (!await fs.pathExists(manifestPath)) {
-    return null;
-  }
-  try {
-    return await fs.readJson(manifestPath);
-  } catch {
-    return null;
-  }
-}
-
-async function writeManifest(manifestPath, manifest) {
-  await fs.ensureDir(path.dirname(manifestPath));
-  await fs.writeJson(manifestPath, manifest, { spaces: 2 });
-}
-
-module.exports = {
-  hashFile,
-  calculateAge,
-  createManifest,
-  readManifest,
-  writeManifest,
-};
+module.exports = { hashFile };

package/lib/migrate.js

@@ -5,6 +5,11 @@ const path = require('path');
 const { runBaseline } = require('./baseline');
 const projectModel = require('./project-model');
 const configManager = require('./config-manager');
+const { resolveUnits } = require('./units');
+const adapters = require('./adapters');
+const baselineStore = require('./baseline-store');
+const { fingerprint } = require('./fingerprint');
+const ruleAliases = require('./rule-aliases');
 
 // Migration from the v1 layout (.lttf/ + .lttf-ruff/ per-directory baselines)
 // to the v2 .gtl/ layout. v1 baseline files hold per-directory violation data
@@ -114,9 +119,133 @@ async function migrate(projectRoot, opts = {}) {
   };
 }
 
+/**
+ * Reconcile one linter section's fingerprint map against a fresh lint run,
+ * rewriting renamed rules through the alias map.
+ *  - a baselined violation still occurring under the same rule  → kept
+ *  - a baselined violation now occurring under a RENAMED rule    → fingerprint
+ *    rewritten old→new, count (the grandfather) preserved
+ *  - a baselined violation no longer occurring (fixed, or its rule removed)
+ *                                                                → dropped
+ *  - a genuinely new violation (occurs now, never baselined under any name)
+ *                                                                → NOT added,
+ *    so it still blocks
+ * @returns {{fingerprints, total, renamed, dropped}}
+ */
+function reconcileFingerprints(baselineFps, current, aliases) {
+  // newRuleId → [oldRuleId, …]
+  const reverse = {};
+  for (const [oldId, newId] of Object.entries(aliases)) {
+    if (newId) (reverse[newId] = reverse[newId] || []).push(oldId);
+  }
+
+  const result = {};
+  const renamed = [];
+  const claimed = new Set();
+
+  for (const v of current || []) {
+    const fp = fingerprint(v);
+    if (baselineFps[fp] != null) {
+      result[fp] = baselineFps[fp];
+      claimed.add(fp);
+      continue;
+    }
+    // v.ruleId may be the NEW name of a violation baselined under an OLD name.
+    for (const oldId of reverse[v.ruleId] || []) {
+      const oldFp = fingerprint({ ...v, ruleId: oldId });
+      if (baselineFps[oldFp] != null && !claimed.has(oldFp)) {
+        result[fp] = baselineFps[oldFp];
+        claimed.add(oldFp);
+        renamed.push({ from: oldId, to: v.ruleId });
+        break;
+      }
+    }
+    // Unmatched current violation → genuinely new → left out of the baseline.
+  }
+
+  const dropped = [];
+  for (const [fp, count] of Object.entries(baselineFps)) {
+    if (!claimed.has(fp)) dropped.push({ fingerprint: fp, count });
+  }
+
+  const total = Object.values(result).reduce((sum, n) => sum + n, 0);
+  return { fingerprints: result, total, renamed, dropped };
+}
+
+/**
+ * Rule-rename / rule-removal migration (`migrate --rules`). Re-lints every
+ * unit and rewrites its baseline fingerprints through the per-linter alias
+ * map. Distinct from the v1→v2 layout migration: this touches only the
+ * fingerprint maps inside existing .gtl baselines.
+ * @returns {{migrated: boolean, units: object[]}}
+ */
+async function migrateRules(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const units = resolveUnits(root);
+  const reports = [];
+
+  for (const unit of units) {
+    const baseline = await baselineStore.readBaseline(unit.baselinePath);
+    if (!baseline) continue;
+    let changed = false;
+    const unitReport = { app: unit.appPath, linters: [] };
+
+    for (const linterId of unit.linters) {
+      const aliases = ruleAliases.getAliases(linterId);
+      if (!aliases || Object.keys(aliases).length === 0) continue;
+
+      const section = baselineStore.getLinterSection(baseline, linterId);
+      if (!section || !section.fingerprints) continue;
+
+      let adapter;
+      try {
+        adapter = adapters.getAdapter(linterId, {
+          projectRoot: root,
+          appRoot: unit.root,
+        });
+      } catch {
+        continue;
+      }
+      if (!adapter.detect(unit.root) || !adapter.available()) continue;
+
+      let current;
+      try {
+        current = adapter.lint([unit.appPath], {});
+      } catch {
+        continue;
+      }
+      // A re-lint that surfaced its own failure (a synthetic *-error
+      // violation) is not trustworthy ground truth — never let it drive a
+      // baseline rewrite, or real grandfathered violations would be dropped.
+      if (current.some((v) => /-error$/.test(v.ruleId) && !v.file)) continue;
+
+      const rec = reconcileFingerprints(section.fingerprints, current, aliases);
+      if (rec.renamed.length === 0 && rec.dropped.length === 0) continue;
+
+      section.fingerprints = rec.fingerprints;
+      section.total = rec.total;
+      changed = true;
+      unitReport.linters.push({
+        linter: linterId,
+        renamed: rec.renamed,
+        dropped: rec.dropped.length,
+      });
+    }
+
+    if (changed) {
+      await baselineStore.writeBaseline(unit.baselinePath, baseline);
+      reports.push(unitReport);
+    }
+  }
+
+  return { migrated: reports.length > 0, units: reports };
+}
+
 module.exports = {
   LEGACY_DIR_NAMES,
   findLegacyDirs,
   detectLegacy,
   migrate,
+  migrateRules,
+  reconcileFingerprints,
 };

package/lib/project-model.js

@@ -69,6 +69,61 @@ function matchesAny(name, patterns) {
   return patterns.some((pattern) => globToRegExp(pattern).test(name));
 }
 
+// package.json is a CONDITIONAL eslint marker — bound only when the directory
+// looks like a real JS app, never on the filename alone. A devDependencies-
+// only, "private": true, source-free package.json (one that merely pins a
+// tooling dependency) must not be mistaken for a lintable JS application.
+const JS_APP_PKG_FIELDS = ['dependencies', 'main', 'exports', 'bin', 'module', 'workspaces'];
+const JS_SOURCE_EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'];
+const ESLINT_BIOME_CONFIG_FILES = new Set([
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
+  '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml',
+  'biome.json', 'biome.jsonc',
+]);
+
+/** Recursively look for JS/TS source under a directory (bounded, skips noise). */
+function hasJsSource(absDir, depth = 3) {
+  if (depth < 0) return false;
+  let entries;
+  try {
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const e of entries) {
+    if (e.isFile() && JS_SOURCE_EXTENSIONS.some((ext) => e.name.endsWith(ext))) {
+      return true;
+    }
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+    if (hasJsSource(path.join(absDir, e.name), depth - 1)) return true;
+  }
+  return false;
+}
+
+/** Does this directory look like a real, lintable JS app (not just tooling)? */
+function looksLikeJsApp(absDir, entries) {
+  // An ESLint / Biome config file is unambiguous.
+  for (const e of entries) {
+    if (e.isFile() && ESLINT_BIOME_CONFIG_FILES.has(e.name)) return true;
+  }
+  // A package.json with app-shaped fields — runtime dependencies, an entry
+  // point, or a workspace declaration — is a real app. devDependencies alone
+  // (a tooling-only manifest) is not.
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(absDir, 'package.json'), 'utf8')
+    );
+    if (JS_APP_PKG_FIELDS.some((field) => pkg[field] != null)) return true;
+  } catch {
+    // Unreadable / invalid package.json — fall through to the source scan.
+  }
+  // Otherwise bind eslint only if there is actual JS/TS source under the dir.
+  return hasJsSource(absDir);
+}
+
 /** Every directory (relative to root) that holds at least one known manifest. */
 function findManifestDirs(projectRoot) {
   const found = [];
@@ -84,8 +139,14 @@ function findManifestDirs(projectRoot) {
 
     const linters = new Set();
     for (const entry of entries) {
-      if (entry.isFile() && MANIFEST_LINTERS[entry.name]) {
-        linters.add(MANIFEST_LINTERS[entry.name]);
+      if (!entry.isFile()) continue;
+      const linter = MANIFEST_LINTERS[entry.name];
+      if (!linter) continue;
+      if (entry.name === 'package.json') {
+        // Conditional: only a real JS app, never a tooling-only manifest.
+        if (looksLikeJsApp(absDir, entries)) linters.add('eslint');
+      } else {
+        linters.add(linter);
       }
     }
     if (hasTerraformSource(entries)) linters.add('tflint');

package/lib/rule-aliases.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// Per-linter rule-alias maps for rule-rename / rule-removal migration.
+//
+// fingerprint() folds ruleId into a violation's identity (deliberately — two
+// different rules on the same line are distinct problems). So when an upstream
+// linter RENAMES a rule, the baselined fingerprint is orphaned and the renamed
+// rule blocks as a "new" violation; when a linter REMOVES a rule, a stale
+// baseline entry lingers and inflates `total`.
+//
+// `gimme-the-lint migrate --rules` re-lints each unit and uses these maps to
+// rewrite a renamed rule's stored fingerprint old→new (preserving the
+// grandfather) and to drop entries for rules that no longer occur.
+//
+//   oldRuleId: 'newRuleId'   — the rule was renamed
+//   oldRuleId: null          — the rule was removed
+//
+// These are DATA, not code — extend a map as an upstream linter changes its
+// rule ids. Every map is empty by default: nothing is migrated until an entry
+// exists, so the mechanism is inert until a real rename is recorded.
+
+const RULE_ALIASES = {
+  eslint: {},
+  biome: {},
+  ruff: {},
+  'golangci-lint': {},
+  clippy: {},
+  tflint: {},
+  'ansible-lint': {},
+};
+
+/** The alias map for a linter ({} when the linter has none). */
+function getAliases(linterId) {
+  return RULE_ALIASES[linterId] || {};
+}
+
+/** Register or extend a linter's alias map (used by updates and tests). */
+function registerAliases(linterId, aliases) {
+  RULE_ALIASES[linterId] = { ...(RULE_ALIASES[linterId] || {}), ...aliases };
+}
+
+module.exports = { RULE_ALIASES, getAliases, registerAliases };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theglitchking/gimme-the-lint",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Polyglot progressive linting for monorepos — adapter-driven baselines, per-app drift detection, and idempotent skips across JavaScript/TypeScript, Python, Go, Rust, Terraform, and Ansible.",
   "keywords": [
     "linting",

package/lib/drift-detector.js

@@ -1,92 +0,0 @@
-'use strict';
-
-const manifestManager = require('./manifest-manager');
-
-async function detectDrift({ manifestPath, configPath, currentDirs }) {
-  const manifest = await manifestManager.readManifest(manifestPath);
-  if (!manifest) {
-    return { noManifest: true, message: 'No manifest found - run baseline first' };
-  }
-
-  const drift = {
-    hasDirectoryDrift: false,
-    hasConfigDrift: false,
-    hasTimeDrift: false,
-    hasViolationDrift: false,
-    addedDirs: [],
-    removedDirs: [],
-    age: 0,
-    details: [],
-  };
-
-  const baselineDirs = manifest.directories_baselined || [];
-  drift.addedDirs = currentDirs.filter((d) => !baselineDirs.includes(d));
-  drift.removedDirs = baselineDirs.filter((d) => !currentDirs.includes(d));
-  drift.hasDirectoryDrift = drift.addedDirs.length > 0 || drift.removedDirs.length > 0;
-
-  if (drift.addedDirs.length > 0) {
-    drift.details.push(`Added directories: ${drift.addedDirs.join(', ')}`);
-  }
-  if (drift.removedDirs.length > 0) {
-    drift.details.push(`Removed directories: ${drift.removedDirs.join(', ')}`);
-  }
-
-  const currentHash = await manifestManager.hashFile(configPath);
-  drift.hasConfigDrift = currentHash !== 'unknown' && currentHash !== manifest.config_hash;
-  if (drift.hasConfigDrift) {
-    drift.details.push('Configuration changed (config file hash mismatch)');
-  }
-
-  drift.age = manifestManager.calculateAge(manifest.created_at);
-  drift.hasTimeDrift = drift.age > 30;
-  if (drift.hasTimeDrift) {
-    drift.details.push(`Baseline is ${drift.age} days old (consider refreshing)`);
-  }
-
-  return drift;
-}
-
-function formatDriftReport(drift) {
-  if (drift.noManifest) {
-    return drift.message;
-  }
-
-  const hasDrift = drift.hasDirectoryDrift || drift.hasConfigDrift || drift.hasTimeDrift;
-  if (!hasDrift) {
-    return null;
-  }
-
-  const lines = ['Drift Detected:'];
-  for (const detail of drift.details) {
-    lines.push(`  - ${detail}`);
-  }
-  return lines.join('\n');
-}
-
-async function autoHeal({ manifestPath, configPath, currentDirs, tool, version, currentViolations, testExcluded }) {
-  const oldManifest = await manifestManager.readManifest(manifestPath);
-
-  const newManifest = await manifestManager.createManifest({
-    tool,
-    version,
-    directories: currentDirs,
-    violations: currentViolations,
-    configPath,
-    testExcluded,
-  });
-
-  await manifestManager.writeManifest(manifestPath, newManifest);
-
-  return {
-    oldDirs: oldManifest ? oldManifest.directories_baselined : [],
-    newDirs: currentDirs,
-    oldViolations: oldManifest ? oldManifest.total_violations : 0,
-    newViolations: currentViolations,
-  };
-}
-
-module.exports = {
-  detectDrift,
-  formatDriftReport,
-  autoHeal,
-};