<p align="center">
  <img src="assets/guardrails-logo.png" alt="Guardrails logo" width="300" />
</p>

# guardrails

Stop AI from undoing your team's decisions.

A fast Rust-based CI tool that enforces bans, ratchets, and design system rules that ESLint can't express — so Cursor, Copilot, and Claude stop reintroducing the patterns you already migrated away from.

## The Problem

AI coding tools are fast. They're also confidently wrong about your team's conventions.

Cursor, Copilot, and Claude generate code from training data — not from your team's decisions. They don't know you migrated off moment.js. They don't know you banned axios. They don't know your Tailwind classes need dark mode variants. So every AI-assisted PR is a coin flip on whether it respects months of architectural work.

- **"We migrated off moment.js six months ago. Cursor just added it back in a PR."** AI tools pull from stale training data. Every deprecated package you've ever used is one autocomplete away from returning.
- **"We have 200 legacyFetch calls and the number keeps going _up_."** AI generates new code using the patterns it sees most in your codebase. Legacy patterns are self-reinforcing unless something blocks them.
- **"Our shadcn components support dark mode — except the ones AI wrote."** AI doesn't understand your design system. It reaches for `bg-white` and `text-gray-900` because that's what it learned from public repos.
- **"We banned the request package, but Copilot just added it to package.json."** Dependency-level decisions live in your team's memory. AI has no access to that context.

Linters catch syntax. Formatters fix whitespace. **guardrails** enforces the decisions your team has already made — especially the ones AI keeps ignoring.

## Why not ESLint?

ESLint is great at what it does. guardrails handles what it can't:

- **Ratcheting.** ESLint is pass/fail. guardrails counts occurrences across your codebase and enforces a ceiling that only goes down. You can migrate 200 legacy calls to 0 at your own pace — and CI prevents regressions at every step.
- **Dependency bans.** ESLint checks source files. guardrails parses `package.json`, `Cargo.toml`, `requirements.txt`, and `go.mod` to catch banned packages before they ship — even if no source file imports them yet.
- **File presence rules.** Enforce that `README.md`, `LICENSE`, and CI configs exist. Forbid `.env` files from being committed. ESLint has no concept of project-level structure.
- **Cross-file counting.** guardrails aggregates pattern matches across your entire codebase. "There should be fewer than 50 uses of legacyFetch" is a one-liner in `guardrails.toml` and impossible in ESLint without a custom plugin.
- **Zero config for Tailwind/shadcn.** Built-in rules enforce dark mode variants and semantic token usage with 130+ default mappings. No plugins, no parser setup, no dependencies.
- **Speed.** Written in Rust. Single binary. No Node.js runtime. Scans a large codebase in milliseconds.

## Quick Start

```bash
# Build from source
cargo build --release

# Initialize a config in your project
guardrails init

# Edit guardrails.toml to fit your project...

# Scan your project
guardrails scan

# Only scan files changed since main
guardrails scan --changed-only

# Generate a ratchet baseline
guardrails baseline .
```

## Example Output

```
src/utils/helpers.ts
  1:0  error  moment.js is deprecated — use date-fns or Temporal API  no-moment
    │ import moment from 'moment';
    → import { format } from 'date-fns'
  2:0  warning  Import specific lodash functions instead of the full package  no-lodash-full
    │ import { debounce } from 'lodash';
    → import debounce from 'lodash/debounce'
  6:3  warning  Remove console.log before committing  no-console-log
    │ console.log("formatting date");

src/components/BadCard.tsx
  7:21  error  Missing dark: variant for color class: 'bg-white'  enforce-dark-mode
    │ <div className="bg-white border border-gray-200 rounded-lg shadow-sm p-6">
    → Use 'bg-background' instead — it adapts to light/dark automatically

✗ 9 violations (7 error, 2 warning)
  Scanned 14 files with 8 rules.
```

## Configuration

Everything lives in a single `guardrails.toml` at the root of your project.

### Global Settings

```toml
[guardrails]
name = "my-project"
include = ["src/**/*", "lib/**/*", "app/**/*"]
exclude = [
    "**/node_modules/**",
    "**/target/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
]
root = "."  # optional, defaults to current directory
```

The `exclude` list above is applied by default even if you don't specify it.

---

## Rule Types

### `banned-import` — Stop deprecated package imports

