import { uriSchemeDelimiterUnescaped, uriSchemeSubDelimiterUnescaped } from "./constant.js";
import type { RelativePath } from '@-xun/fs';
import type { GenericProjectMetadata, WorkspacePackageId } from '@-xun/project-types';
import type { Arrayable } from 'type-fest';
export { uriSchemeDelimiterUnescaped as uriSchemeDelimiter, uriSchemeSubDelimiterUnescaped as uriSchemeSubDelimiter };
/**
 * A regex containing illegal alias key characters.
 *
 * **This regular expression must never have the "global" flag**, meaning it is
 * safe to use with `.test()`.
 */
export declare const invalidAliasRegExp: RegExp;
/**
 * A regex containing illegal alias value characters.
 *
 * **This regular expression must never have the "global" flag**, meaning it is
 * safe to use with `.test()`.
 */
export declare const invalidPathRegExp: RegExp;
/**
 * A regex that matches any string that looks like a relative path without also
 * looking like a bare specifier.
 *
 * **This regular expression must never have the "global" flag**, meaning it is
 * safe to use with `.test()`.
 */
export declare const isLocalLookingRegExp: RegExp;
/**
 * A well-known import alias group, such as "universe" or "multiverse".
 */
export declare enum WellKnownImportAlias {
  /**
   * This alias always refers to the project root (i.e. root package)'s `./src`
   * directory.
   *
   * Examples of matching aliases:
   * - `"universe"`                           (root ./index.ts)
   * - `"universe:some/path/index.ts"`        (root ./src/some/path/index.ts)
   */
  Universe = "universe",
  /**
   * This alias always refers to a sub-root package's `./src` directory.
   *
   * Examples of matching aliases:
   * - `"multiverse+package-id"`              (package ./src/index.js)
   * - `"multiverse+package-id:some/path.js"` (package ./src/some/path.js)
   */
  Multiverse = "multiverse",
  /**
   * This alias refers to either a root or sub-root package's `./test`
   * directory.
   *
   * Examples of matching aliases:
   * - `"testverse:some/path.ts"`             (root ./test/some/path.ts)
   * - `"testverse+package-id:some/path.ts"`  (package ./test/some/path.ts)
   */
  Testverse = "testverse",
  /**
   * This alias always refers to the project root's `./types` directory.
   *
   * Examples of matching aliases:
   * - `"multiverse+common:types.ts"`                (root ./types/global.ts)
   */
  Typeverse = "typeverse",
  /**
   * This alias always refers to some file relative to the project root.
   *
   * Examples of matching aliases:
   * - `"rootverse:some/path.js"`             (root ./some/path.js)
   * - `"rootverse+package-id some/path.ts"`  (package ./some/path.ts)
   */
  Rootverse = "rootverse",
}
/**
 * A metadata object describing an "alias key," sometimes referred to as an
 * "alias". Always corresponds to an "alias value" (i.e. an "alias path").
 *
 * @see {@link RawPath}
 */
export type RawAlias = {
  /**
   * Determines the prefix matching behavior for alias keys. Choices are:
   *
   * - `none`: Any string containing `alias` may match. This is only useful for
   *   custom one-off aliases and should be avoided.
   * - `exact`: Only strings beginning with `alias` exactly may match.
   */
  prefix: 'none' | 'exact';
  /**
   * Determines the suffix matching behavior for alias keys. Choices are:
   *
   * - `none`: Any string containing `alias` may match. This has some
   *   tooling-specific quirks and should be avoided.
   * - `exact`: Only strings ending with `alias` exactly may match.
   * - `open`: Only strings ending with `alias + sep + subpath` may match.
   */
  suffix: 'none' | 'exact' | 'open';
  /**
   * The eponymous "raw alias". Must not contain any path separator characters
   * (i.e. "/", "\", or ":") or the "$" character.
   */
  alias: string;
  /**
   * The well-known import alias "group" to which the raw `alias` belongs.
   */
  group: WellKnownImportAlias;
  /**
   * A regular expression derived from `alias` that can be matched against
   * specifier strings. If this alias's `suffix` is `"open"`, the returned
   * expression will include a single matching group containing the full
   * specifier path without modification.
   *
   * Any RegExp control characters present in `alias` (e.g. "+", "*", "?") will
   * be escaped.
   *
   * @see {@link rawAliasToRegExp}
   */
  regExp: RegExp;
  /**
   * If this alias contains a reference to a package's id (e.g.
   * "universe+package-id"), `packageId` must be defined.
   */
  packageId: WorkspacePackageId | undefined;
};
/**
 * A metadata object describing an "alias path," sometimes referred to as an
 * "alias value". Always corresponds to an "alias key" (i.e. an "alias").
 *
 * @see {@link RawAlias}
 */
