@colrealpro/react-luau-doctor 0.17.6 → 0.18.0

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.17.6",
+  "version": "0.18.0",
   "description": "Static analysis for React-Luau hooks, effects, rendering, and performance.",
   "license": "MIT",
   "type": "module",
@@ -15,8 +15,7 @@
     "vendor",
     "README.md",
     "LICENSE",
-    "THIRD_PARTY_NOTICES.md",
-    "docs"
+    "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "build": "bun run scripts/build.ts",

package/docs/analysis.md

@@ -1,37 +0,0 @@
-# How analysis works
-
-Doctor parses source with `web-tree-sitter` and a bundled Luau grammar. It builds a model of React aliases, functions, hooks, state, refs, and component calls before running rules. It never executes the Luau program.
-
-## File and project evidence
-
-Requires and local aliases identify React and ReactRoblox usage. A namespace does not need to be named `React`. Directory scans filter out modules without React evidence, but supporting modules can still contribute to project analysis.
-
-Cross-file resolution compares normalized path segments. Short names are used only when they identify a unique module; longer unique matches take precedence. This avoids confusing `Controller` with `SessionController`, or guessing between two unrelated `Button` modules. Dynamic requires and runtime module selection can remain unresolved.
-
-The project model summarizes memoized components, externally updated state hooks, callback wrappers, state/Binding API pairs, and source-visible effects. Effect propagation follows imports and calls to find operations that mutate external state during render. Unknown opaque methods are not automatically assumed to have side effects.
-
-## Binding recommendations
-
-The Binding rules trace state updated by external callbacks, including signals and frame events. They inspect how consumers read that state before recommending a Binding.
-
-A warning can be justified when reads flow into bindable host properties or through a custom component proven to forward them. Mixed structural use and unknown component props can produce a lower-confidence candidate instead. A Binding cannot replace every state value: values controlling child structure or other ordinary Lua decisions may still need React state.
-
-Measurement hooks have additional producer-side evidence: a property-change subscription, a read of that property, and a state update. Their recommendations may require a Binding-aware effect or a larger consumer refactor. Dual state/Binding hooks and sibling APIs are inferred from available source, not a configurable list of project hook names.
-
-## Syntax compatibility
-
-A preprocessing pass adapts certain modern Luau constructs that the grammar does not directly support. It aims to preserve byte offsets and line positions. Remaining parse failures are reported as `react-luau/parse-error`, and other rules stop for that file to avoid cascaded findings.
-
-## Confidence and scope limits
-
-Static evidence cannot establish all runtime behavior. Dynamic dispatch, metatables, unavailable dependencies, and indirect ownership can lead to missed findings or findings that need human judgment. Test a proposed repair in Roblox and profile performance changes when relevant.
-
-Git changed scope compares diagnostic multisets using file, rule, severity, and message. Moving a finding within the same file usually does not make it new. Replacing one finding with another identical finding can cancel out in that comparison.
-
-Scoped scans overlay selected file contents on current project context. They do not reconstruct every file from the historical revision. Deleted files are included in baseline accounting, but cross-file changes can still make historical inference imperfect. Use a full scan and review both revisions when investigating a cross-file regression.
-
-The health score weights findings by severity and scanned-file count. It is a triage aid, not an estimate of FPS, reliability, or production readiness. Zero findings can also mean that no eligible React files were found; check `scannedFiles` and partial-report fields.
-
-## Supported input
-
-Doctor targets source-controlled `.lua` and `.luau` files using React-Luau. It does not read Roblox place files, inspect a live Studio session, analyze `.tsx`, or provide DOM, CSS, React Native, or Next.js checks. The npm package is a CLI distribution; a public programmatic API is not supported.

package/docs/ci.md

