@flex-development/mlly 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/utils/validate-assertions.ts

@@ -0,0 +1,119 @@
+/**
+ * @file validateAssertions
+ * @module mlly/utils/validateAssertions
+ */
+
+import type { Format } from '#src/enums'
+import { AssertType } from '#src/enums'
+import type { ImportAssertions } from '#src/interfaces'
+import FORMAT_TYPE_MAP from '#src/internal/format-type-map'
+import validateString from '#src/internal/validate-string'
+import validateURLString from '#src/internal/validate-url-string'
+import type { ModuleId } from '#src/types'
+import {
+  ERR_IMPORT_ASSERTION_TYPE_FAILED,
+  ERR_IMPORT_ASSERTION_TYPE_MISSING,
+  ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED,
+  type NodeError
+} from '@flex-development/errnode'
+import type { LiteralUnion } from '@flex-development/tutils'
+import { URL } from 'node:url'
+
+/**
+ * Test a module's `import` assertions.
+ *
+ * @see {@linkcode Format}
+ * @see {@linkcode ImportAssertions}
+ * @see {@linkcode ModuleId}
+ *
+ * @param {ModuleId} url - Module URL of imported module (for error reporting)
+ * @param {LiteralUnion<Format, string>} format - Module format
+ * @param {ImportAssertions} [assertions={}] - `import` assertions
+ * @return {true} `true` if `assertions` are valid
+ * @throws {NodeError<TypeError>}
+ */
+const validateAssertions = (
+  url: ModuleId,
+  format: LiteralUnion<Format, string>,
+  assertions: ImportAssertions = {}
+): true => {
+  validateURLString(url, 'url')
+  validateString(format, 'format')
+
+  // ensure url is a string
+  if (url instanceof URL) url = url.href
+
+  /**
+   * `type` property check for {@linkcode assertions}.
+   *
+   * @const {boolean} has_type
+   */
+  const has_type: boolean = Object.hasOwnProperty.call(assertions, 'type')
+
+  /**
+   * `import` assertion type.
+   *
+   * @const {AssertType | undefined} type
+   */
+  const type: AssertType | undefined = FORMAT_TYPE_MAP.get(format as Format)
+
+  /**
+   * `import` assertion error check.
+   *
+   * @var {boolean} err
+   */
+  let err: boolean = false
+
+  // validate import assertions
+  switch (type) {
+    case undefined:
+      // ignore assertions for unrecognized module formats to allow for new
+      // formats in the future
+      break
+    case AssertType.IMPLICIT:
+      // format doesn't allow an import assertion type, so the `type` property
+      // must not be set on the import assertions object
+      if (has_type) err = true
+      break
+    case assertions.type:
+      // asserted type is compatible with format
+      break
+    default:
+      // format has an expected type, but asserted type is not compatible
+      err = true
+  }
+
+  // throw if error was encountered
+  if (err) {
+    // import assertion type was not specified
+    if (!has_type) throw new ERR_IMPORT_ASSERTION_TYPE_MISSING(url, type!)
+
+    // import assertion type may have not been a string
+    validateString(assertions.type, 'assertions.type')
+
+    /**
+     * Supported `import` assertion types.
+     *
+     * @const {AssertType[]} supported
+     */
+    const supported: AssertType[] = []
+
+    // get supported import assertion types
+    for (const [, type] of FORMAT_TYPE_MAP) {
+      if (type === AssertType.IMPLICIT) continue
+      supported.push(type)
+    }
+
+    // throw if asserted type is not supported
+    if (!supported.includes(assertions.type as AssertType)) {
+      throw new ERR_IMPORT_ASSERTION_TYPE_UNSUPPORTED(assertions.type!)
+    }
+
+    // unknown error
+    throw new ERR_IMPORT_ASSERTION_TYPE_FAILED(url, assertions.type!)
+  }
+
+  return true
+}
+
+export default validateAssertions

package/src/utils/validate-exports.ts

