pi-jscpd 0.1.0

package/src/parser.ts

@@ -0,0 +1,189 @@
+import {
+  getJscpdCommandSpec,
+  JSCPD_MAX_ARGUMENT_LENGTH,
+  jscpdCommandNames,
+  jscpdCommandRegistry,
+} from "./registry.js";
+import type { JscpdInputError, JscpdParseResult, JscpdSlashParseResult } from "./types.js";
+
+const MAX_ARGUMENTS = Math.max(...jscpdCommandRegistry.map(({ maxArguments }) => maxArguments));
+const MAX_SLASH_INPUT_LENGTH = (MAX_ARGUMENTS + 1) * (JSCPD_MAX_ARGUMENT_LENGTH + 1);
+
+export function parseJscpdCommand(command: unknown, args?: unknown): JscpdParseResult {
+  if (typeof command !== "string" || command.length === 0) {
+    return invalid("invalid-command", "A jscpd command is required.");
+  }
+
+  const spec = getJscpdCommandSpec(command);
+  if (!spec) {
+    return invalid(
+      "unsupported-command",
+      `Unsupported jscpd command. Supported commands: ${jscpdCommandNames.join(", ")}.`,
+    );
+  }
+
+  if (args !== undefined && !Array.isArray(args)) {
+    return invalid(
+      "invalid-arguments",
+      "Arguments must be provided as an array of shell-free string tokens.",
+    );
+  }
+
+  const tokens = args === undefined ? [] : args;
+  if (tokens.length > spec.maxArguments) {
+    return invalid(
+      "too-many-arguments",
+      `${spec.name} accepts at most ${spec.maxArguments} argument tokens.`,
+    );
+  }
+
+  for (const token of tokens) {
+    if (typeof token !== "string" || token.length === 0 || token.includes("\0")) {
+      return invalid(
+        "invalid-arguments",
+        "Argument tokens must be non-empty strings without null bytes.",
+      );
+    }
+    if (token.length > JSCPD_MAX_ARGUMENT_LENGTH) {
+      return invalid(
+        "argument-too-long",
+        `Argument tokens must not exceed ${JSCPD_MAX_ARGUMENT_LENGTH} characters.`,
+      );
+    }
+  }
+
+  return { ok: true, invocation: { command: spec.name, args: [...tokens] } };
+}
+
+export function parseJscpdSlashArgs(rawArgs: string): JscpdSlashParseResult {
+  if (rawArgs.length > MAX_SLASH_INPUT_LENGTH) {
+    return invalid("input-too-long", "The /jscpd argument text is too long.");
+  }
+
+  const tokenized = tokenize(rawArgs);
+  if (!tokenized.ok) return tokenized;
+  if (tokenized.tokens.length === 0) return { ok: true, kind: "bare" };
+
+  const [command, ...args] = tokenized.tokens;
+  const parsed = parseJscpdCommand(command, args);
+  if (!parsed.ok) return parsed;
+  return { ok: true, kind: "command", invocation: parsed.invocation };
+}
+
+interface TokenizeResult {
+  ok: true;
+  tokens: string[];
+}
+
+type TokenQuote = "'" | '"';
+
+interface TokenizerState {
+  tokens: string[];
+  current: string;
+  quote: TokenQuote | undefined;
+  tokenStarted: boolean;
+}
+
+function tokenize(input: string): TokenizeResult | { ok: false; error: JscpdInputError } {
+  const state = createTokenizerState();
+  for (let index = 0; index < input.length; index += 1) {
+    index = consumeTokenCharacter(state, input, index);
+  }
+
+  if (state.quote) return invalid("unclosed-quote", "Unclosed quote in /jscpd arguments.");
+  flushToken(state);
+  return { ok: true, tokens: state.tokens };
+}
+
+function createTokenizerState(): TokenizerState {
+  return { tokens: [], current: "", quote: undefined, tokenStarted: false };
+}
+
+function consumeTokenCharacter(state: TokenizerState, input: string, index: number): number {
+  const char = input[index] ?? "";
+  if (state.quote) return consumeQuotedCharacter(state, input, index, char);
+  return consumeUnquotedCharacter(state, input, index, char);
+}
+
+function consumeQuotedCharacter(
+  state: TokenizerState,
+  input: string,
+  index: number,
+  char: string,
+): number {
+  if (char === state.quote) {
+    state.quote = undefined;
+    return index;
+  }
+  if (state.quote === '"' && char === "\\") {
+    return consumeEscape(state, input, index, isDoubleQuotedEscape);
+  }
+  state.current += char;
+  return index;
+}
+
+function consumeUnquotedCharacter(
+  state: TokenizerState,
+  input: string,
+  index: number,
+  char: string,
+): number {
+  if (isTokenWhitespace(char)) {
+    flushToken(state);
+    return index;
+  }
+
+  state.tokenStarted = true;
+  if (isQuote(char)) {
+    state.quote = char;
+    return index;
+  }
+  if (char === "\\") return consumeEscape(state, input, index, isUnquotedEscape);
+  state.current += char;
+  return index;
+}
+
+function consumeEscape(
+  state: TokenizerState,
+  input: string,
+  index: number,
+  canEscape: (char: string) => boolean,
+): number {
+  const next = input[index + 1];
+  if (next !== undefined && canEscape(next)) {
+    state.current += next;
+    return index + 1;
+  }
+  state.current += "\\";
+  return index;
+}
+
+function flushToken(state: TokenizerState): void {
+  if (!state.tokenStarted) return;
+  state.tokens.push(state.current);
+  state.current = "";
+  state.tokenStarted = false;
+}
+
+function isQuote(char: string): char is TokenQuote {
+  return char === "'" || char === '"';
+}
+
+function isDoubleQuotedEscape(char: string): boolean {
+  return char === '"' || char === "\\";
+}
+
+function isUnquotedEscape(char: string): boolean {
+  return isTokenWhitespace(char) || isQuote(char) || char === "\\";
+}
+
+function isTokenWhitespace(char: string): boolean {
+  return /\s/.test(char);
+}
+
+function invalid(
+  code: JscpdInputError["code"],
+  message: string,
+): { ok: false; error: JscpdInputError } {
+  return { ok: false, error: { code, message } };
+}

