import { Changelog, ChangelogEntry, ChangelogSection, ChangelogItem, ChangelogSectionType, ChangelogHeader, ChangelogMetadata } from '../models'; /** * Options for adding an entry. */ interface AddEntryOptions { /** Position to insert (default: 0, at the beginning) */ readonly position?: number | 'start' | 'end'; /** Replace existing entry with same version */ readonly replaceExisting?: boolean; /** Update metadata after adding */ readonly updateMetadata?: boolean; } /** * Adds a new entry to a changelog. * * @param changelog - The changelog to add to * @param entry - The entry to add * @param options - Optional add options * @returns A new changelog with the entry added * * @example Adding a new entry to a changelog * ```ts * const newChangelog = addEntry(changelog, { * version: '1.2.0', * date: '2024-01-15', * unreleased: false, * sections: [...] * }) * ``` */ declare function addEntry(changelog: Changelog, entry: ChangelogEntry, options?: AddEntryOptions): Changelog; /** * Adds or updates an unreleased entry. * * @param changelog - The changelog to add the unreleased entry to * @param sections - Sections to include in the unreleased entry * @returns A new changelog with unreleased entry added/updated * * @example Adding an unreleased entry with sections * ```typescript * const sections = [createChangelogSection('features', 'Added', [item])] * const updated = addUnreleasedEntry(changelog, sections) * // => Changelog with unreleased entry at the top * ``` */ declare function addUnreleasedEntry(changelog: Changelog, sections: readonly ChangelogSection[]): Changelog; /** * Creates a new release entry from the current unreleased entry. * * @param changelog - The changelog containing the unreleased entry * @param version - The version number for the release * @param date - The release date (defaults to today) * @param compareUrl - Optional comparison URL * @returns A new changelog with the unreleased entry converted to a release * * @example Releasing unreleased changes as a new version * ```typescript * const released = releaseUnreleased(changelog, '2.0.0', '2024-03-01') * // Unreleased entry becomes version 2.0.0 with the specified date * ``` */ declare function releaseUnreleased(changelog: Changelog, version: string, date?: string, compareUrl?: string): Changelog; /** * Predicate function for filtering entries. */ type EntryPredicate = (entry: ChangelogEntry, index: number) => boolean; /** * Predicate function for filtering sections. */ type SectionPredicate = (section: ChangelogSection, entry: ChangelogEntry) => boolean; /** * Predicate function for filtering items. */ type ItemPredicate = (item: ChangelogItem, section: ChangelogSection, entry: ChangelogEntry) => boolean; /** * Filters entries using a predicate function. * * @param changelog - The changelog to filter * @param predicate - Function that returns true for entries to keep * @returns A new changelog with filtered entries * * @example Filtering out unreleased entries * ```ts * const filtered = filterEntries(changelog, (entry) => !entry.unreleased) * ``` */ declare function filterEntries(changelog: Changelog, predicate: EntryPredicate): Changelog; /** * Filters entries that have breaking changes. * * @param changelog - The changelog to filter * @returns A new changelog with only entries containing breaking changes * * @example Filtering for breaking changes * ```typescript * const breaking = filterBreakingChanges(changelog) * // Only entries containing breaking changes or items marked as breaking * ``` */ declare function filterBreakingChanges(changelog: Changelog): Changelog; /** * Filters sections within each entry. * * @param changelog - The changelog to filter * @param predicate - Function that returns true for sections to keep * @returns A new changelog with filtered sections * * @example Filtering for user-facing sections * ```typescript * const userFacing = filterSections(changelog, (section) => * ['features', 'fixes', 'breaking'].includes(section.type) * ) * ``` */ declare function filterSections(changelog: Changelog, predicate: SectionPredicate): Changelog; /** * Keeps only specified section types. * * @param changelog - The changelog to filter * @param types - Section types to keep * @returns A new changelog with only specified section types * * @example Filtering to specific section types * ```typescript * const userChanges = filterSectionTypes(changelog, ['features', 'fixes']) * // Only features and fixes sections remain * ``` */ declare function filterSectionTypes(changelog: Changelog, types: readonly ChangelogSectionType[]): Changelog; /** * Filters items within sections. * * @param changelog - The changelog to filter * @param predicate - Function that returns true for items to keep * @returns A new changelog with filtered items * * @example Filtering items with references * ```typescript * const withRefs = filterItems(changelog, (item) => item.references.length > 0) * // Only items with issue/PR references * ``` */ declare function filterItems(changelog: Changelog, predicate: ItemPredicate): Changelog; /** * Filters items by scope. * * @param changelog - The changelog to filter * @param scopes - Scopes to include * @returns A new changelog with only items matching the scopes * * @example Filtering items by scope * ```typescript * const apiChanges = filterByScope(changelog, ['api', 'core']) * // Only items scoped to 'api' or 'core' * ``` */ declare function filterByScope(changelog: Changelog, scopes: readonly string[]): Changelog; /** * Excludes items by scope. * * @param changelog - The changelog to filter * @param scopes - Scopes to exclude * @returns A new changelog without items matching the scopes * * @example Excluding items by scope * ```typescript * const publicChanges = excludeByScope(changelog, ['internal', 'test']) * // Items scoped to 'internal' or 'test' are removed * ``` */ declare function excludeByScope(changelog: Changelog, scopes: readonly string[]): Changelog; /** * Strategy for resolving merge conflicts. */ type MergeStrategy = 'source' | 'target' | 'union' | 'latest'; /** * Options for merging changelogs. */ interface MergeOptions { /** Strategy for conflicting entries (default: 'union') */ readonly entryStrategy?: MergeStrategy; /** Strategy for conflicting sections (default: 'union') */ readonly sectionStrategy?: MergeStrategy; /** Strategy for conflicting items (default: 'union') */ readonly itemStrategy?: MergeStrategy; /** Use source header (default: true) */ readonly useSourceHeader?: boolean; /** Sort entries by version after merge */ readonly sortByVersion?: boolean; /** Remove duplicates */ readonly removeDuplicates?: boolean; } /** * Default merge options. */ declare const DEFAULT_MERGE_OPTIONS: Required; /** * Result of a merge operation. */ interface MergeResult { /** The merged changelog */ readonly changelog: Changelog; /** Statistics about the merge */ readonly stats: MergeStats; } /** * Statistics about a merge operation. */ interface MergeStats { /** Number of entries in result */ readonly totalEntries: number; /** Entries only in source */ readonly sourceOnly: number; /** Entries only in target */ readonly targetOnly: number; /** Entries merged from both */ readonly merged: number; /** Number of conflicts resolved */ readonly conflictsResolved: number; } /** * Merges two changelogs together. * * @param source - The source changelog * @param target - The target changelog * @param options - Optional merge options * @returns The merge result with merged changelog and stats * * @example Merging two changelogs * ```ts * const result = mergeChangelogs(mainChangelog, branchChangelog) * console.log(`Merged ${result.stats.merged} entries`) * ``` */ declare function mergeChangelogs(source: Changelog, target: Changelog, options?: MergeOptions): MergeResult; /** * Appends entries from target to source (no conflict resolution). * * @param source - The base changelog to append to * @param target - The changelog whose entries will be appended * @param position - Where to insert ('start' or 'end') * @returns A new changelog with combined entries * * @example Appending entries to a changelog * ```typescript * const combined = appendChangelog(mainChangelog, newChangelog, 'start') * // newChangelog entries appear before mainChangelog entries * ``` */ declare function appendChangelog(source: Changelog, target: Changelog, position?: 'start' | 'end'): Changelog; /** * Combines multiple changelogs into one. * * @param changelogs - Array of changelogs to combine * @param options - Optional merge options * @returns The combined changelog * * @example Combining multiple changelogs * ```typescript * const unified = combineChangelogs([pkg1Changelog, pkg2Changelog], { * strategy: 'merge-sections', * }) * // All entries from both changelogs merged with conflict resolution * ``` */ declare function combineChangelogs(changelogs: readonly Changelog[], options?: MergeOptions): Changelog; /** * Options for removing an entry. */ interface RemoveEntryOptions { /** Throw error if entry not found (default: true) */ readonly throwIfNotFound?: boolean; } /** * Removes an entry from a changelog by version. * * @param changelog - The changelog to remove from * @param version - The version to remove * @param options - Optional removal options * @returns A new changelog without the specified entry * * @example Removing an entry by version * ```ts * const newChangelog = removeEntry(changelog, '1.0.0') * ``` */ declare function removeEntry(changelog: Changelog, version: string, options?: RemoveEntryOptions): Changelog; /** * Removes multiple entries from a changelog. * * @param changelog - The changelog to remove from * @param versions - The versions to remove * @param options - Optional removal options * @returns A new changelog without the specified entries * * @example Removing multiple entries * ```typescript * const cleaned = removeEntries(changelog, ['0.1.0', '0.2.0']) * // Pre-release versions removed from changelog * ``` */ declare function removeEntries(changelog: Changelog, versions: readonly string[], options?: RemoveEntryOptions): Changelog; /** * Removes the unreleased entry if it exists. * * @param changelog - The changelog to remove the unreleased entry from * @param options - Optional removal options * @returns A new changelog without the unreleased entry * * @example Removing the unreleased entry * ```typescript * const released = removeUnreleased(changelog) * // Changelog without the unreleased entry * * // Silently ignore if not found * const safe = removeUnreleased(changelog, { throwIfNotFound: false }) * ``` */ declare function removeUnreleased(changelog: Changelog, options?: RemoveEntryOptions): Changelog; /** * Options for removing a section or item. */ interface RemoveSectionOptions { /** Throw error if section/item not found (default: true) */ readonly throwIfNotFound?: boolean; } /** * Removes a section from an entry. * * @param changelog - The changelog containing the entry to modify * @param version - The version of the entry to modify * @param sectionType - The section type to remove * @param options - Optional removal options * @returns A new changelog without the specified section * * @example Removing a deprecated section * ```typescript * const updated = removeSection(changelog, '1.0.0', 'deprecated') * // Version 1.0.0 no longer has a deprecated section * ``` */ declare function removeSection(changelog: Changelog, version: string, sectionType: string, options?: RemoveSectionOptions): Changelog; /** * Removes an item from an entry by description. * * @param changelog - The changelog containing the entry to modify * @param version - The version of the entry to modify * @param sectionType - The section type containing the item * @param itemDescription - The description of the item to remove * @param options - Optional removal options * @returns A new changelog without the specified item * * @example Removing a specific item from a section * ```typescript * const updated = removeItem(changelog, '1.0.0', 'features', 'Add dark mode') * // The 'Add dark mode' item is removed from features in 1.0.0 * ``` */ declare function removeItem(changelog: Changelog, version: string, sectionType: string, itemDescription: string, options?: RemoveSectionOptions): Changelog; /** * Removes empty sections from all entries. * * @param changelog - The changelog to remove empty sections from * @returns A new changelog with empty sections removed * * @example Removing empty sections from all entries * ```typescript * const cleaned = removeEmptySections(changelog) * // Sections with no items are removed from all entries * ``` */ declare function removeEmptySections(changelog: Changelog): Changelog; /** * Removes empty entries (entries with no sections or only empty sections). * * @param changelog - The changelog to remove empty entries from * @param keepUnreleased - Whether to keep an empty unreleased entry (default: true) * @returns A new changelog with empty entries removed * * @example Removing empty entries * ```typescript * const cleaned = removeEmptyEntries(changelog) * // Entries with no content are removed (unreleased kept by default) * * const strict = removeEmptyEntries(changelog, false) * // Even empty unreleased entry is removed * ``` */ declare function removeEmptyEntries(changelog: Changelog, keepUnreleased?: boolean): Changelog; /** * Transformation function for entries. */ type EntryTransformer = (entry: ChangelogEntry, index: number) => ChangelogEntry; /** * Transformation function for sections. */ type SectionTransformer = (section: ChangelogSection, entry: ChangelogEntry) => ChangelogSection; /** * Transformation function for items. */ type ItemTransformer = (item: ChangelogItem, section: ChangelogSection, entry: ChangelogEntry) => ChangelogItem; /** * Transforms all entries in a changelog. * * @param changelog - The changelog to transform * @param transformer - Function to transform each entry * @returns A new changelog with transformed entries * * @example Transforming all entries * ```ts * const transformed = transformEntries(changelog, (entry) => ({ * ...entry, * date: entry.date?.toUpperCase() * })) * ``` */ declare function transformEntries(changelog: Changelog, transformer: EntryTransformer): Changelog; /** * Transforms all sections in all entries. * * @param changelog - The changelog to transform * @param transformer - Function to transform each section * @returns A new changelog with transformed sections * * @example Uppercasing section headings * ```typescript * const renamed = transformSections(changelog, (section) => ({ * ...section, * heading: section.heading.toUpperCase(), * })) * ``` */ declare function transformSections(changelog: Changelog, transformer: SectionTransformer): Changelog; /** * Transforms all items in all sections. * * @param changelog - The changelog to transform * @param transformer - Function to transform each item * @returns A new changelog with transformed items * * @example Prefixing item descriptions with scope * ```typescript * const prefixed = transformItems(changelog, (item) => ({ * ...item, * description: `[${item.scope || 'misc'}] ${item.description}`, * })) * ``` */ declare function transformItems(changelog: Changelog, transformer: ItemTransformer): Changelog; /** * Updates the header of a changelog. * * @param changelog - The changelog to update * @param updates - Partial header updates * @returns A new changelog with updated header * * @example Updating the changelog header * ```typescript * const updated = updateHeader(changelog, { title: '# Release Notes' }) * ``` */ declare function updateHeader(changelog: Changelog, updates: Partial): Changelog; /** * Updates the metadata of a changelog. * * @param changelog - The changelog to update * @param updates - Partial metadata updates * @returns A new changelog with updated metadata * * @example Updating changelog metadata * ```typescript * const updated = updateMetadata(changelog, { repositoryUrl: 'https://github.com/org/repo' }) * ``` */ declare function updateMetadata(changelog: Changelog, updates: Partial): Changelog; /** * Updates a specific entry by version. * * @param changelog - The changelog to update * @param version - Version of entry to update * @param updates - Partial entry updates or transformer function * @returns A new changelog with updated entry * * @example Updating a specific entry * ```typescript * const updated = updateEntry(changelog, '1.0.0', { date: '2024-01-15' }) * * // Or with transformer function * const modified = updateEntry(changelog, '1.0.0', (entry) => ({ * ...entry, * compareUrl: `https://github.com/org/repo/compare/v0.9.0...v${entry.version}`, * })) * ``` */ declare function updateEntry(changelog: Changelog, version: string, updates: Partial | ((entry: ChangelogEntry) => ChangelogEntry)): Changelog; /** * Sorts entries by version (descending - newest first). * * @param changelog - The changelog to sort * @returns A new changelog with sorted entries * * @example Sorting changelog entries by version * ```typescript * const sorted = sortEntries(changelog) * // Entries ordered: Unreleased, 2.0.0, 1.1.0, 1.0.0, ... * ``` */ declare function sortEntries(changelog: Changelog): Changelog; /** * Sorts entries by date (newest first). * * @param changelog - The changelog to sort * @returns A new changelog with sorted entries * * @example Sorting entries by date * ```typescript * const sorted = sortEntriesByDate(changelog) * // Entries ordered by release date, most recent first * ``` */ declare function sortEntriesByDate(changelog: Changelog): Changelog; /** * Reverses the order of entries. * * @param changelog - The changelog to reverse * @returns A new changelog with reversed entries * * @example Reversing entry order * ```typescript * const reversed = reverseEntries(changelog) * // Oldest entries now appear first * ``` */ declare function reverseEntries(changelog: Changelog): Changelog; /** * Sorts sections within each entry by a specified order. * * @param changelog - The changelog to sort * @param order - Optional custom section order (defaults to standard order) * @returns A new changelog with sorted sections * * @example Sorting sections within entries * ```typescript * const sorted = sortSections(changelog) * // Sections in each entry follow: breaking, features, fixes, ... * * const custom = sortSections(changelog, ['fixes', 'features', 'breaking']) * // Custom ordering: fixes first, then features, then breaking * ``` */ declare function sortSections(changelog: Changelog, order?: readonly ChangelogSectionType[]): Changelog; /** * Normalizes section headings to standard format. * * @param changelog - The changelog to normalize * @returns A new changelog with normalized section headings * * @example Normalizing section headings * ```typescript * const normalized = normalizeSectionHeadings(changelog) * // 'New Features' becomes 'Added', 'Bug Fixes' becomes 'Fixed', etc. * ``` */ declare function normalizeSectionHeadings(changelog: Changelog): Changelog; /** * Removes duplicate items across all sections. * * @param changelog - The changelog to deduplicate * @returns A new changelog without duplicate items * * @example Deduplicating items across sections * ```typescript * const deduped = deduplicateItems(changelog) * // Duplicate items (same scope:description) are removed * ``` */ declare function deduplicateItems(changelog: Changelog): Changelog; /** * Compacts a changelog by removing empty sections and entries. * * @param changelog - The changelog to compact * @param keepUnreleased - Whether to keep empty unreleased entry (default: true) * @returns A new compacted changelog * * @example Compacting a changelog * ```typescript * const compacted = compact(changelog) * // Empty sections and entries removed (unreleased kept) * * const strict = compact(changelog, false) * // Even empty unreleased entry is removed * ``` */ declare function compact(changelog: Changelog, keepUnreleased?: boolean): Changelog; /** * Strips metadata from a changelog. * * @param changelog - The changelog to strip * @returns A new changelog with minimal metadata * * @example Stripping metadata from a changelog * ```typescript * const stripped = stripMetadata(changelog) * // Source and warnings removed, only format and isConventional retained * ``` */ declare function stripMetadata(changelog: Changelog): Changelog; /** * Clones a changelog deeply (for modification without affecting original). * * @param changelog - The changelog to clone * @returns A deep copy of the changelog * * @example Cloning a changelog * ```typescript * const copy = cloneChangelog(changelog) * // Independent deep copy, safe to mutate * ``` */ declare function cloneChangelog(changelog: Changelog): Changelog; /** * Adds an item to a specific section within an entry. * * @param changelog - The changelog containing the entry to modify * @param version - The version identifier of the entry to update * @param sectionType - Category identifier for grouping changes (e.g., 'features', 'fixes') * @param item - Description of the change with optional scope and metadata * @returns A new changelog with the item added * * @example Adding a feature item to an entry * ```typescript * const item = { description: 'Add dark mode support', scope: 'ui' } * const updated = addItemToEntry(changelog, '1.2.0', 'features', item) * // Item added to the features section of version 1.2.0 * ``` */ declare function addItemToEntry(changelog: Changelog, version: string, sectionType: string, item: ChangelogItem): Changelog; /** * Filters entries by version range using semver. * * @param changelog - The changelog to filter * @param range - Semver range string (e.g., '>=1.0.0 <2.0.0') * @returns A new changelog with entries matching the range * * @example Filtering by semver range * ```ts * const majors = filterByVersionRange(changelog, '>=1.0.0 <2.0.0') * ``` */ declare function filterByVersionRange(changelog: Changelog, range: string): Changelog; /** * Filters entries from a start version. * * @param changelog - The changelog to filter * @param startVersion - The minimum version (inclusive) * @returns A new changelog with entries >= startVersion * * @example Filtering from a start version * ```typescript * const recent = filterFromVersion(changelog, '2.0.0') * // Only entries for version 2.0.0 and later * ``` */ declare function filterFromVersion(changelog: Changelog, startVersion: string): Changelog; /** * Filters entries up to an end version. * * @param changelog - The changelog to apply the version filter to * @param endVersion - The maximum version (inclusive) * @returns A new changelog with entries <= endVersion * * @example Filtering to an end version * ```typescript * const legacy = filterToVersion(changelog, '1.9.9') * // Only entries for versions up to 1.9.9 * ``` */ declare function filterToVersion(changelog: Changelog, endVersion: string): Changelog; /** * Gets entries within a version range (inclusive). * * @param changelog - The changelog to filter * @param startVersion - The minimum version (inclusive) * @param endVersion - The maximum version (inclusive) * @returns A new changelog with entries in the range * * @example Filtering entries within a version range * ```typescript * const range = filterVersionRange(changelog, '1.5.0', '2.0.0') * // Entries from 1.5.0 through 2.0.0 * ``` */ declare function filterVersionRange(changelog: Changelog, startVersion: string, endVersion: string): Changelog; /** * Gets the N most recent entries. * * @param changelog - The changelog to filter * @param count - Number of entries to keep * @param includeUnreleased - Whether to include unreleased in count (default: false) * @returns A new changelog with only the most recent entries * * @example Getting the most recent entries * ```typescript * const latest = filterRecentEntries(changelog, 5) * // Last 5 released versions (plus unreleased if present) * ``` */ declare function filterRecentEntries(changelog: Changelog, count: number, includeUnreleased?: boolean): Changelog; /** * Filters entries by release date. * * @param changelog - The changelog to filter * @param startDate - Start date (inclusive, ISO format) * @param endDate - End date (inclusive, ISO format) * @returns A new changelog with entries in the date range * * @example Filtering entries by date range * ```typescript * const q1 = filterByDateRange(changelog, '2024-01-01', '2024-03-31') * // Entries released in Q1 2024 * ``` */ declare function filterByDateRange(changelog: Changelog, startDate?: string, endDate?: string): Changelog; export { DEFAULT_MERGE_OPTIONS, addEntry, addItemToEntry, addUnreleasedEntry, appendChangelog, cloneChangelog, combineChangelogs, compact, deduplicateItems, excludeByScope, filterBreakingChanges, filterByDateRange, filterByScope, filterByVersionRange, filterEntries, filterFromVersion, filterItems, filterRecentEntries, filterSectionTypes, filterSections, filterToVersion, filterVersionRange, mergeChangelogs, normalizeSectionHeadings, releaseUnreleased, removeEmptyEntries, removeEmptySections, removeEntries, removeEntry, removeItem, removeSection, removeUnreleased, reverseEntries, sortEntries, sortEntriesByDate, sortSections, stripMetadata, transformEntries, transformItems, transformSections, updateEntry, updateHeader, updateMetadata }; export type { AddEntryOptions, EntryPredicate, EntryTransformer, ItemPredicate, ItemTransformer, MergeOptions, MergeResult, MergeStats, MergeStrategy, RemoveEntryOptions, RemoveSectionOptions, SectionPredicate, SectionTransformer };