@zxyycom/vibe-check 0.0.2 → 0.0.3

package/src/package-checks/command-check/options.ts

@@ -0,0 +1,331 @@
+import {
+  snapshotClosedArray,
+  snapshotClosedPolicyRecord,
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString, isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import type {
+  AfterCommand,
+  CommandEnvironmentResolver,
+  ResolvedCommandCheckOptions
+} from "./contract.ts";
+
+const COMMAND_INPUT_OPTIONAL_KEYS = [
+  "admissionPriority",
+  "afterCommand",
+  "arguments",
+  "checks",
+  "dependsOn",
+  "enabledByFlags",
+  "environment",
+  "maxParallel",
+  "mutex",
+  "observes",
+  "omitQuietPassedRow",
+  "output",
+  "resourceClaims",
+  "resolveEnvironment",
+  "workingDirectory"
+] as const;
+const COMMAND_INPUT_REQUIRED_KEYS = [
+  "checkId",
+  "displayName",
+  "executable",
+  "outputByteLimit",
+  "timeoutMs"
+] as const;
+const RESOLVED_OPTION_KEYS = [
+  "arguments",
+  "environment",
+  "executable",
+  "output",
+  "outputByteLimit",
+  "timeoutMs",
+  "workingDirectory"
+] as const;
+
+/** Snapshots one closed constructor input and materializes every command-owned omission. */
+export function resolveCommandCheckInput(input: unknown):
+  | Readonly<{
+      readonly afterCommand: AfterCommand | undefined;
+      readonly options: ResolvedCommandCheckOptions;
+      readonly resolveEnvironment: CommandEnvironmentResolver | undefined;
+    }>
+  | undefined {
+  const snapshot = snapshotClosedPolicyRecord(input, {
+    optional: COMMAND_INPUT_OPTIONAL_KEYS,
+    required: COMMAND_INPUT_REQUIRED_KEYS
+  });
+  if (snapshot === undefined) return undefined;
+  const afterCommand = resolveAfterCommand(snapshot.afterCommand);
+  const environmentResolver = resolveEnvironmentResolver(snapshot.resolveEnvironment);
+  if (
+    (snapshot.afterCommand !== undefined && afterCommand === undefined) ||
+    (snapshot.resolveEnvironment !== undefined && environmentResolver === undefined) ||
+    (snapshot.environment !== undefined && snapshot.resolveEnvironment !== undefined)
+  ) {
+    return undefined;
+  }
+  const options = resolveCommandOptions(snapshot);
+  return options === undefined
+    ? undefined
+    : Object.freeze({
+        afterCommand,
+        options,
+        resolveEnvironment: environmentResolver
+      });
+}
+
+/** Resolves one callback-produced environment to the same complete closed shape as static input. */
+export function resolveCommandCheckEnvironment(
+  value: unknown
+): ResolvedCommandCheckOptions["environment"] | undefined {
+  if (value === undefined) return undefined;
+  return resolveEnvironment(value);
+}
+
+/** Revalidates the complete resolved shape before execution. */
+export function isValidResolvedCommandCheckOptions(
+  value: unknown
+): value is ResolvedCommandCheckOptions {
+  const options = snapshotExactClosedRecord(value, RESOLVED_OPTION_KEYS);
+  return (
+    options !== undefined &&
+    validCommandText(options.executable) &&
+    validArguments(options.arguments) &&
+    validWorkingDirectory(options.workingDirectory) &&
+    validEnvironment(options.environment) &&
+    validOutput(options.output) &&
+    isPositiveSafeInteger(options.timeoutMs) &&
+    isPositiveSafeInteger(options.outputByteLimit)
+  );
+}
+
+function resolveCommandOptions(
+  input: Readonly<Record<string, unknown>>
+): ResolvedCommandCheckOptions | undefined {
+  if (!isNonEmptyString(input.checkId) || !isNonEmptyString(input.displayName)) return undefined;
+  const options = resolveCommandExecutionOptions(input);
+  if (options === undefined) return undefined;
+  return isValidResolvedCommandCheckOptions(options) ? options : undefined;
+}
+
+function resolveAfterCommand(value: unknown): AfterCommand | undefined {
+  if (value === undefined) return undefined;
+  const afterCommand = snapshotClosedPolicyRecord(value, {
+    optional: ["parseData"],
+    required: ["execute"]
+  });
+  if (afterCommand === undefined || !isAfterCommandExecution(afterCommand.execute))
+    return undefined;
+  if (afterCommand.parseData !== undefined && !isCheckDataParser(afterCommand.parseData)) {
+    return undefined;
+  }
+  return Object.freeze({
+    execute: afterCommand.execute,
+    ...(afterCommand.parseData === undefined ? {} : { parseData: afterCommand.parseData })
+  });
+}
+
+function resolveEnvironmentResolver(value: unknown): CommandEnvironmentResolver | undefined {
+  return isCommandEnvironmentResolver(value) ? value : undefined;
+}
+
+function isAfterCommandExecution(value: unknown): value is AfterCommand["execute"] {
+  return typeof value === "function";
+}
+
+function isCheckDataParser(value: unknown): value is NonNullable<AfterCommand["parseData"]> {
+  return typeof value === "function";
+}
+
+function isCommandEnvironmentResolver(value: unknown): value is CommandEnvironmentResolver {
+  return typeof value === "function";
+}
+
+/** Resolves command-owned execution fields after the ordinary Check identity is known valid. */
+function resolveCommandExecutionOptions(
+  input: Readonly<Record<string, unknown>>
+): ResolvedCommandCheckOptions | undefined {
+  const argumentsSnapshot = resolveArguments(input.arguments);
+  const environment = resolveEnvironment(input.environment);
+  const output = resolveOutput(input.output);
+  const workingDirectory = resolveWorkingDirectory(input.workingDirectory);
+  if (
+    !validCommandText(input.executable) ||
+    argumentsSnapshot === undefined ||
+    environment === undefined ||
+    output === undefined ||
+    workingDirectory === undefined ||
+    !isPositiveSafeInteger(input.timeoutMs) ||
+    !isPositiveSafeInteger(input.outputByteLimit)
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    arguments: argumentsSnapshot,
+    environment,
+    executable: input.executable,
+    output,
+    outputByteLimit: input.outputByteLimit,
+    timeoutMs: input.timeoutMs,
+    workingDirectory
+  });
+}
+
+function resolveArguments(value: unknown): readonly string[] | undefined {
+  if (value === undefined) return Object.freeze([]);
+  const argumentsSnapshot = snapshotClosedArray(value);
+  if (argumentsSnapshot === undefined) return undefined;
+  const argumentsCopy: string[] = [];
+  for (const argument of argumentsSnapshot) {
+    if (!validArgument(argument)) return undefined;
+    argumentsCopy.push(argument);
+  }
+  return Object.freeze(argumentsCopy);
+}
+
+function validArguments(value: unknown): boolean {
+  const argumentsSnapshot = snapshotClosedArray(value);
+  return argumentsSnapshot?.every(validArgument) === true;
+}
+
+function validArgument(value: unknown): value is string {
+  return typeof value === "string" && !value.includes("\0");
+}
+
+function resolveWorkingDirectory(value: unknown): string | null | undefined {
+  if (value === undefined) return null;
+  return validCommandText(value) ? value : undefined;
+}
+
+function validWorkingDirectory(value: unknown): value is string | null {
+  return value === null || validCommandText(value);
+}
+
+function validCommandText(value: unknown): value is string {
+  return isNonEmptyString(value) && !value.includes("\0");
+}
+
+function resolveEnvironment(
+  value: unknown
+): ResolvedCommandCheckOptions["environment"] | undefined {
+  if (value === undefined) return Object.freeze({ mode: "exact", variables: Object.freeze({}) });
+  const environment = snapshotClosedRecord(value);
+  if (environment === undefined || typeof environment.mode !== "string") return undefined;
+  if (environment.mode === "exact") return resolveExactEnvironment(environment);
+  if (environment.mode === "inherit") return resolveInheritedEnvironment(environment);
+  return undefined;
+}
+
+function resolveExactEnvironment(
+  environment: Readonly<Record<string, unknown>>
+): ResolvedCommandCheckOptions["environment"] | undefined {
+  const exact = snapshotClosedPolicyRecord(environment, {
+    optional: ["variables"],
+    required: ["mode"]
+  });
+  if (exact === undefined) return undefined;
+  const variables = Object.hasOwn(exact, "variables")
+    ? resolveExactVariables(exact.variables)
+    : Object.freeze({});
+  if (variables === undefined) return undefined;
+  return Object.freeze({ mode: "exact", variables });
+}
+
+function resolveInheritedEnvironment(
+  environment: Readonly<Record<string, unknown>>
+): ResolvedCommandCheckOptions["environment"] | undefined {
+  const inherited = snapshotClosedPolicyRecord(environment, {
+    optional: ["overrides"],
+    required: ["mode"]
+  });
+  if (inherited === undefined) return undefined;
+  const overrides = Object.hasOwn(inherited, "overrides")
+    ? resolveOverrides(inherited.overrides)
+    : Object.freeze({});
+  if (overrides === undefined) return undefined;
+  return Object.freeze({ mode: "inherit", overrides });
+}
+
+function validEnvironment(value: unknown): boolean {
+  const environment = snapshotClosedRecord(value);
+  if (environment === undefined || typeof environment.mode !== "string") return false;
+  if (environment.mode === "exact") {
+    const exact = snapshotExactClosedRecord(environment, ["mode", "variables"]);
+    return exact !== undefined && validVariableMap(exact.variables, false);
+  }
+  if (environment.mode === "inherit") {
+    const inherited = snapshotExactClosedRecord(environment, ["mode", "overrides"]);
+    return inherited !== undefined && validVariableMap(inherited.overrides, true);
+  }
+  return false;
+}
+
+function resolveExactVariables(value: unknown): Readonly<Record<string, string>> | undefined {
+  const variables = snapshotClosedRecord(value);
+  if (variables === undefined) return undefined;
+  const copied: Record<string, string> = {};
+  for (const [name, variable] of Object.entries(variables)) {
+    if (name.includes("\0") || typeof variable !== "string" || variable.includes("\0"))
+      return undefined;
+    Object.defineProperty(copied, name, {
+      configurable: false,
+      enumerable: true,
+      value: variable,
+      writable: false
+    });
+  }
+  return Object.freeze(copied);
+}
+
+function resolveOverrides(value: unknown): Readonly<Record<string, string | null>> | undefined {
+  const overrides = snapshotClosedRecord(value);
+  if (overrides === undefined) return undefined;
+  const copied: Record<string, string | null> = {};
+  for (const [name, override] of Object.entries(overrides)) {
+    if (
+      name.includes("\0") ||
+      (override !== null && (typeof override !== "string" || override.includes("\0")))
+    ) {
+      return undefined;
+    }
+    Object.defineProperty(copied, name, {
+      configurable: false,
+      enumerable: true,
+      value: override,
+      writable: false
+    });
+  }
+  return Object.freeze(copied);
+}
+
+function validVariableMap(value: unknown, acceptsNull: boolean): boolean {
+  const variables = snapshotClosedRecord(value);
+  return variables !== undefined && validVariableEntries(variables, acceptsNull);
+}
+
+function validVariableEntries(
+  variables: Readonly<Record<string, unknown>>,
+  acceptsNull: boolean
+): boolean {
+  return Object.entries(variables).every(
+    ([name, variable]) =>
+      !name.includes("\0") &&
+      (typeof variable === "string" ? !variable.includes("\0") : acceptsNull && variable === null)
+  );
+}
+
+function resolveOutput(value: unknown): ResolvedCommandCheckOptions["output"] | undefined {
+  if (value === undefined) return Object.freeze({ mode: "discard" });
+  const output = snapshotExactClosedRecord(value, ["mode"]);
+  if (output === undefined) return undefined;
+  if (output.mode !== "discard" && output.mode !== "transcript") return undefined;
+  return Object.freeze({ mode: output.mode });
+}
+
+function validOutput(value: unknown): boolean {
+  const output = snapshotExactClosedRecord(value, ["mode"]);
+  return output !== undefined && (output.mode === "discard" || output.mode === "transcript");
+}