package/src/path-utils.ts

@@ -0,0 +1,44 @@
+import { isAbsolute, relative, sep } from "node:path";
+import { Effect } from "effect";
+import { JscpdFileSystem } from "./effect/services.js";
+
+/** Resolve an existing absolute directory through the injected bounded filesystem. */
+export function canonicalDirectoryEffect(cwd: string) {
+  if (!isAbsolute(cwd)) return Effect.succeed<string | undefined>(undefined);
+  return Effect.flatMap(JscpdFileSystem, (filesystem) =>
+    Effect.all([filesystem.canonicalize(cwd), filesystem.metadata(cwd)], {
+      concurrency: "unbounded",
+    }),
+  ).pipe(
+    Effect.map(([canonical, metadata]) => (metadata.kind === "directory" ? canonical : undefined)),
+  );
+}
+
+/** Resolve a canonical directory and collapse filesystem failures at the application edge. */
+export function optionalCanonicalDirectoryEffect(cwd: string) {
+  return canonicalDirectoryEffect(cwd).pipe(
+    Effect.catchAll(() => Effect.succeed<string | undefined>(undefined)),
+  );
+}
+
+/** Reject control characters before paths or labels reach filesystem APIs. */
+export function hasControlCharacters(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint <= 0x1f || codePoint === 0x7f) return true;
+  }
+  return false;
+}
+
+/** Test containment without treating a sibling path with the same prefix as a child. */
+export function isPathInside(parent: string, candidate: string): boolean {
+  const fromParent = relative(parent, candidate);
+  return (
+    fromParent === "" ||
+    (fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent))
+  );
+}
+
+export function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/presentation.ts

