@reelout/core 0.1.1 → 0.2.0

package/src/workflow/changelog/index.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './buildChangelog'
+export * from './buildReleaseNotes'
+export * from './extractLatestVersion'
+export * from './extractPlainText'
+export * from './extractPreviousVersion'
+export * from './extractSemVer'
+export * from './iterateChangelogVersions'
+export * from './prependChangelog'
+export * from './writeChangelog'

package/src/workflow/changelog/iterateChangelogVersions.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { RootContent } from 'mdast'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import semver from 'semver'
+import { extractPlainText } from './extractPlainText'
+import { extractSemVer } from './extractSemVer'
+
+const SENTENCE_TERMINAL_REGEX = /\p{Sentence_Terminal}$/u
+
+/**
+ * Iterate over Semantic Version strings extracted from a Markdown changelog.
+ *
+ * Parses `changelogContent` into an AST and evaluates nodes sequentially using
+ * custom extractors. Evaluates heading nodes first before checking short
+ * paragraph nodes. Stops execution after the first strategy yields valid
+ * versions.
+ *
+ * @param changelogContent Raw Markdown text of the changelog
+ * @yields Valid SemVer strings found in headings or candidate paragraphs
+ */
+export function* iterateChangelogVersions(
+  changelogContent: string
+): Generator<string> {
+  const root = fromMarkdown(changelogContent)
+
+  const nodeExtractors = [
+    (node: RootContent): string | null => {
+      return node.type === 'heading' ? extractPlainText(node) : null
+    },
+
+    (node: RootContent): string | null => {
+      if (node.type !== 'paragraph') return null
+
+      const paragraphText = extractPlainText(node)
+
+      if (
+        !paragraphText ||
+        paragraphText.length > 48 ||
+        SENTENCE_TERMINAL_REGEX.test(paragraphText)
+      ) {
+        return null
+      }
+
+      return paragraphText
+    },
+  ]
+
+  for (const extractText of nodeExtractors) {
+    let isVersionFound = false
+
+    for (const node of root.children) {
+      const extractedText = extractText(node)
+
+      const candidateVersion = extractedText
+        ? semver.sort(extractSemVer(extractedText)).pop()
+        : null
+
+      if (candidateVersion && semver.valid(candidateVersion)) {
+        isVersionFound = true
+        yield candidateVersion
+      }
+    }
+
+    if (isVersionFound) {
+      return
+    }
+  }
+}

package/src/workflow/changelog/prependChangelog.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { formatFile } from '#util'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { toMarkdown } from 'mdast-util-to-markdown'
+import fs from 'node:fs/promises'
+
+const defaultChangelogTitle = 'Changelog'
+
+/**
+ * Prepend changelog content to a markdown file, creating it if necessary.
+ *
+ * Reads the existing file if present, prepends the new content before the main heading,
+ * formats and writes the result back.
+ *
+ * @param filePath Path to the changelog file
+ * @param revision Changelog content to prepend
+ * @returns Promise that resolves when the changelog is written
+ */
+export async function prependChangelog(
+  filePath: string,
+  revision: string
+): Promise<void> {
+  let content = ''
+
+  try {
+    content = await fs.readFile(filePath, 'utf-8')
+  } catch (err) {
+    /* istanbul ignore next */
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err
+    }
+  }
+
+  const root = fromMarkdown(content)
+
+  let index = root.children.findIndex(
+    (node) => node.type === 'heading' && node.depth === 1
+  )
+
+  if (index === -1) {
+    index = 0
+
+    root.children.unshift({
+      type: 'heading',
+      depth: 1,
+      children: [{ type: 'text', value: defaultChangelogTitle }],
+    })
+  }
+
+  root.children.splice(index + 1, 0, ...fromMarkdown(revision).children)
+
+  content = toMarkdown(root)
+
+  content = await formatFile(filePath, content)
+
+  await fs.writeFile(filePath, content)
+}

