Rake syntax lint guide

Generated by rake lint --guide; edit the rule catalogue, then regenerate. Use rake lint --guide=agents for the compact AGENTS.md block; refresh an existing marked block with rake lint --guide=agents --update AGENTS.md. Optional PostToolUse feedback uses rake lint --hook (stdin JSON, advisory output).

After editing Rust or view! markup, run rake format, then rake lint. Use rake lint --fix for machine-safe edits and rake format --check in CI. A reasoned // rake-lint: allow(ID) reason suppresses a Rust finding; use # rake-lint: allow(ID) reason in Cargo.toml. For one intentional decision throughout a file, use a standalone // rake-lint: allow-file(ID) reason in the file header, before code (or # rake-lint: allow-file(ID) reason before TOML entries). The reason is required. File scope covers only that rule in that file; unused, duplicate or misplaced file directives report invalid-suppression. Use a line suppression for a local exception. Configure rust-analyzer with:

[rustfmt]
overrideCommand = ["rake", "format", "--stdin"]

See docs/format.md and docs/lint.md for command and configuration details. This guide covers syntax only; it does not establish type-aware GPUI correctness.

view-style-class (warn)

style closure has an exact class equivalent

Pure zero-argument utility method chains duplicate the class vocabulary, making intent harder for agents to recognize. Write the equivalent class utilities in the same attribute position. The syntax tier accepts only methods emitted verbatim by the shared class compiler, without conversions, captured values, side effects or variants. Existing class attributes and component properties are left alone. Comments inside the attribute prevent an automatic edit.

What to write instead: replace the style attribute with the equivalent class string, preserving attribute order

Before:

<div style={|s| s.flex().gap_4()}/>

After:

<div class="flex gap-4"/>

view-theme-literal (warn)

literal color or design size bypasses the installed theme

Literal colors, typography sizes and corner radii cannot follow a theme change. In a package with an explicit rake::theme::install call or rake::App::new(...).theme(...) chain, prefer semantic theme utilities or read the installed theme in a dynamic style. This conservative check covers arbitrary color/text/radius classes and literal rgb/rgba/hsl/hsla or px/rems constructor arguments in the corresponding style methods. Ordinary layout spacing is not diagnosed. It does not expand macros, evaluate cfg, follow aliases or prove which theme a view uses; suppress intentional samples with a reason.

What to write instead: use a semantic utility such as bg-surface, text-ink, text-body or rounded-control; keep dynamic styles for theme values

Before:

<div class="bg-[#112233] text-[13px]"/>

After:

<div class="bg-surface text-body"/>

release-debug-assertions (warn)

debug assertions are explicitly enabled in a release profile

Release builds normally disable debug assertions. Enabling this development control retains debug-only checks and cfg(debug_assertions) code in shipped artifacts. Set debug-assertions to false for release and profiles inheriting release, including explicit package/build overrides; keep intentional diagnostics builds separate or suppress this setting with a reason. Cargo profiles do not select features, so this rule never guesses release devtools selection from feature declarations or dependencies.

What to write instead: set debug-assertions = false; use the dev profile for development checks

Before:

[profile.release]
debug-assertions = true

After:

[profile.release]
debug-assertions = false

view-button-label (warn)

button content has no automatic accessible label

Rake automatically labels only nonempty buttons made entirely of literal text. Icons, expressions, and control-flow children need an explicit label so assistive technology can name the action. Use the visible text as the label (label-in-name); add context only after it. For icon-only buttons, name the action.

What to write instead: add aria-label={visible_text}; use the visible text as the label (label-in-name); add context only after it

Before:

<button>{title.clone()}</button>
<button>{icon}</button>

After:

<button aria-label={title.clone()}>{title.clone()}</button>
<button aria-label="Search">{icon}</button>

view-image-alt (deny)

image is missing alt text

The img tag maps alt to its accessible label. Describe meaningful images; an empty alt explicitly marks a decorative image. aria-label does not replace the required alt attribute.

What to write instead: add alt="Description", or alt="" for a decorative image

Before:

<img src="logo.png"/>

After:

<img src="logo.png" alt="Company logo"/>

view-loop-index-id (warn)

loop item ID is derived from an enumerate index

Position changes when items are reordered or inserted, moving retained focus and state to another item. This syntax rule recognizes index bindings from enumerate(), including rev/skip/take/step_by/by_ref adapters. It checks direct IDs, tuples, casts, arithmetic, index methods and format! arguments/captures. Arbitrary calls and data lookups are opaque; identifier spelling alone never makes a value an index.

What to write instead: replace the index in id with a stable data key, such as row.id

Before:

for (index, row) in rows.iter().enumerate() { <div id={("row", index)}/> }

After:

for row in &rows { <div id={("row", row.id)}/> }

suppression-reason (warn)

lint suppression needs a reason

A reason documents why a rule does not apply here. A suppression without a reason is ignored, so the original diagnostic is still reported.

What to write instead: append a nonempty reason after allow(<rule-id>) or allow-file(<rule-id>)

Before:

// rake-lint: allow(view-button-label)

After:

// rake-lint: allow(view-button-label) The mounted widget supplies its own name.

invalid-suppression (warn)

invalid lint suppression

Suppressions must name one known, suppressible rule and have a reason. Misspellings and malformed directives are ignored. Use allow-file only as a standalone file-header comment for an intentional decision applying throughout that file. Unused file suppressions, including duplicates and those made redundant by allow levels, are reported here; remove them when no emitted finding needs the exception. Syntax errors and suppression diagnostics cannot themselves be suppressed.

What to write instead: use a reasoned allow directive; put allow-file in the file header and remove unused file suppressions

Before:

// rake-lint: allow(view-buton-label) Named by widget.

After:

// rake-lint: allow(view-button-label) Named by widget.

syntax-error (deny)

source could not be parsed

The syntax tier uses syn and the real view parser, without compiling the project. Unparseable Rust or view markup prevents a complete check and is always an error. This is a parse check, not validation of all attributes, classes, types, or macro expansions.

What to write instead: correct the syntax at the reported location and run rake lint again

Before:

<div></span>

After:

<div></div>