@reelout/core 0.1.1 → 0.2.0

package/src/workflow/discovery/verifyPackageTag.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import {
+  ensureGitTag,
+  expandGitHistory,
+  getParsedCommit,
+  isGitTagConnected,
+} from '#git'
+import type { Package } from '#types'
+import { isCommitForPackage } from '../analysis/isCommitForPackage'
+
+/**
+ * Verify a Git tag against package specifications and history connection.
+ *
+ * Ensures the target tag exists locally before parsing its commit data. Rejects
+ * tags that do not target a commit matching the given `pkg`. Expands the history
+ * graph up to the tag reference before verifying structural connectivity.
+ *
+ * @param cwd Repository working directory
+ * @param pkg Package descriptor containing version and location context
+ * @param tagName The name of the Git tag to verify
+ * @returns A promise resolving to true if the tag is valid and connected
+ */
+export async function verifyPackageTag(
+  cwd: string,
+  pkg: Package,
+  tagName: string
+): Promise<boolean> {
+  await ensureGitTag(cwd, tagName)
+
+  const tagRef = `refs/tags/${tagName}`
+
+  const tagCommit = await getParsedCommit(cwd, tagRef)
+
+  if (!tagCommit || !isCommitForPackage(pkg, tagCommit)) {
+    return false
+  }
+
+  await expandGitHistory(cwd, { until: tagRef })
+
+  return isGitTagConnected(cwd, tagName)
+}

package/src/workflow/index.ts

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './analysis'
+export * from './changelog'
+export * from './committing'
+export * from './discovery'
+export * from './report'
+export * from './runner'
+export * from './versioning'

package/src/workflow/report/generateReleaseReport.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type {
+  ReleaseContext,
+  ReleaseLifecycle,
+  ReleaseReport,
+  ReleaseStatus,
+} from '#types'
+import { compact } from '#util'
+
+/**
+ * Generate a release report from the current workflow state.
+ *
+ * Extracts relevant information from the context and organizes it into a report
+ * containing workflow phase, status, plugin metadata, packages, and release plans.
+ *
+ * @param context Release context with workflow state and plans
+ * @param plugin Name of the current plugin executing
+ * @param hook Current workflow phase
+ * @param status Workflow completion status (`'success'` or `'failure'`)
+ * @param reason Error or failure reason (used only when status is `'failure'`)
+ * @returns Release report object with structured workflow results
+ */
+export function generateReleaseReport(
+  context: ReleaseContext,
+  plugin: string | undefined,
+  hook: ReleaseLifecycle | undefined,
+  status: ReleaseStatus,
+  reason: unknown
+): ReleaseReport {
+  return {
+    phase: plugin && hook ? { plugin, hook } : undefined,
+    status,
+    reason: Error.isError(reason)
+      ? reason.message
+      : typeof reason === 'string'
+        ? reason
+        : null,
+    prereleaseLabel: context.prereleaseLabel,
+    releaseChannel: context.releaseChannel,
+    plugins: context.plugins.map((plugin) => ({
+      name: plugin.name,
+      version: plugin.version,
+      hooks: Object.keys(plugin).filter(
+        (key) => key !== 'name' && key !== 'version'
+      ),
+    })),
+    packages: context.packages.map((pkg) => ({
+      dir: pkg.dir,
+      name: pkg.name,
+      version: pkg.version,
+    })),
+    plans: compact(
+      context.plans.map((plan) => {
+        if (!plan.release?.version) return null
+
+        return {
+          package: {
+            entry: plan.package.entry,
+            dir: plan.package.dir,
+            name: plan.package.name,
+            version: plan.package.version,
+            private: !!plan.package.private,
+          },
+          release: {
+            type: plan.release.type,
+            version: plan.release.version,
+            tag: plan.release.tag?.name,
+            changelog: plan.release.changelog,
+          },
+        }
+      })
+    ),
+  }
+}

package/src/workflow/report/index.ts

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

