/** * ## Re-exports * * ### Functions * * - [generateApiDocsMd = DevUtils.generateApiDocsMd](classes/DevUtils.md#api-generateapidocsmd) * - [generateApiDocsAndUpdateReadme = DevUtils.generateApiDocsAndUpdateReadme](classes/DevUtils.md#api-generateapidocsandupdatereadme) * - [getGitInfo = DevUtils.getGitInfo](classes/DevUtils.md#api-getgitinfo) * - [loadConfiguration = DevUtils.loadConfiguration](classes/DevUtils.md#api-loadconfiguration) * - [loadConfigurationWithVariant = DevUtils.loadConfigurationWithVariant](classes/DevUtils.md#api-loadconfigurationwithvariant) * * ## Exports * * @module */ import type { TypeDocOptions } from 'typedoc' assert { 'resolution-mode': 'import' }; /** * Git related information. See https://github.com/jacob-meacham/serverless-plugin-git-variables */ export interface GitInfo { /** * name of the git repository */ repository: string; /** * hash of the current commit, a.k.a. commit ID, in short format */ commitIdShort: string; /** * hash of the current commit, a.k.a. commit ID, in full */ commitIdLong: string; /** * name of the current branch */ branch: string; /** * true if the workspace is currently dirty */ isDirty: boolean; /** * the most recent tag of the repo, evaluates to `git describe --always` */ describe: string; /** * the most recent tag of the repo, evaluates to `git describe --always --tags` */ describeLight: string; /** * current Git user's name as configured by `git config user.name ...` */ user: string; /** * current Git user's email as configured by `git config user.email ...` */ email: string; /** * tags on the current commit, or sha1/ID of the commit if there's no tag */ tags: string[]; /** * First tag on the current commit, or sha1/ID of the commit if there's no tag */ tag: string; /** * full git commit message */ message: string; /** * subject of the commit message, as `git log -1 --pretty=%s` */ messageSubject: string; /** * body of the commit message, as `git log -1 --pretty=%b` */ messageBody: string; } export type GitInfoKey = keyof GitInfo; declare const configurationParsers: { yaml: (text: string) => any; json: (text: string) => any; }; /** * Options for loadConfiguration(...) function */ export interface LoadConfigurationOptions { /** * In which directory configuration file(s) should be picked up */ dir: string; /** * Predicate function for deciding whether configuration files in the ancestor directory should be picked up */ shouldCheckAncestorDir: (level: number, dirName: string, dirAbsolutePath: string, consolidatedConfiguration: Partial | undefined, previousDirAbsolutePath: string) => boolean; /** * File extensions that should be picked up. It is an object. For each property, the key is the file extension, the value is the file/parser type. */ extensions: Record; /** * Encoding of the configuration files */ encoding: BufferEncoding; /** * Function for merging the configurations from different files. * It is supposed to merge the object on the right to the object on the left. * The function is also supposed to return the modified object on the left. */ merge: (base: T | undefined, override: T | undefined) => T; } export declare abstract class DevUtils { static generateApiDocsMd(entryPoints?: string[], apiDocDir?: string, options?: Partial>): Promise; /** * Generate API documentation and insert it into README.md file. * @param readmeLocation location of the README.md file * @param entryPoints Entry points for generating API documentation * @param apiDocDir temporary directory for storing intermediate documentation files * @param typeDocOptions Options for TypeDoc * @returns Promise of void * @example * DevUtils.generateApiDocsAndUpdateReadme(readmePath, entryPoints, apiDocDir); */ static generateApiDocsAndUpdateReadme(readmeLocation?: string, entryPoints?: string[], apiDocDir?: string, typeDocOptions?: Partial>): Promise; /** * Get Git related information. This function relies on the existence of Git command line. * * By default all possible information will be returned, but this can be overridden by * specifying `whitelistKeys` argument. * * If `checkEnvironmentVariables` argument is `true`, then environment variables `GIT_COMMIT` and `GITHUB_SHA` * will be checked before trying to identify the commit ID from local Git repository, * also environment variables `GIT_LOCAL_BRANCH`, `GIT_BRANCH`, `BRANCH_NAME`, `GITHUB_REF_NAME` * will be checked before trying to identify the branch name from local Git repository. * * This function never throws Error. For example, if user and email have not been configured, * they would be undefined in the returned object. * * @param whitelistKeys keys (property names) in the returned object that values need to be populated * @param checkEnvironmentVariables true (default value) if environment variables should be checked * @param reportErrors true if errors should be reported in the `errors: any[]` property of the returned object * @returns Git related information */ static getGitInfo(whitelistKeys?: GitInfoKey[], checkEnvironmentVariables?: boolean, reportErrors?: boolean): Promise>; /** * Default options for `loadConfiguration(...)` */ static readonly DEFAULT_OPTIONS_FOR_LOAD_CONFIGURATION: LoadConfigurationOptions; /** * Load configuration from YAML and/or JSON files. * This function is capable of reading multiple configuration files from the same directory and optionally its ancestor directories, and combine the configurations. * * Internal logic of this function is: \ * 1. Start from the directory as specified by options.dir (default is ".") \ * 2. Try to read and parse all the files as specified by `${dir}${options.extensions.}` as type `options.extensions.` \ * 2.1 Unreadable (non-existing, no permission, etc.) files are ignored \ * 2.2 File content parsing error would halt the process with an Error \ * 2.3 Files specified at the top of `options.extensions` overrides those at the bottom \ * 2.4 Default configuration in `options.extensions` is: ".yaml" as YAML, ".yml" as YAML, ".json" as JSON. You can override it. \ * 3. Find the parent directory, and use `options.shouldCheckAncestorDir` function to decide if parent directory should be checked. \ * 3.1 The function won't be called for the starting directory. The first call to this function would be for the parent directory with level=1. \ * 3.2 If parent directory should be checked, use parent directory and go to step 2 \ * 3.3 Otherwise finish up \ * 3.4 Default configuration of `options.shouldCheckAncestorDir` always returns false. You can override it. \ * 3.4.1 Several parameters are passed to the function: level (the immediate parent directory has the level value 1), basename of the directory, absolute path of the directory, already consolidated/merged configurations, absolute path of the directory containing the last/previous file picked up. \ * 4. Configurations in child directories override configurations in parent directories. \ * * Other options: \ * `encoding`: encoding used when reading the file, default is 'utf8' \ * `merge`: the function for merging configurations, the default implementation uses lodash/merge \ * * @example * // Pick up and merge (those to the left overrides those to the right) configurations from: ./my-config.yaml, ./my-config.yml, ./my-config.json * const config = DevUtils.loadConfiguration('my-config'); * * // Let .json override .yml and don't try to pick up .yaml * const config = DevUtils.loadConfiguration('my-config', { extensions: { * '.json': 'json', * '.yml': 'yaml', * } }); * * // Search in parent, grand parent, and great grand parent directories as well * const config = DevUtils.loadConfiguration( * 'my-config', * { * dir: 'test/fixtures/dir_L1/dir_L2/dir_L3/dir_L4', * shouldCheckAncestorDir: (level, _dirName, _dirAbsolutePath) => level <= 3, * }, * ); * * @param fileNameBase Base part of the file name, usually this is the file name without extension, but you can also be creative. * @param overrideOptions Options that would be combined with default options. * @returns The combined configuration, or undefined if no configuration file can be found/read. */ static loadConfiguration(fileNameBase: string, overrideOptions?: Partial>): T | undefined; /** * Load configuration from YAML and/or JSON files with variant suffix. * This function is capable of reading multiple configuration files from the same directory and optionally its ancestor directories, and combine the configurations. * This function is based on {@link loadConfiguration}. * It picks up the specified variant configuration and the base variant configuration from a directory and optionally its ancestor directories, * then merge them by overriding the base variant configuration with the specified variant configuration. * * @param fileNameBase Base part of the file name, for example, `my-config`, `settings`. * @param variant Part of the file name that identifies the variant, for example, `.staging`, `-production`, `_test`. * When searching for configuration files, it would be inserted between the fileNameBase and the file type suffix. * @param baseVariant Part of the file name that identifies the base variant. The default value is `.default`. * When searching for configuration files, it would be inserted between the fileNameBase and the file type suffix. * @param overrideOptions Options that would be combined with default options. * @returns The combined configuration, or undefined if no configuration file can be found/read. */ static loadConfigurationWithVariant(fileNameBase: string, variant: string, baseVariant?: string, overrideOptions?: Partial>): T | undefined; } /** @ignore */ export declare const generateApiDocsMd: typeof DevUtils.generateApiDocsMd; /** @ignore */ export declare const generateApiDocsAndUpdateReadme: typeof DevUtils.generateApiDocsAndUpdateReadme; /** @ignore */ export declare const getGitInfo: typeof DevUtils.getGitInfo; /** @ignore */ export declare const loadConfiguration: typeof DevUtils.loadConfiguration; /** @ignore */ export declare const loadConfigurationWithVariant: typeof DevUtils.loadConfigurationWithVariant; export {}; //# sourceMappingURL=dev-utils.d.ts.map