@withstudiocms/internal_helpers/dist/utils/loadChangelog.d.ts

Internal helper utilities for StudioCMS

import type { List } from 'mdast';
/**
 * Represents a changelog entry for a specific version.
 *
 * @property version - The semantic version string (e.g., "1.2.3").
 * @property changes - An object mapping each semantic version category to a list of changes.
 * @property includes - A set of strings indicating included features or modules for this version.
 */
export type Version = {
    version: string;
    changes: {
        [key in SemverCategory]: List;
    };
    includes: Set<string>;
};
/**
 * Represents the changelog for a package, including its name and a list of versions.
 *
 * @property packageName - The name of the package.
 * @property versions - An array of version objects associated with the package.
 */
export type Changelog = {
    packageName: string;
    versions: Version[];
};
/**
 * Defines the semantic versioning categories used to classify changes.
 * - `major`: Indicates breaking changes.
 * - `minor`: Indicates backward-compatible feature additions.
 * - `patch`: Indicates backward-compatible bug fixes.
 */
export declare const semverCategories: readonly ["major", "minor", "patch"];
/**
 * Represents a semantic versioning category, derived from the `semverCategories` array.
 *
 * This type is useful for constraining values to valid semantic version categories.
 */
export type SemverCategory = (typeof semverCategories)[number];
/**
 * Represents the raw source of a changelog.
 *
 * @property raw - The raw changelog content as a string.
 */
type RawChangelogSrc = {
    raw: string;
};
/**
 * Represents a changelog to be loaded from a file.
 *
 * @property path - The file system path to the changelog file.
 */
type FromFileChangelog = {
    path: string;
};
/**
 * Represents the source of a changelog, which can either be a raw changelog source
 * or a changelog loaded from a file.
 *
 * @see RawChangelogSrc
 * @see FromFileChangelog
 */
export type ChangeLogSrc = RawChangelogSrc | FromFileChangelog;
/**
 * Loads and parses a changelog from either a file path or a raw markdown string.
 *
 * - Reads the changelog markdown content from the provided source.
 * - Converts GitHub usernames in "Thanks ..." sentences to markdown links.
 * - Parses the markdown into an AST and extracts structured changelog information:
 *   - The package name (from the first-level heading).
 *   - Versions (from second-level headings).
 *   - Semantic version categories (from third-level headings).
 *   - Changes for each category, filtering out package references and dependency updates.
 *   - Tracks included package references for each version.
 *
 * Throws errors if the markdown structure does not match the expected format.
 *
 * @param src - The source of the changelog, either a file path or raw markdown.
 * @returns The parsed changelog object containing package name, versions, and categorized changes.
 * @throws {Error} If the markdown structure is unexpected or invalid.
 */
export declare function loadChangelog(src: ChangeLogSrc): Changelog;
export {};