@theglitchking/gimme-the-lint 2.1.0 → 2.3.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.1.0"
+    "version": "2.3.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, and Terraform.",
-      "version": "2.1.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.",
+      "version": "2.3.0",
       "author": {
         "name": "TheGlitchKing"
       },
@@ -32,6 +32,7 @@
         "clippy",
         "tflint",
         "terraform",
+        "ansible-lint",
         "claude-code"
       ],
       "category": "productivity",

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, and Terraform.",
-  "version": "2.1.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.",
+  "version": "2.3.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"
@@ -21,6 +21,7 @@
     "golangci-lint",
     "clippy",
     "tflint",
-    "terraform"
+    "terraform",
+    "ansible-lint"
   ]
 }

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.3.0] - 2026-05-17
+
+### Fixed
+- **Bug A — monorepo linter binary resolution.** The ESLint and Biome adapters
+  resolved `node_modules/.bin/<linter>` only at the repo root, so in a monorepo
+  (where each JS app carries its own `node_modules`) `available()` returned
+  false and the linter was silently skipped — capturing an empty baseline.
+  Adapters now resolve the binary app-dir-first (app → repo root → PATH) and
+  run inside the app directory so the app's own flat config is discovered. The
+  Ruff adapter resolves its `.venv` the same way.
+- **Bug B — discovery bound the wrong directories.** Manifest discovery treated
+  a bare `requirements.txt` as a ruff app marker (binding nested load-test and
+  utility dirs) and discarded a repo-root config whenever any nested manifest
+  existed (leaving the real app unbound). `requirements.txt` is no longer a
+  discovery marker — `pyproject.toml`, `ruff.toml`, `.ruff.toml` and `setup.py`
+  are — and workspace-root detection is now **per linter**, so a repo-root
+  `[tool.ruff]` config binds the root even when nested `package.json` apps sit
+  below it.
+- **Bug C — "couldn't run" collapsed into "skipped".** An unavailable or
+  errored linter was recorded with the status used for "no code here", making
+  an incomplete baseline indistinguishable from a clean one — every
+  pre-existing violation later counted as new and blocked the commit. New
+  baseline statuses `unavailable` and `error` keep incomplete baselines
+  distinct; `migrate` and `baseline` print a prominent summary and exit
+  non-zero (override with `--allow-incomplete`); `hooks` refuses to install
+  against an incomplete baseline (override with `--force`); `check` reports
+  `needs-baseline` instead of flooding new violations.
+
+### Added
+- `migrate` now writes the discovered app/linter layout into
+  `gimme-the-lint.config.js` as an explicit `apps` map, so the guess is visible
+  and editable instead of silently re-derived on every run. It also emits a
+  warning when the layout is ambiguous (a repo-root config plus nested apps).
+
+## [2.2.0] - 2026-05-17
+
+### Added
+- **Ansible support** via a new `ansible-lint` adapter. ansible-lint plugs into
+  the progressive-lint engine like every other linter: it runs
+  `ansible-lint -f codeclimate`, parses the CodeClimate JSON report, and only
+  new violations block. Supports `--fix`.
+- **Manifest-based discovery** for Ansible: a directory containing `ansible.cfg`
+  or `galaxy.yml` is auto-discovered and bound to `ansible-lint`. Ansible
+  playbooks are plain YAML with no manifest, so detection keys off those
+  unambiguous markers rather than a file extension (a YAML scan would match
+  nearly every repo). An Ansible repo with neither marker needs an explicit
+  `apps` entry in `gimme-the-lint.config.js`.
+- **Ansible best-practice config** — `install` seeds `.ansible-lint` with the
+  `moderate` profile (the strictness lever; raise to `safety` / `production`).
+- README now documents every supported codebase with a default-rules summary
+  and the strictness lever for each; `.documentation/lint-rules-guide.md` adds
+  a full Ansible section.
+
 ## [2.1.0] - 2026-05-17
 
 ### Added

package/README.md

@@ -19,7 +19,7 @@ stuff at its own pace; meanwhile no new mess gets in.
 **v2.0** generalizes that idea to any linter and any language. It is no longer
 "ESLint + Ruff for webapps" — it is a progressive-lint **engine** with a
 pluggable **linter adapter** for each tool, across **JavaScript/TypeScript, Python,
-Go, Rust, and Terraform**, in **any monorepo shape**.
+Go, Rust, Terraform, and Ansible**, in **any monorepo shape**.
 
 ---
 