Detects `import`, `require`, `from ... import`, and `use` statements across JavaScript, TypeScript, Python, and Rust.

```toml
[[rule]]
id = "no-moment"
type = "banned-import"
severity = "error"
packages = ["moment", "moment-timezone"]
message = "moment.js is deprecated — use date-fns or Temporal API"
suggest = "import { format } from 'date-fns'"
```

Catches all of these:

```js
import moment from 'moment';           // ES6
const moment = require('moment');       // CommonJS
```
```python
import moment                           # Python
from moment import format               # Python
```
```rust
use moment::format;                     // Rust
```

---

### `banned-pattern` — Block unwanted code patterns

Matches literal strings or regex patterns in source files. Use `glob` to scope which files are checked.

```toml
[[rule]]
id = "no-console-log"
type = "banned-pattern"
severity = "warning"
pattern = "console.log("
glob = "src/**/*.ts"
message = "Remove console.log before committing — use the logger"
suggest = "import { logger } from '@company/logger'"
```

Enable regex for more precise matching:

```toml
[[rule]]
id = "no-any-type"
type = "banned-pattern"
severity = "warning"
pattern = ":\\s*any\\b"
regex = true
glob = "src/**/*.ts"
message = "Avoid 'any' — use proper typing or 'unknown'"
```

---

### `required-pattern` — Enforce that patterns exist

The inverse of `banned-pattern`. Fails if a matching file does *not* contain the pattern.

```toml
[[rule]]
id = "error-boundary-in-pages"
type = "required-pattern"
severity = "error"
glob = "src/pages/**/*.tsx"
pattern = "ErrorBoundary"
message = "All page components must wrap content in an ErrorBoundary"
```

---

### `banned-dependency` — Audit manifest files

Checks `package.json`, `Cargo.toml`, `requirements.txt`, `pyproject.toml`, and `go.mod` for banned packages. Parses `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies` in `package.json`; `dependencies`, `dev-dependencies`, and `build-dependencies` in `Cargo.toml`.

```toml
[[rule]]
id = "no-request"
type = "banned-dependency"
severity = "error"
packages = ["request", "request-promise"]
manifest = "package.json"
message = "The 'request' package is deprecated — use 'node-fetch' or 'undici'"
```

Omit `manifest` to check all recognized manifest files automatically.

---

### `file-presence` — Enforce project structure

Require files to exist, or forbid files that shouldn't be committed.

```toml
[[rule]]
id = "project-hygiene"
type = "file-presence"
severity = "error"
required_files = ["README.md", "LICENSE", ".github/workflows/ci.yml"]
forbidden_files = [".env", ".env.local"]
message = ".env files should not be committed — use .env.example"
```

---

### `ratchet` — Drive incremental refactors

Counts total occurrences of a pattern across all matching files and enforces a ceiling. Lower the ceiling over time as you migrate. CI prevents regressions.

```toml
[[rule]]
id = "ratchet-legacy-fetch"
type = "ratchet"
severity = "error"
pattern = "legacyFetch("
max_count = 47
glob = "src/**/*.ts"
message = "Migrate remaining legacyFetch calls to apiFetch"
suggest = "import { apiFetch } from '@company/http'"
```

Use the `baseline` command to find your current counts:

```bash
$ guardrails baseline .
# Writes .guardrails-baseline.json with counts for all ratchet rules
```

The workflow: set `max_count = 47` today. Next sprint, migrate a few call sites, set `max_count = 40`. The number only goes down. Any PR that adds new legacy calls fails CI.

---

### `tailwind-dark-mode` — Enforce light + dark theme coverage

Scans JSX/TSX/HTML files for Tailwind color utility classes (`bg-white`, `text-gray-900`, `border-slate-200`, etc.) and flags any that don't have a corresponding `dark:` variant in the same class attribute.

```toml
[[rule]]
id = "enforce-dark-mode"
type = "tailwind-dark-mode"
severity = "error"
glob = "**/*.{tsx,jsx}"
message = "Missing dark: variant for color class"
suggest = "Use a shadcn semantic token or add a dark: counterpart"
allowed_classes = ["bg-brand-gradient"]
```

The rule is **shadcn-aware**. It automatically allows all semantic token classes because they resolve through CSS custom properties and already handle both themes:

