diff --git a/types/semantic-release/index.d.ts b/types/semantic-release/index.d.ts index 656461b756..744c5b301e 100644 --- a/types/semantic-release/index.d.ts +++ b/types/semantic-release/index.d.ts @@ -1,46 +1,386 @@ // Type definitions for semantic-release 15.13 // Project: https://github.com/semantic-release/semantic-release#readme // Definitions by: Leonardo Gatica +// Daniel Cassidy // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -/** - * The semantic release configuration itself. - */ -export interface GlobalConfig { - /** The full prepare step configuration. */ - prepare?: any; - /** The branch on which releases should happen. */ - branch: string; - /** The Git repository URL, in any supported format. */ - repositoryUrl: string; - /** The Git tag format used by semantic-release to identify releases. */ - tagFormat: string; -} +/// -export interface LastRelease { - /** The version name of the release */ - version: string; - /** The Git tag of the release. */ - gitTag: string; - /** The Git checksum of the last commit of the release. */ - gitHead: string; -} +declare namespace SemanticRelease { + /** + * semantic-release options. + * + * Can be used to set any core option or plugin options. + * Each option will take precedence over options configured in the + * configuration file and shareable configurations. + */ + interface Options { + /** + * The branch on which releases should happen. + */ + branch?: string; -export interface NextRelease extends LastRelease { - /** The release notes of the next release. */ - notes: string; -} + /** + * The Git repository URL, in any supported format. + */ + repositoryUrl?: string; -export interface Context { - /** The semantic release configuration itself. */ - options?: GlobalConfig; - /** The previous release details. */ - lastRelease?: LastRelease; - /** The next release details. */ - nextRelease?: NextRelease; - /** The shared logger instance of semantic release. */ - logger: { - log: (message: string, ...vars: any[]) => void, - error: (message: string, ...vars: any[]) => void, + /** + * The Git tag format used by semantic-release to identify releases. + */ + tagFormat?: string; + + /** + * Specifies the list of plugins to use. Plugins will run in series, in + * the order specified. + * + * If this option is not specified, then semantic-release will use a + * default list of plugins. + * + * Configuration options for each plugin can be defined by wrapping the + * name and an options object in an array. + */ + plugins?: ReadonlyArray; + + /** + * Dry-run mode, skip publishing, print next version and release notes. + */ + dryRun?: boolean; + + /** + * Set to false to skip Continuous Integration environment verifications. + * This allows for making releases from a local machine. + */ + ci?: boolean; + + /** + * Any other options supported by plugins. + */ + [name: string]: any; + } + + /** + * semantic-release options, after normalization and defaults have been + * applied. + */ + interface GlobalConfig extends Options { + /** + * The branch on which releases should happen. + */ + branch: string; + + /** + * The Git repository URL, in any supported format. + */ + repositoryUrl: string; + + /** + * The Git tag format used by semantic-release to identify releases. + */ + tagFormat: string; + + /** + * Specifies the list of plugins to use. Plugins will run in series, in + * the order specified. + * + * If this option is not specified, then semantic-release will use a + * default list of plugins. + * + * Configuration options for each plugin can be defined by wrapping the + * name and an options object in an array. + */ + plugins: ReadonlyArray; + } + + /** + * Specifies a plugin to use. + * + * The plugin is specified by its module name. + * + * To pass options to a plugin, specify an array containing the plugin module + * name and an options object. + */ + type PluginSpec = string | [string, any]; + + /** semantic-release configuration specific for API usage. */ + interface Config { + /** + * The current working directory to use. It should be configured to + * the root of the Git repository to release from. + * + * It allows to run semantic-release from a specific path without + * having to change the local process cwd with process.chdir(). + * + * @default process.cwd + */ + cwd?: string; + + /** + * The environment variables to use. + * + * It allows to run semantic-release with specific environment + * variables without having to modify the local process.env. + * + * @default process.env + */ + env?: { [name: string]: string }; + + /** + * The writable stream used to log information. + * + * It allows to configure semantic-release to write logs to a specific + * stream rather than the local process.stdout. + * + * @default process.stdout + */ + stdout?: NodeJS.WriteStream; + + /** + * The writable stream used to log errors. + * + * It allows to configure semantic-release to write errors to a + * specific stream rather than the local process.stderr. + * + * @default process.stderr + */ + stderr?: NodeJS.WriteStream; + } + + interface LastRelease { + /** + * The version name of the release. + */ + version: string; + + /** + * The Git tag of the release. + */ + gitTag: string; + + /** + * The Git checksum of the last commit of the release. + */ + gitHead: string; + } + + interface NextRelease extends LastRelease { + /** + * The semver type of the release. + */ + type: "patch" | "minor" | "major"; + + /** + * The release notes of the next release. + */ + notes: string; + } + + interface Context { + /** + * The semantic release configuration itself. + */ + options?: GlobalConfig; + + /** + * The previous release details. + */ + lastRelease?: LastRelease; + + /** + * The next release details. + */ + nextRelease?: NextRelease; + + /** + * The shared logger instance of semantic release. + */ + logger: { + log: (message: string, ...vars: any[]) => void, + error: (message: string, ...vars: any[]) => void, + }; + + /** + * Environment variables. + */ + env: { + [key: string]: string; + }; + } + + interface Commit { + /** + * The commit abbreviated and full hash. + */ + commit: { + /** + * The commit hash. + */ + long: string; + + /** + * The commit abbreviated hash. + */ + short: string; + }; + + /** + * The commit abbreviated and full tree hash. + */ + tree: { + /** + * The commit tree hash. + */ + long: string; + + /** + * The commit abbreviated tree hash. + */ + short: string; + }; + + /** + * The commit author information. + */ + author: { + /** + * The commit author name. + */ + name: string; + + /** + * The commit author email. + */ + email: string; + + /** + * The commit author date. + */ + short: string; + }; + + /** + * The committer information. + */ + committer: { + /** + * The committer name. + */ + name: string; + + /** + * The committer email. + */ + email: string; + + /** + * The committer date. + */ + short: string; + }; + + /** + * The commit subject. + */ + subject: string; + + /** + * The commit body. + */ + body: string; + + /** + * The commit full message (subject and body). + */ + message: string; + + /** + * The commit hash. + */ + hash: string; + + /** + * The committer date. + */ + committerDate: string; + } + + /** + * Details of a release published by a publish plugin. + */ + interface Release { + /** + * The release name, only if set by the corresponding publish plugin. + */ + name?: string; + + /** + * The release URL, only if set by the corresponding publish plugin. + */ + url?: string; + + /** + * The semver type of the release. + */ + type: "patch" | "minor" | "major"; + + /** + * The version of the release. + */ + version: string; + + /** + * The sha of the last commit being part of the release. + */ + gitHead: string; + + /** + * The Git tag associated with the release. + */ + gitTag: string; + + /** + * The release notes for the release. + */ + notes: string; + + /** + * The name of the plugin that published the release. + */ + pluginName: string; + } + + /** + * An object with details of the release if a release was published, or + * false if no release was published. + */ + type Result = false | { + /** + * Information related to the last release found. + */ + lastRelease: LastRelease; + + /** + * The list of commits included in the new release. + */ + commits: Commit[]; + + /** + * Information related to the newly published release. + */ + nextRelease: NextRelease; + + /** + * The list of releases published, one release per publish plugin. + */ + releases: Release[]; }; } + +/** + * Run semantic-release and returns a Promise that resolves to a Result + * object. + */ +declare function SemanticRelease(options: SemanticRelease.Options, + environment?: SemanticRelease.Config): Promise; + +export = SemanticRelease; diff --git a/types/semantic-release/semantic-release-tests.ts b/types/semantic-release/semantic-release-tests.ts index 0c954fe295..7cf5621fe5 100644 --- a/types/semantic-release/semantic-release-tests.ts +++ b/types/semantic-release/semantic-release-tests.ts @@ -1,17 +1,118 @@ import * as lib from 'semantic-release'; +import semanticRelease = require('semantic-release'); + +function verify(pluginConfig: any, context: lib.Context) { + if (!("AWS_ACCESS_KEY_ID" in context.env)) { + throw new Error("AWS_ACCESS_KEY_ID not set"); + } +} function publish(pluginConfig: any, context: lib.Context) { const version = context.nextRelease && context.nextRelease.version; context.logger.log(`New version ${version}`); } -const context = { +const options: lib.GlobalConfig = { + branch: "master", + repositoryUrl: "https://github.com/semantic-release/semantic-release.git", + // Lint check disabled for the following line because this is the actual + // format used by semantic-release. This is not a broken template string. + tagFormat: "v${version}", // tslint:disable-line: no-invalid-template-strings + plugins: ["@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/npm", + "@semantic-release/github", + ["@qiwi/semantic-release-gh-pages-plugin", { + msg: "updated", + branch: "docs" + }]], + dryRun: false, + ci: true, + // Example of extended options supported by plugins. + assets: [ + { + path: "app.zip" + } + ] +}; + +const context: lib.Context = { nextRelease: { + type: "major", version: '1.0.0', gitTag: '1.0.0', gitHead: 'f1eed296d2ffe184fb15f52b1c5ad778f5c87645', notes: 'New release' }, - logger: console + logger: console, + env: { + AWS_ACCESS_KEY_ID: "12345", + SHELL: "/bin/bash", + PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + } }; +verify({}, context); publish({}, context); + +const config: lib.Config = { + cwd: "/home/example/code/semantic-release", + env: { + AWS_ACCESS_KEY_ID: "12345", + SHELL: "/bin/bash", + PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + }, + stdout: process.stdout, + stderr: process.stderr +}; + +const result: Promise = semanticRelease(options, config); + +const result2: lib.Result = { + lastRelease: { + version: "1.1.0", + gitTag: "v1.1.0", + gitHead: "ce5e4bb0624ffaf1deec298b6c79962efec7dd3b" + }, + commits: [{ + commit: { + long: "a018aff59995a17c0564fa3fd0cb96223f4d4096", + short: "a018aff" + }, + tree: { + long: "c8d47c8f9026337f780299eddcd6bbf69aec5db6", + short: "c8d47c8" + }, + author: { + name: "Lillian Devold", + email: "lillian.devold@example.org", + short: "2019-10-22" + }, + committer: { + name: "Lillian Devold", + email: "lillian.devold@example.org", + short: "2019-10-22" + }, + subject: "fix: encode text to HTML", + body: "This closes a potential script injection vector.", + message: "fix: encode text to HTML\n\nThis closes a potential script injection vector.", + hash: "a018aff59995a17c0564fa3fd0cb96223f4d4096", + committerDate: "2019-10-22" + }], + nextRelease: { + type: "minor", + version: "1.2.0", + gitTag: "v1.2.0", + gitHead: "a018aff59995a17c0564fa3fd0cb96223f4d4096", + notes: "" + }, + releases: [{ + name: "example-lib", + url: "https://www.npmjs.com/package/example-lib", + type: "minor", + version: "1.2.0", + gitHead: "a018aff59995a17c0564fa3fd0cb96223f4d4096", + gitTag: "v1.2.0", + notes: "", + pluginName: "@semantic" + }] +};