@preventive/compare 1.2.0 → 1.2.2

package/compare.d.ts

@@ -36,15 +36,27 @@ export type Status = 'added' | 'deleted' | 'modified' | 'renamed' | 'type-change
 // percentage of the new file the old one accounts for, 100 where the content
 // 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.
+// (`.d.ts`, `.d.mts`, `.d.cts`, `.d.css.ts`) and holds types alone but for a
+// runtime both sides leave the same, as proveTypeOnly proves: one touching
+// erased types and comments alone, a side not there leaving an empty runtime. A
+// retained module load or `export {}` runs the same on both sides only within
+// one module format -- an `export {}` emits a marker transpiled to CommonJS, a
+// module load runs as one format and throws as the other -- so where the runtime
+// loads a module, carries a bare `export {}`, or default-exports an identifier a
+// rename whose extensions fix different formats (a `.d.mts` to a `.d.cts`, or a
+// `.d.ts` to or from either) is not stamped, while a rename between two of the same
+// extension (two `.d.ts`, two `.d.mts`, two `.d.cts`) is; a hashbang, a directive or a pragma runs the same either
+// way, so a runtime of only those cancels across formats. A modification keeps its
+// path, hence its format, and a deleted file matches only an empty runtime; an
+// added one an empty runtime or a single bare `export {}`, as nothing loaded it
+// before and what now does runs nothing of that alone, as a module or not. A
+// rename is otherwise taken by its matching
+// source, as any file's is here: a relative load may resolve to another module
+// once the file moves, but that is shown as a rename of its own, not traced. A
+// modification of a package-resolved `.d.ts` is taken to keep its format, though
+// the `package.json` resolving it could change `type` between the trees and flip
+// it -- a change seen in the diff on its own, as format is read here from the
+// extension, not from a package. Absent off Node, and without oxc-parser.
 export interface FileStatus {
   status: Status
   old: TreeFile | null
@@ -192,33 +204,61 @@ export function rootLabel(root: Root | null, prefix: string): { prefix: string;
 // 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:
+// nests too deep for either (`unparsed`); a statement is neither erased nor a
+// module load binding a type nor a bare `export {}`, as `export { type A }`,
+// `export as namespace N` and a side-effect load that binds nothing are not
+// (`code`); or Node's stripping, or a reading of what it leaves, does not find
+// what oxc does (`disagree`).
+export type TypeOnlyReason = 'unsupported' | 'unparsed' | 'code' | 'disagree'
+
+// Whether `text`, read as TypeScript, holds types alone but for a `runtime` a
+// change must leave byte for byte untouched, so that Node, which reads a `.d.ts`
+// as the `.ts` it is named and runs what its type stripping leaves, runs only
+// that 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;
+//   alone -- and those it leaves to run: a module load that binds from it
+//   (`import`, `export *`, `export { a } from` a module, `import { type A }` whose
+//   inline `type` loads it all the same), a bare `export {}`, and `export default E`
+//   on a bare identifier (the idiom a declaration file's default export takes,
+//   `declare const _d: T; export default _d`). `export { type A }`
+//   is code, not a run statement: it is `export {}` only once stripping takes its
+//   specifiers out, not as the source has it; nor is `export as namespace N`, left
+//   as invalid JavaScript that throws when imported, nor a side-effect load that
+//   binds nothing -- a bare `import`, an empty `import {}`, `export {}` with a
+//   source -- which loads a module for no type, nor an `export default` of anything
+//   but a bare identifier (a value expression, an object, a class body);
 // - 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;
+//   and leaves nothing it does not, but comments, the hashbang and those;
+// - what it leaves, the run statements set aside, 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
+// `runtime` is built from those run statements and from the directive and pragma
+// comments stripping keeps -- a `/// <reference ... />`, a `//# sourceMappingURL=`
+// or `//# sourceURL=` and their legacy forms, comments a tool reads as more than prose --
+// the hashbang first and the rest in source order, joined by newlines; empty where the
+// file erases whole and carries none. A run statement is reduced: an inline type specifier
+// stripping blanks within it (`import { type A, B }`), and any comment within it, each become
+// a single blank, so a change to only those leaves `runtime` unchanged; its executable text and
+// its module specifier are kept to the character, so a load of another module still differs.
+// Known limit: that kept text is compared as written, so a change leaving a load runtime-identical
+// yet reformatting it withholds the stamp rather than passing -- a removed trailing inline-type
+// specifier leaving its comma (`{ B, }` where `{ B }` would stand), or a comment added where no
+// blank sat. This errs safe: the stamp is never given wrongly, only sometimes withheld. A
+// directive, a pragma and the hashbang stand as stripping leaves them, since what they say is the
+// point. A triple-slash directive counts only in the prologue,
+// before the first statement, where TypeScript honours it; below one it is prose, so moving
+// it out of the prologue drops it from `runtime`, as removing it does. `loads` is whether any
+// run statement is a module load, a bare `export {}`, or an `export default` on an identifier: the runtime that runs as one module
+// format and throws, or emits a different marker, as the other -- a hashbang, directive or
+// pragma does not. A change is types only where both sides prove and leave the same `runtime`:
+// it then touches erased types and ordinary comments alone. Where `loads`, a rename across
+// module formats does not cancel (see compareTrees' `typeOnly`); a runtime without it runs the
+// same either way and cancels across them. `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 }
+export function proveTypeOnly(text: string): { proven: true; runtime: string; loads: 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/compare",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Git-compatible file tree diffs and minified JavaScript comparison",
   "type": "module",
   "main": "./compare.js",

package/pretty.d.ts

@@ -1,7 +1,8 @@
 // `text` formatted by oxfmt as a file with `extension`, changing what is written
-// no more than layout needs (keys keep their quotes, no trailing commas or arrow
-// parentheses are added, template literals stay), the copy used only where checks
-// of oxfmt's output, apart from oxfmt, find it changes the layout alone:
+// no more than layout needs (keys keep their quotes, names their escapes, a comment
+// its place after an operator; no trailing commas or arrow parentheses are added,
+// template literals stay), the copy used only where checks of oxfmt's output, apart
+// from oxfmt, find it changes the layout alone:
 // - a script's (`js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts`, `tsx`) syntax tree as
 //   oxc parses it, its comments and its text;
 // - a style sheet's (`css`) tree as css-tree, an optional peer, parses it, but for

package/src/changes.js

@@ -49,15 +49,22 @@ const status = (kind, old, fresh, similarity = null) => ({ status: kind, old, ne
 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.
+// `.mts` an ES module, `.cts` a CommonJS one, a `.ts` either. A module load and `export {}` run as one and
+// throw as the other, so where a side's runtime is not empty and the format is null, or the two differ,
+// a change across them is not types only.
 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.
+// A runtime of a single bare `export {}`, any trailing `;`, as proveTypeOnly spells one: its blanks as the
+// source has them, a comment within it a single blank.
+const EXPORT_EMPTY = /^export\s*\{\s*\}\s*;?$/u
+
+// A file's proof: that it holds types alone but for its `runtime` -- a hashbang, the module loads and
+// `export {}` stripping leaves -- which a change must leave byte for byte untouched to be types only.
+// `loads` is whether that runtime holds a module load, `export {}`, or an `export default` on an identifier, the part that runs differently per
+// module format; a hashbang, a directive or a pragma does not, so a runtime of only those is format-free. A
+// side not there has none. Not proven where the proof throws, as no check should.
 function proven(file) {
-  if (file === null) return { proven: true, inert: false }
+  if (file === null) return { proven: true, runtime: '', loads: false }
   const text = textOf(file)
   try {
     return text === undefined ? { proven: false } : proveTypeOnly(text)
@@ -66,22 +73,34 @@ function proven(file) {
   }
 }
 
-// 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.
+// Stamped where each side there is a declaration file proven to hold types alone and the two leave the
+// same runtime -- a change touching only erased types (and comments). A mode changing is a change of its
+// own. Where that runtime loads a module, carries a bare `export {}`, or default-exports an identifier it runs
+// the same on both sides only within one module format, so a rename cancels it only between two extensions
+// that fix the same format -- two `.d.ts` (both package-resolved), two `.d.mts`, or two `.d.cts`; a rename
+// whose extensions differ (a `.d.mts` to a `.d.cts`, or a `.d.ts` to or from either) does not qualify, since
+// an extension pins a format where a package-resolved `.d.ts` leaves it open. A hashbang, a directive or a pragma runs the same either way,
+// so a runtime of only those cancels across formats. A modification keeps its path, hence its format, and
+// a deleted file matches only an empty runtime; an added one an empty runtime or a single bare `export {}`
+// (EXPORT_EMPTY). Nothing loaded an added file before, so only what else the diff changes can, shown as a
+// change of its own, and that loading runs nothing of a bare `export {}` alone: it runs nothing as a module
+// and throws on it as CommonJS, whatever the extension. A module load beside it would run another module.
+// A rename is taken by its matching source, as any file's is here: a relative load in the runtime may
+// resolve to another module once the file moves, but that is the rename's doing, shown as a rename of its
+// own, not traced. Known limitation: a package-resolved `.d.ts` is taken to keep its format across a
+// modification (same path) and to share one across a rename to another `.d.ts`, since format is read from
+// the extension, not resolved from a package. The governing `package.json` could differ -- edited between
+// the two trees, or a different one at the rename's destination -- and flip the format; that flip rides the
+// `package.json` change or the move, each seen in the diff on its own, and is not traced here.
+
 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
-  }
+  if (!old.proven || !fresh.proven) return change
+  if (old.runtime !== fresh.runtime && !(change.old === null && EXPORT_EMPTY.test(fresh.runtime))) return change
+  if (old.loads && change.old && change.new && change.old.path !== change.new.path && fixedModule(change.old.path) !== fixedModule(change.new.path)) return change
   return { ...change, typeOnly: true }
 }
 

package/src/erasure.js

@@ -4,9 +4,9 @@
 // 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.
+// valid JavaScript that loads and runs nothing (`inert`); an import or re-export that loads a module and
+// takes a binding from it (`imports`); or code -- `export as namespace N` left verbatim as invalid
+// JavaScript that throws when the file is imported, and a side-effect load binding nothing, among it.
 export const CODE = 'code', ERASED = 'erased', IMPORT = 'imports', INERT = 'inert'
 
 const TYPES = new Set(['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'])
@@ -37,14 +37,30 @@ function erased(node) {
   }
 }
 
+// An import or re-export that binds nothing and only loads its module: a side-effect `import`, an empty
+// `import {}`, or `export {}` with a source. Code in a declaration file's source -- it loads for effects
+// alone, naming no type -- but also what transform mode emits when it elides an inline-type import or
+// re-export, so the transformed-output check reads it as that elision, not as source code.
+export function bindingless(statement) {
+  if (statement.type === 'ImportDeclaration') return statement.importKind !== 'type' && statement.specifiers.length === 0
+  if (statement.type === 'ExportNamedDeclaration') return !statement.declaration && statement.exportKind !== 'type' && Boolean(statement.source) && statement.specifiers.length === 0
+  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.
+// run nothing is no reason to call the source type-only. An import or re-export that binds nothing from its
+// module -- a side-effect `import`, an empty `import {}`, or `export {}` with a source -- loads it for its
+// side effects alone: code a declaration file has no reason to hold, not a module named for a type.
 export function strippedAs(statement) {
   switch (statement.type) {
-    case 'ImportDeclaration': return statement.importKind === 'type' ? ERASED : IMPORT
+    case 'ImportDeclaration':
+      if (statement.importKind === 'type') return ERASED
+      // A side-effect import binds and names nothing: code a declaration file has no reason to hold, not a
+      // module a type comes from.
+      return bindingless(statement) ? CODE : IMPORT
     case 'ExportAllDeclaration': return statement.exportKind === 'type' ? ERASED : IMPORT
     case 'TSImportEqualsDeclaration':
       if (statement.importKind === 'type') return ERASED
@@ -52,9 +68,17 @@ export function strippedAs(statement) {
     case 'ExportNamedDeclaration':
       if (statement.declaration) return erased(statement.declaration) ? ERASED : strippedAs(statement.declaration)
       if (statement.exportKind === 'type') return ERASED
-      if (statement.source) return IMPORT
+      // A re-export with a source but no specifiers re-exports nothing yet loads the module, a side-effect
+      // load; `export { a } from` a module re-exports a binding. A bare `export {}`, no source, is a marker.
+      if (statement.source) return bindingless(statement) ? CODE : IMPORT
       return statement.specifiers.length === 0 ? INERT : CODE
-    case 'ExportDefaultDeclaration': return statement.declaration.type === 'TSInterfaceDeclaration' || statement.declaration.type === 'TSDeclareFunction' ? ERASED : CODE
+    case 'ExportDefaultDeclaration':
+      if (statement.declaration.type === 'TSInterfaceDeclaration' || statement.declaration.type === 'TSDeclareFunction') return ERASED
+      // `export default E`, a bare identifier, re-exports a binding by name: a run statement that runs as an
+      // ES module and throws as CommonJS, like `export {}`, so it is inert here, not code -- it is the idiom a
+      // declaration file's default export takes (`declare const _d: T; export default _d`). Any other default,
+      // a value expression or a class body among it, is code a declaration file has no reason to hold.
+      return statement.declaration.type === 'Identifier' ? INERT : 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

package/src/pretty.js

@@ -29,11 +29,11 @@ function numberSpelling(text) {
 
 const sorted = (flags) => [...flags].toSorted().join('')
 // 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, }`).
+// blanks, parentheses, semicolons, quotes and numbers, and a comma before a closing bracket, past any
+// comments (`import { a, b, }`). A regular expression's flags it may reorder are sorted where the
+// syntax tree has them (respelled).
 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
 // valid, as would one with other blanks than JSON's four, which stay.
@@ -84,32 +84,48 @@ 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]
+// Each node of a syntax tree given to `each`.
+function visit(program, each) {
+  const 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, ''])
+      each(node)
       for (const key of Object.keys(node)) if (!POSITION.has(key) && typeof node[key] === 'object') work.push(node[key])
     }
   }
+}
+
+// `text` with each of `edits`, `[from, to, put]`, none overlapping another.
+function edited(text, edits) {
   let from = 0, out = ''
-  for (const [at, put] of edits.toSorted(([x], [y]) => x - y)) {
-    out += text.slice(from, at) + put
-    from = at + 1
+  for (const [start, end, put] of edits.toSorted(([x], [y]) => x - y)) {
+    out += text.slice(from, start) + put
+    from = end
   }
   return out + text.slice(from)
 }
 
+// A script as the formatter may write it, read off its syntax tree: each regular expression's flags
+// sorted (`/x/yu` as `/x/uy`), and where it has `types`, 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 respelled(text, program, types) {
+  const edits = []
+  visit(program, (node) => {
+    if (node.regex) edits.push([node.end - node.regex.flags.length, node.end, sorted(node.regex.flags)])
+    if (!types) return
+    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, member.end, ';'])
+    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, node.start + 1, ''])
+  })
+  return edited(text, edits)
+}
+
 // 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) {
