christiangeorgelucas/conventional-commit-tools

import { CommitMessageRequest, DetectBreakingChangeResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit, computeBreaking } from './lib';

/**
 * Detect whether a raw commit message is a breaking change: either a `!`
 * immediately after the type/scope (e.g. "feat(api)!: ...") or a
 * `BREAKING CHANGE:` / `BREAKING-CHANGE:` footer, per the Conventional
 * Commits v1.0.0 spec. `source` reports which signal(s) were present
 * ("marker" | "footer" | "both" | "none"); `description` is the breaking
 * -change footer's text if there is one, else empty. An empty message
 * yields breaking=false, source="none" — never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function detectBreakingChange(ax: AxiomContext, input: CommitMessageRequest): DetectBreakingChangeResult {
  const out = new DetectBreakingChangeResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    const { breaking, description, source } = computeBreaking(raw);
    out.setBreaking(breaking);
    out.setDescription(description);
    out.setSource(source);
  } catch {
    out.setBreaking(false);
    out.setDescription('');
    out.setSource('none');
  }
  return out;
}

import { CommitMessageRequest, DetermineReleaseTypeResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit, computeBreaking, releaseTypeFor, errorMessage } from './lib';

/**
 * Determine the semver release type a single commit implies: a breaking
 * change (marker or footer) -> "major", "feat" -> "minor", "fix" -> "patch",
 * anything else -> "none". The "major"/"minor"/"patch" values share
 * semver-tools' Increment node's `release_type` vocabulary — but Increment's
 * own release-type whitelist does NOT include "none", so a caller composing
 * the two should branch on `release_type != "none"` before calling Increment
 * (a commit that implies no release should simply not trigger a bump, not be
 * passed through as an invalid release type). On an empty message, returns
 * release_type="none" with `reason` explaining why — never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function determineReleaseType(ax: AxiomContext, input: CommitMessageRequest): DetermineReleaseTypeResult {
  const out = new DetermineReleaseTypeResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    const { breaking } = computeBreaking(raw);
    const { releaseType, reason } = releaseTypeFor(raw.type ?? '', breaking);
    out.setReleaseType(releaseType);
    out.setReason(reason);
  } catch (e) {
    out.setReleaseType('none');
    out.setReason(errorMessage(e, 'could not parse commit message'));
  }
  return out;
}

import { CommitMessageRequest, ExtractFootersResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit, parseFooters } from './lib';

/**
 * Extract all footers/trailers from a raw commit message as token/value
 * pairs — e.g. "Reviewed-by: Alice" -> {token: "Reviewed-by", value:
 * "Alice"}, "Closes #123" -> {token: "Closes", value: "#123"},
 * "BREAKING CHANGE: ..." -> {token: "BREAKING CHANGE", value: "..."}. A
 * continuation line that doesn't start a new trailer is folded into the
 * previous trailer's value. Returns an empty list (never throws) when the
 * message has no footer, or is empty.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function extractFooters(ax: AxiomContext, input: CommitMessageRequest): ExtractFootersResult {
  const out = new ExtractFootersResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    out.setFootersList(parseFooters(raw.footer));
  } catch {
    out.setFootersList([]);
  }
  return out;
}

import { CommitMessageRequest, ExtractIssueReferencesResult, IssueReference } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit } from './lib';

/**
 * Extract every issue/PR reference from a raw commit message — anywhere in
 * the header, body, or footer — e.g. "#123", "Closes #45", "fixes
 * octocat/hello-world#123". Each result carries the raw matched text, the
 * reference action if one preceded it ("Closes", "Fixes", "Resolves", ...,
 * empty if none), the issue number, the "#" prefix, and owner/repository if
 * the reference used the "owner/repo#N" cross-repo form. Returns an empty
 * list (never throws) on an empty message.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function extractIssueReferences(ax: AxiomContext, input: CommitMessageRequest): ExtractIssueReferencesResult {
  const out = new ExtractIssueReferencesResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    const refs = (raw.references ?? []).map((r) => {
      const ir = new IssueReference();
      ir.setRaw(r.raw ?? '');
      ir.setAction(r.action ?? '');
      ir.setIssue(r.issue ?? '');
      ir.setPrefix(r.prefix ?? '');
      ir.setOwner(r.owner ?? '');
      ir.setRepository(r.repository ?? '');
      return ir;
    });
    out.setReferencesList(refs);
  } catch {
    out.setReferencesList([]);
  }
  return out;
}

import { CommitMessageRequest, ExtractMentionsResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit } from './lib';

/**
 * Extract every @mention (e.g. "@octocat") anywhere in a raw commit message
 * — useful for crediting contributors/reviewers in generated changelogs.
 * Returns an empty list (never throws) on an empty message.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function extractMentions(ax: AxiomContext, input: CommitMessageRequest): ExtractMentionsResult {
  const out = new ExtractMentionsResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    out.setMentionsList(raw.mentions ?? []);
  } catch {
    out.setMentionsList([]);
  }
  return out;
}

import { CommitMessageRequest, ExtractScopeResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit } from './lib';

/**
 * Extract just the parenthesized scope (e.g. "api" from "feat(api): ...")
 * from a raw commit message's header. `found` is false (with `scope` empty)
 * when the header has no scope, doesn't conform to "type(scope)!: subject"
 * at all, or the message is empty — never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function extractScope(ax: AxiomContext, input: CommitMessageRequest): ExtractScopeResult {
  const out = new ExtractScopeResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    const scope = raw.scope ?? '';
    out.setScope(scope);
    out.setFound(scope.length > 0);
  } catch {
    out.setScope('');
    out.setFound(false);
  }
  return out;
}

import { CommitMessageRequest, ExtractTypeResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit } from './lib';

/**
 * Extract just the commit type (e.g. "feat", "fix", "docs", "chore",
 * "refactor", "test") from a raw commit message's header. `found` is false
 * (with `type` empty) when the header doesn't conform to
 * "type(scope)!: subject", or on an empty message — never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function extractType(ax: AxiomContext, input: CommitMessageRequest): ExtractTypeResult {
  const out = new ExtractTypeResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    const type = raw.type ?? '';
    out.setType(type);
    out.setFound(type.length > 0);
  } catch {
    out.setType('');
    out.setFound(false);
  }
  return out;
}

import { CommitMessageRequest, ParseCommitResult, ConventionalCommit } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit, toConventionalCommit, errorMessage } from './lib';

/**
 * Parse one raw commit message into its full structured representation:
 * type, scope, subject, body, footer trailers, breaking-change marker/footer,
 * issue references, @mentions, and revert info (if it is a
 * `Revert "..."` commit). `commit.header_matched` is false when the first
 * line does not conform to Conventional Commits' "type(scope)!: subject"
 * form — every other field is still populated best-effort from whatever the
 * underlying parser (conventional-commits-parser) could extract, so a
 * non-conventional message still returns useful structure. `ok` is false
 * (with `error` set and `commit` at its zero value) only for a hard input
 * problem: an empty message. Deterministic; never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function parseCommit(ax: AxiomContext, input: CommitMessageRequest): ParseCommitResult {
  const out = new ParseCommitResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    out.setCommit(toConventionalCommit(raw));
    out.setOk(true);
    return out;
  } catch (e) {
    out.setOk(false);
    out.setError(errorMessage(e, 'parsing commit message'));
    out.setCommit(new ConventionalCommit());
    return out;
  }
}

import { ParseCommitLogRequest, ParseCommitLogResult, ConventionalCommit } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { splitLog, parseRawCommit, toConventionalCommit, placeholderCommit } from './lib';

/**
 * Parse a blob of multiple commit messages — separated by a caller-supplied
 * `delimiter` (required; e.g. "\n---\n" or a git-log-friendly separator) —
 * into an array of structured commits, in order. A fragment that fails to
 * parse still yields a best-effort commit with `header_matched=false` rather
 * than being dropped. `error` is set (with empty `commits`) only for a
 * log-level problem: an empty `delimiter`. Deterministic; never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function parseCommitLog(ax: AxiomContext, input: ParseCommitLogRequest): ParseCommitLogResult {
  const out = new ParseCommitLogResult();
  const { messages, error } = splitLog(input.getLog(), input.getDelimiter());
  if (error) {
    out.setError(error);
    out.setCount(0);
    out.setCommitsList([]);
    return out;
  }

  const commits: ConventionalCommit[] = messages.map((msg) => {
    try {
      return toConventionalCommit(parseRawCommit(msg));
    } catch {
      return placeholderCommit(msg);
    }
  });

  out.setCommitsList(commits);
  out.setCount(commits.length);
  return out;
}

import { CommitMessageRequest, ParseRevertResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit } from './lib';

/**
 * Detect whether a raw commit message is a git-generated revert commit
 * (`Revert "<original header>"\n\nThis reverts commit <hash>.`) and, if so,
 * extract the original commit's header and the reverted commit's hash.
 * `is_revert` is false (with the other fields empty) for an ordinary commit,
 * or on an empty message — never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function parseRevert(ax: AxiomContext, input: CommitMessageRequest): ParseRevertResult {
  const out = new ParseRevertResult();
  try {
    const raw = parseRawCommit(input.getMessage());
    const isRevert = raw.revert != null;
    out.setIsRevert(isRevert);
    out.setRevertedHeader(raw.revert?.header ?? '');
    out.setRevertedHash(raw.revert?.hash ?? '');
  } catch {
    out.setIsRevert(false);
    out.setRevertedHeader('');
    out.setRevertedHash('');
  }
  return out;
}

import { CommitMessageRequest, SplitHeaderBodyResult } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';

/**
 * Split a raw commit message into its header (first line) and body
 * (everything after the first blank-line-delimited gap, trimmed) — a purely
 * structural split that works even on a non-conventional message, unlike
 * every other node in this package. Both fields are trimmed of surrounding
 * whitespace. A message with only one line (including an empty message)
 * returns an empty body — never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function splitHeaderBody(ax: AxiomContext, input: CommitMessageRequest): SplitHeaderBodyResult {
  const out = new SplitHeaderBodyResult();
  const message = input.getMessage();

  const normalized = message.replace(/\r\n/g, '\n');
  const newlineIndex = normalized.indexOf('\n');
  if (newlineIndex === -1) {
    out.setHeader(normalized.trim());
    out.setBody('');
    return out;
  }
  out.setHeader(normalized.slice(0, newlineIndex).trim());
  out.setBody(normalized.slice(newlineIndex + 1).replace(/^\n+/, '').trim());
  return out;
}

import { SummarizeCommitsRequest, SummarizeCommitsResult, ConventionalCommit, TypeCount } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { splitLog, parseRawCommit, toConventionalCommit, placeholderCommit, releaseTypeFor } from './lib';

const RELEASE_RANK: Record<string, number> = { major: 3, minor: 2, patch: 1, none: 0 };

/**
 * Summarize a multi-commit log (same `log`/`delimiter` contract as
 * ParseCommitLog) for changelog generation: `total` commits parsed, a count
 * per commit type, the full list of breaking-change commits, and
 * `overall_release_type` — the highest-precedence release type implied by
 * the set (major > minor > patch > none), i.e. the one version bump the
 * whole batch would justify. A commit type of "" (header didn't match
 * Conventional Commits form) is counted under "(none)". `error` is set (with
 * every other field at its zero value) only for a log-level problem: an
 * empty `delimiter`. Deterministic; never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function summarizeCommits(ax: AxiomContext, input: SummarizeCommitsRequest): SummarizeCommitsResult {
  const out = new SummarizeCommitsResult();
  const { messages, error } = splitLog(input.getLog(), input.getDelimiter());
  if (error) {
    out.setError(error);
    return out;
  }

  const counts = new Map<string, number>();
  const breaking: ConventionalCommit[] = [];
  let overall = 'none';

  for (const msg of messages) {
    let commit: ConventionalCommit;
    try {
      commit = toConventionalCommit(parseRawCommit(msg));
    } catch {
      commit = placeholderCommit(msg);
    }

    const type = commit.getType() || '(none)';
    counts.set(type, (counts.get(type) ?? 0) + 1);
    if (commit.getBreaking()) breaking.push(commit);

    const { releaseType } = releaseTypeFor(commit.getType(), commit.getBreaking());
    if (RELEASE_RANK[releaseType] > RELEASE_RANK[overall]) overall = releaseType;
  }

  const countsByType: TypeCount[] = Array.from(counts.entries()).map(([type, count]) => {
    const tc = new TypeCount();
    tc.setType(type);
    tc.setCount(count);
    return tc;
  });

  out.setTotal(messages.length);
  out.setCountsByTypeList(countsByType);
  out.setBreakingChangesList(breaking);
  out.setOverallReleaseType(overall);
  return out;
}

import { ValidateCommitRequest, ValidateCommitResult, ConventionalCommit, ValidationIssue } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { parseRawCommit, toConventionalCommit, mkIssue, errorMessage } from './lib';

/**
 * Validate a raw commit message against the Conventional Commits v1.0.0
 * specification and report exactly why it fails, if it does. Checks: the
 * header matches "type(scope)!: subject"; `type` is present (and, unless
 * `allow_any_type_case` is set, lowercase — the overwhelming real-world
 * convention, matching commitlint's default); `subject` is non-empty. A
 * commit marked breaking (`!` or a `BREAKING CHANGE:` footer) with no
 * breaking-change description is flagged as a warning, not an error — the
 * spec allows `!` alone with no accompanying footer text. `valid` is true
 * iff no `error`-severity issue was found. `commit` is always the best-effort
 * parse, even when invalid, so a caller can inspect what *was* extracted.
 * Deterministic; never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function validateCommit(ax: AxiomContext, input: ValidateCommitRequest): ValidateCommitResult {
  const out = new ValidateCommitResult();
  const issues: ValidationIssue[] = [];

  let commit: ConventionalCommit;
  try {
    commit = toConventionalCommit(parseRawCommit(input.getMessage()));
  } catch (e) {
    issues.push(mkIssue('UNPARSEABLE_MESSAGE', errorMessage(e, 'parsing commit message'), 'error'));
    out.setValid(false);
    out.setIssuesList(issues);
    out.setCommit(new ConventionalCommit());
    return out;
  }

  if (!commit.getHeaderMatched()) {
    issues.push(mkIssue('INVALID_HEADER_FORMAT', 'header does not match "type(scope)!: subject"', 'error'));
  } else {
    const type = commit.getType();
    if (!type) {
      issues.push(mkIssue('MISSING_TYPE', 'commit type is empty', 'error'));
    } else if (!input.getAllowAnyTypeCase() && type !== type.toLowerCase()) {
      issues.push(mkIssue('TYPE_NOT_LOWERCASE', `type "${type}" is not lowercase`, 'error'));
    }
    if (!commit.getSubject().trim()) {
      issues.push(mkIssue('EMPTY_SUBJECT', 'subject is empty', 'error'));
    }
  }

  if (commit.getBreaking() && !commit.getBreakingDescription().trim()) {
    issues.push(mkIssue(
      'EMPTY_BREAKING_DESCRIPTION',
      'commit is marked breaking but has no description (consider adding a "BREAKING CHANGE:" footer)',
      'warning',
    ));
  }

  out.setValid(!issues.some((i) => i.getSeverity() === 'error'));
  out.setIssuesList(issues);
  out.setCommit(commit);
  return out;
}

import { ValidateSubjectRequest, ValidateSubjectResult, ValidationIssue } from '../gen/messages_pb';
import { AxiomContext } from '../gen/axiomContext';
import { mkIssue, DEFAULT_SUBJECT_MAX_LENGTH } from './lib';

/**
 * Validate a commit subject line (the description after "type(scope): ")
 * against the common, well-defined mechanical rules — deliberately NOT
 * imperative-mood (that requires judgment, not a mechanical check): must be
 * non-empty; must not exceed `max_length` (<= 0 uses the common commitlint
 * default of 100); must not have leading/trailing whitespace; must not end
 * with a period. A subject starting with an uppercase letter is flagged as a
 * "warning" (the lowercase-first-letter convention is common but not
 * universal), not an "error" — `valid` is true iff no `error`-severity issue
 * was found. Deterministic; never throws.
 *
 * @param ax - Platform context: ax.log for logging, ax.secrets for secrets.
 */
