typescript 5.8.2: Differentiate import specifier resolution, extensionless imports, and package exports maps across TypeScript bundler, node16, and nodenext resolution modes

# TypeScript `moduleResolution`: Bundler vs Node16 vs NodeNext

## `search_known_solution` Result
- **Result**: MISS (`NO_SAFE_MATCH`). No verified sample matched this goal in the environment.

## What a Model Would Have Written
A model configuring a TypeScript project under modern ESM (`"type": "module"`) will frequently write extensionless relative imports (e.g. `import { helper } from "./helper"`) or directory index imports (e.g. `import { util } from "./utils"`) assuming `moduleResolution: "node16"` / `"nodenext"` behaves like bundlers, or alternatively assume `"bundler"` requires `.js` extensions on relative imports because the project is ESM.

## How the Wrong Version Fails
It fails loudly at compile time: under `node16` / `nodenext`, extensionless relative imports fail with `TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'`, directory imports fail with `TS2834`, and unexported package subpaths fail with `TS2307` due to strict package exports encapsulation.

{"case":{"caseId":"case:sha256:871499089babb1520f5a116de4f6977a012ed8d88656e0ba256966c0bdd30d69","constraints":{"runtime":"node"},"contract":["assert bundler allows extensionless relative imports in ESM while node16 and nodenext reject them with TS2835","assert node16 and nodenext require relative .js specifiers to resolve .ts files in ESM contexts","assert bundler resolves directory index imports in ESM while node16 rejects extensionless directory imports with TS2834","assert direct .ts extensions require allowImportingTsExtensions and fail under standard node16 and bundler with TS5097","assert package exports condition selects import for ESM and require for CJS under node16 but defaults to import under bundler","assert unexported package subpaths are blocked under node16 and bundler via exports encapsulation but resolve under legacy node10"],"goal":"Differentiate import specifier resolution, extensionless imports, and package exports maps across TypeScript bundler, node16, and nodenext resolution modes","kind":"HOW","packages":["pkg:npm/typescript@5.8.2"],"schemaVersion":1,"symbols":["createProgram","resolveModuleName","ModuleResolutionKind","ModuleKind"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/typescript@5.8.2"],"schemaVersion":1,"symbols":["createProgram","resolveModuleName","ModuleResolutionKind","ModuleKind"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-tsc-moduleresolution",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-tsc-moduleresolution",
      "version": "1.0.0",
      "dependencies": {
        "typescript": "5.8.2"
      }
    },
    "node_modules/typescript": {
      "version": "5.8.2",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.2.tgz",
      "integrity": "sha512-aJn6wq13/afZp/jT9QZmwEjDqqvSGp1VT5GVg+f/t6/oVyrgXM6BY1h9BRh/O5p3PlUPAe+WuiEZOmb/49RqoQ==",
      "license": "Apache-2.0",
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
      },
      "engines": {
        "node": ">=14.17"
      }
    }
  }
}

{
  "name": "npm-tsc-moduleresolution",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "typescript": "5.8.2"
  }
}

import ts from 'typescript';

const DEFAULT_LIB = `
declare var console: any;
interface Array<T> {}
interface Boolean {}
interface Function {}
interface IArguments {}
interface Number {}
interface Object {}
interface RegExp {}
interface String {}
`;

