@preventive/compare 1.0.2 → 1.1.0

package/compare.d.ts

@@ -34,12 +34,23 @@ export type Status = 'added' | 'deleted' | 'modified' | 'renamed' | 'type-change
 // file and `new` for a deleted one; a renamed file has both, under their
 // two paths. `similarity` is a rename's, as git's similarity index: the
 // percentage of the new file the old one accounts for, 100 where the content
-// is unchanged; null for anything else.
+// is unchanged; null for anything else. `typeOnly`, on Node alone, stamps a
+// change whose every side there is a file named as a declaration file
+// (`.d.ts`, `.d.mts`, `.d.cts`, `.d.css.ts`) and holds types alone, as
+// proveTypeOnly proves: one that runs nothing on either side, as a side not
+// there runs nothing. A retained `export {}` runs nothing as a module but emits
+// a marker transpiled to CommonJS, so it is allowed only on both sides at once
+// or neither, never added or removed alone, and only where the two extensions
+// fix the same module format (`.mts` a module, `.cts` CommonJS) -- a rename from
+// a `.d.mts` to a `.d.cts` runs it, then throws on it, and a `.d.ts`, its format
+// its package's to say and not known here, never cancels one. Absent off Node,
+// and without oxc-parser.
 export interface FileStatus {
   status: Status
   old: TreeFile | null
   new: TreeFile | null
   similarity: number | null
+  typeOnly?: true
 }
 
 // A status with what happened to the content: `blocks`, @preventive/diff's
