pi-jscpd 0.1.0

package/src/types.ts

@@ -0,0 +1,334 @@
+import type { JscpdCapabilityResult } from "./capability.js";
+import type { JscpdCommand } from "./registry.js";
+
+export type { JscpdCommand } from "./registry.js";
+
+export interface JscpdCommandInvocation {
+  command: JscpdCommand;
+  args: readonly string[];
+}
+
+export interface JscpdExecutionContext {
+  cwd: string;
+  signal?: AbortSignal;
+  /** Internal TUI request for a bounded cache beyond the configured model/tool display limit. */
+  overlayFindingLimit?: number;
+}
+
+/** Reporter-independent statistics supplied by jscpd; pi-jscpd does not recalculate them. */
+export interface JscpdStatisticsRow {
+  readonly lines: number;
+  readonly tokens: number;
+  readonly sources: number;
+  readonly clones: number;
+  readonly duplicatedLines: number;
+  readonly duplicatedTokens: number;
+  readonly percentage: number;
+  readonly percentageTokens: number;
+  readonly newDuplicatedLines: number;
+  readonly newClones: number;
+}
+
+export interface JscpdFormatStatistics extends JscpdStatisticsRow {
+  readonly format: string;
+}
+
+export interface JscpdScanStatistics {
+  readonly total: JscpdStatisticsRow;
+  /** Sorted by format so reporter object-key order cannot affect normalized output. */
+  readonly formats: readonly JscpdFormatStatistics[];
+}
+
+export interface JscpdSourceLocation {
+  /** One-based source line. */
+  readonly line: number;
+  /** Zero-based source column, as emitted by jscpd v5. */
+  readonly column: number;
+  /** Zero-based source byte offset, named `position` by the JSON reporter. */
+  readonly offset: number;
+}
+
+export interface JscpdCloneOccurrence {
+  /** Canonical project-relative path using `/` separators. */
+  readonly path: string;
+  readonly start: JscpdSourceLocation;
+  readonly end: JscpdSourceLocation;
+}
+
+/** The v5 JSON reporter models each clone as one pair rather than a larger clone group. */
+export interface JscpdClonePair {
+  readonly format: string;
+  readonly lines: number;
+  readonly tokens: number;
+  readonly occurrences: readonly [JscpdCloneOccurrence, JscpdCloneOccurrence];
+}
+
+export interface JscpdScanReport {
+  readonly statistics: JscpdScanStatistics;
+  /** Deterministically sorted, bounded clone pairs with no source fragments. */
+  readonly clonePairs: readonly JscpdClonePair[];
+}
+
+export type JscpdReportErrorCode =
+  | "malformed-json"
+  | "unsupported-reporter"
+  | "invalid-top-level"
+  | "invalid-duplicates"
+  | "invalid-statistics"
+  | "invalid-location"
+  | "unsafe-path"
+  | "limit-exceeded"
+  | "duplicate-key"
+  | "ambiguous-path"
+  | "ambiguous-duplicate";
+
+export type JscpdReportDecision<T> =
+  | { status: "accepted"; value: T }
+  | { status: "no-findings"; value?: T }
+  | { status: "rejected"; reason: JscpdReportErrorCode };
+
+export type JscpdUnavailableReason =
+  | "disabled"
+  | "missing-binary"
+  | "incompatible-version"
+  | "probe-cancelled"
+  | "probe-timed-out"
+  | "probe-failed";
+
+export interface JscpdUnavailableResult {
+  status: "unavailable";
+  reason: JscpdUnavailableReason;
+  message: string;
+  capability?: JscpdCapabilityResult;
+}
+
+export interface JscpdScanSummary {
+  readonly clones: number;
+  readonly duplicatedLines: number;
+  readonly duplicatedTokens: number;
+  readonly lines: number;
+  readonly tokens: number;
+  readonly sources: number;
+  readonly percentage: number;
+  readonly percentageTokens: number;
+}
+
+export interface JscpdPresentedOccurrence {
+  /** A bounded project-relative display path followed by exact line coordinates. */
+  readonly path: string;
+  readonly startLine: number;
+  readonly endLine: number;
+}
+
+export interface JscpdPresentedFinding {
+  readonly format: string;
+  readonly lines: number;
+  readonly tokens: number;
+  readonly occurrences: readonly [JscpdPresentedOccurrence, JscpdPresentedOccurrence];
+}
+
+export interface JscpdChangedOccurrence extends JscpdPresentedOccurrence {
+  readonly relation: "new-session" | "existing-match";
+}
+
+export interface JscpdChangedFinding {
+  readonly format: string;
+  readonly lines: number;
+  readonly tokens: number;
+  readonly occurrences: readonly [JscpdChangedOccurrence, JscpdChangedOccurrence];
+}
+
+export interface JscpdChangedResult {
+  readonly status: "changed";
+  readonly outcome: "findings" | "clean";
+  /** False only when the check short-circuited because no session-owned files were tracked. */
+  readonly scanPerformed: boolean;
+  readonly message: string;
+  readonly terminalMessage: string;
+  /** Configured-limit findings used by commands, tools, acknowledgements, and model output. */
+  readonly findings: readonly JscpdChangedFinding[];
+  readonly omittedFindings: number;
+  readonly ambiguousFindings: number;
+  /** Ephemeral overlay-only data, present only when the TUI adapter explicitly requests it. */
+  readonly overlayCache?: JscpdOverlayFindingCache<JscpdChangedFinding>;
+  readonly verification?: JscpdVerificationResult;
+}
+
+export type JscpdChangedUnavailableReason =
+  | "baseline-pending"
+  | "baseline-unavailable"
+  | "baseline-partial"
+  | "baseline-cancelled"
+  | "baseline-timed-out"
+  | "baseline-failed"
+  | "identity-partial";
+
+export interface JscpdChangedUnavailableResult {
+  readonly status: "changed-unavailable";
+  readonly reason: JscpdChangedUnavailableReason;
+  readonly message: string;
+}
+
+export type JscpdVerificationResult =
+  | {
+      readonly state: "checkpoint";
+      readonly scope: "changed" | "project";
+      readonly groups: number;
+      readonly message: string;
+    }
+  | {
+      readonly state: "compared";
+      readonly scope: "changed" | "project";
+      readonly removed: number;
+      readonly remaining: number;
+      readonly created: number;
+      readonly ambiguous: number;
+      readonly message: string;
+    }
+  | {
+      readonly state: "unavailable";
+      readonly scope: "changed" | "project";
+      readonly reason: "identity-partial" | "lifecycle-changed";
+      readonly message: string;
+    };
+
+export interface JscpdOverlayFindingCache<T> {
+  readonly findings: readonly T[];
+  /** Findings beyond the bounded overlay cache, excluding safely unclassified groups. */
+  readonly omittedFindings: number;
+}
+
+export interface JscpdCompletedResult {
+  readonly status: "completed";
+  readonly outcome: "findings" | "clean";
+  /** Concise content returned to the model-facing tool. */
+  readonly message: string;
+  /** Concise content shown by the terminal slash command. */
+  readonly terminalMessage: string;
+  readonly summary: JscpdScanSummary;
+  /** Configured-limit findings used by commands, tools, and model output. */
+  readonly findings: readonly JscpdPresentedFinding[];
+  readonly omittedFindings: number;
+  /** Ephemeral overlay-only data, present only when the TUI adapter explicitly requests it. */
+  readonly overlayCache?: JscpdOverlayFindingCache<JscpdPresentedFinding>;
+  readonly verification?: JscpdVerificationResult;
+}
+
+export type JscpdScanFailureReason =
+  | "unsafe-path"
+  | "unsupported-path"
+  | "scan-cancelled"
+  | "scan-timed-out"
+  | "process-failed"
+  | "missing-report"
+  | "malformed-report"
+  | "incompatible-report"
+  | "invalid-report"
+  | "cleanup-failed";
+
+export interface JscpdScanFailureResult {
+  readonly status: "failed";
+  readonly reason: JscpdScanFailureReason;
+  readonly message: string;
+}
+
+export type JscpdLastCheck =
+  | { readonly state: "never" }
+  | { readonly state: "clean" }
+  | { readonly state: "findings"; readonly clones: number }
+  | { readonly state: "cancelled" }
+  | {
+      readonly state: "failed";
+      readonly reason: JscpdScanFailureReason | JscpdUnavailableReason;
+    };
+
+export interface JscpdStatusResult {
+  readonly status: "status";
+  readonly message: string;
+  readonly terminalMessage: string;
+  readonly mode: "enabled" | "disabled";
+  readonly modeSource: "configuration" | "session";
+  readonly configSource: "defaults" | "project" | "local";
+  readonly configSources: readonly ("defaults" | "project" | "local")[];
+  readonly configDiagnostics: number;
+  readonly capability: JscpdCapabilityResult;
+  readonly lastCheck: JscpdLastCheck;
+  readonly fallowOverlap?:
+    | "absent"
+    | "detected"
+    | "ambiguous"
+    | "explicit-allow"
+    | "explicit-on-demand";
+  readonly fallowAutomatic?: "allowed" | "on-demand";
+}
+
+export interface JscpdControlResult {
+  readonly status: "control";
+  readonly action: "enabled" | "disabled";
+  readonly message: string;
+  readonly terminalMessage: string;
+}
+
+export interface JscpdHelpResult {
+  readonly status: "help";
+  readonly message: string;
+  readonly terminalMessage: string;
+}
+
+export type JscpdExecutionResult =
+  | JscpdCompletedResult
+  | JscpdUnavailableResult
+  | JscpdScanFailureResult
+  | JscpdStatusResult
+  | JscpdControlResult
+  | JscpdHelpResult
+  | JscpdChangedResult
+  | JscpdChangedUnavailableResult;
+
+export interface JscpdCommandExecutor {
+  /** Native application program; only Pi and test adapters execute it. */
+  executeEffect: (
+    invocation: JscpdCommandInvocation,
+    context: JscpdExecutionContext,
+  ) => import("effect").Effect.Effect<
+    JscpdExecutionResult,
+    never,
+    import("./effect/services.js").JscpdWorkflowRequirements
+  >;
+}
+
+export type JscpdInputErrorCode =
+  | "invalid-command"
+  | "unsupported-command"
+  | "invalid-arguments"
+  | "input-too-long"
+  | "too-many-arguments"
+  | "argument-too-long"
+  | "unclosed-quote";
+
+export interface JscpdInputError {
+  code: JscpdInputErrorCode;
+  message: string;
+}
+
+export type JscpdParseResult =
+  | { ok: true; invocation: JscpdCommandInvocation }
+  | { ok: false; error: JscpdInputError };
+
+export type JscpdSlashParseResult =
+  | { ok: true; kind: "bare" }
+  | { ok: true; kind: "command"; invocation: JscpdCommandInvocation }
+  | { ok: false; error: JscpdInputError };
+
+export type JscpdDispatchResult =
+  | JscpdExecutionResult
+  | {
+      status: "invalid";
+      reason: JscpdInputErrorCode;
+      message: string;
+    }
+  | {
+      status: "error";
+      reason: "execution-failed";
+      message: string;
+    };

