@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/package-checks/secret-detection/execution.ts

@@ -0,0 +1,247 @@
+import type { CheckExecutionContext, CheckMessage, CheckResult } from "../../check/check.ts";
+import { appendCheckMessages } from "../../check/finding-presentation.ts";
+import { reconcileFindingWaivers } from "../../finding-waivers/reconciliation.ts";
+import { reportFindingWaiverAudits } from "../code-quality-findings/finding-waiver-evidence.ts";
+import { collectProjectFiles } from "../project-files/collection.ts";
+import type { SecretDetectionFinalData } from "./final-data.ts";
+import {
+  prepareSecretDetectionInputs,
+  type ApprovedTextInput,
+  type SecretCoverageGap
+} from "./input-preparation.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+import {
+  secretCoverageGapRecordId,
+  secretDetectionWaiverAuditRecord,
+  secretFindingIdentity,
+  secretFindingRecordId,
+  type SecretDetectionCoverageGapRecordData,
+  type SecretDetectionFindingRecordData
+} from "./records.ts";
+import { detectSecretlintIssues, type SecretDetectionIssue } from "./secretlint/adapter.ts";
+import { validSecretDetectionOptions } from "./options-validation.ts";
+
+export const SECRET_DETECTION_CHECK_DEFINITION = {
+  checkId: "secret-detection",
+  displayName: "Secret detection"
+} as const;
+
+/** `secretDetection` 的 whole-Check unavailable reason；不携带 detector 或 file-system 原始详情。 */
+export type SecretDetectionUnavailableReasonCode =
+  | "detector-protocol-failed"
+  | "detector-unavailable"
+  | "execution-cancelled"
+  | "invalid-options"
+  | "scan-input-unavailable"
+  | "source-unavailable";
+
+/** Executes the fixed in-process detector only for this Check's exact explicit input selection. */
+export async function executeSecretDetection(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>
+): Promise<CheckResult<SecretDetectionFinalData>> {
+  if (!validSecretDetectionOptions(context.options)) return unavailable("invalid-options");
+  if (context.signal.aborted) return unavailable("execution-cancelled");
+
+  let selectedPaths: readonly string[];
+  try {
+    selectedPaths = collectProjectFiles(context.project.root, context.options.files);
+  } catch {
+    return unavailable("scan-input-unavailable");
+  }
+  if (context.signal.aborted) return unavailable("execution-cancelled");
+  if (selectedPaths.length === 0)
+    return settleSecretDetectionFindings(context, selectedPaths.length, [], []);
+
+  const prepared = prepareSecretDetectionInputs(context, selectedPaths);
+  if (prepared.kind === "unavailable") return unavailable("source-unavailable");
+  if (prepared.kind === "cancelled") return unavailable("execution-cancelled");
+
+  const detected = await detectApprovedInputs(context, prepared.inputs);
+  if (detected.kind === "unavailable") return unavailable(detected.code);
+  return settleSecretDetectionFindings(
+    context,
+    selectedPaths.length,
+    detected.issues,
+    prepared.coverageGaps
+  );
+}
+
+type DetectedIssues = Readonly<
+  | { readonly code: SecretDetectionUnavailableReasonCode; readonly kind: "unavailable" }
+  | { readonly issues: readonly SecretDetectionIssue[]; readonly kind: "complete" }
+>;
+
+async function detectApprovedInputs(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>,
+  inputs: readonly ApprovedTextInput[]
+): Promise<DetectedIssues> {
+  const issues: SecretDetectionIssue[] = [];
+  for (const input of inputs) {
+    if (context.signal.aborted)
+      return Object.freeze({ code: "execution-cancelled", kind: "unavailable" });
+    const detected = await detectSecretlintIssues(input.content, input.path);
+    if (context.signal.aborted)
+      return Object.freeze({ code: "execution-cancelled", kind: "unavailable" });
+    if (detected.kind === "unavailable") {
+      return Object.freeze({ code: "detector-unavailable", kind: "unavailable" });
+    }
+    if (detected.kind === "protocol-failed") {
+      return Object.freeze({ code: "detector-protocol-failed", kind: "unavailable" });
+    }
+    issues.push(...detected.issues);
+  }
+  return Object.freeze({ issues: Object.freeze(issues), kind: "complete" });
+}
+
+export function settleSecretDetectionFindings(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>,
+  selectedFileCount: number,
+  issues: readonly SecretDetectionIssue[],
+  coverageGaps: readonly SecretCoverageGap[]
+): CheckResult<SecretDetectionFinalData> {
+  const reconciliation = reconcileFindingWaivers({
+    findings: issues,
+    identify: secretFindingIdentity,
+    waivers: context.options.findingWaivers
+  });
+  const waivedFindingCount = reconciliation.findings.filter(
+    (finding) => finding.disposition === "waived"
+  ).length;
+  for (const finding of reconciliation.findings) {
+    const identity = secretFindingIdentity(finding.finding);
+    const data: SecretDetectionFindingRecordData = Object.freeze({
+      blocking: finding.disposition !== "waived",
+      kind: "secret-finding",
+      location: finding.finding.location,
+      ordinal: identity.ordinal,
+      path: identity.path,
+      ruleId: identity.ruleId,
+      structuralClass: identity.structuralClass,
+      ...(finding.disposition === "waived"
+        ? { waiver: Object.freeze({ reason: finding.waiver.reason }) }
+        : {})
+    });
+    context.records.report({ id: secretFindingRecordId(identity) }, data);
+  }
+  for (const coverageGap of coverageGaps) {
+    const data: SecretDetectionCoverageGapRecordData = Object.freeze({
+      blocking: true,
+      kind: "coverage-gap",
+      path: coverageGap.path,
+      reason: coverageGap.reason
+    });
+    context.records.report({ id: secretCoverageGapRecordId(coverageGap.path) }, data);
+  }
+  reportFindingWaiverAudits(context, reconciliation, secretDetectionWaiverAuditRecord);
+
+  const data = Object.freeze({
+    coverageGapCount: coverageGaps.length,
+    findingCount: issues.length,
+    scannedFileCount: selectedFileCount - coverageGaps.length,
+    selectedFileCount,
+    waivedFindingCount
+  });
+  if (selectedFileCount === 0) {
+    return appendCheckMessages(
+      Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } }),
+      waiverMessages(reconciliation.waiverAudits)
+    );
+  }
+  const actionableFindingCount = issues.length - waivedFindingCount;
+  const result: CheckResult<SecretDetectionFinalData> = Object.freeze({
+    data,
+    status: coverageGaps.length > 0 || actionableFindingCount > 0 ? "failed" : "passed"
+  });
+  return appendCheckMessages(
+    appendCheckMessages(result, findingMessages(actionableFindingCount, coverageGaps.length)),
+    waiverMessages(reconciliation.waiverAudits)
+  );
+}
+
+function findingMessages(
+  actionableFindingCount: number,
+  coverageGapCount: number
+): readonly CheckMessage[] {
+  const messages: CheckMessage[] = [];
+  if (actionableFindingCount > 0) {
+    messages.push(
+      Object.freeze({
+        code: "secret-findings",
+        level: "error",
+        message: `${actionableFindingCount} high-confidence secret finding(s) require attention; inspect this Check's safe Records, remove the material, or author an exact finding waiver.`
+      })
+    );
+  }
+  if (coverageGapCount > 0) {
+    messages.push(
+      Object.freeze({
+        code: "incomplete-coverage",
+        level: "error",
+        message: `${coverageGapCount} selected input(s) could not receive bounded secret detection coverage; narrow files or increase this Check's explicit resource limits.`
+      })
+    );
+  }
+  return Object.freeze(messages);
+}
+
+function waiverMessages(
+  audits: readonly Readonly<{
+    readonly matchCount: number;
+    readonly status: "applied" | "overmatched" | "unused";
+    readonly waiver: Readonly<{ readonly reason: string }>;
+  }>[]
+): readonly CheckMessage[] {
+  const messages: CheckMessage[] = [];
+  for (const audit of audits) {
+    if (audit.status === "applied") {
+      messages.push(
+        Object.freeze({
+          code: "finding-waived",
+          level: "info",
+          message: `A secret finding was waived: ${audit.waiver.reason}`
+        })
+      );
+      continue;
+    }
+    messages.push(
+      Object.freeze({
+        code: audit.status === "unused" ? "unused-finding-waiver" : "overmatched-finding-waiver",
+        level: "warning",
+        message:
+          audit.status === "unused"
+            ? `A configured secret finding waiver matched no finding; remove or update it. Reason: ${audit.waiver.reason}`
+            : `A configured secret finding waiver matched ${audit.matchCount} findings and was not applied; narrow it. Reason: ${audit.waiver.reason}`
+      })
+    );
+  }
+  return Object.freeze(messages);
+}
+
+function unavailable(
+  code: SecretDetectionUnavailableReasonCode
+): CheckResult<SecretDetectionFinalData> {
+  return Object.freeze({
+    messages: Object.freeze([
+      Object.freeze({ code, level: "error" as const, message: unavailableMessage(code) })
+    ]),
+    reason: { code },
+    status: "unavailable"
+  });
+}
+
+function unavailableMessage(code: SecretDetectionUnavailableReasonCode): string {
+  switch (code) {
+    case "invalid-options":
+      return "secretDetection options are invalid; recreate the Check with its documented explicit files policy.";
+    case "scan-input-unavailable":
+      return "Secret detection could not collect its configured project files; check the project root, permissions, and selected file source.";
+    case "source-unavailable":
+      return "A selected secret detection input could not be read safely; check that it still exists, is readable, and was not replaced during the Run.";
+    case "detector-unavailable":
+      return "The private secret detector did not complete; retry after restoring the package runtime without treating this Run as clean.";
+    case "detector-protocol-failed":
+      return "The private secret detector returned an unsupported result shape; update the package dependency only with a reviewed adapter change.";
+    case "execution-cancelled":
+      return "Secret detection was cancelled before it could form a complete result; inspect the caller's cancellation reason and retry if appropriate.";
+  }
+}