@@ -0,0 +1,124 @@
+/**
+ * @file validateExports
+ * @module mlly/utils/validateExports
+ */
+
+import isArrayIndex from '#src/internal/is-array-index'
+import validateURLString from '#src/internal/validate-url-string'
+import type { ModuleId } from '#src/types'
+import {
+  ERR_INVALID_PACKAGE_CONFIG,
+  type NodeError
+} from '@flex-development/errnode'
+import type { Exports } from '@flex-development/pkg-types'
+import { isNIL } from '@flex-development/tutils'
+import { URL, fileURLToPath } from 'node:url'
+
+/**
+ * Validates the given package [`exports`][1] configuration and schema.
+ *
+ * [1]: https://nodejs.org/api/packages.html#exports
+ *
+ * @see {@linkcode Exports}
+ * @see {@linkcode ModuleId}
+ *
+ * @param {Exports | undefined} exports - Package `exports`
+ * @param {ModuleId} pkg - URL of relevant `package.json` file
+ * @param {ModuleId} parent - URL of module to resolve from
+ * @return {true} `true` if `exports` configuration and schema are valid
+ * @throws {NodeError<Error | TypeError>} If either `pkg` or `parent` is not an
+ * instance of {@linkcode URL} or a string, or if `exports` configuration or
+ * schema is invalid
+ */
+const validateExports = (
+  exports: Exports | undefined,
+  pkg: ModuleId,
+  parent: ModuleId
+): true => {
+  switch (true) {
+    case Array.isArray(exports):
+      for (const item of exports as unknown[]) {
+        switch (true) {
+          case Array.isArray(item):
+          case isNIL(item):
+          case typeof item !== 'object' && typeof item !== 'string':
+            throw new ERR_INVALID_PACKAGE_CONFIG(
+              fileURLToPath(pkg),
+              fileURLToPath(parent),
+              'The "exports" array must contain either objects of package subpath keys, objects of condition name keys, or strings'
+            )
+          default:
+            validateExports(
+              item as Record<string, Exports> | string,
+              pkg,
+              parent
+            )
+            break
+        }
+      }
+
+      break
+    case isNIL(exports):
+    case typeof exports === 'string':
+      break
+    case typeof exports !== 'object':
+      throw new ERR_INVALID_PACKAGE_CONFIG(
+        fileURLToPath(pkg),
+        fileURLToPath(parent),
+        '"exports" must be null, undefined, a string, an object of package subpath keys or condition name keys, or an array containing objects of package subpath keys, objects of condition name keys, or strings'
+      )
+    default:
+      exports = exports as Record<string, Exports>
+
+      validateURLString(pkg, 'pkg')
+      validateURLString(parent, 'parent')
+
+      /**
+       * Keys defined in {@linkcode exports}.
+       *
+       * @const {string[]} keys
+       */
+      const keys: string[] = Object.getOwnPropertyNames(exports)
+
+      // validate keys
+      for (const [index, key] of keys.entries()) {
+        // ensure key is not an array index
+        if (isArrayIndex(key)) {
+          throw new ERR_INVALID_PACKAGE_CONFIG(
+            fileURLToPath(new URL('.', pkg)),
+            fileURLToPath(parent),
+            '"exports" cannot contain numeric property keys'
+          )
+        }
+
+        // if more than one key in keys, ensure all keys are either syntactical
+        // export conditions or subpath exports
+        if (index > 0) {
+          /**
+           * Key before {@linkcode key} in {@linkcode keys}.
+           *
+           * @const {string} prev
+           */
+          const prev: string = keys[index - 1]!
+
+          // ensure keys are syntactical export conditions or subpath exports
+          if (
+            (!key.startsWith('.') && prev.startsWith('.')) ||
+            (key.startsWith('.') && !prev.startsWith('.'))
+          ) {
+            throw new ERR_INVALID_PACKAGE_CONFIG(
+              fileURLToPath(pkg),
+              fileURLToPath(parent),
+              '"exports" cannot contain some keys starting with \'.\' and some not. The exports object must either be an object of package subpath keys or an object of main entry condition name keys only.'
+            )
+          }
+        }
+      }
+
+      break
+  }
+
+  return true
+}
+
+export default validateExports

