@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -1,8 +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 "../../package-tools/finding-waivers/reconciliation.ts";
 
 /** `functionMetrics` 构造函数可省略的文件选择策略。 */
 export type FunctionMetricsFileOptions = ProjectFileSelectionOptions;
@@ -23,6 +25,10 @@ export interface FunctionMetricsLimitOptions {
     /** 省略时为 `12`。 */
     readonly maximum?: number;
   }>;
+  readonly nestingDepth?: Readonly<{
+    /** 省略时为 `7`。 */
+    readonly maximum?: number;
+  }>;
   readonly parameters?: Readonly<{
     /** 省略时为 `6`。 */
     readonly maximum?: number;
@@ -39,26 +45,42 @@ export interface FunctionMetricsCodeAreaOptions {
   readonly limits?: FunctionMetricsLimitOptions;
 }
 
-/** `functionMetrics` 构造函数可省略的 Lizard 可执行文件策略。 */
-export interface FunctionMetricsScannerOptions {
-  /** 省略时为 `lizard`；显式命令必须直接接受 adapter 拥有的 Lizard 参数。 */
-  readonly executable?: string;
+/** function-metrics 可形成 Finding 的封闭 metric 名称。 */
+export type FunctionMetricsFindingMetric =
+  | "cyclomatic-complexity"
+  | "function-code-density"
+  | "nesting-depth"
+  | "parameter-count";
+
+/** function-metrics 用于精确识别一条可豁免 metric finding 的稳定字段。 */
+export interface FunctionMetricsFindingIdentity {
+  readonly functionName: string;
+  readonly metric: FunctionMetricsFindingMetric;
+  /** 已 normalized 的 project-root-relative slash path。 */
+  readonly path: string;
+  /** 该次 finding 中函数起始位置的一基行号；位置变化会让旧 waiver 进入 unused audit。 */
+  readonly startLine: number;
 }
 
+/** 一项 function-metrics metric finding 的声明式豁免。 */
+export type FunctionMetricsFindingWaiver = FindingWaiver<FunctionMetricsFindingIdentity>;
+
 /** `functionMetrics(options?)` 接受并补齐默认值的公开策略。 */
-export interface FunctionMetricsOptions {
+export interface FunctionMetricsOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
   /** 省略时建立默认 `project` 区域；显式映射必须非空，且每个区域必须声明 `files`。 */
   readonly codeAreas?: Readonly<Record<string, FunctionMetricsCodeAreaOptions>>;
   /** 省略时为 `non-blocking`；区域可局部覆盖。 */
   readonly findingPolicy?: FindingPolicy;
-  /** 省略时使用 PATH 中的 `lizard`。 */
-  readonly scanner?: FunctionMetricsScannerOptions;
+  /** 省略时没有豁免；只匹配 normal metric finding，不匹配 input rejection。 */
+  readonly findingWaivers?: readonly FunctionMetricsFindingWaiver[];
 }
 
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedFunctionMetricsOptions {
   readonly codeAreas: Readonly<Record<string, ResolvedFunctionMetricsCodeAreaOptions>>;
-  readonly scanner: ResolvedFunctionMetricsScannerOptions;
+  readonly findingWaivers: readonly FunctionMetricsFindingWaiver[];
 }
 
 export interface ResolvedFunctionMetricsCodeAreaOptions {
@@ -76,9 +98,6 @@ export interface ResolvedFunctionMetricsLimits {
     }>;
   }>;
   readonly cyclomaticComplexity: Readonly<{ readonly maximum: number }>;
+  readonly nestingDepth: Readonly<{ readonly maximum: number }>;
   readonly parameters: Readonly<{ readonly maximum: number }>;
 }
-
-export interface ResolvedFunctionMetricsScannerOptions {
-  readonly executable: string;
-}

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

@@ -3,25 +3,45 @@ import {
   type FunctionMetricAnalysis,
   type FunctionMetricInstance
 } from "./analysis.ts";
+import type { MaterializedFindingWaiver } from "../../package-tools/finding-waivers/reconciliation.ts";
 import { isBlockingFinding } from "../code-quality-findings/policy.ts";
+import {
+  buildHashedFindingWaiverAuditRecord,
+  type FindingWaiverAuditRecordData,
+  type FindingWaiverRecordAudit
+} from "../code-quality-findings/finding-waiver-evidence.ts";
 import type { FunctionMetric, FunctionMetricsAreaInput } from "./measurement-model.ts";
-import type { ResolvedFunctionMetricsLimits } from "./options.ts";
+import type {
+  FunctionMetricsFindingIdentity,
+  FunctionMetricsFindingMetric,
+  ResolvedFunctionMetricsLimits
+} from "./options.ts";
+import { resolveFunctionMetricsFindingIdentity } from "./finding-waiver-identity.ts";
 
-type FunctionMetricName = "cyclomatic-complexity" | "function-code-density" | "parameter-count";
 const INPUT_REJECTED_RECORD_ID_PREFIX = "/input-rejected/";
-
 /** 一条超出函数 metric 上限的 supplemental Record data。 */
 export type FunctionMetricsFindingRecordData = Readonly<{
   readonly blocking: boolean;
   readonly codeAreas: readonly string[];
+  /** Complete source-ordered CCN contributors; present only for CCN findings. */
+  readonly complexityContributors?: readonly Readonly<{
+    readonly line: number;
+    readonly token: string;
+  }>[];
   readonly functionName: string;
   readonly limit: number;
-  readonly metric: FunctionMetricName;
+  readonly metric: FunctionMetricsFindingMetric;
   readonly path: string;
   readonly startLine: number;
   readonly value: number;
+  /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+  readonly waiver?: Readonly<{ readonly reason: string }>;
 }>;
 
+/** 未使用或过宽 function-metrics waiver 的 supplemental audit Record data。 */
+export type FunctionMetricsFindingWaiverAuditRecordData =
+  FindingWaiverAuditRecordData<FunctionMetricsFindingIdentity>;
+
 /** 一条已被 files policy 选中、但不受 functionMetrics 支持的输入 Finding。 */
 export type FunctionMetricsInputRejectedRecordData = Readonly<{
   readonly blocking: false;
@@ -31,10 +51,11 @@ export type FunctionMetricsInputRejectedRecordData = Readonly<{
   readonly reason: "unsupported-file-type";
 }>;
 
-/** functionMetrics 发布的 metric 或 input-rejection Record data。 */
+/** functionMetrics 发布的 metric、input-rejection 或 finding-waiver audit Record data。 */
 export type FunctionMetricsRecordData =
   | FunctionMetricsFindingRecordData
-  | FunctionMetricsInputRejectedRecordData;
+  | FunctionMetricsInputRejectedRecordData
+  | FunctionMetricsFindingWaiverAuditRecordData;
 
 export interface FunctionRecordCandidate {
   readonly data: FunctionMetricsFindingRecordData;
@@ -82,15 +103,42 @@ interface FunctionPolicyContext {
 interface FunctionMetricEvaluation {
   readonly blocking: boolean;
   readonly codeAreas: readonly string[];
+  readonly complexityContributors?: FunctionMetric["complexityContributors"];
   readonly functionName: string;
   readonly limit: number;
-  readonly metric: FunctionMetricName;
+  readonly metric: FunctionMetricsFindingMetric;
   readonly path: string;
   readonly startLine: number;
   readonly subject: string;
   readonly value: number;
 }
 
+export function functionMetricsFindingIdentity(
+  candidate: FunctionRecordCandidate
+): FunctionMetricsFindingIdentity {
+  const { functionName, metric, path, startLine } = candidate.data;
+  return Object.freeze({ functionName, metric, path, startLine });
+}
+
+export function functionMetricsWaiverIdentity(
+  waiver: MaterializedFindingWaiver
+): FunctionMetricsFindingIdentity {
+  const identity = resolveFunctionMetricsFindingIdentity(waiver.identity);
+  if (identity === undefined) {
+    throw new TypeError("functionMetrics waiver identity must retain a valid metric subject");
+  }
+  return identity;
+}
+
+/** 为一项未使用或过宽 waiver 构造 Check-owned audit Record。 */
+export function functionMetricsWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+  readonly data: FunctionMetricsFindingWaiverAuditRecordData;
+  readonly id: string;
+}> {
+  const identity = functionMetricsWaiverIdentity(audit.waiver);
+  return buildHashedFindingWaiverAuditRecord(identity, audit);
+}
+
 /** 为每个超过 matching-area 最严格阈值的 metric 构造 supplemental fact。 */
 export function buildFunctionRecordCandidates(
   analysis: FunctionMetricAnalysis,
@@ -148,6 +196,7 @@ function metricEvaluations(
   if (complexityEvaluation !== null) evaluations.push(complexityEvaluation);
   evaluations.push(
     codeLinesMetricEvaluation(instance, policyContext, matchingAreas),
+    nestingDepthMetricEvaluation(instance, policyContext, matchingAreas),
     parameterMetricEvaluation(instance, policyContext, matchingAreas)
   );
   return evaluations;
@@ -176,12 +225,26 @@ function complexityMetricEvaluation(
   if (value === null) return null;
   return {
     ...sharedMetricEvaluation(instance, policyContext),
+    complexityContributors: instance.metric.complexityContributors,
     limit: Math.min(...matchingAreas.map((area) => area.limits.cyclomaticComplexity.maximum)),
     metric: "cyclomatic-complexity",
     value
   };
 }
 
+function nestingDepthMetricEvaluation(
+  instance: FunctionMetricInstance,
+  policyContext: FunctionPolicyContext,
+  matchingAreas: MatchingFunctionMetricAreas
+): FunctionMetricEvaluation {
+  return {
+    ...sharedMetricEvaluation(instance, policyContext),
+    limit: Math.min(...matchingAreas.map((area) => area.limits.nestingDepth.maximum)),
+    metric: "nesting-depth",
+    value: instance.metric.nestingDepth.value
+  };
+}
+
 function codeLinesMetricEvaluation(
   instance: FunctionMetricInstance,
   policyContext: FunctionPolicyContext,
@@ -221,6 +284,9 @@ function appendFindingCandidate(
       data: Object.freeze({
         blocking: evaluation.blocking,
         codeAreas: evaluation.codeAreas,
+        ...(evaluation.complexityContributors === undefined
+          ? {}
+          : { complexityContributors: evaluation.complexityContributors }),
         functionName: evaluation.functionName,
         limit: evaluation.limit,
         metric: evaluation.metric,

package/src/package-checks/function-metrics/target-files.ts

@@ -1,78 +1,18 @@
-/** Lizard 1.23.0 官方 language readers 支持的 exact input 扩展名。 */
-const LIZARD_SUPPORTED_FILE_EXTENSIONS = Object.freeze([
-  "c",
-  "cc",
-  "cjs",
-  "cpp",
-  "cs",
-  "cxx",
-  "erl",
-  "es",
-  "escript",
-  "f",
-  "f03",
-  "f08",
-  "f70",
-  "f90",
-  "f95",
-  "for",
-  "fpp",
-  "ftn",
-  "gd",
-  "go",
-  "h",
-  "hpp",
-  "hrl",
-  "java",
-  "js",
-  "jsx",
-  "kt",
-  "kts",
-  "lua",
-  "m",
-  "mjs",
-  "mm",
-  "pck",
-  "php",
-  "pkb",
-  "pks",
-  "pl",
-  "plb",
-  "pls",
-  "pm",
-  "py",
-  "r",
-  "rb",
-  "rs",
-  "scala",
-  "sol",
-  "sql",
-  "st",
-  "swift",
-  "ts",
-  "ttcn",
-  "ttcnpp",
-  "tsx",
-  "vue",
-  "zig"
-] as const);
+import {
+  FUNCTION_METRICS_SUPPORTED_FILE_EXTENSIONS,
+  isFunctionMetricsAnalyzerSourceSupported
+} from "./analyzer-adapter.ts";
 
-const LIZARD_SUPPORTED_FILE_EXTENSION_SET: ReadonlySet<string> = new Set(
-  LIZARD_SUPPORTED_FILE_EXTENSIONS
-);
-
-/** functionMetrics 默认 files.include 使用的 case-insensitive extension globs。 */
-export const LIZARD_SUPPORTED_FILE_GLOBS = Object.freeze(
-  LIZARD_SUPPORTED_FILE_EXTENSIONS.map(
+/** functionMetrics default files.include uses the adapter's case-insensitive suffix capability. */
+export const FUNCTION_METRICS_SUPPORTED_FILE_GLOBS = Object.freeze(
+  FUNCTION_METRICS_SUPPORTED_FILE_EXTENSIONS.map(
     (extension) => `**/*.${caseInsensitiveExtensionPattern(extension)}`
   )
 );
 
-export function isLizardTarget(filePath: string): boolean {
-  const extensionSeparator = filePath.lastIndexOf(".");
-  if (extensionSeparator < 0) return false;
-  const extension = filePath.slice(extensionSeparator + 1).toLowerCase();
-  return LIZARD_SUPPORTED_FILE_EXTENSION_SET.has(extension);
+/** Whether an exact project-relative path has a translated analyzer reader. */
+export function isFunctionMetricsTarget(filePath: string): boolean {
+  return isFunctionMetricsAnalyzerSourceSupported(filePath);
 }
 
 function caseInsensitiveExtensionPattern(extension: string): string {

package/src/package-checks/{file-metrics/scc → host-environment}/csv.ts

@@ -1,5 +1,6 @@
 import { parse } from "csv-parse/sync";
 
+/** Parses untrusted scanner CSV into a complete matrix of strings. */
 export function parseCsvRows(csv: string): string[][] {
   const records: unknown = parse(csv, {
     bom: true,
@@ -7,11 +8,9 @@ export function parseCsvRows(csv: string): string[][] {
     skip_empty_lines: true,
     trim: true
   });
-
   if (!Array.isArray(records) || !records.every(isStringRow)) {
     throw new Error("CSV parser returned non-string rows");
   }
-
   return records;
 }
 

package/src/package-checks/host-environment/git.ts

@@ -1,5 +1,5 @@
-import { processFailed, runProcessSync } from "./process/command.ts";
-import type { ProcessResult, RunProcessSyncOptions } from "./process/command.ts";
+import { processFailed, runProcessSync } from "./process.ts";
+import type { ProcessResult, RunProcessSyncOptions } from "./process.ts";
 import { toSlashPath } from "./path.ts";
 
 export type RunGitOptions = Omit<RunProcessSyncOptions, "command">;
@@ -17,6 +17,17 @@ export function runGit(options: RunGitOptions): ProcessResult {
   return runProcessSync({ command: "git", ...options });
 }
 
+/** Renders the actionable failure evidence shared by Git operation boundaries. */
+export function gitFailureDetail(result: ProcessResult): string {
+  const stderr = result.stderr.trim();
+  if (stderr.length > 0) return stderr;
+  const processErrorMessage = result.error?.message;
+  if (processErrorMessage !== undefined && processErrorMessage.length > 0) {
+    return processErrorMessage;
+  }
+  return result.signal === null ? `exit status ${result.status}` : `signal ${result.signal}`;
+}
+
 export function gitHeadSha(cwd: string): string | null {
   const result = runGit({ args: ["rev-parse", "HEAD"], cwd });
   if (processFailed(result)) return null;

package/src/package-checks/host-environment/path.ts

@@ -1,20 +1 @@
-export function toSlashPath(filePath: string): string {
-  return filePath.replace(/\\/g, "/");
-}
-
-/** 判断值是否已是跨平台可稳定发布的 project-root-relative slash path。 */
-export function isNormalizedProjectRelativePath(value: unknown): value is string {
-  if (
-    typeof value !== "string" ||
-    value.length === 0 ||
-    value.startsWith("/") ||
-    value.includes("\\") ||
-    value.includes("\u0000") ||
-    /^[A-Za-z]:/u.test(value)
-  ) {
-    return false;
-  }
-  return value
-    .split("/")
-    .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
-}
+export { isNormalizedProjectRelativePath, toSlashPath } from "../../data-boundary/project-path.ts";

package/src/package-checks/host-environment/process/contract.ts

@@ -12,9 +12,12 @@ export interface ProcessFailure extends Error {
 
 export type ProcessResult = {
   readonly error?: Error;
+  readonly isCanceled?: true;
+  readonly isMaxBuffer?: true;
   readonly signal: NodeJS.Signals | null;
   readonly status: number | null;
   readonly stderr: string;
+  readonly timedOut?: true;
   readonly stdout: string;
 };
 
@@ -32,8 +35,11 @@ export type RunProcessSyncOptions = {
 
 export type RunProcessOptions = {
   readonly args?: readonly string[];
+  readonly cancelSignal?: AbortSignal;
   readonly command: string;
   readonly cwd?: string | URL;
+  /** `false` uses only the supplied `env`; omission preserves Execa's inherited default. */
+  readonly extendEnv?: boolean;
   readonly env?: NodeJS.ProcessEnv;
   readonly label?: string;
   readonly maxBuffer?: number;
@@ -42,15 +48,17 @@ export type RunProcessOptions = {
 };
 
 export type ExecaResultLike = {
-  readonly code?: string;
-  readonly exitCode?: number;
-  readonly failed?: boolean;
-  readonly isMaxBuffer?: boolean;
-  readonly message?: string;
-  readonly originalMessage?: string;
-  readonly shortMessage?: string;
-  readonly signal?: NodeJS.Signals;
+  /** Execa's imported result types permit explicitly present `undefined` values. */
+  readonly code?: string | undefined;
+  readonly exitCode?: number | undefined;
+  readonly failed?: boolean | undefined;
+  readonly isCanceled?: boolean | undefined;
+  readonly isMaxBuffer?: boolean | undefined;
+  readonly message?: string | undefined;
+  readonly originalMessage?: string | undefined;
+  readonly shortMessage?: string | undefined;
+  readonly signal?: NodeJS.Signals | undefined;
   readonly stderr?: unknown;
   readonly stdout?: unknown;
-  readonly timedOut?: boolean;
+  readonly timedOut?: boolean | undefined;
 };

package/src/package-checks/host-environment/process/result.ts

@@ -1,11 +1,16 @@
 import type { ExecaResultLike, ProcessResult } from "./contract.ts";
 
 export function toProcessResult(result: ExecaResultLike, label: string): ProcessResult {
+  const cause = processCause(result);
+  const error = processErrorFor(result, label, cause);
   return {
-    error: processErrorFor(result, label),
+    ...(error === undefined ? {} : { error }),
+    ...(cause === "cancellation" ? { isCanceled: true as const } : {}),
+    ...(cause === "max-buffer" ? { isMaxBuffer: true as const } : {}),
     signal: result.signal ?? null,
     status: result.exitCode ?? null,
     stderr: outputString(result.stderr),
+    ...(cause === "timeout" ? { timedOut: true as const } : {}),
     stdout: outputString(result.stdout)
   };
 }
@@ -14,26 +19,49 @@ function outputString(output: unknown): string {
   return typeof output === "string" ? output : "";
 }
 
-function processErrorFor(result: ExecaResultLike, label = "process"): Error | undefined {
-  if (!isExecutionError(result)) {
-    return undefined;
-  }
-
-  const message =
-    result.originalMessage ?? result.shortMessage ?? result.message ?? `${label} failed`;
-  const error: NodeJS.ErrnoException = new Error(message);
-  if (result.code) {
-    error.code = result.code;
-  }
+type ProcessCause =
+  | "cancellation"
+  | "exit"
+  | "max-buffer"
+  | "signal"
+  | "startup-failure"
+  | "timeout";
+
+function processCause(result: ExecaResultLike): ProcessCause {
+  if (typeof result.exitCode === "number" && result.exitCode !== 0) return "exit";
+  if (result.isCanceled === true) return "cancellation";
+  if (result.timedOut === true) return "timeout";
+  if (result.isMaxBuffer === true) return "max-buffer";
+  if (result.signal !== undefined) return "signal";
+  if (result.exitCode === 0) return "exit";
+  return "startup-failure";
+}
+
+function processErrorFor(
+  result: ExecaResultLike,
+  label: string,
+  cause: ProcessCause
+): Error | undefined {
+  if (!requiresProcessError(cause, result)) return undefined;
+
+  const error: NodeJS.ErrnoException = new Error(processErrorMessage(result, label));
+  const code = processErrorCode(result);
+  if (code !== undefined) error.code = code;
   return error;
 }
 
-function isExecutionError(result: ExecaResultLike): boolean {
-  if (!result.failed) {
-    return false;
-  }
-  if (typeof result.exitCode === "number") {
-    return false;
-  }
-  return Boolean(result.code || result.timedOut || result.isMaxBuffer || result.signal);
+function requiresProcessError(cause: ProcessCause, result: ExecaResultLike): boolean {
+  return cause !== "exit" && result.failed === true;
+}
+
+function processErrorMessage(result: ExecaResultLike, label: string): string {
+  if (result.originalMessage !== undefined) return result.originalMessage;
+  if (result.shortMessage !== undefined) return result.shortMessage;
+  if (result.message !== undefined) return result.message;
+  return `${label} failed`;
+}
+
+function processErrorCode(result: ExecaResultLike): string | undefined {
+  if (result.code === undefined || result.code.length === 0) return undefined;
+  return result.code;
 }

package/src/package-checks/host-environment/process/runner.ts

@@ -14,7 +14,7 @@ export function runProcessSync(options: RunProcessSyncOptions): ProcessResult {
   const result = execaSync(command, args, {
     ...processOptions,
     encoding: processOptions.encoding ?? "utf8",
-    env: plainTextProcessEnv({ env: processOptions.env }),
+    env: plainTextProcessEnv(processOptions.env === undefined ? {} : { env: processOptions.env }),
     maxBuffer: processOptions.maxBuffer ?? DEFAULT_PROCESS_MAX_BUFFER_BYTES,
     reject: false,
     stripFinalNewline: false,
@@ -26,9 +26,11 @@ export function runProcessSync(options: RunProcessSyncOptions): ProcessResult {
 export function runProcess(options: RunProcessOptions): Promise<ProcessResult> {
   const {
     args = [],
+    cancelSignal,
     command,
     cwd,
     env,
+    extendEnv,
     label = command,
     maxBuffer = DEFAULT_PROCESS_MAX_BUFFER_BYTES,
     timeout,
@@ -36,12 +38,14 @@ export function runProcess(options: RunProcessOptions): Promise<ProcessResult> {
   } = options;
 
   return execa(command, args, {
-    cwd,
-    env: plainTextProcessEnv({ env }),
+    ...(cancelSignal === undefined ? {} : { cancelSignal }),
+    ...(cwd === undefined ? {} : { cwd }),
+    ...(extendEnv === undefined ? {} : { extendEnv }),
+    env: plainTextProcessEnv(env === undefined ? {} : { env }),
     maxBuffer,
     reject: false,
     stripFinalNewline: false,
-    timeout,
+    ...(timeout === undefined ? {} : { timeout }),
     windowsHide
   }).then((result) => toProcessResult(result, label));
 }

package/src/package-checks/host-environment/process.ts

@@ -0,0 +1,10 @@
+export { processFailure, processFailureFromResult, processFailed } from "./process/failure.ts";
+export { PLAIN_TEXT_PROCESS_ENV, plainTextProcessEnv } from "./process/env.ts";
+export { runProcess, runProcessSync } from "./process/runner.ts";
+export { DEFAULT_PROCESS_MAX_BUFFER_BYTES } from "./process/contract.ts";
+export type {
+  ProcessFailure,
+  ProcessResult,
+  RunProcessOptions,
+  RunProcessSyncOptions
+} from "./process/contract.ts";

package/src/package-checks/json-schema-validation/default-check.ts

@@ -1,4 +1,8 @@
 import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import {
+  resolvePackageCheckAuthoringInput,
+  type PackageCheckIdentityInput
+} from "../check-authoring.ts";
 import {
   JSON_SCHEMA_VALIDATION_CHECK_DEFINITION,
   executeJsonSchemaValidation
@@ -19,21 +23,50 @@ import { validJsonSchemaValidationOptions } from "./options-validation.ts";
  * @throws {TypeError} input 不符合 closed authoring policy、identity 或 binding 不变量时抛出。
  */
 export function jsonSchemaValidation(
-  options: JsonSchemaValidationOptions = {}
+  options?: JsonSchemaValidationOptions<"json-schema-validation">
 ): TypedCheckWithOptions<
   "json-schema-validation",
   ResolvedJsonSchemaValidationOptions,
   typeof parseJsonSchemaValidationData
+>;
+export function jsonSchemaValidation<const Id extends string>(
+  options: JsonSchemaValidationOptions<Id> & PackageCheckIdentityInput<Id>
+): TypedCheckWithOptions<
+  Id,
+  ResolvedJsonSchemaValidationOptions,
+  typeof parseJsonSchemaValidationData
+>;
+export function jsonSchemaValidation(
+  options: JsonSchemaValidationOptions
+): TypedCheckWithOptions<
+  string,
+  ResolvedJsonSchemaValidationOptions,
+  typeof parseJsonSchemaValidationData
+>;
+export function jsonSchemaValidation(
+  options: JsonSchemaValidationOptions = {}
+): TypedCheckWithOptions<
+  string,
+  ResolvedJsonSchemaValidationOptions,
+  typeof parseJsonSchemaValidationData
 > {
-  const resolvedOptions = resolveJsonSchemaValidationOptions(options);
+  const input = resolvePackageCheckAuthoringInput(
+    options,
+    ["files", "maximumBytes", "schemaIdentity", "referenceResolution", "schemas", "bindings"],
+    JSON_SCHEMA_VALIDATION_CHECK_DEFINITION
+  );
+  if (input === undefined) {
+    throw new TypeError("jsonSchemaValidation options must match the documented closed policy");
+  }
+  const resolvedOptions = resolveJsonSchemaValidationOptions(input.domainOptions);
   if (resolvedOptions === undefined) {
     throw new TypeError("jsonSchemaValidation options must match the documented closed policy");
   }
   return defineCheck({
-    ...JSON_SCHEMA_VALIDATION_CHECK_DEFINITION,
-    execution: executeJsonSchemaValidation,
+    ...input.definition,
+    execute: executeJsonSchemaValidation,
     parseData: parseJsonSchemaValidationData,
-    preflight: (preparedOptions) =>
+    prepare: (preparedOptions) =>
       validJsonSchemaValidationOptions(preparedOptions)
         ? { status: "success", preparedOptions }
         : {

package/src/package-checks/json-schema-validation/final-data.ts

@@ -9,13 +9,21 @@ export const MAX_REPORTED_JSON_SCHEMA_ISSUES = 100;
 
 /** `json-schema-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface JsonSchemaValidationFinalData {
+  /** Definition 中已声明的 binding 总数。 */
   readonly bindingCount: number;
+  /** 因所引用 schema 存在 document 或 compile issue 而未验证 instance 的 binding 数。 */
   readonly blockedBindingCount: number;
+  /** instance out-of-scope、document invalid 或不符合对应 schema 的 binding 数。 */
   readonly invalidBindingCount: number;
+  /** schema document、compile、instance 与 keyword issue 的总数。 */
   readonly issueCount: number;
+  /** 是否因发布上限而省略了一个或多个 issue Record。 */
   readonly issuesTruncated: boolean;
+  /** 实际发布为 Record 的 issue 数。 */
   readonly reportedIssueCount: number;
+  /** Definition 中声明的不同 schema identity 数。 */
   readonly schemaCount: number;
+  /** input 符合对应 schema 的 binding 数。 */
   readonly validBindingCount: number;
 }