@reelout/core 0.1.1 → 0.2.0

package/src/git/repository/getGitRemote.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Get the URL for the named remote (defaults to `origin`).
+ *
+ * @param cwd Repository working directory
+ * @param remoteName Remote name (defaults to `'origin'`)
+ * @returns Remote URL string or `null` when unavailable
+ */
+export function getGitRemote(
+  cwd: string,
+  remoteName = 'origin'
+): Promise<string | null> {
+  return execGit(cwd, ['remote', 'get-url', remoteName])
+    .then((stdout) => stdout.trim())
+    .catch(() => null)
+}

package/src/git/repository/index.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './ensureGitUserConfig'
+export * from './getGitConfigValue'
+export * from './getGitRemote'
+export * from './isGitShallowRepository'
+export * from './pushGitChanges'
+export * from './resolveGitRepository'
+export * from './withShallowLock'

package/src/git/repository/isGitShallowRepository.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Determine whether the repository at `cwd` is a shallow clone.
+ *
+ * Runs `git rev-parse --is-shallow-repository` to detect shallow clones.
+ * Useful before operations that require full history.
+ *
+ * @param cwd Repository working directory
+ * @returns `true` if shallow, `false` if full clone, or `null` on error
+ */
+export async function isGitShallowRepository(cwd: string): Promise<boolean> {
+  const stdout = (
+    await execGit(cwd, ['rev-parse', '--is-shallow-repository'])
+  ).trim()
+
+  return stdout === 'true'
+}

package/src/git/repository/pushGitChanges.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { compact, execGit } from '#util'
+
+/**
+ * Push a branch and optional tags to the `origin` remote using an atomic push.
+ *
+ * @param cwd Repository working directory
+ * @param branch Branch name to push
+ * @param additionalTags Optional list of tag names to push alongside the branch
+ * @returns Promise that resolves when the push completes
+ */
+export async function pushGitChanges(
+  cwd: string,
+  branch: string | null,
+  ...additionalTags: readonly string[]
+): Promise<void> {
+  await execGit(cwd, [
+    'push',
+    'origin',
+    ...compact([branch, ...additionalTags]),
+    '--atomic',
+  ])
+}

package/src/git/repository/resolveGitRepository.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { GitRepository } from '#types'
+import GitHost from 'hosted-git-info'
+import { getGitRemote } from './getGitRemote'
+
+/**
+ * Resolve Git repository host, owner, and project metadata from the `origin` remote URL.
+ *
+ * @param cwd Repository working directory
+ * @returns Promise that resolves to a `GitRepository` object, or `null` when unavailable
+ */
+export async function resolveGitRepository(
+  cwd: string
+): Promise<GitRepository | null> {
+  const origin = await getGitRemote(cwd)
+
+  if (!origin) {
+    return null
+  }
+
+  const info = GitHost.fromUrl(origin)
+
+  if (
+    info &&
+    typeof info.type === 'string' &&
+    typeof info.user === 'string' &&
+    typeof info.project === 'string'
+  ) {
+    return {
+      host: info.type,
+      owner: info.user,
+      repo: info.project,
+      url: info.browse(),
+    }
+  }
+
+  return null
+}

package/src/git/repository/withShallowLock.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { isGitShallowRepository } from './isGitShallowRepository'
+
+const lockQueue = new Map<string, Promise<void>>()
+
+const context = new AsyncLocalStorage<Set<string>>()
+
+/**
+ * Serialize access to a shallow Git repository while running a callback.
+ *
+ * If `cwd` is a shallow clone, callers from different async contexts are
+ * executed one at a time; nested calls within the same async context run
+ * immediately without waiting. If the repository becomes non-shallow before
+ * a queued turn runs, downstream waiters are released early.
+ *
+ * @param cwd Repository working directory path string
+ * @param callback Function to execute while the lock is held
+ * @returns Promise resolving to the result of `callback`
+ */
+export async function withShallowLock<T>(
+  cwd: string,
+  callback: () => T | Promise<T>
+): Promise<T> {
+  if (!(await isGitShallowRepository(cwd))) {
+    return callback()
+  }
+
+  const active = context.getStore()
+
+  if (active?.has(cwd)) {
+    return callback()
+  }
+
+  const { promise, resolve } = Promise.withResolvers<void>()
+  const previous = lockQueue.get(cwd) ?? Promise.resolve()
+  const queued = previous.then(() => promise)
+
+  lockQueue.set(cwd, queued)
+
+  // Wait until previous tasks complete.
+  await previous
+
+  // If an earlier task made the repo non-shallow, release downstream waiters now.
+  if (!(await isGitShallowRepository(cwd))) {
+    resolve()
+  }
+
+  try {
+    return await context.run(new Set(active).add(cwd), callback)
+  } finally {
+    // Ensure downstream waiters are unblocked even if callback throws.
+    resolve()
+
+    // Remove the queue entry only if no newer task has replaced it.
+    if (lockQueue.get(cwd) === queued) {
+      lockQueue.delete(cwd)
+    }
+  }
+}

