@napi-rs/cli 3.10.2 → 3.10.4

package/src/utils/misc.ts

@@ -4353,7 +4353,83 @@ export async function retireFailedSnapshotLeftover(
   return { outcome: 'kept' }
 }
 
-async function snapshotFileSystemTransactionInput(
+interface FileSystemTransactionSourceDrift {
+  /**
+   * Differences that make the copy an unfaithful image of the opened file, or
+   * that mean the path no longer names it. Always fatal.
+   */
+  hard: string[]
+  /**
+   * Differences a re-copy can settle: an inode attribute re-stamp on an
+   * otherwise identical file, or content that has not stopped moving yet.
+   * Retryable.
+   */
+  soft: string[]
+}
+
+/**
+ * Compare the source as it was before the copy against the pinned descriptor
+ * and the path after it, and name every field that moved.
+ *
+ * One message used to stand for eight independent conditions, which made a
+ * failure from a platform the author cannot reach (a FreeBSD CI VM, say)
+ * impossible to diagnose: a truncated read, a chmod, a timestamp re-stamp and a
+ * replaced path all read identically.
+ */
+function describeFileSystemTransactionSourceDrift(
+  before: BigIntStats,
+  after: BigIntStats,
+  bytesRead: number,
+  pathStats: BigIntStats | undefined,
+): FileSystemTransactionSourceDrift {
+  const hard: string[] = []
+  const soft: string[] = []
+  const note = (
+    into: string[],
+    field: string,
+    beforeValue: bigint,
+    afterValue: bigint,
+  ) => {
+    if (beforeValue !== afterValue) {
+      into.push(`${field} ${beforeValue} -> ${afterValue}`)
+    }
+  }
+  note(hard, 'dev', before.dev, after.dev)
+  note(hard, 'ino', before.ino, after.ino)
+  note(hard, 'size', before.size, after.size)
+  if (after.size !== BigInt(bytesRead)) {
+    hard.push(`bytesRead ${bytesRead} != size ${after.size}`)
+  }
+  note(soft, 'mode', before.mode, after.mode)
+  note(soft, 'mtimeNs', before.mtimeNs, after.mtimeNs)
+  note(soft, 'ctimeNs', before.ctimeNs, after.ctimeNs)
+  if (pathStats === undefined) {
+    hard.push('path identity vanished')
+  } else if (!pathStats.isFile()) {
+    hard.push('path identity is no longer a regular file')
+  } else if (!statIdentitiesMatch(before, pathStats)) {
+    hard.push(
+      `path identity ${before.dev}/${before.ino} -> ${pathStats.dev}/${pathStats.ino}`,
+    )
+  }
+  return { hard, soft }
+}
+
+/**
+ * How many times a snapshot re-copies a source that moved underneath it before
+ * giving up. See the drift classification comment inside
+ * {@link snapshotFileSystemTransactionInput}.
+ */
+const fileSystemTransactionSnapshotAttempts = 3
+
+/**
+ * Exported for unit tests; not part of the supported `@napi-rs/cli` surface.
+ *
+ * @param onAfterCopy test seam invoked with the 1-based attempt number after
+ * each copy pass and before the post-copy re-verification, so a test can mutate
+ * the source deterministically instead of racing a timer against the copy.
+ */
+export async function snapshotFileSystemTransactionInput(
   source: string,
   destination: string,
   mode?: number,
@@ -4364,6 +4440,7 @@ async function snapshotFileSystemTransactionInput(
   recordDestinationIdentity?: (
     identity: FileSystemTransactionFileIdentity,
   ) => Promise<void>,
+  onAfterCopy?: (attempt: number) => Promise<void>,
 ): Promise<FileSystemTransactionJournalFileState> {
   // All stats in this flow are bigint so every path-vs-handle continuity check
   // below compares exact 64-bit identity, never the lossy Number dev/ino: a
@@ -4416,7 +4493,6 @@ async function snapshotFileSystemTransactionInput(
         'changed before it could be snapshotted',
       )
     }
-    const finalMode = mode ?? Number(sourceStats.mode & 0o7777n)
     if (createDestinationParent) {
       await mkdir(dirname(destination), { recursive: true })
     }
@@ -4463,50 +4539,116 @@ async function snapshotFileSystemTransactionInput(
         }
         await recordDestinationIdentity(destinationIdentity)
       }
-      const hash = createHash('sha256')
       const buffer = Buffer.allocUnsafe(64 * 1024)
+      // A snapshot's job is to record a *consistent* copy, so the source is
+      // re-verified after the copy against the stats taken before it. Drift
+      // splits in two:
+      //
+      //   hard — dev, ino, size, bytes-read, path identity. The copy is not a
+      //     faithful image of the file that was opened, or the path no longer
+      //     names it. Never tolerated.
+      //   soft — mode, mtimeNs, ctimeNs on an otherwise identical inode. This
+      //     is a metadata re-stamp: a kernel, a permission normalization or a
+      //     stray `utimes` moves these without touching a byte, and it is a
+      //     routine thing to happen to a file this process itself just wrote
+      //     into its own staging directory. Failing a release build over it is
+      //     wrong — the recorded sha256 plus dev/ino/size already guarantee the
+      //     content — so redo the snapshot instead.
+      //
+      // Metadata alone cannot decide that, though, so a retry also has to
+      // reproduce the bytes. Each attempt rebases the baseline on what it just
+      // observed, and a timestamp only moves as far as its filesystem can
+      // express: where the clock is coarse, or where several writes land in one
+      // tick, a writer that rewrites the file in place at the same length moves
+      // no field this function compares. Metadata would read as settled while
+      // the copy mixed two versions of the file, and the hash of that mixture
+      // would be recorded as the authoritative one — nothing downstream ever
+      // reads the source again to notice. So an attempt that follows drift is
+      // accepted only when it hashes to exactly what the attempt before it
+      // hashed to: two passes in a row agreeing on the content is the evidence
+      // the source is settled. A hash that keeps moving is named as
+      // `contentHash` drift and spends the attempt bound like any other.
+      //
+      // The source descriptor is deliberately *not* re-opened between attempts
+      // — it pins the inode validated on the way in, so a retry can never adopt
+      // a successor swapped into the path.
+      let baselineStats = sourceStats
+      let sourceHash = ''
+      let previousHash: string | undefined
       let position = 0
-      while (true) {
-        const { bytesRead } = await sourceHandle.read(
-          buffer,
-          0,
-          buffer.length,
+      let drift: FileSystemTransactionSourceDrift | undefined
+      for (
+        let attempt = 1;
+        attempt <= fileSystemTransactionSnapshotAttempts;
+        attempt++
+      ) {
+        if (attempt > 1) {
+          // Discard the previous attempt's bytes. The destination inode is
+          // transaction-owned and unpublished, and its identity — already
+          // recorded above — is unaffected by a truncate.
+          await destinationHandle.truncate(0)
+        }
+        const hash = createHash('sha256')
+        position = 0
+        while (true) {
+          const { bytesRead } = await sourceHandle.read(
+            buffer,
+            0,
+            buffer.length,
+            position,
+          )
+          if (bytesRead === 0) {
+            break
+          }
+          hash.update(buffer.subarray(0, bytesRead))
+          let written = 0
+          while (written < bytesRead) {
+            const result = await destinationHandle.write(
+              buffer,
+              written,
+              bytesRead - written,
+              position + written,
+            )
+            written += result.bytesWritten
+          }
+          position += bytesRead
+        }
+        sourceHash = hash.digest('hex')
+        await onAfterCopy?.(attempt)
+        const [finalSourceStats, finalPathStats] = await Promise.all([
+          sourceHandle.stat({ bigint: true }),
+          lstatIfExists(source, { bigint: true }),
+        ])
+        drift = describeFileSystemTransactionSourceDrift(
+          baselineStats,
+          finalSourceStats,
           position,
+          finalPathStats,
         )
-        if (bytesRead === 0) {
+        // Rebase on what was just observed either way: on success it is the
+        // settled metadata the journal should record, and on soft drift it is
+        // the baseline the next attempt has to hold still against.
+        baselineStats = finalSourceStats
+        if (previousHash !== undefined && previousHash !== sourceHash) {
+          drift.soft.push(`contentHash ${previousHash} -> ${sourceHash}`)
+        }
+        previousHash = sourceHash
+        if (drift.hard.length > 0 || drift.soft.length === 0) {
           break
         }
-        hash.update(buffer.subarray(0, bytesRead))
-        let written = 0
-        while (written < bytesRead) {
-          const result = await destinationHandle.write(
-            buffer,
-            written,
-            bytesRead - written,
-            position + written,
+      }
+      if (drift && (drift.hard.length > 0 || drift.soft.length > 0)) {
+        const reasons = [...drift.hard, ...drift.soft]
+        if (drift.hard.length === 0) {
+          reasons.push(
+            `still drifting after ${fileSystemTransactionSnapshotAttempts} snapshot attempts`,
           )
-          written += result.bytesWritten
         }
-        position += bytesRead
-      }
-      const [finalSourceStats, finalPathStats] = await Promise.all([
-        sourceHandle.stat({ bigint: true }),
-        lstatIfExists(source, { bigint: true }),
-      ])
-      if (
-        !statIdentitiesMatch(sourceStats, finalSourceStats) ||
-        finalSourceStats.size !== sourceStats.size ||
-        finalSourceStats.size !== BigInt(position) ||
-        finalSourceStats.mode !== sourceStats.mode ||
-        finalSourceStats.mtimeNs !== sourceStats.mtimeNs ||
-        finalSourceStats.ctimeNs !== sourceStats.ctimeNs ||
-        finalPathStats?.isFile() !== true ||
-        !statIdentitiesMatch(sourceStats, finalPathStats)
-      ) {
         throw new Error(
-          `Filesystem transaction source changed while it was snapshotted: ${source}`,
+          `Filesystem transaction source changed while it was snapshotted: ${source} (${reasons.join('; ')})`,
         )
       }
+      const finalMode = mode ?? Number(baselineStats.mode & 0o7777n)
       await applyFileSystemTransactionMode(destinationHandle, destinationMode)
       await destinationHandle.sync()
       const finalDestinationStats = await destinationHandle.stat({
@@ -4538,7 +4680,7 @@ async function snapshotFileSystemTransactionInput(
       const sourceIdentityStats = await sourceHandle.stat({ bigint: true })
       return {
         dev: String(sourceIdentityStats.dev),
-        hash: hash.digest('hex'),
+        hash: sourceHash,
         ino: String(sourceIdentityStats.ino),
         mode: finalMode,
       }

package/src/utils/typegen.ts

@@ -1,5 +1,5 @@
 import { createRequire } from 'node:module'
-import { dirname, relative, resolve } from 'node:path'
+import { dirname, parse, relative, resolve } from 'node:path'
 
 import { sortBy } from 'es-toolkit'
 import type {
@@ -971,6 +971,220 @@ export function collectRelativeDeclarationSpecifiers(source: string): string[] {
   ]
 }
 
+/**
+ * The first construct in `source` a CommonJS declaration file cannot carry,
+ * or `undefined` when copying `source` into a `.d.cts` is honest.
+ *
+ * A `.d.cts` is read under `require` module-resolution mode, so a declaration
+ * that means one thing in an ESM file can mean another — or be a syntax error
+ * — once it lands there. The generated typedef needs none of those forms: its
+ * imports name packages or `node:` builtins, and everything it exports is a
+ * named `export declare`. A `--dts-header` can carry any declaration a module
+ * package can write, though, and silently copying one that resolves
+ * differently produces a `.d.cts` describing a module the loader is not.
+ * Those sources keep refusing, with the offending construct named, so the
+ * header can be fixed or `--dts` pointed at a `.d.cts` source instead.
+ *
+ * What refuses, and why:
+ *
+ * - `export default`, in any of its spellings — `export default x`,
+ *   `export default class`/`function`/`interface`/`enum`/`namespace`,
+ *   `export { x as default }`, `export * as default`. In a `.d.cts` `default`
+ *   is `module.exports.default` — a property the generated loader never
+ *   assigns — not the whole-callable shape a default export is in ESM. Inside
+ *   a `declare module` block `export default` describes that module's own
+ *   shape and carries over honestly, so only top-level defaults refuse.
+ * - A relative specifier that can land on a mode-dependent declaration:
+ *   `.js`-family spellings (`.js`, `.jsx`, `.ts`, `.tsx`) or extensionless
+ *   ones, which resolve `.d.cts`-first under `require` mode and
+ *   `.d.mts`-first under `import` mode — possibly a different file, and
+ *   certainly a different interpretation of the file they find. Explicit
+ *   module-format extensions (`.mjs`, `.mts`, `.cjs`, `.cts`) and non-script
+ *   targets (`.json`, `.wasm`, `.node`, assets) resolve identically either
+ *   way. Bare specifiers (`buffer`, `node:stream/web`, package names) are
+ *   allowed — a dual-condition package's `types` entry can still diverge
+ *   (`import` vs `require` condition), but refusing them would defeat the
+ *   derivation: the generated typedef's own imports are all bare.
+ * - `with { … }` attributes on a runtime `import`/`export … from` statement:
+ *   TS2856 in a `.cts` file. Type-only statements may keep theirs, and a
+ *   `resolution-mode` attribute pins the specifier to one mode — either way
+ *   the same mode `.d.cts` or the source's own — so it is honest again.
+ *
+ * Everything else — `export declare`, interfaces, enums, namespaces,
+ * `export =`, `declare global`, `/// <reference path>` — reads the same on
+ * both sides. One deliberate gap: `import('…')` types inside JSDoc comments
+ * are not scanned — they need a separate JSDoc parse for a source class the
+ * generator never emits.
+ */
+export function commonJsDeclarationBarrier(source: string): string | undefined {
+  const typeScript = loadTypeScript()
+  const sourceFile = parseDeclarationFile(source)
+
+  const specifierBarrier = (
+    literal: import('typescript').StringLiteralLike,
+  ): string | undefined => {
+    if (!literal.text.startsWith('.')) {
+      return undefined
+    }
+    const extension = parse(literal.text).ext.toLowerCase()
+    if (
+      extension !== '' &&
+      !['.js', '.jsx', '.ts', '.tsx'].includes(extension)
+    ) {
+      return undefined
+    }
+    return `a relative '${literal.text}' specifier`
+  }
+
+  const hasResolutionMode = (
+    attributes: import('typescript').ImportAttributes | undefined,
+  ) =>
+    attributes?.elements.some(
+      (element) =>
+        element.name.text === 'resolution-mode' &&
+        typeScript.isStringLiteral(element.value) &&
+        (element.value.text === 'import' || element.value.text === 'require'),
+    ) === true
+
+  const hasDefaultModifier = (node: Node) =>
+    typeScript.canHaveModifiers(node) === true &&
+    typeScript
+      .getModifiers(node)
+      ?.some(
+        (modifier) => modifier.kind === typeScript.SyntaxKind.DefaultKeyword,
+      ) === true
+
+  const isTypeOnlyStatement = (
+    node:
+      | import('typescript').ImportDeclaration
+      | import('typescript').ExportDeclaration,
+  ) =>
+    typeScript.isImportDeclaration(node)
+      ? node.importClause?.isTypeOnly === true
+      : node.isTypeOnly === true
+
+  let barrier: string | undefined
+  const visit = (node: Node, insideModuleDeclaration: boolean): void => {
+    if (barrier !== undefined) {
+      return
+    }
+    if (!insideModuleDeclaration && hasDefaultModifier(node)) {
+      barrier = 'an `export default` declaration'
+      return
+    }
+    if (typeScript.isModuleDeclaration(node)) {
+      if (typeScript.isStringLiteralLike(node.name)) {
+        barrier = specifierBarrier(node.name)
+      }
+      if (barrier === undefined) {
+        // A `declare module`/`declare global` block's statements describe that
+        // module's own shape, so a `default` export inside one is honest; its
+        // specifiers still resolve relative to this file.
+        typeScript.forEachChild(node, (child) => visit(child, true))
+      }
+      return
+    }
+    if (
+      typeScript.isImportDeclaration(node) ||
+      typeScript.isExportDeclaration(node)
+    ) {
+      if (node.attributes !== undefined && !isTypeOnlyStatement(node)) {
+        barrier = '`with` attributes on a runtime module statement'
+        return
+      }
+      if (
+        node.moduleSpecifier !== undefined &&
+        typeScript.isStringLiteralLike(node.moduleSpecifier) &&
+        !hasResolutionMode(node.attributes)
+      ) {
+        barrier = specifierBarrier(node.moduleSpecifier)
+        if (barrier !== undefined) {
+          return
+        }
+      }
+      if (
+        !insideModuleDeclaration &&
+        typeScript.isExportDeclaration(node) &&
+        node.exportClause !== undefined &&
+        ((typeScript.isNamedExports(node.exportClause) &&
+          node.exportClause.elements.some(
+            (element) => element.name.text === 'default',
+          )) ||
+          (typeScript.isNamespaceExport(node.exportClause) &&
+            node.exportClause.name.text === 'default'))
+      ) {
+        barrier = 'a `default` re-export'
+      }
+      return
+    }
+    if (typeScript.isImportEqualsDeclaration(node)) {
+      if (
+        typeScript.isExternalModuleReference(node.moduleReference) &&
+        typeScript.isStringLiteralLike(node.moduleReference.expression)
+      ) {
+        barrier = specifierBarrier(node.moduleReference.expression)
+      }
+      return
+    }
+    if (typeScript.isExportAssignment(node)) {
+      if (node.isExportEquals !== true && !insideModuleDeclaration) {
+        barrier = 'an `export default` declaration'
+      }
+      return
+    }
+    if (typeScript.isImportTypeNode(node)) {
+      if (
+        typeScript.isLiteralTypeNode(node.argument) &&
+        typeScript.isStringLiteralLike(node.argument.literal) &&
+        !hasResolutionMode(node.attributes)
+      ) {
+        barrier = specifierBarrier(node.argument.literal)
+      }
+      // `import('pkg').T<import('./x.js').U>` nests another specifier in the
+      // type arguments — keep descending.
+      if (barrier === undefined) {
+        typeScript.forEachChild(node, (child) =>
+          visit(child, insideModuleDeclaration),
+        )
+      }
+      return
+    }
+    if (
+      typeScript.isCallExpression(node) &&
+      node.arguments.length >= 1 &&
+      typeScript.isStringLiteralLike(node.arguments[0]) &&
+      (node.expression.kind === typeScript.SyntaxKind.ImportKeyword ||
+        (typeScript.isIdentifier(node.expression) &&
+          node.expression.text === 'require'))
+    ) {
+      barrier = specifierBarrier(node.arguments[0])
+      return
+    }
+    typeScript.forEachChild(node, (child) =>
+      visit(child, insideModuleDeclaration),
+    )
+  }
+  for (const statement of sourceFile.statements) {
+    visit(statement, false)
+  }
+  if (barrier === undefined) {
+    // `/// <reference types>` resolves through module resolution — a relative
+    // name can diverge the same way a relative specifier can. `path`
+    // references are file-path resolution and carry over honestly.
+    for (const reference of typeScript.preProcessFile(source, true, true)
+      .typeReferenceDirectives) {
+      if (
+        reference.fileName.startsWith('.') &&
+        reference.resolutionMode === undefined
+      ) {
+        barrier = `a relative '/// <reference types="${reference.fileName}" />' directive`
+        break
+      }
+    }
+  }
+  return barrier
+}
+
 function collectRelativeDeclarationSpecifierReferences(
   source: string,
 ): DeclarationSpecifierReference[] {
@@ -1007,6 +1221,11 @@ function collectRelativeDeclarationSpecifierReferences(
       typeScript.isStringLiteralLike(node.argument.literal)
     ) {
       addStringLiteral(node.argument.literal)
+    } else if (
+      typeScript.isModuleDeclaration(node) &&
+      typeScript.isStringLiteralLike(node.name)
+    ) {
+      addStringLiteral(node.name)
     } else if (
       typeScript.isExternalModuleReference(node) &&
       node.expression &&
@@ -1015,7 +1234,7 @@ function collectRelativeDeclarationSpecifierReferences(
       addStringLiteral(node.expression)
     } else if (
       typeScript.isCallExpression(node) &&
-      node.arguments.length === 1 &&
+      node.arguments.length >= 1 &&
       typeScript.isStringLiteralLike(node.arguments[0]) &&
       (node.expression.kind === typeScript.SyntaxKind.ImportKeyword ||
         (typeScript.isIdentifier(node.expression) &&