@apifuse/provider-sdk 2.2.0-beta.67 → 2.2.0-beta.69

package/AUTHORING.md

@@ -345,7 +345,12 @@ a Web `Response` or `{ status, headers, body }`; an unmatched call fails with
 the operation, transport, and method named in the error. Browser handlers expose
 method-level calls such as `goto`, `evaluate`, and `locator.click`, so provide a
 canned result for each method the handler uses. Native connections similarly
-identify `connectTcp`/`connectTls` and subsequent `write` calls. Direct global
+identify `connectTcp`/`connectTls` and subsequent `write` calls. The offline
+`ctx.stealth` rejects a stealth-owned request header (`User-Agent`,
+`Sec-Fetch-*`, `sec-ch-ua*`, ...) with `STEALTH_HEADER_OVERRIDE_UNSUPPORTED`
+before calling the stub, through the same check the production transport runs,
+so a header spread from a shared constants module or read from a variable fails
+the test instead of the first production request. Direct global
 `fetch` or socket usage is outside this ProviderContext seam and should not be
 used by provider handlers.
 
@@ -680,6 +685,31 @@ The registered mappings are:
 | Unregistered input `ValidationError` code | 400 |
 | Other unregistered `ProviderError` code | 500 |
 
+A registered code that names an upstream outcome also carries a category. When
+a `ProviderError` (or any subclass, `ValidationError` included) with one of
+these codes sets no `category`, the server reports the code's category in
+`X-ApiFuse-Error-Observability`, and the public `source` follows from it:
+
+| Error code | Category when unset | `source` |
+| --- | --- | --- |
+| `NOT_FOUND`, `not_found`, `NO_DATA` | `upstream_http` | `upstream_failure` |
+| `RATE_LIMITED`, `UPSTREAM_RATE_LIMIT`, `LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR` | `upstream_rate_limited` | `upstream_rule` |
+| `UPSTREAM_REJECTED` | `upstream_rejected` | `upstream_rule` |
+| `UPSTREAM_ERROR` | `upstream_http` | `upstream_failure` |
+| `BLOCKED` | `anti_bot_blocked` | `upstream_failure` |
+| `UPSTREAM_AUTH_ERROR` | `upstream_auth` | `upstream_failure` |
+| `UPSTREAM_SCHEMA_ERROR` | `upstream_schema_drift` | `upstream_failure` |
+
+So `throw new ProviderError("…", { code: "UPSTREAM_SCHEMA_ERROR" })` is enough
+for the health monitor to grade a drifted upstream `down`; without the
+category it would be served as `source: "apifuse"` and graded unknown. An
+explicit `category` always wins, an operation-declared rejection status
+(409/410/422) still classifies as `upstream_rejected`, and retryability does
+not follow the category: it stays the instance option, then the declaration,
+then `false`. Every other code, including `AUTH_REQUIRED`, `INVALID_REQUEST`,
+and your own codes, is classified as before (`provider_error` unless you set a
+category).
+
 An unregistered non-validation `ProviderError` code returns HTTP 500 and emits
 the greppable `unregistered_provider_error_code` signal with the code in the
 structured failure log. A matching operation declaration, including one that
@@ -701,7 +731,9 @@ SDK-owned and keep their 502/504 mapping.
   refused a *platform-managed* service key. The caller holds no credential, so
   401 ("re-authenticate") asks for something the caller cannot do, and 502
   ("the upstream is sick") promises a recovery that will never arrive. It is a
-  deployment/config defect, exactly like `MISSING_SECRET`.
+  deployment/config defect, exactly like `MISSING_SECRET`. The status is about
+  what the caller can do; the attribution is still the upstream's, since the
+  upstream is what refused the key, so the category is `upstream_auth`.
 - `UPSTREAM_SCHEMA_ERROR` is non-retryable: a retry returns the same payload
   the provider already could not normalize.
 - `INVALID_REQUEST` is the spelling for caller-side bad input. `INVALID_INPUT`,

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.69
+
+- Release candidate for main commit 0f4bd33ef5bd41cb6813005e923abf4324158582.
+
+## 2.2.0-beta.68
+
+- Release candidate for main commit d630a344c18b2b192edfd09ef92bc30a482b6b8d.
+
 ## 2.2.0-beta.67
 
 - Release candidate for main commit 9ef92b86b293253597801e29764d76beb0a3f3b7.