@@ -1,71 +0,0 @@
-# CI setup
-
-There are two workflows to distinguish: this repository's own build/test CI, and the analyzer workflow installed into your Roblox repository.
-
-## Install into a Roblox repository
-
-Run React-Luau Doctor as described in the [README](../README.md). From the Roblox repository, run:
-
-```bash
-react-luau-doctor ci install --yes
-```
-
-Commit `.github/workflows/react-luau-doctor.yml`. The generated workflow installs Bun, then runs the exact npm package version that generated the workflow, for example `@colrealpro/react-luau-doctor@<version>`. This keeps CI reproducible without committing Doctor's bundle, parser grammar, or dependencies into your repository.
-
-The workflow checks out full Git history. Pull requests use `changed` scope by default. Pushes to `main` run a full advisory scan. Change the branch trigger if your default branch has another name.
-
-## Gates and reporting
-
-```bash
-react-luau-doctor ci config --blocking error --scope changed --yes
-react-luau-doctor ci config --no-comment --no-review-comments --no-commit-status --yes
-```
-
-The default gate is `none`. `error` fails a PR check for errors; `warning` fails for warnings or errors. Push scans remain advisory regardless of this setting.
-
-The generated workflow requests `contents: read`, `pull-requests: write`, `issues: write`, and `statuses: write`. Reporting can create or update a summary, add up to 20 inline comments for findings introduced by a new commit, resolve threads after their findings are fixed, and publish a commit status. Unchanged findings keep their original threads and do not create new notifications. Only bot-authored comments carrying Doctor's markers are managed. Summary details are capped; the workflow log contains the report.
-
-Inline comments use primary diagnostic lines present in the diff. A finding included through a secondary evidence highlight can appear in the report without an inline comment. Fixed-issue counts include findings removed by deleting files and respect project selection and configuration.
-
-GitHub API requests retry rate-limit responses. Retries honor `Retry-After` and primary rate-limit reset headers. Doctor stops instead of waiting when GitHub asks it to pause for more than 60 seconds, leaving the scan result and gate intact.
-
-Fork PR tokens commonly lack write permissions. Reporting failures are logged while scan results, outputs, and the configured gate remain available. Disabling reporting avoids those API calls. Keep the `pull_request` trigger; do not switch to `pull_request_target` to obtain write access while executing PR-controlled files.
-
-## Upgrade
-
-Run the latest Doctor version, then regenerate the managed workflow:
-
-```bash
-bunx @colrealpro/react-luau-doctor@latest ci upgrade --yes
-```
-
-This preserves supported workflow settings while updating the pinned npm version. Review and commit the generated change. `ci config` also regenerates the managed workflow using the version of Doctor that invokes it. Keep custom workflow logic in a separate workflow.
-
-`ci install` and `ci upgrade` accept `--pr`, which uses authenticated GitHub CLI access to create a branch, commit generated files, push, and open a PR. Omit it when you want to review the file locally first.
-
-## Outputs
-
-The generated GitHub step has the id `doctor` and writes these outputs through `GITHUB_OUTPUT`, so later steps in the same job can read values such as `${{ steps.doctor.outputs.score }}`.
-
-| Output | Meaning |
-| --- | --- |
-| `score` | Heuristic score for the reported findings. |
-| `total-issues` | Number of reported diagnostics. |
-| `fixed-issues` | Baseline findings removed by a PR. |
-| `error-count` | Reported errors. |
-| `warning-count` | Reported warnings. |
-| `affected-files` | Files with reported findings. |
-
-## GitLab
-
-```bash
-react-luau-doctor ci install --provider gitlab --blocking error --yes
-```
-
-Commit `.gitlab-ci.yml`. The generated job uses a pinned Bun image and runs the exact npm package version that generated the workflow. It does not publish merge-request comments or statuses. Full Git history is requested; explicitly adapt the comparison base to your merge-request workflow if needed. Existing unrelated `.gitlab-ci.yml` files are not overwritten.
-
-## Verification
-
-The test suite simulates GitHub API requests for summary creation and updates, new review findings, resolved review threads, rate-limit retries, commit statuses, forbidden responses, generated workflow behavior, and shell input handling. Package verification also checks that `ci install` from the packed distribution generates a version-pinned npm workflow without vendoring Doctor into the target repository.
-
-Before enabling a required check, run real PRs in your repository that introduce an error, repair it, delete an affected component, and originate from a fork. Confirm the gate, outputs, comments, and status behavior. Local simulation does not validate GitHub account permissions or hosted-runner behavior.

