@reelout/core 0.1.1 → 0.2.0

package/src/git/commit/getCurrentGitCommit.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { resolveGitRevision } from '../revision/resolveGitRevision'
+
+/**
+ * Resolve the current commit hash for HEAD in the repository.
+ *
+ * @param cwd The repository working directory
+ * @returns A promise that resolves to the full, trimmed commit SHA-1 string
+ */
+export function getCurrentGitCommit(cwd: string): Promise<string> {
+  return resolveGitRevision(cwd, 'HEAD')
+}

package/src/git/commit/getParsedCommit.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { TTLCache } from '#cache'
+import type { Commit } from '#types'
+import { execGit } from '#util'
+import { parseCommit } from './parseCommit'
+import { GIT_PRETTY_FORMAT, parseGitPrettyFormat } from './parseGitPrettyFormat'
+
+const cache = new TTLCache<string, Commit>()
+
+/**
+ * Retrieve and parse a commit by its reference.
+ *
+ * Fetches the raw git log entry for the specified reference, checks the cache
+ * for an existing entry, and parses the log data if a cache miss occurs.
+ *
+ * @param cwd The current working directory path
+ * @param ref The git reference to fetch
+ * @param markers Optional array of custom trailer marker strings
+ * @returns A structured commit object or null if the operation fails
+ */
+export async function getParsedCommit(
+  cwd: string,
+  ref: string,
+  markers: readonly string[] = []
+): Promise<Commit | null> {
+  try {
+    const stdout = await execGit(cwd, [
+      'log',
+      '-1',
+      ref,
+      '--name-only',
+      `--pretty=format:${GIT_PRETTY_FORMAT}`,
+    ])
+
+    const entry = parseGitPrettyFormat(stdout)
+
+    const key = `${entry.hash}:${entry.parent}:${markers}`
+
+    const cached = cache.get(key)
+
+    if (cached) return cached
+
+    const parsed = await parseCommit(entry, markers)
+
+    cache.set(key, parsed)
+
+    return parsed
+  } catch {
+    return null
+  }
+}

package/src/git/commit/index.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './createGitCommit'
+export * from './extractMentions'
+export * from './getCurrentGitCommit'
+export * from './getParsedCommit'
+export * from './parseCommit'
+export * from './parseGitPrettyFormat'

package/src/git/commit/parseCommit.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Commit, CommitNote, CommitTrailer, ParsedCommit } from '#types'
+import { CommitParser } from 'conventional-commits-parser'
+import { buildTrailerPattern } from '../../util/buildTrailerPattern'
+import { extractMentions } from './extractMentions'
+
+export interface GitLogEntry {
+  hash: string
+  parent: string[]
+  authorDate: string
+  committerDate: string
+  subject: string
+  body: string
+  files: string[]
+}
+
+const BREAKING_HEADER_REGEX = /^([\w-]+)(?:\(([^)]+)\))?!: (.*)$/
+
+const BREAKING_MARKERS: readonly string[] = [
+  'BREAKING CHANGE',
+  'BREAKING-CHANGE',
+]
+
+/**
+ * Parse a git log entry into a structured commit object.
+ *
+ * Combines the commit subject and body, extracts conventional commit metadata
+ * using custom trailer markers and breaking header patterns, and normalizes
+ * dates to ISO format strings.
+ *
+ * @param entry The raw git log entry to parse
+ * @param markers Optional array of custom trailer marker strings
+ * @returns A structured commit object containing parsed details, notes, and mentions
+ */
+export async function parseCommit(
+  entry: GitLogEntry,
+  markers: readonly string[] = []
+): Promise<Commit> {
+  const message = [entry.subject, entry.body].filter(Boolean).join('\n\n')
+
+  const parser = new CommitParser({
+    breakingHeaderPattern: BREAKING_HEADER_REGEX,
+    noteKeywords: [],
+    notesPattern: () => buildTrailerPattern(BREAKING_MARKERS.concat(markers)),
+  })
+
+  const commit = parser.parse(message) as object as ParsedCommit
+
+  const notes: CommitNote[] = []
+
+  const trailers: CommitTrailer[] = []
+
+  for (const note of commit.notes) {
+    if (BREAKING_MARKERS.includes(note.title.toUpperCase())) {
+      notes.push(note)
+    }
+
+    trailers.push({
+      key: note.title,
+      value: note.text,
+    })
+  }
+
+  if (notes.length === 0 && BREAKING_HEADER_REGEX.test(commit.header)) {
+    const note: CommitNote = {
+      title: 'BREAKING CHANGE',
+      text: commit.subject,
+    }
+
+    notes.push(note)
+
+    trailers.push({
+      key: note.title,
+      value: note.text,
+    })
+  }
+
+  const mentions = extractMentions(message)
+
+  return {
+    ...commit,
+    hash: entry.hash,
+    parent: entry.parent,
+    authorDate: new Date(entry.authorDate).toISOString(),
+    committerDate: new Date(entry.committerDate).toISOString(),
+    type: commit.type?.toLowerCase() || null,
+    scope: commit.scope || null,
+    subject: commit.subject || null,
+    header: commit.header,
+    body: commit.body,
+    footer: commit.footer,
+    notes,
+    mentions,
+    trailers,
+    files: entry.files,
+  }
+}