package/src/git/revision/detectGitRelationship.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { isGitAncestor } from './isGitAncestor'
+
+export const GIT_REL_FLAGS = {
+  NONE: 0,
+  IS_ANCESTOR: 1,
+  IS_DESCENDANT: 2,
+  IS_EQUAL: 3,
+} as const
+
+export type GitRelFlags = (typeof GIT_REL_FLAGS)[keyof typeof GIT_REL_FLAGS]
+
+/**
+ * Determine the relationship between two git refs.
+ *
+ * Runs `git merge-base --is-ancestor` in both directions and returns a
+ * numeric bitmask using `GIT_REL_FLAGS`. A successful check (exit code 0)
+ * indicates an ancestor relationship; non-zero exit is treated as "not ancestor".
+ *
+ * @param cwd Repository working directory
+ * @param refA First ref (candidate ancestor)
+ * @param refB Second ref (candidate descendant)
+ * @returns Bitmask of type `GitRelFlags`
+ */
+export async function detectGitRelationship(
+  cwd: string,
+  refA: string,
+  refB: string
+): Promise<GitRelFlags> {
+  let flags = GIT_REL_FLAGS.NONE
+
+  const [aIsAncestor, bIsAncestor] = await Promise.all([
+    isGitAncestor(cwd, refA, refB),
+    isGitAncestor(cwd, refB, refA),
+  ])
+
+  if (aIsAncestor) flags |= GIT_REL_FLAGS.IS_ANCESTOR
+  if (bIsAncestor) flags |= GIT_REL_FLAGS.IS_DESCENDANT
+
+  return flags as GitRelFlags
+}

package/src/git/revision/index.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './detectGitRelationship'
+export * from './isGitAncestor'
+export * from './readGitFile'
+export * from './resolveGitRevision'

package/src/git/revision/isGitAncestor.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Determine whether `ancestor` is an ancestor of `descendant`.
+ *
+ * Runs `git merge-base --is-ancestor <ancestor> <descendant>` in the repository at `cwd`.
+ * Resolves to `true` if `ancestor` is an ancestor, `false` if not.
+ * Rethrows errors for invalid refs or other failures.
+ *
+ * @param cwd Repository working directory
+ * @param ancestor Candidate ancestor ref
+ * @param descendant Candidate descendant ref
+ * @returns Resolves to `true` if `ancestor` is an ancestor of `descendant`, `false` otherwise
+ * @throws If a ref is invalid or the Git command fails
+ */
+export function isGitAncestor(
+  cwd: string,
+  ancestor: string,
+  descendant: string
+): Promise<boolean> {
+  return execGit(cwd, ['merge-base', '--is-ancestor', ancestor, descendant])
+    .then(() => true)
+    .catch((err) => {
+      if ((err as { code?: number })?.code === 1) {
+        return false
+      }
+
+      throw err
+    })
+}

package/src/git/revision/readGitFile.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Read a file's contents from a specific Git revision.
+ *
+ * Runs `git show <ref>:<filePath>` and returns the command output as a
+ * string. If the file does not exist at the given revision or the Git
+ * command fails for any reason, the function returns `null`.
+ *
+ * The returned string is the raw file contents as emitted by Git; callers
+ * that need binary-safe handling should decode or process the bytes
+ * accordingly. This function intentionally swallows Git errors and signals
+ * absence via a `null` result rather than throwing.
+ *
+ * @param cwd Repository working directory
+ * @param ref Commit-ish reference (commit SHA, tag, or branch) to read from
+ * @param filePath Path to the file relative to the repository root
+ * @returns File contents as a string, or `null` if the file is unavailable at the ref
+ */
+export function readGitFile(
+  cwd: string,
+  ref: string,
+  filePath: string
+): Promise<string | null> {
+  return execGit(cwd, ['show', `${ref}:${filePath}`]).catch(() => null)
+}

package/src/git/revision/resolveGitRevision.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Resolve a Git revision or commit-ish expression to its full commit hash.
+ *
+ * Runs `git rev-parse --verify <revision>^{commit}` under the hood. Peels annotated
+ * tags, branches, short SHAs, and relative expressions down to a verified commit object.
+ *
+ * @param cwd The repository working directory
+ * @param revision The Git revision or expression to resolve
+ * @returns A promise that resolves to the full, trimmed commit SHA-1 string
+ */
+export async function resolveGitRevision(
+  cwd: string,
+  revision: string
+): Promise<string> {
+  return (
+    await execGit(cwd, ['rev-parse', '--verify', `${revision}^{commit}`])
+  ).trim()
+}

