@reelout/core 0.1.1 → 0.2.0

package/src/util/readJson.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { colors } from 'consola/utils'
+import fs from 'node:fs/promises'
+
+/**
+ * Read and parse a JSON file.
+ *
+ * Throws a descriptive error when the file cannot be read or parsed, or when
+ * the parsed value is not an object.
+ *
+ * @param filePath Path to the JSON file
+ * @returns Parsed JSON object
+ * @throws If the file cannot be read, parsed, or is not an object
+ */
+export async function readJson<T>(filePath: string): Promise<T> {
+  let content: string
+
+  try {
+    content = await fs.readFile(filePath, 'utf-8')
+  } catch (err) {
+    throw new Error(
+      `JSON file at "${colors.bold(filePath)}" could not be read.`,
+      { cause: err }
+    )
+  }
+
+  let json: T
+
+  try {
+    json = JSON.parse(content) as T
+  } catch (err) {
+    throw new Error(
+      `JSON file at "${colors.bold(filePath)}" could not be parsed.`,
+      { cause: err }
+    )
+  }
+
+  if (typeof json !== 'object' || json === null) {
+    throw new Error(
+      `JSON file at "${colors.bold(filePath)}" does not contain a valid object.`
+    )
+  }
+
+  return json
+}

package/src/util/unique.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+/**
+ * Return a new array containing only the first-seen occurrence of each item.
+ *
+ * This preserves the original iteration order and performs equality checks
+ * using JavaScript's `Set` semantics (i.e., primitives by value, objects by
+ * reference). The input array is not mutated.
+ *
+ * @param array The array of items to deduplicate
+ * @returns A new array with duplicates removed, preserving first-seen order
+ */
+export function unique<T>(array: readonly T[]): T[] {
+  const seen = new Set<T>()
+  const result: T[] = []
+
+  for (const item of array) {
+    if (!seen.has(item)) {
+      seen.add(item)
+      result.push(item)
+    }
+  }
+
+  return result
+}

package/src/util/writeJson.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { formatFile } from './formatFile'
+
+/**
+ * Write a JSON `payload` to `filePath`, formatting the content first.
+ *
+ * Ensures the directory exists and writes the formatted JSON.
+ *
+ * @param filePath Path to write the JSON file
+ * @param payload JSON-serializable object to write
+ * @returns Promise that resolves when the file is written
+ */
+export async function writeJson(
+  filePath: string,
+  payload: object
+): Promise<void> {
+  let content = JSON.stringify(payload, null, 2)
+
+  content = await formatFile(filePath, content)
+
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+
+  await fs.writeFile(filePath, content)
+}

package/src/workflow/analysis/analyzePackageChanges.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Commit, CommitClassifier, ReleasePlan } from '#types'
+import { deriveReleaseType, pickPriorityReleaseType } from '../versioning'
+import { isCommitForPackage } from './isCommitForPackage'
+
+/**
+ * Analyze commit history and compute release types for each package plan.
+ *
+ * Iterates through commits, associates them with affected packages, and
+ * calculates each package's release type using the provided classifier.
+ *
+ * @param classifier Function mapping commits to release types
+ * @param plans Array of release plans to update
+ * @param history Commit history as iterable or async iterable
+ * @returns Updated array of plans with computed `releaseType`
+ */
+export async function analyzePackageChanges(
+  classifier: CommitClassifier,
+  plans: readonly ReleasePlan[],
+  history: Iterable<Commit> | AsyncIterable<Commit>
+): Promise<ReleasePlan[]> {
+  for await (const commit of history) {
+    plans = plans.map((plan): ReleasePlan => {
+      if (!isCommitForPackage(plan.package, commit)) {
+        return plan
+      }
+
+      return {
+        ...plan,
+        history: plan.history.concat(commit),
+      }
+    })
+  }
+
+  return plans.map((plan): ReleasePlan => {
+    let { release } = plan
+
+    const releaseType = pickPriorityReleaseType(
+      release?.type,
+      deriveReleaseType(classifier, plan.history)
+    )
+
+    if (releaseType) {
+      release = { ...release, type: releaseType }
+    }
+
+    return {
+      ...plan,
+      release,
+    }
+  })
+}

