@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/learned-critical-path/strategy.ts

@@ -0,0 +1,299 @@
+import { isAbsolute } from "node:path";
+
+import { canonicalizeJsonValue, type CanonicalJsonValue } from "../data-boundary/canonical-data.ts";
+import type {
+  AdmissionPolicyContext,
+  AdmissionProposal,
+  CustomAdmissionStrategy,
+  SchedulerGraphSnapshot,
+  SchedulerMeasurementContext
+} from "../project-definition/project-definition.ts";
+import { prepareSchedulerDurationModel } from "./duration-model/preparation.ts";
+import { learnedSelectionLayers } from "./selection-layers.ts";
+import { staticDecision } from "./static-decision.ts";
+import {
+  predictionForTask,
+  type SchedulerPredictionInput,
+  type SchedulerPredictionSnapshot
+} from "./duration-model/prediction.ts";
+import {
+  createSchedulerCriticalPathSnapshot,
+  criticalPathScoreForTask,
+  type SchedulerCriticalPathSnapshot
+} from "../project-run/task-scheduler/critical-path-ranking.ts";
+
+/** 公开 learned critical-path prepared strategy 的调用方配置。 */
+export interface LearnedCriticalPathStrategyOptions {
+  /** 调用方拥有的可丢弃 learned duration history 本地目录；必须是绝对路径。 */
+  readonly stateDirectory: string;
+  /** 为每个公开 Task 提供 canonical-JSON-compatible 的调用方 identity projection。 */
+  readonly identityForTask: (task: SchedulerGraphSnapshot["tasks"][number]) => unknown;
+  /** 单个 identity 最多保留的样本数；默认 32。 */
+  readonly sampleWindow?: number;
+  /** 最多保留的 identity 数；默认 4096。 */
+  readonly maxHistorySeries?: number;
+  /** 正的 cold-start duration 权重（毫秒）；默认 1。 */
+  readonly coldStartDurationMs?: number;
+  /** 可选调用方 observation sink；observer fault 不改变 scheduling 或 Run facts。 */
+  readonly observe?: (event: LearnedCriticalPathObservation) => void | Promise<void>;
+}
+
+/** 调用方可选 observer 收到的有界 learned strategy 事件；selection-proposed 不表示 Scheduler 已接受 admission。 */
+export type LearnedCriticalPathObservation =
+  | Readonly<{
+      readonly kind: "history-unavailable";
+      readonly reason: "identity-invalid" | "setup-failed";
+    }>
+  | Readonly<{
+      readonly kind: "selection-proposed";
+      readonly taskId: string;
+      readonly estimatedDurationMs: number;
+      readonly criticalPathScore: number;
+      readonly sampleCount: number;
+      readonly source: "learned" | "project-prior" | "cold-start";
+    }>
+  | Readonly<{ readonly kind: "recording-unavailable" }>;
+
+/**
+ * 构造普通公开 prepared strategy。调用方拥有 history location 与 identity projection；
+ * Product 只按同一 custom strategy lifecycle 调用它，不为该 helper 增加特权。
+ */
+export function createLearnedCriticalPathStrategy(
+  options: LearnedCriticalPathStrategyOptions
+): CustomAdmissionStrategy {
+  if (typeof options.stateDirectory !== "string" || !isAbsolute(options.stateDirectory)) {
+    throw new TypeError("learned critical-path stateDirectory must be an absolute path");
+  }
+  const model = modelOptions(options);
+  return Object.freeze({
+    kind: "prepared" as const,
+    prepare: async ({ graph }) => {
+      const predictionInputs = predictionInputsFor(graph, options.identityForTask, model);
+      if (predictionInputs === undefined) {
+        observe(options, { kind: "history-unavailable", reason: "identity-invalid" });
+        return Object.freeze({ decide: staticDecision });
+      }
+      const durationModel = await prepareSchedulerDurationModel({
+        predictionInputs,
+        stateDirectory: options.stateDirectory,
+        coldStartDurationMs: model.coldStartDurationMs,
+        maxSamplesPerSeries: model.sampleWindow,
+        maxSeries: model.maxHistorySeries
+      });
+      if (durationModel.kind === "static-fallback") {
+        observe(options, { kind: "history-unavailable", reason: "setup-failed" });
+        return Object.freeze({ decide: staticDecision });
+      }
+      let criticalPath: SchedulerCriticalPathSnapshot;
+      try {
+        criticalPath = createSchedulerCriticalPathSnapshot(graph, durationModel.prediction);
+      } catch {
+        observe(options, { kind: "history-unavailable", reason: "setup-failed" });
+        return Object.freeze({ decide: staticDecision });
+      }
+      return Object.freeze({
+        decide: (context: AdmissionPolicyContext) =>
+          learnedDecision(context, durationModel.prediction, criticalPath, options),
+        complete: async (context: SchedulerMeasurementContext) => {
+          const recorded = await durationModel.record(context);
+          if (recorded.kind === "failed" || recorded.writeObservation === "failed") {
+            observe(options, { kind: "recording-unavailable" });
+          }
+        }
+      });
+    }
+  });
+}
+
+function modelOptions(options: LearnedCriticalPathStrategyOptions): Readonly<{
+  readonly coldStartDurationMs: number;
+  readonly maxHistorySeries: number;
+  readonly sampleWindow: number;
+}> {
+  const coldStartDurationMs = options.coldStartDurationMs ?? 1;
+  const maxHistorySeries = options.maxHistorySeries ?? 4_096;
+  const sampleWindow = options.sampleWindow ?? 32;
+  validatePositiveFinite(coldStartDurationMs, "coldStartDurationMs");
+  validateBoundedInteger(maxHistorySeries, "maxHistorySeries", 4_096);
+  validateBoundedInteger(sampleWindow, "sampleWindow", 32);
+  return Object.freeze({ coldStartDurationMs, maxHistorySeries, sampleWindow });
+}
+
+function validatePositiveFinite(value: number, name: string): void {
+  if (!Number.isFinite(value) || value <= 0)
+    throw new TypeError(`learned critical-path ${name} must be positive and finite`);
+}
+
+function validateBoundedInteger(value: number, name: string, maximum: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum)
+    throw new TypeError(`learned critical-path ${name} must be a positive safe integer`);
+}
+
+function predictionInputsFor(
+  graph: SchedulerGraphSnapshot,
+  identityForTask: LearnedCriticalPathStrategyOptions["identityForTask"],
+  model: Readonly<{
+    readonly coldStartDurationMs: number;
+    readonly maxHistorySeries: number;
+    readonly sampleWindow: number;
+  }>
+): readonly SchedulerPredictionInput[] | undefined {
+  const inputs: SchedulerPredictionInput[] = [];
+  for (const task of graph.tasks) {
+    let identity: CanonicalJsonValue | undefined;
+    try {
+      identity = canonicalizeJsonValue({ historyKey: identityForTask(task), model });
+    } catch {
+      return undefined;
+    }
+    if (identity === undefined) return undefined;
+    inputs.push(
+      Object.freeze({
+        authoredOptions: identity,
+        checkId: task.taskId,
+        flags: null,
+        taskId: task.taskId
+      })
+    );
+  }
+  return Object.freeze(inputs);
+}
+
+function learnedDecision(
+  context: AdmissionPolicyContext,
+  prediction: SchedulerPredictionSnapshot,
+  criticalPath: SchedulerCriticalPathSnapshot,
+  options: LearnedCriticalPathStrategyOptions
+): AdmissionProposal {
+  const selected = selectLearnedCandidate(context, criticalPath);
+  if (!selected.canAdmit) return Object.freeze({ kind: "wait" });
+  const taskPrediction = predictionForTask(prediction, selected.taskId);
+  const score = criticalPathScoreForTask(criticalPath, selected.taskId);
+  if (taskPrediction !== undefined && score !== undefined) {
+    observe(
+      options,
+      Object.freeze({
+        kind: "selection-proposed",
+        taskId: selected.taskId,
+        criticalPathScore: score,
+        estimatedDurationMs: taskPrediction.estimatedDurationMs,
+        sampleCount: taskPrediction.sampleCount,
+        source: taskPrediction.source
+      })
+    );
+  }
+  return Object.freeze({ kind: "select", taskId: selected.taskId });
+}
+
+function selectLearnedCandidate(
+  context: AdmissionPolicyContext,
+  criticalPath: SchedulerCriticalPathSnapshot
+): AdmissionPolicyContext["candidates"][number] {
+  const layers = learnedSelectionLayers(context);
+  if (layers.tightening.length > 0)
+    return requiredFirst(
+      sortConstrained(layers.tightening, layers.taskById, layers.scopeById, criticalPath)
+    );
+  if (layers.continuation.length > 0)
+    return requiredFirst(
+      sortConstrained(layers.continuation, layers.taskById, layers.scopeById, criticalPath)
+    );
+  return requiredFirst(
+    [...context.candidates].sort(learnedCandidateComparator(layers.taskById, criticalPath))
+  );
+}
+
+function learnedCandidateComparator(
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot
+): (
+  left: AdmissionPolicyContext["candidates"][number],
+  right: AdmissionPolicyContext["candidates"][number]
+) => number {
+  return (left, right) => compareLearnedTasks(taskById, criticalPath, left.taskId, right.taskId);
+}
+
+function sortConstrained(
+  candidates: readonly AdmissionPolicyContext["candidates"][number][],
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  scopeById: ReadonlyMap<string, SchedulerGraphSnapshot["scopes"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot
+): AdmissionPolicyContext["candidates"][number][] {
+  return [...candidates].sort(learnedConstrainedComparator(taskById, scopeById, criticalPath));
+}
+
+function learnedConstrainedComparator(
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  scopeById: ReadonlyMap<string, SchedulerGraphSnapshot["scopes"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot
+): (
+  left: AdmissionPolicyContext["candidates"][number],
+  right: AdmissionPolicyContext["candidates"][number]
+) => number {
+  return (left, right) => {
+    const leftScope = requiredLearnedScope(left, taskById, scopeById);
+    const rightScope = requiredLearnedScope(right, taskById, scopeById);
+    return (
+      leftScope.maxParallel - rightScope.maxParallel ||
+      compareLearnedTasks(taskById, criticalPath, left.taskId, right.taskId) ||
+      compareText(leftScope.id, rightScope.id) ||
+      compareText(left.taskId, right.taskId)
+    );
+  };
+}
+
+function requiredLearnedScope(
+  candidate: AdmissionPolicyContext["candidates"][number],
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  scopeById: ReadonlyMap<string, SchedulerGraphSnapshot["scopes"][number]>
+): SchedulerGraphSnapshot["scopes"][number] {
+  const task = taskById.get(candidate.taskId);
+  const scope =
+    task?.scopeId === null || task === undefined ? undefined : scopeById.get(task.scopeId);
+  if (scope === undefined) throw new Error("constrained task is missing a scope");
+  return scope;
+}
+function compareLearnedTasks(
+  taskById: ReadonlyMap<string, SchedulerGraphSnapshot["tasks"][number]>,
+  criticalPath: SchedulerCriticalPathSnapshot,
+  leftId: string,
+  rightId: string
+): number {
+  const left = taskById.get(leftId);
+  const right = taskById.get(rightId);
+  if (left === undefined || right === undefined)
+    throw new Error("learned candidate is missing from graph");
+  const leftScore = criticalPathScoreForTask(criticalPath, leftId);
+  const rightScore = criticalPathScoreForTask(criticalPath, rightId);
+  if (leftScore === undefined || rightScore === undefined)
+    throw new Error("learned scheduler score is missing");
+  return (
+    rightScore - leftScore ||
+    right.admissionPriority - left.admissionPriority ||
+    compareText(leftId, rightId)
+  );
+}
+
+function observe(
+  options: LearnedCriticalPathStrategyOptions,
+  event: LearnedCriticalPathObservation
+): void {
+  try {
+    const observed = options.observe?.(event);
+    if (observed !== undefined) void Promise.resolve(observed).catch(() => undefined);
+  } catch {
+    // Caller observation is contained.
+  }
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function requiredFirst<T>(values: readonly T[]): T {
+  const first = values[0];
+  if (first === undefined) throw new Error("learned strategy requires a candidate");
+  return first;
+}

package/src/machine-output/v4/atomic-publication.ts

@@ -3,12 +3,6 @@ import fs from "node:fs";
 import { join } from "node:path";
 
 const CANONICAL_NAMES = ["records.ndjson", "run.json"] as const;
-const RETIRED_NAMES = [
-  "metrics.json",
-  "report.md",
-  "warnings-all.ndjson",
-  "warnings.ndjson"
-] as const;
 const OWNED_TEMP_PREFIX = ".vibe-check-publication-";
 
 interface PublicationCandidatePath {
@@ -39,7 +33,6 @@ export function publishPublicationCandidatesV4(
       fs.renameSync(file.temp, file.canonical);
       hasReplacedCanonicalPath = true;
     }
-    cleanupRetiredArtifacts(artifactDir);
   } catch (error: unknown) {
     if (hasReplacedCanonicalPath) cleanupPublicationV4BestEffort(artifactDir);
     else cleanupOwnedTempsBestEffort(artifactDir);
@@ -48,11 +41,7 @@ export function publishPublicationCandidatesV4(
 }
 
 export function cleanupPublicationV4(artifactDir: string): void {
-  removePaths([
-    ...artifactPaths(artifactDir, CANONICAL_NAMES),
-    ...artifactPaths(artifactDir, RETIRED_NAMES),
-    ...ownedTempPaths(artifactDir)
-  ]);
+  removePaths([...artifactPaths(artifactDir, CANONICAL_NAMES), ...ownedTempPaths(artifactDir)]);
 }
 
 export function cleanupPublicationV4BestEffort(artifactDir: string): void {
@@ -94,10 +83,6 @@ function cleanupOwnedTempsBestEffort(artifactDir: string): void {
   }
 }
 
-function cleanupRetiredArtifacts(artifactDir: string): void {
-  removePaths(artifactPaths(artifactDir, RETIRED_NAMES));
-}
-
 function artifactPaths(artifactDir: string, names: readonly string[]): readonly string[] {
   return names.map((name) => join(artifactDir, name));
 }

package/src/package-checks/code-quality-findings/finding-waiver-authoring.ts

@@ -0,0 +1,46 @@
+import { canonicalJsonText } from "../../data-boundary/canonical-data.ts";
+import {
+  snapshotClosedArray,
+  snapshotClosedPolicyRecord
+} from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString } from "../../data-boundary/value-shapes.ts";
+import type { FindingWaiver } from "../../finding-waivers/reconciliation.ts";
+
+/**
+ * Snapshots the shared closed waiver envelope while leaving identity grammar to the producing Check.
+ */
+export function resolveFindingWaiverAuthoring<Identity>(
+  value: unknown,
+  resolveIdentity: (value: unknown) => Identity | undefined
+): readonly FindingWaiver<Identity>[] | undefined {
+  if (value === undefined) return Object.freeze([]);
+  const candidates = snapshotClosedArray(value);
+  if (candidates === undefined) return undefined;
+
+  const waivers: FindingWaiver<Identity>[] = [];
+  const seenIdentities = new Set<string>();
+  for (const candidate of candidates) {
+    const authored = snapshotClosedPolicyRecord(candidate, { required: ["identity", "reason"] });
+    if (authored === undefined || !isNonEmptyString(authored.reason)) return undefined;
+    const identity = resolveIdentity(authored.identity);
+    if (identity === undefined) return undefined;
+    let identityKey: string;
+    try {
+      identityKey = canonicalJsonText(identity);
+    } catch {
+      return undefined;
+    }
+    if (seenIdentities.has(identityKey)) return undefined;
+    seenIdentities.add(identityKey);
+    waivers.push(Object.freeze({ identity, reason: authored.reason }));
+  }
+  return Object.freeze(waivers);
+}
+
+/** Validates the complete resolved waiver list through the same authoring boundary. */
+export function validResolvedFindingWaivers<Identity>(
+  value: unknown,
+  resolveIdentity: (value: unknown) => Identity | undefined
+): value is readonly FindingWaiver<Identity>[] {
+  return value !== undefined && resolveFindingWaiverAuthoring(value, resolveIdentity) !== undefined;
+}

package/src/package-checks/code-quality-findings/finding-waiver-evidence.ts

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+
+import type { CheckExecutionContext } from "../../check/check.ts";
+import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
+import type {
+  FindingWaiverAudit,
+  FindingWaiverReconciliation
+} from "../../finding-waivers/reconciliation.ts";
+
+interface CodeQualityFindingCandidate {
+  readonly data: Readonly<{ readonly blocking: boolean }>;
+  readonly id: string;
+}
+
+type FindingRecordContext = Pick<CheckExecutionContext<object>, "records">;
+
+const FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX = "/finding-waiver-audit/";
+
+export type FindingWaiverRecordAudit = Readonly<
+  Omit<FindingWaiverAudit, "status"> & {
+    readonly status: "overmatched" | "unused";
+  }
+>;
+
+export type FindingWaiverAuditRecordData<Identity> = Readonly<{
+  readonly identity: Identity;
+  readonly kind: "finding-waiver-audit";
+  readonly matchCount: number;
+  readonly reason: string;
+  readonly status: "overmatched" | "unused";
+}>;
+
+/** Builds the common immutable data shared by Check-owned waiver audit Records. */
+export function buildFindingWaiverAuditRecordData<Identity>(
+  identity: Identity,
+  audit: FindingWaiverRecordAudit
+): FindingWaiverAuditRecordData<Identity> {
+  return Object.freeze({
+    identity,
+    kind: "finding-waiver-audit",
+    matchCount: audit.matchCount,
+    reason: audit.waiver.reason,
+    status: audit.status
+  });
+}
+
+/** Builds the shared hash-addressed audit Record used by structured identities. */
+export function buildHashedFindingWaiverAuditRecord<Identity>(
+  identity: Identity,
+  audit: FindingWaiverRecordAudit
+): Readonly<{ readonly data: FindingWaiverAuditRecordData<Identity>; readonly id: string }> {
+  const digest = createHash("sha256").update(canonicalJsonBytes(identity)).digest("hex");
+  return Object.freeze({
+    data: buildFindingWaiverAuditRecordData(identity, audit),
+    id: `${FINDING_WAIVER_AUDIT_RECORD_ID_PREFIX}sha256:${digest}`
+  });
+}
+
+/** Publishes every reconciled metric Finding while preserving applied waiver evidence. */
+export function reportReconciledCodeQualityFindingRecords<
+  Finding extends CodeQualityFindingCandidate
+>(context: FindingRecordContext, reconciliation: FindingWaiverReconciliation<Finding>): void {
+  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);
+  }
+}
+
+/** Publishes only unused/overmatched audit rows built by the identity-owning Check. */
+export function reportFindingWaiverAudits<Finding, AuditData extends object>(
+  context: FindingRecordContext,
+  reconciliation: FindingWaiverReconciliation<Finding>,
+  buildRecord: (
+    audit: FindingWaiverRecordAudit
+  ) => Readonly<{ readonly data: AuditData; readonly id: string }>
+): void {
+  for (const audit of reconciliation.waiverAudits) {
+    if (audit.status === "applied") continue;
+    const record = buildRecord(
+      Object.freeze({
+        matchCount: audit.matchCount,
+        status: audit.status,
+        waiver: audit.waiver
+      })
+    );
+    context.records.report({ id: record.id }, record.data);
+  }
+}

package/src/package-checks/code-quality-findings/policy.ts

@@ -1,4 +1,6 @@
 import type { CheckMessage, CheckResult } from "../../check/check.ts";
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+import { isNonEmptyString } from "../../data-boundary/value-shapes.ts";
 
 export const FINDING_POLICIES = Object.freeze(["blocking", "non-blocking"] as const);
 
@@ -9,7 +11,9 @@ export const DEFAULT_FINDING_POLICY: FindingPolicy = "non-blocking";
 
 /** 三个代码质量 Check 正常完成时返回的精确 finding 计数。 */
 export interface FindingSummary {
+  /** 仍可处置且采用 blocking policy 的 finding 数；waived finding 不计入。 */
   readonly blockingFindingCount: number;
+  /** Check 发现的全部 finding 数，包括已 waived 或 non-blocking 的 finding。 */
   readonly findingCount: number;
 }
 
@@ -32,6 +36,25 @@ export function validFindingPolicy(value: unknown): value is FindingPolicy {
   return FINDING_POLICIES.some((policy) => policy === value);
 }
 
+/** Resolves the closed, non-empty named area map shared by code-quality Checks. */
+export function resolveCodeAreaPolicyMap<Area>(
+  value: unknown,
+  defaultArea: () => Area,
+  resolveArea: (candidate: unknown) => Area | undefined
+): Readonly<Record<string, Area>> | undefined {
+  if (value === undefined) return Object.freeze({ project: defaultArea() });
+  const areas = snapshotClosedRecord(value);
+  if (areas === undefined || Object.keys(areas).length === 0) return undefined;
+  const resolvedEntries: Array<readonly [string, Area]> = [];
+  for (const [areaId, candidate] of Object.entries(areas)) {
+    if (!isNonEmptyString(areaId)) return undefined;
+    const area = resolveArea(candidate);
+    if (area === undefined) return undefined;
+    resolvedEntries.push([areaId, area]);
+  }
+  return Object.freeze(Object.fromEntries(resolvedEntries));
+}
+
 export function isBlockingFinding(policies: readonly FindingPolicy[]): boolean {
   return policies.some((policy) => policy === "blocking");
 }

package/src/package-checks/duplicate-detection/area-policy.ts

@@ -11,13 +11,16 @@ type PathPolicy = Readonly<{
   minimumTokens: number;
 }>;
 
-type AnnotatedFragment = Readonly<{
-  fragment: DuplicateCodeFragment;
-  requiredMinimumLines: number;
-  requiredMinimumTokens: number;
-}>;
+type FragmentAnnotation =
+  | Readonly<{
+      fragment: DuplicateCodeFragment;
+      kind: "comparable";
+      requiredMinimumLines: number;
+      requiredMinimumTokens: number;
+    }>
+  | Readonly<{ kind: "outside-common-area" }>;
 
-/** Restores every matching code area and applies the strictest involved policy. */
+/** Retains fragments whose locations share an area and applies its strictest policy. */
 export function applyDuplicateAreaPolicy(
   fragments: readonly DuplicateCodeFragment[],
   areas: readonly DuplicateDetectionAreaInput[]
@@ -28,6 +31,7 @@ export function applyDuplicateAreaPolicy(
     if (!isValidDuplicateFragment(fragment)) return undefined;
     const annotated = annotateFragment(fragment, policiesByPath);
     if (annotated === undefined) return undefined;
+    if (annotated.kind === "outside-common-area") continue;
     if (
       annotated.fragment.lineCount >= annotated.requiredMinimumLines &&
       annotated.fragment.tokenCount >= annotated.requiredMinimumTokens
@@ -63,9 +67,9 @@ function buildPathPolicies(
 function annotateFragment(
   fragment: DuplicateCodeFragment,
   policiesByPath: ReadonlyMap<string, readonly PathPolicy[]>
-): AnnotatedFragment | undefined {
+): FragmentAnnotation | undefined {
   const locations: DuplicateCodeLocation[] = [];
-  const involvedPolicies: PathPolicy[] = [];
+  let commonPolicies: readonly PathPolicy[] | undefined;
   for (const location of fragment.locations) {
     const pathPolicies = policiesByPath.get(location.path);
     if (pathPolicies === undefined || pathPolicies.length === 0) return undefined;
@@ -76,19 +80,26 @@ function annotateFragment(
         startLine: location.startLine
       })
     );
-    involvedPolicies.push(...pathPolicies);
+    commonPolicies =
+      commonPolicies === undefined
+        ? pathPolicies
+        : commonPolicies.filter((policy) =>
+            pathPolicies.some((candidate) => candidate.codeArea === policy.codeArea)
+          );
   }
-  if (involvedPolicies.length === 0) return undefined;
+  if (commonPolicies === undefined) return undefined;
+  if (commonPolicies.length === 0) return Object.freeze({ kind: "outside-common-area" });
 
   const annotatedFragment = Object.freeze({
     ...fragment,
-    codeAreas: Object.freeze(uniqueSorted(involvedPolicies.map((policy) => policy.codeArea))),
+    codeAreas: Object.freeze(uniqueSorted(commonPolicies.map((policy) => policy.codeArea))),
     locations: Object.freeze(locations)
   });
   return Object.freeze({
     fragment: annotatedFragment,
-    requiredMinimumLines: Math.max(...involvedPolicies.map((policy) => policy.minimumLines)),
-    requiredMinimumTokens: Math.max(...involvedPolicies.map((policy) => policy.minimumTokens))
+    kind: "comparable",
+    requiredMinimumLines: Math.max(...commonPolicies.map((policy) => policy.minimumLines)),
+    requiredMinimumTokens: Math.max(...commonPolicies.map((policy) => policy.minimumTokens))
   });
 }
 

package/src/package-checks/duplicate-detection/cache/identity.ts

@@ -6,7 +6,7 @@ import type {
   DuplicateScannerCacheConfiguration
 } from "./cache-contract.ts";
 
-const RAW_SCAN_CONFIGURATION_VERSION = "3";
+const RAW_SCAN_CONFIGURATION_VERSION = "4";
 
 interface DuplicateScanCacheIdentityInput {
   readonly dependency: ResolvedDuplicateDetectionScannerOptions;

package/src/package-checks/duplicate-detection/default-check.ts

@@ -22,7 +22,7 @@ export function duplicateDetection(
   const resolvedOptions = resolveDuplicateDetectionOptions(options);
   if (resolvedOptions === undefined) {
     throw new TypeError(
-      "duplicateDetection options are invalid; use the documented closed constructor policy"
+      "duplicateDetection options are invalid; use the documented closed constructor policy including exact finding waivers"
     );
   }
   return defineCheck({