nanos-lint 2.8.1 → 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.
@@ -33,11 +34,13 @@ A dedicated, fast linter and type-checker for **[nanos world](https://nanos-worl
 ### 1. Run via `npx` (No installation needed)
 
 Check the current directory:
+
 ```bash
 npx nanos-lint
 ```
 
 Check a specific directory or file:
+
 ```bash
 npx nanos-lint check ./my-package
 npx nanos-lint check ./my-package/Server/Index.lua
@@ -55,14 +58,17 @@ nanos-lint check .
 ### 3. Setup VS Code / Neovim IntelliSense
 
 To configure autocompletion, type annotations, and diagnostics in your local editor:
+
 ```bash
 npx nanos-lint init
 ```
+
 This generates a `.luarc.json` file in your workspace pointing to the nanos world definitions and schemas.
 
 ### 4. Pre-warm Cache for Offline / Docker Environments
 
 To pre-populate all required assets (both LuaLS binary and nanos world annotations) for air-gapped CI or container builds:
+
 ```bash
 npx nanos-lint warmup
 ```
@@ -78,9 +84,9 @@ name: Lint Lua Scripts
 
 on:
   push:
-    branches: [ main, master ]
+    branches: [main, master]
   pull_request:
-    branches: [ main, master ]
+    branches: [main, master]
 
 jobs:
   lint:
@@ -90,25 +96,26 @@ 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'
+          path: "."
+          checklevel: "Warning"
 ```
 
 ### Action Inputs
 
-| Input | Description | Default |
-| :--- | :--- | :--- |
-| `path` | Path to workspace directory or Lua file to check | `.` |
-| `checklevel` | Minimum severity to report (`Error`, `Warning`, `Information`, `Hint`) | `Warning` |
-| `config` | Path to a custom `.luarc.json` configuration file | `""` |
-| `annotations` | Path to a custom `annotations.lua` file | `""` |
-| `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` |
-| `cache` | Whether to cache the LuaLS binary and annotations across workflow runs | `true` |
+| Input           | Description                                                                         | Default   |
+| :-------------- | :---------------------------------------------------------------------------------- | :-------- |
+| `path`          | Path to workspace directory or Lua file to check                                    | `.`       |
+| `checklevel`    | Minimum severity to report (`Error`, `Warning`, `Information`, `Hint`)              | `Warning` |
+| `config`        | Path to a custom `.luarc.json` configuration file                                   | `""`      |
+| `annotations`   | Path to a custom `annotations.lua` file                                             | `""`      |
+| `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`    |
+| `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.
 
@@ -146,20 +153,20 @@ 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
 ```
 
 ### Environment Variables
 
-| Variable | Description |
-| :--- | :--- |
-| `LUALS_BIN` | Explicit path to a pre-installed `lua-language-server` binary; it must be a regular file that reports its version via `--version` (thin wrapper scripts are accepted), otherwise nanos-lint fails with `ERR_LUALS_BIN_INVALID` |
-| `NANOS_ANNOTATIONS_PATH`, `NANOS_ANNOTATIONS` | Explicit path to a custom `annotations.lua` file |
-| `NANOS_LOG_LEVEL` | Default logging level: `error`, `warn`, `info`, `debug`, `silent` (default: `warn`) |
-| `GITHUB_TOKEN` | GitHub personal access token used for authenticated GitHub API requests (avoids unauthenticated rate limits) |
-| `NO_COLOR` | Disables ANSI color output when set to any non-empty value |
-| `FORCE_COLOR` | Forces ANSI color output even in non-TTY environments |
+| Variable                                      | Description                                                                                                                                                                                                                    |
+| :-------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `LUALS_BIN`                                   | Explicit path to a pre-installed `lua-language-server` binary; it must be a regular file that reports its version via `--version` (thin wrapper scripts are accepted), otherwise nanos-lint fails with `ERR_LUALS_BIN_INVALID` |
+| `NANOS_ANNOTATIONS_PATH`, `NANOS_ANNOTATIONS` | Explicit path to a custom `annotations.lua` file                                                                                                                                                                               |
+| `NANOS_LOG_LEVEL`                             | Default logging level: `error`, `warn`, `info`, `debug`, `silent` (default: `warn`)                                                                                                                                            |
+| `GITHUB_TOKEN`                                | GitHub personal access token used for authenticated GitHub API requests (avoids unauthenticated rate limits)                                                                                                                   |
+| `NO_COLOR`                                    | Disables ANSI color output when set to any non-empty value                                                                                                                                                                     |
+| `FORCE_COLOR`                                 | Forces ANSI color output even in non-TTY environments                                                                                                                                                                          |
 
 Only `NANOS_LOG_LEVEL` controls the logging level; a generic `LOG_LEVEL` environment variable is intentionally not read, because CI images commonly set it.
 
@@ -175,23 +182,90 @@ If your project already has a `.luarc.json`, `nanos-lint` automatically merges i
 {
   "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
   "diagnostics": {
-    "disable": [
-      "lowercase-global"
-    ],
-    "globals": [
-      "MyCustomGlobal"
-    ]
+    "disable": ["lowercase-global"],
+    "globals": ["MyCustomGlobal"]
   }
 }
 ```
 
 To scaffold a portable `.luarc.json` with vendored type annotations in your project, run:
+
 ```bash
 npx nanos-lint init
 # Or overwrite an existing configuration:
 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)
