rman 0.37.4 → 1.0.1

package/utils/change-hash.js

@@ -0,0 +1,80 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+/** `.rmanrc changelog.tagPattern` (cascaded, per-package overridable) - a glob for this package's
+ *  release tags. `{name}` (if present) is replaced with the package's own name, e.g. `{name}@*`
+ *  for independent per-package versioning (`@scope/pkg@1.2.3`, the same scheme lerna/changesets
+ *  use - `@`/`/` are both fine in a git tag name). Without `{name}`, it's a single repo-wide tag
+ *  shared by every package (e.g. the default `v*`). */
+export function tagPattern(pkg) {
+    const cfg = pkg.config?.changelog;
+    return typeof cfg?.tagPattern === 'string' && cfg.tagPattern ? cfg.tagPattern : DEFAULT_TAG_PATTERN;
+}
+/** This package's most recent release tag - the `{name}`-bearing pattern looks up that package's
+ *  *own* tags directly (newest by version sort); a repo-wide pattern instead finds the nearest tag
+ *  HEAD actually descends from, since no single package "owns" that tag. `undefined` if never
+ *  tagged at all (a fresh package, or one that's never been released). Shared by `changelog`
+ *  (reading the last-documented version) and `version` (finding the boundary a bump measures
+ *  "since"). */
+export async function findLatestTag(git, pkg) {
+    const pattern = tagPattern(pkg);
+    const expanded = pattern.replace('{name}', pkg.name);
+    return pattern.includes('{name}') ? (await git.listTags(expanded))[0] : await git.describeTag(expanded);
+}
+/** Strips the pattern's literal prefix (everything before its first `*`) from `tag` to get just
+ *  the version part - e.g. tag `@sqb/builder@1.2.3` against pattern `@sqb/builder@*` -> `1.2.3`.
+ *  A pattern with no `*` is returned as its own "version" verbatim (an exact tag, nothing to strip). */
+export function extractVersion(tag, expandedPattern) {
+    const starIdx = expandedPattern.indexOf('*');
+    if (starIdx === -1)
+        return tag;
+    const prefix = expandedPattern.slice(0, starIdx);
+    return tag.startsWith(prefix) ? tag.slice(prefix.length) : tag;
+}
+/** Looks up `name`'s currently-published version on the npm registry, or `undefined` if it isn't
+ *  published there at all (private, scoped-but-unpublished, no network, ...) - the real npm CLI
+ *  call `detectChangeHash` uses by default; injectable via its `npmViewVersion` option so tests
+ *  aren't making real registry calls. */
+export async function defaultNpmViewVersion(name, cwd) {
+    try {
+        const { stdout } = await execFileAsync('npm', ['view', name, 'version'], { cwd });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolves the commit/hash a package's changes should be measured "since" - the boundary
+ * `changelog --from` uses, but reusable anywhere a command wants to answer "what changed for this
+ * package". An explicit `options.from` (anything but `"npm"`) is returned as-is, applying the same
+ * way to every package. Otherwise, it's auto-detected from the package's currently-published npm
+ * version: looked up via `npmViewVersion`, then mapped to a git tag using `.rmanrc
+ * changelog.tagPattern` (so independent and fixed monorepo versioning schemes both work - see
+ * `tagPattern`) - and, if `catchUpFile` is given and exists, widened to also cover anything that
+ * file hasn't caught up on yet (see its doc comment). Returns `undefined` when nothing can be
+ * resolved at all (unpublished, no network, no matching tag, no catch-up file) - callers should
+ * fall back to their own default in that case (e.g. `GitHelper.listCommits`'s "not yet pushed"
+ * default when no hash is given).
+ */
+export async function detectChangeHash(git, pkg, options = {}) {
+    if (options.from && options.from !== 'npm')
+        return options.from;
+    const npmViewVersion = options.npmViewVersion ?? defaultNpmViewVersion;
+    const publishedVersion = await npmViewVersion(pkg.name, git.cwd);
+    let npmHash;
+    if (publishedVersion) {
+        const pattern = tagPattern(pkg);
+        const expanded = pattern.replace('{name}', pkg.name);
+        const starIdx = expanded.indexOf('*');
+        const tag = starIdx === -1 ? expanded : expanded.slice(0, starIdx) + publishedVersion + expanded.slice(starIdx + 1);
+        npmHash = (await git.tagExists(tag)) ? tag : undefined;
+    }
+    const fileHash = options.catchUpFile ? await git.lastCommitTouching(options.catchUpFile) : undefined;
+    if (!fileHash)
+        return npmHash;
+    if (!npmHash)
+        return fileHash;
+    return (await git.mergeBase(npmHash, fileHash)) ?? npmHash;
+}
+const execFileAsync = promisify(execFile);
+const DEFAULT_TAG_PATTERN = 'v*';

package/utils/conventional-commits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `type(scope): description`, optionally with a `!` breaking-change marker - Conventional
+ * Commits' subject-line shape. Anything that doesn't match falls into "Other Changes" as-is (for
+ * changelog entries) or defaults to a patch-level change (for version bump severity) - see
+ * `parseConventionalCommit`.
+ */
+export declare const CONVENTIONAL_PATTERN: RegExp;
+/** A bare version-bump commit (`"6.0.1"`, `"v2.3.0-beta.1"`, ...) - many release tools commit the
+ *  version bump itself with just the new version number as the message. That's a release marker,
+ *  not a real change worth describing (or worth bumping a version over on its own), so it's
+ *  dropped everywhere a real change is being looked for. */
+export declare const VERSION_BUMP_PATTERN: RegExp;
+export interface ParsedCommitSubject {
+    type: string;
+    scope?: string;
+    /** A `!` right before the `:` (e.g. `feat!:`) - Conventional Commits' inline breaking-change
+     *  marker. Doesn't cover a `BREAKING CHANGE:` footer, since only the subject line is available. */
+    breaking: boolean;
+    description: string;
+}
+/** Parses a commit subject as Conventional Commits, or `undefined` if it doesn't match at all
+ *  (a non-conventional message - still a real change, just with no `type` to key off of). */
+export declare function parseConventionalCommit(subject: string): ParsedCommitSubject | undefined;
+/** Whether a commit `body` carries a Conventional Commits `BREAKING CHANGE:` (or
+ *  `BREAKING-CHANGE:`) footer - the other, footer-based way to mark a breaking change, alongside
+ *  the inline `!` the subject line alone can carry (see `parseConventionalCommit`, whose own
+ *  `breaking` only ever reflects that marker, never a footer, since it only sees the subject). */
+export declare function hasBreakingChangeFooter(body: string): boolean;
+/**
+ * A `Release-As: patch|minor|major` footer in a commit `body` - lets that one commit's own
+ * contribution to a detected bump severity be overridden by hand, regardless of what its subject
+ * line (or a `BREAKING CHANGE:` footer) would otherwise imply. The motivating case: a `feat:`
+ * commit that needs to ship right now as a patch, without waiting for the rest of a minor's worth
+ * of work to land - `Release-As: patch` on just that commit ships it alone, at patch severity,
+ * while a later genuine `feat:` (with no override) still correctly triggers a minor of its own.
+ * Case-insensitive; the last match wins if a body somehow has more than one, matching how multiple
+ * git trailers of the same key are conventionally read (later overrides earlier).
+ */
+export declare function parseReleaseAs(body: string): 'patch' | 'minor' | 'major' | undefined;

package/utils/conventional-commits.js

@@ -0,0 +1,43 @@
+/**
+ * `type(scope): description`, optionally with a `!` breaking-change marker - Conventional
+ * Commits' subject-line shape. Anything that doesn't match falls into "Other Changes" as-is (for
+ * changelog entries) or defaults to a patch-level change (for version bump severity) - see
+ * `parseConventionalCommit`.
+ */
+export const CONVENTIONAL_PATTERN = /^(\w+)(\(([^)]+)\))?(!)?:\s*(.+)$/;
+/** A bare version-bump commit (`"6.0.1"`, `"v2.3.0-beta.1"`, ...) - many release tools commit the
+ *  version bump itself with just the new version number as the message. That's a release marker,
+ *  not a real change worth describing (or worth bumping a version over on its own), so it's
+ *  dropped everywhere a real change is being looked for. */
+export const VERSION_BUMP_PATTERN = /^v?\d+\.\d+\.\d+(?:[-+][\w.]+)?$/;
+/** Parses a commit subject as Conventional Commits, or `undefined` if it doesn't match at all
+ *  (a non-conventional message - still a real change, just with no `type` to key off of). */
+export function parseConventionalCommit(subject) {
+    const m = CONVENTIONAL_PATTERN.exec(subject);
+    if (!m)
+        return undefined;
+    const [, type, , scope, breakingMark, description] = m;
+    return { type: type.toLowerCase(), scope, breaking: !!breakingMark, description };
+}
+/** Whether a commit `body` carries a Conventional Commits `BREAKING CHANGE:` (or
+ *  `BREAKING-CHANGE:`) footer - the other, footer-based way to mark a breaking change, alongside
+ *  the inline `!` the subject line alone can carry (see `parseConventionalCommit`, whose own
+ *  `breaking` only ever reflects that marker, never a footer, since it only sees the subject). */
+export function hasBreakingChangeFooter(body) {
+    return /^BREAKING[ -]CHANGE:/im.test(body);
+}
+/**
+ * A `Release-As: patch|minor|major` footer in a commit `body` - lets that one commit's own
+ * contribution to a detected bump severity be overridden by hand, regardless of what its subject
+ * line (or a `BREAKING CHANGE:` footer) would otherwise imply. The motivating case: a `feat:`
+ * commit that needs to ship right now as a patch, without waiting for the rest of a minor's worth
+ * of work to land - `Release-As: patch` on just that commit ships it alone, at patch severity,
+ * while a later genuine `feat:` (with no override) still correctly triggers a minor of its own.
+ * Case-insensitive; the last match wins if a body somehow has more than one, matching how multiple
+ * git trailers of the same key are conventionally read (later overrides earlier).
+ */
+export function parseReleaseAs(body) {
+    const matches = [...body.matchAll(/^release-as:\s*(patch|minor|major)\s*$/gim)];
+    const last = matches.at(-1);
+    return last ? last[1].toLowerCase() : undefined;
+}

package/utils/exec.d.ts

@@ -1,18 +1,17 @@
-import { ChildProcess } from 'child_process';
-export interface IExecutorOptions {
+export interface ExecOptions {
+    /** 'inherit' streams the child directly to our stdio (used for non-TTY/CI passthrough).
+     *  'pipe' (default) captures output so the caller can drive a live view via onLine. */
     stdio?: 'inherit' | 'pipe';
     cwd?: string;
     argv?: string[];
     env?: Record<string, string | undefined>;
     shell?: boolean;
-    onSpawn?: (childProcess: ChildProcess) => void;
     onLine?: (line: string, stdio: 'stderr' | 'stdout') => void;
-    onData?: (data: string, stdio: 'stderr' | 'stdout') => void;
     throwOnError?: boolean;
 }
-export interface ExecuteCommandResult {
+export interface ExecResult {
     code?: number;
     error?: Error;
     stdout?: string;
 }
-export declare function exec(command: string, options?: IExecutorOptions): Promise<ExecuteCommandResult>;
+export declare function exec(command: string, options?: ExecOptions): Promise<ExecResult>;

package/utils/exec.js

@@ -1,7 +1,6 @@
-import { spawn } from 'child_process';
+import { ChildProcess, spawn } from 'child_process';
 import { onExit } from 'signal-exit';
 import { npmRunPathEnv } from './npm-run-path.js';
-const runningChildren = new Map();
 export async function exec(command, options) {
     const opts = {
         shell: true,
@@ -12,72 +11,60 @@ export async function exec(command, options) {
         ...npmRunPathEnv({ cwd: opts.cwd }),
         ...opts.env,
     };
-    if (process.env.TS_NODE_PROJECT)
-        delete opts.env.TS_NODE_PROJECT;
     opts.cwd = opts.cwd || process.cwd();
     const spawnOptions = {
-        stdio: opts.stdio || 'pipe',
+        stdio: opts.stdio === 'inherit' ? 'inherit' : 'pipe',
         env: opts.env,
         cwd: opts.cwd,
         shell: opts.shell,
         windowsHide: true,
     };
-    const result = {
-        code: undefined,
-        stdout: '',
-    };
-    let buffer = '';
-    const processData = (data, stdio) => {
-        buffer += '' + data;
-        result.stdout += '' + data;
-        if (opts.onData)
-            opts.onData(data, stdio);
-    };
-    const processLines = (stdio, flush) => {
-        let chunk = buffer;
+    const result = { code: undefined, stdout: '' };
+    /** Separate buffers per stream - stdout/stderr chunks must never be spliced into the same line. */
+    let stdoutBuffer = '';
+    let stderrBuffer = '';
+    const processLines = (data, stdio, flush) => {
+        result.stdout += data;
+        if (!opts.onLine)
+            return;
+        let buf = (stdio === 'stdout' ? stdoutBuffer : stderrBuffer) + data;
+        /** Only synthesize a trailing newline if there's real unterminated content left - an
+         *  already-empty buffer must not produce a spurious blank line on every flush. */
+        if (flush && buf.length && !buf.endsWith('\n'))
+            buf += '\n';
         let i;
-        if (flush && !chunk.endsWith('\n'))
-            chunk += '\n';
-        while ((i = chunk.indexOf('\n')) >= 0) {
-            const line = chunk.substring(0, i);
-            chunk = chunk.substring(i + 1);
-            if (opts.onLine)
-                opts.onLine(line, stdio);
+        while ((i = buf.indexOf('\n')) >= 0) {
+            const line = buf.slice(0, i);
+            buf = buf.slice(i + 1);
+            opts.onLine(line, stdio);
         }
-        buffer = chunk;
+        if (stdio === 'stdout')
+            stdoutBuffer = buf;
+        else
+            stderrBuffer = buf;
     };
     const child = spawn(command, opts.argv || [], spawnOptions);
-    if (child.pid) {
+    if (child.pid)
         runningChildren.set(child.pid, child);
-        if (opts.onSpawn)
-            opts.onSpawn(child);
-    }
-    child.stdout?.on('data', data => {
-        processData(data, 'stdout');
-        processLines('stdout');
-    });
-    child.stderr?.on('data', data => {
-        processData(data, 'stderr');
-        processLines('stderr');
-    });
+    child.stdout?.on('data', data => processLines(String(data), 'stdout'));
+    child.stderr?.on('data', data => processLines(String(data), 'stderr'));
     return new Promise((resolve, reject) => {
-        let resolved;
+        let resolved = false;
         child.on('error', (err) => {
             if (child.pid)
                 runningChildren.delete(child.pid);
-            processLines('stdout', true);
-            processLines('stderr', true);
+            processLines('', 'stdout', true);
+            processLines('', 'stderr', true);
             if (resolved)
                 return;
-            result.code = err.code || 1;
-            if (!err) {
-                const text = `Command failed (${result.code})`;
-                err = new Error(text);
-            }
-            if (typeof err === 'string')
-                err = new Error(err);
-            result.error = err;
             resolved = true;
+            result.code = err.code || 1;
+            result.error =
+                typeof err === 'string'
+                    ? new Error(err)
+                    : err instanceof Error
+                        ? err
+                        : new Error(`Command failed (${result.code})`);
             if (opts.throwOnError)
                 return reject(result.error);
             resolve(result);
@@ -85,22 +72,21 @@ export async function exec(command, options) {
         child.on('close', (code) => {
             if (child.pid)
                 runningChildren.delete(child.pid);
-            processLines('stdout', true);
-            processLines('stderr', true);
+            processLines('', 'stdout', true);
+            processLines('', 'stderr', true);
             if (resolved)
                 return;
-            result.code = code;
             resolved = true;
-            if (code) {
-                const text = `Command failed (${result.code})`;
-                result.error = new Error(text);
-            }
-            return resolve(result);
+            result.code = code;
+            if (code)
+                result.error = new Error(`Command failed (${code})`);
+            if (result.error && opts.throwOnError)
+                return reject(result.error);
+            resolve(result);
         });
     });
 }
+const runningChildren = new Map();
 onExit(() => {
-    runningChildren.forEach(child => {
-        child.kill();
-    });
+    runningChildren.forEach(child => child.kill());
 });

package/utils/git.d.ts

@@ -0,0 +1,86 @@
+export interface GitOptions {
+    cwd?: string;
+}
+export interface CommitInfo {
+    sha: string;
+    subject: string;
+    /** Everything after the subject line (blank line included) - where Conventional Commits'
+     *  footers/trailers live (`BREAKING CHANGE:`, `Release-As:`, ...) - see `conventional-commits.ts`. */
+    body: string;
+    /** Absolute paths of every file this commit touched. */
+    files: string[];
+}
+export declare class GitHelper {
+    cwd: string;
+    constructor(options?: GitOptions);
+    /** The current branch name, or `undefined` in detached HEAD state (or outside a git repository) -
+     *  what `branch-guard.ts` checks `allowBranch`/`ignoreBranch` against. */
+    currentBranch(): Promise<string | undefined>;
+    /** Files with uncommitted local changes (working tree + index). */
+    listDirtyFiles(options?: {
+        absolute?: boolean;
+    }): Promise<string[]>;
+    /** Files committed on the current branch but not yet in its upstream. */
+    listCommittedFiles(options?: {
+        absolute?: boolean;
+    }): Promise<string[]>;
+    /** Files changed since `hash` (committed diffs plus any uncommitted local changes). */
+    listChangedSince(hash: string, options?: {
+        absolute?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Real commits only (never uncommitted/dirty changes - those have no message and can't be
+     * described in a changelog), oldest first: with `hash`, everything committed since that ref;
+     * without one, whatever's committed on the current branch but not yet in its upstream (same
+     * source as `listCommittedFiles`, via `git cherry`).
+     */
+    listCommits(options?: {
+        hash?: string;
+    }): Promise<CommitInfo[]>;
+    /** Every commit reachable from HEAD, oldest first - for a boundary-free "everything so far"
+     *  view (e.g. a package that's never been tagged/released at all, so there's no "since" ref to
+     *  measure from and `listCommits()`'s own no-hash fallback, upstream push status, doesn't apply -
+     *  a repo with no configured remote at all is common and shouldn't read as "nothing happened"). */
+    listAllCommits(): Promise<CommitInfo[]>;
+    private _commitInfoFor;
+    /** Tag names matching the glob `pattern` (e.g. `"v*"`, `"pkg-a@*"`), newest version first. */
+    listTags(pattern: string): Promise<string[]>;
+    /** Whether `tag` exists as an exact git tag name (not a glob - a literal ref check). */
+    tagExists(tag: string): Promise<boolean>;
+    /** The most recent commit that changed `file` (tracked history only) - `undefined` if it has
+     *  never been committed. Answers "since when has this file last been updated", independent of
+     *  any tag/version scheme - e.g. to check whether a changelog file has fallen behind. */
+    lastCommitTouching(file: string): Promise<string | undefined>;
+    /** The best common ancestor of `a` and `b` - `undefined` if none exists (unrelated histories,
+     *  an invalid ref, ...). */
+    mergeBase(a: string, b: string): Promise<string | undefined>;
+    /** The most recent tag matching the glob `pattern` that HEAD actually descends from (unlike
+     *  `listTags`, this follows commit ancestry rather than just sorting tag names - the right
+     *  choice for a single repo-wide tag scheme, where a package has no tag of its own). */
+    describeTag(pattern: string): Promise<string | undefined>;
+    /** Stages and commits exactly `files` (relative to `cwd`, or absolute) with `message` - never a
+     *  blanket `git add -A`, so the commit only ever contains what the caller explicitly asked for. */
+    commit(files: string[], message: string): Promise<void>;
+    /** Creates an annotated tag `name` pointing at HEAD, with `message` (defaults to `name`).
+     *  Throws if a tag with that name already exists - callers wanting idempotent tagging should
+     *  check `tagExists` first. */
+    createTag(name: string, message?: string): Promise<void>;
+    /** Pushes the current branch to `remote` (default `"origin"`), and its tags too unless
+     *  `options.tags` is `false`. */
+    push(options?: {
+        remote?: string;
+        tags?: boolean;
+    }): Promise<void>;
+    /** Raw `git diff <hash>..HEAD` text (committed changes plus any uncommitted local ones, same as
+     *  plain `git diff <hash>`) - unlike `listChangedSince`, the actual patch content, not just
+     *  which files changed. `pathspec`, if given, narrows it to just that file/directory. */
+    diff(hash: string, pathspec?: string): Promise<string>;
+    /** `git format-patch --root -o <outputDir> HEAD` - one `.patch` file per commit reachable from
+     *  HEAD (oldest first), `--root` included so the very first commit gets one too. Returns the
+     *  patch file paths, in commit order - what `import` replays into another repository. */
+    formatPatches(outputDir: string): Promise<string[]>;
+    /** Applies `patchFiles` (as produced by `formatPatches`, in order) via `git am`, preserving each
+     *  original commit's author/date/message. `--3way` lets a patch that no longer applies cleanly
+     *  fall back to a content-level three-way merge instead of failing outright. */
+    applyPatches(patchFiles: string[]): Promise<void>;
+}