conventional-changelog 6.0.0 → 7.0.1

package/README.md

@@ -1,66 +1,267 @@
-#  [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coverage-image]][coverage-url]
+# conventional-changelog
 
-> Generate a changelog from git metadata
+[![ESM-only package][package]][package-url]
+[![NPM version][npm]][npm-url]
+[![Node version][node]][node-url]
+[![Dependencies status][deps]][deps-url]
+[![Install size][size]][size-url]
+[![Build status][build]][build-url]
+[![Coverage status][coverage]][coverage-url]
 
+[package]: https://img.shields.io/badge/package-ESM--only-ffe536.svg
+[package-url]: https://nodejs.org/api/esm.html
+
+[npm]: https://img.shields.io/npm/v/conventional-changelog.svg
+[npm-url]: https://npmjs.com/package/conventional-changelog
+
+[node]: https://img.shields.io/node/v/conventional-changelog.svg
+[node-url]: https://nodejs.org
+
+[deps]: https://img.shields.io/librariesio/release/npm/conventional-changelog
+[deps-url]: https://libraries.io/npm/conventional-changelog/tree
+
+[size]: https://packagephobia.com/badge?p=conventional-changelog
+[size-url]: https://packagephobia.com/result?p=conventional-changelog
+
+[build]: https://img.shields.io/github/actions/workflow/status/conventional-changelog/conventional-changelog/tests.yaml?branch=master
+[build-url]: https://github.com/conventional-changelog/conventional-changelog/actions
+
+[coverage]: https://coveralls.io/repos/github/conventional-changelog/conventional-changelog/badge.svg?branch=master
+[coverage-url]: https://coveralls.io/github/conventional-changelog/conventional-changelog?branch=master
+
+Generate a changelog from git metadata.
+
+*[Changelog?](https://speakerdeck.com/stevemao/compose-a-changelog)*
+
+> [!NOTE]
+> You don't have to use the angular commit convention. For the best result of the tool to tokenize your commit and produce flexible output, it's recommended to use a commit convention.
+
+<hr />
+<a href="#install">Install</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#usage">Usage</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#recommended-workflow">Recommended workflow</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#why">Why</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#presets">Presets</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#js-api">JS API</a>
+<br />
+<hr />
+
+## Install
+
+```bash
+# pnpm
+pnpm add conventional-changelog
+# yarn
+yarn add conventional-changelog
+# npm
+npm i conventional-changelog
+```
 
 ## Usage
 
-You most likely only need to use this module if you're building a library that provides an abstraction on top of conventional commits,  See [Getting started](https://github.com/conventional-changelog/conventional-changelog#getting-started) if you're an end-user.
+```sh
+conventional-changelog -p angular
+```
+
+This will *not* overwrite any previous changelogs. The above generates a changelog based on commits since the last semver tag that matches the pattern of "Feature", "Fix", "Performance Improvement" or "Breaking Changes".
+
+If this is your first time using this tool and you want to generate all previous changelogs, you could do
 
 ```sh
-$ npm install --save conventional-changelog
+conventional-changelog -p angular -r 0
 ```
 
-```js
-import conventionalChangelog from 'conventional-changelog';
+This *will* overwrite any previous changelogs if they exist.
+
+All available command line parameters can be listed using CLI: `conventional-changelog --help`.
+
+> [!TIP]
+> You can alias your command or add it to your package.json. EG: `"changelog": "conventional-changelog -p angular -r 0"`.
+
+## Recommended workflow
+
+1. Make changes
+2. Commit those changes
+3. Make sure Travis turns green
+4. Bump version in `package.json`
+5. `conventional-changelog`
+6. Commit `package.json` and `CHANGELOG.md` files
+7. Tag
+8. Push
 
-conventionalChangelog({
-  preset: 'angular'
-})
-  .pipe(process.stdout); // or any writable stream
+The reason why you should commit and tag after `conventional-changelog` is that the CHANGELOG should be included in the new release, hence `commits.from` defaults to the latest semver tag.
+
+### With `npm version`
+
+Using the npm scripts to our advantage with the following hooks:
+
+```json
+{
+  "scripts": {
+    "version": "conventional-changelog -p angular && git add CHANGELOG.md"
+  }
+}
 ```
 
-Or if you want to use your own custom preset:
+You could follow the following workflow
+
+1. Make changes
+2. Commit those changes
+3. Pull all the tags
+4. Run the [`npm version [patch|minor|major]`](https://docs.npmjs.com/cli/version) command
+5. Push
+
+You could optionally add a `preversion` script to package your project or running a full suit of test.
+And a `postversion` script to clean your system and push your release and tags.
+
+By adding a `.npmrc` you could also automate your commit message and set your tag prefix as such:
+
+```
+tag-version-prefix=""
+message="chore(release): %s :tada:"
+```
+
+## Why
+
+- Easy fully automate changelog generation. You could still add more points on top of it.
+- Ignoring reverted commits, templating with [handlebars.js](https://github.com/handlebars-lang/handlebars.js) and links to references, etc.
+- Intelligently setup defaults but yet fully configurable with presets of [popular projects](#presets).
+- Everything internally or externally is pluggable.
+- A lot of tests and actively maintained.
+
+## Presets
+
+- [angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular)
+- [atom](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-atom)
+- [codemirror](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-codemirror)
+- [conventionalcommits](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits)
+- [ember](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-ember)
+- [eslint](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint)
+- [express](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-express)
+- [jquery](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-jquery)
+- [jshint](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-jshint)
+
+## JS API
 
 ```js
-import conventionalChangelog from 'conventional-changelog';
-import config from '@org/conventional-changelog-custom-preset';
+import { ConventionalChangelog } from 'conventional-changelog'
+
+const generator = new ConventionalChangelog()
+  .readPackage()
+  .loadPreset('angular')
+
+generator
+  .writeStream()
+  .pipe(process.stdout)
+
+// or
 
-conventionalChangelog({config})
-  .pipe(process.stdout); // or any writable stream
+for await (const chunk of generator.write()) {
+  console.log(chunk)
+}
 ```
 
-## API
+### `new ConventionalChangelog(cwdOrGitClient: string | ConventionalGitClient = process.cwd())`
+
+Create a new instance of conventional-changelog generator. `cwdOrGitClient` is the current working directory or a `ConventionalGitClient` instance.
+
+#### `generator.loadPreset(preset: PresetParams): this`
+
+Load and set necessary params from a preset.
+
+#### `generator.config(config: Preset | Promise<Preset>): this`
+
+Set the config directly.
+
+#### `generator.readPackage(transform?: PackageTransform): this`
+
+Find `package.json` up the directory tree and read it. Optionally transform the package data.
+
+#### `generator.readPackage(path: string, transform?: PackageTransform): this`
+
+Read a `package.json` file from a specific path. Optionally transform the package data.
+
+#### `generator.package(pkg: Record<string, unknown>): this`
+
+Set the package data directly.
+
+#### `generator.readRepository(): this`
 
-### conventionalChangelog([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])
+Read and parse the repository URL from current git repository.
 
-Returns a readable stream.
+#### `generator.repository(infoOrGitUrl: string | Partial<HostedGitInfo>): this`
 
-#### options
+Set the repository info directly.
 
-See the [conventional-changelog-core](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core) docs. The API is the same with the following changes or additions:
+#### `generator.options(options: Options): this`
 
-##### preset
+Set conventional-changelog options.
 
-Type: `string` Possible values: `'angular', 'atom', 'codemirror', 'conventionalcommits', 'ember', 'eslint', 'express', 'jquery', 'jshint'`
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| reset | `boolean` | `false` | Whether to reset the changelog or not. |
+| append | `boolean` | `false`  | Should the log be appended to existing data. |
+| releaseCount | `number` | 1 | How many releases of changelog you want to generate. It counts from the upcoming release. Useful when you forgot to generate any previous changelog. Set to `0` to regenerate all. |
+| outputUnreleased | `boolean` | `true` if a different version than last release is given. Otherwise `false` | If this value is `true` and `context.version` equals last release then `context.version` will be changed to `'Unreleased'`. |
+| transformCommit | `(commit: Commit, params: Params) => Partial<Commit> \| Promise<Partial<Commit> \| null> \| null` |  | A transform function that applies after the parser and before the writer. |
+| warn | `function` |  | Logger for warnings |
+| debug | `function` |  | Logger for debug messages |
+| fromatDate | `(date: Date) => string` |  | Custom date formatter function. |
 
-It's recommended to use a preset so you don't have to define everything yourself. Presets are names of built-in `config`.
+#### `generator.context(context: Context): this`
 
-A scoped preset package such as `@scope/conventional-changelog-custom-preset` can be used by passing `@scope/custom-preset` to this option.
+Set the [writer context](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#context).
 
-**NOTE:** `options.config` will be overwritten by the values of preset. You should use either `preset` or `config`, but not both.
+#### `generator.tags(params: GetSemverTagsParams): this`
 
-## [Notes for parent modules](https://github.com/conventional-changelog/conventional-changelog-core#notes-for-parent-modules)
+Set params to get semver tags.
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| prefix | `string \| RegExp` |  | Specify a prefix for the git tag that will be taken into account during the comparison. |
+| skipUnstable | `boolean` | `false` | If set, unstable release tags will be skipped, e.g. x.x.x-rc. |
+| clean | `boolean` | `false` | Clean version from prefix and trash. |
+
+If you want to take package-prefixed tags, for example lerna-style tags, you should use `packagePrefix` utility function:
+
+```js
+import {
+  ConventionalChangelog,
+  packagePrefix
+} from 'conventional-changelog'
+
+const generator = new ConventionalChangelog()
+  .readPackage()
+  .loadPreset('angular')
+  .tags({
+    prefix: packagePrefix('foo-package')
+  })
+```
+
+#### `generator.commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this`
+
+Set params to get commits.
+
+- [GetCommitsParams](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts#L1-L41)
+- [ParserStreamOptions](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts#L1-L68)
+
+#### `generator.writer(params: WriterOptions): this`
+
+Set [writer options](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#options).
+
+#### `generator.write(includeDetails?: boolean): AsyncGenerator<string | Details<Commit>, void>`
+
+Generate changelog.
+
+#### `generator.writeStream(includeDetails?: boolean): Readable`
+
+Generate changelog stream.
 
 ## License
 
 MIT
-
-[npm-image]: https://badge.fury.io/js/conventional-changelog.svg
-[npm-url]: https://npmjs.org/package/conventional-changelog
-[travis-image]: https://travis-ci.org/conventional-changelog/conventional-changelog.svg?branch=master
-[travis-url]: https://travis-ci.org/conventional-changelog/conventional-changelog
-[daviddm-image]: https://david-dm.org/conventional-changelog/conventional-changelog.svg?theme=shields.io
-[daviddm-url]: https://david-dm.org/conventional-changelog/conventional-changelog
-[coverage-image]: https://coveralls.io/repos/github/conventional-changelog/conventional-changelog/badge.svg?branch=master
-[coverage-url]: https://coveralls.io/github/conventional-changelog/conventional-changelog?branch=master

package/dist/ConventionalChangelog.d.ts

@@ -0,0 +1,120 @@
+/// <reference types="node" resolution-mode="require"/>
+import { Readable } from 'stream';
+import type { ParserStreamOptions, Commit } from 'conventional-commits-parser';
+import { type GetSemverTagsParams, type GetCommitsParams, ConventionalGitClient, packagePrefix } from '@conventional-changelog/git-client';
+import { type Options as WriterOptions, type Context, type Details } from 'conventional-changelog-writer';
+import { type UnknownPresetCreatorParams, type PresetParams } from 'conventional-changelog-preset-loader';
+import type { HostedGitInfo, PackageTransform, Options, Preset } from './types.js';
+export { packagePrefix };
+/**
+ * Conventional changelog generator
+ */
+export declare class ConventionalChangelog {
+    private readonly gitClient;
+    private params;
+    constructor(cwdOrGitClient?: string | ConventionalGitClient);
+    private composeParams;
+    private finalizeContext;
+    private finalizeWriterOptions;
+    private getSemverTags;
+    private getCommits;
+    private transformCommits;
+    private getPackageJson;
+    /**
+     * Load configs from a preset
+     * @param preset
+     * @returns this
+     */
+    loadPreset<PresetCreatorParams extends UnknownPresetCreatorParams = UnknownPresetCreatorParams>(preset: PresetParams<PresetCreatorParams>): this;
+    /**
+     * Set the config directly
+     * @param config - Config object
+     * @returns this
+     */
+    config(config: Preset | Promise<Preset>): this;
+    /**
+     * Find package.json and read it
+     * @param transform - Optional transform function
+     * @returns this
+     */
+    readPackage(transform?: PackageTransform): this;
+    /**
+     * Read package.json from a specified path
+     * @param path - Path to package.json
+     * @param transform - Optional transform function
+     * @returns this
+     */
+    readPackage(path?: string, transform?: PackageTransform): this;
+    /**
+     * Set package.json data
+     * @param pkg - Package.json data
+     * @returns this
+     */
+    package(pkg: Record<string, unknown>): this;
+    /**
+     * Read repository info from the current git repository
+     * @returns this
+     */
+    readRepository(): this;
+    /**
+     * Set repository info
+     * @param infoOrGitUrl - Hosted git info or git url
+     * @returns this
+     */
+    repository(infoOrGitUrl: string | Partial<HostedGitInfo>): this;
+    /**
+     * Set conventional-changelog options
+     * @param options - Generator options
+     * @returns this
+     */
+    options(options: Options): this;
+    /**
+     * Set writer context data
+     * @param context - Writer context data
+     * @returns this
+     */
+    context(context: Context): this;
+    /**
+     * Set params to get semver tags
+     * @param params - Params to get the last semver tag
+     * @returns this
+     */
+    tags(params: GetSemverTagsParams): this;
+    /**
+     * Set params to get commits
+     * @param params - Params to get commits since last release
+     * @param parserOptions - Parser options
+     * @returns this
+     */
+    commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this;
+    /**
+     * Set writer options
+     * @param params - Writer options
+     * @returns this
+     */
+    writer(params: WriterOptions): this;
+    /**
+     * Generate changelog
+     * @param includeDetails - Generate data objects instead of strings
+     * @returns Changelog generator
+     */
+    write(includeDetails?: false): AsyncGenerator<string, void>;
+    /**
+     * Generate changelog data objects
+     * @param includeDetails - Generate data objects instead of strings
+     */
+    write(includeDetails: true): AsyncGenerator<Details<Commit>, void>;
+    /**
+     * Generate changelog
+     * @param includeDetails - Generate data objects instead of strings
+     * @returns Changelog generator
+     */
+    write(includeDetails?: boolean): AsyncGenerator<string | Details<Commit>, void>;
+    /**
+     * Generate changelog to stream
+     * @param includeDetails - Generate data objects instead of strings
+     * @returns Changelog stream
+     */
+    writeStream(includeDetails?: boolean): Readable;
+}
+//# sourceMappingURL=ConventionalChangelog.d.ts.map

package/dist/ConventionalChangelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConventionalChangelog.d.ts","sourceRoot":"","sources":["../src/ConventionalChangelog.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACjC,OAAO,KAAK,EACV,mBAAmB,EACnB,MAAM,EACP,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,qBAAqB,EACrB,aAAa,EACd,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EACL,KAAK,OAAO,IAAI,aAAa,EAC7B,KAAK,OAAO,EACZ,KAAK,OAAO,EAIb,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,YAAY,EAElB,MAAM,sCAAsC,CAAA;AAI7C,OAAO,KAAK,EACV,aAAa,EAGb,gBAAgB,EAEhB,OAAO,EAEP,MAAM,EACP,MAAM,YAAY,CAAA;AAUnB,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,MAAM,CAAiB;gBAEnB,cAAc,GAAE,MAAM,GAAG,qBAAqC;IAmB1E,OAAO,CAAC,aAAa;YAkCP,eAAe;YAiCf,qBAAqB;YA0FrB,aAAa;YAYZ,UAAU;YAiFV,gBAAgB;YAcjB,cAAc;IA8C5B;;;;OAIG;IACH,UAAU,CAAC,mBAAmB,SAAS,0BAA0B,GAAG,0BAA0B,EAC5F,MAAM,EAAE,YAAY,CAAC,mBAAmB,CAAC;IAe3C;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAMvC;;;;OAIG;IACH,WAAW,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAC/C;;;;;OAKG;IACH,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAa9D;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQpC;;;OAGG;IACH,cAAc;IAUd;;;;OAIG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAYxD;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO;IAQxB;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,OAAO;IAQxB;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,mBAAmB;IAQhC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,aAAa,CAAC,EAAE,mBAAmB;IASrE;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa;IAQ5B;;;;OAIG;IACH,KAAK,CAAC,cAAc,CAAC,EAAE,KAAK,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC;IAC3D;;;OAGG;IACH,KAAK,CAAC,cAAc,EAAE,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IAClE;;;;OAIG;IACH,KAAK,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IA4B/E;;;;OAIG;IACH,WAAW,CAAC,cAAc,CAAC,EAAE,OAAO;CAGrC"}