@hyperfrontend/versioning 0.1.0 → 0.2.0

package/commits/classify/index.cjs.js

@@ -0,0 +1,705 @@
+'use strict';
+
+/**
+ * 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
+    }
+}
+
+/**
+ * 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 = 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.construct(_Set, iterable ? [iterable] : []);
+
+/**
+ * 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 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 createClassificationContext(projectScopes, fileCommitHashes, options) {
+    return {
+        projectScopes,
+        fileCommitHashes,
+        dependencyCommitMap: options?.dependencyCommitMap,
+        infrastructureCommitHashes: options?.infrastructureCommitHashes,
+        excludeScopes: options?.excludeScopes ?? DEFAULT_EXCLUDE_SCOPES,
+        includeScopes: options?.includeScopes,
+    };
+}
+/**
+ * Filters an array of classified commits to only included ones.
+ *
+ * @param commits - Array of classified commits
+ * @returns Only commits marked for inclusion
+ */
+function filterIncluded(commits) {
+    return commits.filter((c) => c.include);
+}
+/**
+ * Extracts conventional commits from classified commits for changelog generation.
+ *
+ * @param commits - Array of classified commits
+ * @returns Array of conventional commits
+ */
+function extractConventionalCommits(commits) {
+    return commits.map((c) => c.commit);
+}
+/**
+ * Creates a modified conventional commit with scope handling based on classification.
+ *
+ * For direct commits, the scope is removed (redundant in project changelog).
+ * For indirect commits, the scope is preserved (provides context).
+ *
+ * @param classified - Commit with classification metadata determining scope display
+ * @returns A conventional commit with appropriate scope handling
+ */
+function toChangelogCommit(classified) {
+    const { commit, preserveScope } = classified;
+    if (!preserveScope && commit.scope) {
+        // Remove the scope for direct commits
+        return {
+            ...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;
+}
+
+/**
+ * Creates a matcher that checks if commit scope matches any of the given scopes.
+ *
+ * @param scopes - Scopes to match against (case-insensitive)
+ * @returns Matcher that returns true if scope matches
+ *
+ * @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.
+ *
+ * @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));
+    };
+}
+/**
+ * Creates a matcher that checks if commit message contains any of the given patterns.
+ *
+ * @param patterns - Patterns to search for in commit message (case-insensitive)
+ * @returns Matcher that returns true if message contains any pattern
+ *
+ * @example
+ * const matcher = messageMatcher(['[infra]', '[ci skip]'])
+ */
+function messageMatcher(patterns) {
+    const normalizedPatterns = patterns.map((p) => p.toLowerCase());
+    return (ctx) => {
+        const normalizedMessage = ctx.message.toLowerCase();
+        return normalizedPatterns.some((pattern) => normalizedMessage.includes(pattern));
+    };
+}
+/**
+ * Creates a matcher from a regex pattern tested against the scope.
+ *
+ * @param pattern - Regex pattern to test against scope
+ * @returns Matcher that returns true if scope matches regex
+ *
+ * @example
+ * const matcher = scopeRegexMatcher(/^(ci|build|tool)-.+/)
+ */
+function scopeRegexMatcher(pattern) {
+    return (ctx) => {
+        if (!ctx.scope)
+            return false;
+        return pattern.test(ctx.scope);
+    };
+}
+/**
+ * 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-'))
+ * )
+ */
+function anyOf(...matchers) {
+    return (ctx) => matchers.some((matcher) => matcher(ctx));
+}
+/**
+ * Combines matchers with AND logic - returns true if ALL matchers match.
+ *
+ * @param matchers - Matchers to combine
+ * @returns Combined matcher
+ *
+ * @example
+ * const combined = allOf(
+ *   scopeMatcher(['deps']),
+ *   messageMatcher(['security'])
+ * )
+ */
+function allOf(...matchers) {
+    return (ctx) => matchers.every((matcher) => matcher(ctx));
+}
+/**
+ * Negates a matcher - returns true if matcher returns false.
+ *
+ * @param matcher - Matcher to negate
+ * @returns Negated matcher
+ *
+ * @example
+ * const notRelease = not(scopeMatcher(['release']))
+ */
+function not(matcher) {
+    return (ctx) => !matcher(ctx);
+}
+/**
+ * Matches common CI/CD scopes.
+ *
+ * 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.
+ */
+const DEFAULT_INFRA_SCOPE_MATCHER = 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-')
+ * })
+ */
+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,
+    };
+}
+/**
+ * Evaluates a commit against an infrastructure matcher.
+ *
+ * @param commit - Git commit to evaluate
+ * @param matcher - Matcher function to apply
+ * @param scope - Pre-parsed scope (optional)
+ * @returns True if commit matches infrastructure criteria
+ */
+function evaluateInfrastructure(commit, matcher, scope) {
+    const context = createMatchContext(commit, scope);
+    return matcher(context);
+}
+
+exports.CI_SCOPE_MATCHER = CI_SCOPE_MATCHER;
+exports.DEFAULT_EXCLUDE_SCOPES = DEFAULT_EXCLUDE_SCOPES;
+exports.DEFAULT_INFRA_SCOPE_MATCHER = DEFAULT_INFRA_SCOPE_MATCHER;
+exports.TOOLING_SCOPE_MATCHER = TOOLING_SCOPE_MATCHER;
+exports.TOOL_PREFIX_MATCHER = TOOL_PREFIX_MATCHER;
+exports.allOf = allOf;
+exports.anyOf = anyOf;
+exports.buildInfrastructureMatcher = buildInfrastructureMatcher;
+exports.classifyCommit = classifyCommit;
+exports.classifyCommits = classifyCommits;
+exports.createClassificationContext = createClassificationContext;
+exports.createClassifiedCommit = createClassifiedCommit;
+exports.createEmptyClassificationSummary = createEmptyClassificationSummary;
+exports.createMatchContext = createMatchContext;
+exports.deriveProjectScopes = deriveProjectScopes;
+exports.evaluateInfrastructure = evaluateInfrastructure;
+exports.extractConventionalCommits = extractConventionalCommits;
+exports.filterIncluded = filterIncluded;
+exports.messageMatcher = messageMatcher;
+exports.not = not;
+exports.scopeIsExcluded = scopeIsExcluded;
+exports.scopeMatcher = scopeMatcher;
+exports.scopeMatchesProject = scopeMatchesProject;
+exports.scopePrefixMatcher = scopePrefixMatcher;
+exports.scopeRegexMatcher = scopeRegexMatcher;
+exports.toChangelogCommit = toChangelogCommit;
+//# sourceMappingURL=index.cjs.js.map