typescript 5.9.3: Differentiate compilerOptions.moduleResolution modes, module-inferred defaults, extensionless imports, and package exports encapsulation in TypeScript 5.9.3

# TypeScript CompilerOptions: moduleResolution

## `search_known_solution` Result
The search identified sample `sha256:b725d0d71b44bbc7f011ed622cfaa5f379af031cab0923bc7e7dd9cd3820b7bc` targeting `typescript@5.8.2`. This sample pins the validated requested release `typescript@5.9.3` and explicitly proves the behavior and resolution modes of `ts.CompilerOptions.moduleResolution`.

## Pinned Version
- `typescript`: `5.9.3`

## Observed Behavior
1. **Module-inferred Defaults vs Explicit Configuration**:
   When `compilerOptions.moduleResolution` is omitted:
   - `compilerOptions.module = ts.ModuleKind.ESNext` defaults to `ts.ModuleResolutionKind.Classic` (`1`), not Node or Bundler.
   - `compilerOptions.module = ts.ModuleKind.CommonJS` defaults to `ts.ModuleResolutionKind.Node10` (`2`).
   - `compilerOptions.module = ts.ModuleKind.Node16` defaults to `ts.ModuleResolutionKind.Node16` (`3`).
   - `compilerOptions.module = ts.ModuleKind.NodeNext` defaults to `ts.ModuleResolutionKind.NodeNext` (`99`).
   - `compilerOptions.module = ts.ModuleKind.Preserve` defaults to `ts.ModuleResolutionKind.Bundler` (`100`).
   Setting `compilerOptions.moduleResolution` explicitly overrides any module-inferred default.

2. **Bundler vs Node16 / NodeNext for Extensionless Imports**:
   - `moduleResolution: Bundler` allows extensionless relative imports (e.g., `import { helper } from "./helper"`) and directory index imports (e.g., `import { sub } from "./sub"`).
   - `moduleResolution: Node16` / `NodeNext` strictly requires explicit file extensions in ESM contexts. Extensionless relative imports fail with `TS2835`, and directory index imports fail with `TS2834`.

3. **Relative `.js` Specifiers to `.ts` Source**:
   - Under `Node16`, `NodeNext`, and `Bundler`, importing `./helper.js` resolves correctly to the underlying source file `./helper.ts`.

4. **Direct `.ts` Extension Imports**:
   - Direct `.ts` extensions in import specifiers fail with `TS5097` unless `allowImportingTsExtensions: true` is configured.

5. **Package Exports and Condition Resolution**:
   - Under `Node16` / `NodeNext`, package export conditions are context-sensitive: ESM files (`.mts` or `.ts` under `"type": "module"`) match the `"import"` condition, whereas CommonJS files (`.cts`) match `"require"`. Importing an ESM-only export from CJS fails with `TS2305`.
   - Under `Bundler`, TypeScript defaults to the `"import"` condition even when imported from CommonJS files.
   - `customConditions` compiler option enables user-specified conditional export targets under `Bundler` and `NodeNext`.

6. **Package Encapsulation vs Legacy Resolution**:
   - `Node16`, `NodeNext`, and `Bundler` enforce package encapsulation: importing unexported internal subpaths is rejected with `TS2307`.
   - Legacy `Node10` ignores `package.json` `"exports"` and resolves internal paths directly from the package directory.

## How the Wrong Expectation Fails
- A developer expecting `module: "ESNext"` to automatically resolve package imports will encounter module resolution failures because it defaults to Classic resolution without `node_modules` package lookup.
- A developer writing extensionless imports under `moduleResolution: "node16"` will fail loudly at compile time with `TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'`.
- Accessing unexported subpaths fails with `TS2307: Cannot find module '...' or its corresponding type declarations` under modern resolution modes.