package/src/git/tag/createGitTag.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Create a git tag in the repository at `cwd`.
+ *
+ * Creates an annotated tag when `message` is provided.
+ *
+ * @param cwd Repository working directory
+ * @param tag Tag name to create
+ * @param message Optional tag message (creates an annotated tag when present)
+ * @returns Promise that resolves when the tag is created
+ */
+export async function createGitTag(
+  cwd: string,
+  tag: string,
+  message?: string
+): Promise<void> {
+  await execGit(cwd, [
+    'tag',
+    ...(message ? ['-a', tag, '-m', message, '--cleanup=whitespace'] : [tag]),
+  ])
+}

package/src/git/tag/deleteGitTag.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Delete a local git tag in the repository at `cwd`.
+ *
+ * @param cwd Repository working directory
+ * @param tag Tag name to delete
+ * @returns `true` when deletion succeeded, otherwise `false`
+ */
+export function deleteGitTag(cwd: string, tag: string): Promise<boolean> {
+  return execGit(cwd, ['tag', '-d', tag])
+    .then(() => true)
+    .catch(() => false)
+}

package/src/git/tag/ensureGitTag.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+import { countGitHistory } from '../history/countGitHistory'
+import { withShallowLock } from '../repository/withShallowLock'
+import { deleteGitTag } from './deleteGitTag'
+import { isGitTagPresent } from './isGitTagPresent'
+
+const MIN_HISTORY_DEPTH = 2
+const ORIGIN_NOT_REPO = `fatal: 'origin' does not appear to be a git repository`
+const REMOTE_REF_NOT_FOUND = `fatal: couldn't find remote ref`
+
+/**
+ * Ensure a tag exists locally, fetching it shallowly from `origin` if needed.
+ *
+ * Acquires a shallow-fetch lock, verifies local presence and history depth,
+ * attempts a shallow fetch of `refs/tags/<tag>` when required, and removes a
+ * local tag if the remote reports the tag is missing.
+ *
+ * @param cwd Working directory
+ * @param tag Tag name (for example `v1.2.0`)
+ * @returns `true` if the tag is present or was fetched; otherwise `false`
+ */
+export function ensureGitTag(cwd: string, tag: string): Promise<boolean> {
+  return withShallowLock(cwd, async () => {
+    const tagRef = `refs/tags/${tag}`
+
+    if (
+      (await isGitTagPresent(cwd, tag)) &&
+      (await countGitHistory(cwd, tagRef)) >= MIN_HISTORY_DEPTH
+    ) {
+      return true
+    }
+
+    try {
+      await execGit(cwd, [
+        'fetch',
+        'origin',
+        `${tagRef}:${tagRef}`,
+        `--depth=${MIN_HISTORY_DEPTH}`,
+        '--update-shallow',
+        '--force',
+      ])
+
+      return true
+    } catch (err) {
+      const errorMessage = (err as Error | undefined)?.message
+
+      if (errorMessage?.includes(ORIGIN_NOT_REPO)) {
+        return await isGitTagPresent(cwd, tag)
+      }
+
+      if (errorMessage?.includes(REMOTE_REF_NOT_FOUND)) {
+        if (await isGitTagPresent(cwd, tag)) {
+          await deleteGitTag(cwd, tag)
+        }
+      }
+    }
+
+    return false
+  })
+}

package/src/git/tag/generateGitTagName.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Generate a git tag name for a package.
+ *
+ * For entry packages the tag is `v<version>`. For non-entry packages the
+ * tag is `<name>@<version>`. Returns `null` when `version` is not provided.
+ *
+ * @param entry Whether the package is the repository entry package
+ * @param name Package name (required for non-entry packages)
+ * @param version Package version
+ * @returns Tag string, or `null` when `version` is absent
+ */
+export function generateGitTagName(
+  entry: boolean,
+  name: string | null | undefined,
+  version: string
+): string
+export function generateGitTagName(
+  entry: boolean,
+  name: string | null | undefined,
+  version: string | null | undefined
+): string | null
+export function generateGitTagName(
+  entry: boolean,
+  name: string | null | undefined,
+  version: string | null | undefined
+): string | null {
+  if (!version) {
+    return null
+  }
+
+  if (entry) {
+    return `v${version}`
+  }
+
+  if (!name) {
+    throw new Error('Package name is required to build a tag name.')
+  }
+
+  return `${name}@${version}`
+}