package/docs/cli.md

@@ -1,115 +0,0 @@
-# CLI and configuration
-
-Examples use the installed `react-luau-doctor` command. For one-off use, run the same arguments through `bunx @colrealpro/react-luau-doctor` or `npx @colrealpro/react-luau-doctor`; Bun must be installed either way.
-
-## Scan targets
-
-```bash
-react-luau-doctor .
-react-luau-doctor src/interface --verbose
-react-luau-doctor src/interface/Label.luau
-react-luau-doctor . --project client,shared
-```
-
-Directory discovery selects `.lua` and `.luau` files with React or ReactRoblox evidence. Explicit file targets are always analyzed and bypass directory include/ignore filters. Dependency and output directories such as `node_modules`, `Packages`, `DevPackages`, `ServerPackages`, `vendor`, `build`, `dist`, and `.git` are skipped during discovery.
-
-Local subdirectory scans use the configuration in the command's working directory, with paths reported relative to that directory. Run from the project root for consistent paths.
-
-## Git scopes
-
-| Scope | Result |
-| --- | --- |
-| `full` | Findings across the selected target. No Git repository required. |
-| `files` | All findings in changed files. |
-| `changed` | Findings in changed files that were not present in the baseline. |
-| `lines` | Findings whose primary span or evidence highlights overlap changed lines. |
-
-Pass `--base main` or a commit to choose an explicit comparison. Use `--include-untracked` to include new untracked files, or `--changed-files-from paths.txt` for a newline-separated path list. Git scopes respect configured include/ignore patterns.
-
-`--staged` checks Git index content. It uses file scope unless line scope is requested. Project context includes other source files on disk; this is not an isolated checkout of the complete index or baseline. See [analysis limits](analysis.md).
-
-## Output and exit codes
-
-```bash
-react-luau-doctor . --verbose
-react-luau-doctor . --json --json-compact
-react-luau-doctor . --json-out doctor-report.json
-react-luau-doctor . --output-dir .doctor
-react-luau-doctor . --blocking warning
-```
-
-Local scans default to `--blocking error`. The default display summarizes findings. `--verbose` adds per-file details and help. `--output-dir` writes `report.json`, `diagnostics.json`, and `summary.json`.
-
-JSON schema version 1 includes the root, scanned file count, duration, score, severity counts, and diagnostics. Each diagnostic has an ID, rule, category, severity, message, file, and location. Help, evidence highlights, and suggested-change previews may also be present. IDs include source offsets, so moving code can change an ID.
-
-`--blocking none` is advisory, `error` fails for errors, and `warning` fails for warnings or errors. Findings that pass the gate return 0; a failed gate or command error returns nonzero. Suggestions do not independently fail a gate. Filters affect reported findings and therefore the gate.
-
-Use `--category Hooks`, repeatable for multiple categories, or `--min-severity warning` to narrow results. `--no-warnings` selects errors only. `--no-score` hides the score and `--no-color` disables ANSI colors.
-
-`--max-duration 10` requests a shared scan budget in seconds. Budget exhaustion returns a partial report with skipped files; individual analysis operations can exceed the deadline before the next checkpoint. Do not treat a partial report as a complete audit.
-
-## Configuration
-
-Doctor reads `react-luau-doctor.config.json` from the directory where the command is run. It does not search ancestor directories for local scan configuration.
-
-```json
-{
-  "include": ["src/**/*.luau", "shared/**/*.lua"],
-  "ignore": ["src/generated/**"],
-  "respectInlineDisables": true,
-  "rules": {
-    "react-luau/exhaustive-deps": "error",
-    "react-luau/no-array-index-as-key": "off"
-  }
-}
-```
-
-A rule setting is `error`, `warning`, `suggestion`, or `off`. An explicit severity applies to every finding from that rule, including findings normally downgraded for uncertainty. Without an override, individual findings may have lower severity than the rule default. Unknown rule IDs produce an error.
-
-Patterns support `*`, `**`, and `?`; they are not full gitignore syntax. `**/` can match zero directories. Paths are relative to the scan project root.
-
-You can edit rule policy through the CLI:
-
-```bash
-react-luau-doctor rules set react-luau/exhaustive-deps error
-react-luau-doctor rules disable react-luau/no-array-index-as-key
-react-luau-doctor rules list --configured --json
-```
-
-## Suppressions
-
-```luau
--- react-luau-doctor-disable-next-line no-prop-mutation
-props.value = "legacy"
-
--- react-luau-doctor-disable no-array-index-as-key
--- intentional code here
--- react-luau-doctor-enable no-array-index-as-key
-```
-
-Bare rule names and names prefixed with `react-luau/` are accepted. Prefer a next-line suppression and add a comment explaining the exception. `--no-respect-inline-disables` includes suppressed findings during an audit.
-
-## Explain a finding
-
-```bash
-react-luau-doctor why src/Label.luau:12
-react-luau-doctor rules explain react-luau/exhaustive-deps
-```
-
-`rules explain` accepts a full rule ID or a short name such as `exhaustive-deps`. It shows what the rule checks, current and suggested code, and repair notes. Add `--json` to receive the same example as `example.before`, `example.after`, `example.note`, and `example.kind`. Examples describe a pattern; they are not edits inferred from your project.
-
-`why` rescans with project context and shows matching findings, code frames, rule intent, confidence, repair guidance, and available previews. Review example-pattern previews before applying them.
-
-## Cache
-
-Doctor stores an incremental cache outside the scanned repository:
-
-| Platform | Default location |
-| --- | --- |
-| Linux | `$XDG_CACHE_HOME/react-luau-doctor`, otherwise `~/.cache/react-luau-doctor` |
-| macOS | `~/Library/Caches/react-luau-doctor` |
-| Windows | `%LOCALAPPDATA%/react-luau-doctor/Cache` |
-
-Set `REACT_LUAU_DOCTOR_CACHE_DIR` to choose a location. Use `--no-cache` or `REACT_LUAU_DOCTOR_DISABLE_CACHE=1` to bypass it. Cache entries can include source-derived information, so treat the directory as local project data.
-
-For the complete option list, run `react-luau-doctor --help`.

