@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/package-checks/markdown-link-validation/resolver-engine.ts

@@ -1,7 +1,8 @@
 import { opendir } from "node:fs/promises";
 import path from "node:path";
 
-import { parseMarkdownLinkFacts } from "./markdown-parser.ts";
+import type { MarkdownLinkParseResult, ParsedMarkdownLinkFacts } from "./markdown-parser.ts";
+import { MarkdownLinkParseFactsSession } from "./parse-facts-cache.ts";
 import {
   directoryTarget,
   fileTargetDescriptor,
@@ -9,86 +10,64 @@ import {
   projectTarget
 } from "./target-descriptor.ts";
 import { probeEndpoint, probeRootContainedPath, readRegularFile } from "./filesystem-probes.ts";
+import { readRootContainedMarkdownSource } from "./source-reader.ts";
 import {
   anchorResolution,
   finding,
   isMarkdownPath,
-  isRootRelativePath,
   isWithinRoot,
   parseLocalDestination,
   sameRootRelativePath,
-  sourceUnavailable,
-  toSlashPath,
   unavailable,
   valid,
   type MarkdownLocalResolution,
   type MarkdownLocalResolutionRequest,
   type MarkdownLocalResolver,
   type MarkdownSafeTargetDescriptor,
-  type MarkdownSourceReadResult
+  type EndpointProbe
 } from "./local-resolution.ts";
+import type { ResolvedMarkdownLinkValidationOptions } from "./options.ts";
 
 export class LinkLocalResolver implements MarkdownLocalResolver {
   #targetReadCount = 0;
   readonly #canonicalProjectRoot: string;
+  readonly #parseFactsCache: MarkdownLinkParseFactsSession;
   readonly #maxTargetReads: number;
+  readonly #signal: AbortSignal;
+  readonly #targetFactMemo = new Map<string, Promise<ParsedMarkdownLinkFacts | undefined>>();
 
-  constructor(canonicalProjectRoot: string, maxTargetReads: number) {
+  constructor(
+    canonicalProjectRoot: string,
+    maxTargetReads: number,
+    cache: ResolvedMarkdownLinkValidationOptions["cache"],
+    signal: AbortSignal
+  ) {
     this.#canonicalProjectRoot = canonicalProjectRoot;
     this.#maxTargetReads = maxTargetReads;
+    this.#parseFactsCache = new MarkdownLinkParseFactsSession(cache);
+    this.#signal = signal;
   }
 
   get targetReadCount(): number {
     return this.#targetReadCount;
   }
 
-  async readSource(
-    rootRelativePath: string,
-    maxMarkdownBytes: number
-  ): Promise<MarkdownSourceReadResult> {
-    if (!isRootRelativePath(this.#canonicalProjectRoot, rootRelativePath)) {
-      return sourceUnavailable();
-    }
-
-    const sourcePath = path.resolve(this.#canonicalProjectRoot, rootRelativePath);
-    const rootProbe = await probeRootContainedPath(this.#canonicalProjectRoot, sourcePath);
-    if (
-      rootProbe.kind === "outside" ||
-      rootProbe.kind === "unavailable" ||
-      rootProbe.kind === "missing"
-    ) {
-      return sourceUnavailable();
-    }
-
-    const sourceBytes = await readRegularFile(rootProbe.absolutePath, maxMarkdownBytes);
-    if (!sourceBytes.ok) {
-      return sourceBytes.reason === "too-large"
-        ? Object.freeze({ ok: false as const, reason: "source-too-large" as const })
-        : sourceUnavailable();
-    }
-
-    let markdown: string;
-    try {
-      markdown = new TextDecoder("utf-8", { fatal: true }).decode(sourceBytes.bytes);
-    } catch {
-      return sourceUnavailable();
-    }
-
-    const parsed = parseMarkdownLinkFacts(markdown);
-    if (!parsed.ok) {
-      return Object.freeze({ ok: false as const, reason: "markdown-parse-failed" as const });
-    }
+  finalize(): Promise<void> {
+    return this.#parseFactsCache.finalize(this.#signal);
+  }
 
-    return Object.freeze({
-      ok: true as const,
-      source: Object.freeze({
-        path: toSlashPath(path.relative(this.#canonicalProjectRoot, sourcePath)),
-        facts: parsed.facts
-      })
+  readSource(rootRelativePath: string, maxMarkdownBytes: number) {
+    return readRootContainedMarkdownSource({
+      canonicalProjectRoot: this.#canonicalProjectRoot,
+      maxMarkdownBytes,
+      parseMarkdownBytes: (bytes) => this.#parseMarkdownBytes(bytes),
+      rootRelativePath,
+      signal: this.#signal
     });
   }
 
   async resolve(request: MarkdownLocalResolutionRequest): Promise<MarkdownLocalResolution> {
+    if (this.#signal.aborted) return unavailable("target-unavailable");
     const destination = parseLocalDestination(request.rawDestination);
     if (destination === "not-local") {
       return Object.freeze({ kind: "not-local" as const });
@@ -148,6 +127,7 @@ export class LinkLocalResolver implements MarkdownLocalResolver {
       return unavailable("target-read-limit-exceeded");
     }
     return this.resolveEndpoint(
+      rootProbe.endpoint ?? (await probeEndpoint(rootProbe.absolutePath)),
       rootProbe.absolutePath,
       fragment,
       request,
@@ -169,16 +149,22 @@ export class LinkLocalResolver implements MarkdownLocalResolver {
     if (!this.beginTargetValidation()) {
       return unavailable("target-read-limit-exceeded");
     }
-    return this.resolveEndpoint(targetPath, fragment, request, outsideProjectRootTarget());
+    return this.resolveEndpoint(
+      await probeEndpoint(targetPath),
+      targetPath,
+      fragment,
+      request,
+      outsideProjectRootTarget()
+    );
   }
 
   async resolveEndpoint(
+    endpoint: EndpointProbe,
     targetPath: string,
     fragment: string | null,
     request: MarkdownLocalResolutionRequest,
     target: MarkdownSafeTargetDescriptor
   ): Promise<MarkdownLocalResolution> {
-    const endpoint = await probeEndpoint(targetPath);
     if (endpoint.kind === "missing") {
       return request.requireExistingTargets ? finding("missing-target", target) : valid(target);
     }
@@ -208,21 +194,10 @@ export class LinkLocalResolver implements MarkdownLocalResolver {
       return finding("anchor-target-not-markdown", target);
     }
 
-    const targetMarkdown = await readRegularFile(targetPath, request.maxMarkdownBytes);
-    if (!targetMarkdown.ok) {
-      return unavailable("target-unavailable");
-    }
-    let decodedTarget: string;
-    try {
-      decodedTarget = new TextDecoder("utf-8", { fatal: true }).decode(targetMarkdown.bytes);
-    } catch {
-      return unavailable("target-unavailable");
-    }
-    const parsedTarget = parseMarkdownLinkFacts(decodedTarget);
-    if (!parsedTarget.ok) {
-      return unavailable("target-unavailable");
-    }
-    return anchorResolution(parsedTarget.facts.headings, fragment, target);
+    const facts = await this.#targetFacts(targetPath, request.maxMarkdownBytes);
+    return facts === undefined
+      ? unavailable("target-unavailable")
+      : anchorResolution(facts.headings, fragment, target);
   }
 
   async resolveDirectory(
@@ -231,6 +206,7 @@ export class LinkLocalResolver implements MarkdownLocalResolver {
     request: MarkdownLocalResolutionRequest,
     target: MarkdownSafeTargetDescriptor
   ): Promise<MarkdownLocalResolution> {
+    if (this.#signal.aborted) return unavailable("target-unavailable");
     if (fragment !== null) {
       return finding("anchor-on-directory", target);
     }
@@ -259,6 +235,40 @@ export class LinkLocalResolver implements MarkdownLocalResolver {
     return true;
   }
 
+  async #targetFacts(
+    targetPath: string,
+    maxMarkdownBytes: number
+  ): Promise<ParsedMarkdownLinkFacts | undefined> {
+    if (this.#signal.aborted) return undefined;
+    const key = JSON.stringify([targetPath, maxMarkdownBytes]);
+    const existing = this.#targetFactMemo.get(key);
+    if (existing !== undefined) return existing;
+
+    const pending = this.#readTargetFacts(targetPath, maxMarkdownBytes);
+    this.#targetFactMemo.set(key, pending);
+    const facts = await pending;
+    if (facts === undefined && this.#targetFactMemo.get(key) === pending) {
+      this.#targetFactMemo.delete(key);
+    }
+    return facts;
+  }
+
+  async #readTargetFacts(
+    targetPath: string,
+    maxMarkdownBytes: number
+  ): Promise<ParsedMarkdownLinkFacts | undefined> {
+    const targetMarkdown = await readRegularFile(targetPath, maxMarkdownBytes);
+    if (!targetMarkdown.ok || this.#signal.aborted) return undefined;
+    const parsed = await this.#parseMarkdownBytes(targetMarkdown.bytes);
+    return this.#signal.aborted || parsed === undefined || !parsed.ok ? undefined : parsed.facts;
+  }
+
+  async #parseMarkdownBytes(bytes: Uint8Array): Promise<MarkdownLinkParseResult | undefined> {
+    if (this.#signal.aborted) return undefined;
+    const parsed = await this.#parseFactsCache.parse(bytes, this.#signal);
+    return this.#signal.aborted ? undefined : parsed;
+  }
+
   resolveSameDocument(
     fragment: string | null,
     request: MarkdownLocalResolutionRequest

package/src/package-checks/markdown-link-validation/source-reader.ts

@@ -0,0 +1,86 @@
+import path from "node:path";
+
+import type { MarkdownLinkParseResult } from "./markdown-parser.ts";
+import { probeRootContainedPath, readRegularFile } from "./filesystem-probes.ts";
+import {
+  isRootRelativePath,
+  sourceUnavailable,
+  toSlashPath,
+  type MarkdownSourceReadResult
+} from "./local-resolution.ts";
+
+export interface RootContainedMarkdownSourceReadRequest {
+  readonly canonicalProjectRoot: string;
+  readonly maxMarkdownBytes: number;
+  readonly parseMarkdownBytes: (bytes: Uint8Array) => Promise<MarkdownLinkParseResult | undefined>;
+  readonly rootRelativePath: string;
+  readonly signal: AbortSignal;
+}
+
+type RootContainedSourceBytesRead =
+  | Readonly<{ readonly kind: "bytes"; readonly bytes: Uint8Array }>
+  | Readonly<{ readonly kind: "result"; readonly result: MarkdownSourceReadResult }>;
+
+/** Reads one authorized Markdown source without granting target-resolution behavior. */
+export async function readRootContainedMarkdownSource(
+  request: RootContainedMarkdownSourceReadRequest
+): Promise<MarkdownSourceReadResult> {
+  const sourcePath = authorizedRootRelativeSourcePath(request);
+  if (sourcePath === undefined) return sourceUnavailable();
+  const sourceRead = await readRootContainedSourceBytes(request, sourcePath);
+  if (sourceRead.kind === "result") return sourceRead.result;
+  return parseRootContainedSourceBytes(request, sourcePath, sourceRead.bytes);
+}
+
+function authorizedRootRelativeSourcePath(
+  request: RootContainedMarkdownSourceReadRequest
+): string | undefined {
+  if (request.signal.aborted) return undefined;
+  return isRootRelativePath(request.canonicalProjectRoot, request.rootRelativePath)
+    ? path.resolve(request.canonicalProjectRoot, request.rootRelativePath)
+    : undefined;
+}
+
+async function readRootContainedSourceBytes(
+  request: RootContainedMarkdownSourceReadRequest,
+  sourcePath: string
+): Promise<RootContainedSourceBytesRead> {
+  const rootProbe = await probeRootContainedPath(request.canonicalProjectRoot, sourcePath);
+  if (
+    rootProbe.kind === "outside" ||
+    rootProbe.kind === "unavailable" ||
+    rootProbe.kind === "missing"
+  ) {
+    return Object.freeze({ kind: "result" as const, result: sourceUnavailable() });
+  }
+  const sourceBytes = await readRegularFile(rootProbe.absolutePath, request.maxMarkdownBytes);
+  if (!sourceBytes.ok) {
+    return Object.freeze({
+      kind: "result" as const,
+      result:
+        sourceBytes.reason === "too-large"
+          ? Object.freeze({ ok: false as const, reason: "source-too-large" as const })
+          : sourceUnavailable()
+    });
+  }
+  return Object.freeze({ kind: "bytes" as const, bytes: sourceBytes.bytes });
+}
+
+async function parseRootContainedSourceBytes(
+  request: RootContainedMarkdownSourceReadRequest,
+  sourcePath: string,
+  sourceBytes: Uint8Array
+): Promise<MarkdownSourceReadResult> {
+  const parsed = await request.parseMarkdownBytes(sourceBytes);
+  if (request.signal.aborted || parsed === undefined) return sourceUnavailable();
+  if (!parsed.ok) {
+    return Object.freeze({ ok: false as const, reason: "markdown-parse-failed" as const });
+  }
+  return Object.freeze({
+    ok: true as const,
+    source: Object.freeze({
+      path: toSlashPath(path.relative(request.canonicalProjectRoot, sourcePath)),
+      facts: parsed.facts
+    })
+  });
+}

package/src/package-checks/markdown-link-validation/unavailable-reasons.ts

@@ -0,0 +1,42 @@
+import type {
+  MarkdownLocalResolutionReason,
+  MarkdownSourceReadFailureReason
+} from "./local-resolver.ts";
+
+/** `markdown-link-validation` whole-Check unavailable outcome 的稳定 reason code。 */
+export type MarkdownLinkValidationUnavailableReason =
+  | "invalid-options"
+  | "cancelled"
+  | "occurrence-limit-exceeded"
+  | "project-root-unavailable"
+  | MarkdownLocalResolutionReason
+  | MarkdownSourceReadFailureReason;
+
+const UNAVAILABLE_MESSAGES: Readonly<Record<MarkdownLinkValidationUnavailableReason, string>> = {
+  "invalid-options":
+    "markdownLinkValidation options are invalid; recreate the Check with markdownLinkValidation(options) or restore its complete resolved options.",
+  "project-root-unavailable":
+    "Markdown link validation could not resolve the project root; check that the path exists and is accessible.",
+  "source-unavailable":
+    "A selected Markdown source could not be collected, read, decoded, or contained safely; check the file source and permissions.",
+  "source-too-large":
+    "A selected Markdown source exceeds maxMarkdownBytes; narrow the file selection or raise the bounded limit.",
+  "markdown-parse-failed":
+    "A selected Markdown source could not be parsed completely; inspect that document's Markdown syntax and encoding.",
+  "invalid-local-destination":
+    "A local Markdown destination could not be parsed safely; inspect the affected link destination syntax.",
+  "target-unavailable":
+    "A local Markdown target could not be probed or read safely; check the target path, permissions, size, and encoding.",
+  "occurrence-limit-exceeded":
+    "Markdown link validation exceeded maxOccurrences; narrow the source selection or raise the bounded limit.",
+  "target-read-limit-exceeded":
+    "Markdown link validation exceeded maxTargetReads; narrow the source selection or raise the bounded limit.",
+  cancelled:
+    "Markdown link validation was cancelled before it could form a complete result; inspect the caller's cancellation reason and retry if appropriate."
+};
+
+export function markdownLinkUnavailableMessage(
+  reason: MarkdownLinkValidationUnavailableReason
+): string {
+  return UNAVAILABLE_MESSAGES[reason];
+}

package/src/package-checks/project-files/collection.ts

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
 import { matchesAnyConfigGlob } from "./config-glob.ts";
 import { collectSubmoduleWorktreeFiles } from "./revision-worktree-files.ts";
 import { errorMessage } from "../host-environment/error-message.ts";
-import { processFailed } from "../host-environment/process/command.ts";
+import { processFailed } from "../host-environment/process.ts";
 import { runGit, splitNulDelimitedGitFileList } from "../host-environment/git.ts";
 import { toSlashPath } from "../host-environment/path.ts";
 import { walkFiles } from "../host-environment/filesystem.ts";

package/src/package-checks/project-files/configuration.ts

@@ -1,7 +1,8 @@
 import {
   hasRequiredAndOptionalRecordKeys,
   snapshotClosedArray,
-  snapshotClosedRecord
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
 } from "../../data-boundary/closed-values.ts";
 
 export const PROJECT_FILE_SOURCES = Object.freeze(["filesystem", "git-worktree"] as const);
@@ -101,7 +102,7 @@ export function snapshotProjectFileSelection(
 }
 
 export function validProjectFileSelection(value: unknown): value is ProjectFileSelection {
-  const selection = exactRecord(value, ["exclude", "include", "source"]);
+  const selection = snapshotExactClosedRecord(value, ["exclude", "include", "source"]);
   return (
     selection !== undefined &&
     validStringArray(selection.exclude) &&
@@ -133,18 +134,6 @@ function isString(value: unknown): value is string {
   return typeof value === "string";
 }
 
-function exactRecord(
-  value: unknown,
-  keys: readonly string[]
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined &&
-    Object.keys(record).length === keys.length &&
-    keys.every((key) => Object.hasOwn(record, key))
-    ? record
-    : undefined;
-}
-
 function deepFreeze<T>(value: T): T {
   if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
   for (const nested of Object.values(value)) deepFreeze(nested);

package/src/package-checks/project-files/gitlink-revision.ts

@@ -1,6 +1,6 @@
 /** Reads canonical gitlink entries from a named Git tree revision. */
 
-import { processFailed } from "../host-environment/process/command.ts";
+import { processFailed } from "../host-environment/process.ts";
 import { runGit } from "../host-environment/git.ts";
 import { toSlashPath } from "../host-environment/path.ts";
 

package/src/package-checks/project-files/gitlink-worktree.ts

@@ -4,7 +4,7 @@ import { realpathSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { errorMessage } from "../host-environment/error-message.ts";
-import { processFailed } from "../host-environment/process/command.ts";
+import { processFailed } from "../host-environment/process.ts";
 import { runGit } from "../host-environment/git.ts";
 
 export type GitlinkWorktreeInspection =

package/src/package-checks/project-files/public-collection.ts

@@ -0,0 +1,92 @@
+/** Public validation and immutable snapshot boundary for one project-file selection. */
+
+import { resolve } from "node:path";
+
+import {
+  snapshotClosedArray,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { collectProjectFiles as collectTrustedProjectFiles } from "./collection.ts";
+import { PROJECT_FILE_SOURCES } from "./configuration.ts";
+import type { ProjectFileSelection, ProjectFileSource } from "./configuration.ts";
+
+/** 调用方请求一次项目文件收集时必须完整提供的 root 与 selection。 */
+export interface CollectProjectFilesOptions {
+  /** 显式 project root；relative path 相对当前工作目录解析，不能为空或含 U+0000。 */
+  readonly projectRoot: string;
+  /** 完整的显式 selection；本工具不推断任何 Check 默认值。 */
+  readonly selection: ProjectFileSelection;
+}
+
+type ResolvedCollectProjectFilesOptions = Readonly<{
+  readonly projectRoot: string;
+  readonly selection: ProjectFileSelection;
+}>;
+
+/**
+ * 按一份完整的显式 selection 同步收集 project-root-relative slash paths。
+ *
+ * 成功结果是冻结的稳定去重排序快照，空数组表示没有匹配路径。非法参数同步抛出
+ * `TypeError`；选定 filesystem 或 Git source 的收集失败继续抛出普通 `Error`，不会回退来源。
+ */
+export function collectProjectFiles(
+  authoredOptions: CollectProjectFilesOptions
+): readonly string[] {
+  const options = parseOptions(authoredOptions);
+  return Object.freeze([...collectTrustedProjectFiles(options.projectRoot, options.selection)]);
+}
+
+function parseOptions(value: unknown): ResolvedCollectProjectFilesOptions {
+  const options = snapshotExactClosedRecord(value, ["projectRoot", "selection"]);
+  if (options === undefined) {
+    throw new TypeError(
+      "collectProjectFiles requires an options record with exactly projectRoot and selection"
+    );
+  }
+
+  const projectRoot = parseProjectRoot(options.projectRoot);
+  if (projectRoot === undefined) {
+    throw new TypeError(
+      "collectProjectFiles projectRoot must be a non-empty string without U+0000"
+    );
+  }
+
+  const selection = parseSelection(options.selection);
+  if (selection === undefined) {
+    throw new TypeError(
+      "collectProjectFiles selection must be a complete record with source, include, and exclude"
+    );
+  }
+
+  return Object.freeze({ projectRoot, selection });
+}
+
+function parseProjectRoot(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 && !value.includes("\0")
+    ? resolve(value)
+    : undefined;
+}
+
+function parseSelection(value: unknown): ProjectFileSelection | undefined {
+  const selection = snapshotExactClosedRecord(value, ["source", "include", "exclude"]);
+  if (selection === undefined) return undefined;
+
+  const include = snapshotStringArray(selection.include);
+  const exclude = snapshotStringArray(selection.exclude);
+  if (include === undefined || exclude === undefined || !isProjectFileSource(selection.source)) {
+    return undefined;
+  }
+
+  return Object.freeze({ exclude, include, source: selection.source });
+}
+
+function snapshotStringArray(value: unknown): readonly string[] | undefined {
+  const items = snapshotClosedArray(value);
+  return items !== undefined && items.every((item): item is string => typeof item === "string")
+    ? Object.freeze([...items])
+    : undefined;
+}
+
+function isProjectFileSource(value: unknown): value is ProjectFileSource {
+  return PROJECT_FILE_SOURCES.some((source) => source === value);
+}

package/src/package-checks/project-files/revision-worktree-files.ts

@@ -1,6 +1,6 @@
 /** Enumerates files from initialized, non-cyclic submodule working trees. */
 
-import { processFailed } from "../host-environment/process/command.ts";
+import { processFailed } from "../host-environment/process.ts";
 import { runGit, splitNulDelimitedGitFileList } from "../host-environment/git.ts";
 import {
   canonicalRepositoryPath,

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

@@ -0,0 +1,30 @@
+/** A bounded, non-secret classification result for one explicitly selected file. */
+export type SecretDetectionInputClassification = Readonly<
+  | { readonly kind: "coverage-gap"; readonly reason: SecretDetectionCoverageGapReason }
+  | { readonly content: string; readonly kind: "text" }
+>;
+
+/** Deterministic reasons why an explicitly selected file did not receive detector coverage. */
+export type SecretDetectionCoverageGapReason =
+  | "contains-nul"
+  | "file-count-limit"
+  | "file-byte-limit"
+  | "invalid-utf8"
+  | "total-byte-limit";
+
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+
+/** Classifies already-read bytes without retaining or publishing their content on non-text branches. */
+export function classifySecretDetectionBytes(
+  bytes: Uint8Array,
+  maximumFileBytes: number
+): SecretDetectionInputClassification {
+  if (bytes.byteLength > maximumFileBytes)
+    return Object.freeze({ kind: "coverage-gap", reason: "file-byte-limit" });
+  if (bytes.includes(0)) return Object.freeze({ kind: "coverage-gap", reason: "contains-nul" });
+  try {
+    return Object.freeze({ content: UTF8_DECODER.decode(bytes), kind: "text" });
+  } catch {
+    return Object.freeze({ kind: "coverage-gap", reason: "invalid-utf8" });
+  }
+}

package/src/package-checks/secret-detection/default-check.ts

@@ -0,0 +1,50 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import { executeSecretDetection, SECRET_DETECTION_CHECK_DEFINITION } from "./execution.ts";
+import { parseSecretDetectionData } from "./final-data.ts";
+import type { ResolvedSecretDetectionOptions, SecretDetectionOptions } from "./options.ts";
+import { resolveSecretDetectionOptions } from "./options-resolution.ts";
+import { validSecretDetectionOptions } from "./options-validation.ts";
+
+/**
+ * 构造只检查其必填、显式 `files` policy 所选择输入的 high-confidence secret Check。
+ *
+ * @param options - 必须声明完整 `files`；limits 和 finding waivers 使用本 Check 的固定安全策略。
+ * @returns 固定 `secret-detection` identity、完整冻结 options、final-data parser 与 execution。
+ * @throws {TypeError} files 缺失、策略不完整或输入含未知字段时抛出。
+ */
+export function secretDetection(
+  options: SecretDetectionOptions
+): TypedCheckWithOptions<
+  "secret-detection",
+  ResolvedSecretDetectionOptions,
+  typeof parseSecretDetectionData
+> {
+  const resolvedOptions = resolveSecretDetectionOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError(
+      "secretDetection options must declare the documented closed explicit file policy"
+    );
+  }
+  return defineCheck({
+    ...SECRET_DETECTION_CHECK_DEFINITION,
+    execution: executeSecretDetection,
+    parseData: parseSecretDetectionData,
+    preflight: (preparedOptions) =>
+      validSecretDetectionOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "secretDetection options are invalid; recreate the Check with secretDetection({ files }) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}