package/src/package-checks/secret-detection/final-data.ts

@@ -0,0 +1,57 @@
+import {
+  exactFinalDataRecord,
+  invalidFinalData,
+  nonNegativeSafeInteger
+} from "../final-data-parsing.ts";
+
+/** `secretDetection` 正常完成时发布的安全计数。 */
+export interface SecretDetectionFinalData {
+  /** 已选择但未获得 bounded detector coverage 的文件数。 */
+  readonly coverageGapCount: number;
+  /** 所有安全投影后的 detector finding 数，包括已 waived 的 finding。 */
+  readonly findingCount: number;
+  /** 已获得 bounded text detector coverage 的文件数。 */
+  readonly scannedFileCount: number;
+  /** files policy 的 exact selection 数，恒等于 scannedFileCount 与 coverageGapCount 之和。 */
+  readonly selectedFileCount: number;
+  /** 安全 identity 被唯一 waiver 匹配的 finding 数。 */
+  readonly waivedFindingCount: number;
+}
+
+/** 验证并脱离一份 `secretDetection` canonical final-data object。 */
+export function parseSecretDetectionData(data: unknown): SecretDetectionFinalData {
+  const value = exactFinalDataRecord(
+    data,
+    [
+      "coverageGapCount",
+      "findingCount",
+      "scannedFileCount",
+      "selectedFileCount",
+      "waivedFindingCount"
+    ],
+    "secretDetection"
+  );
+  const coverageGapCount = nonNegativeSafeInteger(value.coverageGapCount);
+  const findingCount = nonNegativeSafeInteger(value.findingCount);
+  const scannedFileCount = nonNegativeSafeInteger(value.scannedFileCount);
+  const selectedFileCount = nonNegativeSafeInteger(value.selectedFileCount);
+  const waivedFindingCount = nonNegativeSafeInteger(value.waivedFindingCount);
+  if (
+    coverageGapCount === undefined ||
+    findingCount === undefined ||
+    scannedFileCount === undefined ||
+    selectedFileCount === undefined ||
+    waivedFindingCount === undefined ||
+    scannedFileCount + coverageGapCount !== selectedFileCount ||
+    waivedFindingCount > findingCount
+  ) {
+    throw invalidFinalData("secretDetection");
+  }
+  return Object.freeze({
+    coverageGapCount,
+    findingCount,
+    scannedFileCount,
+    selectedFileCount,
+    waivedFindingCount
+  });
+}

