@reelout/core 0.1.1 → 0.2.0

package/src/cache/TTLCache.ts

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+interface Entry<V> {
+  value: V
+  timer: NodeJS.Timeout
+  ttl: number
+}
+
+/**
+ * A simple time-to-live cache that automatically evicts entries after a TTL.
+ *
+ * - Entries are removed automatically when their TTL expires.
+ * - Reading an entry resets its TTL to the original value.
+ * - Setting an existing key clears its previous timer and resets the TTL.
+ *
+ * @template K Type of cache keys
+ * @template V Type of cache values
+ */
+export class TTLCache<K, V> {
+  private cache = new Map<K, Entry<V>>()
+
+  /**
+   * Store a value under `key` for `ttl` milliseconds.
+   *
+   * If the key already exists its previous timer is cleared and the TTL is reset.
+   *
+   * @param key Cache key
+   * @param value Value to store
+   * @param ttl Time to live in milliseconds (default: 60_000)
+   */
+  set(key: K, value: V, ttl: number = 60_000): void {
+    const ref = this.cache.get(key)
+
+    if (ref) {
+      clearTimeout(ref.timer)
+    }
+
+    const timer = setTimeout(() => {
+      this.cache.delete(key)
+    }, ttl).unref()
+
+    this.cache.set(key, { value, timer, ttl })
+  }
+
+  /**
+   * Retrieve the value for `key`, or `undefined` if not present.
+   *
+   * Reading an entry resets its TTL to the original `ttl` provided when it was set.
+   *
+   * @param key Cache key
+   * @returns The stored value or `undefined` if not present
+   */
+  get(key: K): V | undefined {
+    const ref = this.cache.get(key)
+
+    if (!ref) return undefined
+
+    this.set(key, ref.value, ref.ttl)
+
+    return ref.value
+  }
+
+  /**
+   * Check whether `key` exists in the cache.
+   *
+   * @param key Cache key
+   * @returns `true` if present; otherwise `false`
+   */
+  has(key: K): boolean {
+    return this.cache.has(key)
+  }
+
+  /**
+   * Remove `key` from the cache and clear its eviction timer.
+   *
+   * @param key Cache key
+   * @returns `true` if the key was present and removed; otherwise `false`
+   */
+  delete(key: K): boolean {
+    const ref = this.cache.get(key)
+
+    if (!ref) return false
+
+    clearTimeout(ref.timer)
+
+    return this.cache.delete(key)
+  }
+
+  /**
+   * Clear all entries and their timers.
+   */
+  clear(): void {
+    for (const { timer } of this.cache.values()) {
+      clearTimeout(timer)
+    }
+
+    this.cache.clear()
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './TTLCache'

package/src/changelog.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Package, ReleasePlugin } from '#types'
+import { formatError } from '#util'
+import {
+  buildChangelog,
+  discoverPackageTag,
+  resolvePackageTag,
+  writeChangelog,
+} from '#workflow'
+import { colors } from 'consola/utils'
+import { version } from '../package.json'
+
+/**
+ * Built-in plugin that resolves package tags, generates changelogs, and writes changelog files.
+ *
+ * Stages:
+ * - discover (enforce: post): resolve missing package tags from the repository.
+ * - build: generate changelogs for planned releases (optionally using the previous tag)
+ *   and attach tag messages derived from changelogs.
+ * - write: persist changelog files for each plan (skipped in dry-run).
+ */
+const changelog = (): ReleasePlugin => ({
+  name: '@reelout/core/changelog',
+  version,
+  discover: {
+    enforce: 'post',
+    handler: async (context) => {
+      context.packages = await Promise.all(
+        context.packages.map(async (pkg): Promise<Package> => ({
+          ...pkg,
+          tag: await resolvePackageTag(context.cwd, pkg),
+        }))
+      )
+    },
+  },
+  build: async (context) => {
+    context.plans = await Promise.all(
+      context.plans.map(async (plan) => {
+        plan = { ...plan }
+
+        if (!plan.release) {
+          return plan
+        }
+
+        if (!plan.release.version) {
+          return plan
+        }
+
+        plan.release = { ...plan.release }
+
+        let changelog: string | null | undefined
+
+        let previousTag = plan.package.tag?.name
+
+        if (!previousTag) {
+          previousTag = (await discoverPackageTag(context.cwd, plan.package))
+            ?.name
+        }
+
+        try {
+          changelog = await buildChangelog(context, plan.history, {
+            packageDir: plan.package.dir,
+            changelogFile: plan.package.changelogFile,
+            version: plan.release.version,
+            previousTag,
+            currentTag: plan.release.tag?.name,
+          })
+        } catch (err) {
+          context.logger.warn(
+            colors.yellow(
+              `Changelog could not be generated for package at "${colors.bold(plan.package.dir)}": ${formatError(err)}`
+            )
+          )
+        }
+
+        if (changelog) {
+          plan.release.changelog = changelog
+        }
+
+        return plan
+      })
+    )
+  },
+  write: async (context) => {
+    if (context.dryRun) {
+      return
+    }
+
+    for (const plan of context.plans) {
+      await writeChangelog(context.cwd, plan)
+    }
+  },
+})
+
+export default changelog

package/src/config/const.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleaseLifecycle } from '#types'
+
+export const ALL_FILES = '**/*'
+
+export const DEFAULT_CHANGELOG_FILE = 'CHANGELOG.md'
+
+export const GIT_TRAILER_RELEASE_AGENT = 'Release-Agent'
+
+/**
+ * 1. Primitive Building Blocks
+ *
+ * Base regular expression patterns for wildcards, alphanumeric strings with hyphens,
+ * and standard non-negative integers.
+ */
+const WILDCARD = '\\*'
+const ALPHANUM_DASH = '[0-9a-zA-Z-]+'
+const NUMERIC_IDENTIFIER = '0|[1-9]\\d*'
+
+/**
+ * 2. Package Name & Prefix Constructs
+ *
+ * Matches package name prefixes (unscoped or scoped) or a simple `v` prefix.
+ *
+ * Capture Groups:
+ * - Group 1: Package name (e.g., `my-package` or `@scope/my-package`)
+ */
+const PKG_NAME_PART = `(?:${WILDCARD}|${ALPHANUM_DASH})`
+const CAPTURED_PACKAGE_NAME = `(${PKG_NAME_PART}|@${PKG_NAME_PART}\\/${PKG_NAME_PART})`
+const OPTIONAL_VERSION_PREFIX = `(?:v|${CAPTURED_PACKAGE_NAME}@)`
+
+/**
+ * 3. Core SemVer Components
+ *
+ * Matches standard `MAJOR.MINOR.PATCH` versions or wildcard variants (e.g., `1.0.0`, `*.*.*`).
+ *
+ * Capture Groups:
+ * - Group 3: Major version
+ * - Group 4: Minor version
+ * - Group 5: Patch version
+ */
+const CAPTURED_VERSION_DIGIT = `(${WILDCARD}|${NUMERIC_IDENTIFIER})`
+const SEMVER_CORE = `${CAPTURED_VERSION_DIGIT}\\.${CAPTURED_VERSION_DIGIT}\\.${CAPTURED_VERSION_DIGIT}`
+
+/**
+ * 4. Prerelease & Build Metadata
+ *
+ * Matches optional prerelease identifiers (e.g., `-alpha.1`) and build metadata (e.g., `+build123`).
+ *
+ * Capture Groups:
+ * - Group 6: Complete prerelease string (without `-`)
+ * - Group 7: Non-numeric prerelease token
+ * - Group 8: Complete build metadata string (without `+`)
+ */
+const CAPTURED_NON_NUMERIC_PRERELEASE_ID = `(\\d*[a-zA-Z-][0-9a-zA-Z-]*)`
+const PRERELEASE_IDENTIFIER = `(?:${WILDCARD}|${NUMERIC_IDENTIFIER}|${CAPTURED_NON_NUMERIC_PRERELEASE_ID})`
+const OPTIONAL_PRERELEASE_SECTION = `(?:-(${PRERELEASE_IDENTIFIER}(?:\\.${PRERELEASE_IDENTIFIER})*))`
+const OPTIONAL_BUILD_SECTION = `(?:\\+(${ALPHANUM_DASH}(?:\\.${ALPHANUM_DASH})*))`
+
+/**
+ * 5. Assembled SemVer Pattern
+ *
+ * Combines core SemVer components with optional prerelease identifiers and build metadata.
+ *
+ * Capture Groups:
+ * - Group 2: Full SemVer version string (excluding package/prefix)
+ */
+const CAPTURED_SEMVER_VERSION = `(${SEMVER_CORE}${OPTIONAL_PRERELEASE_SECTION}?${OPTIONAL_BUILD_SECTION}?)`
+const FULL_SEMVER_PATTERN = `${OPTIONAL_VERSION_PREFIX}?${CAPTURED_SEMVER_VERSION}`
+
+/**
+ * Regular expression to match and capture Semantic Versioning (SemVer) strings,
+ * including optional package prefixes (e.g., `@scope/pkg@`) and `v` prefixes.
+ *
+ * @example
+ * ```ts
+ * SEMVER_REGEX.test('1.0.0') // true
+ * SEMVER_REGEX.test('v1.2.3-beta.1+sha.1234') // true
+ * SEMVER_REGEX.test('@scope/package@1.0.0') // true
+ * ```
+ *
+ * @see {@link https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string SemVer Specification}
+ */
+export const SEMVER_REGEX = new RegExp(FULL_SEMVER_PATTERN)
+
+export const RELEASE_LIFECYCLE_HOOK_LIST = [
+  'configure',
+  'discover',
+  'analyze',
+  'build',
+  'write',
+  'commit',
+  'publish',
+  'finalize',
+] as const satisfies ReleaseLifecycle[]

