Changelog

All notable changes to eslint-plugin-ai-guardrails, following Keep a Changelog and Semantic Versioning.

All notable changes to this project are documented here.

The format follows Keep a Changelog, and this project follows Semantic Versioning.

[1.3.2] — 2026-05-11

Type-safety refactor: Eliminated ambiguous unknown and as unknown as cast annotations across the plugin source. No public API or rule behavior changes.
- New src/cli/json.ts exports JsonValue / JsonObject types now used by PackageJson and writeJson() instead of unknown.
- New src/rules/utils/source-code.ts exports resolveSourceCode(context), replacing the duplicated (context as unknown as { sourceCode?: TSESLint.SourceCode }) shim in all four rules.
- loadParser() in src/index.ts now returns TSESLint.Linter.ParserModule | undefined instead of unknown; the as unknown as PluginWithMeta double-cast on the plugin object was removed via a PluginBase = Omit<PluginWithMeta, 'flatConfigs'> intermediate type.
- no-ai-obvious-comments AST walker now uses a typed AstChild union and an isAstNode type predicate, eliminating the as TSESTree.Node casts in the traversal.
Test suite: now 61 tests (up from 60); all green.

CLI Initialization: Corrected an issue where running init on an Elysia project generated Next.js package scripts instead of the correct bun run commands.

Smart CLI Initialization System (npx eslint-plugin-ai-guardrails init):
- Auto-detects frameworks (Vite, Next.js, Elysia, NestJS) and applies optimal config templates.
- Generates comprehensive baseline setups including eslint.config.js/mjs, tsconfig.json, and automatic vite-plugin-checker wiring.
- Intelligently patches package.json to inject necessary lint, typecheck, and build scripts without overwriting user data.
- Interactive safety prompts prevent accidental destructive overwrites.
Automated AI Rules Scaffolding (AI Cages):
- The CLI now automatically generates and formats strict AI guardrail instructions for .windsurf/rules/ai-guardrails.md, .cursor/rules/ai-guardrails.md, .agents/rules/ai-guardrails.md, and .kiro/steering/ai-guardrails.md.
- Injects a zero-tolerance "AI Cage" prompt to ensure future AI-generated code conforms strictly to project limitations (no redundant comments, strict lines limits).

Comprehensive Comment Quality Linter: The no-ai-obvious-comments rule has been completely overhauled from an absolute ban to a nuanced, professional-grade linter:
- Density Control: Enforces maximum comment limits (20% for large files, 30% for files under 50 lines).
- Horizontal Limits: Fails if any individual comment line exceeds 80 characters.
- Vertical Limits: Allows 10 consecutive lines for docstrings but only 3 lines for inline logic.
- Content Heuristics: Detects commented-out code snippets and flags redundant explanations that merely repeat the code's token logic.
Max Function Lines Rule: The max-function-lines rule now sets skipComments to true by default, ensuring comment blocks do not unfairly trigger line-limit violations.

CLI initializer now creates eslint.config.mjs for new projects and preserves existing lint/build scripts.
CLI initializer now skips tsconfig.json updates when the file exists but contains invalid JSON, preventing destructive overwrites.
Documentation updated to reflect non-destructive init behavior and .mjs flat-config defaults.
Added .stress-tests/ multi-framework failure harness for validating that guardrail violations break builds as expected.

4 ESLint rules for AI-assisted codebase quality:
- max-file-lines — prevent god files (default: 300 lines)
- max-function-lines — prevent god functions (default: 50 lines)
- no-orphan-todos — require tracking references on TODO/FIXME/HACK
- no-ai-obvious-comments — detect redundant comments that repeat code
CLI initializer (npx eslint-plugin-ai-guardrails init) with auto-detection for:
- Package managers (npm, pnpm, yarn, bun)
- Frameworks (Vite, Next.js, NestJS, Elysia)
- Automatic vite-plugin-checker wiring
- tsconfig.json strict baseline creation
ESLint v8 support — legacy .eslintrc config via plugin:ai-guardrails/recommended
ESLint v9 support — flat config via aiGuardrails.flatConfigs.recommended
Plugin metadata — plugin.meta.name and plugin.meta.version for ESLint v9
Lazy parser loading — @typescript-eslint/parser loaded on demand to prevent crashes during installation
CJS/ESM interop — flatConfigs accessible via both require() and import default
Comprehensive test suite — 60 tests covering all rules, edge cases, and plugin exports
Integration-tested against ESLint v8 legacy, v9 flat CJS, v9 flat ESM, and framework-specific configs
CI workflow — GitHub Actions with Node 18, 20, 22 matrix
Full documentation — rule docs, configuration guide, integrations for 7+ frameworks, troubleshooting

CLI config template now uses standard flat config array export (compatible with all ESLint v9 versions)
Version bumped from 0.1.0 to 1.0.0 for production release