package/src/package-checks/secret-detection/finding-waiver-identity.ts

@@ -0,0 +1,37 @@
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
+import type { SecretDetectionFindingIdentity } from "./options.ts";
+
+const PRIVATE_KEY_RULE_ID = "@secretlint/secretlint-rule-privatekey" as const;
+const TEXT_DOCUMENT_STRUCTURAL_CLASS = "text-document" as const;
+
+/** 解析只含安全路径、规则、结构标记和 occurrence ordinal 的 waiver identity。 */
+export function resolveSecretDetectionFindingIdentity(
+  value: unknown
+): SecretDetectionFindingIdentity | undefined {
+  const identity = snapshotExactClosedRecord(value, [
+    "ordinal",
+    "path",
+    "ruleId",
+    "structuralClass"
+  ]);
+  if (
+    identity === undefined ||
+    !isPositiveSafeInteger(identity.ordinal) ||
+    !isNormalizedProjectRelativePath(identity.path) ||
+    identity.ruleId !== PRIVATE_KEY_RULE_ID ||
+    identity.structuralClass !== TEXT_DOCUMENT_STRUCTURAL_CLASS
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    ordinal: identity.ordinal,
+    path: identity.path,
+    ruleId: PRIVATE_KEY_RULE_ID,
+    structuralClass: TEXT_DOCUMENT_STRUCTURAL_CLASS
+  });
+}
+
+export const secretDetectionPrivateKeyRuleId = PRIVATE_KEY_RULE_ID;
+export const secretDetectionTextDocumentStructuralClass = TEXT_DOCUMENT_STRUCTURAL_CLASS;

