@zgeoff/format-codemod 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoff Whatley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @zgeoff/format-codemod
+
+Enforce a small set of blank-line padding conventions in TypeScript via a fast text-splice codemod.
+It parses each file once with [oxc-parser](https://oxc.rs) (native, so parsing is effectively free),
+plans positional whitespace splices from node and comment spans, and skips type-aware analysis, so
+it runs far faster than a full lint pass — fast enough to sit in a pre-commit hook or a `format`
+pipeline without being noticed.
+
+## Rules implemented
+
+Mirrors a subset of ESLint's `padding-line-between-statements` plus
+`@stylistic/lines-between-class-members`. Every rule is "always exactly one blank line"; there are
+no "never" rules.
+
+**`padding-line-between-statements`** — insert one blank line:
+
+- after a `const`/`let`/`var` block, before any non-var statement
+- before any `return`
+- after a `function` or `class` declaration
+- on both sides of a control-flow block: `if`, `for`, `for…in`, `for…of`, `while`, `switch`, `try`
+- on both sides of any statement that spans multiple lines
+- at the boundary between statement kinds — a `const`/`let`/`var` declaration, a call statement, an
+  assignment/increment statement — in any order; runs of one kind stay tight
+- at the boundary between an instantiation-headed statement (`new` at the head of its expression
+  chain, as in `new X(…)` or `new X(…).method()`) and any other statement kind — `new` in argument
+  position doesn't count, and runs of instantiations stay glued
+
+**`@stylistic/lines-between-class-members`** — one blank line between class members.
+
+### Notes
+
+- **Consecutive single-line `const`/`let`/`var` declarations stay glued** (no blank between them); a
+  multiline declaration is separated like any other multiline statement.
+- **Bare declarations only.** `export const`, `export function`, and `export class` are not matched
+  — ESLint's selectors do not look through `export`, and neither does this. `await using` is
+  likewise not a var declaration.
+- **`.d.ts` files are skipped.**
+
+## CLI
+
+```bash
+format-codemod [options] <file|dir|glob> ...
+
+  --check     exit 1 if any file would change; do not write
+  --dry       print unified diff to stdout; do not write
+  --bench     print parse stats as JSON to stderr
+  --quiet     only print files that would change
+  --version
+  --help
+```
+
+Flags are strict: an unknown flag is a usage error (exit 2), never a silent no-op — the default mode
+writes files, so a typo'd `--check` must not fall through to a rewrite.
+
+### Examples
+
+```bash
+format-codemod 'src/**/*.{ts,tsx}'           # rewrite in place
+format-codemod --check 'src/**/*.{ts,tsx}'   # CI gate
+format-codemod --dry path/to/file.ts         # preview diff
+format-codemod .                             # whole repo, in place
+```
+
+Globs use Node 22's built-in `fs.glob`. A literal path is resolved as a file before the glob
+heuristic runs, so bracketed names (Next.js routes like `[slug]/page.tsx`) are handled correctly
+rather than read as glob character classes. A directory argument expands to `**/*.{ts,tsx}` beneath
+it; `node_modules` and `.git` are never descended into, and overlapping patterns are deduped so a
+file is processed once.
+
+`--dry` prints a real unified diff — `@@` hunk headers with three lines of context — that applies
+cleanly with `patch(1)`.
+
+## Dialect handling
+
+The filename picks the parse dialect: `.tsx` enables JSX, everything else parses as plain
+TypeScript. That means `.ts`-only syntax — old-style type assertions (`<string>value`), un-comma'd
+generic arrows (`<T>(a: T) => a`) — parses correctly instead of being misread as JSX.
+
+## Trivia handling
+
+Comment positions come from the parser, not lexical scanning:
+
+- Trailing same-line comments stay attached to the previous statement: `const X = 1; // note` keeps
+  the blank line _after_ the comment (several same-line comments all stay together).
+- Leading comments stay attached to the next statement: the blank line goes _before_ the comment.
+- Indentation of the next statement is preserved.
+- Two statements that share a physical line are left untouched — for example a leading-semicolon
+  `;(expr)` whose `;` terminates the previous statement. A blank-only edit cannot separate them
+  without orphaning a token, so the codemod skips the pair.
+
+## Idempotent
+
+Running the codemod twice produces the same output as running it once. A run on already-compliant
+code is a no-op.
+
+## Programmatic use
+
+```ts
+import { transform } from '@zgeoff/format-codemod';
+
+const { output, edits, parseError } = transform(source, { filename: 'component.tsx' });
+// edits: number of splices applied
+// parseError: error message if the source could not be parsed; source returned untouched
+```
+
+`filename` is optional and only drives dialect selection (default `'source.ts'` — plain TypeScript,
+no JSX); nothing is read from disk.

package/dist/cli/apply-diff-mode.d.ts

@@ -0,0 +1,11 @@
+import type { CLIMode, FileEdit } from './types.ts';
+export interface DiffOutput {
+    readonly message: string | null;
+    readonly stdout: string | null;
+}
+/**
+ * Reached only when the file needs edits. Write mode saves the file here — the
+ * one file-system effect below the entry; what to print is returned, never
+ * printed, because the entry owns the output streams.
+ */
+export declare function applyDiffMode(edit: FileEdit, mode: CLIMode): DiffOutput;

package/dist/cli/build-bench-stats-from-reports.d.ts

@@ -0,0 +1,2 @@
+import type { BenchStats, FileReport } from './types.ts';
+export declare function buildBenchStatsFromReports(reports: readonly FileReport[], ms: number): BenchStats;

package/dist/cli/build-unified-diff.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A real unified diff — @@ hunk headers with context — so --dry output can be
+ * applied with patch(1). Inputs are expected to end with a newline, which
+ * TypeScript sources do and the transform preserves.
+ */
+export declare function buildUnifiedDiff(before: string, after: string, label: string): string;

package/dist/cli/check-file.d.ts

@@ -0,0 +1,2 @@
+import type { CLIMode, FileReport } from './types.ts';
+export declare function checkFile(file: string, mode: CLIMode): FileReport;

package/dist/cli/expand-inputs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Deduped: overlapping patterns (a `src/**` glob plus a file inside src/) must
+ * not process — or report — the same file twice.
+ */
+export declare function expandInputs(patterns: readonly string[]): Promise<string[]>;

package/dist/cli/parse-cli-args.d.ts

@@ -0,0 +1,16 @@
+import type { CLIMode } from './types.ts';
+export interface CLIArgs {
+    readonly mode: CLIMode;
+    readonly quiet: boolean;
+    readonly bench: boolean;
+    readonly help: boolean;
+    readonly version: boolean;
+    readonly inputs: readonly string[];
+}
+/**
+ * Strict parsing: an unknown flag is a usage error, not a silent no-op. That
+ * matters because the default mode writes files — a typo'd --check must never
+ * fall through to an in-place rewrite. CLIArgs is always an object, so the
+ * string (error message) return is unambiguous.
+ */
+export declare function parseCLIArgs(argv: readonly string[]): CLIArgs | string;

package/dist/cli/print-help.d.ts

@@ -0,0 +1 @@
+export declare function printHelp(): void;

package/dist/cli/print-report.d.ts

@@ -0,0 +1,7 @@
+import type { FileReport } from './types.ts';
+/**
+ * Prints one file's outcome: the stdout payload (--dry diffs) to stdout,
+ * messages and per-file progress to stderr. Quiet drops the OK/SKIP noise but
+ * never the messages.
+ */
+export declare function printReport(file: string, report: FileReport, quiet: boolean): void;

package/dist/cli/read-package-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads the version field of the package manifest at the given path, throwing
+ * when the file isn't a manifest. Callers own the path so it resolves against
+ * their own location.
+ */
+export declare function readPackageVersion(pkgPath: string): string;

package/dist/cli/try-check-file.d.ts

@@ -0,0 +1,7 @@
+import type { CLIMode, FileReport } from './types.ts';
+/**
+ * A failed file must fail the batch: --check would otherwise exit 0 having
+ * validated nothing, and a throw would kill the process mid-batch with the
+ * remaining files silently skipped.
+ */
+export declare function tryCheckFile(file: string, mode: CLIMode): FileReport;

package/dist/cli/types.d.ts

@@ -0,0 +1,28 @@
+import type { TransformResult } from '../types.ts';
+export type CLIMode = 'write' | 'check' | 'dry';
+export type FileOutcome = 'ok' | 'changed' | 'failed' | 'skipped';
+/**
+ * Everything the entry needs to report one file: the outcome for exit-code
+ * logic, sizes for --bench, and the text to print — modules below the entry
+ * never write to stdout/stderr themselves.
+ */
+export interface FileReport {
+    readonly outcome: FileOutcome;
+    readonly bytes: number;
+    readonly parsed: boolean;
+    readonly message: string | null;
+    readonly stdout: string | null;
+}
+export interface FileEdit {
+    readonly file: string;
+    readonly src: string;
+    readonly result: TransformResult;
+}
+export interface BenchStats {
+    readonly files: number;
+    readonly parsed: number;
+    readonly bytes: number;
+    readonly ms: number;
+    readonly us_per_file: number;
+    readonly mb_per_sec: number;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,672 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { fileURLToPath } from "node:url";
+
+// src/cli/build-bench-stats-from-reports.ts
+function buildBenchStatsFromReports(reports, ms) {
+  const bytes = reports.reduce((sum, r) => sum + r.bytes, 0);
+  const parsed = reports.filter((r) => r.parsed).length;
+  return {
+    files: reports.length,
+    parsed,
+    bytes,
+    ms,
+    us_per_file: Math.round(ms * 1000 / reports.length),
+    mb_per_sec: Math.round(bytes / 1024 / 1024 / (ms / 1000) * 10) / 10
+  };
+}
+
+// src/cli/expand-inputs.ts
+import fs from "node:fs";
+import path from "node:path";
+async function expandInputs(patterns) {
+  const lists = await Promise.all(patterns.map((p) => expandPattern(p)));
+  return [...new Set(lists.flat())];
+}
+function expandPattern(p) {
+  if (fs.existsSync(p)) {
+    if (fs.statSync(p).isDirectory()) {
+      const pattern = path.join(p, "**/*.{ts,tsx}");
+      return Array.fromAsync(fs.promises.glob(pattern, { exclude: isExcluded }));
+    }
+    return Promise.resolve([p]);
+  }
+  if (/[*?[{]/u.test(p)) {
+    return Array.fromAsync(fs.promises.glob(p, { exclude: isExcluded }));
+  }
+  return Promise.resolve([p]);
+}
+function isExcluded(entry) {
+  const p = typeof entry === "string" ? entry : path.join(entry.parentPath ?? "", entry.name);
+  return p.split(/[\\/]/u).some((seg) => seg === "node_modules" || seg === ".git");
+}
+
+// src/cli/parse-cli-args.ts
+import { parseArgs } from "node:util";
+function parseCLIArgs(argv) {
+  try {
+    const { values, positionals } = parseArgs({
+      args: [...argv],
+      options: {
+        check: { type: "boolean", default: false },
+        dry: { type: "boolean", default: false },
+        bench: { type: "boolean", default: false },
+        quiet: { type: "boolean", default: false },
+        version: { type: "boolean", default: false },
+        help: { type: "boolean", default: false }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+    return {
+      mode: pickMode(values.check, values.dry),
+      quiet: values.quiet,
+      bench: values.bench,
+      help: values.help,
+      version: values.version,
+      inputs: positionals
+    };
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+function pickMode(check, dry) {
+  if (check) {
+    return "check";
+  }
+  return dry ? "dry" : "write";
+}
+
+// src/cli/print-help.ts
+function printHelp() {
+  process.stdout.write(`format-codemod — enforce blank-line padding conventions via text splice
+
+usage:
+  format-codemod [options] <file|dir|glob> ...
+
+options:
+  --check     exit 1 if any file would change (no writes)
+  --dry       print unified diff to stdout (no writes)
+  --bench     print parse stats as JSON to stderr
+  --quiet     only print files that would change
+  --version
+  --help
+
+exit codes:
+  0  clean
+  1  files would change (--check)
+  2  usage error, or one or more files failed (parse error, unreadable, unwritable)
+
+examples:
+  format-codemod 'src/**/*.ts'
+  format-codemod --check 'src/**/*.{ts,tsx}'
+  format-codemod --dry path/to/file.ts
+`);
+}
+
+// src/cli/print-report.ts
+function printReport(file, report, quiet) {
+  if (report.stdout !== null) {
+    process.stdout.write(report.stdout);
+  }
+  if (report.message !== null) {
+    console.error(report.message);
+  }
+  if (!quiet && report.outcome === "ok") {
+    console.error(`OK    ${file}`);
+  }
+  if (!quiet && report.outcome === "skipped") {
+    console.error(`SKIP  ${file}  declaration file`);
+  }
+}
+
+// src/cli/read-package-version.ts
+import fs2 from "node:fs";
+function readPackageVersion(pkgPath) {
+  const parsed = JSON.parse(fs2.readFileSync(pkgPath, "utf8"));
+  if (!isPackageJSON(parsed)) {
+    throw new TypeError("Invalid package.json");
+  }
+  return parsed.version;
+}
+function isPackageJSON(value) {
+  return typeof value === "object" && value !== null && "version" in value && typeof value.version === "string";
+}
+
+// src/cli/check-file.ts
+import fs4 from "node:fs";
+
+// src/transform/apply-edits.ts
+function applyEdits(src, edits) {
+  const segments = [];
+  let tail = src.length;
+  for (const e of edits) {
+    segments.push(src.slice(e.end, tail), e.replacement);
+    tail = e.start;
+  }
+  segments.push(src.slice(0, tail));
+  return segments.toReversed().join("");
+}
+
+// src/transform/plan-gap-edit.ts
+function planGapEdit(file, prev, next) {
+  const gap = buildGap(file, prev, next);
+  if (!isSafeToResize(gap)) {
+    return null;
+  }
+  return planBlankLineEdit(gap);
+}
+function buildGap(file, prev, next) {
+  const start = getNodeEnd(prev);
+  const end = getNodeStart(next);
+  const comments = file.comments.filter((c) => c.start >= start && c.end <= end);
+  return { src: file.src, start, end, comments };
+}
+function getNodeEnd(n) {
+  if (typeof n.end !== "number") {
+    throw new TypeError("AST node is missing an end position");
+  }
+  return n.end;
+}
+function getNodeStart(n) {
+  if (typeof n.start !== "number") {
+    throw new TypeError("AST node is missing a start position");
+  }
+  return n.start;
+}
+function isSafeToResize(gap) {
+  return isTriviaOnly(gap) && gap.src.slice(gap.start, gap.end).includes(`
+`);
+}
+function isTriviaOnly(gap) {
+  let cursor = gap.start;
+  for (const c of gap.comments) {
+    if (gap.src.slice(cursor, c.start).trim() !== "") {
+      return false;
+    }
+    cursor = c.end;
+  }
+  return gap.src.slice(cursor, gap.end).trim() === "";
+}
+function planBlankLineEdit(gap) {
+  const effectiveStart = getEffectiveGapStart(gap);
+  const leadingComment = gap.comments.find((c) => c.start >= effectiveStart);
+  if (leadingComment !== undefined) {
+    return planLeadingCommentEdit(gap.src, effectiveStart, leadingComment.start);
+  }
+  return planWhitespaceGap(gap.src.slice(effectiveStart, gap.end), effectiveStart, gap.end);
+}
+function getEffectiveGapStart(gap) {
+  let pos = gap.start;
+  for (const c of gap.comments) {
+    if (gap.src.slice(pos, c.start).includes(`
+`)) {
+      break;
+    }
+    pos = c.end;
+  }
+  return pos;
+}
+var MIN_NEWLINES = 2;
+function planLeadingCommentEdit(src, restStart, commentStart) {
+  const leading = src.slice(restStart, commentStart);
+  const leadingNewlines = countNewlines(leading);
+  if (leadingNewlines >= MIN_NEWLINES) {
+    return null;
+  }
+  return {
+    start: restStart,
+    end: commentStart,
+    replacement: `${`
+`.repeat(MIN_NEWLINES - leadingNewlines)}${leading}`
+  };
+}
+function planWhitespaceGap(gap, gapStart, gapEnd) {
+  if (countNewlines(gap) >= MIN_NEWLINES) {
+    return null;
+  }
+  const lastNL = gap.lastIndexOf(`
+`);
+  const indent = lastNL === -1 ? "" : gap.slice(lastNL + 1);
+  const trimmed = gap.slice(0, gap.length - indent.length).replace(/\n*$/u, "");
+  const newGap = `${trimmed}${`
+`.repeat(MIN_NEWLINES)}${indent}`;
+  return { start: gapStart, end: gapEnd, replacement: newGap };
+}
+function countNewlines(s) {
+  return (s.match(/\n/gu) ?? []).length;
+}
+
+// src/transform/build-edits-from-ast.ts
+function buildEditsFromAST(src, parsed) {
+  const file = { src, comments: parsed.comments };
+  return walk(file, parsed.program).toSorted((a, b) => b.start - a.start);
+}
+function walk(file, node) {
+  const edits = [];
+  for (const body of getStatementLists(node)) {
+    edits.push(...buildPairEdits(file, node, body));
+  }
+  for (const child of collectChildNodes(node)) {
+    edits.push(...walk(file, child));
+  }
+  return edits;
+}
+function getStatementLists(node) {
+  const bodies = [];
+  const hasBlockBody = node.type === "Program" || node.type === "BlockStatement" || node.type === "ClassBody";
+  if (hasBlockBody && Array.isArray(node.body)) {
+    bodies.push(node.body);
+  }
+  if (node.type === "SwitchCase" && Array.isArray(node.consequent)) {
+    bodies.push(node.consequent);
+  }
+  return bodies;
+}
+function buildPairEdits(file, container, body) {
+  const edits = [];
+  for (let i = 0;i < body.length - 1; i++) {
+    const prev = body[i];
+    const next = body[i + 1];
+    if (prev !== undefined && next !== undefined && (needsBlankLine(container, prev, next) || isMultiline(file.src, prev) || isMultiline(file.src, next))) {
+      const edit = planGapEdit(file, prev, next);
+      if (edit !== null) {
+        edits.push(edit);
+      }
+    }
+  }
+  return edits;
+}
+function isMultiline(src, node) {
+  return typeof node.start === "number" && typeof node.end === "number" && src.slice(node.start, node.end).includes(`
+`);
+}
+var CONTROL_FLOW_TYPES = new Set([
+  "IfStatement",
+  "ForStatement",
+  "ForInStatement",
+  "ForOfStatement",
+  "WhileStatement",
+  "SwitchStatement",
+  "TryStatement"
+]);
+function needsBlankLine(container, prev, next) {
+  if (container.type === "ClassBody") {
+    return true;
+  }
+  if (isVarDecl(prev) && !isVarDecl(next)) {
+    return true;
+  }
+  if (next.type === "ReturnStatement") {
+    return true;
+  }
+  if (isFnOrClassDecl(prev)) {
+    return true;
+  }
+  return isNewHeaded(prev) !== isNewHeaded(next) || isKindBoundary(prev, next) || CONTROL_FLOW_TYPES.has(next.type) || CONTROL_FLOW_TYPES.has(prev.type);
+}
+function isNewHeaded(node) {
+  return getStatementValues(node).some((value) => getExpressionHead(value).type === "NewExpression");
+}
+function getStatementValues(node) {
+  if (node.type === "VariableDeclaration") {
+    return collectASTNodes(node["declarations"]).map((declarator) => declarator["init"]).filter((init) => isASTNode(init));
+  }
+  const { expression } = node;
+  if (node.type !== "ExpressionStatement" || !isASTNode(expression)) {
+    return [];
+  }
+  const { right } = expression;
+  if (expression.type === "AssignmentExpression" && isASTNode(right)) {
+    return [right];
+  }
+  return [expression];
+}
+var HEAD_PROPERTY = {
+  CallExpression: "callee",
+  MemberExpression: "object",
+  ChainExpression: "expression",
+  AwaitExpression: "argument",
+  TSNonNullExpression: "expression",
+  ParenthesizedExpression: "expression"
+};
+function getExpressionHead(node) {
+  let current = node;
+  let property = HEAD_PROPERTY[current.type];
+  while (property !== undefined) {
+    const inner = current[property];
+    if (!isASTNode(inner)) {
+      break;
+    }
+    current = inner;
+    property = HEAD_PROPERTY[current.type];
+  }
+  return current;
+}
+var CALL_TYPES = ["CallExpression", "AwaitExpression"];
+var MUTATION_TYPES = ["AssignmentExpression", "UpdateExpression"];
+function isKindBoundary(prev, next) {
+  const prevKind = getStatementKind(prev);
+  const nextKind = getStatementKind(next);
+  return prevKind !== null && nextKind !== null && prevKind !== nextKind;
+}
+function getStatementKind(node) {
+  if (isVarDecl(node)) {
+    return "declaration";
+  }
+  if (isExpressionStatementOf(node, CALL_TYPES)) {
+    return "call";
+  }
+  return isExpressionStatementOf(node, MUTATION_TYPES) ? "mutation" : null;
+}
+function isExpressionStatementOf(node, types) {
+  const { expression } = node;
+  return node.type === "ExpressionStatement" && isASTNode(expression) && types.includes(expression.type);
+}
+var VAR_DECL_KINDS = new Set(["const", "let", "var"]);
+function isVarDecl(node) {
+  if (node.type === "VariableDeclaration") {
+    return node.kind !== undefined && VAR_DECL_KINDS.has(node.kind);
+  }
+  return false;
+}
+function isFnOrClassDecl(node) {
+  return node.type === "FunctionDeclaration" || node.type === "ClassDeclaration";
+}
+function collectChildNodes(node) {
+  const children = [];
+  for (const key of Object.keys(node)) {
+    if (key !== "loc" && key !== "parent") {
+      children.push(...collectASTNodes(node[key]));
+    }
+  }
+  return children;
+}
+function collectASTNodes(value) {
+  if (!Array.isArray(value)) {
+    return isASTNode(value) ? [value] : [];
+  }
+  const nodes = [];
+  for (const item of value) {
+    if (isASTNode(item)) {
+      nodes.push(item);
+    }
+  }
+  return nodes;
+}
+function isASTNode(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+
+// src/transform/parse-source.ts
+import { parseSync } from "oxc-parser";
+function parseSource(src, filename) {
+  const parsed = parseSync(filename, src);
+  const [firstError] = parsed.errors;
+  if (firstError !== undefined) {
+    return firstError.message;
+  }
+  if (!isASTNode2(parsed.program)) {
+    throw new TypeError("oxc-parser returned a malformed program node");
+  }
+  return { program: parsed.program, comments: parsed.comments };
+}
+function isASTNode2(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+
+// src/transform.ts
+function transform(src, options) {
+  const parsed = parseSource(src, options?.filename ?? "source.ts");
+  if (typeof parsed === "string") {
+    return { output: src, edits: 0, parseError: parsed };
+  }
+  const editList = buildEditsFromAST(src, parsed);
+  const output = applyEdits(src, editList);
+  return { output, edits: editList.length, parseError: null };
+}
+
+// src/cli/apply-diff-mode.ts
+import fs3 from "node:fs";
+
+// src/cli/build-unified-diff.ts
+function buildUnifiedDiff(before, after, label) {
+  const ops = new MyersDiff(splitLines(before), splitLines(after)).buildOps();
+  const hunks = buildHunks(ops);
+  if (hunks.length === 0) {
+    return "";
+  }
+  return [`--- ${label}
+`, `+++ ${label}
+`, ...hunks.map((h) => renderHunk(h))].join("");
+}
+function splitLines(s) {
+  const lines = s.split(`
+`);
+  if (lines.at(-1) === "") {
+    lines.pop();
+  }
+  return lines;
+}
+
+class MyersDiff {
+  a;
+  b;
+  v = new Map([[1, 0]]);
+  trace = [];
+  constructor(a, b) {
+    this.a = a;
+    this.b = b;
+  }
+  buildOps() {
+    this.computeTrace();
+    return this.backtrack();
+  }
+  computeTrace() {
+    for (let d = 0;d <= this.a.length + this.b.length; d++) {
+      this.trace.push(new Map(this.v));
+      if (this.stepRound(d)) {
+        return;
+      }
+    }
+  }
+  stepRound(d) {
+    for (let k = -d;k <= d; k += 2) {
+      const x = this.slideDiagonal(this.pickX(k, d), k);
+      this.v.set(k, x);
+      if (x >= this.a.length && x - k >= this.b.length) {
+        return true;
+      }
+    }
+    return false;
+  }
+  pickX(k, d) {
+    const moveDown = k === -d || k !== d && (this.v.get(k - 1) ?? 0) < (this.v.get(k + 1) ?? 0);
+    return moveDown ? this.v.get(k + 1) ?? 0 : (this.v.get(k - 1) ?? 0) + 1;
+  }
+  slideDiagonal(x, k) {
+    let nx = x;
+    while (nx < this.a.length && nx - k < this.b.length && this.a[nx] === this.b[nx - k]) {
+      nx++;
+    }
+    return nx;
+  }
+  backtrack() {
+    const ops = [];
+    let pos = { x: this.a.length, y: this.b.length };
+    for (let d = this.trace.length - 1;d >= 0; d--) {
+      const round = this.unwindRound(pos, d);
+      ops.push(...round.ops);
+      pos = round.pos;
+    }
+    return ops.toReversed();
+  }
+  unwindRound(pos, d) {
+    const { prev, moveDown } = this.findPrevious(pos, d);
+    const ops = this.buildEqualOps(pos, prev);
+    if (d > 0) {
+      const changeOp = moveDown ? { kind: "+", text: this.b[prev.y] ?? "" } : { kind: "-", text: this.a[prev.x] ?? "" };
+      ops.push(changeOp);
+    }
+    return { ops, pos: prev };
+  }
+  findPrevious(pos, d) {
+    const v = this.trace[d] ?? new Map;
+    const k = pos.x - pos.y;
+    const moveDown = k === -d || k !== d && (v.get(k - 1) ?? 0) < (v.get(k + 1) ?? 0);
+    const prevK = moveDown ? k + 1 : k - 1;
+    const prevX = v.get(prevK) ?? 0;
+    return { prev: { x: prevX, y: prevX - prevK }, moveDown };
+  }
+  buildEqualOps(pos, prev) {
+    const ops = [];
+    let { x, y } = pos;
+    while (x > prev.x && y > prev.y) {
+      ops.push({ kind: " ", text: this.a[x - 1] ?? "" });
+      x--;
+      y--;
+    }
+    return ops;
+  }
+}
+function buildHunks(ops) {
+  return buildWindows(ops).map((w) => buildHunk(ops, w));
+}
+var CONTEXT_LINES = 3;
+function buildWindows(ops) {
+  const windows = [];
+  for (let i = 0;i < ops.length; i++) {
+    if (ops[i]?.kind !== " ") {
+      const from = Math.max(0, i - CONTEXT_LINES);
+      const to = Math.min(ops.length, i + CONTEXT_LINES + 1);
+      const last = windows.at(-1);
+      if (last !== undefined && from <= last.to) {
+        windows[windows.length - 1] = { from: last.from, to };
+      } else {
+        windows.push({ from, to });
+      }
+    }
+  }
+  return windows;
+}
+function buildHunk(ops, w) {
+  const { aLine, bLine } = countPrecedingLines(ops, w.from);
+  const slice = ops.slice(w.from, w.to);
+  const aCount = slice.filter((o) => o.kind !== "+").length;
+  const bCount = slice.filter((o) => o.kind !== "-").length;
+  return {
+    header: `@@ -${formatRange(aLine, aCount)} +${formatRange(bLine, bCount)} @@
+`,
+    lines: slice.map((o) => `${o.kind}${o.text}
+`)
+  };
+}
+function countPrecedingLines(ops, from) {
+  let aLine = 0;
+  let bLine = 0;
+  for (const op of ops.slice(0, from)) {
+    if (op.kind !== "+") {
+      aLine++;
+    }
+    if (op.kind !== "-") {
+      bLine++;
+    }
+  }
+  return { aLine, bLine };
+}
+function formatRange(line, count) {
+  return count === 0 ? `${line},0` : `${line + 1},${count}`;
+}
+function renderHunk(h) {
+  return `${h.header}${h.lines.join("")}`;
+}
+
+// src/cli/apply-diff-mode.ts
+function applyDiffMode(edit, mode) {
+  if (mode === "check") {
+    return { message: `DIFF  ${edit.file}  ${edit.result.edits} edit(s)`, stdout: null };
+  }
+  if (mode === "dry") {
+    return { message: null, stdout: buildUnifiedDiff(edit.src, edit.result.output, edit.file) };
+  }
+  fs3.writeFileSync(edit.file, edit.result.output);
+  return { message: `WROTE ${edit.file}  ${edit.result.edits} edit(s)`, stdout: null };
+}
+
+// src/cli/check-file.ts
+function checkFile(file, mode) {
+  const src = fs4.readFileSync(file, "utf8");
+  const bytes = Buffer.byteLength(src);
+  const result = transform(src, { filename: file });
+  if (result.parseError !== null) {
+    return {
+      outcome: "failed",
+      bytes,
+      parsed: false,
+      message: `PARSE-ERR ${file}  ${result.parseError}`,
+      stdout: null
+    };
+  }
+  if (result.edits === 0 || result.output === src) {
+    return { outcome: "ok", bytes, parsed: true, message: null, stdout: null };
+  }
+  return { outcome: "changed", bytes, parsed: true, ...applyDiffMode({ file, src, result }, mode) };
+}
+
+// src/cli/try-check-file.ts
+function tryCheckFile(file, mode) {
+  if (file.endsWith(".d.ts")) {
+    return { outcome: "skipped", bytes: 0, parsed: false, message: null, stdout: null };
+  }
+  try {
+    return checkFile(file, mode);
+  } catch (error) {
+    const message = `ERROR ${file}  ${error instanceof Error ? error.message : String(error)}`;
+    return { outcome: "failed", bytes: 0, parsed: false, message, stdout: null };
+  }
+}
+
+// src/cli.ts
+var parsedArgs = parseCLIArgs(process.argv.slice(2));
+if (typeof parsedArgs === "string") {
+  console.error(parsedArgs);
+  process.exit(2);
+}
+var { mode, quiet, bench, help, version, inputs } = parsedArgs;
+if (help || inputs.length === 0 && !version) {
+  const exitCode = inputs.length === 0 ? 2 : 0;
+  printHelp();
+  process.exit(exitCode);
+}
+if (version) {
+  const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+  process.stdout.write(`${readPackageVersion(pkgPath)}
+`);
+  process.exit(0);
+}
+var t0 = Date.now();
+var files = await expandInputs(inputs);
+if (files.length === 0) {
+  console.error("no files matched");
+  process.exit(2);
+}
+var reports = [];
+for (const file of files) {
+  const report = tryCheckFile(file, mode);
+  reports.push(report);
+  printReport(file, report, quiet);
+}
+var failures = reports.filter((r) => r.outcome === "failed").length;
+var anyChange = reports.some((r) => r.outcome === "changed");
+if (bench) {
+  const stats = buildBenchStatsFromReports(reports, Date.now() - t0);
+  console.error(JSON.stringify(stats));
+}
+if (failures > 0) {
+  process.exit(2);
+}
+if (mode === "check") {
+  const exitCode = anyChange ? 1 : 0;
+  process.exit(exitCode);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { transform } from './transform.ts';
+export type { TransformOptions } from './transform.ts';
+export type { TransformResult } from './types.ts';

package/dist/index.js

@@ -0,0 +1,292 @@
+// src/transform/apply-edits.ts
+function applyEdits(src, edits) {
+  const segments = [];
+  let tail = src.length;
+  for (const e of edits) {
+    segments.push(src.slice(e.end, tail), e.replacement);
+    tail = e.start;
+  }
+  segments.push(src.slice(0, tail));
+  return segments.toReversed().join("");
+}
+
+// src/transform/plan-gap-edit.ts
+function planGapEdit(file, prev, next) {
+  const gap = buildGap(file, prev, next);
+  if (!isSafeToResize(gap)) {
+    return null;
+  }
+  return planBlankLineEdit(gap);
+}
+function buildGap(file, prev, next) {
+  const start = getNodeEnd(prev);
+  const end = getNodeStart(next);
+  const comments = file.comments.filter((c) => c.start >= start && c.end <= end);
+  return { src: file.src, start, end, comments };
+}
+function getNodeEnd(n) {
+  if (typeof n.end !== "number") {
+    throw new TypeError("AST node is missing an end position");
+  }
+  return n.end;
+}
+function getNodeStart(n) {
+  if (typeof n.start !== "number") {
+    throw new TypeError("AST node is missing a start position");
+  }
+  return n.start;
+}
+function isSafeToResize(gap) {
+  return isTriviaOnly(gap) && gap.src.slice(gap.start, gap.end).includes(`
+`);
+}
+function isTriviaOnly(gap) {
+  let cursor = gap.start;
+  for (const c of gap.comments) {
+    if (gap.src.slice(cursor, c.start).trim() !== "") {
+      return false;
+    }
+    cursor = c.end;
+  }
+  return gap.src.slice(cursor, gap.end).trim() === "";
+}
+function planBlankLineEdit(gap) {
+  const effectiveStart = getEffectiveGapStart(gap);
+  const leadingComment = gap.comments.find((c) => c.start >= effectiveStart);
+  if (leadingComment !== undefined) {
+    return planLeadingCommentEdit(gap.src, effectiveStart, leadingComment.start);
+  }
+  return planWhitespaceGap(gap.src.slice(effectiveStart, gap.end), effectiveStart, gap.end);
+}
+function getEffectiveGapStart(gap) {
+  let pos = gap.start;
+  for (const c of gap.comments) {
+    if (gap.src.slice(pos, c.start).includes(`
+`)) {
+      break;
+    }
+    pos = c.end;
+  }
+  return pos;
+}
+var MIN_NEWLINES = 2;
+function planLeadingCommentEdit(src, restStart, commentStart) {
+  const leading = src.slice(restStart, commentStart);
+  const leadingNewlines = countNewlines(leading);
+  if (leadingNewlines >= MIN_NEWLINES) {
+    return null;
+  }
+  return {
+    start: restStart,
+    end: commentStart,
+    replacement: `${`
+`.repeat(MIN_NEWLINES - leadingNewlines)}${leading}`
+  };
+}
+function planWhitespaceGap(gap, gapStart, gapEnd) {
+  if (countNewlines(gap) >= MIN_NEWLINES) {
+    return null;
+  }
+  const lastNL = gap.lastIndexOf(`
+`);
+  const indent = lastNL === -1 ? "" : gap.slice(lastNL + 1);
+  const trimmed = gap.slice(0, gap.length - indent.length).replace(/\n*$/u, "");
+  const newGap = `${trimmed}${`
+`.repeat(MIN_NEWLINES)}${indent}`;
+  return { start: gapStart, end: gapEnd, replacement: newGap };
+}
+function countNewlines(s) {
+  return (s.match(/\n/gu) ?? []).length;
+}
+
+// src/transform/build-edits-from-ast.ts
+function buildEditsFromAST(src, parsed) {
+  const file = { src, comments: parsed.comments };
+  return walk(file, parsed.program).toSorted((a, b) => b.start - a.start);
+}
+function walk(file, node) {
+  const edits = [];
+  for (const body of getStatementLists(node)) {
+    edits.push(...buildPairEdits(file, node, body));
+  }
+  for (const child of collectChildNodes(node)) {
+    edits.push(...walk(file, child));
+  }
+  return edits;
+}
+function getStatementLists(node) {
+  const bodies = [];
+  const hasBlockBody = node.type === "Program" || node.type === "BlockStatement" || node.type === "ClassBody";
+  if (hasBlockBody && Array.isArray(node.body)) {
+    bodies.push(node.body);
+  }
+  if (node.type === "SwitchCase" && Array.isArray(node.consequent)) {
+    bodies.push(node.consequent);
+  }
+  return bodies;
+}
+function buildPairEdits(file, container, body) {
+  const edits = [];
+  for (let i = 0;i < body.length - 1; i++) {
+    const prev = body[i];
+    const next = body[i + 1];
+    if (prev !== undefined && next !== undefined && (needsBlankLine(container, prev, next) || isMultiline(file.src, prev) || isMultiline(file.src, next))) {
+      const edit = planGapEdit(file, prev, next);
+      if (edit !== null) {
+        edits.push(edit);
+      }
+    }
+  }
+  return edits;
+}
+function isMultiline(src, node) {
+  return typeof node.start === "number" && typeof node.end === "number" && src.slice(node.start, node.end).includes(`
+`);
+}
+var CONTROL_FLOW_TYPES = new Set([
+  "IfStatement",
+  "ForStatement",
+  "ForInStatement",
+  "ForOfStatement",
+  "WhileStatement",
+  "SwitchStatement",
+  "TryStatement"
+]);
+function needsBlankLine(container, prev, next) {
+  if (container.type === "ClassBody") {
+    return true;
+  }
+  if (isVarDecl(prev) && !isVarDecl(next)) {
+    return true;
+  }
+  if (next.type === "ReturnStatement") {
+    return true;
+  }
+  if (isFnOrClassDecl(prev)) {
+    return true;
+  }
+  return isNewHeaded(prev) !== isNewHeaded(next) || isKindBoundary(prev, next) || CONTROL_FLOW_TYPES.has(next.type) || CONTROL_FLOW_TYPES.has(prev.type);
+}
+function isNewHeaded(node) {
+  return getStatementValues(node).some((value) => getExpressionHead(value).type === "NewExpression");
+}
+function getStatementValues(node) {
+  if (node.type === "VariableDeclaration") {
+    return collectASTNodes(node["declarations"]).map((declarator) => declarator["init"]).filter((init) => isASTNode(init));
+  }
+  const { expression } = node;
+  if (node.type !== "ExpressionStatement" || !isASTNode(expression)) {
+    return [];
+  }
+  const { right } = expression;
+  if (expression.type === "AssignmentExpression" && isASTNode(right)) {
+    return [right];
+  }
+  return [expression];
+}
+var HEAD_PROPERTY = {
+  CallExpression: "callee",
+  MemberExpression: "object",
+  ChainExpression: "expression",
+  AwaitExpression: "argument",
+  TSNonNullExpression: "expression",
+  ParenthesizedExpression: "expression"
+};
+function getExpressionHead(node) {
+  let current = node;
+  let property = HEAD_PROPERTY[current.type];
+  while (property !== undefined) {
+    const inner = current[property];
+    if (!isASTNode(inner)) {
+      break;
+    }
+    current = inner;
+    property = HEAD_PROPERTY[current.type];
+  }
+  return current;
+}
+var CALL_TYPES = ["CallExpression", "AwaitExpression"];
+var MUTATION_TYPES = ["AssignmentExpression", "UpdateExpression"];
+function isKindBoundary(prev, next) {
+  const prevKind = getStatementKind(prev);
+  const nextKind = getStatementKind(next);
+  return prevKind !== null && nextKind !== null && prevKind !== nextKind;
+}
+function getStatementKind(node) {
+  if (isVarDecl(node)) {
+    return "declaration";
+  }
+  if (isExpressionStatementOf(node, CALL_TYPES)) {
+    return "call";
+  }
+  return isExpressionStatementOf(node, MUTATION_TYPES) ? "mutation" : null;
+}
+function isExpressionStatementOf(node, types) {
+  const { expression } = node;
+  return node.type === "ExpressionStatement" && isASTNode(expression) && types.includes(expression.type);
+}
+var VAR_DECL_KINDS = new Set(["const", "let", "var"]);
+function isVarDecl(node) {
+  if (node.type === "VariableDeclaration") {
+    return node.kind !== undefined && VAR_DECL_KINDS.has(node.kind);
+  }
+  return false;
+}
+function isFnOrClassDecl(node) {
+  return node.type === "FunctionDeclaration" || node.type === "ClassDeclaration";
+}
+function collectChildNodes(node) {
+  const children = [];
+  for (const key of Object.keys(node)) {
+    if (key !== "loc" && key !== "parent") {
+      children.push(...collectASTNodes(node[key]));
+    }
+  }
+  return children;
+}
+function collectASTNodes(value) {
+  if (!Array.isArray(value)) {
+    return isASTNode(value) ? [value] : [];
+  }
+  const nodes = [];
+  for (const item of value) {
+    if (isASTNode(item)) {
+      nodes.push(item);
+    }
+  }
+  return nodes;
+}
+function isASTNode(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+
+// src/transform/parse-source.ts
+import { parseSync } from "oxc-parser";
+function parseSource(src, filename) {
+  const parsed = parseSync(filename, src);
+  const [firstError] = parsed.errors;
+  if (firstError !== undefined) {
+    return firstError.message;
+  }
+  if (!isASTNode2(parsed.program)) {
+    throw new TypeError("oxc-parser returned a malformed program node");
+  }
+  return { program: parsed.program, comments: parsed.comments };
+}
+function isASTNode2(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+
+// src/transform.ts
+function transform(src, options) {
+  const parsed = parseSource(src, options?.filename ?? "source.ts");
+  if (typeof parsed === "string") {
+    return { output: src, edits: 0, parseError: parsed };
+  }
+  const editList = buildEditsFromAST(src, parsed);
+  const output = applyEdits(src, editList);
+  return { output, edits: editList.length, parseError: null };
+}
+export {
+  transform
+};

package/dist/transform/apply-edits.d.ts

@@ -0,0 +1,7 @@
+import type { Edit } from '../types.ts';
+/**
+ * Callers must pass edits sorted last-to-first, so each splice's offsets stay
+ * valid without adjustment. Segments are collected and joined once instead of
+ * re-copying the whole string per edit.
+ */
+export declare function applyEdits(src: string, edits: readonly Edit[]): string;

package/dist/transform/build-edits-from-ast.d.ts

@@ -0,0 +1,5 @@
+import type { Edit, ParsedSource } from '../types.ts';
+/**
+ * Sorted last-to-first so applying splices in order never shifts later offsets.
+ */
+export declare function buildEditsFromAST(src: string, parsed: ParsedSource): Edit[];

package/dist/transform/parse-source.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedSource } from '../types.ts';
+/**
+ * The filename picks the dialect — `.tsx` enables JSX, anything else parses as
+ * plain TypeScript, so `.ts`-only syntax like `<string>value` assertions and
+ * un-comma'd generic arrows parse correctly. oxc reports syntax errors as a
+ * list instead of throwing; any error means node offsets can't be trusted for
+ * splicing, so the first message is returned and the caller skips the file.
+ * ParsedSource is always an object, so the string return is unambiguous.
+ */
+export declare function parseSource(src: string, filename: string): ParsedSource | string;

package/dist/transform/plan-gap-edit.d.ts

@@ -0,0 +1,8 @@
+import type { ASTNode, Edit, SourceFile } from '../types.ts';
+/**
+ * Plans the single whitespace splice that gives the gap between two statements
+ * exactly one blank line, or null when the gap is already compliant or unsafe
+ * to touch. Comment positions come from the parser rather than lexical
+ * scanning, so comment-lookalike text can't mislead the classification.
+ */
+export declare function planGapEdit(file: SourceFile, prev: ASTNode, next: ASTNode): Edit | null;

package/dist/transform.d.ts

@@ -0,0 +1,13 @@
+import type { TransformResult } from './types.ts';
+export interface TransformOptions {
+    /**
+     * Picks the parse dialect: `.tsx` enables JSX, anything else is plain
+     * TypeScript. Defaults to 'source.ts' — JSX callers must say so.
+     */
+    readonly filename?: string;
+}
+/**
+ * Pure transform: source string in, edited source string out, no I/O. On a
+ * parse error the input is returned untouched alongside the error message.
+ */
+export declare function transform(src: string, options?: TransformOptions): TransformResult;

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The fields of the oxc AST this transform reads; the index signature carries
+ * every other node property so the generic child walk can recurse untyped. The
+ * codemod never mutates the tree, so everything is readonly.
+ */
+export interface ASTNode {
+    readonly type: string;
+    readonly kind?: string;
+    readonly start?: number;
+    readonly end?: number;
+    readonly body?: readonly ASTNode[] | ASTNode;
+    readonly consequent?: readonly ASTNode[];
+    readonly declaration?: ASTNode;
+    readonly [key: string]: unknown;
+}
+export interface CommentSpan {
+    readonly start: number;
+    readonly end: number;
+}
+export interface ParsedSource {
+    readonly program: ASTNode;
+    readonly comments: readonly CommentSpan[];
+}
+/**
+ * The raw text and its comment spans together — what gap planning needs to
+ * classify inter-statement trivia without re-lexing.
+ */
+export interface SourceFile {
+    readonly src: string;
+    readonly comments: readonly CommentSpan[];
+}
+export interface Edit {
+    readonly start: number;
+    readonly end: number;
+    readonly replacement: string;
+}
+export interface TransformResult {
+    readonly output: string;
+    readonly edits: number;
+    readonly parseError: string | null;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@zgeoff/format-codemod",
+  "version": "0.0.1",
+  "description": "Enforce blank-line padding conventions in TypeScript via a fast text-splice codemod",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/tools.git",
+    "directory": "packages/format-codemod"
+  },
+  "bin": {
+    "format-codemod": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json",
+    "prepare": "bun run build",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "oxc-parser": "0.137.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "7.0.1-rc"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=22"
+  }
+}