nanos-lint 2.6.1 → 2.8.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/nanos-lint.svg)](https://www.npmjs.com/package/nanos-lint)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](https://nodejs.org/)
 [![Lua Version](https://img.shields.io/badge/Lua-5.4.9-blue.svg)](https://www.lua.org/manual/5.4/)
-[![LuaLS Version](https://img.shields.io/badge/LuaLS-3.19.1-brightgreen.svg)](https://github.com/LuaLS/lua-language-server)
+[![LuaLS Version](https://img.shields.io/badge/LuaLS-latest-brightgreen.svg)](https://github.com/LuaLS/lua-language-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 A dedicated, fast linter and type-checker for **[nanos world](https://nanos-world.com/)** Lua scripts powered by the **[Lua Language Server (LuaLS)](https://github.com/LuaLS/lua-language-server)**.
@@ -17,7 +17,7 @@ A dedicated, fast linter and type-checker for **[nanos world](https://nanos-worl
 - **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.
 - **Workspace Config Merging**: Fully respects local `.luarc.json` files, merging your project globals and disabled diagnostics on top of the nanos API.
-- **Cross-Platform**: Works on **Windows x64** and **Linux amd64** (plus macOS). Automatically downloads and caches platform LuaLS binaries.
+- **Cross-Platform**: Works on **Windows x64**, **Linux (x64, arm64)**, and **macOS (Apple Silicon arm64, Intel x64)**. Automatically downloads and caches platform LuaLS binaries, defaulting to the latest LuaLS release and falling back to 3.19.1 when offline.
 - **Modern Node.js Runtime**: Built targeting Node.js (>= 24) with zero runtime dependencies.
 
 ---
@@ -60,6 +60,13 @@ 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
+```
+
 ---
 
 ## GitHub Actions Integration
@@ -103,6 +110,8 @@ jobs:
 | `quiet` | Suppress progress messages | `false` |
 | `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.
+
 When running inside GitHub Actions, `nanos-lint` automatically outputs **workflow annotations** (`::error` / `::warning`) that appear inline on PR diffs.
 
 ---
@@ -114,22 +123,30 @@ nanos-lint [command] [options] [path]
 
 COMMANDS:
   check [path]             Check a workspace or Lua file (default)
-  init [path]              Scaffold a .luarc.json configuration in the workspace (copies definitions to .nanos-lint/)
-  download-luals [version] Download and cache the LuaLS binary
+  init [path]              Scaffold a .luarc.json configuration in the workspace (copies definitions to .nanos-lint/; supports --annotations <path>)
+  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
+  cache-status             Alias for cache status
+  download-luals [version] Download and cache the LuaLS binary (the version can also be passed via --luals-version <ver>)
   clean-cache, clean       Clear the nanos-lint cache directory
   help, --help, -h         Show help message
   version, --version, -v   Show version information
 
 OPTIONS:
   -i, --ignore <pattern>   Files or directories to ignore (supports globs, repeatable, comma/newline-separated)
+  -l, --log-level <level>  Logging level: error, warn, info, debug, silent (default: warn)
+                           silent suppresses all output, including the final report (only the exit code remains)
+                           error and warn (the default) suppress progress messages but still print the report
+                           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
+  --annotations=<path>     Path to custom annotations.lua file (applies to both check and init)
   --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)
+  --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
+  --quiet                  Suppress progress output only (equivalent to --log-level=error; the report is still printed)
   -f, --force              (init command only) Overwrite existing .luarc.json
 ```
 
@@ -139,10 +156,15 @@ OPTIONS:
 | :--- | :--- |
 | `LUALS_BIN` | Explicit path to a pre-installed `lua-language-server` binary |
 | `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.
+
+`NANOS_LIVE_TESTS` and `NANOS_TEST_CACHE_ROOT` only affect this repository's test suite and are documented under [Test Suite Environment Variables](#test-suite-environment-variables).
+
 ---
 
 ## Workspace Configuration (`.luarc.json`)
@@ -151,7 +173,7 @@ If your project already has a `.luarc.json`, `nanos-lint` automatically merges i
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/LuaLS/lua-language-server/master/setting/schema.json",
+  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
   "diagnostics": {
     "disable": [
       "lowercase-global"
@@ -178,8 +200,11 @@ Pre-packaged release bundles containing the platform's `lua-language-server` bin
 
 - `nanos-lint-<version>-windows-x64.zip`
 - `nanos-lint-<version>-linux-x64.tar.gz`
+- `nanos-lint-<version>-linux-arm64.tar.gz`
+- `nanos-lint-<version>-macos-arm64.tar.gz` (Apple Silicon)
+- `nanos-lint-<version>-macos-x64.tar.gz` (Intel)
 
-These bundles are fully self-contained and ready for offline CI/CD environments with Node.js installed, eliminating the need to download LuaLS or annotations at runtime. Simply extract the archive and run `./nanos-lint` (Linux) or `nanos-lint.cmd` (Windows).
+These bundles are fully self-contained and ready for offline CI/CD environments with Node.js installed, eliminating the need to download LuaLS or annotations at runtime. Simply extract the archive and run `./nanos-lint` (Linux & macOS) or `nanos-lint.cmd` (Windows).
 
 ---
 
@@ -204,6 +229,23 @@ npm run build
 
 # Run Vitest test suite with coverage (unit + live LuaLS integration tests)
 npm run test:coverage
+
+# Offline: skip live LuaLS tests, perform no network access, disable coverage thresholds
+NANOS_LIVE_TESTS=0 npm run test:coverage
+```
+
+### Test Suite Environment Variables
+
+`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. |
+
+```bash
+NANOS_LIVE_TESTS=0 npm run test:coverage                          # fully offline
+NANOS_TEST_CACHE_ROOT=/tmp/nanos-tests npm run test:coverage      # reuse a warm cache
 ```
 
 See [AGENTS.md](AGENTS.md) for development philosophy and quality gate requirements.

package/action.yml

@@ -51,6 +51,13 @@ runs:
       with:
         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.
+    - name: Compute cache week
+      id: cacheweek
+      shell: bash
+      run: echo "week=$(date -u +%G-W%V)" >> "$GITHUB_OUTPUT"
+
     - name: Cache LuaLS binary and annotations
       if: ${{ inputs.cache != 'false' }}
       uses: actions/cache@v6
@@ -59,10 +66,10 @@ runs:
           ~/.cache/nanos-lint
           ~/AppData/Local/nanos-lint
           ~/Library/Caches/nanos-lint
-        key: nanos-lint-${{ runner.os }}-${{ inputs.luals-version }}
+        key: nanos-lint-${{ runner.os }}-${{ runner.arch }}-${{ inputs.luals-version }}-${{ steps.cacheweek.outputs.week }}
         restore-keys: |
-          nanos-lint-${{ runner.os }}-${{ inputs.luals-version }}-
-          nanos-lint-${{ runner.os }}-
+          nanos-lint-${{ runner.os }}-${{ runner.arch }}-${{ inputs.luals-version }}-
+          nanos-lint-${{ runner.os }}-${{ runner.arch }}-
 
     - name: Run nanos-lint
       shell: bash
@@ -104,10 +111,12 @@ runs:
           ARGS+=("--quiet")
         fi
 
+        # dist/ is gitignored, so `uses: vugi99/nanos-lint@<ref>` consumers always
+        # take the npx branch; the first one is for local `uses: ./` checkouts.
         if [ -f "$ACTION_PATH/dist/cli.js" ]; then
           node "$ACTION_PATH/dist/cli.js" "${ARGS[@]}"
         else
-          npx --yes nanos-lint@^2.6.1 "${ARGS[@]}"
+          # 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.0 "${ARGS[@]}"
         fi
-
-