package/src/config/index.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './const'
+export * from './isSemVerGitTag'
+export * from './normalizeCommitFilter'
+export * from './normalizeReleaseRule'
+export * from './normalizeWorkspace'
+export * from './resolvePlugin'
+export * from './resolveReleaseTarget'
+export * from './sanitizePrereleaseLabel'

package/src/config/isSemVerGitTag.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { SEMVER_REGEX } from './const'
+
+/**
+ * Determine whether a tag string is a valid SemVer-style Git tag.
+ *
+ * Anchors `SEMVER_REGEX.source` for full-string matching and applies the
+ * repository's Git-tag acceptance rules.
+ *
+ * @param tag Tag string to validate
+ * @returns `true` if `tag` is accepted as a SemVer-style Git tag; otherwise `false`
+ */
+export function isSemVerGitTag(tag: string): boolean {
+  const match = new RegExp(`^${SEMVER_REGEX.source}$`).exec(tag)
+
+  if (!match) return false
+
+  const isScopedPackage = Boolean(match[1])
+
+  const hasVersionPrefix = tag.startsWith('v')
+
+  return isScopedPackage || hasVersionPrefix
+}

package/src/config/normalizeCommitFilter.ts

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { CommitClassifier, ReleaseConfig, ReleaseType } from '#types'
+
+/**
+ * Normalize a commit classifier into a consistent function.
+ *
+ * Accepts `null`/`undefined` (returns no-op classifier), a function classifier,
+ * or a config object mapping commit types to release types. Returns a classifier
+ * function that maps commits to their corresponding release types.
+ *
+ * @param classifier Commit classifier config, function, or falsy value
+ * @returns Normalized classifier function
+ */
+export function normalizeCommitFilter(
+  classifier: ReleaseConfig['classifier'] | null | undefined
+): CommitClassifier {
+  if (classifier == null) {
+    return () => null
+  }
+
+  if (typeof classifier === 'function') {
+    return classifier
+  }
+
+  const map = new Map(
+    Object.entries(classifier).flatMap(([releaseType, commitTypes]) => {
+      return commitTypes.map((commitType) => [
+        commitType,
+        releaseType as ReleaseType,
+      ])
+    })
+  )
+
+  return (commit) => (commit.type ? map.get(commit.type) : null)
+}

