@reelout/core 0.1.1 → 0.2.0

package/src/types.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ConsolaInstance } from 'consola/core'
+import type { CommitBase, CommitNote } from 'conventional-commits-parser'
+import type { Hosts } from 'hosted-git-info'
+
+export type CommitType =
+  | 'build'
+  | 'chore'
+  | 'ci'
+  | 'docs'
+  | 'feat'
+  | 'fix'
+  | 'perf'
+  | 'refactor'
+  | 'revert'
+  | 'style'
+  | 'test'
+  | (string & {})
+
+export type { CommitNote }
+
+export interface CommitTrailer {
+  key: string
+  value: string
+}
+
+export interface ParsedCommit extends CommitBase {
+  type: CommitType | null
+  scope: string | null
+  subject: string
+  header: string
+  body: string | null
+  footer: string | null
+}
+
+export interface Commit extends CommitBase {
+  hash: string
+  parent: string[]
+  authorDate: string
+  committerDate: string
+  type: CommitType | null
+  scope: string | null
+  subject: string | null
+  header: string
+  body: string | null
+  footer: string | null
+  trailers: CommitTrailer[]
+  files: readonly string[]
+}
+
+export interface GitRepository {
+  host: Hosts
+  owner: string
+  repo: string
+  url: string
+}
+
+export interface GitAuthor {
+  name: string
+  email: string
+}
+
+export type CommitClassifier = (
+  commit: Commit
+) => ReleaseType | null | undefined
+
+export type ReleaseType = 'major' | 'minor' | 'patch'
+
+export type ReleaseRuleType = 'branch'
+
+export interface ReleaseRule {
+  type: ReleaseRuleType
+  pattern: string
+  prereleaseLabel: string | undefined
+  releaseChannel: string | undefined
+}
+
+export interface ReleaseConfig {
+  author?: Partial<GitAuthor>
+  classifier?: CommitClassifier | Partial<Record<ReleaseType, CommitType[]>>
+  rules?: Record<string, boolean | string | Partial<ReleaseRule>>
+  plugins?: (
+    [string, unknown?] | string | ReleasePlugin | false | null | undefined
+  )[]
+}
+
+export interface ResolvedReleaseConfig {
+  author: GitAuthor
+  classifier: CommitClassifier
+  rules: ReleaseRule[]
+  plugins: ReleasePlugin[]
+}
+
+export interface ReleaseContext extends ResolvedReleaseConfig {
+  cwd: string
+  dryRun: boolean
+  today: string
+  logger: ConsolaInstance
+  repository: GitRepository | null
+  commit: string
+  ref: { name: string; type: ReleaseRuleType }
+  promote: boolean | undefined
+  prereleaseLabel: string | undefined
+  releaseChannel: string | undefined
+  packages: Package[]
+  plans: ReleasePlan[]
+}
+
+export interface Workspace {
+  entry: string
+  members: readonly string[] | null
+}
+
+export interface Package {
+  root: boolean
+  entry: boolean
+  dir: string
+  files?: string | string[] | undefined
+  changelogFile?: string | undefined
+  tag?: Tag | null
+  name: string | undefined
+  version: string | undefined
+  private: boolean | undefined
+  dependencies: string[]
+}
+
+export interface Tag {
+  name: string
+  message?: string | undefined
+}
+
+export interface Release {
+  type: ReleaseType
+  version?: string | null
+  tag?: Tag | null
+  changelog?: string | null
+}
+
+export interface ReleasePlan {
+  package: Package
+  history: Commit[]
+  release: Release | null
+}
+
+export interface ReleasePlugin {
+  name: string
+  version: string
+  configure?: ReleasePluginHook
+  discover?: ReleasePluginHook
+  analyze?: ReleasePluginHook
+  build?: ReleasePluginHook
+  write?: ReleasePluginHook
+  commit?: ReleasePluginHook
+  publish?: ReleasePluginHook
+  finalize?: ReleasePluginHook
+}
+
+export type ReleasePluginHook =
+  ReleasePluginHookHandler | ReleasePluginHookObject
+
+export interface ReleasePluginHookObject {
+  enforce?: ReleasePluginHookEnforce | null | undefined
+  handler: ReleasePluginHookHandler
+}
+
+export type ReleasePluginHookEnforce = 'pre' | 'post'
+
+export type ReleasePluginHookHandler = (
+  context: ReleaseContext
+) =>
+  | undefined
+  | void
+  | ReleasePluginHookRollback
+  | Promise<undefined | void | ReleasePluginHookRollback>
+
+export type ReleasePluginHookRollback = (
+  reason: unknown
+) => void | Promise<void>
+
+export type ReleaseLifecycle = Exclude<keyof ReleasePlugin, 'name' | 'version'>
+
+export type ReleaseStatus = 'success' | 'failure'
+
+export interface ReleaseReport {
+  prereleaseLabel: string | undefined
+  releaseChannel: string | undefined
+  phase: { plugin: string; hook: ReleaseLifecycle } | undefined
+  status: ReleaseStatus
+  reason: string | null
+  plugins: {
+    name: string
+    version: string
+    hooks: string[]
+  }[]
+  packages: {
+    dir: string
+    name: string | undefined
+    version: string | undefined
+  }[]
+  plans: {
+    package: {
+      entry: boolean
+      dir: string
+      name: string | undefined
+      version: string | undefined
+      private: boolean
+    }
+    release: {
+      type: ReleaseType
+      version: string
+      tag: string | null | undefined
+      changelog: string | null | undefined
+    }
+  }[]
+}