{"case":{"believed":"Setting compilerOptions.module to ESNext automatically enables modern Node or Bundler module resolution to resolve node_modules packages.","caseId":"case:sha256:ee4dbeeb0acd3aa8974612be869d2027bb043847c8f119dd2981ecfa0ccab8c3","contract":["When compilerOptions.moduleResolution is omitted, compilerOptions.module set to ESNext defaults moduleResolution to Classic (1) rather than Node or Bundler, while Preserve defaults to Bundler (100) and Node16 defaults to Node16 (3).","compilerOptions.moduleResolution set to Bundler accepts extensionless relative imports and directory index imports in ESM contexts","compilerOptions.moduleResolution set to Node16 and NodeNext rejects extensionless relative imports with TS2835 and directory imports with TS2834","relative .js specifiers resolve to underlying .ts source files across Node16, NodeNext, and Bundler moduleResolution modes","direct .ts extension imports require allowImportingTsExtensions and otherwise fail with TS5097","Node16 moduleResolution selects import or require package export conditions based on importer format, whereas Bundler defaults to import","Node16, NodeNext, and Bundler moduleResolution enforce package exports encapsulation with TS2307, whereas legacy Node10 ignores exports maps","Bundler moduleResolution respects customConditions compiler option to resolve matching conditional package exports"],"goal":"Differentiate compilerOptions.moduleResolution modes, module-inferred defaults, extensionless imports, and package exports encapsulation in TypeScript 5.9.3","kind":"HOW","packages":["pkg:npm/typescript@5.9.3"],"schemaVersion":1,"symbols":["ts.CompilerOptions.moduleResolution"]},"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.9.3"],"schemaVersion":1,"symbols":["ts.CompilerOptions.moduleResolution"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-typescript-wanted-5-9-3-ts-compileroptions-moduleresolution",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-typescript-wanted-5-9-3-ts-compileroptions-moduleresolution",
      "version": "1.0.0",
      "dependencies": {
        "typescript": "5.9.3"
      }
    },
    "node_modules/typescript": {
      "version": "5.9.3",
      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
      "license": "Apache-2.0",
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
      },
      "engines": {
        "node": ">=14.17"
      }
    }
  }
}

{
  "name": "npm-typescript-wanted-5-9-3-ts-compileroptions-moduleresolution",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "typescript": "5.9.3"
  }
}

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';

// Verify requested symbol ts.CompilerOptions.moduleResolution mapping and values
assert.strictEqual(typeof ts.ModuleResolutionKind, 'object');
assert.strictEqual(ts.ModuleResolutionKind.Classic, 1);
assert.strictEqual(ts.ModuleResolutionKind.Node10, 2);
assert.strictEqual(ts.ModuleResolutionKind.NodeJs, 2);
assert.strictEqual(ts.ModuleResolutionKind.Node16, 3);
assert.strictEqual(ts.ModuleResolutionKind.NodeNext, 99);
assert.strictEqual(ts.ModuleResolutionKind.Bundler, 100);

// Verify default moduleResolution resolution via ts.getEmitModuleResolutionKind
const getEffectiveResolution = (options) => ts.getEmitModuleResolutionKind(options);
assert.strictEqual(getEffectiveResolution({ module: ts.ModuleKind.CommonJS }), ts.ModuleResolutionKind.Node10);
assert.strictEqual(getEffectiveResolution({ module: ts.ModuleKind.ESNext }), ts.ModuleResolutionKind.Classic);
assert.strictEqual(getEffectiveResolution({ module: ts.ModuleKind.Node16 }), ts.ModuleResolutionKind.Node16);
assert.strictEqual(getEffectiveResolution({ module: ts.ModuleKind.NodeNext }), ts.ModuleResolutionKind.NodeNext);
assert.strictEqual(getEffectiveResolution({ module: ts.ModuleKind.Preserve }), ts.ModuleResolutionKind.Bundler);

// Explicit moduleResolution overrides the module-inferred default
assert.strictEqual(
  getEffectiveResolution({ module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler }),
  ts.ModuleResolutionKind.Bundler
);
assert.strictEqual(
  getEffectiveResolution({ module: ts.ModuleKind.CommonJS, moduleResolution: ts.ModuleResolutionKind.Node16 }),
  ts.ModuleResolutionKind.Node16
);

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

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

  // Relative import consumers
  '/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',

  // Package dependencies 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',

  // Package with custom conditions
  '/project/node_modules/custom-pkg/package.json': JSON.stringify({
    name: 'custom-pkg',
    version: '1.0.0',
    exports: {
      '.': {
        'worker': { types: './dist/worker.d.ts' },
        'browser': { types: './dist/browser.d.ts' },
        'default': { types: './dist/default.d.ts' },
      },
    },
  }),
  '/project/node_modules/custom-pkg/dist/worker.d.ts': 'export declare const envName: "worker";\n',
  '/project/node_modules/custom-pkg/dist/browser.d.ts': 'export declare const envName: "browser";\n',
  '/project/node_modules/custom-pkg/dist/default.d.ts': 'export declare const envName: "default";\n',

  // Package exports consumers
  '/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