package/src/package-checks/secret-detection/input-preparation.ts

@@ -0,0 +1,233 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { resolve } from "node:path";
+
+import type { CheckExecutionContext } from "../../check/check.ts";
+import {
+  classifySecretDetectionBytes,
+  type SecretDetectionCoverageGapReason
+} from "./classification.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+
+/** Private, already-classified text passed to this Check's private detector adapter. */
+export interface ApprovedTextInput {
+  readonly content: string;
+  readonly path: string;
+}
+
+/** A safe explanation for an exact selected input that did not receive detector coverage. */
+export interface SecretCoverageGap {
+  readonly path: string;
+  readonly reason: SecretDetectionCoverageGapReason;
+}
+
+export type PreparedSecretDetectionInputs = Readonly<
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "unavailable" }
+  | {
+      readonly coverageGaps: readonly SecretCoverageGap[];
+      readonly inputs: readonly ApprovedTextInput[];
+      readonly kind: "complete";
+    }
+>;
+
+/** Reads and classifies the already-selected paths before the detector can receive text. */
+export function prepareSecretDetectionInputs(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>,
+  selectedPaths: readonly string[]
+): PreparedSecretDetectionInputs {
+  const coverageGaps: SecretCoverageGap[] = [];
+  const inputs: ApprovedTextInput[] = [];
+  let consumedBytes = 0;
+
+  for (const [index, path] of selectedPaths.entries()) {
+    if (context.signal.aborted) return Object.freeze({ kind: "cancelled" });
+    const selectionLimit = selectionLimitGaps(
+      context.options.maximumFileCount,
+      selectedPaths,
+      index
+    );
+    if (selectionLimit !== undefined) {
+      coverageGaps.push(...selectionLimit);
+      break;
+    }
+    const prepared = prepareSelectedInput(context, path, consumedBytes);
+    if (prepared.kind === "cancelled" || prepared.kind === "unavailable") return prepared;
+    if (prepared.kind === "coverage-gap") {
+      consumedBytes += prepared.consumedBytes;
+      coverageGaps.push(Object.freeze({ path, reason: prepared.reason }));
+      if (prepared.stop) {
+        coverageGaps.push(...coverageGapsFor(selectedPaths.slice(index + 1), "total-byte-limit"));
+        break;
+      }
+      continue;
+    }
+    consumedBytes += prepared.byteLength;
+    inputs.push(prepared.input);
+  }
+  return Object.freeze({
+    coverageGaps: Object.freeze(coverageGaps),
+    inputs: Object.freeze(inputs),
+    kind: "complete"
+  });
+}
+
+type PreparedSelectedInput = Readonly<
+  | { readonly kind: "cancelled" }
+  | { readonly kind: "unavailable" }
+  | {
+      readonly consumedBytes: number;
+      readonly kind: "coverage-gap";
+      readonly reason: SecretDetectionCoverageGapReason;
+      readonly stop: boolean;
+    }
+  | { readonly byteLength: number; readonly input: ApprovedTextInput; readonly kind: "approved" }
+>;
+
+type BoundedRegularFileRead = Readonly<
+  | { readonly kind: "unavailable" }
+  | {
+      readonly kind: "coverage-gap";
+      readonly reason: Extract<
+        SecretDetectionCoverageGapReason,
+        "file-byte-limit" | "total-byte-limit"
+      >;
+    }
+  | { readonly bytes: Uint8Array; readonly kind: "complete" }
+>;
+
+function selectionLimitGaps(
+  maximumFileCount: number,
+  selectedPaths: readonly string[],
+  index: number
+): readonly SecretCoverageGap[] | undefined {
+  if (index < maximumFileCount) return undefined;
+  return coverageGapsFor(selectedPaths.slice(index), "file-count-limit");
+}
+
+function prepareSelectedInput(
+  context: CheckExecutionContext<ResolvedSecretDetectionOptions>,
+  path: string,
+  consumedBytes: number
+): PreparedSelectedInput {
+  if (context.signal.aborted) return Object.freeze({ kind: "cancelled" });
+  const read = readBoundedRegularFile({
+    consumedBytes,
+    filePath: resolve(context.project.root, path),
+    options: context.options
+  });
+  if (read.kind === "unavailable") return read;
+  if (read.kind === "coverage-gap") {
+    return Object.freeze({
+      consumedBytes: 0,
+      kind: "coverage-gap",
+      reason: read.reason,
+      stop: read.reason === "total-byte-limit"
+    });
+  }
+  if (context.signal.aborted) return Object.freeze({ kind: "cancelled" });
+
+  const classification = classifySecretDetectionBytes(read.bytes, context.options.maximumFileBytes);
+  if (classification.kind === "coverage-gap") {
+    return Object.freeze({
+      consumedBytes: read.bytes.byteLength,
+      kind: "coverage-gap",
+      reason: classification.reason,
+      stop: false
+    });
+  }
+  return Object.freeze({
+    byteLength: read.bytes.byteLength,
+    input: Object.freeze({ content: classification.content, path }),
+    kind: "approved"
+  });
+}
+
+function readBoundedRegularFile(input: {
+  readonly consumedBytes: number;
+  readonly filePath: string;
+  readonly options: ResolvedSecretDetectionOptions;
+}): BoundedRegularFileRead {
+  const descriptor = openRegularFileWithoutFollowingSymlink(input.filePath);
+  if (descriptor === undefined) return Object.freeze({ kind: "unavailable" });
+  try {
+    const byteLength = regularFileByteLength(descriptor);
+    if (byteLength === undefined) return Object.freeze({ kind: "unavailable" });
+    const limit = resourceLimitReason(input.options, byteLength, input.consumedBytes);
+    if (limit !== undefined) return Object.freeze({ kind: "coverage-gap", reason: limit });
+
+    const bytes = readExactBoundedBytes(descriptor, byteLength);
+    if (bytes === undefined || regularFileByteLength(descriptor) !== byteLength) {
+      return Object.freeze({ kind: "unavailable" });
+    }
+    return Object.freeze({ bytes, kind: "complete" });
+  } catch {
+    return Object.freeze({ kind: "unavailable" });
+  } finally {
+    closeDescriptor(descriptor);
+  }
+}
+
+function closeDescriptor(descriptor: number): void {
+  try {
+    closeSync(descriptor);
+  } catch {
+    // The descriptor cannot carry source bytes into a public result; preserve the completed read fact.
+  }
+}
+
+function openRegularFileWithoutFollowingSymlink(filePath: string): number | undefined {
+  if (!supportsNoFollowDescriptorOpen()) return undefined;
+  try {
+    return openSync(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch {
+    return undefined;
+  }
+}
+
+function supportsNoFollowDescriptorOpen(): boolean {
+  return process.platform !== "win32" && constants.O_NOFOLLOW !== 0;
+}
+
+function regularFileByteLength(descriptor: number): number | undefined {
+  try {
+    const details = fstatSync(descriptor);
+    return details.isFile() && Number.isSafeInteger(details.size) && details.size >= 0
+      ? details.size
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readExactBoundedBytes(descriptor: number, byteLength: number): Uint8Array | undefined {
+  const bytes = new Uint8Array(byteLength);
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const read = readSync(
+      descriptor,
+      bytes,
+      offset,
+      Math.min(65_536, bytes.byteLength - offset),
+      null
+    );
+    if (read <= 0) return undefined;
+    offset += read;
+  }
+  return bytes;
+}
+
+function resourceLimitReason(
+  options: ResolvedSecretDetectionOptions,
+  byteLength: number,
+  consumedBytes: number
+): Extract<SecretDetectionCoverageGapReason, "file-byte-limit" | "total-byte-limit"> | undefined {
+  if (byteLength > options.maximumFileBytes) return "file-byte-limit";
+  return consumedBytes + byteLength > options.maximumTotalBytes ? "total-byte-limit" : undefined;
+}
+
+function coverageGapsFor(
+  paths: readonly string[],
+  reason: SecretDetectionCoverageGapReason
+): readonly SecretCoverageGap[] {
+  return Object.freeze(paths.map((path) => Object.freeze({ path, reason })));
+}

package/src/package-checks/secret-detection/options-resolution.ts

@@ -0,0 +1,65 @@
+import { snapshotClosedPolicyRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { resolveFindingWaiverAuthoring } from "../code-quality-findings/finding-waiver-authoring.ts";
+import {
+  snapshotProjectFileSelection,
+  validProjectFileSelection
+} from "../project-files/configuration.ts";
+import { resolveSecretDetectionFindingIdentity } from "./finding-waiver-identity.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+import { validSecretDetectionOptions } from "./options-validation.ts";
+
+export const DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_BYTES = 1_048_576;
+export const DEFAULT_SECRET_DETECTION_MAXIMUM_TOTAL_BYTES = 8_388_608;
+export const DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_COUNT = 2_048;
+
+/** 将 required exact file policy 和有限资源策略物化为完整、冻结 options。 */
+export function resolveSecretDetectionOptions(
+  value: unknown
+): ResolvedSecretDetectionOptions | undefined {
+  const input = snapshotClosedPolicyRecord(value, {
+    optional: ["findingWaivers", "maximumFileBytes", "maximumFileCount", "maximumTotalBytes"],
+    required: ["files"]
+  });
+  if (input === undefined || !validProjectFileSelection(input.files)) return undefined;
+
+  const limits = resolveSecretDetectionResourceLimits(input);
+  const findingWaivers = resolveFindingWaiverAuthoring(
+    input.findingWaivers,
+    resolveSecretDetectionFindingIdentity
+  );
+  if (limits === undefined || findingWaivers === undefined) return undefined;
+
+  const options = Object.freeze({
+    files: snapshotProjectFileSelection(input.files),
+    findingWaivers,
+    ...limits
+  });
+  return validSecretDetectionOptions(options) ? options : undefined;
+}
+
+function resolveSecretDetectionResourceLimits(
+  input: Readonly<{
+    readonly maximumFileBytes?: unknown;
+    readonly maximumFileCount?: unknown;
+    readonly maximumTotalBytes?: unknown;
+  }>
+):
+  | Readonly<{
+      readonly maximumFileBytes: number;
+      readonly maximumFileCount: number;
+      readonly maximumTotalBytes: number;
+    }>
+  | undefined {
+  const maximumFileBytes = input.maximumFileBytes ?? DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_BYTES;
+  const maximumFileCount = input.maximumFileCount ?? DEFAULT_SECRET_DETECTION_MAXIMUM_FILE_COUNT;
+  const maximumTotalBytes = input.maximumTotalBytes ?? DEFAULT_SECRET_DETECTION_MAXIMUM_TOTAL_BYTES;
+  if (
+    !isPositiveSafeInteger(maximumFileBytes) ||
+    !isPositiveSafeInteger(maximumFileCount) ||
+    !isPositiveSafeInteger(maximumTotalBytes)
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ maximumFileBytes, maximumFileCount, maximumTotalBytes });
+}

package/src/package-checks/secret-detection/options-validation.ts

@@ -0,0 +1,27 @@
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { validResolvedFindingWaivers } from "../code-quality-findings/finding-waiver-authoring.ts";
+import { validProjectFileSelection } from "../project-files/configuration.ts";
+import { resolveSecretDetectionFindingIdentity } from "./finding-waiver-identity.ts";
+import type { ResolvedSecretDetectionOptions } from "./options.ts";
+
+/** Guards prepared options before a Run invokes a detector. */
+export function validSecretDetectionOptions(
+  value: unknown
+): value is ResolvedSecretDetectionOptions {
+  const options = snapshotExactClosedRecord(value, [
+    "files",
+    "findingWaivers",
+    "maximumFileBytes",
+    "maximumFileCount",
+    "maximumTotalBytes"
+  ]);
+  return (
+    options !== undefined &&
+    validProjectFileSelection(options.files) &&
+    validResolvedFindingWaivers(options.findingWaivers, resolveSecretDetectionFindingIdentity) &&
+    isPositiveSafeInteger(options.maximumFileBytes) &&
+    isPositiveSafeInteger(options.maximumFileCount) &&
+    isPositiveSafeInteger(options.maximumTotalBytes)
+  );
+}