package/README.md

@@ -148,8 +148,12 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   `ctx.stealth.fetch()` when you need browser-like session or cookie control.
   `ctx.stealth.fetch()` uses the `wreq-js`-backed browser stealth transport and
   accepts request controls for `params`, `sensitiveParams`, `proxy`, `timeout`,
-  `maxBodyBytes`, `redirect`, `throwOnHttpError`, and
-  `stealth.insecureSkipVerify`. For login
+  `maxBodyBytes`, `redirect`, `redirectPolicy`, `throwOnHttpError`, and
+  `stealth.insecureSkipVerify`. A followed redirect drops `Authorization` when
+  it leaves the origin and an explicit `Cookie` when it leaves the site (the
+  session cookie jar takes over there); set
+  `redirectPolicy: { mode: "same-origin", maxHops }` to refuse a cross-origin
+  hop with `HttpRedirectError` before any request reaches it. For login
   flows that must inspect intermediate `Location`/`Set-Cookie` headers, create
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
@@ -157,7 +161,10 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   explicitly defaults to `macos`. The transport owns `User-Agent`,
   `Accept-Encoding`, `sec-ch-ua*`, and every `Sec-Fetch-*` header and throws
   `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` if you set one; declare
-  `stealth.requestClass: "navigation" | "xhr" | "post"` instead. Do not pin a
+  `stealth.requestClass: "navigation" | "form-post" | "xhr" | "post"` instead
+  (`form-post` for an HTML form submission). The offline
+  `ctx.stealth` in `runStandardTests` runs the same check, so a provider test
+  fails wherever production would. Do not pin a
   browser version
   or tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
@@ -309,10 +316,14 @@ apifuse bounty-check [path]
 apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 ```
 
-`apifuse record` is for real upstream-backed operations that declare
-`upstream.baseUrl` and call the upstream through `ctx.http` or `ctx.stealth`. The
-generated local-only `ping` operation intentionally has no upstream and should
-be replaced before recording fixtures.
+`apifuse record` is for real upstream-backed operations that call the upstream
+through `ctx.http` or `ctx.stealth`. Absolute request URLs need no declaration; a
+relative URL resolves the way `serve` resolves it — against the operation's
+`upstream.baseUrl`, else the provider's first declared one (`ctx.stealth` then
+falls back to `https://<allowedHosts[0]>`). A relative `ctx.http` URL with no base
+is refused with the `upstream.baseUrl` to declare. The generated local-only `ping`
+operation intentionally has no upstream and should be replaced before recording
+fixtures.
 
 ## Bounty submission readiness
 

package/bin/apifuse-record.ts

@@ -36,6 +36,8 @@ import {
 	resolveLocalConnection,
 } from "../src/cli/local-connection.js";
 import { createCliResolverRuntime } from "../src/cli/resolver-runtime.js";
