nanos-lint 3.0.1 → 3.2.0

package/README.md

@@ -104,18 +104,22 @@ jobs:
 
 ### 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`    |
-| `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`  |
+| `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.
 
 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.
 
@@ -126,10 +130,10 @@ When running inside GitHub Actions, `nanos-lint` automatically outputs **workflo
 ## CLI Reference
 
 ```
-nanos-lint [command] [options] [path]
+nanos-lint [command] [options] [paths...]
 
 COMMANDS:
-  check [path]             Check a workspace or Lua file (default)
+  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>)
   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)
@@ -142,9 +146,10 @@ COMMANDS:
 
 OPTIONS:
   -i, --ignore <pattern>   Files or directories to ignore (supports globs, repeatable, comma/newline-separated)
+  -d, --dep <path>         Path to package dependency directory or Lua definition file (repeatable; resolves relative to cwd)
   -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
+                           silent suppresses all output, including the final report and the progress display (only the exit code remains)
+                           error and warn (the default) hide the info-level log lines and the non-interactive progress milestones but still print the report and the interactive progress bar
                            debug adds diagnostic tracing
   --checklevel=<level>     Minimum diagnostic level: Error, Warning, Information, Hint (default: Warning)
   --config=<path>          Path to custom .luarc.json configuration file
@@ -154,9 +159,38 @@ OPTIONS:
   --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
   --realm <realm>          Execution realm to check: all, client, server, shared (default: all)
+  --no-progress            Disable the interactive download, extraction and realm derivation progress display
   -f, --force              (init command only) Overwrite existing .luarc.json
 ```
 
+### Progress Display
+
+Downloads and extractions (`LuaLS` archive, `annotations.lua`, realm derivation) report their
+progress on **stderr**, so `stdout` keeps carrying only the diagnostic report:
+
+```
+[luals] Downloading lua-language-server-3.19.1-linux-x64.tar.gz [=====>        ] 37% (1.31 MB / 3.51 MB, 8.2 MB/s, ETA 0.3s)
+[luals] Extracting lua-language-server-3.19.1-linux-x64.tar.gz ⠹ (2.4s)
+```
+
+A live, in-place redraw is used only when stderr is an interactive terminal. Everywhere else
+(CI runners, pipes, redirected output, `TERM=dumb`) the same information is emitted as discrete
+single-line milestones, so logs stay free of carriage returns:
+
+```
+[luals] Downloading lua-language-server-3.19.1-linux-x64.tar.gz: 25% (901 KB / 3.51 MB)
+[luals] Downloaded lua-language-server-3.19.1-linux-x64.tar.gz (3.51 MB in 0.1s (37.3 MB/s))
+```
+
+Dynamic redrawing is also disabled by `--no-progress`, `NANOS_NO_PROGRESS`, `--format json`,
+`-l silent`, `CI`, `NO_COLOR` and `TERM=dumb`. When a transfer declares a compressed
+`content-length` (GitHub serves `annotations.lua` gzip-encoded), the percentage is dropped in
+favour of transferred bytes and speed instead of reporting a misleading total.
+
+Machine-readable output owns `stdout`: with `--format json` (and `cache status --json`) the
+milestones, completions and every other `info`/`debug` diagnostic move to `stderr` as well, so
+`nanos-lint check . --format json -l info | jq .` works at any log level.
+
 ### Environment Variables
 
 | Variable                                      | Description                                                                                                                                                                                                                    |
@@ -165,7 +199,8 @@ OPTIONS:
 | `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                                                                                                                                                                     |
