nanos-lint 3.3.0 → 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.
 
@@ -158,13 +178,54 @@ OPTIONS:
   --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
+  -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
 
 Downloads and extractions (`LuaLS` archive, `annotations.lua`, realm derivation) report their
@@ -251,6 +312,23 @@ 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`:

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.3.0 "${ARGS[@]}"
+          npx --yes nanos-lint@3.4.0 "${ARGS[@]}"
         fi

package/dist/{cli-CsIAHyRZ.js → cli-DN7ZhC9e.js}

@@ -1465,21 +1465,21 @@ function initWorkspace(workspacePath, options) {
 	const targetFile = path.join(workspacePath, ".luarc.json");
 	if (fs.existsSync(targetFile) && !options?.force) throw new ConfigError(`.luarc.json already exists at ${targetFile}. Use --force to overwrite.`, "ERR_CONFIG_EXISTS", "Pass --force to overwrite the existing .luarc.json file.");
 	if (options?.annotationsPath && !options.vendor) throw new ConfigError("--annotations requires --vendor: nanos-lint init does not pin or vendor annotations.lua by default.", "ERR_ANNOTATIONS_WITHOUT_VENDOR", "Run 'nanos-lint init --vendor --annotations <path>' (or pass vendor: true), or omit the custom path to use the managed annotations cache.");
-	const template = loadConfigFile(getDefaultTemplatePath());
+	const template = loadConfigFile(path.resolve(options?.templatePath ?? getDefaultTemplatePath()));
+	if (!template || typeof template !== "object" || Array.isArray(template)) throw new ConfigError("Init template must contain a configuration object.", "ERR_CONFIG_PARSE");
+	template.nanos ??= {};
+	template.nanos.realms ??= Object.fromEntries(DEFAULT_REALM_MAPPINGS.map(({ pattern, realm }) => [pattern, realm]));
 	if (options?.vendor) {
 		const sourceAnnotations = options.annotationsPath || getDefaultAnnotationsPath();
 		if (!fs.existsSync(sourceAnnotations)) throw new ConfigError(`Definitions file not found at ${sourceAnnotations}. Make sure annotations have been downloaded or pass a valid file with --annotations.`, "ERR_ANNOTATIONS_NOT_FOUND", "Run 'nanos-lint warmup' to download annotations or provide --annotations <path>.");
-		const targetNanosDir = path.join(workspacePath, ".nanos-lint");
-		fs.mkdirSync(targetNanosDir, { recursive: true });
-		const targetAnnotations = path.join(targetNanosDir, "annotations.lua");
+		const targetAnnotations = path.join(workspacePath, ".nanos-lint", "annotations.lua");
+		fs.mkdirSync(path.dirname(targetAnnotations), { recursive: true });
 		fs.copyFileSync(sourceAnnotations, targetAnnotations);
 		template.workspace = template.workspace ?? {};
-		template.workspace.library = [".nanos-lint/annotations.lua"];
-		const existingIgnore = template.workspace.ignoreDir ?? [];
-		if (!existingIgnore.includes(".nanos-lint")) template.workspace.ignoreDir = [".nanos-lint", ...existingIgnore];
+		template.workspace.library = [.../* @__PURE__ */ new Set([...template.workspace.library ?? [], ".nanos-lint/annotations.lua"])];
+		template.workspace.ignoreDir = [.../* @__PURE__ */ new Set([".nanos-lint", ...template.workspace.ignoreDir ?? []])];
 		template.files = template.files ?? {};
-		const existingExclude = template.files.exclude ?? [];
-		if (!existingExclude.includes(".nanos-lint/**")) template.files.exclude = [".nanos-lint/**", ...existingExclude];
+		template.files.exclude = [.../* @__PURE__ */ new Set([".nanos-lint/**", ...template.files.exclude ?? []])];
 	}
 	fs.writeFileSync(targetFile, JSON.stringify(template, null, 2), "utf-8");
 	return targetFile;
@@ -7135,6 +7135,40 @@ function resolveCheckTargets(rawPaths) {
 	};
 }
 //#endregion
+//#region src/luals/offline.ts
+/** Validates an explicit local executable and checks a requested version against its output. */
+function validateOfflineBinary(binary, version) {
+	const resolved = assertValidLuaLSBinary(binary, "offline local binary");
+	if (version !== "latest") {
+		if (!execFileSync(resolved, ["--version"], {
+			encoding: "utf-8",
+			timeout: 5e3
+		}).split(/\s+/).some((part) => sanitizeLuaLSVersion(part) === version)) throw new LuaLSError(`Offline LuaLS binary ${resolved} does not match requested version ${version}.`, "ERR_LUALS_OFFLINE", `Run 'nanos-lint warmup --luals-version ${version}' online or set LUALS_BIN to a matching binary.`);
+	}
+	return resolved;
+}
+/** Resolves local LuaLS assets without changing cache entries or discovering remote releases. */
+function resolveOfflineLuaLS(version, cacheDir = getBaseLuaLSCacheDir()) {
+	const requested = version === "latest" ? version : sanitizeLuaLSVersion(version);
+	if (!requested) throw new LuaLSError(`Invalid LuaLS version: "${version}".`, "ERR_LUALS_INVALID_VERSION");
+	if (process.env.LUALS_BIN) return validateOfflineBinary(process.env.LUALS_BIN, requested);
+	const versions = listCachedLuaLSVersions(cacheDir).sort((a, b) => b.localeCompare(a, "en", { numeric: true }));
+	const selected = requested === "latest" ? versions[0] : versions.find((v) => v === requested);
+	if (selected) {
+		logger.info(`[luals] Offline: using cached LuaLS ${selected}.`);
+		return path.join(getCacheDir(selected, cacheDir), getPlatformInfo(selected).binaryRelativePath);
+	}
+	const bundled = path.join(getPackageRoot(), getPlatformInfo(FALLBACK_LUALS_VERSION).binaryRelativePath);
+	if (fs.existsSync(bundled)) return validateOfflineBinary(bundled, requested);
+	try {
+		const found = execFileSync(process.platform === "win32" ? "where.exe" : "which", ["lua-language-server"], { encoding: "utf-8" }).trim().split(/\r?\n/)[0];
+		if (found) return validateOfflineBinary(found, requested);
+	} catch (err) {
+		rethrowLuaLSPermissionError(err, "lua-language-server", "execute");
+	}
+	throw new LuaLSError(`Offline: no usable local LuaLS binary for ${requested}.`, "ERR_LUALS_OFFLINE", `Run 'nanos-lint warmup${requested === "latest" ? "" : ` --luals-version ${requested}`}' online or set LUALS_BIN to a matching local executable.`);
+}
+//#endregion
 //#region src/luals/files.ts
 /** Directories skipped unless the workspace config overrides `workspace.ignoreDir`. */
 const DEFAULT_IGNORE_DIRS = [
@@ -7303,6 +7337,7 @@ function isOfflineError(err) {
 }
 /** Resolves the executable path of a LuaLS binary from env, bundle, cache, or network download. */
 async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
+	if (options?.offline) return resolveOfflineLuaLS(version, options.cacheDir);
 	if (process.env.LUALS_BIN) return assertValidLuaLSBinary(process.env.LUALS_BIN, "LUALS_BIN");
 	if (options?.reuseExisting !== false && (!version || version === "latest")) {
 		const defaultInfo = getPlatformInfo(FALLBACK_LUALS_VERSION);
@@ -7448,7 +7483,7 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		logger.debug(`[luals] Failed to resolve native realpath for target: ${err instanceof Error ? err.message : String(err)}`);
 	}
 	if (!fs.existsSync(absoluteTarget)) throw new LuaLSError(`Target path does not exist: ${targetPath}`, "ERR_TARGET_NOT_FOUND", "Verify that the target path exists and is accessible.");
-	const binary = options.lualsBin ? assertValidLuaLSBinary(options.lualsBin, "--luals-bin") : await resolveLuaLSBinary(options.lualsVersion);
+	const binary = options.lualsBin ? options.offline ? validateOfflineBinary(options.lualsBin, options.lualsVersion ?? "latest") : assertValidLuaLSBinary(options.lualsBin, "--luals-bin") : await resolveLuaLSBinary(options.lualsVersion, { offline: options.offline });
 	let checkDir = absoluteTarget;
 	let targetFileOnly = null;
 	if (fs.statSync(absoluteTarget).isFile()) {
@@ -7990,7 +8025,7 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 	const c = getColors(useColor);
 	const symCross = "✖  ";
 	const symCheck = "✔  ";
-	if (result.passed) {
+	if (result.passed && !result.baselineSummary) {
 		const fileStr = pluralize(result.totalFilesChecked ?? result.totalFiles, "file");
 		return `${c.green}${c.bold}${symCheck}Diagnosis completed, no problems found across ${fileStr}.${c.reset}`;
 	}
@@ -8006,6 +8041,7 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 			logger.debug(`Failed to read file snippet for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
 		}
 		for (const d of diags) {
+			if (d.baseline) continue;
 			const line = d.range.start.line + 1;
 			const col = d.range.start.character + 1;
 			const badge = formatSeverityBadge(d.severity, useColor);
@@ -8031,8 +8067,10 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 		else if (d.severity === 2) warnings++;
 	}
 	lines.push("");