export function createVirtualHost(files, currentDir = '/project') {
  const allFiles = {
    '/lib.d.ts': DEFAULT_LIB,
    ...files,
  };

  return {
    getSourceFile: (fileName, languageVersion) => {
      const content = allFiles[fileName];
      if (content !== undefined) {
        return ts.createSourceFile(
          fileName,
          content,
          languageVersion ?? ts.ScriptTarget.ES2022,
          true
        );
      }
      return undefined;
    },
    getDefaultLibFileName: () => '/lib.d.ts',
    writeFile: () => {},
    getCurrentDirectory: () => currentDir,
    getDirectories: (dir) => {
      const prefix = dir.endsWith('/') ? dir : `${dir}/`;
      const dirs = new Set();
      for (const p of Object.keys(allFiles)) {
        if (p.startsWith(prefix)) {
          const rest = p.slice(prefix.length);
          const slashIdx = rest.indexOf('/');
          if (slashIdx !== -1) dirs.add(rest.slice(0, slashIdx));
        }
      }
      return Array.from(dirs);
    },
    getCanonicalFileName: (f) => f,
    useCaseSensitiveFileNames: () => true,
    getNewLine: () => '\n',
    fileExists: (fileName) => fileName in allFiles,
    readFile: (fileName) => allFiles[fileName],
    directoryExists: (dir) => {
      const prefix = dir.endsWith('/') ? dir : `${dir}/`;
      return Object.keys(allFiles).some((p) => p.startsWith(prefix));
    },
    realpath: (p) => p,
  };
}

export function compileVirtual(files, entryFiles, compilerOptions = {}) {
  const host = createVirtualHost(files);
  const program = ts.createProgram({
    rootNames: entryFiles,
    options: {
      target: ts.ScriptTarget.ES2022,
      noEmit: true,
      skipLibCheck: true,
      ...compilerOptions,
    },
    host,
  });

  const diagnostics = ts.getPreEmitDiagnostics(program).map((d) => ({
    code: d.code,
    fileName: d.file ? d.file.fileName : undefined,
    message: ts.flattenDiagnosticMessageText(d.messageText, '\n'),
  }));

  return { program, diagnostics, host };
}

export function resolveVirtual(moduleName, containingFile, compilerOptions, files, resolutionMode) {
  const host = createVirtualHost(files);
  return ts.resolveModuleName(
    moduleName,
    containingFile,
    compilerOptions,
    host,
    undefined,
    undefined,
    resolutionMode
  );
}

export { ts };

import { strict as assert } from 'node:assert';
import { compileVirtual, resolveVirtual, ts } from '../src/index.mjs';

const virtualFiles = {
  '/project/package.json': JSON.stringify({
    name: 'test-app',
    type: 'module',
  }),

  // Source files in the project
  '/project/src/helper.ts': 'export const helperValue: number = 42;\n',
  '/project/src/sub/index.ts': 'export const dirValue: string = "nested";\n',

  // Consumer files testing relative imports
  '/project/src/esm-extless.ts': 'import { helperValue } from "./helper";\n',
  '/project/src/esm-js.ts': 'import { helperValue } from "./helper.js";\n',
  '/project/src/esm-ts.ts': 'import { helperValue } from "./helper.ts";\n',
  '/project/src/esm-dir.ts': 'import { dirValue } from "./sub";\n',

  // Dual-package fixture in node_modules
  '/project/node_modules/dual-pkg/package.json': JSON.stringify({
    name: 'dual-pkg',
    version: '1.0.0',
    type: 'module',
    exports: {
      '.': {
        import: { types: './dist/esm.d.ts', default: './dist/esm.js' },
        require: { types: './dist/cjs.d.cts', default: './dist/cjs.cjs' },
      },
      './feature': {
        types: './dist/feature.d.ts',
        default: './dist/feature.js',
      },
    },
    main: './dist/legacy.js',
    types: './dist/legacy.d.ts',
  }),
  '/project/node_modules/dual-pkg/dist/esm.d.ts': 'export declare const esmOnly: string;\n',
  '/project/node_modules/dual-pkg/dist/cjs.d.cts': 'export declare const cjsOnly: string;\n',
  '/project/node_modules/dual-pkg/dist/feature.d.ts': 'export declare const featureFlag: boolean;\n',
  '/project/node_modules/dual-pkg/dist/legacy.d.ts': 'export declare const legacyOnly: boolean;\n',

  // Consumer files testing package exports
  '/project/src/use-esm.ts': 'import { esmOnly } from "dual-pkg";\n',
  '/project/src/use-cjs-valid.cts': 'import { cjsOnly } from "dual-pkg";\n',
  '/project/src/use-cjs-invalid.cts': 'import { esmOnly } from "dual-pkg";\n',
  '/project/src/use-feature.ts': 'import { featureFlag } from "dual-pkg/feature";\n',
  '/project/src/use-unexported.ts': 'import { legacyOnly } from "dual-pkg/dist/legacy";\n',
};