@@ -118,10 +134,76 @@ export function sameCode(text, formatted, extension = 'js', csstree = null) {
   if (!SCRIPTS.has(extension)) return false
   const [before, after] = [parsed(text, extension), parsed(formatted, extension)]
   if (before === null || after === null) return false
-  const form = (code, { program }) => scriptForm(/^[cm]?tsx?$/u.test(extension) ? typed(code, program) : code)
+  const form = (code, { program }) => scriptForm(respelled(code, program, /^[cm]?tsx?$/u.test(extension)))
   return form(text, before) === form(formatted, after) && sameList(comments(before), comments(after)) && sameTree(before.program, after.program)
 }
 
+// A name as written from where it starts, escapes and all.
+const NAME = /(?:\\u\{[\dA-Fa-f]+\}|\\u[\dA-Fa-f]{4}|[$\p{ID_Continue}\u{200C}\u{200D}])+/uy
+// What oxfmt may write after a block comment the file has after it: an operator, `,`, `?` or `:`.
+const MOVED = /[\t ]*([!%&*+,\-/:<=>?^|~]+|in(?:stanceof)?(?![$\p{ID_Continue}]))/uy
+const MARK = /[!%&*+,\-/:<=>?^|~]/u
+const NAME_PART = /[$\p{ID_Continue}]/u
+
+// Each name of a syntax tree, `[where it starts, what it reads, as written]`, in order: a shorthand
+// property's key and value, one name, once.
+function names(text, program) {
+  const found = new Map()
+  visit(program, (node) => {
+    if (node.type !== 'Identifier' && node.type !== 'PrivateIdentifier') return
+    const at = node.type === 'Identifier' ? node.start : node.start + 1
+    NAME.lastIndex = at
+    found.set(at, [at, node.name, NAME.exec(text)?.[0] ?? ''])
+  })
+  return [...found.values()].toSorted(([x], [y]) => x - y)
+}
+
+// Where the blanks on its line before `at` start.
+function blanksFrom(text, at) {
+  let from = at
+  while (from > 0 && (text[from - 1] === ' ' || text[from - 1] === '\t')) from--
+  return from
+}
+
+// The copy as the file writes what oxfmt writes otherwise, where that changes no more than its layout,
+// before it is checked as any copy is:
+// - a name's escapes, which oxfmt reads (`\u{61}` as `a`): a copy shows no character the file only
+//   escapes, one unseen, a joiner in a name say, or one like another;
+// - a block comment after an operator, a `,`, `?` or `:`, which oxfmt moves before it where the comment
+//   ends its line (`a &&/* c */\nb` as `a /* c */ && b`): where a comment is may matter to what reads
+//   it, a bundler a `#__PURE__` mark say, and a reader sees it where the file has it.
+// Names and comments are paired in order, as the check finds them alike or refuses the copy.
+function asWritten(text, code, extension) {
+  if (!SCRIPTS.has(extension) || !/\\u|\/\*/u.test(text)) return code
+  const [before, after] = [parsed(text, extension), parsed(code, extension)]
+  if (before === null || after === null) return code
+  const edits = []
+  const [olds, news] = [names(text, before.program), names(code, after.program)]
+  if (olds.length === news.length) {
+    olds.forEach(([, name, written], i) => {
+      const [at, read, spelled] = news[i]
+      if (written !== spelled && written.includes('\\') && name === read) edits.push([at, at + spelled.length, written])
+    })
+  }
+  const [was, now] = [before.comments, after.comments]
+  for (let i = 0; was.length === now.length && i < now.length; i++) {
+    // A run of comments on one line moves as one.
+    const first = i
+    while (i + 1 < now.length && /^[\t ]*$/u.test(code.slice(now[i].end, now[i + 1].start))) i++
+    MOVED.lastIndex = now[i].end
+    const from = blanksFrom(code, now[first].start), moved = MOVED.exec(code)
+    if (moved === null || from === 0 || code[from - 1] === '\n') continue
+    const [, mark] = moved
+    // One the copy has before the comment too stayed, the one after another (`a + /* c */ +b`).
+    if (code.startsWith(mark, from - mark.length)) continue
+    const at = blanksFrom(text, was[first].start) - mark.length
+    if (at >= 0 && text.startsWith(mark, at) && !(mark.startsWith('i') ? NAME_PART : MARK).test(text[at - 1] ?? '')) {
+      edits.push([from, now[first].start, `${mark === ',' ? '' : ' '}${mark} `], [now[i].end, now[i].end + moved[0].length, ''])
+    }
+  }
+  return edited(code, edits)
+}
+
 // A script's block comments over more than one line, a license's say, each end their line: what oxfmt
 // leaves after one on its last line (`*/ class A {`) goes to the next, indented as the comment's first
 // line is. A comment holding a line break ends a line to the parser already (`return /*\n*/ 1` returns),
