luauperf 1.0.3

A static performance linter for Luau
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# luau-perf

A static performance linter for Luau.

## What it does

Scans `.lua` / `.luau` files for performance antipatterns - allocations in loops, untracked connections, deprecated APIs, missing `--!native` headers, and things that prevent FASTCALL/GETIMPORT optimizations.

## Install

```bash
cargo install luauperf
```

Requires [Rust](https://rustup.rs). Or build from source (see below).

## Getting started

```bash
# Lint a directory
luauperf src/

# JSON output for CI or editor integration
luauperf src/ --format json

# See all available rules.
luauperf --list-rules

# Generate a config file.
luauperf --init

# Attempt to automatically fix warnings and errors
luauperf src/ --fix
```

## Config

Add a `luauperf.toml` to your project root:

```toml
# Exclude paths (substring match).
exclude = ["Packages/", "Generated/", "node_modules/"]

[rules]
# Override severity per rule: "error", "warn", or "allow".
"roblox::missing_strict" = "allow"
"cache::magnitude_over_squared" = "error"
"roblox::pcall_in_loop" = "warn"
```

## Rules

Rules are grouped into categories:

- **complexity** - O(n²) patterns, unnecessary work in hot loops.
- **cache** - Things you should compute once and reuse.
- **memory** - Connection leaks, untracked threads, missing cleanup.
- **roblox** - Deprecated APIs, engine-specific footguns.
- **alloc** - Heap allocations in hot paths (strings, closures, tables).
- **native** - Things that break `--!native` codegen.
- **math** - Deprecated math APIs, manual implementations of builtins.
- **string** - String allocations, deprecated patterns.
- **table** - Deprecated table APIs, O(n) shifts.
- **network** - Remote events/functions fired in loops.
- **physics** - Expensive spatial queries in loops.
- **render** - GUI/particle/beam creation in loops.
- **instance** - Instance API misuse.
- **style** - Code quality signals with perf implications.

Full list: [RULES.md](RULES.md), or run `luauperf --list-rules`.

**Severity levels:**
- `error` - Almost certainly a bug or major perf issue.
- `warn` - Probably a problem, worth looking at.
- `allow` - Off by default, turn on in config if you want them.

## Inline ignores

Suppress specific rules per-line, per-next-line, or per-file with comments:

```lua
-- Ignore specific rules on this line
local x = wait() -- luauperf-ignore: roblox::deprecated_wait

-- Ignore all rules on this line
local y = wait() -- luauperf-ignore

-- Ignore specific rules on the next line
-- luauperf-ignore-next-line: alloc::closure_in_loop
local fn = function() end

-- Ignore rules for the entire file (must be in the file header)
--!native
--!strict
-- luauperf-ignore-file: roblox::deprecated_wait, style::print_in_hot_path
```

File-level ignores must appear in the header (before any code), but can be placed after `--!native`, `--!strict`, `--!optimize` directives and other comments.

## Building from source

```bash
git clone https://github.com/bopmite/luauperf
cd luauperf
cargo build --release
# Binary at target/release/luauperf
```

## License

MIT - see [LICENSE](LICENSE).