package/src/git/tag/getCurrentGitTag.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Get the tag name that exactly matches the current `HEAD`, if any.
+ *
+ * @param cwd Repository working directory
+ * @returns Tag name or `null` when no exact tag matches HEAD
+ */
+export async function getCurrentGitTag(cwd: string): Promise<string | null> {
+  try {
+    const stdout = await execGit(cwd, ['describe', '--tags', '--exact-match'])
+
+    const tag = stdout.trim()
+
+    /* istanbul ignore next */
+    return tag ? tag : null
+  } catch {
+    return null
+  }
+}

package/src/git/tag/getGitTagMessage.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Get the message of an annotated git tag in the repository at `cwd`.
+ *
+ * @param cwd Repository working directory
+ * @param tag Tag name to query
+ * @returns The tag message string when found, otherwise `undefined`
+ */
+export async function getGitTagMessage(
+  cwd: string,
+  tag: string
+): Promise<string | undefined> {
+  try {
+    const stdout = await execGit(cwd, [
+      'tag',
+      '-l',
+      '--format=%(objecttype)%00%(contents)',
+      tag,
+    ])
+
+    const [objectType, message] = stdout.split('\0')
+
+    if (objectType?.trim() !== 'tag') {
+      return undefined
+    }
+
+    return message?.trim() || undefined
+  } catch {
+    return undefined
+  }
+}

package/src/git/tag/getLatestGitTag.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Get the most recent tag reachable from `HEAD`.
+ *
+ * @param cwd Repository working directory
+ * @returns Latest tag string or `null` when none is found
+ */
+export async function getLatestGitTag(cwd: string): Promise<string | null> {
+  try {
+    const stdout = await execGit(cwd, ['describe', '--tags', '--abbrev=0'])
+    const tag = stdout.trim()
+
+    /* istanbul ignore next */
+    return tag ? tag : null
+  } catch {
+    return null
+  }
+}

package/src/git/tag/index.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './createGitTag'
+export * from './deleteGitTag'
+export * from './ensureGitTag'
+export * from './generateGitTagName'
+export * from './getCurrentGitTag'
+export * from './getGitTagMessage'
+export * from './getLatestGitTag'
+export * from './isGitTagConnected'
+export * from './isGitTagPointed'
+export * from './isGitTagPresent'

package/src/git/tag/isGitTagConnected.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Determine whether a specific git tag commit is reachable from the current HEAD.
+ *
+ * Uses `git merge-base --is-ancestor refs/tags/<tag>^{commit} HEAD` to verify
+ * that the tag's commit is an ancestor of the current reference. Any non-zero
+ * exit status or execution error is treated as "not reachable".
+ *
+ * @param cwd Working directory where the git command will run
+ * @param tag Tag name to evaluate (for example, "v1.2.0")
+ * @returns True if the tag commit is reachable from HEAD, false otherwise
+ */
+export async function isGitTagConnected(
+  cwd: string,
+  tag: string
+): Promise<boolean> {
+  try {
+    await execGit(cwd, [
+      'merge-base',
+      '--is-ancestor',
+      `refs/tags/${tag}^{commit}`,
+      'HEAD',
+    ])
+
+    return true
+  } catch {
+    return false
+  }
+}

package/src/git/tag/isGitTagPointed.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Check whether a given tag points to the provided commit.
+ *
+ * @param cwd Repository working directory
+ * @param tag Tag name to resolve
+ * @param commit Commit hash to compare against
+ * @returns `true` when the tag points at `commit`, otherwise `false`
+ */
+export async function isGitTagPointed(
+  cwd: string,
+  tag: string,
+  commit: string
+): Promise<boolean> {
+  try {
+    await execGit(cwd, [
+      'merge-base',
+      '--is-ancestor',
+      `refs/tags/${tag}^{commit}`,
+      commit,
+    ])
+
+    await execGit(cwd, [
+      'merge-base',
+      '--is-ancestor',
+      commit,
+      `refs/tags/${tag}^{commit}`,
+    ])
+
+    return true
+  } catch {
+    return false
+  }
+}

package/src/git/tag/isGitTagPresent.ts

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { resolveGitRevision } from '../revision/resolveGitRevision'
+
+/**
+ * Determine whether a specific git tag exists locally in the repository.
+ *
+ * @param cwd Working directory for the git command
+ * @param tag Name of the tag to evaluate
+ * @returns True if the tag reference exists locally, false otherwise
+ */
+export function isGitTagPresent(cwd: string, tag: string): Promise<boolean> {
+  return resolveGitRevision(cwd, `refs/tags/${tag}`)
+    .then(() => true)
+    .catch(() => false)
+}

package/src/index.ts

@@ -1,3 +1,9 @@
-// Copyright (c) 2026 Fai Chen. Licensed under the MIT License.
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
 
-export {}
+export * from './cache'
+export * from './config'
+export * from './git'
+export * from './types'
+export * from './util'
+export * from './workflow'