package/src/git/commit/parseGitPrettyFormat.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { colors } from 'consola/utils'
+import type { GitLogEntry } from './parseCommit'
+
+/**
+ * Field separator used in the git pretty format to produce a single-line
+ *, machine-parseable record.
+ */
+export const GIT_PRETTY_FIELD_SEPARATOR = '\x1f'
+
+/**
+ * Pretty format string passed to `git log --pretty=format:`. Produces seven
+ * fields separated by `GIT_PRETTY_FIELD_SEPARATOR`:
+ * hash, parents, author date, committer date, subject, body, files.
+ */
+export const GIT_PRETTY_FORMAT = [
+  '%H',
+  '%P',
+  '%aI',
+  '%cI',
+  '%s',
+  '%b',
+  '',
+].join(GIT_PRETTY_FIELD_SEPARATOR)
+
+/**
+ * Parse a single line produced by `git log --pretty=format:${GIT_PRETTY_FORMAT}`.
+ *
+ * The input is expected to contain seven fields separated by
+ * `GIT_PRETTY_FIELD_SEPARATOR`:
+ * 1. `hash` (commit hash)
+ * 2. `parent` (space-separated parent hashes)
+ * 3. `authorDate` (ISO 8601)
+ * 4. `committerDate` (ISO 8601)
+ * 5. `subject`
+ * 6. `body`
+ * 7. `files` (newline-separated list)
+ *
+ * The function trims fields, converts parent hashes into an array, normalizes
+ * dates to ISO strings, and splits `files` into an array. Missing optional
+ * fields are normalized to sensible defaults.
+ *
+ * @param raw Raw pretty-format string produced by git
+ * @returns Parsed `GitLogEntry` with `hash`, `parent`, `authorDate`, `committerDate`, `subject`, `body`, and `files`
+ * @throws If required fields (hash, authorDate, committerDate, subject) are missing or malformed
+ */
+export function parseGitPrettyFormat(raw: string): GitLogEntry {
+  let [hash, parentHashes, authorDate, committerDate, subject, body, files] =
+    raw.split(GIT_PRETTY_FIELD_SEPARATOR)
+
+  hash = hash?.trim()
+  parentHashes = parentHashes?.trim()
+  authorDate = authorDate?.trim()
+  committerDate = committerDate?.trim()
+  subject = subject?.trim()
+  body = body?.trim()
+  files = files?.trim()
+
+  if (!hash || !authorDate || !committerDate || typeof subject !== 'string') {
+    throw new Error(
+      `The input "${colors.bold(raw)}" is not in the expected pretty format.`
+    )
+  }
+
+  return {
+    hash,
+    parent: parentHashes ? parentHashes.split(/\s+/) : [],
+    authorDate: new Date(authorDate).toISOString(),
+    committerDate: new Date(committerDate).toISOString(),
+    subject,
+    body: body ?? '',
+    files: files ? files.split('\n') : [],
+  }
+}