@@ -151,10 +233,12 @@ export async function format(text, extension) {
   const oxfmt = await loadFormatter()
   const result = await oxfmt(`pretty.${extension}`, text, PRETTY_OPTIONS).catch(() => null)
   if (result === null || result.errors.length > 0) return { error: 'unformattable' }
-  // A check that fails in itself, its stack say, refuses the copy as one that finds it changed would.
+  // oxfmt's copy as it is, or where the check refuses it, as the file writes what oxfmt respelled: a
+  // copy the check takes respelled nothing so, as its text would differ. A check that fails in itself,
+  // its stack say, refuses the copy as one that finds it changed would.
+  const checked = (code) => (sameCode(text, code, extension, csstree) ? { code } : null)
   try {
-    const code = breakAfterComments(result.code, extension)
-    return sameCode(text, code, extension, csstree) ? { code } : { error: 'pretty-mismatch' }
+    return checked(breakAfterComments(result.code, extension)) ?? checked(breakAfterComments(asWritten(text, result.code, extension), extension)) ?? { error: 'pretty-mismatch' }
   } catch {
     return { error: 'pretty-mismatch' }
   }

package/src/types.node.js

@@ -7,7 +7,7 @@
 
 import * as nodeModule from 'node:module'
 import { getParser } from '#oxc'
-import { CODE, ERASED, IMPORT, INERT, leftover, strippedAs } from './erasure.js'
+import { CODE, ERASED, bindingless, 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 })
@@ -18,8 +18,29 @@ const refused = (reason, at) => ({ proven: false, reason, at })
 // 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 NOT_LINE_BREAK = /[^\n\r\u2028\u2029]/gu
 const BLANK = /\s/u
 
