@hyperfrontend/versioning 0.1.0 → 0.2.0

package/flow/presets/index.cjs.js

@@ -1,5 +1,8 @@
 'use strict';
 
+var node_path = require('node:path');
+var node_fs = require('node:fs');
+
 /**
  * Creates a version flow.
  *
@@ -85,98 +88,2714 @@ function createStep(id, name, execute, options = {}) {
     };
 }
 /**
- * Creates a skipped step result.
+ * 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 publishedCommit = null;
+        let isFirstRelease = true;
+        try {
+            publishedVersion = await registry.getLatestVersion(packageName);
+            isFirstRelease = publishedVersion === null;
+            // When published version exists, get its commit hash from gitHead
+            if (publishedVersion) {
+                try {
+                    const versionInfo = await registry.getVersionInfo(packageName, publishedVersion);
+                    publishedCommit = versionInfo?.gitHead ?? null;
+                    if (publishedCommit) {
+                        logger.debug(`Published ${publishedVersion} at commit ${publishedCommit.slice(0, 7)}`);
+                    }
+                    else {
+                        logger.debug(`Published ${publishedVersion} has no gitHead (older package or published without git)`);
+                    }
+                }
+                catch (error) {
+                    // Version info fetch failed, but we still have the version
+                    logger.debug(`Could not fetch version info for ${publishedVersion}: ${error}`);
+                }
+            }
+        }
+        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}${publishedCommit ? ` @ ${publishedCommit.slice(0, 7)}` : ''}, Local: ${currentVersion}`;
+        return {
+            status: 'success',
+            stateUpdates: {
+                publishedVersion,
+                publishedCommit,
+                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$4 = 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$4.construct(_Error, [message, options]);
+
+/**
+ * Creates a new RepositoryConfig.
+ *
+ * Normalizes the base URL by stripping trailing slashes and validating
+ * that custom platforms have a formatter function.
+ *
+ * @param options - Repository configuration options
+ * @returns A new RepositoryConfig object
+ * @throws {Error} if platform is 'custom' but no formatCompareUrl is provided
+ *
+ * @example
+ * ```typescript
+ * // GitHub repository
+ * const config = createRepositoryConfig({
+ *   platform: 'github',
+ *   baseUrl: 'https://github.com/owner/repo'
+ * })
+ *
+ * // Custom platform
+ * const customConfig = createRepositoryConfig({
+ *   platform: 'custom',
+ *   baseUrl: 'https://my-git.internal/repo',
+ *   formatCompareUrl: (from, to) => `https://my-git.internal/diff/${from}/${to}`
+ * })
+ * ```
+ */
+function createRepositoryConfig(options) {
+    const { platform, formatCompareUrl } = options;
+    // Validate custom platform has formatter
+    if (platform === 'custom' && !formatCompareUrl) {
+        throw createError("Repository config with platform 'custom' requires a formatCompareUrl function");
+    }
+    // Normalize base URL - strip trailing slashes
+    const baseUrl = normalizeBaseUrl(options.baseUrl);
+    return {
+        platform,
+        baseUrl,
+        formatCompareUrl,
+    };
+}
+/**
+ * Checks if a value is a RepositoryConfig object.
+ *
+ * @param value - Value to check
+ * @returns True if the value is a RepositoryConfig
+ *
+ * @example
+ * ```typescript
+ * const config = { platform: 'github', baseUrl: 'https://...' }
+ * if (isRepositoryConfig(config)) {
+ *   // config is typed as RepositoryConfig
+ * }
+ * ```
+ */
+function isRepositoryConfig(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj['platform'] === 'string' &&
+        typeof obj['baseUrl'] === 'string' &&
+        (obj['formatCompareUrl'] === undefined || typeof obj['formatCompareUrl'] === 'function'));
+}
+/**
+ * Normalizes a base URL by stripping trailing slashes and .git suffix.
+ *
+ * @param url - URL to normalize
+ * @returns Normalized URL
+ *
+ * @internal
+ */
+function normalizeBaseUrl(url) {
+    let normalized = url.trim();
+    // Remove trailing slashes
+    while (normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    // Remove .git suffix if present
+    if (normalized.endsWith('.git')) {
+        normalized = normalized.slice(0, -4);
+    }
+    return normalized;
+}
+
+/**
+ * Creates a disabled repository resolution configuration.
+ *
+ * No compare URLs will be generated.
+ *
+ * @returns A RepositoryResolution with mode 'disabled'
+ *
+ * @example
+ * ```typescript
+ * const config = createDisabledResolution()
+ * // { mode: 'disabled' }
+ * ```
+ */
+/**
+ * Checks if a value is a RepositoryResolution object.
+ *
+ * @param value - Value to check
+ * @returns True if the value is a RepositoryResolution
+ */
+function isRepositoryResolution(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    const mode = obj['mode'];
+    return mode === 'explicit' || mode === 'inferred' || mode === 'disabled';
+}
+/**
+ * Default inference order when mode is 'inferred'.
+ */
+const DEFAULT_INFERENCE_ORDER = ['package-json', 'git-remote'];
+
+/**
+ * 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$3 = 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$3.construct(_Map, iterable ? [iterable] : []);
+
+/**
+ * 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;
+/**
+ * (Safe copy) Returns the smaller of zero or more numbers.
+ */
+const min = _Math.min;
+
+/**
+ * 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;
+const _Reflect$2 = globalThis.Reflect;
+// ============================================================================
+// URL
+// ============================================================================
+/**
+ * (Safe copy) Creates a new URL using the captured URL constructor.
+ * Use this instead of `new URL()`.
+ *
+ * @param url - The URL string to parse.
+ * @param base - Optional base URL for relative URLs.
+ * @returns A new URL instance.
+ */
+const createURL = (url, base) => _Reflect$2.construct(_URL, [url, base]);
+/**
+ * (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');
+    };
+
+/**
+ * Checks if a platform identifier is a known platform with built-in support.
+ *
+ * @param platform - Platform identifier to check
+ * @returns True if the platform is a known platform
+ *
+ * @example
+ * ```typescript
+ * isKnownPlatform('github')     // true
+ * isKnownPlatform('gitlab')     // true
+ * isKnownPlatform('custom')     // false
+ * isKnownPlatform('unknown')    // false
+ * ```
+ */
+function isKnownPlatform(platform) {
+    return platform === 'github' || platform === 'gitlab' || platform === 'bitbucket' || platform === 'azure-devops';
+}
+/**
+ * Known platform hostnames mapped to their platform type.
+ * Used for automatic platform detection from repository URLs.
+ *
+ * Includes both standard SaaS domains and common patterns for self-hosted instances.
+ */
+const PLATFORM_HOSTNAMES = createMap([
+    // GitHub
+    ['github.com', 'github'],
+    // GitLab
+    ['gitlab.com', 'gitlab'],
+    // Bitbucket
+    ['bitbucket.org', 'bitbucket'],
+    // Azure DevOps
+    ['dev.azure.com', 'azure-devops'],
+    ['visualstudio.com', 'azure-devops'],
+]);
+/**
+ * Detects platform from a hostname.
+ *
+ * First checks for exact match in known platforms, then applies heuristics
+ * for self-hosted instances (e.g., `github.company.com` → `github`).
+ *
+ * @param hostname - Hostname to detect platform from (e.g., "github.com")
+ * @returns Detected platform or 'unknown' if not recognized
+ *
+ * @example
+ * ```typescript
+ * detectPlatformFromHostname('github.com')           // 'github'
+ * detectPlatformFromHostname('gitlab.mycompany.com') // 'gitlab'
+ * detectPlatformFromHostname('custom-git.internal')  // 'unknown'
+ * ```
+ */
+function detectPlatformFromHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    // Check exact matches first
+    const exactMatch = PLATFORM_HOSTNAMES.get(normalized);
+    if (exactMatch) {
+        return exactMatch;
+    }
+    // Check for Azure DevOps legacy domain pattern
+    if (normalized.endsWith('.visualstudio.com')) {
+        return 'azure-devops';
+    }
+    // Check for Azure DevOps modern domain pattern (includes ssh.dev.azure.com)
+    if (normalized.endsWith('.azure.com')) {
+        return 'azure-devops';
+    }
+    // Heuristics for self-hosted instances
+    // GitHub Enterprise typically uses "github" in the hostname
+    if (normalized.includes('github')) {
+        return 'github';
+    }
+    // GitLab self-hosted typically uses "gitlab" in the hostname
+    if (normalized.includes('gitlab')) {
+        return 'gitlab';
+    }
+    // Bitbucket Data Center/Server might use "bitbucket" in hostname
+    if (normalized.includes('bitbucket')) {
+        return 'bitbucket';
+    }
+    return 'unknown';
+}
+
+/**
+ * Parses a git URL and extracts platform and base URL.
+ *
+ * Supports multiple URL formats:
+ * - `https://github.com/owner/repo`
+ * - `https://github.com/owner/repo.git`
+ * - `git+https://github.com/owner/repo.git`
+ * - `git://github.com/owner/repo.git`
+ * - `git@github.com:owner/repo.git` (SSH format)
+ *
+ * Handles self-hosted instances by detecting platform from hostname:
+ * - `github.mycompany.com` → `github`
+ * - `gitlab.internal.com` → `gitlab`
+ *
+ * Handles Azure DevOps URL formats:
+ * - `https://dev.azure.com/org/project/_git/repo`
+ * - `https://org.visualstudio.com/project/_git/repo`
+ *
+ * @param gitUrl - Git repository URL in any supported format
+ * @returns Parsed repository info with platform and base URL, or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * // GitHub HTTPS
+ * parseRepositoryUrl('https://github.com/owner/repo')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ *
+ * // SSH format
+ * parseRepositoryUrl('git@github.com:owner/repo.git')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ *
+ * // Azure DevOps
+ * parseRepositoryUrl('https://dev.azure.com/org/proj/_git/repo')
+ * // → { platform: 'azure-devops', baseUrl: 'https://dev.azure.com/org/proj/_git/repo' }
+ *
+ * // Self-hosted GitLab
+ * parseRepositoryUrl('https://gitlab.mycompany.com/team/project')
+ * // → { platform: 'gitlab', baseUrl: 'https://gitlab.mycompany.com/team/project' }
+ * ```
+ */
+function parseRepositoryUrl(gitUrl) {
+    if (!gitUrl || typeof gitUrl !== 'string') {
+        return null;
+    }
+    const trimmed = gitUrl.trim();
+    if (!trimmed) {
+        return null;
+    }
+    // Try SSH format first: git@hostname:path
+    const sshParsed = parseSshUrl(trimmed);
+    if (sshParsed) {
+        return sshParsed;
+    }
+    // Try HTTP(S) formats
+    const httpParsed = parseHttpUrl(trimmed);
+    if (httpParsed) {
+        return httpParsed;
+    }
+    return null;
+}
+/**
+ * Parses an SSH-style git URL.
+ *
+ * @param url - URL to parse (e.g., "git@github.com:owner/repo.git")
+ * @returns Parsed repository or null
+ *
+ * @internal
+ */
+function parseSshUrl(url) {
+    // Handle optional ssh:// prefix
+    let remaining = url;
+    if (remaining.startsWith('ssh://')) {
+        remaining = remaining.slice(6);
+    }
+    // Must start with git@
+    if (!remaining.startsWith('git@')) {
+        return null;
+    }
+    // Remove git@ prefix
+    remaining = remaining.slice(4);
+    // Find the separator (: or /)
+    const colonIndex = remaining.indexOf(':');
+    const slashIndex = remaining.indexOf('/');
+    let separatorIndex;
+    if (colonIndex === -1 && slashIndex === -1) {
+        return null;
+    }
+    else if (colonIndex === -1) {
+        separatorIndex = slashIndex;
+    }
+    else if (slashIndex === -1) {
+        separatorIndex = colonIndex;
+    }
+    else {
+        separatorIndex = min(colonIndex, slashIndex);
+    }
+    const hostname = remaining.slice(0, separatorIndex);
+    const pathPart = normalizePathPart(remaining.slice(separatorIndex + 1));
+    if (!hostname || !pathPart) {
+        return null;
+    }
+    const platform = detectPlatformFromHostname(hostname);
+    // For Azure DevOps, construct proper base URL
+    if (platform === 'azure-devops') {
+        const baseUrl = constructAzureDevOpsBaseUrl(hostname, pathPart);
+        if (baseUrl) {
+            return { platform, baseUrl };
+        }
+        return null;
+    }
+    // Standard platforms: https://hostname/path
+    const baseUrl = `https://${hostname}/${pathPart}`;
+    return { platform, baseUrl };
+}
+/**
+ * Parses an HTTP(S)-style git URL.
+ *
+ * @param url - URL to parse
+ * @returns Parsed repository or null
+ *
+ * @internal
+ */
+function parseHttpUrl(url) {
+    // Normalize various git URL prefixes to https://
+    const normalized = url
+        .replace(/^git\+/, '') // git+https:// → https://
+        .replace(/^git:\/\//, 'https://'); // git:// → https://
+    let parsed;
+    try {
+        parsed = createURL(normalized);
+    }
+    catch {
+        return null;
+    }
+    // Only support http and https protocols
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return null;
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    const platform = detectPlatformFromHostname(hostname);
+    const pathPart = normalizePathPart(parsed.pathname);
+    if (!pathPart) {
+        return null;
+    }
+    // Handle Azure DevOps special URL structure
+    if (platform === 'azure-devops') {
+        const baseUrl = constructAzureDevOpsBaseUrl(hostname, pathPart);
+        if (baseUrl) {
+            return { platform, baseUrl };
+        }
+        // If Azure DevOps URL cannot be parsed properly, return null
+        return null;
+    }
+    // Standard platforms
+    const baseUrl = `${parsed.protocol}//${hostname}/${pathPart}`;
+    return { platform, baseUrl };
+}
+/**
+ * Normalizes a path part by removing leading slashes and .git suffix.
+ *
+ * @param path - Path to normalize
+ * @returns Normalized path or null if empty
+ *
+ * @internal
+ */
+function normalizePathPart(path) {
+    let normalized = path.trim();
+    // Remove leading slashes
+    while (normalized.startsWith('/')) {
+        normalized = normalized.slice(1);
+    }
+    // Remove trailing slashes
+    while (normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    // Remove .git suffix
+    if (normalized.endsWith('.git')) {
+        normalized = normalized.slice(0, -4);
+    }
+    // Validate we have something
+    if (!normalized) {
+        return null;
+    }
+    return normalized;
+}
+/**
+ * Constructs the base URL for Azure DevOps repositories.
+ *
+ * Azure DevOps has special URL structures:
+ * - Modern: `https://dev.azure.com/{org}/{project}/_git/{repo}`
+ * - Legacy: `https://{org}.visualstudio.com/{project}/_git/{repo}`
+ * - SSH: `git@ssh.dev.azure.com:v3/{org}/{project}/{repo}`
+ *
+ * @param hostname - Hostname from the URL
+ * @param pathPart - Path portion after hostname
+ * @returns Constructed base URL or null if invalid
+ *
+ * @internal
+ */
+function constructAzureDevOpsBaseUrl(hostname, pathPart) {
+    const pathParts = pathPart.split('/');
+    // dev.azure.com format: org/project/_git/repo
+    if (hostname === 'dev.azure.com' || hostname.endsWith('.azure.com')) {
+        // Need at least: org/project/_git/repo (4 parts)
+        // Or for SSH v3: v3/org/project/repo (4 parts)
+        if (pathParts.length >= 4) {
+            // Check for v3 SSH format
+            if (pathParts[0] === 'v3') {
+                // v3/org/project/repo → https://dev.azure.com/org/project/_git/repo
+                const org = pathParts[1];
+                const project = pathParts[2];
+                const repo = pathParts[3];
+                if (org && project && repo) {
+                    return `https://dev.azure.com/${org}/${project}/_git/${repo}`;
+                }
+            }
+            // Standard format: org/project/_git/repo
+            const gitIndex = pathParts.indexOf('_git');
+            if (gitIndex >= 2 && pathParts[gitIndex + 1]) {
+                const org = pathParts.slice(0, gitIndex - 1).join('/');
+                const project = pathParts[gitIndex - 1];
+                const repo = pathParts[gitIndex + 1];
+                if (org && project && repo) {
+                    return `https://dev.azure.com/${org}/${project}/_git/${repo}`;
+                }
+            }
+        }
+        return null;
+    }
+    // visualstudio.com format: {org}.visualstudio.com/project/_git/repo
+    if (hostname.endsWith('.visualstudio.com')) {
+        const org = hostname.replace('.visualstudio.com', '');
+        const gitIndex = pathParts.indexOf('_git');
+        if (gitIndex >= 1 && pathParts[gitIndex + 1]) {
+            const project = pathParts.slice(0, gitIndex).join('/');
+            const repo = pathParts[gitIndex + 1];
+            if (project && repo) {
+                // Normalize to dev.azure.com format
+                return `https://dev.azure.com/${org}/${project}/_git/${repo}`;
+            }
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Creates a RepositoryConfig from a git URL.
+ *
+ * This is a convenience function that combines `parseRepositoryUrl` with
+ * `createRepositoryConfig` to produce a ready-to-use configuration.
+ *
+ * @param gitUrl - Git repository URL in any supported format
+ * @returns RepositoryConfig or null if URL cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * const config = createRepositoryConfigFromUrl('https://github.com/owner/repo')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ *
+ * const config = createRepositoryConfigFromUrl('git@gitlab.com:group/project.git')
+ * // → { platform: 'gitlab', baseUrl: 'https://gitlab.com/group/project' }
+ * ```
+ */
+function createRepositoryConfigFromUrl(gitUrl) {
+    const parsed = parseRepositoryUrl(gitUrl);
+    if (!parsed) {
+        return null;
+    }
+    // Don't create configs for unknown platforms as they can't generate URLs
+    if (parsed.platform === 'unknown') {
+        return null;
+    }
+    return createRepositoryConfig({
+        platform: parsed.platform,
+        baseUrl: parsed.baseUrl,
+    });
+}
+
+/**
+ * Shorthand platform prefixes supported in package.json repository field.
+ *
+ * Format: `"platform:owner/repo"` or `"owner/repo"` (defaults to GitHub)
+ *
+ * @see https://docs.npmjs.com/cli/v9/configuring-npm/package-json#repository
+ */
+const SHORTHAND_PLATFORMS = createMap([
+    ['github', 'https://github.com'],
+    ['gitlab', 'https://gitlab.com'],
+    ['bitbucket', 'https://bitbucket.org'],
+    ['gist', 'https://gist.github.com'],
+]);
+/**
+ * Infers repository configuration from package.json content.
+ *
+ * Handles multiple formats:
+ * - Shorthand: `"github:owner/repo"`, `"gitlab:group/project"`, `"bitbucket:team/repo"`
+ * - Bare shorthand: `"owner/repo"` (defaults to GitHub)
+ * - URL string: `"https://github.com/owner/repo"`
+ * - Object with URL: `{ "type": "git", "url": "https://..." }`
+ *
+ * @param packageJsonContent - Raw JSON string content of package.json
+ * @returns RepositoryConfig or null if repository cannot be inferred
+ *
+ * @example
+ * ```typescript
+ * // Shorthand format
+ * inferRepositoryFromPackageJson('{"repository": "github:owner/repo"}')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ *
+ * // URL string
+ * inferRepositoryFromPackageJson('{"repository": "https://github.com/owner/repo"}')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ *
+ * // Object format
+ * inferRepositoryFromPackageJson('{"repository": {"type": "git", "url": "https://github.com/owner/repo"}}')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ *
+ * // Bare shorthand (defaults to GitHub)
+ * inferRepositoryFromPackageJson('{"repository": "owner/repo"}')
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ * ```
+ */
+function inferRepositoryFromPackageJson(packageJsonContent) {
+    if (!packageJsonContent || typeof packageJsonContent !== 'string') {
+        return null;
+    }
+    let packageJson;
+    try {
+        packageJson = parse(packageJsonContent);
+    }
+    catch {
+        return null;
+    }
+    return inferRepositoryFromPackageJsonObject(packageJson);
+}
+/**
+ * Infers repository configuration from a parsed package.json object.
+ *
+ * This is useful when you already have the parsed object.
+ *
+ * @param packageJson - Parsed package.json object
+ * @returns RepositoryConfig or null if repository cannot be inferred
+ *
+ * @example
+ * ```typescript
+ * const pkg = { repository: 'github:owner/repo' }
+ * inferRepositoryFromPackageJsonObject(pkg)
+ * // → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }
+ * ```
+ */
+function inferRepositoryFromPackageJsonObject(packageJson) {
+    const { repository } = packageJson;
+    if (!repository) {
+        return null;
+    }
+    // Handle string format
+    if (typeof repository === 'string') {
+        return parseRepositoryString(repository);
+    }
+    // Handle object format
+    if (typeof repository === 'object' && repository.url) {
+        return createRepositoryConfigFromUrl(repository.url);
+    }
+    return null;
+}
+/**
+ * Parses a repository string (shorthand or URL).
+ *
+ * @param repoString - Repository string from package.json
+ * @returns RepositoryConfig or null
+ *
+ * @internal
+ */
+function parseRepositoryString(repoString) {
+    const trimmed = repoString.trim();
+    if (!trimmed) {
+        return null;
+    }
+    // Check for shorthand format: platform:owner/repo
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex > 0) {
+        const potentialPlatform = trimmed.slice(0, colonIndex);
+        // Platform must be only letters (a-z, case insensitive)
+        if (isOnlyLetters(potentialPlatform)) {
+            const platform = potentialPlatform.toLowerCase();
+            const path = trimmed.slice(colonIndex + 1);
+            if (path) {
+                const baseUrl = SHORTHAND_PLATFORMS.get(platform);
+                if (baseUrl) {
+                    // Construct full URL and parse it
+                    const fullUrl = `${baseUrl}/${path}`;
+                    return createRepositoryConfigFromUrl(fullUrl);
+                }
+                // Unknown shorthand platform - try as URL
+                return createRepositoryConfigFromUrl(trimmed);
+            }
+        }
+    }
+    // Check for bare shorthand: owner/repo (no protocol, no platform prefix)
+    // Must match pattern like "owner/repo" but not "https://..." or "git@..."
+    if (!trimmed.includes('://') && !trimmed.startsWith('git@')) {
+        if (isBareShorthand(trimmed)) {
+            // Bare shorthand defaults to GitHub
+            const fullUrl = `https://github.com/${trimmed}`;
+            return createRepositoryConfigFromUrl(fullUrl);
+        }
+    }
+    // Try as a full URL
+    return createRepositoryConfigFromUrl(trimmed);
+}
+/**
+ * Checks if a string contains only ASCII letters (a-z, A-Z).
+ *
+ * @param str - String to check
+ * @returns True if string contains only letters
+ *
+ * @internal
+ */
+function isOnlyLetters(str) {
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        const isLowercase = char >= 97 && char <= 122; // a-z
+        const isUppercase = char >= 65 && char <= 90; // A-Z
+        if (!isLowercase && !isUppercase) {
+            return false;
+        }
+    }
+    return str.length > 0;
+}
+/**
+ * Checks if a string is a bare shorthand format (owner/repo).
+ * Must have exactly one forward slash with content on both sides.
+ *
+ * @param str - String to check
+ * @returns True if string matches owner/repo format
+ *
+ * @internal
+ */
+function isBareShorthand(str) {
+    const slashIndex = str.indexOf('/');
+    if (slashIndex <= 0 || slashIndex === str.length - 1) {
+        return false;
+    }
+    // Must not have another slash
+    return str.indexOf('/', slashIndex + 1) === -1;
+}
+
+const RESOLVE_REPOSITORY_STEP_ID = 'resolve-repository';
+/**
+ * Creates the resolve-repository step.
+ *
+ * This step resolves repository configuration for compare URL generation.
+ * It supports multiple resolution modes:
+ *
+ * - `undefined` or `'disabled'`: No-op, backward compatible default
+ * - `'inferred'`: Auto-detect from package.json or git remote
+ * - `RepositoryConfig`: Direct repository configuration provided
+ * - `RepositoryResolution`: Fine-grained control with mode and options
+ *
+ * State updates:
+ * - repositoryConfig: Resolved repository configuration (if successful)
+ *
+ * @returns A FlowStep that resolves repository configuration
+ *
+ * @example
+ * ```typescript
+ * // Auto-detect repository
+ * const flow = createFlow({
+ *   repository: 'inferred'
+ * })
+ *
+ * // Explicit repository
+ * const flow = createFlow({
+ *   repository: {
+ *     platform: 'github',
+ *     baseUrl: 'https://github.com/owner/repo'
+ *   }
+ * })
+ * ```
+ */
+function createResolveRepositoryStep() {
+    return createStep(RESOLVE_REPOSITORY_STEP_ID, 'Resolve Repository', async (ctx) => {
+        const { config, logger, tree, git, projectRoot } = ctx;
+        const repoConfig = config.repository;
+        // Disabled or undefined - no-op for backward compatibility
+        if (repoConfig === undefined || repoConfig === 'disabled') {
+            logger.debug('Repository resolution disabled');
+            return {
+                status: 'skipped',
+                message: 'Repository resolution disabled',
+            };
+        }
+        // Direct RepositoryConfig provided
+        if (isRepositoryConfig(repoConfig)) {
+            logger.debug(`Using explicit repository config: ${repoConfig.platform}`);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    repositoryConfig: repoConfig,
+                },
+                message: `Using explicit ${repoConfig.platform} repository`,
+            };
+        }
+        // Shorthand 'inferred' mode
+        if (repoConfig === 'inferred') {
+            const resolved = await inferRepository(tree, git, projectRoot, DEFAULT_INFERENCE_ORDER, logger);
+            if (resolved) {
+                return {
+                    status: 'success',
+                    stateUpdates: {
+                        repositoryConfig: resolved,
+                    },
+                    message: `Inferred ${resolved.platform} repository from ${resolved.baseUrl}`,
+                };
+            }
+            // Graceful degradation - no error, just no URLs
+            logger.debug('Could not infer repository from package.json or git remote');
+            return {
+                status: 'skipped',
+                message: 'Could not infer repository configuration',
+            };
+        }
+        // Full RepositoryResolution object
+        if (isRepositoryResolution(repoConfig)) {
+            return handleRepositoryResolution(repoConfig, tree, git, projectRoot, logger);
+        }
+        // Unknown configuration - should not happen with TypeScript
+        logger.warn('Unknown repository configuration format');
+        return {
+            status: 'skipped',
+            message: 'Unknown repository configuration format',
+        };
+    }, {
+        description: 'Resolves repository configuration for compare URL generation',
+    });
+}
+/**
+ * Handles a full RepositoryResolution configuration.
+ *
+ * @param resolution - Repository resolution configuration
+ * @param tree - Virtual file system tree
+ * @param git - Git client instance
+ * @param projectRoot - Path to the project root
+ * @param logger - Logger instance
+ * @returns Flow step result with repository config or skip/error status
+ * @internal
+ */
+async function handleRepositoryResolution(resolution, tree, git, projectRoot, logger) {
+    const { mode, repository, inferenceOrder } = resolution;
+    // Disabled mode
+    if (mode === 'disabled') {
+        logger.debug('Repository resolution explicitly disabled');
+        return {
+            status: 'skipped',
+            message: 'Repository resolution disabled',
+        };
+    }
+    // Explicit mode - must have repository
+    if (mode === 'explicit') {
+        if (!repository) {
+            return {
+                status: 'failed',
+                message: 'Repository config required when mode is "explicit"',
+                error: createError('Repository config required when mode is "explicit"'),
+            };
+        }
+        logger.debug(`Using explicit repository config: ${repository.platform}`);
+        return {
+            status: 'success',
+            stateUpdates: {
+                repositoryConfig: repository,
+            },
+            message: `Using explicit ${repository.platform} repository`,
+        };
+    }
+    // Inferred mode
+    const order = inferenceOrder ?? DEFAULT_INFERENCE_ORDER;
+    const resolved = await inferRepository(tree, git, projectRoot, order, logger);
+    if (resolved) {
+        return {
+            status: 'success',
+            stateUpdates: {
+                repositoryConfig: resolved,
+            },
+            message: `Inferred ${resolved.platform} repository`,
+        };
+    }
+    // Graceful degradation
+    logger.debug('Could not infer repository configuration');
+    return {
+        status: 'skipped',
+        message: 'Could not infer repository configuration',
+    };
+}
+/**
+ * Infers repository configuration from available sources.
+ *
+ * @param tree - Virtual file system tree
+ * @param git - Git client instance
+ * @param projectRoot - Path to the project root
+ * @param order - Inference source order
+ * @param logger - Logger instance
+ * @returns Repository config or null if none found
+ * @internal
+ */
+async function inferRepository(tree, git, projectRoot, order, logger) {
+    for (const source of order) {
+        const config = await inferFromSource(tree, git, projectRoot, source, logger);
+        if (config) {
+            logger.debug(`Inferred repository from ${source}: ${config.platform}`);
+            return config;
+        }
+    }
+    return null;
+}
+/**
+ * Infers repository from a single source.
+ *
+ * @param tree - Virtual file system tree
+ * @param git - Git client instance
+ * @param projectRoot - Path to the project root
+ * @param source - Inference source type
+ * @param logger - Logger instance
+ * @returns Repository config or null if not found
+ * @internal
+ */
+async function inferFromSource(tree, git, projectRoot, source, logger) {
+    if (source === 'package-json') {
+        return inferFromPackageJson(tree, projectRoot, logger);
+    }
+    if (source === 'git-remote') {
+        return inferFromGitRemote(git, logger);
+    }
+    logger.warn(`Unknown inference source: ${source}`);
+    return null;
+}
+/**
+ * Infers repository from package.json repository field.
+ *
+ * @param tree - Virtual file system tree
+ * @param projectRoot - Path to the project root
+ * @param logger - Logger instance
+ * @returns Repository config or null if not found
+ * @internal
+ */
+function inferFromPackageJson(tree, projectRoot, logger) {
+    const packageJsonPath = `${projectRoot}/package.json`;
+    if (!tree.exists(packageJsonPath)) {
+        logger.debug(`package.json not found at ${packageJsonPath}`);
+        return null;
+    }
+    const content = tree.read(packageJsonPath, 'utf-8');
+    if (!content) {
+        logger.debug('Could not read package.json');
+        return null;
+    }
+    const config = inferRepositoryFromPackageJson(content);
+    if (config) {
+        logger.debug(`Found repository in package.json: ${config.baseUrl}`);
+    }
+    return config;
+}
+/**
+ * Infers repository from git remote URL.
+ *
+ * @param git - Git client instance
+ * @param logger - Logger instance
+ * @returns Repository config or null if not found
+ * @internal
+ */
+async function inferFromGitRemote(git, logger) {
+    const remoteUrl = await git.getRemoteUrl('origin');
+    if (!remoteUrl) {
+        logger.debug('Could not get git remote URL');
+        return null;
+    }
+    const config = createRepositoryConfigFromUrl(remoteUrl);
+    if (config) {
+        logger.debug(`Inferred repository from git remote: ${config.baseUrl}`);
+    }
+    return config;
+}
+
+/**
+ * Safe copies of Set 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/set
+ */
+// Capture references at module initialization time
+const _Set = globalThis.Set;
+const _Reflect$1 = globalThis.Reflect;
+/**
+ * (Safe copy) Creates a new Set using the captured Set constructor.
+ * Use this instead of `new Set()`.
+ *
+ * @param iterable - Optional iterable of values.
+ * @returns A new Set instance.
+ */
+const createSet = (iterable) => _Reflect$1.construct(_Set, 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) Prevents modification of existing property attributes and values,
+ * and prevents the addition of new properties.
+ */
+const freeze = _Object.freeze;
+/**
+ * (Safe copy) Returns the names of the enumerable string properties and methods of an object.
+ */
+const keys = _Object.keys;
+/**
+ * (Safe copy) Returns an array of key/values of the enumerable own properties of an object.
+ */
+const entries = _Object.entries;
+/**
+ * (Safe copy) Returns an array of values of the enumerable own properties of an object.
+ */
+const values = _Object.values;
+/**
+ * (Safe copy) Adds one or more properties to an object, and/or modifies attributes of existing properties.
+ */
+const defineProperties = _Object.defineProperties;
+
+/**
+ * Safe copies of Array built-in static 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/array
+ */
+// Capture references at module initialization time
+const _Array = globalThis.Array;
+/**
+ * (Safe copy) Determines whether the passed value is an Array.
+ */
+const isArray = _Array.isArray;
+
+/**
+ * Safe copies of Console 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/console
+ */
+// Capture references at module initialization time
+const _console = globalThis.console;
+/**
+ * (Safe copy) Outputs a message to the console.
+ */
+const log = _console.log.bind(_console);
+/**
+ * (Safe copy) Outputs a warning message to the console.
+ */
+const warn = _console.warn.bind(_console);
+/**
+ * (Safe copy) Outputs an error message to the console.
+ */
+const error = _console.error.bind(_console);
+/**
+ * (Safe copy) Outputs an informational message to the console.
+ */
+const info = _console.info.bind(_console);
+/**
+ * (Safe copy) Outputs a debug message to the console.
+ */
+const debug = _console.debug.bind(_console);
+/**
+ * (Safe copy) Outputs a stack trace to the console.
+ */
+_console.trace.bind(_console);
+/**
+ * (Safe copy) Displays an interactive listing of the properties of a specified object.
+ */
+_console.dir.bind(_console);
+/**
+ * (Safe copy) Displays tabular data as a table.
+ */
+_console.table.bind(_console);
+/**
+ * (Safe copy) Writes an error message to the console if the assertion is false.
+ */
+_console.assert.bind(_console);
+/**
+ * (Safe copy) Clears the console.
+ */
+_console.clear.bind(_console);
+/**
+ * (Safe copy) Logs the number of times that this particular call to count() has been called.
+ */
+_console.count.bind(_console);
+/**
+ * (Safe copy) Resets the counter used with console.count().
+ */
+_console.countReset.bind(_console);
+/**
+ * (Safe copy) Creates a new inline group in the console.
+ */
+_console.group.bind(_console);
+/**
+ * (Safe copy) Creates a new inline group in the console that is initially collapsed.
+ */
+_console.groupCollapsed.bind(_console);
+/**
+ * (Safe copy) Exits the current inline group.
+ */
+_console.groupEnd.bind(_console);
+/**
+ * (Safe copy) Starts a timer with a name specified as an input parameter.
+ */
+_console.time.bind(_console);
+/**
+ * (Safe copy) Stops a timer that was previously started.
+ */
+_console.timeEnd.bind(_console);
+/**
+ * (Safe copy) Logs the current value of a timer that was previously started.
+ */
+_console.timeLog.bind(_console);
+
+const registeredClasses = [];
+
+/**
+ * Returns the data type of the target.
+ * Uses native `typeof` operator, however, makes distinction between `null`, `array`, and `object`.
+ * Also, when classes are registered via `registerClass`, it checks if objects are instance of any known registered class.
+ *
+ * @param target - The target to get the data type of.
+ * @returns The data type of the target.
+ */
+const getType = (target) => {
+    if (target === null)
+        return 'null';
+    const nativeDataType = typeof target;
+    if (nativeDataType === 'object') {
+        if (isArray(target))
+            return 'array';
+        for (const registeredClass of registeredClasses) {
+            if (target instanceof registeredClass)
+                return registeredClass.name;
+        }
+    }
+    return nativeDataType;
+};
+
+/**
+ * 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 = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Creates a wrapper function that only executes the wrapped function if the condition function returns true.
+ *
+ * @param func - The function to be conditionally executed.
+ * @param conditionFunc - A function that returns a boolean, determining if `func` should be executed.
+ * @returns A wrapped version of `func` that executes conditionally.
+ */
+function createConditionalExecutionFunction(func, conditionFunc) {
+    return function (...args) {
+        if (conditionFunc()) {
+            return func(...args);
+        }
+    };
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Creates a wrapper function that silently ignores any errors thrown by the wrapped void function.
+ * This function is specifically for wrapping functions that do not return a value (void functions).
+ * Exceptions are swallowed without any logging or handling.
+ *
+ * @param func - The void function to be wrapped.
+ * @returns A wrapped version of the input function that ignores errors.
+ */
+function createErrorIgnoringFunction(func) {
+    return function (...args) {
+        try {
+            func(...args);
+        }
+        catch {
+            // Deliberately swallowing/ignoring the exception
+        }
+    };
+}
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/**
+ * A no-operation function (noop) that does nothing regardless of the arguments passed.
+ * It is designed to be as permissive as possible in its typing without using the `Function` keyword.
+ *
+ * @param args - Any arguments passed to the function (ignored)
+ */
+const noop = (...args) => {
+    // Intentionally does nothing
+};
+
+const logLevels = ['none', 'error', 'warn', 'log', 'info', 'debug'];
+const priority = {
+    error: 4,
+    warn: 3,
+    log: 2,
+    info: 1,
+    debug: 0,
+};
+/**
+ * Validates whether a given string is a valid log level.
+ *
+ * @param level - The log level to validate
+ * @returns True if the level is valid, false otherwise
+ */
+function isValidLogLevel(level) {
+    return logLevels.includes(level);
+}
+/**
+ * Creates a log level configuration manager for controlling logging behavior.
+ * Provides methods to get, set, and evaluate log levels based on priority.
+ *
+ * @param level - The initial log level (defaults to 'error')
+ * @returns A configuration object with log level management methods
+ * @throws {Error} When the provided level is not a valid log level
+ */
+function createLogLevelConfig(level = 'error') {
+    if (!isValidLogLevel(level)) {
+        throw createError('Cannot create log level configuration with a valid default log level');
+    }
+    const state = { level };
+    const getLogLevel = () => state.level;
+    const setLogLevel = (level) => {
+        if (!isValidLogLevel(level)) {
+            throw createError(`Cannot set value '${level}' level. Expected levels are ${logLevels}.`);
+        }
+        state.level = level;
+    };
+    const shouldLog = (level) => {
+        if (state.level === 'none' || level === 'none' || !isValidLogLevel(level)) {
+            return false;
+        }
+        return priority[level] >= priority[state.level];
+    };
+    return freeze({
+        getLogLevel,
+        setLogLevel,
+        shouldLog,
+    });
+}
+
+/**
+ * Creates a logger instance with configurable log level filtering.
+ * Each log function is wrapped to respect the current log level setting.
+ *
+ * @param error - Function to handle error-level logs (required)
+ * @param warn - Function to handle warning-level logs (optional, defaults to noop)
+ * @param log - Function to handle standard logs (optional, defaults to noop)
+ * @param info - Function to handle info-level logs (optional, defaults to noop)
+ * @param debug - Function to handle debug-level logs (optional, defaults to noop)
+ * @returns A frozen logger object with log methods and level control
+ * @throws {ErrorLevelFn} When any provided log function is invalid
+ */
+function createLogger(error, warn = noop, log = noop, info = noop, debug = noop) {
+    if (notValidLogFn(error)) {
+        throw createError(notFnMsg('error'));
+    }
+    if (notValidLogFn(warn)) {
+        throw createError(notFnMsg('warn'));
+    }
+    if (notValidLogFn(log)) {
+        throw createError(notFnMsg('log'));
+    }
+    if (notValidLogFn(info)) {
+        throw createError(notFnMsg('info'));
+    }
+    if (notValidLogFn(debug)) {
+        throw createError(notFnMsg('debug'));
+    }
+    const { setLogLevel, getLogLevel, shouldLog } = createLogLevelConfig();
+    const wrapLogFn = (fn, level) => {
+        if (fn === noop)
+            return fn;
+        const condition = () => shouldLog(level);
+        return createConditionalExecutionFunction(createErrorIgnoringFunction(fn), condition);
+    };
+    return freeze({
+        error: wrapLogFn(error, 'error'),
+        warn: wrapLogFn(warn, 'warn'),
+        log: wrapLogFn(log, 'log'),
+        info: wrapLogFn(info, 'info'),
+        debug: wrapLogFn(debug, 'debug'),
+        setLogLevel,
+        getLogLevel,
+    });
+}
+/**
+ * Validates whether a given value is a valid log function.
+ *
+ * @param fn - The value to validate
+ * @returns True if the value is not a function (invalid), false if it is valid
+ */
+function notValidLogFn(fn) {
+    return getType(fn) !== 'function' && fn !== noop;
+}
+/**
+ * Generates an error message for invalid log function parameters.
+ *
+ * @param label - The name of the log function that failed validation
+ * @returns A formatted error message string
+ */
+function notFnMsg(label) {
+    return `Cannot create a logger when ${label} is not a function`;
+}
+
+createLogger(error, warn, log, info, debug);
+
+/**
+ * Global log level registry.
+ * Tracks all created scoped loggers to allow global log level changes.
+ */
+const loggerRegistry = createSet();
+/** Redacted placeholder for sensitive values */
+const REDACTED = '[REDACTED]';
+/**
+ * Patterns that indicate a sensitive key name.
+ * Keys containing these patterns will have their values sanitized.
+ */
+const SENSITIVE_KEY_PATTERNS = [
+    /token/i,
+    /key/i,
+    /password/i,
+    /secret/i,
+    /credential/i,
+    /auth/i,
+    /bearer/i,
+    /api[_-]?key/i,
+    /private/i,
+    /passphrase/i,
+];
+/**
+ * Checks if a key name indicates sensitive data.
+ *
+ * @param key - Key name to check
+ * @returns True if the key indicates sensitive data
+ */
+function isSensitiveKey(key) {
+    return SENSITIVE_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+/**
+ * Sanitizes an object by replacing sensitive values with REDACTED.
+ * This function recursively processes nested objects and arrays.
+ *
+ * @param obj - Object to sanitize
+ * @returns New object with sensitive values redacted
+ */
+function sanitize(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (isArray(obj)) {
+        return obj.map((item) => sanitize(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of entries(obj)) {
+            if (isSensitiveKey(key)) {
+                result[key] = REDACTED;
+            }
+            else if (typeof value === 'object' && value !== null) {
+                result[key] = sanitize(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Formats a log message with optional metadata.
+ *
+ * @param namespace - Logger namespace prefix
+ * @param message - Log message
+ * @param meta - Optional metadata object
+ * @returns Formatted log string
+ */
+function formatMessage(namespace, message, meta) {
+    const prefix = `[${namespace}]`;
+    if (meta && keys(meta).length > 0) {
+        const sanitizedMeta = sanitize(meta);
+        return `${prefix} ${message} ${stringify(sanitizedMeta)}`;
+    }
+    return `${prefix} ${message}`;
+}
+/**
+ * Creates a scoped logger with namespace prefix and optional secret sanitization.
+ * All log messages will be prefixed with [namespace] and sensitive metadata
+ * values will be automatically redacted.
+ *
+ * @param namespace - Logger namespace (e.g., 'project-scope', 'analyze')
+ * @param options - Logger configuration options
+ * @returns A configured scoped logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createScopedLogger('project-scope')
+ * logger.setLogLevel('debug')
+ *
+ * // Basic logging
+ * logger.info('Starting analysis', { path: './project' })
+ *
+ * // Sensitive data is automatically redacted
+ * logger.debug('Config loaded', { apiKey: 'secret123' })
+ * // Output: [project-scope] Config loaded {"apiKey":"[REDACTED]"}
+ * ```
+ */
+function createScopedLogger(namespace, options = {}) {
+    const { level = 'error', sanitizeSecrets = true } = options;
+    // Create wrapper functions that add namespace prefix and sanitization
+    const createLogFn = (baseFn) => (message, meta) => {
+        const processedMeta = sanitizeSecrets && meta ? sanitize(meta) : meta;
+        baseFn(formatMessage(namespace, message, processedMeta));
+    };
+    // Create base logger with wrapped functions
+    const baseLogger = createLogger(createLogFn(error), createLogFn(warn), createLogFn(log), createLogFn(info), createLogFn(debug));
+    // Set initial log level (use global override if set)
+    baseLogger.setLogLevel(level);
+    const scopedLogger = freeze({
+        error: (message, meta) => baseLogger.error(message, meta),
+        warn: (message, meta) => baseLogger.warn(message, meta),
+        log: (message, meta) => baseLogger.log(message, meta),
+        info: (message, meta) => baseLogger.info(message, meta),
+        debug: (message, meta) => baseLogger.debug(message, meta),
+        setLogLevel: baseLogger.setLogLevel,
+        getLogLevel: baseLogger.getLogLevel,
+    });
+    // Register logger for global level management
+    loggerRegistry.add(scopedLogger);
+    return scopedLogger;
+}
+/**
+ * Default logger instance for the project-scope library.
+ * Use this for general logging within the library.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@hyperfrontend/project-scope/core'
+ *
+ * logger.setLogLevel('debug')
+ * logger.debug('Analyzing project', { path: './src' })
+ * ```
+ */
+createScopedLogger('project-scope');
+
+createScopedLogger('project-scope:fs');
+/**
+ * Create a file system error with code and context.
+ *
+ * @param message - The error message describing what went wrong
+ * @param code - The category code for this type of filesystem failure
+ * @param context - Additional context including path, operation, and cause
+ * @returns A configured Error object with code and context properties
+ */
+function createFileSystemError(message, code, context) {
+    const error = createError(message);
+    defineProperties(error, {
+        code: { value: code, enumerable: true },
+        context: { value: context, enumerable: true },
+    });
+    return error;
+}
+/**
+ * Read file if exists, return null otherwise.
+ *
+ * @param filePath - Path to file
+ * @param encoding - File encoding (default: utf-8)
+ * @returns File contents or null if file doesn't exist
+ */
+function readFileIfExists(filePath, encoding = 'utf-8') {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return node_fs.readFileSync(filePath, { encoding });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read and parse JSON file if exists, return null otherwise.
+ *
+ * @param filePath - Path to JSON file
+ * @returns Parsed JSON object or null if file doesn't exist or is invalid
+ */
+function readJsonFileIfExists(filePath) {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = node_fs.readFileSync(filePath, { encoding: 'utf-8' });
+        return parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+
+createScopedLogger('project-scope:fs:write');
+
+/**
+ * Get file stats with error handling.
+ *
+ * @param filePath - Path to file
+ * @param followSymlinks - Whether to follow symlinks (default: true)
+ * @returns File stats or null if path doesn't exist
+ */
+function getFileStat(filePath, followSymlinks = true) {
+    if (!node_fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const stat = followSymlinks ? node_fs.statSync(filePath) : node_fs.lstatSync(filePath);
+        return {
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymlink: stat.isSymbolicLink(),
+            size: stat.size,
+            created: stat.birthtime,
+            modified: stat.mtime,
+            accessed: stat.atime,
+            mode: stat.mode,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if path is a directory.
+ *
+ * @param dirPath - Path to check
+ * @returns True if path is a directory
+ */
+function isDirectory(dirPath) {
+    const stats = getFileStat(dirPath);
+    return stats?.isDirectory ?? false;
+}
+/**
+ * Check if path exists.
+ *
+ * @param filePath - Path to check
+ * @returns True if path exists
+ */
+function exists(filePath) {
+    return node_fs.existsSync(filePath);
+}
+
+const fsDirLogger = createScopedLogger('project-scope:fs:dir');
+/**
+ * List immediate contents of a directory.
+ *
+ * @param dirPath - Absolute or relative path to the directory
+ * @returns Array of entries with metadata for each file/directory
+ * @throws {Error} If directory doesn't exist or isn't a directory
+ *
+ * @example
+ * ```typescript
+ * import { readDirectory } from '@hyperfrontend/project-scope'
+ *
+ * const entries = readDirectory('./src')
+ * for (const entry of entries) {
+ *   console.log(entry.name, entry.isFile ? 'file' : 'directory')
+ * }
+ * ```
+ */
+function readDirectory(dirPath) {
+    fsDirLogger.debug('Reading directory', { path: dirPath });
+    if (!node_fs.existsSync(dirPath)) {
+        fsDirLogger.debug('Directory not found', { path: dirPath });
+        throw createFileSystemError(`Directory not found: ${dirPath}`, 'FS_NOT_FOUND', { path: dirPath, operation: 'readdir' });
+    }
+    if (!isDirectory(dirPath)) {
+        fsDirLogger.debug('Path is not a directory', { path: dirPath });
+        throw createFileSystemError(`Not a directory: ${dirPath}`, 'FS_NOT_A_DIRECTORY', { path: dirPath, operation: 'readdir' });
+    }
+    try {
+        const entries = node_fs.readdirSync(dirPath, { withFileTypes: true });
+        fsDirLogger.debug('Directory read complete', { path: dirPath, entryCount: entries.length });
+        return entries.map((entry) => ({
+            name: entry.name,
+            path: node_path.join(dirPath, entry.name),
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+            isSymlink: entry.isSymbolicLink(),
+        }));
+    }
+    catch (error) {
+        fsDirLogger.warn('Failed to read directory', { path: dirPath, error: error instanceof Error ? error.message : String(error) });
+        throw createFileSystemError(`Failed to read directory: ${dirPath}`, 'FS_READ_ERROR', {
+            path: dirPath,
+            operation: 'readdir',
+            cause: error,
+        });
+    }
+}
+
+createScopedLogger('project-scope:fs:traversal');
+
+const packageLogger = createScopedLogger('project-scope:project:package');
+/**
+ * Verifies that a value is an object with only string values,
+ * used for validating dependency maps and script definitions.
+ *
+ * @param value - Value to check
+ * @returns True if value is a record of strings
+ */
+function isStringRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return values(value).every((v) => typeof v === 'string');
+}
+/**
+ * Extracts and normalizes the workspaces field from package.json,
+ * supporting both array format and object with packages array.
+ *
+ * @param value - Raw workspaces value from package.json
+ * @returns Normalized workspace patterns or undefined if invalid
+ */
+function parseWorkspaces(value) {
+    if (isArray(value) && value.every((v) => typeof v === 'string')) {
+        return value;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value;
+        if (isArray(obj['packages'])) {
+            return { packages: obj['packages'] };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate and normalize package.json data.
+ *
+ * @param data - Raw parsed data
+ * @returns Validated package.json
+ */
+function validatePackageJson(data) {
+    if (typeof data !== 'object' || data === null) {
+        throw createError('package.json must be an object');
+    }
+    const pkg = data;
+    return {
+        name: typeof pkg['name'] === 'string' ? pkg['name'] : undefined,
+        version: typeof pkg['version'] === 'string' ? pkg['version'] : undefined,
+        description: typeof pkg['description'] === 'string' ? pkg['description'] : undefined,
+        main: typeof pkg['main'] === 'string' ? pkg['main'] : undefined,
+        module: typeof pkg['module'] === 'string' ? pkg['module'] : undefined,
+        browser: typeof pkg['browser'] === 'string' ? pkg['browser'] : undefined,
+        types: typeof pkg['types'] === 'string' ? pkg['types'] : undefined,
+        bin: typeof pkg['bin'] === 'string' || isStringRecord(pkg['bin']) ? pkg['bin'] : undefined,
+        scripts: isStringRecord(pkg['scripts']) ? pkg['scripts'] : undefined,
+        dependencies: isStringRecord(pkg['dependencies']) ? pkg['dependencies'] : undefined,
+        devDependencies: isStringRecord(pkg['devDependencies']) ? pkg['devDependencies'] : undefined,
+        peerDependencies: isStringRecord(pkg['peerDependencies']) ? pkg['peerDependencies'] : undefined,
+        optionalDependencies: isStringRecord(pkg['optionalDependencies']) ? pkg['optionalDependencies'] : undefined,
+        workspaces: parseWorkspaces(pkg['workspaces']),
+        exports: typeof pkg['exports'] === 'object' ? pkg['exports'] : undefined,
+        engines: isStringRecord(pkg['engines']) ? pkg['engines'] : undefined,
+        ...pkg,
+    };
+}
+/**
+ * Attempts to read and parse package.json if it exists,
+ * returning null on missing file or parse failure.
+ *
+ * @param projectPath - Project directory path or path to package.json
+ * @returns Parsed package.json or null if not found
+ */
+function readPackageJsonIfExists(projectPath) {
+    const packageJsonPath = projectPath.endsWith('package.json') ? projectPath : node_path.join(projectPath, 'package.json');
+    const content = readFileIfExists(packageJsonPath);
+    if (!content) {
+        packageLogger.debug('Package.json not found', { path: packageJsonPath });
+        return null;
+    }
+    try {
+        const validated = validatePackageJson(parse(content));
+        packageLogger.debug('Package.json loaded', { path: packageJsonPath, name: validated.name });
+        return validated;
+    }
+    catch {
+        packageLogger.debug('Failed to parse package.json, returning null', { path: packageJsonPath });
+        return null;
+    }
+}
+
+createScopedLogger('project-scope:root');
+
+const nxLogger = createScopedLogger('project-scope:nx');
+/**
+ * Files indicating NX workspace root.
+ */
+const NX_CONFIG_FILES = ['nx.json', 'workspace.json'];
+/**
+ * NX-specific project file.
+ */
+const NX_PROJECT_FILE = 'project.json';
+/**
+ * Check if directory is an NX workspace root.
+ *
+ * @param path - Directory path to check
+ * @returns True if the directory contains nx.json or workspace.json
+ *
+ * @example
+ * ```typescript
+ * import { isNxWorkspace } from '@hyperfrontend/project-scope'
+ *
+ * if (isNxWorkspace('./my-project')) {
+ *   console.log('This is an NX monorepo')
+ * }
+ * ```
+ */
+function isNxWorkspace(path) {
+    for (const configFile of NX_CONFIG_FILES) {
+        if (exists(node_path.join(path, configFile))) {
+            nxLogger.debug('NX workspace detected', { path, configFile });
+            return true;
+        }
+    }
+    nxLogger.debug('Not an NX workspace', { path });
+    return false;
+}
+/**
+ * Check if directory is an NX project.
+ *
+ * @param path - Directory path to check
+ * @returns True if the directory contains project.json
+ */
+function isNxProject(path) {
+    const isProject = exists(node_path.join(path, NX_PROJECT_FILE));
+    nxLogger.debug('NX project check', { path, isProject });
+    return isProject;
+}
+/**
+ * Detect NX version from package.json dependencies.
+ *
+ * @param workspacePath - Workspace root path
+ * @returns NX version string (without semver range) or null
+ */
+function detectNxVersion(workspacePath) {
+    const packageJson = readPackageJsonIfExists(workspacePath);
+    if (packageJson) {
+        const nxVersion = packageJson.devDependencies?.['nx'] ?? packageJson.dependencies?.['nx'];
+        if (nxVersion) {
+            // Strip semver range characters (^, ~, >=, etc.)
+            return nxVersion.replace(/^[\^~>=<]+/, '');
+        }
+    }
+    return null;
+}
+/**
+ * Check if workspace is integrated (not standalone).
+ * Integrated repos typically have workspaceLayout, namedInputs, or targetDefaults.
+ *
+ * @param nxJson - Parsed nx.json configuration
+ * @returns True if the workspace is integrated
+ */
+function isIntegratedRepo(nxJson) {
+    return nxJson.workspaceLayout !== undefined || nxJson.namedInputs !== undefined || nxJson.targetDefaults !== undefined;
+}
+/**
+ * Get comprehensive NX workspace information.
+ *
+ * @param workspacePath - Workspace root path
+ * @returns Workspace info or null if not an NX workspace
+ */
+function getNxWorkspaceInfo(workspacePath) {
+    nxLogger.debug('Getting NX workspace info', { workspacePath });
+    if (!isNxWorkspace(workspacePath)) {
+        return null;
+    }
+    const nxJson = readJsonFileIfExists(node_path.join(workspacePath, 'nx.json'));
+    if (!nxJson) {
+        // Check for workspace.json as fallback (older NX)
+        const workspaceJson = readJsonFileIfExists(node_path.join(workspacePath, 'workspace.json'));
+        if (!workspaceJson) {
+            nxLogger.debug('No nx.json or workspace.json found', { workspacePath });
+            return null;
+        }
+        nxLogger.debug('Using legacy workspace.json', { workspacePath });
+        // Create minimal nx.json from workspace.json
+        return {
+            root: workspacePath,
+            version: detectNxVersion(workspacePath),
+            nxJson: {},
+            isIntegrated: true,
+            workspaceLayout: {
+                appsDir: 'apps',
+                libsDir: 'libs',
+            },
+        };
+    }
+    const info = {
+        root: workspacePath,
+        version: detectNxVersion(workspacePath),
+        nxJson,
+        isIntegrated: isIntegratedRepo(nxJson),
+        defaultProject: nxJson.defaultProject,
+        workspaceLayout: {
+            appsDir: nxJson.workspaceLayout?.appsDir ?? 'apps',
+            libsDir: nxJson.workspaceLayout?.libsDir ?? 'libs',
+        },
+    };
+    nxLogger.debug('NX workspace info retrieved', {
+        workspacePath,
+        version: info.version,
+        isIntegrated: info.isIntegrated,
+        defaultProject: info.defaultProject,
+    });
+    return info;
+}
+
+createScopedLogger('project-scope:nx:devkit');
+
+const nxConfigLogger = createScopedLogger('project-scope:nx:config');
+/**
+ * Read project.json for an NX project.
+ *
+ * @param projectPath - Project directory path
+ * @returns Parsed project.json or null if not found
+ */
+function readProjectJson(projectPath) {
+    const projectJsonPath = node_path.join(projectPath, NX_PROJECT_FILE);
+    nxConfigLogger.debug('Reading project.json', { path: projectJsonPath });
+    const result = readJsonFileIfExists(projectJsonPath);
+    if (result) {
+        nxConfigLogger.debug('Project.json loaded', { path: projectJsonPath, name: result.name });
+    }
+    else {
+        nxConfigLogger.debug('Project.json not found', { path: projectJsonPath });
+    }
+    return result;
+}
+/**
+ * Get project configuration from project.json or package.json nx field.
+ *
+ * @param projectPath - Project directory path
+ * @param workspacePath - Workspace root path (for relative path calculation)
+ * @returns Project configuration or null if not found
+ */
+function getProjectConfig(projectPath, workspacePath) {
+    nxConfigLogger.debug('Getting project config', { projectPath, workspacePath });
+    // Try project.json first
+    const projectJson = readProjectJson(projectPath);
+    if (projectJson) {
+        nxConfigLogger.debug('Using project.json config', { projectPath, name: projectJson.name });
+        return {
+            ...projectJson,
+            root: projectJson.root ?? node_path.relative(workspacePath, projectPath),
+        };
+    }
+    // Try to infer from package.json nx field
+    const packageJson = readPackageJsonIfExists(projectPath);
+    if (packageJson && typeof packageJson['nx'] === 'object') {
+        nxConfigLogger.debug('Using package.json nx field', { projectPath, name: packageJson.name });
+        const nxConfig = packageJson['nx'];
+        return {
+            name: packageJson.name,
+            root: node_path.relative(workspacePath, projectPath),
+            ...nxConfig,
+        };
+    }
+    nxConfigLogger.debug('No project config found', { projectPath });
+    return null;
+}
+/**
+ * Recursively scan directory for project.json files.
+ *
+ * @param dirPath - Directory to scan
+ * @param workspacePath - Workspace root path
+ * @param projects - Map to add discovered projects to
+ * @param maxDepth - Maximum recursion depth
+ * @param currentDepth - Current recursion depth
+ */
+function scanForProjects(dirPath, workspacePath, projects, maxDepth, currentDepth = 0) {
+    if (currentDepth > maxDepth)
+        return;
+    try {
+        const entries = readDirectory(dirPath);
+        for (const entry of entries) {
+            // Skip node_modules and hidden directories
+            if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'dist') {
+                continue;
+            }
+            const fullPath = node_path.join(dirPath, entry.name);
+            if (entry.isDirectory) {
+                // Check if this directory is an NX project
+                if (isNxProject(fullPath)) {
+                    const config = getProjectConfig(fullPath, workspacePath);
+                    if (config) {
+                        const name = config.name || node_path.relative(workspacePath, fullPath).replace(/[\\/]/g, '-');
+                        projects.set(name, {
+                            ...config,
+                            name,
+                            root: node_path.relative(workspacePath, fullPath),
+                        });
+                    }
+                }
+                // Recursively scan subdirectories
+                scanForProjects(fullPath, workspacePath, projects, maxDepth, currentDepth + 1);
+            }
+        }
+    }
+    catch {
+        // Directory not readable, skip
+    }
+}
+/**
+ * Discover all NX projects in workspace.
+ * Supports both workspace.json (older format) and project.json (newer format).
+ *
+ * @param workspacePath - Workspace root path
+ * @returns Map of project name to configuration
+ */
+function discoverNxProjects(workspacePath) {
+    const projects = createMap();
+    // Check for workspace.json (older NX format)
+    const workspaceJson = readJsonFileIfExists(node_path.join(workspacePath, 'workspace.json'));
+    if (workspaceJson?.projects) {
+        for (const [name, config] of entries(workspaceJson.projects)) {
+            if (typeof config === 'string') {
+                // Path reference to project directory
+                const projectPath = node_path.join(workspacePath, config);
+                const projectConfig = getProjectConfig(projectPath, workspacePath);
+                if (projectConfig) {
+                    projects.set(name, { ...projectConfig, name });
+                }
+            }
+            else if (typeof config === 'object' && config !== null) {
+                // Inline config
+                projects.set(name, { name, ...config });
+            }
+        }
+        return projects;
+    }
+    // Scan for project.json files (newer NX format)
+    const workspaceInfo = getNxWorkspaceInfo(workspacePath);
+    const appsDir = workspaceInfo?.workspaceLayout.appsDir ?? 'apps';
+    const libsDir = workspaceInfo?.workspaceLayout.libsDir ?? 'libs';
+    const searchDirs = [appsDir, libsDir];
+    // Also check packages directory (common in some setups)
+    if (exists(node_path.join(workspacePath, 'packages'))) {
+        searchDirs.push('packages');
+    }
+    for (const dir of searchDirs) {
+        const dirPath = node_path.join(workspacePath, dir);
+        if (exists(dirPath) && isDirectory(dirPath)) {
+            try {
+                scanForProjects(dirPath, workspacePath, projects, 3);
+            }
+            catch {
+                // Directory not accessible
+            }
+        }
+    }
+    // Also check root-level projects (standalone projects in monorepo root)
+    if (isNxProject(workspacePath)) {
+        const config = readProjectJson(workspacePath);
+        if (config) {
+            const name = config.name || node_path.basename(workspacePath);
+            projects.set(name, {
+                ...config,
+                name,
+                root: '.',
+            });
+        }
+    }
+    return projects;
+}
+/**
+ * Build a simple project graph from discovered projects.
+ * For full graph capabilities, use `@nx/devkit`.
+ *
+ * @param workspacePath - Workspace root path
+ * @param projects - Existing configuration map to skip auto-discovery
+ * @returns NxProjectGraph with nodes and dependencies
+ */
+function buildSimpleProjectGraph(workspacePath, projects) {
+    const projectMap = projects ?? discoverNxProjects(workspacePath);
+    const nodes = {};
+    const dependencies = {};
+    for (const [name, config] of projectMap) {
+        nodes[name] = {
+            name,
+            type: config.projectType ?? 'library',
+            data: config,
+        };
+        dependencies[name] = [];
+        // Add implicit dependencies
+        if (config.implicitDependencies) {
+            for (const dep of config.implicitDependencies) {
+                // Skip negative dependencies (those starting with !)
+                if (!dep.startsWith('!')) {
+                    dependencies[name].push({
+                        target: dep,
+                        type: 'implicit',
+                    });
+                }
+            }
+        }
+    }
+    return { nodes, dependencies };
+}
+
+/**
+ * Creates an empty classification summary.
+ *
+ * @returns A new ClassificationSummary with all counts at zero
+ */
+function createEmptyClassificationSummary() {
+    return {
+        total: 0,
+        included: 0,
+        excluded: 0,
+        bySource: {
+            'direct-scope': 0,
+            'direct-file': 0,
+            'unscoped-file': 0,
+            'indirect-dependency': 0,
+            'indirect-infra': 0,
+            'unscoped-global': 0,
+            excluded: 0,
+        },
+    };
+}
+/**
+ * Creates a classified commit.
+ *
+ * @param commit - The parsed conventional commit
+ * @param raw - The raw git commit
+ * @param source - How the commit relates to the project
+ * @param options - Additional classification options
+ * @param options.touchedFiles - Files in the project modified by this commit
+ * @param options.dependencyPath - Chain of dependencies leading to indirect inclusion
+ * @returns A new ClassifiedCommit object
+ */
+function createClassifiedCommit(commit, raw, source, options) {
+    const include = isIncludedSource(source);
+    const preserveScope = shouldPreserveScope(source);
+    return {
+        commit,
+        raw,
+        source,
+        include,
+        preserveScope,
+        touchedFiles: options?.touchedFiles,
+        dependencyPath: options?.dependencyPath,
+    };
+}
+/**
+ * Determines if a source type should be included in changelog.
+ *
+ * @param source - The commit source type
+ * @returns True if commits with this source should be included
+ */
+function isIncludedSource(source) {
+    switch (source) {
+        case 'direct-scope':
+        case 'direct-file':
+        case 'unscoped-file':
+        case 'indirect-dependency':
+        case 'indirect-infra':
+            return true;
+        case 'unscoped-global':
+        case 'excluded':
+            return false;
+    }
+}
+/**
+ * Determines if scope should be preserved for a source type.
+ *
+ * Direct commits omit scope (redundant in project changelog).
+ * Indirect commits preserve scope for context.
+ *
+ * @param source - The commit source type
+ * @returns True if scope should be preserved in changelog
+ */
+function shouldPreserveScope(source) {
+    switch (source) {
+        case 'direct-scope':
+        case 'unscoped-file':
+            return false; // Scope would be redundant
+        case 'direct-file':
+        case 'indirect-dependency':
+        case 'indirect-infra':
+            return true; // Scope provides context
+        case 'unscoped-global':
+        case 'excluded':
+            return false; // Won't be shown
+    }
+}
+
+/**
+ * Derives all scope variations that should match a project.
+ *
+ * Given a project named 'lib-versioning' with package '@hyperfrontend/versioning',
+ * this generates variations like:
+ * - 'lib-versioning' (full project name)
+ * - 'versioning' (without lib- prefix)
+ *
+ * @param options - Project identification options
+ * @returns Array of scope strings that match this project
+ *
+ * @example
+ * deriveProjectScopes({ projectName: 'lib-versioning', packageName: '@hyperfrontend/versioning' })
+ * // Returns: ['lib-versioning', 'versioning']
+ *
+ * @example
+ * deriveProjectScopes({ projectName: 'app-demo', packageName: 'demo-app' })
+ * // Returns: ['app-demo', 'demo']
+ */
+function deriveProjectScopes(options) {
+    const { projectName, packageName, additionalScopes = [] } = options;
+    const scopes = createSet();
+    // Always include the full project name
+    scopes.add(projectName);
+    // Add variations based on common prefixes
+    const prefixVariations = extractPrefixVariations(projectName);
+    for (const variation of prefixVariations) {
+        scopes.add(variation);
+    }
+    // Add package name variations if provided
+    if (packageName) {
+        const packageVariations = extractPackageNameVariations(packageName);
+        for (const variation of packageVariations) {
+            scopes.add(variation);
+        }
+    }
+    // Add any additional scopes
+    for (const scope of additionalScopes) {
+        if (scope) {
+            scopes.add(scope);
+        }
+    }
+    return [...scopes];
+}
+/**
+ * Recognized project name prefixes that can be stripped for scope matching.
+ */
+const PROJECT_PREFIXES = ['lib-', 'app-', 'e2e-', 'tool-', 'plugin-', 'feature-', 'package-'];
+/**
+ * Generates scope variations by stripping recognized project prefixes.
+ *
+ * @param projectName - The project name to extract variations from
+ * @returns Array of scope name variations
+ */
+function extractPrefixVariations(projectName) {
+    const variations = [];
+    for (const prefix of PROJECT_PREFIXES) {
+        if (projectName.startsWith(prefix)) {
+            const withoutPrefix = projectName.slice(prefix.length);
+            if (withoutPrefix) {
+                variations.push(withoutPrefix);
+            }
+            break; // Only remove one prefix
+        }
+    }
+    return variations;
+}
+/**
+ * Extracts scope variations from an npm package name.
+ *
+ * @param packageName - The npm package name (e.g., '@scope/name')
+ * @returns Array of name variations
+ */
+function extractPackageNameVariations(packageName) {
+    const variations = [];
+    // Handle scoped packages: @scope/name -> name
+    if (packageName.startsWith('@')) {
+        const slashIndex = packageName.indexOf('/');
+        if (slashIndex !== -1) {
+            const unscoped = packageName.slice(slashIndex + 1);
+            if (unscoped) {
+                variations.push(unscoped);
+            }
+        }
+    }
+    else {
+        // Non-scoped package: just use the name
+        variations.push(packageName);
+    }
+    return variations;
+}
+/**
+ * Checks if a commit scope matches any of the project scopes.
+ *
+ * @param commitScope - The scope from a conventional commit
+ * @param projectScopes - Array of scopes that match the project
+ * @returns True if the commit scope matches the project
+ *
+ * @example
+ * scopeMatchesProject('versioning', ['lib-versioning', 'versioning']) // true
+ * scopeMatchesProject('logging', ['lib-versioning', 'versioning']) // false
+ */
+function scopeMatchesProject(commitScope, projectScopes) {
+    if (!commitScope) {
+        return false;
+    }
+    // Case-insensitive comparison
+    const normalizedScope = commitScope.toLowerCase();
+    return projectScopes.some((scope) => scope.toLowerCase() === normalizedScope);
+}
+/**
+ * Checks if a commit scope should be explicitly excluded.
+ *
+ * @param commitScope - The scope from a conventional commit
+ * @param excludeScopes - Array of scopes to exclude
+ * @returns True if the scope should be excluded
+ */
+function scopeIsExcluded(commitScope, excludeScopes) {
+    if (!commitScope) {
+        return false;
+    }
+    const normalizedScope = commitScope.toLowerCase();
+    return excludeScopes.some((scope) => scope.toLowerCase() === normalizedScope);
+}
+/**
+ * Default scopes to exclude from changelogs.
+ *
+ * These represent repository-level or infrastructure changes
+ * that typically don't belong in individual project changelogs.
+ */
+const DEFAULT_EXCLUDE_SCOPES = ['release', 'deps', 'workspace', 'root', 'repo', 'ci', 'build'];
+
+/**
+ * Classifies a single commit against a project.
+ *
+ * Implements the hybrid classification strategy:
+ * 1. Check scope match (fast path)
+ * 2. Check file touch (validation/catch-all)
+ * 3. Check dependency touch (indirect)
+ * 4. Fallback to excluded
+ *
+ * @param input - The commit to classify
+ * @param context - Classification context with project info
+ * @returns Classified commit with source attribution
+ *
+ * @example
+ * const classified = classifyCommit(
+ *   { commit: parsedCommit, raw: gitCommit },
+ *   { projectScopes: ['versioning'], fileCommitHashes: new Set(['abc123']) }
+ * )
+ */
+function classifyCommit(input, context) {
+    const { commit, raw } = input;
+    const { projectScopes, fileCommitHashes, dependencyCommitMap, infrastructureCommitHashes, excludeScopes = DEFAULT_EXCLUDE_SCOPES, includeScopes = [], } = context;
+    const scope = commit.scope;
+    const hasScope = !!scope;
+    const allProjectScopes = [...projectScopes, ...includeScopes];
+    // First check: Is this scope explicitly excluded?
+    if (hasScope && scopeIsExcluded(scope, excludeScopes)) {
+        return createClassifiedCommit(commit, raw, 'excluded');
+    }
+    // Priority 1: Scope-based direct match (fast path)
+    if (hasScope && scopeMatchesProject(scope, allProjectScopes)) {
+        return createClassifiedCommit(commit, raw, 'direct-scope');
+    }
+    // Priority 2: File-based direct match (validation/catch-all)
+    if (fileCommitHashes.has(raw.hash)) {
+        // Commit touched project files
+        if (hasScope) {
+            // Has a scope but it's different - likely a typo or cross-cutting change
+            return createClassifiedCommit(commit, raw, 'direct-file');
+        }
+        // No scope but touched project files
+        return createClassifiedCommit(commit, raw, 'unscoped-file');
+    }
+    // Priority 3: Indirect dependency match
+    if (hasScope && dependencyCommitMap) {
+        const dependencyPath = findDependencyPath(scope, raw.hash, dependencyCommitMap);
+        if (dependencyPath) {
+            return createClassifiedCommit(commit, raw, 'indirect-dependency', { dependencyPath });
+        }
+    }
+    // File-based infrastructure match
+    if (infrastructureCommitHashes?.has(raw.hash)) {
+        return createClassifiedCommit(commit, raw, 'indirect-infra');
+    }
+    // Fallback: No match found
+    if (!hasScope) {
+        // Unscoped commit that didn't touch any project files
+        return createClassifiedCommit(commit, raw, 'unscoped-global');
+    }
+    // Scoped commit that doesn't match anything
+    return createClassifiedCommit(commit, raw, 'excluded');
+}
+/**
+ * Classifies multiple commits against a project.
+ *
+ * @param commits - Array of commits to classify
+ * @param context - Classification context with project info
+ * @returns Classification result with all commits and summary
+ */
+function classifyCommits(commits, context) {
+    const classified = [];
+    const included = [];
+    const excluded = [];
+    const summary = createEmptyClassificationSummary();
+    const bySource = { ...summary.bySource };
+    for (const input of commits) {
+        const result = classifyCommit(input, context);
+        classified.push(result);
+        // Update summary
+        bySource[result.source]++;
+        if (result.include) {
+            included.push(result);
+        }
+        else {
+            excluded.push(result);
+        }
+    }
+    return {
+        commits: classified,
+        included,
+        excluded,
+        summary: {
+            total: classified.length,
+            included: included.length,
+            excluded: excluded.length,
+            bySource,
+        },
+    };
+}
+/**
+ * Finds a dependency path for a given scope and commit hash.
+ *
+ * Verifies both:
+ * 1. The scope matches a dependency name (or variation)
+ * 2. The commit hash is in that dependency's commit set
+ *
+ * This prevents false positives from mislabeled commits.
+ *
+ * @param scope - The commit scope
+ * @param hash - The commit hash to verify
+ * @param dependencyCommitMap - Map of dependencies to their commit hashes
+ * @returns Dependency path if found and hash verified, undefined otherwise
+ */
+function findDependencyPath(scope, hash, dependencyCommitMap) {
+    const normalizedScope = scope.toLowerCase();
+    for (const [depName, depHashes] of dependencyCommitMap) {
+        // Check if scope matches dependency name or variations
+        const depVariations = getDependencyVariations(depName);
+        if (depVariations.some((v) => v.toLowerCase() === normalizedScope)) {
+            // CRITICAL: Verify the commit actually touched this dependency's files
+            // This prevents false positives from mislabeled commits
+            if (depHashes.has(hash)) {
+                return [depName];
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Generates name variations for a dependency to enable flexible scope matching.
+ *
+ * @param depName - The dependency project or package name
+ * @returns Array of name variations including stripped prefixes
+ */
+function getDependencyVariations(depName) {
+    const variations = [depName];
+    // Handle lib- prefix
+    if (depName.startsWith('lib-')) {
+        variations.push(depName.slice(4));
+    }
+    // Handle @scope/name
+    if (depName.startsWith('@')) {
+        const slashIndex = depName.indexOf('/');
+        if (slashIndex !== -1) {
+            variations.push(depName.slice(slashIndex + 1));
+        }
+    }
+    return variations;
+}
+/**
+ * Creates a classification context from common inputs.
  *
- * @param message - Explanation for why the step was skipped
- * @returns A FlowStepResult with 'skipped' status
+ * @param projectScopes - Scopes that match the project
+ * @param fileCommitHashes - Set of commit hashes that touched project files
+ * @param options - Additional context options
+ * @param options.dependencyCommitMap - Map of dependency names to commit hashes touching them
+ * @param options.infrastructureCommitHashes - Set of commit hashes touching infrastructure paths
+ * @param options.excludeScopes - Scopes to explicitly exclude from classification
+ * @param options.includeScopes - Additional scopes to include as direct matches
+ * @returns A ClassificationContext object
  */
-function createSkippedResult(message) {
+function createClassificationContext(projectScopes, fileCommitHashes, options) {
     return {
-        status: 'skipped',
-        message,
+        projectScopes,
+        fileCommitHashes,
+        dependencyCommitMap: options?.dependencyCommitMap,
+        infrastructureCommitHashes: options?.infrastructureCommitHashes,
+        excludeScopes: options?.excludeScopes ?? DEFAULT_EXCLUDE_SCOPES,
+        includeScopes: options?.includeScopes,
     };
 }
-
-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
+ * Creates a modified conventional commit with scope handling based on classification.
  *
- * State updates:
- * - publishedVersion: Latest version on registry (null if not published)
- * - currentVersion: Version from local package.json
- * - isFirstRelease: True if never published
+ * For direct commits, the scope is removed (redundant in project changelog).
+ * For indirect commits, the scope is preserved (provides context).
  *
- * @returns A FlowStep that fetches registry information
+ * @param classified - Commit with classification metadata determining scope display
+ * @returns A conventional commit with appropriate scope handling
  */
-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}`;
+function toChangelogCommit(classified) {
+    const { commit, preserveScope } = classified;
+    if (!preserveScope && commit.scope) {
+        // Remove the scope for direct commits
         return {
-            status: 'success',
-            stateUpdates: {
-                publishedVersion,
-                currentVersion,
-                isFirstRelease,
-            },
-            message,
+            ...commit,
+            scope: undefined,
+            // Rebuild raw to reflect removed scope
+            raw: rebuildRawWithoutScope(commit),
         };
-    });
+    }
+    return commit;
+}
+/**
+ * Reconstructs a conventional commit message string without the scope portion.
+ *
+ * @param commit - The conventional commit to rebuild
+ * @returns Reconstructed raw message with scope removed
+ */
+function rebuildRawWithoutScope(commit) {
+    const breaking = commit.breaking && !commit.breakingDescription ? '!' : '';
+    const header = `${commit.type}${breaking}: ${commit.subject}`;
+    if (!commit.body && commit.footers.length === 0) {
+        return header;
+    }
+    let raw = header;
+    if (commit.body) {
+        raw += `\n\n${commit.body}`;
+    }
+    for (const footer of commit.footers) {
+        raw += `\n${footer.key}${footer.separator}${footer.value}`;
+    }
+    return raw;
 }
 
 /**
- * Safe copies of Error built-ins via factory functions.
+ * Creates a matcher that checks if commit scope matches any of the given scopes.
  *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides factory functions that use Reflect.construct internally.
+ * @param scopes - Scopes to match against (case-insensitive)
+ * @returns Matcher that returns true if scope matches
  *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
+ * @example
+ * const matcher = scopeMatcher(['ci', 'build', 'tooling'])
+ * matcher({ scope: 'CI', ... }) // true
+ * matcher({ scope: 'feat', ... }) // false
+ */
+function scopeMatcher(scopes) {
+    const normalizedScopes = createSet(scopes.map((s) => s.toLowerCase()));
+    return (ctx) => {
+        if (!ctx.scope)
+            return false;
+        return normalizedScopes.has(ctx.scope.toLowerCase());
+    };
+}
+/**
+ * Creates a matcher that checks if commit scope starts with any of the given prefixes.
  *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
+ * @param prefixes - Scope prefixes to match (case-insensitive)
+ * @returns Matcher that returns true if scope starts with any prefix
+ *
+ * @example
+ * const matcher = scopePrefixMatcher(['tool-', 'infra-'])
+ * matcher({ scope: 'tool-package', ... }) // true
+ * matcher({ scope: 'lib-utils', ... }) // false
+ */
+function scopePrefixMatcher(prefixes) {
+    const normalizedPrefixes = prefixes.map((p) => p.toLowerCase());
+    return (ctx) => {
+        if (!ctx.scope)
+            return false;
+        const normalizedScope = ctx.scope.toLowerCase();
+        return normalizedPrefixes.some((prefix) => normalizedScope.startsWith(prefix));
+    };
+}
+/**
+ * Combines matchers with OR logic - returns true if ANY matcher matches.
+ *
+ * @param matchers - Matchers to combine
+ * @returns Combined matcher
+ *
+ * @example
+ * const combined = anyOf(
+ *   scopeMatcher(['ci', 'build']),
+ *   messageMatcher(['[infra]']),
+ *   custom((ctx) => ctx.scope?.startsWith('tool-'))
+ * )
  */
-// Capture references at module initialization time
-const _Error = globalThis.Error;
-const _Reflect$2 = globalThis.Reflect;
+function anyOf(...matchers) {
+    return (ctx) => matchers.some((matcher) => matcher(ctx));
+}
 /**
- * (Safe copy) Creates a new Error using the captured Error constructor.
- * Use this instead of `new Error()`.
+ * Matches common CI/CD scopes.
  *
- * @param message - Optional error message.
- * @param options - Optional error options.
- * @returns A new Error instance.
+ * Matches: ci, cd, build, pipeline, workflow, actions
+ */
+const CI_SCOPE_MATCHER = scopeMatcher(['ci', 'cd', 'build', 'pipeline', 'workflow', 'actions']);
+/**
+ * Matches common tooling/workspace scopes.
+ *
+ * Matches: tooling, workspace, monorepo, nx, root
+ */
+const TOOLING_SCOPE_MATCHER = scopeMatcher(['tooling', 'workspace', 'monorepo', 'nx', 'root']);
+/**
+ * Matches tool-prefixed scopes (e.g., tool-package, tool-scripts).
+ */
+const TOOL_PREFIX_MATCHER = scopePrefixMatcher(['tool-']);
+/**
+ * Combined matcher for common infrastructure patterns.
+ *
+ * Combines CI, tooling, and tool-prefix matchers.
+ */
+anyOf(CI_SCOPE_MATCHER, TOOLING_SCOPE_MATCHER, TOOL_PREFIX_MATCHER);
+/**
+ * Builds a combined matcher from infrastructure configuration.
+ *
+ * Combines scope-based matching with any custom matcher using OR logic.
+ * Path-based matching is handled separately via git queries.
+ *
+ * @param config - Infrastructure configuration
+ * @returns Combined matcher, or null if no matchers configured
+ *
+ * @example
+ * const matcher = buildInfrastructureMatcher({
+ *   scopes: ['ci', 'build'],
+ *   matcher: (ctx) => ctx.scope?.startsWith('tool-')
+ * })
  */
-const createError = (message, options) => _Reflect$2.construct(_Error, [message, options]);
+function buildInfrastructureMatcher(config) {
+    const matchers = [];
+    // Add scope matcher if scopes configured
+    if (config.scopes && config.scopes.length > 0) {
+        matchers.push(scopeMatcher(config.scopes));
+    }
+    // Add custom matcher if provided
+    if (config.matcher) {
+        matchers.push(config.matcher);
+    }
+    // Return combined or null
+    if (matchers.length === 0) {
+        return null;
+    }
+    if (matchers.length === 1) {
+        return matchers[0];
+    }
+    return anyOf(...matchers);
+}
+/**
+ * Creates match context from a git commit.
+ *
+ * Extracts scope from conventional commit message if present.
+ *
+ * @param commit - Git commit to create context for
+ * @param scope - Pre-parsed scope (optional, saves re-parsing)
+ * @returns Match context for use with matchers
+ */
+function createMatchContext(commit, scope) {
+    return {
+        commit,
+        scope,
+        subject: commit.subject,
+        message: commit.message,
+    };
+}
 
 /**
  * Replaces all occurrences of a character in a string.
@@ -602,78 +3221,525 @@ function splitLines(message) {
     return lines;
 }
 
+/**
+ * Default scope filtering configuration.
+ *
+ * Uses DEFAULT_EXCLUDE_SCOPES from commits/classify to ensure consistency
+ * between flow-level filtering and commit classification.
+ */
+const DEFAULT_SCOPE_FILTERING_CONFIG = {
+    strategy: 'hybrid',
+    includeScopes: [],
+    excludeScopes: DEFAULT_EXCLUDE_SCOPES,
+    trackDependencyChanges: false,
+    infrastructure: undefined,
+    infrastructureMatcher: undefined,
+};
+
 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
+ * 1. Uses publishedCommit from npm registry (set by fetch-registry step)
+ * 2. Verifies the commit is reachable from current HEAD
+ * 3. Gets all commits since that commit (or recent commits if first release/fallback)
+ * 4. Parses each commit using conventional commit format
+ * 5. Classifies commits based on scope filtering strategy
+ * 6. Filters to only release-worthy commits that belong to this project
  *
  * State updates:
- * - lastReleaseTag: Tag name of last release (null if first release)
- * - commits: Array of parsed conventional commits
+ * - effectiveBaseCommit: The verified base commit (null if fallback was used)
+ * - commits: Array of parsed conventional commits (for backward compatibility)
+ * - classificationResult: Full classification result with source attribution
  *
  * @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}`);
+        const { git, projectName, projectRoot, packageName, workspaceRoot, config, logger, state } = ctx;
+        // Use publishedCommit from registry (set by fetch-registry step)
+        const { publishedCommit, isFirstRelease } = state;
+        let rawCommits;
+        let effectiveBaseCommit = null;
+        if (publishedCommit && !isFirstRelease) {
+            // CRITICAL: Verify the commit exists and is reachable from HEAD
+            if (git.commitReachableFromHead(publishedCommit)) {
+                rawCommits = git.getCommitsSince(publishedCommit);
+                effectiveBaseCommit = publishedCommit;
+                logger.debug(`Found ${rawCommits.length} commits since ${publishedCommit.slice(0, 7)}`);
             }
             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}`);
-                }
+                // GRACEFUL DEGRADATION: Commit not in history (rebase/force push occurred)
+                logger.warn(`Published commit ${publishedCommit.slice(0, 7)} not found in history. ` +
+                    `This may indicate a rebase or force push occurred after publishing v${state.publishedVersion}. ` +
+                    `Falling back to recent commit analysis.`);
+                rawCommits = git.getCommitLog({ maxCount: 100 });
+                // effectiveBaseCommit stays null - no compare URL will be generated
             }
         }
-        // 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)
+            // First release or no published version
             rawCommits = git.getCommitLog({ maxCount: 100 });
             logger.debug(`First release - analyzing up to ${rawCommits.length} commits`);
         }
-        // Parse commits using conventional commit format
-        const commits = [];
+        // Get scope filtering configuration
+        const scopeFilteringConfig = {
+            ...DEFAULT_SCOPE_FILTERING_CONFIG,
+            ...config.scopeFiltering,
+        };
+        const strategy = resolveStrategy(scopeFilteringConfig.strategy ?? 'hybrid', rawCommits);
+        // Parse commits with conventional commit format
         const releaseTypes = config.releaseTypes ?? ['feat', 'fix', 'perf', 'revert'];
+        const parsedCommits = [];
         for (const rawCommit of rawCommits) {
             const parsed = parseConventionalCommit(rawCommit.message);
             if (parsed.type && releaseTypes.includes(parsed.type)) {
-                commits.push(parsed);
+                parsedCommits.push({
+                    commit: parsed,
+                    raw: {
+                        hash: rawCommit.hash,
+                        shortHash: rawCommit.hash.slice(0, 7),
+                        message: rawCommit.message,
+                        subject: parsed.subject ?? rawCommit.message.split('\n')[0],
+                        body: parsed.body ?? '',
+                        authorName: '',
+                        authorEmail: '',
+                        authorDate: '',
+                        committerName: '',
+                        committerEmail: '',
+                        commitDate: '',
+                        parents: [],
+                        refs: [],
+                    },
+                });
+            }
+        }
+        // Build file commit hashes for hybrid/file-only strategies
+        let fileCommitHashes = createSet();
+        if (strategy === 'hybrid' || strategy === 'file-only') {
+            // Get commits that touched project files using path filter
+            const relativePath = getRelativePath(workspaceRoot, projectRoot);
+            const pathFilteredCommits = effectiveBaseCommit
+                ? git.getCommitsSince(effectiveBaseCommit, { path: relativePath })
+                : git.getCommitLog({ maxCount: 100, path: relativePath });
+            fileCommitHashes = createSet(pathFilteredCommits.map((c) => c.hash));
+            logger.debug(`Found ${fileCommitHashes.size} commits touching ${relativePath}`);
+        }
+        // Derive project scopes
+        const projectScopes = deriveProjectScopes({
+            projectName,
+            packageName,
+            additionalScopes: scopeFilteringConfig.includeScopes,
+        });
+        logger.debug(`Project scopes: ${projectScopes.join(', ')}`);
+        // Build infrastructure commit hashes for file-based infrastructure detection
+        const infrastructureCommitHashes = buildInfrastructureCommitHashes(git, effectiveBaseCommit, rawCommits, parsedCommits, scopeFilteringConfig, logger);
+        // Build dependency commit map if tracking is enabled (Phase 4)
+        let dependencyCommitMap;
+        if (scopeFilteringConfig.trackDependencyChanges) {
+            dependencyCommitMap = buildDependencyCommitMap(git, workspaceRoot, projectName, effectiveBaseCommit, logger);
+        }
+        // Create classification context
+        const classificationContext = createClassificationContext(projectScopes, fileCommitHashes, {
+            excludeScopes: scopeFilteringConfig.excludeScopes,
+            includeScopes: scopeFilteringConfig.includeScopes,
+            infrastructureCommitHashes,
+            dependencyCommitMap,
+        });
+        // Classify commits
+        const classificationResult = classifyCommits(parsedCommits, classificationContext);
+        // Apply strategy-specific filtering
+        const includedCommits = applyStrategyFilter(classificationResult.included, strategy);
+        // Extract conventional commits for backward compatibility
+        // Use toChangelogCommit to properly handle scope based on classification
+        const commits = includedCommits.map((c) => toChangelogCommit(c));
+        // Build message with classification summary
+        const { summary } = classificationResult;
+        const message = buildSummaryMessage(commits.length, rawCommits.length, summary, strategy);
+        logger.debug(`Classification breakdown: direct-scope=${summary.bySource['direct-scope']}, ` +
+            `direct-file=${summary.bySource['direct-file']}, unscoped-file=${summary.bySource['unscoped-file']}, ` +
+            `excluded=${summary.bySource['excluded']}`);
+        return {
+            status: 'success',
+            stateUpdates: {
+                effectiveBaseCommit,
+                commits,
+                classificationResult,
+            },
+            message,
+        };
+    }, {
+        dependsOn: ['fetch-registry'],
+    });
+}
+/**
+ * Resolves the filtering strategy, handling 'inferred' by analyzing commits.
+ *
+ * @param strategy - The configured scope filtering strategy
+ * @param commits - The commits to analyze for strategy inference
+ * @returns The resolved strategy (never 'inferred')
+ */
+function resolveStrategy(strategy, commits) {
+    if (strategy !== 'inferred') {
+        return strategy;
+    }
+    // Infer strategy from commit history
+    // Count commits with conventional scopes
+    let scopedCount = 0;
+    for (const commit of commits) {
+        const parsed = parseConventionalCommit(commit.message);
+        if (parsed.scope) {
+            scopedCount++;
+        }
+    }
+    const scopeRatio = commits.length > 0 ? scopedCount / commits.length : 0;
+    // If >70% of commits have scopes, scope-only is viable
+    // If <30% have scopes, file-only is better
+    // Otherwise, use hybrid
+    if (scopeRatio > 0.7) {
+        return 'scope-only';
+    }
+    else if (scopeRatio < 0.3) {
+        return 'file-only';
+    }
+    return 'hybrid';
+}
+/**
+ * Applies strategy-specific filtering to classified commits.
+ *
+ * @param commits - The classified commits to filter
+ * @param strategy - The resolved filtering strategy to apply
+ * @returns Filtered commits based on the strategy
+ */
+function applyStrategyFilter(commits, strategy) {
+    switch (strategy) {
+        case 'scope-only':
+            // Only include direct-scope commits
+            return commits.filter((c) => c.source === 'direct-scope');
+        case 'file-only':
+            // Only include file-based commits (direct-file, unscoped-file)
+            return commits.filter((c) => c.source === 'direct-file' || c.source === 'unscoped-file');
+        case 'hybrid':
+        default:
+            // Include all non-excluded commits (already filtered in classifyCommits)
+            return commits;
+    }
+}
+/**
+ * Gets the relative path from workspace root to project root.
+ *
+ * @param workspaceRoot - The absolute path to the workspace root
+ * @param projectRoot - The absolute path to the project root
+ * @returns The relative path from workspace to project
+ */
+function getRelativePath(workspaceRoot, projectRoot) {
+    if (projectRoot.startsWith(workspaceRoot)) {
+        return projectRoot.slice(workspaceRoot.length).replace(/^\//, '');
+    }
+    return projectRoot;
+}
+/**
+ * Builds a summary message for the step result.
+ *
+ * @param includedCount - Number of commits included in the release
+ * @param totalCount - Total number of commits analyzed
+ * @param summary - Classification summary object
+ * @param summary.bySource - Count of commits by source type
+ * @param strategy - The filtering strategy used
+ * @returns A human-readable summary message
+ */
+function buildSummaryMessage(includedCount, totalCount, summary, strategy) {
+    if (includedCount === 0) {
+        return `No releasable commits found for this project (${totalCount} total, strategy: ${strategy})`;
+    }
+    const parts = [`Found ${includedCount} releasable commits`, `(${totalCount} total`, `strategy: ${strategy})`];
+    return parts.join(' ');
+}
+/**
+ * Builds a set of commit hashes that touched infrastructure paths or match infrastructure criteria.
+ *
+ * Supports multiple detection methods combined with OR logic:
+ * 1. Path-based: Commits touching configured infrastructure paths (via git)
+ * 2. Scope-based: Commits with scopes matching infrastructure.scopes
+ * 3. Custom matcher: User-provided matching logic
+ *
+ * @param git - Git client for querying commits by path
+ * @param baseCommit - Base commit hash for commit range (null for first release/fallback)
+ * @param rawCommits - All raw commits being analyzed
+ * @param parsedCommits - Parsed commits with conventional commit data
+ * @param config - Scope filtering configuration
+ * @param logger - Logger with debug method for output
+ * @param logger.debug - Debug logging function
+ * @returns Set of commit hashes classified as infrastructure
+ */
+function buildInfrastructureCommitHashes(git, baseCommit, rawCommits, parsedCommits, config, logger) {
+    // Collect all infrastructure commit hashes
+    let infraHashes = createSet();
+    // Method 1: Path-based detection (query git for commits touching infra paths)
+    const infraPaths = config.infrastructure?.paths ?? [];
+    if (infraPaths.length > 0) {
+        for (const infraPath of infraPaths) {
+            const pathCommits = baseCommit
+                ? git.getCommitsSince(baseCommit, { path: infraPath })
+                : git.getCommitLog({ maxCount: 100, path: infraPath });
+            for (const commit of pathCommits) {
+                infraHashes = infraHashes.add(commit.hash);
+            }
+        }
+        logger.debug(`Found ${infraHashes.size} commits touching infrastructure paths: ${infraPaths.join(', ')}`);
+    }
+    // Method 2 & 3: Scope-based and custom matcher detection
+    // Build a combined matcher from infrastructure config and/or custom matcher
+    const configMatcher = config.infrastructure ? buildInfrastructureMatcher(config.infrastructure) : null;
+    const customMatcher = config.infrastructureMatcher;
+    const combinedMatcher = combineMatcher(configMatcher, customMatcher);
+    if (combinedMatcher) {
+        // Build a lookup for parsed commits by hash
+        let parsedByHash = createMap();
+        for (const parsed of parsedCommits) {
+            parsedByHash = parsedByHash.set(parsed.raw.hash, parsed);
+        }
+        // Evaluate each raw commit against the matcher
+        for (const rawCommit of rawCommits) {
+            // Skip if already matched by path
+            if (infraHashes.has(rawCommit.hash))
+                continue;
+            // Get parsed scope if available
+            const parsed = parsedByHash.get(rawCommit.hash);
+            const scope = parsed?.commit.scope;
+            // Create match context and evaluate
+            const context = createMatchContext(rawCommit, scope);
+            if (combinedMatcher(context)) {
+                infraHashes = infraHashes.add(rawCommit.hash);
+            }
+        }
+        logger.debug(`Infrastructure matcher found ${infraHashes.size} total commits`);
+    }
+    // Return undefined if no infrastructure detection configured
+    if (infraHashes.size === 0 && infraPaths.length === 0 && !combinedMatcher) {
+        return undefined;
+    }
+    return infraHashes;
+}
+/**
+ * Combines two optional matchers into one using OR logic.
+ *
+ * @param a - First matcher (may be null)
+ * @param b - Second matcher (may be undefined)
+ * @returns Combined matcher or null if neither provided
+ */
+function combineMatcher(a, b) {
+    if (a && b) {
+        return (ctx) => a(ctx) || b(ctx);
+    }
+    return a ?? b ?? null;
+}
+/**
+ * Builds a map of dependency project names to the commit hashes that touched them.
+ *
+ * This enables accurate indirect-dependency classification by verifying that:
+ * 1. A commit's scope matches a dependency name
+ * 2. The commit actually touched that dependency's files (hash in set)
+ *
+ * Uses lib-project-scope for dependency discovery, avoiding hard NX dependency.
+ *
+ * @param git - Git client for querying commits by path
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param projectName - Name of the project being versioned
+ * @param baseCommit - Base commit hash for commit range (null for first release/fallback)
+ * @param logger - Logger with debug method for output
+ * @param logger.debug - Debug logging function
+ * @returns Map of dependency names to commit hashes touching that dependency
+ */
+function buildDependencyCommitMap(git, workspaceRoot, projectName, baseCommit, logger) {
+    let dependencyMap = createMap();
+    try {
+        // Discover all projects in workspace using lib-project-scope
+        // This gracefully handles NX and non-NX workspaces
+        const projects = discoverNxProjects(workspaceRoot);
+        const projectGraph = buildSimpleProjectGraph(workspaceRoot, projects);
+        // Get dependencies for the current project
+        const projectDeps = projectGraph.dependencies[projectName] ?? [];
+        if (projectDeps.length === 0) {
+            logger.debug(`No dependencies found for project: ${projectName}`);
+            return dependencyMap;
+        }
+        logger.debug(`Found ${projectDeps.length} dependencies for ${projectName}: ${projectDeps.map((d) => d.target).join(', ')}`);
+        // For each dependency, find commits that touched its files
+        for (const dep of projectDeps) {
+            const depNode = projectGraph.nodes[dep.target];
+            if (!depNode?.data?.root) {
+                logger.debug(`Skipping dependency ${dep.target}: no root path found`);
+                continue;
             }
+            const depRoot = depNode.data.root;
+            // Query git for commits touching this dependency's path
+            const depCommits = baseCommit
+                ? git.getCommitsSince(baseCommit, { path: depRoot })
+                : git.getCommitLog({ maxCount: 100, path: depRoot });
+            if (depCommits.length > 0) {
+                const hashSet = createSet(depCommits.map((c) => c.hash));
+                dependencyMap = dependencyMap.set(dep.target, hashSet);
+                logger.debug(`Dependency ${dep.target}: ${depCommits.length} commits at ${depRoot}`);
+            }
+        }
+    }
+    catch (error) {
+        // Graceful degradation: if project discovery fails, return empty map
+        // This allows versioning to proceed without dependency tracking
+        const message = error instanceof Error ? error.message : String(error);
+        logger.debug(`Failed to build dependency map: ${message}`);
+    }
+    return dependencyMap;
+}
+
+/**
+ * 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;
+
+/**
+ * Compares two semantic versions.
+ *
+ * @param a - First version
+ * @param b - Second version
+ * @returns -1 if a < b, 0 if a == b, 1 if a > b
+ *
+ * @example
+ * compare(parseVersion('1.0.0'), parseVersion('2.0.0')) // -1
+ * compare(parseVersion('1.0.0'), parseVersion('1.0.0')) // 0
+ * compare(parseVersion('2.0.0'), parseVersion('1.0.0')) // 1
+ */
+function compare(a, b) {
+    // Compare major, minor, patch
+    if (a.major !== b.major) {
+        return a.major < b.major ? -1 : 1;
+    }
+    if (a.minor !== b.minor) {
+        return a.minor < b.minor ? -1 : 1;
+    }
+    if (a.patch !== b.patch) {
+        return a.patch < b.patch ? -1 : 1;
+    }
+    // Compare prerelease
+    // Version with prerelease has lower precedence than release
+    if (a.prerelease.length === 0 && b.prerelease.length > 0) {
+        return 1; // a is release, b is prerelease -> a > b
+    }
+    if (a.prerelease.length > 0 && b.prerelease.length === 0) {
+        return -1; // a is prerelease, b is release -> a < b
+    }
+    // Both have prerelease - compare identifiers
+    const maxLen = max(a.prerelease.length, b.prerelease.length);
+    for (let i = 0; i < maxLen; i++) {
+        const aId = a.prerelease[i];
+        const bId = b.prerelease[i];
+        // Shorter prerelease array has lower precedence
+        if (aId === undefined && bId !== undefined) {
+            return -1;
+        }
+        if (aId !== undefined && bId === undefined) {
+            return 1;
+        }
+        if (aId === undefined || bId === undefined) {
+            continue;
+        }
+        // Compare identifiers
+        const cmp = compareIdentifiers(aId, bId);
+        if (cmp !== 0) {
+            return cmp;
+        }
+    }
+    return 0;
+}
+/**
+ * Checks if a > b.
+ *
+ * @param a - First version to compare
+ * @param b - Second version to compare
+ * @returns True if a is greater than b
+ */
+function gt(a, b) {
+    return compare(a, b) === 1;
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Compares two prerelease identifiers.
+ * Numeric identifiers have lower precedence than alphanumeric.
+ * Numeric identifiers are compared numerically.
+ * Alphanumeric identifiers are compared lexically.
+ *
+ * @param a - First prerelease identifier
+ * @param b - Second prerelease identifier
+ * @returns -1 if a < b, 0 if equal, 1 if a > b
+ */
+function compareIdentifiers(a, b) {
+    const aIsNumeric = isNumeric(a);
+    const bIsNumeric = isNumeric(b);
+    // Numeric identifiers have lower precedence
+    if (aIsNumeric && !bIsNumeric) {
+        return -1;
+    }
+    if (!aIsNumeric && bIsNumeric) {
+        return 1;
+    }
+    // Both numeric - compare as numbers
+    if (aIsNumeric && bIsNumeric) {
+        const aNum = parseInt(a, 10);
+        const bNum = parseInt(b, 10);
+        if (aNum < bNum)
+            return -1;
+        if (aNum > bNum)
+            return 1;
+        return 0;
+    }
+    // Both alphanumeric - compare lexically
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+/**
+ * Checks if a string consists only of digits.
+ *
+ * @param str - String to check for numeric content
+ * @returns True if string contains only digits
+ */
+function isNumeric(str) {
+    if (str.length === 0)
+        return false;
+    for (let i = 0; i < str.length; i++) {
+        const code = str.charCodeAt(i);
+        if (code < 48 || code > 57) {
+            return false;
         }
-        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'],
-    });
+    }
+    return true;
 }
 
 /**
@@ -693,32 +3759,6 @@ function format(version) {
     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.
  *
@@ -1196,7 +4236,7 @@ function createCalculateBumpStep() {
                 message: 'No version bump needed',
             };
         }
-        // Calculate next version
+        // Parse versions for comparison
         const current = parseVersion(currentVersion ?? '0.0.0');
         if (!current.success || !current.version) {
             return {
@@ -1205,6 +4245,27 @@ function createCalculateBumpStep() {
                 message: `Could not parse current version: ${currentVersion}`,
             };
         }
+        const { publishedVersion } = state;
+        const published = parseVersion(publishedVersion ?? '0.0.0');
+        // Detect pending publication state: currentVersion > publishedVersion
+        // This means a previous bump happened but was never published
+        const isPendingPublication = published.success && published.version && publishedVersion != null && gt(current.version, published.version);
+        if (isPendingPublication && published.version) {
+            // ALWAYS calculate from publishedVersion - commits may have changed
+            const next = increment(published.version, bumpType);
+            const nextVersion = format(next);
+            logger.info(`Pending publication detected: recalculating from ${publishedVersion} → ${nextVersion}`);
+            return {
+                status: 'success',
+                stateUpdates: {
+                    bumpType,
+                    nextVersion,
+                    isPendingPublication: true,
+                },
+                message: `${bumpType} bump (pending): ${publishedVersion} → ${nextVersion}`,
+            };
+        }
+        // Normal path: increment from currentVersion
         const next = increment(current.version, bumpType);
         const nextVersion = format(next);
         return {
@@ -1259,24 +4320,6 @@ function createCheckIdempotencyStep() {
     });
 }
 
-/**
- * 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.
  *
@@ -1291,6 +4334,8 @@ function createChangelogItem(description, options) {
         commits: options?.commits ?? [],
         references: options?.references ?? [],
         breaking: options?.breaking ?? false,
+        source: options?.source,
+        indirect: options?.indirect,
     };
 }
 /**
@@ -1414,96 +4459,6 @@ function getSectionType(heading) {
     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
  *
@@ -1559,6 +4514,25 @@ function parseVersionFromHeading(heading) {
     if (trimmed[pos] === ']') {
         pos++;
     }
+    // Handle markdown link format [version](url) - jscutlery/semver style
+    // This extracts the compare URL from patterns like [0.0.4](https://github.com/.../compare/...)
+    if (trimmed[pos] === '(') {
+        const urlStart = pos + 1;
+        let depth = 1;
+        pos++;
+        // Find matching closing parenthesis (handles nested parens in URLs)
+        while (pos < trimmed.length && depth > 0) {
+            if (trimmed[pos] === '(')
+                depth++;
+            else if (trimmed[pos] === ')')
+                depth--;
+            pos++;
+        }
+        // Extract URL if we found the closing paren
+        if (depth === 0) {
+            compareUrl = trimmed.slice(urlStart, pos - 1);
+        }
+    }
     // Skip whitespace and separator
     while (pos < trimmed.length && (trimmed[pos] === ' ' || trimmed[pos] === '-' || trimmed[pos] === '–')) {
         pos++;
@@ -1575,8 +4549,8 @@ function parseVersionFromHeading(heading) {
     while (pos < trimmed.length && trimmed[pos] === ' ') {
         pos++;
     }
-    // Check for link at end: [compare](url)
-    if (pos < trimmed.length) {
+    // Check for link at end: [compare](url) - only if no URL was already extracted
+    if (pos < trimmed.length && !compareUrl) {
         const linkMatch = extractLink(trimmed.slice(pos));
         if (linkMatch?.url) {
             compareUrl = linkMatch.url;
@@ -2973,20 +5947,28 @@ function serializeIssueRef(ref) {
  * ```
  */
 function addEntry(changelog, entry, options) {
+    const position = options?.position ?? 'start';
+    const replaceExisting = options?.replaceExisting ?? false;
+    const updateMetadata = options?.updateMetadata ?? false;
     // Check for existing entry
     const existingIndex = changelog.entries.findIndex((e) => e.version === entry.version);
-    if (existingIndex !== -1 && true) {
+    if (existingIndex !== -1 && !replaceExisting) {
         throw createError(`Entry with version "${entry.version}" already exists. Use replaceExisting: true to replace.`);
     }
     let newEntries;
-    {
+    if (existingIndex !== -1 && replaceExisting) {
+        // Replace existing entry
+        newEntries = [...changelog.entries];
+        newEntries[existingIndex] = entry;
+    }
+    else {
         // Add new entry
-        const insertIndex = 0 ;
+        const insertIndex = position === 'start' ? 0 : position === 'end' ? changelog.entries.length : position;
         newEntries = [...changelog.entries];
         newEntries.splice(insertIndex, 0, entry);
     }
     // Build new metadata if requested
-    const metadata = changelog.metadata;
+    const metadata = updateMetadata ? { ...changelog.metadata, warnings: [] } : changelog.metadata;
     return {
         ...changelog,
         entries: newEntries,
@@ -2994,6 +5976,144 @@ function addEntry(changelog, entry, options) {
     };
 }
 
+/**
+ * Changelog Entry Removal
+ *
+ * Functions for removing entries from a changelog.
+ */
+/**
+ * Removes multiple entries from a changelog.
+ *
+ * @param changelog - The changelog to remove from
+ * @param versions - The versions to remove
+ * @param options - Optional removal options
+ * @returns A new changelog without the specified entries
+ */
+function removeEntries(changelog, versions, options) {
+    const versionsSet = createSet(versions);
+    const newEntries = changelog.entries.filter((e) => !versionsSet.has(e.version));
+    return {
+        ...changelog,
+        entries: newEntries,
+    };
+}
+
+/**
+ * Creates a platform-specific compare URL for viewing changes between two commits.
+ *
+ * Each platform has a different URL format:
+ * - **GitHub**: `{baseUrl}/compare/{fromCommit}...{toCommit}` (three dots)
+ * - **GitLab**: `{baseUrl}/-/compare/{fromCommit}...{toCommit}` (three dots, `/-/` prefix)
+ * - **Bitbucket**: `{baseUrl}/compare/{toCommit}..{fromCommit}` (two dots, reversed order)
+ * - **Azure DevOps**: `{baseUrl}/compare?version=GT{toCommit}&compareVersion=GT{fromCommit}` (query params)
+ *
+ * For `custom` platforms, a `formatCompareUrl` function must be provided in the repository config.
+ * For `unknown` platforms, returns `null`.
+ *
+ * @param options - Compare URL options including repository, fromCommit, and toCommit
+ * @returns The compare URL string, or null if URL cannot be generated
+ *
+ * @example
+ * ```typescript
+ * // GitHub
+ * createCompareUrl({
+ *   repository: { platform: 'github', baseUrl: 'https://github.com/owner/repo' },
+ *   fromCommit: 'abc1234',
+ *   toCommit: 'def5678'
+ * })
+ * // → 'https://github.com/owner/repo/compare/abc1234...def5678'
+ *
+ * // GitLab
+ * createCompareUrl({
+ *   repository: { platform: 'gitlab', baseUrl: 'https://gitlab.com/group/project' },
+ *   fromCommit: 'abc1234',
+ *   toCommit: 'def5678'
+ * })
+ * // → 'https://gitlab.com/group/project/-/compare/abc1234...def5678'
+ *
+ * // Bitbucket (reversed order)
+ * createCompareUrl({
+ *   repository: { platform: 'bitbucket', baseUrl: 'https://bitbucket.org/owner/repo' },
+ *   fromCommit: 'abc1234',
+ *   toCommit: 'def5678'
+ * })
+ * // → 'https://bitbucket.org/owner/repo/compare/def5678..abc1234'
+ *
+ * // Azure DevOps
+ * createCompareUrl({
+ *   repository: { platform: 'azure-devops', baseUrl: 'https://dev.azure.com/org/proj/_git/repo' },
+ *   fromCommit: 'abc1234',
+ *   toCommit: 'def5678'
+ * })
+ * // → 'https://dev.azure.com/org/proj/_git/repo/compare?version=GTdef5678&compareVersion=GTabc1234'
+ *
+ * // Custom formatter
+ * createCompareUrl({
+ *   repository: {
+ *     platform: 'custom',
+ *     baseUrl: 'https://my-git.internal/repo',
+ *     formatCompareUrl: (from, to) => `https://my-git.internal/diff/${from}/${to}`
+ *   },
+ *   fromCommit: 'abc1234',
+ *   toCommit: 'def5678'
+ * })
+ * // → 'https://my-git.internal/diff/abc1234/def5678'
+ * ```
+ */
+function createCompareUrl(options) {
+    const { repository, fromCommit, toCommit } = options;
+    // Validate inputs
+    if (!repository || !fromCommit || !toCommit) {
+        return null;
+    }
+    // If custom formatter is provided, use it (works for any platform including overrides)
+    if (repository.formatCompareUrl) {
+        return repository.formatCompareUrl(fromCommit, toCommit);
+    }
+    const { platform, baseUrl } = repository;
+    // Cannot generate URL for unknown platforms without a formatter
+    if (platform === 'unknown') {
+        return null;
+    }
+    // Custom platform requires a formatter
+    if (platform === 'custom') {
+        return null;
+    }
+    // Generate URL for known platforms
+    if (isKnownPlatform(platform)) {
+        return formatKnownPlatformCompareUrl(platform, baseUrl, fromCommit, toCommit);
+    }
+    return null;
+}
+/**
+ * Formats a compare URL for known platforms.
+ *
+ * @param platform - Known platform type
+ * @param baseUrl - Repository base URL
+ * @param fromCommit - Source commit hash (older version)
+ * @param toCommit - Target commit hash (newer version)
+ * @returns Formatted compare URL
+ *
+ * @internal
+ */
+function formatKnownPlatformCompareUrl(platform, baseUrl, fromCommit, toCommit) {
+    switch (platform) {
+        case 'github':
+            // GitHub: {baseUrl}/compare/{fromCommit}...{toCommit}
+            return `${baseUrl}/compare/${fromCommit}...${toCommit}`;
+        case 'gitlab':
+            // GitLab: {baseUrl}/-/compare/{fromCommit}...{toCommit}
+            return `${baseUrl}/-/compare/${fromCommit}...${toCommit}`;
+        case 'bitbucket':
+            // Bitbucket: {baseUrl}/compare/{toCommit}..{fromCommit} (reversed order, two dots)
+            return `${baseUrl}/compare/${toCommit}..${fromCommit}`;
+        case 'azure-devops':
+            // Azure DevOps: {baseUrl}/compare?version=GT{toCommit}&compareVersion=GT{fromCommit}
+            // Use encodeURIComponent for query parameter values
+            return `${baseUrl}/compare?version=GT${encodeURIComponent(toCommit)}&compareVersion=GT${encodeURIComponent(fromCommit)}`;
+    }
+}
+
 const GENERATE_CHANGELOG_STEP_ID = 'generate-changelog';
 /**
  * Maps conventional commit types to changelog section types.
@@ -3011,6 +6131,32 @@ const COMMIT_TYPE_TO_SECTION = {
     chore: 'chores',
     style: 'other',
 };
+/**
+ * Checks if a commit source represents an indirect change.
+ *
+ * @param source - The commit source type
+ * @returns True if the commit is indirect (dependency or infrastructure)
+ */
+function isIndirectSource(source) {
+    return source === 'indirect-dependency' || source === 'indirect-infra';
+}
+/**
+ * Groups classified commits by their section type.
+ *
+ * @param commits - Array of classified commits
+ * @returns Record of section type to classified commits
+ */
+function groupClassifiedCommitsBySection(commits) {
+    const groups = {};
+    for (const classified of commits) {
+        const sectionType = COMMIT_TYPE_TO_SECTION[classified.commit.type ?? 'chore'] ?? 'chores';
+        if (!groups[sectionType]) {
+            groups[sectionType] = [];
+        }
+        groups[sectionType].push(classified);
+    }
+    return groups;
+}
 /**
  * Groups commits by their section type.
  *
@@ -3028,6 +6174,35 @@ function groupCommitsBySection(commits) {
     }
     return groups;
 }
+/**
+ * Creates a changelog item from a classified commit.
+ *
+ * Applies scope display rules:
+ * - Direct commits: scope omitted (redundant in project changelog)
+ * - Indirect commits: scope preserved (provides context)
+ *
+ * @param classified - The classified commit with source metadata
+ * @returns A changelog item with proper scope handling
+ */
+function classifiedCommitToItem(classified) {
+    // Apply scope transformation based on classification
+    const commit = toChangelogCommit(classified);
+    const indirect = isIndirectSource(classified.source);
+    let text = commit.subject;
+    // Add scope prefix if preserved (indirect commits)
+    if (commit.scope) {
+        text = `**${commit.scope}:** ${text}`;
+    }
+    // Add breaking change indicator
+    if (commit.breaking) {
+        text = `⚠️ BREAKING: ${text}`;
+    }
+    return createChangelogItem(text, {
+        source: classified.source,
+        indirect,
+        breaking: commit.breaking,
+    });
+}
 /**
  * Creates a changelog item from a conventional commit.
  *
@@ -3073,9 +6248,26 @@ function createGenerateChangelogStep() {
         }
         // Handle case with no commits (e.g., first release)
         if (!commits || commits.length === 0) {
+            // Generate compare URL using commit hashes ONLY
+            // Only generate if we have a valid base commit (effectiveBaseCommit will be null if fallback was used)
+            let compareUrl;
+            if (state.repositoryConfig && state.effectiveBaseCommit) {
+                const currentCommit = ctx.git.getHeadHash();
+                compareUrl =
+                    createCompareUrl({
+                        repository: state.repositoryConfig,
+                        fromCommit: state.effectiveBaseCommit,
+                        toCommit: currentCommit,
+                    }) ?? undefined;
+            }
+            else if (state.publishedCommit && !state.effectiveBaseCommit) {
+                // Log why we're not generating a compare URL
+                ctx.logger.info('Compare URL omitted: published commit not in current history');
+            }
             const entry = createChangelogEntry(nextVersion, {
                 date: createDate().toISOString().split('T')[0],
                 sections: [createChangelogSection('features', 'Features', [createChangelogItem('Initial release')])],
+                compareUrl,
             });
             return {
                 status: 'success',
@@ -3083,41 +6275,109 @@ function createGenerateChangelogStep() {
                 message: 'Generated initial release changelog entry',
             };
         }
-        // Group commits by section
-        const grouped = groupCommitsBySection(commits);
-        // Create sections
+        // Use classification result when available for proper scope handling
+        const { classificationResult } = state;
         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)));
+        if (classificationResult && classificationResult.included.length > 0) {
+            // Use classified commits for proper scope display rules
+            const classifiedCommits = classificationResult.included;
+            // Separate direct and indirect commits
+            const directCommits = classifiedCommits.filter((c) => !isIndirectSource(c.source));
+            const indirectCommits = classifiedCommits.filter((c) => isIndirectSource(c.source));
+            // Add breaking changes section first if any
+            const breakingCommits = classifiedCommits.filter((c) => c.commit.breaking);
+            if (breakingCommits.length > 0) {
+                sections.push(createChangelogSection('breaking', 'Breaking Changes', breakingCommits.map((c) => {
+                    const commit = toChangelogCommit(c);
+                    const text = commit.breakingDescription ?? commit.subject;
+                    const indirect = isIndirectSource(c.source);
+                    return createChangelogItem(commit.scope ? `**${commit.scope}:** ${text}` : text, {
+                        source: c.source,
+                        indirect,
+                        breaking: true,
+                    });
+                })));
+            }
+            // Group direct commits by section
+            const groupedDirect = groupClassifiedCommitsBySection(directCommits);
+            // Add other sections in conventional order (direct commits only)
+            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 = groupedDirect[sectionType];
+                if (sectionCommits && sectionCommits.length > 0) {
+                    sections.push(createChangelogSection(sectionType, heading, sectionCommits.map(classifiedCommitToItem)));
+                }
+            }
+            // Add Dependency Updates section for indirect commits if any
+            if (indirectCommits.length > 0) {
+                sections.push(createChangelogSection('other', // Use 'other' as section type for dependency updates
+                'Dependency Updates', indirectCommits.map((c) => classifiedCommitToItem(c))));
+            }
+        }
+        else {
+            // Fallback: use commits without classification (backward compatibility)
+            const grouped = groupCommitsBySection(commits);
+            // 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)));
+                }
             }
         }
+        // Generate compare URL using commit hashes ONLY
+        // Only generate if we have a valid base commit (effectiveBaseCommit will be null if fallback was used)
+        let compareUrl;
+        if (state.repositoryConfig && state.effectiveBaseCommit) {
+            const currentCommit = ctx.git.getHeadHash();
+            compareUrl =
+                createCompareUrl({
+                    repository: state.repositoryConfig,
+                    fromCommit: state.effectiveBaseCommit,
+                    toCommit: currentCommit,
+                }) ?? undefined;
+            ctx.logger.debug(`Compare URL: ${state.effectiveBaseCommit.slice(0, 7)}...${currentCommit.slice(0, 7)}`);
+        }
+        else if (state.publishedCommit && !state.effectiveBaseCommit) {
+            // Log why we're not generating a compare URL
+            ctx.logger.info('Compare URL omitted: published commit not in current history');
+        }
         // Create the entry
         const entry = createChangelogEntry(nextVersion, {
             date: createDate().toISOString().split('T')[0],
             sections,
+            compareUrl,
         });
         return {
             status: 'success',
@@ -3173,7 +6433,28 @@ function createWriteChangelogStep() {
         }
         // Parse existing and add entry
         const existing = parseChangelog(existingContent);
-        const updated = addEntry(existing, changelogEntry);
+        const isPendingPublication = state.isPendingPublication === true;
+        let changelog = existing;
+        // Clean up stacked entries when in pending publication state
+        if (isPendingPublication && state.publishedVersion) {
+            const publishedVer = parseVersion(state.publishedVersion);
+            if (publishedVer.success && publishedVer.version) {
+                const pubVer = publishedVer.version;
+                const toRemove = changelog.entries
+                    .filter((e) => !e.unreleased)
+                    .filter((e) => {
+                    const ver = parseVersion(e.version);
+                    return ver.success && ver.version && gt(ver.version, pubVer);
+                })
+                    .map((e) => e.version);
+                if (toRemove.length > 0) {
+                    logger.info(`Removing stacked entries: ${toRemove.join(', ')}`);
+                    changelog = removeEntries(changelog, toRemove);
+                }
+            }
+        }
+        // Add entry (replaceExisting handles case where nextVersion entry already exists)
+        const updated = addEntry(changelog, changelogEntry, { replaceExisting: isPendingPublication });
         const serialized = serializeChangelog(updated);
         tree.write(changelogPath, serialized);
         return {
@@ -3210,23 +6491,26 @@ function createUpdatePackageStep() {
             return createSkippedResult('No version bump needed');
         }
         const packageJsonPath = `${projectRoot}/package.json`;
+        logger.debug(`Reading package.json from: ${packageJsonPath}`);
         // Read package.json
         let content;
         try {
             content = tree.read(packageJsonPath, 'utf-8') ?? '';
             if (!content) {
+                logger.error(`package.json not found at ${packageJsonPath}`);
                 return {
                     status: 'failed',
-                    error: createError('package.json not found'),
-                    message: 'Could not read package.json',
+                    error: createError(`package.json not found at ${packageJsonPath}`),
+                    message: `Could not read package.json at ${packageJsonPath}`,
                 };
             }
         }
         catch (error) {
+            logger.error(`Failed to read package.json at ${packageJsonPath}: ${error}`);
             return {
                 status: 'failed',
                 error: error instanceof Error ? error : createError(String(error)),
-                message: 'Failed to read package.json',
+                message: `Failed to read package.json at ${packageJsonPath}`,
             };
         }
         // Parse and update version
@@ -3509,14 +6793,15 @@ const CONVENTIONAL_FLOW_CONFIG = {
  *
  * 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)
+ * 2. Resolve repository configuration (for compare URLs)
+ * 3. Analyze commits since last release
+ * 4. Calculate version bump based on commit types
+ * 5. Check if version already published (idempotency)
+ * 6. Generate changelog entry (with compare URL if repository resolved)
+ * 7. Update package.json version
+ * 8. Write changelog to file
+ * 9. Create git commit (optional)
+ * 10. Create git tag (optional, typically after publish)
  *
  * @param config - Optional configuration overrides
  * @returns A VersionFlow configured for conventional commits
@@ -3541,6 +6826,7 @@ function createConventionalFlow(config) {
     const mergedConfig = { ...CONVENTIONAL_FLOW_CONFIG, ...config };
     return createFlow('conventional', 'Conventional Commits Flow', [
         createFetchRegistryStep(),
+        createResolveRepositoryStep(),
         createAnalyzeCommitsStep(),
         createCalculateBumpStep(),
         createCheckIdempotencyStep(),
@@ -3672,6 +6958,7 @@ function createIndependentFlow(config) {
     const mergedConfig = { ...INDEPENDENT_FLOW_CONFIG, ...config };
     return createFlow('independent', 'Independent Versioning Flow', [
         createFetchRegistryStep(),
+        createResolveRepositoryStep(),
         createAnalyzeCommitsStep(),
         createCalculateBumpStep(),
         createCheckDependentBumpsStep(),
@@ -3700,6 +6987,7 @@ function createIndependentFlow(config) {
 function createBatchReleaseFlow(config) {
     return createFlow('batch-release', 'Batch Release Flow', [
         createFetchRegistryStep(),
+        createResolveRepositoryStep(),
         createAnalyzeCommitsStep(),
         createCalculateBumpStep(),
         createCheckIdempotencyStep(),
@@ -3833,6 +7121,7 @@ function createSyncedFlow(config) {
     const mergedConfig = { ...SYNCED_FLOW_CONFIG, ...config };
     return createFlow('synced', 'Synced Versioning Flow', [
         createFetchRegistryStep(),
+        createResolveRepositoryStep(),
         createAnalyzeCommitsStep(),
         createCalculateBumpStep(),
         createCheckIdempotencyStep(),
@@ -3872,6 +7161,7 @@ function createFixedVersionFlow(version, config) {
     });
     return createFlow('fixed', 'Fixed Version Flow', [
         createFetchRegistryStep(),
+        createResolveRepositoryStep(),
         createAnalyzeCommitsStep(),
         fixedBumpStep,
         createCheckIdempotencyStep(),