@claudiu-ceia/spatch 0.2.0

package/src/index.ts

@@ -0,0 +1,21 @@
+export {
+  patchProject,
+  spatch,
+} from "./spatch.ts";
+export type {
+  SpatchFileResult,
+  SpatchOccurrence,
+  SpatchOptions,
+  SpatchResult,
+} from "./types.ts";
+export {
+  DEFAULT_EXCLUDED_DIRECTORIES,
+  DEFAULT_PATCHABLE_EXTENSIONS,
+} from "./types.ts";
+
+export {
+  formatPatchOutput,
+  patchCommand,
+  runPatchCommand,
+} from "./command.ts";
+export type { PatchCommandFlags } from "./command.ts";

package/src/patch-document.ts

@@ -0,0 +1,133 @@
+import {
+  any,
+  eof,
+  formatErrorCompact,
+  many,
+  map,
+  optional,
+  regex as parseRegex,
+  seq,
+  str,
+} from "@claudiu-ceia/combine";
+
+export type ParsedPatchDocument = {
+  pattern: string;
+  replacement: string;
+  additions: number;
+  deletions: number;
+  contextLines: number;
+  trailingNewline: boolean;
+};
+
+type ParsedPatchLine =
+  | { kind: "context"; value: string }
+  | { kind: "addition"; value: string }
+  | { kind: "deletion"; value: string };
+
+const lineContentParser = parseRegex(/[^\n]*/, "line content");
+
+const escapedMarkerLineParser = map(
+  seq(str("\\"), any(str("+"), str("-")), lineContentParser),
+  ([, marker, content]) => ({
+    kind: "context",
+    value: `${marker}${content}`,
+  } satisfies ParsedPatchLine),
+);
+
+const additionLineParser = map(
+  seq(str("+"), lineContentParser),
+  ([, content]) => ({ kind: "addition", value: content } satisfies ParsedPatchLine),
+);
+
+const deletionLineParser = map(
+  seq(str("-"), lineContentParser),
+  ([, content]) => ({ kind: "deletion", value: content } satisfies ParsedPatchLine),
+);
+
+const contextLineParser = map(
+  lineContentParser,
+  (content) => ({ kind: "context", value: content } satisfies ParsedPatchLine),
+);
+
+const patchLineParser = any(
+  escapedMarkerLineParser,
+  additionLineParser,
+  deletionLineParser,
+  contextLineParser,
+);
+
+const patchDocumentParser = map(
+  seq(
+    patchLineParser,
+    many(map(seq(str("\n"), patchLineParser), ([, line]) => line)),
+    optional(str("\n")),
+    eof(),
+  ),
+  ([firstLine, remainingLines, trailingNewline]) => ({
+    lines: [firstLine, ...remainingLines],
+    trailingNewline: trailingNewline !== null,
+  }),
+);
+
+export function parsePatchDocument(source: string): ParsedPatchDocument {
+  if (source.length === 0) {
+    throw new Error("Patch document cannot be empty.");
+  }
+
+  const normalized = source.replaceAll("\r\n", "\n");
+  const trailingNewline = normalized.endsWith("\n");
+  const parsed = patchDocumentParser({ text: normalized, index: 0 });
+  if (!parsed.success) {
+    throw new Error(`Invalid patch document: ${formatErrorCompact(parsed)}`);
+  }
+
+  const lines =
+    trailingNewline &&
+    parsed.value.lines.length > 0 &&
+    parsed.value.lines[parsed.value.lines.length - 1]?.kind === "context" &&
+    parsed.value.lines[parsed.value.lines.length - 1]?.value === ""
+      ? parsed.value.lines.slice(0, -1)
+      : parsed.value.lines;
+
+  const patternLines: string[] = [];
+  const replacementLines: string[] = [];
+  let additions = 0;
+  let deletions = 0;
+  let contextLines = 0;
+
+  for (const line of lines) {
+    if (line.kind === "context") {
+      patternLines.push(line.value);
+      replacementLines.push(line.value);
+      contextLines += 1;
+      continue;
+    }
+
+    if (line.kind === "addition") {
+      replacementLines.push(line.value);
+      additions += 1;
+      continue;
+    }
+
+    patternLines.push(line.value);
+    deletions += 1;
+  }
+
+  if (additions === 0 && deletions === 0) {
+    throw new Error(
+      "Patch document must contain at least one '+' or '-' line.",
+    );
+  }
+
+  const pattern = patternLines.join("\n");
+  const replacement = replacementLines.join("\n");
+
+  return {
+    pattern: trailingNewline ? `${pattern}\n` : pattern,
+    replacement: trailingNewline ? `${replacement}\n` : replacement,
+    additions,
+    deletions,
+    contextLines,
+    trailingNewline,
+  };
+}

package/src/phases/output.ts