package/src/git/history/countGitHistory.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Count mainline commits reachable from a given reference.
+ *
+ * Uses `git rev-list --count --first-parent` to calculate the length of the
+ * primary history trunk, excluding commits introduced by side-branch merges.
+ *
+ * @param cwd Repository working directory
+ * @param ref Commit reference to count from (defaults to `HEAD`)
+ * @returns Number of commits along the primary branch line up to `ref`
+ */
+export async function countGitHistory(
+  cwd: string,
+  ref: string = 'HEAD'
+): Promise<number> {
+  const stdout = await execGit(cwd, [
+    'rev-list',
+    '--count',
+    '--first-parent',
+    ref,
+  ])
+
+  return Number.parseInt(stdout.trim(), 10)
+}

package/src/git/history/expandGitHistory.ts

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+import { isGitShallowRepository } from '../repository/isGitShallowRepository'
+import { withShallowLock } from '../repository/withShallowLock'
+import { isGitAncestor } from '../revision/isGitAncestor'
+import { resolveGitRevision } from '../revision/resolveGitRevision'
+import { countGitHistory } from './countGitHistory'
+
+export interface ExpandGitHistoryOptions {
+  /**
+   * Number of commits to deepen the history by when paging
+   * @default 50
+   */
+  pageSize?: number | undefined
+
+  /**
+   * Local reference used to measure current shallow depth (for example HEAD)
+   * When provided the function accounts for existing depth before fetching more
+   */
+  from?: string | null | undefined
+
+  /**
+   * Target boundary reference where history deepening should stop
+   * If provided the function will first attempt a single fetch to reach this commit
+   */
+  until?: string | null | undefined
+}
+
+/**
+ * Deepen a shallow clone so additional commits become available.
+ *
+ * Attempts a single `--shallow-since` fetch to reach `until` (if provided),
+ * otherwise deepens by `pageSize`, accounting for existing depth when `from`
+ * is supplied. Operation is serialized to avoid concurrent deepens.
+ *
+ * @param cwd Repository working directory
+ * @param options Options: { pageSize?, from?, until? }
+ * @returns true if history was deepened or already sufficient, otherwise false
+ */
+export async function expandGitHistory(
+  cwd: string,
+  options: ExpandGitHistoryOptions = {}
+): Promise<boolean> {
+  if (!(await isGitShallowRepository(cwd))) {
+    return false
+  }
+
+  return withShallowLock(cwd, async () => {
+    const { until } = options
+    let { from } = options
+    let { pageSize = 50 } = options
+
+    // If an `until` boundary is provided, try a single fetch using the target commit's date
+    if (until) {
+      if (await isGitAncestor(cwd, until, 'HEAD')) {
+        return true
+      }
+
+      const commitDate = (
+        await execGit(cwd, ['show', '-s', '--format=%cI', `${until}^{commit}`])
+      ).trim()
+
+      try {
+        await execGit(cwd, [
+          'fetch',
+          `--shallow-since=${commitDate}`,
+          '--update-shallow',
+          '--filter=blob:none',
+        ])
+
+        return true
+      } catch {}
+    }
+
+    // Incremental deepening: account for existing local depth when `from` is set
+    if (from) {
+      from = await resolveGitRevision(cwd, from)
+
+      const depth = await countGitHistory(cwd, from)
+
+      if (depth > pageSize) {
+        return true
+      }
+
+      // Reduce requested deepen amount by existing depth (exclude the `from` commit)
+      pageSize -= depth - 1
+    }
+
+    // Perform a deepen fetch; if `from` is not an ancestor of HEAD, fetch that ref
+    try {
+      await execGit(cwd, [
+        'fetch',
+        `--deepen=${pageSize}`,
+        '--update-shallow',
+        '--filter=blob:none',
+        ...(from && !(await isGitAncestor(cwd, from, 'HEAD'))
+          ? ['origin', from, 'HEAD']
+          : []),
+      ])
+
+      return true
+    } catch {
+      return false
+    }
+  })
+}

