pi-jscpd 0.1.0

package/src/scheduler.ts

@@ -0,0 +1,434 @@
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableRef, Scope } from "effect";
+import { JscpdClockLive, jscpdClockLive } from "./effect/clock.js";
+import type { JscpdWorkflowRequirements as JscpdRuntimeRequirements } from "./effect/services.js";
+import { type JscpdClock, JscpdClock as JscpdClockTag } from "./effect/services.js";
+import type { JscpdCommandExecutor, JscpdExecutionResult } from "./types.js";
+
+export interface JscpdAutomaticScanContext {
+  readonly generation: number;
+  readonly signal: AbortSignal;
+  /** True only while this run still owns the latest mutation in the active lifecycle scope. */
+  readonly isCurrent: () => boolean;
+}
+
+export type JscpdAutomaticScanDisposition = "attempted" | "deferred";
+
+export type JscpdAutomaticScanEffectTask<R = never, E = never> = (
+  context: JscpdAutomaticScanContext,
+) => Effect.Effect<JscpdAutomaticScanDisposition, E, R>;
+
+export type JscpdExplicitRunResult<T> =
+  | { readonly status: "completed"; readonly value: T }
+  | { readonly status: "closed" };
+
+export interface JscpdScanSchedulerSnapshot {
+  readonly changedGeneration: number;
+  readonly attemptedGeneration: number;
+  readonly automatic: "idle" | "pending" | "active";
+  readonly closed: boolean;
+}
+
+export interface JscpdScanScheduler {
+  readonly markChangedEffect: Effect.Effect<number>;
+  readonly scheduleAutomaticEffect: <R, E>(
+    task: JscpdAutomaticScanEffectTask<R, E>,
+  ) => Effect.Effect<boolean, never, R>;
+  readonly runExplicitEffect: <T, E, R>(
+    task: Effect.Effect<T, E, R>,
+  ) => Effect.Effect<JscpdExplicitRunResult<T>, E, R>;
+  readonly cancelAutomaticEffect: Effect.Effect<void>;
+  readonly resetEffect: Effect.Effect<void>;
+  readonly disposeEffect: Effect.Effect<void>;
+  readonly snapshotEffect: Effect.Effect<JscpdScanSchedulerSnapshot>;
+}
+
+interface JscpdScanSchedulerEffectService {
+  readonly markChanged: Effect.Effect<number>;
+  readonly requestAutomatic: <R, E>(
+    task: JscpdAutomaticScanEffectTask<R, E>,
+  ) => Effect.Effect<boolean, never, R>;
+  readonly runExplicit: <T, E, R>(
+    task: Effect.Effect<T, E, R>,
+  ) => Effect.Effect<JscpdExplicitRunResult<T>, E, R>;
+  readonly cancelAutomatic: Effect.Effect<void>;
+  readonly reset: Effect.Effect<void>;
+  readonly dispose: Effect.Effect<void>;
+  readonly snapshot: Effect.Effect<JscpdScanSchedulerSnapshot>;
+}
+
+export const JscpdScanScheduling = Context.GenericTag<JscpdScanSchedulerEffectService>(
+  "pi-jscpd/effect/ScanScheduling",
+);
+
+interface PendingAutomaticScan {
+  readonly epoch: number;
+  readonly generation: number;
+  readonly task: JscpdAutomaticScanEffectTask;
+}
+
+interface ActiveAutomaticScan extends PendingAutomaticScan {
+  readonly controller: AbortController;
+  readonly fiber: Fiber.RuntimeFiber<JscpdAutomaticScanDisposition, never>;
+}
+
+interface SchedulerState {
+  readonly epoch: number;
+  readonly changedGeneration: number;
+  readonly attemptedGeneration: number;
+  readonly pending?: PendingAutomaticScan;
+  readonly active?: ActiveAutomaticScan;
+  readonly startQueued: boolean;
+  readonly closed: boolean;
+}
+
+const INITIAL_SCHEDULER_STATE: SchedulerState = Object.freeze({
+  epoch: 0,
+  changedGeneration: 0,
+  attemptedGeneration: 0,
+  startQueued: false,
+  closed: false,
+});
+
+/**
+ * Effect owns automatic scheduling and cancellation. Scan processes remain serialized by the
+ * jscpd adapter. The queue is bounded to one active and one latest-generation pending request.
+ */
+export function createJscpdScanScheduler(
+  scope: Scope.CloseableScope,
+  clock: JscpdClock = jscpdClockLive,
+): JscpdScanScheduler {
+  const service = scanSchedulerEffectServiceFor(new ScanSchedulerOwner(scope, clock));
+  return {
+    markChangedEffect: service.markChanged,
+    scheduleAutomaticEffect: service.requestAutomatic,
+    runExplicitEffect: service.runExplicit,
+    cancelAutomaticEffect: service.cancelAutomatic,
+    resetEffect: service.reset,
+    disposeEffect: service.dispose.pipe(Effect.zipRight(Scope.close(scope, Exit.void))),
+    snapshotEffect: service.snapshot,
+  };
+}
+
+/** Build a scheduler whose background fibers are children of the extension's managed scope. */
+export function createJscpdScanSchedulerLayer(clockLayer = JscpdClockLive) {
+  return Layer.scoped(
+    JscpdScanScheduling,
+    Effect.gen(function* () {
+      const scope = yield* Effect.scope;
+      const clock = yield* JscpdClockTag;
+      const owner = new ScanSchedulerOwner(scope, clock);
+      yield* Effect.addFinalizer(() => owner.disposeEffect());
+      return scanSchedulerEffectServiceFor(owner);
+    }),
+  ).pipe(Layer.provide(clockLayer));
+}
+
+class ScanSchedulerOwner {
+  readonly #scope: Scope.Scope;
+  readonly #clock: JscpdClock;
+  readonly #state = MutableRef.make<SchedulerState>(INITIAL_SCHEDULER_STATE);
+
+  constructor(scope: Scope.Scope, clock: JscpdClock) {
+    this.#scope = scope;
+    this.#clock = clock;
+  }
+
+  markChangedEffect(): Effect.Effect<number> {
+    return Effect.suspend(() => {
+      const current = MutableRef.get(this.#state);
+      if (current.closed) return Effect.succeed(current.changedGeneration);
+      if (current.changedGeneration < Number.MAX_SAFE_INTEGER) {
+        const changedGeneration = current.changedGeneration + 1;
+        MutableRef.set(this.#state, { ...current, changedGeneration });
+        return Effect.succeed(changedGeneration);
+      }
+      return this.cancelAutomaticEffect().pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            const reset = MutableRef.get(this.#state);
+            MutableRef.set(this.#state, {
+              ...reset,
+              changedGeneration: 1,
+              attemptedGeneration: 0,
+            });
+          }),
+        ),
+        Effect.as(1),
+      );
+    });
+  }
+
+  requestAutomaticEffect<R, E>(
+    task: JscpdAutomaticScanEffectTask<R, E>,
+  ): Effect.Effect<boolean, never, R> {
+    return Effect.context<R>().pipe(
+      Effect.flatMap((context) =>
+        Effect.suspend(() => {
+          const current = MutableRef.get(this.#state);
+          if (current.closed || current.changedGeneration <= current.attemptedGeneration) {
+            return Effect.succeed(false);
+          }
+          const generation = current.changedGeneration;
+          if (hasCurrentRequestFor(current, generation)) return Effect.succeed(false);
+          const preparedTask: JscpdAutomaticScanEffectTask = (scanContext) =>
+            task(scanContext).pipe(
+              Effect.provide(context),
+              Effect.catchAllCause((cause) =>
+                Cause.isInterruptedOnly(cause)
+                  ? Effect.interrupt
+                  : Effect.succeed("attempted" as const),
+              ),
+            );
+          MutableRef.set(this.#state, {
+            ...current,
+            pending: Object.freeze({ epoch: current.epoch, generation, task: preparedTask }),
+          });
+          return this.queueStartEffect().pipe(Effect.as(true));
+        }),
+      ),
+    );
+  }
+
+  runExplicitEffect<T, E, R>(
+    task: Effect.Effect<T, E, R>,
+  ): Effect.Effect<JscpdExplicitRunResult<T>, E, R> {
+    return Effect.suspend(() => {
+      if (MutableRef.get(this.#state).closed) return Effect.succeed(closedExplicitResult());
+      return this.cancelAutomaticEffect().pipe(
+        Effect.flatMap(() =>
+          MutableRef.get(this.#state).closed
+            ? Effect.succeed(closedExplicitResult())
+            : task.pipe(
+                Effect.map((value) => Object.freeze({ status: "completed" as const, value })),
+              ),
+        ),
+      );
+    });
+  }
+
+  cancelAutomaticEffect(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const current = MutableRef.get(this.#state);
+      current.active?.controller.abort();
+      MutableRef.set(this.#state, {
+        ...current,
+        epoch: current.epoch + 1,
+        pending: undefined,
+      });
+      return current.active ? Fiber.interruptFork(current.active.fiber) : Effect.void;
+    });
+  }
+
+  resetEffect(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      if (MutableRef.get(this.#state).closed) return Effect.void;
+      return this.cancelAutomaticEffect().pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            const current = MutableRef.get(this.#state);
+            MutableRef.set(this.#state, {
+              ...current,
+              changedGeneration: 0,
+              attemptedGeneration: 0,
+            });
+          }),
+        ),
+      );
+    });
+  }
+
+  disposeEffect(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const current = MutableRef.get(this.#state);
+      if (current.closed && !current.active) return Effect.void;
+      current.active?.controller.abort();
+      MutableRef.set(this.#state, {
+        ...current,
+        epoch: current.epoch + 1,
+        pending: undefined,
+        closed: true,
+      });
+      return current.active
+        ? Fiber.interrupt(current.active.fiber).pipe(Effect.asVoid)
+        : Effect.void;
+    });
+  }
+
+  snapshot(): JscpdScanSchedulerSnapshot {
+    const state = MutableRef.get(this.#state);
+    return Object.freeze({
+      changedGeneration: state.changedGeneration,
+      attemptedGeneration: state.attemptedGeneration,
+      automatic: state.active ? "active" : state.pending ? "pending" : "idle",
+      closed: state.closed,
+    });
+  }
+
+  private queueStartEffect(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const current = MutableRef.get(this.#state);
+      if (current.startQueued || current.closed || current.active || !current.pending) {
+        return Effect.void;
+      }
+      MutableRef.set(this.#state, { ...current, startQueued: true });
+      return Effect.forkIn(
+        this.#clock.sleep(0).pipe(Effect.zipRight(this.startPendingEffect())),
+        this.#scope,
+      ).pipe(Effect.asVoid);
+    });
+  }
+
+  private startPendingEffect(): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const current = MutableRef.get(this.#state);
+      MutableRef.set(this.#state, { ...current, startQueued: false });
+      const candidate = current.pending;
+      if (current.closed || current.active || !candidate) return Effect.void;
+      MutableRef.set(this.#state, { ...MutableRef.get(this.#state), pending: undefined });
+      if (
+        candidate.epoch !== current.epoch ||
+        candidate.generation <= current.attemptedGeneration ||
+        candidate.generation > current.changedGeneration
+      ) {
+        return this.queueStartEffect();
+      }
+      return this.launchAutomaticEffect(candidate);
+    });
+  }
+
+  private launchAutomaticEffect(candidate: PendingAutomaticScan): Effect.Effect<void> {
+    return Effect.gen(this, function* () {
+      const controller = new AbortController();
+      const gate = yield* Deferred.make<void>();
+      const program = Deferred.await(gate).pipe(
+        Effect.zipRight(this.runAutomaticTaskEffect(candidate, controller)),
+      );
+      const fiber = yield* Effect.forkIn(program, this.#scope);
+      const current = MutableRef.get(this.#state);
+      if (current.closed || current.epoch !== candidate.epoch) {
+        controller.abort();
+        yield* Deferred.succeed(gate, undefined);
+        yield* Fiber.interruptFork(fiber);
+        return;
+      }
+      MutableRef.set(this.#state, {
+        ...current,
+        active: Object.freeze({ ...candidate, controller, fiber }),
+      });
+      yield* Deferred.succeed(gate, undefined);
+    });
+  }
+
+  private runAutomaticTaskEffect(
+    candidate: PendingAutomaticScan,
+    controller: AbortController,
+  ): Effect.Effect<JscpdAutomaticScanDisposition> {
+    const context = Object.freeze({
+      generation: candidate.generation,
+      signal: controller.signal,
+      isCurrent: () => this.isCurrent(candidate, controller),
+    });
+    return Effect.suspend(() => candidate.task(context)).pipe(
+      Effect.catchAllCause((cause) =>
+        Cause.isInterruptedOnly(cause)
+          ? Effect.failCause(cause)
+          : Effect.succeed("attempted" as const),
+      ),
+      Effect.onInterrupt(() => Effect.sync(() => controller.abort())),
+      Effect.onExit((exit) => this.finishAutomaticEffect(candidate, controller, exit)),
+    );
+  }
+
+  private finishAutomaticEffect(
+    candidate: PendingAutomaticScan,
+    controller: AbortController,
+    exit: Exit.Exit<JscpdAutomaticScanDisposition, never>,
+  ): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const current = MutableRef.get(this.#state);
+      if (current.active?.controller !== controller) return Effect.void;
+      const disposition = Exit.isSuccess(exit) ? exit.value : undefined;
+      const attemptedGeneration =
+        disposition === "attempted" &&
+        !current.closed &&
+        candidate.epoch === current.epoch &&
+        !controller.signal.aborted
+          ? Math.max(current.attemptedGeneration, candidate.generation)
+          : current.attemptedGeneration;
+      MutableRef.set(this.#state, {
+        ...current,
+        active: undefined,
+        attemptedGeneration,
+      });
+      return this.queueStartEffect();
+    });
+  }
+
+  private isCurrent(candidate: PendingAutomaticScan, controller: AbortController): boolean {
+    const state = MutableRef.get(this.#state);
+    return (
+      !state.closed &&
+      !controller.signal.aborted &&
+      candidate.epoch === state.epoch &&
+      candidate.generation === state.changedGeneration
+    );
+  }
+}
+
+function hasCurrentRequestFor(state: SchedulerState, generation: number): boolean {
+  return (
+    (state.active?.epoch === state.epoch && state.active.generation >= generation) ||
+    (state.pending?.epoch === state.epoch && state.pending.generation >= generation)
+  );
+}
+
+function scanSchedulerEffectServiceFor(owner: ScanSchedulerOwner): JscpdScanSchedulerEffectService {
+  return {
+    markChanged: Effect.suspend(() => owner.markChangedEffect()),
+    requestAutomatic: (task) => owner.requestAutomaticEffect(task),
+    runExplicit: (task) => owner.runExplicitEffect(task),
+    cancelAutomatic: Effect.suspend(() => owner.cancelAutomaticEffect()),
+    reset: Effect.suspend(() => owner.resetEffect()),
+    dispose: Effect.suspend(() => owner.disposeEffect()),
+    snapshot: Effect.sync(() => owner.snapshot()),
+  };
+}
+
+function closedExplicitResult<T>(): JscpdExplicitRunResult<T> {
+  return Object.freeze({ status: "closed" });
+}
+
+/** Cancel scheduler-owned automatic work before explicit scan operations. */
+export function createJscpdScheduledExecutor(
+  executor: JscpdCommandExecutor,
+  scheduler: JscpdScanScheduler,
+): JscpdCommandExecutor {
+  const executeEffect = (
+    invocation: Parameters<JscpdCommandExecutor["executeEffect"]>[0],
+    context: Parameters<JscpdCommandExecutor["executeEffect"]>[1],
+  ): Effect.Effect<JscpdExecutionResult, never, JscpdRuntimeRequirements> => {
+    const cancel = invocation.command === "off" ? scheduler.cancelAutomaticEffect : Effect.void;
+    const execute = executor.executeEffect(invocation, context);
+    if (invocation.command !== "scan" && invocation.command !== "changed") {
+      return cancel.pipe(Effect.zipRight(execute));
+    }
+    const scheduled = scheduler.runExplicitEffect(execute);
+    return cancel.pipe(
+      Effect.zipRight(scheduled),
+      Effect.map((result) =>
+        result.status === "completed" ? result.value : schedulerClosedResult(),
+      ),
+    );
+  };
+  return {
+    executeEffect,
+  };
+}
+
+function schedulerClosedResult(): JscpdExecutionResult {
+  return Object.freeze({
+    status: "failed",
+    reason: "scan-cancelled",
+    message: "The jscpd scan was cancelled because the session is shutting down.",
+  });
+}