export type RawPath = {
  /**
   * Determines the final path returned in lieu of a matched alias. Choices are:
   *
   * - `root`: `path` will always be resolved starting from the project root.
   *   This resolution may be handled by this package or by the tooling itself
   *   depending on said tooling's capabilities.
   */
  prefix: 'root';
  /**
   * Determines the final path returned in lieu of a matched alias. Choices are:
   *
   * - `none`: `path` will be returned as-is. This is only useful for custom
   *   one-off aliases and should be avoided.
   * - `open`: The subpath matched by the `'open'` {@link RawAlias.suffix}
   *   configuration will be appended to `path` (separated by `'/'`) and
   *   returned. If the corresponding {@link RawAlias.suffix} is not also
   *   configured with `{ suffix: 'open' }`, an error will be thrown.
   */
  suffix: 'none' | 'open';
  /**
   * The eponymous "raw path". Must not contain the ":" linux path separator
   * character. Must not start or end with the "/" character, or start with
   * "./".
   *
   * `path` is considered relative to the project root.
   */
  path: RelativePath;
  /**
   * If `false`, an extension will be appended to the path automatically. The
   * extension to be appended depends on which tooling the aliases are being
   * generated for.
   *
   * Set `extensionless` to `false` when `path` points to a file. Otherwise, set
   * it to `true`.
   *
   * @default true
   */
  extensionless: boolean;
};
/**
 * Represents a single mapping between a {@link RawAlias} and a {@link RawPath}.
 */
export type RawAliasMapping = [key: RawAlias, value: RawPath];
/**
 * Accepts partial {@link RawAlias} and {@link RawPath} objects and returns
 * proper {@link RawAlias} and {@link RawPath} objects as a key-value tuple.
 *
 * Note that `rawAlias` defaults to `{ prefix: 'exact', suffix: 'open',
 * extensionless: true }` while `rawPath` defaults to `{ prefix: 'root', suffix:
 * 'open' }`.
 */
export declare function makeRawAliasMapping(rawAlias: Partial<Omit<RawAlias, 'alias' | 'group' | 'regExp' | 'packageId'>> & Pick<RawAlias, 'alias' | 'group' | 'packageId'>, rawPath: Partial<Omit<RawPath, 'path'>> & Pick<RawPath, 'path'>): RawAliasMapping;
/**
 * Given `projectMetadata`, this function returns an array of
 * {@link RawAliasMapping} entries. Each entry maps an import specifier alias
 * ({@link RawAlias}) to a filesystem path ({@link RawPath}) used throughout
 * said project. Filesystem paths will always be generated as relative paths
 * with respect to the project root.
 *
 * Entries will be returned in the order expected for the majority of
 * configuration subsystems: multiverse \> universe \> testverse \> typeverse \>
 * rootverse. An alternative order, expected for import sorting, is also
 * available (via `outputTarget`): multiverse \> rootverse \> universe \>
 * testverse \> typeverse.
 *
 * Entries within the same verse are sorted in "specificity" order, meaning
 * open-suffix aliases will have a chance to match before exact-suffix aliases,
 * and more specific open-suffix aliases will have a chance to match before
 * less-specific or catch-all open-suffix aliases. Entries of the same
 * "specificity" will then be natural sorted.
 *
 * (Unsorted) examples of supported aliases:
 * - `"universe"`                           (root ./index.ts)
 * - `"universe:some/path/index.ts"`        (root ./src/some/path/index.ts)
 * - `"multiverse+package-id"`              (package ./src/index.js)
 * - `"multiverse+package-id:some/path.js"` (package ./src/some/path.js)
 * - `"testverse:some/path.ts"`             (root ./test/some/path.ts)
 * - `"testverse+package-id:some/path.ts"`  (package ./test/some/path.ts)
 * - `"multiverse+common:types.ts"`         (root ./types/global.ts)
 * - `"rootverse:some/path.js"`             (root ./some/path.js)
 * - `"rootverse+package-id:some/path.ts"`  (package ./some/path.ts)
 *
 * @see https://github.com/Xunnamius/symbiote/wiki/Standard-Aliases
 */