@@ -0,0 +1,232 @@
+import {
+  boundedJscpdDisplayPath,
+  jscpdFindingDetailLines,
+  jscpdFindingGuidance,
+} from "./finding-presentation.js";
+import type {
+  JscpdChangedFinding,
+  JscpdChangedResult,
+  JscpdCompletedResult,
+  JscpdPresentedFinding,
+  JscpdScanReport,
+  JscpdScanSummary,
+} from "./types.js";
+
+const DEFAULT_MAX_PRESENTED_FINDINGS = 10;
+const MAX_CONFIGURED_PRESENTED_FINDINGS = 100;
+
+/** Build bounded model and terminal views from one normalized jscpd report. */
+export function presentJscpdScan(
+  report: JscpdScanReport,
+  configuredMaxFindings = DEFAULT_MAX_PRESENTED_FINDINGS,
+  overlayFindingLimit?: number,
+): JscpdCompletedResult {
+  const summary = scanSummary(report);
+  const maxFindings = boundedFindingLimit(configuredMaxFindings);
+  const overlayLimit = boundedOverlayFindingLimit(overlayFindingLimit);
+  const retained = report.clonePairs
+    .slice(0, Math.max(maxFindings, overlayLimit ?? 0))
+    .map(presentFinding);
+  const findings = Object.freeze(retained.slice(0, maxFindings));
+  const omittedFindings = Math.max(0, report.clonePairs.length - findings.length);
+  const overlayCache = overlayLimit
+    ? Object.freeze({
+        findings: Object.freeze(retained.slice(0, overlayLimit)),
+        omittedFindings: Math.max(0, report.clonePairs.length - overlayLimit),
+      })
+    : undefined;
+  const outcome = findings.length === 0 ? "clean" : "findings";
+
+  if (outcome === "clean") {
+    const text = `jscpd scan clean: 0 duplicate blocks across ${summary.lines} lines and ${summary.tokens} tokens in ${summary.sources} sources.`;
+    return {
+      status: "completed",
+      outcome,
+      message: text,
+      terminalMessage: text,
+      summary,
+      findings,
+      omittedFindings,
+      ...(overlayCache ? { overlayCache } : {}),
+    };
+  }
+
+  const headline = `jscpd found ${plural(summary.clones, "duplicate block")}: ${summary.duplicatedLines} duplicated lines (${formatPercentage(summary.percentage)}) and ${summary.duplicatedTokens} duplicated tokens (${formatPercentage(summary.percentageTokens)}) across ${summary.sources} sources.`;
+  const findingLines = findings.flatMap((finding, index) =>
+    jscpdFindingDetailLines(finding, index + 1, summary.clones),
+  );
+  const omittedLine =
+    omittedFindings > 0
+      ? [`${plural(omittedFindings, "additional duplicate block")} omitted by the display limit.`]
+      : [];
+  const message = [
+    headline,
+    ...findingLines,
+    ...omittedLine,
+    ...jscpdFindingGuidance("project"),
+  ].join("\n");
+
+  return {
+    status: "completed",
+    outcome,
+    message,
+    terminalMessage: message,
+    summary,
+    findings,
+    omittedFindings,
+    ...(overlayCache ? { overlayCache } : {}),
+  };
+}
+
+/** Present only unacknowledged net-new groups involving session-owned files. */
+export function presentJscpdChanged(
+  clonePairs: readonly JscpdScanReport["clonePairs"][number][],
+  changedFiles: ReadonlySet<string>,
+  configuredMaxFindings = DEFAULT_MAX_PRESENTED_FINDINGS,
+  ambiguousFindings = 0,
+  overlayFindingLimit?: number,
+): JscpdChangedResult {
+  const maxFindings = boundedFindingLimit(configuredMaxFindings);
+  const overlayLimit = boundedOverlayFindingLimit(overlayFindingLimit);
+  const retained = clonePairs
+    .slice(0, Math.max(maxFindings, overlayLimit ?? 0))
+    .map((pair) => presentChangedFinding(pair, changedFiles));
+  const findings = Object.freeze(retained.slice(0, maxFindings));
+  const omittedFindings = Math.max(0, clonePairs.length - findings.length);
+  const overlayCache = overlayLimit
+    ? Object.freeze({
+        findings: Object.freeze(retained.slice(0, overlayLimit)),
+        omittedFindings: Math.max(0, clonePairs.length - overlayLimit),
+      })
+    : undefined;
+  const outcome = findings.length === 0 ? "clean" : "findings";
+  const ambiguity =
+    ambiguousFindings > 0
+      ? ` ${plural(ambiguousFindings, "clone group")} could not be classified conservatively.`
+      : "";
+  if (outcome === "clean") {
+    const message = `jscpd changed: no unacknowledged new duplicate blocks involve session-owned changed files.${ambiguity}`;
+    return Object.freeze({
+      status: "changed",
+      outcome,
+      scanPerformed: true,
+      message,
+      terminalMessage: message,
+      findings,
+      omittedFindings,
+      ambiguousFindings,
+      ...(overlayCache ? { overlayCache } : {}),
+    });
+  }
+  const headline = `jscpd changed found ${plural(clonePairs.length, "unacknowledged new duplicate block")} involving session-owned changed files.`;
+  const findingLines = findings.flatMap((finding, index) =>
+    jscpdFindingDetailLines(finding, index + 1, clonePairs.length),
+  );
+  const omittedLine =
+    omittedFindings > 0
+      ? [
+          `${plural(omittedFindings, "additional new duplicate block")} omitted by the display limit and not acknowledged.`,
+        ]
+      : [];
+  const message = [
+    headline,
+    ...findingLines,
+    ...omittedLine,
+    ambiguity.trim(),
+    ...jscpdFindingGuidance("changed"),
+  ]
+    .filter(Boolean)
+    .join("\n");
+  return Object.freeze({
+    status: "changed",
+    outcome,
+    scanPerformed: true,
+    message,
+    terminalMessage: message,
+    findings,
+    omittedFindings,
+    ambiguousFindings,
+    ...(overlayCache ? { overlayCache } : {}),
+  });
+}
+
+function boundedFindingLimit(value: number): number {
+  return Number.isSafeInteger(value) && value >= 1 && value <= MAX_CONFIGURED_PRESENTED_FINDINGS
+    ? value
+    : DEFAULT_MAX_PRESENTED_FINDINGS;
+}
+
+function boundedOverlayFindingLimit(value: number | undefined): number | undefined {
+  return value !== undefined &&
+    Number.isSafeInteger(value) &&
+    value >= 1 &&
+    value <= MAX_CONFIGURED_PRESENTED_FINDINGS
+    ? value
+    : undefined;
+}
+
+function scanSummary(report: JscpdScanReport): JscpdScanSummary {
+  const total = report.statistics.total;
+  return Object.freeze({
+    clones: total.clones,
+    duplicatedLines: total.duplicatedLines,
+    duplicatedTokens: total.duplicatedTokens,
+    lines: total.lines,
+    tokens: total.tokens,
+    sources: total.sources,
+    percentage: total.percentage,
+    percentageTokens: total.percentageTokens,
+  });
+}
+
+function presentFinding(pair: JscpdScanReport["clonePairs"][number]): JscpdPresentedFinding {
+  const [first, second] = pair.occurrences;
+  return Object.freeze({
+    format: pair.format,
+    lines: pair.lines,
+    tokens: pair.tokens,
+    occurrences: Object.freeze([
+      Object.freeze({
+        path: boundedJscpdDisplayPath(first.path),
+        startLine: first.start.line,
+        endLine: first.end.line,
+      }),
+      Object.freeze({
+        path: boundedJscpdDisplayPath(second.path),
+        startLine: second.start.line,
+        endLine: second.end.line,
+      }),
+    ]) as readonly [
+      JscpdPresentedFinding["occurrences"][0],
+      JscpdPresentedFinding["occurrences"][1],
+    ],
+  });
+}
+
+function presentChangedFinding(
+  pair: JscpdScanReport["clonePairs"][number],
+  changedFiles: ReadonlySet<string>,
+): JscpdChangedFinding {
+  const occurrences = pair.occurrences.map((occurrence) =>
+    Object.freeze({
+      path: boundedJscpdDisplayPath(occurrence.path),
+      startLine: occurrence.start.line,
+      endLine: occurrence.end.line,
+      relation: changedFiles.has(occurrence.path) ? "new-session" : "existing-match",
+    }),
+  ) as [JscpdChangedFinding["occurrences"][0], JscpdChangedFinding["occurrences"][1]];
+  return Object.freeze({
+    format: pair.format,
+    lines: pair.lines,
+    tokens: pair.tokens,
+    occurrences: Object.freeze(occurrences),
+  });
+}
+
+function plural(count: number, singular: string): string {
+  return `${count} ${singular}${count === 1 ? "" : "s"}`;
+}
+
+function formatPercentage(value: number): string {
+  return `${Number(value.toFixed(2))}%`;
+}