const bundlerExtless = compileVirtual(virtualFiles, ['/project/src/esm-extless.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
});
assert.strictEqual(bundlerExtless.diagnostics.length, 0, 'Bundler accepts extensionless relative imports in ESM');

// 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.strictEqual(nodeExtless.diagnostics.length, 1);
  assert.strictEqual(nodeExtless.diagnostics[0].code, 2835, 'Node16/NodeNext must fail with TS2835');
  assert.ok(
    nodeExtless.diagnostics[0].message.includes("Did you mean './helper.js'"),
    'TS2835 diagnostic suggests adding .js extension'
  );
}

// 2. Relative .js specifiers resolve to .ts source files in ESM
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.strictEqual(jsRes.diagnostics.length, 0, `Resolution kind ${resolution} maps .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.strictEqual(bundlerDir.diagnostics.length, 0, 'Bundler resolves directory index imports in ESM');

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

// 4. Direct .ts extension imports
// Without allowImportingTsExtensions, .ts specifiers fail with TS5097
const bundlerTsFail = compileVirtual(virtualFiles, ['/project/src/esm-ts.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
});
assert.strictEqual(bundlerTsFail.diagnostics.length, 1);
assert.strictEqual(bundlerTsFail.diagnostics[0].code, 5097, 'Bundler without flag fails direct .ts import with TS5097');

// With allowImportingTsExtensions, direct .ts specifiers succeed
const bundlerTsPass = compileVirtual(virtualFiles, ['/project/src/esm-ts.ts'], {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
  allowImportingTsExtensions: true,
});
assert.strictEqual(bundlerTsPass.diagnostics.length, 0, 'Bundler with allowImportingTsExtensions accepts .ts extension');

// 5. Dual ESM/CJS package exports conditions
// In ESM file (.ts in 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.strictEqual(node16Esm.diagnostics.length, 0, 'Node16 in ESM selects 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.strictEqual(node16CjsValid.diagnostics.length, 0, 'Node16 in CJS selects require condition');

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

// Verify condition resolution via resolveVirtual
const resEsm = resolveVirtual('dual-pkg', '/project/src/use-esm.ts', {
  module: ts.ModuleKind.Node16,
  moduleResolution: ts.ModuleResolutionKind.Node16,
}, virtualFiles, ts.ModuleKind.ESNext);
assert.strictEqual(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.strictEqual(resCjs.resolvedModule?.resolvedFileName, '/project/node_modules/dual-pkg/dist/cjs.d.cts');

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

// 6. Custom conditions support under Bundler
const resCustomDefault = resolveVirtual('custom-pkg', '/project/src/use-esm.ts', {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
}, virtualFiles);
assert.strictEqual(resCustomDefault.resolvedModule?.resolvedFileName, '/project/node_modules/custom-pkg/dist/default.d.ts');

const resCustomWorker = resolveVirtual('custom-pkg', '/project/src/use-esm.ts', {
  module: ts.ModuleKind.ESNext,
  moduleResolution: ts.ModuleResolutionKind.Bundler,
  customConditions: ['worker'],
}, virtualFiles);
assert.strictEqual(resCustomWorker.resolvedModule?.resolvedFileName, '/project/node_modules/custom-pkg/dist/worker.d.ts');

// 7. Package exports encapsulation vs legacy Node10 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.strictEqual(featureRes.diagnostics.length, 0, `Exported subpath resolves under ${resolution}`);
}

// Unexported internal subpath 'dual-pkg/dist/legacy' is blocked under Node16/NodeNext/Bundler (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.strictEqual(unexportedRes.diagnostics.length, 1);
  assert.strictEqual(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.strictEqual(legacyRes.diagnostics.length, 0, 'Legacy Node10 resolution bypasses package exports encapsulation');

console.log('CONTRACT PASS: ts.CompilerOptions.moduleResolution verified in TypeScript 5.9.3');