// ============================================================================
// 1. Extensionless Relative Imports in ESM
// ============================================================================
// Bundler allows extensionless relative imports in ESM files.
const bundlerExtless = compileVirtual(virtualFiles, ['/project/src/esm-extless.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
});
assert.equal(bundlerExtless.diagnostics.length, 0, 'Bundler should accept extensionless relative imports');

// Node16 and NodeNext strictly reject extensionless relative imports in ESM with TS2835.
for (const resolution of [ts.ModuleResolutionKind.Node16, ts.ModuleResolutionKind.NodeNext]) {
  const nodeExtless = compileVirtual(virtualFiles, ['/project/src/esm-extless.ts'], {
    module: ts.ModuleKind.Node16,
    moduleResolution: resolution,
  });
  assert.equal(nodeExtless.diagnostics.length, 1);
  assert.equal(nodeExtless.diagnostics[0].code, 2835, 'Node16/NodeNext must fail with TS2835');
  assert.ok(
    nodeExtless.diagnostics[0].message.includes("Did you mean './helper.js'"),
    'TS2835 error message suggests adding .js extension'
  );
}

// ============================================================================
// 2. Relative .js Specifier to .ts Source in ESM
// ============================================================================
// Both Node16/NodeNext and Bundler resolve './helper.js' to physical './helper.ts'.
for (const resolution of [ts.ModuleResolutionKind.Node16, ts.ModuleResolutionKind.NodeNext, ts.ModuleResolutionKind.Bundler]) {
  const modKind = resolution === ts.ModuleResolutionKind.Bundler ? ts.ModuleKind.ESNext : ts.ModuleKind.Node16;
  const jsRes = compileVirtual(virtualFiles, ['/project/src/esm-js.ts'], {
    module: modKind,
    moduleResolution: resolution,
  });
  assert.equal(jsRes.diagnostics.length, 0, `Resolution kind ${resolution} should map .js import to .ts source`);
}

// ============================================================================
// 3. Directory Index Imports in ESM
// ============================================================================
// Bundler resolves directory index './sub' -> './sub/index.ts'.
const bundlerDir = compileVirtual(virtualFiles, ['/project/src/esm-dir.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
});
assert.equal(bundlerDir.diagnostics.length, 0, 'Bundler should resolve directory index imports in ESM');

// Node16 rejects directory imports in ESM with TS2834.
const nodeDir = compileVirtual(virtualFiles, ['/project/src/esm-dir.ts'], {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
});
assert.equal(nodeDir.diagnostics.length, 1);
assert.equal(nodeDir.diagnostics[0].code, 2834, 'Node16 must fail directory import with TS2834');

// ============================================================================
// 4. Direct .ts Extension Imports
// ============================================================================
// Standard Node16, NodeNext, and Bundler reject direct .ts extensions with TS5097.
const bundlerTsFail = compileVirtual(virtualFiles, ['/project/src/esm-ts.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
});
assert.equal(bundlerTsFail.diagnostics.length, 1);
assert.equal(bundlerTsFail.diagnostics[0].code, 5097, 'Bundler without flag fails with TS5097');

// Bundler with allowImportingTsExtensions allows direct .ts extension imports.
const bundlerTsPass = compileVirtual(virtualFiles, ['/project/src/esm-ts.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
  allowImportingTsExtensions: true,
});
assert.equal(bundlerTsPass.diagnostics.length, 0, 'Bundler with allowImportingTsExtensions should pass');

// ============================================================================
// 5. Dual ESM/CJS Package Exports Condition Resolution
// ============================================================================
// In ESM file (.ts with type: module), Node16 resolves 'import' condition ('esmOnly').
const node16Esm = compileVirtual(virtualFiles, ['/project/src/use-esm.ts'], {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
});
assert.equal(node16Esm.diagnostics.length, 0, 'Node16 in ESM should select import condition');