package/src/git/history/index.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './countGitHistory'
+export * from './expandGitHistory'
+export * from './mergeGitHistory'
+export * from './restoreFullGitHistory'
+export * from './showGitHistory'
+export * from './showParsedGitHistory'

package/src/git/history/mergeGitHistory.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Commit } from '#types'
+import {
+  detectGitRelationship,
+  GIT_REL_FLAGS,
+} from '../revision/detectGitRelationship'
+
+/**
+ * Merge two newest-first commit lists into a single deduplicated newest-first list.
+ *
+ * Compares commits by hash, uses git relationship (ancestor/descendant) when needed,
+ * and falls back to committerDate for unrelated commits.
+ *
+ * @param cwd Repository working directory used for relationship checks
+ * @param a Commits from the first source (newest-first)
+ * @param b Commits from the second source (newest-first)
+ * @returns Merged commits in newest-first order with duplicates removed
+ */
+export async function mergeGitHistory(
+  cwd: string,
+  a: readonly Commit[],
+  b: readonly Commit[]
+): Promise<Commit[]> {
+  const merged: Commit[] = []
+  const a2 = [...a]
+  const b2 = [...b]
+  let i = a2.shift()
+  let j = b2.shift()
+
+  while (i && j) {
+    const rel =
+      i.hash === j.hash
+        ? GIT_REL_FLAGS.IS_EQUAL
+        : await detectGitRelationship(cwd, i.hash, j.hash)
+
+    switch (rel) {
+      case GIT_REL_FLAGS.IS_EQUAL:
+        merged.push(i)
+        i = a2.shift()
+        j = b2.shift()
+        break
+
+      case GIT_REL_FLAGS.IS_ANCESTOR:
+        merged.push(j)
+        j = b2.shift()
+        break
+
+      case GIT_REL_FLAGS.IS_DESCENDANT:
+        merged.push(i)
+        i = a2.shift()
+        break
+
+      case GIT_REL_FLAGS.NONE:
+        if (i.committerDate < j.committerDate) {
+          merged.push(j)
+          j = b2.shift()
+        } else {
+          merged.push(i)
+          i = a2.shift()
+        }
+        break
+    }
+  }
+
+  if (i) {
+    merged.push(i)
+  }
+
+  if (j) {
+    merged.push(j)
+  }
+
+  return merged.concat(a2).concat(b2)
+}

package/src/git/history/restoreFullGitHistory.ts

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Convert a shallow clone into a full clone by fetching additional history.
+ *
+ * Runs `git fetch --unshallow`. Returns `true` when the operation succeeds
+ * and `false` on error.
+ *
+ * @param cwd Repository working directory
+ * @returns `true` when the operation succeeded, otherwise `false`
+ */
+export function restoreFullGitHistory(cwd: string): Promise<boolean> {
+  return execGit(cwd, ['fetch', '--unshallow'])
+    .then(() => true)
+    .catch(() => false)
+}