package/src/workflow/report/printReleaseReport.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleaseContext, ReleaseReport } from '#types'
+import { colors } from 'consola/utils'
+import path from 'node:path'
+
+/**
+ * Print a formatted release report to the logger.
+ *
+ * Logs the workflow status and details about released packages. On success,
+ * displays released package names and version changes. On failure, displays
+ * the error reason.
+ *
+ * @param context Release context for logging
+ * @param report Release report to display
+ * @returns void
+ */
+export function printReleaseReport(
+  context: ReleaseContext,
+  report: ReleaseReport
+): void {
+  const statusLabel = {
+    success: colors.green('SUCCESS'),
+    failure: colors.red('FAILURE'),
+  }[report.status]
+
+  context.logger.info(`Status: ${statusLabel}`)
+
+  if (report.status === 'failure') {
+    return context.logger.error(
+      [
+        'Release complete:',
+        colors.red(
+          report.reason ||
+            'An unexpected error occurred during the release process.'
+        ),
+      ].join(' ')
+    )
+  }
+
+  if (report.plans.length === 0) {
+    return context.logger.info(
+      [
+        'Release complete:',
+        colors.yellow('No packages are scheduled for release.'),
+      ].join(' ')
+    )
+  }
+
+  const header = [
+    'Release complete:',
+    colors.bold(colors.green(`${report.plans.length} released`)),
+    colors.gray(`(${report.packages.length})`),
+  ].join(' ')
+
+  const list = report.plans
+    .toSorted((a, b) =>
+      (a.package.name || '').localeCompare(b.package.name || '')
+    )
+    .map((plan) => {
+      let dir = path.normalize(path.join(plan.package.dir, '.'))
+
+      dir = dir === '.' ? dir : `./${dir}`
+
+      const name = plan.package.name
+        ? colors.bgBlue(` ${plan.package.name} `)
+        : !plan.package.entry && colors.gray(` ${dir} `)
+
+      let version = [plan.release.version, plan.package.version]
+        .filter(Boolean)
+        .join(' ← ')
+
+      version = ` ${version} `
+
+      const type = plan.release.type && colors.gray(` ${plan.release.type} `)
+
+      const summary = [
+        name,
+        plan.release.type === 'major'
+          ? colors.bgRed(version)
+          : colors.bgGreen(version),
+        type,
+      ]
+        .filter(Boolean)
+        .join('')
+
+      const changelog = plan.release.changelog
+        ?.replace(/^(#+ .+)$/gm, (_, header) => colors.cyan(header))
+        .trim()
+
+      return [summary, changelog].filter(Boolean).join('\n\n')
+    })
+    .join('\n\n')
+
+  context.logger.info(`${header}\n\n${list}\n`)
+}

package/src/workflow/runner/index.ts

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

package/src/workflow/runner/runWorkflow.ts

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { RELEASE_LIFECYCLE_HOOK_LIST } from '#config'
+import type {
+  ReleaseContext,
+  ReleaseLifecycle,
+  ReleasePlugin,
+  ReleasePluginHookRollback,
+  ReleaseStatus,
+} from '#types'
+import { compact } from '#util'
+import { colors } from 'consola/utils'
+import { generateReleaseReport, printReleaseReport } from '../report'
+
+/**
+ * Execute the plugin-driven release workflow using the provided `ReleaseContext`.
+ *
+ * The workflow runs plugin stages in order: `configure`, `discover`,
+ * `analyze`, `build`, `write`, `commit`, and `publish`. After a successful
+ * run the function sets `context.status` to `'success'`. The workflow is
+ * finalized in all cases; on success a release report is printed.
+ *
+ * The returned array contains all computed release plans, including plans
+ * without releases. Side effects (file writes, commits, tags, publishing)
+ * are performed by plugins and may be skipped when `context.dryRun` is true.
+ *
+ * @returns Promise that resolves when the workflow is complete.
+ */
+export async function runWorkflow(
+  createContext: () => ReleaseContext | Promise<ReleaseContext>
+): Promise<void> {
+  const isSilent = import.meta.env.MODE === 'test'
+  const context = await createContext()
+  const stack: ReleasePluginHookRollback[] = []
+  let plugin: ReleasePlugin | undefined
+  let hook: ReleaseLifecycle | undefined
+  let status: ReleaseStatus = 'success'
+  let reason: unknown = null
+
+  try {
+    const ordered = RELEASE_LIFECYCLE_HOOK_LIST.flatMap((hookName) => {
+      return compact(
+        context.plugins.map((plugin) => {
+          let hook = plugin[hookName]
+
+          if (!hook) return undefined
+
+          hook = typeof hook === 'function' ? { handler: hook } : hook
+
+          const { enforce, handler } = hook
+
+          const weight = enforce === 'pre' ? -1 : enforce === 'post' ? 1 : 0
+
+          return {
+            plugin,
+            hook: hookName,
+            handler,
+            weight,
+          }
+        })
+      ).sort((a, b) => a.weight - b.weight)
+    })
+
+    let handler: (typeof ordered)[number]['handler']
+
+    for ({ plugin, hook, handler } of ordered) {
+      const label = `${colors.gray(`[${hook}]`)} ${plugin.name}`
+      let startedLogging = false
+      let timer: NodeJS.Timeout | undefined
+
+      /* istanbul ignore next */
+      if (!isSilent) {
+        timer = setTimeout(() => {
+          startedLogging = true
+          context.logger.start(label)
+        }, 10)
+      }
+
+      const startTime = performance.now()
+
+      try {
+        const rollback = await handler(context)
+
+        if (typeof rollback === 'function') {
+          stack.push(rollback)
+        }
+      } finally {
+        clearTimeout(timer)
+      }
+
+      const endTime = performance.now()
+      const duration = (endTime - startTime) / 1000
+
+      /* istanbul ignore next */
+      if (startedLogging) {
+        const color = duration >= 5 ? colors.red : colors.cyan
+        const time = color(`${duration.toFixed(2)}s`)
+
+        context.logger.success(`${label} ${time}`)
+      }
+    }
+  } catch (err) {
+    status = 'failure'
+    reason = err
+
+    for (const rollback of stack.toReversed()) {
+      try {
+        await rollback(reason)
+      } catch {}
+    }
+
+    throw err
+  } finally {
+    printReleaseReport(
+      context,
+      generateReleaseReport(context, plugin?.name, hook, status, reason)
+    )
+  }
+}

package/src/workflow/versioning/bumpVersion.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Package, ReleaseType } from '#types'
+import { colors } from 'consola/utils'
+import semver from 'semver'
+
+/**
+ * Bump a semantic version according to release type and prerelease settings.
+ *
+ * Increments the version using the provided release type. When a prerelease ID
+ * is provided, generates a prerelease version with that identifier. Throws an
+ * error when the version is invalid or the initial version is missing.
+ *
+ * @param pkg Package object containing current version
+ * @param releaseType Semantic version component to increment (`'major'`, `'minor'`, `'patch'`)
+ * @param prereleaseId Optional prerelease identifier (e.g., `'alpha'`, `'beta'`)
+ * @returns Next semantic version string, or `null` when `releaseType` is falsy
+ * @throws If the version is invalid or initial version is missing
+ */
+export function bumpVersion(
+  pkg: Package,
+  releaseType: ReleaseType | null | undefined,
+  prereleaseId: string | null | undefined
+): string | null {
+  if (!releaseType) {
+    return null
+  }
+
+  if (!pkg.version) {
+    if (pkg.private) {
+      return null
+    }
+
+    throw new Error(
+      'An initial version is required to compute the next version.'
+    )
+  }
+
+  const parsed = semver.parse(pkg.version)
+
+  if (!parsed) {
+    throw new Error(
+      `The version "${colors.bold(pkg.version)}" is not a valid SemVer.`
+    )
+  }
+
+  prereleaseId ||= undefined
+
+  let type: semver.ReleaseType = releaseType
+
+  if (prereleaseId) {
+    type = `pre${releaseType}` as const
+
+    if (parsed.prerelease.length > 0) {
+      if (
+        (releaseType === 'major' && parsed.minor === 0 && parsed.patch === 0) ||
+        (releaseType === 'minor' && parsed.patch === 0) ||
+        releaseType === 'patch'
+      ) {
+        type = 'prerelease'
+      }
+    }
+  }
+
+  return semver.inc(parsed, type, { loose: undefined }, prereleaseId, '0')
+}

package/src/workflow/versioning/deriveReleaseType.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Commit, CommitClassifier, ReleaseType } from '#types'
+import { determineReleaseType } from './determineReleaseType'
+import { pickPriorityReleaseType } from './pickPriorityReleaseType'
+
+/**
+ * Derive the combined release type from a commit history collection.
+ *
+ * Processes commits sequentially, accumulating the highest-precedence release
+ * type found by evaluating each individual commit and comparing it against the
+ * current maximum via `pickPriorityReleaseType`.
+ *
+ * @param classifier Function mapping commits to release types
+ * @param history Array of parsed commits to evaluate
+ * @returns `ReleaseType` string, or `null` when no matching rule applies
+ */
+export function deriveReleaseType(
+  classifier: CommitClassifier,
+  history: readonly Commit[]
+): ReleaseType | null {
+  let releaseType: ReleaseType | null = null
+
+  for (const commit of history) {
+    releaseType = pickPriorityReleaseType(
+      releaseType,
+      determineReleaseType(classifier, commit)
+    )
+  }
+
+  return releaseType
+}