package/src/config/normalizeReleaseRule.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleaseContext, ReleaseRule } from '#types'
+
+/**
+ * Normalize a release rule for the given ref.
+ *
+ * If `rule` is `true`, derive the rule from the ref (branch or tag).
+ * Falsy inputs return an empty rule.
+ *
+ * @param ref Current repository ref (branch or tag)
+ * @param rule Rule input to normalize
+ * @returns Normalized `ReleaseRule` object
+ */
+export function normalizeReleaseRule(
+  ref: ReleaseContext['ref'],
+  rule: boolean | string | Partial<ReleaseRule> | null | undefined
+): ReleaseRule {
+  if (rule === true) {
+    switch (ref.type) {
+      case 'branch':
+        rule = ref.name.split('/').at(0)
+        break
+    }
+  }
+
+  if (!rule) {
+    rule = {}
+  }
+
+  if (typeof rule === 'string') {
+    rule = { prereleaseLabel: rule, releaseChannel: rule }
+  }
+
+  return {
+    type: rule.type || ref.type,
+    pattern: rule.pattern || ref.name,
+    prereleaseLabel: rule.prereleaseLabel,
+    releaseChannel: rule.releaseChannel,
+  }
+}

package/src/config/normalizeWorkspace.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Workspace } from '#types'
+import path from 'node:path'
+
+/**
+ * Normalize and validate workspace configuration for a repository.
+ *
+ * Resolves the workspace entry directory relative to `cwd` and normalizes
+ * the path representation. Returns a workspace object with normalized `entry`
+ * and optional workspace members.
+ *
+ * @param cwd Repository working directory
+ * @param workspace Partial workspace configuration (optional)
+ * @returns Normalized workspace object
+ */
+export function normalizeWorkspace(
+  cwd: string,
+  workspace?: {
+    entry?: string | null | undefined
+    members?: readonly string[] | null | undefined
+  }
+): Workspace {
+  let entry = workspace?.entry || '.'
+  const members = workspace?.members ?? null
+
+  entry = path.normalize(path.relative(cwd, path.resolve(cwd, entry)))
+
+  return {
+    entry,
+    members,
+  }
+}

