@zxyycom/vibe-check 0.0.1

package/types/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Vibe Check 是由项目在 Bun runtime 中调用的 TypeScript API，用于定义并执行项目质量 Check。
+ * 所有公开能力从 package root 导入；package `README.md` 说明 consumer authoring、结果读取和分发范围。
+ *
+ * @packageDocumentation
+ */
+export { duplicateDetection } from "./package-checks/duplicate-detection/default-check.ts";
+export { parseDuplicateDetectionData } from "./package-checks/duplicate-detection/final-data.ts";
+export type { DuplicateDetectionFinalData } from "./package-checks/duplicate-detection/final-data.ts";
+export type { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./package-checks/duplicate-detection/options.ts";
+export type { DuplicateDetectionUnavailableReasonCode } from "./package-checks/duplicate-detection/execution.ts";
+export type { DuplicateDetectionRecordData } from "./package-checks/duplicate-detection/records.ts";
+export { fileMetrics } from "./package-checks/file-metrics/constructor.ts";
+export { parseFileMetricsData } from "./package-checks/file-metrics/final-data.ts";
+export type { FileMetricsFinalData } from "./package-checks/file-metrics/final-data.ts";
+export type { FileMetricsFindingIdentity, FileMetricsFindingWaiver, FileMetricsOptions, ResolvedFileMetricsOptions } from "./package-checks/file-metrics/options.ts";
+export type { FileMetricsUnavailableReasonCode } from "./package-checks/file-metrics/execution.ts";
+export type { FileMetricsRecordData } from "./package-checks/file-metrics/records.ts";
+export { functionMetrics } from "./package-checks/function-metrics/constructor.ts";
+export { parseFunctionMetricsData } from "./package-checks/function-metrics/final-data.ts";
+export type { FunctionMetricsFinalData } from "./package-checks/function-metrics/final-data.ts";
+export type { FunctionMetricsOptions, ResolvedFunctionMetricsOptions } from "./package-checks/function-metrics/options.ts";
+export type { FunctionMetricsUnavailableReasonCode } from "./package-checks/function-metrics/execution.ts";
+export type { FunctionMetricsRecordData } from "./package-checks/function-metrics/records.ts";
+export { jsonSchemaValidation } from "./package-checks/json-schema-validation/default-check.ts";
+export { parseJsonSchemaValidationData } from "./package-checks/json-schema-validation/final-data.ts";
+export type { JsonSchemaValidationFinalData } from "./package-checks/json-schema-validation/final-data.ts";
+export type { JsonSchemaValidationOptions, ResolvedJsonSchemaValidationOptions } from "./package-checks/json-schema-validation/options.ts";
+export type { JsonSchemaDocumentReason, JsonSchemaValidationRecordData, JsonSchemaValidationRecordReason, JsonSchemaValidationUnavailableCode } from "./package-checks/json-schema-validation/json-schema-validation.ts";
+export { jsonValidation } from "./package-checks/json-validation/default-check.ts";
+export { parseJsonValidationData } from "./package-checks/json-validation/final-data.ts";
+export type { JsonValidationFinalData } from "./package-checks/json-validation/final-data.ts";
+export type { JsonValidationOptions, ResolvedJsonValidationOptions } from "./package-checks/json-validation/options.ts";
+export type { JsonValidationRecordData, JsonValidationRecordReason, JsonValidationUnavailableCode } from "./package-checks/json-validation/json-validation.ts";
+export { maintenanceReminders } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
+export type { MaintenanceReminder, MaintenanceReminderOptions, MaintenanceRemindersUnavailableCode } from "./package-checks/maintenance-reminders/maintenance-reminders.ts";
+export { parseMaintenanceRemindersData } from "./package-checks/maintenance-reminders/final-data.ts";
+export type { MaintenanceReminderAssessment, MaintenanceReminderUnavailableReason, MaintenanceRemindersFinalData } from "./package-checks/maintenance-reminders/final-data.ts";
+export { markdownLinkValidation } from "./package-checks/markdown-link-validation/default-check.ts";
+export { parseMarkdownLinkValidationData } from "./package-checks/markdown-link-validation/final-data.ts";
+export type { MarkdownLinkValidationFinalData } from "./package-checks/markdown-link-validation/final-data.ts";
+export type { MarkdownLinkValidationOptions, ResolvedMarkdownLinkValidationOptions } from "./package-checks/markdown-link-validation/options.ts";
+export type { MarkdownLinkValidationUnavailableReason } from "./package-checks/markdown-link-validation/execution.ts";
+export type { MarkdownLinkValidationRecordData } from "./package-checks/markdown-link-validation/records.ts";
+export type { MarkdownLinkFindingReason } from "./package-checks/markdown-link-validation/local-resolver.ts";
+export type { FindingPolicy } from "./package-checks/code-quality-findings/policy.ts";
+export { reconcileFindingWaivers } from "./finding-waivers/reconciliation.ts";
+export type { FindingWaiver, FindingWaiverAudit, FindingWaiverReconciliation, MaterializedFindingWaiver, ReconciledFinding, ReconcileFindingWaiversOptions } from "./finding-waivers/reconciliation.ts";
+export { defaultProjectFileSelection } from "./package-checks/project-files/configuration.ts";
+export type { ProjectFileSelection, ProjectFileSelectionOptions, ProjectFileSource } from "./package-checks/project-files/configuration.ts";
+export { defineCheck, inherit } from "./check/check.ts";
+export type { Check, CheckExecution, CheckExecutionContext, CheckPreflight, CheckPreflightResult, CheckOutcome, CheckResult, CheckUnavailableReason, InheritableCheckCollection } from "./check/check.ts";
+export { defineConfig } from "./project-definition/project-definition.ts";
+export type { ProjectOutputs, ProjectDefinition, SchedulerPolicy } from "./project-definition/project-definition.ts";
+export type { CheckAggregate, CheckAggregation, RunControls } from "./project-run/controls/contract.ts";
+export { run } from "./project-run/run.ts";
+export type { RunResult } from "./project-run/result.ts";

package/types/machine-output/v4/atomic-publication.d.ts

@@ -0,0 +1,9 @@
+interface PublicationCandidates {
+    readonly recordsNdjson: string;
+    readonly runJson: string;
+}
+/** Writes an already validated two-file candidate set through owned temporary paths. */
+export declare function publishPublicationCandidatesV4(artifactDir: string, candidates: PublicationCandidates): void;
+export declare function cleanupPublicationV4(artifactDir: string): void;
+export declare function cleanupPublicationV4BestEffort(artifactDir: string): void;
+export {};

package/types/machine-output/v4/freeze-publication-value.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Output projections are validated or freshly constructed plain data. Freeze
+ * them before they cross a publication boundary so later consumers cannot
+ * drift from the one validated model.
+ */
+export declare function freezePublicationValue<T>(value: T): T;

package/types/machine-output/v4/projection.d.ts

@@ -0,0 +1,7 @@
+import type { TrustedPublicationModelV4 } from "./publication-model.ts";
+import type { MachineRecordV4, MachineRunV4 } from "./schema.ts";
+export interface MachinePublicationV4 {
+    readonly records: readonly MachineRecordV4[];
+    readonly run: MachineRunV4;
+}
+export declare function projectMachinePublicationV4(model: TrustedPublicationModelV4): MachinePublicationV4;

package/types/machine-output/v4/publication-invariants.d.ts

@@ -0,0 +1,3 @@
+import type { MachineRecordV4, MachineRunV4 } from "./schema.ts";
+import { type ValidationFailure } from "./validation-result.ts";
+export declare function validatePublicationInvariants(run: MachineRunV4, records: readonly MachineRecordV4[]): ValidationFailure | null;

package/types/machine-output/v4/publication-model.d.ts

@@ -0,0 +1,15 @@
+import type { CoreSnapshot } from "../../check-settlement/facts.ts";
+export interface PublicationInvocationV4 {
+    readonly invocationId: string;
+    readonly projectRoot: ".";
+    readonly timestamp: string;
+}
+/** Trusted Core facts and validated invocation metadata for v4 candidate projection. */
+export interface TrustedPublicationModelV4 {
+    readonly invocation: PublicationInvocationV4;
+    readonly snapshot: CoreSnapshot;
+}
+export declare function createPublicationModelV4(input: Readonly<{
+    invocation: PublicationInvocationV4;
+    snapshot: CoreSnapshot;
+}>): TrustedPublicationModelV4;

package/types/machine-output/v4/publish.d.ts

@@ -0,0 +1,7 @@
+import { type TrustedPublicationModelV4 } from "./publication-model.ts";
+export { cleanupPublicationV4, cleanupPublicationV4BestEffort } from "./atomic-publication.ts";
+/** Publishes only the validated two-file machine set; human projection is not a v4 concern. */
+export declare function publishScanV4(input: Readonly<{
+    artifactDir: string;
+    model: TrustedPublicationModelV4;
+}>): void;

package/types/machine-output/v4/records-fingerprint.d.ts

@@ -0,0 +1,4 @@
+import type { MachineRecordV4 } from "./schema.ts";
+export declare const MACHINE_RECORDS_V4_FINGERPRINT_PREFIX = "check-record/v2/records/sha256:";
+/** Binds the complete, canonically ordered v4 Record row set, including empty. */
+export declare function createRecordsFingerprintV4(records: readonly MachineRecordV4[]): string;

package/types/machine-output/v4/schema-identities.d.ts

@@ -0,0 +1,7 @@
+export declare const MACHINE_RUN_V4_SCHEMA_ID = "urn:vibe-check:schema:run:v4";
+export declare const MACHINE_RECORD_V4_SCHEMA_ID = "urn:vibe-check:schema:record:v4";
+export declare const MACHINE_RUN_V4_IDENTITY = "vibe-check.run.v4";
+export declare const MACHINE_RECORD_V4_IDENTITY = "vibe-check.record.v4";
+export declare const MACHINE_V4_TIMESTAMP_PATTERN = "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$";
+export declare const MACHINE_RUN_V4_SCHEMA_PATH = "docs/schemas/vibe-check-run.schema.json";
+export declare const MACHINE_RECORD_V4_SCHEMA_PATH = "docs/schemas/vibe-check-record.schema.json";

package/types/machine-output/v4/schema.d.ts

@@ -0,0 +1,44 @@
+import Type from "typebox";
+export declare const MACHINE_RECORD_V4_SCHEMA: Type.TObject<{
+    checkId: Type.TString;
+    data: Type.TRecord<"^.*$", Type.TAny>;
+    id: Type.TString;
+    schemaVersion: Type.TLiteral<"vibe-check.record.v4">;
+}>;
+export declare const MACHINE_RUN_V4_SCHEMA: Type.TObject<{
+    checks: Type.TArray<Type.TObject<{
+        checkId: Type.TString;
+        displayName: Type.TString;
+        outcome: Type.TUnion<[Type.TObject<{
+            data: Type.TRecord<"^.*$", Type.TAny>;
+            status: Type.TLiteral<"passed">;
+        }>, Type.TObject<{
+            data: Type.TRecord<"^.*$", Type.TAny>;
+            status: Type.TLiteral<"failed">;
+        }>, Type.TObject<{
+            reason: Type.TOptional<Type.TObject<{
+                code: Type.TString;
+            }>>;
+            status: Type.TLiteral<"not-applicable">;
+        }>, Type.TObject<{
+            reason: Type.TObject<{
+                checkIds: Type.TOptional<Type.TArray<Type.TString>>;
+                code: Type.TString;
+            }>;
+            status: Type.TLiteral<"unavailable">;
+        }>]>;
+    }>>;
+    invocation: Type.TObject<{
+        invocationId: Type.TString;
+        projectRoot: Type.TLiteral<".">;
+        timestamp: Type.TString;
+    }>;
+    recordsFingerprint: Type.TString;
+    schemaVersion: Type.TLiteral<"vibe-check.run.v4">;
+}>;
+type DeepReadonly<Value> = Value extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : Value extends object ? {
+    readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
+} : Value;
+export type MachineRecordV4 = DeepReadonly<Type.Static<typeof MACHINE_RECORD_V4_SCHEMA>>;
+export type MachineRunV4 = DeepReadonly<Type.Static<typeof MACHINE_RUN_V4_SCHEMA>>;
+export {};

package/types/machine-output/v4/serializers.d.ts

@@ -0,0 +1,6 @@
+import type { MachinePublicationV4 } from "./projection.ts";
+export interface MachinePublicationCandidatesV4 {
+    readonly recordsNdjson: string;
+    readonly runJson: string;
+}
+export declare function serializeMachinePublicationV4(publication: MachinePublicationV4): MachinePublicationCandidatesV4;

package/types/machine-output/v4/validation-result.d.ts

@@ -0,0 +1,26 @@
+import type { MachinePublicationV4 } from "./projection.ts";
+export type MachinePublicationValidationCategory = "decoding" | "framing" | "schema" | "set-invariant" | "syntax";
+export type MachinePublicationSetRelationship = "check-canonical-order" | "core-snapshot" | "record-canonical-order" | "record-check-ownership" | "records-fingerprint";
+export interface MachinePublicationValidationDiagnostic {
+    readonly category: MachinePublicationValidationCategory;
+    readonly index?: number;
+    readonly line?: number;
+    readonly logicalArtifact: "records.ndjson" | "run.json";
+    readonly message: string;
+    readonly pointer?: string;
+    readonly relationship?: MachinePublicationSetRelationship;
+}
+export type MachinePublicationValidationResult = Readonly<ValidationFailure | {
+    ok: true;
+    value: MachinePublicationV4;
+}>;
+export interface ValidationFailure {
+    readonly ok: false;
+    readonly diagnostic: MachinePublicationValidationDiagnostic;
+}
+export declare function validationSuccess<Value>(value: Value): {
+    ok: true;
+    value: Value;
+};
+export declare function validationFailure(diagnostic: MachinePublicationValidationDiagnostic): ValidationFailure;
+export declare function setInvariantFailure(relationship: MachinePublicationSetRelationship, logicalArtifact: MachinePublicationValidationDiagnostic["logicalArtifact"], message: string, index?: number): ValidationFailure;

package/types/machine-output/v4/validation.d.ts

@@ -0,0 +1,6 @@
+import { type MachinePublicationValidationResult } from "./validation-result.ts";
+export type { MachinePublicationSetRelationship, MachinePublicationValidationCategory, MachinePublicationValidationDiagnostic, MachinePublicationValidationResult } from "./validation-result.ts";
+export declare function validateMachinePublicationSetV4(input: Readonly<{
+    recordsNdjson: Uint8Array;
+    runJson: Uint8Array;
+}>): MachinePublicationValidationResult;

package/types/package-checks/code-quality-findings/policy.d.ts

@@ -0,0 +1,20 @@
+import type { CheckResult } from "../../check/check.ts";
+export declare const FINDING_POLICIES: readonly ["blocking", "non-blocking"];
+/** package-provided Check 用于结算 normal finding 的阻断策略。 */
+export type FindingPolicy = (typeof FINDING_POLICIES)[number];
+export declare const DEFAULT_FINDING_POLICY: FindingPolicy;
+/** 三个代码质量 Check 正常完成时返回的精确 finding 计数。 */
+export interface FindingSummary {
+    readonly blockingFindingCount: number;
+    readonly findingCount: number;
+}
+/** 一项 finding 在 Check 自己结算前的领域中性处置。 */
+export interface FindingSettlement {
+    /** 该 finding 是否仍需要进入该 Check 的正常 finding 结算。 */
+    readonly actionable: boolean;
+    readonly blocking: boolean;
+}
+export declare function resolveFindingPolicy(value: unknown, fallback?: FindingPolicy): FindingPolicy | undefined;
+export declare function validFindingPolicy(value: unknown): value is FindingPolicy;
+export declare function isBlockingFinding(policies: readonly FindingPolicy[]): boolean;
+export declare function settleFindings(findings: readonly FindingSettlement[]): CheckResult<FindingSummary>;

package/types/package-checks/duplicate-detection/area-policy.d.ts

@@ -0,0 +1,3 @@
+import type { DuplicateCodeFragment, DuplicateDetectionAreaInput } from "./measurement-model.ts";
+/** Restores every matching code area and applies the strictest involved policy. */
+export declare function applyDuplicateAreaPolicy(fragments: readonly DuplicateCodeFragment[], areas: readonly DuplicateDetectionAreaInput[]): readonly DuplicateCodeFragment[] | undefined;

package/types/package-checks/duplicate-detection/cache/cache-contract.d.ts

@@ -0,0 +1,48 @@
+import type { FileInputFingerprint } from "../../project-files/file-fingerprint.ts";
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+export declare const SCAN_CACHE_VERSION = "quality-scan-cache-v3";
+export type DuplicateScannerCacheConfiguration = Readonly<{
+    backend: Readonly<{
+        kind: "package";
+    } | {
+        executable: string;
+        kind: "custom";
+    }>;
+    minimumLines: number;
+    minimumTokens: number;
+    reportedPathMode: "absolute";
+    reporter: "json";
+    workerPolicy: "tool-default";
+}>;
+export type DuplicateCodeCacheIdentity = Readonly<{
+    commitSha: string;
+    configVersion: string;
+    inputFingerprint: FileInputFingerprint;
+    scannerConfiguration: DuplicateScannerCacheConfiguration;
+    toolName: "jscpd";
+    toolVersion: string;
+}>;
+export type DuplicateCodeCacheHit = Readonly<{
+    cacheKey: string;
+    cachePath: string;
+    hit: true;
+    metrics: readonly DuplicateCodeFragment[];
+}>;
+export type DuplicateCodeCacheMiss = Readonly<{
+    cacheKey: string;
+    cachePath: string;
+    hit: false;
+    reason: "cache-miss" | "cache-payload-invalid" | "cache-payload-mismatch";
+}>;
+export type ScanCachePayload = Readonly<{
+    cacheKey: string;
+    commitSha: string;
+    configVersion: string;
+    createdAt: string;
+    inputFingerprint: FileInputFingerprint;
+    metrics: unknown;
+    scannerConfiguration: DuplicateScannerCacheConfiguration;
+    scanCacheVersion: string;
+    toolName: "jscpd";
+    toolVersion: string;
+}>;

package/types/package-checks/duplicate-detection/cache/identity.d.ts

@@ -0,0 +1,17 @@
+import type { DuplicateDetectionExactInputSet } from "../measurement-model.ts";
+import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
+import type { DuplicateCodeCacheIdentity, DuplicateScannerCacheConfiguration } from "./cache-contract.ts";
+interface DuplicateScanCacheIdentityInput {
+    readonly dependency: ResolvedDuplicateDetectionScannerOptions;
+    readonly exactInput: DuplicateDetectionExactInputSet;
+    readonly minimumLines: number;
+    readonly minimumTokens: number;
+    readonly toolVersion: string;
+}
+export declare function createDuplicateScanCacheIdentity(input: DuplicateScanCacheIdentityInput): DuplicateCodeCacheIdentity;
+export declare function jscpdCacheConfiguration(input: {
+    readonly dependency: ResolvedDuplicateDetectionScannerOptions;
+    readonly minimumLines: number;
+    readonly minimumTokens: number;
+}): DuplicateScannerCacheConfiguration;
+export {};

package/types/package-checks/duplicate-detection/cache/key.d.ts

@@ -0,0 +1,4 @@
+import { type DuplicateCodeCacheIdentity } from "./cache-contract.ts";
+export declare function buildScanCacheKey(identity: DuplicateCodeCacheIdentity): string;
+export declare function getScanCachePath(rootDir: string, cacheKey: string): string;
+export declare function stableStringify(value: unknown): string;

package/types/package-checks/duplicate-detection/cache/payload.d.ts

@@ -0,0 +1,4 @@
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+import { type DuplicateCodeCacheIdentity, type ScanCachePayload } from "./cache-contract.ts";
+export declare function isMatchingPayload(payload: unknown, identity: DuplicateCodeCacheIdentity, cacheKey: string): payload is ScanCachePayload;
+export declare function isMetricArray(value: unknown): value is readonly DuplicateCodeFragment[];

package/types/package-checks/duplicate-detection/cache/store.d.ts

@@ -0,0 +1,18 @@
+/** 读取和写入 duplicate-code raw-scan cache entries。 */
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+import { type DuplicateCodeCacheHit, type DuplicateCodeCacheIdentity, type DuplicateCodeCacheMiss } from "./cache-contract.ts";
+export { buildScanCacheKey, getScanCachePath } from "./key.ts";
+export { SCAN_CACHE_VERSION } from "./cache-contract.ts";
+export type { DuplicateCodeCacheHit, DuplicateCodeCacheIdentity, DuplicateCodeCacheMiss } from "./cache-contract.ts";
+export declare function loadScanCacheEntry({ rootDir, identity }: {
+    identity: DuplicateCodeCacheIdentity;
+    rootDir: string;
+}): DuplicateCodeCacheHit | DuplicateCodeCacheMiss;
+export declare function writeScanCacheEntry({ rootDir, identity, metrics }: {
+    identity: DuplicateCodeCacheIdentity;
+    metrics: readonly DuplicateCodeFragment[];
+    rootDir: string;
+}): {
+    cacheKey: string;
+    cachePath: string;
+};

package/types/package-checks/duplicate-detection/default-check.d.ts

@@ -0,0 +1,11 @@
+import { type TypedCheckWithOptions } from "../../check/check.ts";
+import { parseDuplicateDetectionData } from "./final-data.ts";
+import type { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./options.ts";
+/**
+ * 使用可省略的区域、cache 与 scanner policy 构造一个完整 duplicate-detection Check。
+ *
+ * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
+ * @returns 固定 `duplicate-detection` identity、完整冻结 options、preflight 与 execution。
+ * @throws {TypeError} input 含未知字段、空 area、非法阈值、非法 cache 或 scanner policy 时抛出。
+ */
+export declare function duplicateDetection(options?: DuplicateDetectionOptions): TypedCheckWithOptions<"duplicate-detection", ResolvedDuplicateDetectionOptions, typeof parseDuplicateDetectionData>;

package/types/package-checks/duplicate-detection/execution.d.ts

@@ -0,0 +1,11 @@
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import type { ResolvedDuplicateDetectionOptions } from "./options.ts";
+import type { DuplicateDetectionFinalData } from "./final-data.ts";
+export declare const DUPLICATE_DETECTION_CHECK_DEFINITION: {
+    readonly checkId: "duplicate-detection";
+    readonly displayName: "Duplicate detection";
+};
+/** `duplicate-detection` whole-Check unavailable outcome 的稳定 reason code。 */
+export type DuplicateDetectionUnavailableReasonCode = "cache-write-failed" | "external-dependency-unavailable" | "external-execution-failed" | "external-result-invalid" | "invalid-options" | "source-unavailable";
+/** Default Check callback；scanner configuration 由其完整 options 拥有。 */
+export declare function executeDuplicateDetection(context: CheckExecutionContext<ResolvedDuplicateDetectionOptions>): Promise<CheckResult<DuplicateDetectionFinalData>>;

package/types/package-checks/duplicate-detection/final-data.d.ts

@@ -0,0 +1,5 @@
+import type { FindingSummary } from "../code-quality-findings/policy.ts";
+/** `duplicate-detection` 在 passed/failed outcome 中发布的主数据。 */
+export type DuplicateDetectionFinalData = FindingSummary;
+/** 验证并脱离一份 `duplicate-detection` canonical final-data object。 */
+export declare function parseDuplicateDetectionData(data: unknown): DuplicateDetectionFinalData;

package/types/package-checks/duplicate-detection/jscpd/availability.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
+type JscpdAvailability = Readonly<{
+    available: true;
+    error: null;
+    name: "jscpd";
+    reason: null;
+    source: JscpdSource;
+    version: string;
+} | {
+    available: false;
+    error: string;
+    name: "jscpd";
+    reason: "execution-error" | "tool-unavailable";
+    source: JscpdSource;
+    version: null;
+}>;
+type JscpdSource = "custom command" | "package dependency";
+export declare function checkJscpd(rootDir: string, dependency: ResolvedDuplicateDetectionScannerOptions): Promise<JscpdAvailability>;
+export {};

package/types/package-checks/duplicate-detection/jscpd/command-path.d.ts

@@ -0,0 +1 @@
+export declare function isMissingExplicitCommand(command: string): boolean;

package/types/package-checks/duplicate-detection/jscpd/command-resolution.d.ts

@@ -0,0 +1,23 @@
+import type { DuplicateDetectionScannerCommand } from "../options.ts";
+export interface JscpdCommand {
+    readonly executable: string;
+    readonly scanPrefixArguments: readonly string[];
+    readonly versionArguments: readonly string[];
+}
+export type ResolvedJscpdCommand = Readonly<{
+    command: JscpdCommand;
+    kind: "resolved";
+}> | Readonly<{
+    error: string;
+    kind: "unavailable";
+}>;
+/**
+ * package-provided scanner 的可移植 marker。真实 executable 只由私有 jscpd adapter 解析，避免公共
+ * Definition 与 fingerprint 保存 consumer-specific Bun 或 package path。
+ */
+export declare const DEFAULT_JSCPD_COMMAND: DuplicateDetectionScannerCommand;
+export declare function isPackageJscpdCommand(command: DuplicateDetectionScannerCommand): command is Extract<DuplicateDetectionScannerCommand, {
+    readonly kind: "package";
+}>;
+export declare function resolveJscpdCommand(command: DuplicateDetectionScannerCommand): ResolvedJscpdCommand;
+export declare function readJscpdBinTarget(packageManifestPath: string): string | null;

package/types/package-checks/duplicate-detection/jscpd/json-report.d.ts

@@ -0,0 +1,2 @@
+import type { JscpdScanResult } from "./scanner-contract.ts";
+export declare function parseJscpdJsonReport(json: string, cwd: string): JscpdScanResult;

package/types/package-checks/duplicate-detection/jscpd/scanner-contract.d.ts

@@ -0,0 +1,11 @@
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
+export type JscpdScanFailureReason = "jscpd-execution-error" | "jscpd-report-failure" | "jscpd-parse-failure";
+export type JscpdScanResult = {
+    readonly measurements: readonly ExactInputMeasurement<DuplicateCodeFragment>[];
+    readonly ok: true;
+} | {
+    readonly error: string;
+    readonly ok: false;
+    readonly reason: JscpdScanFailureReason;
+};

package/types/package-checks/duplicate-detection/jscpd/scanner.d.ts

@@ -0,0 +1,21 @@
+/**
+ * jscpd duplicate-code detection wrapper.
+ *
+ * Runs the Check-owned jscpd CLI, writes a temporary config for the
+ * approved exact-scope file list, and normalizes the JSON report behind the
+ * repository-owned DuplicateCodeFragment model.
+ */
+import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
+import type { JscpdScanResult } from "./scanner-contract.ts";
+export type { JscpdScanResult } from "./scanner-contract.ts";
+export { parseJscpdJsonReport } from "./json-report.ts";
+export declare function parseJscpdVersionOutput(output: string): string | null;
+interface ScanWithJscpdOptions {
+    readonly cwd: string;
+    readonly dependency: ResolvedDuplicateDetectionScannerOptions;
+    readonly files: readonly string[];
+    readonly minimumLines: number;
+    readonly minimumTokens: number;
+}
+export declare function scanWithJscpd(options: ScanWithJscpdOptions): JscpdScanResult;
+export declare function scanWithJscpdAsync(options: ScanWithJscpdOptions): Promise<JscpdScanResult>;

package/types/package-checks/duplicate-detection/jscpd/scoped-fragments.d.ts

@@ -0,0 +1,4 @@
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+import type { ExactInputMeasurement } from "../../project-files/exact-input-measurement.ts";
+export declare function toScopedJscpdMeasurement(fragment: DuplicateCodeFragment): ExactInputMeasurement<DuplicateCodeFragment>;
+export declare function toScopedJscpdMeasurements(fragments: readonly DuplicateCodeFragment[]): ExactInputMeasurement<DuplicateCodeFragment>[];

package/types/package-checks/duplicate-detection/measurement-model.d.ts

@@ -0,0 +1,36 @@
+import type { ResolvedDuplicateDetectionOptions, ResolvedDuplicateDetectionScannerOptions } from "./options.ts";
+export interface DuplicateCodeLocation {
+    readonly endLine: number;
+    readonly path: string;
+    readonly startLine: number;
+}
+export interface DuplicateCodeFragment {
+    readonly codeAreas: readonly string[];
+    readonly id: number;
+    readonly lineCount: number;
+    readonly locations: readonly DuplicateCodeLocation[];
+    readonly tokenCount: number;
+}
+export interface DuplicateDetectionAreaInput {
+    readonly approvedExactPaths: readonly string[];
+    readonly codeArea: string;
+    readonly minimumLines: number;
+    readonly minimumTokens: number;
+}
+export interface DuplicateDetectionExactInputSet {
+    readonly approvedExactPaths: readonly string[];
+    readonly areas: readonly DuplicateDetectionAreaInput[];
+    readonly cacheRootDir: string;
+    readonly commitSha: string;
+    readonly inputFingerprint: Readonly<{
+        readonly fileCount: number;
+        readonly fileList: readonly string[];
+        readonly fingerprint: string;
+    }>;
+    readonly rootDir: string;
+}
+export interface DuplicateMeasurementInput {
+    readonly cache: ResolvedDuplicateDetectionOptions["cache"];
+    readonly dependency: ResolvedDuplicateDetectionScannerOptions;
+    readonly exactInput: DuplicateDetectionExactInputSet;
+}

package/types/package-checks/duplicate-detection/measurement.d.ts

@@ -0,0 +1,14 @@
+import type { DuplicateCodeFragment, DuplicateMeasurementInput } from "./measurement-model.ts";
+export type DuplicateMeasurementResult = Readonly<{
+    fragments: readonly DuplicateCodeFragment[];
+    kind: "complete";
+} | {
+    kind: "execution-failed";
+} | {
+    kind: "invalid-result";
+} | {
+    kind: "cache-write-failed";
+} | {
+    kind: "unavailable";
+}>;
+export declare function measureDuplicateDetection(options: DuplicateMeasurementInput): Promise<DuplicateMeasurementResult>;

package/types/package-checks/duplicate-detection/options-resolution.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedDuplicateDetectionOptions } from "./options.ts";
+/** 校验 constructor input，并将所有可省略 policy 物化为完整、冻结的 Check options。 */
+export declare function resolveDuplicateDetectionOptions(value: unknown): ResolvedDuplicateDetectionOptions | undefined;

package/types/package-checks/duplicate-detection/options-validation.d.ts

@@ -0,0 +1 @@
+export declare function validResolvedDuplicateDetectionOptions(value: object): boolean;

package/types/package-checks/duplicate-detection/options.d.ts

@@ -0,0 +1,65 @@
+import type { ProjectFileSelection, ProjectFileSelectionOptions } from "../project-files/configuration.ts";
+import type { FindingPolicy } from "../code-quality-findings/policy.ts";
+export type DuplicateDetectionScannerCommand = 
+/** 使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
+Readonly<{
+    readonly kind: "package";
+}>
+/** 显式授权另一个 jscpd 命令。 */
+ | Readonly<{
+    /** 项目已授权且直接接受 jscpd CLI 参数的非空命令。 */
+    readonly executable: string;
+    readonly kind: "custom";
+}>;
+/** `duplicateDetection` 构造函数可省略的缓存策略。 */
+export interface DuplicateDetectionCacheOptions {
+    /** 省略时为 `.cache/vibe-check`；相对路径以项目根目录解析。 */
+    readonly directory?: string;
+    /** 省略时启用。 */
+    readonly enabled?: boolean;
+}
+/** `duplicateDetection` 构造函数可省略的 scanner 策略。 */
+export interface DuplicateDetectionScannerOptions {
+    /** 省略时使用随 `@zxyycom/vibe-check` 安装的 jscpd。 */
+    readonly command?: DuplicateDetectionScannerCommand;
+}
+/** 重复代码区域可省略并由构造函数补齐的文件策略。 */
+export type DuplicateDetectionFileOptions = ProjectFileSelectionOptions;
+/** 可独立选择文件、阈值和 finding policy 的重复代码区域。 */
+export interface DuplicateDetectionCodeAreaOptions {
+    /** 显式区域必须声明本字段；其中各子字段可省略并使用 package 默认值。 */
+    readonly files: DuplicateDetectionFileOptions;
+    /** 省略时继承顶层 `findingPolicy`。 */
+    readonly findingPolicy?: FindingPolicy;
+    /** 省略时为 `4`。 */
+    readonly minimumLines?: number;
+    /** 省略时为 `100`。 */
+    readonly minimumTokens?: number;
+}
+/** `duplicateDetection(options?)` 接受并补齐默认值的公开策略。 */
+export interface DuplicateDetectionOptions {
+    /** 省略时建立默认 `project` 区域；显式映射必须非空。 */
+    readonly codeAreas?: Readonly<Record<string, DuplicateDetectionCodeAreaOptions>>;
+    readonly cache?: DuplicateDetectionCacheOptions;
+    /** 省略时为 `non-blocking`；区域可局部覆盖。 */
+    readonly findingPolicy?: FindingPolicy;
+    readonly scanner?: DuplicateDetectionScannerOptions;
+}
+/** 构造函数生成并由 Check preflight/execution 消费的完整 options。 */
+export interface ResolvedDuplicateDetectionOptions {
+    readonly cache: Readonly<{
+        readonly directory: string;
+        readonly enabled: boolean;
+    }>;
+    readonly codeAreas: Readonly<Record<string, ResolvedDuplicateDetectionCodeAreaOptions>>;
+    readonly scanner: ResolvedDuplicateDetectionScannerOptions;
+}
+export interface ResolvedDuplicateDetectionCodeAreaOptions {
+    readonly files: ProjectFileSelection;
+    readonly findingPolicy: FindingPolicy;
+    readonly minimumLines: number;
+    readonly minimumTokens: number;
+}
+export interface ResolvedDuplicateDetectionScannerOptions {
+    readonly command: DuplicateDetectionScannerCommand;
+}

package/types/package-checks/duplicate-detection/project-revision.d.ts

@@ -0,0 +1 @@
+export declare function getGitSha(cwd: string): string;

package/types/package-checks/duplicate-detection/records.d.ts

@@ -0,0 +1,22 @@
+import type { DuplicateCodeFragment } from "./measurement-model.ts";
+import type { ResolvedDuplicateDetectionOptions } from "./options.ts";
+/** 一条可信重复片段 supplemental Record 的 data。 */
+export type DuplicateDetectionRecordData = Readonly<{
+    readonly blocking: boolean;
+    readonly codeAreas: readonly string[];
+    readonly lineCount: number;
+    readonly locations: readonly Readonly<{
+        readonly endLine: number;
+        readonly path: string;
+        readonly startLine: number;
+    }>[];
+    readonly metric: "duplicate-tokens";
+    readonly tokenCount: number;
+}>;
+export interface DuplicateRecordCandidate {
+    readonly data: DuplicateDetectionRecordData;
+    readonly id: string;
+}
+/** Builds Check-owned supplemental facts without adding a Product record catalog. */
+export declare function buildDuplicateRecordCandidates(fragments: readonly DuplicateCodeFragment[], codeAreas: ResolvedDuplicateDetectionOptions["codeAreas"]): readonly DuplicateRecordCandidate[] | undefined;
+export declare function isValidDuplicateFragment(fragment: DuplicateCodeFragment): boolean;