@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -0,0 +1,75 @@
+import type { CheckMessage } from "../../check/check.ts";
+import { presentCheckFindings } from "../../package-tools/finding-presentation/finding-presentation.ts";
+import type {
+  FindingWaiverAudit,
+  FindingWaiverReconciliation
+} from "../../package-tools/finding-waivers/reconciliation.ts";
+import type { DuplicateDetectionFindingLocation } from "./options.ts";
+import { duplicateDetectionWaiverIdentity, type DuplicateRecordCandidate } from "./records.ts";
+
+const PRESENTED_FINDING_LIMIT = 10;
+
+/** Projects duplicate Records into bounded, project-relative terminal summaries. */
+export function duplicateFindingMessages(
+  candidates: readonly DuplicateRecordCandidate[]
+): readonly CheckMessage[] {
+  return presentCheckFindings({
+    findings: candidates,
+    limit: PRESENTED_FINDING_LIMIT,
+    message: ({ data }) =>
+      Object.freeze({
+        code: "finding-detail",
+        level: data.blocking ? ("error" as const) : ("warning" as const),
+        message: `Duplicate fragment contains ${data.tokenCount} tokens across ${data.lineCount} lines at ${duplicateLocationSummary(data.locations)}.`
+      }),
+    omittedMessage: ({ omittedCount, omittedFindings }) =>
+      Object.freeze({
+        code: "findings-omitted",
+        level: omittedFindings.some(({ data }) => data.blocking)
+          ? ("error" as const)
+          : ("warning" as const),
+        message: `${omittedCount} additional duplicate finding(s) were not shown; inspect this Check's Records for the complete set.`
+      })
+  });
+}
+
+/** 将每项 duplicate-detection waiver audit 投影为可行动的 terminal message。 */
+export function duplicateWaiverMessages(
+  reconciliation: FindingWaiverReconciliation<DuplicateRecordCandidate>
+): readonly CheckMessage[] {
+  return Object.freeze(reconciliation.waiverAudits.map(duplicateWaiverMessage));
+}
+
+function duplicateWaiverMessage(audit: FindingWaiverAudit): CheckMessage {
+  const identity = duplicateDetectionWaiverIdentity(audit.waiver);
+  const subject = duplicateLocationSummary(identity.locations);
+  switch (audit.status) {
+    case "applied":
+      return Object.freeze({
+        code: "finding-waived",
+        level: "info",
+        message: `Duplicate finding at ${subject} was waived: ${audit.waiver.reason}`
+      });
+    case "unused":
+      return Object.freeze({
+        code: "unused-finding-waiver",
+        level: "warning",
+        message: `Configured duplicate-detection finding waiver at ${subject} matched no finding; remove it or update its identity. Reason: ${audit.waiver.reason}`
+      });
+    case "overmatched":
+      return Object.freeze({
+        code: "overmatched-finding-waiver",
+        level: "warning",
+        message: `Configured duplicate-detection finding waiver at ${subject} matched ${audit.matchCount} findings and was not applied; narrow its identity. Reason: ${audit.waiver.reason}`
+      });
+  }
+}
+
+function duplicateLocationSummary(locations: readonly DuplicateDetectionFindingLocation[]): string {
+  const presented = locations
+    .slice(0, 2)
+    .map(({ endLine, path, startLine }) => `${path}:${startLine}-${endLine}`)
+    .join(", ");
+  const omitted = locations.length - 2;
+  return omitted > 0 ? `${presented}, and ${omitted} more location(s)` : presented;
+}

package/src/package-checks/duplicate-detection/finding-waiver-identity.ts

