catalyst v0.9.3
Catalyst
Static performance analysis for Crystal.
Detects allocation anti-patterns, algorithmic complexity issues, and resource leaks before they reach production. Like Fasterer for Crystal.
Installation
git clone https://github.com/unurgunite/catalyst
cd catalyst
crystal build src/catalyst.cr --release -o bin/catalyst
Usage
# Scan a directory recursively
catalyst src/
# Scan specific files
catalyst src/app.cr src/lib.cr
# CI mode — exit code 1 on findings
catalyst --ci src/
# JSON output
catalyst --format json src/
# Only show findings at or above a severity
catalyst --severity error src/
# Apply safe auto-fixes
catalyst --fix src/
# See what --fix would change, without writing
catalyst --fix --dry-run src/
# Enable only specific rules
catalyst --rules CAT-001,CAT-002 src/
# Gate on new findings only (baseline workflow)
catalyst --update-baseline .catalyst-baseline.json src/
catalyst --baseline .catalyst-baseline.json --ci src/
# List all rules
catalyst --list-rules
--format and --severity override the values from .catalyst.yml.
Exit codes: 0 clean, 1 findings in --ci mode, 2 configuration or runtime error.
Auto-fix safety
--fix never writes a file it cannot re-parse: every rewritten file is parsed before it is saved, and any fix whose result would not parse is skipped with a diagnostic on STDERR. A finding whose replacement equals the original line is treated as a no-op. The original file is copied to <file>.bak before the first fix and an existing .bak is never overwritten, so a re-run cannot clobber the only pre-fix copy — delete or move the .bak yourself once you have reviewed the change. Use --dry-run to preview. Diagnostics always go to STDERR, so --format json and --format sarif output stays machine-readable on STDOUT.
Configuration
Create .catalyst.yml in project root:
severity: warning
format: terminal
rules:
CAT-001:
severity: error
ignore:
- lib/**
- "**/*_spec.cr"
paths:
- src/
lib/** keeps vendored shards out of the report: on real projects they accounted for the large majority of findings, and none of them are yours to fix. **/*_spec.cr does the same for test files — a spec that opens a socket on purpose is usually not a leak — though that one is a judgment call, so it is opt-in rather than built in.
Rules
All 43 rules are documented in the Wiki. Numbers are not contiguous: CAT-011, 019, 024, 036, 040, 044, 046, 047 and 048 were removed, and their numbers stay retired so an old ignore entry still means what it did.
Six rules are off by default, because their advice cannot be told apart from correct code by looking at the source:
| Rule | Why it is off | Turn it on with |
|---|---|---|
| CAT-014 | Whether a file is read whole or streamed depends on its size, which is not in the code. On 3166 third-party files all 49 findings were File.read on a config, a test fixture, or a method returning String. |
--rules CAT-014 |
| CAT-015 | Struct versus class is a memory decision that depends on the data's lifetime, which the syntax does not show. | --rules CAT-015 |
| CAT-017 | Whether local time is wrong depends on how and where the program runs. | --rules CAT-017 |
| CAT-038 | A capacity hint only pays off when the final size is known, and that is a runtime fact. | --rules CAT-038 |
| CAT-045 | Whether a raise is an expected failure or a bug is a trust-boundary question no syntax answers. |
--rules CAT-045 |
| CAT-049 | A thread is only the wrong choice when a fiber really suffices. | --rules CAT-049 |
Either form works for every one of them; --rules re-enables a rule for one run, a config entry for good:
rules:
CAT-014:
enabled: true
catalyst --list-rules marks them with [opt-in]. Turning one on does not lift it above --severity: CAT-014 reports info outside a loop, so a default warning run still hides it — add --severity hint when you want the full picture.
Quick reference:
catalyst --list-rules
Development
crystal spec
crystal run bin/ameba.cr --
crystal tool format --check
Two things the spec suite cannot check on its own:
# Apply every fix and compile the result. A fix can emit code that parses
# but does not build, which no assertion in the suite would notice.
crystal run scripts/check_fix_compiles.cr -- --run
# Compile every benchmark under bench/. CI runs this on each push.
for file in bench/cat-*/*.cr; do crystal build --no-codegen "$file"; done
License
MIT
catalyst
- 0
- 0
- 0
- 1
- 0
- 11 days ago
- July 7, 2026
Wed, 04 Nov 2026 21:35:38 GMT