@@ -0,0 +1,25 @@
+import type { SpatchResult } from "../types.ts";
+import type { ParsedPatchSpec } from "./parse.ts";
+import type { RewritePhaseResult } from "./rewrite.ts";
+
+export type OutputPhaseInput = {
+  patch: ParsedPatchSpec;
+  rewrite: RewritePhaseResult;
+  elapsedMs: number;
+};
+
+export function buildSpatchResult(input: OutputPhaseInput): SpatchResult {
+  return {
+    dryRun: input.rewrite.dryRun,
+    scope: input.rewrite.scope,
+    pattern: input.patch.pattern,
+    replacement: input.patch.replacement,
+    filesScanned: input.rewrite.filesScanned,
+    filesMatched: input.rewrite.filesMatched,
+    filesChanged: input.rewrite.filesChanged,
+    totalMatches: input.rewrite.totalMatches,
+    totalReplacements: input.rewrite.totalReplacements,
+    elapsedMs: input.elapsedMs,
+    files: input.rewrite.files,
+  };
+}

package/src/phases/parse.ts

@@ -0,0 +1,33 @@
+import { resolveTextInput } from "@claudiu-ceia/astkit-core";
+import { parsePatchDocument } from "../patch-document.ts";
+import type { SpatchOptions } from "../types.ts";
+
+export type ParsedPatchSpec = {
+  pattern: string;
+  replacement: string;
+};
+
+export type ParsedPatchInvocation = {
+  patch: ParsedPatchSpec;
+  options: SpatchOptions;
+};
+
+export function parsePatchSpec(patchDocument: string): ParsedPatchSpec {
+  const parsed = parsePatchDocument(patchDocument);
+  return {
+    pattern: parsed.pattern,
+    replacement: parsed.replacement,
+  };
+}
+
+export async function parsePatchInvocation(
+  patchInput: string,
+  options: SpatchOptions = {},
+): Promise<ParsedPatchInvocation> {
+  const patchDocument = await resolveTextInput(patchInput, options);
+
+  return {
+    patch: parsePatchSpec(patchDocument),
+    options,
+  };
+}

package/src/phases/rewrite.ts

