@claudiu-ceia/spatch 0.2.0 → 0.3.1

package/README.md

@@ -1,180 +1,256 @@
 # spatch
 
-`spatch` applies structural rewrites using a patch document.
+Deterministic structural rewrites for TypeScript/JavaScript using a compact patch-document format.
 
-A patch document is a text block where:
-- `-` lines define what to match
-- `+` lines define what to insert
-- other lines are context shared by both sides
+`spatch` lets you describe a code change once and apply it safely across a scoped project.
 
-You can pass the patch document either:
-- inline as a string
-- as a file path
+## Contents
 
-## CLI
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Patch document format](#patch-document-format)
+- [Metavariables](#metavariables)
+- [Matching and formatting behavior](#matching-and-formatting-behavior)
+- [CLI](#cli)
+- [Output modes](#output-modes)
+- [Scope and safety model](#scope-and-safety-model)
+- [API](#api)
+- [Caveats](#caveats)
+- [Development](#development)
+
+## Install
 
 ```bash
-spatch <patch-input> [scope] [--cwd <path>] [--dry-run] [--json] [--no-color] [--interactive]
-# or:
-astkit patch <patch-input> [scope] [--cwd <path>] [--dry-run] [--json] [--no-color] [--interactive]
+npm install --save-dev @claudiu-ceia/spatch
 ```
 
-Examples:
+Or run directly:
 
 ```bash
-# patch document from file
-spatch rules/const-to-let.spatch src --cwd /repo
+npx @claudiu-ceia/spatch --help
+```
 
-# inline patch document
-spatch $'-const :[name] = :[value];\n+let :[name] = :[value];' src
+In this monorepo during development:
 
-# preview only
-spatch rules/const-to-let.spatch src --dry-run
+```bash
+bun run spatch -- --help
+```
 
-# structured JSON output
-spatch rules/const-to-let.spatch src --json
+## Quickstart
 
-# interactive apply mode
-spatch rules/const-to-let.spatch src --interactive
+Create a patch file:
+
+```spatch
+-const :[name] = :[value];
++let :[name] = :[value];
 ```
 
-## API
+Preview:
 
-```ts
-import { patchProject } from "@claudiu-ceia/spatch";
+```bash
+spatch rules/const-to-let.spatch src --dry-run
+```
 
-await patchProject(patchInput, {
-  cwd: "/repo",       // optional, default process.cwd()
-  scope: "src",       // file or directory, default "."
-  dryRun: false,       // default false
-  encoding: "utf8",   // default utf8
-});
+Apply:
+
+```bash
+spatch rules/const-to-let.spatch src
+```
+
+CI guardrail:
+
+```bash
+spatch rules/const-to-let.spatch src --check
 ```
 
-`patchInput` can be:
-- a patch document string
-- a path to a patch file (resolved from `cwd`)
+## Patch document format
+
+A patch document is line-based:
+
+- `-...` deletion line: belongs to the match pattern only
+- `+...` addition line: belongs to the replacement only
+- ` ...` context line: shared by both pattern and replacement
+- `\-...` and `\+...` escaped markers: treated as literal context starting with `-` or `+`
 
-## Patch Document Grammar
+At least one `-` or `+` line is required.
 
-### Line kinds
+If the patch document ends with a trailing newline, generated pattern/replacement keep that trailing newline.
 
-- `-...`: deletion line (belongs to match pattern only)
-- `+...`: addition line (belongs to replacement only)
-- ` ...`: context line (belongs to both pattern and replacement)
-- `\-...` and `\+...`: escaped marker lines, treated as literal context starting with `-` or `+`
+You can pass patch input as:
 
-### Minimum change rule
+- inline patch text
+- a patch file path
+- `-` to read from stdin
 
-A patch document must contain at least one `-` line or one `+` line.
+Examples:
+
+```bash
+# file input
+spatch rules/rename.spatch src
 
-### Newline behavior
+# stdin input
+cat rules/rename.spatch | spatch - src
 
-If the patch document ends with a trailing newline, both generated `pattern` and `replacement` preserve it.
+# inline input (bash/zsh)
+spatch $'-foo(:[x])\n+bar(:[x])' src
+```
 
 ## Metavariables
 
-Inside pattern/replacement text, holes use this syntax:
+Supported placeholders:
 
-- `:[name]`
-- `:[_]` (anonymous hole, not captured)
-- `:[name~regex]` (capture must satisfy regex)
-- `...` (variadic wildcard; captured and reusable in replacement)
+- `:[name]` named capture
+- `:[_]` anonymous wildcard (not captured)
+- `:[name~regex]` named capture constrained by regex
+- `...` variadic wildcard, reusable in replacement
 
 Examples:
 
-```text
--const :[name] = :[value];
+```spatch
+-const :[name~[a-zA-Z_$][\w$]*] = :[value];
 +let :[name] = :[value];
 ```
 
-```text
--const :[name~[a-z]+] = :[value~\d+];
-+let :[name] = Number(:[value]);
+```spatch
+-transform(:[input], :[config], ...);
++normalize(:[input], :[config], ...);
 ```
 
-Repeated holes enforce equality:
+Repeated names enforce equality:
 
-```text
--:[x] + :[x];
-+double(:[x]);
+```spatch
+-:[x] + :[x]
++double(:[x])
 ```
 
-`foo + foo` matches, `foo + bar` does not.
+Regex constraint safety limits:
 
-Variadic example:
+- max regex constraint length: `256` characters
+- disallowed in constraints: lookarounds, backreferences, nested quantified groups (for example `([a-z]+)+`)
+- constrained captures longer than `2048` characters are rejected during matching
 
-```text
--foo(:[x], ...);
-+bar(:[x], ...);
-```
+## Matching and formatting behavior
+
+`spatch` matches structurally, not by raw text equality.
+
+- matching is trivia-insensitive between lexemes (whitespace/comments can differ)
+- captures are structurally balanced (parens/brackets/braces, strings, comments)
+- `...` captures variadic middle segments
 
-Rewrites the callee and preserves remaining arguments.
+Formatting behavior:
 
-## How It Works
+- if replacement has the same lexical shape, original trivia layout is preserved
+- if replacement changes lexical shape, output follows replacement template layout
 
-### 1) Parse phase
+Example: a single-line pattern can match multi-line code without reformatting the whole block.
 
-`patchProject` resolves `patchInput` into a patch document and parses it into:
-- `pattern`
-- `replacement`
+```spatch
+-transform(:[input], :[config], ...);
++normalize(:[input], :[config], ...);
+```
+
+Example rewrite result:
+
+```ts
+// source
+const call = transform(source /* keep comment */, cfg, optA, optB);
 
-### 2) Rewrite phase
+// after spatch
+const call = normalize(source /* keep comment */, cfg, optA, optB);
+```
 
-For each scoped file:
-- compile template tokens from `pattern`
-- find all structural matches
-- render `replacement` with captures
-- apply replacements
-- optionally write file (skipped in `dryRun`)
+## CLI
 
-### 3) Output phase
+```bash
+spatch [--concurrency n] [--verbose level] [--interactive] [--json] [--no-color] [--dry-run] [--check] [--cwd path] <patch> [scope]
+spatch --help
+```
 
-Return an aggregate result:
-- files scanned/matched/changed
-- match and replacement counts
-- elapsed time
-- per-file occurrences with spans and captures
+Flags:
 
-## Structural Balancing
+- `--dry-run`: preview changes without writing files
+- `--check`: fail with non-zero exit if replacements would be made (implies dry-run)
+- `--interactive`: confirm each change (`y/n/a/q`)
+- `--json`: emit structured JSON result
+- `--no-color`: disable colored output
+- `--cwd <path>`: working directory used to resolve patch input and scope
+- `--concurrency <n>`: max files processed in parallel (default `8`)
+- `--verbose <level>`: perf tracing (`1` summary, `2` includes slow files)
 
-Hole captures are checked for structural balance to avoid malformed partial captures.
+Notes:
 
-Balanced constructs supported in capture chunks:
-- parentheses `(...)`
-- brackets `[...]`
-- braces `{...}`
-- single/double/template strings
-- line and block comments
+- `--interactive` cannot be combined with `--dry-run` or `--check`
+- run `spatch --help` for the generated stricli help text
 
-## End-to-End Example
+## Output modes
 
-Patch document:
+Default output is compact diff-style text plus a summary.
 
 ```text
-function wrap() {
--  const value = :[value];
-+  let value = :[value];
-   return value;
-}
+diff --git a/src/a.ts b/src/a.ts
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -10,1 +10,1 @@
+-foo(x)
++bar(x)
+1 file changed, 1 replacement, (dry-run)
 ```
 
-Call:
+`--json` returns the full `SpatchResult` object for automation.
+
+## Scope and safety model
+
+Scope boundary:
+
+- if `cwd` is inside a git repository, scope must stay within the nearest repo root
+- if no git repo root is found, scope must stay within `cwd`
+
+Write safety:
+
+- non-interactive apply uses stale-content checks and atomic temp-file rename writes
+- interactive mode re-validates selected spans, then writes through the same stale-safe atomic path
+
+This makes `--check` suitable for CI and agent workflows.
+
+## API
 
 ```ts
-await patchProject("rules/wrap.spatch", { cwd: "/repo", scope: "src" });
+import { patchProject } from "@claudiu-ceia/spatch";
+
+const result = await patchProject("rules/const-to-let.spatch", {
+  cwd: "/repo",
+  scope: "src",
+  dryRun: true,
+  encoding: "utf8",
+  concurrency: 8,
+  verbose: 1,
+  logger: console.error,
+});
+
+console.log(result.totalReplacements);
 ```
 
-## Flow Diagram
+`patchInput` can be patch text or a patch file path.
 
-```text
-patchProject(patchInput, options)
-  -> parsePatchInvocation
-      -> resolve patch text (inline or file)
-      -> parsePatchDocument (+/-/context)
-  -> rewriteProject
-      -> compileTemplate(pattern)
-      -> collect files
-      -> for each file: match -> render -> apply -> (write)
-  -> buildSpatchResult
+Exports:
+
+- `patchProject`
+- `DEFAULT_PATCHABLE_EXTENSIONS`, `DEFAULT_EXCLUDED_DIRECTORIES`
+
+## Caveats
+
+- matching is syntactic/structural, not semantic/type-aware
+- comments/whitespace are preserved by lexical slot; when reordering captures, inline comments follow slot position
+- very broad patterns can have large blast radius, use `--dry-run` and optionally `--interactive` first
+
+## Development
+
+From monorepo root:
+
+```bash
+bun run spatch -- --help
+bun run spatch -- '<patch-input>' [scope]
+npm run test:spatch
+npm run test:spatch:coverage
+npm run typecheck
 ```

package/dist/app.d.ts

@@ -0,0 +1 @@
+export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;

package/dist/app.js

@@ -0,0 +1,28 @@
+import { buildApplication, text_en } from "@stricli/core";
+import { patchCommand } from "./command.js";
+function formatCommandException(exc) {
+    if (exc instanceof Error) {
+        return exc.message.length > 0 ? `Error: ${exc.message}` : "Error";
+    }
+    return String(exc);
+}
+const text = {
+    ...text_en,
+    exceptionWhileParsingArguments: (exc) => `Unable to parse arguments, ${formatCommandException(exc)}`,
+    exceptionWhileLoadingCommandFunction: (exc) => `Unable to load command function, ${formatCommandException(exc)}`,
+    exceptionWhileLoadingCommandContext: (exc) => `Unable to load command context, ${formatCommandException(exc)}`,
+    exceptionWhileRunningCommand: (exc) => `Command failed, ${formatCommandException(exc)}`,
+};
+export const app = buildApplication(patchCommand, {
+    name: "spatch",
+    scanner: {
+        caseStyle: "original",
+    },
+    documentation: {
+        caseStyle: "original",
+    },
+    localization: {
+        defaultLocale: "en",
+        loadText: () => text,
+    },
+});

package/dist/cli.js

@@ -1,120 +1,4 @@
 #!/usr/bin/env node
-import { formatPatchOutput, runPatchCommand } from "./command.js";
-function parsePositiveInteger(name, raw) {
-    const value = Number(raw);
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new Error(`${name} must be a positive number`);
-    }
-    return Math.floor(value);
-}
-function readFlagValue(argv, index) {
-    const token = argv[index];
-    if (!token) {
-        throw new Error("Missing flag token");
-    }
-    const eqIndex = token.indexOf("=");
-    if (eqIndex >= 0) {
-        const value = token.slice(eqIndex + 1);
-        if (value.length === 0) {
-            throw new Error(`Missing value for ${token.slice(0, eqIndex)}`);
-        }
-        return { value, consumed: 1 };
-    }
-    const next = argv[index + 1];
-    if (!next) {
-        throw new Error(`Missing value for ${token}`);
-    }
-    return { value: next, consumed: 2 };
-}
-function printHelp() {
-    process.stdout.write([
-        "spatch - structural patch for TS/JS",
-        "",
-        "Usage:",
-        "  spatch [--dry-run] [--interactive] [--json] [--no-color] [--cwd <path>] <patch-input> [scope]",
-        "",
-        "Flags:",
-        "  --dry-run            Preview changes without writing files",
-        "  --interactive        Interactively select which matches to apply",
-        "  --json               Output structured JSON",
-        "  --no-color           Disable colored output",
-        "  --cwd <path>         Working directory for resolving patch and scope",
-        "  --concurrency <n>    Max files processed concurrently (default: 8)",
-        "  --verbose <level>    Perf tracing to stderr (1=summary, 2=slow files)",
-        "",
-    ].join("\n"));
-}
-const argv = process.argv.slice(2);
-if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-    printHelp();
-    process.exit(0);
-}
-const flags = {};
-const positional = [];
-for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i];
-    if (!token)
-        continue;
-    if (!token.startsWith("-")) {
-        positional.push(token);
-        continue;
-    }
-    if (token === "--dry-run") {
-        flags["dry-run"] = true;
-        continue;
-    }
-    if (token === "--interactive") {
-        flags.interactive = true;
-        continue;
-    }
-    if (token === "--json") {
-        flags.json = true;
-        continue;
-    }
-    if (token === "--no-color") {
-        flags["no-color"] = true;
-        continue;
-    }
-    if (token === "--cwd" || token.startsWith("--cwd=")) {
-        const { value, consumed } = readFlagValue(argv, i);
-        flags.cwd = value;
-        i += consumed - 1;
-        continue;
-    }
-    if (token === "--concurrency" || token.startsWith("--concurrency=")) {
-        const { value, consumed } = readFlagValue(argv, i);
-        flags.concurrency = parsePositiveInteger("--concurrency", value);
-        i += consumed - 1;
-        continue;
-    }
-    if (token === "--verbose" || token.startsWith("--verbose=")) {
-        const { value, consumed } = readFlagValue(argv, i);
-        const level = Number(value);
-        if (!Number.isFinite(level) || level < 0) {
-            throw new Error("--verbose must be a non-negative number");
-        }
-        flags.verbose = Math.floor(level);
-        i += consumed - 1;
-        continue;
-    }
-    throw new Error(`Unknown flag: ${token}`);
-}
-const patchInput = positional[0];
-const scope = positional[1];
-if (!patchInput) {
-    printHelp();
-    process.exit(1);
-}
-if (positional.length > 2) {
-    throw new Error("Too many positional arguments.");
-}
-const result = await runPatchCommand(patchInput, scope, flags);
-if (flags.json ?? false) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-else {
-    const output = formatPatchOutput(result, {
-        color: Boolean(process.stdout.isTTY) && !(flags["no-color"] ?? false),
-    });
-    process.stdout.write(`${output}\n`);
-}
+import { run } from "@stricli/core";
+import { app } from "./app.js";
+await run(app, process.argv.slice(2), { process });

package/dist/command/flags.d.ts

@@ -0,0 +1,64 @@
+export type PatchCommandFlags = {
+    "dry-run"?: boolean;
+    check?: boolean;
+    interactive?: boolean;
+    json?: boolean;
+    "no-color"?: boolean;
+    cwd?: string;
+    concurrency?: number;
+    verbose?: number;
+};
+export declare const patchCommandFlagParameters: {
+    readonly concurrency: {
+        readonly kind: "parsed";
+        readonly optional: true;
+        readonly brief: "Max files processed concurrently (default: 8)";
+        readonly placeholder: "n";
+        readonly parse: (input: string) => number;
+    };
+    readonly verbose: {
+        readonly kind: "parsed";
+        readonly optional: true;
+        readonly brief: "Print perf tracing (1=summary, 2=includes slow files)";
+        readonly placeholder: "level";
+        readonly parse: (input: string) => number;
+    };
+    readonly interactive: {
+        readonly kind: "boolean";
+        readonly optional: true;
+        readonly withNegated: false;
+        readonly brief: "Interactively select which matches to apply";
+    };
+    readonly json: {
+        readonly kind: "boolean";
+        readonly optional: true;
+        readonly withNegated: false;
+        readonly brief: "Output structured JSON instead of compact diff-style text";
+    };
+    readonly "no-color": {
+        readonly kind: "boolean";
+        readonly optional: true;
+        readonly withNegated: false;
+        readonly brief: "Disable colored output";
+    };
+    readonly "dry-run": {
+        readonly kind: "boolean";
+        readonly optional: true;
+        readonly withNegated: false;
+        readonly brief: "Preview changes without writing files";
+    };
+    readonly check: {
+        readonly kind: "boolean";
+        readonly optional: true;
+        readonly withNegated: false;
+        readonly brief: "Exit non-zero if changes would be made (implies --dry-run)";
+    };
+    readonly cwd: {
+        readonly kind: "parsed";
+        readonly optional: true;
+        readonly brief: "Working directory for resolving patch file and scope";
+        readonly placeholder: "path";
+        readonly parse: (input: string) => string;
+    };
+};
+export declare function validatePatchCommandFlags(flags: PatchCommandFlags): void;

package/dist/command/flags.js

@@ -0,0 +1,73 @@
+export const patchCommandFlagParameters = {
+    concurrency: {
+        kind: "parsed",
+        optional: true,
+        brief: "Max files processed concurrently (default: 8)",
+        placeholder: "n",
+        parse: (input) => {
+            const value = Number(input);
+            if (!Number.isFinite(value) || value <= 0) {
+                throw new Error("--concurrency must be a positive number");
+            }
+            return Math.floor(value);
+        },
+    },
+    verbose: {
+        kind: "parsed",
+        optional: true,
+        brief: "Print perf tracing (1=summary, 2=includes slow files)",
+        placeholder: "level",
+        parse: (input) => {
+            const value = Number(input);
+            if (!Number.isFinite(value) || value < 0) {
+                throw new Error("--verbose must be a non-negative number");
+            }
+            return Math.floor(value);
+        },
+    },
+    interactive: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Interactively select which matches to apply",
+    },
+    json: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Output structured JSON instead of compact diff-style text",
+    },
+    "no-color": {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Disable colored output",
+    },
+    "dry-run": {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Preview changes without writing files",
+    },
+    check: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Exit non-zero if changes would be made (implies --dry-run)",
+    },
+    cwd: {
+        kind: "parsed",
+        optional: true,
+        brief: "Working directory for resolving patch file and scope",
+        placeholder: "path",
+        parse: (input) => input,
+    },
+};
+export function validatePatchCommandFlags(flags) {
+    if ((flags.interactive ?? false) && (flags["dry-run"] ?? false)) {
+        throw new Error("Cannot combine --interactive with --dry-run.");
+    }
+    if ((flags.interactive ?? false) && (flags.check ?? false)) {
+        throw new Error("Cannot combine --interactive with --check.");
+    }
+}

package/dist/command/interactive/path-resolution.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveInteractiveFilePath(file: string, options: {
+    cwd: string;
+    scope: string;
+    scopeKind: "file" | "directory";
+}): Promise<string>;