`bg-background`, `text-foreground`, `bg-muted`, `text-muted-foreground`, `bg-card`, `bg-primary`, `text-primary-foreground`, `bg-secondary`, `bg-accent`, `bg-destructive`, `text-destructive-foreground`, `border-border`, `ring-ring`, and all sidebar variants.

It also recognizes properly paired dark variants:

```jsx
{/* ✅ Passes — dark: variant is paired */}
<div className="bg-white dark:bg-slate-900 text-black dark:text-white">

{/* ✅ Passes — semantic tokens handle theming automatically */}
<div className="bg-background text-foreground border-border">

{/* ❌ Fails — hardcoded colors with no dark: counterpart */}
<div className="bg-white text-gray-900 border-gray-200">
```

The rule understands `className="..."`, `class="..."`, and Tailwind utility functions like `cn()`, `clsx()`, `classNames()`, `cva()`, and `twMerge()`.

When it flags a violation, it suggests the specific semantic token replacement:

```
7:21  error  Missing dark: variant for color class: 'bg-white'  enforce-dark-mode
  │ <div className="bg-white border border-gray-200 rounded-lg shadow-sm p-6">
  → Use 'bg-background' instead — it adapts to light/dark automatically
```

---

### `tailwind-theme-tokens` — Ban raw colors, enforce semantic tokens

Goes a step further than dark mode enforcement: **bans raw Tailwind color classes entirely** and requires the use of shadcn semantic token classes. Ships with a comprehensive default mapping covering backgrounds, text, borders, rings, dividers, and destructive states.

```toml
[[rule]]
id = "use-theme-tokens"
type = "tailwind-theme-tokens"
severity = "warning"
glob = "**/*.{tsx,jsx}"
message = "Use shadcn semantic token instead of raw color"
```

Default mapping includes (partial):

| Raw Tailwind Class | Semantic Token |
|---|---|
| `bg-white` | `bg-background` |
| `bg-gray-50`, `bg-slate-100` | `bg-muted` |
| `text-gray-900`, `text-black` | `text-foreground` |
| `text-gray-500`, `text-slate-400` | `text-muted-foreground` |
| `border-gray-200`, `border-slate-300` | `border-border` |
| `bg-red-500`, `bg-red-600` | `bg-destructive` |
| `text-red-500` | `text-destructive` |
| `bg-slate-900` | `bg-primary` |
| `ring-slate-200` | `ring-ring` |

Extend with your own brand tokens:

```toml
token_map = [
    "bg-indigo-600=bg-brand",
    "text-indigo-50=text-brand-foreground",
    "border-indigo-300=border-brand",
]
```

Exempt specific classes that are intentionally unthemed:

```toml
allowed_classes = ["bg-green-500", "text-red-600"]
```

---

## All Rule Config Fields

| Field | Type | Used By | Description |
|---|---|---|---|
| `id` | string | All | Unique rule identifier |
| `type` | string | All | Rule type (see sections above) |
| `severity` | `error` / `warning` / `info` | All | Severity level (default: `error`) |
| `message` | string | All | Human-readable explanation |
| `suggest` | string | All | Fix suggestion shown in output |
| `enabled` | bool | All | Enable/disable (default: `true`) |
| `glob` | string | File rules | Narrow which files this rule applies to |
| `packages` | string[] | `banned-import`, `banned-dependency` | Package names to ban |
| `pattern` | string | `banned-pattern`, `required-pattern`, `ratchet` | String or regex to match |
| `regex` | bool | Pattern rules | Treat `pattern` as regex (default: `false`) |
| `manifest` | string | `banned-dependency` | Manifest file to check (omit for auto-detect) |
| `required_files` | string[] | `file-presence` | Files that must exist |
| `forbidden_files` | string[] | `file-presence` | Files that must not exist |
| `max_count` | int | `ratchet` | Maximum allowed occurrences |
| `allowed_classes` | string[] | `tailwind-dark-mode`, `tailwind-theme-tokens` | Classes exempt from checks |
| `token_map` | string[] | `tailwind-theme-tokens` | Custom `"raw=semantic"` mappings |

---

## CLI Reference

```
guardrails <COMMAND>

Commands:
  scan        Scan files for rule violations (primary command)
  baseline    Count ratchet pattern occurrences and write a baseline JSON file
  init        Generate a starter guardrails.toml for your project
  mcp         Run as an MCP (Model Context Protocol) server over stdio
```