+// Comments a tool reads as more than prose, which stripping keeps verbatim: a triple-slash directive, which
+// pulls other declarations into the file's types, and a source map or source URL pragma, which names where
+// a tool looks (its legacy forms, `//@` and a `/*# */` block, among it). They join the runtime, so a change
+// to one shows there rather than passing as types only. A directive is one of TypeScript's named tags
+// (`reference`, `amd-module`, `amd-dependency`) carrying an attribute, so whitespace follows the name;
+// TypeScript lowercases the tag before matching, so the name is case-insensitive (`/// <REFERENCE .. />` is a
+// directive). A `/// <summary>`, a bare `/// <reference>` or `/// <reference/>` without an attribute, or any
+// other triple-slash comment is prose. A pragma likewise needs its grammar: the engine reads
+// `//# sourceMappingURL=` only with whitespace after the `#` or `@`, then blanks it skips, then a non-empty
+// value -- so `//#sourceURL=x` and an empty `//# sourceURL=` are prose, while `//# sourceURL=  x` names `x`
+// and is a pragma. The pragma name, unlike the directive tag, is case-sensitive: V8 reads only the exact
+// `sourceURL`/`sourceMappingURL`, so `//# SOURCEURL=x` is prose. Erring wide is safe here (a prose change
+// merely withholds a stamp), but matching every real directive or pragma is not optional: missing one would
+// stamp its change, so each is kept as broad as its effective grammar allows, no stricter. A directive steers
+// only where it leads the file, `prologue` true: TypeScript honours it before the first statement and reads
+// it as prose below one, so moving it out of the prologue drops it, as removing it does.
+const DIRECTIVE = /^\/\/\/\s*<(?:reference|amd-module|amd-dependency)\s/iu
+const PRAGMA = /^\/[/*][#@]\s+source(?:Mapping)?URL=\s*\S/u
+const steers = (text, prologue) => (DIRECTIVE.test(text) && prologue) || PRAGMA.test(text)
+
 // 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.
@@ -62,11 +83,13 @@ function parsed(parseSync, text) {
 }
 
 // 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 }) {
+// breaks, and what it keeps that is no blank lies in a comment, the hashbang, or a statement it leaves to
+// run -- a module load or `export {}` -- not in one oxc finds erased. A comment within an erased statement
+// (strip blanks it) goes with it. A type-only specifier within a kept import blanks, and the else branch
+// below allows it.
+function disagreement(text, code, { comments, program }, erased, runtime) {
   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 [...comments, ...runtime, ...(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.
@@ -76,6 +99,54 @@ function disagreement(text, code, { comments, program }, { erased, inert }) {
   return -1
 }
 
+// `code` with each span blanked to spaces, its line breaks kept, so what is left of the stripped text
+// once the statements it leaves to run are set aside can be read for anything else.
+function blankedOutside(code, spans) {
+  let out = code
+  for (const { start, end } of spans) out = out.slice(0, start) + out.slice(start, end).replace(NOT_LINE_BREAK, ' ') + out.slice(end)
+  return out
+}
+
+// A run statement's text for the signature, with what stripping erased within it and the comments it holds
+// reduced, so a change touching only those does not change the signature: an inline type specifier (`import
+// { type A, B }`) blanks to a run of blanks whose width tracks the type's name, and a comment within an
+// otherwise unchanged load (`import /* c */ { B }`) stands as text amid blanks. A gap between tokens is any
+// maximal run of blanks and comments; one holding a comment, or a character stripping erased (where `body`
+// and `code` differ), collapses whole to a single blank, comment and adjacent blanks together, so adding or
+// changing either does not shift the rest. A gap of only source blanks that stripping left (plain spacing
+// between tokens) is kept as is, so such a difference withholds the stamp rather than passing. Every
+// character stripping kept otherwise stays byte for byte: the executable syntax and, with their blanks and
+// all, the string literals -- a module specifier's quotes bound any blank run inside it and hold no comment,
+// and stripping never wrote there, so it is kept, and a load of another module (even one whose specifier
+// differs only in a blank) still differs here. Known limit: the kept text is read as written, so a load left
+// runtime-identical but reformatted still differs -- a removed trailing inline-type specifier leaving its
+// comma (`{ B, }` for `{ B }`), or a comment added where no blank sat. Closing that would mean canonicalizing
+// the executable text (Node's transform mode does, eliding the specifier and its comma), a wider signature
+// left for another change; erring this way only withholds a stamp, never gives a wrong one.
+function runtimeText(body, code, comments, { start, end }) {
+  const commented = new Uint8Array(end - start)
+  for (const comment of comments) {
+    if (comment.start >= start && comment.end <= end) commented.fill(1, comment.start - start, comment.end - start)
+  }
+  const reducible = (at) => BLANK.test(code[at]) || commented[at - start] === 1
+  let at = start, out = ''
+  while (at < end) {
+    if (reducible(at)) {
+      let drop = false, to = at
+      while (to < end && reducible(to)) {
+        if (body[to] !== code[to] || commented[to - start] === 1) drop = true
+        to++
+      }
+      out += drop ? ' ' : code.slice(at, to)
+      at = to
+    } else {
+      out += code[at]
+      at++
+    }
+  }
+  return out
+}
+
 // 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}`)
