From 04d56d1e54e130f9daae45ce201ef269d7ed2650 Mon Sep 17 00:00:00 2001 From: Daniel Cassidy Date: Tue, 22 Oct 2019 21:49:31 +0100 Subject: [PATCH] semantic-release: add missing type definitions (#39317) * semantic-release: Add env field to Context. See: https://semantic-release.gitbook.io/semantic-release/developer-guide/plugin * semantic-release: Add missing plugins option. See: https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins See: https://semantic-release.gitbook.io/semantic-release/usage/plugins#plugin-options-configuration * semantic-release: Add missing dryRun & ci options. See: https://semantic-release.gitbook.io/semantic-release/usage/configuration#dryrun See: https://semantic-release.gitbook.io/semantic-release/usage/configuration#ci * semantic-release: Add indexer to GlobalConfig. In addition to the defined fields, users may specify any other arbitrary fields with arbitrary values. These and all other options will be passed through to plugins. Remove "prepare" field since this field is not actually defined or used by semantic-release itself. Its only mention in the semantic-release documentation is as an example for an option that will be passed through to plugins. This use is covered by the indexer. See: https://semantic-release.gitbook.io/semantic-release/usage/configuration See: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api * semantic-release: Add missing types for "JavaScript API". See: https://semantic-release.gitbook.io/semantic-release/developer-guide/js-api * semantic-release: Add self to list of maintainers. * semantic-release: Add test cases for Result type * semantic-release: fix lint errors. * semantic-release: Fix to compile with TypeScript 2.0. --- types/semantic-release/index.d.ts | 412 ++++++++++++++++-- .../semantic-release-tests.ts | 105 ++++- 2 files changed, 479 insertions(+), 38 deletions(-) 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" + }] +};