package/src/config/resolvePlugin.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleasePlugin } from '#types'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+/**
+ * Resolve a plugin reference to a `ReleasePlugin` instance.
+ *
+ * Accepts a module specifier, a loaded plugin object, or an initializer
+ * function (optionally with options) and normalizes it to a `ReleasePlugin`,
+ * or `null` when resolution fails.
+ *
+ * @param cwd Base directory used to resolve module specifiers
+ * @param plugin Plugin reference (module path, function, object, or [path, opts])
+ * @returns Resolved `ReleasePlugin` or `null` when not resolvable
+ */
+export async function resolvePlugin(
+  cwd: string,
+  plugin: unknown
+): Promise<ReleasePlugin | null> {
+  let options: unknown
+
+  if (Array.isArray(plugin)) {
+    ;[plugin, options] = plugin
+  }
+
+  if (typeof plugin === 'string') {
+    const require = createRequire(pathToFileURL(cwd))
+    plugin = await import(require.resolve(plugin))
+  }
+
+  if (
+    plugin != null &&
+    typeof plugin === 'object' &&
+    Object.hasOwn(plugin, 'default')
+  ) {
+    plugin = (plugin as { default: unknown }).default
+  }
+
+  if (typeof plugin === 'function') {
+    plugin = plugin(options)
+  }
+
+  if (
+    plugin != null &&
+    typeof plugin === 'object' &&
+    Object.hasOwn(plugin, 'name') &&
+    typeof (plugin as ReleasePlugin).name === 'string'
+  ) {
+    return plugin as ReleasePlugin
+  }
+
+  return null
+}

package/src/config/resolveReleaseTarget.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleaseContext, ReleaseRule } from '#types'
+import { interpolate, isMatch } from '#util'
+import { sanitizePrereleaseLabel } from './sanitizePrereleaseLabel'
+
+export type ResolveReleaseTargetOptions = Record<
+  Extract<keyof ReleaseRule, 'prereleaseLabel' | 'releaseChannel'>,
+  string | boolean | undefined
+>
+
+/**
+ * Resolve prerelease label and release channel for a ref.
+ *
+ * Resolution priority for each key:
+ * 1. Explicit `options` (string values are used verbatim; `false` disables the key).
+ * 2. First matching `rule` (rules are checked in order).
+ * 3. Fallback: derive and sanitize a label from `ref.name`.
+ *
+ * Resolved string values are interpolated with `data` before being returned.
+ *
+ * @param ref Reference context containing `type` and `name`
+ * @param rules Ordered list of release rules to match against
+ * @param options User overrides for `prereleaseLabel` and `releaseChannel`
+ * @param data Values used to interpolate resolved template strings
+ * @returns Partial release rule with resolved `prereleaseLabel` and/or `releaseChannel`
+ */
+export function resolveReleaseTarget(
+  ref: ReleaseContext['ref'],
+  rules: readonly ReleaseRule[],
+  options: ResolveReleaseTargetOptions,
+  data: Record<string, unknown>
+): Partial<ReleaseRule> {
+  const matchedRule = rules.find(
+    (rule) => rule.type === ref.type && isMatch(ref.name, rule.pattern)
+  )
+
+  const resolve = (key: keyof ResolveReleaseTargetOptions) => {
+    const value1 = options[key]
+
+    if (value1 === false) {
+      return undefined
+    }
+
+    if (value1 && typeof value1 === 'string') {
+      return value1
+    }
+
+    const value2 = matchedRule?.[key] || value1
+
+    if (!value2) {
+      return undefined
+    }
+
+    if (typeof value2 === 'string') {
+      return value2
+    }
+
+    return sanitizePrereleaseLabel(ref.name)
+  }
+
+  const prereleaseLabel = resolve('prereleaseLabel')
+
+  const releaseChannel = resolve('releaseChannel')
+
+  return {
+    prereleaseLabel: prereleaseLabel && interpolate(prereleaseLabel, data),
+    releaseChannel: releaseChannel && interpolate(releaseChannel, data),
+  }
+}