@@ -94,21 +165,49 @@ export function proveWith(text, stripTypeScriptTypes) {
   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]: [] }
+  // `erased` statements strip to blanks; `runtime` ones stripping leaves to run -- a module load or
+  // `export {}`. Anything else is code, which no declaration file of types alone holds.
+  const erased = [], runtime = []
   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 (kind === CODE) return refused('code', shift + statement.start)
+    ;(kind === ERASED ? erased : runtime).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
+  const at = disagreement(body, stripped.code, tree, erased, runtime)
+  if (at !== -1) return refused('disagree', shift + at)
+  // Set the run statements aside; the rest of the stripped text must be blanks, comments and a hashbang.
+  const left = leftover(blankedOutside(stripped.code, runtime))
   if (left !== -1) return refused('disagree', shift + left)
+  // Transform mode (--experimental-transform-types) reveals a construct strip under-erases as code: its
+  // output, read again, must hold nothing but run statements and what erased to nothing. A bindingless load
+  // is not under-erasure here: transform emits one where it elides an inline-type import or re-export (an
+  // `import { type A }` becomes a bare side-effect `import`), so it is allowed though its source form is code.
   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)
+  if ('error' in transformed) return refused('disagree', null)
+  const after = parsed(parseSync, transformed.code)
+  if (after === null || after.errors.length > 0 || after.program.body.some((statement) => strippedAs(statement) === CODE && !bindingless(statement))) return refused('disagree', null)
+  // The runtime a change must leave untouched to be types only: the hashbang, the module loads and
+  // `export {}` stripping leaves, and the directive and pragma comments it keeps -- in source order. Empty
+  // where the file erases whole and carries none. A run statement is read through runtimeText, so an inline
+  // type specifier or a comment within it does not count; the hashbang, a directive and a pragma stand
+  // verbatim, since what they say is the point. A triple-slash directive counts only in the prologue, before
+  // the first statement, where TypeScript honours it; a comment blanked within an erased statement reads as
+  // blanks here, so only a kept one steers. `loads` is whether any run statement is a module load, a bare
+  // `export {}`, or an `export default` on an identifier, the runtime that runs differently per module format
+  // -- a hashbang, directive or pragma does not.
+  const prologue = tree.program.body.length > 0 ? tree.program.body[0].start : stripped.code.length
+  const hashbang = tree.program.hashbang ? [tree.program.hashbang] : []
+  const steering = tree.comments.filter(({ start, end }) => steers(stripped.code.slice(start, end), start < prologue))
+  const verbatim = ({ start, end }) => stripped.code.slice(start, end)
+  const parts = [
+    ...hashbang.map((node) => ({ start: node.start, text: verbatim(node) })),
+    ...runtime.map((node) => ({ start: node.start, text: runtimeText(body, stripped.code, tree.comments, node) })),
+    ...steering.map((node) => ({ start: node.start, text: verbatim(node) })),
+  ]
+  const signature = parts.sort((a, b) => a.start - b.start).map((part) => part.text).join('\n')
+  return { proven: true, runtime: signature, loads: runtime.length > 0 }
 }
 
 export const proveTypeOnly = (text) => proveWith(text, nodeModule.stripTypeScriptTypes)