Adopt Sheath Gradually with Baselines

Baselines let you adopt Sheath on an existing codebase without fixing every historical issue during the initial rollout. A baseline records the current violations and filters them out on future runs so new regressions still surface.

Parser diagnostics are never recorded or filtered by a baseline. A parse error prevents normal rules from checking the rest of that template, so it always remains visible and makes the lint command fail.

#Default File

The default baseline path is:

sheath-baseline.json

If that file exists in your project root, Sheath automatically uses it unless you pass --ignore-baseline.

#Generate a Baseline

php artisan sheath:lint --generate-baseline

To write to a custom location:

php artisan sheath:lint --generate-baseline --baseline=build/sheath-baseline.json

#Use a Baseline

If sheath-baseline.json exists, a normal php artisan sheath:lint run will filter those recorded violations automatically.

You can also point to a specific file:

php artisan sheath:lint --baseline=sheath-baseline.json

To ignore the baseline temporarily:

php artisan sheath:lint --ignore-baseline

#Update a Baseline

After fixing issues, regenerate the baseline against the current code:

php artisan sheath:lint --update-baseline

Sheath prints the new count and whether the baseline shrank or grew.

An existing baseline is treated as configuration, not as an optional cache. Unreadable files, invalid JSON, malformed entries, and schema versions newer than the installed Sheath release fail the run instead of being ignored. A generate or update command also fails when its destination cannot be written.

#Matching Behavior

Baseline paths are project-relative, such as resources/views/home.blade.php, so the same baseline works locally and in CI.

A current violation matches an entry for the same file and rule when either:

the surrounding code still matches, or
the violation message matches and the line number is within the configured drift tolerance

The default line tolerance is 3, configurable via baselineLineTolerance in config/sheath.php.

Diagnostic text is deliberately part of baseline matching. If a rule correction changes its message, the old entry does not hide the newly described finding; the finding resurfaces and --update-baseline records the current diagnostic if it should remain baselined. Rule IDs are the stable machine identifiers, while messages may be refined between releases.

#One entry, one violation

Each entry excuses exactly one violation. If a file has one baselined a11y-alt-text finding and later gains a second on the next line, the first is filtered and the second is reported. A baseline hides recorded findings, not findings added later.

#File Format

The baseline file stores:

version
generated
violations
counts.total
counts.byRule

Example:

{
  "version": 3,
  "generated": "2026-03-11T10:00:00+00:00",
  "violations": {
    "resources/views/dashboard.blade.php": [
      {
        "ruleId": "a11y-alt-text",
        "line": 42,
        "message": "Images must have an alt attribute for accessibility.",
        "hash": "c82b347204bfa86b9a78a6842e89fe9e"
      }
    ]
  },
  "counts": {
    "total": 1,
    "byRule": {
      "a11y-alt-text": 1
    }
  }
}

#Recommended Workflow

# capture the current state
php artisan sheath:lint --generate-baseline

# commit the baseline
git add sheath-baseline.json
git commit -m "Add Sheath baseline"

# work normally; new issues still appear
php artisan sheath:lint

# periodically fix issues and shrink the baseline
php artisan sheath:lint --fix
php artisan sheath:lint --update-baseline

#CI Usage

- name: Lint Blade templates
  run: php artisan sheath:lint --max-warnings=0

If sheath-baseline.json is committed, Sheath will apply it automatically in CI as well.

#Best Practices

Commit the baseline file.
Review baseline diffs in pull requests.
Prefer shrinking the baseline over growing it.
Use --ignore-baseline occasionally to inspect the full remaining backlog.