nanos-lint 3.0.1 → 3.2.0

package/dist/{cli-B9EpAClV.js → cli-CeNxOiST.js}

@@ -41,6 +41,7 @@ function parseLogLevel(raw) {
 }
 var Logger = class {
 	level = DEFAULT_LOG_LEVEL;
+	diagnosticStream = "stdout";
 	constructor(initialLevel) {
 		if (initialLevel && isValidLogLevel(initialLevel)) this.level = initialLevel;
 		else {
@@ -56,6 +57,17 @@ var Logger = class {
 	getLevel() {
 		return this.level;
 	}
+	/**
+	* Selects the stream used by `info`/`debug`. Machine-readable formats switch this to
+	* `stderr`, so a report on stdout is never interleaved with diagnostic lines.
+	*/
+	setDiagnosticStream(stream) {
+		this.diagnosticStream = stream;
+	}
+	/** Returns the stream used by `info`/`debug`. */
+	getDiagnosticStream() {
+		return this.diagnosticStream;
+	}
 	/** Checks if a message at the specified level should be emitted. */
 	isEnabledFor(level) {
 		return LOG_LEVEL_PRIORITY[this.level] >= LOG_LEVEL_PRIORITY[level];
@@ -72,13 +84,22 @@ var Logger = class {
 	warn(...args) {
 		if (this.isEnabledFor("warn")) console.warn(...args);
 	}
-	/** Logs an informational message to stdout. */
+	/** Logs an informational message to stdout, or to stderr when stdout carries a report. */
 	info(...args) {
-		if (this.isEnabledFor("info")) console.log(...args);
+		if (this.isEnabledFor("info")) this.emitDiagnostic(args, "log");
 	}
-	/** Logs a debug-level diagnostic message to stdout. */
+	/** Logs a debug-level diagnostic message to stdout, or to stderr when stdout carries a report. */
 	debug(...args) {
-		if (this.isEnabledFor("debug")) console.debug(...args);
+		if (this.isEnabledFor("debug")) this.emitDiagnostic(args, "debug");
+	}
+	/** Writes an `info`/`debug` diagnostic on the configured stream. */
+	emitDiagnostic(args, stdoutMethod) {
+		if (this.diagnosticStream === "stderr") {
+			console.error(...args);
+			return;
+		}
+		if (stdoutMethod === "debug") console.debug(...args);
+		else console.log(...args);
 	}
 };
 const logger = new Logger();
@@ -1186,10 +1207,12 @@ function mergeConfigs(base, override = {}, definitionsPath = getDefaultAnnotatio
 	const normalizedDefPath = resolvedPath.split(path.sep).join("/");
 	const baseLibraries = base.workspace?.library ?? [];
 	const overrideLibraries = override.workspace?.library ?? [];
+	const depLibraries = (options?.dependencyLibraries ?? []).map((p) => p.replace(/\\/g, "/"));
 	const librarySet = /* @__PURE__ */ new Set([
 		normalizedDefPath,
 		...baseLibraries,
-		...overrideLibraries
+		...overrideLibraries,
+		...depLibraries
 	]);
 	const baseGlobals = base.diagnostics?.globals ?? [];
 	const overrideGlobals = override.diagnostics?.globals ?? [];
@@ -1328,7 +1351,10 @@ function buildWorkspaceConfig(workspacePath, customConfigPath, options) {
 		}
 		cliIgnore = expanded;
 	}
-	const merged = mergeConfigs(defaultTemplate, userConfig, activeAnnotationsPath, { cliIgnore });
+	const merged = mergeConfigs(defaultTemplate, userConfig, activeAnnotationsPath, {
+		cliIgnore,
+		dependencyLibraries: options?.dependencyLibraries
+	});
 	if (!hasCliIgnore) {
 		const resolvedTarget = path.resolve(workspacePath);
 		if (fs.existsSync(path.join(resolvedTarget, "main.lua")) && (fs.existsSync(path.join(resolvedTarget, "bin", "lua-language-server.exe")) || fs.existsSync(path.join(resolvedTarget, "bin", "lua-language-server")))) {
@@ -1343,6 +1369,11 @@ function buildWorkspaceConfig(workspacePath, customConfigPath, options) {
 			])];
 		}
 	}
+	if (options?.unrequestedExclusions && options.unrequestedExclusions.length > 0) {
+		merged.files = merged.files ?? {};
+		const existingExclude = merged.files.exclude ?? [];
+		merged.files.exclude = [.../* @__PURE__ */ new Set([...existingExclude, ...options.unrequestedExclusions])];
+	}
 	return merged;
 }
 /**
@@ -5046,6 +5077,294 @@ async function writeAtomicFile(targetPath, data, options = {}) {
 	}
 }
 //#endregion
+//#region src/terminal-progress.ts
+/** Minimum delay between two terminal redraws (about ten frames per second). */
+const PROGRESS_THROTTLE_MS = 100;
+/** Braille frames cycled while an indeterminate operation runs. */
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** Fractions of a transfer logged as milestones when no terminal can be redrawn. */
+const PROGRESS_MILESTONES = [
+	.25,
+	.5,
+	.75
+];
+const CURSOR_HIDE = "\x1B[?25l";
+const CURSOR_SHOW = "\x1B[?25h";
+const CLEAR_LINE = "\r\x1B[2K";
+const FRAME_TAIL = "  ";
+const DEFAULT_COLUMNS = 80;
+const MIN_BAR_WIDTH = 8;
+const MAX_BAR_WIDTH = 28;
+const TRUNCATION = "...";
+let progressMode = "auto";
+let cursorHidden = false;
+let guardsInstalled = false;
+let activeDynamicRenders = 0;
+/** Sets the redraw policy used by every progress display created afterwards. */
+function setProgressMode(mode) {
+	progressMode = mode;
+}
+/** Returns the current redraw policy. */
+function getProgressMode() {
+	return progressMode;
+}
+/** Returns whether an environment value is set to anything but an explicit false. */
+function isEnvFlagSet(value) {
+	if (value === void 0) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no" && normalized !== "off";
+}
+/**
+* Returns whether dynamic redrawing is allowed for the given environment and terminal.
+* Non-interactive environments get single-line milestones instead of carriage returns.
+*/
+function isProgressInteractive(env = process.env, isTTY = process.stderr.isTTY) {
+	if (progressMode === "off" || !logger.isOutputEnabled() || !isTTY) return false;
+	if ((env.TERM ?? "").trim().toLowerCase() === "dumb") return false;
+	return !(isEnvFlagSet(env.CI) || isEnvFlagSet(env.NO_COLOR) || isEnvFlagSet(env.NANOS_NO_PROGRESS));
+}
+/** Writes a control sequence straight to file descriptor 2, tolerating a closed stderr. */
+function writeToStderr(sequence) {
+	try {
+		fs.writeSync(2, sequence);
+	} catch (err) {}
+}
+/**
+* Writes a progress line to stderr, so stdout keeps carrying only the command report.
+*
+* Without a terminal the displays fall back to these discrete milestones, which are just as
+* much part of the progress display as an in-place redraw and therefore share its stream.
+*/
+function logProgressLine(message) {
+	if (logger.isEnabledFor("info")) console.error(message);
+}
+/** Writes a settle message on the stream matching its severity. */
+function logSettle(message, level) {
+	if (level === "warn") {
+		logger.warn(message);
+		return;
+	}
+	logProgressLine(message);
+}
+/** Restores the cursor and abandons the active progress line; safe to call at any time. */
+function restoreTerminal() {
+	if (!cursorHidden) return;
+	cursorHidden = false;
+	writeToStderr(`${CLEAR_LINE}${CURSOR_SHOW}`);
+}
+/** Restores the cursor, then re-raises the signal with the default disposition. */
+function handleTerminationSignal(signal) {
+	restoreTerminal();
+	removeTerminalGuards();
+	process.kill(process.pid, signal);
+}
+/** Installs exit, crash and signal hooks so a hidden cursor is always restored. */
+function installTerminalGuards() {
+	if (guardsInstalled) return;
+	guardsInstalled = true;
+	process.on("exit", restoreTerminal);
+	process.on("uncaughtExceptionMonitor", restoreTerminal);
+	process.on("SIGINT", handleTerminationSignal);
+	process.on("SIGTERM", handleTerminationSignal);
+}
+/** Removes the cursor guards once no dynamic render is active. */
+function removeTerminalGuards() {
+	if (!guardsInstalled) return;
+	guardsInstalled = false;
+	process.off("exit", restoreTerminal);
+	process.off("uncaughtExceptionMonitor", restoreTerminal);
+	process.off("SIGINT", handleTerminationSignal);
+	process.off("SIGTERM", handleTerminationSignal);
+}
+/** Builds the mutable rendering state shared by bars and spinners. */
+function createRenderState(options) {
+	const stream = options.stream ?? process.stderr;
+	const now = options.now ?? Date.now;
+	return {
+		stream,
+		interactive: options.interactive ?? isProgressInteractive(process.env, stream.isTTY),
+		ownsProcessStderr: options.stream === void 0,
+		label: options.label,
+		now,
+		throttleMs: Math.max(1, options.throttleMs ?? 100),
+		startedAt: now(),
+		lastFrameAt: Number.NEGATIVE_INFINITY,
+		active: false
+	};
+}
+/** Truncates a frame so it never wraps onto a second terminal line. */
+function fitToWidth(state, line) {
+	const limit = Math.max(1, (state.stream.columns ?? DEFAULT_COLUMNS) - 1);
+	if (line.length <= limit) return line;
+	if (limit <= 3) return TRUNCATION.slice(0, limit);
+	return `${line.slice(0, limit - 3)}${TRUNCATION}`;
+}
+/** Hides the cursor and arms the exit guards when a dynamic render starts. */
+function beginFrame(state) {
+	if (state.active) return;
+	state.active = true;
+	if (!state.ownsProcessStderr) {
+		state.stream.write(CURSOR_HIDE);
+		return;
+	}
+	activeDynamicRenders += 1;
+	if (activeDynamicRenders > 1) return;
+	cursorHidden = true;
+	installTerminalGuards();
+	state.stream.write(CURSOR_HIDE);
+}
+/** Clears the dynamic line and reveals the cursor once the render stops. */
+function endFrame(state) {
+	if (!state.interactive || !state.active) return;
+	state.active = false;
+	state.stream.write(CLEAR_LINE);
+	if (!state.ownsProcessStderr) {
+		state.stream.write(CURSOR_SHOW);
+		return;
+	}
+	activeDynamicRenders = Math.max(0, activeDynamicRenders - 1);
+	if (activeDynamicRenders === 0) {
+		cursorHidden = false;
+		removeTerminalGuards();
+		state.stream.write(CURSOR_SHOW);
+	}
+}
+/** Draws one frame, throttled unless `force`d, replacing whatever the line held. */
+function drawFrame(state, line, force = false) {
+	if (!state.interactive) return;
+	const now = state.now();
+	if (!force && now - state.lastFrameAt < state.throttleMs) return;
+	state.lastFrameAt = now;
+	beginFrame(state);
+	state.stream.write(`${CLEAR_LINE}${fitToWidth(state, line)}${FRAME_TAIL}`);
+}
+/** Formats a duration in milliseconds as seconds. */
+function formatDuration(ms) {
+	const seconds = Math.max(0, ms) / 1e3;
+	return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+/** Formats a completed transfer as size, duration and average speed. */
+function formatTransferSummary(bytes, elapsedMs) {
+	const elapsed = Math.max(elapsedMs, 1);
+	return `${formatBytes(bytes)} in ${formatDuration(elapsed)} (${formatBytes(bytes / (elapsed / 1e3))}/s)`;
+}
+/** Builds the `[====>   ]` fill for a completion ratio. */
+function buildBar(ratio, width) {
+	const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+	if (filled >= width) return "=".repeat(width);
+	return `${"=".repeat(filled)}>${" ".repeat(width - filled - 1)}`;
+}
+/** Picks a bar width that keeps the whole frame inside the terminal. */
+function barWidthFor(state, reserved) {
+	const columns = state.stream.columns ?? DEFAULT_COLUMNS;
+	return Math.max(MIN_BAR_WIDTH, Math.min(MAX_BAR_WIDTH, columns - reserved));
+}
+/** Renders one deterministic transfer frame. */
+function renderBarFrame(state, transferred, total) {
+	const elapsedMs = state.now() - state.startedAt;
+	const speed = transferred / (Math.max(elapsedMs, 1) / 1e3);
+	const speedText = `${formatBytes(speed)}/s`;
+	if (!total || total <= 0) return `${state.label} ${formatBytes(transferred)} (${speedText}, ${formatDuration(elapsedMs)})`;
+	const ratio = Math.max(0, Math.min(1, transferred / total));
+	const percent = Math.floor(ratio * 100);
+	const eta = speed > 0 && transferred < total ? `, ETA ${formatDuration((total - transferred) / speed * 1e3)}` : "";
+	const tail = ` ${percent}% (${formatBytes(transferred)} / ${formatBytes(total)}, ${speedText}${eta})`;
+	const width = barWidthFor(state, state.label.length + tail.length + 2 + 4);
+	return `${state.label} [${buildBar(ratio, width)}]${tail}`;
+}
+/** Renders one indeterminate spinner frame. */
+function renderSpinnerFrame(state, frame) {
+	const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? "|";
+	return `${state.label} ${glyph} (${formatDuration(state.now() - state.startedAt)})`;
+}
+/** Creates a byte progress bar; without a terminal it logs start, milestones and completion. */
+function createProgressBar(options) {
+	const state = createRenderState(options);
+	let transferred = 0;
+	let total = options.total !== void 0 && options.total > 0 ? options.total : void 0;
+	let milestone = 0;
+	if (!state.interactive && options.announce !== false) logProgressLine(`${state.label}${total ? ` (${formatBytes(total)})` : ""}...`);
+	if (state.interactive) drawFrame(state, renderBarFrame(state, 0, total), true);
+	const settle = (message, level) => {
+		endFrame(state);
+		if (message) logSettle(message, level);
+	};
+	return {
+		update: (next, nextTotal) => {
+			transferred = Math.max(transferred, next);
+			if (nextTotal !== void 0 && nextTotal > 0) total = nextTotal;
+			if (total !== void 0 && transferred > total) total = void 0;
+			if (state.interactive) {
+				drawFrame(state, renderBarFrame(state, transferred, total));
+				return;
+			}
+			if (!total) return;
+			const ratio = transferred / total;
+			while (milestone < PROGRESS_MILESTONES.length && ratio >= (PROGRESS_MILESTONES[milestone] ?? 1)) {
+				const reached = PROGRESS_MILESTONES[milestone] ?? 1;
+				milestone += 1;
+				logProgressLine(`${state.label}: ${Math.round(reached * 100)}% (${formatBytes(transferred)} / ${formatBytes(total)})`);
+			}
+		},
+		finish: (message) => settle(message, "info"),
+		fail: (message) => settle(message, "warn")
+	};
+}
+/** Creates an indeterminate spinner driven by a timer and by manual ticks from sync loops. */
+function createSpinner(options) {
+	const state = createRenderState(options);
+	let frame = 0;
+	let timer;
+	const clearTimer = () => {
+		if (timer !== void 0) {
+			clearInterval(timer);
+			timer = void 0;
+		}
+	};
+	const settle = (message, level) => {
+		clearTimer();
+		endFrame(state);
+		if (message) logSettle(message, level);
+	};
+	return {
+		start: () => {
+			if (!state.interactive) {
+				if (options.announce !== false) logProgressLine(`${state.label}...`);
+				return;
+			}
+			drawFrame(state, renderSpinnerFrame(state, frame), true);
+			if (timer === void 0) {
+				timer = setInterval(() => {
+					frame += 1;
+					drawFrame(state, renderSpinnerFrame(state, frame), true);
+				}, state.throttleMs);
+				timer.unref();
+			}
+		},
+		tick: () => {
+			frame += 1;
+			drawFrame(state, renderSpinnerFrame(state, frame));
+		},
+		updateText: (label) => {
+			state.label = label;
+			drawFrame(state, renderSpinnerFrame(state, frame), true);
+		},
+		stop: (message) => settle(message, "info"),
+		fail: (message) => settle(message, "warn")
+	};
+}
+//#endregion
 //#region src/annotations-realms.ts
 /** Side markers emitted by the upstream docgen, mapped to the realm that owns them. */
 const SIDE_MARKERS = [
@@ -5055,6 +5374,8 @@ const SIDE_MARKERS = [
 	["authority-only", "shared"],
 	["network-authority", "shared"]
 ];
+/** Number of source lines parsed between two spinner ticks while splitting realms. */
+const PARSE_PROGRESS_STEP_LINES = 2e3;
 /** Finds the realm declared by the side marker of a documentation block. */
 function realmOfDocBlock(doc) {
 	for (const line of doc) for (const [image, realm] of SIDE_MARKERS) if (line.includes(`assets/${image}.png`)) return realm;
@@ -5085,10 +5406,17 @@ function kindOf(declaration) {
 	return "other";
 }
 /** Segments annotations into comment runs plus their optional declaration statement. */
-function parseAnnotationUnits(text) {
+function parseAnnotationUnits(text, onProgress) {
 	const lines = text.split(/\r?\n/);
 	const units = [];
 	let index = 0;
+	let nextTick = PARSE_PROGRESS_STEP_LINES;
+	const tick = () => {
+		if (onProgress !== void 0 && index >= nextTick) {
+			nextTick = index + PARSE_PROGRESS_STEP_LINES;
+			onProgress();
+		}
+	};
 	const push = (doc, decl) => {
 		const first = decl?.[0] ?? null;
 		units.push({
@@ -5102,6 +5430,7 @@ function parseAnnotationUnits(text) {
 		});
 	};
 	while (index < lines.length) {
+		tick();
 		const doc = [];
 		while (index < lines.length && (lines[index].startsWith("---") || lines[index].trim() === "")) {
 			if (lines[index].startsWith("---")) doc.push(lines[index]);
@@ -5200,11 +5529,12 @@ function renderRealm(units, realm) {
 * and a realm-specific class table is dropped from the other realm unless it still has
 * instance members there.
 */
-function splitAnnotationsByRealm(text) {
-	const units = parseAnnotationUnits(text);
+function splitAnnotationsByRealm(text, onProgress) {
+	const units = parseAnnotationUnits(text, onProgress);
 	const classRealms = classRealmsOf(units);
 	const crossRealm = crossRealmClasses(units);
 	const memberRealms = markedMemberRealms(units);
+	onProgress?.();
 	for (const unit of units) {
 		if (unit.owner) {
 			unit.realm = unit.owner;
@@ -5218,8 +5548,11 @@ function splitAnnotationsByRealm(text) {
 		const classRealm = unit.receiver ? classRealms.get(unit.receiver) : void 0;
 		unit.realm = classRealm && classRealm !== "shared" && !crossRealm.has(unit.receiver) ? classRealm : "shared";
 	}
+	onProgress?.();
+	const client = renderRealm(units, "client");
+	onProgress?.();
 	return {
-		client: renderRealm(units, "client"),
+		client,
 		server: renderRealm(units, "server")
 	};
 }
@@ -5249,17 +5582,204 @@ function deriveRealmAnnotationFiles(annotationsPath, cacheDir) {
 		client: clientPath,
 		server: serverPath
 	};
-	const split = splitAnnotationsByRealm(fs.readFileSync(annotationsPath, "utf-8"));
-	fs.mkdirSync(targetDir, { recursive: true });
-	writeAtomicFileSync(clientPath, split.client);
-	writeAtomicFileSync(serverPath, split.server);
-	logger.debug(`[realms] Derived realm annotations in ${targetDir}.`);
+	const spinner = createSpinner({ label: "[realms] Deriving client/server annotations" });
+	spinner.start();
+	try {
+		const split = splitAnnotationsByRealm(fs.readFileSync(annotationsPath, "utf-8"), () => spinner.tick());
+		spinner.updateText("[realms] Writing derived annotations");
+		fs.mkdirSync(targetDir, { recursive: true });
+		writeAtomicFileSync(clientPath, split.client);
+		writeAtomicFileSync(serverPath, split.server);
+		logger.debug(`[realms] Derived realm annotations in ${targetDir}.`);
+		spinner.stop(`[realms] Derived client/server annotations in ${targetDir}.`);
+	} catch (err) {
+		spinner.fail();
+		throw err;
+	}
 	return {
 		client: clientPath,
 		server: serverPath
 	};
 }
 //#endregion
+//#region src/download-guard.ts
+/**
+* Shared transport policy for every outbound download performed by nanos-lint.
+*
+* `SECURITY.md` requires download requests *and* HTTP redirects to use HTTPS and to stay on
+* GitHub infrastructure. Redirects are therefore resolved hop by hop in `"manual"` mode: the
+* default `"follow"` mode contacts the redirect target before any check can run, which would
+* let a redirect downgrade to plaintext `http://` or reach an internal address.
+*/
+const ALLOWED_DOWNLOAD_DOMAINS = ["github.com", "githubusercontent.com"];
+/** Headers that must never follow a redirect to another origin. */
+const CREDENTIAL_HEADERS = [
+	"authorization",
+	"cookie",
+	"proxy-authorization"
+];
+/** Returns the origin of an already validated URL, or null when it cannot be parsed. */
+function originOf(urlString) {
+	try {
+		return new URL(urlString).origin;
+	} catch {
+		return null;
+	}
+}
+/**
+* Returns the caller's headers with credentials removed.
+*
+* The runtime strips `Authorization` when it follows a redirect by itself, so dropping it here
+* keeps that guarantee once the guard re-issues each hop manually instead of following it.
+*/
+function withoutCredentialHeaders(headers) {
+	if (headers === void 0) return;
+	const stripped = new Headers(headers);
+	for (const name of CREDENTIAL_HEADERS) stripped.delete(name);
+	return stripped;
+}
+/** Validates that a URL uses HTTPS and targets an allowlisted GitHub host. */
+function isAllowedDownloadUrl(urlString) {
+	try {
+		const parsed = new URL(urlString);
+		if (parsed.protocol !== "https:") return false;
+		const hostname = parsed.hostname.toLowerCase();
+		return ALLOWED_DOWNLOAD_DOMAINS.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+	} catch {
+		return false;
+	}
+}
+/**
+* Releases a response body without letting cleanup failures mask the block reason.
+*
+* Every failure mode is swallowed on purpose: a missing body, a double that exposes no
+* `cancel()`, and a `cancel()` that rejects or returns a non-promise must all leave the
+* caller free to report why the response was refused.
+*/
+async function cancelResponseBody(res) {
+	try {
+		if (typeof res.body?.cancel === "function") await res.body.cancel();
+	} catch (err) {}
+}
+/** Reads the `Location` header of a redirect response, tolerating minimal test doubles. */
+function getRedirectLocation(res) {
+	if (typeof res.headers?.get !== "function") return null;
+	return res.headers.get("location");
+}
+/**
+* Reads the `content-length` of a response whose bytes are streamed as received.
+*
+* A content-encoded response (`content-encoding: gzip`, `br`, ...) is decoded by the runtime
+* while its `content-length` still counts the compressed payload, so that value describes
+* neither the byte stream a progress bar counts nor the text that reaches the cache. Such a
+* response reports no usable length and progress falls back to transferred bytes and speed.
+*/
+function parseDeclaredContentLength(res) {
+	const encoding = (res.headers?.get?.("content-encoding") ?? "").trim().toLowerCase();
+	if (encoding !== "" && encoding !== "identity") return;
+	const header = res.headers?.get?.("content-length");
+	if (!header) return;
+	const declared = parseInt(header, 10);
+	return Number.isFinite(declared) && declared > 0 ? declared : void 0;
+}
+/** Classifies a response the runtime followed by itself despite `redirect: "manual"`. */
+function isOpaqueRedirect(res) {
+	return res.type === "opaqueredirect";
+}
+/**
+* Performs a fetch with hop-by-hop redirect validation against the allowlist.
+*
+* Each hop must use HTTPS and stay on an allowlisted GitHub host; a hop that does not is never
+* contacted, because `redirect: "manual"` surfaces the 3xx response instead of following it.
+* The final response URL is validated as well, which keeps the policy enforced even on a
+* runtime that ignores `"manual"` and follows redirects on its own.
+*/
+async function guardedFetch(url, init = {}) {
+	if (!isAllowedDownloadUrl(url)) return {
+		ok: false,
+		reason: "disallowed-url",
+		url
+	};
+	let currentUrl = url;
+	let currentInit = init;
+	let followed = 0;
+	const requestOrigin = originOf(url);
+	for (;;) {
+		let response;
+		try {
+			response = await fetch(currentUrl, {
+				...currentInit,
+				redirect: "manual"
+			});
+		} catch (err) {
+			return {
+				ok: false,
+				reason: "network-error",
+				url: currentUrl,
+				error: err
+			};
+		}
+		if (isOpaqueRedirect(response)) {
+			await cancelResponseBody(response);
+			return {
+				ok: false,
+				reason: "disallowed-redirect",
+				url: currentUrl
+			};
+		}
+		if (!(response.status >= 300 && response.status < 400)) {
+			if (response.url && !isAllowedDownloadUrl(response.url)) {
+				await cancelResponseBody(response);
+				return {
+					ok: false,
+					reason: "disallowed-redirect",
+					url: response.url
+				};
+			}
+			return {
+				ok: true,
+				response
+			};
+		}
+		const location = getRedirectLocation(response);
+		if (location === null || location.trim() === "") {
+			await cancelResponseBody(response);
+			return {
+				ok: false,
+				reason: "missing-location",
+				url: currentUrl
+			};
+		}
+		let nextUrl;
+		try {
+			nextUrl = new URL(location, currentUrl).href;
+		} catch (err) {
+			nextUrl = "";
+		}
+		if (!isAllowedDownloadUrl(nextUrl)) {
+			await cancelResponseBody(response);
+			return {
+				ok: false,
+				reason: "disallowed-redirect",
+				url: nextUrl || location
+			};
+		}
+		await cancelResponseBody(response);
+		followed++;
+		if (followed > 5) return {
+			ok: false,
+			reason: "too-many-redirects",
+			url: nextUrl
+		};
+		const nextOrigin = originOf(nextUrl);
+		if (requestOrigin !== null && nextOrigin !== null && nextOrigin !== requestOrigin) currentInit = {
+			...init,
+			headers: withoutCredentialHeaders(init.headers)
+		};
+		currentUrl = nextUrl;
+	}
+}
+//#endregion
 //#region src/luals/version.ts
 const FALLBACK_LUALS_VERSION = "3.19.1";
 const DEFAULT_LUALS_VERSION = "latest";
@@ -5291,10 +5811,15 @@ async function fetchLatestLuaLSVersionFromGitHub() {
 	try {
 		const headers = { "User-Agent": "nanos-lint" };
 		if (process.env.GITHUB_TOKEN) headers["Authorization"] = `token ${process.env.GITHUB_TOKEN}`;
-		const res = await fetch("https://api.github.com/repos/LuaLS/lua-language-server/releases/latest", {
+		const result = await guardedFetch("https://api.github.com/repos/LuaLS/lua-language-server/releases/latest", {
 			headers,
 			signal: AbortSignal.timeout(5e3)
 		});
+		if (!result.ok || !result.response) {
+			if (result.reason && result.reason !== "network-error") logger.warn(`[luals] Refused LuaLS release lookup: requests must stay on allowlisted GitHub infrastructure over HTTPS (${result.url ?? "unknown URL"}).`);
+			return null;
+		}
+		const res = result.response;
 		if (res.ok) {
 			const data = await res.json();
 			const version = typeof data.tag_name === "string" ? sanitizeLuaLSVersion(data.tag_name) : null;
@@ -6090,20 +6615,6 @@ function findExistingLuaLSDir(version, baseCacheDir = getBaseLuaLSCacheDir()) {
 //#region src/luals/download.ts
 const DOWNLOAD_TIMEOUT_MS = 12e4;
 const MAX_ARCHIVE_SIZE_BYTES = 157286400;
-const ALLOWED_DOWNLOAD_DOMAINS = ["github.com", "githubusercontent.com"];
-/**
-* Validates that a download URL uses HTTPS and targets an allowlisted host.
-*/
-function isAllowedDownloadUrl(urlString) {
-	try {
-		const parsed = new URL(urlString);
-		if (parsed.protocol !== "https:") return false;
-		const hostname = parsed.hostname.toLowerCase();
-		return ALLOWED_DOWNLOAD_DOMAINS.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
-	} catch {
-		return false;
-	}
-}
 /** Chunk size used when hashing an archive, so a 150 MB asset is never buffered whole. */
 const HASH_CHUNK_SIZE_BYTES = 1048576;
 /**
@@ -6138,6 +6649,15 @@ async function* limitDownloadStream(source) {
 		yield chunk;
 	}
 }
+/** Reports cumulative transferred bytes while passing a download stream through unchanged. */
+async function* trackDownloadProgress(source, onProgress) {
+	let transferred = 0;
+	for await (const chunk of source) {
+		transferred += chunk.length;
+		onProgress(transferred);
+		yield chunk;
+	}
+}
 /** Returns whether a cache directory holds a complete, executable LuaLS installation. */
 function isCompleteLuaLSInstall(binaryPath, completeMarker, version) {
 	if (!fs.existsSync(binaryPath) || !fs.existsSync(completeMarker)) return false;
@@ -6198,28 +6718,27 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 			logger.info(`[luals] Reusing existing LuaLS ${resolvedVersion} installation from ${existingSourceDir}...`);
 			fs.cpSync(existingSourceDir, tempDir, { recursive: true });
 		} else {
-			if (!isAllowedDownloadUrl(url)) throw new LuaLSError(`Refusing to download LuaLS from untrusted URL: ${url}`, "ERR_LUALS_DOWNLOAD", "Download URLs must use HTTPS and target an allowlisted GitHub host.");
 			logger.info(`[luals] Downloading LuaLS ${resolvedVersion} from ${url}...`);
 			let response = null;
 			let lastErr = null;
 			for (let attempt = 1; attempt <= 3; attempt++) {
 				try {
-					const res = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
-					if (res.url && !isAllowedDownloadUrl(res.url)) {
-						if (typeof res.body?.cancel === "function") try {
-							await res.body.cancel();
-						} catch (cancelErr) {}
-						logger.warn(`[luals] Redirect to untrusted URL blocked: ${res.url}`);
-						throw new LuaLSError(`Redirect to untrusted URL blocked: ${res.url}`, "ERR_LUALS_DOWNLOAD", "Download redirects must stay on allowlisted HTTPS GitHub hosts.");
-					}
-					if (res.ok && res.body) {
-						response = res;
+					const outcome = await guardedFetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+					if (!outcome.ok || !outcome.response) {
+						if (outcome.reason !== "network-error") {
+							const blockedMessage = `Redirect to untrusted URL blocked: ${outcome.url ?? url}`;
+							logger.warn(`[luals] ${blockedMessage}`);
+							throw new LuaLSError(blockedMessage, "ERR_LUALS_DOWNLOAD", "Download redirects must stay on allowlisted HTTPS GitHub hosts.");
+						}
+						lastErr = outcome.error ?? /* @__PURE__ */ new Error(`Failed to download ${url}`);
+					} else if (outcome.response.ok && outcome.response.body) {
+						response = outcome.response;
 						break;
+					} else {
+						const res = outcome.response;
+						await cancelResponseBody(res);
+						lastErr = /* @__PURE__ */ new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
 					}
-					if (typeof res.body?.cancel === "function") try {
-						await res.body.cancel();
-					} catch (cancelErr) {}
-					lastErr = /* @__PURE__ */ new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
 				} catch (err) {
 					if (err instanceof LuaLSError) throw err;
 					lastErr = err;
@@ -6235,50 +6754,76 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 					throw new LuaLSError(`Archive size (${contentLength} bytes) exceeds maximum limit (${MAX_ARCHIVE_SIZE_BYTES} bytes)`, "ERR_LUALS_DOWNLOAD", "Verify the LuaLS release asset size or specify a local binary with LUALS_BIN.");
 				}
 			}
+			const declaredTotal = parseDeclaredContentLength(response);
+			const downloadStartedAt = Date.now();
+			let transferred = 0;
+			const progress = createProgressBar({
+				label: `[luals] Downloading ${info.assetName}`,
+				total: declaredTotal,
+				announce: false
+			});
 			const fileStream = fs.createWriteStream(archivePath);
 			try {
 				const streamSource = typeof Readable.fromWeb === "function" && !("pipe" in response.body) ? Readable.fromWeb(response.body) : response.body;
-				await pipeline(streamSource, limitDownloadStream, fileStream);
+				await pipeline(streamSource, limitDownloadStream, (source) => trackDownloadProgress(source, (bytes) => {
+					transferred = bytes;
+					progress.update(bytes, declaredTotal);
+				}), fileStream);
 			} catch (streamErr) {
+				progress.fail();
 				try {
 					if (fs.existsSync(archivePath)) fs.unlinkSync(archivePath);
 				} catch (unlinkErr) {}
 				if (streamErr instanceof LuaLSError) throw streamErr;
 				throw new LuaLSError(`Failed to download LuaLS from ${url}: ${streamErr instanceof Error ? streamErr.message : String(streamErr)}`, "ERR_LUALS_DOWNLOAD", "Check your network connection or specify a custom binary with LUALS_BIN.", { cause: streamErr });
 			}
+			progress.finish(`[luals] Downloaded ${info.assetName} (${formatTransferSummary(transferred, Date.now() - downloadStartedAt)})`);
 			const archiveSha256 = computeFileSha256(archivePath);
 			logger.info(`[luals] Downloaded ${info.assetName} (SHA-256 ${archiveSha256})`);
 			logger.info(`[luals] Extracting to ${destDir}...`);
-			await validateArchiveMembers(archivePath);
-			try {
-				const tarArgs = process.platform === "win32" ? [
-					"-xf",
-					path.basename(archivePath),
-					"-C",
-					tempDir
-				] : [
-					"-xf",
-					path.basename(archivePath),
-					"--no-same-owner",
-					"--no-same-permissions",
-					"-C",
-					tempDir
-				];
-				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",
-					"-Command",
-					`Expand-Archive -Path '${escapePowerShellSingleQuote(archivePath)}' -DestinationPath '${escapePowerShellSingleQuote(tempDir)}' -Force`
-				]);
-				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.");
+			const spinner = createSpinner({
+				label: `[luals] Extracting ${info.assetName}`,
+				announce: false
+			});
+			spinner.start();
+			let extractedSize;
 			try {
-				fs.unlinkSync(archivePath);
-			} catch (err) {
-				logger.debug(`[luals] Failed to delete temporary archive ${archivePath}: ${err instanceof Error ? err.message : String(err)}`);
+				await validateArchiveMembers(archivePath);
+				try {
+					const tarArgs = process.platform === "win32" ? [
+						"-xf",
+						path.basename(archivePath),
+						"-C",
+						tempDir
+					] : [
+						"-xf",
+						path.basename(archivePath),
+						"--no-same-owner",
+						"--no-same-permissions",
+						"-C",
+						tempDir
+					];
+					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",
+						"-Command",
+						`Expand-Archive -Path '${escapePowerShellSingleQuote(archivePath)}' -DestinationPath '${escapePowerShellSingleQuote(tempDir)}' -Force`
+					]);
+					else throw tarErr;
+				}
+				spinner.updateText("[luals] Verifying extracted files");
+				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) {
+					logger.debug(`[luals] Failed to delete temporary archive ${archivePath}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				spinner.stop(`[luals] Extracted ${formatBytes(extractedSize)} to ${destDir}`);
+			} catch (extractErr) {
+				spinner.fail();
+				throw extractErr;
 			}
 		}
 		const tempBinaryPath = path.join(tempDir, info.binaryRelativePath);
@@ -6340,6 +6885,236 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 	}
 }
 //#endregion
+//#region src/target-resolver.ts
+/** Resolves the canonical filesystem path, falling back to original path on failure. */
+function getCanonicalPath(p) {
+	try {
+		return fs.realpathSync.native ? fs.realpathSync.native(p) : fs.realpathSync(p);
+	} catch {
+		return p;
+	}
+}
+/** Determines whether a path points to the root of a filesystem volume. */
+function isFilesystemRoot(dir) {
+	const stripped = dir.trim();
+	if (stripped === "/" || stripped === "\\" || stripped === "") return true;
+	if (/^[a-zA-Z]:[\\/]?$/.test(stripped)) return true;
+	const norm = path.resolve(stripped);
+	if (norm === "/" || norm === "\\") return true;
+	return /^[a-zA-Z]:[\\/]?$/.test(norm);
+}
+/**
+* Computes the lowest common ancestor directory for a set of paths.
+* All paths must reside on the same filesystem root or volume.
+*/
+function findCommonAncestorDirectory(paths) {
+	if (paths.length === 0) return path.resolve(".");
+	const resolved = paths.map((p) => {
+		const abs = path.resolve(p);
+		try {
+			if (fs.existsSync(abs)) return fs.statSync(abs).isDirectory() ? abs : path.dirname(abs);
+		} catch (err) {}
+		return path.dirname(abs);
+	});
+	if (resolved.length === 1 && resolved[0]) return resolved[0];
+	const isWin = process.platform === "win32";
+	const splitPaths = resolved.map((p) => path.resolve(p).split(path.sep));
+	const first = splitPaths[0];
+	if (!first || first.length === 0) return path.resolve(".");
+	const firstRoot = first[0];
+	if (!splitPaths.every((p) => {
+		const rootSeg = p[0];
+		if (rootSeg === void 0) return false;
+		return isWin ? rootSeg.toLowerCase() === firstRoot?.toLowerCase() : rootSeg === firstRoot;
+	}) || firstRoot === void 0) throw new ConfigError(`Cannot check paths across different root drives or volumes: ${paths.join(", ")}`, "ERR_MULTIPLE_ROOTS", "Ensure all checked paths are within the same workspace or project root.");
+	const minLen = Math.min(...splitPaths.map((p) => p.length));
+	let commonLen = 0;
+	for (let i = 0; i < minLen; i++) {
+		const segment = first[i];
+		if (segment === void 0) break;
+		if (!splitPaths.every((p) => {
+			const seg = p[i];
+			if (seg === void 0) return false;
+			return isWin ? seg.toLowerCase() === segment.toLowerCase() : seg === segment;
+		})) break;
+		commonLen++;
+	}
+	if (commonLen === 0) throw new ConfigError(`Cannot check paths across different root drives or volumes: ${paths.join(", ")}`, "ERR_MULTIPLE_ROOTS", "Ensure all checked paths are within the same workspace or project root.");
+	let commonPath = first.slice(0, commonLen).join(path.sep);
+	if (!commonPath) commonPath = path.sep;
+	if (isWin && /^[a-zA-Z]:$/.test(commonPath)) commonPath = `${commonPath}\\`;
+	return path.resolve(commonPath);
+}
+/**
+* Searches upward from a starting directory to locate an enclosing project root
+* containing `.luarc.json`. Returns the start directory if not found.
+*/
+function findProjectRoot(startDir) {
+	let curr = path.resolve(startDir);
+	while (true) {
+		if (fs.existsSync(path.join(curr, ".luarc.json"))) return curr;
+		if (fs.existsSync(path.join(curr, ".git"))) break;
+		const parent = path.dirname(curr);
+		if (parent === curr) break;
+		curr = parent;
+	}
+	return startDir;
+}
+/**
+* Characters the LuaLS glob matcher treats as syntax.
+*
+* LuaLS compiles `files.exclude` with `glob.gitignore` (see its
+* `script/glob/glob.lua`), whose grammar only understands backslash escapes:
+* bracket expressions such as `[[]` are parsed as character ranges and match
+* nothing useful. Escaping is therefore done with `\`.
+*/
+const GLOB_METACHARACTERS = /* @__PURE__ */ new Set([
+	"*",
+	"?",
+	"[",
+	"]",
+	"{",
+	"}",
+	",",
+	"\\"
+]);
+/**
+* Escapes the glob metacharacters of a single path segment so it matches literally.
+*
+* Note: `normalizePattern()` in `src/luals/files.ts` rewrites backslashes to path
+* separators when counting checked files, so these escapes only reach LuaLS. That is
+* harmless: the counted file set is filtered by the requested target paths anyway.
+*/
+function escapeGlobSegment(segment) {
+	let escaped = "";
+	for (const char of segment) escaped += GLOB_METACHARACTERS.has(char) ? `\\${char}` : char;
+	return escaped;
+}
+/** Escapes glob metacharacters in every segment of a slash-separated relative path. */
+function escapeGlobPath(relativePath) {
+	return relativePath.split("/").map(escapeGlobSegment).join("/");
+}
+/**
+* Computes glob exclusion patterns for directories and files under workspace root
+* that are completely outside the requested target paths.
+*/
+function computeUnrequestedExclusions(root, targetPaths) {
+	const resolvedRoot = path.resolve(root);
+	if (targetPaths.length === 0 || targetPaths.some((t) => t === "." || t === "" || path.resolve(resolvedRoot, t) === resolvedRoot)) return [];
+	const isWin = process.platform === "win32";
+	const canonicalRoot = getCanonicalPath(resolvedRoot);
+	const relTargets = targetPaths.map((t) => {
+		const canonical = getCanonicalPath(path.isAbsolute(t) ? t : path.resolve(canonicalRoot, t));
+		const rel = path.relative(canonicalRoot, canonical).replace(/\\/g, "/");
+		return isWin ? rel.toLowerCase() : rel;
+	}).filter((rel) => !rel.startsWith("../") && rel !== "..");
+	if (relTargets.length === 0 || relTargets.includes("") || relTargets.includes(".")) return [];
+	const exclusions = [];
+	/** Recursively scans directory entries to identify unrequested paths. */
+	function scanDir(dir, relPrefix) {
+		let entries;
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const entryRel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+			const normEntry = isWin ? entryRel.toLowerCase() : entryRel;
+			let isExactTarget = false;
+			let isAncestorOfTarget = false;
+			let isDescendantOfTarget = false;
+			for (const target of relTargets) {
+				if (normEntry === target) {
+					isExactTarget = true;
+					break;
+				}
+				if (target.startsWith(`${normEntry}/`)) {
+					isAncestorOfTarget = true;
+					break;
+				}
+				if (normEntry.startsWith(`${target}/`)) {
+					isDescendantOfTarget = true;
+					break;
+				}
+			}
+			if (isExactTarget || isDescendantOfTarget) continue;
+			if (isAncestorOfTarget) {
+				if (entry.isDirectory()) scanDir(path.join(dir, entry.name), entryRel);
+				continue;
+			}
+			if (entry.isDirectory()) exclusions.push(`${escapeGlobPath(entryRel)}/**`);
+			else if (entry.isFile() && entry.name.toLowerCase().endsWith(".lua")) exclusions.push(escapeGlobPath(entryRel));
+		}
+	}
+	scanDir(canonicalRoot, "");
+	return exclusions;
+}
+/** Determines whether a workspace-relative file path matches any of the target paths. */
+function matchesTargetPaths(relativePath, root, targetPaths) {
+	if (targetPaths.length === 0 || targetPaths.length === 1 && (targetPaths[0] === "." || targetPaths[0] === "")) return true;
+	const isWin = process.platform === "win32";
+	const canonicalRoot = getCanonicalPath(root);
+	const normRel = isWin ? relativePath.replace(/\\/g, "/").toLowerCase() : relativePath.replace(/\\/g, "/");
+	for (const rawTarget of targetPaths) {
+		const fromCwd = path.resolve(rawTarget);
+		const canonicalTarget = getCanonicalPath(fs.existsSync(fromCwd) ? fromCwd : path.isAbsolute(rawTarget) ? rawTarget : path.resolve(canonicalRoot, rawTarget));
+		let relTarget = path.relative(canonicalRoot, canonicalTarget).replace(/\\/g, "/");
+		relTarget = stripTrailingSlashes(relTarget).replace(/^\.\//, "");
+		const normTarget = isWin ? relTarget.toLowerCase() : relTarget;
+		if (normTarget === "" || normTarget === ".") return true;
+		if (normRel === normTarget || normRel.startsWith(`${normTarget}/`)) return true;
+	}
+	return false;
+}
+/** Keeps only diagnostics for files that match the requested target paths. */
+function filterReportByTargetPaths(report, root, targetPaths) {
+	if (targetPaths.length === 0 || targetPaths.length === 1 && (targetPaths[0] === "." || targetPaths[0] === "")) return report;
+	const filtered = {};
+	const canonicalRoot = getCanonicalPath(root);
+	for (const [uri, diags] of Object.entries(report)) {
+		const filePath = fileUriToPath(uri);
+		const canonicalFile = getCanonicalPath(path.resolve(filePath));
+		if (matchesTargetPaths(path.relative(canonicalRoot, canonicalFile).replace(/\\/g, "/"), canonicalRoot, targetPaths)) filtered[uri] = diags;
+	}
+	return filtered;
+}
+/** Validates and resolves CLI target paths into a common root directory and target list. */
+function resolveCheckTargets(rawPaths) {
+	const paths = rawPaths && rawPaths.length > 0 ? rawPaths : ["."];
+	const canonicalTargets = paths.map((targetPath) => {
+		const resolved = path.resolve(targetPath);
+		if (!fs.existsSync(resolved)) throw new LuaLSError(`Target path does not exist: ${targetPath}`, "ERR_TARGET_NOT_FOUND", "Verify that the target path exists and is accessible.");
+		return getCanonicalPath(resolved);
+	});
+	const first = paths[0];
+	if (paths.length === 1 && first) {
+		const canonicalFirst = canonicalTargets[0];
+		const startDir = fs.statSync(canonicalFirst).isFile() ? path.dirname(canonicalFirst) : canonicalFirst;
+		const projRoot = findProjectRoot(startDir);
+		if (projRoot !== startDir) {
+			if (isFilesystemRoot(projRoot)) throw new ConfigError(`Cannot check targets across the root filesystem (${projRoot}): checked paths must share a common project directory.`, "ERR_ROOT_ANCESTOR", "Ensure all checked paths reside within a common project directory.");
+			logger.debug(`[targets] Using discovered project root "${projRoot}" for "${first}".`);
+			return {
+				rootPath: projRoot,
+				targetPaths: canonicalTargets
+			};
+		}
+		return {
+			rootPath: first,
+			targetPaths: canonicalTargets
+		};
+	}
+	const ancestor = findCommonAncestorDirectory(canonicalTargets);
+	if (isFilesystemRoot(ancestor)) throw new ConfigError(`Cannot check targets across the root filesystem (${ancestor}): checked paths must share a common project directory.`, "ERR_ROOT_ANCESTOR", "Ensure all checked paths reside within a common project directory.");
+	const rootPath = findProjectRoot(ancestor);
+	if (rootPath !== ancestor) logger.debug(`[targets] Using discovered project root "${rootPath}" for "${ancestor}".`);
+	return {
+		rootPath,
+		targetPaths: canonicalTargets
+	};
+}
+//#endregion
 //#region src/luals/files.ts
 /** Directories skipped unless the workspace config overrides `workspace.ignoreDir`. */
 const DEFAULT_IGNORE_DIRS = [
@@ -6463,7 +7238,7 @@ function resolveTargetPath(targetPath) {
 * honoring `workspace.ignoreDir` and `files.exclude` (#27). Absolute paths are returned
 * for single-file targets, and an empty list is returned when the walk fails.
 */
-function listCheckedFiles(targetPath, configPath) {
+function listCheckedFiles(targetPath, configPath, targetPaths) {
 	const absPath = resolveTargetPath(targetPath);
 	if (!absPath) return [];
 	if (fs.statSync(absPath).isFile()) return absPath.toLowerCase().endsWith(".lua") ? [absPath] : [];
@@ -6478,7 +7253,7 @@ function listCheckedFiles(targetPath, configPath) {
 	}
 	const ignore = [...toIgnorePatterns(ignoreDirs), ...toIgnorePatterns(excludePatterns)];
 	try {
-		return ts(LUA_FILE_PATTERN, {
+		const files = ts(LUA_FILE_PATTERN, {
 			cwd: absPath,
 			ignore,
 			dot: true,
@@ -6486,14 +7261,16 @@ function listCheckedFiles(targetPath, configPath) {
 			follow: false,
 			withFileTypes: true
 		}).filter((entry) => entry.isFile()).map((entry) => entry.relativePosix());
+		if (targetPaths && targetPaths.length > 0) return files.filter((f) => matchesTargetPaths(f, absPath, targetPaths));
+		return files;
 	} catch (err) {
 		logger.warn(`[luals] Failed to walk ${absPath} while listing checked files: ${err instanceof Error ? err.message : String(err)}`);
 		return [];
 	}
 }
 /** Counts candidate Lua files within targetPath, taking workspace ignoreDir and files.exclude into account (#27). */
-function countCheckedFiles(targetPath, configPath) {
-	return listCheckedFiles(targetPath, configPath).length;
+function countCheckedFiles(targetPath, configPath, targetPaths) {
+	return listCheckedFiles(targetPath, configPath, targetPaths).length;
 }
 //#endregion
 //#region src/luals/runner.ts
@@ -6705,7 +7482,7 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		const normTarget = normalizeComparable(targetFileOnly);
 		for (const [rawUri, diags] of Object.entries(diagnostics)) if (normalizeComparable(fileUriToPath(rawUri)) === normTarget) filtered[rawUri] = diags;
 		diagnostics = filtered;
-	}
+	} else if (options.paths && options.paths.length > 0) diagnostics = filterReportByTargetPaths(diagnostics, checkDir, options.paths);
 	let totalProblems = 0;
 	let totalErrors = 0;
 	let totalWarnings = 0;
@@ -6717,7 +7494,7 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		else if (d.severity === 2) totalWarnings += 1;
 	}
 	const passed = totalProblems === 0;
-	const filesChecked = countCheckedFiles(targetPath, configPath);
+	const filesChecked = countCheckedFiles(targetPath, configPath, options.paths);
 	return {
 		passed,
 		totalProblems,
@@ -6729,6 +7506,179 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 	};
 }
 //#endregion
+//#region src/deps.ts
+/** Accumulates repeatable --dep arguments. */
+function collectDeps(val, prev) {
+	const trimmed = val.trim();
+	if (!trimmed) return prev ?? [];
+	return (prev ?? []).concat(trimmed);
+}
+/** Normalizes a filesystem path to forward slashes for LuaLS compatibility. */
+function normalizeSlash(p) {
+	return p.replace(/\\/g, "/");
+}
+/**
+* Resolves package dependencies declared in .luarc.json (nanos.deps) or via CLI (--dep),
+* resolving transitive dependencies with cycle detection and partitioning them by realm.
+*/
+function resolvePackageDependencies(root, userConfig, cliDeps) {
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [];
+	if (cliDeps && cliDeps.length > 0) {
+		for (const dep of cliDeps) if (typeof dep === "string" && dep.trim()) queue.push({
+			rawPath: dep.trim(),
+			fromDir: process.cwd()
+		});
+	}
+	const rawConfigDeps = userConfig.nanos?.deps;
+	if (rawConfigDeps !== void 0) {
+		if (Array.isArray(rawConfigDeps)) for (const dep of rawConfigDeps) if (typeof dep === "string" && dep.trim()) queue.push({
+			rawPath: dep.trim(),
+			fromDir: root
+		});
+		else logger.warn(`[deps] Skipping invalid nanos.deps entry: expected a string path.`);
+		else logger.warn(`[deps] Ignoring nanos.deps: expected an array of path strings.`);
+	}
+	const resolvedFiles = [];
+	const resolvedDirs = [];
+	const depConfigMap = /* @__PURE__ */ new Map();
+	const isWin = process.platform === "win32";
+	while (queue.length > 0) {
+		const item = queue.shift();
+		if (!item) continue;
+		const { rawPath, fromDir } = item;
+		const absPath = path.resolve(fromDir, rawPath);
+		if (!fs.existsSync(absPath)) {
+			logger.warn(`[deps] Dependency path not found: "${rawPath}" (skipping).`);
+			continue;
+		}
+		let canonical;
+		try {
+			canonical = fs.realpathSync.native(absPath);
+		} catch (err) {
+			try {
+				canonical = fs.realpathSync(absPath);
+			} catch (innerErr) {
+				canonical = absPath;
+			}
+		}
+		const cycleKey = isWin ? canonical.toLowerCase() : canonical;
+		if (visited.has(cycleKey)) continue;
+		visited.add(cycleKey);
+		let stat;
+		try {
+			stat = fs.statSync(canonical);
+		} catch (err) {
+			continue;
+		}
+		if (stat.isFile()) {
+			if (canonical.toLowerCase().endsWith(".lua")) resolvedFiles.push(normalizeSlash(canonical));
+			else logger.warn(`[deps] Skipping non-Lua dependency file: "${rawPath}".`);
+			continue;
+		}
+		if (stat.isDirectory()) {
+			resolvedDirs.push(canonical);
+			const candidateLuarc = path.join(canonical, ".luarc.json");
+			if (fs.existsSync(candidateLuarc)) try {
+				const depConfig = loadUserConfig(canonical);
+				depConfigMap.set(canonical, depConfig);
+				const transDeps = depConfig.nanos?.deps;
+				if (transDeps !== void 0) {
+					if (Array.isArray(transDeps)) for (const trans of transDeps) if (typeof trans === "string" && trans.trim()) queue.push({
+						rawPath: trans.trim(),
+						fromDir: canonical
+					});
+					else logger.warn(`[deps] Skipping invalid nanos.deps entry in "${canonical}": expected a string path.`);
+					else logger.warn(`[deps] Ignoring nanos.deps in "${canonical}": expected an array of path strings.`);
+				}
+			} catch (err) {
+				logger.warn(`[deps] Failed to parse transitive dependency configuration at "${candidateLuarc}": ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+	}
+	const serverSet = /* @__PURE__ */ new Set();
+	const clientSet = /* @__PURE__ */ new Set();
+	const sharedSet = /* @__PURE__ */ new Set();
+	const allSet = /* @__PURE__ */ new Set();
+	for (const file of resolvedFiles) {
+		serverSet.add(file);
+		clientSet.add(file);
+		sharedSet.add(file);
+		allSet.add(file);
+	}
+	for (const depDir of resolvedDirs) {
+		const normDepDir = normalizeSlash(depDir);
+		allSet.add(normDepDir);
+		let depConfig = depConfigMap.get(depDir);
+		if (!depConfig) try {
+			depConfig = loadUserConfig(depDir);
+		} catch (err) {
+			depConfig = {};
+		}
+		const { enabled, mappings } = resolveRealmMappings(depConfig);
+		if (!enabled) {
+			serverSet.add(normDepDir);
+			clientSet.add(normDepDir);
+			sharedSet.add(normDepDir);
+			continue;
+		}
+		const serverFolder = path.join(depDir, "Server");
+		const clientFolder = path.join(depDir, "Client");
+		const sharedFolder = path.join(depDir, "Shared");
+		const hasServer = fs.existsSync(serverFolder);
+		const hasClient = fs.existsSync(clientFolder);
+		const hasShared = fs.existsSync(sharedFolder);
+		if (hasServer || hasClient || hasShared) {
+			if (hasServer) serverSet.add(normalizeSlash(serverFolder));
+			if (hasClient) clientSet.add(normalizeSlash(clientFolder));
+			if (hasShared) {
+				const normShared = normalizeSlash(sharedFolder);
+				serverSet.add(normShared);
+				clientSet.add(normShared);
+				sharedSet.add(normShared);
+			}
+			try {
+				const entries = fs.readdirSync(depDir, { withFileTypes: true });
+				for (const entry of entries) if (entry.isFile() && entry.name.toLowerCase().endsWith(".lua")) {
+					const rootFile = normalizeSlash(path.join(depDir, entry.name));
+					serverSet.add(rootFile);
+					clientSet.add(rootFile);
+					sharedSet.add(rootFile);
+				}
+			} catch (err) {}
+			continue;
+		}
+		if (depConfig.nanos?.realms) {
+			let matchedAnyCustom = false;
+			for (const { pattern, realm } of mappings) {
+				const baseFolder = pattern.replace(/\/\*\*.*$/, "").replace(/\/\*.*$/, "");
+				const targetPath = path.join(depDir, baseFolder);
+				if (fs.existsSync(targetPath)) {
+					matchedAnyCustom = true;
+					const norm = normalizeSlash(targetPath);
+					if (realm === "server") serverSet.add(norm);
+					else if (realm === "client") clientSet.add(norm);
+					else {
+						serverSet.add(norm);
+						clientSet.add(norm);
+						sharedSet.add(norm);
+					}
+				}
+			}
+			if (matchedAnyCustom) continue;
+		}
+		serverSet.add(normDepDir);
+		clientSet.add(normDepDir);
+		sharedSet.add(normDepDir);
+	}
+	return {
+		server: Array.from(serverSet),
+		client: Array.from(clientSet),
+		shared: Array.from(sharedSet),
+		all: Array.from(allSet)
+	};
+}
+//#endregion
 //#region src/realms.ts
 /** Normalizes a workspace-relative path for case-insensitive comparison on Windows. */
 function normalizeRelative(candidate) {
@@ -6786,13 +7736,17 @@ function selectedRealms(selection) {
 	return ["shared", selection];
 }
 /** Builds a pass config from the merged base config by swapping library and exclusions. */
-function buildPassConfig(baseConfig, realm, annotationsPath, realmAnnotationPath, excludedPatterns) {
+function buildPassConfig(baseConfig, realm, annotationsPath, realmAnnotationPath, excludedPatterns, dependencyLibraries = []) {
 	const config = JSON.parse(JSON.stringify(baseConfig));
 	const normalizedFull = annotationsPath.replace(/\\/g, "/");
 	const libraries = (config.workspace?.library ?? []).filter((entry) => entry.replace(/\\/g, "/") !== normalizedFull);
 	config.workspace = {
 		...config.workspace ?? {},
-		library: [realmAnnotationPath, ...libraries]
+		library: Array.from(/* @__PURE__ */ new Set([
+			realmAnnotationPath,
+			...libraries,
+			...dependencyLibraries
+		]))
 	};
 	if (realm !== "shared" && excludedPatterns.length > 0) config.files = {
 		...config.files ?? {},
@@ -6814,19 +7768,25 @@ function planRealmCheck(options) {
 		logger.debug("[realms] Realm mapping disabled; running a single standard pass.");
 		return null;
 	}
+	const unrequestedExclusions = options.targetPaths ? computeUnrequestedExclusions(resolvedTarget, options.targetPaths) : [];
 	const baseConfig = buildWorkspaceConfig(resolvedTarget, options.customConfigPath, {
 		ignore: options.ignore,
-		annotationsPath
+		annotationsPath,
+		unrequestedExclusions
 	});
 	const tempConfigs = [];
 	const baseConfigPath = writeTempConfig(baseConfig);
 	tempConfigs.push(baseConfigPath);
 	try {
 		const realmFiles = collectRealmFiles(resolvedTarget, mappings, listCheckedFiles(resolvedTarget, baseConfigPath));
+		const isTargetFile = (file) => {
+			if (!options.targetPaths || options.targetPaths.length === 0) return true;
+			return matchesTargetPaths(file, resolvedTarget, options.targetPaths);
+		};
 		const realmReportFiles = {
-			client: new Set(realmFiles.client.map(normalizeRelative)),
-			server: new Set(realmFiles.server.map(normalizeRelative)),
-			shared: new Set([...realmFiles.shared, ...realmFiles.unmatched].map(normalizeRelative))
+			client: new Set(realmFiles.client.filter(isTargetFile).map(normalizeRelative)),
+			server: new Set(realmFiles.server.filter(isTargetFile).map(normalizeRelative)),
+			shared: new Set([...realmFiles.shared, ...realmFiles.unmatched].filter(isTargetFile).map(normalizeRelative))
 		};
 		const hasRealmFolders = realmFiles.client.length > 0 || realmFiles.server.length > 0 || realmFiles.shared.length > 0;
 		if (selection === "all" && !hasRealmFolders) {
@@ -6835,14 +7795,22 @@ function planRealmCheck(options) {
 			return null;
 		}
 		const wanted = selectedRealms(selection).filter((realm) => realmReportFiles[realm].size > 0);
+		if (wanted.length === 0) {
+			if (selection !== "all") logger.warn(`[realms] No target files match the requested realm "${selection}"; falling back to a standard check.`);
+			else logger.debug("[realms] No files to report for selected realm pass; running a single standard pass.");
+			for (const tempConfig of tempConfigs) removeTempConfig(tempConfig);
+			return null;
+		}
 		const derived = wanted.some((realm) => realm !== "shared") ? deriveRealmAnnotationFiles(annotationsPath) : {
 			client: annotationsPath,
 			server: annotationsPath
 		};
+		const resolvedDeps = resolvePackageDependencies(resolvedTarget, userConfig, options.cliDeps);
 		const passes = [];
 		for (const realm of wanted) {
 			const excluded = mappings.filter((mapping) => mapping.realm !== realm && mapping.realm !== "shared").map((mapping) => mapping.pattern);
-			const configPath = writeTempConfig(buildPassConfig(baseConfig, realm, annotationsPath, realm === "client" ? derived.client : realm === "server" ? derived.server : annotationsPath, excluded));
+			const depLibraries = realm === "server" ? resolvedDeps.server : realm === "client" ? resolvedDeps.client : resolvedDeps.shared;
+			const configPath = writeTempConfig(buildPassConfig(baseConfig, realm, annotationsPath, realm === "client" ? derived.client : realm === "server" ? derived.server : annotationsPath, excluded, depLibraries));
 			tempConfigs.push(configPath);
 			passes.push({
 				realm,
@@ -6873,9 +7841,15 @@ function removeTempConfig(configPath) {
 /** Keeps only the diagnostics of files owned by the pass. */
 function filterReportByFiles(report, root, reportFiles) {
 	const filtered = {};
+	const canonicalRoot = getCanonicalPath(root);
 	for (const [uri, diagnostics] of Object.entries(report)) {
 		const filePath = fileUriToPath(uri);
-		const relative = normalizeRelative(path.relative(root, path.resolve(filePath)));
+		const resolvedFile = path.resolve(filePath);
+		let relative = normalizeRelative(path.relative(root, resolvedFile));
+		if (!reportFiles.has(relative)) {
+			const canonicalFile = getCanonicalPath(resolvedFile);
+			relative = normalizeRelative(path.relative(canonicalRoot, canonicalFile));
+		}
 		if (reportFiles.has(relative)) filtered[uri] = diagnostics;
 	}
 	return filtered;
@@ -10116,7 +11090,7 @@ 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) {
+async function readBoundedResponseBody(res, maxBytes, onExceeded, onProgress) {
 	const lengthHeader = res.headers?.get?.("content-length");
 	if (lengthHeader) {
 		const declared = parseInt(lengthHeader, 10);
@@ -10137,6 +11111,7 @@ async function readBoundedResponseBody(res, maxBytes, onExceeded) {
 				onExceeded(total, "stream");
 				return null;
 			}
+			onProgress?.(total);
 			chunks.push(buf);
 		}
 		return Buffer.concat(chunks).toString("utf-8");
@@ -10152,15 +11127,35 @@ async function readBoundedResponseBody(res, maxBytes, onExceeded) {
 	}
 	return "";
 }
+/**
+* Resolves a request through the download guard, which refuses an off-allowlist request URL,
+* an off-allowlist redirect hop and an off-allowlist final response URL, releasing the body of
+* every refused response instead of downloading it.
+*/
+async function resolveGuardedResponse(url, init) {
+	const result = await guardedFetch(url, init);
+	if (result.ok && result.response) return { res: result.response };
+	return { block: result };
+}
+/** Builds the user-facing error for a request refused by the download transport policy. */
+function downloadBlockError(result) {
+	if (result.reason === "network-error") return new AnnotationsError(`Failed to download annotations.lua: ${result.error instanceof Error ? result.error.message : String(result.error)}`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify your internet connection and that GitHub raw endpoints are accessible.", { cause: result.error });
+	return new AnnotationsError(`${result.reason === "too-many-redirects" ? "Redirect chain too long" : result.reason === "missing-location" ? "Redirect without a usable target" : "Redirect blocked"}: requests must stay on allowlisted GitHub infrastructure over HTTPS (${result.url ?? "unknown URL"})`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify that no proxy or DNS override redirects GitHub traffic to another host or to plaintext http://.");
+}
 /** Fetches the latest commit SHA for the annotations branch from the GitHub API. */
 async function fetchLatestCommitId() {
 	try {
 		const headers = { "User-Agent": "nanos-lint" };
 		if (process.env.GITHUB_TOKEN) headers["Authorization"] = `token ${process.env.GITHUB_TOKEN}`;
-		const res = await fetch(GITHUB_COMMITS_API, {
+		const outcome = await resolveGuardedResponse(GITHUB_COMMITS_API, {
 			headers,
 			signal: AbortSignal.timeout(5e3)
 		});
+		if ("block" in outcome) {
+			if (outcome.block.reason !== "network-error") logger.warn(`[annotations] ${downloadBlockError(outcome.block).message}`);
+			return null;
+		}
+		const { res } = outcome;
 		if (res.ok) {
 			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)`);
@@ -10187,16 +11182,40 @@ function getRawAnnotationsUrl(commitSha) {
 }
 /** Downloads raw annotations.lua content from GitHub raw content endpoints. */
 async function fetchRawAnnotationsContent(commitSha) {
-	const url = getRawAnnotationsUrl(commitSha);
-	const res = await fetch(url, {
+	const outcome = await resolveGuardedResponse(getRawAnnotationsUrl(commitSha), {
 		headers: { "User-Agent": "nanos-lint" },
 		signal: AbortSignal.timeout(15e3)
 	});
+	if ("block" in outcome) {
+		const blockError = downloadBlockError(outcome.block);
+		logger.warn(`[annotations] ${blockError.message}`);
+		throw blockError;
+	}
+	const { res } = outcome;
 	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 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>.");
+	const declaredTotal = parseDeclaredContentLength(res);
+	const startedAt = Date.now();
+	let transferred = 0;
+	const commitLabel = commitSha ? ` (${commitSha.slice(0, 7)})` : "";
+	const progress = createProgressBar({
+		label: `[annotations] Downloading ${ANNOTATIONS_FILENAME}${commitLabel}`,
+		total: declaredTotal,
+		announce: false
 	});
-	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>.");
+	let text;
+	try {
+		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>.");
+		}, (bytes) => {
+			transferred = bytes;
+			progress.update(bytes, declaredTotal);
+		});
+		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>.");
+	} catch (err) {
+		progress.fail();
+		throw err;
+	}
+	progress.finish(`[annotations] Downloaded ${ANNOTATIONS_FILENAME} (${formatTransferSummary(transferred, Date.now() - startedAt)})`);
 	return text;
 }
 /**
@@ -10443,15 +11462,16 @@ function createProgram(options) {
 		"info",
 		"debug",
 		"silent"
-	]).default(DEFAULT_LOG_LEVEL)).hook("preAction", (thisCommand, actionCommand) => {
+	]).default(DEFAULT_LOG_LEVEL)).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);
-	}).exitOverride().configureOutput({
+		if (opts.progress === false) setProgressMode("off");
+	}).exitOverride().configureHelp({ showGlobalOptions: true }).configureOutput({
 		writeOut: (str) => console.log(str.trimEnd()),
 		writeErr: (str) => logger.error(str.trimEnd())
 	});
-	program.command("check [path]", { isDefault: true }).description("Check a workspace or Lua file (default command)").addOption(new Option("--checklevel <level>", "Minimum diagnostic level: Error, Warning, Information, Hint").choices([
+	program.command("check [paths...]", { isDefault: true }).description("Check workspace files or directories (default command)").addOption(new Option("--checklevel <level>", "Minimum diagnostic level: Error, Warning, Information, Hint").choices([
 		"Error",
 		"Warning",
 		"Information",
@@ -10460,7 +11480,7 @@ function createProgram(options) {
 		"pretty",
 		"json",
 		"github"
-	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).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("--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",
@@ -10471,44 +11491,58 @@ function createProgram(options) {
 		"client",
 		"server",
 		"shared"
-	]).default("all")).action(async (targetPath = ".", opts) => {
+	]).default("all")).action(async (targetPaths = ["."], opts) => {
 		if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
+		const { rootPath, targetPaths: canonicalTargets } = resolveCheckTargets(targetPaths && targetPaths.length > 0 ? targetPaths : ["."]);
 		const format = opts.github ? "github" : opts.format || (process.env.GITHUB_ACTIONS ? "github" : "pretty");
+		if (format === "json") {
+			setProgressMode("off");
+			logger.setDiagnosticStream("stderr");
+		}
 		const checkOptions = {
-			path: targetPath,
+			path: rootPath,
+			paths: canonicalTargets,
 			configpath: opts.config,
 			checklevel: opts.checklevel,
 			format,
 			lualsVersion: opts.lualsVersion,
 			failOnError: opts.fail !== false,
-			ignore: opts.ignore
+			ignore: opts.ignore,
+			deps: opts.dep
 		};
 		if (opts.config) {
 			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 userConfig = loadUserConfig(rootPath, checkOptions.configpath);
 		const realmPlan = planRealmCheck({
-			targetPath,
-			userConfig: loadUserConfig(targetPath, checkOptions.configpath),
+			targetPath: rootPath,
+			userConfig,
 			selection: opts.realm ?? "all",
 			annotationsPath,
 			customConfigPath: checkOptions.configpath,
-			ignore: checkOptions.ignore
+			ignore: checkOptions.ignore,
+			targetPaths: canonicalTargets,
+			cliDeps: checkOptions.deps
 		});
 		let result;
 		if (realmPlan) try {
-			result = await runRealmAwareCheck(realmPlan, targetPath, checkOptions);
+			result = await runRealmAwareCheck(realmPlan, rootPath, checkOptions);
 		} finally {
 			realmPlan.cleanup();
 		}
 		else {
-			const resolved = resolveWorkspaceConfig(targetPath, checkOptions.configpath, {
+			const resolvedDeps = resolvePackageDependencies(rootPath, userConfig, checkOptions.deps);
+			const unrequestedExclusions = computeUnrequestedExclusions(rootPath, canonicalTargets);
+			const resolved = resolveWorkspaceConfig(rootPath, checkOptions.configpath, {
 				ignore: checkOptions.ignore,
-				annotationsPath
+				annotationsPath,
+				dependencyLibraries: resolvedDeps.all,
+				unrequestedExclusions
 			});
 			try {
-				result = await runLuaLSCheck(targetPath, resolved.configPath, checkOptions);
+				result = await runLuaLSCheck(rootPath, resolved.configPath, checkOptions);
 			} finally {
 				if (resolved.isTemp && fs.existsSync(resolved.configPath)) try {
 					fs.unlinkSync(resolved.configPath);
@@ -10556,6 +11590,7 @@ function createProgram(options) {
 		}
 	};
 	const handleCacheStatus = (opts) => {
+		if (opts?.json) logger.setDiagnosticStream("stderr");
 		const report = getCacheStatus();
 		if (opts?.json) writeOutput(JSON.stringify(report, null, 2));
 		else writeOutput(formatCacheStatusPretty(report));
@@ -10589,6 +11624,7 @@ Examples:
   $ npx nanos-lint check . --checklevel=Error
   $ npx nanos-lint check . --ignore "myfolder/hello-*.lua"
   $ npx nanos-lint check . --realm server
+  $ npx nanos-lint check Shared/ Server/ --realm server
   $ npx nanos-lint init
   $ npx nanos-lint clean-cache
 `);
@@ -10596,6 +11632,8 @@ Examples:
 }
 /** Parses command-line arguments and executes the requested CLI action. */
 async function runCLI(args = process.argv.slice(2)) {
+	setProgressMode("auto");
+	logger.setDiagnosticStream("stdout");
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (!arg) continue;
@@ -10668,6 +11706,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { getBaseLuaLSCacheDir as $, getDirectorySize as $t, formatProblemSummary as A, VALID_LUALS_DIAGNOSTIC_CODES as At, runLuaLSCheck as B, parseJsonc as Bt, getCachedAnnotationsFilePath as C, fetchLatestLuaLSVersionFromGitHub as Ct, updateLastCheckedDate as D, deriveRealmAnnotationFiles as Dt, readAnnotationsMetadata as E, sanitizeLuaLSVersion as Et, shouldEnableColor as F, getPackageRoot as Ft, MAX_ARCHIVE_SIZE_BYTES as G, writeTempConfig as Gt, listCheckedFiles as H, resolveWorkspaceConfig as Ht, collectRealmFiles as I, initWorkspace as It, isAllowedDownloadUrl as J, ConfigError as Jt, computeFileSha256 as K, AnnotationsError as Kt, planRealmCheck as L, loadConfigFile as Lt, formatSeverityBadge as M, getDefaultAnnotationsPath as Mt, getColors as N, getDefaultTemplatePath as Nt, formatGitHubAnnotations as O, splitAnnotationsByRealm as Ot, pluralize as P, getDefinitionsDir as Pt, findExistingLuaLSDir as Q, formatBytes as Qt, runRealmAwareCheck as R, loadUserConfig as Rt, getAnnotationsMetadataFilePath as S, FALLBACK_LUALS_VERSION as St, isAnnotationsValid as T, resolveLuaLSVersion as Tt, ALLOWED_DOWNLOAD_DOMAINS as U, stripJsonComments as Ut, countCheckedFiles as V, resolveRealmMappings as Vt, DOWNLOAD_TIMEOUT_MS as W, stripTrailingSlashes as Wt, LUALS_METADATA_FILENAME as X, NanosLintError as Xt, limitDownloadStream as Y, LuaLSError as Yt, cleanupOldCachedLuaLSVersions as Z, cleanCache as Zt, MAX_ANNOTATIONS_SIZE_BYTES as _, isZipArchive as _t, formatCacheStatusPretty as a, Logger as an, readLuaLSMetadata as at, MIN_ANNOTATIONS_SIZE_BYTES as b, getPlatformInfo as bt, DOCGEN_BRANCH as c, parseLogLevel as cn, MAX_DECOMPRESSED_SIZE_BYTES as ct, RAW_ANNOTATIONS_URL as d, escapePowerShellSingleQuote as dt, systemPaths as en, getCacheDir as et, downloadAndCacheAnnotations as f, getTarBinary as ft, ANNOTATIONS_FILENAME as g, isGzipArchive as gt, getRawAnnotationsUrl as h, isBinaryValid as ht, runCLI as i, LOG_LEVEL_PRIORITY as in, listCachedLuaLSVersions as it, formatReport as j, buildWorkspaceConfig as jt, formatPretty as k, DEFAULT_REALM_MAPPINGS as kt, DOCGEN_REPO as l, MIN_DOWNLOADED_BINARY_SIZE_BYTES as lt, fetchRawAnnotationsContent as m, isBinaryRunnable as mt, createProgram as n, DEFAULT_LOG_LEVEL as nn, getLuaLSMetadataPath as nt, getCacheStatus as o, isValidLogLevel as on, writeLuaLSMetadata as ot, fetchLatestCommitId as p, inspectZipMembers as pt, downloadAndExtractLuaLS as q, CacheError as qt, isDirectExecution as r, LOG_LEVELS as rn, listCachedLuaLSVersionDirs as rt, resolveAnnotations as s, logger as sn, MAX_ARCHIVE_MEMBER_COUNT as st, collectIgnorePatterns as t, fileUriToPath as tn, getIsoWeek as tt, GITHUB_COMMITS_API as u, assertValidLuaLSBinary as ut, MAX_COMMIT_JSON_SIZE_BYTES as v, parseTarTvSize as vt, getTodayDateString as w, resolveLatestLuaLSVersion as wt, getAnnotationsCacheDir as x, DEFAULT_LUALS_VERSION as xt, METADATA_FILENAME as y, validateArchiveMembers as yt, resolveLuaLSBinary as z, mergeConfigs as zt };
+export { DOWNLOAD_TIMEOUT_MS as $, getDefaultAnnotationsPath as $t, formatProblemSummary as A, DEFAULT_LUALS_VERSION as At, resolvePackageDependencies as B, PROGRESS_MILESTONES as Bt, getCachedAnnotationsFilePath as C, DEFAULT_LOG_LEVEL as Cn, isBinaryRunnable as Ct, updateLastCheckedDate as D, isValidLogLevel as Dn, parseTarTvSize as Dt, readAnnotationsMetadata as E, Logger as En, isZipArchive as Et, shouldEnableColor as F, sanitizeLuaLSVersion as Ft, computeUnrequestedExclusions as G, formatTransferSummary as Gt, runLuaLSCheck as H, SPINNER_FRAMES as Ht, collectRealmFiles as I, ALLOWED_DOWNLOAD_DOMAINS as It, findProjectRoot as J, restoreTerminal as Jt, filterReportByTargetPaths as K, getProgressMode as Kt, planRealmCheck as L, isAllowedDownloadUrl as Lt, formatSeverityBadge as M, fetchLatestLuaLSVersionFromGitHub as Mt, getColors as N, resolveLatestLuaLSVersion as Nt, formatGitHubAnnotations as O, logger as On, validateArchiveMembers as Ot, pluralize as P, resolveLuaLSVersion as Pt, resolveCheckTargets as Q, buildWorkspaceConfig as Qt, runRealmAwareCheck as R, deriveRealmAnnotationFiles as Rt, getAnnotationsMetadataFilePath as S, fileUriToPath as Sn, inspectZipMembers as St, isAnnotationsValid as T, LOG_LEVEL_PRIORITY as Tn, isGzipArchive as Tt, countCheckedFiles as U, createProgressBar as Ut, resolveLuaLSBinary as V, PROGRESS_THROTTLE_MS as Vt, listCheckedFiles as W, createSpinner as Wt, isFilesystemRoot as X, DEFAULT_REALM_MAPPINGS as Xt, getCanonicalPath as Y, setProgressMode as Yt, matchesTargetPaths as Z, VALID_LUALS_DIAGNOSTIC_CODES as Zt, MAX_ANNOTATIONS_SIZE_BYTES as _, NanosLintError as _n, MAX_DECOMPRESSED_SIZE_BYTES as _t, formatCacheStatusPretty as a, loadUserConfig as an, LUALS_METADATA_FILENAME as at, MIN_ANNOTATIONS_SIZE_BYTES as b, getDirectorySize as bn, escapePowerShellSingleQuote as bt, DOCGEN_BRANCH as c, resolveRealmMappings as cn, getBaseLuaLSCacheDir as ct, RAW_ANNOTATIONS_URL as d, stripTrailingSlashes as dn, getLuaLSMetadataPath as dt, getDefaultTemplatePath as en, MAX_ARCHIVE_SIZE_BYTES as et, downloadAndCacheAnnotations as f, writeTempConfig as fn, listCachedLuaLSVersionDirs as ft, ANNOTATIONS_FILENAME as g, LuaLSError as gn, MAX_ARCHIVE_MEMBER_COUNT as gt, getRawAnnotationsUrl as h, ConfigError as hn, writeLuaLSMetadata as ht, runCLI as i, loadConfigFile as in, trackDownloadProgress as it, formatReport as j, FALLBACK_LUALS_VERSION as jt, formatPretty as k, parseLogLevel as kn, getPlatformInfo as kt, DOCGEN_REPO as l, resolveWorkspaceConfig as ln, getCacheDir as lt, fetchRawAnnotationsContent as m, CacheError as mn, readLuaLSMetadata as mt, createProgram as n, getPackageRoot as nn, downloadAndExtractLuaLS as nt, getCacheStatus as o, mergeConfigs as on, cleanupOldCachedLuaLSVersions as ot, fetchLatestCommitId as p, AnnotationsError as pn, listCachedLuaLSVersions as pt, findCommonAncestorDirectory as q, isProgressInteractive as qt, isDirectExecution as r, initWorkspace as rn, limitDownloadStream as rt, resolveAnnotations as s, parseJsonc as sn, findExistingLuaLSDir as st, collectIgnorePatterns as t, getDefinitionsDir as tn, computeFileSha256 as tt, GITHUB_COMMITS_API as u, stripJsonComments as un, getIsoWeek as ut, MAX_COMMIT_JSON_SIZE_BYTES as v, cleanCache as vn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as vt, getTodayDateString as w, LOG_LEVELS as wn, isBinaryValid as wt, getAnnotationsCacheDir as x, systemPaths as xn, getTarBinary as xt, METADATA_FILENAME as y, formatBytes as yn, assertValidLuaLSBinary as yt, collectDeps as z, splitAnnotationsByRealm as zt };
 
-//# sourceMappingURL=cli-B9EpAClV.js.map
+//# sourceMappingURL=cli-CeNxOiST.js.map