diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 36d33b1..f9b0d9b 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,11 +1,11 @@ name: Bug report -description: Report a problem with the tool. +description: Report a problem with the linter, formatter, or language server. body: - type: textarea id: environment attributes: label: Version and environment - description: Include the tool version, operating system, and editor if relevant. + description: Name the affected tool (qbx-lint or qbx-lua-ls), its version, your operating system, and your editor/LSP client if relevant. validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 0c8ae2c..e16f35d 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,5 +1,5 @@ name: Feature request -description: Suggest a change or a new feature. +description: Suggest a change to the linter, formatter, language server, or shared analysis. body: - type: textarea id: problem @@ -11,6 +11,6 @@ body: id: suggestion attributes: label: What would help? - description: Describe the change, with an example if possible. + description: Name the affected tool or shared behavior and describe the change, with an example if possible. validations: required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 864aec6..43165b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,10 @@ # Contributing +This repository accepts changes to both `qbx-lint` and `qbx-lua-ls`, including their shared +parser, formatter, analysis and FiveM data. The former standalone server repository is archived; +use this repository for language-server issues and pull requests. Editor adapters remain in +[qbx-editor](https://github.com/Qbox-project/qbx-editor). + Use a stable Rust toolchain with `rustfmt` and `clippy`. From the repository root: ```sh @@ -98,9 +103,13 @@ ordinary tests use the checked-in data. ## Reporting a bug -Include `qbx-lint --version`, your platform, the command you ran, expected and actual output, -and a minimal Lua example. Include the manifest and relevant `qbxlint.toml` settings when the -problem depends on imports, side selection, or resource layout. +Report linter, formatter and language-server bugs in +[this repository](https://github.com/Qbox-project/qbx-lint/issues). Include the affected tool +and its version (`qbx-lint --version` or `qbx-lua-ls --version`), your platform, expected and actual +behavior, and a minimal Lua example. For CLI bugs, include the command you ran. For LSP bugs, +include the editor/LSP client, settings, server logs and the editor action that triggered the +problem. Include the manifest and relevant `qbxlint.toml` settings when the problem depends on +imports, side selection, or resource layout. For a pull request, explain the resulting behavior and the checks you ran. Keep generated-data updates identifiable in the diff. Release notes are generated from commit messages, so write them as [Conventional Commits](https://www.conventionalcommits.org). diff --git a/README.md b/README.md index fbc595d..8e00bc9 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,68 @@ -# qbx-lint +# Qbox Lua tooling (qbx-lint) -A Lua linter and formatter for FiveM resources. It parses CfxLua syntax, reads resource manifests, -and checks code against bundled native definitions, runtime globals, and client/server context. +This repository contains a **Lua linter, formatter, and language server for FiveM**. Both tools +share the same CfxLua parser, formatting engine, analysis rules and bundled FiveM data. They read +resource manifests to understand imports and client/server context. -It reports Lua mistakes, missing manifest imports, event and export mismatches, and common Qbox -patterns. The same workspace contains the parser, formatter, analysis crates and -[qbx-lua-ls](crates/qbx_lua_ls), the server behind the -[Qbox Lua editor integrations](https://github.com/Qbox-project/qbx-editor). +| Tool | What it does | Guide | +| --- | --- | --- | +| `qbx-lint` | Lints and formats files from the command line or CI, with reports and automatic fixes. | [CLI usage](#use) | +| `qbx-lua-ls` | Provides editor diagnostics, completion, hover, navigation, rename, quick fixes and formatting over LSP. | [Language server and editors](#language-server-and-editors) | -Shared analysis and language-server changes can be developed and tested in one pull request. -See the [language-server guide](crates/qbx_lua_ls/README.md) for features and setup, and the -[migration notes](docs/repository-migration.md) for Git history and release compatibility. +The former `Qbox-project/qbx-lua-ls` repository was merged into +[`crates/qbx_lua_ls`](crates/qbx_lua_ls). From **v1.0.5**, releases here contain both executables; +the original commits, authors and historical tags are preserved. See the +[migration notes](docs/repository-migration.md) for what moved and where to contribute. + +Editor adapters remain in [qbx-editor](https://github.com/Qbox-project/qbx-editor). Shared +analysis and language-server changes can now be developed and tested in one pull request here. ## Install -Build from a checkout with a stable Rust toolchain and Cargo: +### Download binaries + +Download the archive for your platform from the +[releases page](https://github.com/Qbox-project/qbx-lint/releases): choose `qbx-lint-` for +the CLI or `qbx-lua-ls-` for the language server. Each archive contains one executable +and its license. Extract the executable and put it on your `PATH`, or configure its absolute +path in your editor. `SHA256SUMS` contains checksums for both tools. + +Both tools are available for Windows x64, Linux x64/ARM64 (musl), and macOS x64/ARM64. +The [Qbox Lua VS Code extension](https://marketplace.visualstudio.com/items?itemName=Qbox.qbx-lua) +bundles the server, so VS Code users can install the extension directly. + +### Build from source + +Use a stable Rust toolchain and Cargo. One checkout contains everything needed for both tools: ```sh git clone https://github.com/Qbox-project/qbx-lint.git cd qbx-lint + +# Install either or both tools. cargo install --path crates/qbx_lint --locked --profile lint-release +cargo install --path crates/qbx_lua_ls --locked + qbx-lint --version +qbx-lua-ls --version ``` Cargo installs the executable into its `bin` directory, which must be on your `PATH`. -For a local build without installation, run `cargo build --profile lint-release --locked -p qbx_lint`. -The executable is then in `target/lint-release` (`qbx-lint.exe` on Windows). +For local builds without installation, run these commands separately from the workspace root: -Download the archive for your platform from the -[releases page](https://github.com/Qbox-project/qbx-lint/releases), extract it, and put the -executable on your `PATH`. +```sh +cargo build --profile lint-release --locked -p qbx_lint +cargo build --release --locked -p qbx_lua_ls +``` + +The CLI is in `target/lint-release/qbx-lint` and the server is in `target/release/qbx-lua-ls` +(add `.exe` on Windows). The separate profiles preserve the CLI's abort-on-panic behavior and +the server's request recovery; see [CONTRIBUTING.md](CONTRIBUTING.md). ## Use +### Command-line linter and formatter + Run these commands from your resource or server checkout: ```sh @@ -64,8 +94,32 @@ fails if a source file cannot be formatted. The formatter verifies tokens and co writing. Both formatting and automatic fixes reject non-UTF-8 source; escrow, binary and obfuscated files are skipped. +## Language server and editors + +`qbx-lua-ls` provides: + +- Diagnostics and quick fixes using the same rules as the CLI, with resource and client/server context. +- Completion, hover and signature help for Lua symbols, FiveM natives, exports, events and LuaCATS annotations. +- Definitions, references, rename, semantic tokens and inlay hints. +- Whole-document formatting using the shared `qbxlint.toml` settings. + +For VS Code, install [Qbox Lua](https://marketplace.visualstudio.com/items?itemName=Qbox.qbx-lua) +and open a resource folder or your server's `resources` folder. The extension includes the server. +For Zed, Neovim, Helix and other LSP clients, see the +[editor setup guide](https://github.com/Qbox-project/qbx-editor/blob/main/docs/editors.md). + +The server communicates over standard input and output using the Language Server Protocol. +An editor starts `qbx-lua-ls` without arguments; `--version` checks the installed version. +It does not need a running FiveM server. See the [server guide](crates/qbx_lua_ls/README.md) +for the full feature list and limits, and the +[LSP configuration and protocol reference](crates/qbx_lua_ls/docs/protocol.md) for client settings. + ## Configure +Both the CLI and language server use `qbxlint.toml` for lint rules and formatting. +The language server also accepts editor settings for library paths, diagnostics, inlay hints +and semantic tokens; see its [configuration guide](crates/qbx_lua_ls/README.md#configuration). + The CLI searches upward from the first input path for `qbxlint.toml` or `.qbxlint.toml`. Use `--config path/to/qbxlint.toml` to select a file explicitly. Paths in configuration patterns are relative to that file's directory. @@ -118,6 +172,11 @@ that a resource is secure. Review automatic edits and test resource behavior in ## Contribute +Report linter, formatter, shared analysis and language-server bugs in +[this repository's issues](https://github.com/Qbox-project/qbx-lint/issues), and submit changes +here. Editor adapter and UI issues belong in +[qbx-editor](https://github.com/Qbox-project/qbx-editor/issues). + See [CONTRIBUTING.md](CONTRIBUTING.md) for the crate layout, checks, and data generation commands. Release notes are on the [releases page](https://github.com/Qbox-project/qbx-lint/releases). diff --git a/crates/qbx_lua_ls/README.md b/crates/qbx_lua_ls/README.md index 86ebdf6..f89895d 100644 --- a/crates/qbx_lua_ls/README.md +++ b/crates/qbx_lua_ls/README.md @@ -1,8 +1,15 @@ # qbx-lua-ls -A language server for FiveM Lua. It reads `fxmanifest.lua` to resolve resource imports and -client/server scripts, uses LuaCATS annotations for editor help, and provides diagnostics from -[qbx-lint](https://github.com/Qbox-project/qbx-lint). +The FiveM Lua language server included in the [Qbox Lua tooling workspace](../../README.md). +It lives in `crates/qbx_lua_ls` alongside the `qbx-lint` CLI and their shared parser, formatter, +analysis and FiveM data crates. It reads `fxmanifest.lua` to resolve resource imports and +client/server scripts, uses LuaCATS annotations for editor help, and provides the same lint +rules as the CLI. + +The former standalone `Qbox-project/qbx-lua-ls` repository is archived. Development, issues, +pull requests and releases for both tools now live in +[Qbox-project/qbx-lint](https://github.com/Qbox-project/qbx-lint). The original Git history is +preserved; see [what moved and how](../../docs/repository-migration.md). The server communicates over standard input and output using the Language Server Protocol (LSP). Editor integrations and setup instructions live in @@ -61,7 +68,9 @@ See the [convention and maintenance notes](docs/framework-callbacks.md) for sour ## Build and run -Download the archive for your platform from [Releases](https://github.com/Qbox-project/qbx-lint/releases). +Download the `qbx-lua-ls-` archive for your platform from the +[shared releases](https://github.com/Qbox-project/qbx-lint/releases). These releases also +contain `qbx-lint-` CLI archives; choose the server archive for an LSP client. Archives cover Windows x64, Linux x64/ARM64 (musl), and macOS x64/ARM64. You can also build from source using the steps below. @@ -74,6 +83,9 @@ cd qbx-lint cargo build --release --locked -p qbx_lua_ls ``` +To install the server on `PATH` with Cargo instead, run +`cargo install --path crates/qbx_lua_ls --locked` from the workspace root. + The executable is `target/release/qbx-lua-ls`, or `target/release/qbx-lua-ls.exe` on Windows. Put it on `PATH`, or configure its absolute path in your editor. Start it without arguments for LSP over stdio; `--version` prints the version. It does not need a running FiveM server. diff --git a/docs/reference.md b/docs/reference.md index 0b1643f..877fe9a 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,5 +1,10 @@ # Configuration and analysis reference +The `qbx-lint` CLI and `qbx-lua-ls` language server share the parser, analysis rules and +`qbxlint.toml` formatting settings described here. Command-line options apply to the CLI; +for editor settings and LSP requests, see the +[language-server protocol reference](../crates/qbx_lua_ls/docs/protocol.md). + ## Syntax The parser handles Lua 5.4 and CfxLua extensions, including backtick hash literals, optional diff --git a/docs/repository-migration.md b/docs/repository-migration.md index 88660e9..21003c2 100644 --- a/docs/repository-migration.md +++ b/docs/repository-migration.md @@ -4,6 +4,31 @@ The editor adapters remain in `Qbox-project/qbx-editor`. A change to shared analysis and LSP behavior now belongs in one pull request, checked by the workspace CI on Windows and Linux. +The migration completed on **30 September 2026**. The +[workspace import](https://github.com/Qbox-project/qbx-lint/pull/8), +[shared release preparation](https://github.com/Qbox-project/qbx-lint/pull/9), and +[editor integration update](https://github.com/Qbox-project/qbx-editor/pull/3) are merged. +[Tooling v1.0.5](https://github.com/Qbox-project/qbx-lint/releases/tag/v1.0.5) is the first release +containing both binaries. [Editor v1.0.5](https://github.com/Qbox-project/qbx-editor/releases/tag/v1.0.5) +uses the combined workspace and is published to VS Code Marketplace and Open VSX. +The [old server repository](https://github.com/Qbox-project/qbx-lua-ls) is archived. + +## What moved + +| Component | Current home | +| --- | --- | +| Command-line linter and formatter | `qbx-lint/crates/qbx_lint` | +| Language server, its tests, scripts and protocol docs | `qbx-lint/crates/qbx_lua_ls` | +| Shared parser, formatter, analysis and FiveM data | Other crates in `qbx-lint/crates` | +| Editor adapters and interfaces | `Qbox-project/qbx-editor` | + +Clone only `qbx-lint` to work on either Rust tool. Open linter, formatter, analysis and LSP +issues and pull requests in [qbx-lint](https://github.com/Qbox-project/qbx-lint/issues); +editor adapter and UI issues belong in [qbx-editor](https://github.com/Qbox-project/qbx-editor/issues). +See the [main README](../README.md) for installation and usage, the +[server guide](../crates/qbx_lua_ls/README.md) for LSP features and setup, and +[CONTRIBUTING.md](../CONTRIBUTING.md) for workspace checks. + ## Preserved history The language server was imported into `crates/qbx_lua_ls` with a full-history subtree merge, @@ -12,21 +37,20 @@ without squashing or rewriting its commits. The import joins the two existing co - Linter source tip: `6cdc955`. - Language-server source tip: `3957972`. -All commits reachable from those tips retain their original IDs, authors, committers, +All 103 commits reachable from those tips retain their original IDs, authors, committers, timestamps and messages. Workspace integration is recorded in subsequent commits. Historical server commits still describe paths at their original repository root; use `git log --follow -m` for the history of an individual moved file. -The migration pull request must be merged with **Create a merge commit**. Squashing or rebasing -the migration would not retain the imported commit graph on the default branch. +The migration was merged with **Create a merge commit**, retaining both original commit graphs +on `main`. -The original repositories both used `v1.0.x` tags. Keep the linter tags unchanged and preserve -the server's historical tag objects under `lua-ls/v1.0.x`, avoiding collisions: +The original repositories both used `v1.0.x` tags. The linter's tags are unchanged, and the +server's original tag objects and targets are published under `lua-ls/v1.0.0` through +`lua-ls/v1.0.4`, avoiding collisions. To view a moved file's history: ```sh -git fetch --no-tags https://github.com/Qbox-project/qbx-lua-ls.git \ - 'refs/tags/*:refs/tags/lua-ls/*' -git push origin 'refs/tags/lua-ls/*:refs/tags/lua-ls/*' +git log --follow -m -- crates/qbx_lua_ls/src/server.rs ``` These names do not trigger the release workflow's `v*` tag filter. Old GitHub release pages @@ -46,16 +70,15 @@ The root `action.yml` and `Qbox-project/qbx-lint@` action address remain av Existing linter tags and their release assets are unchanged. Existing server releases remain downloadable from `Qbox-project/qbx-lua-ls`; future releases are published here. -## Cutover order +## Download and editor compatibility -1. Merge the workspace migration with a merge commit and publish the namespaced historical - server tags. Do not recreate or move existing `v1.0.x` tags. -2. Bump the workspace to the next unused version and publish a new shared release, such as - `v1.0.5`. Check that it contains both tools for all five platforms and their checksums. -3. Merge the companion `qbx-editor` migration. Its CI and development scripts use this - workspace, its release builds use the matching workspace tag, and Zed downloads server - archives from this repository. Publish the editor using the new shared server version. -4. Add a migration notice to `Qbox-project/qbx-lua-ls` and archive it after the editor cutover. - Keep its historical releases available for existing editor versions and download links. +Use [qbx-lint releases](https://github.com/Qbox-project/qbx-lint/releases) for both tools from +`v1.0.5` onward. Select `qbx-lint-` for command-line use or `qbx-lua-ls-` for an +LSP client; each archive contains that tool and its license. Shared releases include checksums +for both sets of archives. -Do not publish an editor release using an old linter tag: those tags predate the server import. +`qbx-editor` CI and development scripts now use the combined workspace. Its release builds use +the matching workspace tag, and its Zed adapter downloads server archives from `qbx-lint`. +An editor release must use `v1.0.5` or a later shared tooling tag; older linter tags predate +the server import. Historical standalone server releases through `v1.0.4` remain available +in the archived repository for existing editor versions and download links. diff --git a/docs/rules.md b/docs/rules.md index 5d70b6d..b5f44b1 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -1,5 +1,9 @@ # Rules +These analysis rules power both the `qbx-lint` CLI and `qbx-lua-ls` editor diagnostics. +Configure them through `qbxlint.toml`; language-server clients can also supply +[diagnostic rule overrides](../crates/qbx_lua_ls/README.md#configuration). + Use `qbx-lint --list-rules` to inspect the rules in your installed version. Levels below are the defaults; `hint` findings require `--min-severity hint` to appear in CLI output. Configuration can set any rule to `off`, `hint`, `info`, `warning`, or `error`.