package/changelog.config.cts

@@ -1,204 +0,0 @@
-/**
- * @file Changelog Configuration
- * @module config/changelog
- * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli
- */
-
-import type { Config } from 'conventional-changelog-cli'
-import type { Options } from 'conventional-changelog-core'
-import type {
-  CommitGroup,
-  GeneratedContext
-} from 'conventional-changelog-writer'
-import type { Commit, CommitRaw } from 'conventional-commits-parser'
-import dateformat from 'dateformat'
-import fs from 'node:fs'
-import pkg from './package.json'
-
-/**
- * Changlog context.
- *
- * @extends {GeneratedContext}
- */
-interface Context extends GeneratedContext {
-  currentTag: string
-  linkCompare: boolean
-  previousTag: string
-}
-
-/**
- * Changelog configuration options.
- *
- * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits
- * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core
- * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer
- * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser
- * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits
- *
- * @const {Config} config
- */
-const config: Config = {
-  options: {
-    preset: {
-      header: '',
-      name: 'conventionalcommits',
-      releaseCommitMessageFormat: 'release: {{currentTag}}',
-      types: [
-        { section: ':package: Build', type: 'build' },
-        { section: ':house_with_garden: Housekeeping', type: 'chore' },
-        { section: ':robot: Continuous Integration', type: 'ci' },
-        { section: ':pencil: Documentation', type: 'docs' },
-        { section: ':sparkles: Features', type: 'feat' },
-        { section: ':bug: Fixes', type: 'fix' },
-        { section: ':fire: Performance Improvements', type: 'perf' },
-        { section: ':zap: Refactors', type: 'refactor' },
-        { section: ':rewind: Reverts', type: 'revert' },
-        { hidden: true, type: 'style' },
-        { section: ':white_check_mark: Testing', type: 'test' },
-        { hidden: true, type: 'wip' }
-      ]
-    },
-    skipUnstable: false,
-    tagPrefix: pkg.tagPrefix,
-    /**
-     * Raw commit transformer.
-     *
-     * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#transform-1
-     *
-     * @param {CommitRaw} commit - Raw commit object
-     * @param {Options.Transform.Callback} apply - Commit handler
-     * @return {void} Nothing when complete
-     */
-    transform(commit: CommitRaw, apply: Options.Transform.Callback): void {
-      commit.committerDate = dateformat(commit.committerDate, 'yyyy-mm-dd')
-
-      if (commit.gitTags) {
-        /**
-         * Regex expression used to check {@link commit.gitTags} for the release
-         * {@link commit} belongs to.
-         *
-         * @const {RegExp} vgx
-         */
-        const vgx: RegExp = pkg.tagPrefix
-          ? new RegExp(`tag:\\s*[=]?${pkg.tagPrefix}(.+?)[,)]`, 'gi')
-          : /tag:\s*[=v]?(.+?)[),]/gi
-
-        commit = Object.assign({}, commit, {
-          version: vgx.exec(commit.gitTags)?.[1] ?? undefined
-        })
-      }
-
-      commit.notes = commit.notes.map(note => ({
-        ...note,
-        text: note.text.replace(/(\n?\n?Signed-off-by:).+/gm, '')
-      }))
-
-      return void apply(null, {
-        ...commit,
-        raw: commit,
-        shortHash: commit.hash.slice(0, 7)
-      })
-    }
-  },
-  parserOpts: {
-    issuePrefixesCaseSensitive: true
-  },
-  writerOpts: {
-    /**
-     * Sorts commit groups in descending order by group title.
-     *
-     * GitHub emojis in titles will be ignored.
-     *
-     * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#commitgroupssort
-     *
-     * @param {CommitGroup} a - Commit group object
-     * @param {CommitGroup} b - Commit group object to compare to `a`
-     * @return {number} Compare result
-     */
-    commitGroupsSort(a: CommitGroup, b: CommitGroup): number {
-      if (a.title === false) return 1
-      if (b.title === false) return -1
-
-      /**
-       * Regex used to extract commit group titles without GitHub emojis.
-       *
-       * @const {RegExp} tgx - Regex used to extract commit group title
-       */
-      const tgx: RegExp = /([A-Z])\w+/
-
-      return tgx.exec(a.title)![0]!.localeCompare(tgx.exec(b.title)![0]!)
-    },
-    /**
-     * Sorts commits in descending order by commit header and date.
-     *
-     * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#commitssort
-     *
-     * @param {Commit} a - Commit object
-     * @param {Commit} b - Commit object to compare to `b`
-     * @return {number} Compare result
-     */
-    commitsSort(a: Commit, b: Commit): number {
-      /**
-       * Compare result for {@link b.committerDate} & {@link a.committerDate}.
-       *
-       * @const {number} by_date
-       */
-      const by_date: number =
-        new Date(b.committerDate).getTime() -
-        new Date(a.committerDate).getTime()
-
-      return a.header && b.header
-        ? a.header.localeCompare(b.header) || by_date
-        : by_date
-    },
-    /**
-     * Modifies `context` before the changelog is generated.
-     *
-     * This includes:
-     *
-     * - Setting the release date to the current date
-     * - Setting the current release tag
-     * - Setting the previous release tag
-     * - Setting compare link generation
-     *
-     * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#finalizecontext
-     * @see https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#finalizecontext
-     *
-     * @param {GeneratedContext} context - Generated changelog context
-     * @return {Context} Final changelog context
-     */
-    finalizeContext(context: GeneratedContext): Context {
-      /**
-       * Use current date as release date instead of date of most recent commit.
-       *
-       * @see https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/lib/util.js#L194-L196
-       */
-      context.date = dateformat(new Date(), 'yyyy-mm-dd')
-
-      /**
-       * Release tag for upcoming version.
-       *
-       * @const {string} currentTag
-       */
-      const currentTag: string = pkg.tagPrefix + pkg.version
-
-      /**
-       * Release tag for previous version.
-       *
-       * @const {string} previousTag
-       */
-      const previousTag: string = context.gitSemverTags[0]!
-
-      return {
-        ...context,
-        currentTag,
-        linkCompare: currentTag !== previousTag,
-        previousTag
-      }
-    },
-    headerPartial: fs.readFileSync('templates/changelog/header.hbs', 'utf8'),
-    ignoreReverted: false
-  }
-}
-
-module.exports = config