package/src/util/buildTrailerPattern.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Build a regular expression to match trailer lines using custom markers.
+ *
+ * Combines the provided marker strings with a standard alphanumeric pattern
+ * to construct a regular expression that matches trailer definitions.
+ *
+ * @param markers Optional array of custom trailer marker strings
+ * @returns A regular expression matching trailer lines
+ */
+export function buildTrailerPattern(markers: readonly string[] = []) {
+  return new RegExp(
+    `^(${markers
+      .map(RegExp.escape)
+      .concat('[A-Za-z0-9_-]+')
+      .join('|')})[ \\t]*:[ \\t]*(.*)$`
+  )
+}

package/src/util/compact.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { isDefined } from './isDefined'
+
+/**
+ * Remove `null` and `undefined` values from an array.
+ *
+ * @param array The array to compact
+ * @returns A new array that does not contain `null` or `undefined` values
+ */
+export function compact<T>(array: readonly (T | null | undefined)[]): T[] {
+  return array.filter(isDefined)
+}

package/src/util/execCommand.ts

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+
+export interface PromiseWithChild<T> extends Promise<T> {
+  child: ChildProcessWithoutNullStreams
+}
+
+let now = new Date('2026-01-01T00:00:00Z').valueOf()
+
+const MUTATING_GIT_COMMANDS = new Set([
+  'commit',
+  'tag',
+  'cherry-pick',
+  'rebase',
+  'merge',
+  'revert',
+  'commit-tree',
+  'mktag',
+])
+
+/**
+ * Execute a command asynchronously and return its standard output.
+ *
+ * @param cwd Working directory for the command
+ * @param command Binary to execute
+ * @param args Command-line arguments
+ * @returns Promise resolving to the stdout string
+ */
+export function execCommand(
+  cwd: string,
+  command: string,
+  args: readonly string[]
+): PromiseWithChild<string> {
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+  }
+
+  if (import.meta.env.MODE === 'test' && command === 'git') {
+    const primaryArg = args.find((arg) => !arg.startsWith('-'))
+
+    if (primaryArg && MUTATING_GIT_COMMANDS.has(primaryArg)) {
+      const date = new Date(now).toISOString()
+      env.GIT_AUTHOR_DATE = date
+      env.GIT_COMMITTER_DATE = date
+      now += 1000
+    }
+  }
+
+  let childProcess!: ChildProcessWithoutNullStreams
+
+  const promise = new Promise<string>((resolve, reject) => {
+    childProcess = spawn(command, args, {
+      cwd,
+      env,
+    })
+
+    childProcess.stdout.setEncoding('utf-8')
+    childProcess.stderr.setEncoding('utf-8')
+
+    let stdout = ''
+    let stderr = ''
+
+    childProcess.stdout.on('data', (data: string) => {
+      stdout += data
+    })
+
+    childProcess.stderr.on('data', (data: string) => {
+      stderr += data
+    })
+
+    childProcess.on('error', (err) => {
+      reject(err)
+    })
+
+    childProcess.on('close', (code, signal) => {
+      if (code === 0) {
+        return resolve(stdout)
+      }
+
+      const quotedCommand = quoteCommandForMessage([command, ...args].join(' '))
+
+      /* istanbul ignore next */
+      const exitStatus =
+        code !== null
+          ? `exit code ${code}`
+          : signal
+            ? `signal ${signal}`
+            : 'unknown status'
+
+      const errorMessage = `Command ${quotedCommand} failed (${exitStatus})`
+
+      const errorDiagnostics = (stderr || stdout).trim()
+
+      const err = new Error(
+        [errorMessage, errorDiagnostics]
+          .filter(Boolean)
+          .join(errorDiagnostics.includes('\n') ? '\n' : ': '),
+        {
+          cause: {
+            code,
+            signal,
+            diagnostics: errorDiagnostics,
+          },
+        }
+      )
+
+      Object.defineProperty(err, 'code', { value: code })
+
+      reject(err)
+    })
+  }) as PromiseWithChild<string>
+
+  promise.child = childProcess
+
+  return promise
+}
+
+function quoteCommandForMessage(command: string): string {
+  if (!command.includes("'")) {
+    return `'${command}'`
+  }
+
+  if (!command.includes('"')) {
+    return `"${command}"`
+  }
+
+  return JSON.stringify(command)
+}

