feat(resolve): resolveAlias

Signed-off-by: Lexus Drumgold <unicornware@flexdevelopment.llc>

Author: unicornware

.eslintrc.cjs

@@ -11,7 +11,15 @@
 const config = {
   root: true,
   extends: ['./.eslintrc.base.cjs'],
-  overrides: [...require('./.eslintrc.base.cjs').overrides]
+  overrides: [
+    ...require('./.eslintrc.base.cjs').overrides,
+    {
+      files: ['src/lib/resolve-alias.ts'],
+      rules: {
+        '@typescript-eslint/unbound-method': 0
+      }
+    }
+  ]
 }
 
 module.exports = config

__mocks__/.gitkeep

@@ -0,0 +1,23 @@
+/**
+ * @file Mocks - pathe
+ * @module mocks/pathe
+ * @see https://github.com/unjs/pathe
+ */
+
+/**
+ * [`pathe`][1] module type.
+ *
+ * [1]: https://github.com/unjs/pathe
+ */
+type Actual = typeof import('pathe')
+
+/**
+ * `pathe` module.
+ *
+ * @const {Actual} actual
+ */
+const actual: Actual = await vi.importActual<Actual>('pathe')
+
+export const dirname = vi.fn(actual.dirname)
+export const relative = vi.fn(actual.relative)
+export const resolve = vi.fn(actual.resolve)

__mocks__/pathe.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Mocks - tsconfig-paths
+ * @module mocks/tsconfig-paths
+ * @see https://github.com/dividab/tsconfig-paths
+ */
+
+/**
+ * [`tsconfig-paths`][1] module type.
+ *
+ * [1]: https://github.com/dividab/tsconfig-paths
+ */
+type Actual = typeof import('tsconfig-paths')
+
+/**
+ * `tsconfig-paths` module.
+ *
+ * @const {Actual} actual
+ */
+const actual: Actual = await vi.importActual<Actual>('tsconfig-paths')
+
+export const createMatchPath = vi.fn(actual.createMatchPath)

__mocks__/tsconfig-paths/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Mocks - tsconfig-paths/lib/tsconfig-loader
+ * @module mocks/tsconfig-paths/lib/tsconfig-loader
+ * @see https://github.com/dividab/tsconfig-paths
+ */
+
+/**
+ * `tsconfig-paths/lib/tsconfig-loader` module type.
+ */
+type Actual = typeof import('tsconfig-paths/lib/tsconfig-loader')
+
+/**
+ * Mocked module path.
+ *
+ * @const {string} path
+ */
+const path: string = 'tsconfig-paths/lib/tsconfig-loader'
+
+/**
+ * `tsconfig-paths/lib/tsconfig-loader` module.
+ *
+ * @const {Actual} actual
+ */
+const actual: Actual = await vi.importActual<Actual>(path)
+
+export const loadTsconfig = vi.fn(actual.loadTsconfig)

__mocks__/tsconfig-paths/lib/tsconfig-loader.ts

@@ -69,6 +69,10 @@
     "test:cov": "yarn test --coverage",
     "test:watch": "vitest"
   },