package/src/package-checks/command-check/transcript.ts

@@ -0,0 +1,35 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+
+const TRANSCRIPT_FILE_NAME = "process.log";
+
+/** Atomically replaces this Check-local fixed transcript without exposing command inputs or native errors. */
+export async function writeCommandTranscript(
+  artifactDirectory: string,
+  contents: string
+): Promise<boolean> {
+  const targetPath = join(artifactDirectory, TRANSCRIPT_FILE_NAME);
+  const temporaryPath = join(artifactDirectory, `.process-${randomUUID()}.tmp`);
+  try {
+    await fs.mkdir(artifactDirectory, { recursive: true });
+    await fs.writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx" });
+    await fs.rename(temporaryPath, targetPath);
+    return true;
+  } catch {
+    await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    return false;
+  }
+}
+
+export function runningTranscript(): string {
+  return "status=running\n";
+}
+
+export function closedTranscript(input: {
+  readonly status: "passed" | "failed" | "unavailable";
+  readonly stderr: string;
+  readonly stdout: string;
+}): string {
+  return `status=${input.status}\nstdout:\n${input.stdout}\nstderr:\n${input.stderr}`;
+}

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

@@ -1,4 +1,8 @@
 import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  resolvePackageCheckAuthoringInput,
+  type PackageCheckIdentityInput
+} from "../check-authoring.ts";
 import { DUPLICATE_DETECTION_CHECK_DEFINITION, executeDuplicateDetection } from "./execution.ts";
 import { parseDuplicateDetectionData } from "./final-data.ts";
 import type { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./options.ts";
@@ -9,27 +13,54 @@ import { validResolvedDuplicateDetectionOptions } from "./options-validation.ts"
  * 使用可省略的区域、cache 与 scanner policy 构造一个完整 duplicate-detection Check。
  *
  * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
- * @returns 固定 `duplicate-detection` identity、完整冻结 options、preflight 与 execution。
+ * @returns 固定 `duplicate-detection` identity、完整冻结 options、preparation 与 execution。
  * @throws {TypeError} input 含未知字段、空 area、非法阈值、非法 cache 或 scanner policy 时抛出。
  */
 export function duplicateDetection(
-  options: DuplicateDetectionOptions = {}
+  options?: DuplicateDetectionOptions<"duplicate-detection">
 ): TypedCheckWithOptions<
   "duplicate-detection",
   ResolvedDuplicateDetectionOptions,
   typeof parseDuplicateDetectionData
+>;
+export function duplicateDetection<const Id extends string>(
+  options: DuplicateDetectionOptions<Id> & PackageCheckIdentityInput<Id>
+): TypedCheckWithOptions<Id, ResolvedDuplicateDetectionOptions, typeof parseDuplicateDetectionData>;
+export function duplicateDetection(
+  options: DuplicateDetectionOptions
+): TypedCheckWithOptions<
+  string,
+  ResolvedDuplicateDetectionOptions,
+  typeof parseDuplicateDetectionData
+>;
+export function duplicateDetection(
+  options: DuplicateDetectionOptions = {}
+): TypedCheckWithOptions<
+  string,
+  ResolvedDuplicateDetectionOptions,
+  typeof parseDuplicateDetectionData
 > {
-  const resolvedOptions = resolveDuplicateDetectionOptions(options);
+  const input = resolvePackageCheckAuthoringInput(
+    options,
+    ["codeAreas", "cache", "findingPolicy", "findingWaivers", "scanner"],
+    DUPLICATE_DETECTION_CHECK_DEFINITION
+  );
+  if (input === undefined) {
+    throw new TypeError(
+      "duplicateDetection options are invalid; use the documented closed constructor policy including exact finding waivers"
+    );
+  }
+  const resolvedOptions = resolveDuplicateDetectionOptions(input.domainOptions);
   if (resolvedOptions === undefined) {
     throw new TypeError(
       "duplicateDetection options are invalid; use the documented closed constructor policy including exact finding waivers"
     );
   }
   return defineCheck({
-    ...DUPLICATE_DETECTION_CHECK_DEFINITION,
-    execution: executeDuplicateDetection,
+    ...input.definition,
+    execute: executeDuplicateDetection,
     parseData: parseDuplicateDetectionData,
-    preflight: (preparedOptions) =>
+    prepare: (preparedOptions) =>
       validResolvedDuplicateDetectionOptions(preparedOptions)
         ? { status: "success", preparedOptions }
         : {

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

@@ -4,7 +4,7 @@ import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
 import {
   reconcileFindingWaivers,
   type FindingWaiverReconciliation
-} from "../../finding-waivers/reconciliation.ts";
+} from "../../package-tools/finding-waivers/reconciliation.ts";
 import { collectProjectFileSets, requireProjectFileSet } from "../project-files/collection.ts";
 import { fingerprintProjectFiles } from "../project-files/file-fingerprint.ts";
 import { settleFindings } from "../code-quality-findings/policy.ts";
@@ -12,7 +12,7 @@ import {
   reportFindingWaiverAudits,
   reportReconciledCodeQualityFindingRecords
 } from "../code-quality-findings/finding-waiver-evidence.ts";
-import { appendCheckMessages } from "../../check/finding-presentation.ts";
+import { appendCheckMessages } from "../../package-tools/finding-presentation/finding-presentation.ts";
 import { duplicateFindingMessages, duplicateWaiverMessages } from "./finding-messages.ts";
 import { getGitSha } from "./project-revision.ts";
 import { measureDuplicateDetection, type DuplicateMeasurementResult } from "./measurement.ts";
@@ -194,8 +194,6 @@ function directMeasurementFailure(
     case "unavailable":
       return unavailable("external-dependency-unavailable");
   }
-  const exhaustiveMeasurement: never = measurement;
-  return exhaustiveMeasurement;
 }
 
 function unavailable(

package/src/package-checks/duplicate-detection/finding-messages.ts

@@ -1,9 +1,9 @@
 import type { CheckMessage } from "../../check/check.ts";
-import { presentCheckFindings } from "../../check/finding-presentation.ts";
+import { presentCheckFindings } from "../../package-tools/finding-presentation/finding-presentation.ts";
 import type {
   FindingWaiverAudit,
   FindingWaiverReconciliation
-} from "../../finding-waivers/reconciliation.ts";
+} from "../../package-tools/finding-waivers/reconciliation.ts";
 import type { DuplicateDetectionFindingLocation } from "./options.ts";
 import { duplicateDetectionWaiverIdentity, type DuplicateRecordCandidate } from "./records.ts";
 

package/src/package-checks/duplicate-detection/jscpd/availability.ts

@@ -133,5 +133,5 @@ function commandOutput(result: ToolCommandResult): string {
 function processTermination(result: ToolCommandResult): string {
   return typeof result.status === "number"
     ? `exit ${result.status}`
-    : `signal ${result.signal || "unknown"}`;
+    : `signal ${result.signal ?? "unknown"}`;
 }

package/src/package-checks/duplicate-detection/options.ts

@@ -1,9 +1,10 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type {
   ProjectFileSelection,
   ProjectFileSelectionOptions
 } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 
 export type DuplicateDetectionScannerCommand =
   /** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
@@ -61,7 +62,9 @@ export interface DuplicateDetectionCodeAreaOptions {
 }
 
 /** `duplicateDetection(options?)` 接受并补齐默认值的公开策略。 */
-export interface DuplicateDetectionOptions {
+export interface DuplicateDetectionOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
   /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
   readonly codeAreas?: Readonly<Record<string, DuplicateDetectionCodeAreaOptions>>;
   readonly cache?: DuplicateDetectionCacheOptions;
@@ -72,7 +75,7 @@ export interface DuplicateDetectionOptions {
   readonly scanner?: DuplicateDetectionScannerOptions;
 }
 
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedDuplicateDetectionOptions {
   readonly cache: Readonly<{ readonly directory: string; readonly enabled: boolean }>;
   readonly codeAreas: Readonly<Record<string, ResolvedDuplicateDetectionCodeAreaOptions>>;

package/src/package-checks/duplicate-detection/records.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 
 import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
-import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import {
   buildHashedFindingWaiverAuditRecord,
   type FindingWaiverAuditRecordData,

package/src/package-checks/file-metrics/constructor.ts

@@ -1,4 +1,8 @@
 import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  resolvePackageCheckAuthoringInput,
+  type PackageCheckIdentityInput
+} from "../check-authoring.ts";
 import { FILE_METRICS_CHECK_DEFINITION, executeFileMetrics } from "./execution.ts";
 import { parseFileMetricsData } from "./final-data.ts";
 import type { FileMetricsOptions, ResolvedFileMetricsOptions } from "./options.ts";
@@ -9,23 +13,42 @@ import { isValidResolvedFileMetricsOptions } from "./options-validation.ts";
  * 使用可省略的区域、代码行与 scanner policy 构造一个完整 file-metrics Check。
  *
  * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
- * @returns 固定 `file-metrics` identity、完整冻结 options、preflight 与 execution。
+ * @returns 固定 `file-metrics` identity、完整冻结 options、preparation 与 execution。
  * @throws {TypeError} input 含未知字段、空 area、非法代码行 policy、非法 waiver 或空 executable 时抛出。
  */
+export function fileMetrics(
+  options?: FileMetricsOptions<"file-metrics">
+): TypedCheckWithOptions<"file-metrics", ResolvedFileMetricsOptions, typeof parseFileMetricsData>;
+export function fileMetrics<const Id extends string>(
+  options: FileMetricsOptions<Id> & PackageCheckIdentityInput<Id>
+): TypedCheckWithOptions<Id, ResolvedFileMetricsOptions, typeof parseFileMetricsData>;
+export function fileMetrics(
+  options: FileMetricsOptions
+): TypedCheckWithOptions<string, ResolvedFileMetricsOptions, typeof parseFileMetricsData>;
 export function fileMetrics(
   options: FileMetricsOptions = {}
-): TypedCheckWithOptions<"file-metrics", ResolvedFileMetricsOptions, typeof parseFileMetricsData> {
-  const resolvedOptions = resolveFileMetricsOptions(options);
+): TypedCheckWithOptions<string, ResolvedFileMetricsOptions, typeof parseFileMetricsData> {
+  const input = resolvePackageCheckAuthoringInput(
+    options,
+    ["codeAreas", "findingPolicy", "findingWaivers", "scanner"],
+    FILE_METRICS_CHECK_DEFINITION
+  );
+  if (input === undefined) {
+    throw new TypeError(
+      "fileMetrics options must match the documented closed { codeAreas?, findingPolicy?, findingWaivers?, scanner? } constructor policy"
+    );
+  }
+  const resolvedOptions = resolveFileMetricsOptions(input.domainOptions);
   if (resolvedOptions === undefined) {
     throw new TypeError(
       "fileMetrics options must match the documented closed { codeAreas?, findingPolicy?, findingWaivers?, scanner? } constructor policy"
     );
   }
   return defineCheck({
-    ...FILE_METRICS_CHECK_DEFINITION,
-    execution: executeFileMetrics,
+    ...input.definition,
+    execute: executeFileMetrics,
     parseData: parseFileMetricsData,
-    preflight: (preparedOptions) =>
+    prepare: (preparedOptions) =>
       isValidResolvedFileMetricsOptions(preparedOptions)
         ? { status: "success", preparedOptions }
         : {

package/src/package-checks/file-metrics/execution.ts

@@ -2,14 +2,14 @@ import type { CheckExecutionContext, CheckMessage, CheckResult } from "../../che
 import {
   reconcileFindingWaivers,
   type FindingWaiverReconciliation
-} from "../../finding-waivers/reconciliation.ts";
+} from "../../package-tools/finding-waivers/reconciliation.ts";
 import { collectProjectFileSets, requireProjectFileSet } from "../project-files/collection.ts";
 import { settleFindings } from "../code-quality-findings/policy.ts";
 import {
   reportFindingWaiverAudits,
   reportReconciledCodeQualityFindingRecords
 } from "../code-quality-findings/finding-waiver-evidence.ts";
-import { appendCheckMessages } from "../../check/finding-presentation.ts";
+import { appendCheckMessages } from "../../package-tools/finding-presentation/finding-presentation.ts";
 import { fileMetricFindingMessages } from "./finding-messages.ts";
 import { measureFileMetrics, type FileMeasurementResult } from "./measurement.ts";
 import type { FileMetricsExactInputSet } from "./measurement-model.ts";
@@ -196,8 +196,6 @@ function measurementFailureResult(
     case "unavailable":
       return unavailable("external-dependency-unavailable");
   }
-  const exhaustiveMeasurement: never = measurement;
-  return exhaustiveMeasurement;
 }
 
 function unavailable(code: FileMetricsUnavailableReasonCode): CheckResult<FileMetricsFinalData> {

package/src/package-checks/file-metrics/finding-messages.ts

@@ -1,5 +1,5 @@
 import type { CheckMessage } from "../../check/check.ts";
-import { presentCheckFindings } from "../../check/finding-presentation.ts";
+import { presentCheckFindings } from "../../package-tools/finding-presentation/finding-presentation.ts";
 import type { FileRecordCandidate } from "./records.ts";
 
 const PRESENTED_FINDING_LIMIT = 10;

package/src/package-checks/file-metrics/options.ts

@@ -1,9 +1,10 @@
+import type { PackageCheckAuthoringOptions } from "../check-authoring.ts";
 import type {
   ProjectFileSelection,
   ProjectFileSelectionOptions
 } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
-import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { FindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 
 /** `fileMetrics` 构造函数可省略的 SCC 可执行文件策略。 */
 export interface FileMetricsScannerOptions {
@@ -52,7 +53,9 @@ export interface FileMetricsFindingIdentity {
 export type FileMetricsFindingWaiver = FindingWaiver<FileMetricsFindingIdentity>;
 
 /** `fileMetrics(options?)` 接受并补齐默认值的公开策略。 */
-export interface FileMetricsOptions {
+export interface FileMetricsOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
   /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
   readonly codeAreas?: Readonly<Record<string, FileMetricsCodeAreaOptions>>;
   /** 省略时为 `non-blocking`；区域可局部覆盖。 */
@@ -63,7 +66,7 @@ export interface FileMetricsOptions {
   readonly scanner?: FileMetricsScannerOptions;
 }
 
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedFileMetricsOptions {
   readonly codeAreas: Readonly<Record<string, ResolvedFileMetricsCodeAreaOptions>>;
   readonly findingWaivers: readonly FileMetricsFindingWaiver[];

package/src/package-checks/file-metrics/records.ts

@@ -2,7 +2,7 @@ import type { FileMetric } from "./measurement-model.ts";
 import type { FileMetricsFindingIdentity, ResolvedFileMetricsCodeAreaOptions } from "./options.ts";
 import { isBlockingFinding } from "../code-quality-findings/policy.ts";
 import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
-import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import {
   buildFindingWaiverAuditRecordData,
   type FindingWaiverAuditRecordData,

package/src/package-checks/file-metrics/scc/availability.ts

@@ -96,5 +96,5 @@ function commandOutput(commandResult: SccVersionCommandResult): string {
 function processTermination(commandResult: SccVersionCommandResult): string {
   return typeof commandResult.status === "number"
     ? `exit ${commandResult.status}`
-    : `signal ${commandResult.signal || "unknown"}`;
+    : `signal ${commandResult.signal ?? "unknown"}`;
 }