catalyst v0.9.3

Performance linter for Crystal. Catches allocations, O(n²) patterns, and resource leaks before they reach production.

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

Repository

catalyst

Owner
Statistic
  • 0
  • 0
  • 0
  • 1
  • 0
  • 11 days ago
  • July 7, 2026
License

Links
Synced at

Wed, 04 Nov 2026 21:35:38 GMT

Languages