@zxyycom/vibe-check 0.0.1

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

@@ -0,0 +1,162 @@
+import {
+  hasRequiredAndOptionalRecordKeys,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import {
+  resolveProjectFileSelection,
+  snapshotDefaultProjectFileSelection
+} from "../project-files/configuration.ts";
+import {
+  DEFAULT_FINDING_POLICY,
+  resolveFindingPolicy,
+  type FindingPolicy
+} from "../code-quality-findings/policy.ts";
+import { DEFAULT_JSCPD_COMMAND } from "./jscpd/command-resolution.ts";
+import type {
+  DuplicateDetectionScannerCommand,
+  ResolvedDuplicateDetectionCodeAreaOptions,
+  ResolvedDuplicateDetectionOptions,
+  ResolvedDuplicateDetectionScannerOptions
+} from "./options.ts";
+import { validResolvedDuplicateDetectionOptions } from "./options-validation.ts";
+
+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"]
+  });
+  if (input === undefined) return undefined;
+
+  const cache = resolveCache(input.cache);
+  const findingPolicy = resolveFindingPolicy(input.findingPolicy, DEFAULT_FINDING_POLICY);
+  if (findingPolicy === undefined) return undefined;
+  const codeAreas = resolveCodeAreas(input.codeAreas, findingPolicy);
+  const scanner = resolveScanner(input.scanner);
+  if (cache === undefined || codeAreas === undefined || scanner === undefined) return undefined;
+
+  const options = Object.freeze({ cache, codeAreas, scanner });
+  return validResolvedDuplicateDetectionOptions(options) ? options : undefined;
+}
+
+function resolveCache(value: unknown): ResolvedDuplicateDetectionOptions["cache"] | undefined {
+  if (value === undefined) {
+    return Object.freeze({ directory: DEFAULT_CACHE_DIRECTORY, enabled: true });
+  }
+  const cache = snapshotPolicyRecord(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;
+  return Object.freeze({ directory, enabled });
+}
+
+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));
+}
+
+function defaultCodeArea(findingPolicy: FindingPolicy): ResolvedDuplicateDetectionCodeAreaOptions {
+  return Object.freeze({
+    files: snapshotDefaultProjectFileSelection(),
+    findingPolicy,
+    minimumLines: DEFAULT_MINIMUM_LINES,
+    minimumTokens: DEFAULT_MINIMUM_TOKENS
+  });
+}
+
+function resolveCodeArea(
+  value: unknown,
+  defaultFindingPolicy: FindingPolicy
+): ResolvedDuplicateDetectionCodeAreaOptions | undefined {
+  const area = snapshotPolicyRecord(value, {
+    optional: ["findingPolicy", "minimumLines", "minimumTokens"],
+    required: ["files"]
+  });
+  if (area === undefined) return undefined;
+  const files = resolveProjectFileSelection(area.files);
+  const findingPolicy = resolveFindingPolicy(area.findingPolicy, defaultFindingPolicy);
+  const minimumLines = area.minimumLines ?? DEFAULT_MINIMUM_LINES;
+  const minimumTokens = area.minimumTokens ?? DEFAULT_MINIMUM_TOKENS;
+  if (
+    files === undefined ||
+    findingPolicy === undefined ||
+    !positiveSafeInteger(minimumLines) ||
+    !positiveSafeInteger(minimumTokens)
+  ) {
+    return undefined;
+  }
+  return Object.freeze({ files, findingPolicy, minimumLines, minimumTokens });
+}
+
+function resolveScanner(value: unknown): ResolvedDuplicateDetectionScannerOptions | undefined {
+  if (value === undefined) return Object.freeze({ command: DEFAULT_JSCPD_COMMAND });
+  const scanner = snapshotPolicyRecord(value, { optional: ["command"] });
+  if (scanner === undefined) return undefined;
+  const command = resolveScannerCommand(scanner.command);
+  return command === undefined ? undefined : Object.freeze({ command });
+}
+
+function resolveScannerCommand(value: unknown): DuplicateDetectionScannerCommand | undefined {
+  if (value === undefined) return DEFAULT_JSCPD_COMMAND;
+  const command = snapshotClosedRecord(value);
+  if (command?.kind === "package") {
+    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)) {
+    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

@@ -0,0 +1,75 @@
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.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;
+}
+
+export function validResolvedDuplicateDetectionOptions(value: object): boolean {
+  const options = exactRecord(value, ["cache", "codeAreas", "scanner"]);
+  return (
+    options !== undefined &&
+    validDuplicateCache(options.cache) &&
+    validDuplicateCodeAreas(options.codeAreas) &&
+    validDuplicateDetectionScanner(options.scanner)
+  );
+}
+
+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, [
+      "files",
+      "findingPolicy",
+      "minimumLines",
+      "minimumTokens"
+    ]);
+    return (
+      nonEmptyString(areaId) &&
+      area !== undefined &&
+      validProjectFileSelection(area.files) &&
+      validFindingPolicy(area.findingPolicy) &&
+      positiveSafeInteger(area.minimumLines) &&
+      positiveSafeInteger(area.minimumTokens)
+    );
+  });
+}
+
+function validDuplicateDetectionScanner(value: unknown): boolean {
+  const scanner = exactRecord(value, ["command"]);
+  return scanner !== undefined && validJscpdCommand(scanner.command);
+}
+
+function validJscpdCommand(value: unknown): boolean {
+  const record = snapshotClosedRecord(value);
+  if (record?.kind === "package") {
+    return Object.keys(record).length === 1;
+  }
+  const command = exactRecord(value, ["executable", "kind"]);
+  return command?.kind === "custom" && nonEmptyString(command.executable);
+}
+
+function validDuplicateCache(value: unknown): boolean {
+  const cache = exactRecord(value, ["directory", "enabled"]);
+  return (
+    cache !== undefined && nonEmptyString(cache.directory) && typeof cache.enabled === "boolean"
+  );
+}

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