@@ -38,10 +38,10 @@ is ever flagged. (In v1 this job was outsourced to the third-party
 
 Each app is bound to the linters its package manifest implies — `package.json`
 → ESLint, `pyproject.toml` → Ruff, `go.mod` → golangci-lint, `Cargo.toml` →
-Clippy, `biome.json` → Biome. Terraform has no manifest, so a directory of
-`*.tf` / `*.tofu` files binds to tflint by extension. Drift detection runs per
-app, so a config or linter-version change in one app never churns the baselines
-of another.
+Clippy, `biome.json` → Biome, `ansible.cfg` / `galaxy.yml` → ansible-lint.
+Terraform has no manifest, so a directory of `*.tf` / `*.tofu` files binds to
+tflint by extension. Drift detection runs per app, so a config or linter-version
+change in one app never churns the baselines of another.
 
 ---
 
@@ -50,7 +50,7 @@ of another.
 - **Progressive linting** — only new violations block; existing ones are baselined
 - **In-house diff engine** — line/column-independent fingerprints survive code shifts
 - **Pluggable linter adapters** — the choice of linter is config, not a hardcode
-- **Polyglot** — JavaScript/TypeScript, Python, Go, Rust, Terraform out of the box
+- **Polyglot** — JavaScript/TypeScript, Python, Go, Rust, Terraform, Ansible out of the box
 - **Per-app model** — auto-discovers every package in a monorepo; no `frontend/`
   + `backend/` assumption
 - **Per-app drift detection** — app add/remove, config change, linter version, age
@@ -75,21 +75,37 @@ of another.
 | Go | `golangci-lint` | `go.mod` |
 | Rust | `clippy` (`cargo clippy`) | `Cargo.toml` |
 | Terraform / OpenTofu | `tflint` | `*.tf` / `*.tofu` files (no manifest) |
+| Ansible | `ansible-lint` | `ansible.cfg`, `galaxy.yml` |
 
 ## Shipped lint configs
 
 `install` seeds every discovered app with a best-practice ("recommended" tier)
-config for its linter — `eslint.config.js` + `.prettierrc.json`, `biome.json`,
-`pyproject.toml` `[tool.ruff]`, `.golangci.yml`, `clippy.toml` + `Cargo.toml`
-`[lints.clippy]`, `.tflint.hcl` — plus a repo-root `.gitleaks.toml`. Configs are
-**created only if absent**; your own config is never overwritten.
-
-Every shipped config carries a **security layer**: gitleaks scans all files for
-secrets (passwords, SSL/private keys, tokens) and always blocks, while each
-linter adds language-specific security rules (`gosec`, Ruff `S` / flake8-bandit,
-`eslint-plugin-security`, Biome's `security` group). See
-[`.documentation/lint-rules-guide.md`](.documentation/lint-rules-guide.md) for
-the baseline rules per codebase and how to adjust them.
+config for its linter — **created only if absent**, so your own config is never
+overwritten. Each ships a sensible default rule set and a single **lever** to
+dial strictness up or down:
+
+| Codebase | Linter | Default rules (recommended tier) | Strictness lever |
+|----------|--------|----------------------------------|------------------|
+| JS/TS | ESLint | `@eslint/js` + React recommended, import-architecture guards, security plugins, Prettier-compatible | rules block in `eslint.config.js` |
+| JS/TS | Biome | recommended set + full `security` group + console/complexity rules | rule levels in `biome.json` |
+| Python | Ruff | pyflakes / pycodestyle / isort / bugbear / pyupgrade + `S` security + comprehensions / simplify | `select` / `ignore` in `pyproject.toml` |
+| Go | golangci-lint | `standard` set + correctness & quality linters + `gosec` | `linters.enable` in `.golangci.yml` |
+| Rust | Clippy | `pedantic` + `cargo` at `warn`, noisy lints allowed back | `[lints.clippy]` levels in `Cargo.toml` |
+| Terraform | tflint | bundled `terraform` ruleset, `recommended` preset | `preset` in `.tflint.hcl` (`recommended` → `all`) |
+| Ansible | ansible-lint | `moderate` profile | `profile` in `.ansible-lint` (`min` → `production`) |
+| Secrets (all) | gitleaks | default ruleset + key / password rules — **always blocks** | `[allowlist]` in `.gitleaks.toml` |
+
+Every shipped config carries a **security layer**. gitleaks scans every file in
+every codebase for secrets (passwords, SSL/private keys, tokens) and always
+blocks — secrets are never baselined. Each linter adds language-specific
+security rules on top (`gosec`, Ruff `S` / flake8-bandit, `eslint-plugin-security`,
+Biome's `security` group), which follow normal progressive baselining.
+
+To go stricter, pull the lever in the table above — because violations are
+progressively baselined, raising strictness never blocks existing code, only new
+code is held to the higher bar. Full per-codebase detail — every default rule
+and how to adjust it — is in
+[`.documentation/lint-rules-guide.md`](.documentation/lint-rules-guide.md).
 
 ---
 
@@ -284,7 +300,8 @@ lib/
 ├── diff-engine.js      pure diff: new vs baselined vs fixed
 ├── baseline-store.js   one baseline.json format for every linter
 ├── adapters/           one adapter per linter (eslint, biome, ruff,
-│                       golangci-lint, clippy, tflint) + the base contract
+│                       golangci-lint, clippy, tflint, ansible-lint)
+│                       + the base contract
 ├── project-model.js    discovers apps + binds them to linters
 ├── units.js            resolves apps → {dir, linters, baseline path}
 ├── check.js            runCheck: lint → diff → report
@@ -304,7 +321,8 @@ git hooks, GitHub Action and Claude Code plugin are thin front doors over it.
 - **Node.js** >= 20
 - **Git** (for hooks and staged-file detection)
 - A linter for each language you use (`eslint`/`biome`, `ruff`, `golangci-lint`,
-  `clippy`, `tflint`) — any language whose linter is absent is simply skipped
+  `clippy`, `tflint`, `ansible-lint`) — any language whose linter is absent is
+  simply skipped
 
 ## License
 

package/bin/gimme-the-lint.js

@@ -154,6 +154,7 @@ program
   .description('Create or refresh progressive-lint baselines')
   .option('--strict', 'Fail when a linter is missing for code that is present')
   .option('--empty', 'Write empty baselines (greenfield: treat every violation as new)')
+  .option('--allow-incomplete', 'Exit 0 even if some linters could not be baselined')
   .action(async (target, opts) => {
     const chalk = require('chalk');
     const { runBaseline } = require('../lib/baseline');
@@ -166,6 +167,17 @@ program
       });
       console.log(formatBaselineReport(report, process.cwd()));
       console.log('');
+      // A baseline that could not capture a linter is incomplete — fail loudly
+      // rather than reporting success, unless the user opts in.
+      if (report.incomplete && report.incomplete.length && !opts.allowIncomplete) {
+        console.error(
+          chalk.red(
+            `✗ Baseline INCOMPLETE — ${report.incomplete.length} linter(s) not captured. ` +
+              'Install them and re-run, or pass --allow-incomplete.\n'
+          )
+        );
+        process.exit(1);
+      }
     } catch (err) {
       console.error(chalk.red(`\n✗ ${err.message}\n`));
       process.exit(1);
@@ -176,6 +188,7 @@ program
   .command('migrate')
   .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')
   .action(async (opts) => {
     const chalk = require('chalk');
     const { migrate } = require('../lib/migrate');
@@ -188,9 +201,46 @@ program
       console.log(chalk.green('\n✓ Migrated to the v2 .gtl/ layout\n'));
       console.log(`  Legacy baselines backed up: ${result.backedUp.join(', ')}`);
       console.log(chalk.dim(`    → ${result.backupPath}`));
+      if (result.appsConfig && result.appsConfig.created) {
+        console.log(
+          `  Wrote explicit app map → ${path.basename(result.appsConfig.path)}`
+        );
+      }
       console.log(`  Re-baselined ${result.baseline.unitCount} app(s) into .gtl/`);
+      for (const w of result.discoveryWarnings || []) {
+        console.log(chalk.yellow(`  ⚠ ${w}`));
+      }
       console.log('');
-      console.log('Next: review the new .gtl/ directory and commit it.');
+
+      // An incomplete baseline must never be reported as a clean migration.
+      if (result.incomplete && result.incomplete.length) {
+        console.error(
+          chalk.red(`✗ ${result.incomplete.length} linter(s) were NOT baselined:`)
+        );
+        for (const i of result.incomplete) {
+          console.error(chalk.red(`    ${i.app} · ${i.linter} (${i.status})`));
+        }
+        console.error(
+          chalk.yellow(
+            '  The baseline is INCOMPLETE — install the missing linters and run\n' +
+              '  `gimme-the-lint baseline`, then commit .gtl/.'
+          )
+        );
+        if (!opts.allowIncomplete) {
+          console.error(
+            chalk.red(
+              '\n✗ Migration finished with an incomplete baseline ' +
+                '(pass --allow-incomplete to accept).\n'
+            )
+          );
+          process.exit(1);
+        }
+        console.log('');
+      }
+
+      console.log(
+        'Next: review the new .gtl/ directory and gimme-the-lint.config.js, then commit them.'
+      );
       console.log('');
     } catch (err) {
       console.error(chalk.red(`\n✗ Migration failed: ${err.message}\n`));
@@ -210,13 +260,43 @@ program
 program
   .command('hooks')
   .description('Install git hooks for pre-commit linting')
-  .action(async () => {
+  .option('--force', 'Install even when the baseline is incomplete')
+  .action(async (opts) => {
     const chalk = require('chalk');
     const gitHooksManager = require('../lib/git-hooks-manager');
+    const { findIncompleteBaselines } = require('../lib/baseline');
 
     try {
+      // Refuse to gate commits against an incomplete baseline: hooks would
+      // diff against linter sections that were never captured, so every
+      // pre-existing violation would count as new and block the commit.
+      const incomplete = await findIncompleteBaselines(process.cwd());
+      if (incomplete.length && !opts.force) {
+        console.error(
+          chalk.red('\n✗ Refusing to install hooks — the baseline is incomplete:\n')
+        );
+        for (const i of incomplete) {
+          console.error(chalk.red(`    ${i.app} · ${i.linter} (${i.status})`));
+        }
+        console.error(
+          chalk.yellow(
+            '\n  These linters were never baselined, so a pre-commit hook would\n' +
+              '  flag every pre-existing violation as new. Install the missing\n' +
+              '  linters and run `gimme-the-lint baseline`, or pass --force.\n'
+          )
+        );
+        process.exit(1);
+      }
+
       const installed = await gitHooksManager.installHooks(process.cwd());
       console.log(chalk.green(`\n✓ Installed git hooks: ${installed.join(', ')}\n`));
+      if (incomplete.length && opts.force) {
+        console.log(
+          chalk.yellow(
+            '⚠ Installed against an INCOMPLETE baseline (--force) — re-baseline soon.\n'
+          )
+        );
+      }
     } catch (e) {
       console.error(chalk.red(`\n✗ ${e.message}\n`));
       process.exit(1);

package/lib/adapters/adapter.js

@@ -26,8 +26,14 @@ const DEFAULT_IGNORE_DIRS = new Set([
 const SCAN_DEPTH = 5;
 
 class LinterAdapter {
-  constructor({ projectRoot } = {}) {
+  constructor({ projectRoot, appRoot } = {}) {
     this.projectRoot = projectRoot || process.cwd();
+    // appRoot is the directory of the specific app/unit being linted. In a
+    // monorepo each app carries its own node_modules / .venv, so project-local
+    // tool resolution and config discovery must start here — not at the repo
+    // root, which often has neither. Defaults to projectRoot for single-package
+    // projects and for callers that do not supply it.
+    this.appRoot = appRoot || this.projectRoot;
   }
 
   // --- identity (override in subclasses) ---

package/lib/adapters/ansible.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const { LinterAdapter } = require('./adapter');
+const { createViolation, SEVERITY } = require('../violation');
+
+// ansible-lint adapter. ansible-lint is the de-facto linter for Ansible
+// playbooks, roles and collections; `-f codeclimate` emits a machine-readable
+// JSON report. Ansible has no manifest file and playbooks are plain YAML, so
+// detection keys off the unambiguous Ansible markers `ansible.cfg` and
+// `galaxy.yml` — a YAML extension scan would match virtually every repo.
+// ansible-lint auto-discovers playbooks/roles from the directory it runs in.
+
+const ANSIBLE_CONFIG_FILES = ['.ansible-lint', '.config/ansible-lint.yml'];
+
+/** Map an ansible-lint (CodeClimate) severity onto a NormalizedViolation severity. */
+function mapSeverity(severity) {
+  switch (String(severity).toLowerCase()) {
+    case 'info':
+      return SEVERITY.INFO;
+    case 'minor':
+      return SEVERITY.WARNING;
+    case 'major':
+    case 'critical':
+    case 'blocker':
+      return SEVERITY.ERROR;
+    default:
+      return SEVERITY.WARNING;
+  }
+}
+
+class AnsibleLintAdapter extends LinterAdapter {
+  get id() {
+    return 'ansible-lint';
+  }
+
+  get languages() {
+    return ['ansible'];
+  }
+
+  get supportsFix() {
+    return true;
+  }
+
+  get manifestFiles() {
+    return ['ansible.cfg', 'galaxy.yml'];
+  }
+
+  // Ansible source is plain YAML — far too broad to scan by extension, so
+  // detection is manifest-only (see manifestFiles).
+  get sourceExtensions() {
+    return [];
+  }
+
+  configFiles() {
+    return ANSIBLE_CONFIG_FILES;
+  }
+
+  buildCommand(targets, opts = {}) {
+    const args = ['-f', 'codeclimate'];
+    if (opts.fix && this.supportsFix) args.push('--fix');
+    const paths = targets && targets.length ? targets.slice() : ['.'];
+    args.push(...paths);
+    return { cmd: this.binary, args, cwd: opts.cwd || this.projectRoot };
+  }
+
+  parse(stdout) {
+    const text = (stdout || '').trim();
+    if (!text) return [];
+
+    let report;
+    try {
+      report = JSON.parse(text);
+    } catch {
+      return [];
+    }
+    if (!Array.isArray(report)) return [];
+
+    return report.map((issue) => {
+      const loc = issue.location || {};
+      const lines = loc.lines || {};
+      const begin = (loc.positions && loc.positions.begin) || {};
+      // CodeClimate locations come as either { lines: { begin } } or
+      // { positions: { begin: { line, column } } }.
+      let line = lines.begin != null ? lines.begin : begin.line;
+      if (line && typeof line === 'object') line = line.line;
+      return createViolation({
+        file: this._relativize(loc.path || ''),
+        line: Number(line) || 0,
+        col: Number(begin.column) || 0,
+        ruleId: issue.check_name || 'ansible-lint',
+        severity: mapSeverity(issue.severity),
+        message: issue.description || '',
+        source: 'ansible-lint',
+      });
+    });
+  }
+}
+
+module.exports = AnsibleLintAdapter;

package/lib/adapters/biome.js

@@ -38,9 +38,14 @@ class BiomeAdapter extends LinterAdapter {
     return ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'];
   }
 
-  /** Prefer the project-local Biome; fall back to one on PATH. */
+  /**
+   * Prefer the app-local Biome, then the repo-root Biome, then PATH. Each JS
+   * app in a monorepo has its own node_modules; resolving only at projectRoot
+   * makes available() falsely return false for app-installed Biome.
+   */
   get binary() {
     return this.resolveBinary([
+      path.join(this.appRoot, 'node_modules', '.bin', 'biome'),
       path.join(this.projectRoot, 'node_modules', '.bin', 'biome'),
       'biome',
     ]);
@@ -52,9 +57,14 @@ class BiomeAdapter extends LinterAdapter {
 
   buildCommand(targets, opts = {}) {
     const args = ['lint', '--reporter=json'];
-    const list = targets && targets.length ? targets : ['.'];
+    // Run inside the app directory so Biome resolves the app's own biome.json.
+    const cwd = opts.cwd || this.appRoot;
+    const list = (targets && targets.length ? targets : ['.']).map((t) => {
+      const rel = path.relative(cwd, path.resolve(this.projectRoot, t));
+      return rel === '' ? '.' : rel;
+    });
     args.push(...list);
-    return { cmd: this.binary, args, cwd: opts.cwd || this.projectRoot };
+    return { cmd: this.binary, args, cwd };
   }
 
   parse(stdout) {

package/lib/adapters/eslint.js

@@ -40,9 +40,15 @@ class EslintAdapter extends LinterAdapter {
     return ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'];
   }
 
-  /** Prefer the project-local ESLint; fall back to one on PATH. */
+  /**
+   * Prefer the app-local ESLint, then the repo-root ESLint, then PATH. In a
+   * monorepo each JS app has its own node_modules; the repo root often has
+   * none, so resolving only at projectRoot makes available() falsely return
+   * false and the linter gets silently skipped.
+   */
   get binary() {
     return this.resolveBinary([
+      path.join(this.appRoot, 'node_modules', '.bin', 'eslint'),
       path.join(this.projectRoot, 'node_modules', '.bin', 'eslint'),
       'eslint',
     ]);
@@ -55,9 +61,15 @@ class EslintAdapter extends LinterAdapter {
   buildCommand(targets, opts = {}) {
     const args = ['--format=json'];
     if (opts.fix) args.push('--fix');
-    const list = targets && targets.length ? targets : ['.'];
+    // Run inside the app directory so ESLint resolves the app's own flat
+    // config (eslint.config.js) — in a monorepo the repo root often has none.
+    const cwd = opts.cwd || this.appRoot;
+    const list = (targets && targets.length ? targets : ['.']).map((t) => {
+      const rel = path.relative(cwd, path.resolve(this.projectRoot, t));
+      return rel === '' ? '.' : rel;
+    });
     args.push(...list);
-    return { cmd: this.binary, args, cwd: opts.cwd || this.projectRoot };
+    return { cmd: this.binary, args, cwd };
   }
 
   parse(stdout) {

package/lib/adapters/index.js

@@ -7,6 +7,7 @@ const RuffAdapter = require('./ruff');
 const GolangciLintAdapter = require('./golangci-lint');
 const ClippyAdapter = require('./clippy');
 const TflintAdapter = require('./tflint');
+const AnsibleLintAdapter = require('./ansible');
 
 // The adapter registry. `tool` strings in gimme-the-lint.config.js resolve to
 // concrete adapters here. Adding a language to gimme-the-lint means adding one
@@ -19,6 +20,7 @@ const REGISTRY = {
   'golangci-lint': GolangciLintAdapter,
   clippy: ClippyAdapter,
   tflint: TflintAdapter,
+  'ansible-lint': AnsibleLintAdapter,
 };
 
 /** Construct an adapter instance by id. Throws on an unknown id. */

package/lib/adapters/ruff.js

@@ -31,9 +31,10 @@ class RuffAdapter extends LinterAdapter {
     return ['.py', '.pyi'];
   }
 
-  /** Prefer the project venv's Ruff; fall back to one on PATH. */
+  /** Prefer the app venv's Ruff, then the repo-root venv, then PATH. */
   get binary() {
     return this.resolveBinary([
+      path.join(this.appRoot, '.venv', 'bin', 'ruff'),
       path.join(this.projectRoot, '.venv', 'bin', 'ruff'),
       'ruff',
     ]);

package/lib/baseline-store.js

@@ -29,12 +29,25 @@ const { fingerprint } = require('./fingerprint');
 const SCHEMA_VERSION = 2;
 
 // Per-linter status values recorded in each section / the manifest.
+//
+// UNAVAILABLE and ERROR mean the baseline for that linter was NOT captured —
+// they must stay distinct from CLEAN (linter ran, nothing found) and from a
+// genuine empty baseline. A section in either state is an INCOMPLETE baseline:
+// treating it as clean would make every pre-existing violation count as new
+// the first time the linter actually runs.
 const STATUS = Object.freeze({
   BASELINED: 'baselined', // violations captured into the baseline
   CLEAN: 'clean', // linter ran, found nothing to baseline
-  SKIPPED: 'skipped', // code present but linter binary unavailable
+  SKIPPED: 'skipped', // intentionally not baselined (kept for back-compat)
+  UNAVAILABLE: 'unavailable', // code present but the linter binary is missing
+  ERROR: 'error', // the linter applies here but failed to run
 });
 
+/** True when a section's status means the baseline was not actually captured. */
+function isIncompleteStatus(status) {
+  return status === STATUS.UNAVAILABLE || status === STATUS.ERROR;
+}
+
 /** Build a {fingerprint: count} map from a list of NormalizedViolations. */
 function buildFingerprintMap(violations) {
   const map = {};
@@ -109,6 +122,7 @@ async function writeBaseline(baselinePath, baseline) {
 module.exports = {
   SCHEMA_VERSION,
   STATUS,
+  isIncompleteStatus,
   buildFingerprintMap,
   createLinterSection,
   emptyBaseline,

package/lib/baseline.js

@@ -11,6 +11,12 @@ const gtlManifest = require('./gtl-manifest');
 // .gtl/apps/<app>/baseline.json. After this, only NEW violations block.
 // With opts.noBaseline it writes an EMPTY baseline instead — the greenfield
 // "strict from day one" stance (Phase 5).
+//
+// A linter that is unavailable or errors out is recorded with an INCOMPLETE
+// status (unavailable / error), never as a clean baseline — see baseline-store
+// STATUS. runBaseline() surfaces these in `incomplete` so callers (migrate,
+// the baseline CLI, the hooks installer) can refuse to gate commits against a
+// baseline that never actually captured a linter.
 
 /** Hash the first config file found for an adapter (unit root, then project). */
 async function configHashFor(projectRoot, unitRoot, adapter) {
@@ -33,7 +39,10 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
   for (const linterId of unit.linters) {
     let adapter;
     try {
-      adapter = adapters.getAdapter(linterId, { projectRoot });
+      adapter = adapters.getAdapter(linterId, {
+        projectRoot,
+        appRoot: unit.root,
+      });
     } catch (err) {
       sections.push({ linter: linterId, status: 'error', reason: err.message });
       continue;
@@ -44,6 +53,9 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
       continue;
     }
 
+    // Code is present but the linter binary is missing. Under strict/offline
+    // this is a hard failure; otherwise record an UNAVAILABLE section — NOT a
+    // clean one — so downstream knows this baseline was never captured.
     if (!adapter.available()) {
       if (opts.strict) {
         const err = new Error(
@@ -56,13 +68,13 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
         baseline,
         linterId,
         baselineStore.createLinterSection([], {
-          status: baselineStore.STATUS.SKIPPED,
+          status: baselineStore.STATUS.UNAVAILABLE,
         })
       );
       sections.push({
         linter: linterId,
-        status: 'skipped',
-        reason: `${adapter.id} not installed`,
+        status: baselineStore.STATUS.UNAVAILABLE,
+        reason: `${adapter.id} is not installed`,
       });
       continue;
     }
@@ -72,7 +84,20 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
       try {
         violations = adapter.lint([unit.appPath], {});
       } catch (err) {
-        sections.push({ linter: linterId, status: 'error', reason: err.message });
+        // The linter applies here but could not run — record an ERROR section
+        // rather than leaving the baseline silently without this linter.
+        baselineStore.setLinterSection(
+          baseline,
+          linterId,
+          baselineStore.createLinterSection([], {
+            status: baselineStore.STATUS.ERROR,
+          })
+        );
+        sections.push({
+          linter: linterId,
+          status: baselineStore.STATUS.ERROR,
+          reason: err.message,
+        });
         continue;
       }
     }
@@ -101,10 +126,29 @@ async function baselineUnit(projectRoot, unit, opts = {}) {
   };
 }
 
+/** Collect every incomplete (unavailable/errored) section from unit results. */
+function collectIncomplete(unitResults) {
+  const incomplete = [];
+  for (const u of unitResults || []) {
+    for (const s of u.sections || []) {
+      if (baselineStore.isIncompleteStatus(s.status)) {
+        incomplete.push({
+          app: u.appPath,
+          linter: s.linter,
+          status: s.status,
+          reason: s.reason,
+        });
+      }
+    }
+  }
+  return incomplete;
+}
+
 /**
  * Create/refresh baselines for the whole project.
  * @param {string} projectRoot
  * @param {object} opts { noBaseline, strict }
+ * @returns {{unitCount, units, incomplete}}
  */
 async function runBaseline(projectRoot, opts = {}) {
   const root = projectRoot || process.cwd();
@@ -115,11 +159,38 @@ async function runBaseline(projectRoot, opts = {}) {
   }
   // Refresh the global manifest so drift detection has a current snapshot.
   await gtlManifest.writeManifest(root, gtlManifest.buildManifest(results));
-  return { unitCount: units.length, units: results };
+  return {
+    unitCount: units.length,
+    units: results,
+    incomplete: collectIncomplete(results),
+  };
+}
+
+/**
+ * Scan committed baselines for incomplete (unavailable/errored) linter
+ * sections. Used by the hooks installer to refuse to gate commits against a
+ * baseline that never captured a linter.
+ * @returns {Promise<{app, linter, status}[]>}
+ */
+async function findIncompleteBaselines(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const out = [];
+  for (const unit of resolveUnits(root)) {
+    const baseline = await baselineStore.readBaseline(unit.baselinePath);
+    if (!baseline || !baseline.linters) continue;
+    for (const [linterId, section] of Object.entries(baseline.linters)) {
+      if (baselineStore.isIncompleteStatus(section && section.status)) {
+        out.push({ app: unit.appPath, linter: linterId, status: section.status });
+      }
+    }
+  }
+  return out;
 }
 
 module.exports = {
   runBaseline,
   baselineUnit,
   configHashFor,
+  collectIncomplete,
+  findIncompleteBaselines,
 };

package/lib/check.js

@@ -74,6 +74,21 @@ async function checkUnit(projectRoot, unit, adapter, opts) {
 
   const baseline = await baselineStore.readBaseline(unit.baselinePath);
   const section = baselineStore.getLinterSection(baseline, adapter.id);
+
+  // An incomplete baseline section (the linter was unavailable or errored when
+  // the baseline was captured) is not a real baseline — diffing against its
+  // empty fingerprint map would flag every pre-existing violation as new and
+  // block the commit. Surface it as a warning to re-baseline instead.
+  if (section && baselineStore.isIncompleteStatus(section.status)) {
+    return {
+      ...base,
+      status: 'needs-baseline',
+      reason:
+        `baseline for ${adapter.id} is incomplete (was "${section.status}" ` +
+        'when captured) — run: gimme-the-lint baseline',
+    };
+  }
+
   const result = diffEngine.diff(violations, section);
 
   return {
@@ -99,7 +114,10 @@ async function runCheck(projectRoot, opts = {}) {
     for (const linterId of unit.linters) {
       let adapter;
       try {
-        adapter = adapters.getAdapter(linterId, { projectRoot: root });
+        adapter = adapters.getAdapter(linterId, {
+          projectRoot: root,
+          appRoot: unit.root,
+        });
       } catch (err) {
         results.push({
           unit: unit.id,

package/lib/config-manager.js

@@ -104,10 +104,50 @@ module.exports = ${JSON.stringify(config, null, 2)};
   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.
+ * @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 configPath = isESM ? cjsPath : jsPath;
+
+  const appsObj = {};
+  for (const app of apps || []) {
+    appsObj[app.appPath] = { linters: app.linters };
+  }
+  const content = `// gimme-the-lint configuration
+// Generated by gimme-the-lint migrate — explicit app/linter bindings.
+// Edit this map to correct any mis-discovered apps or linters.
+module.exports = ${JSON.stringify({ apps: appsObj }, null, 2)};
+`;
+  await fs.writeFile(configPath, content, 'utf8');
+  return { created: true, path: configPath, apps: appsObj };
+}
+
 module.exports = {
   copyTemplate,
   detectProjectType,
   getConfig,
   initConfig,
+  writeAppsConfig,
   TEMPLATES_DIR,
 };

package/lib/drift.js

@@ -47,7 +47,10 @@ async function detectDrift(projectRoot) {
     for (const linterId of app.linters) {
       let adapter;
       try {
-        adapter = adapters.getAdapter(linterId, { projectRoot: root });
+        adapter = adapters.getAdapter(linterId, {
+          projectRoot: root,
+          appRoot: path.resolve(root, app.appPath),
+        });
       } catch {
         continue;
       }

package/lib/linter-configs.js

@@ -23,6 +23,7 @@ const LINTER_CONFIGS = {
   'golangci-lint': { template: '.golangci.template.yml', dest: '.golangci.yml' },
   tflint: { template: '.tflint.template.hcl', dest: '.tflint.hcl' },
   clippy: { template: 'clippy.template.toml', dest: 'clippy.toml' },
+  'ansible-lint': { template: '.ansible-lint.template.yml', dest: '.ansible-lint' },
 };
 
 /** Copy one template into an app dir, create-if-absent. */

package/lib/migrate.js

@@ -3,6 +3,8 @@
 const fs = require('fs-extra');
 const path = require('path');
 const { runBaseline } = require('./baseline');
+const projectModel = require('./project-model');
+const configManager = require('./config-manager');
 
 // Migration from the v1 layout (.lttf/ + .lttf-ruff/ per-directory baselines)
 // to the v2 .gtl/ layout. v1 baseline files hold per-directory violation data
@@ -89,6 +91,12 @@ async function migrate(projectRoot, opts = {}) {
     backedUp.push(rel);
   }
 
+  // Pin the discovered app/linter layout into gimme-the-lint.config.js so the
+  // guess is visible and editable, not silently re-derived on every run.
+  const discoveredApps = projectModel.discoverApps(root);
+  const appsConfig = await configManager.writeAppsConfig(root, discoveredApps);
+  const discoveryWarnings = projectModel.discoveryWarnings(root);
+
   // Re-baseline from the current code into the v2 .gtl/ layout.
   const baseline = await runBaseline(root, { strict: opts.strict });
 
@@ -96,7 +104,13 @@ async function migrate(projectRoot, opts = {}) {
     migrated: true,
     backedUp,
     backupPath: path.relative(root, backupRoot),
+    discoveredApps,
+    appsConfig,
+    discoveryWarnings,
     baseline,
+    // Incomplete linter sections (unavailable / errored) — a baseline in this
+    // state never captured those linters and must not silently gate commits.
+    incomplete: baseline.incomplete || [],
   };
 }
 

package/lib/project-model.js

@@ -11,16 +11,23 @@ const configManager = require('./config-manager');
 // monorepo — apps/orders-api (TS), apps/orders-worker (Py), apps/billing
 // (Go), apps/audit (Rust) — discover cleanly with zero config.
 
-// Manifest filename → linter id.
+// Manifest filename → linter id. These must be STRONG markers — a file whose
+// presence reliably means "a real, separately-configured app lives here".
+// `requirements.txt` is deliberately excluded: it is too weak (it shows up in
+// load-test dirs, docs tooling, sub-utilities) and binding ruff to every dir
+// that has one mis-binds nested noise and hides the real app.
 const MANIFEST_LINTERS = {
   'package.json': 'eslint',
   'biome.json': 'biome',
   'biome.jsonc': 'biome',
   'pyproject.toml': 'ruff',
+  'ruff.toml': 'ruff',
+  '.ruff.toml': 'ruff',
   'setup.py': 'ruff',
-  'requirements.txt': 'ruff',
   'go.mod': 'golangci-lint',
   'Cargo.toml': 'clippy',
+  'ansible.cfg': 'ansible-lint',
+  'galaxy.yml': 'ansible-lint',
 };
 
 // Terraform / OpenTofu have no manifest file — a directory of *.tf (or *.tofu)
@@ -102,12 +109,15 @@ function findManifestDirs(projectRoot) {
 }
 
 /**
- * Discover the apps in a project.
- * An "app" is a LEAF manifest directory — one with no manifest-bearing
- * directory beneath it. A manifest dir that DOES contain nested packages is a
- * workspace root (npm/pnpm/nx/lerna) and is not itself linted; its packages
- * are. Workspace globs need no special parsing because each package carries
- * its own manifest.
+ * Discover the apps in a project, binding each to its linters.
+ *
+ * Workspace-root detection is PER LINTER: a manifest directory is an app for
+ * linter L unless another manifest directory NESTED below it also carries L
+ * (then the outer dir is a workspace root for L, and the nested dirs are the
+ * apps). This is what lets a repo-root `pyproject.toml` (ruff) be a real
+ * Python app even when nested `package.json` dirs (eslint) sit below it — the
+ * old "any nested manifest ⇒ skip the whole dir" rule discarded the root
+ * config and bound nothing for Python.
  * @returns {{appPath: string, linters: string[]}[]}
  */
 function discoverApps(projectRoot, opts = {}) {
@@ -119,35 +129,66 @@ function discoverApps(projectRoot, opts = {}) {
   ];
 
   const manifestDirs = findManifestDirs(root);
-  const allDirs = manifestDirs.map((m) => m.dir);
 
-  const apps = [];
+  // dir → Set<linter>, accumulated via the per-linter workspace-root rule.
+  const appLinters = new Map();
   for (const entry of manifestDirs) {
-    const childPrefix = entry.dir === '.' ? '' : `${entry.dir}/`;
-    const isWorkspaceRoot = allDirs.some(
-      (other) => other !== entry.dir && other.startsWith(childPrefix)
-    );
-    if (isWorkspaceRoot) continue;
-
     // Skip template/scaffold directories (match any path segment).
     const segments = entry.dir === '.' ? [] : entry.dir.split('/');
     if (segments.some((segment) => matchesAny(segment, skipPatterns))) continue;
 
+    const childPrefix = entry.dir === '.' ? '' : `${entry.dir}/`;
+    for (const linter of entry.linters) {
+      const isWorkspaceRootForLinter = manifestDirs.some(
+        (other) =>
+          other.dir !== entry.dir &&
+          other.dir.startsWith(childPrefix) &&
+          other.linters.has(linter)
+      );
+      if (isWorkspaceRootForLinter) continue; // nested dirs are the apps for L
+      if (!appLinters.has(entry.dir)) appLinters.set(entry.dir, new Set());
+      appLinters.get(entry.dir).add(linter);
+    }
+  }
+
+  const apps = [];
+  for (const [dir, linterSet] of appLinters) {
     // A biome.json is an explicit choice of Biome over ESLint for JS/TS —
     // honor it by dropping the default ESLint binding for that app.
-    let linters = [...entry.linters];
+    let linters = [...linterSet];
     if (linters.includes('biome') && linters.includes('eslint')) {
       linters = linters.filter((l) => l !== 'eslint');
     }
-
-    apps.push({ appPath: entry.dir, linters: linters.sort() });
+    if (linters.length) apps.push({ appPath: dir, linters: linters.sort() });
   }
 
   return apps.sort((a, b) => a.appPath.localeCompare(b.appPath));
 }
 
+/**
+ * Discovery warnings — surfaced by `migrate` / `baseline` so a guessed app
+ * layout is visible rather than silent. The ambiguous case is a repo-root
+ * linter config AND nested apps: discovery has to guess the boundary, so an
+ * explicit `apps` map should pin it.
+ * @returns {string[]}
+ */
+function discoveryWarnings(projectRoot, opts = {}) {
+  const apps = discoverApps(projectRoot, opts);
+  const warnings = [];
+  const hasRootApp = apps.some((a) => a.appPath === '.');
+  if (hasRootApp && apps.length > 1) {
+    warnings.push(
+      'Discovery found a repo-root linter config AND nested app(s); the app ' +
+        'boundaries are a guess. Pin them with an explicit `apps` map in ' +
+        'gimme-the-lint.config.js (migrate writes one for you).'
+    );
+  }
+  return warnings;
+}
+
 module.exports = {
   discoverApps,
+  discoveryWarnings,
   findManifestDirs,
   globToRegExp,
   MANIFEST_LINTERS,

package/lib/report.js

@@ -52,6 +52,10 @@ function formatCheckReport(report) {
       lines.push(chalk.dim(`· ${label} — no staged changes`));
     } else if (u.status === 'error') {
       lines.push(`${chalk.red('✗')} ${label} ${chalk.red(`— ${u.reason}`)}`);
+    } else if (u.status === 'needs-baseline') {
+      lines.push(
+        `${chalk.yellow('⚠ NEEDS BASELINE')} ${label} ${chalk.yellow(`— ${u.reason}`)}`
+      );
     }
     // 'no-code' is intentionally silent.
     if ((u.status === 'pass' || u.status === 'fail') && u.hasBaseline === false) {
@@ -91,10 +95,18 @@ function formatBaselineReport(report, projectRoot) {
     lines.push(chalk.cyan(`  ${u.appPath}`));
     for (const s of u.sections) {
       if (s.status === 'no-code') continue;
-      if (s.status === 'skipped') {
-        lines.push(`    ${chalk.yellow('⚠ SKIPPED')} ${s.linter} — ${s.reason}`);
+      if (s.status === 'unavailable') {
+        lines.push(
+          `    ${chalk.red('⚠ UNAVAILABLE')} ${s.linter} — ${s.reason} ` +
+            chalk.red('(NOT baselined)')
+        );
       } else if (s.status === 'error') {
-        lines.push(`    ${chalk.red('✗')} ${s.linter} — ${s.reason}`);
+        lines.push(
+          `    ${chalk.red('✗ ERROR')} ${s.linter} — ${s.reason} ` +
+            chalk.red('(NOT baselined)')
+        );
+      } else if (s.status === 'skipped') {
+        lines.push(`    ${chalk.yellow('⚠ SKIPPED')} ${s.linter} — ${s.reason}`);
       } else {
         lines.push(
           `    ${chalk.green('✓')} ${s.linter} — ${s.total} violation(s) ` +
@@ -104,6 +116,28 @@ function formatBaselineReport(report, projectRoot) {
     }
     lines.push(chalk.dim(`    → ${path.relative(root, u.baselinePath)}`));
   }
+
+  // Prominent incomplete summary — a baseline missing linters must never look
+  // like a success.
+  if (report.incomplete && report.incomplete.length) {
+    lines.push('');
+    lines.push(
+      chalk.red(`✗ ${report.incomplete.length} linter(s) were NOT baselined:`)
+    );
+    for (const i of report.incomplete) {
+      lines.push(chalk.red(`    ${i.app} · ${i.linter} (${i.status})`));
+    }
+    lines.push(
+      chalk.yellow(
+        '  This baseline is INCOMPLETE. Install the missing linters and re-run'
+      )
+    );
+    lines.push(
+      chalk.yellow(
+        '  `gimme-the-lint baseline` before relying on it to gate commits.'
+      )
+    );
+  }
   return lines.join('\n');
 }
 

package/lib/toolchain.js

@@ -51,7 +51,10 @@ function findGaps(projectRoot) {
     for (const linterId of unit.linters) {
       let adapter;
       try {
-        adapter = adapters.getAdapter(linterId, { projectRoot: root });
+        adapter = adapters.getAdapter(linterId, {
+          projectRoot: root,
+          appRoot: unit.root,
+        });
       } catch {
         continue;
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theglitchking/gimme-the-lint",
-  "version": "2.1.0",
-  "description": "Polyglot progressive linting for monorepos — adapter-driven baselines, per-app drift detection, and idempotent skips across JavaScript/TypeScript, Python, Go, Rust, and Terraform.",
+  "version": "2.3.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",
     "progressive-linting",
@@ -23,7 +23,9 @@
     "rust",
     "tflint",
     "terraform",
-    "opentofu"
+    "opentofu",
+    "ansible-lint",
+    "ansible"
   ],
   "author": {
     "name": "TheGlitchKing",

package/templates/.ansible-lint.template.yml

@@ -0,0 +1,20 @@
+# Generated by gimme-the-lint — ansible-lint (recommended tier)
+#
+# `profile` is ansible-lint's strictness lever, from least to most strict:
+#   min -> basic -> moderate -> safety -> shared -> production
+# "moderate" is the recommended baseline. Raise to "safety" or "production"
+# for stricter enforcement.
+profile: moderate
+
+exclude_paths:
+  - .cache/
+  - .git/
+  - molecule/
+
+# Downgrade specific rules to non-blocking warnings:
+# warn_list:
+#   - experimental
+#
+# Skip specific rules entirely:
+# skip_list:
+#   - yaml[line-length]