pi-jscpd 0.1.0

package/src/effect/errors.ts

@@ -0,0 +1,311 @@
+import { Data } from "effect";
+import type {
+  JscpdChangedUnavailableReason,
+  JscpdScanFailureReason,
+  JscpdUnavailableReason,
+} from "../types.js";
+
+/** Stable tags for expected operational failures across the Effect migration. */
+export const JSCPD_EXPECTED_ERROR_TAGS = Object.freeze([
+  "JscpdAnalyzerUnavailable",
+  "JscpdProcessFailure",
+  "JscpdFileSystemFailure",
+  "JscpdOperationCancelled",
+  "JscpdOperationTimedOut",
+  "JscpdLimitExceeded",
+  "JscpdInvalidInput",
+  "JscpdStaleOperation",
+  "JscpdWorkspaceFailure",
+  "JscpdPersistenceFailure",
+  "JscpdDeliveryFailure",
+] as const);
+
+export type JscpdOperationStage = "probe" | "scan" | "baseline" | "lifecycle";
+
+export class JscpdAnalyzerUnavailable extends Data.TaggedError("JscpdAnalyzerUnavailable")<{
+  readonly reason: "missing" | "incompatible";
+}> {}
+
+export class JscpdProcessFailure extends Data.TaggedError("JscpdProcessFailure")<{
+  readonly stage: "probe" | "scan";
+  readonly reason: "not-found" | "spawn" | "exit" | "termination";
+}> {}
+
+export class JscpdFileSystemFailure extends Data.TaggedError("JscpdFileSystemFailure")<{
+  readonly operation: "canonicalize" | "metadata" | "read" | "write" | "remove";
+  readonly reason: "missing" | "permission" | "not-regular" | "symlink" | "io";
+}> {}
+
+export class JscpdOperationCancelled extends Data.TaggedError("JscpdOperationCancelled")<{
+  readonly stage: JscpdOperationStage;
+}> {}
+
+export class JscpdOperationTimedOut extends Data.TaggedError("JscpdOperationTimedOut")<{
+  readonly stage: Exclude<JscpdOperationStage, "lifecycle">;
+}> {}
+
+export class JscpdLimitExceeded extends Data.TaggedError("JscpdLimitExceeded")<{
+  readonly subject: "process-output" | "report" | "configuration" | "path" | "message" | "state";
+}> {}
+
+export class JscpdInvalidInput extends Data.TaggedError("JscpdInvalidInput")<{
+  readonly subject: "configuration" | "path" | "process-request" | "report";
+  readonly reason: "unsafe" | "unsupported" | "malformed" | "incompatible" | "invalid";
+}> {}
+
+export class JscpdStaleOperation extends Data.TaggedError("JscpdStaleOperation")<{
+  readonly operation: "baseline" | "scan" | "automatic" | "verification";
+}> {}
+
+export class JscpdWorkspaceFailure extends Data.TaggedError("JscpdWorkspaceFailure")<{
+  readonly operation: "create" | "read-report" | "cleanup";
+}> {}
+
+export class JscpdPersistenceFailure extends Data.TaggedError("JscpdPersistenceFailure")<{
+  readonly operation: "restore" | "append";
+}> {}
+
+export class JscpdDeliveryFailure extends Data.TaggedError("JscpdDeliveryFailure")<{
+  readonly channel: "message" | "notification" | "status";
+}> {}
+
+export type JscpdExpectedError =
+  | JscpdAnalyzerUnavailable
+  | JscpdProcessFailure
+  | JscpdFileSystemFailure
+  | JscpdOperationCancelled
+  | JscpdOperationTimedOut
+  | JscpdLimitExceeded
+  | JscpdInvalidInput
+  | JscpdStaleOperation
+  | JscpdWorkspaceFailure
+  | JscpdPersistenceFailure
+  | JscpdDeliveryFailure;
+
+export const JSCPD_EXPECTED_ERROR_MESSAGE_MAX_LENGTH = 240;
+
+type PublicResultMapping =
+  | {
+      readonly disposition: "result";
+      readonly status: "unavailable";
+      readonly reason: JscpdUnavailableReason;
+      readonly message: string;
+    }
+  | {
+      readonly disposition: "result";
+      readonly status: "failed";
+      readonly reason: JscpdScanFailureReason;
+      readonly message: string;
+    }
+  | {
+      readonly disposition: "result";
+      readonly status: "changed-unavailable";
+      readonly reason: JscpdChangedUnavailableReason;
+      readonly message: string;
+    }
+  | {
+      readonly disposition: "diagnostic" | "defer" | "ignore";
+      readonly reason:
+        | "invalid-configuration"
+        | "stale-operation"
+        | "bounded-state"
+        | "delivery-failed"
+        | "persistence-failed";
+      readonly message: string;
+    };
+
+/**
+ * Foundation mapping only. Production adapters continue using their current mappings until the
+ * owning migration slices replace them; this function fixes bounded public intent meanwhile.
+ */
+export function mapJscpdExpectedError(error: JscpdExpectedError): PublicResultMapping {
+  const mapper = expectedErrorMappers[error._tag] as (
+    candidate: JscpdExpectedError,
+  ) => PublicResultMapping;
+  return mapper(error);
+}
+
+type ExpectedErrorMappers = {
+  readonly [Error in JscpdExpectedError as Error["_tag"]]: (error: Error) => PublicResultMapping;
+};
+
+const expectedErrorMappers = {
+  JscpdAnalyzerUnavailable: mapAnalyzerUnavailable,
+  JscpdProcessFailure: mapProcessFailure,
+  JscpdFileSystemFailure: mapFileSystemFailure,
+  JscpdOperationCancelled: mapOperationCancelled,
+  JscpdOperationTimedOut: mapOperationTimedOut,
+  JscpdLimitExceeded: mapLimitExceeded,
+  JscpdInvalidInput: mapInvalidInput,
+  JscpdStaleOperation: mapStaleOperation,
+  JscpdWorkspaceFailure: mapWorkspaceFailure,
+  JscpdPersistenceFailure: mapPersistenceFailure,
+  JscpdDeliveryFailure: mapDeliveryFailure,
+} satisfies ExpectedErrorMappers;
+
+function mapAnalyzerUnavailable(error: JscpdAnalyzerUnavailable): PublicResultMapping {
+  return publicResult(
+    "unavailable",
+    error.reason === "missing" ? "missing-binary" : "incompatible-version",
+    "jscpd is unavailable; reinstall pi-jscpd or use a compatible jscpd v5 installation.",
+  );
+}
+
+function mapProcessFailure(error: JscpdProcessFailure): PublicResultMapping {
+  return error.stage === "probe"
+    ? publicResult("unavailable", "probe-failed", "The jscpd probe failed safely.")
+    : publicResult("failed", "process-failed", "The jscpd process did not complete safely.");
+}
+
+function mapFileSystemFailure(error: JscpdFileSystemFailure): PublicResultMapping {
+  return error.operation === "read"
+    ? publicResult("failed", "missing-report", "The bounded jscpd report could not be read.")
+    : publicResult("failed", "process-failed", "A required bounded filesystem operation failed.");
+}
+
+function mapOperationCancelled(error: JscpdOperationCancelled): PublicResultMapping {
+  const mappings = {
+    probe: publicResult("unavailable", "probe-cancelled", "The jscpd probe was cancelled."),
+    scan: publicResult("failed", "scan-cancelled", "The jscpd scan was cancelled."),
+    baseline: publicResult(
+      "changed-unavailable",
+      "baseline-cancelled",
+      "The session baseline was cancelled; a later changed check can retry.",
+    ),
+    lifecycle: publicResult(
+      "changed-unavailable",
+      "baseline-cancelled",
+      "The session baseline was cancelled; a later changed check can retry.",
+    ),
+  } satisfies Record<JscpdOperationStage, PublicResultMapping>;
+  return mappings[error.stage];
+}
+
+function mapOperationTimedOut(error: JscpdOperationTimedOut): PublicResultMapping {
+  const mappings = {
+    probe: publicResult("unavailable", "probe-timed-out", "The jscpd probe timed out."),
+    scan: publicResult("failed", "scan-timed-out", "The jscpd scan timed out."),
+    baseline: publicResult(
+      "changed-unavailable",
+      "baseline-timed-out",
+      "The session baseline timed out; explicit project scans remain available.",
+    ),
+  } satisfies Record<JscpdOperationTimedOut["stage"], PublicResultMapping>;
+  return mappings[error.stage];
+}
+
+function mapLimitExceeded(error: JscpdLimitExceeded): PublicResultMapping {
+  if (error.subject === "configuration") {
+    return boundedDisposition(
+      "diagnostic",
+      "invalid-configuration",
+      "Oversized jscpd guardrail configuration was ignored.",
+    );
+  }
+  if (error.subject === "message" || error.subject === "state") {
+    return boundedDisposition("defer", "bounded-state", "Oversized advisory data was omitted.");
+  }
+  return publicResult(
+    "failed",
+    error.subject === "report" ? "invalid-report" : "process-failed",
+    "The jscpd operation exceeded a configured safety limit.",
+  );
+}
+
+function mapInvalidInput(error: JscpdInvalidInput): PublicResultMapping {
+  if (error.subject === "configuration") {
+    return boundedDisposition(
+      "diagnostic",
+      "invalid-configuration",
+      "Invalid jscpd guardrail configuration was ignored.",
+    );
+  }
+  if (error.subject === "path") return mapInvalidPath(error);
+  return error.subject === "process-request"
+    ? publicResult("failed", "process-failed", "The bounded process request was invalid.")
+    : mapInvalidReport(error);
+}
+
+function mapInvalidPath(error: JscpdInvalidInput): PublicResultMapping {
+  const unsupported = error.reason === "unsupported";
+  return publicResult(
+    "failed",
+    unsupported ? "unsupported-path" : "unsafe-path",
+    unsupported
+      ? "The requested scan path is unsupported."
+      : "The requested scan path is outside the project or unsafe.",
+  );
+}
+
+function mapInvalidReport(error: JscpdInvalidInput): PublicResultMapping {
+  const reasons = {
+    unsafe: "invalid-report",
+    unsupported: "invalid-report",
+    malformed: "malformed-report",
+    incompatible: "incompatible-report",
+    invalid: "invalid-report",
+  } as const satisfies Record<JscpdInvalidInput["reason"], JscpdScanFailureReason>;
+  return publicResult(
+    "failed",
+    reasons[error.reason],
+    "jscpd returned an invalid or incompatible report.",
+  );
+}
+
+function mapStaleOperation(_error: JscpdStaleOperation): PublicResultMapping {
+  return boundedDisposition(
+    "defer",
+    "stale-operation",
+    "A superseded jscpd result was discarded safely.",
+  );
+}
+
+function mapWorkspaceFailure(error: JscpdWorkspaceFailure): PublicResultMapping {
+  const reasons = {
+    create: "process-failed",
+    "read-report": "missing-report",
+    cleanup: "cleanup-failed",
+  } as const satisfies Record<JscpdWorkspaceFailure["operation"], JscpdScanFailureReason>;
+  const messages = {
+    create: "The temporary jscpd report workspace was unavailable.",
+    "read-report": "The temporary jscpd report workspace was unavailable.",
+    cleanup: "The temporary jscpd report workspace could not be confirmed clean.",
+  } as const satisfies Record<JscpdWorkspaceFailure["operation"], string>;
+  return publicResult("failed", reasons[error.operation], messages[error.operation]);
+}
+
+function mapPersistenceFailure(_error: JscpdPersistenceFailure): PublicResultMapping {
+  return boundedDisposition(
+    "ignore",
+    "persistence-failed",
+    "Advisory jscpd session state could not be persisted.",
+  );
+}
+
+function mapDeliveryFailure(_error: JscpdDeliveryFailure): PublicResultMapping {
+  return boundedDisposition(
+    "defer",
+    "delivery-failed",
+    "The advisory jscpd update could not be delivered and may be retried.",
+  );
+}
+
+function publicResult<
+  Status extends "unavailable" | "failed" | "changed-unavailable",
+  Reason extends JscpdUnavailableReason | JscpdScanFailureReason | JscpdChangedUnavailableReason,
+>(status: Status, reason: Reason, message: string) {
+  return Object.freeze({ disposition: "result" as const, status, reason, message });
+}
+
+function boundedDisposition(
+  disposition: "diagnostic" | "defer" | "ignore",
+  reason:
+    | "invalid-configuration"
+    | "stale-operation"
+    | "bounded-state"
+    | "delivery-failed"
+    | "persistence-failed",
+  message: string,
+): PublicResultMapping {
+  return Object.freeze({ disposition, reason, message });
+}

