@isentinel/jest-roblox 0.3.1 → 0.3.2

package/README.md

@@ -444,6 +444,7 @@ root, and `workspace.outputFile: true` writes a per-package result file per
 | `--outputFile <path>` | Write results to a file |
 | `--gameOutput <path>` | Write game print/warn/error to a file |
 | `--coverage` | Collect coverage |
+| `--no-coverage` | Disable coverage for this run, even when enabled in config |
 | `--coverageDirectory <path>` | Where to put coverage reports |
 | `--coverageReporters <r...>` | Which report formats to use |
 | `--collectCoverageFrom <glob>` | Globs for files to include in coverage (repeatable) |

package/dist/cli.mjs

@@ -1,31 +1,8 @@
-import { A as mergeCliWithConfig, D as LuauScriptError, E as formatBanner, H as ConfigError, R as VALID_BACKENDS, U as version, V as isValidBackend, f as outputMultiResult, j as loadConfig, p as outputSingleResult, t as runJestRoblox, y as parseGameOutput } from "./run-Cl5gYSQr.mjs";
+import { B as VALID_BACKENDS, G as version, M as mergeCliWithConfig, N as loadConfig, O as formatBanner, U as isValidBackend, W as ConfigError, d as walkErrorChain, h as outputSingleResult, k as LuauScriptError, m as outputMultiResult, t as runJestRoblox, u as formatMissingScopes, x as parseGameOutput } from "./run-CyHhajiY.mjs";
 import { OpenCloudError } from "@bedrock-rbx/ocale";
 import process from "node:process";
 import { parseArgs as parseArgs$1 } from "node:util";
 import color from "tinyrainbow";