package/src/util/execGit.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { execCommand, type PromiseWithChild } from './execCommand'
+
+/**
+ * Run a git command in a working directory and return its standard output.
+ *
+ * @param cwd Working directory for the git command
+ * @param args Git CLI arguments
+ * @returns Promise resolving to the stdout string
+ */
+export function execGit(
+  cwd: string,
+  args: readonly string[]
+): PromiseWithChild<string> {
+  return execCommand(cwd, 'git', args)
+}

package/src/util/formatError.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Normalize an unknown thrown value for logging or display.
+ *
+ * - If `err` is an `Error`, returns its `message` string.
+ * - Otherwise returns the original `err` value unchanged (may be a string,
+ *   object, number, `null`, or `undefined`).
+ *
+ * This function intentionally does not coerce non-Error values to strings so
+ * callers can decide how to render structured values.
+ *
+ * @param err The thrown value to normalize
+ * @returns The error message when `err` is an `Error`, otherwise the original value
+ */
+export function formatError<T>(err: T): T | string {
+  if (Error.isError(err)) return err.message
+  if (typeof err === 'string') return err
+  return err
+}

package/src/util/formatFile.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import prettier from 'prettier'
+
+/**
+ * Format `content` for `filePath` using Prettier when possible.
+ *
+ * Resolves project/editorconfig settings and formats the provided content.
+ * Returns the original content on error or when no parser is inferred.
+ *
+ * @param filePath Path used to infer parser and config
+ * @param content Source content to format
+ * @returns Formatted content or original content on failure
+ */
+export async function formatFile(
+  filePath: string,
+  content: string
+): Promise<string> {
+  try {
+    const info = await prettier.getFileInfo(filePath, {
+      resolveConfig: true,
+    })
+
+    const config = await prettier.resolveConfig(filePath, {
+      editorconfig: true,
+    })
+
+    if (info.inferredParser == null) {
+      return content
+    }
+
+    return await prettier.format(content, {
+      ...config,
+      parser: info.inferredParser,
+      filepath: filePath,
+    })
+  } catch {
+    return content
+  }
+}

package/src/util/index.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './buildTrailerPattern'
+export * from './compact'
+export * from './execCommand'
+export * from './execGit'
+export * from './formatError'
+export * from './formatFile'
+export * from './interpolate'
+export * from './isCI'
+export * from './isDefined'
+export * from './isMatch'
+export * from './readJson'
+export * from './unique'
+export * from './writeJson'

