@zxyycom/vibe-check 0.0.1 → 0.0.3

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 "../../package-tools/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/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,9 +2,15 @@ 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 "../../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";
 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(
@@ -197,8 +196,6 @@ function measurementFailureResult(
     case "unavailable":
       return unavailable("external-dependency-unavailable");
   }
-  const exhaustiveMeasurement: never = measurement;
-  return exhaustiveMeasurement;
 }
 
 function unavailable(code: FileMetricsUnavailableReasonCode): CheckResult<FileMetricsFinalData> {
@@ -218,7 +215,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 "../../package-tools/finding-presentation/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/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,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 "../../package-tools/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";
 
@@ -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"}`;
 }