@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -3,6 +3,7 @@ import type {
   ProjectFileSelectionOptions
 } from "../project-files/configuration.ts";
 import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
 
 /** `functionMetrics` 构造函数可省略的文件选择策略。 */
 export type FunctionMetricsFileOptions = ProjectFileSelectionOptions;
@@ -23,6 +24,10 @@ export interface FunctionMetricsLimitOptions {
     /** 省略时为 `12`。 */
     readonly maximum?: number;
   }>;
+  readonly nestingDepth?: Readonly<{
+    /** 省略时为 `7`。 */
+    readonly maximum?: number;
+  }>;
   readonly parameters?: Readonly<{
     /** 省略时为 `6`。 */
     readonly maximum?: number;
@@ -39,26 +44,40 @@ 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 {
   /** 省略时建立默认 `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。 */
 export interface ResolvedFunctionMetricsOptions {
   readonly codeAreas: Readonly<Record<string, ResolvedFunctionMetricsCodeAreaOptions>>;
-  readonly scanner: ResolvedFunctionMetricsScannerOptions;
+  readonly findingWaivers: readonly FunctionMetricsFindingWaiver[];
 }
 
 export interface ResolvedFunctionMetricsCodeAreaOptions {
@@ -76,9 +95,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 "../../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">;

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/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;
 }
 

package/src/package-checks/json-schema-validation/options-validation.ts

@@ -1,27 +1,16 @@
 import {
-  hasExactPlainRecordKeys,
   snapshotClosedArray,
-  snapshotClosedRecord
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
 } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
 import { validProjectFileSelection } from "../project-files/configuration.ts";
 import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
 
-function exactRecord(
-  value: unknown,
-  keys: readonly string[]
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
-}
-
-function positiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
 export function validJsonSchemaValidationOptions(
   candidateOptions: unknown
 ): candidateOptions is ResolvedJsonSchemaValidationOptions {
-  const options = exactRecord(candidateOptions, [
+  const options = snapshotExactClosedRecord(candidateOptions, [
     "files",
     "maximumBytes",
     "schemaIdentity",
@@ -32,7 +21,7 @@ export function validJsonSchemaValidationOptions(
   if (
     options === undefined ||
     !validProjectFileSelection(options.files) ||
-    !positiveSafeInteger(options.maximumBytes) ||
+    !isPositiveSafeInteger(options.maximumBytes) ||
     !validJsonSchemaIdentity(options.schemaIdentity) ||
     !validJsonSchemaReferenceResolution(options.referenceResolution)
   ) {
@@ -50,7 +39,7 @@ export function validJsonSchemaValidationOptions(
 }
 
 function validJsonSchemaIdentity(candidateIdentity: unknown): boolean {
-  const identity = exactRecord(candidateIdentity, ["mode"]);
+  const identity = snapshotExactClosedRecord(candidateIdentity, ["mode"]);
   return (
     identity !== undefined &&
     (identity.mode === "require-match" ||
@@ -65,11 +54,11 @@ function validJsonSchemaReferenceResolution(candidateResolution: unknown): boole
     return false;
   }
   if (referenceResolution.mode === "offline") {
-    return exactRecord(referenceResolution, ["mode"]) !== undefined;
+    return snapshotExactClosedRecord(referenceResolution, ["mode"]) !== undefined;
   }
   if (referenceResolution.mode !== "allowlisted") return false;
 
-  const allowlisted = exactRecord(referenceResolution, ["mode", "sources"]);
+  const allowlisted = snapshotExactClosedRecord(referenceResolution, ["mode", "sources"]);
   const sources = allowlisted === undefined ? undefined : snapshotClosedArray(allowlisted.sources);
   return sources !== undefined && sources.length > 0 && validJsonSchemaReferenceSources(sources);
 }
@@ -104,11 +93,11 @@ function validatedReferenceSource(sourceCandidate: unknown) {
 }
 
 function validBundledSource(source: Readonly<Record<string, unknown>>): boolean {
-  return exactRecord(source, ["kind", "catalog"])?.catalog === "json-schema-2020-12";
+  return snapshotExactClosedRecord(source, ["kind", "catalog"])?.catalog === "json-schema-2020-12";
 }
 
 function validatedHttpsSource(source: Readonly<Record<string, unknown>>) {
-  const httpsSource = exactRecord(source, ["kind", "id", "origin", "pathPrefix"]);
+  const httpsSource = snapshotExactClosedRecord(source, ["kind", "id", "origin", "pathPrefix"]);
   if (
     httpsSource === undefined ||
     !safeAbsoluteIdentifier(httpsSource.id) ||
@@ -124,7 +113,7 @@ function validatedSchemaRegistryIds(schemas: readonly unknown[]): ReadonlySet<st
   const declaredSchemaIds = new Set<string>();
   const schemaPaths = new Set<string>();
   for (const schemaCandidate of schemas) {
-    const schemaRecord = exactRecord(schemaCandidate, ["id", "path"]);
+    const schemaRecord = snapshotExactClosedRecord(schemaCandidate, ["id", "path"]);
     if (
       schemaRecord === undefined ||
       !safeAbsoluteIdentifier(schemaRecord.id) ||
@@ -147,7 +136,11 @@ function validJsonSchemaBindings(
   const bindingIds = new Set<string>();
   const bindingTargets = new Set<string>();
   for (const bindingCandidate of bindings) {
-    const bindingRecord = exactRecord(bindingCandidate, ["id", "instancePath", "schemaId"]);
+    const bindingRecord = snapshotExactClosedRecord(bindingCandidate, [
+      "id",
+      "instancePath",
+      "schemaId"
+    ]);
     if (
       bindingRecord === undefined ||
       !safeBindingId(bindingRecord.id) ||

package/src/package-checks/json-schema-validation/options.ts

@@ -3,39 +3,62 @@ import type {
   ProjectFileSelectionOptions
 } from "../project-files/configuration.ts";
 
+/** 已注册 schema 的 root `$id` 与配置 identity 之间的全 Check 统一规则。 */
 export type JsonSchemaIdentityMode =
+  /** root `$id` 必须等于 `schemas[].id`，该配置 ID 也是 engine identity。 */
   | "require-match"
+  /** 配置 ID 是 engine identity；object schema 的 invocation-local compile copy 使用该 `$id`。 */
   | "configuration-authoritative"
+  /** 安全的 root `$id` 是 engine identity；配置 ID 仍是 binding 与公开事实的标签。 */
   | "document-authoritative";
 
+/** 整个 Check 共用、不能按单个 schema 混用的 root schema identity policy。 */
 export interface JsonSchemaIdentity {
+  /** root `$id` 与配置 `schemas[].id` 的关系。 */
   readonly mode: JsonSchemaIdentityMode;
 }
 
+/** allowlisted 引用解析可读取的单一 Schema 来源及其固定边界。 */
 export type JsonSchemaReferenceSource =
+  /** Package 固定的 JSON Schema catalog；它不授权网络请求。 */
   | Readonly<{ readonly kind: "bundled"; readonly catalog: "json-schema-2020-12" }>
   | Readonly<{
+      /** 只允许本 source 明确限定的 HTTPS reference scope。 */
       readonly kind: "https";
+      /** 调用方为本 source 选择的安全稳定 identity，不是请求 URL。 */
       readonly id: string;
+      /** 精确 HTTPS origin；不含 path、credentials、query 或 fragment。 */
       readonly origin: string;
+      /** 已授权 URL path 的边界；从 `/` 开始，非 root prefix 必须以 `/` 结束。 */
       readonly pathPrefix: string;
     }>;
 
+/** 本次 Check 解析 local、bundled 与 allowlisted Schema 引用的封闭策略。 */
 export type JsonSchemaReferenceResolution =
+  /** 只使用 local schemas 和允许的 bundled catalog，不读取额外 HTTPS schema。 */
   | Readonly<{ readonly mode: "offline" }>
   | Readonly<{
+      /** 只从 `sources` 的精确 scope 读取额外 schema；没有 implicit registry、headers 或 redirects。 */
       readonly mode: "allowlisted";
+      /** 完整替换的明确 source 集合；每项决定自身可读取的 reference scope。 */
       readonly sources: readonly JsonSchemaReferenceSource[];
     }>;
 
+/** 调用方注册的一份 local schema resource；注册表不自动发现 schema。 */
 export interface RegisteredJsonSchema {
+  /** binding 与公开 facts 使用的安全 schema identity。 */
   readonly id: string;
+  /** 已由 `files` selection 批准的 normalized project-relative `.json` path。 */
   readonly path: string;
 }
 
+/** 调用方将一个已批准 local JSON instance 明确绑定到已注册 schema 的关系。 */
 export interface JsonSchemaInstanceBinding {
+  /** 本次 Check 内唯一、用于公开 facts 的 binding identity。 */
   readonly id: string;
+  /** 已由 `files` selection 批准的 normalized project-relative `.json` instance path。 */
   readonly instancePath: string;
+  /** 必须引用 `schemas` 中已注册 schema 的 identity。 */
   readonly schemaId: string;
 }
 

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

@@ -6,10 +6,15 @@ import {
 
 /** `json-validation` 在 passed/failed outcome 中发布的主数据。 */
 export interface JsonValidationFinalData {
+  /** 已完成 JSON parse 判定的文件数，恒等于 validFileCount 与 invalidFileCount 之和。 */
   readonly scannedFileCount: number;
+  /** 被 bounded strict-document boundary 接受为有效 JSON 的文件数。 */
   readonly validFileCount: number;
+  /** 形成 `too-large`、encoding、syntax 或 duplicate-key document issue 的文件数。 */
   readonly invalidFileCount: number;
+  /** 全部 invalid file 与 rejected input 的合计问题数。 */
   readonly issueCount: number;
+  /** files policy 已选中、但因不是 lower-case `.json` path 而被拒绝的输入数。 */
   readonly rejectedInputCount: number;
 }
 

package/src/package-checks/json-validation/options-validation.ts

@@ -1,27 +1,13 @@
-import {
-  hasExactPlainRecordKeys,
-  snapshotClosedRecord
-} from "../../data-boundary/closed-values.ts";
+import { snapshotExactClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
 import { validProjectFileSelection } from "../project-files/configuration.ts";
 import type { ResolvedJsonValidationOptions } from "./options.ts";
 
-function exactRecord(
-  value: unknown,
-  keys: readonly string[]
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
-}
-
-function positiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
 export function validJsonValidationOptions(value: unknown): value is ResolvedJsonValidationOptions {
-  const options = exactRecord(value, ["files", "maximumBytes"]);
+  const options = snapshotExactClosedRecord(value, ["files", "maximumBytes"]);
   return (
     options !== undefined &&
     validProjectFileSelection(options.files) &&
-    positiveSafeInteger(options.maximumBytes)
+    isPositiveSafeInteger(options.maximumBytes)
   );
 }

package/src/package-checks/maintenance-reminders/final-data.ts

@@ -43,25 +43,42 @@ export function isMaintenanceCommitId(value: unknown): value is string {
 }
 
 export type MeasuredMaintenanceReminderAssessment = Readonly<{
+  /** 未超过任何阈值时为 clear；至少严格超过一个阈值时为 due。 */
   readonly assessment: "clear" | "due";
+  /** reminder 配置锁定的完整基线 commit ID。 */
   readonly baseCommit: string;
+  /** first-parent 区间内 numstat additions 与 deletions 的总和。 */
   readonly changedLines: number;
+  /** 从 HEAD 沿 first-parent 到 baseCommit 的 commit 数。 */
   readonly commitCount: number;
+  /** 实际值严格超过配置上限的维度；clear assessment 时为空。 */
   readonly exceeded: readonly ("commits" | "changed-lines")[];
+  /** 测量时 HEAD 的完整 commit ID。 */
   readonly headCommit: string;
+  /** Definition 中该 reminder 的稳定局部 ID。 */
   readonly id: string;
+  /** due 或 unavailable 是否阻断 Check 的配置模式。 */
   readonly mode: MaintenanceReminderMode;
 }>;
 
 export type UnavailableMaintenanceReminderAssessment = Readonly<{
+  /** 表示该 reminder 未能形成计数测量。 */
   readonly assessment: "unavailable";
+  /** reminder 配置锁定的完整基线 commit ID。 */
   readonly baseCommit: string;
+  /** unavailable assessment 不发布 partial changed-line count。 */
   readonly changedLines: null;
+  /** unavailable assessment 不发布 partial commit count。 */
   readonly commitCount: null;
+  /** unavailable assessment 不判定任何阈值已超过。 */
   readonly exceeded: readonly [];
+  /** 已成功解析时的完整 HEAD commit ID；解析 HEAD 失败时为 null。 */
   readonly headCommit: string | null;
+  /** Definition 中该 reminder 的稳定局部 ID。 */
   readonly id: string;
+  /** due 或 unavailable 是否阻断 Check 的配置模式。 */
   readonly mode: MaintenanceReminderMode;
+  /** 未能测量的稳定机器可读原因。 */
   readonly reason: MaintenanceReminderUnavailableReason;
 }>;
 
@@ -72,6 +89,7 @@ export type MaintenanceReminderAssessment =
 
 /** `maintenance-reminders` 在 passed/failed outcome 中发布的主数据。 */
 export interface MaintenanceRemindersFinalData {
+  /** 每个已配置 reminder 的唯一 assessment，按 Definition 顺序发布。 */
   readonly entries: readonly MaintenanceReminderAssessment[];
 }