package/src/workflow/changelog/writeChangelog.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { DEFAULT_CHANGELOG_FILE } from '#config'
+import type { ReleasePlan } from '#types'
+import path from 'node:path'
+import { prependChangelog } from './prependChangelog'
+
+/**
+ * Write changelog content to the file system based on the release plan.
+ *
+ * @param cwd Repository working directory
+ * @param plan Release plan containing package and changelog content
+ * @returns Promise that resolves when the changelog file has been written
+ */
+export async function writeChangelog(
+  cwd: string,
+  plan: ReleasePlan
+): Promise<void> {
+  if (plan.release?.changelog) {
+    const changelogFile = plan.package.changelogFile || DEFAULT_CHANGELOG_FILE
+
+    const filePath = path.join(cwd, plan.package.dir, changelogFile)
+
+    await prependChangelog(filePath, plan.release.changelog)
+  }
+}

package/src/workflow/committing/generateReleaseCommitMessage.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { GIT_TRAILER_RELEASE_AGENT } from '#config'
+import type { ReleasePlan } from '#types'
+import { version } from '../../../package.json'
+
+/**
+ * Generate a formatted release commit message based on release plans and
+ * custom trailers.
+ *
+ * Compiles package version updates and included commit logs into a standardized
+ * conventional commit message body, appending configured release agent and
+ * custom trailers. Returns null if no valid release subject can be derived.
+ *
+ * @param plans Readonly array of release plans containing package changes and commit history
+ * @param trailers Optional record of custom git trailers to append to the commit
+ * @returns The formatted release commit message string or null if the subject is empty
+ */
+export async function generateReleaseCommitMessage(
+  plans: readonly ReleasePlan[],
+  trailers: Readonly<Record<string, string | number | null | undefined>> = {}
+): Promise<string | null> {
+  const standalone = plans.length === 1
+
+  trailers = {
+    [GIT_TRAILER_RELEASE_AGENT]: `ReelOut/${import.meta.env.MODE === 'test' ? '0.0.0' : /* istanbul ignore next */ version}`,
+    ...trailers,
+  }
+
+  plans = plans
+    .filter((plan) => plan.release?.tag?.name)
+    .toSorted((a, b) => {
+      if (a.package.entry) return -1
+      if (b.package.entry) return 1
+      /* istanbul ignore next */
+      return (a.package.name ?? '').localeCompare(b.package.name ?? '')
+    })
+
+  let subject: string | null | undefined
+
+  if (plans.length === 1) {
+    subject = standalone
+      ? plans[0]?.release?.version
+      : plans[0]?.release?.tag?.name
+  } else if (plans.length >= 2 && plans.length <= 3) {
+    subject = plans.map((plan) => plan.release?.tag?.name).join(', ')
+  } else if (plans.length > 3) {
+    subject = `${plans.length} packages (${plans
+      .slice(0, 2)
+      .map((plan) => plan.release?.tag?.name)
+      .join(', ')}, +${plans.length - 2} more)`
+  }
+
+  if (!subject) {
+    return null
+  }
+
+  const packages = plans.map((plan) => {
+    return `- ${plan.package.name || plan.package.dir}: ${plan.package.version} → ${plan.release?.version}`
+  })
+
+  const commits = Array.from(
+    new Map(
+      plans
+        .flatMap((plan) => plan.history)
+        .map((commit) => [commit.hash, commit])
+    ).values()
+  )
+    .toSorted((a, b) => {
+      return (
+        new Date(a.committerDate).valueOf() -
+        new Date(b.committerDate).valueOf()
+      )
+    })
+    .map(({ header }) => `- ${header}`)
+
+  return [
+    `chore: release ${subject}`,
+
+    packages.length >= 2
+      ? ['## Version Updates', ...packages].join('\n')
+      : undefined,
+
+    commits.length > 0
+      ? ['## Changes Included', ...commits].join('\n')
+      : undefined,
+
+    Object.entries(trailers)
+      .map(([key, value]) => (key && value != null ? `${key}: ${value}` : ''))
+      .filter(Boolean)
+      .join('\n'),
+  ]
+    .filter(Boolean)
+    .join('\n\n')
+}

