relacher 0.0.1

package/README.md

@@ -0,0 +1,153 @@
+# Relache
+
+![NPM Version](https://img.shields.io/npm/v/relache?color=green)
+![NPM Downloads](https://img.shields.io/npm/dw/relache?label=npm)
+[![License](https://img.shields.io/github/license/emilien-jegou/oyui)](./LICENSE)
+
+**Relache** is a scriptable, workspace-aware release orchestration library and CLI tool designed specifically for multi-package workspaces.
+
+```
+📦 cli_tool     3.1.2 → 3.3.0 [minor]
+   flake.nix  README.md  CHANGELOG.md  CHANGELOG.md
+     ✦ 4a0ce62 feat(ui): add progress indicator to execution flow  Author 2025-01-30
+     ✦ Cascaded as [minor] from deps: plugin_api [minor]
+```
+
+## Features
+
+* 🤖 **Conventional Commits Engine:** Analyzes commit patterns to determine if modifications warrant a `patch`, `minor`, or `major` bump.
+* 🔗 **Topological Cascading Rules:** Automatically tracks internal crate dependencies, propagating downstream version updates throughout your workspace.
+* 🛠️ **TypeScript-First Configuration:** Declare, modify, and customize your release steps in code (via Bun, Deno, or Node) rather than static YAML or TOML configs.
+* 📝 **Custom Changelog Rendering:** Flexible templating interfaces to format changelog files with precise controls.
+
+---
+
+### Why relache?
+
+Most releases tools are configuration based, they often run as "all-or-nothing" CI black boxes. You execute the command, and it commits, tags, and publishes automatically.
+
+Think of them as large functions that take your whole toml config and repo state as arguments.
+
+Since relache is exposed as a typescript library you have full control of each step of the release lifecycle, you can replace or extends blocks as-needed without needing an extensive plugin system.
+
+It's also meant to be used to update thoses annoying tasks of updating the version in deeply nested places. e.g. a frontend component, a readme...
+
+```typescript
+  // cargoDeps will analyzer your workspace and form a graph of every crates
+  const CargoDeps = cargoDeps(tempDir).on('cli_tool', (c) => c
+      .update(
+        regexUpdate({
+          path: './flake.nix',
+          search: 'version = "[^"]+"',
+          replace: 'version = "{{version}}"',
+        }),
+      )
+      .update(
+        regexUpdate({
+          path: './README.md',
+          search: 'CLI Tool v[^\\s]+',
+          replace: 'CLI Tool v{{version}}',
+        }),
+      )
+      .update(
+        changelogUpdate({
+          path: './crates/cli_tool/CHANGELOG.md',
+        }),
+      )
+      .update(
+        changelogUpdate({
+          path: './CHANGELOG.md',
+          global: true,
+          template: cliffTemplate,
+        }),
+      ),
+  );
+
+  // this is how a crate is stored internally (simplified), notice how it's
+  // just a toml parser under the hood, no mention of rust, you can copy the
+  // source code of the cargo parser and pretty much adapt it to any setup of your
+  // liking:
+  //
+  // {
+  //  "name": "cli_tool",
+  //  "watch": ["crates/cli_tool"],
+  //  "depends": ["plugin_api"],
+  //  "updates": [
+  //     {
+  //      "kind": "toml",
+  //      "path": "crates/cli_tool/Cargo.toml",
+  //      "toml": "package.version"
+  //     },
+  //     // flake.nix, regex, changelog...
+  //  ]
+  // }
+
+  // ... You could prepare more actions here, like adding npm deps.
+
+  const vcs = new JjVcsProvider(tempDir);
+
+  const updates = await prepare(CargoDeps, vcs, {
+    cwd: tempDir,
+    sizes: {
+      major: { pattern: '^[a-z]+(?:\\([^)]+\\))?!:|BREAKING CHANGE' },
+      minor: { pattern: '^feat|^revert' },
+      patch: { pattern: '^fix|^build|^refactor|^nit|^style' },
+      skip: { pattern: '^release|^chore|^infra|^docs|^test|^ci|^build' },
+    },
+    cascade: {
+      patch: {
+        skip: 'patch',
+        patch: 'patch',
+        minor: 'minor',
+        major: 'minor',
+      },
+    },
+  });
+
+  prettyPrint(updates);
+
+  const ans = prompt("Proceed with staging and committing release? [y/N]");
+  if (ans?.trim().toLowerCase() === "y") {
+    await run(updates, vcs, { cwd: root });
+    console.log("Release tags and files written successfully.");
+  }
+```
+
+## 📦 Installation
+
+Add `relache` to your JavaScript or TypeScript workspace:
+
+```sh
+bun add relache --dev
+# or
+pnpm install relache --save-dev
+```
+
+---
+
+## 🛠️ Configuration & Customization
+
+### Designing Custom Changelogs
+You can supply your own renderer directly through the `template` option in `changelogUpdate`, bypassing rigid markdown configurations:
+
+```typescript
+import type { ChangelogContext } from "relache";
+
+function customTemplate({ version, date, commits }: ChangelogContext): string {
+  let lines = [`## [${version}] - ${date}\n`];
+
+  for (const commit of commits) {
+    const icon = commit.isBreaking ? "⚠️" : commit.type === "feat" ? "✨" : "🐛";
+    lines.push(`- ${icon} **${commit.scope || "general"}:** ${commit.description}`);
+  }
+
+  return lines.join("\n");
+}
+```
+
+---
+
+## 🙏 Credits
+
+* [git-cliff](https://github.com/orhun/git-cliff)
+* [versio](https://github.com/chaaz/versio)

package/lib-types/builder/cargo.d.ts

@@ -0,0 +1,13 @@
+import { type DependencyList } from './shared';
+/**
+ * Loads a single Cargo project from a target Cargo.toml.
+ */
+export declare function cargoProject(cwd: string): DependencyList;
+/**
+ * Loads a Cargo workspace, tracking member paths and dependency links.
+ */
+export declare function cargoWorkspace(cwd: string): DependencyList;
+/**
+ * Auto-detects whether the directory corresponds to a workspace or single-project setup.
+ */
+export declare function cargoDeps(cwd: string): DependencyList;

package/lib-types/builder/index.d.ts

@@ -0,0 +1,3 @@
+export * from './shared';
+export * from './cargo';
+export * from './pnpm';

package/lib-types/builder/pnpm.d.ts

@@ -0,0 +1,13 @@
+import { type DependencyList } from './shared';
+/**
+ * Loads a single project package configuration from package.json.
+ */
+export declare function pnpmProject(cwd: string): DependencyList;
+/**
+ * Parses pnpm-workspace.yaml to identify target members and versioning topologies.
+ */
+export declare function pnpmWorkspace(cwd: string): DependencyList;
+/**
+ * Auto-detects whether the workspace configuration exists, reverting to single packages.
+ */
+export declare function pnpmDeps(cwd: string): DependencyList;

package/lib-types/builder/shared.d.ts

@@ -0,0 +1,12 @@
+import type { ChangelogUpdate, RegexUpdate, DependencyConfig, UpdateAction } from '../types';
+export declare function changelogUpdate(options: Omit<ChangelogUpdate, 'kind'>): ChangelogUpdate;
+export declare function regexUpdate(options: Omit<RegexUpdate, 'kind'>): RegexUpdate;
+export declare class SingleDependencyBuilder {
+    private config;
+    constructor(config: DependencyConfig);
+    update(action: UpdateAction): this;
+}
+export interface DependencyList extends Array<DependencyConfig> {
+    on(name: string, cb: (builder: SingleDependencyBuilder) => void): this;
+}
+export declare function decorateList(configs: DependencyConfig[]): DependencyList;

package/lib-types/index.d.ts

@@ -0,0 +1,6 @@
+export * from './prepare';
+export * from './run';
+export * from './vcs';
+export * from './builder';
+export * from './print';
+export * from './types';

package/lib-types/prepare.d.ts

@@ -0,0 +1,14 @@
+import { type BumpSize, type Commit, type VcsProvider, type DependencyConfig, type DependencyUpdateReport, type IntermediateReport, type PrepareOptions, type SizePatterns, type CascadeRules, type UpdateAction, type ChangelogContext } from './types';
+export declare function getTomlValue(content: string): string | null;
+export declare function bumpVersion(version: string, size: BumpSize): string;
+export declare function getCurrentVersion(dep: DependencyConfig, cwd: string): string;
+export declare function matchBumpSize(message: string, sizes: SizePatterns): BumpSize;
+export declare function evaluateCommitsBump(commits: Commit[], sizes: SizePatterns): BumpSize;
+export declare function topologicalSort(items: IntermediateReport[]): IntermediateReport[];
+export declare function propagateBumps(sorted: IntermediateReport[], rules?: CascadeRules): void;
+export declare function initReportItems(cargoDeps: DependencyConfig[], vcs: VcsProvider, sizes: SizePatterns, cwd: string): Promise<IntermediateReport[]>;
+export declare function prepare(cargoDeps: DependencyConfig[], vcs: VcsProvider, options?: PrepareOptions): Promise<DependencyUpdateReport[]>;
+export declare function buildChangelogBlock(version: string, commits: Commit[]): string;
+export declare function finalizeReports(sorted: IntermediateReport[]): DependencyUpdateReport[];
+export declare function defaultChangelogTemplate({ version, date, commits }: ChangelogContext): string;
+export declare function mapResolvedUpdates(updates: UpdateAction[], newVersion: string, crateCommits: Commit[], globalCommits: Commit[]): UpdateAction[];

package/lib-types/print.d.ts

@@ -0,0 +1,2 @@
+import type { DependencyUpdateReport } from './types';
+export declare function prettyPrint(reports: DependencyUpdateReport[]): void;

package/lib-types/run.d.ts

@@ -0,0 +1,7 @@
+import type { DependencyUpdateReport, VcsProvider } from './types';
+/**
+ * Applies calculated updates to files on disk, stages, commits, and tags using the provided VcsProvider.
+ */
+export declare function run(reports: DependencyUpdateReport[], vcs: VcsProvider, options: {
+    cwd: string;
+}): Promise<void>;

package/lib-types/types.d.ts

@@ -0,0 +1,87 @@
+import type { VcsProvider } from './vcs';
+export type BumpSize = "major" | "minor" | "patch" | "skip";
+export interface Commit {
+    hash: string;
+    shortHash: string;
+    author: string;
+    date: string;
+    message: string;
+    type: string;
+    scope: string | null;
+    isBreaking: boolean;
+    description: string;
+}
+export interface ChangelogContext {
+    version: string;
+    date: string;
+    commits: Commit[];
+}
+export interface ChangelogUpdate {
+    kind: "changelog";
+    path: string;
+    global?: boolean;
+    template?: (ctx: ChangelogContext) => string;
+    resolvedBlock?: string;
+}
+export interface TomlUpdate {
+    kind: "toml";
+    path: string;
+    toml: string;
+}
+export interface RegexUpdate {
+    kind: "regex";
+    path: string;
+    search: string;
+    replace: string;
+    resolvedReplace?: string;
+}
+export type UpdateAction = TomlUpdate | RegexUpdate | ChangelogUpdate;
+export interface DependencyConfig {
+    name: string;
+    watch?: string[];
+    updates?: UpdateAction[];
+    depends?: string[];
+}
+export interface PatternConfig {
+    pattern: string;
+}
+export interface SizePatterns {
+    major: PatternConfig;
+    minor: PatternConfig;
+    patch: PatternConfig;
+    skip: PatternConfig;
+}
+export interface CascadeRules {
+    skip?: Record<BumpSize, BumpSize>;
+    patch?: Record<BumpSize, BumpSize>;
+    minor?: Record<BumpSize, BumpSize>;
+    major?: Record<BumpSize, BumpSize>;
+}
+export interface PrepareOptions {
+    sizes?: SizePatterns;
+    cascade?: CascadeRules;
+    cwd?: string;
+}
+export interface DependencyUpdateReport {
+    name: string;
+    currentVersion: string;
+    newVersion: string;
+    bump: BumpSize;
+    originalBump?: BumpSize;
+    commits: Commit[];
+    updates: UpdateAction[];
+    depends?: string[];
+}
+export interface IntermediateReport {
+    name: string;
+    currentVersion: string;
+    newVersion: string;
+    bump: BumpSize;
+    originalBump?: BumpSize;
+    commits: Commit[];
+    updates: UpdateAction[];
+    depends: string[];
+}
+export declare const defaultSizes: SizePatterns;
+export declare const defaultCascadeRules: Required<CascadeRules>;
+export type { VcsProvider };

package/lib-types/vcs/git.d.ts

@@ -0,0 +1,14 @@
+import type { Commit, VcsProvider } from '../types';
+export declare function runGit(cmd: string, cwd: string): string;
+export declare function findLatestTag(tags: string[], prefix: string): string | null;
+export declare function resolveGitTag(name: string, allTags: string[]): string | null;
+export declare function getGitCommits(name: string, watch: string[], allTags: string[], cwd: string): Commit[];
+export declare class GitVcsProvider implements VcsProvider {
+    private cwd;
+    private allTags;
+    constructor(cwd: string);
+    private getAllTags;
+    getCommits(name: string, watch: string[]): Promise<Commit[]>;
+    commit(message: string): Promise<void>;
+    tag(tagName: string): Promise<void>;
+}

package/lib-types/vcs/index.d.ts

@@ -0,0 +1,8 @@
+import type { Commit } from '../types';
+export interface VcsProvider {
+    getCommits(name: string, watch: string[]): Promise<Commit[]>;
+    commit(message: string): Promise<void>;
+    tag(tagName: string): Promise<void>;
+}
+export * from './git';
+export * from './jj';

package/lib-types/vcs/jj.d.ts

@@ -0,0 +1,14 @@
+import type { Commit, VcsProvider } from '../types';
+export declare function runJj(cmd: string, cwd: string): string;
+export declare function findLatestJjTag(tags: string[], prefix: string): string | null;
+export declare function resolveJjTag(name: string, allTags: string[]): string | null;
+export declare function getJjCommits(name: string, watch: string[], allTags: string[], cwd: string): Commit[];
+export declare class JjVcsProvider implements VcsProvider {
+    private cwd;
+    private allTags;
+    constructor(cwd: string);
+    private getAllTags;
+    getCommits(name: string, watch: string[]): Promise<Commit[]>;
+    commit(message: string): Promise<void>;
+    tag(tagName: string): Promise<void>;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "relacher",
+  "version": "0.0.1",
+  "description": "Scriptable release orchestration library for monorepos",
+  "type": "module",
+  "private": false,
+  "author": "Emilien Jegou",
+  "license": "MIT",
+  "homepage": "https://github.com/emilien-jegou/relache#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emilien-jegou/relache.git"
+  },
+  "bugs": {
+    "url": "https://github.com/emilien-jegou/relache/issues"
+  },
+  "keywords": [
+    "bun",
+    "release",
+    "release-management",
+    "versioning",
+    "semver",
+    "monorepo",
+    "jujutsu",
+    "jj",
+    "git",
+    "pnpm",
+    "workspace",
+    "scriptable"
+  ],
+  "main": "./src/index.ts",
+  "types": "./lib-types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib-types/index.d.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "lib-types",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "ts:build": "tsc -p tsconfig.build.json",
+    "ts:watch": "tsc --noEmit --incremental --preserveWatchOutput --pretty --watch",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "lint:watch": "oxlint --watch",
+    "prepublishOnly": "bun run ts:build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^24.12.4",
+    "oxfmt": "^0.19.0",
+    "oxlint": "^1.64.0",
+    "prettier": "^3.8.3",
+    "typescript": "^5.0.0"
+  }
+}

package/src/builder/cargo.ts

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { DependencyConfig } from '../types';
+
+import { decorateList, type DependencyList } from './shared';
+
+/**
+ * Loads a single Cargo project from a target Cargo.toml.
+ */
+export function cargoProject(cwd: string): DependencyList {
+  const configs: DependencyConfig[] = [];
+  const rootCargo = path.join(cwd, 'Cargo.toml');
+
+  if (fs.existsSync(rootCargo)) {
+    const fileContent = fs.readFileSync(rootCargo, 'utf8');
+    const nameMatch = fileContent.match(/^name\s*=\s*"([^"]+)"/m);
+    const parsedName = nameMatch && nameMatch[1] ? nameMatch[1] : '';
+    if (parsedName) {
+      configs.push({
+        name: parsedName,
+        watch: ['.'],
+        depends: [],
+        updates: [{ kind: 'toml', path: 'Cargo.toml', toml: 'package.version' }],
+      });
+    }
+  }
+
+  return decorateList(configs);
+}
+
+/**
+ * Loads a Cargo workspace, tracking member paths and dependency links.
+ */
+export function cargoWorkspace(cwd: string): DependencyList {
+  const configs: DependencyConfig[] = [];
+  const rootCargo = path.join(cwd, 'Cargo.toml');
+
+  if (fs.existsSync(rootCargo)) {
+    const content = fs.readFileSync(rootCargo, 'utf8');
+    const membersMatch = content.match(/members\s*=\s*\[([^\]]+)\]/);
+    if (membersMatch && membersMatch[1]) {
+      const rawMembers = membersMatch[1].split(',').map((m) => m.replace(/["\s]/g, ''));
+      const crateInfos: { name: string; memberPath: string; content: string }[] = [];
+
+      for (const member of rawMembers) {
+        const globPath = path.join(cwd, member);
+        const cargoPaths = globPath.endsWith('*')
+          ? fs
+            .readdirSync(path.dirname(globPath))
+            .map((dir) => path.join(path.dirname(globPath), dir, 'Cargo.toml'))
+          : [path.join(globPath, 'Cargo.toml')];
+
+        for (const p of cargoPaths) {
+          if (fs.existsSync(p)) {
+            const fileContent = fs.readFileSync(p, 'utf8');
+            const nameMatch = fileContent.match(/^name\s*=\s*"([^"]+)"/m);
+            const parsedName = nameMatch && nameMatch[1] ? nameMatch[1] : '';
+            if (parsedName) {
+              crateInfos.push({
+                name: parsedName,
+                memberPath: path.dirname(p),
+                content: fileContent,
+              });
+            }
+          }
+        }
+      }
+
+      for (const info of crateInfos) {
+        const relativePath = path.relative(cwd, info.memberPath);
+        const relativeCargo = path.join(relativePath, 'Cargo.toml');
+
+        const depends: string[] = [];
+        for (const other of crateInfos) {
+          if (other.name === info.name) continue;
+          const depPattern = new RegExp(`^${other.name}\\s*=`, 'm');
+          if (depPattern.test(info.content)) {
+            depends.push(other.name);
+          }
+        }
+
+        configs.push({
+          name: info.name,
+          watch: [relativePath],
+          depends,
+          updates: [{ kind: 'toml', path: relativeCargo, toml: 'package.version' }],
+        });
+      }
+    }
+  }
+
+  return decorateList(configs);
+}
+
+/**
+ * Auto-detects whether the directory corresponds to a workspace or single-project setup.
+ */
+export function cargoDeps(cwd: string): DependencyList {
+  const rootCargo = path.join(cwd, 'Cargo.toml');
+  if (fs.existsSync(rootCargo)) {
+    const content = fs.readFileSync(rootCargo, 'utf8');
+    if (content.includes('members =')) {
+      return cargoWorkspace(cwd);
+    }
+    if (content.includes('package =') || content.match(/^name\s*=/m)) {
+      return cargoProject(cwd);
+    }
+  }
+  return decorateList([]);
+}

package/src/builder/index.ts

@@ -0,0 +1,3 @@
+export * from './shared';
+export * from './cargo';
+export * from './pnpm';