+  "dependencies": {
+    "pathe": "0.3.8",
+    "tsconfig-paths": "4.1.0"
+  },
   "devDependencies": {
     "@commitlint/cli": "17.1.2",
     "@commitlint/config-conventional": "17.1.0",

package.json

@@ -63,6 +63,24 @@ export const EXPORT_STAR_REGEX: RegExp =
 export const REQUIRE_STATEMENT_REGEX: RegExp =
   /(?<!(?:\/\/|\*).*)(?:\bconst[ {]+(?<imports>[\w\t\n\r $*,/]+)[ =}]+)?(?<type>\brequire(?:\.resolve)?)\(["'](?<specifier>[\w./-]+)["']\)/gm
 
+/**
+ * Default resolvable file extensions.
+ *
+ * @const {ReadonlyArray<string>} RESOLVE_EXTENSIONS
+ */
+export const RESOLVE_EXTENSIONS: readonly string[] = Object.freeze([
+  '.cjs',
+  '.css',
+  '.cts',
+  '.js',
+  '.json',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx'
+])
+
 /**
  * Static import statement regex.
  *

src/constants.ts

@@ -5,6 +5,7 @@
 
 export type { default as DynamicImport } from './import-dynamic'
 export type { default as StaticImport } from './import-static'
+export type { default as AliasResolverOptions } from './options-alias-resolver'
 export type { default as Statement } from './statement'
 export type { default as ExportStatement } from './statement-export'
 export type { default as ImportStatement } from './statement-import'

src/interfaces/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @file Interfaces - AliasResolverOptions
+ * @module mlly/interfaces/AliasResolverOptions
+ */
+
+import type { OneOrMany } from '@flex-development/tutils'
+
+/**
+ * Path alias resolution options.
+ *
+ * @see https://github.com/dividab/tsconfig-paths
+ */
+interface AliasResolverOptions {
+  /**
+   * Base directory to resolve non-absolute module names.
+   *
+   * @see https://www.typescriptlang.org/tsconfig#baseUrl
+   *
+   * @default process.cwd()
+   */
+  baseUrl?: string
+
+  /**
+   * Module extensions to probe for.
+   *
+   * @default RESOLVE_EXTENSIONS
+   */
+  extensions?: string[]
+
+  /**
+   * Checks for the existence of a file at `path`.
+   *
+   * @param {string} path - Path to check
+   * @return {boolean} `true` if file exists, `false` otherwise
+   */
+  fileExists?(path: string): boolean
+
+  /**
+   * `package.json` fields to check when resolving modules.
+   *
+   * A nested field can be selected by passing an array of field names.
+   *
+   * @default ['main', 'module']
+   */
+  mainFields?: OneOrMany<string>[]
+
+  /**
+   * Path mappings.
+   *
+   * **Note**: Should be relative to {@link baseUrl}.
+   *
+   * @see https://www.typescriptlang.org/tsconfig#paths
+   *
+   * @default {}
+   */
+  paths?: Record<string, string[]>
+
+  /**
+   * Synchronously returns the contents of `filename`.
+   *
+   * @param {string} filename - Filename
+   * @return {string} Contents of `filename`
+   */
+  readFile?(filename: string): string
+
+  /**
+   * Absolute path to tsconfig file.
+   */
+  tsconfig?: string
+
+  /**
+   * Absolute path to file containing path alias.
+   */
+  url?: string
+}
+
+export type { AliasResolverOptions as default }

src/interfaces/options-alias-resolver.ts

@@ -0,0 +1,53 @@
+/**
+ * @file Functional Tests - resolveAlias
+ * @module mlly/lib/tests/resolveAlias/functional
+ */
+
+import type { Spy } from '#tests/interfaces'
+import path from 'node:path'
+import * as pathe from 'pathe'
+import { createMatchPath } from 'tsconfig-paths'
+import { loadTsconfig } from 'tsconfig-paths/lib/tsconfig-loader'
+import tsconfig from '../../../tsconfig.json' assert { type: 'json' }
+import testSubject from '../resolve-alias'
+
+vi.mock('pathe')
+vi.mock('tsconfig-paths')
+vi.mock('tsconfig-paths/lib/tsconfig-loader')
+
+describe('functional:lib/resolveAlias', () => {
+  const specifier: string = '#src/lib/resolve-alias'
+  const tscpath: string = path.resolve('tsconfig.json')
+
+  it('should load tsconfig file', () => {
+    // Act
+    ;(loadTsconfig as unknown as Spy).mockReturnValueOnce(undefined)
+    testSubject(specifier, { tsconfig: tscpath })
+
+    // Expect
+    expect(loadTsconfig).toHaveBeenCalledOnce()
+    expect(loadTsconfig).toHaveBeenCalledWith(tscpath, undefined, undefined)
+  })
+
+  it('should use baseUrl and paths from tsconfig', () => {
+    // Arrange
+    const { baseUrl, paths } = tsconfig.compilerOptions
+
+    // Act
+    ;(loadTsconfig as unknown as Spy).mockReturnValueOnce(tsconfig)
+    testSubject(specifier, { tsconfig: tscpath })
+
+    // Expect
+    expect(pathe.dirname).toHaveBeenCalledOnce()
+    expect(pathe.dirname).toHaveBeenCalledWith(tscpath)
+    expect(pathe.resolve).toHaveBeenCalledOnce()
+    expect(pathe.resolve).toHaveBeenCalledWith(path.dirname(tscpath), baseUrl)
+    expect(createMatchPath).toHaveBeenCalledOnce()
+    expect(createMatchPath).toHaveBeenCalledWith(
+      path.resolve(path.dirname(tscpath), baseUrl),
+      paths,
+      ['main', 'module'],
+      true
+    )
+  })
+})

src/lib/__tests__/resolve-alias.functional.spec.ts

@@ -0,0 +1,73 @@
+/**
+ * @file Unit Tests - resolveAlias
+ * @module mlly/lib/tests/resolveAlias/unit
+ */
+
+import type { AliasResolverOptions as Options } from '#src/interfaces'
+import path from 'node:path'
+import testSubject from '../resolve-alias'
+
+describe('unit:lib/resolveAlias', () => {
+  const paths: NonNullable<Options['paths']> = {
+    '#fixtures/*': ['__fixtures__/*'],
+    '#src/*': ['src/*'],
+    '@flex-development/tutils/*': [
+      'node_modules/@flex-development/tutils/dist/*'
+    ]
+  }
+
+  it('should convert alias from unknown source to absolute specifier', () => {
+    // Act
+    const result = testSubject('#src/lib/detect-syntax', { paths })
+
+    // Expect
+    expect(result).to.equal(path.join(process.cwd(), 'src/lib/detect-syntax'))
+  })
+
+  it('should convert current directory alias to relative specifier', () => {
+    // Arrange
+    const specifier = '#src/constants'
+    const url = path.resolve('src/index.ts')
+
+    // Act + Expect
+    expect(testSubject(specifier, { paths, url })).to.equal('./constants')
+  })
+
+  it('should convert module alias to relative specifier', () => {
+    // Arrange
+    const expected = '../../../__fixtures__/aggregate-error-ponyfill.cjs'
+    const specifier = '#fixtures/aggregate-error-ponyfill.cjs'
+    const url = path.resolve('src/lib/__tests__/detect-syntax.spec.ts')
+
+    // Act + Expect
+    expect(testSubject(specifier, { paths, url })).to.equal(expected)
+  })
+
+  it('should convert node_modules alias to bare specifier', () => {
+    // Arrange
+    const expected = '@flex-development/tutils/dist/guards/is-node-env'
+    const specifier = '@flex-development/tutils/guards/is-node-env'
+
+    // Act + Expect
+    expect(testSubject(specifier, { paths })).to.equal(expected)
+  })
+
+  it('should convert parent directory alias to relative specifier', () => {
+    // Arrange
+    const url = path.resolve('src/interfaces/statement.ts')
+
+    // Act + Expect
+    expect(testSubject('#src/types', { paths, url })).to.equal('../types')
+  })
+
+  it('should return specifier if path match was not found', () => {
+    // Arrange
+    const specifier: string = '#src/lib/resolve-alias'
+
+    // Act
+    const results = testSubject(specifier, { paths: {} })
+
+    // Expect
+    expect(results).to.equal(specifier)
+  })
+})

src/lib/__tests__/resolve-alias.spec.ts

@@ -11,3 +11,4 @@ export { default as findRequires } from './find-requires'
 export { default as findStaticImports } from './find-static-imports'
 export { default as hasCJSSyntax } from './has-cjs-syntax'
 export { default as hasESMSyntax } from './has-esm-syntax'
+export { default as resolveAlias } from './resolve-alias'