@zxyycom/vibe-check 0.0.1

package/src/machine-output/v4/schema.ts

@@ -0,0 +1,97 @@
+import Type from "typebox";
+
+import {
+  MACHINE_RECORD_V4_IDENTITY,
+  MACHINE_RECORD_V4_SCHEMA_ID,
+  MACHINE_RUN_V4_IDENTITY,
+  MACHINE_RUN_V4_SCHEMA_ID,
+  MACHINE_V4_TIMESTAMP_PATTERN
+} from "./schema-identities.ts";
+
+const NonEmptyString = Type.String({ minLength: 1 });
+const NonEmptyCheckId = Type.String({ minLength: 1 });
+const CanonicalJsonObject = Type.Record(Type.String(), Type.Any());
+const NotApplicableReason = Type.Object({ code: NonEmptyString }, { additionalProperties: false });
+const UnavailableReason = Type.Object(
+  {
+    checkIds: Type.Optional(Type.Array(NonEmptyCheckId, { minItems: 1 })),
+    code: NonEmptyString
+  },
+  { additionalProperties: false }
+);
+
+const CheckOutcomeSchema = Type.Union([
+  Type.Object(
+    { data: CanonicalJsonObject, status: Type.Literal("passed") },
+    { additionalProperties: false }
+  ),
+  Type.Object(
+    { data: CanonicalJsonObject, status: Type.Literal("failed") },
+    { additionalProperties: false }
+  ),
+  Type.Object(
+    { reason: Type.Optional(NotApplicableReason), status: Type.Literal("not-applicable") },
+    { additionalProperties: false }
+  ),
+  Type.Object(
+    { reason: UnavailableReason, status: Type.Literal("unavailable") },
+    { additionalProperties: false }
+  )
+]);
+
+const PublishedCheckSchema = Type.Object(
+  {
+    checkId: NonEmptyCheckId,
+    displayName: NonEmptyString,
+    outcome: CheckOutcomeSchema
+  },
+  { additionalProperties: false }
+);
+
+export const MACHINE_RECORD_V4_SCHEMA = Type.Object(
+  {
+    checkId: NonEmptyCheckId,
+    data: CanonicalJsonObject,
+    id: NonEmptyString,
+    schemaVersion: Type.Literal(MACHINE_RECORD_V4_IDENTITY)
+  },
+  {
+    $id: MACHINE_RECORD_V4_SCHEMA_ID,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    additionalProperties: false,
+    title: "Vibe Check machine record v4"
+  }
+);
+
+export const MACHINE_RUN_V4_SCHEMA = Type.Object(
+  {
+    checks: Type.Array(PublishedCheckSchema),
+    invocation: Type.Object(
+      {
+        invocationId: NonEmptyString,
+        projectRoot: Type.Literal("."),
+        timestamp: Type.String({ pattern: MACHINE_V4_TIMESTAMP_PATTERN })
+      },
+      { additionalProperties: false }
+    ),
+    recordsFingerprint: Type.String({
+      pattern: "^check-record/v2/records/sha256:[a-f0-9]{64}$"
+    }),
+    schemaVersion: Type.Literal(MACHINE_RUN_V4_IDENTITY)
+  },
+  {
+    $id: MACHINE_RUN_V4_SCHEMA_ID,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    additionalProperties: false,
+    title: "Vibe Check machine 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>>;

package/src/machine-output/v4/serializers.ts

@@ -0,0 +1,18 @@
+import type { MachinePublicationV4 } from "./projection.ts";
+
+export interface MachinePublicationCandidatesV4 {
+  readonly recordsNdjson: string;
+  readonly runJson: string;
+}
+
+export function serializeMachinePublicationV4(
+  publication: MachinePublicationV4
+): MachinePublicationCandidatesV4 {
+  return Object.freeze({
+    runJson: JSON.stringify(publication.run, null, 2),
+    recordsNdjson:
+      publication.records.length === 0
+        ? ""
+        : `${publication.records.map((record) => JSON.stringify(record)).join("\n")}\n`
+  });
+}

package/src/machine-output/v4/validation-result.ts

@@ -0,0 +1,59 @@
+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 function validationSuccess<Value>(value: Value): { ok: true; value: Value } {
+  return { ok: true, value };
+}
+
+export function validationFailure(
+  diagnostic: MachinePublicationValidationDiagnostic
+): ValidationFailure {
+  return { ok: false, diagnostic };
+}
+
+export function setInvariantFailure(
+  relationship: MachinePublicationSetRelationship,
+  logicalArtifact: MachinePublicationValidationDiagnostic["logicalArtifact"],
+  message: string,
+  index?: number
+): ValidationFailure {
+  return validationFailure({
+    category: "set-invariant",
+    ...(index === undefined ? {} : { index, line: index + 1 }),
+    logicalArtifact,
+    message,
+    relationship
+  });
+}

package/src/machine-output/v4/validation.ts

@@ -0,0 +1,166 @@
+import Value from "typebox/value";
+
+import type { MachinePublicationV4 } from "./projection.ts";
+import { freezePublicationValue } from "./freeze-publication-value.ts";
+import { validatePublicationInvariants } from "./publication-invariants.ts";
+import {
+  MACHINE_RECORD_V4_SCHEMA,
+  MACHINE_RUN_V4_SCHEMA,
+  type MachineRecordV4,
+  type MachineRunV4
+} from "./schema.ts";
+import {
+  validationFailure,
+  validationSuccess,
+  type MachinePublicationValidationDiagnostic,
+  type MachinePublicationValidationResult
+} from "./validation-result.ts";
+
+export type {
+  MachinePublicationSetRelationship,
+  MachinePublicationValidationCategory,
+  MachinePublicationValidationDiagnostic,
+  MachinePublicationValidationResult
+} from "./validation-result.ts";
+
+type Parsed<Value> = Readonly<
+  { ok: false; diagnostic: MachinePublicationValidationDiagnostic } | { ok: true; value: Value }
+>;
+
+export function validateMachinePublicationSetV4(
+  input: Readonly<{
+    recordsNdjson: Uint8Array;
+    runJson: Uint8Array;
+  }>
+): MachinePublicationValidationResult {
+  const runResult = parseRun(input.runJson);
+  if (!runResult.ok) return runResult;
+  const recordsResult = parseRecords(input.recordsNdjson);
+  if (!recordsResult.ok) return recordsResult;
+  const invariant = validatePublicationInvariants(runResult.value, recordsResult.value);
+  return (
+    invariant ??
+    validationSuccess(
+      Object.freeze({
+        run: freezePublicationValue(runResult.value),
+        records: freezePublicationValue(recordsResult.value)
+      }) satisfies MachinePublicationV4
+    )
+  );
+}
+
+function parseRun(bytes: Uint8Array): Parsed<MachineRunV4> {
+  const decoded = decode(bytes, "run.json");
+  if (!decoded.ok) return decoded;
+  const parsed = parseJson(decoded.value, {
+    logicalArtifact: "run.json",
+    message: "Run artifact must contain exactly one JSON value."
+  });
+  if (!parsed.ok) return parsed;
+  if (!Value.Check(MACHINE_RUN_V4_SCHEMA, parsed.value)) {
+    const error = Value.Errors(MACHINE_RUN_V4_SCHEMA, parsed.value)[0];
+    return validationFailure({
+      category: "schema",
+      logicalArtifact: "run.json",
+      message: "Run artifact does not match the machine run v4 schema.",
+      pointer: error?.instancePath ?? ""
+    });
+  }
+  return validationSuccess(parsed.value);
+}
+
+function parseRecords(bytes: Uint8Array): Parsed<MachineRecordV4[]> {
+  if (bytes.byteLength === 0) return validationSuccess([]);
+  if (bytes[bytes.byteLength - 1] !== 0x0a) {
+    return validationFailure({
+      category: "framing",
+      line: countLf(bytes) + 1,
+      logicalArtifact: "records.ndjson",
+      message: "Non-empty record stream must end with exactly one LF."
+    });
+  }
+  const decoded = decode(bytes, "records.ndjson");
+  if (!decoded.ok) return decoded;
+  return parseRecordSegments(decoded.value.slice(0, -1).split("\n"));
+}
+
+function parseRecordSegments(segments: readonly string[]): Parsed<MachineRecordV4[]> {
+  const records: MachineRecordV4[] = [];
+  for (const [index, segment] of segments.entries()) {
+    const framingFailure = validateRecordSegment(segment, index);
+    if (framingFailure !== null) return framingFailure;
+    const parsed = parseJson(segment, {
+      index,
+      line: index + 1,
+      logicalArtifact: "records.ndjson",
+      message: "Record segment must contain exactly one JSON value."
+    });
+    if (!parsed.ok) return parsed;
+    if (!Value.Check(MACHINE_RECORD_V4_SCHEMA, parsed.value)) {
+      const error = Value.Errors(MACHINE_RECORD_V4_SCHEMA, parsed.value)[0];
+      return validationFailure({
+        category: "schema",
+        index,
+        line: index + 1,
+        logicalArtifact: "records.ndjson",
+        message: "Record does not match the machine record v4 schema.",
+        pointer: error?.instancePath ?? ""
+      });
+    }
+    records.push(parsed.value);
+  }
+  return validationSuccess(records);
+}
+
+function validateRecordSegment(
+  segment: string,
+  index: number
+): Extract<Parsed<never>, { ok: false }> | null {
+  if (segment.length > 0 && !/^[\t\r ]+$/.test(segment)) return null;
+  return validationFailure({
+    category: "framing",
+    index,
+    line: index + 1,
+    logicalArtifact: "records.ndjson",
+    message: "Record segment must not be empty or whitespace-only."
+  });
+}
+
+function parseJson(
+  text: string,
+  diagnostic: Omit<MachinePublicationValidationDiagnostic, "category">
+): Parsed<unknown> {
+  try {
+    return validationSuccess(JSON.parse(text) as unknown);
+  } catch {
+    return validationFailure({ category: "syntax", ...diagnostic });
+  }
+}
+
+function decode(
+  bytes: Uint8Array,
+  logicalArtifact: MachinePublicationValidationDiagnostic["logicalArtifact"]
+): Parsed<string> {
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+    return validationFailure({
+      category: "decoding",
+      logicalArtifact,
+      message: "Leading UTF-8 BOM is not allowed."
+    });
+  }
+  try {
+    return validationSuccess(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    return validationFailure({
+      category: "decoding",
+      logicalArtifact,
+      message: "Input is not valid UTF-8."
+    });
+  }
+}
+
+function countLf(bytes: Uint8Array): number {
+  let count = 0;
+  for (const byte of bytes) if (byte === 0x0a) count += 1;
+  return count;
+}

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

@@ -0,0 +1,85 @@
+import type { CheckMessage, CheckResult } from "../../check/check.ts";
+
+export const FINDING_POLICIES = Object.freeze(["blocking", "non-blocking"] as const);
+
+/** package-provided Check 用于结算 normal finding 的阻断策略。 */
+export type FindingPolicy = (typeof FINDING_POLICIES)[number];
+
+export const DEFAULT_FINDING_POLICY: FindingPolicy = "non-blocking";
+
+/** 三个代码质量 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 function resolveFindingPolicy(
+  value: unknown,
+  fallback: FindingPolicy = DEFAULT_FINDING_POLICY
+): FindingPolicy | undefined {
+  if (value === undefined) return fallback;
+  return FINDING_POLICIES.find((policy) => policy === value);
+}
+
+export function validFindingPolicy(value: unknown): value is FindingPolicy {
+  return FINDING_POLICIES.some((policy) => policy === value);
+}
+
+export function isBlockingFinding(policies: readonly FindingPolicy[]): boolean {
+  return policies.some((policy) => policy === "blocking");
+}
+
+export function settleFindings(
+  findings: readonly FindingSettlement[]
+): CheckResult<FindingSummary> {
+  const blockingFindingCount = findings.filter(
+    (finding) => finding.actionable && finding.blocking
+  ).length;
+  const findingCount = findings.length;
+  const actionableNonBlockingFindingCount = findings.filter(
+    (finding) => finding.actionable && !finding.blocking
+  ).length;
+  const messages = findingMessages({ actionableNonBlockingFindingCount, blockingFindingCount });
+  return Object.freeze({
+    status: blockingFindingCount > 0 ? "failed" : "passed",
+    data: Object.freeze({
+      blockingFindingCount,
+      findingCount
+    }),
+    ...(messages.length === 0 ? {} : { messages })
+  });
+}
+
+function findingMessages(
+  summary: Readonly<{
+    readonly actionableNonBlockingFindingCount: number;
+    readonly blockingFindingCount: number;
+  }>
+): readonly CheckMessage[] {
+  if (summary.blockingFindingCount > 0) {
+    return Object.freeze([
+      Object.freeze({
+        code: "blocking-findings",
+        level: "error",
+        message: `${summary.blockingFindingCount} blocking finding(s) require attention; inspect this Check's Records for affected paths and measurements, then update the code or policy.`
+      })
+    ]);
+  }
+  if (summary.actionableNonBlockingFindingCount > 0) {
+    return Object.freeze([
+      Object.freeze({
+        code: "non-blocking-findings",
+        level: "warning",
+        message: `${summary.actionableNonBlockingFindingCount} non-blocking finding(s) were recorded; inspect this Check's Records for affected paths and measurements, then update the code or policy.`
+      })
+    ]);
+  }
+  return Object.freeze([]);
+}

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

@@ -0,0 +1,103 @@
+import type {
+  DuplicateCodeFragment,
+  DuplicateCodeLocation,
+  DuplicateDetectionAreaInput
+} from "./measurement-model.ts";
+import { isValidDuplicateFragment } from "./records.ts";
+
+type PathPolicy = Readonly<{
+  codeArea: string;
+  minimumLines: number;
+  minimumTokens: number;
+}>;
+
+type AnnotatedFragment = Readonly<{
+  fragment: DuplicateCodeFragment;
+  requiredMinimumLines: number;
+  requiredMinimumTokens: number;
+}>;
+
+/** Restores every matching code area and applies the strictest involved policy. */
+export function applyDuplicateAreaPolicy(
+  fragments: readonly DuplicateCodeFragment[],
+  areas: readonly DuplicateDetectionAreaInput[]
+): readonly DuplicateCodeFragment[] | undefined {
+  const policiesByPath = buildPathPolicies(areas);
+  const accepted: DuplicateCodeFragment[] = [];
+  for (const fragment of fragments) {
+    if (!isValidDuplicateFragment(fragment)) return undefined;
+    const annotated = annotateFragment(fragment, policiesByPath);
+    if (annotated === undefined) return undefined;
+    if (
+      annotated.fragment.lineCount >= annotated.requiredMinimumLines &&
+      annotated.fragment.tokenCount >= annotated.requiredMinimumTokens
+    ) {
+      accepted.push(annotated.fragment);
+    }
+  }
+  return Object.freeze(accepted);
+}
+
+function buildPathPolicies(
+  areas: readonly DuplicateDetectionAreaInput[]
+): ReadonlyMap<string, readonly PathPolicy[]> {
+  const mutablePolicies = new Map<string, PathPolicy[]>();
+  for (const area of areas) {
+    for (const path of area.approvedExactPaths) {
+      const policies = mutablePolicies.get(path) ?? [];
+      policies.push(
+        Object.freeze({
+          codeArea: area.codeArea,
+          minimumLines: area.minimumLines,
+          minimumTokens: area.minimumTokens
+        })
+      );
+      mutablePolicies.set(path, policies);
+    }
+  }
+  return new Map(
+    Array.from(mutablePolicies, ([path, policies]) => [path, Object.freeze(policies)] as const)
+  );
+}
+
+function annotateFragment(
+  fragment: DuplicateCodeFragment,
+  policiesByPath: ReadonlyMap<string, readonly PathPolicy[]>
+): AnnotatedFragment | undefined {
+  const locations: DuplicateCodeLocation[] = [];
+  const involvedPolicies: PathPolicy[] = [];
+  for (const location of fragment.locations) {
+    const pathPolicies = policiesByPath.get(location.path);
+    if (pathPolicies === undefined || pathPolicies.length === 0) return undefined;
+    locations.push(
+      Object.freeze({
+        endLine: location.endLine,
+        path: location.path,
+        startLine: location.startLine
+      })
+    );
+    involvedPolicies.push(...pathPolicies);
+  }
+  if (involvedPolicies.length === 0) return undefined;
+
+  const annotatedFragment = Object.freeze({
+    ...fragment,
+    codeAreas: Object.freeze(uniqueSorted(involvedPolicies.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))
+  });
+}
+
+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/duplicate-detection/cache/cache-contract.ts

@@ -0,0 +1,49 @@
+import type { FileInputFingerprint } from "../../project-files/file-fingerprint.ts";
+import type { DuplicateCodeFragment } from "../measurement-model.ts";
+
+export 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/src/package-checks/duplicate-detection/cache/identity.ts

@@ -0,0 +1,61 @@
+import type { DuplicateDetectionExactInputSet } from "../measurement-model.ts";
+import type { ResolvedDuplicateDetectionScannerOptions } from "../options.ts";
+import { isPackageJscpdCommand } from "../jscpd/command-resolution.ts";
+import type {
+  DuplicateCodeCacheIdentity,
+  DuplicateScannerCacheConfiguration
+} from "./cache-contract.ts";
+
+const RAW_SCAN_CONFIGURATION_VERSION = "3";
+
+interface DuplicateScanCacheIdentityInput {
+  readonly dependency: ResolvedDuplicateDetectionScannerOptions;
+  readonly exactInput: DuplicateDetectionExactInputSet;
+  readonly minimumLines: number;
+  readonly minimumTokens: number;
+  readonly toolVersion: string;
+}
+
+export function createDuplicateScanCacheIdentity(
+  input: DuplicateScanCacheIdentityInput
+): DuplicateCodeCacheIdentity {
+  return Object.freeze({
+    toolName: "jscpd",
+    toolVersion: input.toolVersion,
+    scannerConfiguration: jscpdCacheConfiguration({
+      dependency: input.dependency,
+      minimumLines: input.minimumLines,
+      minimumTokens: input.minimumTokens
+    }),
+    configVersion: RAW_SCAN_CONFIGURATION_VERSION,
+    commitSha: input.exactInput.commitSha,
+    inputFingerprint: {
+      fileCount: input.exactInput.inputFingerprint.fileCount,
+      fileList: [...input.exactInput.inputFingerprint.fileList],
+      fingerprint: input.exactInput.inputFingerprint.fingerprint
+    }
+  });
+}
+
+export function jscpdCacheConfiguration(input: {
+  readonly dependency: ResolvedDuplicateDetectionScannerOptions;
+  readonly minimumLines: number;
+  readonly minimumTokens: number;
+}): DuplicateScannerCacheConfiguration {
+  const backend: DuplicateScannerCacheConfiguration["backend"] = isPackageJscpdCommand(
+    input.dependency.command
+  )
+    ? Object.freeze({ kind: "package" })
+    : Object.freeze({
+        executable: input.dependency.command.executable,
+        kind: "custom"
+      });
+  return Object.freeze({
+    backend,
+    minimumLines: input.minimumLines,
+    minimumTokens: input.minimumTokens,
+    reportedPathMode: "absolute",
+    reporter: "json",
+    workerPolicy: "tool-default"
+  });
+}

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

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+
+import { isNonArrayRecord } from "../../../data-boundary/value-shapes.ts";
+import { SCAN_CACHE_VERSION, type DuplicateCodeCacheIdentity } from "./cache-contract.ts";
+
+export function buildScanCacheKey(identity: DuplicateCodeCacheIdentity): string {
+  const keyInput = {
+    scan_cache_version: SCAN_CACHE_VERSION,
+    tool_name: identity.toolName,
+    tool_version: identity.toolVersion,
+    scanner_configuration: identity.scannerConfiguration,
+    config_version: identity.configVersion,
+    commit_sha: identity.commitSha,
+    input_fingerprint: identity.inputFingerprint
+  };
+
+  return hashStable(keyInput);
+}
+
+export function getScanCachePath(rootDir: string, cacheKey: string): string {
+  return join(getQualityCacheRoot(rootDir), `${cacheKey}.json`);
+}
+
+function getQualityCacheRoot(rootDir: string): string {
+  return join(rootDir, SCAN_CACHE_VERSION);
+}
+
+function hashStable(value: unknown): string {
+  return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+
+export function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+
+  if (isNonArrayRecord(value)) {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(",")}}`;
+  }
+
+  return JSON.stringify(value);
+}