+| `NANOS_NO_PROGRESS`                           | Disables the interactive download/extraction progress display when set to any non-empty value other than `0`, `false`, `no` or `off`                                                                                           |
+| `NO_COLOR`                                    | Disables ANSI color output when set to any non-empty value; dynamic progress redrawing stops for any non-empty value other than `0`, `false`, `no` or `off`                                                                    |
 | `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.
@@ -225,6 +260,23 @@ nanos world runs two isolated Lua VMs: the server executes `Server/**` + `Shared
 
 The `nanos` key is nanos-lint specific and ignored by LuaLS, so the same `.luarc.json` keeps working in the editor.
 
+### Package Dependencies (`nanos.deps`)
+
+When packages depend on other packages (e.g. located in `Server/Packages/` or external integration folders), you can declare them in `.luarc.json` under `nanos.deps` or via the `-d, --dep` CLI option:
+
+```json
+{
+  "nanos": {
+    "deps": ["../base_package", "../integration_package", "../definitions/common.lua"]
+  }
+}
+```
+
+- **Path Resolution**: Paths defined in `nanos.deps` resolve relative to the package directory containing the `.luarc.json`. In contrast, paths passed via the `-d, --dep <path>` CLI option resolve relative to the current working directory (`process.cwd()`).
+- **Transitive Dependencies & Cycle Detection**: Dependencies are traversed recursively. If a dependency defines its own `nanos.deps` in `.luarc.json`, those dependencies are loaded automatically. Circular dependencies are detected and visited only once.
+- **Realm Partitioning**: Dependency directories are inspected for realm conventions (`Server/`, `Client/`, `Shared/`). Server passes only include `Server/` and `Shared/` folders of dependencies; client passes only include `Client/` and `Shared/` folders. Single definition `.lua` files and non-partitioned dependency directories are included in all passes.
+- **Resilience**: If a declared dependency path does not exist, `nanos-lint` emits a warning and continues without failing the lint pass.
+
 ### 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:
@@ -266,6 +318,22 @@ Deliberate limits:
 - **`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.
 
+### Variadic Target Paths & Scoped Context
+
+`nanos-lint` accepts multiple files or directories on the command line:
+
+```bash
+# Lint both Shared and Server folders in one pass
+npx nanos-lint check Shared/ Server/ --realm server
+
+# Lint multiple specific files
+npx nanos-lint check Shared/utility.lua Server/main.lua
+```
+
+- **Project Root Discovery**: When checking subpaths or individual files (e.g. `Server/main.lua`), `nanos-lint` searches upward to locate the enclosing project root containing `.luarc.json` so custom realm mappings and dependencies are properly loaded.
+- **Unrequested Sibling Exclusion**: To prevent unrelated files under the common ancestor directory from defining globals that mask `undefined-global` diagnostics in requested files, `nanos-lint` automatically excludes unrequested siblings during the check.
+- **Root Filesystem Protection**: Target paths must share a common project directory. Passing disjoint paths spanning the filesystem root (or different drive letters on Windows) is rejected with an error.
+
 ---
 
 ## Pre-packaged Release Distributions (Offline / CD)

package/action.yml

@@ -10,6 +10,14 @@ inputs:
     description: "Path to workspace directory or Lua file to check"
     required: false
     default: "."
+  paths:
+    description: "One or more workspace target paths or Lua files to check (supports newline or comma-separated entries)"
+    required: false
+    default: ""
+  dep:
+    description: "External package dependency paths or definition files (supports newline or comma-separated entries)"
+    required: false
+    default: ""
   checklevel:
     description: "Minimum diagnostic severity level to report (Error, Warning, Information, Hint)"
     required: false
@@ -79,6 +87,8 @@ runs:
       shell: bash
       env:
         INPUT_PATH: ${{ inputs.path }}
+        INPUT_PATHS: ${{ inputs.paths }}
+        INPUT_DEP: ${{ inputs.dep }}
         INPUT_CHECKLEVEL: ${{ inputs.checklevel }}
         INPUT_CONFIG: ${{ inputs.config }}
         INPUT_ANNOTATIONS: ${{ inputs.annotations }}
@@ -89,7 +99,27 @@ runs:
         INPUT_IGNORE: ${{ inputs.ignore }}
         ACTION_PATH: ${{ github.action_path }}
       run: |
-        ARGS=("check" "$INPUT_PATH" "--checklevel=$INPUT_CHECKLEVEL" "--luals-version=$INPUT_LUALS_VERSION" "--format=github")
+        TARGET_PATHS=()
+        if [ -n "$INPUT_PATHS" ]; then
+          while IFS= read -r line || [ -n "$line" ]; do
+            trimmed=$(echo "$line" | xargs)
+            if [ -n "$trimmed" ]; then
+              IFS=',' read -ra ADDR <<< "$trimmed"
+              for i in "${ADDR[@]}"; do
+                sub_trimmed=$(echo "$i" | xargs)
+                if [ -n "$sub_trimmed" ]; then
+                  TARGET_PATHS+=("$sub_trimmed")
+                fi
+              done
+            fi
+          done <<< "$INPUT_PATHS"
+        elif [ -n "$INPUT_PATH" ]; then
+          TARGET_PATHS+=("$INPUT_PATH")
+        else
+          TARGET_PATHS+=(".")
+        fi
+
+        ARGS=("check" "${TARGET_PATHS[@]}" "--checklevel=$INPUT_CHECKLEVEL" "--luals-version=$INPUT_LUALS_VERSION" "--format=github")
 
         if [ -n "$INPUT_CONFIG" ]; then
           ARGS+=("--config=$INPUT_CONFIG")
@@ -99,6 +129,21 @@ runs:
           ARGS+=("--annotations=$INPUT_ANNOTATIONS")
         fi
 
+        if [ -n "$INPUT_DEP" ]; then
+          while IFS= read -r line || [ -n "$line" ]; do
+            trimmed=$(echo "$line" | xargs)
+            if [ -n "$trimmed" ]; then
+              IFS=',' read -ra ADDR <<< "$trimmed"
+              for i in "${ADDR[@]}"; do
+                sub_trimmed=$(echo "$i" | xargs)
+                if [ -n "$sub_trimmed" ]; then
+                  ARGS+=("--dep=$sub_trimmed")
+                fi
+              done
+            fi
+          done <<< "$INPUT_DEP"
+        fi
+
         if [ -n "$INPUT_IGNORE" ]; then
           while IFS= read -r line || [ -n "$line" ]; do
             trimmed=$(echo "$line" | xargs)
@@ -127,5 +172,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.0.1 "${ARGS[@]}"
+          npx --yes nanos-lint@3.2.0 "${ARGS[@]}"
         fi