@@ -0,0 +1,72 @@
+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/src/package-checks/duplicate-detection/project-revision.ts

@@ -0,0 +1,5 @@
+import { gitHeadSha } from "../host-environment/git.ts";
+
+export function getGitSha(cwd: string): string {
+  return gitHeadSha(cwd) ?? "unknown";
+}

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

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+
+import { canonicalJsonBytes } from "../../data-boundary/canonical-data.ts";
+import { isBlockingFinding, type FindingPolicy } from "../code-quality-findings/policy.ts";
+import type { DuplicateCodeFragment, DuplicateCodeLocation } 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 function buildDuplicateRecordCandidates(
+  fragments: readonly DuplicateCodeFragment[],
+  codeAreas: ResolvedDuplicateDetectionOptions["codeAreas"]
+): readonly DuplicateRecordCandidate[] | undefined {
+  const ids = duplicateIdsInOrder(fragments);
+  if (ids === undefined) return undefined;
+
+  const candidates: DuplicateRecordCandidate[] = [];
+  for (const [index, fragment] of fragments.entries()) {
+    const candidate = createDuplicateRecordCandidate(fragment, ids[index], codeAreas);
+    if (candidate === undefined) return undefined;
+    candidates.push(candidate);
+  }
+  candidates.sort((left, right) => compareText(left.id, right.id));
+  return Object.freeze(candidates);
+}
+
+function createDuplicateRecordCandidate(
+  fragment: DuplicateCodeFragment,
+  id: string | undefined,
+  configuredAreas: ResolvedDuplicateDetectionOptions["codeAreas"]
+): DuplicateRecordCandidate | undefined {
+  if (!isValidDuplicateFragment(fragment) || id === undefined) return undefined;
+
+  const locations = sortedLocations(fragment.locations);
+  const codeAreas = uniqueSorted(fragment.codeAreas);
+  if (codeAreas.length === 0 || !sameStrings(codeAreas, fragment.codeAreas)) return undefined;
+  const findingPolicies: FindingPolicy[] = [];
+  for (const areaId of codeAreas) {
+    const area = configuredAreas[areaId];
+    if (area === undefined) return undefined;
+    findingPolicies.push(area.findingPolicy);
+  }
+
+  return Object.freeze({
+    id,
+    data: Object.freeze({
+      blocking: isBlockingFinding(findingPolicies),
+      codeAreas: Object.freeze(codeAreas),
+      lineCount: fragment.lineCount,
+      locations: Object.freeze(
+        locations.map((location) =>
+          Object.freeze({
+            endLine: location.endLine,
+            path: location.path,
+            startLine: location.startLine
+          })
+        )
+      ),
+      metric: "duplicate-tokens",
+      tokenCount: fragment.tokenCount
+    })
+  });
+}
+
+export function isValidDuplicateFragment(fragment: DuplicateCodeFragment): boolean {
+  return (
+    hasValidFragmentMeasurements(fragment) &&
+    Array.isArray(fragment.locations) &&
+    fragment.locations.length >= 2 &&
+    fragment.locations.every(isValidLocation) &&
+    Array.isArray(fragment.codeAreas) &&
+    fragment.codeAreas.every(nonEmptyString)
+  );
+}
+
+function hasValidFragmentMeasurements(fragment: DuplicateCodeFragment): boolean {
+  return (
+    nonNegativeSafeInteger(fragment.id) &&
+    nonNegativeSafeInteger(fragment.lineCount) &&
+    nonNegativeSafeInteger(fragment.tokenCount)
+  );
+}
+
+function nonNegativeSafeInteger(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+function isValidLocation(location: DuplicateCodeLocation): boolean {
+  const validPath = typeof location.path === "string" && location.path.length > 0;
+  const validLines =
+    Number.isSafeInteger(location.startLine) &&
+    location.startLine >= 1 &&
+    Number.isSafeInteger(location.endLine) &&
+    location.endLine >= location.startLine;
+  return validPath && validLines;
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function sameStrings(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function duplicateIdsInOrder(
+  fragments: readonly DuplicateCodeFragment[]
+): readonly string[] | undefined {
+  const occurrences = new Map<string, number>();
+  const ids: string[] = [];
+  for (const fragment of fragments) {
+    if (!isValidDuplicateFragment(fragment)) return undefined;
+    const fingerprint = duplicateFingerprint(fragment);
+    const occurrence = (occurrences.get(fingerprint) ?? 0) + 1;
+    occurrences.set(fingerprint, occurrence);
+    ids.push(`duplicate-fragment/v1/sha256:${fingerprint}/occurrence:${occurrence}`);
+  }
+  return Object.freeze(ids);
+}
+
+function duplicateFingerprint(fragment: DuplicateCodeFragment): string {
+  return createHash("sha256")
+    .update(
+      canonicalJsonBytes({
+        lineCount: fragment.lineCount,
+        paths: uniqueSorted(fragment.locations.map((location) => location.path)),
+        tokenCount: fragment.tokenCount
+      })
+    )
+    .digest("hex");
+}
+
+function sortedLocations(locations: readonly DuplicateCodeLocation[]): DuplicateCodeLocation[] {
+  return [...locations].sort((left, right) =>
+    compareText(locationSortKey(left), locationSortKey(right))
+  );
+}
+
+function locationSortKey(location: DuplicateCodeLocation): string {
+  const startLine = String(location.startLine).padStart(12, "0");
+  const endLine = String(location.endLine).padStart(12, "0");
+  return `${location.path}\u0000${startLine}\u0000${endLine}`;
+}
+
+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;
+}

package/src/package-checks/file-metrics/constructor.ts

@@ -0,0 +1,46 @@
+import { defineCheck, type TypedCheckWithOptions } from "../../check/check.ts";
+import { FILE_METRICS_CHECK_DEFINITION, executeFileMetrics } from "./execution.ts";
+import { parseFileMetricsData } from "./final-data.ts";
+import type { FileMetricsOptions, ResolvedFileMetricsOptions } from "./options.ts";
+import { resolveFileMetricsOptions } from "./options-resolution.ts";
+import { isValidResolvedFileMetricsOptions } from "./options-validation.ts";
+
+/**
+ * 使用可省略的区域、代码行与 scanner policy 构造一个完整 file-metrics Check。
+ *
+ * @param options - 省略字段由 package 补齐；显式 files 数组作为对应字段的完整替换值。
+ * @returns 固定 `file-metrics` identity、完整冻结 options、preflight 与 execution。
+ * @throws {TypeError} input 含未知字段、空 area、非法代码行 policy、非法 waiver 或空 executable 时抛出。
+ */
+export function fileMetrics(
+  options: FileMetricsOptions = {}
+): TypedCheckWithOptions<"file-metrics", ResolvedFileMetricsOptions, typeof parseFileMetricsData> {
+  const resolvedOptions = resolveFileMetricsOptions(options);
+  if (resolvedOptions === undefined) {
+    throw new TypeError(
+      "fileMetrics options must match the documented closed { codeAreas?, findingPolicy?, findingWaivers?, scanner? } constructor policy"
+    );
+  }
+  return defineCheck({
+    ...FILE_METRICS_CHECK_DEFINITION,
+    execution: executeFileMetrics,
+    parseData: parseFileMetricsData,
+    preflight: (preparedOptions) =>
+      isValidResolvedFileMetricsOptions(preparedOptions)
+        ? { status: "success", preparedOptions }
+        : {
+            status: "failure",
+            action: "block",
+            reason: { code: "invalid-options" },
+            messages: [
+              {
+                code: "invalid-options",
+                level: "error",
+                message:
+                  "fileMetrics options are invalid; recreate the Check with fileMetrics(options) or restore its complete resolved options."
+              }
+            ]
+          },
+    options: resolvedOptions
+  });
+}