@@ -0,0 +1,287 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  compileTemplate,
+  ELLIPSIS_CAPTURE_PREFIX,
+  findTemplateMatches,
+  renderTemplate,
+  collectPatchableFiles,
+  createLineStarts,
+  formatMs,
+  mapLimit,
+  nowNs,
+  nsToMs,
+  toLineCharacter,
+} from "@claudiu-ceia/astkit-core";
+import type { SpatchFileResult, SpatchOptions } from "../types.ts";
+import type { ParsedPatchSpec } from "./parse.ts";
+
+export type RewritePhaseResult = {
+  cwd: string;
+  scope: string;
+  dryRun: boolean;
+  filesScanned: number;
+  filesMatched: number;
+  filesChanged: number;
+  totalMatches: number;
+  totalReplacements: number;
+  files: SpatchFileResult[];
+};
+
+type RewritePerfStats = {
+  filesRead: number;
+  readNs: bigint;
+  matchNs: bigint;
+  renderNs: bigint;
+  applyNs: bigint;
+  writeNs: bigint;
+  matchedFiles: number;
+  totalMatches: number;
+  totalReplacements: number;
+};
+
+export async function rewriteProject(
+  patch: ParsedPatchSpec,
+  options: SpatchOptions,
+): Promise<RewritePhaseResult> {
+  const verbose = options.verbose ?? 0;
+  const log = options.logger ?? (() => {});
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const scope = options.scope ?? ".";
+  const dryRun = options.dryRun ?? false;
+  const encoding = options.encoding ?? "utf8";
+  const concurrency = options.concurrency ?? 8;
+  const resolvedScope = path.resolve(cwd, scope);
+  const compileStarted = verbose > 0 ? nowNs() : 0n;
+  const compiledPattern = compileTemplate(patch.pattern);
+  if (verbose > 0) {
+    log(
+      `[spatch] compilePattern ${formatMs(nsToMs(nowNs() - compileStarted))}`,
+    );
+  }
+
+  const collectStarted = verbose > 0 ? nowNs() : 0n;
+  const files = await collectPatchableFiles({
+    cwd,
+    scope,
+    extensions: options.extensions,
+    excludedDirectories: options.excludedDirectories,
+  });
+  if (verbose > 0) {
+    log(
+      `[spatch] collectFiles ${formatMs(nsToMs(nowNs() - collectStarted))} files=${files.length}`,
+    );
+  }
+
+  const slowFiles: Array<{ file: string; ms: number; matches: number; replacements: number }> =
+    [];
+  const stats: RewritePerfStats = {
+    filesRead: 0,
+    readNs: 0n,
+    matchNs: 0n,
+    renderNs: 0n,
+    applyNs: 0n,
+    writeNs: 0n,
+    matchedFiles: 0,
+    totalMatches: 0,
+    totalReplacements: 0,
+  };
+  const rewriteStarted = verbose > 0 ? nowNs() : 0n;
+  const results = await mapLimit(
+    files,
+    async (filePath) => {
+      const perFileStarted = verbose >= 2 ? nowNs() : 0n;
+      const fileResult = await rewriteFile({
+        cwd,
+        filePath,
+        replacementTemplate: patch.replacement,
+        compiledPattern,
+        encoding,
+        dryRun,
+        stats: verbose > 0 ? stats : undefined,
+      });
+      if (verbose >= 2 && fileResult) {
+        slowFiles.push({
+          file: fileResult.file,
+          ms: nsToMs(nowNs() - perFileStarted),
+          matches: fileResult.matchCount,
+          replacements: fileResult.replacementCount,
+        });
+      }
+      return fileResult;
+    },
+    { concurrency },
+  );
+  if (verbose > 0) {
+    log(
+      `[spatch] rewriteFiles ${formatMs(nsToMs(nowNs() - rewriteStarted))} concurrency=${concurrency} dryRun=${dryRun}`,
+    );
+    log(
+      `[spatch] breakdown read=${formatMs(nsToMs(stats.readNs))} match=${formatMs(nsToMs(stats.matchNs))} render=${formatMs(nsToMs(stats.renderNs))} apply=${formatMs(nsToMs(stats.applyNs))} write=${formatMs(nsToMs(stats.writeNs))}`,
+    );
+  }
+
+  let filesMatched = 0;
+  let filesChanged = 0;
+  let totalMatches = 0;
+  let totalReplacements = 0;
+  const fileResults: SpatchFileResult[] = [];
+  for (const fileResult of results) {
+    if (!fileResult) {
+      continue;
+    }
+
+    filesMatched += 1;
+    totalMatches += fileResult.matchCount;
+    totalReplacements += fileResult.replacementCount;
+    if (fileResult.changed) {
+      filesChanged += 1;
+    }
+
+    fileResults.push(fileResult);
+  }
+
+  if (verbose >= 2 && slowFiles.length > 0) {
+    slowFiles.sort((a, b) => b.ms - a.ms);
+    for (const entry of slowFiles.slice(0, 10)) {
+      log(
+        `[spatch] slowFile ${formatMs(entry.ms)} file=${entry.file} matches=${entry.matches} replacements=${entry.replacements}`,
+      );
+    }
+  }
+
+  if (verbose > 0) {
+    log(
+      `[spatch] summary filesScanned=${files.length} filesMatched=${filesMatched} filesChanged=${filesChanged} totalMatches=${totalMatches} totalReplacements=${totalReplacements}`,
+    );
+  }
+
+  return {
+    cwd,
+    scope: resolvedScope,
+    dryRun,
+    filesScanned: files.length,
+    filesMatched,
+    filesChanged,
+    totalMatches,
+    totalReplacements,
+    files: fileResults,
+  };
+}
+
+type RewriteFileInput = {
+  cwd: string;
+  filePath: string;
+  replacementTemplate: string;
+  compiledPattern: ReturnType<typeof compileTemplate>;
+  encoding: BufferEncoding;
+  dryRun: boolean;
+  stats?: RewritePerfStats;
+};
+
+async function rewriteFile(
+  input: RewriteFileInput,
+): Promise<SpatchFileResult | null> {
+  const readStarted = input.stats ? nowNs() : 0n;
+  const originalText = await readFile(input.filePath, input.encoding);
+  if (input.stats) {
+    input.stats.filesRead += 1;
+    input.stats.readNs += nowNs() - readStarted;
+  }
+
+  const matchStarted = input.stats ? nowNs() : 0n;
+  const matches = findTemplateMatches(originalText, input.compiledPattern);
+  if (input.stats) {
+    input.stats.matchNs += nowNs() - matchStarted;
+  }
+  if (matches.length === 0) {
+    return null;
+  }
+
+  const lineStarts = createLineStarts(originalText);
+  const renderStarted = input.stats ? nowNs() : 0n;
+  const occurrences = matches.map((match) => {
+    const rendered = renderTemplate(input.replacementTemplate, match.captures);
+    const { line, character } = toLineCharacter(lineStarts, match.start);
+    return {
+      start: match.start,
+      end: match.end,
+      line,
+      character,
+      matched: match.text,
+      replacement: rendered,
+      captures: filterPublicCaptures(match.captures),
+    };
+  });
+  if (input.stats) {
+    input.stats.renderNs += nowNs() - renderStarted;
+  }
+
+  const replacementCount = occurrences.reduce(
+    (count, occurrence) =>
+      count + (occurrence.matched === occurrence.replacement ? 0 : 1),
+    0,
+  );
+  const applyStarted = input.stats ? nowNs() : 0n;
+  const rewrittenText = applyOccurrences(originalText, occurrences);
+  if (input.stats) {
+    input.stats.applyNs += nowNs() - applyStarted;
+  }
+  const changed = rewrittenText !== originalText;
+
+  if (changed && !input.dryRun) {
+    const writeStarted = input.stats ? nowNs() : 0n;
+    await writeFile(input.filePath, rewrittenText, input.encoding);
+    if (input.stats) {
+      input.stats.writeNs += nowNs() - writeStarted;
+    }
+  }
+
+  if (input.stats) {
+    input.stats.matchedFiles += 1;
+    input.stats.totalMatches += matches.length;
+    input.stats.totalReplacements += replacementCount;
+  }
+
+  return {
+    file: path.relative(input.cwd, input.filePath) || path.basename(input.filePath),
+    matchCount: matches.length,
+    replacementCount,
+    changed,
+    byteDelta: changed
+      ? Buffer.byteLength(rewrittenText, input.encoding) -
+        Buffer.byteLength(originalText, input.encoding)
+      : 0,
+    occurrences,
+  };
+}
+
+function filterPublicCaptures(
+  captures: Record<string, string>,
+): Record<string, string> {
+  const entries = Object.entries(captures).filter(
+    ([name]) => !name.startsWith(ELLIPSIS_CAPTURE_PREFIX),
+  );
+  return Object.fromEntries(entries);
+}
+
+function applyOccurrences(
+  source: string,
+  occurrences: ReadonlyArray<{ start: number; end: number; replacement: string }>,
+): string {
+  if (occurrences.length === 0) {
+    return source;
+  }
+
+  const parts: string[] = [];
+  let cursor = 0;
+
+  for (const occurrence of occurrences) {
+    parts.push(source.slice(cursor, occurrence.start));
+    parts.push(occurrence.replacement);
+    cursor = occurrence.end;
+  }
+
+  parts.push(source.slice(cursor));
+  return parts.join("");
+}