package/src/session-state.ts

@@ -0,0 +1,229 @@
+import { Effect } from "effect";
+import {
+  emptyJscpdAcknowledgements,
+  type JscpdAcknowledgementTracker,
+  type JscpdPersistedAcknowledgements,
+  parseJscpdAcknowledgements,
+  snapshotJscpdAcknowledgements,
+} from "./acknowledgements.js";
+import {
+  isSafeChangedFilePath,
+  type JscpdChangedFileTracker,
+  MAX_CHANGED_FILES,
+} from "./changed-files.js";
+import { JscpdPiPort } from "./effect/services.js";
+import type { JscpdSessionModeService, JscpdStatusService } from "./status.js";
+import type { JscpdLastCheck, JscpdScanFailureReason, JscpdUnavailableReason } from "./types.js";
+import { hasExactKeys, isRecord } from "./value-utils.js";
+
+export const JSCPD_SESSION_STATE_TYPE = "pi-jscpd/session-state";
+export const JSCPD_SESSION_STATE_VERSION = 3;
+
+export type JscpdSessionModeOverride = "enabled" | "disabled" | null;
+
+export interface JscpdPersistedSessionState {
+  readonly version: typeof JSCPD_SESSION_STATE_VERSION;
+  readonly modeOverride: JscpdSessionModeOverride;
+  readonly lastCheck: JscpdLastCheck;
+  readonly changedFiles: readonly string[];
+  readonly acknowledgements: JscpdPersistedAcknowledgements;
+}
+
+const SCAN_FAILURE_REASONS = new Set<JscpdScanFailureReason>([
+  "unsafe-path",
+  "unsupported-path",
+  "scan-cancelled",
+  "scan-timed-out",
+  "process-failed",
+  "missing-report",
+  "malformed-report",
+  "incompatible-report",
+  "invalid-report",
+  "cleanup-failed",
+]);
+
+const UNAVAILABLE_REASONS = new Set<JscpdUnavailableReason>([
+  "disabled",
+  "missing-binary",
+  "incompatible-version",
+  "probe-cancelled",
+  "probe-timed-out",
+  "probe-failed",
+]);
+
+const MAX_RESTORED_CLONES = 1_000;
+
+/** Build the only extension state written to Pi's branch-local custom entries. */
+export function snapshotJscpdSessionState(
+  mode: JscpdSessionModeService,
+  status: JscpdStatusService,
+  changedFiles: JscpdChangedFileTracker,
+  acknowledgements: JscpdAcknowledgementTracker,
+): JscpdPersistedSessionState {
+  return Object.freeze({
+    version: JSCPD_SESSION_STATE_VERSION,
+    modeOverride: mode.override(),
+    lastCheck: status.lastCheck(),
+    changedFiles: Object.freeze([...changedFiles.files()]),
+    acknowledgements: snapshotJscpdAcknowledgements(acknowledgements),
+  });
+}
+
+/** Persist one already-bounded snapshot through the injected branch-local Pi port. */
+export function persistJscpdSessionStateEffect(state: JscpdPersistedSessionState) {
+  return Effect.flatMap(JscpdPiPort, (pi) =>
+    pi.appendSessionEntry(JSCPD_SESSION_STATE_TYPE, state),
+  );
+}
+
+/**
+ * Restore only the latest pi-jscpd entry on the supplied active branch.
+ * A malformed or unsupported latest entry resets state instead of reviving an older snapshot.
+ */
+export function restoreJscpdSessionState(
+  activeBranch: readonly unknown[],
+): JscpdPersistedSessionState | undefined {
+  for (let index = activeBranch.length - 1; index >= 0; index -= 1) {
+    const entry = activeBranch[index];
+    if (!isJscpdCustomEntry(entry)) continue;
+    return parsePersistedState(entry.data);
+  }
+  return undefined;
+}
+
+function isJscpdCustomEntry(
+  value: unknown,
+): value is { type: "custom"; customType: typeof JSCPD_SESSION_STATE_TYPE; data: unknown } {
+  if (!isRecord(value)) return false;
+  return value.type === "custom" && value.customType === JSCPD_SESSION_STATE_TYPE;
+}
+
+function parsePersistedState(value: unknown): JscpdPersistedSessionState | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.version === 1) return migrateVersionOneState(value);
+  if (value.version === 2) return migrateVersionTwoState(value);
+  if (value.version !== JSCPD_SESSION_STATE_VERSION) return undefined;
+  if (
+    !hasExactKeys(value, [
+      "version",
+      "modeOverride",
+      "lastCheck",
+      "changedFiles",
+      "acknowledgements",
+    ])
+  ) {
+    return undefined;
+  }
+  return parseStateFields(
+    value.modeOverride,
+    value.lastCheck,
+    value.changedFiles,
+    value.acknowledgements,
+  );
+}
+
+/** Preserve pre-M3 session controls/status while starting changed-file attribution empty. */
+function migrateVersionOneState(value: unknown): JscpdPersistedSessionState | undefined {
+  if (!hasExactKeys(value, ["version", "modeOverride", "lastCheck"]) || value.version !== 1) {
+    return undefined;
+  }
+  return parseStateFields(value.modeOverride, value.lastCheck, [], emptyJscpdAcknowledgements());
+}
+
+/** Preserve M3 changed-file attribution while starting acknowledgement identity v1 empty. */
+function migrateVersionTwoState(value: unknown): JscpdPersistedSessionState | undefined {
+  if (
+    !hasExactKeys(value, ["version", "modeOverride", "lastCheck", "changedFiles"]) ||
+    value.version !== 2
+  ) {
+    return undefined;
+  }
+  return parseStateFields(
+    value.modeOverride,
+    value.lastCheck,
+    value.changedFiles,
+    emptyJscpdAcknowledgements(),
+  );
+}
+
+function parseStateFields(
+  modeOverride: unknown,
+  lastCheckValue: unknown,
+  changedFilesValue: unknown,
+  acknowledgementsValue: unknown,
+): JscpdPersistedSessionState | undefined {
+  if (modeOverride !== null && modeOverride !== "enabled" && modeOverride !== "disabled") {
+    return undefined;
+  }
+  const lastCheck = parseLastCheck(lastCheckValue);
+  const changedFiles = parseChangedFiles(changedFilesValue);
+  const acknowledgements = parseJscpdAcknowledgements(acknowledgementsValue);
+  if (!lastCheck || !changedFiles || !acknowledgements) return undefined;
+  return Object.freeze({
+    version: JSCPD_SESSION_STATE_VERSION,
+    modeOverride,
+    lastCheck,
+    changedFiles,
+    acknowledgements,
+  });
+}
+
+function parseChangedFiles(value: unknown): readonly string[] | undefined {
+  if (!Array.isArray(value) || value.length > MAX_CHANGED_FILES) return undefined;
+  const files: string[] = [];
+  const seen = new Set<string>();
+  for (const path of value) {
+    if (!isSafeChangedFilePath(path) || seen.has(path)) return undefined;
+    seen.add(path);
+    files.push(path);
+  }
+  return Object.freeze(files);
+}
+
+function parseLastCheck(value: unknown): JscpdLastCheck | undefined {
+  if (!isRecord(value)) return undefined;
+  switch (value.state) {
+    case "never":
+    case "clean":
+    case "cancelled":
+      return parseSimpleLastCheck(value, value.state);
+    case "findings":
+      return parseFindingsLastCheck(value);
+    case "failed":
+      return parseFailedLastCheck(value);
+    default:
+      return undefined;
+  }
+}
+
+function parseSimpleLastCheck(
+  value: unknown,
+  state: "never" | "clean" | "cancelled",
+): JscpdLastCheck | undefined {
+  if (!hasExactKeys(value, ["state"])) return undefined;
+  return Object.freeze({ state });
+}
+
+function parseFindingsLastCheck(value: unknown): JscpdLastCheck | undefined {
+  if (!hasExactKeys(value, ["state", "clones"])) return undefined;
+  if (!isRestorableCloneCount(value.clones)) return undefined;
+  return Object.freeze({ state: "findings", clones: value.clones });
+}
+
+function parseFailedLastCheck(value: unknown): JscpdLastCheck | undefined {
+  if (!hasExactKeys(value, ["state", "reason"])) return undefined;
+  if (!isFailureReason(value.reason)) return undefined;
+  return Object.freeze({ state: "failed", reason: value.reason });
+}
+
+function isRestorableCloneCount(value: unknown): value is number {
+  return Number.isSafeInteger(value) && Number(value) >= 0 && Number(value) <= MAX_RESTORED_CLONES;
+}
+
+function isFailureReason(value: unknown): value is JscpdScanFailureReason | JscpdUnavailableReason {
+  if (typeof value !== "string") return false;
+  return (
+    SCAN_FAILURE_REASONS.has(value as JscpdScanFailureReason) ||
+    UNAVAILABLE_REASONS.has(value as JscpdUnavailableReason)
+  );
+}