nanos-lint 2.8.1 → 2.8.2

package/dist/{cli-BAy_Ztvh.js → cli-BTHx4yp_.js}

@@ -5,8 +5,8 @@ import path, { posix, win32 } from "node:path";
 import os from "node:os";
 import process$1 from "node:process";
 import childProcess, { execFile, execFileSync } from "node:child_process";
-import crypto from "node:crypto";
 import { promisify, stripVTControlCharacters } from "node:util";
+import crypto from "node:crypto";
 import Pe, { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { lstatSync, readdir, readdirSync, readlinkSync, realpathSync } from "fs";
@@ -29,9 +29,11 @@ const LOG_LEVEL_PRIORITY = {
 	debug: 4
 };
 const DEFAULT_LOG_LEVEL = "warn";
+/** Validates whether a string corresponds to a recognized log level. */
 function isValidLogLevel(level) {
 	return level in LOG_LEVEL_PRIORITY;
 }
+/** Parses a string into a valid LogLevel, defaulting to 'warn'. */
 function parseLogLevel(raw) {
 	if (!raw) return DEFAULT_LOG_LEVEL;
 	const lower = raw.trim().toLowerCase();
@@ -46,12 +48,15 @@ var Logger = class {
 			if (envLevel && isValidLogLevel(envLevel.trim().toLowerCase())) this.level = envLevel.trim().toLowerCase();
 		}
 	}
+	/** Sets the active minimum logging level. */
 	setLevel(level) {
 		if (isValidLogLevel(level)) this.level = level;
 	}
+	/** Returns the current active log level. */
 	getLevel() {
 		return this.level;
 	}
+	/** Checks if a message at the specified level should be emitted. */
 	isEnabledFor(level) {
 		return LOG_LEVEL_PRIORITY[this.level] >= LOG_LEVEL_PRIORITY[level];
 	}
@@ -59,15 +64,19 @@ var Logger = class {
 	isOutputEnabled() {
 		return this.level !== "silent";
 	}
+	/** Logs an error-level message to stderr. */
 	error(...args) {
 		if (this.isEnabledFor("error")) console.error(...args);
 	}
+	/** Logs a warning-level message to stderr. */
 	warn(...args) {
 		if (this.isEnabledFor("warn")) console.warn(...args);
 	}
+	/** Logs an informational message to stdout. */
 	info(...args) {
 		if (this.isEnabledFor("info")) console.log(...args);
 	}
+	/** Logs a debug-level diagnostic message to stdout. */
 	debug(...args) {
 		if (this.isEnabledFor("debug")) console.debug(...args);
 	}
@@ -1022,6 +1031,7 @@ function getPackageRoot() {
 	}
 	return path.resolve(__dirname, "..");
 }
+/** Resolves the default annotations path from environment variable, bundled file, or user cache. */
 function getDefaultAnnotationsPath() {
 	const envPath = process.env.NANOS_ANNOTATIONS_PATH || process.env.NANOS_ANNOTATIONS;
 	if (envPath && fs.existsSync(envPath)) return path.resolve(envPath);
@@ -1036,6 +1046,7 @@ function getDefaultAnnotationsPath() {
 function getDefinitionsDir() {
 	return path.dirname(getDefaultAnnotationsPath());
 }
+/** Resolves the absolute path to the default .luarc.json template shipped with the package. */
 function getDefaultTemplatePath() {
 	const root = getPackageRoot();
 	return path.join(root, "templates", ".luarc.json");
@@ -1047,6 +1058,7 @@ function stripJsonComments(text) {
 	const cleanText = text.replace(/^\uFEFF/, "");
 	return stripComments(cleanText);
 }
+/** Parses JSONC text with support for comments and trailing commas. */
 function parseJsonc(text) {
 	const cleanText = text.replace(/^\uFEFF/, "");
 	const errors = [];
@@ -1057,6 +1069,7 @@ function parseJsonc(text) {
 	}
 	return result;
 }
+/** Reads and parses a .luarc.json configuration file from disk. */
 function loadConfigFile(filePath) {
 	if (!fs.existsSync(filePath)) throw new ConfigError(`Configuration file not found: ${filePath}`, "ERR_CONFIG_NOT_FOUND", "Ensure the configuration file path is correct or run 'nanos-lint init' to generate a default config.");
 	const content = fs.readFileSync(filePath, "utf-8");
@@ -1352,25 +1365,12 @@ function initWorkspace(workspacePath, options) {
 //#region src/luals/version.ts
 const FALLBACK_LUALS_VERSION = "3.19.1";
 const DEFAULT_LUALS_VERSION = "latest";
-/**
-* Characters accepted in a LuaLS version/tag. Only ASCII letters, digits, dots,
-* dashes and underscores are allowed, so a version can never contain a path
-* separator, a drive letter or a traversal segment.
-*/
+/** Characters accepted in a safe LuaLS version tag. */
 const SAFE_VERSION_CHARS = new Map([..."0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz._-"].map((ch) => [ch, ch]));
 const MAX_VERSION_LENGTH = 64;
 /**
-* Validates a LuaLS version/tag and rebuilds it from the allow-list above.
-*
-* Version strings originate from untrusted sources: the GitHub releases API
-* response and user supplied `--luals-version` arguments. They are interpolated
-* into cache directory paths, download URLs, and the path of the binary that is
-* eventually executed, so they must be constrained to a single safe path
-* segment. Rebuilding the value character by character guarantees the returned
-* string only ever contains allow-listed characters (CodeQL: js/command-line-injection).
-*
-* @returns the normalized version (a single leading `v` is dropped), or `null`
-*          when the input cannot be used as a version tag.
+* Validates and normalizes a LuaLS version string to prevent path traversal or injection.
+* Drops a single leading 'v' and returns null on invalid characters.
 */
 function sanitizeLuaLSVersion(raw) {
 	const trimmed = raw.trim();
@@ -1427,6 +1427,7 @@ async function resolveLuaLSVersion(version) {
 }
 //#endregion
 //#region src/luals/platform.ts
+/** Resolves platform-specific binary naming and relative paths for the host operating system. */
 function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 	const platform = process.platform;
 	const arch = process.arch;
@@ -1464,6 +1465,158 @@ function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 }
 //#endregion
 //#region src/luals/validation.ts
+const execFileAsync$2 = promisify(execFile);
+/**
+* Escapes single quotes for safe PowerShell single-quoted string interpolation.
+*/
+function escapePowerShellSingleQuote(str) {
+	return str.replace(/'/g, "''");
+}
+/**
+* Maximum total decompressed size of a LuaLS release archive (500 MB).
+* Protects against zip bombs and maliciously inflated archives (#31).
+*/
+const MAX_DECOMPRESSED_SIZE_BYTES = 524288e3;
+/**
+* Maximum number of members allowed in a LuaLS release archive (10,000).
+* Protects against inode exhaustion and archive recursion attacks (#31).
+*/
+const MAX_ARCHIVE_MEMBER_COUNT = 1e4;
+/** Parses the file size column from a 'tar -tvf' listing output line. */
+function parseTarTvSize(line) {
+	const parts = line.trim().split(/\s+/);
+	if (parts.length < 5) return 0;
+	const p1 = parts[1];
+	const p2 = parts[2];
+	const p4 = parts[4];
+	if (p1 && p2 && p1.includes("/") && /^\d+$/.test(p2)) return parseInt(p2, 10) || 0;
+	if (p4 && /^\d+$/.test(p4)) return parseInt(p4, 10) || 0;
+	for (let i = 2; i < Math.min(parts.length - 1, 6); i++) {
+		const p = parts[i];
+		if (p && /^\d+$/.test(p)) return parseInt(p, 10) || 0;
+	}
+	return 0;
+}
+/** Asserts that an archive entry name does not escape the destination directory. */
+function checkEscapedMember(member) {
+	if (member.startsWith("/") || member.startsWith("\\") || /^[a-zA-Z]:[\\/]/.test(member) || member.split(/[/\\]/).includes("..")) throw new LuaLSError(`Archive member path escapes extraction directory: ${member}`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+}
+/** Validates that archive entry count and decompressed size do not exceed safety limits. */
+function checkArchiveLimits(count, size) {
+	if (count > 1e4) throw new LuaLSError(`Archive member count (${count}) exceeds maximum limit (${MAX_ARCHIVE_MEMBER_COUNT})`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+	if (size > 524288e3) throw new LuaLSError(`Archive declared decompressed size (${size} bytes) exceeds maximum limit (${MAX_DECOMPRESSED_SIZE_BYTES} bytes)`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and ensure there is sufficient disk space.");
+}
+/** Locates the platform tar executable path, checking System32 on Windows. */
+function getTarBinary() {
+	if (process.platform === "win32") {
+		const sysTar = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "tar.exe");
+		if (fs.existsSync(sysTar)) return sysTar;
+	}
+	return "tar";
+}
+/** Pre-inspects a ZIP archive's central directory to enforce extraction safety constraints (#31). */
+function inspectZipMembers(archivePath) {
+	const buf = fs.readFileSync(archivePath);
+	if (buf.length < 22) throw new LuaLSError("Failed to inspect release archive before extraction: archive is too small to be a valid zip", "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+	let eocdOffset = -1;
+	const minOffset = Math.max(0, buf.length - 22 - 65535);
+	for (let i = buf.length - 22; i >= minOffset; i--) if (buf.readUInt32LE(i) === 101010256) {
+		const commentLen = buf.readUInt16LE(i + 20);
+		if (i + 22 + commentLen === buf.length) {
+			eocdOffset = i;
+			break;
+		}
+	}
+	if (eocdOffset === -1) {
+		for (let i = buf.length - 22; i >= minOffset; i--) if (buf.readUInt32LE(i) === 101010256) {
+			eocdOffset = i;
+			break;
+		}
+	}
+	if (eocdOffset === -1) throw new LuaLSError("Failed to inspect release archive before extraction: corrupt or invalid zip archive (missing EOCD)", "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+	const entryCount = buf.readUInt16LE(eocdOffset + 10);
+	let offset = buf.readUInt32LE(eocdOffset + 16);
+	let memberCount = 0;
+	let totalDeclaredSize = 0;
+	for (let i = 0; i < entryCount && offset + 46 <= buf.length; i++) {
+		if (buf.readUInt32LE(offset) !== 33639248) throw new LuaLSError("Failed to inspect release archive before extraction: invalid central directory header", "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+		const uncompressedSize = buf.readUInt32LE(offset + 24);
+		const fileNameLen = buf.readUInt16LE(offset + 28);
+		const extraLen = buf.readUInt16LE(offset + 30);
+		const commentLen = buf.readUInt16LE(offset + 32);
+		if ((buf.readUInt32LE(offset + 38) >>> 16 & 61440) === 40960) throw new LuaLSError("Archive member is a symbolic or hard link. Refusing to extract archive-planted links.", "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+		const fileNameStart = offset + 46;
+		const fileNameEnd = fileNameStart + fileNameLen;
+		if (fileNameEnd > buf.length) throw new LuaLSError("Failed to inspect release archive before extraction: corrupt file name length in zip", "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+		const fileName = buf.toString("utf-8", fileNameStart, fileNameEnd);
+		memberCount++;
+		totalDeclaredSize += uncompressedSize;
+		checkEscapedMember(fileName);
+		offset += 46 + fileNameLen + extraLen + commentLen;
+	}
+	checkArchiveLimits(memberCount, totalDeclaredSize);
+	return {
+		memberCount,
+		totalDeclaredSize
+	};
+}
+/** Detects whether an archive file starts with ZIP magic bytes. */
+function isZipArchive(archivePath) {
+	try {
+		const fd = fs.openSync(archivePath, "r");
+		const buf = Buffer.alloc(4);
+		const bytesRead = fs.readSync(fd, buf, 0, 4, 0);
+		fs.closeSync(fd);
+		if (bytesRead < 4) return false;
+		return buf[0] === 80 && buf[1] === 75 && (buf[2] === 3 && buf[3] === 4 || buf[2] === 5 && buf[3] === 6 || buf[2] === 7 && buf[3] === 8);
+	} catch {
+		return false;
+	}
+}
+/** Detects whether an archive file starts with GZIP magic bytes. */
+function isGzipArchive(archivePath) {
+	try {
+		const fd = fs.openSync(archivePath, "r");
+		const buf = Buffer.alloc(2);
+		const bytesRead = fs.readSync(fd, buf, 0, 2, 0);
+		fs.closeSync(fd);
+		return bytesRead >= 2 && buf[0] === 31 && buf[1] === 139;
+	} catch {
+		return false;
+	}
+}
+/** Pre-inspects archive members using tar listing or zip directory parsing to enforce extraction safety constraints (#31). */
+async function validateArchiveMembers(archivePath) {
+	if (isZipArchive(archivePath) || archivePath.toLowerCase().endsWith(".zip") && !isGzipArchive(archivePath)) return inspectZipMembers(archivePath);
+	let memberCount = 0;
+	let totalDeclaredSize = 0;
+	const tarBin = getTarBinary();
+	const archiveDir = path.dirname(archivePath);
+	const archiveFile = path.basename(archivePath);
+	try {
+		const [namesOutput, verboseOutput] = await Promise.all([execFileAsync$2(tarBin, ["-tf", archiveFile], { cwd: archiveDir }), execFileAsync$2(tarBin, ["-tvf", archiveFile], { cwd: archiveDir })]);
+		for (const rawName of namesOutput.stdout.split(/\r?\n/)) {
+			const member = rawName.trim();
+			if (!member) continue;
+			memberCount++;
+			checkEscapedMember(member);
+		}
+		for (const rawLine of verboseOutput.stdout.split(/\r?\n/)) {
+			const line = rawLine.trim();
+			if (!line) continue;
+			if (/^[lh]/.test(line) || line.includes(" -> ") || line.includes(" link to ")) throw new LuaLSError("Archive member is a symbolic or hard link. Refusing to extract archive-planted links.", "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and verify the LuaLS release integrity.");
+			totalDeclaredSize += parseTarTvSize(line);
+		}
+		checkArchiveLimits(memberCount, totalDeclaredSize);
+	} catch (err) {
+		if (err instanceof LuaLSError) throw err;
+		throw new LuaLSError(`Failed to inspect release archive before extraction: ${err instanceof Error ? err.message : String(err)}`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and ensure there is sufficient disk space.", { cause: err });
+	}
+	return {
+		memberCount,
+		totalDeclaredSize
+	};
+}
 /**
 * Minimum plausible size of a downloaded LuaLS executable. Release assets are
 * several megabytes, so anything smaller is a truncated download or a stray
@@ -1545,6 +1698,7 @@ function assertValidLuaLSBinary(binaryPath, source) {
 }
 //#endregion
 //#region src/luals/cache.ts
+/** Returns the base directory in the system cache where LuaLS versions and metadata are stored. */
 function getBaseLuaLSCacheDir() {
 	return path.join(systemPaths.cache, "luals");
 }
@@ -1574,9 +1728,11 @@ function getIsoWeek(d = /* @__PURE__ */ new Date()) {
 	const weekNo = Math.ceil(((date.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
 	return `${date.getUTCFullYear()}-W${String(weekNo).padStart(2, "0")}`;
 }
+/** Returns the path to the LuaLS metadata.json file within the specified cache directory. */
 function getLuaLSMetadataPath(baseCacheDir = getBaseLuaLSCacheDir()) {
 	return path.join(baseCacheDir, LUALS_METADATA_FILENAME);
 }
+/** Reads and parses the LuaLS metadata.json file, purging corrupted or invalid files automatically. */
 function readLuaLSMetadata(baseCacheDir = getBaseLuaLSCacheDir()) {
 	const metaPath = getLuaLSMetadataPath(baseCacheDir);
 	if (!fs.existsSync(metaPath)) return null;
@@ -1606,6 +1762,7 @@ function readLuaLSMetadata(baseCacheDir = getBaseLuaLSCacheDir()) {
 	}
 	return null;
 }
+/** Writes metadata.json containing the latest checked version and timestamp. */
 function writeLuaLSMetadata(metadata, baseCacheDir = getBaseLuaLSCacheDir()) {
 	try {
 		fs.mkdirSync(baseCacheDir, { recursive: true });
@@ -1768,12 +1925,6 @@ function computeFileSha256(filePath) {
 }
 const execFileAsync$1 = promisify(execFile);
 /**
-* Escapes single quotes for safe PowerShell single-quoted string interpolation.
-*/
-function escapePowerShellSingleQuote(str) {
-	return str.replace(/'/g, "''");
-}
-/**
 * Enforces a maximum byte count on an asynchronous download stream.
 */
 async function* limitDownloadStream(source) {
@@ -1784,6 +1935,7 @@ async function* limitDownloadStream(source) {
 		yield chunk;
 	}
 }
+/** Downloads, verifies, and extracts the LuaLS release archive for the current platform. */
 async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDir, options) {
 	const resolvedVersion = await resolveLuaLSVersion(version);
 	const info = getPlatformInfo(resolvedVersion);
@@ -1866,21 +2018,22 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 			const archiveSha256 = computeFileSha256(archivePath);
 			logger.info(`[luals] Downloaded ${info.assetName} (SHA-256 ${archiveSha256})`);
 			if (!options?.quiet) logger.info(`[luals] Extracting to ${destDir}...`);
+			await validateArchiveMembers(archivePath);
 			try {
 				const tarArgs = process.platform === "win32" ? [
 					"-xf",
-					archivePath,
+					path.basename(archivePath),
 					"-C",
 					tempDir
 				] : [
 					"-xf",
-					archivePath,
+					path.basename(archivePath),
 					"--no-same-owner",
 					"--no-same-permissions",
 					"-C",
 					tempDir
 				];
-				await execFileAsync$1("tar", tarArgs);
+				await execFileAsync$1(getTarBinary(), tarArgs, { cwd: path.dirname(archivePath) });
 			} catch (tarErr) {
 				if (process.platform === "win32" && info.assetName.endsWith(".zip")) await execFileAsync$1("powershell.exe", [
 					"-NoProfile",
@@ -1889,6 +2042,8 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 				]);
 				else throw tarErr;
 			}
+			const extractedSize = getDirectorySize(tempDir);
+			if (extractedSize > 524288e3) throw new LuaLSError(`Extracted archive size (${extractedSize} bytes) exceeds maximum limit (${MAX_DECOMPRESSED_SIZE_BYTES} bytes)`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and ensure there is sufficient disk space.");
 			try {
 				fs.unlinkSync(archivePath);
 			} catch (err) {
@@ -5256,21 +5411,8 @@ const LUA_FILE_PATTERN = "**/*.lua";
 /** `glob` rejects patterns longer than this, so they are dropped before matching. */
 const MAX_PATTERN_LENGTH = 65536;
 /**
-* Complexity budget per pattern. `minimatch` evaluates patterns through an AST
-* but still compiles them to regular expressions, so ambiguous wildcards inside
-* one path segment can backtrack, and brace groups expand combinatorially
-* (`{a,b}` repeated 16 times is 65 536 alternatives). A hostile or accidental
-* `.luarc.json` could otherwise stall the file walk, so patterns beyond the
-* budget are skipped with a warning instead of being matched.
-*
-* The ambiguity of one segment grows like `C(segment length, wildcards)`, so the
-* per-segment cap is what keeps matching cheap. `**\/*a*a*a*a\/*a*a*a*a\/*a*a*a*a\/*a*a*a*z.lua`
-* (4 wildcards per segment) stays within a 4-wildcard cap yet costs ~5 ms per
-* candidate file — ~100 s on a 20 000-file tree — while two wildcards per
-* segment cost `C(60, 2) = 1 770` splits, hundreds of times less. The budget is
-* deliberately far below what minimatch can parse: every realistic pattern
-* (`**\/*.{bak,tmp}`, `**\/node_modules\/**`, `**\/item-[0-9].lua`,
-* `**\/*.min.*`) needs at most two wildcards in any one segment.
+* Complexity budget per pattern to bound backtracking and combinatorial brace expansion.
+* Patterns exceeding limits are skipped with a warning to protect against ReDoS (#27).
 */
 const MAX_WILDCARDS_PER_SEGMENT = 2;
 const MAX_TOTAL_WILDCARDS = 12;
@@ -5303,15 +5445,7 @@ function isPatternWithinBudget(pattern) {
 	if (countWildcards(pattern) > MAX_TOTAL_WILDCARDS) return false;
 	return pattern.split("/").every((segment) => countWildcards(segment) <= MAX_WILDCARDS_PER_SEGMENT);
 }
-/**
-* Normalizes one user-supplied pattern (`workspace.ignoreDir`, `files.exclude`
-* or a built-in default) into the slash-separated form `glob` expects.
-* Backslashes are accepted as separators so Windows-authored `.luarc.json`
-* files keep working, and trailing slashes are dropped so `vendor/` behaves
-* exactly like `vendor`. Patterns that cannot be matched (`""`, `"."`, NUL
-* bytes, oversized input, absolute paths, or non-string JSON values) are
-* rejected instead of being handed to `glob`.
-*/
+/** Normalizes a user pattern to slash-separated form, dropping trailing slashes and invalid inputs. */
 function normalizePattern(pattern) {
 	if (typeof pattern !== "string") return null;
 	const normalized = pattern.trim().replace(/\\/g, "/").replace(/\/+$/, "");
@@ -5320,27 +5454,11 @@ function normalizePattern(pattern) {
 }
 /** Drive-letter prefixes, recognized on every platform (not just Windows). */
 const WINDOWS_ABSOLUTE_PATTERN = /^[A-Za-z]:\//;
-/**
-* `workspace.ignoreDir` / `files.exclude` entries are workspace-relative in
-* LuaLS, and `glob` matches ignore patterns against walk-relative paths. An
-* absolute entry is therefore unusable, and `glob` anchors it on some platforms
-* but not others (a macOS `/var` -> `/private/var` walk root or a Windows drive
-* letter behave differently again), so it is skipped to keep one `.luarc.json`
-* behaving identically on Linux, macOS and Windows.
-*/
+/** Rejects absolute patterns to maintain cross-platform consistency with LuaLS relative paths. */
 function isAbsolutePattern(normalized) {
 	return path.posix.isAbsolute(normalized) || WINDOWS_ABSOLUTE_PATTERN.test(normalized);
 }
-/**
-* Expands one LuaLS pattern into the equivalent `glob` ignore patterns:
-*
-* - basename-only patterns (`*.lua`, `vendor`) match at any depth, so the
-*   `**\/`-prefixed variants are added (mirrors LuaLS `matchBase` semantics);
-* - a pattern also excludes everything below a matching directory, which is
-*   what the trailing `/**` variant expresses;
-* - the pattern itself is always kept so an exact file or directory match
-*   works as written.
-*/
+/** Expands a LuaLS pattern to include basename and sub-directory variants for glob matching. */
 function expandIgnorePattern(pattern) {
 	return pattern.includes("/") ? [pattern, `${pattern}/**`] : [`**/${pattern}`, `**/${pattern}/**`];
 }
@@ -5361,17 +5479,7 @@ function toIgnorePatterns(patterns) {
 	}
 	return ignore;
 }
-/**
-* Counts candidate Lua files within targetPath, taking `workspace.ignoreDir`
-* and `files.exclude` into account.
-*
-* Traversal and matching are delegated to the bundled `glob` package, whose
-* `minimatch` matcher understands the full glob syntax LuaLS accepts (brace
-* expansion, character classes, `**`, `?`) instead of the hand-rolled
-* glob-to-regex translation used before. Combined with the pattern budgets
-* above, this keeps the count predictable for adversarial configurations
-* while remaining consistent with LuaLS exclude semantics (#27).
-*/
+/** Counts candidate Lua files within targetPath, taking workspace ignoreDir and files.exclude into account (#27). */
 function countCheckedFiles(targetPath, configPath) {
 	let absPath = path.resolve(targetPath);
 	if (!fs.existsSync(absPath)) return 0;
@@ -5410,11 +5518,13 @@ function countCheckedFiles(targetPath, configPath) {
 //#endregion
 //#region src/luals/runner.ts
 const execFileAsync = promisify(execFile);
+/** Determines if an error represents an offline network condition. */
 function isOfflineError(err) {
 	if (!err) return false;
 	const msg = err instanceof Error ? err.message : String(err);
 	return /offline|enotfound|eai_again|econnrefused|etimedout|fetch failed/i.test(msg);
 }
+/** Resolves the executable path of a LuaLS binary from env, bundle, cache, or network download. */
 async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 	if (process.env.LUALS_BIN) return assertValidLuaLSBinary(process.env.LUALS_BIN, "LUALS_BIN");
 	if (options?.reuseExisting !== false && (!version || version === "latest")) {
@@ -5572,6 +5682,7 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 	cleanupOldCachedLuaLSVersions(targetVersion, baseCacheDir);
 	return downloadedBinary;
 }
+/** Executes the LuaLS diagnostics check on the target path using merged configurations. */
 async function runLuaLSCheck(targetPath, configPath, options) {
 	let absoluteTarget = path.resolve(targetPath);
 	try {
@@ -5680,6 +5791,7 @@ function shouldEnableColor() {
 	if (process.env.FORCE_COLOR !== void 0 && process.env.FORCE_COLOR !== "0") return true;
 	return process.stdout ? Boolean(process.stdout.isTTY) : true;
 }
+/** Returns ANSI color escape code helpers or empty strings when colors are disabled. */
 function getColors(useColor = shouldEnableColor()) {
 	if (!useColor) return {
 		reset: "",
@@ -5706,6 +5818,7 @@ function getColors(useColor = shouldEnableColor()) {
 		gray: "\x1B[90m"
 	};
 }
+/** Formats a numeric diagnostic severity level into a colored badge. */
 function formatSeverityBadge(severity, useColor = shouldEnableColor()) {
 	const c = getColors(useColor);
 	const name = SEVERITY_NAMES[severity] || "Warning";
@@ -5716,9 +5829,11 @@ function formatSeverityBadge(severity, useColor = shouldEnableColor()) {
 		default: return `${c.gray}[${name}]${c.reset}`;
 	}
 }
+/** Formats a noun with its count and pluralizes if necessary. */
 function pluralize(count, singular, plural = `${singular}s`) {
 	return `${count} ${count === 1 ? singular : plural}`;
 }
+/** Formats the summary text detailing diagnostic counts and affected files. */
 function formatProblemSummary(totalProblems, errors, warnings, files) {
 	const parts = [];
 	if (errors > 0) parts.push(pluralize(errors, "error"));
@@ -5728,6 +5843,7 @@ function formatProblemSummary(totalProblems, errors, warnings, files) {
 	const breakdown = parts.length > 0 ? ` (${parts.join(", ")})` : "";
 	return `Diagnosis complete: ${pluralize(totalProblems, "problem")}${breakdown} found across ${pluralize(files, "file")}.`;
 }
+/** Formats check results into pretty human-readable terminal output. */
 function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor()) {
 	const c = getColors(useColor);
 	const symCross = "✖  ";
@@ -5777,6 +5893,7 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 	lines.push(`${c.red}${c.bold}${symCross}${summary}${c.reset}`);
 	return lines.join("\n");
 }
+/** Formats check diagnostics into GitHub Actions workflow annotation commands. */
 function formatGitHubAnnotations(result, cwd = process.cwd()) {
 	const commands = [];
 	for (const [rawUri, diags] of Object.entries(result.diagnostics)) {
@@ -5796,6 +5913,7 @@ function formatGitHubAnnotations(result, cwd = process.cwd()) {
 	}
 	return commands.join("\n");
 }
+/** Formats check results according to the chosen format (pretty, json, github). */
 function formatReport(result, format = "pretty", cwd = process.cwd(), useColor = shouldEnableColor()) {
 	switch (format) {
 		case "json": return JSON.stringify(result, null, 2);
@@ -8763,13 +8881,13 @@ function useColor() {
 }
 new Command();
 //#endregion
-//#region src/annotations.ts
-const DOCGEN_REPO = "nanos-world/vscode-extension";
-const DOCGEN_BRANCH = "docgen-output";
-const RAW_ANNOTATIONS_URL = "https://raw.githubusercontent.com/nanos-world/vscode-extension/refs/heads/docgen-output/annotations.lua";
-const GITHUB_COMMITS_API = "https://api.github.com/repos/nanos-world/vscode-extension/commits/docgen-output";
+//#region src/annotations-metadata.ts
 const ANNOTATIONS_FILENAME = "annotations.lua";
 const METADATA_FILENAME = "metadata.json";
+const MIN_ANNOTATIONS_SIZE_BYTES = 1e3;
+const MAX_ANNOTATIONS_SIZE_BYTES = 10485760;
+const MAX_COMMIT_JSON_SIZE_BYTES = 1048576;
+/** Returns current date string formatted as YYYY-MM-DD alongside a date components object. */
 function getTodayDateString(d = /* @__PURE__ */ new Date()) {
 	const year = d.getFullYear();
 	const month = d.getMonth() + 1;
@@ -8783,60 +8901,127 @@ function getTodayDateString(d = /* @__PURE__ */ new Date()) {
 		}
 	};
 }
+/** Returns the system cache directory used for nanos world annotations. */
 function getAnnotationsCacheDir() {
 	return path.join(systemPaths.cache, "annotations");
 }
+/** Returns the full path to the cached annotations.lua file. */
 function getCachedAnnotationsFilePath() {
 	return path.join(getAnnotationsCacheDir(), ANNOTATIONS_FILENAME);
 }
+/** Returns the full path to the annotations metadata.json file. */
 function getAnnotationsMetadataFilePath() {
 	return path.join(getAnnotationsCacheDir(), METADATA_FILENAME);
 }
+/** Reads and parses annotations metadata.json, purging corrupt files automatically. */
 function readAnnotationsMetadata(cacheDir = getAnnotationsCacheDir()) {
 	const metaPath = path.join(cacheDir, "metadata.json");
 	if (!fs.existsSync(metaPath)) return null;
-	try {
-		const content = fs.readFileSync(metaPath, "utf-8");
-		const parsed = JSON.parse(content);
-		if (typeof parsed?.commitId === "string" && typeof parsed?.lastChecked === "string") return parsed;
+	const purge = (reason) => {
 		try {
 			fs.unlinkSync(metaPath);
-			logger.warn(`[annotations] Stale or invalid annotations metadata at ${metaPath} purged.`);
-		} catch (unlinkErr) {
-			logger.debug(`[annotations] Failed to unlink invalid metadata: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}`);
+			logger.warn(`[annotations] ${reason} annotations metadata at ${metaPath} purged.`);
+		} catch (err) {
+			logger.debug(`[annotations] Failed to unlink metadata: ${err instanceof Error ? err.message : String(err)}`);
 		}
+	};
+	try {
+		const parsed = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+		if (typeof parsed?.commitId === "string" && typeof parsed?.lastChecked === "string") return parsed;
+		purge("Stale or invalid");
 	} catch (err) {
 		logger.debug(`Failed to parse annotations metadata: ${err instanceof Error ? err.message : String(err)}`);
-		try {
-			fs.unlinkSync(metaPath);
-			logger.warn(`[annotations] Corrupted annotations metadata at ${metaPath} purged.`);
-		} catch (unlinkErr) {
-			logger.debug(`[annotations] Failed to unlink corrupted metadata: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}`);
-		}
+		purge("Corrupted");
 	}
 	return null;
 }
-const MIN_ANNOTATIONS_SIZE_BYTES = 1e3;
-/**
-* Verifies that an annotations file exists, is a regular file, is of non-trivial size (>= MIN_ANNOTATIONS_SIZE_BYTES),
-* and begins with valid LuaLS metadata or nanos world definitions.
-*/
+/** Verifies that an annotations file exists, is non-trivial in size, and contains valid header. */
 function isAnnotationsValid(filePath) {
 	if (!fs.existsSync(filePath)) return false;
 	try {
 		const stat = fs.statSync(filePath);
 		if (!stat.isFile() || stat.size < 1e3) return false;
 		const fd = fs.openSync(filePath, "r");
-		const buffer = Buffer.alloc(512);
-		const bytesRead = fs.readSync(fd, buffer, 0, 512, 0);
-		fs.closeSync(fd);
-		const header = buffer.toString("utf-8", 0, bytesRead).trimStart();
-		return header.startsWith("---@meta") || header.includes("nanos world") || header.includes("nanos-world");
+		try {
+			const buffer = Buffer.alloc(512);
+			const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
+			const header = buffer.toString("utf-8", 0, bytesRead).trimStart();
+			return header.startsWith("---@meta") || header.includes("nanos world") || header.includes("nanos-world");
+		} finally {
+			fs.closeSync(fd);
+		}
 	} catch (err) {
 		logger.debug(`[annotations] Annotation validation failed for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
 		return false;
 	}
 }
+/** Updates metadata lastChecked date atomically without modifying annotations.lua. */
+function updateLastCheckedDate(commitId, cacheDir = getAnnotationsCacheDir()) {
+	const { dateStr, dateObj } = getTodayDateString();
+	const metadata = {
+		commitId,
+		lastChecked: dateStr,
+		date: dateObj
+	};
+	fs.mkdirSync(cacheDir, { recursive: true });
+	const metaPath = path.join(cacheDir, METADATA_FILENAME);
+	const tempMetaPath = path.join(os.tmpdir(), `.metadata-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`);
+	try {
+		fs.writeFileSync(tempMetaPath, JSON.stringify(metadata, null, 2), "utf-8");
+		fs.copyFileSync(tempMetaPath, metaPath);
+	} finally {
+		try {
+			if (fs.existsSync(tempMetaPath)) fs.unlinkSync(tempMetaPath);
+		} catch (err) {
+			logger.warn(`Failed to clean up temporary metadata file ${tempMetaPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	return metadata;
+}
+//#endregion
+//#region src/annotations-download.ts
+const DOCGEN_REPO = "nanos-world/vscode-extension";
+const DOCGEN_BRANCH = "docgen-output";
+const RAW_ANNOTATIONS_URL = "https://raw.githubusercontent.com/nanos-world/vscode-extension/refs/heads/docgen-output/annotations.lua";
+const GITHUB_COMMITS_API = "https://api.github.com/repos/nanos-world/vscode-extension/commits/docgen-output";
+/** Reads an HTTP response body with an upper byte limit to guard against memory exhaustion. */
+async function readBoundedResponseBody(res, maxBytes, onExceeded) {
+	const lengthHeader = res.headers?.get?.("content-length");
+	if (lengthHeader) {
+		const declared = parseInt(lengthHeader, 10);
+		if (!isNaN(declared) && declared > maxBytes) {
+			if (typeof res.body?.cancel === "function") await res.body.cancel().catch(() => {});
+			onExceeded(declared, "header");
+			return null;
+		}
+	}
+	if (res.body && typeof res.body[Symbol.asyncIterator] === "function") {
+		let total = 0;
+		const chunks = [];
+		for await (const chunk of res.body) {
+			const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			total += buf.length;
+			if (total > maxBytes) {
+				if (typeof res.body.cancel === "function") await res.body.cancel().catch(() => {});
+				onExceeded(total, "stream");
+				return null;
+			}
+			chunks.push(buf);
+		}
+		return Buffer.concat(chunks).toString("utf-8");
+	}
+	if (typeof res.text === "function") {
+		const text = await res.text();
+		const len = Buffer.byteLength(text, "utf-8");
+		if (len > maxBytes) {
+			onExceeded(len, "stream");
+			return null;
+		}
+		return text;
+	}
+	return "";
+}
+/** Fetches the latest commit SHA for the annotations branch from the GitHub API. */
 async function fetchLatestCommitId() {
 	try {
 		const headers = { "User-Agent": "nanos-lint" };
@@ -8846,7 +9031,17 @@ async function fetchLatestCommitId() {
 			signal: AbortSignal.timeout(5e3)
 		});
 		if (res.ok) {
-			const data = await res.json();
+			const rawJson = await readBoundedResponseBody(res, MAX_COMMIT_JSON_SIZE_BYTES, (bytes) => {
+				logger.warn(`GitHub commits response exceeded size limit of ${MAX_COMMIT_JSON_SIZE_BYTES} bytes (${bytes} bytes)`);
+			});
+			if (rawJson === null) return null;
+			if (!rawJson && !res.bodyUsed && typeof res.json === "function") {
+				const data = await res.json();
+				if (typeof data.sha === "string" && /^[0-9a-fA-F]{7,40}$/.test(data.sha)) return data.sha;
+				return null;
+			}
+			if (!rawJson) return null;
+			const data = JSON.parse(rawJson);
 			if (typeof data.sha === "string" && /^[0-9a-fA-F]{7,40}$/.test(data.sha)) return data.sha;
 		}
 	} catch (err) {
@@ -8854,13 +9049,12 @@ async function fetchLatestCommitId() {
 	}
 	return null;
 }
-/**
-* Returns raw annotations URL, pinned to commit SHA if provided and valid.
-*/
+/** Returns raw annotations URL, pinned to commit SHA if provided and valid. */
 function getRawAnnotationsUrl(commitSha) {
 	if (commitSha && /^[0-9a-fA-F]{7,40}$/.test(commitSha)) return `https://raw.githubusercontent.com/${DOCGEN_REPO}/${commitSha}/annotations.lua`;
 	return RAW_ANNOTATIONS_URL;
 }
+/** Downloads raw annotations.lua content from GitHub raw content endpoints. */
 async function fetchRawAnnotationsContent(commitSha) {
 	const url = getRawAnnotationsUrl(commitSha);
 	const res = await fetch(url, {
@@ -8868,10 +9062,13 @@ async function fetchRawAnnotationsContent(commitSha) {
 		signal: AbortSignal.timeout(15e3)
 	});
 	if (!res.ok) throw new AnnotationsError(`Failed to download annotations.lua: ${res.status} ${res.statusText}`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify your internet connection and that GitHub raw endpoints are accessible.");
-	const text = await res.text();
+	const text = await readBoundedResponseBody(res, MAX_ANNOTATIONS_SIZE_BYTES, (bytes, reason) => {
+		throw new AnnotationsError(reason === "header" ? `Annotations file size (${bytes} bytes) exceeds maximum limit (${MAX_ANNOTATIONS_SIZE_BYTES} bytes)` : `Annotations file download exceeded maximum allowed size of ${MAX_ANNOTATIONS_SIZE_BYTES} bytes`, "ERR_ANNOTATIONS_TOO_LARGE", "Specify a local annotations file via --annotations <path>.");
+	});
 	if (!text || text.length < 1e3) throw new AnnotationsError("Downloaded annotations.lua appears truncated or invalid", "ERR_ANNOTATIONS_INVALID", "Retry downloading or pass a local annotations file via --annotations <path>.");
 	return text;
 }
+/** Copies a file with exponential backoff retries to handle transient file lock contention. */
 async function copyFileWithRetry(src, dest, maxRetries = 10) {
 	for (let attempt = 0; attempt < maxRetries; attempt++) try {
 		fs.copyFileSync(src, dest);
@@ -8885,35 +9082,7 @@ async function copyFileWithRetry(src, dest, maxRetries = 10) {
 		throw err;
 	}
 }
-/**
-* Updates the metadata lastChecked date atomically without modifying annotations.lua.
-*/
-function updateLastCheckedDate(commitId, cacheDir = getAnnotationsCacheDir()) {
-	const { dateStr, dateObj } = getTodayDateString();
-	const metadata = {
-		commitId,
-		lastChecked: dateStr,
-		date: dateObj
-	};
-	fs.mkdirSync(cacheDir, { recursive: true });
-	const metaPath = path.join(cacheDir, METADATA_FILENAME);
-	const tempMetaPath = path.join(os.tmpdir(), `.metadata-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`);
-	try {
-		fs.writeFileSync(tempMetaPath, JSON.stringify(metadata, null, 2), "utf-8");
-		fs.copyFileSync(tempMetaPath, metaPath);
-	} finally {
-		try {
-			if (fs.existsSync(tempMetaPath)) fs.unlinkSync(tempMetaPath);
-		} catch (err) {
-			logger.warn(`Failed to clean up temporary metadata file ${tempMetaPath}: ${err instanceof Error ? err.message : String(err)}`);
-		}
-	}
-	return metadata;
-}
-/**
-* Downloads annotations.lua, writes it and the new metadata in a chained atomic transaction.
-* If any step fails, the previous cache state is reverted.
-*/
+/** Downloads annotations.lua and writes metadata in a chained atomic transaction with rollback. */
 async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCacheDir(), options) {
 	fs.mkdirSync(cacheDir, { recursive: true });
 	const finalAnnotationsPath = path.join(cacheDir, ANNOTATIONS_FILENAME);
@@ -8924,8 +9093,8 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 	try {
 		fs.mkdirSync(tempDir, { recursive: true });
 		if (!options?.quiet) {
-			if (commitId && commitId !== "unknown") logger.info(`[annotations] Downloading nanos world API annotations (${commitId.slice(0, 7)})...`);
-			else logger.info("[annotations] Downloading nanos world API annotations...");
+			const label = commitId && commitId !== "unknown" ? ` (${commitId.slice(0, 7)})` : "";
+			logger.info(`[annotations] Downloading nanos world API annotations${label}...`);
 		}
 		const content = await fetchRawAnnotationsContent(commitId);
 		const tempAnnotationsPath = path.join(tempDir, ANNOTATIONS_FILENAME);
@@ -8951,16 +9120,16 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 		await copyFileWithRetry(tempAnnotationsPath, finalAnnotationsPath);
 		await copyFileWithRetry(tempMetaPath, finalMetaPath);
 		if (!options?.quiet) {
-			if (commitId && commitId !== "unknown") logger.info(`[annotations] Updated annotations.lua to commit ${commitId.slice(0, 7)}.`);
-			else logger.info("[annotations] Updated annotations.lua.");
+			const label = commitId && commitId !== "unknown" ? ` to commit ${commitId.slice(0, 7)}` : "";
+			logger.info(`[annotations] Updated annotations.lua${label}.`);
 		}
 		return finalAnnotationsPath;
 	} catch (err) {
 		if (hasBackup && fs.existsSync(backupDir)) try {
-			const backupAnnotations = path.join(backupDir, ANNOTATIONS_FILENAME);
-			const backupMeta = path.join(backupDir, METADATA_FILENAME);
-			if (fs.existsSync(backupAnnotations)) await copyFileWithRetry(backupAnnotations, finalAnnotationsPath);
-			if (fs.existsSync(backupMeta)) await copyFileWithRetry(backupMeta, finalMetaPath);
+			const bAnn = path.join(backupDir, ANNOTATIONS_FILENAME);
+			const bMeta = path.join(backupDir, METADATA_FILENAME);
+			if (fs.existsSync(bAnn)) await copyFileWithRetry(bAnn, finalAnnotationsPath);
+			if (fs.existsSync(bMeta)) await copyFileWithRetry(bMeta, finalMetaPath);
 		} catch (rollbackErr) {
 			logger.error(`Failed to restore annotations from backup during rollback: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`);
 		}
@@ -8980,21 +9149,28 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 		}
 	}
 }
+//#endregion
+//#region src/annotations.ts
+/** Validates that a user-supplied or environment-specified annotations path exists and is a valid file. */
 function validateCustomAnnotationsPath(filePath, source) {
 	const resolved = path.resolve(filePath);
-	if (!fs.existsSync(resolved)) {
-		if (source === "custom") throw new AnnotationsError(`Custom annotations file not found: ${resolved}`, "ERR_ANNOTATIONS_NOT_FOUND", "Verify that the path specified in --annotations exists and is accessible.");
-		else throw new AnnotationsError(`Annotations file specified in environment not found: ${resolved}`, "ERR_ANNOTATIONS_ENV_NOT_FOUND", "Verify that the path specified in NANOS_ANNOTATIONS_PATH or NANOS_ANNOTATIONS exists.");
-	}
+	const isCustom = source === "custom";
+	const targetDesc = isCustom ? "path specified in --annotations" : "path specified in NANOS_ANNOTATIONS_PATH or NANOS_ANNOTATIONS";
+	if (!fs.existsSync(resolved)) throw new AnnotationsError(isCustom ? `Custom annotations file not found: ${resolved}` : `Annotations file specified in environment not found: ${resolved}`, isCustom ? "ERR_ANNOTATIONS_NOT_FOUND" : "ERR_ANNOTATIONS_ENV_NOT_FOUND", `Verify that the ${targetDesc} exists and is accessible.`);
 	const stat = fs.statSync(resolved);
-	if (!stat.isFile()) throw new AnnotationsError(source === "custom" ? `Custom annotations path is not a file: ${resolved}` : `Annotations path specified in environment is not a file: ${resolved}`, "ERR_ANNOTATIONS_NOT_A_FILE", source === "custom" ? "Verify that the path specified in --annotations points to a regular file, not a directory." : "Verify that the path specified in NANOS_ANNOTATIONS_PATH or NANOS_ANNOTATIONS points to a regular file, not a directory.");
-	if (stat.size === 0) throw new AnnotationsError(source === "custom" ? `Custom annotations file is empty: ${resolved}` : `Annotations file specified in environment is empty: ${resolved}`, "ERR_ANNOTATIONS_INVALID", source === "custom" ? "Verify that the path specified in --annotations is a valid non-empty Lua annotations file." : "Verify that the path specified in NANOS_ANNOTATIONS_PATH or NANOS_ANNOTATIONS is a valid non-empty Lua annotations file.");
+	if (!stat.isFile()) throw new AnnotationsError(isCustom ? `Custom annotations path is not a file: ${resolved}` : `Annotations path specified in environment is not a file: ${resolved}`, "ERR_ANNOTATIONS_NOT_A_FILE", `Verify that the ${targetDesc} points to a regular file, not a directory.`);
+	if (stat.size === 0) throw new AnnotationsError(isCustom ? `Custom annotations file is empty: ${resolved}` : `Annotations file specified in environment is empty: ${resolved}`, "ERR_ANNOTATIONS_INVALID", `Verify that the ${targetDesc} is a valid non-empty Lua annotations file.`);
 	try {
 		const fd = fs.openSync(resolved, "r");
-		const buffer = Buffer.alloc(Math.min(stat.size, 512));
-		const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
-		fs.closeSync(fd);
-		if (buffer.subarray(0, bytesRead).includes(0)) throw new AnnotationsError(source === "custom" ? `Custom annotations file appears to be a binary file: ${resolved}` : `Annotations file specified in environment appears to be a binary file: ${resolved}`, "ERR_ANNOTATIONS_INVALID", "Verify that the annotations file is a valid Lua text annotations file.");
+		let isBinary = false;
+		try {
+			const buffer = Buffer.alloc(Math.min(stat.size, 512));
+			const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
+			isBinary = buffer.subarray(0, bytesRead).includes(0);
+		} finally {
+			fs.closeSync(fd);
+		}
+		if (isBinary) throw new AnnotationsError(isCustom ? `Custom annotations file appears to be a binary file: ${resolved}` : `Annotations file specified in environment appears to be a binary file: ${resolved}`, "ERR_ANNOTATIONS_INVALID", "Verify that the annotations file is a valid Lua text annotations file.");
 	} catch (err) {
 		if (err instanceof AnnotationsError) throw err;
 	}
@@ -9063,6 +9239,7 @@ async function resolveAnnotations(options = {}) {
 }
 //#endregion
 //#region src/cache-status.ts
+/** Collects detailed status and disk usage information for LuaLS and annotations caches. */
 function getCacheStatus(baseCacheDir = systemPaths.cache) {
 	const totalSize = getDirectorySize(baseCacheDir);
 	const totalSizeFormatted = formatBytes(totalSize);
@@ -9120,6 +9297,7 @@ function getCacheStatus(baseCacheDir = systemPaths.cache) {
 		}
 	};
 }
+/** Formats a cache status report into human-readable terminal output. */
 function formatCacheStatusPretty(report) {
 	const lines = [];
 	lines.push("nanos-lint Cache Status");
@@ -9154,6 +9332,7 @@ function formatCacheStatusPretty(report) {
 }
 //#endregion
 //#region src/cli.ts
+/** Retrieves the formatted package name and version string from package.json. */
 function getVersionString() {
 	const root = getPackageRoot();
 	try {
@@ -9167,10 +9346,12 @@ function getVersionString() {
 function writeOutput(message) {
 	if (logger.isOutputEnabled()) console.log(message);
 }
+/** Accumulates repeatable --ignore pattern arguments, splitting by comma and newline. */
 function collectIgnorePatterns(val, prev) {
 	const parts = val.split(/[\r\n,]+/).map((s) => s.trim()).filter(Boolean);
 	return (prev ?? []).concat(parts);
 }
+/** Constructs and configures the top-level Commander program and its CLI subcommands. */
 function createProgram(options) {
 	const setExitCode = options?.setExitCode ?? (() => {});
 	const program = new Command("nanos-lint");
@@ -9319,6 +9500,7 @@ Examples:
 `);
 	return program;
 }
+/** Parses command-line arguments and executes the requested CLI action. */
 async function runCLI(args = process.argv.slice(2)) {
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
@@ -9355,6 +9537,7 @@ async function runCLI(args = process.argv.slice(2)) {
 		return 1;
 	}
 }
+/** Determines whether the current module is being directly executed as an application entrypoint. */
 function isDirectExecution(importMetaUrl = import.meta.url, argv1 = process.argv[1]) {
 	if (!argv1) return false;
 	const toPath = (urlStr) => {
@@ -9391,6 +9574,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { listCachedLuaLSVersionDirs as $, formatSeverityBadge as A, NanosLintError as At, computeFileSha256 as B, isValidLogLevel as Bt, readAnnotationsMetadata as C, resolveWorkspaceConfig as Ct, formatPretty as D, CacheError as Dt, formatGitHubAnnotations as E, AnnotationsError as Et, runLuaLSCheck as F, fileUriToPath as Ft, LUALS_METADATA_FILENAME as G, escapePowerShellSingleQuote as H, parseLogLevel as Ht, countCheckedFiles as I, DEFAULT_LOG_LEVEL as It, getBaseLuaLSCacheDir as J, cleanupOldCachedLuaLSVersions as K, ALLOWED_DOWNLOAD_DOMAINS as L, LOG_LEVELS as Lt, pluralize as M, formatBytes as Mt, shouldEnableColor as N, getDirectorySize as Nt, formatProblemSummary as O, ConfigError as Ot, resolveLuaLSBinary as P, systemPaths as Pt, getLuaLSMetadataPath as Q, DOWNLOAD_TIMEOUT_MS as R, LOG_LEVEL_PRIORITY as Rt, isAnnotationsValid as S, parseJsonc as St, updateLastCheckedDate as T, stripTrailingSlashes as Tt, isAllowedDownloadUrl as U, downloadAndExtractLuaLS as V, logger as Vt, limitDownloadStream as W, getIsoWeek as X, getCacheDir as Y, getLegacyCacheDir as Z, getAnnotationsCacheDir as _, getDefinitionsDir as _t, formatCacheStatusPretty as a, isBinaryRunnable as at, getRawAnnotationsUrl as b, loadConfigFile as bt, DOCGEN_BRANCH as c, DEFAULT_LUALS_VERSION as ct, METADATA_FILENAME as d, resolveLatestLuaLSVersion as dt, listCachedLuaLSVersions as et, MIN_ANNOTATIONS_SIZE_BYTES as f, resolveLuaLSVersion as ft, fetchRawAnnotationsContent as g, getDefaultTemplatePath as gt, fetchLatestCommitId as h, getDefaultAnnotationsPath as ht, runCLI as i, assertValidLuaLSBinary as it, getColors as j, cleanCache as jt, formatReport as k, LuaLSError as kt, DOCGEN_REPO as l, FALLBACK_LUALS_VERSION as lt, downloadAndCacheAnnotations as m, VALID_LUALS_DIAGNOSTIC_CODES as mt, createProgram as n, writeLuaLSMetadata as nt, getCacheStatus as o, isBinaryValid as ot, RAW_ANNOTATIONS_URL as p, sanitizeLuaLSVersion as pt, findExistingLuaLSDir as q, isDirectExecution as r, MIN_DOWNLOADED_BINARY_SIZE_BYTES as rt, ANNOTATIONS_FILENAME as s, getPlatformInfo as st, collectIgnorePatterns as t, readLuaLSMetadata as tt, GITHUB_COMMITS_API as u, fetchLatestLuaLSVersionFromGitHub as ut, getAnnotationsMetadataFilePath as v, getPackageRoot as vt, resolveAnnotations as w, stripJsonComments as wt, getTodayDateString as x, mergeConfigs as xt, getCachedAnnotationsFilePath as y, initWorkspace as yt, MAX_ARCHIVE_SIZE_BYTES as z, Logger as zt };
+export { getLuaLSMetadataPath as $, formatProblemSummary as A, loadConfigFile as At, DOWNLOAD_TIMEOUT_MS as B, NanosLintError as Bt, getCachedAnnotationsFilePath as C, sanitizeLuaLSVersion as Ct, updateLastCheckedDate as D, getDefinitionsDir as Dt, readAnnotationsMetadata as E, getDefaultTemplatePath as Et, shouldEnableColor as F, stripTrailingSlashes as Ft, limitDownloadStream as G, fileUriToPath as Gt, computeFileSha256 as H, formatBytes as Ht, resolveLuaLSBinary as I, AnnotationsError as It, findExistingLuaLSDir as J, LOG_LEVEL_PRIORITY as Jt, LUALS_METADATA_FILENAME as K, DEFAULT_LOG_LEVEL as Kt, runLuaLSCheck as L, CacheError as Lt, formatSeverityBadge as M, parseJsonc as Mt, getColors as N, resolveWorkspaceConfig as Nt, formatGitHubAnnotations as O, getPackageRoot as Ot, pluralize as P, stripJsonComments as Pt, getLegacyCacheDir as Q, parseLogLevel as Qt, countCheckedFiles as R, ConfigError as Rt, getAnnotationsMetadataFilePath as S, resolveLuaLSVersion as St, isAnnotationsValid as T, getDefaultAnnotationsPath as Tt, downloadAndExtractLuaLS as U, getDirectorySize as Ut, MAX_ARCHIVE_SIZE_BYTES as V, cleanCache as Vt, isAllowedDownloadUrl as W, systemPaths as Wt, getCacheDir as X, isValidLogLevel as Xt, getBaseLuaLSCacheDir as Y, Logger as Yt, getIsoWeek as Z, logger as Zt, MAX_ANNOTATIONS_SIZE_BYTES as _, getPlatformInfo as _t, formatCacheStatusPretty as a, MAX_DECOMPRESSED_SIZE_BYTES as at, MIN_ANNOTATIONS_SIZE_BYTES as b, fetchLatestLuaLSVersionFromGitHub as bt, DOCGEN_BRANCH as c, escapePowerShellSingleQuote as ct, RAW_ANNOTATIONS_URL as d, isBinaryRunnable as dt, listCachedLuaLSVersionDirs as et, downloadAndCacheAnnotations as f, isBinaryValid as ft, ANNOTATIONS_FILENAME as g, validateArchiveMembers as gt, getRawAnnotationsUrl as h, parseTarTvSize as ht, runCLI as i, MAX_ARCHIVE_MEMBER_COUNT as it, formatReport as j, mergeConfigs as jt, formatPretty as k, initWorkspace as kt, DOCGEN_REPO as l, getTarBinary as lt, fetchRawAnnotationsContent as m, isZipArchive as mt, createProgram as n, readLuaLSMetadata as nt, getCacheStatus as o, MIN_DOWNLOADED_BINARY_SIZE_BYTES as ot, fetchLatestCommitId as p, isGzipArchive as pt, cleanupOldCachedLuaLSVersions as q, LOG_LEVELS as qt, isDirectExecution as r, writeLuaLSMetadata as rt, resolveAnnotations as s, assertValidLuaLSBinary as st, collectIgnorePatterns as t, listCachedLuaLSVersions as tt, GITHUB_COMMITS_API as u, inspectZipMembers as ut, MAX_COMMIT_JSON_SIZE_BYTES as v, DEFAULT_LUALS_VERSION as vt, getTodayDateString as w, VALID_LUALS_DIAGNOSTIC_CODES as wt, getAnnotationsCacheDir as x, resolveLatestLuaLSVersion as xt, METADATA_FILENAME as y, FALLBACK_LUALS_VERSION as yt, ALLOWED_DOWNLOAD_DOMAINS as z, LuaLSError as zt };
 
-//# sourceMappingURL=cli-BAy_Ztvh.js.map
+//# sourceMappingURL=cli-BTHx4yp_.js.map