Configuration Guide

All configuration options for eslint-plugin-ai-guardrails — rule options, team presets, and CI setup.

Supported File Types

AI Guardrails only applies to TypeScript files:

*.ts, *.tsx, *.mts, *.cts

JavaScript files are intentionally excluded — this plugin targets TypeScript-first workflows where AI tools generate the most structural debt.

ESLint v9 — Flat Config

// eslint.config.mjs
import aiGuardrails from 'eslint-plugin-ai-guardrails';

export default [
  aiGuardrails.flatConfigs.recommended
];

// eslint.config.mjs
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import aiGuardrails from 'eslint-plugin-ai-guardrails';

export default [
  { ignores: ['dist', 'build', 'coverage', 'node_modules'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  aiGuardrails.flatConfigs.recommended
];

// eslint.config.cjs
const aiGuardrails = require('eslint-plugin-ai-guardrails');

module.exports = [
  aiGuardrails.flatConfigs.recommended
];

ESLint v8 — Legacy Config

// .eslintrc.json
{
  "parser": "@typescript-eslint/parser",
  "plugins": ["ai-guardrails"],
  "extends": ["plugin:ai-guardrails/recommended"]
}

{
  "parser": "@typescript-eslint/parser",
  "plugins": ["ai-guardrails"],
  "rules": {
    "ai-guardrails/max-file-lines": "warn",
    "ai-guardrails/max-function-lines": "warn",
    "ai-guardrails/no-orphan-todos": "error",
    "ai-guardrails/no-ai-obvious-comments": "warn"
  }
}

Rule Options Reference

`max-file-lines`

["warn", { "max": 300, "skipBlankLines": true, "skipComments": false }]

Option	Type	Default	Description
`max`	`number`	`300`	Maximum effective lines per file
`skipBlankLines`	`boolean`	`true`	Don't count blank lines
`skipComments`	`boolean`	`false`	Don't count comment lines

`max-function-lines`

["warn", { "max": 50, "skipBlankLines": true, "skipComments": true, "skipSingleLine": false }]

Option	Type	Default	Description
`max`	`number`	`50`	Maximum effective lines per function body
`skipBlankLines`	`boolean`	`true`	Don't count blank lines
`skipComments`	`boolean`	`true`	Don't count comment lines
`skipSingleLine`	`boolean`	`false`	Ignore single-line functions

`no-orphan-todos`

["error", { "requireReference": true, "requireDate": false, "dateFormat": "YYYY-MM-DD" }]

Option	Type	Default	Description
`requireReference`	`boolean`	`true`	Require a URL or issue reference (`#123`)
`requireDate`	`boolean`	`false`	Require a date in `YYYY-MM-DD` format
`dateFormat`	`string`	`"YYYY-MM-DD"`	Expected date format

`no-ai-obvious-comments`

"warn"

No options. Strictly enforces density constraints (max 20%), horizontal limits (80 chars), and content quality to ensure professional comments.

Team Presets

Relaxed — getting started

Good for teams adopting guardrails gradually without blocking existing code:

{
  "rules": {
    "ai-guardrails/max-file-lines": ["warn", { "max": 500 }],
    "ai-guardrails/max-function-lines": ["warn", { "max": 80 }],
    "ai-guardrails/no-orphan-todos": "warn",
    "ai-guardrails/no-ai-obvious-comments": "warn"
  }
}

Strict — established teams

For teams that want hard enforcement from day one:

{
  "rules": {
    "ai-guardrails/max-file-lines": ["error", { "max": 200 }],
    "ai-guardrails/max-function-lines": ["error", { "max": 30 }],
    "ai-guardrails/no-orphan-todos": [
      "error",
      { "requireReference": true, "requireDate": true }
    ],
    "ai-guardrails/no-ai-obvious-comments": "error"
  }
}

CI: Fail Build on Warnings

Use --max-warnings 0 to treat all warnings as errors in CI:

{
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "typecheck": "tsc --noEmit",
    "build": "npm run lint && npm run typecheck && <build-step>"
  }
}

This guarantees any ESLint warning or TypeScript error fails the pipeline — no silent drift.

Configuration Guide

On this page