-	const summary = formatProblemSummary(result.totalProblems, errors, warnings, result.totalFiles);
-	lines.push(`${c.red}${c.bold}${symCross}${summary}${c.reset}`);
+	const counts = result.baselineSummary;
+	const summary = counts ? `Diagnosis complete: ${counts.new} new, ${counts.baselined} baselined, ${counts.total} total (${counts.stale} stale baseline entries).` : formatProblemSummary(result.totalProblems, errors, warnings, result.totalFiles);
+	const color = result.passed ? c.green : c.red;
+	lines.push(`${color}${c.bold}${result.passed ? symCheck : symCross}${summary}${c.reset}`);
 	return lines.join("\n");
 }
 /** Formats check diagnostics into GitHub Actions workflow annotation commands. */
@@ -8043,6 +8081,7 @@ function formatGitHubAnnotations(result, cwd = process.cwd()) {
 		const filePath = fileUriToPath(rawUri);
 		const escapedFile = (path.isAbsolute(filePath) ? path.relative(cwd, filePath).replace(/\\/g, "/") : filePath.replace(/\\/g, "/")).replace(/%/g, "%25").replace(/,/g, "%2C");
 		for (const d of diags) {
+			if (d.baseline) continue;
 			const line = d.range.start.line + 1;
 			const col = d.range.start.character + 1;
 			const endLine = d.range.end.line + 1;
@@ -11319,6 +11358,10 @@ async function resolveAnnotations(options = {}) {
 	if (fs.existsSync(bundled) && isAnnotationsValid(bundled)) return bundled;
 	const cacheDir = options.cacheDir ?? getAnnotationsCacheDir();
 	const cachedAnnotationsFile = path.join(cacheDir, ANNOTATIONS_FILENAME);
+	if (options.offline) {
+		if (isAnnotationsValid(cachedAnnotationsFile)) return cachedAnnotationsFile;
+		throw new AnnotationsError(`Offline: no usable local annotations.lua at ${cachedAnnotationsFile}.`, "ERR_ANNOTATIONS_OFFLINE", "Run 'nanos-lint warmup' online or specify --annotations <path>.");
+	}
 	const metadata = readAnnotationsMetadata(cacheDir);
 	const { dateStr } = getTodayDateString();
 	if (fs.existsSync(cachedAnnotationsFile) && !isAnnotationsValid(cachedAnnotationsFile)) {
@@ -11374,7 +11417,10 @@ async function copyAnnotations(targetPath = DEFAULT_COPY_TARGET, options = {}) {
 	let resolvedTarget = path.resolve(targetPath);
 	if (targetPath.endsWith("/") || targetPath.endsWith("\\") || fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isDirectory() || path.extname(resolvedTarget).toLowerCase() !== ".lua") resolvedTarget = path.join(resolvedTarget, ANNOTATIONS_FILENAME);
 	if (fs.existsSync(resolvedTarget) && !options.force) throw new AnnotationsError(`Target annotations file already exists: ${resolvedTarget}. Use --force to overwrite.`, "ERR_ANNOTATIONS_EXISTS", "Pass --force to overwrite the existing annotations file.");
-	const sourcePath = options.annotationsPath ? validateCustomAnnotationsPath(options.annotationsPath, "custom") : await resolveAnnotations({ cacheDir: options.cacheDir });
+	const sourcePath = options.annotationsPath ? validateCustomAnnotationsPath(options.annotationsPath, "custom") : await resolveAnnotations({
+		cacheDir: options.cacheDir,
+		offline: options.offline
+	});
 	const targetDir = path.dirname(resolvedTarget);
 	fs.mkdirSync(targetDir, { recursive: true });
 	fs.copyFileSync(sourcePath, resolvedTarget);
@@ -11480,6 +11526,106 @@ function writeOutput(message) {
 	if (logger.isOutputEnabled()) console.log(message);
 }
 //#endregion
+//#region src/baseline.ts
+/** Builds a line-independent diagnostic identity relative to the checked workspace root. */
+function entryFor(root, uri, diagnostic) {
+	const file = fileUriToPath(uri);
+	return {
+		path: path.relative(root, path.isAbsolute(file) ? file : path.resolve(root, file)).replace(/\\/g, "/"),
+		code: diagnostic.code ?? "",
+		message: diagnostic.message.replace(/\s+/g, " ").trim(),
+		severity: diagnostic.severity,
+		count: 1
+	};
+}
+/** Serializes the fields defining a diagnostic identity, excluding occurrence count. */
+function keyFor(entry) {
+	return JSON.stringify([
+		entry.path,
+		entry.code,
+		entry.message,
+		entry.severity
+	]);
+}
+/** Records sorted diagnostic identities and multiplicities without source positions. */
+function createBaseline(result, root) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const [uri, diagnostics] of Object.entries(result.diagnostics)) for (const diagnostic of diagnostics) {
+		const entry = entryFor(root, uri, diagnostic);
+		const key = keyFor(entry);
+		const previous = entries.get(key);
+		if (previous) previous.count++;
+		else entries.set(key, entry);
+	}
+	return {
+		version: 1,
+		entries: [...entries.values()].sort((a, b) => {
+			const left = keyFor(a);
+			const right = keyFor(b);
+			return left < right ? -1 : left > right ? 1 : 0;
+		})
+	};
+}
+/** Validates a persisted baseline and rejects ambiguous or incompatible entries. */
+function readBaseline(file) {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+		if (parsed?.version !== 1 || !Array.isArray(parsed.entries)) throw new Error("Unsupported baseline schema (expected version 1).");
+		const keys = /* @__PURE__ */ new Set();
+		for (const entry of parsed.entries) {
+			if (!entry || typeof entry.path !== "string" || !entry.path || typeof entry.code !== "string" || typeof entry.message !== "string" || !Number.isInteger(entry.severity) || entry.severity < 1 || entry.severity > 4 || !Number.isSafeInteger(entry.count) || entry.count < 1) throw new Error("Invalid baseline diagnostic entry.");
+			const key = keyFor(entry);
+			if (keys.has(key)) throw new Error("Duplicate baseline diagnostic entry.");
+			keys.add(key);
+		}
+		return parsed;
+	} catch (cause) {
+		throw new ConfigError(`Cannot read diagnostic baseline ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, "ERR_BASELINE_READ", "Regenerate with 'nanos-lint check <targets> --write-baseline <path>' using the same targets and options.", { cause });
+	}
+}
+/** Atomically writes a deterministic baseline, creating its parent directory if needed. */
+function writeBaseline(file, result, root) {
+	try {
+		writeAtomicFileSync(path.resolve(file), `${JSON.stringify(createBaseline(result, root), null, 2)}\n`);
+	} catch (cause) {
+		throw new ConfigError(`Cannot write diagnostic baseline ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, "ERR_BASELINE_WRITE", "Choose a writable baseline path.", { cause });
+	}
+}
+/** Classifies each diagnostic against an occurrence budget and computes strict staleness. */
+function compareBaseline(result, baseline, root, strict = false) {
+	const remaining = new Map(baseline.entries.map((entry) => [keyFor(entry), entry.count]));
+	const diagnostics = {};
+	let baselined = 0;
+	let total = 0;
+	for (const [uri, items] of Object.entries(result.diagnostics)) diagnostics[uri] = [...items].sort((a, b) => a.range.start.line - b.range.start.line || a.range.start.character - b.range.start.character).map((diagnostic) => {
+		const key = keyFor(entryFor(root, uri, diagnostic));
+		const count = remaining.get(key) ?? 0;
+		const matched = count > 0;
+		if (matched) {
+			remaining.set(key, count - 1);
+			baselined++;
+		}
+		total++;
+		return {
+			...diagnostic,
+			baseline: matched
+		};
+	});
+	const stale = [...remaining.values()].reduce((sum, count) => sum + count, 0);
+	const newProblems = total - baselined;
+	return {
+		...result,
+		diagnostics,
+		passed: newProblems === 0 && (!strict || stale === 0),
+		baselineSummary: {
+			new: newProblems,
+			baselined,
+			total,
+			stale
+		}
+	};
+}
+//#endregion
 //#region src/cli-check.ts
 /** Executes the check command on target paths with specified options. */
 async function executeCheckCommand(targetPaths = ["."], opts, setExitCode) {
@@ -11490,7 +11636,10 @@ async function executeCheckCommand(targetPaths = ["."], opts, setExitCode) {
 		setProgressMode("off");
 		logger.setDiagnosticStream("stderr");
 	}
+	if (opts.baseline && opts.writeBaseline || opts.baselineStrict && !opts.baseline) throw new ConfigError("Use either --baseline or --write-baseline; --baseline-strict requires --baseline.", "ERR_BASELINE_OPTIONS");
+	const baseline = opts.baseline ? readBaseline(path.resolve(opts.baseline)) : void 0;
 	const checkOptions = {
+		offline: opts.offline,
 		path: rootPath,
 		paths: canonicalTargets,
 		configpath: opts.config,
@@ -11505,7 +11654,10 @@ async function executeCheckCommand(targetPaths = ["."], opts, setExitCode) {
 		const resolvedConfig = path.resolve(opts.config);
 		if (!fs.existsSync(resolvedConfig)) throw new ConfigError(`Configuration file not found: ${resolvedConfig}`, "ERR_CONFIG_NOT_FOUND", "Verify the path passed to --config exists and is readable.");
 	}
-	const annotationsPath = await resolveAnnotations({ customPath: opts.annotations });
+	const annotationsPath = await resolveAnnotations({
+		customPath: opts.annotations,
+		offline: opts.offline
+	});
 	const userConfig = loadUserConfig(rootPath, checkOptions.configpath);
 	const realmPlan = planRealmCheck({
 		targetPath: rootPath,
@@ -11542,6 +11694,10 @@ async function executeCheckCommand(targetPaths = ["."], opts, setExitCode) {
 			}
 		}
 	}
+	if (opts.writeBaseline) {
+		writeBaseline(opts.writeBaseline, result, rootPath);
+		result = compareBaseline(result, createBaseline(result, rootPath), rootPath);
+	} else if (baseline) result = compareBaseline(result, baseline, rootPath, opts.baselineStrict);
 	const output = formatReport(result, checkOptions.format, process.cwd());
 	if (output) writeOutput(output);
 	if (!result.passed && checkOptions.failOnError) setExitCode(1);
@@ -11574,7 +11730,7 @@ function createProgram(options) {
 		"info",
 		"debug",
 		"silent"
-	]).default(DEFAULT_LOG_LEVEL)).option("--no-progress", "Disable the interactive download, extraction and realm derivation progress display").hook("preAction", (thisCommand, actionCommand) => {
+	]).default(DEFAULT_LOG_LEVEL)).option("--offline", "Use local dependencies only; never access the network").option("--no-progress", "Disable the interactive download, extraction and realm derivation progress display").hook("preAction", (thisCommand, actionCommand) => {
 		const target = actionCommand || thisCommand;
 		const opts = target.optsWithGlobals ? target.optsWithGlobals() : target.opts();
 		if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
@@ -11592,7 +11748,7 @@ function createProgram(options) {
 		"pretty",
 		"json",
 		"github"
-	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).option("-d, --dep <path>", "Path to package dependency or Lua definition file (repeatable)", collectDeps).option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`, DEFAULT_LUALS_VERSION).option("--no-fail", "Do not exit with code 1 if diagnostics are found").addOption(new Option("-l, --log-level <level>", "Logging level: error, warn, info, debug, silent").choices([
+	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).option("-d, --dep <path>", "Path to package dependency or Lua definition file (repeatable)", collectDeps).option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`, DEFAULT_LUALS_VERSION).option("--baseline <path>", "Report and fail only on diagnostics absent from a saved baseline").option("--write-baseline <path>", "Record current diagnostics as a baseline and exit successfully").option("--baseline-strict", "Also fail on stale baseline entries (requires --baseline)").option("--no-fail", "Do not exit with code 1 if diagnostics are found").addOption(new Option("-l, --log-level <level>", "Logging level: error, warn, info, debug, silent").choices([
 		"error",
 		"warn",
 		"info",
@@ -11603,38 +11759,48 @@ function createProgram(options) {
 		"client",
 		"server",
 		"shared"
-	]).default("all")).action(async (targetPaths = ["."], opts) => {
+	]).default("all")).action(async (targetPaths = ["."], opts, cmd) => {
+		opts.offline = cmd.optsWithGlobals().offline;
 		await executeCheckCommand(targetPaths, opts, setExitCode);
 	});
-	program.command("init [path]").description("Scaffold a .luarc.json configuration in the workspace").option("-f, --force", "Overwrite existing .luarc.json configuration").option("--vendor", "Vendor annotations.lua into .nanos-lint/ inside workspace for portable standalone editor setup").option("--annotations <path>", "Path to custom annotations.lua file (requires --vendor)").action(async (targetPath = ".", opts) => {
+	program.command("init [path]").description("Scaffold a .luarc.json configuration in the workspace").option("-t, --template <path>", "Custom JSONC .luarc.json scaffold template").option("-f, --force", "Overwrite existing .luarc.json configuration").option("--vendor", "Vendor annotations.lua into .nanos-lint/ inside workspace for portable standalone editor setup").option("--annotations <path>", "Path to custom annotations.lua file (requires --vendor)").action(async (targetPath = ".", opts, cmd) => {
+		opts.offline = cmd.optsWithGlobals().offline;
 		const shouldVendor = Boolean(opts.vendor);
-		const annotationsPath = shouldVendor ? await resolveAnnotations({ customPath: opts.annotations }) : opts.annotations;
+		const annotationsPath = shouldVendor ? await resolveAnnotations({
+			customPath: opts.annotations,
+			offline: opts.offline
+		}) : opts.annotations;
 		writeOutput(`[init] Initialized nanos world LuaLS configuration: ${initWorkspace(path.resolve(targetPath), {
 			force: opts.force,
 			annotationsPath,
-			vendor: shouldVendor
+			vendor: shouldVendor,
+			templatePath: opts.template
 		})}`);
 		setExitCode(0);
 	});
-	program.command("copy-annotations [destination]").alias("export-annotations").description("Copy cached nanos world annotations.lua definitions into a target file or directory (targets not ending in .lua are treated as directories)").option("-f, --force", "Overwrite existing annotations file").option("--annotations <path>", "Path to custom annotations.lua source file").action(async (destination, opts) => {
+	program.command("copy-annotations [destination]").alias("export-annotations").description("Copy cached nanos world annotations.lua definitions into a target file or directory (targets not ending in .lua are treated as directories)").option("-f, --force", "Overwrite existing annotations file").option("--annotations <path>", "Path to custom annotations.lua source file").action(async (destination, opts, cmd) => {
 		writeOutput(`[copy-annotations] Copied nanos world annotations to: ${await copyAnnotations(destination, {
 			force: opts.force,
-			annotationsPath: opts.annotations
+			annotationsPath: opts.annotations,
+			offline: cmd.optsWithGlobals().offline
 		})}`);
 		setExitCode(0);
 	});
-	program.command("warmup").alias("download").description("Pre-fetch and cache both LuaLS binary and annotations for offline execution").option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`).option("--annotations <path>", "Path to custom annotations.lua file").action(async (opts) => {
-		writeOutput(`[warmup] LuaLS binary ready: ${await resolveLuaLSBinary(opts?.lualsVersion || "latest")}`);
-		const annotationsPath = await resolveAnnotations({ customPath: opts?.annotations });
+	program.command("warmup").alias("download").description("Pre-fetch and cache both LuaLS binary and annotations for offline execution").option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`).option("--annotations <path>", "Path to custom annotations.lua file").action(async (opts, cmd) => {
+		writeOutput(`[warmup] LuaLS binary ready: ${await resolveLuaLSBinary(opts?.lualsVersion || "latest", { offline: cmd.optsWithGlobals().offline })}`);
+		const annotationsPath = await resolveAnnotations({
+			customPath: opts?.annotations,
+			offline: cmd.optsWithGlobals().offline
+		});
 		const meta = readAnnotationsMetadata();
 		writeOutput(`[warmup] nanos world annotations ready: ${annotationsPath}${meta?.commitId && meta.commitId !== "unknown" ? ` (commit ${meta.commitId.slice(0, 7)})` : ""}`);
 		writeOutput("[warmup] Cache pre-warmed successfully. Ready for offline execution.");
 		setExitCode(0);
 	});
-	program.command("download-luals [version]").description("Download and cache the LuaLS binary").option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`).action(async (version, opts) => {
+	program.command("download-luals [version]").description("Download and cache the LuaLS binary").option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`).action(async (version, opts, cmd) => {
 		const ver = version || opts?.lualsVersion || "latest";
 		writeOutput(`[luals] Downloading LuaLS ${ver}...`);
-		writeOutput(`[luals] Ready at: ${await resolveLuaLSBinary(ver)}`);
+		writeOutput(`[luals] Ready at: ${await resolveLuaLSBinary(ver, { offline: cmd.optsWithGlobals().offline })}`);
 		setExitCode(0);
 	});
 	const handleCleanCache = () => {
@@ -11766,6 +11932,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { resolveCheckTargets as $, VALID_LUALS_DIAGNOSTIC_CODES as $t, formatPretty as A, logger as An, validateArchiveMembers as At, collectDeps as B, deriveRealmAnnotationFiles as Bt, getAnnotationsMetadataFilePath as C, systemPaths as Cn, inspectZipMembers as Ct, readAnnotationsMetadata as D, LOG_LEVEL_PRIORITY as Dn, isZipArchive as Dt, isAnnotationsValid as E, LOG_LEVELS as En, isGzipArchive as Et, pluralize as F, resolveLatestLuaLSVersion as Ft, listCheckedFiles as G, createProgressBar as Gt, resolveLuaLSBinary as H, PROGRESS_MILESTONES as Ht, shouldEnableColor as I, resolveLuaLSVersion as It, findCommonAncestorDirectory as J, getProgressMode as Jt, computeUnrequestedExclusions as K, createSpinner as Kt, collectRealmFiles as L, sanitizeLuaLSVersion as Lt, formatReport as M, DEFAULT_LUALS_VERSION as Mt, formatSeverityBadge as N, FALLBACK_LUALS_VERSION as Nt, updateLastCheckedDate as O, Logger as On, parseTarTvSize as Ot, getColors as P, fetchLatestLuaLSVersionFromGitHub as Pt, matchesTargetPaths as Q, DEFAULT_REALM_MAPPINGS as Qt, planRealmCheck as R, ALLOWED_DOWNLOAD_DOMAINS as Rt, getAnnotationsCacheDir as S, getDirectorySize as Sn, getTarBinary as St, getTodayDateString as T, DEFAULT_LOG_LEVEL as Tn, isBinaryValid as Tt, runLuaLSCheck as U, PROGRESS_THROTTLE_MS as Ut, resolvePackageDependencies as V, splitAnnotationsByRealm as Vt, countCheckedFiles as W, SPINNER_FRAMES as Wt, getCanonicalPath as X, restoreTerminal as Xt, findProjectRoot as Y, isProgressInteractive as Yt, isFilesystemRoot as Z, setProgressMode as Zt, ANNOTATIONS_FILENAME as _, ConfigError as _n, MAX_ARCHIVE_MEMBER_COUNT as _t, formatCacheStatusPretty as a, initWorkspace as an, trackDownloadProgress as at, METADATA_FILENAME as b, cleanCache as bn, assertValidLuaLSBinary as bt, resolveAnnotations as c, mergeConfigs as cn, findExistingLuaLSDir as ct, GITHUB_COMMITS_API as d, resolveWorkspaceConfig as dn, getIsoWeek as dt, buildWorkspaceConfig as en, DOWNLOAD_TIMEOUT_MS as et, RAW_ANNOTATIONS_URL as f, stripJsonComments as fn, getLuaLSMetadataPath as ft, getRawAnnotationsUrl as g, CacheError as gn, writeLuaLSMetadata as gt, fetchRawAnnotationsContent as h, AnnotationsError as hn, readLuaLSMetadata as ht, runCLI as i, getPackageRoot as in, limitDownloadStream as it, formatProblemSummary as j, parseLogLevel as jn, getPlatformInfo as jt, formatGitHubAnnotations as k, isValidLogLevel as kn, rethrowLuaLSPermissionError as kt, DOCGEN_BRANCH as l, parseJsonc as ln, getBaseLuaLSCacheDir as lt, fetchLatestCommitId as m, writeTempConfig as mn, listCachedLuaLSVersions as mt, createProgram as n, getDefaultTemplatePath as nn, computeFileSha256 as nt, getCacheStatus as o, loadConfigFile as on, LUALS_METADATA_FILENAME as ot, downloadAndCacheAnnotations as p, stripTrailingSlashes as pn, listCachedLuaLSVersionDirs as pt, filterReportByTargetPaths as q, formatTransferSummary as qt, isDirectExecution as r, getDefinitionsDir as rn, downloadAndExtractLuaLS as rt, copyAnnotations as s, loadUserConfig as sn, cleanupOldCachedLuaLSVersions as st, collectIgnorePatterns as t, getDefaultAnnotationsPath as tn, MAX_ARCHIVE_SIZE_BYTES as tt, DOCGEN_REPO as u, resolveRealmMappings as un, getCacheDir as ut, MAX_ANNOTATIONS_SIZE_BYTES as v, LuaLSError as vn, MAX_DECOMPRESSED_SIZE_BYTES as vt, getCachedAnnotationsFilePath as w, fileUriToPath as wn, isBinaryRunnable as wt, MIN_ANNOTATIONS_SIZE_BYTES as x, formatBytes as xn, escapePowerShellSingleQuote as xt, MAX_COMMIT_JSON_SIZE_BYTES as y, NanosLintError as yn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as yt, runRealmAwareCheck as z, isAllowedDownloadUrl as zt };
+export { findProjectRoot as $, isProgressInteractive as $t, isAnnotationsValid as A, LOG_LEVELS as An, isGzipArchive as At, shouldEnableColor as B, resolveLuaLSVersion as Bt, MAX_COMMIT_JSON_SIZE_BYTES as C, NanosLintError as Cn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as Ct, getAnnotationsMetadataFilePath as D, systemPaths as Dn, inspectZipMembers as Dt, getAnnotationsCacheDir as E, getDirectorySize as En, getTarBinary as Et, formatProblemSummary as F, parseLogLevel as Fn, getPlatformInfo as Ft, resolvePackageDependencies as G, splitAnnotationsByRealm as Gt, planRealmCheck as H, ALLOWED_DOWNLOAD_DOMAINS as Ht, formatReport as I, DEFAULT_LUALS_VERSION as It, countCheckedFiles as J, SPINNER_FRAMES as Jt, resolveLuaLSBinary as K, PROGRESS_MILESTONES as Kt, formatSeverityBadge as L, FALLBACK_LUALS_VERSION as Lt, updateLastCheckedDate as M, Logger as Mn, parseTarTvSize as Mt, formatGitHubAnnotations as N, isValidLogLevel as Nn, rethrowLuaLSPermissionError as Nt, getCachedAnnotationsFilePath as O, fileUriToPath as On, isBinaryRunnable as Ot, formatPretty as P, logger as Pn, validateArchiveMembers as Pt, findCommonAncestorDirectory as Q, getProgressMode as Qt, getColors as R, fetchLatestLuaLSVersionFromGitHub as Rt, MAX_ANNOTATIONS_SIZE_BYTES as S, LuaLSError as Sn, MAX_DECOMPRESSED_SIZE_BYTES as St, MIN_ANNOTATIONS_SIZE_BYTES as T, formatBytes as Tn, escapePowerShellSingleQuote as Tt, runRealmAwareCheck as U, isAllowedDownloadUrl as Ut, collectRealmFiles as V, sanitizeLuaLSVersion as Vt, collectDeps as W, deriveRealmAnnotationFiles as Wt, computeUnrequestedExclusions as X, createSpinner as Xt, listCheckedFiles as Y, createProgressBar as Yt, filterReportByTargetPaths as Z, formatTransferSummary as Zt, downloadAndCacheAnnotations as _, stripTrailingSlashes as _n, listCachedLuaLSVersionDirs as _t, compareBaseline as a, getDefaultAnnotationsPath as an, MAX_ARCHIVE_SIZE_BYTES as at, getRawAnnotationsUrl as b, CacheError as bn, writeLuaLSMetadata as bt, writeBaseline as c, getPackageRoot as cn, limitDownloadStream as ct, copyAnnotations as d, loadUserConfig as dn, cleanupOldCachedLuaLSVersions as dt, restoreTerminal as en, getCanonicalPath as et, resolveAnnotations as f, mergeConfigs as fn, findExistingLuaLSDir as ft, RAW_ANNOTATIONS_URL as g, stripJsonComments as gn, getLuaLSMetadataPath as gt, GITHUB_COMMITS_API as h, resolveWorkspaceConfig as hn, getIsoWeek as ht, runCLI as i, buildWorkspaceConfig as in, DOWNLOAD_TIMEOUT_MS as it, readAnnotationsMetadata as j, LOG_LEVEL_PRIORITY as jn, isZipArchive as jt, getTodayDateString as k, DEFAULT_LOG_LEVEL as kn, isBinaryValid as kt, formatCacheStatusPretty as l, initWorkspace as ln, trackDownloadProgress as lt, DOCGEN_REPO as m, resolveRealmMappings as mn, getCacheDir as mt, createProgram as n, DEFAULT_REALM_MAPPINGS as nn, matchesTargetPaths as nt, createBaseline as o, getDefaultTemplatePath as on, computeFileSha256 as ot, DOCGEN_BRANCH as p, parseJsonc as pn, getBaseLuaLSCacheDir as pt, runLuaLSCheck as q, PROGRESS_THROTTLE_MS as qt, isDirectExecution as r, VALID_LUALS_DIAGNOSTIC_CODES as rn, resolveCheckTargets as rt, readBaseline as s, getDefinitionsDir as sn, downloadAndExtractLuaLS as st, collectIgnorePatterns as t, setProgressMode as tn, isFilesystemRoot as tt, getCacheStatus as u, loadConfigFile as un, LUALS_METADATA_FILENAME as ut, fetchLatestCommitId as v, writeTempConfig as vn, listCachedLuaLSVersions as vt, METADATA_FILENAME as w, cleanCache as wn, assertValidLuaLSBinary as wt, ANNOTATIONS_FILENAME as x, ConfigError as xn, MAX_ARCHIVE_MEMBER_COUNT as xt, fetchRawAnnotationsContent as y, AnnotationsError as yn, readLuaLSMetadata as yt, pluralize as z, resolveLatestLuaLSVersion as zt };
 
-//# sourceMappingURL=cli-CsIAHyRZ.js.map
+//# sourceMappingURL=cli-DN7ZhC9e.js.map