nanos-lint 2.8.2 → 3.0.0

package/README.md

@@ -13,6 +13,7 @@ A dedicated, fast linter and type-checker for **[nanos world](https://nanos-worl
 
 ## Features
 
+- **Realm-aware diagnostics**: `Server/`, `Client/` and `Shared/` are checked against their real execution context, so cross-realm API misuse and client/server global leakage fail the build instead of crashing at runtime.
 - **Accurate nanos world Type Checking**: Bundles verified nanos world API annotations (Lua 5.4.9).
 - **Zero-Install Local CLI**: Run directly via `npx nanos-lint [path]` without installing anything.
 - **Native GitHub Action**: Use `vugi99/nanos-lint` directly in CI workflows with inline GitHub PR annotations.
@@ -95,7 +96,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Lint nanos world Lua scripts
-        uses: vugi99/nanos-lint@v2
+        uses: vugi99/nanos-lint@v3
         with:
           path: "."
           checklevel: "Warning"
@@ -112,7 +113,8 @@ jobs:
 | `ignore`        | Files or directories to ignore (supports glob patterns, newline or comma separated) | `""`      |
 | `luals-version` | Version of `lua-language-server` to use                                             | `latest`  |
 | `fail-on-error` | Fail the workflow step if diagnostics are found                                     | `true`    |
-| `quiet`         | Suppress progress messages                                                          | `false`   |
+| `log-level`     | Logging level (`error`, `warn`, `info`, `debug`, `silent`)                          | `warn`    |
+| `realm`         | Execution realm to check (`all`, `client`, `server`, `shared`)                      | `all`     |
 | `cache`         | Whether to cache the LuaLS binary and annotations across workflow runs              | `true`    |
 
 When caching is enabled, the cache key rolls over each ISO week, so a freshly downloaded LuaLS binary is actually persisted under the new week's key; in the meantime the previous week's entry is restored from the cache.
@@ -151,7 +153,7 @@ OPTIONS:
   --github                 Output in GitHub Actions format (shortcut for --format=github)
   --luals-version=<ver>    Version of LuaLS to use (default: latest, falling back to 3.19.1 when offline)
   --no-fail                Do not exit with code 1 if diagnostics are found
-  --quiet                  Suppress progress output only (equivalent to --log-level=error; the report is still printed)
+  --realm <realm>          Execution realm to check: all, client, server, shared (default: all)
   -f, --force              (init command only) Overwrite existing .luarc.json
 ```
 
@@ -194,6 +196,76 @@ npx nanos-lint init
 npx nanos-lint init --force
 ```
 
+### Realm Mapping (`nanos.realms`)
+
+nanos world runs two isolated Lua VMs: the server executes `Server/**` + `Shared/**`, the client executes `Client/**` + `Shared/**`. `nanos-lint` mirrors that split and lets you describe a non-standard layout in `.luarc.json`:
+
+```json
+{
+  "nanos": {
+    "realms": {
+      "src/server/**": "server",
+      "src/client/**": "client",
+      "common/**": "shared"
+    }
+  }
+}
+```
+
+| Realm value             | Meaning                                                                                                         |
+| :---------------------- | :-------------------------------------------------------------------------------------------------------------- |
+| `"server"`              | Checked with the server context: client-only APIs and `Client/**` globals do not exist.                         |
+| `"client"`              | Checked with the client context: server-only APIs and `Server/**` globals do not exist.                         |
+| `"shared"` / `"global"` | Checked with the complete context, because a shared script may guard side-specific calls behind runtime checks. |
+
+- Omitting `nanos.realms` falls back to the conventional `Server/**`, `Client/**`, `Shared/**` layout, and realm passes only run when at least one of those patterns matches a checked Lua file.
+- `"nanos": { "realms": {} }` disables realm checking and restores a single standard pass.
+- When several entries match the same file, the last matching entry wins.
+- Files matched by no entry (a root `main.lua`, for example) are checked with the complete context.
+
+The `nanos` key is nanos-lint specific and ignored by LuaLS, so the same `.luarc.json` keeps working in the editor.
+
+### File Counting and Glob Semantics
+
+The `N files checked` figure is produced by matching `workspace.ignoreDir` and `files.exclude` with the bundled `glob` engine. The v3.0.0 contract is:
+
+- **Trailing slashes and `./` prefixes** are normalized (`vendor/` behaves like `vendor`), and `\` separators are converted to `/`.
+- **Wildcards** follow standard glob semantics (`*`, `**`, `?`, `[0-9]`, `{a,b}`), including inside `workspace.ignoreDir`.
+- **Absolute entries are rejected** (with a warning). LuaLS matches patterns relative to the workspace root, and `glob` anchors absolute patterns inconsistently across platforms, so one `.luarc.json` stays portable by not supporting them.
+- **Negation prefixes (`!pattern`) are rejected** (with a warning). LuaLS uses a gitignore-style matcher without negation support, so honoring `!` here would count files LuaLS never checks.
+- **Over-budget patterns** (excessive wildcards or brace alternatives) are skipped with a warning instead of risking a slow, backtracking-heavy match. Skipping can only over-count, never hide a file.
+- **Symlinks are never followed**: symlinked `.lua` files are not counted and symlinked directories are not traversed.
+- A `workspace.ignoreDir` list in your `.luarc.json` **replaces** the built-in defaults for that file, mirroring LuaLS. The configuration handed to LuaLS is always merged with nanos-lint's defaults, so `.git`, `.vscode`, `.nanos-lint` and `node_modules` stay ignored during a check.
+
+---
+
+## Realm-Aware Checking
+
+nanos world loads a package into two isolated Lua VMs: the **server** executes `Server/**` plus `Shared/**`, and the **client** executes `Client/**` plus `Shared/**`. `nanos-lint` mirrors that split so a `Client/` script can no longer call `Server.ChangeMap()` unnoticed, and a global defined in `Client/` no longer satisfies a `Server/` script.
+
+`nanos-lint check <path>` detects the conventional layout automatically and runs one LuaLS pass per realm (see [Realm Mapping](#realm-mapping-nanosrealms) to describe a custom layout):
+
+| Pass       | Files reported             | Context                                                                                                                |
+| :--------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
+| **server** | `Server/**`                | Server annotations only; `Client/**` is excluded from the analysis.                                                    |
+| **client** | `Client/**`                | Client annotations only; `Server/**` is excluded from the analysis.                                                    |
+| **shared** | `Shared/**` and root files | The complete annotation set, because a shared script may legitimately call a side-specific API behind a runtime check. |
+
+Only the annotations that belong to a realm are loaded, so misuse is reported as `undefined-global` (for side-only classes such as `Client`, `Server`, `Database` or `WebUI`) or as `undefined-field` (for realm-specific members of classes that exist on both sides, such as `Character:SetTeam()` on the client).
+
+```bash
+nanos-lint check .                # every detected realm
+nanos-lint check . --realm server # server files + shared files
+nanos-lint check . --realm client # client files + shared files
+nanos-lint check . --realm shared # shared files only, with the complete context
+```
+
+Deliberate limits:
+
+- **Runtime guards are not analyzed.** `Shared/**` is checked with the complete context, so a guarded `Server.ChangeMap()` inside a `Package.IsUnloading()`-style branch is accepted, and so is an unguarded one. Real nanos world packages gate calls in too many ways for static detection to be reliable.
+- **`Package.Require` keeps resolving across realms**, because `runtime.path` keeps `?.lua`, `Shared/?.lua`, `Client/?.lua` and `Server/?.lua` in every pass. A shared file may require a realm-specific module behind a guard.
+- **Realm checking only activates when a configured pattern matches at least one checked Lua file**, so non-package repositories keep running a single standard pass. `"nanos": { "realms": {} }` disables it explicitly.
+
 ---
 
 ## Pre-packaged Release Distributions (Offline / CD)

package/action.yml

@@ -30,10 +30,14 @@ inputs:
     description: "Whether to fail the action step if diagnostic errors/warnings are found"
     required: false
     default: "true"
-  quiet:
-    description: "Suppress progress output"
+  log-level:
+    description: "Logging level: error, warn, info, debug, silent"
     required: false
-    default: "false"
+    default: "warn"
+  realm:
+    description: "Execution realm to check: all, client, server, shared"
+    required: false
+    default: "all"
   ignore:
     description: "Files or directories to ignore (supports glob patterns, multiple entries can be newline or comma separated)"
     required: false
@@ -80,7 +84,8 @@ runs:
         INPUT_ANNOTATIONS: ${{ inputs.annotations }}
         INPUT_LUALS_VERSION: ${{ inputs.luals-version }}
         INPUT_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}
-        INPUT_QUIET: ${{ inputs.quiet }}
+        INPUT_LOG_LEVEL: ${{ inputs.log-level }}
+        INPUT_REALM: ${{ inputs.realm }}
         INPUT_IGNORE: ${{ inputs.ignore }}
         ACTION_PATH: ${{ github.action_path }}
       run: |
@@ -107,8 +112,12 @@ runs:
           ARGS+=("--no-fail")
         fi
 
-        if [ "$INPUT_QUIET" = "true" ]; then
-          ARGS+=("--quiet")
+        if [ -n "$INPUT_LOG_LEVEL" ]; then
+          ARGS+=("--log-level=$INPUT_LOG_LEVEL")
+        fi
+
+        if [ -n "$INPUT_REALM" ]; then
+          ARGS+=("--realm=$INPUT_REALM")
         fi
 
         # dist/ is gitignored, so `uses: vugi99/nanos-lint@<ref>` consumers always
@@ -118,5 +127,5 @@ runs:
         else
           # Exact version: a range could run a different release than the pinned
           # tag. Bump together with "version" in package.json.
-          npx --yes nanos-lint@2.8.2 "${ARGS[@]}"
+          npx --yes nanos-lint@3.0.0 "${ARGS[@]}"
         fi