### `scan` options

```
guardrails scan [OPTIONS] [PATHS]...

  -c, --config <PATH>       Config file path [default: guardrails.toml]
  -f, --format <FORMAT>     Output format [default: pretty]
      --stdin               Read file content from stdin instead of disk
      --filename <NAME>     Filename to use for glob matching when using --stdin
      --changed-only        Only scan files changed relative to a base branch (requires git)
      --base <REF>          Base ref for --changed-only [default: auto-detect or "main"]
      --fix                 Apply fixes automatically
      --dry-run             Preview fixes without applying (requires --fix)
```

### `baseline` options

```
guardrails baseline [OPTIONS] <PATHS>...

  -c, --config <PATH>       Config file path [default: guardrails.toml]
  -o, --output <PATH>       Output file [default: .guardrails-baseline.json]
```

### `init` options

```
guardrails init [OPTIONS]

  -o, --output <PATH>       Output file [default: guardrails.toml]
      --force               Overwrite existing config file
```

### Output Formats

| Format | Flag | Use Case |
|---|---|---|
| `pretty` | `-f pretty` | Human-readable terminal output with colors, source context, and suggestions |
| `compact` | `-f compact` | One line per violation, grep-friendly |
| `json` | `-f json` | Machine-readable, for tooling integration |
| `github` | `-f github` | GitHub Actions annotation format — violations appear inline on PR diffs |
| `sarif` | `-f sarif` | SARIF v2.1.0 for GitHub Code Scanning |
| `markdown` | `-f markdown` | Markdown tables for PR summaries and `$GITHUB_STEP_SUMMARY` |

### Exit Codes

| Code | Meaning |
|---|---|
| `0` | No violations found |
| `1` | Violations found |
| `2` | Configuration or runtime error |

---

## CI Integration

### GitHub Actions (recommended)

Use the `AstroGuard/guardrails` action for the simplest setup. On pull requests it automatically scans only changed files; on pushes to main it scans everything.

```yaml
name: Guardrails

on:
  pull_request:
  push:
    branches: [main]

jobs:
  guardrails:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history needed for diff-aware scanning

      - uses: dtolnay/rust-toolchain@stable

      - uses: AstroGuard/guardrails@main
        with:
          paths: 'src'
          # changed-only defaults to "auto" (enabled on PRs, disabled on push)
          # base: 'main'  # Override the base branch for diff comparison
```

The action produces inline annotations on the PR diff (`--format github`) and writes a markdown summary to `$GITHUB_STEP_SUMMARY`.

### Generic CI

```yaml
- name: Run guardrails
  run: guardrails scan --format compact
```

### Pre-commit Hook

```bash
#!/bin/sh
guardrails scan --changed-only --base HEAD
```

---

## Architecture

```
src/
├── main.rs                         CLI entry point (clap)
├── lib.rs                          Library root — re-exports public API
├── config.rs                       TOML configuration parsing
├── scan.rs                         File tree walker + rule orchestration
├── git_diff.rs                     Git diff parsing for --changed-only
├── mcp.rs                          MCP (Model Context Protocol) server
├── init.rs                         Config scaffolding (guardrails init)
├── presets.rs                      Built-in rule presets
├── cli/
│   ├── mod.rs                      CLI argument definitions (clap)
│   ├── format.rs                   Output rendering (pretty, JSON, GitHub, SARIF, etc.)
│   └── toml_config.rs              TOML config validation helpers
└── rules/
    ├── mod.rs                      Rule trait, Violation type, rule registry
    ├── factory.rs                  Rule construction from config
    ├── banned_import.rs            Import detection (JS/TS/Python/Rust)
    ├── banned_pattern.rs           Literal + regex pattern matching
    ├── required_pattern.rs         Ensure patterns exist in matching files
    ├── banned_dependency.rs        Manifest parsing (package.json, Cargo.toml, etc.)
    ├── file_presence.rs            Required/forbidden file checks
    ├── ratchet.rs                  Decreasing-count enforcement
    ├── window_pattern.rs           Sliding-window pattern matching
    ├── tailwind_dark_mode.rs       Dark mode variant enforcement
    └── tailwind_theme_tokens.rs    shadcn semantic token enforcement

examples/
├── guardrails.toml                 Sample project config
├── guardrails.example.toml         Documented reference for all rule types
├── github-ci.yml                   GitHub Actions workflow example
├── claude-code-hooks.json          Claude Code hooks integration
├── BadCard.tsx                     Anti-pattern example — hardcoded colors
└── GoodCard.tsx                    Best-practice example — semantic tokens
```

