@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,78 @@
+import { isNonArrayRecord } from "../../../data-boundary/value-shapes.ts";
+import type { DuplicateCodeFragment, DuplicateCodeLocation } from "../measurement-model.ts";
+import { stableStringify } from "./key.ts";
+import {
+  SCAN_CACHE_VERSION,
+  type DuplicateCodeCacheIdentity,
+  type ScanCachePayload
+} from "./cache-contract.ts";
+
+export function isMatchingPayload(
+  payload: unknown,
+  identity: DuplicateCodeCacheIdentity,
+  cacheKey: string
+): payload is ScanCachePayload {
+  if (!isNonArrayRecord(payload)) return false;
+
+  return (
+    cacheIdentityFieldsMatch(payload, identity, cacheKey) &&
+    cacheStructuredFieldsMatch(payload, identity)
+  );
+}
+
+export function isMetricArray(value: unknown): value is readonly DuplicateCodeFragment[] {
+  if (!Array.isArray(value)) return false;
+  return value.every(isDuplicateCodeFragment);
+}
+
+function cacheIdentityFieldsMatch(
+  payload: Record<string, unknown>,
+  identity: DuplicateCodeCacheIdentity,
+  cacheKey: string
+): boolean {
+  return (
+    payload.scanCacheVersion === SCAN_CACHE_VERSION &&
+    payload.cacheKey === cacheKey &&
+    payload.toolName === identity.toolName &&
+    payload.toolVersion === identity.toolVersion &&
+    payload.configVersion === identity.configVersion &&
+    payload.commitSha === identity.commitSha
+  );
+}
+
+function cacheStructuredFieldsMatch(
+  payload: Record<string, unknown>,
+  identity: DuplicateCodeCacheIdentity
+): boolean {
+  return (
+    stableStringify(payload.scannerConfiguration) ===
+      stableStringify(identity.scannerConfiguration) &&
+    stableStringify(payload.inputFingerprint) === stableStringify(identity.inputFingerprint)
+  );
+}
+
+function isDuplicateCodeFragment(value: unknown): value is DuplicateCodeFragment {
+  return (
+    isNonArrayRecord(value) &&
+    isFiniteNumber(value.id) &&
+    isFiniteNumber(value.tokenCount) &&
+    isFiniteNumber(value.lineCount) &&
+    Array.isArray(value.codeAreas) &&
+    value.codeAreas.every((area) => typeof area === "string") &&
+    Array.isArray(value.locations) &&
+    value.locations.every(isDuplicateCodeLocation)
+  );
+}
+
+function isDuplicateCodeLocation(value: unknown): value is DuplicateCodeLocation {
+  return (
+    isNonArrayRecord(value) &&
+    typeof value.path === "string" &&
+    isFiniteNumber(value.startLine) &&
+    isFiniteNumber(value.endLine)
+  );
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}

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

@@ -0,0 +1,77 @@
+/** 读取和写入 duplicate-code raw-scan cache entries。 */
+
+import { readJsonFile, writeJsonFile } from "../../host-environment/filesystem.ts";
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+import { buildScanCacheKey, getScanCachePath } from "./key.ts";
+import { isMatchingPayload, isMetricArray } from "./payload.ts";
+import {
+  SCAN_CACHE_VERSION,
+  type DuplicateCodeCacheHit,
+  type DuplicateCodeCacheIdentity,
+  type DuplicateCodeCacheMiss,
+  type ScanCachePayload
+} 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 function loadScanCacheEntry({
+  rootDir,
+  identity
+}: {
+  identity: DuplicateCodeCacheIdentity;
+  rootDir: string;
+}): DuplicateCodeCacheHit | DuplicateCodeCacheMiss {
+  const cacheKey = buildScanCacheKey(identity);
+  const cachePath = getScanCachePath(rootDir, cacheKey);
+
+  let payload: unknown;
+  try {
+    payload = readJsonFile(cachePath);
+  } catch {
+    return { hit: false, reason: "cache-miss", cacheKey, cachePath };
+  }
+
+  if (!isMatchingPayload(payload, identity, cacheKey)) {
+    return { hit: false, reason: "cache-payload-mismatch", cacheKey, cachePath };
+  }
+
+  if (!isMetricArray(payload.metrics)) {
+    return { hit: false, reason: "cache-payload-invalid", cacheKey, cachePath };
+  }
+
+  return { hit: true, metrics: payload.metrics, cacheKey, cachePath };
+}
+
+export function writeScanCacheEntry({
+  rootDir,
+  identity,
+  metrics
+}: {
+  identity: DuplicateCodeCacheIdentity;
+  metrics: readonly DuplicateCodeFragment[];
+  rootDir: string;
+}): { cacheKey: string; cachePath: string } {
+  const cacheKey = buildScanCacheKey(identity);
+  const cachePath = getScanCachePath(rootDir, cacheKey);
+  const payload: ScanCachePayload = {
+    scanCacheVersion: SCAN_CACHE_VERSION,
+    cacheKey,
+    toolName: identity.toolName,
+    toolVersion: identity.toolVersion,
+    scannerConfiguration: identity.scannerConfiguration,
+    configVersion: identity.configVersion,
+    commitSha: identity.commitSha,
+    inputFingerprint: identity.inputFingerprint,
+    metrics,
+    createdAt: new Date().toISOString()
+  };
+
+  writeJsonFile({ filePath: cachePath, value: payload });
+  return { cacheKey, cachePath };
+}

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