// In CJS file (.cts), Node16 resolves 'require' condition ('cjsOnly').
const node16CjsValid = compileVirtual(virtualFiles, ['/project/src/use-cjs-valid.cts'], {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
});
assert.equal(node16CjsValid.diagnostics.length, 0, 'Node16 in CJS should select require condition');

// In CJS file (.cts), importing 'esmOnly' under Node16 fails with TS2305 because 'require' condition is used.
const node16CjsInvalid = compileVirtual(virtualFiles, ['/project/src/use-cjs-invalid.cts'], {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
});
assert.equal(node16CjsInvalid.diagnostics.length, 1);
assert.equal(node16CjsInvalid.diagnostics[0].code, 2305, 'Node16 CJS importer cannot access ESM-only export');

// Programmatic resolveVirtual verification of condition targets:
const resEsm = resolveVirtual('dual-pkg', '/project/src/use-esm.ts', {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
}, virtualFiles, ts.ModuleKind.ESNext);
assert.equal(resEsm.resolvedModule?.resolvedFileName, '/project/node_modules/dual-pkg/dist/esm.d.ts');

const resCjs = resolveVirtual('dual-pkg', '/project/src/use-cjs-valid.cts', {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
}, virtualFiles, ts.ModuleKind.CommonJS);
assert.equal(resCjs.resolvedModule?.resolvedFileName, '/project/node_modules/dual-pkg/dist/cjs.d.cts');

// Bundler selects 'import' condition even when resolutionMode is CommonJS.
const resBundler = resolveVirtual('dual-pkg', '/project/src/use-cjs-valid.cts', {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
}, virtualFiles);
assert.equal(resBundler.resolvedModule?.resolvedFileName, '/project/node_modules/dual-pkg/dist/esm.d.ts');

// ============================================================================
// 6. Package Subpath Encapsulation vs Legacy Resolution
// ============================================================================
// Exported subpath 'dual-pkg/feature' resolves under Node16, NodeNext, and Bundler.
for (const resolution of [ts.ModuleResolutionKind.Node16, ts.ModuleResolutionKind.NodeNext, ts.ModuleResolutionKind.Bundler]) {
  const modKind = resolution === ts.ModuleResolutionKind.Bundler ? ts.ModuleKind.ESNext : ts.ModuleKind.Node16;
  const featureRes = compileVirtual(virtualFiles, ['/project/src/use-feature.ts'], {
    module: modKind,
    moduleResolution: resolution,
  });
  assert.equal(featureRes.diagnostics.length, 0, `Exported subpath should resolve under resolution ${resolution}`);
}

// Unexported internal subpath 'dual-pkg/dist/legacy' is blocked under Node16/NodeNext/Bundler via encapsulation (TS2307).
for (const resolution of [ts.ModuleResolutionKind.Node16, ts.ModuleResolutionKind.NodeNext, ts.ModuleResolutionKind.Bundler]) {
  const modKind = resolution === ts.ModuleResolutionKind.Bundler ? ts.ModuleKind.ESNext : ts.ModuleKind.Node16;
  const unexportedRes = compileVirtual(virtualFiles, ['/project/src/use-unexported.ts'], {
    module: modKind,
    moduleResolution: resolution,
  });
  assert.equal(unexportedRes.diagnostics.length, 1);
  assert.equal(unexportedRes.diagnostics[0].code, 2307, `Unexported subpath must fail with TS2307 under ${resolution}`);
}

// Under legacy Node10 (node), exports encapsulation is ignored and the unexported subpath resolves directly.
const legacyRes = compileVirtual(virtualFiles, ['/project/src/use-unexported.ts'], {
  module: ts.ModuleKind.CommonJS,
  moduleResolution: ts.ModuleResolutionKind.Node10,
});
assert.equal(legacyRes.diagnostics.length, 0, 'Legacy Node10 resolution bypasses package exports encapsulation');

console.log('CONTRACT PASS: verified TypeScript moduleResolution bundler vs node16 vs nodenext behavior');