<p align="center">
<img src="assets/baseline-logo.png" alt="Baseline logo" width="300" />
</p>
# baseline
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. **baseline** enforces the decisions your team has already made — especially the ones AI keeps ignoring.
## Why not ESLint?
ESLint is great at what it does. baseline handles what it can't:
- **Ratcheting.** ESLint is pass/fail. baseline 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. baseline 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.** baseline aggregates pattern matches across your entire codebase. "There should be fewer than 50 uses of legacyFetch" is a one-liner in `baseline.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
# Run instantly via npm (no install needed)
npx code-baseline scan
# Or install globally
npm install -g code-baseline
# Or via Cargo
cargo install code-baseline
```
```bash
# Initialize a config in your project
baseline init
# Edit baseline.toml to fit your project...
# Scan your project
baseline scan
# Only scan files changed since main
baseline scan --changed-only
# Generate a ratchet baseline
baseline 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 `baseline.toml` at the root of your project.
### Global Settings
```toml
[baseline]
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
$ baseline baseline .
# Writes .baseline-snapshot.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):
| `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
| `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
```
baseline <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 baseline.toml for your project
mcp Run as an MCP (Model Context Protocol) server over stdio
```
### `scan` options
```
baseline scan [OPTIONS] [PATHS]...
-c, --config <PATH> Config file path [default: baseline.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
```
baseline baseline [OPTIONS] <PATHS>...
-c, --config <PATH> Config file path [default: baseline.toml]
-o, --output <PATH> Output file [default: .baseline-snapshot.json]
```
### `init` options
```
baseline init [OPTIONS]
-o, --output <PATH> Output file [default: baseline.toml]
--force Overwrite existing config file
```
### Output Formats
| `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
| `0` | No violations found |
| `1` | Violations found |
| `2` | Configuration or runtime error |
---
## CI Integration
### GitHub Actions (recommended)
Use the `stewartjarod/baseline` action for the simplest setup. On pull requests it automatically scans only changed files; on pushes to main it scans everything.
```yaml
name: Baseline
on:
pull_request:
push:
branches: [main]
jobs:
baseline:
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: stewartjarod/baseline@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 baseline
run: baseline scan --format compact
```
### Pre-commit Hook
```bash
#!/bin/sh
baseline 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 (baseline 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/
├── baseline.toml Sample project config
├── baseline.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. baseline 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
$ baseline baseline .
# Writes .baseline-snapshot.json with counts per ratchet rule
# Step 2: Set the ceiling in baseline.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