nanos-lint 3.2.1 → 3.4.0

package/README.md

@@ -73,6 +73,23 @@ To pre-populate all required assets (both LuaLS binary and nanos world annotatio
 npx nanos-lint warmup
 ```
 
+Offline execution uses only local dependencies and skips all nanos-lint network requests:
+
+```sh
+nanos-lint warmup                         # provision online
+nanos-lint check Packages/events --offline
+npx --offline nanos-lint check Packages/events --offline
+```
+
+For `latest`, offline mode selects the highest usable cached version (numeric tag order)
+and reports it, then tries a bundled binary or PATH. `LUALS_BIN` overrides discovery.
+Pinned versions require a matching cache or local executable. Custom annotations
+(`--annotations` or `NANOS_ANNOTATIONS_PATH`), bundled annotations, and valid stale
+cached annotations work offline. `warmup --offline` verifies local assets without
+downloading them. Missing assets fail with provisioning instructions.
+The flag controls nanos-lint; npm/npx may access the registry before it starts. Use
+a preinstalled executable or npm's own `--offline` with an already cached package.
+
 ---
 
 ## GitHub Actions Integration
@@ -104,20 +121,23 @@ jobs:
 
 ### Action Inputs
 
-| Input           | Description                                                                           | Default   |
-| :-------------- | :------------------------------------------------------------------------------------ | :-------- |
-| `path`          | Path to workspace directory or Lua file to check                                      | `.`       |
-| `paths`         | One or more workspace target paths or Lua files to check (newline or comma-separated) | `""`      |
-| `dep`           | External package dependency paths or definition files (newline or comma-separated)    | `""`      |
-| `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`    |
+| Input             | Description                                                                           | Default   |
+| :---------------- | :------------------------------------------------------------------------------------ | :-------- |
+| `path`            | Path to workspace directory or Lua file to check                                      | `.`       |
+| `paths`           | One or more workspace target paths or Lua files to check (newline or comma-separated) | `""`      |
+| `dep`             | External package dependency paths or definition files (newline or comma-separated)    | `""`      |
+| `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`  |
+| `baseline`        | Accepted diagnostic baseline; only new diagnostics fail                               | `""`      |
+| `write-baseline`  | Record current diagnostics and exit successfully                                      | `""`      |
+| `baseline-strict` | Also fail when baseline entries disappear (requires `baseline`)                       | `false`   |
+| `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`    |
 
 `paths` takes precedence over `path` when both are set; `path` is kept for backwards compatibility with the single-target form.
 
@@ -134,7 +154,8 @@ nanos-lint [command] [options] [paths...]
 
 COMMANDS:
   check [paths...]         Check workspace files or directories (default)
-  init [path]              Scaffold a .luarc.json configuration in the workspace (copies definitions to .nanos-lint/; supports --annotations <path>)
+  init [path]              Scaffold a .luarc.json configuration in the workspace (supports --vendor, --force)
+  copy-annotations [dest]  Copy cached annotations.lua definitions into a target file or directory (alias: export-annotations; targets not ending in .lua are treated as directories)
   warmup, download         Pre-fetch and cache both LuaLS binary and annotations for offline execution
   cache status, cache info Show cache status, installed versions, and disk usage (supports --json)
   cache clean              Clear the nanos-lint cache directory
@@ -153,14 +174,56 @@ OPTIONS:
                            debug adds diagnostic tracing
   --checklevel=<level>     Minimum diagnostic level: Error, Warning, Information, Hint (default: Warning)
   --config=<path>          Path to custom .luarc.json configuration file
-  --annotations=<path>     Path to custom annotations.lua file (applies to both check and init)
+  --annotations=<path>     Path to custom annotations.lua file (applies to check, init --vendor, and copy-annotations)
   --format=<format>        Output format: pretty, json, github (default: pretty)
   --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)
+  --baseline <path>        Report and fail only on new diagnostics
+  --write-baseline <path>  Record diagnostics and exit 0
+  --baseline-strict        Also fail on stale entries (requires --baseline)
   --no-fail                Do not exit with code 1 if diagnostics are found
   --realm <realm>          Execution realm to check: all, client, server, shared (default: all)
+  --offline                Use local dependencies only; never access the network
   --no-progress            Disable the interactive download, extraction and realm derivation progress display
-  -f, --force              (init command only) Overwrite existing .luarc.json
+  -t, --template <path>    (init command only) Use a custom JSONC scaffold template
+  --vendor                 (init command only) Vendor annotations.lua into .nanos-lint/ inside workspace
+  -f, --force              (init and copy-annotations only) Overwrite existing files
+```
+
+### Diagnostic Baselines
+
+Use a diagnostic baseline to accept an existing backlog and fail on new problems:
+
+```sh
+nanos-lint check . --write-baseline .nanos-lint/baseline.json
+nanos-lint check . --baseline .nanos-lint/baseline.json
+nanos-lint check . --baseline .nanos-lint/baseline.json --baseline-strict
+```
+
+Recording writes all reported diagnostics in a deterministic versioned JSON file,
+creates parent directories, and exits 0 (also with `--no-fail`). Comparison shows
+only new diagnostics with a summary such as `12 new, 154 baselined, 166 total`.
+JSON output retains every diagnostic and adds `baseline: true|false` plus
+`baselineSummary` counts. GitHub annotations are emitted only for new diagnostics.
+
+Matches use paths relative to the checked root, diagnostic code, whitespace-normalized
+message, severity, and occurrence counts. Line changes preserve matches; additional
+occurrences or severity changes are new problems. Removed occurrences are stale and
+only fail with `--baseline-strict`. `--no-fail` suppresses diagnostic failure, including
+strict staleness; invalid baseline files still fail. Missing, invalid, or incompatible
+files require regeneration with `--write-baseline`. Recording and comparison are
+mutually exclusive. Keep targets, realm, check level, configuration, and LuaLS version
+consistent between runs; pin `--luals-version` to avoid diagnostic changes from upgrades.
+Relative baseline paths are resolved from the working directory.
+
+The GitHub Action exposes the same options as `baseline`, `write-baseline`, and
+`baseline-strict` inputs:
+
+```yaml
+- uses: vugi99/nanos-lint@v3
+  with:
+    baseline: .nanos-lint/baseline.json
+    baseline-strict: "false"
 ```
 
 ### Progress Display
@@ -223,7 +286,7 @@ If your project already has a `.luarc.json`, `nanos-lint` automatically merges i
 }
 ```
 
-To scaffold a portable `.luarc.json` with vendored type annotations in your project, run:
+To scaffold a `.luarc.json` configuration in your project:
 
 ```bash
 npx nanos-lint init