package/src/workflow/analysis/index.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+export * from './analyzePackageChanges'
+export * from './isCommitForPackage'
+export * from './promotePrereleaseVersions'
+export * from './propagateDependencyUpdates'
+export * from './sliceUnreleased'
+export * from './streamPackageCommits'

package/src/workflow/analysis/isCommitForPackage.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { ALL_FILES } from '#config'
+import type { Commit, Package } from '#types'
+import { isMatch } from '#util'
+import path from 'node:path'
+
+/**
+ * Test whether a commit modifies files in a package.
+ *
+ * @param pkg Package with an explicit file pattern or base directory
+ * @param commit Parsed commit containing changed file paths
+ * @returns `true` if any changed file matches the package pattern
+ */
+export function isCommitForPackage(pkg: Package, commit: Commit): boolean {
+  return commit.files.some((file) => {
+    const { dir } = pkg
+    const files = pkg.files || path.join(dir, ALL_FILES)
+
+    return isMatch(file, files)
+  })
+}

package/src/workflow/analysis/promotePrereleaseVersions.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { ReleasePlan, ReleaseType } from '#types'
+import semver from 'semver'
+
+/**
+ * Promote prerelease versions when they have no explicit release type.
+ *
+ * Analyzes prerelease and zero-major versions to determine an appropriate
+ * release type for graduation:
+ * - Prerelease versions are promoted based on their highest incremented component
+ *   (patch, minor, or major)
+ * - Zero-major versions (0.y.z) are promoted to major
+ * - Stable versions (1.0.0+) remain unchanged
+ * - Plans with explicit releases are preserved as-is
+ *
+ * @param plans Release plans to analyze
+ * @returns Plans with inferred release types for prerelease versions
+ */
+export async function promotePrereleaseVersions(
+  plans: readonly ReleasePlan[]
+): Promise<ReleasePlan[]> {
+  return plans.map((plan): ReleasePlan => {
+    if (plan.release) return plan
+
+    if (!plan.package.tag) return plan
+
+    const parsed = semver.parse(plan.package.version)
+
+    if (!parsed) return plan
+
+    let type: ReleaseType | undefined
+
+    if (parsed.prerelease.length) {
+      if (parsed.patch !== 0) type = 'patch'
+      else if (parsed.minor !== 0) type = 'minor'
+      else if (parsed.major !== 0) type = 'major'
+      else type = 'major'
+    } else if (parsed.major === 0) {
+      type = 'major'
+    }
+
+    if (type) {
+      return { ...plan, release: { type } }
+    }
+
+    return plan
+  })
+}