package/src/workflow/committing/index.ts

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

package/src/workflow/committing/isReleaseCommit.ts

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { GIT_TRAILER_RELEASE_AGENT } from '#config'
+import { getParsedCommit } from '#git'
+import type { Commit, CommitTrailer } from '#types'
+import { execGit } from '#util'
+
+export type ReleaseMarker = string | ((trailer: CommitTrailer) => boolean)
+
+/**
+ * Determine whether a commit represents a release or matches a release marker.
+ *
+ * Resolves string commit identifiers to parsed commit objects, checks if any
+ * associated trailer matches the marker predicate, and falls back to verifying
+ * exact tag matches for the `commit` hash.
+ *
+ * @param cwd The working directory path for Git commands
+ * @param commit The commit object, hash string, or null/undefined
+ * @param marker The trailer key string or a predicate function to evaluate
+ * @returns True if the commit is a release commit, otherwise false
+ */
+export async function isReleaseCommit(
+  cwd: string,
+  commit: Commit | string | null | undefined,
+  marker: ReleaseMarker = GIT_TRAILER_RELEASE_AGENT
+): Promise<boolean> {
+  if (typeof commit === 'string') {
+    commit = await getParsedCommit(
+      cwd,
+      commit,
+      typeof marker === 'string' ? [marker] : []
+    )
+  }
+
+  if (!commit) {
+    return false
+  }
+
+  const predicate =
+    typeof marker === 'string'
+      ? (trailer: CommitTrailer) => trailer.key === marker && !!trailer.value
+      : marker
+
+  if (commit.trailers.some(predicate)) {
+    return true
+  }
+
+  return execGit(cwd, ['describe', '--tags', '--exact-match', commit.hash])
+    .then(() => true)
+    .catch(() => false)
+}

package/src/workflow/discovery/buildDependencyGraph.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleasePlan } from '#types'
+
+export type DependencyGraph = Map<string, Set<ReleasePlan>>
+
+/**
+ * Build a dependency graph mapping package names to dependent release plans.
+ *
+ * Each key is a package name and the value is a set of `ReleasePlan`s that
+ * list that package as a dependency.
+ *
+ * @param plans Array of release plans to analyze
+ * @returns Dependency graph mapping package name -> set of dependent plans
+ */
+export function buildDependencyGraph(
+  plans: readonly ReleasePlan[]
+): DependencyGraph {
+  const graph = new Map<string, Set<ReleasePlan>>()
+
+  const packageNames = new Set(
+    plans
+      .map((plan) => plan.package.name)
+      .filter((name): name is string => !!name)
+  )
+
+  for (const plan of plans) {
+    for (const depName of plan.package.dependencies) {
+      let set = graph.get(depName)
+
+      if (!set && packageNames.has(depName)) {
+        graph.set(depName, (set = new Set()))
+      }
+
+      if (set) {
+        set.add(plan)
+      }
+    }
+  }
+
+  return graph
+}