package/src/effect/filesystem.ts

@@ -0,0 +1,240 @@
+import { constants as fsConstants, type Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { chmod, mkdtemp, open, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { Effect, Layer } from "effect";
+import { JscpdFileSystemFailure, JscpdLimitExceeded, JscpdWorkspaceFailure } from "./errors.js";
+import {
+  type JscpdBoundedReadRequest,
+  type JscpdFileMetadata,
+  JscpdFileSystem,
+  type JscpdFileSystemError,
+} from "./services.js";
+
+const MAX_FILESYSTEM_BYTES = 64 * 1_024 * 1_024;
+
+/** Live bounded filesystem implementation shared by configuration and untrusted-data boundaries. */
+export const jscpdFileSystemLive: JscpdFileSystem = {
+  canonicalize: (path) =>
+    Effect.tryPromise({
+      try: () => realpath(path),
+      catch: (error) => fileSystemFailure("canonicalize", error),
+    }),
+  metadata: (path) =>
+    Effect.tryPromise({
+      try: async () => metadataFrom(await stat(path)),
+      catch: (error) => fileSystemFailure("metadata", error),
+    }),
+  read: readBoundedFile,
+  write: (request) => {
+    if (!isValidByteBound(request.maxBytes) || request.bytes.byteLength > request.maxBytes) {
+      return Effect.fail(new JscpdLimitExceeded({ subject: "state" }));
+    }
+    return Effect.tryPromise({
+      try: () => writeFile(request.path, request.bytes, { mode: request.mode }),
+      catch: (error) => fileSystemFailure("write", error),
+    });
+  },
+  makeTempDirectory: makeSecureTempDirectory,
+  remove: (path, recursive) =>
+    Effect.tryPromise({
+      try: () =>
+        rm(path, {
+          recursive,
+          force: true,
+          maxRetries: recursive ? 2 : 0,
+          retryDelay: recursive ? 10 : 100,
+        }),
+      catch: (error) => fileSystemFailure("remove", error),
+    }),
+};
+
+export const JscpdFileSystemLive = Layer.succeed(JscpdFileSystem, jscpdFileSystemLive);
+
+function makeSecureTempDirectory(
+  prefix: string,
+): Effect.Effect<string, JscpdWorkspaceFailure | JscpdFileSystemFailure> {
+  return Effect.tryPromise({
+    try: () => mkdtemp(prefix),
+    catch: () => new JscpdWorkspaceFailure({ operation: "create" }),
+  }).pipe(
+    Effect.flatMap((directory) =>
+      Effect.tryPromise({
+        try: () => chmod(directory, 0o700),
+        catch: () => new JscpdWorkspaceFailure({ operation: "create" }),
+      }).pipe(
+        Effect.as(directory),
+        Effect.catchAll((error) =>
+          Effect.tryPromise({
+            try: () => rm(directory, { recursive: true, force: true }),
+            catch: () => fileSystemFailure("remove", undefined),
+          }).pipe(
+            Effect.catchAll(() => Effect.void),
+            Effect.zipRight(Effect.fail(error)),
+          ),
+        ),
+      ),
+    ),
+  );
+}
+
+function readBoundedFile(
+  request: JscpdBoundedReadRequest,
+): Effect.Effect<Uint8Array, JscpdFileSystemError> {
+  if (!isValidReadRequest(request)) {
+    return Effect.fail(new JscpdFileSystemFailure({ operation: "read", reason: "io" }));
+  }
+  const flags = fsConstants.O_RDONLY | (request.noFollow ? fsConstants.O_NOFOLLOW : 0);
+  return readBoundedFileWith(
+    request,
+    Effect.tryPromise({
+      try: () => open(request.path, flags),
+      catch: (error) => fileSystemFailure("read", error),
+    }),
+  );
+}
+
+/** Bracketed handle seam used to prove acquisition/read settlement under interruption. */
+export function readBoundedFileWith(
+  request: JscpdBoundedReadRequest,
+  acquire: Effect.Effect<FileHandle, JscpdFileSystemFailure>,
+): Effect.Effect<Uint8Array, JscpdFileSystemError> {
+  return Effect.acquireUseRelease(
+    acquire,
+    (file) => readFromHandle(file, request).pipe(Effect.uninterruptible),
+    closeFile,
+  );
+}
+
+function readFromHandle(
+  file: FileHandle,
+  request: JscpdBoundedReadRequest,
+): Effect.Effect<Uint8Array, JscpdFileSystemError> {
+  return Effect.tryPromise({
+    try: () => readValidatedFile(file, request),
+    catch: (error) => readFailure(error),
+  });
+}
+
+async function readValidatedFile(
+  file: FileHandle,
+  request: JscpdBoundedReadRequest,
+): Promise<Uint8Array> {
+  const metadata = await file.stat();
+  assertRegularFile(metadata, request.regularFileOnly);
+  const offset = request.offset ?? 0;
+  const capacity = readCapacity(metadata.size, offset, request);
+  const bytes = Buffer.alloc(capacity);
+  const total = await fillBuffer(file, bytes, offset);
+  assertValidReadLength(total, request);
+  return bytes.subarray(0, total);
+}
+
+function assertRegularFile(metadata: Stats, regularFileOnly: boolean): void {
+  if (regularFileOnly && !metadata.isFile()) {
+    throw new JscpdFileSystemFailure({ operation: "read", reason: "not-regular" });
+  }
+}
+
+function readCapacity(fileSize: number, offset: number, request: JscpdBoundedReadRequest): number {
+  const requestedLength = request.length;
+  if (offset > fileSize || (requestedLength !== undefined && offset + requestedLength > fileSize)) {
+    throw new JscpdFileSystemFailure({ operation: "read", reason: "io" });
+  }
+  if (requestedLength === undefined && fileSize - offset > request.maxBytes) {
+    throw new JscpdLimitExceeded({ subject: request.limitSubject });
+  }
+  return requestedLength ?? request.maxBytes + 1;
+}
+
+function assertValidReadLength(total: number, request: JscpdBoundedReadRequest): void {
+  if (request.length !== undefined && total !== request.length) {
+    throw new JscpdFileSystemFailure({ operation: "read", reason: "io" });
+  }
+  if (total > request.maxBytes) {
+    throw new JscpdLimitExceeded({ subject: request.limitSubject });
+  }
+}
+
+async function fillBuffer(file: FileHandle, bytes: Buffer, offset: number): Promise<number> {
+  let total = 0;
+  while (total < bytes.byteLength) {
+    const read = await file.read(bytes, total, bytes.byteLength - total, offset + total);
+    if (read.bytesRead === 0) break;
+    total += read.bytesRead;
+  }
+  return total;
+}
+
+function closeFile(file: FileHandle): Effect.Effect<void> {
+  return Effect.tryPromise({
+    try: () => file.close(),
+    catch: (error) => fileSystemFailure("read", error),
+  }).pipe(Effect.orDie);
+}
+
+function metadataFrom(metadata: Stats): JscpdFileMetadata {
+  const kind = metadata.isFile()
+    ? "file"
+    : metadata.isDirectory()
+      ? "directory"
+      : metadata.isSymbolicLink()
+        ? "symlink"
+        : "other";
+  return { kind, size: metadata.size };
+}
+
+function isValidReadRequest(request: JscpdBoundedReadRequest): boolean {
+  const offset = request.offset ?? 0;
+  return (
+    isValidByteBound(request.maxBytes) &&
+    Number.isSafeInteger(offset) &&
+    offset >= 0 &&
+    (request.length === undefined ||
+      (Number.isSafeInteger(request.length) &&
+        request.length >= 0 &&
+        request.length <= request.maxBytes &&
+        Number.isSafeInteger(offset + request.length)))
+  );
+}
+
+function isValidByteBound(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0 && value <= MAX_FILESYSTEM_BYTES;
+}
+
+function readFailure(error: unknown): JscpdFileSystemError {
+  return error instanceof JscpdFileSystemFailure || error instanceof JscpdLimitExceeded
+    ? error
+    : fileSystemFailure("read", error);
+}
+
+function fileSystemFailure(
+  operation: JscpdFileSystemFailure["operation"],
+  error: unknown,
+): JscpdFileSystemFailure {
+  const code = errorCode(error);
+  const reason = isMissingCode(operation, code)
+    ? "missing"
+    : code === "EACCES" || code === "EPERM"
+      ? "permission"
+      : code === "ELOOP"
+        ? "symlink"
+        : "io";
+  return new JscpdFileSystemFailure({ operation, reason });
+}
+
+function isMissingCode(
+  operation: JscpdFileSystemFailure["operation"],
+  code: string | undefined,
+): boolean {
+  return (
+    code === "ENOENT" ||
+    code === "ENOTDIR" ||
+    (operation === "canonicalize" && process.platform === "win32" && code === "EINVAL")
+  );
+}
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? (error as NodeJS.ErrnoException).code
+    : undefined;
+}

package/src/effect/runtime-boundary.ts

@@ -0,0 +1,25 @@
+import { type Scope as EffectScope, Layer, ManagedRuntime, Scope } from "effect";
+import { JscpdProcessLive } from "../process.js";
+import { JscpdClockLive } from "./clock.js";
+import { JscpdFileSystemLive } from "./filesystem.js";
+import type { JscpdEffectRuntime } from "./runtime-contract.js";
+
+export type { JscpdEffectRuntime, JscpdRuntimeRequirements } from "./runtime-contract.js";
+
+const JscpdRuntimeLive = Layer.mergeAll(JscpdClockLive, JscpdFileSystemLive, JscpdProcessLive);
+
+/** Create the sole managed production runtime for one extension instance. */
+export function createJscpdManagedRuntime(): JscpdEffectRuntime {
+  const runtime = ManagedRuntime.make(JscpdRuntimeLive);
+  return {
+    runPromise: (effect, signal) => runtime.runPromise(effect, signal ? { signal } : undefined),
+    runPromiseExit: (effect, signal) =>
+      runtime.runPromiseExit(effect, signal ? { signal } : undefined),
+    runSync: (effect) => runtime.runSync(effect),
+    dispose: () => runtime.dispose(),
+  } as JscpdEffectRuntime;
+}
+
+export function makeEffectScope(runtime: JscpdEffectRuntime): EffectScope.CloseableScope {
+  return runtime.runSync(Scope.make());
+}

package/src/effect/runtime-contract.ts

@@ -0,0 +1,18 @@
+import type { Effect, Exit as EffectExit } from "effect";
+import type { JscpdWorkflowRequirements } from "./services.js";
+
+export type JscpdRuntimeRequirements = JscpdWorkflowRequirements;
+
+/** Host-owned execution boundary shared by every compatibility facade in one extension. */
+export interface JscpdEffectRuntime {
+  runPromise<A, E, R extends JscpdRuntimeRequirements>(
+    effect: Effect.Effect<A, E, R>,
+    signal?: AbortSignal,
+  ): Promise<A>;
+  runPromiseExit<A, E, R extends JscpdRuntimeRequirements>(
+    effect: Effect.Effect<A, E, R>,
+    signal?: AbortSignal,
+  ): Promise<EffectExit.Exit<A, E>>;
+  runSync<A, E, R extends JscpdRuntimeRequirements>(effect: Effect.Effect<A, E, R>): A;
+  dispose(): Promise<void>;
+}