@hyperfrontend/versioning 0.1.0

package/flow/presets/index.cjs.js

@@ -0,0 +1,3903 @@
+'use strict';
+
+/**
+ * Creates a version flow.
+ *
+ * @param id - Flow identifier
+ * @param name - Human-readable flow name
+ * @param steps - Ordered steps to execute
+ * @param options - Optional flow configuration
+ * @returns A VersionFlow object
+ *
+ * @example
+ * ```typescript
+ * const myFlow = createFlow(
+ *   'custom',
+ *   'Custom Release Flow',
+ *   [fetchStep, analyzeStep, bumpStep],
+ *   { description: 'My custom versioning workflow' }
+ * )
+ * ```
+ */
+function createFlow(id, name, steps, options = {}) {
+    return {
+        id,
+        name,
+        steps,
+        description: options.description,
+        config: options.config ?? {},
+    };
+}
+
+/**
+ * Safe copies of JSON built-in methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/json
+ */
+// Capture references at module initialization time
+const _JSON = globalThis.JSON;
+/**
+ * (Safe copy) Converts a JavaScript Object Notation (JSON) string into an object.
+ */
+const parse = _JSON.parse;
+/**
+ * (Safe copy) Converts a JavaScript value to a JavaScript Object Notation (JSON) string.
+ */
+const stringify = _JSON.stringify;
+
+/**
+ * Creates a flow step.
+ *
+ * @param id - Unique step identifier
+ * @param name - Human-readable step name
+ * @param execute - Step executor function
+ * @param options - Optional step configuration
+ * @returns A FlowStep object
+ *
+ * @example
+ * ```typescript
+ * const fetchStep = createStep(
+ *   'fetch-registry',
+ *   'Fetch Registry Version',
+ *   async (ctx) => {
+ *     const version = await ctx.registry.getLatestVersion(ctx.packageName)
+ *     return {
+ *       status: 'success',
+ *       stateUpdates: { publishedVersion: version },
+ *       message: `Found published version: ${version}`
+ *     }
+ *   }
+ * )
+ * ```
+ */
+function createStep(id, name, execute, options = {}) {
+    return {
+        id,
+        name,
+        execute,
+        description: options.description,
+        skipIf: options.skipIf,
+        continueOnError: options.continueOnError,
+        dependsOn: options.dependsOn,
+    };
+}
+/**
+ * Creates a skipped step result.
+ *
+ * @param message - Explanation for why the step was skipped
+ * @returns A FlowStepResult with 'skipped' status
+ */
+function createSkippedResult(message) {
+    return {
+        status: 'skipped',
+        message,
+    };
+}
+
+const FETCH_REGISTRY_STEP_ID = 'fetch-registry';
+/**
+ * Creates the fetch-registry step.
+ *
+ * This step:
+ * 1. Queries the registry for the latest published version
+ * 2. Reads the current version from package.json
+ * 3. Determines if this is a first release
+ *
+ * State updates:
+ * - publishedVersion: Latest version on registry (null if not published)
+ * - currentVersion: Version from local package.json
+ * - isFirstRelease: True if never published
+ *
+ * @returns A FlowStep that fetches registry information
+ */
+function createFetchRegistryStep() {
+    return createStep(FETCH_REGISTRY_STEP_ID, 'Fetch Registry Version', async (ctx) => {
+        const { registry, tree, projectRoot, packageName, logger } = ctx;
+        // Read local package.json for current version
+        const packageJsonPath = `${projectRoot}/package.json`;
+        let currentVersion = '0.0.0';
+        try {
+            const content = tree.read(packageJsonPath, 'utf-8');
+            if (content) {
+                const pkg = parse(content);
+                currentVersion = pkg.version ?? '0.0.0';
+            }
+        }
+        catch (error) {
+            logger.warn(`Could not read package.json: ${error}`);
+        }
+        // Query registry for published version
+        let publishedVersion = null;
+        let isFirstRelease = true;
+        try {
+            publishedVersion = await registry.getLatestVersion(packageName);
+            isFirstRelease = publishedVersion === null;
+        }
+        catch (error) {
+            // Package might not exist yet, which is fine
+            logger.debug(`Registry query failed (package may not exist): ${error}`);
+            isFirstRelease = true;
+        }
+        const message = isFirstRelease ? `First release (local: ${currentVersion})` : `Published: ${publishedVersion}, Local: ${currentVersion}`;
+        return {
+            status: 'success',
+            stateUpdates: {
+                publishedVersion,
+                currentVersion,
+                isFirstRelease,
+            },
+            message,
+        };
+    });
+}
+
+/**
+ * Safe copies of Error built-ins via factory functions.
+ *
+ * Since constructors cannot be safely captured via Object.assign, this module
+ * provides factory functions that use Reflect.construct internally.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
+ */
+// Capture references at module initialization time
+const _Error = globalThis.Error;
+const _Reflect$2 = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Error using the captured Error constructor.
+ * Use this instead of `new Error()`.
+ *
+ * @param message - Optional error message.
+ * @param options - Optional error options.
+ * @returns A new Error instance.
+ */
+const createError = (message, options) => _Reflect$2.construct(_Error, [message, options]);
+
+/**
+ * Replaces all occurrences of a character in a string.
+ * Uses character-by-character iteration to avoid regex (ReDoS-safe).
+ *
+ * @param input - The input string
+ * @param target - The character to replace
+ * @param replacement - The replacement character
+ * @returns String with all occurrences replaced
+ */
+function replaceChar(input, target, replacement) {
+    const result = [];
+    for (let i = 0; i < input.length; i++) {
+        result.push(input[i] === target ? replacement : input[i]);
+    }
+    return result.join('');
+}
+/**
+ * Replaces all hyphens with spaces.
+ * Convenience wrapper for normalizing footer keys.
+ *
+ * @param input - The input string
+ * @returns String with hyphens replaced by spaces
+ */
+function hyphenToSpace(input) {
+    return replaceChar(input, '-', ' ');
+}
+
+/**
+ * Parses the body section of a commit message.
+ *
+ * The body starts after the first blank line and continues until
+ * we encounter a footer (key: value or key #value pattern) or end of message.
+ *
+ * @param lines - All lines of the commit message
+ * @param startIndex - Index to start looking for body (after header)
+ * @returns Parsed body or undefined if no body
+ */
+function parseBody(lines, startIndex) {
+    // Skip blank lines to find body start
+    let pos = startIndex;
+    while (pos < lines.length && lines[pos].trim() === '') {
+        pos++;
+    }
+    if (pos >= lines.length) {
+        return undefined;
+    }
+    // If the first non-blank line is a footer, there's no body
+    if (isFooterLine(lines[pos])) {
+        return undefined;
+    }
+    const bodyLines = [];
+    // Collect body lines until we hit a footer or end
+    while (pos < lines.length) {
+        const line = lines[pos];
+        // Check if this line looks like a footer
+        if (isFooterLine(line)) {
+            break;
+        }
+        // Check for blank line followed by a footer
+        if (line.trim() === '' && pos + 1 < lines.length && isFooterLine(lines[pos + 1])) {
+            break;
+        }
+        bodyLines.push(line);
+        pos++;
+    }
+    // Trim trailing blank lines from body
+    while (bodyLines.length > 0 && bodyLines[bodyLines.length - 1].trim() === '') {
+        bodyLines.pop();
+    }
+    if (bodyLines.length === 0) {
+        return undefined;
+    }
+    return {
+        body: bodyLines.join('\n'),
+        endIndex: pos,
+    };
+}
+/**
+ * Checks if a line looks like a footer.
+ *
+ * Footer format:
+ * - key: value
+ * - key #value (for issue references)
+ * - BREAKING CHANGE: description
+ * - BREAKING-CHANGE: description
+ *
+ * @param line - The line to check
+ * @returns True if the line looks like a footer
+ */
+function isFooterLine(line) {
+    if (!line)
+        return false;
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return false;
+    // Check for BREAKING CHANGE or BREAKING-CHANGE
+    if (trimmed.startsWith('BREAKING CHANGE:') || trimmed.startsWith('BREAKING-CHANGE:')) {
+        return true;
+    }
+    // Check for token: value or token #value pattern
+    let pos = 0;
+    // Skip leading whitespace
+    while (pos < trimmed.length && trimmed[pos] === ' ') {
+        pos++;
+    }
+    // Read token (alphanumeric and hyphens)
+    const tokenStart = pos;
+    while (pos < trimmed.length) {
+        const char = trimmed[pos];
+        const code = char.charCodeAt(0);
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 45 // -
+        ) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    // Must have at least one character in token
+    if (pos === tokenStart)
+        return false;
+    // Must be followed by : or space-#
+    if (trimmed[pos] === ':') {
+        return true;
+    }
+    if (trimmed[pos] === ' ' && trimmed[pos + 1] === '#') {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Checks if a footer key indicates a breaking change.
+ *
+ * @param key - The footer key to check
+ * @returns True if the key indicates a breaking change
+ */
+function isBreakingFooterKey(key) {
+    const normalized = hyphenToSpace(key.toUpperCase());
+    return normalized === 'BREAKING CHANGE';
+}
+
+/**
+ * Parses the footer section of a commit message.
+ *
+ * @param lines - All lines of the commit message
+ * @param startIndex - Index where footers start
+ * @returns Parsed footers
+ */
+function parseFooters(lines, startIndex) {
+    const footers = [];
+    let breakingDescription;
+    let pos = startIndex;
+    // Skip blank lines
+    while (pos < lines.length && lines[pos].trim() === '') {
+        pos++;
+    }
+    while (pos < lines.length) {
+        const line = lines[pos];
+        const footer = parseFooterLine(line);
+        if (footer) {
+            footers.push(footer);
+            // Check for breaking change
+            if (isBreakingFooterKey(footer.key)) {
+                breakingDescription = footer.value;
+                // Breaking description may span multiple lines
+                pos++;
+                while (pos < lines.length && !isNewFooter(lines[pos])) {
+                    const nextLine = lines[pos];
+                    if (nextLine.trim() !== '') {
+                        breakingDescription += '\n' + nextLine;
+                    }
+                    pos++;
+                }
+                continue;
+            }
+        }
+        pos++;
+    }
+    return { footers, breakingDescription };
+}
+/**
+ * Parses a single footer line.
+ *
+ * @param line - The line to parse
+ * @returns The parsed CommitFooter or null if not a valid footer
+ */
+function parseFooterLine(line) {
+    if (!line)
+        return null;
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return null;
+    // Check for BREAKING CHANGE or BREAKING-CHANGE
+    if (trimmed.startsWith('BREAKING CHANGE:')) {
+        return {
+            key: 'BREAKING CHANGE',
+            value: trimmed.slice(16).trim(),
+            separator: ':',
+        };
+    }
+    if (trimmed.startsWith('BREAKING-CHANGE:')) {
+        return {
+            key: 'BREAKING-CHANGE',
+            value: trimmed.slice(16).trim(),
+            separator: ':',
+        };
+    }
+    // Parse token: value or token #value
+    let pos = 0;
+    // Read token
+    const tokenStart = pos;
+    while (pos < trimmed.length) {
+        const char = trimmed[pos];
+        const code = char.charCodeAt(0);
+        if ((code >= 97 && code <= 122) || // a-z
+            (code >= 65 && code <= 90) || // A-Z
+            (code >= 48 && code <= 57) || // 0-9
+            code === 45 // -
+        ) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    if (pos === tokenStart)
+        return null;
+    const key = trimmed.slice(tokenStart, pos);
+    // Check separator
+    let separator;
+    let valueStart;
+    if (trimmed[pos] === ':') {
+        separator = ':';
+        valueStart = pos + 1;
+    }
+    else if (trimmed[pos] === ' ' && trimmed[pos + 1] === '#') {
+        separator = ' #';
+        valueStart = pos + 2;
+    }
+    else {
+        return null;
+    }
+    // Skip whitespace after separator (for : case)
+    if (separator === ':') {
+        while (valueStart < trimmed.length && trimmed[valueStart] === ' ') {
+            valueStart++;
+        }
+    }
+    const value = trimmed.slice(valueStart);
+    return { key, value, separator };
+}
+/**
+ * Checks if a line starts a new footer.
+ *
+ * @param line - The line to check
+ * @returns True if the line starts a new footer
+ */
+function isNewFooter(line) {
+    if (!line)
+        return false;
+    return parseFooterLine(line) !== null;
+}
+
+/**
+ * Parses a conventional commit header line.
+ *
+ * @param line - The first line of the commit message
+ * @returns Parsed header with type, scope, subject, and breaking flag
+ */
+function parseHeader$1(line) {
+    let pos = 0;
+    const len = line.length;
+    // Extract type (alphanumeric characters until ( or : or !)
+    const typeStart = pos;
+    while (pos < len) {
+        const char = line[pos];
+        const code = char.charCodeAt(0);
+        // a-z, A-Z, 0-9
+        if ((code >= 97 && code <= 122) || (code >= 65 && code <= 90) || (code >= 48 && code <= 57)) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    const type = line.slice(typeStart, pos).toLowerCase();
+    // Check for scope in parentheses
+    let scope;
+    if (line[pos] === '(') {
+        pos++; // skip (
+        const scopeStart = pos;
+        while (pos < len && line[pos] !== ')') {
+            pos++;
+        }
+        scope = line.slice(scopeStart, pos);
+        if (line[pos] === ')') {
+            pos++; // skip )
+        }
+    }
+    // Check for breaking change indicator (!)
+    const breaking = line[pos] === '!';
+    if (breaking) {
+        pos++;
+    }
+    // Expect colon
+    if (line[pos] === ':') {
+        pos++;
+    }
+    // Skip whitespace after colon
+    while (pos < len && line[pos] === ' ') {
+        pos++;
+    }
+    // Rest is subject
+    const subject = line.slice(pos).trim();
+    return {
+        type,
+        scope,
+        subject,
+        breaking,
+    };
+}
+
+/**
+ * Maximum commit message length (10KB)
+ */
+const MAX_MESSAGE_LENGTH = 10 * 1024;
+/**
+ * Parses a conventional commit message.
+ *
+ * @param message - The complete commit message
+ * @returns Parsed ConventionalCommit object
+ * @throws {Error} If message exceeds maximum length
+ */
+function parseConventionalCommit(message) {
+    if (message.length > MAX_MESSAGE_LENGTH) {
+        throw createError(`Commit message exceeds maximum length of ${MAX_MESSAGE_LENGTH} characters`);
+    }
+    const lines = splitLines(message);
+    if (lines.length === 0) {
+        return {
+            type: '',
+            subject: '',
+            footers: [],
+            breaking: false,
+            raw: message,
+        };
+    }
+    // Parse header (first line)
+    const header = parseHeader$1(lines[0]);
+    // Parse body and footers
+    let body;
+    let footersStartIndex = 1;
+    if (lines.length > 1) {
+        const bodyResult = parseBody(lines, 1);
+        if (bodyResult) {
+            body = bodyResult.body;
+            footersStartIndex = bodyResult.endIndex;
+        }
+    }
+    // Parse footers
+    const footersResult = parseFooters(lines, footersStartIndex);
+    const breakingDescriptionFromFooter = footersResult.breakingDescription;
+    // Determine breaking status
+    const breaking = header.breaking || footersResult.footers.some((f) => hyphenToSpace(f.key.toUpperCase()) === 'BREAKING CHANGE');
+    // Determine breaking description
+    let breakingDescription;
+    if (header.breaking && header.subject) {
+        // If breaking via !, the subject may describe the breaking change
+        breakingDescription = header.subject;
+    }
+    if (breakingDescriptionFromFooter) {
+        breakingDescription = breakingDescriptionFromFooter;
+    }
+    return {
+        type: header.type,
+        scope: header.scope,
+        subject: header.subject,
+        body,
+        footers: footersResult.footers,
+        breaking,
+        breakingDescription,
+        raw: message,
+    };
+}
+/**
+ * Splits a message into lines, handling different line endings.
+ *
+ * @param message - The message to split into lines
+ * @returns An array of lines from the message
+ */
+function splitLines(message) {
+    const lines = [];
+    let currentLine = '';
+    let i = 0;
+    while (i < message.length) {
+        const char = message[i];
+        if (char === '\r') {
+            lines.push(currentLine);
+            currentLine = '';
+            // Skip \n if this is \r\n
+            if (message[i + 1] === '\n') {
+                i++;
+            }
+        }
+        else if (char === '\n') {
+            lines.push(currentLine);
+            currentLine = '';
+        }
+        else {
+            currentLine += char;
+        }
+        i++;
+    }
+    // Add final line if not empty
+    if (currentLine || message.endsWith('\n') || message.endsWith('\r')) {
+        lines.push(currentLine);
+    }
+    return lines;
+}
+
+const ANALYZE_COMMITS_STEP_ID = 'analyze-commits';
+/**
+ * Creates the analyze-commits step.
+ *
+ * This step:
+ * 1. Finds the last release tag for this package
+ * 2. Gets all commits since that tag (or all commits if first release)
+ * 3. Parses each commit using conventional commit format
+ * 4. Filters to only release-worthy commits
+ *
+ * State updates:
+ * - lastReleaseTag: Tag name of last release (null if first release)
+ * - commits: Array of parsed conventional commits
+ *
+ * @returns A FlowStep that analyzes commits
+ */
+function createAnalyzeCommitsStep() {
+    return createStep(ANALYZE_COMMITS_STEP_ID, 'Analyze Commits', async (ctx) => {
+        const { git, projectName, packageName, config, logger, state } = ctx;
+        // Find the last release tag for this package
+        let lastReleaseTag = null;
+        if (!state.isFirstRelease) {
+            // Try to find a tag matching the package name pattern
+            const tags = git.getTagsForPackage(packageName);
+            if (tags.length > 0) {
+                // Tags are returned in reverse chronological order
+                lastReleaseTag = tags[0].name;
+                logger.debug(`Found last release tag: ${lastReleaseTag}`);
+            }
+            else {
+                // Try with project name format
+                const projectTags = git.getTagsForPackage(projectName);
+                if (projectTags.length > 0) {
+                    lastReleaseTag = projectTags[0].name;
+                    logger.debug(`Found last release tag (project format): ${lastReleaseTag}`);
+                }
+            }
+        }
+        // Get commits
+        let rawCommits;
+        if (lastReleaseTag) {
+            rawCommits = git.getCommitsSince(lastReleaseTag);
+            logger.debug(`Found ${rawCommits.length} commits since ${lastReleaseTag}`);
+        }
+        else {
+            // First release - get all commits (limit to recent for performance)
+            rawCommits = git.getCommitLog({ maxCount: 100 });
+            logger.debug(`First release - analyzing up to ${rawCommits.length} commits`);
+        }
+        // Parse commits using conventional commit format
+        const commits = [];
+        const releaseTypes = config.releaseTypes ?? ['feat', 'fix', 'perf', 'revert'];
+        for (const rawCommit of rawCommits) {
+            const parsed = parseConventionalCommit(rawCommit.message);
+            if (parsed.type && releaseTypes.includes(parsed.type)) {
+                commits.push(parsed);
+            }
+        }
+        const message = commits.length > 0
+            ? `Found ${commits.length} releasable commits (${rawCommits.length} total)`
+            : `No releasable commits found (${rawCommits.length} total)`;
+        return {
+            status: 'success',
+            stateUpdates: {
+                lastReleaseTag,
+                commits,
+            },
+            message,
+        };
+    }, {
+        dependsOn: ['fetch-registry'],
+    });
+}
+
+/**
+ * Converts a SemVer to its canonical string representation.
+ *
+ * @param version - The version to format
+ * @returns The version string (e.g., "1.2.3-alpha.1+build.123")
+ */
+function format(version) {
+    let result = `${version.major}.${version.minor}.${version.patch}`;
+    if (version.prerelease.length > 0) {
+        result += '-' + version.prerelease.join('.');
+    }
+    if (version.build.length > 0) {
+        result += '+' + version.build.join('.');
+    }
+    return result;
+}
+
+/**
+ * Safe copies of Number built-in methods and constants.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/number
+ */
+// Capture references at module initialization time
+const _parseInt = globalThis.parseInt;
+const _isNaN = globalThis.isNaN;
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * (Safe copy) Parses a string and returns an integer.
+ */
+const parseInt = _parseInt;
+// ============================================================================
+// Global Type Checking (legacy, less strict)
+// ============================================================================
+/**
+ * (Safe copy) Global isNaN function (coerces to number first, less strict than Number.isNaN).
+ */
+const globalIsNaN = _isNaN;
+
+/**
+ * Creates a new SemVer object.
+ *
+ * @param options - Version components
+ * @returns A new SemVer object
+ */
+function createSemVer(options) {
+    return {
+        major: options.major,
+        minor: options.minor,
+        patch: options.patch,
+        prerelease: options.prerelease ?? [],
+        build: options.build ?? [],
+        raw: options.raw,
+    };
+}
+
+/**
+ * Increments a version based on the bump type.
+ *
+ * @param version - The version to increment
+ * @param type - The type of bump (major, minor, patch, etc.)
+ * @param prereleaseId - Optional prerelease identifier for prerelease bumps
+ * @returns A new incremented SemVer
+ *
+ * @example
+ * increment(parseVersion('1.2.3'), 'minor') // 1.3.0
+ * increment(parseVersion('1.2.3'), 'major') // 2.0.0
+ * increment(parseVersion('1.2.3'), 'prerelease', 'alpha') // 1.2.4-alpha.0
+ */
+function increment(version, type, prereleaseId) {
+    switch (type) {
+        case 'major':
+            return createSemVer({
+                major: version.major + 1,
+                minor: 0,
+                patch: 0,
+                prerelease: [],
+                build: [],
+            });
+        case 'minor':
+            return createSemVer({
+                major: version.major,
+                minor: version.minor + 1,
+                patch: 0,
+                prerelease: [],
+                build: [],
+            });
+        case 'patch':
+            // If version has prerelease, just remove it (1.2.3-alpha -> 1.2.3)
+            if (version.prerelease.length > 0) {
+                return createSemVer({
+                    major: version.major,
+                    minor: version.minor,
+                    patch: version.patch,
+                    prerelease: [],
+                    build: [],
+                });
+            }
+            return createSemVer({
+                major: version.major,
+                minor: version.minor,
+                patch: version.patch + 1,
+                prerelease: [],
+                build: [],
+            });
+        case 'premajor':
+            return createSemVer({
+                major: version.major + 1,
+                minor: 0,
+                patch: 0,
+                prerelease: ['alpha', '0'],
+                build: [],
+            });
+        case 'preminor':
+            return createSemVer({
+                major: version.major,
+                minor: version.minor + 1,
+                patch: 0,
+                prerelease: ['alpha', '0'],
+                build: [],
+            });
+        case 'prepatch':
+            return createSemVer({
+                major: version.major,
+                minor: version.minor,
+                patch: version.patch + 1,
+                prerelease: ['alpha', '0'],
+                build: [],
+            });
+        case 'prerelease':
+            return incrementPrerelease(version);
+        case 'none':
+        default:
+            return version;
+    }
+}
+/**
+ * Increments the prerelease portion of a version.
+ *
+ * @param version - The version to increment
+ * @param id - Optional prerelease identifier
+ * @returns A new version with incremented prerelease
+ */
+function incrementPrerelease(version, id) {
+    const prerelease = [...version.prerelease];
+    if (prerelease.length === 0) {
+        // No existing prerelease - start at patch+1 with id.0
+        return createSemVer({
+            major: version.major,
+            minor: version.minor,
+            patch: version.patch + 1,
+            prerelease: ['alpha', '0'],
+            build: [],
+        });
+    }
+    // Check if the last identifier is numeric
+    const lastIdx = prerelease.length - 1;
+    const last = prerelease[lastIdx];
+    const lastNum = parseInt(last, 10);
+    if (!globalIsNaN(lastNum)) {
+        // Increment the numeric part
+        prerelease[lastIdx] = String(lastNum + 1);
+    }
+    else {
+        // Append .0
+        prerelease.push('0');
+    }
+    return createSemVer({
+        major: version.major,
+        minor: version.minor,
+        patch: version.patch,
+        prerelease,
+        build: [],
+    });
+}
+
+/**
+ * Maximum version string length to prevent memory exhaustion.
+ */
+const MAX_VERSION_LENGTH = 256;
+/**
+ * Parses a semantic version string.
+ *
+ * Accepts versions in the format: MAJOR.MINOR.PATCH[-prerelease][+build]
+ * Optional leading 'v' or '=' prefixes are stripped.
+ *
+ * @param input - The version string to parse
+ * @returns A ParseVersionResult with the parsed version or error
+ *
+ * @example
+ * parseVersion('1.2.3') // { success: true, version: { major: 1, minor: 2, patch: 3, ... } }
+ * parseVersion('v1.0.0-alpha.1+build.123') // { success: true, ... }
+ * parseVersion('invalid') // { success: false, error: '...' }
+ */
+function parseVersion(input) {
+    // Input validation
+    if (!input || typeof input !== 'string') {
+        return { success: false, error: 'Version string is required' };
+    }
+    if (input.length > MAX_VERSION_LENGTH) {
+        return { success: false, error: `Version string exceeds maximum length of ${MAX_VERSION_LENGTH}` };
+    }
+    // Strip leading whitespace
+    let pos = 0;
+    while (pos < input.length && isWhitespace$1(input.charCodeAt(pos))) {
+        pos++;
+    }
+    // Strip trailing whitespace
+    let end = input.length;
+    while (end > pos && isWhitespace$1(input.charCodeAt(end - 1))) {
+        end--;
+    }
+    // Strip optional leading 'v' or '='
+    if (pos < end) {
+        const code = input.charCodeAt(pos);
+        if (code === 118 || code === 86) {
+            // 'v' or 'V'
+            pos++;
+        }
+        else if (code === 61) {
+            // '='
+            pos++;
+        }
+    }
+    // Parse major version
+    const majorResult = parseNumericIdentifier(input, pos, end);
+    if (!majorResult.success) {
+        return { success: false, error: majorResult.error ?? 'Invalid major version' };
+    }
+    pos = majorResult.endPos;
+    // Expect dot
+    if (pos >= end || input.charCodeAt(pos) !== 46) {
+        // '.'
+        return { success: false, error: 'Expected "." after major version' };
+    }
+    pos++;
+    // Parse minor version
+    const minorResult = parseNumericIdentifier(input, pos, end);
+    if (!minorResult.success) {
+        return { success: false, error: minorResult.error ?? 'Invalid minor version' };
+    }
+    pos = minorResult.endPos;
+    // Expect dot
+    if (pos >= end || input.charCodeAt(pos) !== 46) {
+        // '.'
+        return { success: false, error: 'Expected "." after minor version' };
+    }
+    pos++;
+    // Parse patch version
+    const patchResult = parseNumericIdentifier(input, pos, end);
+    if (!patchResult.success) {
+        return { success: false, error: patchResult.error ?? 'Invalid patch version' };
+    }
+    pos = patchResult.endPos;
+    // Parse optional prerelease
+    const prerelease = [];
+    if (pos < end && input.charCodeAt(pos) === 45) {
+        // '-'
+        pos++;
+        const prereleaseResult = parseIdentifiers(input, pos, end, [43]); // Stop at '+'
+        if (!prereleaseResult.success) {
+            return { success: false, error: prereleaseResult.error ?? 'Invalid prerelease' };
+        }
+        prerelease.push(...prereleaseResult.identifiers);
+        pos = prereleaseResult.endPos;
+    }
+    // Parse optional build metadata
+    const build = [];
+    if (pos < end && input.charCodeAt(pos) === 43) {
+        // '+'
+        pos++;
+        const buildResult = parseIdentifiers(input, pos, end, []);
+        if (!buildResult.success) {
+            return { success: false, error: buildResult.error ?? 'Invalid build metadata' };
+        }
+        build.push(...buildResult.identifiers);
+        pos = buildResult.endPos;
+    }
+    // Check for trailing characters
+    if (pos < end) {
+        return { success: false, error: `Unexpected character at position ${pos}: "${input[pos]}"` };
+    }
+    return {
+        success: true,
+        version: createSemVer({
+            major: majorResult.value,
+            minor: minorResult.value,
+            patch: patchResult.value,
+            prerelease,
+            build,
+            raw: input,
+        }),
+    };
+}
+/**
+ * Parses a numeric identifier (non-negative integer, no leading zeros except for "0").
+ *
+ * @param input - Input string to parse
+ * @param start - Start position in the input
+ * @param end - End position in the input
+ * @returns Numeric parsing result
+ */
+function parseNumericIdentifier(input, start, end) {
+    if (start >= end) {
+        return { success: false, value: 0, endPos: start, error: 'Expected numeric identifier' };
+    }
+    let pos = start;
+    const firstCode = input.charCodeAt(pos);
+    // Must start with a digit
+    if (!isDigit(firstCode)) {
+        return { success: false, value: 0, endPos: pos, error: 'Expected digit' };
+    }
+    // Check for leading zero (only "0" is valid, not "01", "007", etc.)
+    if (firstCode === 48 && pos + 1 < end && isDigit(input.charCodeAt(pos + 1))) {
+        return { success: false, value: 0, endPos: pos, error: 'Numeric identifier cannot have leading zeros' };
+    }
+    // Consume digits
+    let value = 0;
+    while (pos < end && isDigit(input.charCodeAt(pos))) {
+        value = value * 10 + (input.charCodeAt(pos) - 48);
+        pos++;
+        // Prevent overflow
+        if (value > Number.MAX_SAFE_INTEGER) {
+            return { success: false, value: 0, endPos: pos, error: 'Numeric identifier is too large' };
+        }
+    }
+    return { success: true, value, endPos: pos };
+}
+/**
+ * Parses dot-separated identifiers (for prerelease/build).
+ *
+ * @param input - Input string to parse
+ * @param start - Start position in the input
+ * @param end - End position in the input
+ * @param stopCodes - Character codes that signal end of identifiers
+ * @returns Identifiers parsing result
+ */
+function parseIdentifiers(input, start, end, stopCodes) {
+    const identifiers = [];
+    let pos = start;
+    while (pos < end) {
+        // Check for stop characters
+        if (stopCodes.includes(input.charCodeAt(pos))) {
+            break;
+        }
+        // Parse one identifier
+        const identStart = pos;
+        while (pos < end) {
+            const code = input.charCodeAt(pos);
+            // Stop at dot or stop characters
+            if (code === 46 || stopCodes.includes(code)) {
+                break;
+            }
+            // Must be alphanumeric or hyphen
+            if (!isAlphanumeric(code) && code !== 45) {
+                return { success: false, identifiers: [], endPos: pos, error: `Invalid character in identifier: "${input[pos]}"` };
+            }
+            pos++;
+        }
+        // Empty identifier is not allowed
+        if (pos === identStart) {
+            return { success: false, identifiers: [], endPos: pos, error: 'Empty identifier' };
+        }
+        identifiers.push(input.slice(identStart, pos));
+        // Consume dot separator
+        if (pos < end && input.charCodeAt(pos) === 46) {
+            pos++;
+            // Dot at end is invalid
+            if (pos >= end || stopCodes.includes(input.charCodeAt(pos))) {
+                return { success: false, identifiers: [], endPos: pos, error: 'Identifier expected after dot' };
+            }
+        }
+    }
+    return { success: true, identifiers, endPos: pos };
+}
+/**
+ * Checks if a character code is a digit (0-9).
+ *
+ * @param code - Character code to check
+ * @returns True if the code represents a digit
+ */
+function isDigit(code) {
+    return code >= 48 && code <= 57;
+}
+/**
+ * Checks if a character code is alphanumeric or hyphen.
+ *
+ * @param code - Character code to check
+ * @returns True if the code represents an alphanumeric character
+ */
+function isAlphanumeric(code) {
+    return ((code >= 48 && code <= 57) || // 0-9
+        (code >= 65 && code <= 90) || // A-Z
+        (code >= 97 && code <= 122) // a-z
+    );
+}
+/**
+ * Checks if a character code is whitespace.
+ *
+ * @param code - Character code to check
+ * @returns True if the code represents whitespace
+ */
+function isWhitespace$1(code) {
+    return code === 32 || code === 9 || code === 10 || code === 13;
+}
+
+const CALCULATE_BUMP_STEP_ID = 'calculate-bump';
+/**
+ * Determines the highest bump type from analyzed commits.
+ *
+ * Priority: major > minor > patch > none
+ * Breaking changes always result in major (post-1.0.0) or minor (pre-1.0.0).
+ *
+ * @param commits - Parsed conventional commits
+ * @param minorTypes - Types that trigger minor bumps
+ * @param patchTypes - Types that trigger patch bumps
+ * @param currentVersion - Current version string (for pre-1.0.0 handling)
+ * @returns The highest bump type needed
+ */
+function calculateBumpFromCommits(commits, minorTypes, patchTypes, currentVersion) {
+    if (commits.length === 0) {
+        return 'none';
+    }
+    // Check for breaking changes
+    const hasBreaking = commits.some((c) => c.breaking);
+    if (hasBreaking) {
+        // Pre-1.0.0: breaking changes are minor, not major
+        const parsed = parseVersion(currentVersion);
+        if (parsed.success && parsed.version && parsed.version.major === 0) {
+            return 'minor';
+        }
+        return 'major';
+    }
+    // Check for minor-triggering types
+    const hasMinor = commits.some((c) => c.type && minorTypes.includes(c.type));
+    if (hasMinor) {
+        return 'minor';
+    }
+    // Check for patch-triggering types
+    const hasPatch = commits.some((c) => c.type && patchTypes.includes(c.type));
+    if (hasPatch) {
+        return 'patch';
+    }
+    return 'none';
+}
+/**
+ * Creates the calculate-bump step.
+ *
+ * This step:
+ * 1. Analyzes commit types and breaking changes
+ * 2. Determines the appropriate bump level
+ * 3. Calculates the next version
+ *
+ * State updates:
+ * - bumpType: 'major' | 'minor' | 'patch' | 'none'
+ * - nextVersion: Calculated next version string
+ *
+ * @returns A FlowStep that calculates version bump
+ */
+function createCalculateBumpStep() {
+    return createStep(CALCULATE_BUMP_STEP_ID, 'Calculate Version Bump', async (ctx) => {
+        const { config, state, logger } = ctx;
+        const { commits, currentVersion, isFirstRelease } = state;
+        // Handle first release
+        if (isFirstRelease) {
+            const firstVersion = config.firstReleaseVersion ?? '0.1.0';
+            logger.info(`First release: using version ${firstVersion}`);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    bumpType: 'minor',
+                    nextVersion: firstVersion,
+                },
+                message: `First release: ${firstVersion}`,
+            };
+        }
+        // Check for forced bump type (releaseAs)
+        if (config.releaseAs) {
+            const forcedBumpType = config.releaseAs;
+            const current = parseVersion(currentVersion ?? '0.0.0');
+            if (!current.success || !current.version) {
+                return {
+                    status: 'failed',
+                    error: createError(`Invalid current version: ${currentVersion}`),
+                    message: `Could not parse current version: ${currentVersion}`,
+                };
+            }
+            const next = increment(current.version, forcedBumpType);
+            const nextVersion = format(next);
+            logger.info(`Forced ${forcedBumpType} bump via releaseAs: ${currentVersion} → ${nextVersion}`);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    bumpType: forcedBumpType,
+                    nextVersion,
+                },
+                message: `${forcedBumpType} bump (forced): ${currentVersion} → ${nextVersion}`,
+            };
+        }
+        // No commits = no bump needed
+        if (!commits || commits.length === 0) {
+            return createSkippedResult('No releasable commits found');
+        }
+        const minorTypes = config.minorTypes ?? ['feat'];
+        const patchTypes = config.patchTypes ?? ['fix', 'perf', 'revert'];
+        const bumpType = calculateBumpFromCommits(commits, minorTypes, patchTypes, currentVersion ?? '0.0.0');
+        if (bumpType === 'none') {
+            return {
+                status: 'success',
+                stateUpdates: {
+                    bumpType: 'none',
+                    nextVersion: undefined,
+                },
+                message: 'No version bump needed',
+            };
+        }
+        // Calculate next version
+        const current = parseVersion(currentVersion ?? '0.0.0');
+        if (!current.success || !current.version) {
+            return {
+                status: 'failed',
+                error: createError(`Invalid current version: ${currentVersion}`),
+                message: `Could not parse current version: ${currentVersion}`,
+            };
+        }
+        const next = increment(current.version, bumpType);
+        const nextVersion = format(next);
+        return {
+            status: 'success',
+            stateUpdates: {
+                bumpType,
+                nextVersion,
+            },
+            message: `${bumpType} bump: ${currentVersion} → ${nextVersion}`,
+        };
+    }, {
+        dependsOn: ['analyze-commits'],
+    });
+}
+/**
+ * Creates a step that checks for idempotency.
+ *
+ * This step prevents redundant releases by checking if the
+ * calculated version is already published.
+ *
+ * @returns A FlowStep that checks idempotency
+ */
+function createCheckIdempotencyStep() {
+    return createStep('check-idempotency', 'Check Idempotency', async (ctx) => {
+        const { registry, packageName, state } = ctx;
+        const { nextVersion, bumpType } = state;
+        // No bump = nothing to check
+        if (!nextVersion || bumpType === 'none') {
+            return {
+                status: 'success',
+                message: 'No version to check (no bump needed)',
+            };
+        }
+        // Check if version is already published
+        const isPublished = await registry.isVersionPublished(packageName, nextVersion);
+        if (isPublished) {
+            return {
+                status: 'skipped',
+                stateUpdates: {
+                    bumpType: 'none',
+                    nextVersion: undefined,
+                },
+                message: `Version ${nextVersion} is already published`,
+            };
+        }
+        return {
+            status: 'success',
+            message: `Version ${nextVersion} is not yet published`,
+        };
+    }, {
+        dependsOn: ['calculate-bump'],
+    });
+}
+
+/**
+ * Safe copies of Date built-in via factory function and static methods.
+ *
+ * Since constructors cannot be safely captured via Object.assign, this module
+ * provides a factory function that uses Reflect.construct internally.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/date
+ */
+// Capture references at module initialization time
+const _Date = globalThis.Date;
+const _Reflect$1 = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect$1.construct(_Date, args);
+}
+
+/**
+ * Creates a new changelog item.
+ *
+ * @param description - The description text of the change
+ * @param options - Optional configuration for scope, commits, references, and breaking flag
+ * @returns A new ChangelogItem object
+ */
+function createChangelogItem(description, options) {
+    return {
+        description,
+        scope: options?.scope,
+        commits: options?.commits ?? [],
+        references: options?.references ?? [],
+        breaking: options?.breaking ?? false,
+    };
+}
+/**
+ * Creates a new changelog section.
+ *
+ * @param type - The type of section (features, fixes, breaking, etc.)
+ * @param heading - The display heading for the section
+ * @param items - Optional array of changelog items in this section
+ * @returns A new ChangelogSection object
+ */
+function createChangelogSection(type, heading, items = []) {
+    return {
+        type,
+        heading,
+        items,
+    };
+}
+/**
+ * Creates a new changelog entry.
+ *
+ * @param version - The version string (e.g., '1.0.0')
+ * @param options - Optional configuration for date, sections, and other properties
+ * @returns A new ChangelogEntry object
+ */
+function createChangelogEntry(version, options) {
+    return {
+        version,
+        date: options?.date ?? null,
+        unreleased: options?.unreleased ?? false,
+        compareUrl: options?.compareUrl,
+        sections: options?.sections ?? [],
+        rawContent: options?.rawContent,
+    };
+}
+
+/**
+ * Maps section headings to their canonical types.
+ * Used during parsing to normalize different heading styles.
+ */
+const SECTION_TYPE_MAP = {
+    // Breaking changes
+    'breaking changes': 'breaking',
+    breaking: 'breaking',
+    'breaking change': 'breaking',
+    // Features
+    features: 'features',
+    feature: 'features',
+    added: 'features',
+    new: 'features',
+    // Fixes
+    fixes: 'fixes',
+    fix: 'fixes',
+    'bug fixes': 'fixes',
+    bugfixes: 'fixes',
+    fixed: 'fixes',
+    // Performance
+    performance: 'performance',
+    'performance improvements': 'performance',
+    perf: 'performance',
+    // Documentation
+    documentation: 'documentation',
+    docs: 'documentation',
+    // Deprecations
+    deprecations: 'deprecations',
+    deprecated: 'deprecations',
+    // Refactoring
+    refactoring: 'refactoring',
+    refactor: 'refactoring',
+    'code refactoring': 'refactoring',
+    // Tests
+    tests: 'tests',
+    test: 'tests',
+    testing: 'tests',
+    // Build
+    build: 'build',
+    'build system': 'build',
+    dependencies: 'build',
+    // CI
+    ci: 'ci',
+    'continuous integration': 'ci',
+    // Chores
+    chores: 'chores',
+    chore: 'chores',
+    maintenance: 'chores',
+    // Other
+    other: 'other',
+    miscellaneous: 'other',
+    misc: 'other',
+    changed: 'other',
+    changes: 'other',
+    removed: 'other',
+    security: 'other',
+};
+/**
+ * Standard section headings for serialization.
+ * Maps section types to their preferred heading text.
+ */
+const SECTION_HEADINGS = {
+    breaking: 'Breaking Changes',
+    features: 'Features',
+    fixes: 'Bug Fixes',
+    performance: 'Performance',
+    documentation: 'Documentation',
+    deprecations: 'Deprecations',
+    refactoring: 'Refactoring',
+    tests: 'Tests',
+    build: 'Build',
+    ci: 'CI',
+    chores: 'Chores',
+    other: 'Other',
+};
+/**
+ * Determines the section type from a heading string.
+ * Returns 'other' if the heading is not recognized.
+ *
+ * @param heading - The heading string to parse
+ * @returns The corresponding ChangelogSectionType
+ */
+function getSectionType(heading) {
+    const normalized = heading.toLowerCase().trim();
+    return SECTION_TYPE_MAP[normalized] ?? 'other';
+}
+
+/**
+ * Safe copies of Map built-in via factory function.
+ *
+ * Since constructors cannot be safely captured via Object.assign, this module
+ * provides a factory function that uses Reflect.construct internally.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/map
+ */
+// Capture references at module initialization time
+const _Map = globalThis.Map;
+const _Reflect = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Map using the captured Map constructor.
+ * Use this instead of `new Map()`.
+ *
+ * @param iterable - Optional iterable of key-value pairs.
+ * @returns A new Map instance.
+ */
+const createMap = (iterable) => _Reflect.construct(_Map, iterable ? [iterable] : []);
+
+/**
+ * Safe copies of Object built-in methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
+ */
+// Capture references at module initialization time
+const _Object = globalThis.Object;
+/**
+ * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
+ */
+const entries = _Object.entries;
+
+/**
+ * Safe copies of URL built-ins via factory functions.
+ *
+ * Provides safe references to URL and URLSearchParams.
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/url
+ */
+// Capture references at module initialization time
+const _URL = globalThis.URL;
+/**
+ * (Safe copy) Creates an object URL for the given object.
+ * Use this instead of `URL.createObjectURL()`.
+ *
+ * Note: This is a browser-only API. In Node.js environments, this will throw.
+ */
+typeof _URL.createObjectURL === 'function'
+    ? _URL.createObjectURL.bind(_URL)
+    : () => {
+        throw new Error('URL.createObjectURL is not available in this environment');
+    };
+/**
+ * (Safe copy) Revokes an object URL previously created with createObjectURL.
+ * Use this instead of `URL.revokeObjectURL()`.
+ *
+ * Note: This is a browser-only API. In Node.js environments, this will throw.
+ */
+typeof _URL.revokeObjectURL === 'function'
+    ? _URL.revokeObjectURL.bind(_URL)
+    : () => {
+        throw new Error('URL.revokeObjectURL is not available in this environment');
+    };
+
+/**
+ * Safe copies of Math built-in methods.
+ *
+ * These references are captured at module initialization time to protect against
+ * prototype pollution attacks. Import only what you need for tree-shaking.
+ *
+ * @module @hyperfrontend/immutable-api-utils/built-in-copy/math
+ */
+// Capture references at module initialization time
+const _Math = globalThis.Math;
+// ============================================================================
+// Min/Max
+// ============================================================================
+/**
+ * (Safe copy) Returns the larger of zero or more numbers.
+ */
+const max = _Math.max;
+
+/**
+ * Line Parser
+ *
+ * Utilities for parsing individual changelog lines without regex.
+ */
+/**
+ * Parses a version string from a heading.
+ * Examples: "1.2.3", "v1.2.3", "[1.2.3]", "1.2.3 - 2024-01-01"
+ *
+ * @param heading - The heading string to parse
+ * @returns An object containing the parsed version, date, and optional compareUrl
+ */
+function parseVersionFromHeading(heading) {
+    const trimmed = heading.trim();
+    // Check for unreleased
+    const lowerHeading = trimmed.toLowerCase();
+    if (lowerHeading === 'unreleased' || lowerHeading === '[unreleased]') {
+        return { version: 'Unreleased', date: null };
+    }
+    let pos = 0;
+    let version = '';
+    let date = null;
+    let compareUrl;
+    // Skip leading [ if present
+    if (trimmed[pos] === '[') {
+        pos++;
+    }
+    // Skip leading 'v' if present
+    if (trimmed[pos] === 'v' || trimmed[pos] === 'V') {
+        pos++;
+    }
+    // Parse version number (digits and dots)
+    const versionStart = pos;
+    while (pos < trimmed.length) {
+        const char = trimmed[pos];
+        const code = char.charCodeAt(0);
+        // Allow digits, dots, hyphens (for prerelease), plus signs
+        if ((code >= 48 && code <= 57) || // 0-9
+            char === '.' ||
+            char === '-' ||
+            char === '+' ||
+            (code >= 97 && code <= 122) || // a-z (for prerelease tags like alpha, beta, rc)
+            (code >= 65 && code <= 90) // A-Z
+        ) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    version = trimmed.slice(versionStart, pos);
+    // Skip trailing ] if present
+    if (trimmed[pos] === ']') {
+        pos++;
+    }
+    // Skip whitespace and separator
+    while (pos < trimmed.length && (trimmed[pos] === ' ' || trimmed[pos] === '-' || trimmed[pos] === '–')) {
+        pos++;
+    }
+    // Try to parse date (YYYY-MM-DD format)
+    if (pos < trimmed.length) {
+        const dateMatch = extractDate(trimmed.slice(pos));
+        if (dateMatch) {
+            date = dateMatch.date;
+            pos += dateMatch.length;
+        }
+    }
+    // Skip to check for compare URL (in parentheses or link)
+    while (pos < trimmed.length && trimmed[pos] === ' ') {
+        pos++;
+    }
+    // Check for link at end: [compare](url)
+    if (pos < trimmed.length) {
+        const linkMatch = extractLink(trimmed.slice(pos));
+        if (linkMatch?.url) {
+            compareUrl = linkMatch.url;
+        }
+    }
+    return { version, date, compareUrl };
+}
+/**
+ * Extracts a date in YYYY-MM-DD format from a string.
+ *
+ * @param str - The string to extract a date from
+ * @returns The extracted date and its length, or null if no date found
+ */
+function extractDate(str) {
+    let pos = 0;
+    // Skip optional parentheses
+    if (str[pos] === '(')
+        pos++;
+    // Parse year (4 digits)
+    const yearStart = pos;
+    while (pos < str.length && pos - yearStart < 4) {
+        const code = str.charCodeAt(pos);
+        if (code >= 48 && code <= 57) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    if (pos - yearStart !== 4)
+        return null;
+    // Expect - or /
+    if (str[pos] !== '-' && str[pos] !== '/')
+        return null;
+    const separator = str[pos];
+    pos++;
+    // Parse month (2 digits)
+    const monthStart = pos;
+    while (pos < str.length && pos - monthStart < 2) {
+        const code = str.charCodeAt(pos);
+        if (code >= 48 && code <= 57) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    if (pos - monthStart !== 2)
+        return null;
+    // Expect same separator
+    if (str[pos] !== separator)
+        return null;
+    pos++;
+    // Parse day (2 digits)
+    const dayStart = pos;
+    while (pos < str.length && pos - dayStart < 2) {
+        const code = str.charCodeAt(pos);
+        if (code >= 48 && code <= 57) {
+            pos++;
+        }
+        else {
+            break;
+        }
+    }
+    if (pos - dayStart !== 2)
+        return null;
+    // Skip optional closing parenthesis
+    if (str[pos] === ')')
+        pos++;
+    const dateStr = str.slice(yearStart, dayStart + 2);
+    const date = slashToHyphen(dateStr);
+    return { date, length: pos };
+}
+/**
+ * Replaces forward slashes with hyphens (ReDoS-safe).
+ *
+ * @param input - The input string
+ * @returns String with forward slashes replaced by hyphens
+ */
+function slashToHyphen(input) {
+    const result = [];
+    for (let i = 0; i < input.length; i++) {
+        result.push(input[i] === '/' ? '-' : input[i]);
+    }
+    return result.join('');
+}
+/**
+ * Extracts a markdown link from a string.
+ *
+ * @param str - The string to extract a link from
+ * @returns The extracted link text, url, and length, or null if no link found
+ */
+function extractLink(str) {
+    if (str[0] !== '[')
+        return null;
+    let pos = 1;
+    let depth = 1;
+    // Find closing ]
+    while (pos < str.length && depth > 0) {
+        if (str[pos] === '[')
+            depth++;
+        else if (str[pos] === ']')
+            depth--;
+        pos++;
+    }
+    if (depth !== 0)
+        return null;
+    const text = str.slice(1, pos - 1);
+    // Expect (
+    if (str[pos] !== '(')
+        return null;
+    pos++;
+    const urlStart = pos;
+    depth = 1;
+    while (pos < str.length && depth > 0) {
+        if (str[pos] === '(')
+            depth++;
+        else if (str[pos] === ')')
+            depth--;
+        pos++;
+    }
+    if (depth !== 0)
+        return null;
+    const url = str.slice(urlStart, pos - 1);
+    return { text, url, length: pos };
+}
+/**
+ * Parses commit references from a line.
+ * Examples: (abc1234), [abc1234], commit abc1234
+ *
+ * @param text - The text to parse for commit references
+ * @param baseUrl - Optional base URL for constructing commit links
+ * @returns An array of parsed CommitRef objects
+ */
+function parseCommitRefs(text, baseUrl) {
+    const refs = [];
+    let pos = 0;
+    while (pos < text.length) {
+        // Look for potential hash patterns
+        // Common formats: (abc1234), [abc1234], abc1234fabcdef
+        // Check for parenthetical hash
+        if (text[pos] === '(' || text[pos] === '[') {
+            const closeChar = text[pos] === '(' ? ')' : ']';
+            const start = pos + 1;
+            pos++;
+            // Read potential hash
+            while (pos < text.length && isHexDigit(text[pos])) {
+                pos++;
+            }
+            // Check if valid hash (7-40 hex chars)
+            const hash = text.slice(start, pos);
+            if (hash.length >= 7 && hash.length <= 40 && text[pos] === closeChar) {
+                refs.push({
+                    hash,
+                    shortHash: hash.slice(0, 7),
+                    url: baseUrl ? `${baseUrl}/commit/${hash}` : undefined,
+                });
+                pos++; // skip closing bracket
+                continue;
+            }
+        }
+        pos++;
+    }
+    return refs;
+}
+/**
+ * Parses issue/PR references from a line.
+ * Examples: #123, GH-123, closes #123
+ *
+ * @param text - The text to parse for issue references
+ * @param baseUrl - Optional base URL for constructing issue links
+ * @returns An array of parsed IssueRef objects
+ */
+function parseIssueRefs(text, baseUrl) {
+    const refs = [];
+    let pos = 0;
+    while (pos < text.length) {
+        // Look for # followed by digits
+        if (text[pos] === '#') {
+            pos++;
+            const numStart = pos;
+            while (pos < text.length && isDigitChar(text[pos])) {
+                pos++;
+            }
+            if (pos > numStart) {
+                const number = parseInt(text.slice(numStart, pos), 10);
+                // Check context for PR vs issue
+                const beforeHash = text.slice(max(0, numStart - 10), numStart - 1).toLowerCase();
+                const type = beforeHash.includes('pr') || beforeHash.includes('pull') ? 'pull-request' : 'issue';
+                refs.push({
+                    number,
+                    type,
+                    url: baseUrl ? `${baseUrl}/issues/${number}` : undefined,
+                });
+                continue;
+            }
+        }
+        pos++;
+    }
+    return refs;
+}
+/**
+ * Parses the scope from a changelog item.
+ * Example: "**scope:** description" -> { scope: "scope", description: "description" }
+ *
+ * @param text - The text to parse for scope
+ * @returns An object with optional scope and the description
+ */
+function parseScopeFromItem(text) {
+    const trimmed = text.trim();
+    // Check for **scope:** pattern (colon inside or outside bold)
+    if (trimmed.startsWith('**')) {
+        let pos = 2;
+        const scopeStart = pos;
+        // Read until ** or :
+        while (pos < trimmed.length && trimmed[pos] !== '*' && trimmed[pos] !== ':') {
+            pos++;
+        }
+        // Handle **scope:** pattern (colon before closing **)
+        if (trimmed[pos] === ':' && trimmed[pos + 1] === '*' && trimmed[pos + 2] === '*') {
+            const scope = trimmed.slice(scopeStart, pos);
+            pos += 3; // skip :**
+            // Skip whitespace
+            while (trimmed[pos] === ' ')
+                pos++;
+            return { scope, description: trimmed.slice(pos) };
+        }
+        // Handle **scope**: pattern (colon after closing **)
+        if (trimmed[pos] === '*' && trimmed[pos + 1] === '*') {
+            const scope = trimmed.slice(scopeStart, pos);
+            pos += 2; // skip **
+            // Skip : if present
+            if (trimmed[pos] === ':')
+                pos++;
+            // Skip whitespace
+            while (trimmed[pos] === ' ')
+                pos++;
+            return { scope, description: trimmed.slice(pos) };
+        }
+    }
+    // Check for scope: pattern (without bold)
+    const colonPos = trimmed.indexOf(':');
+    if (colonPos > 0 && colonPos < 30) {
+        // scope shouldn't be too long
+        const potentialScope = trimmed.slice(0, colonPos);
+        // Scope should be a simple identifier (letters, numbers, hyphens)
+        if (isValidScope(potentialScope)) {
+            const description = trimmed.slice(colonPos + 1).trim();
+            return { scope: potentialScope, description };
+        }
+    }
+    return { description: trimmed };
+}
+/**
+ * Checks if a string is a valid scope (alphanumeric with hyphens).
+ *
+ * @param str - The string to check
+ * @returns True if the string is a valid scope identifier
+ */
+function isValidScope(str) {
+    if (!str || str.length === 0)
+        return false;
+    for (let i = 0; i < str.length; i++) {
+        const code = str.charCodeAt(i);
+        if (!(code >= 48 && code <= 57) && // 0-9
+            !(code >= 65 && code <= 90) && // A-Z
+            !(code >= 97 && code <= 122) && // a-z
+            code !== 45 // -
+        ) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Checks if a character is a hex digit.
+ *
+ * @param char - The character to check
+ * @returns True if the character is a hex digit (0-9, A-F, a-f)
+ */
+function isHexDigit(char) {
+    const code = char.charCodeAt(0);
+    return ((code >= 48 && code <= 57) || // 0-9
+        (code >= 65 && code <= 70) || // A-F
+        (code >= 97 && code <= 102) // a-f
+    );
+}
+/**
+ * Checks if a character is a digit.
+ *
+ * @param char - The character to check
+ * @returns True if the character is a digit (0-9)
+ */
+function isDigitChar(char) {
+    const code = char.charCodeAt(0);
+    return code >= 48 && code <= 57;
+}
+
+/**
+ * Changelog Tokenizer
+ *
+ * A state machine tokenizer that processes markdown character-by-character.
+ * No regex is used to ensure ReDoS safety.
+ */
+/**
+ * Maximum input length to prevent memory exhaustion (1MB)
+ */
+const MAX_INPUT_LENGTH = 1024 * 1024;
+/**
+ * Tokenizes a changelog markdown string into tokens.
+ *
+ * @param input - The markdown content to tokenize
+ * @returns Array of tokens
+ * @throws {Error} If input exceeds maximum length
+ */
+function tokenize(input) {
+    if (input.length > MAX_INPUT_LENGTH) {
+        throw createError(`Input exceeds maximum length of ${MAX_INPUT_LENGTH} characters`);
+    }
+    const state = {
+        pos: 0,
+        line: 1,
+        column: 1,
+        input,
+        tokens: [],
+    };
+    while (state.pos < state.input.length) {
+        const char = state.input[state.pos];
+        // Check for newline
+        if (char === '\n') {
+            consumeNewline(state);
+            continue;
+        }
+        // Check for carriage return (handle \r\n)
+        if (char === '\r') {
+            state.pos++;
+            if (state.input[state.pos] === '\n') {
+                consumeNewline(state);
+            }
+            continue;
+        }
+        // At start of line, check for special markers
+        if (state.column === 1) {
+            // Check for heading
+            if (char === '#') {
+                consumeHeading(state);
+                continue;
+            }
+            // Check for list item
+            if ((char === '-' || char === '*') && isWhitespace(state.input[state.pos + 1])) {
+                consumeListItem(state);
+                continue;
+            }
+        }
+        // Check for inline markdown elements
+        if (char === '[') {
+            consumeLink(state);
+            continue;
+        }
+        if (char === '`') {
+            consumeCode(state);
+            continue;
+        }
+        if (char === '*' && state.input[state.pos + 1] === '*') {
+            consumeBold(state);
+            continue;
+        }
+        // Default: consume as text
+        consumeText(state);
+    }
+    // Add EOF token
+    pushToken(state, 'eof', '');
+    return state.tokens;
+}
+/**
+ * Consumes a newline character.
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeNewline(state) {
+    // Check if this is a blank line (previous token was also newline or at start)
+    const prevToken = state.tokens[state.tokens.length - 1];
+    const isBlank = prevToken?.type === 'newline' || prevToken?.type === 'blank-line' || state.tokens.length === 0;
+    pushToken(state, isBlank ? 'blank-line' : 'newline', '\n');
+    state.pos++;
+    state.line++;
+    state.column = 1;
+}
+/**
+ * Consumes a heading (# through ####).
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeHeading(state) {
+    const startColumn = state.column;
+    let level = 0;
+    // Count # characters
+    while (state.input[state.pos] === '#' && level < 4) {
+        state.pos++;
+        state.column++;
+        level++;
+    }
+    // Skip whitespace after #
+    while (isWhitespace(state.input[state.pos]) && state.input[state.pos] !== '\n') {
+        state.pos++;
+        state.column++;
+    }
+    // Consume the rest of the line as heading content
+    const contentStart = state.pos;
+    while (state.pos < state.input.length && state.input[state.pos] !== '\n') {
+        state.pos++;
+        state.column++;
+    }
+    const content = state.input.slice(contentStart, state.pos);
+    const type = `heading-${level}`;
+    state.tokens.push({
+        type,
+        value: content.trim(),
+        line: state.line,
+        column: startColumn,
+    });
+}
+/**
+ * Consumes a list item (- or *).
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeListItem(state) {
+    const startColumn = state.column;
+    // Skip the marker and whitespace
+    state.pos++; // skip - or *
+    state.column++;
+    while (isWhitespace(state.input[state.pos]) && state.input[state.pos] !== '\n') {
+        state.pos++;
+        state.column++;
+    }
+    // Consume the rest of the line as list item content
+    const contentStart = state.pos;
+    while (state.pos < state.input.length && state.input[state.pos] !== '\n') {
+        state.pos++;
+        state.column++;
+    }
+    const content = state.input.slice(contentStart, state.pos);
+    state.tokens.push({
+        type: 'list-item',
+        value: content,
+        line: state.line,
+        column: startColumn,
+    });
+}
+/**
+ * Consumes a markdown link [text](url).
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeLink(state) {
+    const startColumn = state.column;
+    const startLine = state.line;
+    // Skip opening [
+    state.pos++;
+    state.column++;
+    // Find closing ]
+    const textStart = state.pos;
+    let depth = 1;
+    while (state.pos < state.input.length && depth > 0) {
+        const char = state.input[state.pos];
+        if (char === '[')
+            depth++;
+        else if (char === ']')
+            depth--;
+        else if (char === '\n') {
+            // Link text shouldn't span lines; emit '[' as text and reset
+            state.tokens.push({
+                type: 'text',
+                value: '[',
+                line: startLine,
+                column: startColumn,
+            });
+            state.pos = textStart;
+            state.column = startColumn + 1;
+            return;
+        }
+        if (depth > 0) {
+            state.pos++;
+            state.column++;
+        }
+    }
+    if (depth !== 0) {
+        // No closing ], emit '[' as text and reset
+        state.tokens.push({
+            type: 'text',
+            value: '[',
+            line: startLine,
+            column: startColumn,
+        });
+        state.pos = textStart;
+        state.column = startColumn + 1;
+        return;
+    }
+    const linkText = state.input.slice(textStart, state.pos);
+    state.pos++; // skip ]
+    state.column++;
+    // Check for (url)
+    if (state.input[state.pos] === '(') {
+        state.pos++; // skip (
+        state.column++;
+        const urlStart = state.pos;
+        depth = 1;
+        while (state.pos < state.input.length && depth > 0) {
+            const char = state.input[state.pos];
+            if (char === '(')
+                depth++;
+            else if (char === ')')
+                depth--;
+            else if (char === '\n') {
+                // URL shouldn't span lines
+                break;
+            }
+            if (depth > 0) {
+                state.pos++;
+                state.column++;
+            }
+        }
+        if (depth === 0) {
+            const linkUrl = state.input.slice(urlStart, state.pos);
+            state.pos++; // skip )
+            state.column++;
+            // Emit link-text token
+            state.tokens.push({
+                type: 'link-text',
+                value: linkText,
+                line: startLine,
+                column: startColumn,
+            });
+            // Emit link-url token
+            state.tokens.push({
+                type: 'link-url',
+                value: linkUrl,
+                line: startLine,
+                column: startColumn + linkText.length + 3,
+            });
+            return;
+        }
+    }
+    // No URL part, emit as text
+    state.tokens.push({
+        type: 'text',
+        value: `[${linkText}]`,
+        line: startLine,
+        column: startColumn,
+    });
+}
+/**
+ * Consumes a code span `code`.
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeCode(state) {
+    const startColumn = state.column;
+    const startLine = state.line;
+    state.pos++; // skip opening `
+    state.column++;
+    const contentStart = state.pos;
+    while (state.pos < state.input.length && state.input[state.pos] !== '`' && state.input[state.pos] !== '\n') {
+        state.pos++;
+        state.column++;
+    }
+    if (state.input[state.pos] === '`') {
+        const content = state.input.slice(contentStart, state.pos);
+        state.pos++; // skip closing `
+        state.column++;
+        state.tokens.push({
+            type: 'code',
+            value: content,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+    else {
+        // No closing `, emit as text
+        state.tokens.push({
+            type: 'text',
+            value: '`' + state.input.slice(contentStart, state.pos),
+            line: startLine,
+            column: startColumn,
+        });
+    }
+}
+/**
+ * Consumes bold text **text**.
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeBold(state) {
+    const startColumn = state.column;
+    const startLine = state.line;
+    state.pos += 2; // skip opening **
+    state.column += 2;
+    const contentStart = state.pos;
+    while (state.pos < state.input.length) {
+        // Check for closing **
+        if (state.input[state.pos] === '*' && state.input[state.pos + 1] === '*') {
+            break;
+        }
+        if (state.input[state.pos] === '\n') {
+            state.line++;
+            state.column = 0;
+        }
+        state.pos++;
+        state.column++;
+    }
+    if (state.input[state.pos] === '*' && state.input[state.pos + 1] === '*') {
+        const content = state.input.slice(contentStart, state.pos);
+        state.pos += 2; // skip closing **
+        state.column += 2;
+        state.tokens.push({
+            type: 'bold',
+            value: content,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+    else {
+        // No closing **, emit as text
+        state.tokens.push({
+            type: 'text',
+            value: '**' + state.input.slice(contentStart, state.pos),
+            line: startLine,
+            column: startColumn,
+        });
+    }
+}
+/**
+ * Consumes plain text until a special character or end of line.
+ *
+ * @param state - The tokenizer state to update
+ */
+function consumeText(state) {
+    const startColumn = state.column;
+    const startLine = state.line;
+    const startPos = state.pos;
+    while (state.pos < state.input.length) {
+        const char = state.input[state.pos];
+        // Stop at newline
+        if (char === '\n' || char === '\r') {
+            break;
+        }
+        // Stop at special characters (but only if they start a pattern)
+        if (char === '[')
+            break;
+        if (char === '`')
+            break;
+        if (char === '*' && state.input[state.pos + 1] === '*')
+            break;
+        state.pos++;
+        state.column++;
+    }
+    const content = state.input.slice(startPos, state.pos);
+    if (content.length > 0) {
+        state.tokens.push({
+            type: 'text',
+            value: content,
+            line: startLine,
+            column: startColumn,
+        });
+    }
+}
+/**
+ * Pushes a token to the state.
+ *
+ * @param state - The tokenizer state to update
+ * @param type - Token classification (e.g., 'heading-1', 'text', 'link-url')
+ * @param value - Text content associated with the token
+ */
+function pushToken(state, type, value) {
+    state.tokens.push({
+        type,
+        value,
+        line: state.line,
+        column: state.column,
+    });
+}
+/**
+ * Checks if a character is whitespace (but not newline).
+ *
+ * @param char - The character to check
+ * @returns True if the character is whitespace (space or tab)
+ */
+function isWhitespace(char) {
+    return char === ' ' || char === '\t';
+}
+
+/**
+ * Changelog Parser
+ *
+ * Parses a changelog markdown string into a structured Changelog object.
+ * Uses a state machine tokenizer for ReDoS-safe parsing.
+ */
+/**
+ * Parses a changelog markdown string into a Changelog object.
+ *
+ * @param content - The markdown content to parse
+ * @param source - Optional source file path
+ * @returns Parsed Changelog object
+ */
+function parseChangelog(content, source) {
+    const tokens = tokenize(content);
+    const state = {
+        tokens,
+        pos: 0,
+        warnings: [],
+    };
+    // Parse header
+    const header = parseHeader(state);
+    // Parse entries
+    const entries = parseEntries(state);
+    // Detect format
+    const format = detectFormat(header, entries);
+    // Build metadata
+    const metadata = {
+        format,
+        isConventional: format === 'conventional',
+        repositoryUrl: state.repositoryUrl,
+        warnings: state.warnings,
+    };
+    return {
+        source,
+        header,
+        entries,
+        metadata,
+    };
+}
+/**
+ * Parses the changelog header section.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns The parsed ChangelogHeader with title, description, and links
+ */
+function parseHeader(state) {
+    let title = '# Changelog';
+    const description = [];
+    const links = [];
+    // Look for h1 title
+    const headingToken = currentToken(state);
+    if (headingToken?.type === 'heading-1') {
+        title = `# ${headingToken.value}`;
+        advance(state);
+    }
+    // Skip newlines
+    skipNewlines(state);
+    // Collect description lines until we hit h2 (version entry)
+    while (!isEOF(state) && currentToken(state)?.type !== 'heading-2') {
+        const token = currentToken(state);
+        if (!token)
+            break;
+        if (token.type === 'text') {
+            description.push(token.value);
+        }
+        else if (token.type === 'link-text') {
+            // Check for link definition
+            const nextToken = peek(state, 1);
+            if (nextToken?.type === 'link-url') {
+                description.push(`[${token.value}](${nextToken.value})`);
+                links.push({ label: token.value, url: nextToken.value });
+                // Try to detect repository URL
+                if (!state.repositoryUrl && nextToken.value.includes('github.com')) {
+                    state.repositoryUrl = extractRepoUrl(nextToken.value);
+                }
+                advance(state); // skip link-text
+                advance(state); // skip link-url
+                continue;
+            }
+        }
+        else if (token.type === 'newline' || token.type === 'blank-line') {
+            if (description.length > 0 && description[description.length - 1] !== '') {
+                description.push('');
+            }
+        }
+        advance(state);
+    }
+    // Trim trailing empty lines
+    while (description.length > 0 && description[description.length - 1] === '') {
+        description.pop();
+    }
+    return { title, description, links };
+}
+/**
+ * Parses all changelog entries.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns An array of parsed ChangelogEntry objects
+ */
+function parseEntries(state) {
+    const entries = [];
+    while (!isEOF(state)) {
+        // Look for h2 heading (version entry)
+        if (currentToken(state)?.type === 'heading-2') {
+            const entry = parseEntry(state);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        else {
+            advance(state);
+        }
+    }
+    return entries;
+}
+/**
+ * Parses a single changelog entry.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns The parsed ChangelogEntry or null if parsing fails
+ */
+function parseEntry(state) {
+    const headingToken = currentToken(state);
+    if (headingToken?.type !== 'heading-2') {
+        return null;
+    }
+    const { version, date, compareUrl } = parseVersionFromHeading(headingToken.value);
+    const unreleased = version.toLowerCase() === 'unreleased';
+    advance(state); // skip h2
+    skipNewlines(state);
+    // Parse sections
+    const sections = parseSections(state);
+    return {
+        version,
+        date,
+        unreleased,
+        compareUrl,
+        sections,
+    };
+}
+/**
+ * Parses sections within an entry.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns An array of parsed ChangelogSection objects
+ */
+function parseSections(state) {
+    const sections = [];
+    while (!isEOF(state)) {
+        const token = currentToken(state);
+        // Stop at next version entry (h2)
+        if (token?.type === 'heading-2') {
+            break;
+        }
+        // Parse section (h3)
+        if (token?.type === 'heading-3') {
+            const section = parseSection(state);
+            if (section) {
+                sections.push(section);
+            }
+        }
+        else if (token?.type === 'list-item') {
+            // Items without section heading - create "other" section
+            const items = parseItems(state);
+            if (items.length > 0) {
+                sections.push({
+                    type: 'other',
+                    heading: 'Changes',
+                    items,
+                });
+            }
+        }
+        else {
+            advance(state);
+        }
+    }
+    return sections;
+}
+/**
+ * Parses a single section.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns The parsed ChangelogSection or null if parsing fails
+ */
+function parseSection(state) {
+    const headingToken = currentToken(state);
+    if (headingToken?.type !== 'heading-3') {
+        return null;
+    }
+    const heading = headingToken.value;
+    const type = getSectionType(heading);
+    advance(state); // skip h3
+    skipNewlines(state);
+    // Parse items
+    const items = parseItems(state);
+    return {
+        type,
+        heading,
+        items,
+    };
+}
+/**
+ * Parses list items.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns An array of parsed ChangelogItem objects
+ */
+function parseItems(state) {
+    const items = [];
+    while (!isEOF(state)) {
+        const token = currentToken(state);
+        // Stop at headings
+        if (token?.type === 'heading-2' || token?.type === 'heading-3') {
+            break;
+        }
+        // Parse list item
+        if (token?.type === 'list-item') {
+            const item = parseItem(state);
+            if (item) {
+                items.push(item);
+            }
+        }
+        else {
+            advance(state);
+        }
+    }
+    return items;
+}
+/**
+ * Parses a single list item.
+ *
+ * @param state - The parser state containing tokens and position
+ * @returns The parsed ChangelogItem or null if parsing fails
+ */
+function parseItem(state) {
+    const token = currentToken(state);
+    if (token?.type !== 'list-item') {
+        return null;
+    }
+    const text = token.value;
+    const { scope, description } = parseScopeFromItem(text);
+    const commits = parseCommitRefs(text, state.repositoryUrl);
+    const references = parseIssueRefs(text, state.repositoryUrl);
+    // Check for breaking change indicators
+    const breaking = isBreakingItem(text);
+    advance(state);
+    return createChangelogItem(description, {
+        scope,
+        commits,
+        references,
+        breaking,
+    });
+}
+/**
+ * Checks if an item indicates a breaking change.
+ *
+ * @param text - The text content of the item
+ * @returns True if the item indicates a breaking change
+ */
+function isBreakingItem(text) {
+    const lower = text.toLowerCase();
+    return lower.includes('breaking change') || lower.includes('breaking:') || lower.startsWith('!') || lower.includes('[breaking]');
+}
+/**
+ * Detects the changelog format.
+ *
+ * @param header - The parsed header of the changelog
+ * @param entries - The parsed changelog entries
+ * @returns The detected ChangelogFormat
+ */
+function detectFormat(header, entries) {
+    const descriptionText = header.description.join(' ').toLowerCase();
+    // Check for Keep a Changelog
+    if (descriptionText.includes('keep a changelog') || descriptionText.includes('keepachangelog')) {
+        return 'keep-a-changelog';
+    }
+    // Check for conventional changelog patterns
+    const hasConventionalSections = entries.some((entry) => entry.sections.some((section) => ['features', 'fixes', 'performance'].includes(section.type)));
+    if (hasConventionalSections) {
+        return 'conventional';
+    }
+    // Check if we have entries with structured sections
+    if (entries.some((entry) => entry.sections.length > 0)) {
+        return 'custom';
+    }
+    return 'unknown';
+}
+/**
+ * Extracts repository URL from a GitHub URL.
+ *
+ * @param url - The URL to extract the repository from
+ * @returns The repository URL or undefined if not found
+ */
+function extractRepoUrl(url) {
+    // Try to extract base repo URL from various GitHub URL patterns
+    const githubIndex = url.indexOf('github.com/');
+    if (githubIndex !== -1) {
+        const afterGithub = url.slice(githubIndex + 11);
+        const parts = afterGithub.split('/');
+        if (parts.length >= 2) {
+            return `https://github.com/${parts[0]}/${parts[1]}`;
+        }
+    }
+    return undefined;
+}
+// ============================================================================
+// Parser utilities
+// ============================================================================
+/**
+ * Gets the current token at the parser position.
+ *
+ * @param state - The parser state
+ * @returns The current token or undefined if at end
+ */
+function currentToken(state) {
+    return state.tokens[state.pos];
+}
+/**
+ * Peeks at a token at an offset from the current position.
+ *
+ * @param state - The parser state
+ * @param offset - The offset from current position
+ * @returns The token at the offset or undefined if out of bounds
+ */
+function peek(state, offset) {
+    return state.tokens[state.pos + offset];
+}
+/**
+ * Advances the parser position by one token.
+ *
+ * @param state - The parser state to advance
+ */
+function advance(state) {
+    state.pos++;
+}
+/**
+ * Checks if the parser has reached the end of the token stream.
+ *
+ * @param state - The parser state
+ * @returns True if at end of file
+ */
+function isEOF(state) {
+    const token = currentToken(state);
+    return !token || token.type === 'eof';
+}
+/**
+ * Skips newline tokens until a non-newline token is found.
+ *
+ * @param state - The parser state
+ */
+function skipNewlines(state) {
+    while (!isEOF(state)) {
+        const token = currentToken(state);
+        if (token?.type !== 'newline' && token?.type !== 'blank-line') {
+            break;
+        }
+        advance(state);
+    }
+}
+
+/**
+ * Changelog Serialization Templates
+ *
+ * Output templates and formatting helpers for changelog serialization.
+ * Provides configurable options for different changelog styles.
+ */
+/**
+ * Default serialization options.
+ */
+const DEFAULT_SERIALIZE_OPTIONS = {
+    includeDescription: true,
+    includeLinks: true,
+    includeCompareUrls: true,
+    includeCommits: true,
+    includeReferences: true,
+    includeScope: true,
+    includeRawContent: false,
+    sectionOrder: [
+        'breaking',
+        'features',
+        'fixes',
+        'performance',
+        'documentation',
+        'deprecations',
+        'refactoring',
+        'tests',
+        'build',
+        'ci',
+        'chores',
+        'other',
+    ],
+    sectionHeadings: {},
+    lineEnding: '\n',
+    entrySpacing: 1,
+    sectionSpacing: 1,
+    useAsterisks: false,
+};
+/**
+ * Merges user options with defaults.
+ *
+ * @param options - User-provided options
+ * @returns Complete options with defaults applied
+ */
+function resolveOptions(options) {
+    {
+        return DEFAULT_SERIALIZE_OPTIONS;
+    }
+}
+/**
+ * Gets the heading for a section type, respecting custom headings.
+ *
+ * @param type - The changelog section type to get the heading for
+ * @param customHeadings - Optional map of custom section type to heading overrides
+ * @returns The heading string to use
+ */
+function getSectionHeading(type, customHeadings) {
+    return customHeadings?.[type] ?? SECTION_HEADINGS[type];
+}
+/**
+ * Creates a markdown link.
+ *
+ * @param text - The display text for the link
+ * @param url - The destination URL for the link
+ * @returns Formatted markdown link
+ */
+function formatLink(text, url) {
+    return `[${text}](${url})`;
+}
+/**
+ * Creates a list item marker.
+ *
+ * @param useAsterisks - Whether to use * instead of -
+ * @returns The list item marker ('- ' or '* ')
+ */
+function getListMarker(useAsterisks) {
+    return useAsterisks ? '* ' : '- ';
+}
+/**
+ * Creates blank lines for spacing.
+ *
+ * @param count - Number of blank lines
+ * @param lineEnding - Line ending style
+ * @returns String with specified number of blank lines
+ */
+function createSpacing(count, lineEnding) {
+    if (count <= 0)
+        return '';
+    return lineEnding.repeat(count);
+}
+
+/**
+ * Changelog Serialization to String
+ *
+ * Converts a Changelog object back to markdown format.
+ * Supports configurable output formatting for different changelog styles.
+ */
+/**
+ * Serializes a Changelog object to markdown string.
+ *
+ * @param changelog - The changelog to serialize
+ * @param options - Optional serialization options
+ * @returns The markdown string representation
+ *
+ * @example
+ * ```ts
+ * const markdown = serializeChangelog(changelog)
+ * ```
+ *
+ * @example
+ * ```ts
+ * const markdown = serializeChangelog(changelog, {
+ *   includeCommits: false,
+ *   useAsterisks: true,
+ * })
+ * ```
+ */
+function serializeChangelog(changelog, options) {
+    const opts = resolveOptions();
+    const parts = [];
+    // Serialize header
+    parts.push(serializeHeader(changelog.header, opts));
+    // Serialize entries
+    for (let i = 0; i < changelog.entries.length; i++) {
+        const entry = changelog.entries[i];
+        parts.push(serializeEntry(entry, opts));
+        // Add spacing between entries (except after the last one)
+        if (i < changelog.entries.length - 1) {
+            parts.push(createSpacing(opts.entrySpacing, opts.lineEnding));
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Serializes the changelog header.
+ *
+ * @param header - The header to serialize
+ * @param opts - Resolved options
+ * @returns The serialized header string
+ */
+function serializeHeader(header, opts) {
+    const parts = [];
+    const nl = opts.lineEnding;
+    // Title
+    parts.push(header.title + nl);
+    parts.push(nl);
+    // Description
+    if (opts.includeDescription && header.description.length > 0) {
+        for (const line of header.description) {
+            parts.push(line + nl);
+        }
+        parts.push(nl);
+    }
+    // Links section
+    if (opts.includeLinks && header.links.length > 0) {
+        for (const link of header.links) {
+            parts.push(serializeLink(link) + nl);
+        }
+        parts.push(nl);
+    }
+    return parts.join('');
+}
+/**
+ * Serializes a changelog link.
+ *
+ * @param link - The link to serialize
+ * @returns The serialized link
+ */
+function serializeLink(link) {
+    return `[${link.label}]: ${link.url}`;
+}
+/**
+ * Serializes a changelog entry.
+ *
+ * @param entry - The entry to serialize
+ * @param opts - Resolved options
+ * @returns The serialized entry string
+ */
+function serializeEntry(entry, opts) {
+    const parts = [];
+    const nl = opts.lineEnding;
+    // Entry heading
+    parts.push(serializeEntryHeading(entry, opts) + nl);
+    parts.push(nl);
+    // Raw content fallback
+    if (opts.includeRawContent && entry.rawContent) {
+        parts.push(entry.rawContent + nl);
+        return parts.join('');
+    }
+    // Sort sections by specified order
+    const sortedSections = sortSections(entry.sections, opts.sectionOrder);
+    // Serialize sections
+    for (let i = 0; i < sortedSections.length; i++) {
+        const section = sortedSections[i];
+        parts.push(serializeSection(section, opts));
+        // Add spacing between sections (except after the last one)
+        if (i < sortedSections.length - 1) {
+            parts.push(createSpacing(opts.sectionSpacing, nl));
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Serializes an entry heading.
+ *
+ * @param entry - The changelog entry to serialize the heading for
+ * @param opts - Resolved serialization options
+ * @returns The heading line
+ */
+function serializeEntryHeading(entry, opts) {
+    const parts = ['## '];
+    // Version with optional compare URL
+    if (opts.includeCompareUrls && entry.compareUrl) {
+        parts.push(formatLink(entry.version, entry.compareUrl));
+    }
+    else {
+        parts.push(entry.version);
+    }
+    // Date
+    if (entry.date) {
+        parts.push(` - ${entry.date}`);
+    }
+    return parts.join('');
+}
+/**
+ * Sorts sections by the specified order.
+ *
+ * @param sections - The sections to sort
+ * @param order - The desired section order
+ * @returns Sorted sections
+ */
+function sortSections(sections, order) {
+    const orderMap = createMap();
+    order.forEach((type, index) => orderMap.set(type, index));
+    return [...sections].sort((a, b) => {
+        const orderA = orderMap.get(a.type) ?? Number.MAX_SAFE_INTEGER;
+        const orderB = orderMap.get(b.type) ?? Number.MAX_SAFE_INTEGER;
+        return orderA - orderB;
+    });
+}
+/**
+ * Serializes a changelog section.
+ *
+ * @param section - The section to serialize
+ * @param opts - Resolved options
+ * @returns The serialized section string
+ */
+function serializeSection(section, opts) {
+    const parts = [];
+    const nl = opts.lineEnding;
+    // Section heading - use original heading if available, otherwise generate
+    const heading = section.heading || getSectionHeading(section.type, opts.sectionHeadings);
+    parts.push(`### ${heading}${nl}`);
+    parts.push(nl);
+    // Items
+    for (const item of section.items) {
+        parts.push(serializeItem(item, opts) + nl);
+    }
+    return parts.join('');
+}
+/**
+ * Serializes a changelog item.
+ *
+ * @param item - The item to serialize
+ * @param opts - Resolved options
+ * @returns The serialized item string
+ */
+function serializeItem(item, opts) {
+    const parts = [];
+    const marker = getListMarker(opts.useAsterisks);
+    parts.push(marker);
+    // Breaking change indicator
+    if (item.breaking) {
+        parts.push('**BREAKING** ');
+    }
+    // Scope
+    if (opts.includeScope && item.scope) {
+        parts.push(`**${item.scope}:** `);
+    }
+    // Description
+    parts.push(item.description);
+    // Commit references
+    if (opts.includeCommits && item.commits.length > 0) {
+        parts.push(' (');
+        parts.push(item.commits.map(serializeCommitRef).join(', '));
+        parts.push(')');
+    }
+    // Issue/PR references
+    if (opts.includeReferences && item.references.length > 0) {
+        const refs = item.references.map(serializeIssueRef).join(', ');
+        parts.push(` ${refs}`);
+    }
+    return parts.join('');
+}
+/**
+ * Serializes a commit reference.
+ *
+ * @param ref - The commit reference
+ * @returns The serialized reference
+ */
+function serializeCommitRef(ref) {
+    if (ref.url) {
+        return formatLink(ref.shortHash, ref.url);
+    }
+    return ref.shortHash;
+}
+/**
+ * Serializes an issue/PR reference.
+ *
+ * @param ref - The issue reference
+ * @returns The serialized reference
+ */
+function serializeIssueRef(ref) {
+    const text = `#${ref.number}`;
+    if (ref.url) {
+        return formatLink(text, ref.url);
+    }
+    return text;
+}
+
+/**
+ * Changelog Entry Addition
+ *
+ * Functions for adding new entries to a changelog.
+ */
+/**
+ * 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
+ * ```ts
+ * const newChangelog = addEntry(changelog, {
+ *   version: '1.2.0',
+ *   date: '2024-01-15',
+ *   unreleased: false,
+ *   sections: [...]
+ * })
+ * ```
+ */
+function addEntry(changelog, entry, options) {
+    // Check for existing entry
+    const existingIndex = changelog.entries.findIndex((e) => e.version === entry.version);
+    if (existingIndex !== -1 && true) {
+        throw createError(`Entry with version "${entry.version}" already exists. Use replaceExisting: true to replace.`);
+    }
+    let newEntries;
+    {
+        // Add new entry
+        const insertIndex = 0 ;
+        newEntries = [...changelog.entries];
+        newEntries.splice(insertIndex, 0, entry);
+    }
+    // Build new metadata if requested
+    const metadata = changelog.metadata;
+    return {
+        ...changelog,
+        entries: newEntries,
+        metadata,
+    };
+}
+
+const GENERATE_CHANGELOG_STEP_ID = 'generate-changelog';
+/**
+ * Maps conventional commit types to changelog section types.
+ */
+const COMMIT_TYPE_TO_SECTION = {
+    feat: 'features',
+    fix: 'fixes',
+    perf: 'performance',
+    docs: 'documentation',
+    refactor: 'refactoring',
+    revert: 'other',
+    build: 'build',
+    ci: 'ci',
+    test: 'tests',
+    chore: 'chores',
+    style: 'other',
+};
+/**
+ * Groups commits by their section type.
+ *
+ * @param commits - Array of conventional commits
+ * @returns Record of section type to commits
+ */
+function groupCommitsBySection(commits) {
+    const groups = {};
+    for (const commit of commits) {
+        const sectionType = COMMIT_TYPE_TO_SECTION[commit.type ?? 'chore'] ?? 'chores';
+        if (!groups[sectionType]) {
+            groups[sectionType] = [];
+        }
+        groups[sectionType].push(commit);
+    }
+    return groups;
+}
+/**
+ * Creates a changelog item from a conventional commit.
+ *
+ * @param commit - The conventional commit
+ * @returns A changelog item
+ */
+function commitToItem(commit) {
+    let text = commit.subject;
+    // Add scope prefix if present
+    if (commit.scope) {
+        text = `**${commit.scope}:** ${text}`;
+    }
+    // Add breaking change indicator
+    if (commit.breaking) {
+        text = `⚠️ BREAKING: ${text}`;
+    }
+    return createChangelogItem(text);
+}
+/**
+ * Creates the generate-changelog step.
+ *
+ * This step:
+ * 1. Groups commits by type/section
+ * 2. Creates changelog items from commits
+ * 3. Assembles a complete changelog entry
+ *
+ * State updates:
+ * - changelogEntry: The generated ChangelogEntry
+ *
+ * @returns A FlowStep that generates changelog
+ */
+function createGenerateChangelogStep() {
+    return createStep(GENERATE_CHANGELOG_STEP_ID, 'Generate Changelog Entry', async (ctx) => {
+        const { config, state } = ctx;
+        const { commits, nextVersion, bumpType } = state;
+        // Skip if no bump needed
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No version bump, skipping changelog generation');
+        }
+        // Skip if changelog disabled
+        if (config.skipChangelog) {
+            return createSkippedResult('Changelog generation disabled');
+        }
+        // Handle case with no commits (e.g., first release)
+        if (!commits || commits.length === 0) {
+            const entry = createChangelogEntry(nextVersion, {
+                date: createDate().toISOString().split('T')[0],
+                sections: [createChangelogSection('features', 'Features', [createChangelogItem('Initial release')])],
+            });
+            return {
+                status: 'success',
+                stateUpdates: { changelogEntry: entry },
+                message: 'Generated initial release changelog entry',
+            };
+        }
+        // Group commits by section
+        const grouped = groupCommitsBySection(commits);
+        // Create sections
+        const sections = [];
+        // Add breaking changes section first if any
+        const breakingCommits = commits.filter((c) => c.breaking);
+        if (breakingCommits.length > 0) {
+            sections.push(createChangelogSection('breaking', 'Breaking Changes', breakingCommits.map((c) => {
+                const text = c.breakingDescription ?? c.subject;
+                return createChangelogItem(c.scope ? `**${c.scope}:** ${text}` : text);
+            })));
+        }
+        // Add other sections in conventional order
+        const sectionOrder = [
+            { type: 'features', heading: 'Features' },
+            { type: 'fixes', heading: 'Bug Fixes' },
+            { type: 'performance', heading: 'Performance' },
+            { type: 'documentation', heading: 'Documentation' },
+            { type: 'refactoring', heading: 'Code Refactoring' },
+            { type: 'build', heading: 'Build' },
+            { type: 'ci', heading: 'Continuous Integration' },
+            { type: 'tests', heading: 'Tests' },
+            { type: 'chores', heading: 'Chores' },
+            { type: 'other', heading: 'Other' },
+        ];
+        for (const { type: sectionType, heading } of sectionOrder) {
+            const sectionCommits = grouped[sectionType];
+            if (sectionCommits && sectionCommits.length > 0) {
+                sections.push(createChangelogSection(sectionType, heading, sectionCommits.map(commitToItem)));
+            }
+        }
+        // Create the entry
+        const entry = createChangelogEntry(nextVersion, {
+            date: createDate().toISOString().split('T')[0],
+            sections,
+        });
+        return {
+            status: 'success',
+            stateUpdates: { changelogEntry: entry },
+            message: `Generated changelog with ${sections.length} section(s), ${commits.length} commit(s)`,
+        };
+    }, {
+        dependsOn: ['check-idempotency'],
+    });
+}
+/**
+ * Creates the write-changelog step.
+ *
+ * This step writes the generated changelog entry to CHANGELOG.md.
+ *
+ * @returns A FlowStep that writes changelog to file
+ */
+function createWriteChangelogStep() {
+    return createStep('write-changelog', 'Write Changelog', async (ctx) => {
+        const { tree, projectRoot, config, state, logger } = ctx;
+        const { changelogEntry, nextVersion, bumpType } = state;
+        // Skip if no bump or no changelog
+        if (!nextVersion || bumpType === 'none' || !changelogEntry || config.skipChangelog) {
+            return createSkippedResult('No changelog to write');
+        }
+        const changelogPath = `${projectRoot}/CHANGELOG.md`;
+        let existingContent = '';
+        // Read existing changelog
+        try {
+            existingContent = tree.read(changelogPath, 'utf-8') ?? '';
+        }
+        catch {
+            logger.debug('No existing CHANGELOG.md found');
+        }
+        // If no existing content, create new changelog
+        if (!existingContent.trim()) {
+            const newChangelog = {
+                header: {
+                    title: '# Changelog',
+                    description: ['All notable changes to this project will be documented in this file.'],
+                    links: [],
+                },
+                entries: [changelogEntry]};
+            const serialized = serializeChangelog(newChangelog);
+            tree.write(changelogPath, serialized);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    modifiedFiles: [...(state.modifiedFiles ?? []), changelogPath],
+                },
+                message: `Created CHANGELOG.md with version ${nextVersion}`,
+            };
+        }
+        // Parse existing and add entry
+        const existing = parseChangelog(existingContent);
+        const updated = addEntry(existing, changelogEntry);
+        const serialized = serializeChangelog(updated);
+        tree.write(changelogPath, serialized);
+        return {
+            status: 'success',
+            stateUpdates: {
+                modifiedFiles: [...(state.modifiedFiles ?? []), changelogPath],
+            },
+            message: `Updated CHANGELOG.md with version ${nextVersion}`,
+        };
+    }, {
+        dependsOn: ['generate-changelog'],
+    });
+}
+
+const UPDATE_PACKAGES_STEP_ID = 'update-packages';
+/**
+ * Creates the update-packages step.
+ *
+ * This step:
+ * 1. Updates the version field in package.json
+ * 2. Tracks the modified files
+ *
+ * State updates:
+ * - modifiedFiles: Adds package.json to list
+ *
+ * @returns A FlowStep that updates package.json
+ */
+function createUpdatePackageStep() {
+    return createStep(UPDATE_PACKAGES_STEP_ID, 'Update Package Version', async (ctx) => {
+        const { tree, projectRoot, state, logger } = ctx;
+        const { nextVersion, bumpType, currentVersion } = state;
+        // Skip if no bump needed
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No version bump needed');
+        }
+        const packageJsonPath = `${projectRoot}/package.json`;
+        // Read package.json
+        let content;
+        try {
+            content = tree.read(packageJsonPath, 'utf-8') ?? '';
+            if (!content) {
+                return {
+                    status: 'failed',
+                    error: createError('package.json not found'),
+                    message: 'Could not read package.json',
+                };
+            }
+        }
+        catch (error) {
+            return {
+                status: 'failed',
+                error: error instanceof Error ? error : createError(String(error)),
+                message: 'Failed to read package.json',
+            };
+        }
+        // Parse and update version
+        let pkg;
+        try {
+            pkg = parse(content);
+        }
+        catch (error) {
+            return {
+                status: 'failed',
+                error: error instanceof Error ? error : createError(String(error)),
+                message: 'Failed to parse package.json',
+            };
+        }
+        pkg['version'] = nextVersion;
+        // Write back with preserved formatting
+        const updated = stringify(pkg, null, 2) + '\n';
+        tree.write(packageJsonPath, updated);
+        logger.info(`Updated package.json: ${currentVersion} → ${nextVersion}`);
+        return {
+            status: 'success',
+            stateUpdates: {
+                modifiedFiles: [...(state.modifiedFiles ?? []), packageJsonPath],
+            },
+            message: `Updated version to ${nextVersion}`,
+        };
+    }, {
+        dependsOn: ['calculate-bump'],
+    });
+}
+/**
+ * Creates a step that updates dependent packages in a monorepo.
+ *
+ * This step cascades version updates to packages that depend
+ * on the updated package.
+ *
+ * @returns A FlowStep that cascades dependency updates
+ */
+function createCascadeDependenciesStep() {
+    return createStep('cascade-dependencies', 'Cascade Dependency Updates', async (ctx) => {
+        const { config, state, logger } = ctx;
+        const { nextVersion, bumpType } = state;
+        // Skip if dependency tracking not enabled
+        if (!config.trackDeps) {
+            return createSkippedResult('Dependency tracking not enabled');
+        }
+        // Skip if no bump needed
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No version bump to cascade');
+        }
+        // In a full implementation, this would:
+        // 1. Use workspace discovery to find dependent packages
+        // 2. Update their dependency references
+        // 3. Track the modified files
+        logger.warn('Cascade dependencies step is not fully implemented yet');
+        return {
+            status: 'success',
+            message: 'Dependency cascade skipped (not fully implemented)',
+        };
+    }, {
+        dependsOn: ['update-packages'],
+    });
+}
+
+/**
+ * Interpolates template variables in a string.
+ *
+ * Supports: ${projectName}, ${packageName}, ${version}
+ *
+ * @param template - Template string with ${var} placeholders
+ * @param vars - Variable values
+ * @returns Interpolated string
+ */
+function interpolate(template, vars) {
+    let result = template;
+    for (const [key, value] of entries(vars)) {
+        const placeholder = '${' + key + '}';
+        let index = result.indexOf(placeholder);
+        while (index !== -1) {
+            result = result.slice(0, index) + value + result.slice(index + placeholder.length);
+            index = result.indexOf(placeholder, index + value.length);
+        }
+    }
+    return result;
+}
+
+const CREATE_COMMIT_STEP_ID = 'create-commit';
+/**
+ * Creates the create-commit step.
+ *
+ * This step:
+ * 1. Stages modified files
+ * 2. Creates a commit with the configured message
+ *
+ * State updates:
+ * - commitHash: Hash of the created commit
+ *
+ * @returns A FlowStep that creates a git commit
+ */
+function createGitCommitStep() {
+    return createStep(CREATE_COMMIT_STEP_ID, 'Create Version Commit', async (ctx) => {
+        const { git, config, state, projectName, packageName, logger } = ctx;
+        const { nextVersion, bumpType, modifiedFiles } = state;
+        // Skip if git operations disabled
+        if (config.skipGit) {
+            return createSkippedResult('Git operations disabled');
+        }
+        // Skip if no bump needed
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No version bump, no commit needed');
+        }
+        // Skip if dry run
+        if (config.dryRun) {
+            const message = interpolate(config.commitMessage ?? 'chore(${projectName}): release version ${version}', {
+                projectName,
+                packageName,
+                version: nextVersion,
+            });
+            return {
+                status: 'success',
+                message: `[DRY RUN] Would commit: "${message}"`,
+            };
+        }
+        // Stage files
+        if (modifiedFiles && modifiedFiles.length > 0) {
+            try {
+                git.stage(modifiedFiles);
+                logger.debug(`Staged ${modifiedFiles.length} file(s)`);
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    error: error instanceof Error ? error : createError(String(error)),
+                    message: 'Failed to stage files',
+                };
+            }
+        }
+        else {
+            // Stage all changes
+            try {
+                git.stageAll();
+                logger.debug('Staged all changes');
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    error: error instanceof Error ? error : createError(String(error)),
+                    message: 'Failed to stage files',
+                };
+            }
+        }
+        // Create commit message
+        const message = interpolate(config.commitMessage ?? 'chore(${projectName}): release version ${version}', {
+            projectName,
+            packageName,
+            version: nextVersion,
+        });
+        // Create commit
+        try {
+            const commit = git.createCommit(message);
+            logger.info(`Created commit: ${commit.hash.slice(0, 7)}`);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    commitHash: commit.hash,
+                },
+                message: `Created commit ${commit.hash.slice(0, 7)}: ${message}`,
+            };
+        }
+        catch (error) {
+            return {
+                status: 'failed',
+                error: error instanceof Error ? error : createError(String(error)),
+                message: 'Failed to create commit',
+            };
+        }
+    }, {
+        dependsOn: ['update-packages', 'write-changelog'],
+    });
+}
+
+const CREATE_TAG_STEP_ID = 'create-tag';
+/**
+ * Creates the create-tag step.
+ *
+ * This step:
+ * 1. Creates an annotated git tag
+ * 2. Uses the configured tag format
+ *
+ * State updates:
+ * - tagName: Name of the created tag
+ *
+ * @returns A FlowStep that creates a git tag
+ */
+function createTagStep() {
+    return createStep(CREATE_TAG_STEP_ID, 'Create Git Tag', async (ctx) => {
+        const { git, config, state, projectName, packageName, logger } = ctx;
+        const { nextVersion, bumpType, changelogEntry } = state;
+        // Skip if git operations disabled
+        if (config.skipGit) {
+            return createSkippedResult('Git operations disabled');
+        }
+        // Skip if tags disabled
+        if (config.skipTag) {
+            return createSkippedResult('Tag creation disabled');
+        }
+        // Skip if no bump needed
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No version bump, no tag needed');
+        }
+        // Generate tag name
+        const tagName = interpolate(config.tagFormat ?? '${projectName}@${version}', {
+            projectName,
+            packageName,
+            version: nextVersion,
+        });
+        // Skip if dry run
+        if (config.dryRun) {
+            return {
+                status: 'success',
+                stateUpdates: { tagName },
+                message: `[DRY RUN] Would create tag: ${tagName}`,
+            };
+        }
+        // Create tag message from changelog entry if available
+        let tagMessage = `Release ${nextVersion}`;
+        if (changelogEntry && changelogEntry.sections.length > 0) {
+            const highlights = [];
+            for (const section of changelogEntry.sections.slice(0, 3)) {
+                const itemCount = section.items.length;
+                highlights.push(`${section.type}: ${itemCount} change${itemCount !== 1 ? 's' : ''}`);
+            }
+            tagMessage = `Release ${nextVersion}\n\n${highlights.join('\n')}`;
+        }
+        // Create tag
+        try {
+            const tag = git.createTag(tagName, {
+                message: tagMessage,
+            });
+            logger.info(`Created tag: ${tag.name}`);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    tagName: tag.name,
+                },
+                message: `Created tag: ${tagName}`,
+            };
+        }
+        catch (error) {
+            return {
+                status: 'failed',
+                error: error instanceof Error ? error : createError(String(error)),
+                message: `Failed to create tag: ${tagName}`,
+            };
+        }
+    }, {
+        dependsOn: ['create-commit'],
+    });
+}
+
+/**
+ * Default configuration for conventional flow.
+ */
+const CONVENTIONAL_FLOW_CONFIG = {
+    preset: 'conventional',
+    releaseTypes: ['feat', 'fix', 'perf', 'revert'],
+    minorTypes: ['feat'],
+    patchTypes: ['fix', 'perf', 'revert'],
+    skipGit: false,
+    skipTag: true, // Tags typically created after publish
+    skipChangelog: false,
+    dryRun: false,
+    commitMessage: 'chore(${projectName}): release version ${version}',
+    tagFormat: '${projectName}@${version}',
+    trackDeps: false,
+    firstReleaseVersion: '0.1.0',
+};
+/**
+ * Creates a conventional flow.
+ *
+ * This flow follows the standard conventional commits workflow:
+ * 1. Fetch published version from registry
+ * 2. Analyze commits since last release
+ * 3. Calculate version bump based on commit types
+ * 4. Check if version already published (idempotency)
+ * 5. Generate changelog entry
+ * 6. Update package.json version
+ * 7. Write changelog to file
+ * 8. Create git commit (optional)
+ * 9. Create git tag (optional, typically after publish)
+ *
+ * @param config - Optional configuration overrides
+ * @returns A VersionFlow configured for conventional commits
+ *
+ * @example
+ * ```typescript
+ * import { createConventionalFlow, executeFlow } from '@hyperfrontend/versioning'
+ *
+ * // Use defaults
+ * const flow = createConventionalFlow()
+ *
+ * // With overrides
+ * const customFlow = createConventionalFlow({
+ *   skipTag: false,
+ *   releaseTypes: ['feat', 'fix'],
+ * })
+ *
+ * const result = await executeFlow(flow, 'lib-utils', '/workspace')
+ * ```
+ */
+function createConventionalFlow(config) {
+    const mergedConfig = { ...CONVENTIONAL_FLOW_CONFIG, ...config };
+    return createFlow('conventional', 'Conventional Commits Flow', [
+        createFetchRegistryStep(),
+        createAnalyzeCommitsStep(),
+        createCalculateBumpStep(),
+        createCheckIdempotencyStep(),
+        createGenerateChangelogStep(),
+        createUpdatePackageStep(),
+        createWriteChangelogStep(),
+        createGitCommitStep(),
+        createTagStep(),
+    ], {
+        description: 'Standard versioning using conventional commits specification',
+        config: mergedConfig,
+    });
+}
+/**
+ * Creates a minimal flow for quick releases.
+ *
+ * Skips changelog and tag creation.
+ *
+ * @param config - Optional configuration overrides
+ * @returns A minimal VersionFlow
+ */
+function createMinimalFlow(config) {
+    return createConventionalFlow({
+        skipChangelog: true,
+        skipTag: true,
+        ...config,
+    });
+}
+/**
+ * Creates a changelog-only flow.
+ *
+ * Only generates changelog, no version bumps or git operations.
+ *
+ * @param config - Optional configuration overrides
+ * @returns A VersionFlow that only updates changelog
+ */
+function createChangelogOnlyFlow(config) {
+    return createFlow('changelog-only', 'Changelog Only Flow', [
+        createFetchRegistryStep(),
+        createAnalyzeCommitsStep(),
+        createCalculateBumpStep(),
+        createGenerateChangelogStep(),
+        createWriteChangelogStep(),
+    ], {
+        description: 'Generate changelog without version bump or git operations',
+        config: {
+            ...CONVENTIONAL_FLOW_CONFIG,
+            skipGit: true,
+            skipTag: true,
+            ...config,
+        },
+    });
+}
+
+/**
+ * Default configuration for independent flow.
+ */
+const INDEPENDENT_FLOW_CONFIG = {
+    ...CONVENTIONAL_FLOW_CONFIG,
+    preset: 'independent',
+    trackDeps: true,
+};
+/**
+ * Creates a step that checks for dependent package bumps.
+ *
+ * In independent versioning, when a dependency is bumped,
+ * dependents may also need version bumps.
+ *
+ * @returns A FlowStep that checks dependent bumps
+ */
+function createCheckDependentBumpsStep() {
+    return createStep('check-dependent-bumps', 'Check Dependent Bumps', async (ctx) => {
+        const { config, state, logger } = ctx;
+        const { bumpType, nextVersion } = state;
+        // Skip if dependency tracking not enabled
+        if (!config.trackDeps) {
+            return createSkippedResult('Dependency tracking not enabled');
+        }
+        // Skip if no bump needed for this package
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No bump to propagate');
+        }
+        // In a full implementation, this would:
+        // 1. Load workspace dependency graph
+        // 2. Find packages that depend on this one
+        // 3. Mark them for potential bumps
+        logger.debug('Dependent bump checking not fully implemented');
+        return {
+            status: 'success',
+            message: 'Dependent bump check complete (basic implementation)',
+        };
+    }, {
+        dependsOn: ['calculate-bump'],
+    });
+}
+/**
+ * Creates an independent versioning flow.
+ *
+ * This flow is designed for monorepos where each package
+ * is versioned independently:
+ *
+ * 1. Fetch published version from registry
+ * 2. Analyze commits since last release
+ * 3. Calculate version bump based on commit types
+ * 4. Check for dependent package bumps (cascade)
+ * 5. Check if version already published (idempotency)
+ * 6. Generate changelog entry
+ * 7. Update package.json version
+ * 8. Cascade dependency updates
+ * 9. Write changelog to file
+ * 10. Create git commit
+ * 11. Create git tag
+ *
+ * @param config - Optional configuration overrides
+ * @returns A VersionFlow configured for independent versioning
+ *
+ * @example
+ * ```typescript
+ * import { createIndependentFlow, executeFlow } from '@hyperfrontend/versioning'
+ *
+ * const flow = createIndependentFlow()
+ * const result = await executeFlow(flow, 'lib-utils', '/workspace')
+ *
+ * // Check which dependents were bumped
+ * console.log(result.state.cascadedBumps)
+ * ```
+ */
+function createIndependentFlow(config) {
+    const mergedConfig = { ...INDEPENDENT_FLOW_CONFIG, ...config };
+    return createFlow('independent', 'Independent Versioning Flow', [
+        createFetchRegistryStep(),
+        createAnalyzeCommitsStep(),
+        createCalculateBumpStep(),
+        createCheckDependentBumpsStep(),
+        createCheckIdempotencyStep(),
+        createGenerateChangelogStep(),
+        createUpdatePackageStep(),
+        createCascadeDependenciesStep(),
+        createWriteChangelogStep(),
+        createGitCommitStep(),
+        createTagStep(),
+    ], {
+        description: 'Version packages independently with dependency tracking',
+        config: mergedConfig,
+    });
+}
+/**
+ * Creates a flow for releasing multiple packages independently.
+ *
+ * This is a variant that skips commit/tag creation, intended
+ * to be used when releasing multiple packages in sequence
+ * with a single commit at the end.
+ *
+ * @param config - Optional configuration overrides
+ * @returns A VersionFlow for batch independent releases
+ */
+function createBatchReleaseFlow(config) {
+    return createFlow('batch-release', 'Batch Release Flow', [
+        createFetchRegistryStep(),
+        createAnalyzeCommitsStep(),
+        createCalculateBumpStep(),
+        createCheckIdempotencyStep(),
+        createGenerateChangelogStep(),
+        createUpdatePackageStep(),
+        createWriteChangelogStep(),
+    ], {
+        description: 'Prepare release without committing (for batch releases)',
+        config: {
+            ...INDEPENDENT_FLOW_CONFIG,
+            skipGit: true,
+            skipTag: true,
+            ...config,
+        },
+    });
+}
+
+/**
+ * Default configuration for synced flow.
+ */
+const SYNCED_FLOW_CONFIG = {
+    ...CONVENTIONAL_FLOW_CONFIG,
+    preset: 'synced',
+    tagFormat: 'v${version}', // Single tag for all packages
+    commitMessage: 'chore: release version ${version}',
+};
+/**
+ * Creates a step that updates all workspace packages to the same version.
+ *
+ * @returns A FlowStep that syncs all package versions
+ */
+function createSyncAllPackagesStep() {
+    return createStep('sync-all-packages', 'Sync All Package Versions', async (ctx) => {
+        const { tree, workspaceRoot, state, logger } = ctx;
+        const { nextVersion, bumpType } = state;
+        // Skip if no bump needed
+        if (!nextVersion || bumpType === 'none') {
+            return createSkippedResult('No version bump needed');
+        }
+        // In a full implementation, this would:
+        // 1. Discover all workspace packages
+        // 2. Update each package.json to the same version
+        // 3. Update cross-references between packages
+        // For now, just update the root package.json as a demo
+        const rootPackageJson = `${workspaceRoot}/package.json`;
+        const modifiedFiles = [];
+        try {
+            const content = tree.read(rootPackageJson, 'utf-8');
+            if (content) {
+                const pkg = parse(content);
+                pkg['version'] = nextVersion;
+                tree.write(rootPackageJson, stringify(pkg, null, 2) + '\n');
+                modifiedFiles.push(rootPackageJson);
+                logger.info(`Updated root package.json to ${nextVersion}`);
+            }
+        }
+        catch (error) {
+            logger.warn(`Could not update root package.json: ${error}`);
+        }
+        return {
+            status: 'success',
+            stateUpdates: {
+                modifiedFiles: [...(state.modifiedFiles ?? []), ...modifiedFiles],
+            },
+            message: `Synced ${modifiedFiles.length} package(s) to version ${nextVersion}`,
+        };
+    }, {
+        dependsOn: ['calculate-bump'],
+    });
+}
+/**
+ * Creates a step that generates a combined changelog for all packages.
+ *
+ * @returns A FlowStep that creates a combined changelog
+ */
+function createCombinedChangelogStep() {
+    return createStep('combined-changelog', 'Generate Combined Changelog', async (ctx) => {
+        const { config, state, logger } = ctx;
+        const { nextVersion, bumpType } = state;
+        // Skip if no bump or changelog disabled
+        if (!nextVersion || bumpType === 'none' || config.skipChangelog) {
+            return createSkippedResult('No changelog to generate');
+        }
+        // In a synced flow, we generate a single changelog at the workspace root
+        // This is a simplified version - full implementation would aggregate
+        // commits from all packages
+        logger.info('Generating combined changelog for workspace');
+        // Reuse the standard changelog generation
+        // The actual entry is generated by createGenerateChangelogStep
+        return {
+            status: 'success',
+            message: 'Combined changelog preparation complete',
+        };
+    }, {
+        dependsOn: ['check-idempotency'],
+    });
+}
+/**
+ * Creates a synced versioning flow.
+ *
+ * This flow maintains the same version across all packages
+ * in a monorepo. When any package changes, all packages
+ * get the same new version.
+ *
+ * Flow steps:
+ * 1. Fetch published version from registry
+ * 2. Analyze commits across all packages
+ * 3. Calculate version bump (highest needed)
+ * 4. Check if version already published
+ * 5. Sync all package versions
+ * 6. Generate combined changelog
+ * 7. Write changelog to root
+ * 8. Create git commit
+ * 9. Create single git tag
+ *
+ * @param config - Optional configuration overrides
+ * @returns A VersionFlow configured for synced versioning
+ *
+ * @example
+ * ```typescript
+ * import { createSyncedFlow, executeFlow } from '@hyperfrontend/versioning'
+ *
+ * const flow = createSyncedFlow()
+ * const result = await executeFlow(flow, 'workspace', '/workspace')
+ *
+ * // All packages now share the same version
+ * console.log(`Released v${result.state.nextVersion}`)
+ * ```
+ */
+function createSyncedFlow(config) {
+    const mergedConfig = { ...SYNCED_FLOW_CONFIG, ...config };
+    return createFlow('synced', 'Synced Versioning Flow', [
+        createFetchRegistryStep(),
+        createAnalyzeCommitsStep(),
+        createCalculateBumpStep(),
+        createCheckIdempotencyStep(),
+        createSyncAllPackagesStep(),
+        createCombinedChangelogStep(),
+        createGenerateChangelogStep(),
+        createWriteChangelogStep(),
+        createGitCommitStep(),
+        createTagStep(),
+    ], {
+        description: 'Keep all packages at the same version',
+        config: mergedConfig,
+    });
+}
+/**
+ * Creates a fixed versioning flow.
+ *
+ * Similar to synced, but uses a fixed version scheme
+ * where the version is explicitly provided rather than
+ * calculated from commits.
+ *
+ * @param version - The fixed version to use
+ * @param config - Optional configuration overrides
+ * @returns A VersionFlow with a fixed version
+ */
+function createFixedVersionFlow(version, config) {
+    // Override the calculate-bump step to use fixed version
+    const fixedBumpStep = createStep('calculate-bump', 'Use Fixed Version', async () => ({
+        status: 'success',
+        stateUpdates: {
+            bumpType: 'minor', // Arbitrary, version is fixed
+            nextVersion: version,
+        },
+        message: `Using fixed version: ${version}`,
+    }), {
+        dependsOn: ['analyze-commits'],
+    });
+    return createFlow('fixed', 'Fixed Version Flow', [
+        createFetchRegistryStep(),
+        createAnalyzeCommitsStep(),
+        fixedBumpStep,
+        createCheckIdempotencyStep(),
+        createSyncAllPackagesStep(),
+        createCombinedChangelogStep(),
+        createGenerateChangelogStep(),
+        createWriteChangelogStep(),
+        createGitCommitStep(),
+        createTagStep(),
+    ], {
+        description: `Release with fixed version ${version}`,
+        config: { ...SYNCED_FLOW_CONFIG, ...config },
+    });
+}
+
+exports.CONVENTIONAL_FLOW_CONFIG = CONVENTIONAL_FLOW_CONFIG;
+exports.INDEPENDENT_FLOW_CONFIG = INDEPENDENT_FLOW_CONFIG;
+exports.SYNCED_FLOW_CONFIG = SYNCED_FLOW_CONFIG;
+exports.createBatchReleaseFlow = createBatchReleaseFlow;
+exports.createChangelogOnlyFlow = createChangelogOnlyFlow;
+exports.createCheckDependentBumpsStep = createCheckDependentBumpsStep;
+exports.createCombinedChangelogStep = createCombinedChangelogStep;
+exports.createConventionalFlow = createConventionalFlow;
+exports.createFixedVersionFlow = createFixedVersionFlow;
+exports.createIndependentFlow = createIndependentFlow;
+exports.createMinimalFlow = createMinimalFlow;
+exports.createSyncAllPackagesStep = createSyncAllPackagesStep;
+exports.createSyncedFlow = createSyncedFlow;
+//# sourceMappingURL=index.cjs.js.map