feat: add no-unused-vars rule

[nzakas]

Adds shell/no-unused-vars, which mirrors ShellCheck SC2034: variables that are assigned but never read.

Behavior

Writes tracked:

• assignments, including declare/local/typeset and arr[i]=;
• for loop variables;
• variables set by read, mapfile, and readarray (skipping read flags that take an argument, like -p prompt);
• the getopts variable;
• arithmetic assignments ((( total = 1 + 2 )), x++).

Reads tracked:

• any $var or ${...} expansion;
• bare names in arithmetic ($((x + 1)));
• the arguments of unset, export, and readonly;
• exported declarations (export or declare -x);
• environment prefixes (FOO=1 cmd), which are passed to the command.

Never reported:

• names starting with _;
• common special shell variables (IFS, PS1, PATH, OPTIND, REPLY, LC_*, and others);
• names listed in the rule's option: { "allowed": ["NAME"] }.

Skipped files: if the file uses eval, source/., or a nameref (declare -n / nameref), the rule reports nothing, since variables can then be read in ways static analysis can't see.

Other details:

• The rule has one object option (allowed), and this PR adds the README's "Rule options" section for it.
• Recommended config: "error".

Known limitations

• No function scoping. The analysis is file-wide, so an unused local x inside a function isn't reported if some other x is read elsewhere in the file.
• Indirect references aren't resolved. ${!ref} counts as a read of ref only, not of the variable it points to.

Documentation

Adds docs/rules/no-unused-vars.md, following the format of the @eslint/json, @eslint/css, and @eslint/markdown rule docs: description, background, rule details with incorrect and correct examples, options, when not to use it, and the ShellCheck reference. The rule's meta.docs.url points at that file, and its README table entry links to it.

Testing

23 RuleTester cases and 5 documentation checks (374 total); build, lint, and format checks pass.

🤖 Generated with Claude Code

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 55 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: eslint/coderabbit/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: c1113205-a002-4a19-b593-df023e43e9b5

📥 Commits

Reviewing files that changed from the base of the PR and between 74b6423 and 17c3d55.

📒 Files selected for processing (6)

• README.md
• docs/rules/no-unused-vars.md
• src/index.spec.ts
• src/index.ts
• src/rules/no-unused-vars.spec.ts
• src/rules/no-unused-vars.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot review overview

🟡 Changes recommended

Several valid Bash read/write contexts are misclassified, producing both false positives and false negatives.

Review effort: Balanced
Findings: 1

Open (1)

• Scan array-literal subscripts as arithmetic contexts · New

What changed in this PR

Adds the recommended bash/no-unused-vars rule with documentation and tests.

Changes:

• Implements file-wide variable read/write tracking.
• Registers the rule in the plugin and recommended configuration.
• Adds rule documentation, options, and test coverage.

File	Description
src/​rules/​no-unused-vars.ts	Implements unused-variable analysis.
src/​rules/​no-unused-vars.spec.ts	Tests core rule behavior.
src/​index.ts	Registers and enables the rule.
src/​index.spec.ts	Verifies rule exposure.
README.md	Documents the rule and option.
docs/​rules/​no-unused-vars.md	Adds detailed rule documentation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[nzakas]

@copilot address the review comment. Be sure to add tests.

[Copilot]

@copilot address the review comment. Be sure to add tests.

Addressed in d2a28ce, with tests for each case:

• Array literal subscripts (arr=([i]=v)) and ${s:offset:length} slices are now scanned as arithmetic reads.
• Operands of [[ a -eq b ]] (and the other arithmetic comparisons) count as reads.
• readonly x and declare -p x count as reads.
• export -n is no longer treated as an export or as a nameref.
• read -a arr records arr as a write, and mapfile flags that take an argument (such as -C and -u) are skipped.
• Every LC_* variable is now ignored, as the docs already said.

I also updated the docs.

[nzakas]

/easycla

[fasttime]

A note that ShellCheck has a more comprehensive list of special variables: https://github.com/koalaman/shellcheck/blob/61ceb720d121fb448b4e98bc10a14b756ac4da8c/src/ShellCheck/Data.hs#L27-L70