@colrealpro/react-luau-doctor 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.20.0
+
+### Added
+
+- VS Code extension with live diagnostics and hover explanations, requiring no CLI or Bun installation
+- Quick fixes to explain findings, add inline disables, or disable rules in project config
+- Optional background scanning of unopened files
+- Autocomplete and validation for `react-luau-doctor.config.json`, with a schema in both packages
+
+### New rules
+
+- `react-luau/no-mutating-state-updater` catches mutations of previous state in updater callbacks
+- `react-luau/no-call-component-as-function` catches direct calls to component functions
+- `react-luau/no-create-binding-in-render` catches bindings recreated during render
+- `react-luau/no-binding-getvalue-in-render` catches binding snapshots read during render, except for ref initialization
+- `react-luau/usememo-must-return` catches memo callbacks that return no value
+- `react-luau/no-static-name-prop` suggests child table keys instead of static Roblox `Name` props
+
+### Fixed
+
+- Restored per-file CLI progress while parsing effects and sped up worker shutdown
+- `no-set-state-in-render` catches setters in prop expressions and local initializers, including aliases
+- `exhaustive-deps` follows dependency table aliases and handles shadowed module locals correctly
+- `no-prop-mutation` catches prop mutations in nested functions and callbacks
+- `no-array-index-as-key` uses collection shapes and types to distinguish array positions from dictionary keys
+- `rules-of-hooks` accepts loops over provably static module tables
+- `prefer-binding-over-state` skips custom component props proven incompatible with bindings
+
 ## 0.19.1
 
 ### Changed

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 ColRealPro
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 ColRealPro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,135 +1,148 @@
-# React-Luau Doctor
-
-Find React-Luau mistakes before they reach your Roblox UI.
-
-React-Luau Doctor checks `.lua` and `.luau` source files for hook mistakes, missing cleanup, render side effects, and avoidable rerenders. Findings include a category, severity, source location, and repair guidance. The `why` command explains individual findings and shows suggested changes where available.
-
-This beta CLI runs with Bun and analyzes React-Luau source on your computer or CI runner. It does not run inside Roblox Studio, analyze JavaScript/TypeScript React, or edit your code automatically.
-
-## Get started
-
-React-Luau Doctor requires [Bun](https://bun.com/) 1.4.0 or newer. Run it directly from npm with either Bun or npm:
-
-```bash
-bunx @colrealpro/react-luau-doctor .
-```
-
-```bash
-npx @colrealpro/react-luau-doctor .
-```
-
-`npx` still requires Bun to be installed because the React-Luau Doctor CLI itself runs with Bun.
-
-For a reusable `react-luau-doctor` command, install it globally with Bun:
-
-```bash
-bun add --global @colrealpro/react-luau-doctor
-react-luau-doctor .
-react-luau-doctor . --verbose
-```
-
-To work on React-Luau Doctor itself, clone the repository and use Bun for development:
-
-```bash
-git clone https://github.com/colrealpro/react-luau-doctor.git
-cd react-luau-doctor
-bun install --frozen-lockfile
-bun run build
-bun run ci
-```
-
-## Read a finding
-
-For example, this component changes a prop during render:
-
-```luau
-local React = require(script.Parent.React)
-
-local function Label(props)
-    props.text = "Changed"
-    return React.createElement("TextLabel", { Text = props.text })
-end
-
-return Label
-```
-
-Doctor reports `react-luau/no-prop-mutation`. Compute a local value instead of writing to `props`.
-
-```bash
-react-luau-doctor why src/Label.luau:4
-react-luau-doctor rules explain react-luau/no-prop-mutation
-```
-
-Suggested changes are review guidance. Some are exact previews, others are example patterns that need adapting to your component.
-
-## What it checks
-
-The rule catalog covers correctness, hooks, effects, performance, Roblox behavior, and architecture. Checks include conditional hooks, incomplete dependency tables, connections without cleanup, state updates during render, fresh props crossing memo boundaries, and externally updated state that may be better represented by a Binding.
-
-```bash
-react-luau-doctor rules list
-react-luau-doctor . --category Hooks
-react-luau-doctor . --blocking error
-```
-
-Errors are the highest severity. Warnings identify likely problems, while suggestions include lower-confidence findings that deserve review. You can override each rule's severity or disable it. A clean report is not proof of runtime correctness, and the score is a heuristic, not a performance measurement.
-
-See the [rule catalog](docs/rules.md) and [analysis limits](docs/analysis.md).
-
-## Check a change
-
-```bash
-react-luau-doctor . --scope changed --base main
-react-luau-doctor . --scope lines --base main
-react-luau-doctor . --staged
-react-luau-doctor . --json-out doctor-report.json
-```
-
-`changed` compares findings against a Git base. `lines` keeps findings that overlap changed lines. `--staged` reads index content, so later unstaged edits do not affect the checked file contents.
-
-## Add CI
-
-From your Roblox repository:
-
-```bash
-react-luau-doctor ci install --yes
-```
-
-Commit the generated `.github/workflows/react-luau-doctor.yml`. The workflow pins the exact npm version of React-Luau Doctor that generated it and runs that package with Bun, so your repository does not need to vendor the analyzer or its parser assets.
-
-By default, pull requests receive advisory findings without failing the check. Enable a gate with:
-
-```bash
-react-luau-doctor ci config --blocking error --yes
-```
-
-[CI setup](docs/ci.md) explains permissions, fork PRs, updates, outputs, and GitLab support. Local tests exercise reporting against a simulated GitHub API. A real GitHub Actions run is still required to validate your repository's permissions and runner behavior.
-
-## Configure a project
-
-Create `react-luau-doctor.config.json` in the directory where you run scans:
-
-```json
-{
-  "include": ["src/**/*.luau"],
-  "ignore": ["src/generated/**"],
-  "rules": {
-    "react-luau/no-array-index-as-key": "off",
-    "react-luau/exhaustive-deps": "error"
-  }
-}
-```
-
-Use narrow inline suppressions when an individual finding is intentional:
-
-```luau
--- react-luau-doctor-disable-next-line no-array-index-as-key
-```
-
-See the [CLI and configuration reference](docs/cli.md) for scanning, reporting, cache controls, and suppression syntax.
-
-## Contribute
-
-Read [development and release checks](docs/development.md). For a false positive or missed issue, open an [issue](https://github.com/colrealpro/react-luau-doctor/issues) with the smallest Luau example you can share, the tool version, and the relevant configuration.
-
-MIT licensed. Inspired by [React Doctor](https://github.com/millionco/react-doctor); not affiliated with its authors, Roblox, or the React-Luau maintainers. See [third-party notices](THIRD_PARTY_NOTICES.md) for parser attribution.
+<p align="center">
+  <img src="editors/vscode/Icon.png" alt="React-Luau Doctor icon" width="128" />
+</p>
+
+<h1 align="center">React-Luau Doctor</h1>
+
+<p align="center">
+  Static analysis tool for React-Luau codebases. It helps identify potential issues, enforce best practices, and improve React code quality.
+</p>
+
+<br>
+
+React-Luau Doctor scans your codebase and finds mistakes in hooks, effects, state management, and performance. Rules are built specifically around React-Luau patterns, including problems that can't be caught by traditional typechecking or linting. It works as a CLI or CI tool. Editor diagnostics can also be provided through the [LSP](docs/lsp.md) extension
+
+## Getting started
+
+React-Luau Doctor requires [Bun](https://bun.com/) 1.4.0 or newer. You can run it directly from npm with:
+
+```bash
+npx @colrealpro/react-luau-doctor
+```
+
+or install it globally and run it normally:
+
+```bash
+bun add --global @colrealpro/react-luau-doctor
+react-luau-doctor
+```
+
+This will create a short overview of your project, and report the highest severity issues, you can add `--verbose` to see all the findings
+
+## Examples
+
+```lua
+local React = require("..path/to/React")
+local RunService = game:GetService("RunService")
+
+local function PlayerList(props)
+	local playerCount, setPlayerCount = React.useState(0)
+	local absolutePosition, setAbsolutePosition = React.useState(
+		props.container.AbsolutePosition
+	)
+
+	local labelText = React.useMemo(function()
+		return `Players: {playerCount}`
+	end, { playerCount })
+
+	React.useEffect(function()
+		setPlayerCount(#props.players)
+	end, { props.players })
+
+	React.useEffect(function()
+		props.container:GetPropertyChangedSignal("AbsolutePosition"):Connect(function()
+			setAbsolutePosition(props.container.AbsolutePosition)
+		end)
+	end, { props.container })
+
+	if props.hidden then
+		return nil
+	end
+
+	React.useEffect(function()
+		print(props.title)
+	end, { props.title })
+
+	return React.createElement("TextLabel", {
+		Text = labelText,
+		Position = UDim2.fromOffset(absolutePosition.X, absolutePosition.Y),
+	})
+end
+```
+
+React-Luau Doctor would report the following for this component:
+
+```
+src/PlayerList.lua
+
+  X error    Hook React.useEffect may run after an earlier reachable return,
+             so some renders can execute fewer hooks.
+             react-luau/rules-of-hooks
+
+  ! warning  setPlayerCount() stores a value derived from props inside an effect.
+             react-luau/no-derived-state-effect
+
+  ! warning  State absolutePosition mirrors AbsolutePosition and only feeds
+             presentation updates, so React reconciliation is acting as an
+             unnecessary host-property feedback step.
+             react-luau/prefer-binding-over-state
+
+  ! warning  Effect creates a connection or subscription without matching cleanup.
+             react-luau/effect-needs-cleanup
+
+  ! warning  useMemo caches a trivial derived value.
+             react-luau/rerender-unnecessary-usememo
+```
+
+## Editor support
+
+React-Luau Doctor provides a LSP extension for VS Code
+
+The LSP uses the same analysis as the CLI, and updates findings in real time as you edit your code
+
+See [LSP](docs/lsp.md) for installation and configuration
+
+## CI
+
+React-Luau Doctor also provides a CI that can be used to run analysis on your codebase and report findings in PRs, or be used to block merging if doctor finds issues (can't promise satisfaction on blocking merging though yet)
+
+Install it with:
+
+```bash
+react-luau-doctor ci install
+```
+
+It will bring you through a couple options, you can skip it and use the defaults by adding `--yes` to the command
+
+## Configuring rules
+
+Create a `react-luau-doctor.config.json` file in your project:
+
+```json
+{
+  "ignore": [
+    "**/*.story.lua",
+    "**/*.story.luau"
+  ],
+  "rules": {
+    "react-luau/no-array-index-as-key": "off",
+    "react-luau/exhaustive-deps": "error"
+  }
+}
+```
+
+This will let you enable and disable some rules or change their severity to your liking if you dislike some of the rules.
+
+Inline disables can also be used when a finding is intentional:
+```lua
+-- react-luau-doctor-disable-next-line no-array-index-as-key
+```
+
+## Contributing
+
+All contributions are welcome! Bug fixes, new rules, improvements to existing rules, and documentation changes are all appreciated!
+
+Feel free to open an issue for bugs or feature requests, or submit a pull request
+
+
+MIT licensed. Inspired by [React Doctor](https://github.com/millionco/react-doctor); not affiliated with its authors, Roblox, or the React-Luau maintainers. See [third-party notices](THIRD_PARTY_NOTICES.md) for parser attribution.

package/THIRD_PARTY_NOTICES.md

@@ -1,18 +1,25 @@
-# Third-party notices
-
-## tree-sitter-luau
-
-This project redistributes `tree-sitter-luau.wasm` from
-`tree-sitter-grammars/tree-sitter-luau`, version 1.2.0.
-
-The grammar is MIT licensed. Its license text is included at
-`vendor/tree-sitter-luau.LICENSE`.
-
-Project: https://github.com/tree-sitter-grammars/tree-sitter-luau
-
-## web-tree-sitter
-
-The runtime parser is provided by `web-tree-sitter`, which is MIT licensed.
-Its license is installed with the npm dependency.
-
-Project: https://github.com/tree-sitter/tree-sitter
+# Third-party notices
+
+## tree-sitter-luau
+
+This project redistributes `tree-sitter-luau.wasm` from
+`tree-sitter-grammars/tree-sitter-luau`, version 1.2.0.
+
+The grammar is MIT licensed. Its license text is included at
+`vendor/tree-sitter-luau.LICENSE`.
+
+Project: https://github.com/tree-sitter-grammars/tree-sitter-luau
+
+## web-tree-sitter
+
+The runtime parser is provided by `web-tree-sitter`, which is MIT licensed.
+Its license is installed with the npm dependency.
+
+Project: https://github.com/tree-sitter/tree-sitter
+
+## jsonc-parser
+
+Project config edits use Microsoft's MIT-licensed `jsonc-parser`
+Its license is installed with the npm dependency and included in the VS Code extension at `vendor/jsonc-parser.LICENSE`
+
+Project: https://github.com/microsoft/node-jsonc-parser