package/src/config/sanitizePrereleaseLabel.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Sanitize a string into a safe, semver-compliant prerelease label.
+ *
+ * Replaces sequential non-alphanumeric characters or consecutive hyphens
+ * with a single hyphen, and strips leading or trailing hyphens.
+ *
+ * @param label Raw string to sanitize
+ * @returns Safe string for a prerelease label
+ */
+export function sanitizePrereleaseLabel(label: string): string {
+  return label
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}

package/src/git/branch/getCurrentGitBranch.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Get the current Git branch name.
+ *
+ * Uses `execGit` to run `git symbolic-ref -q --short HEAD` in the provided
+ * working directory and trims the result. Returns an empty string when the
+ * repository is in a detached HEAD state.
+ *
+ * @param cwd The working directory to run the Git command in
+ * @returns The current branch name as a string
+ */
+export async function getCurrentGitBranch(cwd: string): Promise<string> {
+  return (await execGit(cwd, ['symbolic-ref', '-q', '--short', 'HEAD'])).trim()
+}

package/src/git/branch/index.ts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './getCurrentGitBranch'

package/src/git/commit/createGitCommit.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execGit } from '#util'
+
+/**
+ * Stage all changes and create a git commit with the specified message.
+ *
+ * Validates the commit message and working directory status before staging
+ * all changes and executing the commit command.
+ *
+ * @param cwd The target directory path for executing git commands
+ * @param message The message to associate with the commit
+ * @returns A promise that resolves when the operation completes
+ */
+export async function createGitCommit(
+  cwd: string,
+  message: string | null | undefined
+): Promise<void> {
+  if (!message) return
+
+  await execGit(cwd, ['add', '.'])
+
+  const stdout = (await execGit(cwd, ['status', '--porcelain'])).trim()
+
+  if (!stdout) return
+
+  await execGit(cwd, ['commit', '--message', message])
+}

package/src/git/commit/extractMentions.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+const ALPHANUMERIC = '[a-zA-Z0-9]'
+const SEPARATOR = '[-_]'
+const USERNAME = `${ALPHANUMERIC}+(?:${SEPARATOR}+${ALPHANUMERIC}+)*`
+const EMAIL_LOCAL = '[a-zA-Z0-9._%+-]'
+const DOMAIN_SUFFIX = '[a-zA-Z0-9.-]*\\.[a-zA-Z]{2,}'
+const SCOPED_PACKAGE_SPEC_SUFFIX = `/${USERNAME}@[0-9]+\\.[0-9]+\\.[0-9]+`
+
+/**
+ * Extract unique mention handles from the input text string.
+ *
+ * Evaluates `text` against boundary rules to isolate valid handles while
+ * excluding email addresses, domain names, and scoped package specs, then
+ * de-duplicates the resulting handles.
+ *
+ * @param text The input string to parse for mentions
+ * @returns An array of unique mention handles
+ */
+export function extractMentions(text: string): string[] {
+  if (!text) return []
+
+  const regex = new RegExp(
+    `(?<!${EMAIL_LOCAL})@(${USERNAME})\\b(?!${SEPARATOR}|${DOMAIN_SUFFIX}|${SCOPED_PACKAGE_SPEC_SUFFIX})`,
+    'g'
+  )
+
+  const matches = text.matchAll(regex)
+
+  const mentions = new Set(matches.map((match) => match[1] as string))
+
+  return Array.from(mentions)
+}