package/dist/constants.d.mts

@@ -1,19 +0,0 @@
-/**
- * @file Constants
- * @module mlly/constants
- */
-import type { Ext } from './types/index.mjs';
-/**
- * Default export conditions.
- *
- * @see https://nodejs.org/api/packages.html#conditional-exports
- *
- * @const {Readonly<Set<string>>} CONDITIONS
- */
-export declare const CONDITIONS: Readonly<Set<string>>;
-/**
- * Default resolvable file extensions.
- *
- * @const {ReadonlyArray<Ext>} RESOLVE_EXTENSIONS
- */
-export declare const RESOLVE_EXTENSIONS: readonly Ext[];

package/dist/constants.mjs

@@ -1,24 +0,0 @@
-const CONDITIONS = Object.freeze(
-  /* @__PURE__ */ new Set(["node", "import"])
-);
-const RESOLVE_EXTENSIONS = Object.freeze([
-  ".mjs",
-  ".mts",
-  ".cjs",
-  ".cts",
-  ".js",
-  ".ts",
-  ".jsx",
-  ".tsx",
-  ".css",
-  ".json",
-  ".node",
-  ".wasm",
-  ".d.mts",
-  ".d.cts",
-  ".d.ts"
-]);
-export {
-  CONDITIONS,
-  RESOLVE_EXTENSIONS
-};

package/dist/internal/compiler-options-json.d.mts