package/src/util/interpolate.ts

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+const BACKSLASH = '\\'
+const LEFT_BRACE = '{'
+const RIGHT_BRACE = '}'
+const DOT = '.'
+const ESCAPE_CHARS = [BACKSLASH, LEFT_BRACE, RIGHT_BRACE]
+const BANNED_KEYS = ['__proto__', 'constructor', 'prototype']
+
+/**
+ * Interpolate placeholders in `template` using values from `data`.
+ *
+ * - Placeholders use `{path.to.value}` (dot notation).
+ * - Backslash escapes are supported for `{`, `}`, `\`, and `.` inside tokens.
+ * - Tokens that reference banned keys (`__proto__`, `constructor`, `prototype`)
+ *   are left unexpanded to avoid prototype pollution.
+ * - Only own properties are followed when resolving paths; if any step is
+ *   missing, the original token text is preserved.
+ * - Resolved non-object, non-null values are stringified and inserted.
+ * - Unclosed tokens and a trailing backslash are preserved verbatim.
+ *
+ * @param template Template string containing placeholders like `{user.name}`
+ * @param data Object used to resolve placeholder paths
+ * @returns The template with placeholders replaced by corresponding values
+ */
+export function interpolate(
+  template: string,
+  data: Record<string, unknown>
+): string {
+  let result = ''
+  let i = 0
+  let char: string | undefined
+  let nextChar: string | undefined
+
+  while ((char = template[i])) {
+    // Escape handling: if a backslash precedes an escapable char, emit the
+    // escaped character; otherwise emit the backslash itself.
+    if (char === BACKSLASH) {
+      nextChar = template[i + 1]
+
+      if (nextChar !== undefined && ESCAPE_CHARS.includes(nextChar)) {
+        result += nextChar
+        i += 2
+      } else {
+        result += char
+        i += 1
+      }
+    }
+
+    // Placeholder handling: parse a token starting at '{' until a matching '}'.
+    else if (char === LEFT_BRACE) {
+      const keys: string[] = []
+      let key = ''
+      let token = ''
+      let closed = false
+      i += 1
+
+      // Parse token body, supporting escaped characters and escaped dots.
+      while ((char = template[i])) {
+        if (char === RIGHT_BRACE) {
+          closed = true
+          keys.push(key)
+          i += 1
+          break
+        }
+
+        if (char === BACKSLASH) {
+          nextChar = template[i + 1]
+
+          // Allow escaping of brace, backslash, and dot inside tokens.
+          if (
+            nextChar !== undefined &&
+            [...ESCAPE_CHARS, DOT].includes(nextChar)
+          ) {
+            key += nextChar
+            token += nextChar
+            i += 2
+          } else {
+            // Treat an isolated backslash as a literal within the token.
+            key += char
+            token += char
+            i += 1
+          }
+        } else if (char === DOT) {
+          // Dot separates path segments; record the current segment.
+          keys.push(key)
+          key = ''
+          token += char
+          i += 1
+        } else {
+          key += char
+          token += char
+          i += 1
+        }
+      }
+
+      // If token closed with '}', attempt to resolve the path against `data`.
+      if (closed) {
+        let value: unknown = data
+
+        for (const key of keys) {
+          const isSafeKey = !BANNED_KEYS.includes(key)
+
+          // Only follow own properties on objects and skip banned keys.
+          if (
+            value !== null &&
+            typeof value === 'object' &&
+            Object.hasOwn(value, key) &&
+            isSafeKey
+          ) {
+            value = (value as Record<string, unknown>)[key]
+          } else {
+            value = undefined
+            break
+          }
+        }
+
+        // If resolution failed or produced an object/null, preserve the token.
+        if (value == null || typeof value === 'object') {
+          result += LEFT_BRACE + token + RIGHT_BRACE
+        } else {
+          result += String(value)
+        }
+      }
+
+      // Unclosed token: preserve the raw token text (including the opening brace).
+      else {
+        result += LEFT_BRACE + token
+      }
+    }
+
+    // Ordinary characters are appended directly.
+    else {
+      result += char
+      i += 1
+    }
+  }
+
+  return result
+}

package/src/util/isCI.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Detect whether the current process is running in a CI environment.
+ *
+ * Returns true when the standard `CI` environment variable is set to a
+ * truthy value. Explicit string values `"false"` and `"0"` are treated as
+ * false to accommodate CI systems that expose `CI` but allow disabling it.
+ *
+ * This check is intentionally minimal and does not inspect provider-specific
+ * environment variables (e.g., `GITHUB_ACTIONS`, `GITLAB_CI`). Callers that
+ * need provider-level detail should check those variables separately.
+ *
+ * @returns `true` if running in CI; otherwise `false`
+ */
+export function isCI(): boolean {
+  return !!(
+    process.env.CI &&
+    process.env.CI !== 'false' &&
+    process.env.CI !== '0'
+  )
+}

package/src/util/isDefined.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Type guard that asserts a value is neither `null` nor `undefined`.
+ *
+ * @param value Value to test
+ * @returns `true` when `value` is not `null` or `undefined`
+ */
+export function isDefined<T>(value: T): value is NonNullable<T> {
+  return value != null
+}

package/src/util/isMatch.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { minimatch } from 'minimatch'
+
+/**
+ * Determine whether a target string matches glob patterns.
+ *
+ * Matches positive and negative glob patterns using dotfile support. Automatically
+ * expands a single negative pattern by prepending a global wildcard match.
+ *
+ * @param target Target string to evaluate against glob patterns
+ * @param patterns Single glob pattern or list of patterns to evaluate
+ * @returns True if target matches positive patterns and satisfies negative patterns
+ */
+export function isMatch(
+  target: string,
+  patterns: string | readonly string[]
+): boolean {
+  if (typeof patterns === 'string') {
+    if (patterns.startsWith('!')) {
+      patterns = ['**/*', patterns]
+    } else {
+      patterns = [patterns]
+    }
+  }
+
+  const positives: string[] = []
+  const negatives: string[] = []
+
+  for (const pattern of patterns) {
+    if (pattern.startsWith('!')) {
+      negatives.push(pattern)
+    } else {
+      positives.push(pattern)
+    }
+  }
+
+  return (
+    positives.some((pattern) => minimatch(target, pattern, { dot: true })) &&
+    negatives.every((pattern) => minimatch(target, pattern, { dot: true }))
+  )
+}