export declare function generateRawAliasMap(projectMetadata: GenericProjectMetadata,
/**
 * This controls the order of the elements of this function's output. The
 * options are:
 *
 * - for-config: the output is ordered for general consumption by tooling
 * - for-import-ordering: the output is ordered for eslint-plugin-import
 * - for-import-hinting: the output is ordered for tsconfig
 *
 * `"for-import-ordering"` is useful for automatic import ordering and sorting
 * powered by eslint. `"for-import-hinting"` ensures that aliases are ordered
 * in such a way that TypeScript-based intellisense will return more prudent
 * results.
 */
outputTarget?: 'for-config' | 'for-import-ordering' | 'for-import-hinting'): RawAliasMapping[];
/**
 * Returns an object that can be plugged into
 * "babel-plugin-transform-rewrite-imports" Babel plugin configurations at
 * `replaceExtensions`.
 *
 * See also:
 * https://www.npmjs.com/package/babel-plugin-transform-rewrite-imports
 */
export declare function deriveAliasesForBabel(rawAliasMappings: readonly RawAliasMapping[]): {
  [k: string]: string;
};
/**
 * Returns an array that can be plugged into ESLint configurations at
 * `settings['import/resolver'].alias.map`. These days, the output of this
 * function is used primarily for import ordering and sorting via
 * eslint-plugin-import.
 *
 * See also: https://www.npmjs.com/package/eslint-import-resolver-alias
 */
export declare function deriveAliasesForEslint(rawAliasMappings: readonly RawAliasMapping[]): string[][];
/**
 * Returns an object that can be plugged into Webpack configurations at
 * `resolve.alias`.
 *
 * See also: https://webpack.js.org/configuration/resolve/#resolvealias
 */
export declare function deriveAliasesForWebpack(rawAliasMappings: readonly RawAliasMapping[]): {
  [k: string]: string;
};
/**
 * Returns an object that can be plugged into NextJs configurations. Currently
 * only Webpack-based alias configurations are supported, making this function
 * identical to {@link getWebpackAliases}. This may change in the future given
 * the existence of SWC and related tooling in the Next.js ecosystem.
 *
 * See also: https://nextjs.org/docs/messages/invalid-resolve-alias
 */
export declare function deriveAliasesForNextJs(rawAliasMappings: readonly RawAliasMapping[]): {
  [k: string]: string;
};
/**
 * Returns an object that can be plugged into Jest configurations at
 * `moduleNameMapper`.
 *
 * See also:
 * https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring
 */
export declare function deriveAliasesForJest(rawAliasMappings: readonly RawAliasMapping[]): {
  [k: string]: string;
};
/**
 * Returns an object that can be plugged into TypeScript project configurations
 * at `compilerOptions.paths`.
 *
 * See also: https://www.typescriptlang.org/tsconfig/#paths
 */
export declare function deriveAliasesForTypeScript(rawAliasMappings: readonly RawAliasMapping[]): {
  [k: string]: string[];
};
/**
 * Accepts a _raw `specifier`_ and returns the first matching
 * {@link RawAliasMapping} (in precedence order) or `undefined` if `specifier`
 * does not match any `rawAliasMappings`
 *
 * A "raw `specifier`" is the specifier string of an import statement before it
 * has been resolved to an actual filesystem path.
 */