package/docs/development.md

@@ -1,63 +0,0 @@
-# Development and releases
-
-Use Bun 1.4.0 for reproducible release builds. Newer Bun versions can run the CLI, but bundle output can vary with the builder version. Git is required by the scoped-scan tests. Package verification needs `tar` and registry access. It uses npm when available, otherwise runs npm through Bun.
-
-## Work locally
-
-```bash
-bun install --frozen-lockfile
-bun run check
-bun test
-bun run build
-```
-
-`bun test` runs fixture-based rules, Git scope cases, configuration tests, CLI subprocesses, generated CI tests, and simulated GitHub API reporting. The API tests bind only to loopback and use a test token.
-
-`dist/` is generated output and should not be committed. Keep `vendor/` and `bun.lock` tracked. npm's `prepack` hook rebuilds `dist/` before packing or publishing.
-
-## Source layout
-
-| Path | Responsibility |
-| --- | --- |
-| `src/cli.ts` | Commands, options, explanation output, exit gates. |
-| `src/scanner.ts` | File scans, rule execution, diagnostic construction. |
-| `src/ast/` | Syntax traversal and file-level React evidence. |
-| `src/project-model.ts` | Cross-file React relationships. |
-| `src/project-effects.ts` | Source-visible effects and propagation. |
-| `src/rules/` | Rule definitions and repair guidance. |
-| `src/git.ts`, `src/scope.ts` | Git content selection and comparisons. |
-| `src/ci.ts` | Generated workflows, npm version pinning, GitHub reporting. |
-| `vendor/` | Luau parser grammar and its license. |
-
-The build bundles `src/cli.ts` into `dist/cli.js`, leaving runtime dependencies external. `dist/` exists for the npm distribution, where the package `bin` points at `dist/cli.js`; it is not a source-controlled CI runtime. The parser locates its grammar relative to the published package layout.
-
-## Change a rule
-
-Add a minimal failing fixture and a valid counterpart. Test the intended diagnostic, location, default severity, and help. Cover explicit severity overrides when a rule supplies confidence-based severities. Register new rules in `src/rules/index.ts`, add a before/after repair example in `src/fix-examples.ts`, and update the catalog in `docs/rules.md`. Tests require an example for every rule and parse each suggested snippet.
-
-Check a proposed repair in Roblox where runtime behavior matters. Tests of syntax alone cannot validate UI behavior or performance.
-
-## Change CI
-
-Generated GitHub and GitLab workflows pin `${package name}@${package version}` from `package.json` and resolve the package from npm at run time. Keep the package version pin exact rather than using `latest` in generated CI, so a repository only changes analyzer versions when its workflow is regenerated.
-
-Pass variable workflow values through environment variables rather than interpolating them directly into shell source. Tests cover generated settings, package pinning, and shell metacharacters.
-
-Repository CI typechecks, tests, builds, and verifies the packed npm distribution. `dist/` is ignored, so CI does not compare generated bundle bytes against committed artifacts.
-
-## Release checklist
-
-1. Update the version in `package.json`. A version change also invalidates persistent analysis caches.
-2. Build with Bun 1.4.0 and run the full local checks with `bun run ci`.
-3. Run `npm pack --dry-run` to inspect the package list. It must include `dist/cli.js`, the grammar, license notices, and docs, while excluding tests, dependencies, development-only source files, and CI-only runtime copies.
-4. Run `bun run verify:package` to pack, install, scan, and generate CI from an isolated tarball.
-5. Commit source, documentation, and lockfile changes, then push to `colrealpro/react-luau-doctor` and wait for repository CI. Do not commit `dist/`.
-6. Publish the verified npm version and confirm `bunx @colrealpro/react-luau-doctor@<version> --version` resolves from the registry.
-7. Generate CI from the published version and test real PR reporting plus a fork PR in a disposable repository before recommending required checks.
-8. Create the matching release tag after the published package and hosted CI behavior are verified.
-
-npm distributes the developer CLI; it does not install a runtime library into Roblox. Release commands are still manual: this checkout does not publish packages, create releases, or push changes automatically.
-
-## Report a problem
-
-Include the tool version, Bun version, operating system, minimal Luau source, configuration, and the command you ran. For Git-related issues, describe the base revision and whether edits were staged. Remove private source and tokens from shared reports.