@@ -0,0 +1,68 @@
+import {
+  snapshotClosedArray,
+  snapshotClosedPolicyRecord
+} from "../../data-boundary/closed-values.ts";
+import { isPositiveSafeInteger } from "../../data-boundary/value-shapes.ts";
+import { isNormalizedProjectRelativePath } from "../host-environment/path.ts";
+import type {
+  DuplicateDetectionFindingIdentity,
+  DuplicateDetectionFindingLocation
+} from "./options.ts";
+
+export function resolveDuplicateDetectionFindingIdentity(
+  value: unknown
+): DuplicateDetectionFindingIdentity | undefined {
+  const identity = snapshotClosedPolicyRecord(value, { required: ["locations", "metric"] });
+  if (identity === undefined || identity.metric !== "duplicate-tokens") return undefined;
+  const candidates = snapshotClosedArray(identity.locations);
+  if (candidates === undefined || candidates.length < 2) return undefined;
+  const locations: DuplicateDetectionFindingLocation[] = [];
+  for (const candidate of candidates) {
+    const resolved = resolveDuplicateFindingLocation(candidate);
+    if (resolved === undefined) return undefined;
+    const previous = locations.at(-1);
+    if (previous !== undefined && compareDuplicateFindingLocations(previous, resolved) >= 0) {
+      return undefined;
+    }
+    locations.push(resolved);
+  }
+  return Object.freeze({ locations: Object.freeze(locations), metric: "duplicate-tokens" });
+}
+
+function resolveDuplicateFindingLocation(
+  value: unknown
+): DuplicateDetectionFindingLocation | undefined {
+  const location = snapshotClosedPolicyRecord(value, {
+    required: ["endLine", "path", "startLine"]
+  });
+  if (
+    location === undefined ||
+    !isNormalizedProjectRelativePath(location.path) ||
+    !isPositiveSafeInteger(location.startLine) ||
+    !isPositiveSafeInteger(location.endLine) ||
+    location.endLine < location.startLine
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    endLine: location.endLine,
+    path: location.path,
+    startLine: location.startLine
+  });
+}
+
+export function compareDuplicateFindingLocations(
+  left: DuplicateDetectionFindingLocation,
+  right: DuplicateDetectionFindingLocation
+): number {
+  const pathOrder = compareText(left.path, right.path);
+  if (pathOrder !== 0) return pathOrder;
+  const startLineOrder = left.startLine - right.startLine;
+  return startLineOrder === 0 ? left.endLine - right.endLine : startLineOrder;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

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

@@ -1,4 +1,4 @@
-import { runProcess } from "../../host-environment/process/command.ts";
+import { runProcess } from "../../host-environment/process.ts";
 import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
 import { isMissingExplicitCommand } from "./command-path.ts";
 import { isPackageJscpdCommand, resolveJscpdCommand } from "./command-resolution.ts";
@@ -133,5 +133,5 @@ function commandOutput(result: ToolCommandResult): string {
 function processTermination(result: ToolCommandResult): string {
   return typeof result.status === "number"
     ? `exit ${result.status}`
-    : `signal ${result.signal || "unknown"}`;
+    : `signal ${result.signal ?? "unknown"}`;
 }

package/src/package-checks/duplicate-detection/jscpd/command-resolution.ts

@@ -20,7 +20,7 @@ export type ResolvedJscpdCommand =
 
 /**
  * package-provided scanner 的可移植 marker。真实 executable 只由私有 jscpd adapter 解析，避免公共
- * Definition 与 fingerprint 保存 consumer-specific Bun 或 package path。
+ * Definition 与 fingerprint 保存 consumer-specific runtime 或 package path。
  */
 export const DEFAULT_JSCPD_COMMAND: DuplicateDetectionScannerCommand = Object.freeze({
   kind: "package"

package/src/package-checks/duplicate-detection/jscpd/json-report.ts

@@ -60,7 +60,12 @@ function parseJscpdFragment(
 ): DuplicateCodeFragment {
   const lineCount = integerField(duplication, "lines");
   const tokenCount = integerField(duplication, "tokens");
-  const locations = parseJscpdLocations(duplication, cwd, lineCount);
+  const locations = parseJscpdLocations(
+    duplication,
+    cwd,
+    lineCount,
+    optionalStringField(duplication, "format")
+  );
 
   return {
     id,
@@ -74,12 +79,13 @@ function parseJscpdFragment(
 function parseJscpdLocations(
   duplication: Record<string, unknown>,
   cwd: string,
-  lineCount: number
+  lineCount: number,
+  format: string | null
 ): DuplicateCodeLocation[] {
   return [
     parseJscpdLocationObject(duplication.firstFile, "firstFile"),
     parseJscpdLocationObject(duplication.secondFile, "secondFile")
-  ].map((location) => parseJscpdLocation(location, cwd, lineCount));
+  ].map((location) => parseJscpdLocation(location, cwd, lineCount, format));
 }
 
 function parseJscpdLocationObject(value: unknown, name: string): JscpdFileLocation {
@@ -92,7 +98,8 @@ function parseJscpdLocationObject(value: unknown, name: string): JscpdFileLocati
 function parseJscpdLocation(
   location: JscpdFileLocation,
   cwd: string,
-  lineCount: number
+  lineCount: number,
+  format: string | null
 ): DuplicateCodeLocation {
   const filePath = stringField(location, "name");
   const startLine =
@@ -100,12 +107,24 @@ function parseJscpdLocation(
   const endLine = nestedIntegerField(location, "endLoc", "line") ?? integerField(location, "end");
 
   return {
-    path: normalizeScannerReportedPath(filePath, cwd),
+    path: normalizeScannerReportedPath(stripJscpdFormatSuffix(filePath, format), cwd),
     startLine,
     endLine: endLine || startLine + Math.max(0, lineCount - 1)
   };
 }
 
+function stripJscpdFormatSuffix(filePath: string, format: string | null): string {
+  const suffix = format === null ? null : `:${format}`;
+  return suffix !== null && filePath.endsWith(suffix)
+    ? filePath.slice(0, -suffix.length)
+    : filePath;
+}
+
+function optionalStringField(record: Record<string, unknown>, name: string): string | null {
+  const value = record[name];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
 function integerField(record: Record<string, unknown>, name: string): number {
   const value = record[name];
   if (typeof value !== "number" || !Number.isSafeInteger(value)) {

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

@@ -8,14 +8,10 @@
 
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 import { errorMessage } from "../../host-environment/error-message.ts";
-import {
-  runProcess,
-  runProcessSync,
-  type ProcessResult
-} from "../../host-environment/process/command.ts";
+import { runProcess, runProcessSync, type ProcessResult } from "../../host-environment/process.ts";
 import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
 import { resolveJscpdCommand, type JscpdCommand } from "./command-resolution.ts";
 import { parseJscpdJsonReport } from "./json-report.ts";
@@ -131,6 +127,7 @@ function prepareJscpdScan(options: ScanWithJscpdOptions): PreparedJscpdScan {
     cwd,
     dependency: resolved.command,
     invocation: prepareJscpdInvocation({
+      cwd,
       scanPrefixArguments: resolved.command.scanPrefixArguments,
       files,
       minimumLines,
@@ -140,11 +137,13 @@ function prepareJscpdScan(options: ScanWithJscpdOptions): PreparedJscpdScan {
 }
 
 function prepareJscpdInvocation({
+  cwd,
   scanPrefixArguments,
   files,
   minimumLines,
   minimumTokens
 }: {
+  readonly cwd: string;
   readonly scanPrefixArguments: readonly string[];
   readonly files: readonly string[];
   readonly minimumLines: number;
@@ -154,7 +153,7 @@ function prepareJscpdInvocation({
   const outputDir = join(tempDir, "report");
   const configPath = join(tempDir, ".jscpd.json");
   const config = {
-    path: files,
+    path: files.map((path) => resolve(cwd, path)),
     reporters: ["json"],
     minTokens: minimumTokens,
     minLines: minimumLines,

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

@@ -1,17 +1,21 @@
 import {
-  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedPolicyRecord,
   snapshotClosedRecord
 } from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString, 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";
+import { resolveFindingWaiverAuthoring } from "../code-quality-findings/finding-waiver-authoring.ts";
 import { DEFAULT_JSCPD_COMMAND } from "./jscpd/command-resolution.ts";
+import { resolveDuplicateDetectionFindingIdentity } from "./finding-waiver-identity.ts";
 import type {
   DuplicateDetectionScannerCommand,
   ResolvedDuplicateDetectionCodeAreaOptions,
@@ -24,17 +28,12 @@ const DEFAULT_CACHE_DIRECTORY = ".cache/vibe-check";
 const DEFAULT_MINIMUM_LINES = 4;
 const DEFAULT_MINIMUM_TOKENS = 100;
 
-interface PolicyRecordKeys {
-  readonly optional?: readonly string[];
-  readonly required?: readonly string[];
-}
-
 /** 校验 constructor input，并将所有可省略 policy 物化为完整、冻结的 Check options。 */
 export function resolveDuplicateDetectionOptions(
   value: unknown
 ): ResolvedDuplicateDetectionOptions | undefined {
-  const input = snapshotPolicyRecord(value, {
-    optional: ["cache", "codeAreas", "findingPolicy", "scanner"]
+  const input = snapshotClosedPolicyRecord(value, {
+    optional: ["cache", "codeAreas", "findingPolicy", "findingWaivers", "scanner"]
   });
   if (input === undefined) return undefined;
 
@@ -42,10 +41,20 @@ export function resolveDuplicateDetectionOptions(
   const findingPolicy = resolveFindingPolicy(input.findingPolicy, DEFAULT_FINDING_POLICY);
   if (findingPolicy === undefined) return undefined;
   const codeAreas = resolveCodeAreas(input.codeAreas, findingPolicy);
+  const findingWaivers = resolveFindingWaiverAuthoring(
+    input.findingWaivers,
+    resolveDuplicateDetectionFindingIdentity
+  );
   const scanner = resolveScanner(input.scanner);
-  if (cache === undefined || codeAreas === undefined || scanner === undefined) return undefined;
+  if (
+    cache === undefined ||
+    codeAreas === undefined ||
+    findingWaivers === undefined ||
+    scanner === undefined
+  )
+    return undefined;
 
-  const options = Object.freeze({ cache, codeAreas, scanner });
+  const options = Object.freeze({ cache, codeAreas, findingWaivers, scanner });
   return validResolvedDuplicateDetectionOptions(options) ? options : undefined;
 }
 
@@ -53,11 +62,11 @@ function resolveCache(value: unknown): ResolvedDuplicateDetectionOptions["cache"
   if (value === undefined) {
     return Object.freeze({ directory: DEFAULT_CACHE_DIRECTORY, enabled: true });
   }
-  const cache = snapshotPolicyRecord(value, { optional: ["directory", "enabled"] });
+  const cache = snapshotClosedPolicyRecord(value, { optional: ["directory", "enabled"] });
   if (cache === undefined) return undefined;
   const directory = cache.directory ?? DEFAULT_CACHE_DIRECTORY;
   const enabled = cache.enabled ?? true;
-  if (!nonEmptyString(directory) || typeof enabled !== "boolean") return undefined;
+  if (!isNonEmptyString(directory) || typeof enabled !== "boolean") return undefined;
   return Object.freeze({ directory, enabled });
 }
 
@@ -65,20 +74,11 @@ function resolveCodeAreas(
   value: unknown,
   defaultFindingPolicy: FindingPolicy
 ): ResolvedDuplicateDetectionOptions["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, ResolvedDuplicateDetectionCodeAreaOptions]> = [];
-  for (const [areaId, candidate] of Object.entries(areas)) {
-    if (!nonEmptyString(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): ResolvedDuplicateDetectionCodeAreaOptions {
@@ -94,7 +94,7 @@ function resolveCodeArea(
   value: unknown,
   defaultFindingPolicy: FindingPolicy
 ): ResolvedDuplicateDetectionCodeAreaOptions | undefined {
-  const area = snapshotPolicyRecord(value, {
+  const area = snapshotClosedPolicyRecord(value, {
     optional: ["findingPolicy", "minimumLines", "minimumTokens"],
     required: ["files"]
   });
@@ -106,8 +106,8 @@ function resolveCodeArea(
   if (
     files === undefined ||
     findingPolicy === undefined ||
-    !positiveSafeInteger(minimumLines) ||
-    !positiveSafeInteger(minimumTokens)
+    !isPositiveSafeInteger(minimumLines) ||
+    !isPositiveSafeInteger(minimumTokens)
   ) {
     return undefined;
   }
@@ -116,7 +116,7 @@ function resolveCodeArea(
 
 function resolveScanner(value: unknown): ResolvedDuplicateDetectionScannerOptions | undefined {
   if (value === undefined) return Object.freeze({ command: DEFAULT_JSCPD_COMMAND });
-  const scanner = snapshotPolicyRecord(value, { optional: ["command"] });
+  const scanner = snapshotClosedPolicyRecord(value, { optional: ["command"] });
   if (scanner === undefined) return undefined;
   const command = resolveScannerCommand(scanner.command);
   return command === undefined ? undefined : Object.freeze({ command });
@@ -129,34 +129,9 @@ function resolveScannerCommand(value: unknown): DuplicateDetectionScannerCommand
     return Object.keys(command).length === 1 ? DEFAULT_JSCPD_COMMAND : undefined;
   }
   if (command?.kind !== "custom") return undefined;
-  const custom = snapshotPolicyRecord(command, { required: ["executable", "kind"] });
-  if (custom === undefined || custom.kind !== "custom" || !nonEmptyString(custom.executable)) {
+  const custom = snapshotClosedPolicyRecord(command, { required: ["executable", "kind"] });
+  if (custom === undefined || custom.kind !== "custom" || !isNonEmptyString(custom.executable)) {
     return undefined;
   }
   return Object.freeze({ executable: custom.executable, kind: "custom" });
 }
-
-function snapshotPolicyRecord(
-  value: unknown,
-  keys: PolicyRecordKeys
-): Readonly<Record<string, unknown>> | undefined {
-  const record = snapshotClosedRecord(value);
-  if (
-    record === undefined ||
-    !hasRequiredAndOptionalRecordKeys(record, {
-      optional: keys.optional ?? [],
-      required: keys.required ?? []
-    })
-  ) {
-    return undefined;
-  }
-  return record;
-}
-
-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;
-}

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

@@ -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";
 
 export type DuplicateDetectionScannerCommand =
   /** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
@@ -28,10 +30,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;
@@ -44,19 +62,24 @@ export interface DuplicateDetectionCodeAreaOptions {
 }
 
 /** `duplicateDetection(options?)` 接受并补齐默认值的公开策略。 */
-export interface DuplicateDetectionOptions {
+export interface DuplicateDetectionOptions<
+  Id extends string = string
+> extends PackageCheckAuthoringOptions<Id> {
   /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
   readonly codeAreas?: Readonly<Record<string, DuplicateDetectionCodeAreaOptions>>;
   readonly cache?: DuplicateDetectionCacheOptions;
   /** 省略时为 `non-blocking`；区域可局部覆盖。 */
   readonly findingPolicy?: FindingPolicy;
+  /** 省略时没有豁免；identity 使用 Finding 发布的完整排序 location ranges。 */
+  readonly findingWaivers?: readonly DuplicateDetectionFindingWaiver[];
   readonly scanner?: DuplicateDetectionScannerOptions;
 }
 
-/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+/** 构造函数生成并由 Check preparation/execution 消费的完整 options。 */
 export interface ResolvedDuplicateDetectionOptions {
   readonly cache: Readonly<{ readonly directory: string; readonly enabled: boolean }>;
   readonly codeAreas: Readonly<Record<string, ResolvedDuplicateDetectionCodeAreaOptions>>;
+  readonly findingWaivers: readonly DuplicateDetectionFindingWaiver[];
   readonly scanner: ResolvedDuplicateDetectionScannerOptions;
 }