package/src/workflow/discovery/discoverPackageTag.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { DEFAULT_CHANGELOG_FILE } from '#config'
+import {
+  generateGitTagName,
+  getGitTagMessage,
+  readGitFile,
+  resolveGitRevision,
+} from '#git'
+import type { Package, Tag } from '#types'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { extractLatestVersion } from '../changelog/extractLatestVersion'
+import { verifyPackageTag } from './verifyPackageTag'
+
+/**
+ * Discover and validate the Git tag for a package.
+ *
+ * Returns the existing tag if already present on the `pkg` object. Resolves
+ * the local changelog file path, extracts the current version, and generates
+ * the expected Git tag name. Verifies the tag against the repository and
+ * ensures its historical changelog version matches the current local version.
+ *
+ * @param cwd The current working directory
+ * @param pkg The package configuration object
+ * @returns The validated `Tag` object or null if validation fails
+ */
+export async function discoverPackageTag(
+  cwd: string,
+  pkg: Package
+): Promise<Tag | null> {
+  if (pkg.tag) {
+    return pkg.tag
+  }
+
+  const changelogFile = pkg.changelogFile || DEFAULT_CHANGELOG_FILE
+
+  const changelogFilePath = path.resolve(cwd, pkg.dir, changelogFile)
+
+  let localChangelogContent: string | null | undefined
+
+  try {
+    localChangelogContent = await readFile(changelogFilePath, 'utf-8')
+  } catch {}
+
+  if (!localChangelogContent) {
+    return null
+  }
+
+  const currentVersion = extractLatestVersion(localChangelogContent)
+
+  if (!currentVersion) {
+    return null
+  }
+
+  let expectedTagName: string | null | undefined
+
+  try {
+    expectedTagName = generateGitTagName(pkg.entry, pkg.name, currentVersion)
+  } catch {}
+
+  if (!expectedTagName) {
+    return null
+  }
+
+  if (!(await verifyPackageTag(cwd, pkg, expectedTagName))) {
+    return null
+  }
+
+  const tagRef = `refs/tags/${expectedTagName}`
+
+  const historicalChangelogContent = await readGitFile(
+    cwd,
+    await resolveGitRevision(cwd, tagRef),
+    path.relative(cwd, changelogFilePath)
+  )
+
+  if (!historicalChangelogContent) {
+    return null
+  }
+
+  const historicalChangelogVersion = extractLatestVersion(
+    historicalChangelogContent
+  )
+
+  if (
+    !historicalChangelogVersion ||
+    historicalChangelogVersion !== currentVersion
+  ) {
+    return null
+  }
+
+  return {
+    name: expectedTagName,
+    message: await getGitTagMessage(cwd, expectedTagName),
+  }
+}

package/src/workflow/discovery/index.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './buildDependencyGraph'
+export * from './discoverPackageTag'
+export * from './resolvePackageStableTag'
+export * from './resolvePackageTag'
+export * from './sortPackages'
+export * from './verifyPackageTag'

package/src/workflow/discovery/resolvePackageStableTag.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { DEFAULT_CHANGELOG_FILE } from '#config'
+import { generateGitTagName, getGitTagMessage } from '#git'
+import type { Package, Tag } from '#types'
+import assert from 'node:assert'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import semver from 'semver'
+import { iterateChangelogVersions } from '../changelog/iterateChangelogVersions'
+import { verifyPackageTag } from './verifyPackageTag'
+
+/**
+ * Resolve the latest stable Git tag for a package.
+ *
+ * Reads changelog release versions for `pkg` and verifies strict descending
+ * semver order. Ignores prerelease versions unless transitioning across major
+ * or prerelease boundaries, and verifies that the matching Git tag exists.
+ *
+ * @param cwd Absolute path to the root working directory
+ * @param pkg Package configuration object
+ * @returns Verified tag metadata object or `null` if no stable tag is resolved
+ * @throws If a version is invalid, versions are not in strict descending
+ * order, or the corresponding Git tag is missing
+ */
+export async function resolvePackageStableTag(
+  cwd: string,
+  pkg: Package
+): Promise<Tag | null> {
+  const changelogFile = pkg.changelogFile || DEFAULT_CHANGELOG_FILE
+
+  const changelogFilePath = path.resolve(cwd, pkg.dir, changelogFile)
+
+  let changelogContent: string
+
+  try {
+    changelogContent = await readFile(changelogFilePath, 'utf-8')
+  } catch (error: unknown) {
+    /* istanbul ignore else */
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+      return null
+    }
+
+    /* istanbul ignore next */
+    throw error
+  }
+
+  let precedingVersion: semver.SemVer | null = null
+
+  for (const version of iterateChangelogVersions(changelogContent)) {
+    const currentVersion = semver.parse(version)
+
+    assert(
+      currentVersion,
+      `Version "${version}" is not a valid semantic version.`
+    )
+
+    if (precedingVersion && semver.gte(currentVersion, precedingVersion)) {
+      throw new Error(
+        `Version "${version}" must be strictly lower than preceding version "${precedingVersion.raw}".`
+      )
+    }
+
+    if (
+      !semver.prerelease(currentVersion) &&
+      (currentVersion.major >= 1 ||
+        (precedingVersion && semver.prerelease(precedingVersion)))
+    ) {
+      const tagName = generateGitTagName(pkg.entry, pkg.name, version)
+
+      if (!(await verifyPackageTag(cwd, pkg, tagName))) {
+        throw new Error(
+          `Git tag "${tagName}" is not associated with package "${pkg.name ?? ''}" in directory "${pkg.dir}".`
+        )
+      }
+
+      return {
+        name: tagName,
+        message: await getGitTagMessage(cwd, tagName),
+      }
+    }
+
+    precedingVersion = currentVersion
+  }
+
+  return null
+}