package/docs/rules.md

@@ -1,56 +0,0 @@
-# Rule catalog
-
-Doctor currently includes 35 rules. This table lists their default severities; individual findings can be downgraded when evidence is uncertain. Explicit configuration overrides the severity for every finding from that rule.
-
-| Rule | Default | Category | Checks |
-| --- | --- | --- | --- |
-| `react-luau/parse-error` | error | Correctness | Report executable Luau syntax that the bundled parser cannot form into a complete syntax tree. |
-| `react-luau/rules-of-hooks` | error | Hooks | Hooks must run in the same order on every render of a React component or custom hook. |
-| `react-luau/exhaustive-deps` | warning | Hooks | React hook dependency tables should include captured reactive render values. |
-| `react-luau/effect-needs-cleanup` | warning | Effects | Effects that create owned resources or outliving tasks should return matching cleanup. |
-| `react-luau/no-derived-state-effect` | warning | Effects | Avoid copying render-known derived values into state from an effect. |
-| `react-luau/no-self-updating-effect` | warning | Effects | Effects should not unconditionally update state that is also one of their dependencies. |
-| `react-luau/no-effect-with-fresh-deps` | error | Hooks | Dependency tables should not contain tables or functions recreated on every render. |
-| `react-luau/no-mutable-in-deps` | error | Hooks | Mutable ref.current values do not belong in hook dependency tables. |
-| `react-luau/prefer-binding-over-state` | warning | Performance | Prefer React.useBinding when externally updated values do not need React reconciliation on every change. |
-| `react-luau/prefer-binding-over-state-candidate` | suggestion | Performance | Surface lower-confidence state-to-Binding opportunities that need developer review. |
-| `react-luau/rerender-unstable-memo-props` | warning | Performance | Warn when fresh table or function props defeat shallow React.memo comparisons. |
-| `react-luau/rerender-high-frequency-state` | warning | Performance | Find state updates from frame callbacks that can rerender expensive component trees continuously. |
-| `react-luau/rerender-unnecessary-usememo` | warning | Performance | Find trivial derived values that cost more to memoize than to compute directly. |
-| `react-luau/rerender-unnecessary-usecallback` | warning | Performance | Find useCallback values whose stable function identity is never observed. |
-| `react-luau/rerender-static-discovery-in-render` | warning | Performance | Find static Instance/module discovery repeated during component render. |
-| `react-luau/rerender-repeated-collection-scan` | warning | Performance | Find repeated direct render passes over the same collection expression. |
-| `react-luau/rerender-static-state` | warning | Performance | Find React state whose setter is never used and therefore cannot change. |
-| `react-luau/prefer-use-ref-for-mutable-cell` | suggestion | Hooks | Prefer useRef over useMemo-created tables that only emulate a mutable current cell. |
-| `react-luau/rerender-functional-setstate` | warning | Performance | Use the functional state setter form when deferred callbacks update from the previous state value. |
-| `react-luau/rerender-lazy-state-init` | warning | Performance | Expensive useState initializers should use React's lazy initializer form. |
-| `react-luau/rerender-lazy-ref-init` | warning | Performance | Avoid eagerly rebuilding expensive values passed to useRef on every render. |
-| `react-luau/rerender-state-only-in-handlers` | warning | Performance | State that is only read from callbacks may be mutable data rather than rendered state. |
-| `react-luau/no-set-state-in-render` | warning | Correctness | Do not call a component's state setter unconditionally during render. |
-| `react-luau/no-direct-state-mutation` | warning | Correctness | Do not mutate table state in place. |
-| `react-luau/no-ref-current-in-render` | warning | Correctness | Avoid mutating ref.current during render except for predictable initialization or deliberate latest-value mirrors. |
-| `react-luau/no-create-context-in-render` | error | Correctness | React contexts must have stable identity and should not be created during render. |
-| `react-luau/no-nested-component-definition` | warning | Architecture | Do not define rendered component types inside another component. |
-| `react-luau/no-random-key` | error | Correctness | React child keys must not be regenerated on each render. |
-| `react-luau/no-yield-in-render` | error | Correctness | React render functions must not yield. |
-| `react-luau/no-task-spawn-in-render` | error | Correctness | Do not schedule asynchronous work during render. |
-| `react-luau/no-side-effects-in-render` | error | Correctness | Do not create Instances, start tweens, subscribe, or perform other externally observable side effects during component render. |
-| `react-luau/no-create-root-in-render` | error | Roblox | Do not create ReactRoblox roots during component render. |
-| `react-luau/no-prop-mutation` | error | Correctness | Component props should be treated as immutable inputs. |
-| `react-luau/no-array-index-as-key` | suggestion | Correctness | Review dynamic React children that use their current array position as identity. |
-| `react-luau/unstable-context-value` | warning | Performance | Avoid recreating context value tables on every provider render when identity matters. |
-
-## Investigate and configure
-
-```bash
-react-luau-doctor rules list
-react-luau-doctor rules explain react-luau/exhaustive-deps
-react-luau-doctor why src/Label.luau:12
-react-luau-doctor rules set react-luau/exhaustive-deps error
-```
-
-Errors, warnings, and suggestions express reporting policy, not proof of a runtime bug. Review the explanation and code context before changing behavior. Suppress intentional exceptions narrowly.
-
-The Binding candidate rule is suggestion-tier because the consumer may require ordinary state or a larger refactor. Array-index keys can also be intentional for collections with stable ordering. See [analysis limits](analysis.md) and [configuration](cli.md).
-
-Instance creation and tween operations during render are reported by `react-luau/no-side-effects-in-render` and use that rule's severity and configuration.