@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -1,33 +1,25 @@
-import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import {
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString, isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
 import { validProjectFileSelection } from "../project-files/configuration.ts";
 import { validFindingPolicy } from "../code-quality-findings/policy.ts";
-
-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 positiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
-function nonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.length > 0;
-}
+import { validResolvedFindingWaivers } from "../code-quality-findings/finding-waiver-authoring.ts";
+import { resolveDuplicateDetectionFindingIdentity } from "./finding-waiver-identity.ts";
 
 export function validResolvedDuplicateDetectionOptions(value: object): boolean {
-  const options = exactRecord(value, ["cache", "codeAreas", "scanner"]);
+  const options = snapshotExactClosedRecord(value, [
+    "cache",
+    "codeAreas",
+    "findingWaivers",
+    "scanner"
+  ]);
   return (
     options !== undefined &&
     validDuplicateCache(options.cache) &&
     validDuplicateCodeAreas(options.codeAreas) &&
+    validResolvedFindingWaivers(options.findingWaivers, resolveDuplicateDetectionFindingIdentity) &&
     validDuplicateDetectionScanner(options.scanner)
   );
 }
@@ -36,25 +28,25 @@ function validDuplicateCodeAreas(value: unknown): boolean {
   const areas = snapshotClosedRecord(value);
   if (areas === undefined || Object.keys(areas).length === 0) return false;
   return Object.entries(areas).every(([areaId, candidate]) => {
-    const area = exactRecord(candidate, [
+    const area = snapshotExactClosedRecord(candidate, [
       "files",
       "findingPolicy",
       "minimumLines",
       "minimumTokens"
     ]);
     return (
-      nonEmptyString(areaId) &&
+      isNonEmptyString(areaId) &&
       area !== undefined &&
       validProjectFileSelection(area.files) &&
       validFindingPolicy(area.findingPolicy) &&
-      positiveSafeInteger(area.minimumLines) &&
-      positiveSafeInteger(area.minimumTokens)
+      isPositiveSafeInteger(area.minimumLines) &&
+      isPositiveSafeInteger(area.minimumTokens)
     );
   });
 }
 
 function validDuplicateDetectionScanner(value: unknown): boolean {
-  const scanner = exactRecord(value, ["command"]);
+  const scanner = snapshotExactClosedRecord(value, ["command"]);
   return scanner !== undefined && validJscpdCommand(scanner.command);
 }
 
@@ -63,13 +55,13 @@ function validJscpdCommand(value: unknown): boolean {
   if (record?.kind === "package") {
     return Object.keys(record).length === 1;
   }
-  const command = exactRecord(value, ["executable", "kind"]);
-  return command?.kind === "custom" && nonEmptyString(command.executable);
+  const command = snapshotExactClosedRecord(value, ["executable", "kind"]);
+  return command?.kind === "custom" && isNonEmptyString(command.executable);
 }
 
 function validDuplicateCache(value: unknown): boolean {
-  const cache = exactRecord(value, ["directory", "enabled"]);
+  const cache = snapshotExactClosedRecord(value, ["directory", "enabled"]);
   return (
-    cache !== undefined && nonEmptyString(cache.directory) && typeof cache.enabled === "boolean"
+    cache !== undefined && isNonEmptyString(cache.directory) && typeof cache.enabled === "boolean"
   );
 }

package/src/package-checks/duplicate-detection/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";
 
 export type DuplicateDetectionScannerCommand =
   /** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
@@ -28,10 +29,26 @@ export interface DuplicateDetectionScannerOptions {
   readonly command?: DuplicateDetectionScannerCommand;
 }
 
+/** duplicate-detection identity 的 locations 数组中的一段 project-relative range。 */
+export interface DuplicateDetectionFindingLocation {
+  readonly endLine: number;
+  readonly path: string;
+  readonly startLine: number;
+}
+
+/** duplicate-detection 用于精确识别一条可豁免 finding 的稳定字段。 */
+export interface DuplicateDetectionFindingIdentity {
+  readonly locations: readonly DuplicateDetectionFindingLocation[];
+  readonly metric: "duplicate-tokens";
+}
+
+/** 一项 duplicate-detection finding 的声明式豁免。 */
+export type DuplicateDetectionFindingWaiver = FindingWaiver<DuplicateDetectionFindingIdentity>;
+
 /** 重复代码区域可省略并由构造函数补齐的文件策略。 */
 export type DuplicateDetectionFileOptions = ProjectFileSelectionOptions;
 
-/** 可独立选择文件、阈值和 finding policy 的重复代码区域。 */
+/** 同时拥有文件选择、比较边界、阈值和 finding policy 的重复代码区域。 */
 export interface DuplicateDetectionCodeAreaOptions {
   /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
   readonly files: DuplicateDetectionFileOptions;
@@ -50,6 +67,8 @@ export interface DuplicateDetectionOptions {
   readonly cache?: DuplicateDetectionCacheOptions;
   /** 省略时为 `non-blocking`；区域可局部覆盖。 */
   readonly findingPolicy?: FindingPolicy;
+  /** 省略时没有豁免；identity 使用 Finding 发布的完整排序 location ranges。 */
+  readonly findingWaivers?: readonly DuplicateDetectionFindingWaiver[];
   readonly scanner?: DuplicateDetectionScannerOptions;
 }
 
@@ -57,6 +76,7 @@ export interface DuplicateDetectionOptions {
 export interface ResolvedDuplicateDetectionOptions {
   readonly cache: Readonly<{ readonly directory: string; readonly enabled: boolean }>;
   readonly codeAreas: Readonly<Record<string, ResolvedDuplicateDetectionCodeAreaOptions>>;
+  readonly findingWaivers: readonly DuplicateDetectionFindingWaiver[];
   readonly scanner: ResolvedDuplicateDetectionScannerOptions;
 }
 

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

@@ -1,12 +1,25 @@
 import { createHash } from "node:crypto";
 
 import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
+import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import {
+  buildHashedFindingWaiverAuditRecord,
+  type FindingWaiverAuditRecordData,
+  type FindingWaiverRecordAudit
+} from "../code-quality-findings/finding-waiver-evidence.ts";
 import { isBlockingFinding, type FindingPolicy } from "../code-quality-findings/policy.ts";
+import {
+  compareDuplicateFindingLocations,
+  resolveDuplicateDetectionFindingIdentity
+} from "./finding-waiver-identity.ts";
 import type { DuplicateCodeFragment, DuplicateCodeLocation } from "./measurement-model.ts";
-import type { ResolvedDuplicateDetectionOptions } from "./options.ts";
+import type {
+  DuplicateDetectionFindingIdentity,
+  ResolvedDuplicateDetectionOptions
+} from "./options.ts";
 
 /** 一条可信重复片段 supplemental Record 的 data。 */
-export type DuplicateDetectionRecordData = Readonly<{
+export type DuplicateDetectionFindingRecordData = Readonly<{
   readonly blocking: boolean;
   readonly codeAreas: readonly string[];
   readonly lineCount: number;
@@ -17,11 +30,50 @@ export type DuplicateDetectionRecordData = Readonly<{
   }>[];
   readonly metric: "duplicate-tokens";
   readonly tokenCount: number;
+  /** 精确匹配 waiver 时保留理由，并令该 finding 不再参与 actionable settlement。 */
+  readonly waiver?: Readonly<{ readonly reason: string }>;
 }>;
 
+/** 未使用或过宽 duplicate-detection waiver 的 supplemental audit Record data。 */
+export type DuplicateDetectionFindingWaiverAuditRecordData =
+  FindingWaiverAuditRecordData<DuplicateDetectionFindingIdentity>;
+
+/** duplicateDetection 发布的 normal finding 或 waiver-audit Record data。 */
+export type DuplicateDetectionRecordData =
+  | DuplicateDetectionFindingRecordData
+  | DuplicateDetectionFindingWaiverAuditRecordData;
+
 export interface DuplicateRecordCandidate {
-  readonly data: DuplicateDetectionRecordData;
+  readonly data: DuplicateDetectionFindingRecordData;
+  readonly id: string;
+}
+
+export function duplicateDetectionFindingIdentity(
+  candidate: DuplicateRecordCandidate
+): DuplicateDetectionFindingIdentity {
+  return Object.freeze({
+    locations: candidate.data.locations,
+    metric: candidate.data.metric
+  });
+}
+
+export function duplicateDetectionWaiverIdentity(
+  waiver: MaterializedFindingWaiver
+): DuplicateDetectionFindingIdentity {
+  const identity = resolveDuplicateDetectionFindingIdentity(waiver.identity);
+  if (identity === undefined) {
+    throw new TypeError("duplicateDetection waiver identity must retain sorted valid locations");
+  }
+  return identity;
+}
+
+/** 为一项未使用或过宽 waiver 构造 Check-owned audit Record。 */
+export function duplicateDetectionWaiverAuditRecord(audit: FindingWaiverRecordAudit): Readonly<{
+  readonly data: DuplicateDetectionFindingWaiverAuditRecordData;
   readonly id: string;
+}> {
+  const identity = duplicateDetectionWaiverIdentity(audit.waiver);
+  return buildHashedFindingWaiverAuditRecord(identity, audit);
 }
 
 /** Builds Check-owned supplemental facts without adding a Product record catalog. */
@@ -86,11 +138,20 @@ export function isValidDuplicateFragment(fragment: DuplicateCodeFragment): boole
     Array.isArray(fragment.locations) &&
     fragment.locations.length >= 2 &&
     fragment.locations.every(isValidLocation) &&
+    locationsAreDistinct(fragment.locations) &&
     Array.isArray(fragment.codeAreas) &&
     fragment.codeAreas.every(nonEmptyString)
   );
 }
 
+function locationsAreDistinct(locations: readonly DuplicateCodeLocation[]): boolean {
+  return locations.every((location, index) =>
+    locations
+      .slice(index + 1)
+      .every((other) => compareDuplicateFindingLocations(location, other) !== 0)
+  );
+}
+
 function hasValidFragmentMeasurements(fragment: DuplicateCodeFragment): boolean {
   return (
     nonNegativeSafeInteger(fragment.id) &&
@@ -149,15 +210,7 @@ function duplicateFingerprint(fragment: DuplicateCodeFragment): string {
 }
 
 function sortedLocations(locations: readonly DuplicateCodeLocation[]): DuplicateCodeLocation[] {
-  return [...locations].sort((left, right) =>
-    compareText(locationSortKey(left), locationSortKey(right))
-  );
-}
-
-function locationSortKey(location: DuplicateCodeLocation): string {
-  const startLine = String(location.startLine).padStart(12, "0");
-  const endLine = String(location.endLine).padStart(12, "0");
-  return `${location.path}\u0000${startLine}\u0000${endLine}`;
+  return [...locations].sort(compareDuplicateFindingLocations);
 }
 
 function uniqueSorted(values: readonly string[]): string[] {

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

@@ -5,6 +5,12 @@ import {
 } from "../../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 { fileMetricFindingMessages } from "./finding-messages.ts";
 import { measureFileMetrics, type FileMeasurementResult } from "./measurement.ts";
 import type { FileMetricsExactInputSet } from "./measurement-model.ts";
 import type {
@@ -61,17 +67,7 @@ export async function executeFileMetrics(
   });
   if (candidates === undefined) return unavailable("external-result-invalid");
   const reconciliation = reconcileFileMetricWaivers(candidates, context.options.findingWaivers);
-  for (const finding of reconciliation.findings) {
-    const data =
-      finding.disposition === "waived"
-        ? Object.freeze({
-            ...finding.finding.data,
-            blocking: false,
-            waiver: Object.freeze({ reason: finding.waiver.reason })
-          })
-        : finding.finding.data;
-    context.records.report({ id: finding.finding.id }, data);
-  }
+  reportReconciledCodeQualityFindingRecords(context, reconciliation);
   reportWaiverAuditRecords(context, reconciliation);
   const settlement = settleFindings(
     reconciliation.findings.map(({ disposition, finding }) => ({
@@ -79,7 +75,13 @@ export async function executeFileMetrics(
       blocking: finding.data.blocking
     }))
   );
-  return appendWaiverMessages(settlement, reconciliation);
+  const actionableFindings = reconciliation.findings
+    .filter(({ disposition }) => disposition !== "waived")
+    .map(({ finding }) => finding);
+  return appendWaiverMessages(
+    appendCheckMessages(settlement, fileMetricFindingMessages(actionableFindings)),
+    reconciliation
+  );
 }
 
 function noEligibleInputResult(
@@ -108,10 +110,7 @@ function reportWaiverAuditRecords(
   context: CheckExecutionContext<ResolvedFileMetricsOptions>,
   reconciliation: FindingWaiverReconciliation<FileRecordCandidate>
 ): void {
-  for (const audit of reconciliation.waiverAudits) {
-    const record = fileMetricsWaiverAuditRecord(audit);
-    if (record !== undefined) context.records.report({ id: record.id }, record.data);
-  }
+  reportFindingWaiverAudits(context, reconciliation, fileMetricsWaiverAuditRecord);
 }
 
 function appendWaiverMessages(
@@ -218,7 +217,7 @@ function unavailableMessage(code: FileMetricsUnavailableReasonCode): string {
     case "source-unavailable":
       return "File metrics could not collect its configured project files; check the project root, file permissions, and selected file source.";
     case "external-dependency-unavailable":
-      return "The configured SCC command is unavailable or incompatible; install SCC 3.7.0 or configure a compatible executable.";
+      return "The configured SCC command is unavailable or incompatible; install SCC 4.0.0 or configure a compatible executable.";
     case "external-execution-failed":
       return "SCC did not complete successfully; run the configured command directly and inspect its environment.";
     case "external-result-invalid":

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

@@ -0,0 +1,29 @@
+import type { CheckMessage } from "../../check/check.ts";
+import { presentCheckFindings } from "../../check/finding-presentation.ts";
+import type { FileRecordCandidate } from "./records.ts";
+
+const PRESENTED_FINDING_LIMIT = 10;
+
+/** Projects actionable file-metric Records into bounded terminal summaries. */
+export function fileMetricFindingMessages(
+  findings: readonly FileRecordCandidate[]
+): readonly CheckMessage[] {
+  return presentCheckFindings({
+    findings,
+    limit: PRESENTED_FINDING_LIMIT,
+    message: ({ data }) =>
+      Object.freeze({
+        code: "finding-detail",
+        level: data.blocking ? ("error" as const) : ("warning" as const),
+        message: `${data.path}: ${data.codeLines} code lines exceeds the ${data.limit} line limit (areas: ${data.codeAreas.join(", ")}).`
+      }),
+    omittedMessage: ({ omittedCount, omittedFindings }) =>
+      Object.freeze({
+        code: "findings-omitted",
+        level: omittedFindings.some(({ data }) => data.blocking)
+          ? ("error" as const)
+          : ("warning" as const),
+        message: `${omittedCount} additional file metric finding(s) were not shown; inspect this Check's Records for the complete set.`
+      })
+  });
+}

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

@@ -1,14 +1,19 @@
 import {
-  hasRequiredAndOptionalRecordKeys,
   snapshotClosedArray,
-  snapshotClosedRecord
+  snapshotClosedPolicyRecord
 } from "../../data-boundary/closed-values.ts";
+import {
+  isNonEmptyString,
+  isNonNegativeSafeInteger,
+  isPositiveSafeInteger
+} from "../../data-boundary/value-shapes.ts";
 import {
   resolveProjectFileSelection,
   snapshotDefaultProjectFileSelection
 } from "../project-files/configuration.ts";
 import {
   DEFAULT_FINDING_POLICY,
+  resolveCodeAreaPolicyMap,
   resolveFindingPolicy,
   type FindingPolicy
 } from "../code-quality-findings/policy.ts";
@@ -26,16 +31,11 @@ const DEFAULT_MAXIMUM_CODE_LINES = 360;
 const DEFAULT_ALLOWANCE_MAXIMUM_CODE_LINES = 600;
 const DEFAULT_ALLOWANCE_MAXIMUM_DECISION_TOKENS = 12;
 
-interface PolicyRecordKeys {
-  readonly optional?: readonly string[];
-  readonly required?: readonly string[];
-}
-
 /** 校验 constructor input，并将所有可省略 policy 物化为完整、冻结的 Check options。 */
 export function resolveFileMetricsOptions(
   authoredOptions: unknown
 ): ResolvedFileMetricsOptions | undefined {
-  const input = snapshotPolicyRecord(authoredOptions, {
+  const input = snapshotClosedPolicyRecord(authoredOptions, {
     optional: ["codeAreas", "findingPolicy", "findingWaivers", "scanner"]
   });
   if (input === undefined) return undefined;
@@ -70,14 +70,14 @@ function resolveFindingWaivers(value: unknown): readonly FileMetricsFindingWaive
 }
 
 function resolveFindingWaiver(value: unknown): FileMetricsFindingWaiver | undefined {
-  const waiver = snapshotPolicyRecord(value, { required: ["identity", "reason"] });
+  const waiver = snapshotClosedPolicyRecord(value, { required: ["identity", "reason"] });
   if (waiver === undefined || !isNonEmptyString(waiver.reason)) return undefined;
   const identity = resolveFindingIdentity(waiver.identity);
   return identity === undefined ? undefined : Object.freeze({ identity, reason: waiver.reason });
 }
 
 function resolveFindingIdentity(value: unknown): FileMetricsFindingIdentity | undefined {
-  const identity = snapshotPolicyRecord(value, { required: ["metric", "path"] });
+  const identity = snapshotClosedPolicyRecord(value, { required: ["metric", "path"] });
   return identity === undefined ||
     identity.metric !== "code-lines" ||
     !isNormalizedProjectRelativePath(identity.path)
@@ -89,18 +89,11 @@ function resolveCodeAreas(
   value: unknown,
   defaultFindingPolicy: FindingPolicy
 ): ResolvedFileMetricsOptions["codeAreas"] | undefined {
-  if (value === undefined) return Object.freeze({ project: defaultCodeArea(defaultFindingPolicy) });
-  const areas = snapshotClosedRecord(value);
-  if (areas === undefined || Object.keys(areas).length === 0) return undefined;
-
-  const resolvedEntries: Array<readonly [string, ResolvedFileMetricsCodeAreaOptions]> = [];
-  for (const [areaId, candidate] of Object.entries(areas)) {
-    if (!isNonEmptyString(areaId)) return undefined;
-    const area = resolveCodeArea(candidate, defaultFindingPolicy);
-    if (area === undefined) return undefined;
-    resolvedEntries.push([areaId, area]);
-  }
-  return Object.freeze(Object.fromEntries(resolvedEntries));
+  return resolveCodeAreaPolicyMap(
+    value,
+    () => defaultCodeArea(defaultFindingPolicy),
+    (candidate) => resolveCodeArea(candidate, defaultFindingPolicy)
+  );
 }
 
 function defaultCodeArea(findingPolicy: FindingPolicy): ResolvedFileMetricsCodeAreaOptions {
@@ -115,7 +108,7 @@ function resolveCodeArea(
   value: unknown,
   defaultFindingPolicy: FindingPolicy
 ): ResolvedFileMetricsCodeAreaOptions | undefined {
-  const area = snapshotPolicyRecord(value, {
+  const area = snapshotClosedPolicyRecord(value, {
     optional: ["codeLines", "findingPolicy"],
     required: ["files"]
   });
@@ -132,7 +125,7 @@ function resolveCodeLines(
   value: unknown
 ): ResolvedFileMetricsCodeAreaOptions["codeLines"] | undefined {
   if (value === undefined) return defaultCodeLines();
-  const codeLines = snapshotPolicyRecord(value, {
+  const codeLines = snapshotClosedPolicyRecord(value, {
     optional: ["lowDecisionTokenAllowance", "maximum"]
   });
   if (codeLines === undefined) return undefined;
@@ -162,7 +155,7 @@ function resolveAllowance(
   value: unknown
 ): ResolvedFileMetricsCodeAreaOptions["codeLines"]["lowDecisionTokenAllowance"] | undefined {
   if (value === undefined) return defaultCodeLines().lowDecisionTokenAllowance;
-  const allowance = snapshotPolicyRecord(value, {
+  const allowance = snapshotClosedPolicyRecord(value, {
     optional: ["maximumCodeLines", "maximumDecisionTokens"]
   });
   if (allowance === undefined) return undefined;
@@ -180,34 +173,8 @@ function resolveAllowance(
 
 function resolveScanner(value: unknown): ResolvedFileMetricsOptions["scanner"] | undefined {
   if (value === undefined) return Object.freeze({ executable: DEFAULT_EXECUTABLE });
-  const scanner = snapshotPolicyRecord(value, { optional: ["executable"] });
+  const scanner = snapshotClosedPolicyRecord(value, { optional: ["executable"] });
   if (scanner === undefined) return undefined;
   const executable = scanner.executable ?? DEFAULT_EXECUTABLE;
   return isNonEmptyString(executable) ? Object.freeze({ executable }) : undefined;
 }
-
-function snapshotPolicyRecord(
-  value: unknown,
-  keys: PolicyRecordKeys
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  return record !== undefined &&
-    hasRequiredAndOptionalRecordKeys(record, {
-      optional: keys.optional ?? [],
-      required: keys.required ?? []
-    })
-    ? record
-    : undefined;
-}
-
-function isPositiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
-function isNonNegativeSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.length > 0;
-}

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

@@ -1,4 +1,13 @@
-import { snapshotClosedArray, snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import {
+  snapshotClosedArray,
+  snapshotClosedRecord,
+  snapshotExactClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import {
+  isNonEmptyString,
+  isNonNegativeSafeInteger,
+  isPositiveSafeInteger
+} from "../../data-boundary/value-shapes.ts";
 import { validProjectFileSelection } from "../project-files/configuration.ts";
 import { validFindingPolicy } from "../code-quality-findings/policy.ts";
 import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
@@ -8,7 +17,11 @@ import type { ResolvedFileMetricsOptions } from "./options.ts";
 export function isValidResolvedFileMetricsOptions(
   resolvedOptions: unknown
 ): resolvedOptions is ResolvedFileMetricsOptions {
-  const options = exactRecord(resolvedOptions, ["codeAreas", "findingWaivers", "scanner"]);
+  const options = snapshotExactClosedRecord(resolvedOptions, [
+    "codeAreas",
+    "findingWaivers",
+    "scanner"
+  ]);
   return (
     options !== undefined &&
     isValidCodeAreas(options.codeAreas) &&
@@ -22,9 +35,11 @@ function isValidFindingWaivers(value: unknown): boolean {
   if (waivers === undefined) return false;
   const identities = new Set<string>();
   for (const candidate of waivers) {
-    const waiver = exactRecord(candidate, ["identity", "reason"]);
+    const waiver = snapshotExactClosedRecord(candidate, ["identity", "reason"]);
     const identity =
-      waiver === undefined ? undefined : exactRecord(waiver.identity, ["metric", "path"]);
+      waiver === undefined
+        ? undefined
+        : snapshotExactClosedRecord(waiver.identity, ["metric", "path"]);
     if (
       waiver === undefined ||
       identity === undefined ||
@@ -50,7 +65,7 @@ function isValidCodeAreas(value: unknown): boolean {
 }
 
 function isValidCodeArea(value: unknown): boolean {
-  const area = exactRecord(value, ["codeLines", "files", "findingPolicy"]);
+  const area = snapshotExactClosedRecord(value, ["codeLines", "files", "findingPolicy"]);
   return (
     area !== undefined &&
     validProjectFileSelection(area.files) &&
@@ -60,9 +75,9 @@ function isValidCodeArea(value: unknown): boolean {
 }
 
 function isValidCodeLinePolicy(value: unknown): boolean {
-  const policy = exactRecord(value, ["lowDecisionTokenAllowance", "maximum"]);
+  const policy = snapshotExactClosedRecord(value, ["lowDecisionTokenAllowance", "maximum"]);
   if (policy === undefined || !isPositiveSafeInteger(policy.maximum)) return false;
-  const allowance = exactRecord(policy.lowDecisionTokenAllowance, [
+  const allowance = snapshotExactClosedRecord(policy.lowDecisionTokenAllowance, [
     "maximumCodeLines",
     "maximumDecisionTokens"
   ]);
@@ -75,30 +90,6 @@ function isValidCodeLinePolicy(value: unknown): boolean {
 }
 
 function isValidScanner(value: unknown): boolean {
-  const scanner = exactRecord(value, ["executable"]);
+  const scanner = snapshotExactClosedRecord(value, ["executable"]);
   return scanner !== undefined && isNonEmptyString(scanner.executable);
 }
-
-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 isPositiveSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
-}
-
-function isNonNegativeSafeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.length > 0;
-}

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

@@ -2,10 +2,12 @@ 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 {
-  FindingWaiverAudit,
-  MaterializedFindingWaiver
-} from "../../finding-waivers/reconciliation.ts";
+import type { MaterializedFindingWaiver } from "../../finding-waivers/reconciliation.ts";
+import {
+  buildFindingWaiverAuditRecordData,
+  type FindingWaiverAuditRecordData,
+  type FindingWaiverRecordAudit
+} from "../code-quality-findings/finding-waiver-evidence.ts";
 import type {
   CanonicalJsonObject,
   CanonicalJsonValue
@@ -38,13 +40,8 @@ export type FileMetricsFindingRecordData = Readonly<{
 }>;
 
 /** 未使用或过宽 file-metrics waiver 的 supplemental audit Record data。 */
-export type FileMetricsFindingWaiverAuditRecordData = Readonly<{
-  readonly identity: FileMetricsFindingIdentity;
-  readonly kind: "finding-waiver-audit";
-  readonly matchCount: number;
-  readonly reason: string;
-  readonly status: "overmatched" | "unused";
-}>;
+export type FileMetricsFindingWaiverAuditRecordData =
+  FindingWaiverAuditRecordData<FileMetricsFindingIdentity>;
 
 /** file-metrics 发布的 finding 或 waiver-audit supplemental Record data。 */
 export type FileMetricsRecordData =
@@ -58,20 +55,11 @@ export interface FileRecordCandidate {
 
 /** 仅为未使用和过宽 waiver 构造补充 audit Record；正常 applied waiver 由 finding Record 自己保留。 */
 export function fileMetricsWaiverAuditRecord(
-  audit: FindingWaiverAudit
-):
-  | Readonly<{ readonly data: FileMetricsFindingWaiverAuditRecordData; readonly id: string }>
-  | undefined {
-  if (audit.status === "applied") return undefined;
+  audit: FindingWaiverRecordAudit
+): Readonly<{ readonly data: FileMetricsFindingWaiverAuditRecordData; readonly id: string }> {
   const identity = fileMetricsWaiverIdentity(audit.waiver);
   return Object.freeze({
-    data: Object.freeze({
-      identity,
-      kind: "finding-waiver-audit",
-      matchCount: audit.matchCount,
-      reason: audit.waiver.reason,
-      status: audit.status
-    }),
+    data: buildFindingWaiverAuditRecordData(identity, audit),
     id: `${FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX}${identity.path}`
   });
 }

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

@@ -1,5 +1,5 @@
 import { errorMessage } from "../../host-environment/error-message.ts";
-import { processFailure, runProcess } from "../../host-environment/process/command.ts";
+import { processFailure, runProcess } from "../../host-environment/process.ts";
 import type { ResolvedFileMetricsScannerOptions } from "../options.ts";
 import { SCC_VERSION_OUTPUT } from "./parser.ts";