@@ -176,6 +187,39 @@ export function layoutPackageDirs(baseDirs: Map<string, string> | null, otherDir
 // (`./dir/`, `./src/dir/`); a prefix the root doesn't lead is dropped.
 export function rootLabel(root: Root | null, prefix: string): { prefix: string; from: string | null; to: string | null }
 
+// Why a text is not proven to hold types alone: proving needs Node, whose type
+// stripping is held to oxc's tree, and oxc-parser, an optional peer, there,
+// and is not asked of a stripping that once failed as may leave it unsound
+// (`unsupported`); Node's stripping or oxc finds an error in it, as in
+// `export const x: number`, which only a declaration file may write, or it
+// nests too deep for either (`unparsed`); a statement stripping leaves loads a
+// module, as `import { type A }` and `export *` from one do (`imports`), or is
+// anything else (`code`); or Node's stripping, or a reading of what it leaves,
+// does not find what oxc does (`disagree`).
+export type TypeOnlyReason = 'unsupported' | 'unparsed' | 'imports' | 'code' | 'disagree'
+
+// Whether `text`, read as TypeScript, holds types alone, so that Node, which
+// reads a `.d.ts` as the `.ts` it is named and runs what its type stripping
+// leaves, runs nothing of it:
+// - oxc's tree has no statement but those stripping erases whole -- interfaces,
+//   type aliases, anything `declare`d (bodies and initializers with it), a
+//   function's signature, `import type` and `export type`, a namespace of types
+//   alone -- and a bare `export {}`. `import { type A }` loads its module like
+//   any import, inline `type` or not, so it is not type-only; nor is
+//   `export { type A }`, which is only `export {}` once stripping takes its
+//   specifiers out; nor `export as namespace N`, left as invalid JavaScript that
+//   throws when imported;
+// - Node's stripTypeScriptTypes erases, to the character, what oxc finds erased
+//   and leaves nothing it does not, but comments, the hashbang and that one;
+// - what it leaves, read token by token apart from either, holds nothing else;
+// - nor does what its transform mode (--experimental-transform-types) leaves.
+// `inert` is true where a bare `export {}` is kept: valid JavaScript that loads
+// and runs nothing as a module, but a marker transpiled to CommonJS, so a change
+// is types only only where both sides match in it. `at` is where in `text` what
+// is found begins, where it has a place. Throws a TypeError where `text` is not a
+// well-formed string. Node warns once that stripTypeScriptTypes is experimental.
+export function proveTypeOnly(text: string): { proven: true; inert: boolean } | { proven: false; reason: TypeOnlyReason; at: number | null }
+
 // `path` is the name at fault as its entry spelled it, and `tree` which tree
 // holds it.
 export class CompareError extends Error {

package/compare.js

@@ -25,5 +25,10 @@ export { renameParts } from './src/paths.js'
 // each old path, directory and package directory as the new tree lays it out.
 export { layoutDir, layoutPackageDirs, rootLabel, treeLayout } from './src/layout.js'
 
+// Whether a TypeScript text holds types alone, so that Node runs nothing of it,
+// as compareTrees stamps a declaration file's change: proven on Node alone, where
+// oxc-parser, an optional peer, is loaded on first use.
+export { proveTypeOnly } from '#types'
+
 // What a tree that does not hold together is refused with.
 export { CompareError } from './src/error.js'

package/names.d.ts

@@ -28,7 +28,9 @@ export type RenameReason = 'unparsed' | 'dynamic' | 'jsx' | 'block-function' | '
 // it; and the blocks checked to take `before` to the new side (thrown should
 // they not). `reason` says why no names were given; `reads` the properties
 // either text reads names through (`name`, `toString`, `stack`, `callee`,
-// `caller`), sorted, as code reading its names may act otherwise renamed;
+// `caller`), sorted, as code reading its names may act otherwise renamed:
+// none where none is renamed, and `name` only where a name renamed is a
+// function's or class's, the one name it reads (`function f`, `f = () => {}`);
 // `marks` the plain diff's blocks that differ in renamed names alone; and
 // `warnings` what a check that should never fail found.
 export function renamedDiff(before: string, after: string, options?: RenameOptions & { whitespace?: 'none' | 'all' | 'change' | 'trailing' }): Promise<{

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@preventive/compare",
-  "version": "1.0.2",
-  "description": "Two file trees compared as git diff compares them, with their line change sets and the patch git writes; and minified JavaScript compared with its layout and its renamed names set aside, each step checked to hide no change",
+  "version": "1.1.0",
+  "description": "Git-compatible file tree diffs and minified JavaScript comparison",
   "type": "module",
   "main": "./compare.js",
   "types": "./compare.d.ts",
@@ -31,6 +31,10 @@
     "#oxc": {
       "node": "./src/oxc.node.js",
       "default": "./src/oxc.js"
+    },
+    "#types": {
+      "node": "./src/types.node.js",
+      "default": "./src/types.js"
     }
   },
   "files": [
@@ -45,6 +49,7 @@
     "src/blocks.js",
     "src/changes.js",
     "src/css.js",
+    "src/erasure.js",
     "src/error.js",
     "src/layout.js",
     "src/marked.js",
@@ -71,6 +76,8 @@
     "src/similarity.js",
     "src/text.js",
     "src/tree.js",
+    "src/types.js",
+    "src/types.node.js",
     "src/whitespace.js",
     "src/words.js"
   ],

package/src/changes.js

@@ -1,10 +1,12 @@
 // compareTrees: a path in both trees is modified or type-changed, a path in one
 // added or deleted unless renames.js pairs it with another, as git diff -M does
-// and, unless `renamesByPath` is false, by the paths a build moves files to.
+// and, unless `renamesByPath` is false, by the paths a build moves files to; on
+// Node, a change to a declaration file holding types alone on each side stamped so.
 
+import { proveTypeOnly } from '#types'
 import { MAX_SCORE } from './similarity.js'
 import { findRenames } from './renames.js'
-import { checkLineOptions, contentOf } from './text.js'
+import { checkLineOptions, contentOf, textOf } from './text.js'
 import { readTree, sameContent } from './tree.js'
 
 // git's defaults: -M at 50%, diff.renameLimit at 1000.
@@ -42,6 +44,47 @@ const sameFile = (a, b) => sameContent(a, b) && (a.type !== 'file' || a.mode ===
 
 const status = (kind, old, fresh, similarity = null) => ({ status: kind, old, new: fresh, similarity })
 
+// A declaration file as TypeScript names one: `.d.ts`, `.d.mts`, `.d.cts`, and
+// `.d.css.ts` for a `.css` file's.
+const DECLARATION = /\.d\.(?:[^./]+\.)?[cm]?ts$/u
+
+// The module system a declaration file's extension fixes, or null where its package says and this cannot:
+// `.mts` an ES module, `.cts` a CommonJS one, a `.ts` either. `export {}` runs nothing as a module and
+// throws as CommonJS, so where the format is null, or the two sides' differ, it does not cancel.
+const fixedModule = (path) => (path.endsWith('.mts') ? 'module' : path.endsWith('.cts') ? 'commonjs' : null)
+
+// A file's proof: that it holds types alone, and whether that rests on a retained `export {}` (`inert`),
+// which runs nothing as a module but emits a marker transpiled to CommonJS. A side not there holds
+// nothing. Not proven where the proof throws, as no check should.
+function proven(file) {
+  if (file === null) return { proven: true, inert: false }
+  const text = textOf(file)
+  try {
+    return text === undefined ? { proven: false } : proveTypeOnly(text)
+  } catch {
+    return { proven: false }
+  }
+}
+
+// Stamped where each side there is a file named as a declaration file and proven to hold types alone, and
+// a retained `export {}` is on both sides or neither: on one alone it is a change in what runs once
+// transpiled, so the change is not types only. For it to cancel, the two extensions must fix the same
+// module format: a rename from a `.d.mts` to a `.d.cts` runs it, then throws on it, and a `.d.ts` leaves
+// the format to its package, which this cannot read, so a retained `export {}` in one never cancels.
+function stamped(change) {
+  const sides = [change.old, change.new].filter((file) => file !== null)
+  if (!sides.every((file) => file.type === 'file' && DECLARATION.test(file.path))) return change
+  // A mode changed, an executable bit set or cleared, is a change in its own right, types aside.
+  if (change.old && change.new && change.old.mode !== change.new.mode) return change
+  const fresh = proven(change.new), old = proven(change.old)
+  if (!old.proven || !fresh.proven || Boolean(old.inert) !== Boolean(fresh.inert)) return change
+  if (old.inert) {
+    const format = fixedModule(change.old.path)
+    if (format === null || format !== fixedModule(change.new.path)) return change
+  }
+  return { ...change, typeOnly: true }
+}
+
 function pathChanges(old, fresh) {
   const added = [], changes = [], deleted = []
   for (const [path, file] of old) {
@@ -86,5 +129,5 @@ export function compareTrees(a, b, { renames = true, renamesByPath = true, renam
   for (const [s, file] of deleted.entries()) if (!moved.has(s)) changes.push(status('deleted', file, null))
   // A rename stands at its new path, as git lists it.
   changes.sort((x, y) => byPath((x.new ?? x.old).path, (y.new ?? y.old).path))
-  return lines ? changes.map((change) => ({ ...change, ...contentOf(change.old, change.new, lineOptions) })) : changes
+  return (lines ? changes.map((change) => ({ ...change, ...contentOf(change.old, change.new, lineOptions) })) : changes).map(stamped)
 }

package/src/erasure.js

@@ -0,0 +1,109 @@
+// What Node's type stripping erases of TypeScript, as oxc's syntax tree has it, and what a text it
+// stripped may hold: Node reads a `.d.ts` as the `.ts` it is named and runs what it does not erase,
+// so a declaration file runs nothing only where stripping leaves nothing to run. Nothing here
+// parses; types.node.js gives both the tree and Node's text.
+
+// What stripping makes of a statement: nothing (`erased`); a bare `export {}` the source writes, left as
+// valid JavaScript that loads and runs nothing (`inert`); a statement that loads a module (`imports`); or
+// code -- `export as namespace N`, left verbatim as invalid JavaScript that throws when the file is
+// imported, among it.
+export const CODE = 'code', ERASED = 'erased', IMPORT = 'imports', INERT = 'inert'
+
+const TYPES = new Set(['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'])
+
+// A namespace not declared is erased where TypeScript emits nothing for it: it holds interfaces,
+// type aliases and such namespaces alone, exported or not. One declared within it is held to the
+// same, as Node holds it: `namespace N { declare namespace M { const x = 1 } }` is refused.
+function typesAlone(namespace) {
+  if (namespace.kind !== 'namespace') return false
+  if (namespace.body?.type === 'TSModuleDeclaration') return typesAlone(namespace.body)
+  if (namespace.body?.type !== 'TSModuleBlock') return false
+  return namespace.body.body.every((statement) => {
+    const node = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement
+    return TYPES.has(node?.type) || (node?.type === 'TSModuleDeclaration' && typesAlone(node))
+  })
+}
+
+// A declaration erased whole: a type, an interface, a function's signature, anything `declare`d
+// (its initializers and bodies with it), a namespace of types. A decorator is code, kept where
+// the class it decorates is erased (`@d declare class A {}` leaves `@d`).
+function erased(node) {
+  switch (node.type) {
+    case 'TSInterfaceDeclaration': case 'TSTypeAliasDeclaration': case 'TSDeclareFunction': return true
+    case 'VariableDeclaration': case 'TSEnumDeclaration': return node.declare === true
+    case 'ClassDeclaration': return node.declare === true && !(node.decorators?.length > 0)
+    case 'TSModuleDeclaration': return node.declare === true || typesAlone(node)
+    default: return false
+  }
+}
+
+// A statement of a program's, as stripping leaves it. `import type` and `export type` are erased whole,
+// loading nothing; `import { type A }` from a module loads it all the same, inline `type` or not, so it
+// is a module load. A bare `export {}` is inert; `export { type A }` is code, not inert: it is `export {}`
+// only once stripping takes its specifiers out, not as the source has it, and that a stripped no-op would
+// run nothing is no reason to call the source type-only.
+export function strippedAs(statement) {
+  switch (statement.type) {
+    case 'ImportDeclaration': return statement.importKind === 'type' ? ERASED : IMPORT
+    case 'ExportAllDeclaration': return statement.exportKind === 'type' ? ERASED : IMPORT
+    case 'TSImportEqualsDeclaration':
+      if (statement.importKind === 'type') return ERASED
+      return statement.moduleReference.type === 'TSExternalModuleReference' ? IMPORT : CODE
+    case 'ExportNamedDeclaration':
+      if (statement.declaration) return erased(statement.declaration) ? ERASED : strippedAs(statement.declaration)
+      if (statement.exportKind === 'type') return ERASED
+      if (statement.source) return IMPORT
+      return statement.specifiers.length === 0 ? INERT : CODE
+    case 'ExportDefaultDeclaration': return statement.declaration.type === 'TSInterfaceDeclaration' || statement.declaration.type === 'TSDeclareFunction' ? ERASED : CODE
+    // `export as namespace N` is left verbatim, invalid as JavaScript, so importing the file throws.
+    case 'TSNamespaceExportDeclaration': return CODE
+    default: return erased(statement) ? ERASED : CODE
+  }
+}
+
+// What a stripped text may hold, read token by token as no parser reads it: blanks and line breaks
+// (JavaScript's, `\s`), comments, a hashbang first, and `export {}` (empty, or what was all type
+// specifiers), with any trailing `;`.
+const LINE_END = /[\n\r\u2028\u2029]/gu
+const BLANK = /\s/u
+const EXPORT_EMPTY = [/export(?![\w$])/uy, /\{/uy, /\}/uy]
+
+function lineEnd(text, at) {
+  LINE_END.lastIndex = at
+  return LINE_END.test(text) ? LINE_END.lastIndex - 1 : text.length
+}
+
+// Past blanks and comments; an unclosed comment stays, for what follows to refuse.
+function skip(text, at) {
+  for (;;) {
+    const close = text.startsWith('/*', at) ? text.indexOf('*/', at + 2) : -1
+    if (BLANK.test(text[at] ?? '')) at++
+    else if (text.startsWith('//', at)) at = lineEnd(text, at)
+    else if (close === -1) return at
+    else at = close + 2
+  }
+}
+
+// Past an `export {}` from `from`, with any trailing `;`, or -1 where none starts there.
+function exportEmptyEnd(text, from) {
+  let at = from
+  for (const token of EXPORT_EMPTY) {
+    token.lastIndex = skip(text, at)
+    at = token.test(text) ? token.lastIndex : -1
+    if (at === -1) return -1
+  }
+  const semicolon = skip(text, at)
+  return text[semicolon] === ';' ? semicolon + 1 : at
+}
+
+// Where a stripped text first holds anything else, or -1 where it holds nothing else.
+export function leftover(text) {
+  let at = text.startsWith('#!') ? lineEnd(text, 0) : 0
+  for (;;) {
+    at = skip(text, at)
+    if (at === text.length) return -1
+    const end = exportEmptyEnd(text, at)
+    if (end === -1) return at
+    at = end
+  }
+}

package/src/names/analyze.js

@@ -10,6 +10,9 @@ const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFu
 const BLOCKS = new Set(['BlockStatement', 'ForStatement', 'ForInStatement', 'ForOfStatement', 'SwitchStatement'])
 // Globals that make a script a CommonJS module, its top level its own.
 const COMMONJS = new Set(['exports', 'module', 'require'])
+// A function or class with no name of its own, which takes the one it is bound to.
+const ANONYMOUS = new Set(['FunctionExpression', 'ArrowFunctionExpression', 'ClassExpression'])
+const NAMING_ASSIGNMENTS = new Set(['=', '&&=', '||=', '??='])
 
 // oxc is loaded outside the try: one missing is no text that won't parse. A text
 // oxc's semantic check finds an error in is one it can't vouch for.
@@ -90,6 +93,24 @@ function moduleNames(node, s) {
   else if (node.declaration?.id) s.keeping.add(node.declaration.id)
 }
 
+function anonymous(node) {
+  while (node?.type === 'ParenthesizedExpression') node = node.expression
+  return ANONYMOUS.has(node?.type) && !node.id
+}
+
+// The names functions and classes are named by, as `.name` reads them: a
+// declaration's or an expression's own, or the one an unnamed one is bound to
+// (`var f = () => {}`, `f = function () {}`, `(f = class {}) => f`).
+function namingNames(node, s) {
+  switch (node.type) {
+    case 'FunctionDeclaration': case 'FunctionExpression': case 'ClassDeclaration': case 'ClassExpression': if (node.id) s.naming.add(node.id); break
+    case 'VariableDeclarator': if (node.id.type === 'Identifier' && anonymous(node.init)) s.naming.add(node.id); break
+    case 'AssignmentPattern': if (node.left.type === 'Identifier' && anonymous(node.right)) s.naming.add(node.left); break
+    case 'AssignmentExpression': if (NAMING_ASSIGNMENTS.has(node.operator) && node.left.type === 'Identifier' && anonymous(node.right)) s.naming.add(node.left); break
+    default: break
+  }
+}
+
 // Names that are no variable's (keys, labels), names kept, and the properties
 // names are read through.
 function otherNames(node, s) {
@@ -181,7 +202,7 @@ function enter(node, where, s) {
 
 // A work list rather than a recursion: a minified file's expressions nest deeply.
 function walk(program) {
-  const s = { declarations: new Map(), scopes: [], variables: [], keeping: new Set(), others: new Set(), reads: new Set(), references: [], work: [] }
+  const s = { declarations: new Map(), scopes: [], variables: [], keeping: new Set(), others: new Set(), naming: new Set(), reads: new Set(), references: [], work: [] }
   s.root = Object.assign(scope(s, null, true), { strict: program.sourceType === 'module' || saysStrict(program.body) })
   s.work.push([program, s.root])
   while (s.work.length > 0) {
@@ -190,6 +211,7 @@ function walk(program) {
       if (!s.declarations.has(node) && !s.others.has(node)) s.references.push([node, where])
       continue
     }
+    namingNames(node, s)
     const reason = visit(node, where, s)
     if (reason) return { reason }
     enter(node, where, s)
@@ -207,7 +229,10 @@ function resolved(program, s) {
     if (variable) occurrences.push([node, variable, where])
     else globals.push([node, where])
   }
-  for (const [node, variable] of occurrences) if (s.keeping.has(node)) variable.kept = true
+  for (const [node, variable] of occurrences) {
+    if (s.keeping.has(node)) variable.kept = true
+    if (s.naming.has(node)) variable.naming = true
+  }
   const own = program.sourceType === 'module' || program.sourceType === 'commonjs' || globals.some(([node]) => COMMONJS.has(node.name))
   for (const variable of s.variables) variable.aside = variable.name.length <= RENAMED_MAX_LENGTH && MINIFIED.test(variable.name) && !variable.kept && (own || variable.scope !== s.root)
   // A shorthand property's two names are one, at one place.

package/src/names/pairing.js

@@ -3,6 +3,7 @@
 // each other, and two each the other's most counted pair, a tie pairing neither.
 
 import { changeSet } from '@preventive/diff'
+import { RESERVED } from './syntax.js'
 
 // Unchanged lines between changes that pair as unchanged ones, not as changed.
 const ANCHORED_RUN = 3
@@ -10,21 +11,125 @@ const ANCHORED_RUN = 3
 // Whitespace alone never tells a name apart.
 const changes = (a, b) => changeSet(a, b, { horizon: 0, whitespace: 'all' })
 
-// A text's lines with its renamable variables' names set aside (`key`), and
-// each line's such variables in order (`lines`).
-function keyed(text, { occurrences }) {
+// A text's lines with its renamable variables' names set aside (`key`), but
+// those `written` names (a pair found), each line's variables set aside in
+// order (`lines`), and where in its key each stood (`places`).
+function keyed(text, { occurrences }, written = () => null) {
   const starts = [0]
   for (let at = text.indexOf('\n'); at !== -1; at = text.indexOf('\n', at + 1)) starts.push(at + 1)
-  const lines = starts.map(() => [])
-  let at = 0, key = '', line = 0
+  const lines = starts.map(() => []), places = starts.map(() => [])
+  let at = 0, key = '', line = 0, removed = 0
   for (const [node, variable] of occurrences) {
     if (!variable.aside) continue
-    key += text.slice(at, node.start)
+    const name = written(variable)
+    for (; line + 1 < starts.length && starts[line + 1] <= node.start; line++) removed = 0
+    if (name === null) {
+      lines[line].push(variable)
+      places[line].push(node.start - starts[line] - removed)
+    }
+    key += text.slice(at, node.start) + (name ?? '')
+    removed += node.end - node.start - (name?.length ?? 0)
     at = node.end
-    while (line + 1 < starts.length && starts[line + 1] <= node.start) line++
-    lines[line].push(variable)
   }
-  return { key: key + text.slice(at), lines }
+  key += text.slice(at)
+  return { key, keys: key.split('\n'), lines, places }
+}
+
+// Lines as a diff that sets whitespace aside compares them.
+const SPACE = /[ \t\n\v\f\r]/gu
+const plain = (lines) => lines.map((line) => line.replace(SPACE, ''))
+
+// The kept lines of each side a run of changes could stand in place of: a run
+// bordered by lines alike its own may sit anywhere along them short of the next
+// run, as diff slides it, so which of those it leaves kept, facing which, is
+// the diff's pick and says nothing (a function added before one written alike
+// with names set aside: either's header may face the old one's) -- unless the
+// line it would keep instead reads the same variables (`same`), which say
+// the same either way.
+function slack(a, b, blocks, sameA, sameB) {
+  const loose = (lines, runs, same) => {
+    const flags = new Uint8Array(lines.length)
+    runs.forEach(([start, end], k) => {
+      const ceiling = runs[k + 1]?.[0] ?? lines.length, floor = k > 0 ? runs[k - 1][1] : 0
+      for (let e = end, s = start; s > floor && lines[s - 1] === lines[e - 1]; s--, e--) if (!same(s - 1, e - 1)) flags[s - 1] = 1
+      for (let e = end, s = start; e < ceiling && lines[s] === lines[e]; s++, e++) if (!same(e, s)) flags[e] = 1
+    })
+    return flags
+  }
+  return [loose(a, blocks.filter(({ a0, a1 }) => a1 > a0).map(({ a0, a1 }) => [a0, a1]), sameA),
+    loose(b, blocks.filter(({ b0, b1 }) => b1 > b0).map(({ b0, b1 }) => [b0, b1]), sameB)]
+}
+
+// Whether two of a run's lines, from `from`, read the same variables in order.
+const reading = (k, from = 0) => (x, y) => {
+  const one = k.lines[from + x], other = k.lines[from + y]
+  return one.length === other.length && one.every((variable, n) => variable === other[n])
+}
+
+// The pairs of lines a diff of `a` and `b` keeps, each told whether slack.
+function* kept(a, b, sameA, sameB) {
+  const text = (lines) => lines.map((line) => `${line}\n`).join('')
+  const blocks = changes(text(a), text(b))
+  const [looseA, looseB] = slack(a, b, blocks, sameA, sameB)
+  let i = 0, j = 0
+  for (const { a0, a1, b1 } of [...blocks, { a0: a.length, a1: a.length, b1: b.length }]) {
+    for (; i < a0; i++, j++) yield [i, j, looseA[i] || looseB[j]]
+    i = a1
+    j = b1
+  }
+}
+
+// A run of lines' tokens (`list`) and the variable each stands for (`at`): the
+// place a variable stood one token alike any other's. Null past MAX_TOKENS.
+const PLACE = '*', TOKEN = /[\p{ID_Continue}$\u200C\u200D]+|\S/gu
+// A diff's cost grows faster than its length: a change of more tokens a side
+// than this pairs by its lines alone.
+const MAX_TOKENS = 20000
+function tokens(k, from, to) {
+  const at = [], list = []
+  const add = (token, variable) => {
+    list.push(token)
+    at.push(variable)
+    return list.length <= MAX_TOKENS
+  }
+  const text = (line, start, end) => {
+    for (const [token] of k.keys[line].slice(start, end).matchAll(TOKEN)) if (!add(`=${token}`, null)) return false
+    return true
+  }
+  for (let line = from; line < to; line++) {
+    let start = 0
+    for (const [n, place] of k.places[line].entries()) {
+      if (!text(line, start, place) || !add(PLACE, k.lines[line][n])) return null
+      start = place
+    }
+    if (!text(line, start)) return null
+  }
+  return { list, at }
+}
+
+// A word but a keyword: what ties tokens kept together to their own place, as
+// punctuation and keywords alone line up any statement with any other.
+const WORD = /^=[\p{ID_Start}$_]/u
+const ties = (token) => WORD.test(token) && !RESERVED.has(token.slice(1))
+
+// The variables of a change that its tokens, diffed, keep facing each other in
+// a run of tokens kept together holding a word: its lines written anew, wrapped
+// or ended otherwise (`let t = ...;` -> `let t = ...,`), or reading more
+// variables or fewer (`f(a)` -> `f(b, c)`: none, `b` or `c` alike). Lines
+// reordered line up by punctuation alone, `aa(a, b); bb(b);` ->
+// `bb(y, z); aa(x);` facing `(a, b)` with `(y, z)`, which pairs nothing.
+function placed(ka, a0, a1, kb, b0, b1) {
+  const reads = (k, from, to) => k.lines.slice(from, to).some((line) => line.length > 0)
+  if (!reads(ka, a0, a1) || !reads(kb, b0, b1)) return []
+  const a = tokens(ka, a0, a1), b = a && tokens(kb, b0, b1)
+  if (!b) return []
+  const found = [], pairs = [...kept(a.list, b.list, (x, y) => a.at[x] === a.at[y], (x, y) => b.at[x] === b.at[y])]
+  for (let end = 1, start = 0; start < pairs.length; start = end++) {
+    while (end < pairs.length && pairs[end][0] === pairs[end - 1][0] + 1 && pairs[end][1] === pairs[end - 1][1] + 1) end++
+    const run = pairs.slice(start, end)
+    if (run.some(([x]) => ties(a.list[x]))) for (const [x, y, loose] of run) if (a.at[x] && !loose) found.push([a.at[x], b.at[y]])
+  }
+  return found
 }
 
 const tallies = () => ({ backward: new Map(), forward: new Map() })
@@ -33,40 +138,38 @@ function count(map, from, to) {
   map.get(from).set(to, (map.get(from).get(to) ?? 0) + 1)
 }
 
-// Pairs of lines counted, a long run of unchanged ones apart from the rest. In
-// a change of unlike lengths, lines alike but for a final `;` or `,` pair (a
-// declaration others now follow: `let t = ...;` -> `let t = ...,`).
+// Pairs of lines counted, a long run of unchanged ones apart from the rest, and
+// apart from both the variables a change's tokens pair (`tokened`). Lines
+// reading variables one side has and the other not say nothing. In a change of
+// unlike lengths, lines alike but for a final `;` or `,` pair (a declaration
+// others now follow: `let t = ...;` -> `let t = ...,`).
 function tallied(ka, kb) {
-  const changed = tallies(), unchanged = tallies()
-  // Lines reading variables one side has and the other not say nothing.
-  const tally = ({ backward, forward }, pa, pb) => {
-    const news = kb.lines[pb], olds = ka.lines[pa]
-    if (olds.length !== news.length) return
-    olds.forEach((variable, k) => {
-      count(forward, variable, news[k])
-      count(backward, news[k], variable)
-    })
+  const changed = tallies(), tokened = tallies(), unchanged = tallies()
+  const counted = ({ backward, forward }, variable, other) => {
+    count(forward, variable, other)
+    count(backward, other, variable)
   }
-  const keysA = ka.key.split('\n'), keysB = kb.key.split('\n')
-  const trimmed = (lines, from, to) => `${lines.slice(from, to).map((line) => line.replace(/[;,]\s*$/u, '')).join('\n')}\n`
+  const alike = (counts, olds, news) => olds.length === news.length && olds.forEach((variable, k) => counted(counts, variable, news[k]))
+  const trimmed = (lines, from, to) => plain(lines.slice(from, to).map((line) => line.replace(/[;,]\s*$/u, '')))
+  const blocks = changes(ka.key, kb.key)
+  const [looseA, looseB] = slack(plain(ka.keys), plain(kb.keys), blocks, reading(ka), reading(kb))
   let i = 0, j = 0
-  for (const block of [...changes(ka.key, kb.key), { a0: ka.lines.length, a1: ka.lines.length, b0: kb.lines.length, b1: kb.lines.length }]) {
-    const anchored = block.a0 - i >= ANCHORED_RUN
-    while (i < block.a0) tally(anchored ? unchanged : changed, i++, j++)
+  for (const block of [...blocks, { a0: ka.lines.length, a1: ka.lines.length, b0: kb.lines.length, b1: kb.lines.length }]) {
+    const counts = block.a0 - i >= ANCHORED_RUN ? unchanged : changed
+    for (; i < block.a0; i++, j++) if (!looseA[i] && !looseB[j]) alike(counts, ka.lines[i], kb.lines[j])
     const [olds, news] = [block.a1 - block.a0, block.b1 - block.b0]
-    if (olds === news) for (let k = 0; k < olds; k++) tally(changed, block.a0 + k, block.b0 + k)
-    else if (olds > 0 && news > 0) {
-      let x = 0, y = 0
-      for (const inner of [...changes(trimmed(keysA, block.a0, block.a1), trimmed(keysB, block.b0, block.b1)), { a0: olds, a1: olds, b0: news, b1: news }]) {
-        while (x < inner.a0) tally(changed, block.a0 + x++, block.b0 + y++)
-        x = inner.a1
-        y = inner.b1
+    if (olds > 0 && news > 0) {
+      if (olds === news) for (let k = 0; k < olds; k++) alike(changed, ka.lines[block.a0 + k], kb.lines[block.b0 + k])
+      else {
+        const pairs = kept(trimmed(ka.keys, block.a0, block.a1), trimmed(kb.keys, block.b0, block.b1), reading(ka, block.a0), reading(kb, block.b0))
+        for (const [x, y] of [...pairs].filter((pair) => !pair[2])) alike(changed, ka.lines[block.a0 + x], kb.lines[block.b0 + y])
       }
+      for (const [variable, other] of placed(ka, block.a0, block.a1, kb, block.b0, block.b1)) counted(tokened, variable, other)
     }
     i = block.a1
     j = block.b1
   }
-  return { changed, unchanged }
+  return { changed, tokened, unchanged }
 }
 
 // The most counted of those not yet paired, none where two tie.
@@ -101,11 +204,22 @@ function matched({ backward, forward }, { map, paired }, eligible = () => true)
 }
 
 // Unchanged lines pair first; changed ones then pair only what those say
-// nothing of, as `weak` pairs, the first to give way where names read wrongly.
+// nothing of, and a change's tokens only what no line says anything of: lines
+// reordered, a change's tokens may line up across them. Both are `weak` pairs,
+// the first to give way where names read wrongly. A second pass reads the
+// pairs found as names, so lines alike with every name set aside and diffed
+// against the wrong one line up by those.
 export function pairing(before, after, a, b) {
-  const { changed, unchanged } = tallied(keyed(before, a), keyed(after, b))
-  const found = { map: new Map(), paired: new Set() }
-  matched(unchanged, found)
-  const weak = new Set(matched(changed, found, (old, to) => !unchanged.forward.has(old) && !unchanged.backward.has(to)))
+  const found = { map: new Map(), paired: new Set() }, said = new Set(), weak = new Set()
+  const passes = [[() => null, () => null], [(variable) => found.map.get(variable)?.name ?? null, (variable) => (found.paired.has(variable) ? variable.name : null)]]
+  for (const [old, now] of passes) {
+    // A pass pairs nothing where every variable of a side is paired already.
+    if (!a.variables.some((variable) => variable.aside && !found.map.has(variable)) || !b.variables.some((variable) => variable.aside && !found.paired.has(variable))) break
+    const { changed, tokened, unchanged } = tallied(keyed(before, a, old), keyed(after, b, now))
+    for (const [counts, tier] of [[unchanged, false], [changed, true], [tokened, true]]) {
+      for (const variable of matched(counts, found, (from, to) => !said.has(from) && !said.has(to))) if (tier) weak.add(variable)
+      for (const variable of [...counts.forward.keys(), ...counts.backward.keys()]) said.add(variable)
+    }
+  }
   return { map: found.map, weak }
 }

package/src/names/rename.js

@@ -53,7 +53,10 @@ function renamedNames(before, after, { extension = 'js', otherExtension = extens
   if (!bindsAlike(before, text, a)) return { reason: 'unverified' }
   const changed = a.variables.filter((variable) => given.get(variable) !== variable.name)
   const renamed = changed.filter((variable) => paired.map.has(variable)).length
-  const reads = [...new Set([...a.reads, ...b.reads])].toSorted()
+  // A read of names can act otherwise only where one is renamed, and `.name` reads a function's or
+  // class's alone: one only where a name renamed is one's.
+  const naming = changed.some((variable) => variable.naming || paired.map.get(variable)?.naming)
+  const reads = changed.length === 0 ? [] : [...new Set([...a.reads, ...b.reads])].filter((read) => read !== 'name' || naming).toSorted()
   return { text, renamed, apart: changed.length - renamed, kind: { module: a.module, commonjs: a.commonjs, own: a.own }, reads }
 }
 

package/src/oxc.js

@@ -4,3 +4,4 @@ import { minifySync } from 'oxc-minify'
 import { parseSync } from 'oxc-parser'
 
 export const getOxc = () => ({ parseSync, minifySync })
+export const getParser = () => parseSync

package/src/oxc.node.js

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module'
 // oxc-parser and oxc-minify, optional peers, required on first use; one missing
 // is thrown as the environment's error, not taken for a text that won't parse.
 const require = createRequire(import.meta.url)
-let oxc
+let oxc, parser
 
 function load(name) {
   try {
@@ -14,3 +14,5 @@ function load(name) {
 }
 
 export const getOxc = () => (oxc ??= { parseSync: load('oxc-parser').parseSync, minifySync: load('oxc-minify').minifySync })
+// The parser alone, for what needs no minifier: a declaration file proven to hold types alone.
+export const getParser = () => (parser ??= load('oxc-parser').parseSync)

package/src/pretty.js

@@ -28,7 +28,11 @@ function numberSpelling(text) {
 }
 
 const sorted = (flags) => [...flags].toSorted().join('')
-const scriptForm = (text) => text.replaceAll(NUMBER, numberSpelling).replaceAll(/\\(?=["'])|[\s();]/gu, '').replaceAll("'", '"')
+// A script's text but for what the formatter may respell, beside the syntax tree compared after:
+// blanks, parentheses, semicolons, quotes, numbers and a regular expression's flags, and a comma before
+// a closing bracket, past any comments (`import { a, b, }`).
+const scriptForm = (text) => text.replaceAll(NUMBER, numberSpelling).replaceAll(/,(?=(?:\s|\/\/[^\n]*|\/\*[^]*?\*\/)*[\])}>])/gu, '')
+  .replaceAll(/\\(?=["'])|[\s();]/gu, '').replaceAll("'", '"')
   .replaceAll(/(?<=\/)[dgimsuvy]{2,}(?![\p{L}\p{N}_$])/gu, sorted)
 
 // JSON has no point without a digit either side: such a number is kept as written, or a copy would read as
@@ -45,7 +49,8 @@ function parsed(text, extension) {
   return result.errors.length > 0 ? null : result
 }
 
-const comments = ({ comments: list }) => list.map(({ type, value }) => `${type} ${indentless(value)}`)
+// A comment as written, but for its indentation and the blanks ending it, which formatting trims.
+const comments = ({ comments: list }) => list.map(({ type, value }) => `${type} ${indentless(value).replace(/[\t ]+$/u, '')}`)
 // `a && (b && c)` and `(a && b) && c` read alike, as do `||` and `??` chains.
 function chain(node, operator) {
   const operands = [], rest = [node]
@@ -79,14 +84,42 @@ function sameTree(a, b) {
   return true
 }
 
+// A script's types as the formatter writes them: a member's separator `;` where it was `,`
+// (`{ a: string, b: number }`), and no `|` or `&` before a union's or an intersection's first type
+// (`type P =\n  | A\n  | B`, `[K in\n  | A\n  | B]`). oxc reads a member with the separator ending it
+// and a union from the mark leading it, so each is taken where it is, in whatever context.
+function typed(text, program) {
+  const edits = [], work = [program]
+  while (work.length > 0) {
+    const node = work.pop()
+    // Pushed one by one: a spread of a file's statements could pass more arguments than a call takes.
+    if (Array.isArray(node)) for (const item of node) work.push(item)
+    else if (node !== null && typeof node === 'object') {
+      const members = node.type === 'TSTypeLiteral' ? node.members : node.type === 'TSInterfaceBody' ? node.body : []
+      for (const member of members) if (text[member.end - 1] === ',') edits.push([member.end - 1, ';'])
+      const mark = node.type === 'TSUnionType' ? '|' : node.type === 'TSIntersectionType' ? '&' : null
+      if (mark && text[node.start] === mark && node.types[0]?.start > node.start) edits.push([node.start, ''])
+      for (const key of Object.keys(node)) if (!POSITION.has(key) && typeof node[key] === 'object') work.push(node[key])
+    }
+  }
+  let from = 0, out = ''
+  for (const [at, put] of edits.toSorted(([x], [y]) => x - y)) {
+    out += text.slice(from, at) + put
+    from = at + 1
+  }
+  return out + text.slice(from)
+}
+
 // A safeguard on oxfmt's own output, not a comparison of any two texts: exported
 // for tests alone, not by the package. CSS is read by `csstree` where given.
 export function sameCode(text, formatted, extension = 'js', csstree = null) {
   if (extension === 'css') return csstree !== null && sameCss(csstree, text, formatted)
   if (extension === 'json') return sameList(jsonForm(text), jsonForm(formatted))
-  if (!SCRIPTS.has(extension) || scriptForm(text) !== scriptForm(formatted)) return false
+  if (!SCRIPTS.has(extension)) return false
   const [before, after] = [parsed(text, extension), parsed(formatted, extension)]
-  return before !== null && after !== null && sameList(comments(before), comments(after)) && sameTree(before.program, after.program)
+  if (before === null || after === null) return false
+  const form = (code, { program }) => scriptForm(/^[cm]?tsx?$/u.test(extension) ? typed(code, program) : code)
+  return form(text, before) === form(formatted, after) && sameList(comments(before), comments(after)) && sameTree(before.program, after.program)
 }
 
 // A script's block comments over more than one line, a license's say, each end their line: what oxfmt

package/src/types.js

@@ -0,0 +1,8 @@
+// types.node.js where Node does not run this: with no type stripping of Node's to hold oxc's tree to,
+// no text is proven to hold types alone, and neither oxc nor anything else is loaded for it.
+
+export function proveTypeOnly(text) {
+  if (typeof text !== 'string') throw new TypeError(`a text must be a string, not ${typeof text}`)
+  if (!text.isWellFormed()) throw new TypeError('a text must be a well-formed string')
+  return { proven: false, reason: 'unsupported', at: null }
+}

package/src/types.node.js

@@ -0,0 +1,114 @@
+// Whether a text holds types alone, proven on Node: Node runs a `.d.ts` it imports as the `.ts` it is
+// named, what its type stripping leaves of it, so oxc's syntax tree and that stripping itself must each
+// find nothing but types in it, the same to the character; what stripping leaves is read again apart from
+// either, and so is what its transform mode (--experimental-transform-types) leaves. The portable twin,
+// types.js, proves nothing and loads nothing. oxc-parser, an optional peer, is loaded on first use, and
+// without it nothing is proven: compareTrees, which stamps declaration files, needs no peer.
+
+import * as nodeModule from 'node:module'
+import { getParser } from '#oxc'
+import { CODE, ERASED, IMPORT, INERT, leftover, strippedAs } from './erasure.js'
+
+// Each a fresh result, never a shared object a caller could mutate into another's.
+const unsupported = () => ({ proven: false, reason: 'unsupported', at: null })
+const refused = (reason, at) => ({ proven: false, reason, at })
+
+// What stripping writes in place of what it erases is a blank of as many UTF-8 bytes (a space, a no-break
+// space, an en space; a space and a byte order mark for four), unit for unit; line breaks and other blanks
+// it keeps. Any blank but a line break is taken for one.
+const WRITTEN = /[^\S\n\r\u2028\u2029]/u
+const LINE_BREAK = /[\n\r\u2028\u2029]/u
+const BLANK = /\s/u
+
+// Node's stripping is one instance for the process, its loader of `.ts` files' too, and one stopped partway
+// (a stack overflowed, execution terminated) is not trusted again: one that threw here anything but its
+// refusal of a text, or that does not strip the canary as it should, as one stopped elsewhere may not.
+const untrusted = new WeakSet()
+const REFUSALS = new Set(['ERR_INVALID_TYPESCRIPT_SYNTAX', 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'])
+const CANARY = ['let a: "\u00E9\u4E00\u{1F600}" = 1 // c\n', 'let a   \u00A0\u2002 \uFEFF  = 1 // c\n']
+
+function parser() {
+  try {
+    return getParser()
+  } catch {
+    return null
+  }
+}
+
+// Node's stripping in either mode: null where this Node has none, built without it.
+function strip(stripTypeScriptTypes, text, mode) {
+  try {
+    return { code: stripTypeScriptTypes(text, { mode }) }
+  } catch (error) {
+    if (error?.code === 'ERR_NO_TYPESCRIPT') return null
+    if (!REFUSALS.has(error?.code)) untrusted.add(stripTypeScriptTypes)
+    return { error }
+  }
+}
+
+function trusted(stripTypeScriptTypes) {
+  if (!untrusted.has(stripTypeScriptTypes) && strip(stripTypeScriptTypes, CANARY[0], 'strip')?.code === CANARY[1]) return true
+  untrusted.add(stripTypeScriptTypes)
+  return false
+}
+
+// oxc's tree, or null where oxc throws rather than tells an error.
+function parsed(parseSync, text) {
+  try {
+    return parseSync('file.ts', text, { lang: 'ts', sourceType: 'module' })
+  } catch {
+    return null
+  }
+}
+
+// Where stripping and oxc's tree do not agree, or -1: stripping blanks what it erases and keeps line
+// breaks, and what it keeps that is no blank lies in a comment or the hashbang outside the statements
+// oxc finds erased, or in an inert one. A comment within an erased statement goes with it.
+function disagreement(text, code, { comments, program }, { erased, inert }) {
+  const kept = new Uint8Array(text.length)
+  for (const { start, end } of [...comments, ...inert, ...(program.hashbang ? [program.hashbang] : [])]) kept.fill(1, start, end)
+  for (const { start, end } of erased) kept.fill(0, start, end)
+  // A character stripping changed must become a blank, not a line break written over one; one it kept
+  // must be a blank, or lie in a span.
+  for (let i = 0; i < text.length; i++) {
+    if (code[i] === text[i] ? !kept[i] && !BLANK.test(code[i]) : !WRITTEN.test(code[i]) || LINE_BREAK.test(text[i])) return i
+  }
+  return -1
+}
+
+// proveTypeOnly with the stripping given: exported for tests alone, not by the package.
+export function proveWith(text, stripTypeScriptTypes) {
+  if (typeof text !== 'string') throw new TypeError(`a text must be a string, not ${typeof text}`)
+  if (!text.isWellFormed()) throw new TypeError('a text must be a well-formed string')
+  const parseSync = parser()
+  if (typeof stripTypeScriptTypes !== 'function' || parseSync === null || !trusted(stripTypeScriptTypes)) return unsupported()
+  // Stripping drops a byte order mark the text starts with.
+  const shift = text.startsWith('\uFEFF') ? 1 : 0
+  const body = text.slice(shift)
+  // Stripping goes first: oxc's parser, native, overflows its stack on nesting deep enough and ends the
+  // process, where stripping throws first, at less than half the depth on an 8 MB stack. oxc reads only
+  // what stripping read whole: it either strips it, or refuses what it does not erase once it has read it all.
+  const stripped = strip(stripTypeScriptTypes, body, 'strip')
+  if (stripped === null) return unsupported()
+  if ('error' in stripped && stripped.error?.code !== 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') return refused('unparsed', null)
+  const tree = parsed(parseSync, body)
+  if (tree === null) return refused('unparsed', null)
+  if (tree.errors.length > 0) return refused('unparsed', shift + (tree.errors[0].labels?.[0]?.start ?? 0))
+  const spans = { [ERASED]: [], [INERT]: [] }
+  for (const statement of tree.program.body) {
+    const kind = strippedAs(statement)
+    if (kind === IMPORT || kind === CODE) return refused(kind, shift + statement.start)
+    spans[kind].push(statement)
+  }
+  if ('error' in stripped || stripped.code.length !== body.length) return refused('disagree', null)
+  const at = disagreement(body, stripped.code, tree, spans)
+  const left = at === -1 ? leftover(stripped.code) : at
+  if (left !== -1) return refused('disagree', shift + left)
+  const transformed = strip(stripTypeScriptTypes, body, 'transform')
+  if (transformed === null) return unsupported()
+  // A retained `export {}` runs nothing as a module but emits a marker transpiled to CommonJS, so the file
+  // is types-but-for-it: `inert`, stamped by compareTrees only where both sides of a change match.
+  return 'code' in transformed && leftover(transformed.code) === -1 ? { proven: true, inert: spans[INERT].length > 0 } : refused('disagree', null)
+}
+
+export const proveTypeOnly = (text) => proveWith(text, nodeModule.stripTypeScriptTypes)