@zgeoff/format-codemod 0.0.5 → 0.0.7

package/README.md

@@ -1,49 +1,67 @@
 # @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.
+Machine-owned vertical spacing for TypeScript. Every gap between adjacent statements is normalized
+to exactly one blank line where a rule below requires one, and zero where none does — a superset of
+ESLint's `padding-line-between-statements` and `@stylistic/lines-between-class-members`, run as a
+text-splice codemod. Each file is parsed once with [oxc-parser](https://oxc.rs) (native) and edited
+by positional whitespace splices — no type-aware analysis — so a pass is fast enough for a
+pre-commit hook or a `format` pipeline. Runs are idempotent: a pass over compliant code is a no-op.
 
-## Rules implemented
+Three kinds of gap are left alone:
 
-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.
+- A gap holding any comment is never collapsed, only grown — prose between statements marks
+  intentional grouping the rules can't see.
+- The interior of an import block is never touched — it belongs to the import sorter. The boundary
+  after the last import is still padded.
+- Two statements sharing a physical line (a leading-semicolon `;(expr)` guard) are skipped — a
+  blank-only edit can't separate them without orphaning a token.
 
-**`padding-line-between-statements`** — insert one blank line:
+## Rules
 
-- after a `const`/`let`/`var` block, before any non-var statement
-- before any `return`
+**Padded on both sides** — the statement is its own paragraph:
+
+- a control-flow block: `if`, `for`, `for…in`, `for…of`, `while`, `switch`, `try`
+- any statement that spans multiple lines
+- a type alias or interface declaration — runs of them are padded apart, not glued. This is the one
+  rule that looks through `export`: `export type X = …` pads like `type X = …`.
+
+**Padded on one side:**
+
+- before every `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
-  `using`/`await using` declaration, a call statement, an assignment/increment statement — in any
-  order; runs of one kind stay tight
-- after a `using`/`await using` block, before any statement of another kind
-- 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
-- at the boundary between an awaited and a non-awaited statement — awaited means an `await using`
-  declaration, or an `await` in the head of the statement's value chain (`await f()`,
-  `const x = await f()`, `x = (await f()).prop`); an `await` in argument position (`use(await f())`)
-  or under a non-chain head (`flag ? await f() : g()`) doesn't count, and runs of awaited statements
-  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. `using`/`await using`
-  declarations are not var declarations; they form their own statement kind.
-- **The `using` and awaited-boundary rules go beyond ESLint** — `padding-line-between-statements`
-  cannot express either, so on these the codemod is the spec.
-- **`.d.ts` files are skipped.**
+- after a directive prologue (`'use strict'`, `'use client'`); runs of directives stay glued
+- after the last import of a block
+
+**Kind boundaries** — statements classify into kinds; a run of one kind sits flush, and the boundary
+between two kinds takes a blank line:
+
+- `const`/`let`/`var` declarations
+- `using`/`await using` declarations
+- bare calls and method calls — two distinct kinds, split by the first call in reading order:
+  `expect(x).toBe(y)` opens with a bare function, `fs.writeFileSync(…)` opens with a member, and a
+  member call chained onto a bare call's result is still a bare call
+- assignments and increments
+
+Two axes overlay the kinds and pad their own boundaries:
+
+- instantiation — a statement headed by `new` (`new X(…)`, `new X(…).method()`) is separated from
+  any non-instantiation statement; `new` in argument position doesn't count, and runs of
+  instantiations stay glued
+- awaitedness — an awaited statement (`await using`, or an `await` in the head of the statement's
+  value chain: `await f()`, `const x = await f()`) is separated from non-awaited ones; an `await` in
+  argument position (`use(await f())`) or under a non-chain head (`flag ? await f() : g()`) doesn't
+  count, and runs of awaited statements stay glued
+
+**Class members** — one blank line between members.
+
+Only bare declarations match the declaration rules: `export const`, `export function`, and
+`export class` are not declarations to the classifier (type aliases and interfaces are the one
+exception, above).
+
+Comment positions come from the parser, not lexical scanning, so comment-lookalike text can't
+mislead the classification. A trailing same-line comment stays attached to the statement before it —
+the blank line goes after the comment; a comment on its own line attaches to the statement after it
+— the blank line goes before. The next statement's indentation is preserved.
 
 ## CLI
 
@@ -59,67 +77,43 @@ format-codemod [options] <file|dir|glob> ...
   --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
+Flags are strict: an unknown flag is a usage error, never a silent no-op — the default mode writes
+files, so a typo'd `--check` must not fall through to a rewrite. Exit codes: `0` clean, `1` files
+would change (`--check`), `2` usage error or one or more files failed (parse error, unreadable,
+unwritable).
 
 ```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 --dry path/to/file.ts         # preview diff; applies cleanly with patch(1)
 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.
+### Inputs
 
-`--dry` prints a real unified diff — `@@` hunk headers with three lines of context — that applies
-cleanly with `patch(1)`.
+Globs use Node'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 read as files, not glob
+character classes. A directory expands to `**/*.{ts,tsx}` beneath it; `node_modules` and `.git` are
+never descended into, and overlapping patterns are deduped so each file is processed once. `.d.ts`
+files are skipped. The extension picks the parse dialect: `.tsx` enables JSX, everything else parses
+as plain TypeScript — so `.ts`-only syntax (`<string>value` assertions, un-comma'd generic arrows
+`<T>(a: T) => a`) parses correctly instead of being misread as JSX.
 
 ### Ignoring files
 
-A `.formatignore` file in the working directory supplies ignore globs without bloating the command
-line — one per line, with blank lines and `#`-prefixed comment lines skipped:
+A `.formatignore` file in the working directory supplies ignore globs — one per line, blank lines
+and `#`-prefixed comment lines skipped:
 
 ```gitignore
 # committed codegen
 src/generated/**
-
-# build output
 dist/**
 ```
 
-Each line uses the same glob semantics as `--ignore` (Node's `path.matchesGlob`, tried against both
-the expanded path and the path relative to the working directory). It is not a gitignore dialect:
-`!` negation and directory-anchoring rules are not supported. `--ignore` flags remain available and
-merge additively with the file's globs.
-
-## 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.
+Each line uses the same semantics as `--ignore` (Node's `path.matchesGlob`, tried against both the
+expanded path and the path relative to the working directory). It is not a gitignore dialect: `!`
+negation and directory-anchoring rules are not supported. `--ignore` flags merge additively with the
+file's globs.
 
 ## Programmatic use
 
@@ -131,5 +125,5 @@ const { output, edits, parseError } = transform(source, { filename: 'component.t
 // 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.
+`filename` is optional and only picks the dialect (default `'source.ts'` — plain TypeScript, no
+JSX); nothing is read from disk.

package/dist/cli.js

@@ -207,6 +207,27 @@ function collectChildNodes(node) {
   return children;
 }
 
+// src/transform/collect-head-chain.ts
+var HEAD_PROPERTY = {
+  CallExpression: "callee",
+  MemberExpression: "object",
+  ChainExpression: "expression",
+  AwaitExpression: "argument",
+  TSNonNullExpression: "expression",
+  ParenthesizedExpression: "expression"
+};
+function collectHeadChain(expression) {
+  const chain = [];
+  let current = expression;
+  while (current !== undefined) {
+    chain.push(current);
+    const property = HEAD_PROPERTY[current.type];
+    const inner = property === undefined ? undefined : current[property];
+    current = isASTNode(inner) ? inner : undefined;
+  }
+  return chain;
+}
+
 // src/transform/needs-blank-line.ts
 var CONTROL_FLOW_TYPES = new Set([
   "IfStatement",
@@ -221,19 +242,30 @@ function needsBlankLine(container, prev, next) {
   if (container.type === "ClassBody") {
     return true;
   }
-  if (isVarDecl(prev) && !isVarDecl(next) || isUsingDecl(prev) && !isUsingDecl(next)) {
+  if (isRunEnd(prev, next) || next.type === "ReturnStatement" || isFnOrClassDecl(prev)) {
     return true;
   }
-  if (next.type === "ReturnStatement") {
+  if (isTypeDecl(prev) || isTypeDecl(next)) {
     return true;
   }
-  if (isFnOrClassDecl(prev)) {
+  return isNewHeaded(prev) !== isNewHeaded(next) || isAwaitHeaded(prev) !== isAwaitHeaded(next) || isKindBoundary(prev, next) || CONTROL_FLOW_TYPES.has(next.type) || CONTROL_FLOW_TYPES.has(prev.type);
+}
+function isRunEnd(prev, next) {
+  return isVarDecl(prev) && !isVarDecl(next) || isUsingDecl(prev) && !isUsingDecl(next) || isDirective(prev) && !isDirective(next) || prev.type === "ImportDeclaration" && next.type !== "ImportDeclaration";
+}
+function isDirective(node) {
+  return typeof node["directive"] === "string";
+}
+var TYPE_DECL_TYPES = new Set(["TSTypeAliasDeclaration", "TSInterfaceDeclaration"]);
+function isTypeDecl(node) {
+  if (TYPE_DECL_TYPES.has(node.type)) {
     return true;
   }
-  return isNewHeaded(prev) !== isNewHeaded(next) || isAwaitHeaded(prev) !== isAwaitHeaded(next) || isKindBoundary(prev, next) || CONTROL_FLOW_TYPES.has(next.type) || CONTROL_FLOW_TYPES.has(prev.type);
+  const declaration = node.declaration;
+  return node.type === "ExportNamedDeclaration" && isASTNode(declaration) && TYPE_DECL_TYPES.has(declaration.type);
 }
 function isNewHeaded(node) {
-  return getStatementValues(node).some((value) => getExpressionHead(value).type === "NewExpression");
+  return getStatementValues(node).some((value) => collectHeadChain(value).at(-1)?.type === "NewExpression");
 }
 function getStatementValues(node) {
   if (node.type === "VariableDeclaration") {
@@ -249,44 +281,11 @@ function getStatementValues(node) {
   }
   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;
-}
 function isAwaitHeaded(node) {
   if (node.type === "VariableDeclaration" && node.kind === "await using") {
     return true;
   }
-  return getStatementValues(node).some((value) => hasAwaitInHeadChain(value));
-}
-function hasAwaitInHeadChain(node) {
-  let current = node;
-  while (current !== undefined) {
-    if (current.type === "AwaitExpression") {
-      return true;
-    }
-    const property = HEAD_PROPERTY[current.type];
-    const inner = property === undefined ? undefined : current[property];
-    current = isASTNode(inner) ? inner : undefined;
-  }
-  return false;
+  return getStatementValues(node).some((value) => collectHeadChain(value).some((link) => link.type === "AwaitExpression"));
 }
 var CALL_TYPES = ["CallExpression", "AwaitExpression"];
 var MUTATION_TYPES = ["AssignmentExpression", "UpdateExpression"];
@@ -303,10 +302,20 @@ function getStatementKind(node) {
     return "declaration";
   }
   if (isExpressionStatementOf(node, CALL_TYPES)) {
-    return "call";
+    return pickCallKind(node);
   }
   return isExpressionStatementOf(node, MUTATION_TYPES) ? "mutation" : null;
 }
+function pickCallKind(node) {
+  const expression = node["expression"];
+  const callee = isASTNode(expression) ? findDeepestCallee(expression) : null;
+  return callee?.type === "MemberExpression" ? "method-call" : "bare-call";
+}
+function findDeepestCallee(expression) {
+  const deepestCall = collectHeadChain(expression).findLast((link) => link.type === "CallExpression");
+  const callee = deepestCall?.["callee"];
+  return isASTNode(callee) ? callee : null;
+}
 function isExpressionStatementOf(node, types) {
   const expression = node["expression"];
   return node.type === "ExpressionStatement" && isASTNode(expression) && types.includes(expression.type);
@@ -330,12 +339,12 @@ function isFnOrClassDecl(node) {
 }
 
 // src/transform/plan-gap-edit.ts
-function planGapEdit(file, prev, next) {
-  const gap = buildGap(file, prev, next);
+function planGapEdit(input) {
+  const gap = buildGap(input.file, input.prev, input.next);
   if (!isSafeToResize(gap)) {
     return null;
   }
-  return planBlankLineEdit(gap);
+  return input.pad ? planBlankLineEdit(gap) : planCollapseEdit(gap);
 }
 function buildGap(file, prev, next) {
   const start = getNodeEnd(prev);
@@ -417,6 +426,19 @@ function planWhitespaceGap(gap, gapStart, gapEnd) {
 function countNewlines(s) {
   return (s.match(/\n/gu) ?? []).length;
 }
+function planCollapseEdit(gap) {
+  if (gap.comments.length > 0) {
+    return null;
+  }
+  const text = gap.src.slice(gap.start, gap.end);
+  if (countNewlines(text) < MIN_NEWLINES) {
+    return null;
+  }
+  const indent = text.slice(text.lastIndexOf(`
+`) + 1);
+  return { start: gap.start, end: gap.end, replacement: `
+${indent}` };
+}
 
 // src/transform/build-edits-from-ast.ts
 function buildEditsFromAST(src, parsed) {
@@ -449,8 +471,9 @@ function buildPairEdits(file, container, body) {
   for (let i = 0;i < body.length - 1; i++) {
     const prev = body[i];
     const next = body[i + 1];
-    if (prev !== undefined && next !== undefined && !isImportPair(prev, next) && (needsBlankLine(container, prev, next) || isMultiline(file.src, prev) || isMultiline(file.src, next))) {
-      const edit = planGapEdit(file, prev, next);
+    if (prev !== undefined && next !== undefined && !isImportPair(prev, next)) {
+      const pad = needsBlankLine(container, prev, next) || isMultiline(file.src, prev) || isMultiline(file.src, next);
+      const edit = planGapEdit({ file, prev, next, pad });
       if (edit !== null) {
         edits.push(edit);
       }
@@ -527,10 +550,10 @@ class MyersDiff {
     this.b = b;
   }
   buildOps() {
-    this.computeTrace();
+    this.updateTrace();
     return this.backtrack();
   }
-  computeTrace() {
+  updateTrace() {
     for (let d = 0;d <= this.a.length + this.b.length; d++) {
       this.trace.push(new Map(this.v));
       if (this.stepRound(d)) {

package/dist/index.js

@@ -40,6 +40,27 @@ function collectChildNodes(node) {
   return children;
 }
 
+// src/transform/collect-head-chain.ts
+var HEAD_PROPERTY = {
+  CallExpression: "callee",
+  MemberExpression: "object",
+  ChainExpression: "expression",
+  AwaitExpression: "argument",
+  TSNonNullExpression: "expression",
+  ParenthesizedExpression: "expression"
+};
+function collectHeadChain(expression) {
+  const chain = [];
+  let current = expression;
+  while (current !== undefined) {
+    chain.push(current);
+    const property = HEAD_PROPERTY[current.type];
+    const inner = property === undefined ? undefined : current[property];
+    current = isASTNode(inner) ? inner : undefined;
+  }
+  return chain;
+}
+
 // src/transform/needs-blank-line.ts
 var CONTROL_FLOW_TYPES = new Set([
   "IfStatement",
@@ -54,19 +75,30 @@ function needsBlankLine(container, prev, next) {
   if (container.type === "ClassBody") {
     return true;
   }
-  if (isVarDecl(prev) && !isVarDecl(next) || isUsingDecl(prev) && !isUsingDecl(next)) {
+  if (isRunEnd(prev, next) || next.type === "ReturnStatement" || isFnOrClassDecl(prev)) {
     return true;
   }
-  if (next.type === "ReturnStatement") {
+  if (isTypeDecl(prev) || isTypeDecl(next)) {
     return true;
   }
-  if (isFnOrClassDecl(prev)) {
+  return isNewHeaded(prev) !== isNewHeaded(next) || isAwaitHeaded(prev) !== isAwaitHeaded(next) || isKindBoundary(prev, next) || CONTROL_FLOW_TYPES.has(next.type) || CONTROL_FLOW_TYPES.has(prev.type);
+}
+function isRunEnd(prev, next) {
+  return isVarDecl(prev) && !isVarDecl(next) || isUsingDecl(prev) && !isUsingDecl(next) || isDirective(prev) && !isDirective(next) || prev.type === "ImportDeclaration" && next.type !== "ImportDeclaration";
+}
+function isDirective(node) {
+  return typeof node["directive"] === "string";
+}
+var TYPE_DECL_TYPES = new Set(["TSTypeAliasDeclaration", "TSInterfaceDeclaration"]);
+function isTypeDecl(node) {
+  if (TYPE_DECL_TYPES.has(node.type)) {
     return true;
   }
-  return isNewHeaded(prev) !== isNewHeaded(next) || isAwaitHeaded(prev) !== isAwaitHeaded(next) || isKindBoundary(prev, next) || CONTROL_FLOW_TYPES.has(next.type) || CONTROL_FLOW_TYPES.has(prev.type);
+  const declaration = node.declaration;
+  return node.type === "ExportNamedDeclaration" && isASTNode(declaration) && TYPE_DECL_TYPES.has(declaration.type);
 }
 function isNewHeaded(node) {
-  return getStatementValues(node).some((value) => getExpressionHead(value).type === "NewExpression");
+  return getStatementValues(node).some((value) => collectHeadChain(value).at(-1)?.type === "NewExpression");
 }
 function getStatementValues(node) {
   if (node.type === "VariableDeclaration") {
@@ -82,44 +114,11 @@ function getStatementValues(node) {
   }
   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;
-}
 function isAwaitHeaded(node) {
   if (node.type === "VariableDeclaration" && node.kind === "await using") {
     return true;
   }
-  return getStatementValues(node).some((value) => hasAwaitInHeadChain(value));
-}
-function hasAwaitInHeadChain(node) {
-  let current = node;
-  while (current !== undefined) {
-    if (current.type === "AwaitExpression") {
-      return true;
-    }
-    const property = HEAD_PROPERTY[current.type];
-    const inner = property === undefined ? undefined : current[property];
-    current = isASTNode(inner) ? inner : undefined;
-  }
-  return false;
+  return getStatementValues(node).some((value) => collectHeadChain(value).some((link) => link.type === "AwaitExpression"));
 }
 var CALL_TYPES = ["CallExpression", "AwaitExpression"];
 var MUTATION_TYPES = ["AssignmentExpression", "UpdateExpression"];
@@ -136,10 +135,20 @@ function getStatementKind(node) {
     return "declaration";
   }
   if (isExpressionStatementOf(node, CALL_TYPES)) {
-    return "call";
+    return pickCallKind(node);
   }
   return isExpressionStatementOf(node, MUTATION_TYPES) ? "mutation" : null;
 }
+function pickCallKind(node) {
+  const expression = node["expression"];
+  const callee = isASTNode(expression) ? findDeepestCallee(expression) : null;
+  return callee?.type === "MemberExpression" ? "method-call" : "bare-call";
+}
+function findDeepestCallee(expression) {
+  const deepestCall = collectHeadChain(expression).findLast((link) => link.type === "CallExpression");
+  const callee = deepestCall?.["callee"];
+  return isASTNode(callee) ? callee : null;
+}
 function isExpressionStatementOf(node, types) {
   const expression = node["expression"];
   return node.type === "ExpressionStatement" && isASTNode(expression) && types.includes(expression.type);
@@ -163,12 +172,12 @@ function isFnOrClassDecl(node) {
 }
 
 // src/transform/plan-gap-edit.ts
-function planGapEdit(file, prev, next) {
-  const gap = buildGap(file, prev, next);
+function planGapEdit(input) {
+  const gap = buildGap(input.file, input.prev, input.next);
   if (!isSafeToResize(gap)) {
     return null;
   }
-  return planBlankLineEdit(gap);
+  return input.pad ? planBlankLineEdit(gap) : planCollapseEdit(gap);
 }
 function buildGap(file, prev, next) {
   const start = getNodeEnd(prev);
@@ -250,6 +259,19 @@ function planWhitespaceGap(gap, gapStart, gapEnd) {
 function countNewlines(s) {
   return (s.match(/\n/gu) ?? []).length;
 }
+function planCollapseEdit(gap) {
+  if (gap.comments.length > 0) {
+    return null;
+  }
+  const text = gap.src.slice(gap.start, gap.end);
+  if (countNewlines(text) < MIN_NEWLINES) {
+    return null;
+  }
+  const indent = text.slice(text.lastIndexOf(`
+`) + 1);
+  return { start: gap.start, end: gap.end, replacement: `
+${indent}` };
+}
 
 // src/transform/build-edits-from-ast.ts
 function buildEditsFromAST(src, parsed) {
@@ -282,8 +304,9 @@ function buildPairEdits(file, container, body) {
   for (let i = 0;i < body.length - 1; i++) {
     const prev = body[i];
     const next = body[i + 1];
-    if (prev !== undefined && next !== undefined && !isImportPair(prev, next) && (needsBlankLine(container, prev, next) || isMultiline(file.src, prev) || isMultiline(file.src, next))) {
-      const edit = planGapEdit(file, prev, next);
+    if (prev !== undefined && next !== undefined && !isImportPair(prev, next)) {
+      const pad = needsBlankLine(container, prev, next) || isMultiline(file.src, prev) || isMultiline(file.src, next);
+      const edit = planGapEdit({ file, prev, next, pad });
       if (edit !== null) {
         edits.push(edit);
       }

package/dist/transform/collect-head-chain.d.ts

@@ -0,0 +1,9 @@
+import type { ASTNode } from '../types.ts';
+/**
+ * The nodes on the walk from an expression to its head, outermost first and
+ * ending at the head itself — `(await f()).prop` yields the member access,
+ * the parenthesis, the await, the call, and finally `f`. Nodes outside the
+ * walk (call arguments, ternary branches) never appear, so a scan of the
+ * chain sees only what a reader meets before the expression's first token.
+ */
+export declare function collectHeadChain(expression: ASTNode): ASTNode[];

package/dist/transform/needs-blank-line.d.ts

@@ -1,11 +1,13 @@
 import type { ASTNode } from '../types.ts';
 /**
  * The "always" rules: a blank line between class members, after a var or
- * using block before a statement of any other kind, before a return, after a
- * function/class declaration, on both sides of a control-flow block — its
- * closing brace ends a visual unit just like its opening keyword starts one —
- * and at the boundary between statement kinds: call vs mutation,
- * instantiation vs anything else, and awaited vs non-awaited. There are no
- * "never" rules, so any match means one blank.
+ * using block before a statement of any other kind, after a directive
+ * prologue, after the last import of a block, before a return, after a
+ * function/class declaration, on both sides of a type alias or interface
+ * declaration, on both sides of a control-flow block — its closing brace
+ * ends a visual unit just like its opening keyword starts one —
+ * and at the boundary between statement kinds: bare call vs method call vs
+ * mutation, instantiation vs anything else, and awaited vs non-awaited. Any
+ * match means exactly one blank line; a pair matching no rule sits flush.
  */
 export declare function needsBlankLine(container: ASTNode, prev: ASTNode, next: ASTNode): boolean;

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

@@ -1,8 +1,20 @@
 import type { ASTNode, Edit, SourceFile } from '../types.ts';
+/**
+ * A pair of adjacent statements in a file and the gap shape they take: one
+ * blank line between them when `pad` is set, none otherwise.
+ */
+export interface GapEditInput {
+    readonly file: SourceFile;
+    readonly prev: ASTNode;
+    readonly next: ASTNode;
+    readonly pad: boolean;
+}
 /**
  * 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.
+ * its target shape, or null when the gap is already compliant or unsafe to
+ * touch. Collapsing never crosses a comment: prose between statements marks
+ * grouping the padding rules can't see, so a comment-bearing gap only ever
+ * grows. 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;
+export declare function planGapEdit(input: GapEditInput): Edit | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/format-codemod",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Enforce blank-line padding conventions in TypeScript via a fast text-splice codemod",
   "license": "MIT",
   "repository": {