@@ -218,17 +292,20 @@ cd nanos-lint
 # Install dependencies
 npm install
 
-# Run ESLint
-npm run lint
-
-# Run type check
-npm run typecheck
-
-# Build distribution bundle
-npm run build
-
-# Run Vitest test suite with coverage (unit + live LuaLS integration tests)
-npm run test:coverage
+# Run all quality gates (recommended before commit/PR)
+npm run gates
+# Or alias
+npm run check:all
+
+# Run individual quality gates
+npm run format:check    # Prettier code formatting (auto-fix via npm run format:fix)
+npm run lint            # ESLint
+npm run lint:deps       # Dependency architecture & license checks (dependency-cruiser)
+npm run lint:comments   # Comment density limit (<= 15%)
+npm run lint:docstrings # Docstring coverage (>= 90% top-level/exported function coverage per file in src/)
+npm run typecheck       # TypeScript typecheck
+npm run build           # Build distribution bundle
+npm run test:coverage   # Vitest unit + live LuaLS integration tests with coverage
 
 # Offline: skip live LuaLS tests, perform no network access, disable coverage thresholds
 NANOS_LIVE_TESTS=0 npm run test:coverage
@@ -238,10 +315,10 @@ NANOS_LIVE_TESTS=0 npm run test:coverage
 
 `tests/global-setup.ts` downloads the LuaLS binary and annotations **once per run** into an isolated temporary cache, so the real `~/.cache/nanos-lint` is never touched; the run fails if anything downloads LuaLS a second time.
 
-| Variable | Description |
-| :--- | :--- |
-| `NANOS_LIVE_TESTS` | `0` (or `false`/`no`/`off`) skips the live LuaLS/annotations tests, performs no network access, and does not enforce the coverage thresholds. Any other value or unset requires the shared fixtures; if they cannot be resolved the run fails. |
-| `NANOS_TEST_CACHE_ROOT` | Reuses the given directory as the isolated test cache instead of a fresh one, avoiding a re-download on repeat runs. |
+| Variable                | Description                                                                                                                                                                                                                                    |
+| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NANOS_LIVE_TESTS`      | `0` (or `false`/`no`/`off`) skips the live LuaLS/annotations tests, performs no network access, and does not enforce the coverage thresholds. Any other value or unset requires the shared fixtures; if they cannot be resolved the run fails. |
+| `NANOS_TEST_CACHE_ROOT` | Reuses the given directory as the isolated test cache instead of a fresh one, avoiding a re-download on repeat runs.                                                                                                                           |
 
 ```bash
 NANOS_LIVE_TESTS=0 npm run test:coverage                          # fully offline

package/action.yml

@@ -1,55 +1,59 @@
-name: 'nanos-world Lua Linter'
-description: 'Fast, accurate linter and type-checker for nanos world Lua scripts powered by LuaLS'
-author: 'nanos-world'
+name: "nanos-world Lua Linter"
+description: "Fast, accurate linter and type-checker for nanos world Lua scripts powered by LuaLS"
+author: "nanos-world"
 branding:
-  icon: 'check-circle'
-  color: 'yellow'
+  icon: "check-circle"
+  color: "yellow"
 
 inputs:
   path:
-    description: 'Path to workspace directory or Lua file to check'
+    description: "Path to workspace directory or Lua file to check"
     required: false
-    default: '.'
+    default: "."
   checklevel:
-    description: 'Minimum diagnostic severity level to report (Error, Warning, Information, Hint)'
+    description: "Minimum diagnostic severity level to report (Error, Warning, Information, Hint)"
     required: false
-    default: 'Warning'
+    default: "Warning"
   config:
-    description: 'Path to a custom .luarc.json configuration file'
+    description: "Path to a custom .luarc.json configuration file"
     required: false
-    default: ''
+    default: ""
   annotations:
-    description: 'Path to a custom annotations.lua file'
+    description: "Path to a custom annotations.lua file"
     required: false
-    default: ''
+    default: ""
   luals-version:
     description: 'Version of LuaLS to use (or "latest")'
     required: false
-    default: 'latest'
+    default: "latest"
   fail-on-error:
-    description: 'Whether to fail the action step if diagnostic errors/warnings are found'
+    description: "Whether to fail the action step if diagnostic errors/warnings are found"
     required: false
-    default: 'true'
-  quiet:
-    description: 'Suppress progress output'
+    default: "true"
+  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)'
+    description: "Files or directories to ignore (supports glob patterns, multiple entries can be newline or comma separated)"
     required: false
-    default: ''
+    default: ""
   cache:
-    description: 'Whether to cache the LuaLS binary and annotations across workflow runs'
+    description: "Whether to cache the LuaLS binary and annotations across workflow runs"
     required: false
-    default: 'true'
+    default: "true"
 
 runs:
-  using: 'composite'
+  using: "composite"
   steps:
     - name: Setup Node.js
       uses: actions/setup-node@v7
       with:
-        node-version: '24'
+        node-version: "24"
 
     # The ISO week refreshes the cache entry (a static key would never be saved
     # again); restore-keys fall back to previous weeks. Cheap: one `date` call.
@@ -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.1 "${ARGS[@]}"
+          npx --yes nanos-lint@3.0.0 "${ARGS[@]}"
         fi

package/bin/nanos-lint.js

@@ -13,5 +13,3 @@ runCLI()
     }
     process.exit(1);
   });
-
-