nanos-lint 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vugi99
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# nanos-lint
+
+[![CI](https://github.com/vugi99/nanos-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/vugi99/nanos-lint/actions/workflows/ci.yml)
+[![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)
+[![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)** Lua scripts powered by the **[Lua Language Server (LuaLS)](https://github.com/LuaLS/lua-language-server)**.
+
+---
+
+## Features
+
+- **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.
+- **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.
+- **Modern Node.js Runtime**: Built targeting Node.js (>= 24) with zero runtime dependencies.
+
+---
+
+## Requirements
+
+- **Node.js**: `>= 24.0.0` (required for npm/npx CLI usage; standalone release bundles include all dependencies)
+
+---
+
+## Quick Start
+
+### 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
+```
+
+### 2. Global Installation
+
+```bash
+npm install -g nanos-lint
+
+# Then use anywhere
+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.
+
+---
+
+## GitHub Actions Integration
+
+Add `nanos-lint` to your repository's workflow (e.g. `.github/workflows/lint.yml`):
+
+```yaml
+name: Lint Lua Scripts
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Lint nanos world Lua scripts
+        uses: vugi99/nanos-lint@v2
+        with:
+          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 | `""` |
+| `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` |
+
+When running inside GitHub Actions, `nanos-lint` automatically outputs **workflow annotations** (`::error` / `::warning`) that appear inline on PR diffs.
+
+---
+
+## CLI Reference
+
+```
+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
+  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)
+  --checklevel=<level>     Minimum diagnostic level: Error, Warning, Information, Hint (default: Warning)
+  --config=<path>          Path to custom .luarc.json configuration file
+  --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)
+  --no-fail                Do not exit with code 1 if diagnostics are found
+  --quiet                  Suppress progress output
+  -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 |
+| `NO_COLOR` | Disables ANSI color output when set to any non-empty value |
+| `FORCE_COLOR` | Forces ANSI color output even in non-TTY environments |
+
+---
+
+## Workspace Configuration (`.luarc.json`)
+
+If your project already has a `.luarc.json`, `nanos-lint` automatically merges it. Your custom settings (e.g., custom globals, disabled diagnostics, additional libraries) are retained, while nanos world definitions are injected in `workspace.library`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/LuaLS/lua-language-server/master/setting/schema.json",
+  "diagnostics": {
+    "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
+```
+
+---
+
+## Standalone Binary Distributions (Offline / CD)
+
+For environments without Node.js, pre-packaged release bundles containing the compiled `lua-language-server` binary and nanos-lint wrapper are available on the [Releases](https://github.com/vugi99/nanos-lint/releases) page:
+
+- `nanos-lint-<version>-windows-x64.zip`
+- `nanos-lint-<version>-linux-x64.tar.gz`
+
+Simply extract the archive and run `./nanos-lint` (Linux) or `nanos-lint.cmd` (Windows).
+
+---
+
+## Development
+
+```bash
+# Clone with submodules
+git clone --recursive https://github.com/vugi99/nanos-lint.git
+cd nanos-lint
+
+# Install dependencies
+npm install
+
+# Update annotations submodule from upstream
+git submodule update --remote --merge
+
+# Run ESLint
+npm run lint
+
+# Run type check
+npm run typecheck
+
+# Run Vitest test suite (unit + live LuaLS integration tests)
+npm test
+
+# Build distribution bundle
+npm run build
+```
+
+See [AGENTS.md](AGENTS.md) for development philosophy and quality gate requirements.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/action.yml

@@ -0,0 +1,87 @@
+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'
+
+inputs:
+  path:
+    description: 'Path to workspace directory or Lua file to check'
+    required: false
+    default: '.'
+  checklevel:
+    description: 'Minimum diagnostic severity level to report (Error, Warning, Information, Hint)'
+    required: false
+    default: 'Warning'
+  config:
+    description: 'Path to a custom .luarc.json configuration file'
+    required: false
+    default: ''
+  luals-version:
+    description: 'Version of LuaLS to use (or "latest")'
+    required: false
+    default: 'latest'
+  fail-on-error:
+    description: 'Whether to fail the action step if diagnostic errors/warnings are found'
+    required: false
+    default: 'true'
+  quiet:
+    description: 'Suppress progress output'
+    required: false
+    default: 'false'
+  ignore:
+    description: 'Files or directories to ignore (supports glob patterns, multiple entries can be newline or comma separated)'
+    required: false
+    default: ''
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v7
+      with:
+        node-version: '24'
+
+    - name: Run nanos-lint
+      shell: bash
+      env:
+        INPUT_PATH: ${{ inputs.path }}
+        INPUT_CHECKLEVEL: ${{ inputs.checklevel }}
+        INPUT_CONFIG: ${{ inputs.config }}
+        INPUT_LUALS_VERSION: ${{ inputs.luals-version }}
+        INPUT_FAIL_ON_ERROR: ${{ inputs.fail-on-error }}
+        INPUT_QUIET: ${{ inputs.quiet }}
+        INPUT_IGNORE: ${{ inputs.ignore }}
+        ACTION_PATH: ${{ github.action_path }}
+      run: |
+        ARGS=("check" "$INPUT_PATH" "--checklevel=$INPUT_CHECKLEVEL" "--luals-version=$INPUT_LUALS_VERSION" "--format=github")
+
+        if [ -n "$INPUT_CONFIG" ]; then
+          ARGS+=("--config=$INPUT_CONFIG")
+        fi
+
+        if [ -n "$INPUT_IGNORE" ]; then
+          while IFS= read -r line || [ -n "$line" ]; do
+            trimmed=$(echo "$line" | xargs)
+            if [ -n "$trimmed" ]; then
+              ARGS+=("--ignore=$trimmed")
+            fi
+          done <<< "$INPUT_IGNORE"
+        fi
+
+        if [ "$INPUT_FAIL_ON_ERROR" = "false" ]; then
+          ARGS+=("--no-fail")
+        fi
+
+        if [ "$INPUT_QUIET" = "true" ]; then
+          ARGS+=("--quiet")
+        fi
+
+        if [ -f "$ACTION_PATH/dist/cli.js" ]; then
+          node "$ACTION_PATH/dist/cli.js" "${ARGS[@]}"
+        else
+          npx --yes nanos-lint@^2.1.0 "${ARGS[@]}"
+        fi
+
+

package/bin/nanos-lint.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { runCLI } from "../dist/cli.js";
+
+runCLI()
+  .then((code) => {
+    process.exit(code);
+  })
+  .catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`error: ${message}`);
+    if (process.env.DEBUG && err instanceof Error && err.stack) {
+      console.error(err.stack);
+    }
+    process.exit(1);
+  });
+
+