@napi-rs/cli 3.10.3 → 3.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/cli",
-  "version": "3.10.3",
+  "version": "3.10.4",
   "description": "Cli tools for napi-rs",
   "author": "LongYinan <lynweklm@gmail.com>",
   "homepage": "https://napi.rs/",

package/src/api/__tests__/build.spec.ts

@@ -831,6 +831,263 @@ test('a fresh WASI declaration narrows the inherited root union', async (t) => {
 const ROOT_BINDING_TARGET_DECLARATION =
   "export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'"
 
+test('an ESM root declaration derives the WASI declaration unless it cannot cross', async (t) => {
+  const { tmpDir, projectDir, typeDefDir } = t.context
+  await writeFile(
+    join(typeDefDir, 'sum.type'),
+    '{"kind":"fn","name":"sum","def":"function sum(a: number, b: number): number"}\n',
+  )
+  const { dts } = await generateTypeDef({
+    typeDefDir,
+    cwd: projectDir,
+    declareBindingTarget: true,
+  })
+
+  // A `"type": "module"` package's `index.d.ts` is an ESM declaration, and so
+  // is an explicit `.d.mts` — but the generated typedef carries nothing a
+  // `.d.cts` cannot re-declare, so the WASI declaration derives verbatim.
+  // (napi-rs#3531: an unconditional refusal failed every WASI build in a
+  // module package, including `--esm` ones.)
+  const sourcePath = join(projectDir, 'index.d.ts')
+  const destinationPath = join(projectDir, 'pkg.wasi.d.cts')
+  for (const esmSourcePath of [sourcePath, join(projectDir, 'index.d.mts')]) {
+    t.is(
+      prepareWasiBindingTypeDef(
+        dts,
+        esmSourcePath,
+        destinationPath,
+        true,
+        'module',
+      ),
+      dts,
+    )
+  }
+
+  // The threadless flavor still gets its node-global rewrites on the way, and
+  // what it emits is valid TypeScript beside the ESM source it came from.
+  const threadless = prepareWasiBindingTypeDef(
+    dts,
+    sourcePath,
+    destinationPath,
+    false,
+    'module',
+  )
+  const codes = await semanticDiagnosticCodes(join(tmpDir, 'esm-derived'), {
+    'index.d.ts': dts,
+    'pkg.wasi.d.cts': threadless,
+  })
+  t.deepEqual(codes['pkg.wasi.d.cts'], [])
+
+  // Only the constructs a CommonJS declaration cannot carry still refuse —
+  // each one named in the error, from `.d.ts` and `.d.mts` sources alike.
+  const hazards: Array<[what: string, source: string, barrier: string]> = [
+    [
+      'an `export default` declaration',
+      'export declare function sum(a: number): number\nexport default sum\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default class declaration',
+      'export default class Sum {}\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default function declaration',
+      'export default function sum(a: number): number\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default interface declaration',
+      'export default interface Sum { a: number }\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default namespace declaration',
+      'export default namespace Sum { const a: number }\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a `default` re-export',
+      'declare const sum: number\nexport { sum as default }\n',
+      'a `default` re-export',
+    ],
+    [
+      'a `default` re-export from a package',
+      "export { sum as default } from 'sums'\n",
+      'a `default` re-export',
+    ],
+    [
+      'a type-only `default` re-export',
+      'type Sum = number\nexport type { Sum as default }\n',
+      'a `default` re-export',
+    ],
+    [
+      'a `default` namespace re-export',
+      "export * as default from 'sums'\n",
+      'a `default` re-export',
+    ],
+    [
+      'a relative import specifier',
+      "import { sum } from './sum.js'\nexport declare function f(): typeof sum\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'an extensionless relative specifier',
+      "import { sum } from './sum'\nexport declare function f(): typeof sum\n",
+      "a relative './sum' specifier",
+    ],
+    [
+      'a relative export specifier',
+      "export { sum } from './sum.js'\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative export-star specifier',
+      "export * from './sums.js'\n",
+      "a relative './sums.js' specifier",
+    ],
+    [
+      'a relative import type specifier',
+      "import type { Sum } from './sum.js'\nexport declare function f(s: Sum): void\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative import() type',
+      "export declare function f(): import('./sum.js').Sum\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative import-equals specifier',
+      "import sum = require('./sum.js')\nexport declare function f(): typeof sum\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative ambient module specifier',
+      "declare module './sum.js' { export const sum: number }\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative types reference',
+      "/// <reference types='./sum' />\nexport declare const sum: number\n",
+      'a relative \'/// <reference types="./sum" />\' directive',
+    ],
+    [
+      'attributes on a runtime statement',
+      "import sum from './sum.json' with { type: 'json' }\nexport declare const s: typeof sum\n",
+      '`with` attributes on a runtime module statement',
+    ],
+  ]
+  const esmSources: Array<
+    [path: string, packageType: 'module' | 'commonjs' | undefined]
+  > = [
+    [sourcePath, 'module'],
+    [join(projectDir, 'index.d.mts'), undefined],
+  ]
+  for (const [what, source, barrier] of hazards) {
+    for (const [esmSourcePath, packageType] of esmSources) {
+      const error = t.throws(
+        () =>
+          prepareWasiBindingTypeDef(
+            source,
+            esmSourcePath,
+            destinationPath,
+            true,
+            packageType,
+          ),
+        { instanceOf: Error },
+      )
+      t.true(
+        error?.message.includes(barrier),
+        `${what} names the offending construct, got: ${error?.message}`,
+      )
+    }
+  }
+
+  // Everything else a module package can write crosses honestly.
+  const honest: Record<string, string> = {
+    'bare and node: imports':
+      "import { Buffer } from 'buffer'\nimport type { ReadableStream } from 'node:stream/web'\nexport declare function f(b: Buffer, s: ReadableStream): void\n",
+    '.mjs specifiers':
+      "import { sum } from './sum.mjs'\nexport declare function f(): typeof sum\n",
+    '.cjs specifiers':
+      "import { sum } from './sum.cjs'\nexport declare function f(): typeof sum\n",
+    'an export assignment':
+      'declare const binding: { sum(a: number): number }\nexport = binding\n',
+    'a declare global block':
+      'declare global { namespace Legacy { const v: number } }\nexport {}\n',
+    'a bare ambient module':
+      "declare module 'legacy' { export const sum: number }\n",
+    'a .mjs ambient module':
+      "declare module './sum.mjs' { export const sum: number }\n",
+    'a default inside an ambient module':
+      "declare module 'legacy' { const sum: number\nexport default sum }\n",
+    'a type-only import with resolution-mode':
+      "import type { Sum } from './sum.js' with { 'resolution-mode': 'import' }\nexport declare function f(s: Sum): void\n",
+    'a type-only import pinned to require mode':
+      "import type { Sum } from './sum.js' with { 'resolution-mode': 'require' }\nexport declare function f(s: Sum): void\n",
+    'a type-only export with resolution-mode':
+      "export type { Sum } from './sum.js' with { 'resolution-mode': 'import' }\n",
+    'a json specifier':
+      "import sum from './sum.json'\nexport declare const s: typeof sum\n",
+    'a path reference':
+      "/// <reference path='./sum.d.ts' />\nexport declare const sum: number\n",
+    'a bare import() type':
+      "export declare function f(): import('buffer').Buffer\n",
+    'an import() type pinned to import mode':
+      "export declare function f(): import('./sum.js', { with: { 'resolution-mode': 'import' } }).Sum\n",
+    'a namespace export':
+      'export declare namespace Legacy { const sum: number }\n',
+  }
+  for (const [what, source] of Object.entries(honest)) {
+    t.notThrows(
+      () =>
+        prepareWasiBindingTypeDef(
+          source,
+          sourcePath,
+          destinationPath,
+          true,
+          'module',
+        ),
+      what,
+    )
+  }
+
+  // Nothing is scanned when the source is already CommonJS — a `.d.cts` (or a
+  // `.d.ts` in a `commonjs` package) reads the same beside its destination, so
+  // every hazard above carries over verbatim.
+  for (const [, source] of hazards) {
+    for (const [cjsSourcePath, packageType] of [
+      [join(projectDir, 'index.d.cts'), 'module'],
+      [sourcePath, 'commonjs'],
+      [sourcePath, undefined],
+    ] as const) {
+      t.notThrows(() =>
+        prepareWasiBindingTypeDef(
+          source,
+          cjsSourcePath,
+          destinationPath,
+          true,
+          packageType,
+        ),
+      )
+    }
+  }
+
+  // A specifier that can cross still rebases onto the destination directory
+  // — including a `declare module` augmentation name, which targets the file
+  // it spells out.
+  const relocated = prepareWasiBindingTypeDef(
+    "/// <reference path='./sum.d.ts' />\ndeclare module './sum.mjs' { export const sum: number }\nexport declare function f(): import('./sum.mjs').Sum\nexport { sum } from './sum.mjs'\n",
+    join(projectDir, 'types', 'index.d.mts'),
+    destinationPath,
+    true,
+  )
+  t.true(relocated.includes("declare module './types/sum.mjs'"))
+  t.true(relocated.includes("import('./types/sum.mjs')"))
+  t.true(relocated.includes("from './types/sum.mjs'"))
+  t.true(relocated.includes("reference path='./types/sum.d.ts'"))
+})
+
 test('a crate without type defs still declares the binding target', async (t) => {
   const { projectDir, typeDefDir } = t.context
 

package/src/api/build.ts

@@ -21,6 +21,7 @@ import type { BuildOptions as RawBuildOptions } from '../def/build.js'
 import {
   CLI_VERSION,
   commitFileSystemTransaction,
+  commonJsDeclarationBarrier,
   copyFileAtomic,
   type Crate,
   debugFactory,
@@ -795,6 +796,16 @@ export function bindingTargetDeclarationPredicate(input: {
     (input.rootLoaderCandidate && (input.hasWasiFallback || exports.length > 0))
 }
 
+/**
+ * The `.d.cts` content for a WASI flavor loader, derived from the root
+ * declaration this build wrote.
+ *
+ * An ESM source (`*.d.mts`, or `*.d.ts` in a `"type": "module"` package) is
+ * re-declared verbatim when nothing in it changes meaning under CommonJS
+ * interpretation — which is everything a generated typedef and most
+ * `--dts-header`s contain. {@link commonJsDeclarationBarrier} names the
+ * constructs that still refuse, and why.
+ */
 export function prepareWasiBindingTypeDef(
   source: string,
   sourcePath: string,
@@ -803,12 +814,15 @@ export function prepareWasiBindingTypeDef(
   packageType?: 'module' | 'commonjs',
 ) {
   if (
-    sourcePath.endsWith('.d.mts') ||
-    (sourcePath.endsWith('.d.ts') && packageType === 'module')
+    sourcePath.endsWith('.mts') ||
+    (sourcePath.endsWith('.ts') && packageType === 'module')
   ) {
-    throw new Error(
-      `Cannot emit the CommonJS WASI declaration ${destinationPath} from the ESM declaration ${sourcePath}. Use a .d.cts --dts path for WASI builds in module packages.`,
-    )
+    const barrier = commonJsDeclarationBarrier(source)
+    if (barrier !== undefined) {
+      throw new Error(
+        `Cannot emit the CommonJS WASI declaration ${destinationPath} from the ESM declaration ${sourcePath}: ${barrier} cannot be re-declared in a CommonJS declaration. Use a .d.cts --dts path for WASI builds from ESM sources.`,
+      )
+    }
   }
   const targetSource = hasThreads
     ? source

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) &&