export function validateSubject(ax: AxiomContext, input: ValidateSubjectRequest): ValidateSubjectResult {
  const out = new ValidateSubjectResult();
  const subject = input.getSubject();
  out.setLength(subject.length);

  const maxLength = input.getMaxLength() > 0 ? input.getMaxLength() : DEFAULT_SUBJECT_MAX_LENGTH;
  const trimmed = subject.trim();
  const issues: ValidationIssue[] = [];

  if (!trimmed) {
    issues.push(mkIssue('EMPTY_SUBJECT', 'subject is empty', 'error'));
  }
  if (subject.length > maxLength) {
    issues.push(mkIssue('TOO_LONG', `subject is ${subject.length} characters, exceeds max_length ${maxLength}`, 'error'));
  }
  if (subject !== trimmed) {
    issues.push(mkIssue('LEADING_OR_TRAILING_WHITESPACE', 'subject has leading or trailing whitespace', 'error'));
  }
  if (trimmed.endsWith('.')) {
    issues.push(mkIssue('TRAILING_PERIOD', 'subject should not end with a period', 'error'));
  }
  if (trimmed && /^[A-Z]/.test(trimmed)) {
    issues.push(mkIssue('CAPITALIZED_FIRST_LETTER', 'subject starts with an uppercase letter (convention is lowercase)', 'warning'));
  }

  out.setValid(!issues.some((i) => i.getSeverity() === 'error'));
  out.setIssuesList(issues);
  return out;
}