package/src/workflow/analysis/propagateDependencyUpdates.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { mergeGitHistory } from '#git'
+import type { Commit, ReleasePlan } from '#types'
+import { buildDependencyGraph } from '../discovery'
+
+/**
+ * Propagate release updates through package dependencies.
+ *
+ * Marks packages that depend on a releasing package for a `patch` release
+ * when they do not already have a release type.
+ *
+ * @param plans Array of release plans to update
+ * @returns Updated array of release plans
+ */
+export async function propagateDependencyUpdates(
+  cwd: string,
+  plans: readonly ReleasePlan[]
+): Promise<ReleasePlan[]> {
+  const graph = buildDependencyGraph(plans)
+
+  const scheduled = new Map<ReleasePlan, Commit[]>()
+
+  const stack: ReleasePlan[] = []
+
+  for (const plan of plans) {
+    if (plan.release?.type) {
+      const visited = new Set([plan])
+
+      stack.push(plan)
+
+      let curr: ReleasePlan | undefined
+
+      while ((curr = stack.pop())) {
+        if (curr.package.name) {
+          for (const dependent of graph.get(curr.package.name) ?? []) {
+            if (!visited.has(dependent)) {
+              visited.add(dependent)
+
+              stack.push(dependent)
+
+              scheduled.set(
+                dependent,
+                await mergeGitHistory(
+                  cwd,
+                  scheduled.get(dependent) ?? dependent.history,
+                  plan.history
+                )
+              )
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return plans.map((plan) => {
+    const history = scheduled.get(plan)
+
+    if (history) {
+      plan = { ...plan, history }
+
+      if (!plan.release?.type) {
+        plan.release = { type: 'patch' }
+      }
+    }
+
+    return plan
+  })
+}

package/src/workflow/analysis/sliceUnreleased.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { showParsedGitHistory, type ShowGitHistoryOptions } from '#git'
+import type { Commit } from '#types'
+import {
+  isReleaseCommit,
+  type ReleaseMarker,
+} from '../committing/isReleaseCommit'
+
+export interface SliceUnreleasedOptions extends ShowGitHistoryOptions {
+  marker?: ReleaseMarker | undefined
+}
+
+/**
+ * Yield parsed commits from the workspace until a release commit is found.
+ *
+ * Iterates through parsed commit history and yields unreleased commits in
+ * order. Stops processing upon reaching the first release commit.
+ *
+ * @param cwd Path to the working directory
+ * @param options Options for configuring Git history retrieval
+ * @yields Parsed `Commit` objects up to the most recent release commit
+ */
+export async function* sliceUnreleased(
+  cwd: string,
+  options?: SliceUnreleasedOptions
+): AsyncGenerator<Commit> {
+  for await (const commit of showParsedGitHistory(cwd, options)) {
+    if (await isReleaseCommit(cwd, commit, options?.marker)) {
+      break
+    }
+
+    yield commit
+  }
+}

package/src/workflow/analysis/streamPackageCommits.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { showParsedGitHistory, type ShowGitHistoryOptions } from '#git'
+import type { Commit, Package } from '#types'
+import { isCommitForPackage } from './isCommitForPackage'
+
+/**
+ * Yield commits from git history associated with a package.
+ *
+ * Filters git commit history to stream only entries relevant to the target
+ * `pkg` directory.
+ *
+ * @param cwd Path to the working directory for git commands
+ * @param pkg Package configuration containing the target directory
+ * @param options Options for parsing and filtering git history
+ * @yields Commits belonging to the specified package
+ */
+export async function* streamPackageCommits(
+  cwd: string,
+  pkg: Package,
+  options: ShowGitHistoryOptions = {}
+): AsyncGenerator<Commit> {
+  options = {
+    ...options,
+    filePath: options.filePath || pkg.dir,
+  }
+
+  for await (const commit of showParsedGitHistory(cwd, options)) {
+    if (isCommitForPackage(pkg, commit)) {
+      yield commit
+    }
+  }
+}

package/src/workflow/changelog/buildChangelog.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { DEFAULT_CHANGELOG_FILE } from '#config'
+import type { Commit, ReleaseContext } from '#types'
+import { formatFile } from '#util'
+import createPreset from 'conventional-changelog-conventionalcommits'
+import {
+  writeChangelogString,
+  type CommitKnownProps,
+  type FinalTemplateContext,
+  type TemplateContext,
+} from 'conventional-changelog-writer'
+import path from 'node:path'
+
+export interface BuildChangelogOptions {
+  packageDir?: string | undefined
+  changelogFile?: string | undefined
+  version?: string | null | undefined
+  previousTag?: string | null | undefined
+  currentTag?: string | null | undefined
+}
+
+const preset = await createPreset()
+
+const headerPartial = (context: FinalTemplateContext) => {
+  return context.version ? preset.writer.headerPartial?.(context) : undefined
+}
+
+/**
+ * Build the changelog string for a release.
+ *
+ * Compiles commit history and release context into a formatted changelog using
+ * conventional commits and writer configurations. Resolves file paths and handles
+ * tag comparisons when repository URLs are available.
+ *
+ * @param context The release context containing repository and working directory details
+ * @param history The iterable or async iterable collection of commits to process
+ * @param options The build configuration options for the changelog
+ * @returns The formatted changelog content string
+ */
+export async function buildChangelog(
+  context: ReleaseContext,
+  history: Iterable<Commit> | AsyncIterable<Commit>,
+  options: BuildChangelogOptions = {}
+): Promise<string> {
+  const repository = context.repository?.url || undefined
+
+  const version = options.version || undefined
+
+  const previousTag = options.previousTag || undefined
+
+  const currentTag = options.currentTag || undefined
+
+  const filePath = path.join(
+    context.cwd,
+    options.packageDir || '.',
+    options.changelogFile || DEFAULT_CHANGELOG_FILE
+  )
+
+  const content = await writeChangelogString<CommitKnownProps>(
+    history,
+    {
+      date: context.today,
+      version,
+      previousTag,
+      currentTag,
+      linkCompare: !!repository && !!previousTag && !!currentTag,
+      linkReferences: !!repository,
+      repoUrl: repository,
+      commit: 'commit',
+      issue: 'issues',
+      headerPartial,
+    } as TemplateContext,
+    preset.writer
+  )
+
+  return formatFile(filePath, content)
+}

package/src/workflow/changelog/buildReleaseNotes.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { DEFAULT_CHANGELOG_FILE } from '#config'
+import type { Commit, ReleaseContext } from '#types'
+import { formatFile } from '#util'
+import type { Heading, RootContent } from 'mdast'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { toMarkdown } from 'mdast-util-to-markdown'
+import path from 'node:path'
+import { buildChangelog } from './buildChangelog'
+
+/**
+ * Build release notes from a release context and commit history.
+ *
+ * Generates changelog content from commits, parses it into an abstract syntax
+ * tree, shifts heading depths, and formats the resulting markdown file.
+ *
+ * @param context The release context containing repository and configuration details
+ * @param history The iterable or async iterable collection of commits to process
+ * @returns The formatted release notes as a markdown string
+ */
+export async function buildReleaseNotes(
+  context: ReleaseContext,
+  history: Iterable<Commit> | AsyncIterable<Commit>
+): Promise<string> {
+  const changelogContent = await buildChangelog(context, history)
+
+  const root = fromMarkdown(changelogContent)
+
+  root.children = root.children.flatMap<RootContent>((node) => {
+    if (node.type === 'heading') {
+      /* istanbul ignore next */
+      if (node.depth <= 2) {
+        return []
+      }
+
+      node = {
+        ...node,
+        depth: (node.depth - 1) as Heading['depth'],
+      }
+    }
+
+    return node
+  })
+
+  const filePath = path.join(context.cwd, DEFAULT_CHANGELOG_FILE)
+
+  return formatFile(filePath, toMarkdown(root))
+}

package/src/workflow/changelog/extractLatestVersion.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { iterateChangelogVersions } from './iterateChangelogVersions'
+
+/**
+ * Find the highest semantic version from the first version-bearing element.
+ *
+ * Pulls the first available version string from the parsed markdown iterator.
+ * Short-circuits execution immediately upon locating a match to avoid passing
+ * through the remaining document structure.
+ *
+ * @param changelogContent The raw markdown string representing the changelog
+ * @returns The highest valid semantic version string found or null
+ */
+export function extractLatestVersion(changelogContent: string): string | null {
+  for (const version of iterateChangelogVersions(changelogContent)) {
+    return version
+  }
+
+  return null
+}

package/src/workflow/changelog/extractPlainText.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import type { Heading, Paragraph, PhrasingContent } from 'mdast'
+
+/**
+ * Extract trimmed plain text from a Heading, Paragraph, or PhrasingContent node.
+ *
+ * Performs a depth-first traversal, concatenating string `value` tokens in
+ * document order. Non-string values are ignored. Returns `null` for empty or
+ * missing input.
+ *
+ * @param node Node to extract text from
+ * @returns The trimmed plain-text string, or null if empty
+ */
+export function extractPlainText(
+  node: Heading | Paragraph | PhrasingContent | null | undefined
+): string | null {
+  if (!node) {
+    return null
+  }
+
+  const queue = [node]
+  let result = ''
+
+  while ((node = queue.shift())) {
+    if ('value' in node && typeof node.value === 'string') {
+      result += node.value
+    }
+
+    /* istanbul ignore else */
+    if ('children' in node && Array.isArray(node.children)) {
+      queue.unshift(...node.children)
+    }
+  }
+
+  return result.trim() || null
+}

package/src/workflow/changelog/extractPreviousVersion.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { colors } from 'consola/utils'
+import semver from 'semver'
+import { iterateChangelogVersions } from './iterateChangelogVersions'
+
+// TODO: remove unused
+/**
+ * Find the latest stable version that precedes the current version.
+ *
+ * Parses markdown from top to bottom to extract semantic versions from headings
+ * and paragraphs. Enforces that discovered versions appear in strict
+ * descending order. Returns the first version that falls outside the current
+ * version's major, minor, and patch boundaries if the current version is
+ * `v1.0.0` or higher, or the first non-matching version for `v0.x.x` releases.
+ *
+ * @param currentVersion The version to evaluate against
+ * @param changelogContent The raw markdown content to scan for versions
+ * @returns The resolved stable version string or null when none is found
+ * @throws If `currentVersion` is invalid or already stable, or if versions in the changelog are not listed in strict descending order
+ */
+export async function extractPreviousVersion(
+  currentVersion: string | null | undefined,
+  changelogContent: string
+): Promise<string | null> {
+  const parsedCurrent = semver.parse(currentVersion)
+
+  if (!currentVersion || !parsedCurrent) {
+    throw new Error(
+      `The current version "${colors.bold(String(currentVersion))}" is not a valid semantic version.`
+    )
+  }
+
+  const currentMajor = parsedCurrent.major
+
+  if (currentMajor >= 1 && parsedCurrent.prerelease.length === 0) {
+    throw new Error(
+      `The current version "${colors.bold(currentVersion)}" is already a stable release.`
+    )
+  }
+
+  const baseVersion = `${parsedCurrent.major}.${parsedCurrent.minor}.${parsedCurrent.patch}`
+
+  let priorVersion: semver.SemVer | null = null
+
+  for (const version of iterateChangelogVersions(changelogContent)) {
+    const parsedVersion = semver.parse(version)
+
+    /* istanbul ignore else */
+    if (parsedVersion) {
+      if (!priorVersion) {
+        if (version !== currentVersion) {
+          return version
+        }
+
+        priorVersion = parsedVersion
+      } else {
+        if (semver.gte(parsedVersion, priorVersion)) {
+          throw new Error(
+            `Each newer release must have a higher version, but "${colors.bold(priorVersion.version)}" appears before "${colors.bold(version)}".`
+          )
+        }
+
+        priorVersion = parsedVersion
+
+        const { major, minor, patch } = parsedVersion
+
+        if (currentMajor >= 1 && `${major}.${minor}.${patch}` !== baseVersion) {
+          return version
+        }
+      }
+    }
+  }
+
+  return null
+}

package/src/workflow/changelog/extractSemVer.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Fai
+
+import { SEMVER_REGEX } from '#config'
+import { compact } from '#util'
+
+const ANCHORED_SEMVER_REGEX = new RegExp(`^${SEMVER_REGEX.source}$`)
+
+const BRACKETED_SEMVER_REGEX = new RegExp(`\\[${SEMVER_REGEX.source}\\]`)
+
+/**
+ * Extract SemVer core strings from a line.
+ *
+ * Splits the line on runs of spaces or tabs and on `..`/`...`. For each token,
+ * first attempts an anchored SemVer match (must match the whole token), then
+ * a bracketed match that finds a SemVer inside `[...]`. Returns the captured
+ * SemVer core (capture group 2) for each successful match; falsy results are
+ * filtered out.
+ *
+ * @param line Line to scan for SemVer cores
+ * @returns Array of extracted SemVer core strings; empty if none
+ */
+export function extractSemVer(line: string): string[] {
+  const tokens = line.split(/[ \t]+|\.{2,3}/)
+
+  return compact(
+    tokens.map((token) => {
+      return (
+        ANCHORED_SEMVER_REGEX.exec(token) ?? BRACKETED_SEMVER_REGEX.exec(token)
+      )?.at(2)
+    })
+  )
+}