-//#region src/utils/error-chain.ts
-const MAX_DEPTH = 5;
-function walkErrorChain(err) {
-	const entries = [];
-	let current = err;
-	while (current instanceof Error && entries.length < MAX_DEPTH) {
-		entries.push({
-			name: current.constructor.name,
-			code: readStringProperty(current, "code"),
-			errno: readStringProperty(current, "errno"),
-			message: current.message,
-			syscall: readStringProperty(current, "syscall")
-		});
-		current = current.cause;
-	}
-	return entries;
-}
-function readStringProperty(err, key) {
-	const value = Reflect.get(err, key);
-	if (value === void 0 || value === null) return;
-	return String(value);
-}
-//#endregion
 //#region src/cli.ts
 const VERSION = version;
 const HELP_TEXT = `
@@ -47,6 +24,7 @@ Options:
   --no-color                        Disable colored output
   -u, --updateSnapshot              Update snapshot files
   --coverage                        Enable coverage collection
+  --no-coverage                     Disable coverage for this run (overrides config)
   --collectCoverageFrom <glob>      Globs for files to include in coverage (repeatable)
   --coverageDirectory <path>        Directory for coverage output (default: coverage)
   --coverageReporters <r...>        Coverage reporters (default: text, lcov)
@@ -90,6 +68,7 @@ Examples:
   jest-roblox -t "should spawn"       Run tests matching pattern
   jest-roblox --formatters json       Output JSON to file
   jest-roblox --coverage              Run tests with coverage instrumentation
+  jest-roblox --no-coverage           Skip coverage instrumentation for this run
 `;
 function parseArgs(args) {
 	const { positionals, values } = parseArgs$1({
@@ -122,6 +101,7 @@ function parseArgs(args) {
 				type: "boolean"
 			},
 			"no-color": { type: "boolean" },
+			"no-coverage": { type: "boolean" },
 			"no-coverage-cache": { type: "boolean" },
 			"no-show-luau": { type: "boolean" },
 			"outputFile": { type: "string" },
@@ -176,7 +156,7 @@ function parseArgs(args) {
 		affectedSince: values["affected-since"],
 		apiKey: values.apiKey,
 		backend: validateBackend(values.backend),
-		collectCoverage: values.coverage,
+		collectCoverage: values["no-coverage"] === true ? false : values.coverage,
 		collectCoverageFrom: values.collectCoverageFrom,
 		color: values["no-color"] === true ? false : values.color,
 		config: values.config,
@@ -288,6 +268,7 @@ function formatBackendErrorBanner(err) {
 		const extras = formatChainExtras(entry);
 		const label = color.dim(`[${index.toString()}]`);
 		body.push(`    ${label} ${entry.name}: ${entry.message}${extras}`);
+		if (entry.requiredScopes !== void 0) body.push(`        ${color.yellow(formatMissingScopes(entry.requiredScopes))}`);
 	}
 	return formatBanner({
 		body,

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { B as defineProject, C as formatFailure, F as JEST_ARGV_EXCLUDED_KEYS, I as ROOT_CLI_KEYS, L as SHARED_TEST_KEYS, M as resolveConfig, N as DEFAULT_CONFIG, O as extractJsonFromOutput, P as GLOBAL_TEST_KEYS, S as writeJsonFile, T as formatTestSummary, _ as runProjects, a as visitStatement, b as writeGameOutput, c as OpenCloudBackend, d as generateTestScript, g as formatExecuteOutput, h as formatJobSummary, i as visitExpression, j as loadConfig, k as parseJestOutput, l as createOpenCloudBackend, m as formatAnnotations, n as runTypecheck, o as StudioBackend, r as visitBlock, s as createStudioBackend, t as runJestRoblox, u as buildJestArgv, v as formatGameOutputNotice, w as formatResult, x as formatJson, y as parseGameOutput, z as defineConfig } from "./run-Cl5gYSQr.mjs";
+import { A as extractJsonFromOutput, C as formatJson, D as formatTestSummary, E as formatResult, F as DEFAULT_CONFIG, H as defineProject, I as GLOBAL_TEST_KEYS, L as JEST_ARGV_EXCLUDED_KEYS, N as loadConfig, P as resolveConfig, R as ROOT_CLI_KEYS, S as writeGameOutput, T as formatFailure, V as defineConfig, _ as formatJobSummary, a as visitStatement, b as formatGameOutputNotice, c as OpenCloudBackend, f as buildJestArgv, g as formatAnnotations, i as visitExpression, j as parseJestOutput, l as createOpenCloudBackend, n as runTypecheck, o as StudioBackend, p as generateTestScript, r as visitBlock, s as createStudioBackend, t as runJestRoblox, v as formatExecuteOutput, w as writeJsonFile, x as parseGameOutput, y as runProjects, z as SHARED_TEST_KEYS } from "./run-CyHhajiY.mjs";
 export { DEFAULT_CONFIG, GLOBAL_TEST_KEYS, JEST_ARGV_EXCLUDED_KEYS, OpenCloudBackend, ROOT_CLI_KEYS, SHARED_TEST_KEYS, StudioBackend, buildJestArgv, createOpenCloudBackend, createStudioBackend, defineConfig, defineProject, extractJsonFromOutput, formatAnnotations, formatExecuteOutput, formatFailure, formatGameOutputNotice, formatJobSummary, formatJson, formatResult, formatTestSummary, generateTestScript, loadConfig, parseGameOutput, parseJestOutput, resolveConfig, runJestRoblox, runProjects, runTypecheck, visitBlock, visitExpression, visitStatement, writeGameOutput, writeJsonFile };

package/dist/{run-Cl5gYSQr.mjs → run-CyHhajiY.mjs}

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { PermissionError, PollTimeoutError } from "@bedrock-rbx/ocale";
+import { PermissionError, PollTimeoutError, TRANSIENT_TRANSPORT_CODES } from "@bedrock-rbx/ocale";
 import process from "node:process";
 import { isDeepStrictEqual } from "node:util";
 import color from "tinyrainbow";
@@ -33,7 +33,7 @@ import { Buffer } from "node:buffer";
 import { parseJSONC, parseYAML } from "confbox";
 import { Visitor, parseSync } from "oxc-parser";
 //#region package.json
-var version = "0.3.1";
+var version = "0.3.2";
 //#endregion
 //#region src/config/errors.ts
 var ConfigError = class extends Error {
@@ -933,12 +933,35 @@ function mapBranchArmLocations(traceMap, locations, sourceMapDirectory) {
 		tsPath
 	};
 }
+/**
+* Detects a phantom branch arm produced by a source-less synthetic statement
+* `if` (e.g. a roblox-ts Array polyfill like `.filter`/`.includes`). The
+* synthetic `if` has no source map entry, so trace-mapping's greatest-lower-
+* bound bias snaps both arms onto the nearest preceding segment — the then-
+* arm's own start — yielding a zero-width arm that coincides with another
+* arm's start and can never be covered.
+*
+* A genuine statement `if` is safe: roblox-ts always renders it multi-line, so
+* the then-body (generated line `if+1`) and the implicit-else arm (generated
+* line `if`) carry distinct source-map segments and never collapse. This is
+* gated to `type === "if"` by the caller: a single-line `expr-if` (ternary)
+* legitimately collapses to one column-0 segment and must NOT be dropped.
+*/
+function hasCollapsedPhantomArm(locations) {
+	return locations.some((arm, index) => {
+		if (!(arm.start.line === arm.end.line && arm.start.column === arm.end.column)) return false;
+		return locations.some((other, otherIndex) => {
+			return otherIndex !== index && other.start.line === arm.start.line && other.start.column === arm.start.column;
+		});
+	});
+}
 function mapFileBranches(resources, fileCoverage, pendingBranches) {
 	if (resources.coverageMap.branchMap === void 0) return;
 	for (const [branchId, entry] of Object.entries(resources.coverageMap.branchMap)) {
 		const armHitCounts = fileCoverage.b?.[branchId] ?? [];
 		const result = mapBranchArmLocations(resources.traceMap, entry.locations, resources.sourceMapDirectory);
 		if (result === void 0) continue;
+		if (entry.type === "if" && hasCollapsedPhantomArm(result.locations)) continue;
 		let fileBranches = pendingBranches.get(result.tsPath);
 		if (fileBranches === void 0) {
 			fileBranches = [];
@@ -2081,6 +2104,7 @@ function findMapping(filePath, mappings, key = "outDir") {
 }
 function replacePrefix(filePath, from, to) {
 	if (filePath === from) return to;
+	if (from === ".") return `${to}/${filePath.startsWith("./") ? filePath.slice(2) : filePath}`;
 	if (filePath.startsWith(`${from}/`)) return `${to}${filePath.slice(from.length)}`;
 	return filePath;
 }
@@ -2717,7 +2741,7 @@ function formatTestSummary(result, timing, styles, options) {
 }
 function formatResult(result, timing, options) {
 	const styles = createStyles(options.color, options.slowTestThreshold);
-	const lines = [formatRunHeader(options, styles)];
+	const lines = [""];
 	for (const file of result.testResults) {
 		if (options.failuresOnly === true && file.numFailingTests === 0 && !hasExecError(file)) continue;
 		lines.push(formatFileSummary(file, options, styles));
@@ -2891,7 +2915,7 @@ function formatMultiProjectResult(projects, timing, options) {
 		result,
 		styles
 	}));
-	const lines = [formatRunHeader(options, styles), sections.join("\n\n")];
+	const lines = ["", sections.join("\n\n")];
 	const mergedResult = mergeJestResults(projects.map((project) => project.result));
 	lines.push("", formatTestSummary(mergedResult, timing, styles, {
 		snapshotWriteFailures: options.snapshotWriteFailures,
@@ -3698,6 +3722,15 @@ function hasFormatter(formatters, name) {
 function usesAgentFormatter(formatters, verbose = false) {
 	return hasFormatter(formatters, "agent") && !verbose;
 }
+/**
+* Whether human-facing progress output (the run header, the "Running X of Y"
+* notice, the workspace streaming lines) should be written: not silent and not
+* a machine-readable formatter (json, or non-verbose agent). The single source
+* of truth so these sinks can't drift apart.
+*/
+function isDefaultHumanFormatter(options) {
+	return options.silent !== true && !usesAgentFormatter(options.formatters, options.verbose) && !hasFormatter(options.formatters, "json");
+}
 //#endregion
 //#region src/snapshot/path-resolver.ts
 function createSnapshotPathResolver(config) {
@@ -4896,7 +4929,10 @@ var OcaleRunner = class {
 			script,
 			timeoutSeconds,
 			universeId: this.credentials.universeId
-		}, { timeoutMs: timeout });
+		}, {
+			retryableTransportCodes: TRANSIENT_TRANSPORT_CODES,
+			timeoutMs: timeout
+		});
 		if (!result.success) {
 			if (result.err instanceof PollTimeoutError) throw new Error("Execution timed out", { cause: result.err });
 			throw new Error(result.err.message, { cause: result.err });
@@ -4918,7 +4954,7 @@ var OcaleRunner = class {
 			placeId: this.credentials.placeId,
 			universeId: this.credentials.universeId
 		};
-		const result = await this.places.save(parameters);
+		const result = await this.places.save(parameters, { retryableTransportCodes: TRANSIENT_TRANSPORT_CODES });
 		if (!result.success) throw new Error(`Failed to upload place: ${result.err.message}`, { cause: result.err });
 		return {
 			uploadMs: Date.now() - uploadStart,
@@ -5036,6 +5072,35 @@ function generateTestScript(options) {
 	return test_runner_bundled_default.replace("__CONFIG_JSON__", () => JSON.stringify({ configs }));
 }
 //#endregion
+//#region src/utils/error-chain.ts
+const MAX_DEPTH = 5;
+function walkErrorChain(err) {
+	const entries = [];
+	let current = err;
+	while (current instanceof Error && entries.length < MAX_DEPTH) {
+		entries.push({
+			name: current.constructor.name,
+			code: readStringProperty(current, "code"),
+			errno: readStringProperty(current, "errno"),
+			message: current.message,
+			requiredScopes: current instanceof PermissionError ? current.requiredScopes : void 0,
+			syscall: readStringProperty(current, "syscall")
+		});
+		current = current.cause;
+	}
+	return entries;
+}
+function formatMissingScopes(scopes) {
+	if (scopes.length === 0) return "API key has insufficient scopes. Add via Creator Dashboard.";
+	const joined = scopes.join(", ");
+	return `API key missing scope${scopes.length === 1 ? "" : "s"} ${joined}. Add via Creator Dashboard.`;
+}
+function readStringProperty(err, key) {
+	const value = Reflect.get(err, key);
+	if (value === void 0 || value === null) return;
+	return String(value);
+}
+//#endregion
 //#region src/backends/open-cloud.ts
 const PARALLEL_AUTO_CAP = 3;
 const BASE_URL_ENV = "JEST_ROBLOX_OPEN_CLOUD_BASE_URL";
@@ -5171,10 +5236,7 @@ function createOpenCloudBackend(credentials) {
 }
 function describeError(err) {
 	const cause = err instanceof Error ? err.cause : void 0;
-	if (cause instanceof PermissionError) {
-		const scopes = cause.requiredScopes.join(", ");
-		return `API key missing scope${cause.requiredScopes.length === 1 ? "" : "s"} ${scopes}. Add via Creator Dashboard.`;
-	}
+	if (cause instanceof PermissionError) return formatMissingScopes(cause.requiredScopes);
 	return err instanceof Error ? err.message : String(err);
 }
 function warnStreamingDisabled(err, state) {
@@ -5947,6 +6009,27 @@ function narrowConfigByFiles(config, files) {
 		testPathPattern: `(${branches.join("|")})`
 	};
 }
+/**
+* Forward an Instance-namespace `testPathPattern` to the Luau runner.
+*
+* Node-side discovery is the source of truth: the FS-namespace filter
+* (positional args or `--testPathPattern`) has already resolved to a concrete
+* file set against real paths. Drop the raw FS-shaped pattern and re-narrow by
+* the discovered files so Jest-on-Roblox matches the same files — its paths are
+* Roblox Instance names (e.g. `ServerScriptService/...`) with no `src/` prefix,
+* so a raw FS pattern like `src/server/foo.spec` matches zero files there.
+*
+* `filterActive` gates the rewrite: a bare run (no positionals, no
+* `testPathPattern`) leaves the config untouched so the Luau side runs every
+* `testMatch` file rather than a giant basename alternation.
+*/
+function narrowForLuauRun(config, runtimeFiles, filterActive) {
+	if (!filterActive) return config;
+	return narrowConfigByFiles({
+		...config,
+		testPathPattern: void 0
+	}, runtimeFiles);
+}
 function toBasenamePattern(file) {
 	const posix = file.replaceAll("\\", "/");
 	const lastSlash = posix.lastIndexOf("/");
@@ -7972,6 +8055,27 @@ function resolveSetupFilePaths(config) {
 	resolveAllSetupFilePaths([config]);
 }
 //#endregion
+//#region src/run/run-header.ts
+/**
+* Print the ` RUN  vX.Y  <rootDir>` header to stdout at the moment a run begins
+* (right before the backend uploads), so the CLI doesn't look stalled while it
+* waits for remote results. The end-of-run formatters no longer emit it.
+*
+* Self-gates to the default human formatter: nothing is written under
+* `--silent`, `--formatters json`, or `--formatters agent` (without
+* `--verbose`), which produce machine-readable output that must stay clean.
+*/
+function emitRunHeader(input) {
+	if (!isDefaultHumanFormatter(input)) return;
+	process.stdout.write(formatRunHeader({
+		collectCoverage: input.collectCoverage,
+		color: input.color,
+		rootDir: input.rootDir,
+		verbose: input.verbose ?? false,
+		version: input.version
+	}));
+}
+//#endregion
 //#region src/run/multi.ts
 const DEFAULT_ROJO_PROJECT = "default.project.json";
 const VERSION$2 = version;
@@ -8015,6 +8119,15 @@ async function runMultiProject(options) {
 			rootConfig
 		});
 	});
+	if (pendingJobs.length > 0) emitRunHeader({
+		collectCoverage: rootConfig.collectCoverage,
+		color: rootConfig.color,
+		formatters: rootConfig.formatters,
+		rootDir: rootConfig.rootDir,
+		silent: rootConfig.silent,
+		verbose: rootConfig.verbose,
+		version: VERSION$2
+	});
 	const projectResults = await runJobs(backend, pendingJobs, parallel, timing);
 	const uniqueTypeTestFiles = [...new Set(allTypeTestFiles)];
 	const typecheckResult = uniqueTypeTestFiles.length > 0 ? timing.profile("runTypecheck", () => {
@@ -8086,10 +8199,11 @@ function collectPendingJobs(arguments_) {
 			testMatch: project.include
 		};
 		const { runtimeFiles, typeTestFiles } = classifyTestFiles(discoverTestFiles(discoveryConfig, projectCliFiles).files, rootConfig);
-		const projConfig = narrowConfigByFiles({
+		const filterActive = (projectCliFiles?.length ?? 0) > 0 || discoveryConfig.testPathPattern !== void 0;
+		const projConfig = narrowForLuauRun({
 			...discoveryConfig,
 			testMatch: project.testMatch
-		}, projectCliFiles ?? []);
+		}, runtimeFiles, filterActive);
 		allTypeTestFiles.push(...typeTestFiles);
 		if (runtimeFiles.length === 0) continue;
 		const runtimeInjectionPaths = [];
@@ -8212,15 +8326,15 @@ const VERSION$1 = version;
 async function runSingleProject(options) {
 	const { cli } = options;
 	const timing = options.timing ?? NOOP_TIMING_COLLECTOR;
-	const config = timing.profile("narrowConfigByFiles", () => {
-		return narrowConfigByFiles(options.config, cli.files ?? []);
-	});
+	const baseConfig = { ...options.config };
 	timing.profile("resolveSetupFilePaths", () => {
-		resolveSetupFilePaths(config);
+		resolveSetupFilePaths(baseConfig);
+	});
+	const discovery = timing.profile("discoverTestFiles", () => {
+		return discoverTestFiles(baseConfig, cli.files);
 	});
-	const discovery = timing.profile("discoverTestFiles", () => discoverTestFiles(config, cli.files));
 	if (discovery.files.length === 0) {
-		if (config.passWithNoTests) return {
+		if (baseConfig.passWithNoTests) return {
 			mode: "single",
 			preCoverageMs: 0
 		};
@@ -8232,7 +8346,11 @@ async function runSingleProject(options) {
 		};
 	}
 	const { runtimeFiles, typeTestFiles } = timing.profile("classifyTestFiles", () => {
-		return classifyTestFiles(discovery.files, config);
+		return classifyTestFiles(discovery.files, baseConfig);
+	});
+	const filterActive = (cli.files?.length ?? 0) > 0 || baseConfig.testPathPattern !== void 0;
+	const config = timing.profile("narrowForLuauRun", () => {
+		return narrowForLuauRun(baseConfig, runtimeFiles, filterActive);
 	});
 	if (typeTestFiles.length === 0 && runtimeFiles.length === 0) {
 		if (config.passWithNoTests) return {
@@ -8280,7 +8398,17 @@ async function runSingleProject(options) {
 }
 async function executeRuntimeTests(options) {
 	const { cli, config, testFiles, timing, totalFiles } = options;
-	if (!config.silent && !usesAgentFormatter(config.formatters, config.verbose) && !hasFormatter(config.formatters, "json") && testFiles.length !== totalFiles) process.stderr.write(`Running ${String(testFiles.length)} of ${String(totalFiles)} test files\n`);
+	const useDefaultFormatter = isDefaultHumanFormatter(config);
+	emitRunHeader({
+		collectCoverage: config.collectCoverage,
+		color: config.color,
+		formatters: config.formatters,
+		rootDir: config.rootDir,
+		silent: config.silent,
+		verbose: config.verbose,
+		version: VERSION$1
+	});
+	if (useDefaultFormatter && testFiles.length !== totalFiles) process.stderr.write(`Running ${String(testFiles.length)} of ${String(totalFiles)} test files\n`);
 	const backend = await timing.profileAsync("resolveBackend", async () => {
 		return resolveBackend(cli, config);
 	});
@@ -9213,13 +9341,33 @@ async function prepareWorkspaceDispatch(input) {
 	}
 	return { scriptOverride: generateMaterializerScript(inputs) };
 }
+/**
+* Resolve a `--testPathPattern` against this package's files Node-side, then
+* forward an Instance-namespace basename pattern (see {@link narrowForLuauRun}).
+*
+* A pattern that matches no file in this package simply targets a different
+* package: keep the (zero-matching) raw pattern so Jest-on-Roblox runs nothing,
+* and set `passWithNoTests` so it doesn't `exit(1)`. The raw pattern is
+* load-bearing here — clearing it would drop the filter entirely and make the
+* Luau side fall back to `testMatch`, running the whole package.
+*/
+function narrowPackageTestPathPattern(packageConfig) {
+	if (packageConfig.testPathPattern === void 0) return packageConfig;
+	const { files } = discoverTestFiles(packageConfig);
+	const { runtimeFiles } = classifyTestFiles(files, packageConfig);
+	if (runtimeFiles.length === 0) return {
+		...packageConfig,
+		passWithNoTests: true
+	};
+	return narrowForLuauRun(packageConfig, runtimeFiles, true);
+}
 async function loadPackages(input) {
 	const { cli, packageInfos, timing } = input;
 	const loaded = [];
 	for (const info of packageInfos) {
-		const packageConfig = mergeCliWithConfig(cli, await timing.profileAsync(`load-config:${info.name}`, async () => {
+		const packageConfig = narrowPackageTestPathPattern(mergeCliWithConfig(cli, await timing.profileAsync(`load-config:${info.name}`, async () => {
 			return loadConfig$1(void 0, info.packageDirectory);
-		}));
+		})));
 		const rojoProject = packageConfig.rojoProject ?? ROJO_PROJECT_DEFAULT;
 		const hasExplicitIgnore = packageConfig.coveragePathIgnorePatterns !== DEFAULT_CONFIG.coveragePathIgnorePatterns;
 		const hasExplicitCoverageCache = packageConfig.coverageCache !== DEFAULT_CONFIG.coverageCache;
@@ -9811,6 +9959,14 @@ async function runWorkspaceMode(cli, workspace, timing) {
 	}
 	let runtimeResults;
 	try {
+		emitRunHeader({
+			color: runOptions.color,
+			formatters: runOptions.formatters,
+			rootDir: workspaceRoot,
+			silent: runOptions.silent,
+			verbose: cli.verbose,
+			version: VERSION
+		});
 		const onStreamingResult = resolveStreamingProgressSink(runOptions, cli);
 		runtimeResults = await runWorkspace({
 			backend,
@@ -9908,8 +10064,11 @@ function composeWorkspaceDisplayName(package_, project) {
 * either break the structured output or be silenced anyway.
 */
 function resolveStreamingProgressSink(runOptions, cli) {
-	if (runOptions.silent) return;
-	if (hasFormatter(runOptions.formatters, "json") || usesAgentFormatter(runOptions.formatters, cli.verbose)) return;
+	if (!isDefaultHumanFormatter({
+		formatters: runOptions.formatters,
+		silent: runOptions.silent,
+		verbose: cli.verbose
+	})) return;
 	return (entry) => {
 		const line = formatStreamingProgressLine(entry, { color: runOptions.color });
 		process.stdout.write(`${line}\n`);
@@ -9942,4 +10101,4 @@ async function runJestRoblox(cli, config) {
 	}
 }
 //#endregion
-export { mergeCliWithConfig as A, defineProject as B, formatFailure as C, LuauScriptError as D, formatBanner as E, JEST_ARGV_EXCLUDED_KEYS as F, ConfigError as H, ROOT_CLI_KEYS as I, SHARED_TEST_KEYS as L, resolveConfig as M, DEFAULT_CONFIG as N, extractJsonFromOutput as O, GLOBAL_TEST_KEYS as P, VALID_BACKENDS as R, writeJsonFile$1 as S, formatTestSummary as T, version as U, isValidBackend as V, runProjects as _, visitStatement as a, writeGameOutput as b, OpenCloudBackend as c, generateTestScript as d, outputMultiResult as f, formatExecuteOutput as g, formatJobSummary as h, visitExpression as i, loadConfig$1 as j, parseJestOutput as k, createOpenCloudBackend as l, formatAnnotations as m, runTypecheck as n, StudioBackend as o, outputSingleResult as p, visitBlock as r, createStudioBackend as s, runJestRoblox as t, buildJestArgv as u, formatGameOutputNotice as v, formatResult as w, formatJson as x, parseGameOutput as y, defineConfig as z };
+export { extractJsonFromOutput as A, VALID_BACKENDS as B, formatJson as C, formatTestSummary as D, formatResult as E, DEFAULT_CONFIG as F, version as G, defineProject as H, GLOBAL_TEST_KEYS as I, JEST_ARGV_EXCLUDED_KEYS as L, mergeCliWithConfig as M, loadConfig$1 as N, formatBanner as O, resolveConfig as P, ROOT_CLI_KEYS as R, writeGameOutput as S, formatFailure as T, isValidBackend as U, defineConfig as V, ConfigError as W, formatJobSummary as _, visitStatement as a, formatGameOutputNotice as b, OpenCloudBackend as c, walkErrorChain as d, buildJestArgv as f, formatAnnotations as g, outputSingleResult as h, visitExpression as i, parseJestOutput as j, LuauScriptError as k, createOpenCloudBackend as l, outputMultiResult as m, runTypecheck as n, StudioBackend as o, generateTestScript as p, visitBlock as r, createStudioBackend as s, runJestRoblox as t, formatMissingScopes as u, formatExecuteOutput as v, writeJsonFile$1 as w, parseGameOutput as x, runProjects as y, SHARED_TEST_KEYS as z };

package/dist/sea-entry.cjs

@@ -686,7 +686,7 @@ function C$4({ force: e } = {}) {
 var y$3 = C$4();
 //#endregion
 //#region package.json
-var version = "0.3.1";
+var version = "0.3.2";
 //#endregion
 //#region src/config/errors.ts
 var ConfigError = class extends Error {
@@ -20150,12 +20150,35 @@ function mapBranchArmLocations(traceMap, locations, sourceMapDirectory) {
 		tsPath
 	};
 }
+/**
+* Detects a phantom branch arm produced by a source-less synthetic statement
+* `if` (e.g. a roblox-ts Array polyfill like `.filter`/`.includes`). The
+* synthetic `if` has no source map entry, so trace-mapping's greatest-lower-
+* bound bias snaps both arms onto the nearest preceding segment — the then-
+* arm's own start — yielding a zero-width arm that coincides with another
+* arm's start and can never be covered.
+*
+* A genuine statement `if` is safe: roblox-ts always renders it multi-line, so
+* the then-body (generated line `if+1`) and the implicit-else arm (generated
+* line `if`) carry distinct source-map segments and never collapse. This is
+* gated to `type === "if"` by the caller: a single-line `expr-if` (ternary)
+* legitimately collapses to one column-0 segment and must NOT be dropped.
+*/
+function hasCollapsedPhantomArm(locations) {
+	return locations.some((arm, index) => {
+		if (!(arm.start.line === arm.end.line && arm.start.column === arm.end.column)) return false;
+		return locations.some((other, otherIndex) => {
+			return otherIndex !== index && other.start.line === arm.start.line && other.start.column === arm.start.column;
+		});
+	});
+}
 function mapFileBranches(resources, fileCoverage, pendingBranches) {
 	if (resources.coverageMap.branchMap === void 0) return;
 	for (const [branchId, entry] of Object.entries(resources.coverageMap.branchMap)) {
 		const armHitCounts = fileCoverage.b?.[branchId] ?? [];
 		const result = mapBranchArmLocations(resources.traceMap, entry.locations, resources.sourceMapDirectory);
 		if (result === void 0) continue;
+		if (entry.type === "if" && hasCollapsedPhantomArm(result.locations)) continue;
 		let fileBranches = pendingBranches.get(result.tsPath);
 		if (fileBranches === void 0) {
 			fileBranches = [];
@@ -25919,6 +25942,7 @@ function findMapping(filePath, mappings, key = "outDir") {
 }
 function replacePrefix(filePath, from, to) {
 	if (filePath === from) return to;
+	if (from === ".") return `${to}/${filePath.startsWith("./") ? filePath.slice(2) : filePath}`;
 	if (filePath.startsWith(`${from}/`)) return `${to}${filePath.slice(from.length)}`;
 	return filePath;
 }
@@ -26758,7 +26782,7 @@ var core_default = (/* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exp
 			}
 		});
 	};
-	var MODES = /* @__PURE__ */ Object.freeze({
+	var MODES = /*#__PURE__*/ Object.freeze({
 		__proto__: null,
 		APOS_STRING_MODE,
 		BACKSLASH_ESCAPE,
@@ -29055,7 +29079,7 @@ function formatTestSummary(result, timing, styles, options) {
 }
 function formatResult(result, timing, options) {
 	const styles = createStyles(options.color, options.slowTestThreshold);
-	const lines = [formatRunHeader(options, styles)];
+	const lines = [""];
 	for (const file of result.testResults) {
 		if (options.failuresOnly === true && file.numFailingTests === 0 && !hasExecError(file)) continue;
 		lines.push(formatFileSummary(file, options, styles));
@@ -29229,7 +29253,7 @@ function formatMultiProjectResult(projects, timing, options) {
 		result,
 		styles
 	}));
-	const lines = [formatRunHeader(options, styles), sections.join("\n\n")];
+	const lines = ["", sections.join("\n\n")];
 	const mergedResult = mergeJestResults(projects.map((project) => project.result));
 	lines.push("", formatTestSummary(mergedResult, timing, styles, {
 		snapshotWriteFailures: options.snapshotWriteFailures,
@@ -30036,6 +30060,15 @@ function hasFormatter(formatters, name) {
 function usesAgentFormatter(formatters, verbose = false) {
 	return hasFormatter(formatters, "agent") && !verbose;
 }
+/**
+* Whether human-facing progress output (the run header, the "Running X of Y"
+* notice, the workspace streaming lines) should be written: not silent and not
+* a machine-readable formatter (json, or non-verbose agent). The single source
+* of truth so these sinks can't drift apart.
+*/
+function isDefaultHumanFormatter(options) {
+	return options.silent !== true && !usesAgentFormatter(options.formatters, options.verbose) && !hasFormatter(options.formatters, "json");
+}
 //#endregion
 //#region src/snapshot/path-resolver.ts
 function createSnapshotPathResolver(config) {
@@ -37469,7 +37502,10 @@ var OcaleRunner = class {
 			script,
 			timeoutSeconds,
 			universeId: this.credentials.universeId
-		}, { timeoutMs: timeout });
+		}, {
+			retryableTransportCodes: TRANSIENT_TRANSPORT_CODES,
+			timeoutMs: timeout
+		});
 		if (!result.success) {
 			if (result.err instanceof PollTimeoutError) throw new Error("Execution timed out", { cause: result.err });
 			throw new Error(result.err.message, { cause: result.err });
@@ -37491,7 +37527,7 @@ var OcaleRunner = class {
 			placeId: this.credentials.placeId,
 			universeId: this.credentials.universeId
 		};
-		const result = await this.places.save(parameters);
+		const result = await this.places.save(parameters, { retryableTransportCodes: TRANSIENT_TRANSPORT_CODES });
 		if (!result.success) throw new Error(`Failed to upload place: ${result.err.message}`, { cause: result.err });
 		return {
 			uploadMs: Date.now() - uploadStart,
@@ -37609,6 +37645,35 @@ function generateTestScript(options) {
 	return test_runner_bundled_default.replace("__CONFIG_JSON__", () => JSON.stringify({ configs }));
 }
 //#endregion
+//#region src/utils/error-chain.ts
+const MAX_DEPTH = 5;
+function walkErrorChain(err) {
+	const entries = [];
+	let current = err;
+	while (current instanceof Error && entries.length < MAX_DEPTH) {
+		entries.push({
+			name: current.constructor.name,
+			code: readStringProperty(current, "code"),
+			errno: readStringProperty(current, "errno"),
+			message: current.message,
+			requiredScopes: current instanceof PermissionError ? current.requiredScopes : void 0,
+			syscall: readStringProperty(current, "syscall")
+		});
+		current = current.cause;
+	}
+	return entries;
+}
+function formatMissingScopes(scopes) {
+	if (scopes.length === 0) return "API key has insufficient scopes. Add via Creator Dashboard.";
+	const joined = scopes.join(", ");
+	return `API key missing scope${scopes.length === 1 ? "" : "s"} ${joined}. Add via Creator Dashboard.`;
+}
+function readStringProperty(err, key) {
+	const value = Reflect.get(err, key);
+	if (value === void 0 || value === null) return;
+	return String(value);
+}
+//#endregion
 //#region src/backends/open-cloud.ts
 const PARALLEL_AUTO_CAP = 3;
 const BASE_URL_ENV = "JEST_ROBLOX_OPEN_CLOUD_BASE_URL";
@@ -37744,10 +37809,7 @@ function createOpenCloudBackend(credentials) {
 }
 function describeError(err) {
 	const cause = err instanceof Error ? err.cause : void 0;
-	if (cause instanceof PermissionError) {
-		const scopes = cause.requiredScopes.join(", ");
-		return `API key missing scope${cause.requiredScopes.length === 1 ? "" : "s"} ${scopes}. Add via Creator Dashboard.`;
-	}
+	if (cause instanceof PermissionError) return formatMissingScopes(cause.requiredScopes);
 	return err instanceof Error ? err.message : String(err);
 }
 function warnStreamingDisabled(err, state) {
@@ -38520,6 +38582,27 @@ function narrowConfigByFiles(config, files) {
 		testPathPattern: `(${branches.join("|")})`
 	};
 }
+/**
+* Forward an Instance-namespace `testPathPattern` to the Luau runner.
+*
+* Node-side discovery is the source of truth: the FS-namespace filter
+* (positional args or `--testPathPattern`) has already resolved to a concrete
+* file set against real paths. Drop the raw FS-shaped pattern and re-narrow by
+* the discovered files so Jest-on-Roblox matches the same files — its paths are
+* Roblox Instance names (e.g. `ServerScriptService/...`) with no `src/` prefix,
+* so a raw FS pattern like `src/server/foo.spec` matches zero files there.
+*
+* `filterActive` gates the rewrite: a bare run (no positionals, no
+* `testPathPattern`) leaves the config untouched so the Luau side runs every
+* `testMatch` file rather than a giant basename alternation.
+*/
+function narrowForLuauRun(config, runtimeFiles, filterActive) {
+	if (!filterActive) return config;
+	return narrowConfigByFiles({
+		...config,
+		testPathPattern: void 0
+	}, runtimeFiles);
+}
 function toBasenamePattern(file) {
 	const posix = file.replaceAll("\\", "/");
 	const lastSlash = posix.lastIndexOf("/");
@@ -40549,6 +40632,27 @@ function resolveSetupFilePaths(config) {
 	resolveAllSetupFilePaths([config]);
 }
 //#endregion
+//#region src/run/run-header.ts
+/**
+* Print the ` RUN  vX.Y  <rootDir>` header to stdout at the moment a run begins
+* (right before the backend uploads), so the CLI doesn't look stalled while it
+* waits for remote results. The end-of-run formatters no longer emit it.
+*
+* Self-gates to the default human formatter: nothing is written under
+* `--silent`, `--formatters json`, or `--formatters agent` (without
+* `--verbose`), which produce machine-readable output that must stay clean.
+*/
+function emitRunHeader(input) {
+	if (!isDefaultHumanFormatter(input)) return;
+	node_process.default.stdout.write(formatRunHeader({
+		collectCoverage: input.collectCoverage,
+		color: input.color,
+		rootDir: input.rootDir,
+		verbose: input.verbose ?? false,
+		version: input.version
+	}));
+}
+//#endregion
 //#region src/run/multi.ts
 const DEFAULT_ROJO_PROJECT = "default.project.json";
 const VERSION$3 = version;
@@ -40592,6 +40696,15 @@ async function runMultiProject(options) {
 			rootConfig
 		});
 	});
+	if (pendingJobs.length > 0) emitRunHeader({
+		collectCoverage: rootConfig.collectCoverage,
+		color: rootConfig.color,
+		formatters: rootConfig.formatters,
+		rootDir: rootConfig.rootDir,
+		silent: rootConfig.silent,
+		verbose: rootConfig.verbose,
+		version: VERSION$3
+	});
 	const projectResults = await runJobs(backend, pendingJobs, parallel, timing);
 	const uniqueTypeTestFiles = [...new Set(allTypeTestFiles)];
 	const typecheckResult = uniqueTypeTestFiles.length > 0 ? timing.profile("runTypecheck", () => {
@@ -40663,10 +40776,11 @@ function collectPendingJobs(arguments_) {
 			testMatch: project.include
 		};
 		const { runtimeFiles, typeTestFiles } = classifyTestFiles(discoverTestFiles(discoveryConfig, projectCliFiles).files, rootConfig);
-		const projConfig = narrowConfigByFiles({
+		const filterActive = (projectCliFiles?.length ?? 0) > 0 || discoveryConfig.testPathPattern !== void 0;
+		const projConfig = narrowForLuauRun({
 			...discoveryConfig,
 			testMatch: project.testMatch
-		}, projectCliFiles ?? []);
+		}, runtimeFiles, filterActive);
 		allTypeTestFiles.push(...typeTestFiles);
 		if (runtimeFiles.length === 0) continue;
 		const runtimeInjectionPaths = [];
@@ -40789,15 +40903,15 @@ const VERSION$2 = version;
 async function runSingleProject(options) {
 	const { cli } = options;
 	const timing = options.timing ?? NOOP_TIMING_COLLECTOR;
-	const config = timing.profile("narrowConfigByFiles", () => {
-		return narrowConfigByFiles(options.config, cli.files ?? []);
-	});
+	const baseConfig = { ...options.config };
 	timing.profile("resolveSetupFilePaths", () => {
-		resolveSetupFilePaths(config);
+		resolveSetupFilePaths(baseConfig);
+	});
+	const discovery = timing.profile("discoverTestFiles", () => {
+		return discoverTestFiles(baseConfig, cli.files);
 	});
-	const discovery = timing.profile("discoverTestFiles", () => discoverTestFiles(config, cli.files));
 	if (discovery.files.length === 0) {
-		if (config.passWithNoTests) return {
+		if (baseConfig.passWithNoTests) return {
 			mode: "single",
 			preCoverageMs: 0
 		};
@@ -40809,7 +40923,11 @@ async function runSingleProject(options) {
 		};
 	}
 	const { runtimeFiles, typeTestFiles } = timing.profile("classifyTestFiles", () => {
-		return classifyTestFiles(discovery.files, config);
+		return classifyTestFiles(discovery.files, baseConfig);
+	});
+	const filterActive = (cli.files?.length ?? 0) > 0 || baseConfig.testPathPattern !== void 0;
+	const config = timing.profile("narrowForLuauRun", () => {
+		return narrowForLuauRun(baseConfig, runtimeFiles, filterActive);
 	});
 	if (typeTestFiles.length === 0 && runtimeFiles.length === 0) {
 		if (config.passWithNoTests) return {
@@ -40857,7 +40975,17 @@ async function runSingleProject(options) {
 }
 async function executeRuntimeTests(options) {
 	const { cli, config, testFiles, timing, totalFiles } = options;
-	if (!config.silent && !usesAgentFormatter(config.formatters, config.verbose) && !hasFormatter(config.formatters, "json") && testFiles.length !== totalFiles) node_process.default.stderr.write(`Running ${String(testFiles.length)} of ${String(totalFiles)} test files\n`);
+	const useDefaultFormatter = isDefaultHumanFormatter(config);
+	emitRunHeader({
+		collectCoverage: config.collectCoverage,
+		color: config.color,
+		formatters: config.formatters,
+		rootDir: config.rootDir,
+		silent: config.silent,
+		verbose: config.verbose,
+		version: VERSION$2
+	});
+	if (useDefaultFormatter && testFiles.length !== totalFiles) node_process.default.stderr.write(`Running ${String(testFiles.length)} of ${String(totalFiles)} test files\n`);
 	const backend = await timing.profileAsync("resolveBackend", async () => {
 		return resolveBackend(cli, config);
 	});
@@ -41790,13 +41918,33 @@ async function prepareWorkspaceDispatch(input) {
 	}
 	return { scriptOverride: generateMaterializerScript(inputs) };
 }
+/**
+* Resolve a `--testPathPattern` against this package's files Node-side, then
+* forward an Instance-namespace basename pattern (see {@link narrowForLuauRun}).
+*
+* A pattern that matches no file in this package simply targets a different
+* package: keep the (zero-matching) raw pattern so Jest-on-Roblox runs nothing,
+* and set `passWithNoTests` so it doesn't `exit(1)`. The raw pattern is
+* load-bearing here — clearing it would drop the filter entirely and make the
+* Luau side fall back to `testMatch`, running the whole package.
+*/
+function narrowPackageTestPathPattern(packageConfig) {
+	if (packageConfig.testPathPattern === void 0) return packageConfig;
+	const { files } = discoverTestFiles(packageConfig);
+	const { runtimeFiles } = classifyTestFiles(files, packageConfig);
+	if (runtimeFiles.length === 0) return {
+		...packageConfig,
+		passWithNoTests: true
+	};
+	return narrowForLuauRun(packageConfig, runtimeFiles, true);
+}
 async function loadPackages(input) {
 	const { cli, packageInfos, timing } = input;
 	const loaded = [];
 	for (const info of packageInfos) {
-		const packageConfig = mergeCliWithConfig(cli, await timing.profileAsync(`load-config:${info.name}`, async () => {
+		const packageConfig = narrowPackageTestPathPattern(mergeCliWithConfig(cli, await timing.profileAsync(`load-config:${info.name}`, async () => {
 			return loadConfig(void 0, info.packageDirectory);
-		}));
+		})));
 		const rojoProject = packageConfig.rojoProject ?? ROJO_PROJECT_DEFAULT;
 		const hasExplicitIgnore = packageConfig.coveragePathIgnorePatterns !== DEFAULT_CONFIG.coveragePathIgnorePatterns;
 		const hasExplicitCoverageCache = packageConfig.coverageCache !== DEFAULT_CONFIG.coverageCache;
@@ -42389,6 +42537,14 @@ async function runWorkspaceMode(cli, workspace, timing) {
 	}
 	let runtimeResults;
 	try {
+		emitRunHeader({
+			color: runOptions.color,
+			formatters: runOptions.formatters,
+			rootDir: workspaceRoot,
+			silent: runOptions.silent,
+			verbose: cli.verbose,
+			version: VERSION$1
+		});
 		const onStreamingResult = resolveStreamingProgressSink(runOptions, cli);
 		runtimeResults = await runWorkspace({
 			backend,
@@ -42486,8 +42642,11 @@ function composeWorkspaceDisplayName(package_, project) {
 * either break the structured output or be silenced anyway.
 */
 function resolveStreamingProgressSink(runOptions, cli) {
-	if (runOptions.silent) return;
-	if (hasFormatter(runOptions.formatters, "json") || usesAgentFormatter(runOptions.formatters, cli.verbose)) return;
+	if (!isDefaultHumanFormatter({
+		formatters: runOptions.formatters,
+		silent: runOptions.silent,
+		verbose: cli.verbose
+	})) return;
 	return (entry) => {
 		const line = formatStreamingProgressLine(entry, { color: runOptions.color });
 		node_process.default.stdout.write(`${line}\n`);
@@ -42520,29 +42679,6 @@ async function runJestRoblox(cli, config) {
 	}
 }
 //#endregion
-//#region src/utils/error-chain.ts
-const MAX_DEPTH = 5;
-function walkErrorChain(err) {
-	const entries = [];
-	let current = err;
-	while (current instanceof Error && entries.length < MAX_DEPTH) {
-		entries.push({
-			name: current.constructor.name,
-			code: readStringProperty(current, "code"),
-			errno: readStringProperty(current, "errno"),
-			message: current.message,
-			syscall: readStringProperty(current, "syscall")
-		});
-		current = current.cause;
-	}
-	return entries;
-}
-function readStringProperty(err, key) {
-	const value = Reflect.get(err, key);
-	if (value === void 0 || value === null) return;
-	return String(value);
-}
-//#endregion
 //#region src/cli.ts
 const VERSION = version;
 const HELP_TEXT = `
@@ -42564,6 +42700,7 @@ Options:
   --no-color                        Disable colored output
   -u, --updateSnapshot              Update snapshot files
   --coverage                        Enable coverage collection
+  --no-coverage                     Disable coverage for this run (overrides config)
   --collectCoverageFrom <glob>      Globs for files to include in coverage (repeatable)
   --coverageDirectory <path>        Directory for coverage output (default: coverage)
   --coverageReporters <r...>        Coverage reporters (default: text, lcov)
@@ -42607,6 +42744,7 @@ Examples:
   jest-roblox -t "should spawn"       Run tests matching pattern
   jest-roblox --formatters json       Output JSON to file
   jest-roblox --coverage              Run tests with coverage instrumentation
+  jest-roblox --no-coverage           Skip coverage instrumentation for this run
 `;
 function parseArgs(args) {
 	const { positionals, values } = (0, node_util.parseArgs)({
@@ -42639,6 +42777,7 @@ function parseArgs(args) {
 				type: "boolean"
 			},
 			"no-color": { type: "boolean" },
+			"no-coverage": { type: "boolean" },
 			"no-coverage-cache": { type: "boolean" },
 			"no-show-luau": { type: "boolean" },
 			"outputFile": { type: "string" },
@@ -42693,7 +42832,7 @@ function parseArgs(args) {
 		affectedSince: values["affected-since"],
 		apiKey: values.apiKey,
 		backend: validateBackend(values.backend),
-		collectCoverage: values.coverage,
+		collectCoverage: values["no-coverage"] === true ? false : values.coverage,
 		collectCoverageFrom: values.collectCoverageFrom,
 		color: values["no-color"] === true ? false : values.color,
 		config: values.config,
@@ -42805,6 +42944,7 @@ function formatBackendErrorBanner(err) {
 		const extras = formatChainExtras(entry);
 		const label = y$3.dim(`[${index.toString()}]`);
 		body.push(`    ${label} ${entry.name}: ${entry.message}${extras}`);
+		if (entry.requiredScopes !== void 0) body.push(`        ${y$3.yellow(formatMissingScopes(entry.requiredScopes))}`);
 	}
 	return formatBanner({
 		body,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isentinel/jest-roblox",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Jest-compatible CLI for running roblox-ts tests via Roblox Open Cloud",
   "keywords": [
     "jest",
@@ -59,7 +59,7 @@
   },
   "devDependencies": {
     "@isentinel/eslint-config": "5.0.0-beta.11",
-    "@isentinel/roblox-ts": "4.0.5",
+    "@isentinel/roblox-ts": "4.0.6",
     "@isentinel/tsconfig": "1.2.0",
     "@isentinel/weld": "0.2.0",
     "@oxc-project/types": "0.123.0",