package/src/value-utils.ts

@@ -0,0 +1,14 @@
+/** Narrow an untrusted value to a non-array object record. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Require an exact own-key set before untrusted persistence data enters domain state. */
+export function hasExactKeys<T extends readonly string[]>(
+  value: unknown,
+  expected: T,
+): value is Record<T[number], unknown> {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === expected.length && expected.every((key) => Object.hasOwn(value, key));
+}

package/src/verification.ts

@@ -0,0 +1,220 @@
+import { Context, Effect, Layer, MutableRef } from "effect";
+import { compareJscpdCloneSnapshots, type JscpdCloneSnapshot } from "./clone-identity.js";
+import type { JscpdChangedResult, JscpdCompletedResult, JscpdVerificationResult } from "./types.js";
+
+export type JscpdVerificationKind = "changed" | "project";
+
+export interface JscpdVerificationService {
+  compareAndRemember(
+    kind: JscpdVerificationKind,
+    scopeKey: string,
+    snapshot: JscpdCloneSnapshot,
+    expectedScope?: number,
+  ): JscpdVerificationResult;
+  compareAndRememberEffect?: (
+    kind: JscpdVerificationKind,
+    scopeKey: string,
+    snapshot: JscpdCloneSnapshot,
+    expectedScope?: number,
+  ) => Effect.Effect<JscpdVerificationResult>;
+  scope(): number;
+  readonly scopeEffect?: Effect.Effect<number>;
+  reset(): void;
+}
+
+interface VerificationCheckpoint {
+  readonly scopeKey: string;
+  readonly snapshot: JscpdCloneSnapshot;
+}
+
+interface VerificationState {
+  readonly scope: number;
+  readonly checkpoints: ReadonlyMap<JscpdVerificationKind, VerificationCheckpoint>;
+}
+
+interface JscpdVerificationEffectService {
+  readonly compareAndRemember: (
+    kind: JscpdVerificationKind,
+    scopeKey: string,
+    snapshot: JscpdCloneSnapshot,
+    expectedScope?: number,
+  ) => Effect.Effect<JscpdVerificationResult>;
+  readonly scope: Effect.Effect<number>;
+  readonly reset: Effect.Effect<void>;
+}
+
+export const JscpdVerification = Context.GenericTag<JscpdVerificationEffectService>(
+  "pi-jscpd/effect/Verification",
+);
+
+/** Keep one ephemeral pre-refactor checkpoint for each explicit scan kind. */
+export function createJscpdVerificationService(): JscpdVerificationService {
+  return verificationServiceFor(new VerificationOwner());
+}
+
+export function createJscpdVerificationLayer() {
+  const owner = new VerificationOwner();
+  return Layer.succeed(JscpdVerification, verificationEffectServiceFor(owner));
+}
+
+class VerificationOwner {
+  readonly #state = MutableRef.make<VerificationState>({ scope: 0, checkpoints: new Map() });
+
+  compareAndRemember(
+    kind: JscpdVerificationKind,
+    scopeKey: string,
+    snapshot: JscpdCloneSnapshot,
+    expectedScope = this.scope(),
+  ): JscpdVerificationResult {
+    const state = MutableRef.get(this.#state);
+    if (state.scope !== expectedScope) return staleVerification(kind);
+    if (snapshot.status !== "accepted") return unavailableVerification(kind);
+    const previous = state.checkpoints.get(kind);
+    const checkpoints = new Map(state.checkpoints);
+    checkpoints.set(kind, Object.freeze({ scopeKey, snapshot }));
+    MutableRef.set(this.#state, { ...state, checkpoints });
+    return previous?.scopeKey === scopeKey
+      ? compareVerificationSnapshots(kind, previous.snapshot, snapshot)
+      : checkpointVerification(kind, snapshot.groups.length);
+  }
+
+  scope(): number {
+    return MutableRef.get(this.#state).scope;
+  }
+
+  reset(): void {
+    const state = MutableRef.get(this.#state);
+    MutableRef.set(this.#state, { scope: state.scope + 1, checkpoints: new Map() });
+  }
+}
+
+function compareVerificationSnapshots(
+  kind: JscpdVerificationKind,
+  previous: JscpdCloneSnapshot,
+  snapshot: JscpdCloneSnapshot,
+): JscpdVerificationResult {
+  const comparison = compareJscpdCloneSnapshots(previous, snapshot);
+  return comparedVerification(
+    kind,
+    comparison.removed.length,
+    comparison.existing.length,
+    comparison.new.length,
+    comparison.ambiguous.length,
+  );
+}
+
+function verificationServiceFor(owner: VerificationOwner): JscpdVerificationService {
+  return {
+    compareAndRemember: (kind, scopeKey, snapshot, expectedScope) =>
+      owner.compareAndRemember(kind, scopeKey, snapshot, expectedScope),
+    compareAndRememberEffect: (kind, scopeKey, snapshot, expectedScope) =>
+      Effect.sync(() => owner.compareAndRemember(kind, scopeKey, snapshot, expectedScope)),
+    scope: () => owner.scope(),
+    scopeEffect: Effect.sync(() => owner.scope()),
+    reset: () => owner.reset(),
+  };
+}
+
+export function jscpdVerificationScopeEffect(
+  service: JscpdVerificationService,
+): Effect.Effect<number> {
+  return service.scopeEffect ?? Effect.sync(() => service.scope());
+}
+
+export function compareAndRememberJscpdVerificationEffect(
+  service: JscpdVerificationService,
+  kind: JscpdVerificationKind,
+  scopeKey: string,
+  snapshot: JscpdCloneSnapshot,
+  expectedScope?: number,
+): Effect.Effect<JscpdVerificationResult> {
+  return (
+    service.compareAndRememberEffect?.(kind, scopeKey, snapshot, expectedScope) ??
+    Effect.sync(() => service.compareAndRemember(kind, scopeKey, snapshot, expectedScope))
+  );
+}
+
+function verificationEffectServiceFor(owner: VerificationOwner): JscpdVerificationEffectService {
+  return {
+    compareAndRemember: (kind, scopeKey, snapshot, expectedScope) =>
+      Effect.sync(() => owner.compareAndRemember(kind, scopeKey, snapshot, expectedScope)),
+    scope: Effect.sync(() => owner.scope()),
+    reset: Effect.sync(() => owner.reset()),
+  };
+}
+
+export function withJscpdVerification(
+  result: JscpdCompletedResult,
+  verification: JscpdVerificationResult,
+): JscpdCompletedResult;
+export function withJscpdVerification(
+  result: JscpdChangedResult,
+  verification: JscpdVerificationResult,
+): JscpdChangedResult;
+export function withJscpdVerification(
+  result: JscpdCompletedResult | JscpdChangedResult,
+  verification: JscpdVerificationResult,
+): JscpdCompletedResult | JscpdChangedResult {
+  return Object.freeze({
+    ...result,
+    message: `${result.message}\n${verification.message}`,
+    terminalMessage: `${result.terminalMessage}\n${verification.message}`,
+    verification,
+  });
+}
+
+function checkpointVerification(
+  kind: JscpdVerificationKind,
+  groups: number,
+): JscpdVerificationResult {
+  const route = kind === "changed" ? "/jscpd changed" : "the same /jscpd scan";
+  return Object.freeze({
+    state: "checkpoint",
+    scope: kind,
+    groups,
+    message: `Verification checkpoint recorded with ${counted(groups, "duplicate block")}. After ordinary edits and relevant tests, rerun ${route} to compare the result.`,
+  });
+}
+
+function comparedVerification(
+  kind: JscpdVerificationKind,
+  removed: number,
+  remaining: number,
+  created: number,
+  ambiguous: number,
+): JscpdVerificationResult {
+  const qualifier = ambiguous > 0 ? ` ${counted(ambiguous, "comparison")} remained ambiguous.` : "";
+  return Object.freeze({
+    state: "compared",
+    scope: kind,
+    removed,
+    remaining,
+    created,
+    ambiguous,
+    message: `Verification since the previous matching ${kind} scan: ${removed} removed, ${remaining} remaining, ${created} newly created.${qualifier}`,
+  });
+}
+
+function unavailableVerification(kind: JscpdVerificationKind): JscpdVerificationResult {
+  return Object.freeze({
+    state: "unavailable",
+    scope: kind,
+    reason: "identity-partial",
+    message:
+      "Verification comparison is unavailable because complete content identities could not be derived; the current scan result remains advisory.",
+  });
+}
+
+function staleVerification(kind: JscpdVerificationKind): JscpdVerificationResult {
+  return Object.freeze({
+    state: "unavailable",
+    scope: kind,
+    reason: "lifecycle-changed",
+    message:
+      "Verification comparison was discarded because the session or branch changed; rerun the explicit check in the current context.",
+  });
+}
+
+function counted(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}