+import { isAbsoluteUrl } from "../src/runtime/http.js";
+import { getProviderBaseUrl, getProviderStealthBaseUrl } from "../src/runtime/provider.js";
 import { assertProcessEngineModeSupported } from "../src/runtime/engine-mode.js";
 import type { JsonValue } from "../src/contract-json.js";
 import {
@@ -93,6 +95,11 @@ const HELP_TEXT = `Usage: apifuse record [path] --operation <operation> --params
 
 Calls a real upstream-backed operation through ctx.http or ctx.stealth and writes __fixtures__/raw.json.
 
+Absolute request URLs need no declaration. A relative URL resolves the way serve resolves it: against
+the operation's upstream.baseUrl, else the provider's first declared one (ctx.stealth then falls back
+to https://<allowedHosts[0]>). A relative ctx.http URL with no base anywhere is refused and names
+the upstream.baseUrl to declare.
+
 Streaming responses are recorded as evidence (status, selected headers, full-body SHA-256 and byte
 count, plus a ${STREAM_PREVIEW_BYTES}-byte base64 preview). Test replay is evidence-only: ctx.http.stream exposes the
 preview as its body and the original body_sha256/body_bytes as response metadata.
@@ -137,7 +144,7 @@ export async function main() {
 
 		capture = createCaptureContext(
 			provider,
-			resolveOperationBaseUrl(provider, operationName),
+			resolveRecordBaseUrls(provider, operationName),
 			args.sanitize,
 			connection,
 		);
@@ -148,6 +155,7 @@ export async function main() {
 		try {
 			result = await executeOperation(provider, operationName, capture.ctx, parsedParams);
 		} catch (operationError) {
+			capture.throwIfRefused();
 			let partial: unknown;
 			try {
 				partial = await capture.getCapturedRaw();
@@ -172,6 +180,9 @@ export async function main() {
 			);
 			if (telemetryLine) console.log(telemetryLine);
 		}
+		// Checked on success too: an operation that caught the refusal and carried
+		// on would otherwise save a fixture missing the request it never made.
+		capture.throwIfRefused();
 		const captured = await capture.getCapturedRaw();
 
 		if (captured === undefined) {
@@ -534,23 +545,58 @@ async function parseParams(
 	return operation.input ? parseSchema(operation.input, parsed, "record.params") : parsed;
 }
 
-function resolveOperationBaseUrl(provider: ProviderRuntime, operationName: string): string {
-	const baseUrl = provider.operations[operationName]?.upstream?.baseUrl;
-	if (!baseUrl) {
-		throw new Error(
-			`Operation "${operationName}" for provider "${provider.id}" must define upstream.baseUrl.`,
-		);
-	}
+/**
+ * The bases the recorder's `ctx.http` and `ctx.stealth` resolve relative
+ * request URLs against. An absent base means only absolute URLs resolve.
+ */
+export type RecordBaseUrls = {
+	readonly http?: string;
+	readonly stealth?: string;
+};
+
+/**
+ * `upstream.baseUrl` only resolves relative request URLs (and seeds the stealth
+ * cookie jar's default origin); the recorder uses it for nothing else, so an
+ * operation that requests absolute URLs records without one. The operation's
+ * own base wins; otherwise the recorder binds the bases `serve` binds, so a
+ * relative URL resolves in a recording exactly as it does in production.
+ */
+export function resolveRecordBaseUrls(
+	provider: ProviderRuntime,
+	operationName: string,
+): RecordBaseUrls {
+	const declared = provider.operations[operationName]?.upstream?.baseUrl;
+	const own = typeof declared === "string" && declared.length > 0 ? declared : undefined;
+	const http = own ?? getProviderBaseUrl(provider);
+	const stealth = own ?? getProviderStealthBaseUrl(provider);
+	return { ...(http ? { http } : {}), ...(stealth ? { stealth } : {}) };
+}
 
-	return baseUrl;
+/** A request the recorder cannot resolve without a declaration; fails the run even if the operation catches it. */
+class RecordRefusalError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RecordRefusalError";
+	}
 }
 
 export function createCaptureContext(
 	provider: ProviderRuntime,
-	baseUrl: string,
+	baseUrls: RecordBaseUrls,
 	sanitize: boolean,
 	connection?: LocalConnection,
 ) {
+	let refusal: RecordRefusalError | undefined;
+	const refuse = (message: string): never => {
+		refusal ??= new RecordRefusalError(message);
+		throw refusal;
+	};
+	const assertResolvableHttpUrl = (url: string) => {
+		if (baseUrls.http || isAbsoluteUrl(url)) return;
+		refuse(
+			`ctx.http cannot resolve the relative URL "${requestPathForFixture(url)}": no operation of provider "${provider.id}" declares upstream.baseUrl. Declare upstream.baseUrl on the recorded operation, or request an absolute URL.`,
+		);
+	};
 	let nextCaptureOrder = 0;
 	let nextStreamOrdinal = 0;
 	let capturedRaw: JsonValue | undefined;
@@ -610,7 +656,8 @@ export function createCaptureContext(
 		rawCaptures.push({ order, value: json });
 	};
 
-	const http = captureHttpClient(createHttpClient(baseUrl), {
+	const http = captureHttpClient(createHttpClient(baseUrls.http), {
+		assertResolvableUrl: assertResolvableHttpUrl,
 		reserveOrder: reserveCaptureOrder,
 		reserveStreamOrdinal: () => {
 			nextStreamOrdinal += 1;
@@ -619,7 +666,7 @@ export function createCaptureContext(
 		onSensitiveParams: captureSensitiveParams,
 		onResponse: (order, response) => retainRawCapture(order, response.data),
 		onStreamResponse: (order, ordinal, requestUrl, method, response) => {
-			const resolvedRequestUrl = new URL(requestUrl, baseUrl).toString();
+			const resolvedRequestUrl = new URL(requestUrl, baseUrls.http).toString();
 			const request = {
 				ordinal,
 				method,
@@ -642,18 +689,25 @@ export function createCaptureContext(
 			capturedSse = {
 				order,
 				method,
-				path: requestPathForFixture(new URL(requestUrl, baseUrl).toString()),
+				path: requestPathForFixture(new URL(requestUrl, baseUrls.http).toString()),
 			};
 		},
 	});
-	const stealth = proxyStealthClient(
-		createStealthClient(baseUrl, {
-			...(provider.stealth ? { stealth: provider.stealth } : {}),
-		}),
-		captureSensitiveParams,
-		(order, response) => retainRawCapture(order, normalizeCapturedStealthResponse(response)),
-		reserveCaptureOrder,
-	);
+	// Without a base `serve` binds no stealth transport either, so every call is refused.
+	const refuseStealth = (): never =>
+		refuse(
+			`ctx.stealth has no base URL: provider "${provider.id}" declares neither upstream.baseUrl nor allowedHosts. Declare allowedHosts on the provider (serve binds ctx.stealth to https://<allowedHosts[0]>) or upstream.baseUrl on the recorded operation.`,
+		);
+	const stealth: StealthClient = baseUrls.stealth
+		? proxyStealthClient(
+				createStealthClient(baseUrls.stealth, {
+					...(provider.stealth ? { stealth: provider.stealth } : {}),
+				}),
+				captureSensitiveParams,
+				(order, response) => retainRawCapture(order, normalizeCapturedStealthResponse(response)),
+				reserveCaptureOrder,
+			)
+		: { fetch: async () => refuseStealth(), createSession: refuseStealth };
 
 	const providerEnvironment = createProviderEnvironment(
 		process.env,
@@ -723,6 +777,9 @@ export function createCaptureContext(
 	return {
 		ctx,
 		resolverTelemetry,
+		throwIfRefused: () => {
+			if (refusal) throw refusal;
+		},
 		getCapturedRaw: async () => {
 			if (streamCaptures.length === 0) {
 				if (capturedSse) throw unsupportedSseCaptureError(capturedSse);
@@ -843,6 +900,8 @@ function snapshotRequestOptions<T extends SensitiveRequestOptions>(options: T):
 }
 
 type HttpCaptureCallbacks = {
+	/** Throws before the request when the recorder cannot resolve `url`. */
+	assertResolvableUrl(url: string): void;
 	reserveOrder(): number;
 	reserveStreamOrdinal(): number;
 	onSensitiveParams(url: string, options?: RequestOptions): void;
@@ -867,6 +926,7 @@ function captureHttpClient(client: HttpClient, callbacks: HttpCaptureCallbacks):
 		return response;
 	};
 	const captureRequestOptions = (method: PropertyKey, args: unknown[]) => {
+		callbacks.assertResolvableUrl(String(args[0]));
 		const invocation = parseHttpRequestInvocation(method, args);
 		const options = invocation ? requestOptionsFromHttpInvocation(invocation) : undefined;
 		if (!invocation || !options) return;

package/bin/apifuse-submit-check.ts

@@ -4076,18 +4076,37 @@ type MaskCommentsAndStringsOptions = {
 	blankPropertyKeys?: boolean;
 };
 
+// Which literal bodies are blanked alongside comment bodies. "all" blanks
+// every string/template/regex body; "values" does the same but keeps quoted
+// property-key text (only its structural characters are blanked); "none"
+// leaves every literal and all code byte-identical, so only comments go.
+type LiteralMaskMode = "all" | "values" | "none";
+
 export function maskCommentsAndStrings(
 	source: string,
 	fileName = "provider.ts",
 	options: MaskCommentsAndStringsOptions = {},
 ): string {
-	const blankPropertyKeys = options.blankPropertyKeys === true;
-	const cacheKey = `${blankPropertyKeys ? "blank-keys" : "preserve-keys"}\0${source}`;
+	return maskSource(source, fileName, options.blankPropertyKeys === true ? "all" : "values");
+}
+
+// Blanks comment bodies only, from the same TypeScript-lexer comment ranges
+// maskCommentsAndStrings uses: a `//` inside a string, template, or regex is
+// not a comment, and a block comment spanning lines is blanked whole. Line
+// terminators survive, so line N of the result is line N of the source.
+// Throws like maskCommentsAndStrings when the source cannot be parsed.
+export function maskComments(source: string, fileName = "provider.ts"): string {
+	return maskSource(source, fileName, "none");
+}
+
+function maskSource(source: string, fileName: string, literals: LiteralMaskMode): string {
+	const { scriptKind } = maskScriptKind(fileName);
+	const cacheKey = `${literals}\0${scriptKind}\0${source}`;
 	const cached = maskCache.get(cacheKey);
 	if (cached !== undefined) {
 		return cached;
 	}
-	const masked = computeMaskedSource(source, fileName, blankPropertyKeys);
+	const masked = computeMaskedSource(source, fileName, literals);
 	if (maskCache.size >= MASK_CACHE_LIMIT) {
 		const oldest = maskCache.keys().next();
 		if (!oldest.done) {
@@ -4098,13 +4117,34 @@ export function maskCommentsAndStrings(
 	return masked;
 }
 
-function computeMaskedSource(source: string, fileName: string, blankPropertyKeys: boolean): string {
+// The script kind a source is lexed as, from its file name, and the synthetic
+// implementation file name transpileModule parses it under. Declaration files
+// trigger an internal TypeScript Debug Failure when passed to transpileModule,
+// so `.d.ts` (like every other non-JS/JSX/TSX name) parses as `provider.ts`.
+function maskScriptKind(fileName: string): {
+	scriptKind: TS.ScriptKind;
+	syntheticFileName: string;
+} {
+	if (fileName.endsWith(".tsx")) {
+		return { scriptKind: ts.ScriptKind.TSX, syntheticFileName: "provider.tsx" };
+	}
+	if (fileName.endsWith(".jsx")) {
+		return { scriptKind: ts.ScriptKind.JSX, syntheticFileName: "provider.jsx" };
+	}
+	if (/\.[cm]?js$/.test(fileName)) {
+		return { scriptKind: ts.ScriptKind.JS, syntheticFileName: "provider.js" };
+	}
+	return { scriptKind: ts.ScriptKind.TS, syntheticFileName: "provider.ts" };
+}
+
+function computeMaskedSource(source: string, fileName: string, literals: LiteralMaskMode): string {
+	const blankPropertyKeys = literals === "all";
+	const { scriptKind, syntheticFileName } = maskScriptKind(fileName);
 	const transpiled = ts.transpileModule(source, {
-		// Declaration files trigger an internal TypeScript Debug Failure when
-		// passed to transpileModule. Parsing is all we need here, so always use a
-		// synthetic implementation filename while retaining the real filename
-		// for source mapping and sanitized diagnostics below.
-		fileName: "provider.ts",
+		// Parsing is all we need here: parse under the synthetic implementation
+		// filename while retaining the real filename for source mapping and
+		// sanitized diagnostics below.
+		fileName: syntheticFileName,
 		reportDiagnostics: true,
 		compilerOptions: { target: ts.ScriptTarget.Latest },
 	});
@@ -4113,7 +4153,7 @@ function computeMaskedSource(source: string, fileName: string, blankPropertyKeys
 		source,
 		ts.ScriptTarget.Latest,
 		true,
-		ts.ScriptKind.TS,
+		scriptKind,
 	);
 	const parseDiagnostic = transpiled.diagnostics?.[0];
 	if (parseDiagnostic) {
@@ -4144,10 +4184,7 @@ function computeMaskedSource(source: string, fileName: string, blankPropertyKeys
 		}
 	};
 
-	const visit = (node: TS.Node): void => {
-		addCommentRanges(ts.getLeadingCommentRanges(source, node.getFullStart()));
-		addCommentRanges(ts.getTrailingCommentRanges(source, node.getEnd()));
-
+	const maskLiteralBody = (node: TS.Node): void => {
 		const start = node.getStart(sourceFile);
 		if (ts.isStringLiteral(node)) {
 			// Preserve quoted property keys ("response": ...) by default so range/key
@@ -4184,7 +4221,12 @@ function computeMaskedSource(source: string, fileName: string, blankPropertyKeys
 		} else if (node.kind === ts.SyntaxKind.TemplateTail) {
 			maskRange(start + 1, node.end - 1);
 		}
+	};
 
+	const visit = (node: TS.Node): void => {
+		addCommentRanges(ts.getLeadingCommentRanges(source, node.getFullStart()));
+		addCommentRanges(ts.getTrailingCommentRanges(source, node.getEnd()));
+		if (literals !== "none") maskLiteralBody(node);
 		for (const child of node.getChildren(sourceFile)) visit(child);
 	};
 
@@ -5599,18 +5641,18 @@ function findEntropySecretFindings(providerRoot: string, providerId: string): Se
 		if (isEntropySecretExcludedPath(relativePath)) continue;
 		const content = readFileSync(filePath, "utf8");
 		const lines = content.split(/\r?\n/);
-		for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
-			const line = lines[lineIndex] ?? "";
-			for (const candidate of extractStringLiteralCandidates(line)) {
-				const finding = classifyEntropyCandidate({
-					value: candidate,
-					line,
-					file: relativePath,
-					lineNumber: lineIndex + 1,
-					providerId,
-				});
-				if (finding) findings.push(finding);
-			}
+		for (const candidate of extractStringLiteralCandidates(content, relativePath)) {
+			// Context is the whole source line, comment tail included: a
+			// comment that names the value is evidence about it, even though
+			// comment text itself is never a candidate.
+			const finding = classifyEntropyCandidate({
+				value: candidate.value,
+				line: lines[candidate.lineIndex] ?? "",
+				file: relativePath,
+				lineNumber: candidate.lineIndex + 1,
+				providerId,
+			});
+			if (finding) findings.push(finding);
 		}
 	}
 	return findings;
@@ -5626,7 +5668,62 @@ function isEntropySecretExcludedPath(relativePath: string): boolean {
 	);
 }
 
-export function extractStringLiteralCandidates(line: string): string[] {
+export type StringLiteralCandidate = {
+	value: string;
+	// 0-based index of the source line the literal sits on.
+	lineIndex: number;
+};
+
+// Every string-literal candidate (a quoted body of at least
+// ENTROPY_CANDIDATE_MIN_LENGTH characters) in one provider source file.
+// Candidates come from code only. Comments are prose, not values, so each
+// file's own comment syntax is removed before a quote is read:
+// - JS/TS sources: comment trivia is blanked with the TypeScript lexer
+//   (maskComments, the comment ranges the other source lints skip), so `//`
+//   inside a string or regex is not a comment and a `/* … */` block spanning
+//   lines is skipped whole. A backtick in code opens a template literal — a
+//   string value — so it stays a quote form.
+// - Shell sources (.sh/.bash, Dockerfile, entrypoint): `#` starts a comment
+//   when it begins a word outside quotes, and a backtick is command
+//   substitution (code), not a string delimiter.
+// Identifiers are therefore never candidates by construction: a bare name is
+// not a string literal, and a backticked name in a comment is comment text.
+// A JS/TS source the lexer cannot parse keeps the unmasked scan (every quote
+// pair is a candidate): when comments cannot be located the scan may
+// over-report, never under-report.
+export function extractStringLiteralCandidates(
+	content: string,
+	relativePath: string,
+): StringLiteralCandidate[] {
+	const shell = !isJavaScriptFamilySource(relativePath);
+	const codeLines = (shell ? content : maskCommentsForSecretScan(content, relativePath)).split(
+		/\r?\n/,
+	);
+	const candidates: StringLiteralCandidate[] = [];
+	for (let lineIndex = 0; lineIndex < codeLines.length; lineIndex += 1) {
+		const line = codeLines[lineIndex] ?? "";
+		const values = shell ? extractShellLineStrings(line) : extractQuotedLineStrings(line);
+		for (const value of values) candidates.push({ value, lineIndex });
+	}
+	return candidates;
+}
+
+function isJavaScriptFamilySource(relativePath: string): boolean {
+	return /\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(relativePath);
+}
+
+function maskCommentsForSecretScan(content: string, relativePath: string): string {
+	try {
+		return maskComments(content, relativePath);
+	} catch {
+		// Unparseable: scan the source unmasked rather than skip it.
+		return content;
+	}
+}
+
+// Quoted bodies on one comment-free JS/TS line (`"`, `'`, and template
+// backticks), with backslash escapes.
+function extractQuotedLineStrings(line: string): string[] {
 	const candidates: string[] = [];
 	for (let index = 0; index < line.length; index += 1) {
 		const quote = line[index];
@@ -5653,6 +5750,51 @@ export function extractStringLiteralCandidates(line: string): string[] {
 	return candidates;
 }
 
+// Characters after which a `#` begins a new shell word (blanks and the
+// metacharacters `;&|()<>`).
+const SHELL_WORD_BOUNDARY = /[\s;&|()<>]/;
+
+// Quoted bodies on one shell line. Single quotes take no escapes; double
+// quotes and unquoted text honor backslash escapes. A `#` that begins a word
+// outside quotes ends the line's code (the rest is a comment). A word begins
+// at the line start or after an UNESCAPED boundary character, so `${#var}`,
+// `$#`, `"a"#b`, and `word\ #` (escaped blank) keep `#` inside the word.
+// Backticks are command substitution, so their text is lexed as code. A
+// quote left open on the line is read as a literal character, as the
+// line-based scan always has.
+function extractShellLineStrings(line: string): string[] {
+	const candidates: string[] = [];
+	let index = 0;
+	let atWordStart = true;
+	while (index < line.length) {
+		const char = line[index];
+		if (char === "\\") {
+			index += 2;
+			atWordStart = false;
+			continue;
+		}
+		if (char === "#" && atWordStart) break;
+		if (char === '"' || char === "'") {
+			const contentStart = index + 1;
+			let cursor = contentStart;
+			while (cursor < line.length && line[cursor] !== char) {
+				cursor += char === '"' && line[cursor] === "\\" ? 2 : 1;
+			}
+			if (cursor < line.length) {
+				if (cursor - contentStart >= ENTROPY_CANDIDATE_MIN_LENGTH) {
+					candidates.push(line.slice(contentStart, cursor));
+				}
+				index = cursor + 1;
+				atWordStart = false;
+				continue;
+			}
+		}
+		atWordStart = SHELL_WORD_BOUNDARY.test(char ?? "");
+		index += 1;
+	}
+	return candidates;
+}
+
 function classifyEntropyCandidate(input: {
 	value: string;
 	line: string;
@@ -5757,7 +5899,7 @@ function literalContainerKey(literal: LineStringLiteral): string {
 // other literal is a VALUE: ternary arms (preceded by "?" or ":"), array
 // elements, call arguments, and assignment right-hand sides, even when a
 // ternary's ":" happens to follow them. Uses the same quote/escape walking as
-// extractStringLiteralCandidates.
+// extractQuotedLineStrings.
 function tokenizeLineStringLiterals(line: string): LineStringLiteral[] {
 	const literals: LineStringLiteral[] = [];
 	const bracketStack: Array<{ bracket: "[" | "(" | "{"; index: number }> = [];