package/src/spatch.ts

@@ -0,0 +1,32 @@
+import { buildSpatchResult } from "./phases/output.ts";
+import {
+  parsePatchInvocation,
+  type ParsedPatchSpec,
+} from "./phases/parse.ts";
+import { rewriteProject } from "./phases/rewrite.ts";
+import type { SpatchOptions, SpatchResult } from "./types.ts";
+
+export async function patchProject(
+  patchInput: string,
+  options: SpatchOptions = {},
+): Promise<SpatchResult> {
+  const invocation = await parsePatchInvocation(patchInput, options);
+
+  return runPatchPhases(invocation.patch, invocation.options);
+}
+
+export const spatch = patchProject;
+
+async function runPatchPhases(
+  patch: ParsedPatchSpec,
+  options: SpatchOptions,
+): Promise<SpatchResult> {
+  const startedAt = Date.now();
+
+  const rewrite = await rewriteProject(patch, options);
+  return buildSpatchResult({
+    patch,
+    rewrite,
+    elapsedMs: Date.now() - startedAt,
+  });
+}

package/src/template.ts

@@ -0,0 +1,2 @@
+export { compileTemplate, findTemplateMatches, renderTemplate } from "@claudiu-ceia/astkit-core";
+export type { CompiledTemplate, TemplateMatch } from "@claudiu-ceia/astkit-core";

package/src/types.ts

@@ -0,0 +1,49 @@
+export {
+  DEFAULT_EXCLUDED_DIRECTORIES,
+  DEFAULT_SOURCE_EXTENSIONS as DEFAULT_PATCHABLE_EXTENSIONS,
+} from "@claudiu-ceia/astkit-core";
+
+export type SpatchOptions = {
+  scope?: string;
+  cwd?: string;
+  dryRun?: boolean;
+  extensions?: readonly string[];
+  excludedDirectories?: readonly string[];
+  encoding?: BufferEncoding;
+  concurrency?: number;
+  verbose?: number;
+  logger?: (line: string) => void;
+};
+
+export type SpatchOccurrence = {
+  start: number;
+  end: number;
+  line: number;
+  character: number;
+  matched: string;
+  replacement: string;
+  captures: Record<string, string>;
+};
+
+export type SpatchFileResult = {
+  file: string;
+  matchCount: number;
+  replacementCount: number;
+  changed: boolean;
+  byteDelta: number;
+  occurrences: SpatchOccurrence[];
+};
+
+export type SpatchResult = {
+  dryRun: boolean;
+  scope: string;
+  pattern: string;
+  replacement: string;
+  filesScanned: number;
+  filesMatched: number;
+  filesChanged: number;
+  totalMatches: number;
+  totalReplacements: number;
+  elapsedMs: number;
+  files: SpatchFileResult[];
+};