package/src/workflow/versioning/determineReleaseType.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Commit, CommitClassifier, ReleaseType } from '#types'
+
+/**
+ * Determine the release type for a single commit.
+ *
+ * Automatically returns `'major'` if the commit is marked as a breaking change.
+ * Otherwise, routes the commit through the custom `classifier` and ensures the
+ * resolved value is a valid semantic versioning release type.
+ *
+ * @param classifier Function mapping commits to release types
+ * @param commit Parsed commit to evaluate
+ * @returns `ReleaseType` string, or `null` when no matching rule applies
+ */
+export function determineReleaseType(
+  classifier: CommitClassifier,
+  commit: Commit
+): ReleaseType | null {
+  if (commit.notes.length > 0) {
+    return 'major'
+  }
+
+  const type = classifier(commit)
+
+  switch (type) {
+    case 'major':
+    case 'minor':
+    case 'patch':
+      return type
+  }
+
+  return null
+}

package/src/workflow/versioning/index.ts

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './bumpVersion'
+export * from './deriveReleaseType'
+export * from './determineReleaseType'
+export * from './isStableVersion'
+export * from './pickPriorityReleaseType'

package/src/workflow/versioning/isStableVersion.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { colors } from 'consola/utils'
+import semver from 'semver'
+
+/**
+ * Determine whether a version string represents a stable SemVer release.
+ *
+ * A version is considered stable when:
+ * - It is a valid SemVer string.
+ * - Its major version is greater than 0 (not 0.x.x).
+ * - It contains no prerelease identifiers (no `-alpha`, `-beta`, `-rc`, etc.).
+ *
+ * Build metadata (the `+` suffix) does not affect stability.
+ *
+ * @param version Semantic version string to check
+ * @returns `true` if `version` is a stable SemVer; otherwise `false`
+ * @throws If `version` is not a valid SemVer string
+ */
+export function isStableVersion(version: string): boolean {
+  const parsed = semver.parse(version)
+
+  if (!parsed) {
+    throw new Error(
+      `The version "${colors.bold(version)}" is not a valid SemVer.`
+    )
+  }
+
+  return parsed.major > 0 && parsed.prerelease.length === 0
+}

package/src/workflow/versioning/pickPriorityReleaseType.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleaseType } from '#types'
+
+/**
+ * Determine the highest-priority release type between two candidates.
+ *
+ * Compares release types by precedence order: `major` > `minor` > `patch`.
+ * Returns the higher-precedence type, or `null` if neither applies.
+ *
+ * @param curr Current accumulated release type
+ * @param next Candidate release type to consider
+ * @returns Highest-precedence `ReleaseType`, or `null` if neither applies
+ */
+export function pickPriorityReleaseType(
+  curr: ReleaseType | null | undefined,
+  next: ReleaseType | null | undefined
+): ReleaseType | null {
+  for (const type of ['major', 'minor', 'patch'] satisfies ReleaseType[]) {
+    if (curr === type || next === type) {
+      return type
+    }
+  }
+
+  return null
+}