### Extending with New Rules

The `Rule` trait defines the interface:

```rust
pub trait Rule: Send + Sync {
    fn id(&self) -> &str;
    fn severity(&self) -> Severity;

    /// Check a single file. Called for each file matching the glob.
    fn check_file(&self, ctx: &ScanContext) -> Vec<Violation>;

    /// Check the project as a whole (manifests, file presence, ratchet totals).
    fn check_project(&self, root: &Path) -> Vec<Violation>;

    /// Whether this rule scans individual files.
    fn is_file_rule(&self) -> bool;

    /// Optional glob to narrow file matching beyond the global include/exclude.
    fn file_glob(&self) -> Option<&str>;
}
```

To add a new rule:

1. Create `src/rules/your_rule.rs` implementing the `Rule` trait.
2. Add a variant to `RuleType` in `src/config.rs`.
3. Register it in `build_rule()` in `src/rules/factory.rs`.
4. Add any new config fields to `RuleConfig` in `src/config.rs`.

---

## Real-World Usage Patterns

### AI keeps importing moment.js — make it stop

AI coding assistants pull from training data that includes deprecated packages. guardrails catches these before they land:

```toml
[[rule]]
id = "no-moment"
type = "banned-import"
severity = "error"
packages = ["moment", "moment-timezone"]
message = "moment.js is deprecated — use date-fns or Temporal API"

[[rule]]
id = "no-enzyme"
type = "banned-import"
severity = "error"
packages = ["enzyme", "enzyme-adapter-react-16", "enzyme-adapter-react-17"]
message = "Enzyme is deprecated — use @testing-library/react"

[[rule]]
id = "no-request"
type = "banned-dependency"
severity = "error"
packages = ["request", "request-promise", "axios"]
message = "Use the native fetch API or undici"
```

### AI writes bg-white. Your design system says bg-background.

You're migrating from raw Tailwind to shadcn semantic tokens. Use both Tailwind rules together:

```toml
# Hard error: every color class must work in dark mode
[[rule]]
id = "enforce-dark-mode"
type = "tailwind-dark-mode"
severity = "error"
glob = "**/*.{tsx,jsx}"

# Soft warning: prefer semantic tokens (gives teams time to migrate)
[[rule]]
id = "use-theme-tokens"
type = "tailwind-theme-tokens"
severity = "warning"
glob = "**/*.{tsx,jsx}"
token_map = ["bg-indigo-600=bg-brand", "text-indigo-50=text-brand-foreground"]
```

### 200 legacy calls and AI is adding more — ratchet them to zero

You have 200 call sites using `oldApi.fetch()` and want to migrate to `newApi.request()`:

```bash
# Step 1: Find the current count
$ guardrails baseline .
# Writes .guardrails-baseline.json with counts per ratchet rule

# Step 2: Set the ceiling in guardrails.toml
```

```toml
[[rule]]
id = "ratchet-old-api"
type = "ratchet"
severity = "error"
pattern = "oldApi.fetch("
max_count = 200
glob = "src/**/*.ts"
message = "Migrate to newApi.request()"
```

```bash
# Step 3: After each migration sprint, lower the ceiling
# Sprint 1: max_count = 180
# Sprint 2: max_count = 150
# Sprint 3: max_count = 120
# ...
# Done:     max_count = 0
```

---

## Future Directions

- **Tree-sitter integration** — AST-aware rules for scope-sensitive matching (e.g., "ban `any` in function parameters but not in type guards")
- **WASM plugin system** — distribute custom rules as portable WASM modules
- **Watch mode** — re-run on file changes during development
- **Monorepo support** — per-package config inheritance with shared base rules

## Inspiration

This project was inspired by Matt Holden's concept of [guardrail coding](https://www.fuzzycomputer.com/posts/guardrail-coding) — the idea that AI coding tools should be guided by deterministic environment constraints (linters, rules, tests) rather than fuzzy prompt-space instructions. Follow Matt at [@holdenmatt](https://x.com/holdenmatt).

## License

MIT