@@ -0,0 +1,50 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import { DUPLICATE_DETECTION_CHECK_DEFINITION, executeDuplicateDetection } from "./execution.ts";
+import { parseDuplicateDetectionData } from "./final-data.ts";
+import type { DuplicateDetectionOptions, ResolvedDuplicateDetectionOptions } from "./options.ts";
+import { resolveDuplicateDetectionOptions } from "./options-resolution.ts";
+import { validResolvedDuplicateDetectionOptions } from "./options-validation.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 function duplicateDetection(
+  options: DuplicateDetectionOptions = {}
+): TypedCheckWithOptions<
+  "duplicate-detection",
+  ResolvedDuplicateDetectionOptions,
+  typeof parseDuplicateDetectionData
+> {
+  const resolvedOptions = resolveDuplicateDetectionOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError(
+      "duplicateDetection options are invalid; use the documented closed constructor policy"
+    );
+  }
+  return defineCheck({
+    ...DUPLICATE_DETECTION_CHECK_DEFINITION,
+    execution: executeDuplicateDetection,
+    parseData: parseDuplicateDetectionData,
+    preflight: (preparedOptions) =>
+      validResolvedDuplicateDetectionOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "duplicateDetection options are invalid; recreate the Check with duplicateDetection(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}

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

@@ -0,0 +1,168 @@
+import { resolve } from "node:path";
+
+import type { CheckExecutionContext, CheckResult } from "../../check/check.ts";
+import { collectProjectFileSets, requireProjectFileSet } from "../project-files/collection.ts";
+import { fingerprintProjectFiles } from "../project-files/file-fingerprint.ts";
+import { settleFindings } from "../code-quality-findings/policy.ts";
+import { getGitSha } from "./project-revision.ts";
+import { measureDuplicateDetection, type DuplicateMeasurementResult } from "./measurement.ts";
+import type {
+  DuplicateDetectionAreaInput,
+  DuplicateDetectionExactInputSet
+} from "./measurement-model.ts";
+import type { ResolvedDuplicateDetectionOptions } from "./options.ts";
+import { validResolvedDuplicateDetectionOptions } from "./options-validation.ts";
+import { buildDuplicateRecordCandidates } from "./records.ts";
+import type { DuplicateDetectionFinalData } from "./final-data.ts";
+
+export const DUPLICATE_DETECTION_CHECK_DEFINITION = {
+  checkId: "duplicate-detection",
+  displayName: "Duplicate detection"
+} as const;
+
+/** `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 async function executeDuplicateDetection(
+  context: CheckExecutionContext<ResolvedDuplicateDetectionOptions>
+): Promise<CheckResult<DuplicateDetectionFinalData>> {
+  if (!validResolvedDuplicateDetectionOptions(context.options))
+    return unavailable("invalid-options");
+
+  let exactInput: DuplicateDetectionExactInputSet;
+  try {
+    exactInput = prepareExactInputSet(context.project.root, context.options);
+  } catch {
+    return unavailable("source-unavailable");
+  }
+  if (exactInput.approvedExactPaths.length < 2) {
+    return Object.freeze({ status: "not-applicable", reason: { code: "no-eligible-input" } });
+  }
+  const measurement = await measureDuplicateDetection({
+    cache: context.options.cache,
+    dependency: context.options.scanner,
+    exactInput
+  });
+  if (measurement.kind !== "complete") return directMeasurementFailure(measurement);
+  const candidates = buildDuplicateRecordCandidates(
+    measurement.fragments,
+    context.options.codeAreas
+  );
+  if (candidates === undefined) return unavailable("external-result-invalid");
+  for (const candidate of candidates) {
+    context.records.report({ id: candidate.id }, candidate.data);
+  }
+  return settleFindings(
+    candidates.map((candidate) => ({ actionable: true, blocking: candidate.data.blocking }))
+  );
+}
+
+function prepareExactInputSet(
+  rootDir: string,
+  options: ResolvedDuplicateDetectionOptions
+): DuplicateDetectionExactInputSet {
+  const areas = collectAreaInputs(rootDir, options.codeAreas);
+  const approvedExactPaths = uniqueSorted(areas.flatMap((area) => area.approvedExactPaths));
+  const inputFingerprint = fingerprintProjectFiles(rootDir, approvedExactPaths);
+  return Object.freeze({
+    approvedExactPaths: Object.freeze(approvedExactPaths),
+    areas,
+    cacheRootDir: resolve(rootDir, options.cache.directory),
+    commitSha: getGitSha(rootDir),
+    inputFingerprint: Object.freeze({
+      ...inputFingerprint,
+      fileList: Object.freeze([...inputFingerprint.fileList])
+    }),
+    rootDir
+  });
+}
+
+function collectAreaInputs(
+  rootDir: string,
+  codeAreas: ResolvedDuplicateDetectionOptions["codeAreas"]
+): readonly DuplicateDetectionAreaInput[] {
+  const areas: DuplicateDetectionAreaInput[] = [];
+  const orderedPolicies = Object.entries(codeAreas).sort(([left], [right]) =>
+    compareText(left, right)
+  );
+  const filesByArea = collectProjectFileSets(
+    rootDir,
+    Object.fromEntries(orderedPolicies.map(([areaId, policy]) => [areaId, policy.files]))
+  );
+  for (const [codeArea, policy] of orderedPolicies) {
+    const approvedExactPaths = requireProjectFileSet(filesByArea, codeArea);
+    if (approvedExactPaths.length === 0) continue;
+    areas.push(
+      Object.freeze({
+        approvedExactPaths: Object.freeze(approvedExactPaths),
+        codeArea,
+        minimumLines: policy.minimumLines,
+        minimumTokens: policy.minimumTokens
+      })
+    );
+  }
+  return Object.freeze(areas);
+}
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort(compareText);
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function directMeasurementFailure(
+  measurement: Exclude<DuplicateMeasurementResult, { kind: "complete" }>
+): CheckResult<DuplicateDetectionFinalData> {
+  switch (measurement.kind) {
+    case "cache-write-failed":
+      return unavailable("cache-write-failed");
+    case "execution-failed":
+      return unavailable("external-execution-failed");
+    case "invalid-result":
+      return unavailable("external-result-invalid");
+    case "unavailable":
+      return unavailable("external-dependency-unavailable");
+  }
+  const exhaustiveMeasurement: never = measurement;
+  return exhaustiveMeasurement;
+}
+
+function unavailable(
+  code: DuplicateDetectionUnavailableReasonCode
+): CheckResult<DuplicateDetectionFinalData> {
+  return Object.freeze({
+    status: "unavailable",
+    reason: { code },
+    messages: Object.freeze([
+      Object.freeze({ code, level: "error" as const, message: unavailableMessage(code) })
+    ])
+  });
+}
+
+function unavailableMessage(code: DuplicateDetectionUnavailableReasonCode): string {
+  switch (code) {
+    case "invalid-options":
+      return "duplicateDetection options are invalid; recreate the Check with duplicateDetection(options) or restore its complete resolved options.";
+    case "source-unavailable":
+      return "Duplicate detection could not collect its configured project files; check the project root, file permissions, and selected file source.";
+    case "external-dependency-unavailable":
+      return "The configured jscpd command is unavailable or incompatible; restore the package dependency or configure a compatible executable.";
+    case "external-execution-failed":
+      return "jscpd did not complete successfully; run the configured command directly and inspect its environment.";
+    case "external-result-invalid":
+      return "jscpd output could not form a trusted complete result; check command and report compatibility.";
+    case "cache-write-failed":
+      return "Duplicate detection completed scanning but could not write its cache; check the configured cache directory permissions.";
+  }
+}

package/src/package-checks/duplicate-detection/final-data.ts

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

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

@@ -0,0 +1,137 @@
+import { runProcess } from "../../host-environment/process/command.ts";
+import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
+import { isMissingExplicitCommand } from "./command-path.ts";
+import { isPackageJscpdCommand, resolveJscpdCommand } from "./command-resolution.ts";
+import { parseJscpdVersionOutput } from "./scanner.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";
+
+type ToolCommandResult = Awaited<ReturnType<typeof runProcess>>;
+
+export async function checkJscpd(
+  rootDir: string,
+  dependency: ResolvedDuplicateDetectionScannerOptions
+): Promise<JscpdAvailability> {
+  const resolved = resolveJscpdCommand(dependency.command);
+  if (resolved.kind === "unavailable") {
+    return unavailableJscpd(resolved.error, "tool-unavailable", dependency);
+  }
+  if (isMissingExplicitCommand(resolved.command.executable)) {
+    return unavailableJscpd("jscpd dependency binary unavailable", "tool-unavailable", dependency);
+  }
+
+  try {
+    const result = await runProcess({
+      args: [...resolved.command.versionArguments],
+      command: resolved.command.executable,
+      cwd: rootDir
+    });
+    return availabilityFromVersionResult(result, dependency);
+  } catch (error: unknown) {
+    return error instanceof Error
+      ? processErrorAvailability(error, dependency)
+      : unavailableJscpd("unknown error", "execution-error", dependency);
+  }
+}
+
+function availabilityFromVersionResult(
+  result: ToolCommandResult,
+  dependency: ResolvedDuplicateDetectionScannerOptions
+): JscpdAvailability {
+  if (result.error) return processErrorAvailability(result.error, dependency);
+  const output = commandOutput(result);
+  if (result.status !== 0) return failedVersionAvailability(result, output, dependency);
+  const version = parseJscpdVersionOutput(output);
+  if (version === null) return unrecognizedVersionAvailability(dependency);
+  return {
+    name: "jscpd",
+    available: true,
+    version,
+    error: null,
+    source: jscpdSource(dependency),
+    reason: null
+  };
+}
+
+function failedVersionAvailability(
+  result: ToolCommandResult,
+  output: string,
+  dependency: ResolvedDuplicateDetectionScannerOptions
+): JscpdAvailability {
+  const detail = output ? `: ${output}` : "";
+  return unavailableJscpd(
+    `jscpd --version failed, ${processTermination(result)}${detail}`,
+    "execution-error",
+    dependency
+  );
+}
+
+function unrecognizedVersionAvailability(
+  dependency: ResolvedDuplicateDetectionScannerOptions
+): JscpdAvailability {
+  return unavailableJscpd(
+    "jscpd --version returned unrecognized output",
+    "execution-error",
+    dependency
+  );
+}
+
+function processErrorAvailability(
+  error: Error,
+  dependency: ResolvedDuplicateDetectionScannerOptions
+): JscpdAvailability {
+  const isMissingTool = (error as NodeJS.ErrnoException).code === "ENOENT";
+  return unavailableJscpd(
+    isMissingTool ? "jscpd dependency binary unavailable" : `jscpd version error: ${error.message}`,
+    isMissingTool ? "tool-unavailable" : "execution-error",
+    dependency
+  );
+}
+
+function unavailableJscpd(
+  error: string,
+  reason: Exclude<JscpdAvailability["reason"], null>,
+  dependency: ResolvedDuplicateDetectionScannerOptions
+): JscpdAvailability {
+  return {
+    name: "jscpd",
+    available: false,
+    version: null,
+    error,
+    source: jscpdSource(dependency),
+    reason
+  };
+}
+
+function jscpdSource(dependency: ResolvedDuplicateDetectionScannerOptions): JscpdSource {
+  return isPackageJscpdCommand(dependency.command) ? "package dependency" : "custom command";
+}
+
+function commandOutput(result: ToolCommandResult): string {
+  return (result.stdout || "").trim() || (result.stderr || "").trim();
+}
+
+function processTermination(result: ToolCommandResult): string {
+  return typeof result.status === "number"
+    ? `exit ${result.status}`
+    : `signal ${result.signal || "unknown"}`;
+}

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

@@ -0,0 +1,8 @@
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+export function isMissingExplicitCommand(command: string): boolean {
+  return (
+    (isAbsolute(command) || command.includes("/") || command.includes("\\")) && !existsSync(command)
+  );
+}

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

@@ -0,0 +1,112 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isNonArrayRecord } from "../../../data-boundary/value-shapes.ts";
+import type { DuplicateDetectionScannerCommand } from "../options.ts";
+
+const JSCPD_BIN_NAME = "jscpd";
+const JSCPD_PACKAGE_NAME = "jscpd";
+
+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 const DEFAULT_JSCPD_COMMAND: DuplicateDetectionScannerCommand = Object.freeze({
+  kind: "package"
+});
+
+export function isPackageJscpdCommand(
+  command: DuplicateDetectionScannerCommand
+): command is Extract<DuplicateDetectionScannerCommand, { readonly kind: "package" }> {
+  return command.kind === "package";
+}
+
+export function resolveJscpdCommand(
+  command: DuplicateDetectionScannerCommand
+): ResolvedJscpdCommand {
+  if (command.kind === "custom") {
+    return Object.freeze({
+      command: Object.freeze({
+        executable: command.executable,
+        scanPrefixArguments: Object.freeze([]),
+        versionArguments: Object.freeze(["--version"])
+      }),
+      kind: "resolved"
+    });
+  }
+
+  const binTarget = installedJscpdBinTarget();
+  if (binTarget === null) {
+    return Object.freeze({
+      error: "candidate jscpd package manifest or declared bin target is unavailable",
+      kind: "unavailable"
+    });
+  }
+
+  return Object.freeze({
+    command: Object.freeze({
+      executable: process.execPath,
+      scanPrefixArguments: Object.freeze([binTarget]),
+      versionArguments: Object.freeze([binTarget, "--version"])
+    }),
+    kind: "resolved"
+  });
+}
+
+export function readJscpdBinTarget(packageManifestPath: string): string | null {
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(packageManifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+
+  const binTarget = declaredJscpdBinTarget(manifest);
+  if (binTarget === null || isAbsolute(binTarget)) return null;
+
+  const packageDirectory = dirname(packageManifestPath);
+  const resolvedTarget = resolve(packageDirectory, binTarget);
+  const targetRelativePath = relative(packageDirectory, resolvedTarget);
+  if (
+    targetRelativePath === "" ||
+    targetRelativePath === ".." ||
+    targetRelativePath.startsWith("../") ||
+    targetRelativePath.startsWith("..\\") ||
+    !existsSync(resolvedTarget)
+  ) {
+    return null;
+  }
+
+  return resolvedTarget;
+}
+
+function installedJscpdBinTarget(): string | null {
+  try {
+    const packageManifestPath = fileURLToPath(
+      import.meta.resolve(`${JSCPD_PACKAGE_NAME}/package.json`)
+    );
+    return readJscpdBinTarget(packageManifestPath);
+  } catch {
+    return null;
+  }
+}
+
+function declaredJscpdBinTarget(manifest: unknown): string | null {
+  if (!isNonArrayRecord(manifest)) return null;
+  const bin = manifest.bin;
+  if (typeof bin === "string") return bin;
+  if (!isNonArrayRecord(bin)) return null;
+  const target = bin[JSCPD_BIN_NAME];
+  return typeof target === "string" ? target : null;
+}