export declare function mapRawSpecifierToRawAliasMapping(rawAliasMappings: readonly RawAliasMapping[], specifier: string): RawAliasMapping | undefined;
/**
 * Accepts a _raw `specifier`_ and returns an "bare" {@link RelativePath} (in
 * that it does not begin with "./") to a theoretical location on the filesystem
 * or `undefined` if `specifier` does not match any `rawAliasMappings`.
 *
 * The path returned by this function is always relative to the project root.
 *
 * A "raw `specifier`" is the specifier string of an import statement before it
 * has been resolved to a real filesystem path (such as by this function).
 */
export declare function mapRawSpecifierToPath(rawAliasMappings: Arrayable<RawAliasMapping>, specifier: string, {
  extensionToAppend
}?: {
  /**
   * For alias raw paths configured with `extensionless === false`, this is
   * the extension that will be appended to the final path. Should begin with
   * a "." character.
   *
   * @default ".ts"
   */
  extensionToAppend?: string;
}): RelativePath | undefined;
/**
 * This function throws if the given specifier violates any general symbiote
 * project invariants with respect to the given {@link RawAliasMapping}s.
 */
export declare function ensureRawSpecifierOk(rawAliasMappings: Arrayable<RawAliasMapping>, specifier: string, {
  allowMultiversalImports,
  allowForeignUniversalImports,
  allowTestversalImports,
  allowRootverseNodeModules,
  packageId,
  extensionToAppend,
  containingFilePath
}: {
  /**
   * Unless `true`, if a multiverse import not belonging to `packageId` is
   * encountered, this function will throw.
   *
   * Note that multiversal testverse and typeverse imports, while technically
   * multiversal imports, are _never_ governed by this property.
   */
  allowMultiversalImports: boolean;
  /**
   * Unless `true`, if `packageId` is defined and a universe import not
   * belonging to `packageId` is encountered, this function will throw.
   *
   * Note that foreign universal imports are a type of multiversal import and
   * as such are additionally governed by `allowMultiversalImports`.
   */
  allowForeignUniversalImports: boolean;
  /**
   * Unless `true`, if a testverse import is encountered, this function will
   * throw.
   *
   * Note that multiversal testverse imports, while technically a type of
   * multiversal import, are _never_ governed by `allowMultiversalImports`.
   */
  allowTestversalImports: boolean;
  /**
   * Unless `true`, if a rootverse import precariously referencing
   * node_modules is encountered, this function will throw.
   *
   * Note that multiversal rootverse imports of node_modules are a type of
   * multiversal import and as such are additionally governed by
   * `allowMultiversalImports`.
   */
  allowRootverseNodeModules: boolean;
  /**
   * Since it is ill-advised to make universe imports from within a sub-root,
   * such imports should not be seen when we're building distributables for a
   * workspace package. If `packageId` is not `undefined`, this check will be
   * enabled.
   *
   * Additionally, defining `packageId` enables multiverse self-reference
   * checks to ensure a sub-root is not using a multiverse alias to import its
   * own files, which is suboptimal.
   */
  packageId?: WorkspacePackageId;
  /**
   * This is the extension potentially appended to `specifier` if alias raw
   * path was configured with `extensionless === false`. Should begin with a
   * "." character.
   *
   * This value is used only to check for bad index imports and is so named
   * for consistency's sake. No appending of extensions is performed by this
   * function.
   *
   * @default ".ts"
   */
  extensionToAppend?: string;
  /**
   * A string representing the file containing the alias that, if given, will
   * be included in any exceptions thrown by this function.
   */
  containingFilePath?: string;
}): void;
/**
 * Takes a {@link RawAlias} partial and returns a regular expression that can be
 * matched against specifier strings. If `suffix` is `"open"`, the returned
 * expression will include a single matching group containing the full specifier
 * path without modification.
 *
 * Any RegExp control characters in `alias` will be escaped.
 */
export declare function rawAliasToRegExp({
  prefix,
  alias,
  suffix
}: Omit<RawAlias, 'regExp'>): RegExp;