package/src/git/history/showGitHistory.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+import { resolveGitRevision } from '../revision/resolveGitRevision'
+import {
+  expandGitHistory,
+  type ExpandGitHistoryOptions,
+} from './expandGitHistory'
+
+export interface ShowGitHistoryOptions extends ExpandGitHistoryOptions {
+  filePath?: string | readonly string[] | undefined
+}
+
+/**
+ * Yield commit SHAs from repository history in paginated order.
+ *
+ * Ensures commits are available via `expandGitHistory`, resolves `until` to a
+ * commit id, and pages from `from` toward `until`, yielding each commit SHA.
+ * If a git command fails the generator ends silently.
+ *
+ * @param cwd Repository working directory
+ * @param options Supports `from`, `until`, `pageSize`, and `filePath`
+ * @yields Commit SHA strings in paginated order
+ */
+export async function* showGitHistory(
+  cwd: string,
+  options: ShowGitHistoryOptions = {}
+): AsyncGenerator<string> {
+  try {
+    const { filePath, pageSize = 50 } = options
+    let from = options.from || 'HEAD'
+    let until = options.until || undefined
+
+    if (until) {
+      until = await resolveGitRevision(cwd, until)
+    }
+
+    while (true) {
+      await expandGitHistory(cwd, { from, until, pageSize })
+
+      const args = ['rev-list', `--max-count=${pageSize}`, from]
+
+      if (until) {
+        args.push(`^${until}`)
+      }
+
+      if (filePath) {
+        args.push(
+          '--',
+          ...(Array.isArray(filePath) ? filePath : [filePath]).filter(Boolean)
+        )
+      }
+
+      const stdout = await execGit(cwd, args)
+
+      const list = stdout.trim().split('\n').filter(Boolean)
+
+      for (const item of list.slice(0, -1)) {
+        yield item
+      }
+
+      const tail = list.at(-1)
+
+      if (!tail) {
+        return
+      }
+
+      if (tail === from) {
+        yield tail
+
+        from = `${tail}^`
+
+        from = await resolveGitRevision(cwd, from)
+      } else {
+        from = tail
+      }
+    }
+  } catch {}
+}

package/src/git/history/showParsedGitHistory.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Commit } from '#types'
+import { getParsedCommit } from '../commit/getParsedCommit'
+import { showGitHistory, type ShowGitHistoryOptions } from './showGitHistory'
+
+/**
+ * Yield parsed commits sequentially from repository history.
+ *
+ * Fetches commits using `showGitHistory` and parses each SHA with
+ * `getParsedCommit`. Yields successfully parsed `Commit` objects on demand and
+ * omits unparsable commits.
+ *
+ * @param cwd Repository working directory
+ * @param options Filter and pagination options passed to `showGitHistory`
+ * @yields Parsed `Commit` objects in historical order
+ */
+export async function* showParsedGitHistory(
+  cwd: string,
+  options?: ShowGitHistoryOptions
+): AsyncGenerator<Commit> {
+  for await (const commit of showGitHistory(cwd, options)) {
+    const parsed = await getParsedCommit(cwd, commit)
+
+    if (parsed) {
+      yield parsed
+    }
+  }
+}

package/src/git/index.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './branch'
+export * from './commit'
+export * from './history'
+export * from './repository'
+export * from './revision'
+export * from './tag'

package/src/git/repository/ensureGitUserConfig.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+import { getGitConfigValue } from './getGitConfigValue'
+
+/**
+ * Ensure git `user.name` and `user.email` are configured for the repository at `cwd`.
+ *
+ * No-op when the values are already present.
+ *
+ * @param cwd Repository working directory
+ * @param user Object containing `name` and `email` values to set when missing
+ * @returns Promise that resolves when configuration is ensured
+ */
+export async function ensureGitUserConfig(
+  cwd: string,
+  user: { name: string; email: string }
+): Promise<void> {
+  if (
+    (await getGitConfigValue(cwd, 'user.name')) &&
+    (await getGitConfigValue(cwd, 'user.email'))
+  ) {
+    return
+  }
+
+  // https://github.com/actions/checkout?tab=readme-ov-file#push-a-commit-using-the-built-in-token
+  await execGit(cwd, ['config', 'user.name', user.name])
+
+  await execGit(cwd, ['config', 'user.email', user.email])
+}

package/src/git/repository/getGitConfigValue.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Get a local git configuration value for `key` in the repository at `cwd`.
+ *
+ * Returns the config value when present; otherwise `undefined`.
+ *
+ * @param cwd Repository working directory
+ * @param key Git config key to read
+ * @returns The config value or `undefined` if not set
+ */
+export async function getGitConfigValue(
+  cwd: string,
+  key: string
+): Promise<string | undefined> {
+  try {
+    const stdout = await execGit(cwd, ['config', '--local', '--get', key])
+    const value = stdout.trim()
+
+    return value ? value : undefined
+  } catch {
+    return undefined
+  }
+}