@@ -1,111 +0,0 @@
-/**
- * @file Internals - CompilerOptionsJson
- * @module mlly/internal/CompilerOptionsJson
- */
-import type { CompilerOptionsValue, MapLike } from 'typescript';
-/**
- * TypeScript compiler options provided by a user.
- *
- * @internal
- *
- * @see https://www.typescriptlang.org/tsconfig
- */
-interface CompilerOptionsJson {
-    allowJs?: boolean;
-    allowSyntheticDefaultImports?: boolean;
-    allowUmdGlobalAccess?: boolean;
-    allowUnreachableCode?: boolean;
-    allowUnusedLabels?: boolean;
-    alwaysStrict?: boolean;
-    assumeChangesOnlyAffectDirectDependencies?: boolean;
-    baseUrl?: string;
-    charset?: string;
-    checkJs?: boolean;
-    composite?: boolean;
-    declaration?: boolean;
-    declarationDir?: string;
-    declarationMap?: boolean;
-    disableReferencedProjectLoad?: boolean;
-    disableSizeLimit?: boolean;
-    disableSolutionSearching?: boolean;
-    disableSourceOfProjectReferenceRedirect?: boolean;
-    downlevelIteration?: boolean;
-    emitBOM?: boolean;
-    emitDeclarationOnly?: boolean;
-    emitDecoratorMetadata?: boolean;
-    esModuleInterop?: boolean;
-    exactOptionalPropertyTypes?: boolean;
-    experimentalDecorators?: boolean;
-    forceConsistentCasingInFileNames?: boolean;
-    importHelpers?: boolean;
-    importsNotUsedAsValues?: 'error' | 'preserve' | 'remove';
-    incremental?: boolean;
-    inlineSourceMap?: boolean;
-    inlineSources?: boolean;
-    isolatedModules?: boolean;
-    jsx?: 'preserve' | 'react-jsx' | 'react-jsxdev' | 'react-native' | 'react';
-    jsxFactory?: string;
-    jsxFragmentFactory?: string;
-    jsxImportSource?: string;
-    keyofStringsOnly?: boolean;
-    lib?: ('DOM.Iterable' | 'dom.iterable' | 'DOM' | 'dom' | 'ES5' | 'es5' | 'ES6' | 'es6' | 'ES7' | 'es7' | 'ES2015.Collection' | 'es2015.collection' | 'ES2015.Core' | 'es2015.core' | 'ES2015.Generator' | 'es2015.generator' | 'ES2015.Iterable' | 'es2015.iterable' | 'ES2015.Promise' | 'es2015.promise' | 'ES2015.Proxy' | 'es2015.proxy' | 'ES2015.Reflect' | 'es2015.reflect' | 'ES2015.Symbol.WellKnown' | 'es2015.symbol.wellknown' | 'ES2015.Symbol' | 'es2015.symbol' | 'ES2015' | 'es2015' | 'ES2016.Array.Include' | 'es2016.array.include' | 'ES2016' | 'es2016' | 'ES2017.Intl' | 'es2017.intl' | 'ES2017.Object' | 'es2017.object' | 'ES2017.SharedMemory' | 'es2017.sharedmemory' | 'ES2017.String' | 'es2017.string' | 'ES2017.TypedArrays' | 'es2017.typedarrays' | 'ES2017' | 'es2017' | 'ES2018.AsyncGenerator' | 'es2018.asyncgenerator' | 'ES2018.AsyncIterable' | 'es2018.asynciterable' | 'ES2018.Intl' | 'es2018.intl' | 'ES2018.Promise' | 'es2018.promise' | 'ES2018.Regexp' | 'es2018.regexp' | 'ES2018' | 'es2018' | 'ES2019.Array' | 'es2019.array' | 'ES2019.Object' | 'es2019.object' | 'ES2019.String' | 'es2019.string' | 'ES2019.Symbol' | 'es2019.symbol' | 'ES2019' | 'es2019' | 'ES2020.BigInt' | 'es2020.bigint' | 'ES2020.Intl' | 'es2020.intl' | 'ES2020.Promise' | 'es2020.promise' | 'ES2020.SharedMemory' | 'es2020.sharedmemory' | 'ES2020.String' | 'es2020.string' | 'ES2020.Symbol.WellKnown' | 'es2020.symbol.wellknown' | 'ES2020' | 'es2020' | 'ES2021.Promise' | 'es2021.promise' | 'ES2021.String' | 'es2021.string' | 'ES2021.WeakRef' | 'es2021.weakref' | 'ES2021' | 'es2021' | 'ESNext.Array' | 'esnext.array' | 'ESNext.AsyncIterable' | 'esnext.asynciterable' | 'ESNext.BigInt' | 'esnext.bigint' | 'ESNext.Intl' | 'esnext.intl' | 'ESNext.Promise' | 'esnext.promise' | 'ESNext.String' | 'esnext.string' | 'ESNext.Symbol' | 'esnext.symbol' | 'ESNext.WeakRef' | 'esnext.weakref' | 'ESNext' | 'esnext' | 'ScriptHost' | 'scripthost' | 'WebWorker.ImportScripts' | 'webworker.importscripts' | 'WebWorker.Iterable' | 'webworker.iterable' | 'WebWorker' | 'webworker')[];
-    locale?: string;
-    mapRoot?: string;
-    maxNodeModuleJsDepth?: number;
-    module?: 'AMD' | 'amd' | 'CommonJS' | 'commonjs' | 'ES6' | 'es6' | 'ES2015' | 'es2015' | 'ES2020' | 'es2020' | 'ES2022' | 'es2022' | 'ESNext' | 'esnext' | 'Node16' | 'node16' | 'NodeNext' | 'nodenext' | 'None' | 'none' | 'System' | 'system' | 'UMD' | 'umd';
-    moduleDetection?: 'auto' | 'force' | 'legacy';
-    moduleResolution?: 'classic' | 'node' | 'node16' | 'nodenext';
-    moduleSuffixes?: string[];
-    newLine?: 'CRLF' | 'crlf' | 'LF' | 'lf';
-    noEmit?: boolean;
-    noEmitHelpers?: boolean;
-    noEmitOnError?: boolean;
-    noErrorTruncation?: boolean;
-    noFallthroughCasesInSwitch?: boolean;
-    noImplicitAny?: boolean;
-    noImplicitOverride?: boolean;
-    noImplicitReturns?: boolean;
-    noImplicitThis?: boolean;
-    noImplicitUseStrict?: boolean;
-    noLib?: boolean;
-    noPropertyAccessFromIndexSignature?: boolean;
-    noResolve?: boolean;
-    noStrictGenericChecks?: boolean;
-    noUncheckedIndexedAccess?: boolean;
-    noUnusedLocals?: boolean;
-    noUnusedParameters?: boolean;
-    out?: string;
-    outDir?: string;
-    outFile?: string;
-    paths?: MapLike<string[]>;
-    preserveConstEnums?: boolean;
-    preserveSymlinks?: boolean;
-    preserveValueImports?: boolean;
-    project?: string;
-    reactNamespace?: string;
-    removeComments?: boolean;
-    resolveJsonModule?: boolean;
-    rootDir?: string;
-    rootDirs?: string[];
-    skipDefaultLibCheck?: boolean;
-    skipLibCheck?: boolean;
-    sourceMap?: boolean;
-    sourceRoot?: string;
-    strict?: boolean;
-    strictBindCallApply?: boolean;
-    strictFunctionTypes?: boolean;
-    strictNullChecks?: boolean;
-    strictPropertyInitialization?: boolean;
-    stripInternal?: boolean;
-    suppressExcessPropertyErrors?: boolean;
-    suppressImplicitAnyIndexErrors?: boolean;
-    target?: 'ES3' | 'es3' | 'ES5' | 'es5' | 'ES6' | 'es6' | 'ES2015' | 'es2015' | 'ES2016' | 'es2016' | 'ES2017' | 'es2017' | 'ES2018' | 'es2018' | 'ES2019' | 'es2019' | 'ES2020' | 'es2020' | 'ES2021' | 'es2021' | 'ESNext' | 'esnext';
-    traceResolution?: boolean;
-    tsBuildInfoFile?: string;
-    typeRoots?: string[];
-    types?: string[];
-    useDefineForClassFields?: boolean;
-    useUnknownInCatchVariables?: boolean;
-    [option: string]: CompilerOptionsValue | undefined;
-}
-export type { CompilerOptionsJson as default };