@@ -231,6 +294,41 @@ npx nanos-lint init
 npx nanos-lint init --force
 ```
 
+By default `init` writes no annotations reference at all: `workspace.library` stays empty and
+`nanos-lint check` injects the managed cache path into its own temporary merged configuration at
+runtime, so a later cache update is picked up without touching repository files. Editors that read
+`.luarc.json` directly need a pinned copy, which is always an explicit opt-in:
+
+```bash
+# Initialize with annotations vendored into .nanos-lint/ and pinned in workspace.library
+npx nanos-lint init --vendor
+
+# Or copy the cached annotations to a custom file, or to any target that does not end in
+# ".lua" (treated as a directory). Copying alone does not pin anything: add the resulting
+# path to workspace.library yourself.
+npx nanos-lint copy-annotations
+npx nanos-lint copy-annotations ./types
+```
+
+`copy-annotations` refuses to overwrite an existing file unless `--force` is passed.
+
+### Custom Init Templates
+
+Initialize packages from a shared configuration template:
+
+```sh
+nanos-lint init Packages/events --template tools/team-luarc.json
+nanos-lint init Packages/events -t tools/team-luarc.json --vendor --annotations tools/annotations.lua
+```
+
+The custom JSON/JSONC file becomes the base configuration. Relative paths in its
+settings are interpreted relative to the target workspace, so shared templates can
+use entries such as `nanos.deps: ["../collider"]`. Custom settings and realm mappings
+are preserved, including `{}` to disable realms. Omitted realm mappings receive
+the conventional Server/Client/Shared defaults. Vendoring adds its annotation
+library, ignore and exclusion entries without discarding template entries. Existing
+`.luarc.json` files still require `--force` to overwrite.
+
 ### 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`:
@@ -369,7 +467,7 @@ npm run check:all
 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:comments   # Comment density limit (<= 10%)
 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

package/action.yml

@@ -34,6 +34,18 @@ inputs:
     description: 'Version of LuaLS to use (or "latest")'
     required: false
     default: "latest"
+  baseline:
+    description: "Path to an accepted diagnostic baseline; only new diagnostics fail"
+    required: false
+    default: ""
+  write-baseline:
+    description: "Record current diagnostics to this baseline path and exit successfully"
+    required: false
+    default: ""
+  baseline-strict:
+    description: "Also fail on stale baseline entries (requires baseline)"
+    required: false
+    default: "false"
   fail-on-error:
     description: "Whether to fail the action step if diagnostic errors/warnings are found"
     required: false
@@ -93,6 +105,9 @@ runs:
         INPUT_CONFIG: ${{ inputs.config }}
         INPUT_ANNOTATIONS: ${{ inputs.annotations }}
         INPUT_LUALS_VERSION: ${{ inputs.luals-version }}
+        INPUT_BASELINE: ${{ inputs.baseline }}
+        INPUT_WRITE_BASELINE: ${{ inputs.write-baseline }}
+        INPUT_BASELINE_STRICT: ${{ inputs.baseline-strict }}
         INPUT_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}
         INPUT_LOG_LEVEL: ${{ inputs.log-level }}
         INPUT_REALM: ${{ inputs.realm }}
@@ -153,6 +168,18 @@ runs:
           done <<< "$INPUT_IGNORE"
         fi
 
+        if [ -n "$INPUT_BASELINE" ]; then
+          ARGS+=("--baseline=$INPUT_BASELINE")
+        fi
+
+        if [ -n "$INPUT_WRITE_BASELINE" ]; then
+          ARGS+=("--write-baseline=$INPUT_WRITE_BASELINE")
+        fi
+
+        if [ "$INPUT_BASELINE_STRICT" = "true" ]; then
+          ARGS+=("--baseline-strict")
+        fi
+
         if [ "$INPUT_FAIL_ON_ERROR" = "false" ]; then
           ARGS+=("--no-fail")
         fi
@@ -172,5 +199,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@3.2.1 "${ARGS[@]}"
+          npx --yes nanos-lint@3.4.0 "${ARGS[@]}"
         fi