package/src/workflow/discovery/resolvePackageTag.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { generateGitTagName, getGitTagMessage } from '#git'
+import type { Package, Tag } from '#types'
+import { verifyPackageTag } from './verifyPackageTag'
+
+/**
+ * Resolve the release tag for a single package version.
+ *
+ * Returns the cached `pkg.tag` immediately if it already exists. Generates an
+ * expected tag name from the package metadata and verifies its integrity using
+ * `verifyPackageTag`.
+ *
+ * @param cwd Repository working directory
+ * @param pkg Package descriptor containing version and location context
+ * @returns A promise resolving to the tag metadata or null when not found
+ */
+export async function resolvePackageTag(
+  cwd: string,
+  pkg: Package
+): Promise<Tag | null> {
+  if (pkg.tag) {
+    return pkg.tag
+  }
+
+  let expectedTagName: string | null | undefined
+
+  try {
+    expectedTagName = generateGitTagName(pkg.entry, pkg.name, pkg.version)
+  } catch {}
+
+  if (!expectedTagName) {
+    return null
+  }
+
+  if (await verifyPackageTag(cwd, pkg, expectedTagName)) {
+    return {
+      name: expectedTagName,
+      message: await getGitTagMessage(cwd, expectedTagName),
+    }
+  }
+
+  return null
+}

package/src/workflow/discovery/sortPackages.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Package } from '#types'
+
+interface PackageNode {
+  package: Package
+  level: number
+}
+
+/**
+ * Sort workspace packages topologically based on their dependency graphs.
+ *
+ * Deepest dependents are placed first in the resulting array, ensuring that
+ * a package always precedes its own dependencies. Ties and circular dependencies
+ * are resolved deterministically using an alphabetical sort on the package directory (`dir`).
+ *
+ * @param packages The workspace packages to sort.
+ * @returns A new array of packages sorted by dependency depth and directory path.
+ */
+export function sortPackages(packages: readonly Package[]): Package[] {
+  const packageNodes: PackageNode[] = []
+  const packageMap = new Map<string, PackageNode>()
+
+  for (const pkg of packages.toSorted((a, b) => a.dir.localeCompare(b.dir))) {
+    const node: PackageNode = {
+      package: pkg,
+      level: -1,
+    }
+
+    packageNodes.push(node)
+
+    if (pkg.name) {
+      packageMap.set(pkg.name, node)
+    }
+  }
+
+  for (const node of packageNodes) {
+    visit(node)
+  }
+
+  function visit(
+    node: PackageNode,
+    level = 0,
+    visited = new Set<PackageNode>()
+  ): void {
+    if (node.level >= level) {
+      return
+    }
+
+    if (visited.has(node)) {
+      return
+    }
+
+    visited.add(node)
+
+    for (const depName of node.package.dependencies) {
+      const depNode = packageMap.get(depName)
+
+      if (depNode && depNode !== node) {
+        visit(depNode, level + 1, visited)
+      }
+    }
+
+    node.level = level
+  }
+
+  const sorted = packageNodes
+    .toSorted((a, b) => b.level - a.level)
+    .map((node) => node.package)
+
+  return sorted
+}