fork-version 1.7.6 → 2.0.1

package/dist/index.d.cts

@@ -1,6 +1,69 @@
 import { z } from 'zod';
 import { ReleaseType } from 'semver';
 
+interface ParserOptions {
+    /**
+     * Pattern to match commit subjects
+     * - Expected capture groups: `type` `title`
+     * - Optional capture groups: `scope`, `breakingChange`
+     */
+    subjectPattern: RegExp | undefined;
+    /**
+     * Pattern to match merge commits
+     * - Expected capture groups: `id`, `source`
+     */
+    mergePattern: RegExp | undefined;
+    /**
+     * Pattern to match revert commits
+     * - Expected capture groups: `subject`, `hash`
+     */
+    revertPattern: RegExp | undefined;
+    /**
+     * Pattern to match commented out lines which will be trimmed
+     */
+    commentPattern: RegExp | undefined;
+    /**
+     * Pattern to match mentions
+     * - Expected capture groups: `username`
+     */
+    mentionPattern: RegExp | undefined;
+    /**
+     * List of action labels to match reference sections
+     * @default
+     * ["close", "closes", "closed", "fix", "fixes", "fixed", "resolve", "resolves", "resolved"]
+     */
+    referenceActions?: string[];
+    /**
+     * Pattern to match reference sections
+     * - Expected capture groups: `action`, `reference`
+     */
+    referenceActionPattern: RegExp | undefined;
+    /**
+     * List of issue prefixes to match issue ids
+     * @default
+     * ["#"]
+     */
+    issuePrefixes?: string[];
+    /**
+     * Pattern to match issue references
+     * - Expected capture groups: `repository`, `prefix`, `issue`
+     */
+    issuePattern: RegExp | undefined;
+    /**
+     * List of keywords to match note titles
+     * @default
+     * ["BREAKING CHANGE", "BREAKING-CHANGE"]
+     */
+    noteKeywords?: string[];
+    /**
+     * Pattern to match note sections
+     * - Expected capture groups: `title`
+     * - Optional capture groups: `text`
+     */
+    notePattern: RegExp | undefined;
+}
+declare function createParserOptions(userOptions?: Partial<ParserOptions>): ParserOptions;
+
 declare const ForkConfigSchema: z.ZodObject<{
     /**
      * If set, Fork-Version will print the current version and exit.
@@ -145,6 +208,7 @@ declare const ForkConfigSchema: z.ZodObject<{
     sign: z.ZodBoolean;
     /**
      * If true, git will run user defined git hooks before committing.
+     * @see {@link https://git-scm.com/docs/githooks Git - Git Hooks}
      * @default false
      */
     verify: z.ZodBoolean;
@@ -208,30 +272,30 @@ declare const ForkConfigSchema: z.ZodObject<{
         releaseCommitMessageFormat: z.ZodOptional<z.ZodString>;
         issuePrefixes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
+        commitUrlFormat?: string | undefined;
+        compareUrlFormat?: string | undefined;
+        issueUrlFormat?: string | undefined;
+        userUrlFormat?: string | undefined;
+        releaseCommitMessageFormat?: string | undefined;
         types?: {
             type: string;
             scope?: string | undefined;
             section?: string | undefined;
             hidden?: boolean | undefined;
         }[] | undefined;
+        issuePrefixes?: string[] | undefined;
+    }, {
         commitUrlFormat?: string | undefined;
         compareUrlFormat?: string | undefined;
         issueUrlFormat?: string | undefined;
         userUrlFormat?: string | undefined;
         releaseCommitMessageFormat?: string | undefined;
-        issuePrefixes?: string[] | undefined;
-    }, {
         types?: {
             type: string;
             scope?: string | undefined;
             section?: string | undefined;
             hidden?: boolean | undefined;
         }[] | undefined;
-        commitUrlFormat?: string | undefined;
-        compareUrlFormat?: string | undefined;
-        issueUrlFormat?: string | undefined;
-        userUrlFormat?: string | undefined;
-        releaseCommitMessageFormat?: string | undefined;
         issuePrefixes?: string[] | undefined;
     }>;
     /**
@@ -241,8 +305,8 @@ declare const ForkConfigSchema: z.ZodObject<{
     releaseMessageSuffix: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     inspectVersion: boolean;
-    path: string;
     files: string[];
+    path: string;
     changelog: string;
     header: string;
     tagPrefix: string;
@@ -260,17 +324,17 @@ declare const ForkConfigSchema: z.ZodObject<{
     skipCommit: boolean;
     skipTag: boolean;
     changelogPresetConfig: {
+        commitUrlFormat?: string | undefined;
+        compareUrlFormat?: string | undefined;
+        issueUrlFormat?: string | undefined;
+        userUrlFormat?: string | undefined;
+        releaseCommitMessageFormat?: string | undefined;
         types?: {
             type: string;
             scope?: string | undefined;
             section?: string | undefined;
             hidden?: boolean | undefined;
         }[] | undefined;
-        commitUrlFormat?: string | undefined;
-        compareUrlFormat?: string | undefined;
-        issueUrlFormat?: string | undefined;
-        userUrlFormat?: string | undefined;
-        releaseCommitMessageFormat?: string | undefined;
         issuePrefixes?: string[] | undefined;
     };
     glob?: string | undefined;
@@ -281,8 +345,8 @@ declare const ForkConfigSchema: z.ZodObject<{
     releaseMessageSuffix?: string | undefined;
 }, {
     inspectVersion: boolean;
-    path: string;
     files: string[];
+    path: string;
     changelog: string;
     header: string;
     tagPrefix: string;
@@ -300,17 +364,17 @@ declare const ForkConfigSchema: z.ZodObject<{
     skipCommit: boolean;
     skipTag: boolean;
     changelogPresetConfig: {
+        commitUrlFormat?: string | undefined;
+        compareUrlFormat?: string | undefined;
+        issueUrlFormat?: string | undefined;
+        userUrlFormat?: string | undefined;
+        releaseCommitMessageFormat?: string | undefined;
         types?: {
             type: string;
             scope?: string | undefined;
             section?: string | undefined;
             hidden?: boolean | undefined;
         }[] | undefined;
-        commitUrlFormat?: string | undefined;
-        compareUrlFormat?: string | undefined;
-        issueUrlFormat?: string | undefined;
-        userUrlFormat?: string | undefined;
-        releaseCommitMessageFormat?: string | undefined;
         issuePrefixes?: string[] | undefined;
     };
     glob?: string | undefined;
@@ -324,9 +388,6 @@ declare const ForkConfigSchema: z.ZodObject<{
 type ForkConfig = z.infer<typeof ForkConfigSchema>;
 type Config = Partial<ForkConfig>;
 
-declare function getUserConfig(): Promise<ForkConfig>;
-declare function defineConfig(config: Config): Config;
-
 declare class Logger {
     private config;
     disableLogs: boolean;
@@ -337,6 +398,376 @@ declare class Logger {
     debug(...messages: any[]): void;
 }
 
+interface CommitMerge {
+    id: string;
+    source: string;
+}
+interface CommitRevert {
+    hash: string;
+    subject: string;
+}
+interface CommitReference {
+    prefix: string;
+    issue: string;
+    action: string | null;
+    owner: string | null;
+    repository: string | null;
+}
+interface CommitNote {
+    title: string;
+    text: string;
+}
+interface Commit {
+    raw: string;
+    subject: string;
+    body: string;
+    hash: string;
+    /**
+     * Committer date in ISO 8601 format
+     * @example
+     * "2024-12-22T17:36:50Z"
+     */
+    date: string;
+    /**
+     * Committer name (respects .mailmap)
+     */
+    name: string;
+    /**
+     * Committer email (respects .mailmap)
+     */
+    email: string;
+    type: string;
+    scope: string;
+    breakingChange: string;
+    title: string;
+    merge: CommitMerge | null;
+    revert: CommitRevert | null;
+    mentions: string[];
+    references: CommitReference[];
+    notes: CommitNote[];
+}
+
+declare class CommitParser {
+    #private;
+    constructor(userOptions?: Partial<ParserOptions>);
+    setLogger(logger: Logger): this;
+    createCommit(): Commit;
+    /**
+     * Parse the raw commit message into its expected parts
+     * - subject
+     * - body
+     * - hash
+     * - date
+     * - name
+     * - email
+     *
+     * @throws {ParserError}
+     */
+    parseRawCommit(rawCommit: string): Commit;
+    /**
+     * Parse the commit subject into its expected parts
+     * - type
+     * - scope (optional)
+     * - breaking change (optional)
+     * - title
+     *
+     * @throws {ParserError}
+     */
+    parseSubject(commit: Commit): boolean;
+    /**
+     * Parse merge information from the commit subject
+     * @example
+     * ```txt
+     * "Merge pull request #123 from fork-version/feature"
+     * ```
+     */
+    parseMerge(commit: Commit): boolean;
+    /**
+     * Parse revert information from the commit body
+     * @example
+     * ```txt
+     * "Revert "feat: initial commit"
+     *
+     * This reverts commit 4a79e9e546b4020d2882b7810dc549fa71960f4f."
+     * ```
+     */
+    parseRevert(commit: Commit): boolean;
+    /**
+     * Search for mentions from the commit line
+     * @example
+     * ```txt
+     * "@fork-version"
+     * ```
+     */
+    parseMentions(line: string, outMentions: Set<string>): boolean;
+    /**
+     * Search for references from the commit line
+     * @example
+     * ```txt
+     * "#1234"
+     * "owner/repo#1234"
+     * ```
+     */
+    parseReferenceParts(referenceText: string, action: string | null): CommitReference[] | undefined;
+    /**
+     * Search for actions and references from the commit line
+     * @example
+     * ```txt
+     * "Closes #1234"
+     * "fixes owner/repo#1234"
+     * ```
+     */
+    parseReferences(line: string, outReferences: CommitReference[]): boolean;
+    /**
+     * Search for notes from the commit line
+     * @example
+     * ```txt
+     * "BREAKING CHANGE: this is a breaking change"
+     * ```
+     */
+    parseNotes(line: string, outNotes: CommitNote[]): boolean;
+    /**
+     * Parse the raw commit for mentions, references and notes
+     */
+    parseRawLines(commit: Commit): void;
+    /**
+     * Parse a commit log with the following format separated by new line characters:
+     * ```txt
+     * refactor: add test file
+     * Add a test file to the project
+     * 4ef2c86d393a9660aa9f753144256b1f200c16bd
+     * 2024-12-22T17:36:50Z
+     * Fork Version
+     * fork-version@example.com
+     * ```
+     *
+     * @example
+     * ```ts
+     * parse("refactor: add test file\nAdd a test file to the project\n4ef2c86d393a9660aa9f753144256b1f200c16bd\n2024-12-22T17:36:50Z\nFork Version\nfork-version@example.com");
+     * ```
+     *
+     * The expected input value can be generated by running the following command:
+     * ```sh
+     * git log --format="%s%n%b%n%H%n%cI%n%cN%n%cE%n"
+     * ```
+     * @see {@link https://git-scm.com/docs/pretty-formats|Git Pretty Format Documentation}
+     */
+    parse(rawCommit: string): Commit | undefined;
+}
+
+/**
+ * Filter out revert commits and their corresponding reverted commits,
+ * this function expects the input to be sorted by date in descending order
+ * from the most recent to the oldest commit.
+ *
+ * @example
+ * ```ts
+ * const commits: Commit[] = [...];
+ * const filteredCommits = filterRevertedCommits(commits);
+ * ```
+ */
+declare function filterRevertedCommits(parsedCommits: Commit[]): Commit[];
+
+/**
+ * [Fork-Version - Config Properties](https://github.com/eglavin/fork-version/blob/main/README.md#config-properties)
+ */
+declare function defineConfig(config: Config): Config;
+
+declare function getCliArguments(): {
+    inspectVersion: boolean | undefined;
+    files: string[] | undefined;
+    glob: string | undefined;
+    path: string | undefined;
+    changelog: string | undefined;
+    header: string | undefined;
+    tagPrefix: string | undefined;
+    preRelease: boolean | undefined;
+    preReleaseTag: string | undefined;
+    currentVersion: string | undefined;
+    nextVersion: string | undefined;
+    releaseAs: string | undefined;
+    allowMultipleVersions: boolean | undefined;
+    commitAll: boolean | undefined;
+    changelogAll: boolean | undefined;
+    debug: boolean | undefined;
+    dryRun: boolean | undefined;
+    silent: boolean | undefined;
+    gitTagFallback: boolean | undefined;
+    sign: boolean | undefined;
+    verify: boolean | undefined;
+    skipBump: boolean | undefined;
+    skipChangelog: boolean | undefined;
+    skipCommit: boolean | undefined;
+    skipTag: boolean | undefined;
+    commitUrlFormat: string | undefined;
+    compareUrlFormat: string | undefined;
+    issueUrlFormat: string | undefined;
+    userUrlFormat: string | undefined;
+    releaseCommitMessageFormat: string | undefined;
+    releaseMessageSuffix: string | undefined;
+} & Record<string, unknown>;
+
+declare function getUserConfig(cliArguments: Partial<ReturnType<typeof getCliArguments>>): Promise<ForkConfig>;
+
+declare class Git {
+    #private;
+    private config;
+    constructor(config: Pick<ForkConfig, "path" | "dryRun">);
+    /**
+     * Add file contents to the index
+     *
+     * [git-add Documentation](https://git-scm.com/docs/git-add)
+     *
+     * @example
+     * ```ts
+     * await git.add("CHANGELOG.md");
+     * ```
+     */
+    add(...args: (string | undefined)[]): Promise<string>;
+    /**
+     * Record changes to the repository
+     *
+     * [git-commit Documentation](https://git-scm.com/docs/git-commit)
+     *
+     * @example
+     * ```ts
+     * await git.commit("--message", "chore(release): 1.2.3");
+     * ```
+     */
+    commit(...args: (string | undefined)[]): Promise<string>;
+    /**
+     * Create, list, delete or verify a tag object
+     *
+     * [git-tag Documentation](https://git-scm.com/docs/git-tag)
+     *
+     * @example
+     * ```ts
+     * await git.tag("--annotate", "v1.2.3", "--message", "chore(release): 1.2.3");
+     * ```
+     */
+    tag(...args: (string | undefined)[]): Promise<string>;
+    /**
+     * Show commit logs
+     *
+     * - [git-log Documentation](https://git-scm.com/docs/git-log)
+     * - [pretty-formats Documentation](https://git-scm.com/docs/pretty-formats)
+     *
+     * @example
+     * ```ts
+     * await git.log("--oneline");
+     * ```
+     */
+    log(...args: (string | undefined)[]): Promise<string>;
+    /**
+     * Check if a file is ignored by git
+     *
+     * [git-check-ignore Documentation](https://git-scm.com/docs/git-check-ignore)
+     *
+     * @example
+     * ```ts
+     * await git.isIgnored("src/my-file.txt");
+     * ```
+     */
+    isIgnored(file: string): Promise<boolean>;
+    /**
+     * Get the name of the current branch
+     *
+     * [git-rev-parse Documentation](https://git-scm.com/docs/git-rev-parse)
+     *
+     * @example
+     * ```ts
+     * await git.getBranchName(); // "main"
+     * ```
+     */
+    getBranchName(): Promise<string>;
+    /**
+     * Get the URL of the remote repository
+     *
+     * [git-config Documentation](https://git-scm.com/docs/git-config)
+     *
+     * @example
+     * ```ts
+     * await git.getRemoteUrl(); // "https://github.com/eglavin/fork-version"
+     * ```
+     */
+    getRemoteUrl(): Promise<string>;
+    /**
+     * `getTags` returns valid semver version tags in order of the commit history
+     *
+     * Using `git log` to get the commit history, we then parse the tags from the
+     * commit details which is expected to be in the following format:
+     * ```txt
+     * commit 3841b1d05750d42197fe958e3d8e06df378a842d (HEAD -> main, tag: v1.0.2, tag: v1.0.1, tag: v1.0.0)
+     * Author: Username <username@example.com>
+     * Date:   Sat Nov 9 15:00:00 2024 +0000
+     *
+     *     chore(release): v1.0.0
+     * ```
+     *
+     * - [Functionality extracted from the conventional-changelog - git-semver-tags project](https://github.com/conventional-changelog/conventional-changelog/blob/fac8045242099c016f5f3905e54e02b7d466bd7b/packages/git-semver-tags/index.js)
+     * - [conventional-changelog git-semver-tags MIT Licence](https://github.com/conventional-changelog/conventional-changelog/blob/fac8045242099c016f5f3905e54e02b7d466bd7b/packages/git-semver-tags/LICENSE.md)
+     *
+     * @example
+     * ```ts
+     * await git.getTags("v"); // ["v1.0.2", "v1.0.1", "v1.0.0"]
+     * ```
+     */
+    getTags(tagPrefix: string | undefined): Promise<string[]>;
+    /**
+     * Returns the latest git tag based on commit date
+     *
+     * @example
+     * ```ts
+     * await git.getMostRecentTag("v"); // "1.2.3"
+     * ```
+     */
+    getMostRecentTag(tagPrefix: string | undefined): Promise<string | undefined>;
+    /**
+     * Get cleaned semver tags, with any tag prefix's removed
+     *
+     * @example
+     * ```ts
+     * await git.getCleanedTags("v"); // ["1.2.3", "1.2.2", "1.2.1"]
+     * ```
+     */
+    getCleanedTags(tagPrefix: string | undefined): Promise<string[]>;
+    /**
+     * Get the highest semver version from git tags. This will return the highest
+     * semver version found for the given tag prefix, regardless of the commit date.
+     *
+     * @example
+     * ```ts
+     * await git.getHighestSemverVersionFromTags("v"); // "1.2.3"
+     * ```
+     */
+    getHighestSemverVersionFromTags(tagPrefix: string | undefined): Promise<string | undefined>;
+    /**
+     * Get commit history in a parsable format
+     *
+     * An array of strings with commit details is returned in the following format:
+     * ```txt
+     * subject
+     * body
+     * hash
+     * committer date
+     * committer name
+     * committer email
+     * ```
+     *
+     * @example
+     * ```ts
+     * await git.getCommits("v1.0.0", "HEAD", "src/utils");
+     * ```
+     */
+    getCommits(from?: string, to?: string, ...paths: string[]): Promise<string[]>;
+}
+
+interface CommitsSinceTag {
+    latestTag: string | undefined;
+    commits: Commit[];
+}
+declare function getCommitsSinceTag(config: ForkConfig, logger: Logger, git: Git): Promise<CommitsSinceTag>;
+
 interface FileState {
     name: string;
     path: string;
@@ -355,6 +786,7 @@ declare class FileManager {
     private YAMLPackage;
     private PlainText;
     private MSBuildProject;
+    private ARMBicep;
     constructor(config: ForkConfig, logger: Logger);
     /**
      * Get the state from the given file name.
@@ -384,36 +816,6 @@ declare class FileManager {
     write(fileState: FileState, newVersion: string): void;
 }
 
-declare class Git {
-    private config;
-    constructor(config: Pick<ForkConfig, "path" | "dryRun">);
-    private execGit;
-    add(...args: (string | undefined)[]): Promise<string>;
-    commit(...args: (string | undefined)[]): Promise<string>;
-    tag(...args: (string | undefined)[]): Promise<string>;
-    isIgnored(file: string): Promise<boolean>;
-    getCurrentBranchName(): Promise<string>;
-    /**
-     * `getTags` returns valid semver version tags in order of the commit history.
-     *
-     * Using `git log` to get the commit history, we then parse the tags from the
-     * commit details which is expected to be in the following format:
-     * @example
-     * ```txt
-     * commit 3841b1d05750d42197fe958e3d8e06df378a842d (HEAD -> main, tag: 1.0.2)
-     * Author: Username <username@example.com>
-     * Date:   Sat Nov 9 15:00:00 2024 +0000
-     *
-     *     chore(release): 1.2.3
-     * ```
-     *
-     * - [Functionality extracted from the conventional-changelog - git-semver-tags project](https://github.com/conventional-changelog/conventional-changelog/blob/fac8045242099c016f5f3905e54e02b7d466bd7b/packages/git-semver-tags/index.js)
-     * - [conventional-changelog git-semver-tags MIT Licence](https://github.com/conventional-changelog/conventional-changelog/blob/fac8045242099c016f5f3905e54e02b7d466bd7b/packages/git-semver-tags/LICENSE.md)
-     */
-    getTags(tagPrefix: string | undefined): Promise<string[]>;
-    getLatestTag(tagPrefix: string | undefined): Promise<string>;
-}
-
 interface CurrentVersion {
     version: string;
     files: FileState[];
@@ -421,12 +823,15 @@ interface CurrentVersion {
 declare function getCurrentVersion(config: ForkConfig, logger: Logger, git: Git, fileManager: FileManager, filesToUpdate: string[]): Promise<CurrentVersion>;
 interface NextVersion {
     version: string;
-    level?: number;
-    preMajor?: boolean;
-    reason?: string;
     releaseType?: ReleaseType;
+    preMajor?: boolean;
+    changes?: {
+        major: number;
+        minor: number;
+        patch: number;
+    };
 }
-declare function getNextVersion(config: ForkConfig, logger: Logger, currentVersion: string): Promise<NextVersion>;
+declare function getNextVersion(config: ForkConfig, logger: Logger, commits: Commit[], currentVersion: string): Promise<NextVersion>;
 
 declare function updateChangelog(config: ForkConfig, logger: Logger, nextVersion: string): Promise<void>;
 
@@ -434,4 +839,4 @@ declare function commitChanges(config: ForkConfig, logger: Logger, git: Git, fil
 
 declare function tagChanges(config: ForkConfig, logger: Logger, git: Git, nextVersion: string): Promise<void>;
 
-export { type Config, type CurrentVersion, FileManager, type FileState, type ForkConfig, ForkConfigSchema, type IFileManager, Logger, type NextVersion, commitChanges, defineConfig, getCurrentVersion, getNextVersion, getUserConfig, tagChanges, updateChangelog };
+export { type Commit, type CommitMerge, type CommitNote, CommitParser, type CommitReference, type CommitRevert, type CommitsSinceTag, type Config, type CurrentVersion, FileManager, type FileState, type ForkConfig, ForkConfigSchema, Git, type IFileManager, Logger, type NextVersion, type ParserOptions, commitChanges, createParserOptions, defineConfig, filterRevertedCommits, getCommitsSinceTag, getCurrentVersion, getNextVersion, getUserConfig, tagChanges, updateChangelog };