rman 0.38.0 → 1.0.1

package/commands/version.command.d.ts

@@ -0,0 +1,3 @@
+import type { Argv } from 'yargs';
+import type { Repository } from '../core/repository.js';
+export declare function initCli(repository: Repository, program: Argv): void;

package/commands/version.command.js

@@ -0,0 +1,125 @@
+import readline from 'node:readline/promises';
+import colors from 'ansi-colors';
+import { VersionService } from '../services/version.service.js';
+import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+export function initCli(repository, program) {
+    program.command({
+        command: 'version [bump]',
+        describe: 'Bumps versions of changed packages (and their dependents), grouped via .rmanrc "group"',
+        builder: cmd => applyBranchGuardOptions(applyPackageFilterOptions(cmd))
+            .example('$0 version patch', '# Bump patch severity directly, applied immediately')
+            .example('$0 version', "# Auto-detect severity from commits, show the plan, don't write anything")
+            .example('$0 version --interactive', '# Show the plan either way, then ask for confirmation')
+            .positional('bump', {
+            describe: 'A release-type keyword ("patch"/"minor"/"major") or an explicit semver version. ' +
+                'Omit to auto-detect from commits and only preview the plan.',
+            type: 'string',
+        })
+            .option('interactive', {
+            alias: 'i',
+            describe: 'Show the plan and ask for confirmation before applying (with or without an explicit bump)',
+            type: 'boolean',
+        })
+            .option('ignore-dirty', {
+            describe: 'Exclude a package with uncommitted local changes instead of aborting the whole run',
+            type: 'boolean',
+        })
+            .option('push', {
+            describe: 'Push the resulting commit(s) and tag(s) to the remote once applied',
+            type: 'boolean',
+        })
+            .option('message', {
+            alias: 'm',
+            describe: 'Override the commit message for every group this run commits (default: .rmanrc ' +
+                'version.commitMessage, or "chore(release): v{version}") - "{version}" is substituted ' +
+                "when a commit's own group shares one version.",
+            type: 'string',
+        })
+            .option('changelog', {
+            describe: "Also write each bumped package's CHANGELOG.md (same as running changelog --write " +
+                'separately) and fold it into the same commit as its version bump',
+            type: 'boolean',
+        })
+            .option('preid', {
+            describe: 'Make the bump a prerelease with this identifier (e.g. "beta" -> 1.2.3-beta.0). ' +
+                'Running again with the same --preid increments it (-> 1.2.3-beta.1); a different ' +
+                'identifier starts a fresh prerelease line. Ignored when bump is an explicit semver version.',
+            type: 'string',
+        }),
+        handler: async (args) => {
+            await assertAllowedBranch(repository, readBranchGuardOptions(args));
+            const bump = args.bump;
+            const plan = await VersionService.getPlan(repository, {
+                ...readPackageFilterOptions(args),
+                bump,
+                ignoreDirty: args.ignoreDirty,
+                preid: args.preid,
+            });
+            printPlan(plan);
+            const errors = plan.filter(e => e.status === 'error');
+            if (errors.length) {
+                const message = `${errors.length} package(s) have uncommitted local changes ` +
+                    '(pass --ignore-dirty to exclude them instead of aborting)';
+                console.log(colors.red(message));
+                const err = new Error(message);
+                err.logged = true;
+                throw err;
+            }
+            if (!plan.some(e => e.status === 'bump')) {
+                console.log(colors.gray('Nothing to version.'));
+                return;
+            }
+            let apply = !!bump;
+            if (args.interactive) {
+                apply = await confirm('Apply these changes?');
+            }
+            else if (!bump) {
+                console.log(colors.gray('Run again with an explicit bump, or --interactive, to apply.'));
+                return;
+            }
+            if (!apply)
+                return;
+            const applied = await VersionService.applyPlan(repository, plan, {
+                push: args.push,
+                message: args.message,
+                changelog: args.changelog,
+            });
+            for (const entry of applied) {
+                if (entry.status === 'bump') {
+                    console.log(colors.green('updated'), colors.cyan(entry.package.name), entry.from, '->', colors.yellow(entry.to));
+                }
+            }
+        },
+    });
+}
+function printPlan(entries) {
+    for (const e of entries) {
+        const name = colors.cyan(e.package.name);
+        const group = colors.gray(`(${e.group})`);
+        switch (e.status) {
+            case 'bump':
+                console.log(colors.green('bump'), name, group, e.from, '->', colors.yellow(e.to), colors.gray(e.reason ?? ''));
+                break;
+            case 'no-change':
+                console.log(colors.gray('no-change'), name, group, e.from);
+                break;
+            case 'skip':
+                console.log(colors.cyan('skip'), name, group, colors.gray(e.reason ?? ''));
+                break;
+            case 'error':
+                console.log(colors.red('error'), name, group, colors.red(e.reason ?? ''));
+                break;
+        }
+    }
+}
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`${question} (y/N) `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/constants.js

@@ -1 +1 @@
-export const version = '0.38.0';
+export const version = '1.0.1';

package/core/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reads the rman configuration defined at a single directory level, merging
+ * (in increasing precedence): `package.json#rman`, `.rman.yml`, `.rmanrc`.
+ */
+export declare function readDirConfig(dirname: string): any;
+/**
+ * Resolves the effective config for `targetDir` by cascading from `rootDir`
+ * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
+ * works: each directory level overrides the ones above it. This lets a
+ * package (or any intermediate directory) narrow or override the repository's
+ * root configuration for itself and everything below it.
+ */
+export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, any>): any;

package/core/config.js

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import * as yaml from 'js-yaml';
+import path from 'path';
+import merge from 'putil-merge';
+/**
+ * Reads the rman configuration defined at a single directory level, merging
+ * (in increasing precedence): `package.json#rman`, `.rman.yml`, `.rmanrc`.
+ */
+export function readDirConfig(dirname) {
+    const result = {};
+    const pkgJsonFile = path.join(dirname, 'package.json');
+    if (fs.existsSync(pkgJsonFile)) {
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonFile, 'utf-8'));
+        if (pkgJson && typeof pkgJson.rman === 'object')
+            merge(result, pkgJson.rman, { deep: true });
+    }
+    const ymlFile = path.join(dirname, '.rman.yml');
+    if (fs.existsSync(ymlFile)) {
+        const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
+        if (obj && typeof obj === 'object')
+            merge(result, obj, { deep: true });
+    }
+    const rcFile = path.join(dirname, '.rmanrc');
+    if (fs.existsSync(rcFile)) {
+        const obj = JSON.parse(fs.readFileSync(rcFile, 'utf-8'));
+        if (obj && typeof obj === 'object')
+            merge(result, obj, { deep: true });
+    }
+    return result;
+}
+/**
+ * Resolves the effective config for `targetDir` by cascading from `rootDir`
+ * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
+ * works: each directory level overrides the ones above it. This lets a
+ * package (or any intermediate directory) narrow or override the repository's
+ * root configuration for itself and everything below it.
+ */
+export function resolveConfig(rootDir, targetDir, cache = new Map()) {
+    const result = {};
+    for (const dir of dirChain(rootDir, targetDir)) {
+        let local = cache.get(dir);
+        if (!local) {
+            local = readDirConfig(dir);
+            cache.set(dir, local);
+        }
+        merge(result, local, { deep: true });
+    }
+    return result;
+}
+function dirChain(rootDir, targetDir) {
+    const rel = path.relative(rootDir, targetDir);
+    if (!rel || rel === '.' || rel.startsWith('..'))
+        return [rootDir];
+    const dirs = [rootDir];
+    let dir = rootDir;
+    for (const segment of rel.split(path.sep)) {
+        dir = path.join(dir, segment);
+        dirs.push(dir);
+    }
+    return dirs;
+}

package/core/package.d.ts

@@ -2,6 +2,8 @@ export declare class Package {
     readonly dirname: string;
     private _json;
     dependencies: string[];
+    /** Effective rman config for this package, cascaded from the repository root. */
+    config: any;
     constructor(dirname: string);
     get basename(): string;
     get name(): string;

package/core/package.js

@@ -4,6 +4,8 @@ export class Package {
     dirname;
     _json;
     dependencies = [];
+    /** Effective rman config for this package, cascaded from the repository root. */
+    config = {};
     constructor(dirname) {
         this.dirname = dirname;
         this.reloadJson();

package/core/repository.d.ts

@@ -1,20 +1,53 @@
 import { Package } from './package.js';
 export declare class Repository extends Package {
     readonly dirname: string;
-    readonly config: any;
     readonly monorepo: boolean;
     readonly packages: Package[];
+    /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
+     *  resolved repository root, possibly several levels up), this is where the user's shell
+     *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
+    readonly cwd: string;
     readonly rootPackage: Package;
-    protected constructor(dirname: string, config: any, monorepo: boolean, packages: Package[]);
+    protected constructor(dirname: string, monorepo: boolean, packages: Package[], 
+    /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
+     *  resolved repository root, possibly several levels up), this is where the user's shell
+     *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
+    cwd?: string);
+    /**
+     * The package whose own directory contains `cwd` (the deepest match, so a package nested
+     * inside another's directory resolves to the innermost one) - or `undefined` when `cwd` *is*
+     * the repository root itself, or isn't inside any known package (e.g. a non-monorepo checkout,
+     * or a stray directory the workspace glob doesn't cover).
+     */
+    get currentPackage(): Package | undefined;
     getPackages(options?: {
         scope?: string | string[];
         toposort?: boolean;
     }): Package[];
     getPackage(name: string): Package | undefined;
+    /**
+     * Reports each package's git change status. `dirty` (uncommitted local
+     * changes) is always checked first, regardless of `hash` - a file can be
+     * dirty no matter what it's being compared against. Once a package isn't
+     * dirty, the reference point decides the rest: without `hash`, `committed`
+     * means committed but not yet in the upstream branch; with `hash`, `changed`
+     * means it differs from that commit. Otherwise a package is `clean`.
+     */
+    listStatus(options?: {
+        hash?: string;
+    }): Promise<Record<string, Repository.PackageStatus>>;
+    /**
+     * Resolves the effective rman config for the repository root and every
+     * package, cascading root -> intermediate directories -> package directory,
+     * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
+     */
+    protected _resolveConfigs(): void;
     protected _updateDependencies(): void;
     static create(root?: string, options?: {
         deep?: number;
     }): Repository;
     protected static _resolvePackages(dirname: string, patterns: string[]): Package[];
-    protected static _readConfig(dirname: string): any;
+}
+export declare namespace Repository {
+    type PackageStatus = 'dirty' | 'committed' | 'changed' | 'clean';
 }

package/core/repository.js

@@ -1,27 +1,55 @@
 import glob from 'fast-glob';
 import fs from 'fs';
-import * as yaml from 'js-yaml';
 import path from 'path';
-import merge from 'putil-merge';
+import { GitHelper } from '../utils/git.js';
+import { resolveConfig } from './config.js';
 import { Package } from './package.js';
 export class Repository extends Package {
     dirname;
-    config;
     monorepo;
     packages;
+    cwd;
     rootPackage;
-    constructor(dirname, config, monorepo, packages) {
+    constructor(dirname, monorepo, packages, 
+    /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
+     *  resolved repository root, possibly several levels up), this is where the user's shell
+     *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
+    cwd = dirname) {
         super(dirname);
         this.dirname = dirname;
-        this.config = config;
         this.monorepo = monorepo;
         this.packages = packages;
+        this.cwd = cwd;
         this.rootPackage = new Package(dirname);
         if (!monorepo)
             this.packages = [this.rootPackage];
+        this._resolveConfigs();
+        this._updateDependencies();
+    }
+    /**
+     * The package whose own directory contains `cwd` (the deepest match, so a package nested
+     * inside another's directory resolves to the innermost one) - or `undefined` when `cwd` *is*
+     * the repository root itself, or isn't inside any known package (e.g. a non-monorepo checkout,
+     * or a stray directory the workspace glob doesn't cover).
+     */
+    get currentPackage() {
+        if (path.resolve(this.cwd) === path.resolve(this.dirname))
+            return undefined;
+        let best;
+        for (const pkg of this.packages) {
+            const rel = path.relative(pkg.dirname, this.cwd);
+            const isSelfOrDescendant = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+            if (isSelfOrDescendant && (!best || pkg.dirname.length > best.dirname.length))
+                best = pkg;
+        }
+        return best;
     }
     getPackages(options) {
-        const result = [...this.packages];
+        let result = [...this.packages];
+        if (options?.scope) {
+            const scopes = Array.isArray(options.scope) ? options.scope : [options.scope];
+            result = result.filter(p => scopes.includes(p.name));
+        }
         if (options?.toposort)
             topoSortPackages(result);
         return result;
@@ -29,6 +57,50 @@ export class Repository extends Package {
     getPackage(name) {
         return this.packages.find(p => p.name === name);
     }
+    /**
+     * Reports each package's git change status. `dirty` (uncommitted local
+     * changes) is always checked first, regardless of `hash` - a file can be
+     * dirty no matter what it's being compared against. Once a package isn't
+     * dirty, the reference point decides the rest: without `hash`, `committed`
+     * means committed but not yet in the upstream branch; with `hash`, `changed`
+     * means it differs from that commit. Otherwise a package is `clean`.
+     */
+    async listStatus(options) {
+        const hash = options?.hash;
+        const git = new GitHelper({ cwd: this.dirname });
+        const packages = this.getPackages();
+        const belongsTo = (p, files) => files.some(f => !path.relative(p.dirname, f).startsWith('..'));
+        const [dirtyFiles, referenceFiles] = await Promise.all([
+            git.listDirtyFiles({ absolute: true }),
+            hash ? git.listChangedSince(hash, { absolute: true }) : git.listCommittedFiles({ absolute: true }),
+        ]);
+        const result = {};
+        for (const p of packages) {
+            if (belongsTo(p, dirtyFiles))
+                result[p.name] = 'dirty';
+            else if (belongsTo(p, referenceFiles))
+                result[p.name] = hash ? 'changed' : 'committed';
+            else
+                result[p.name] = 'clean';
+        }
+        return result;
+    }
+    /**
+     * Resolves the effective rman config for the repository root and every
+     * package, cascading root -> intermediate directories -> package directory,
+     * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
+     */
+    _resolveConfigs() {
+        const cache = new Map();
+        const rootConfig = resolveConfig(this.dirname, this.dirname, cache);
+        this.config = rootConfig;
+        this.rootPackage.config = rootConfig;
+        for (const pkg of this.packages) {
+            if (pkg === this.rootPackage)
+                continue;
+            pkg.config = resolveConfig(this.dirname, pkg.dirname, cache);
+        }
+    }
     _updateDependencies() {
         const deps = {};
         for (const pkg of this.packages) {
@@ -38,7 +110,7 @@ export class Repository extends Package {
                 ...pkg.json.peerDependencies,
                 ...pkg.json.optionalDependencies,
             };
-            const configDeps = this.config.packages?.[pkg.name]?.dependencies;
+            const configDeps = pkg.config.packages?.[pkg.name]?.dependencies;
             if (configDeps) {
                 if (Array.isArray(configDeps))
                     configDeps.forEach(x => (o[x] = o[x] || '*'));
@@ -60,13 +132,16 @@ export class Repository extends Package {
                 return;
             circularCheck.push(pkg.name);
             for (const s of pkg.dependencies) {
-                if (!target.includes(s)) {
+                /** `target` starts out *as* the top-level package's own `dependencies` array, so its
+                 *  direct entries are trivially "already in target" - recursing only when newly-added
+                 *  would mean a direct dependency's own transitive deps never get pulled in. Recurse
+                 *  unconditionally (guarded by circularCheck); only skip re-adding an existing entry,
+                 *  and never let the top-level package end up depending on itself via a cycle. */
+                if (s !== circularCheck[0] && !target.includes(s))
                     target.push(s);
-                    const p = this.getPackage(s);
-                    if (p) {
-                        deepFindDependencies(p, target);
-                    }
-                }
+                const p = this.getPackage(s);
+                if (p)
+                    deepFindDependencies(p, target);
             }
         };
         for (const pkg of this.packages) {
@@ -84,10 +159,7 @@ export class Repository extends Package {
                 const pkgJson = JSON.parse(fs.readFileSync(f, 'utf-8'));
                 if (Array.isArray(pkgJson.workspaces)) {
                     const packages = this._resolvePackages(pkgDirname, pkgJson.workspaces);
-                    const config = this._readConfig(pkgDirname);
-                    const repo = new Repository(pkgDirname, config, true, packages);
-                    repo._updateDependencies();
-                    return repo;
+                    return new Repository(pkgDirname, true, packages, dirname);
                 }
                 /** If we reach to the root of the project */
                 if (fs.existsSync(path.join(pkgDirname, '.git')))
@@ -95,11 +167,7 @@ export class Repository extends Package {
             }
             pkgDirname = path.resolve(pkgDirname, '..');
         }
-        const config = this._readConfig(dirname);
-        const repo = new Repository(dirname, config, false, []);
-        repo._updateDependencies();
-        return repo;
-        // throw new Error('No monorepo project detected');
+        return new Repository(dirname, false, [], dirname);
     }
     static _resolvePackages(dirname, patterns) {
         const packages = [];
@@ -118,29 +186,6 @@ export class Repository extends Package {
         }
         return packages;
     }
-    static _readConfig(dirname) {
-        const result = {};
-        const f = path.resolve(dirname, 'package.json');
-        let pkgJson;
-        if (fs.existsSync(f)) {
-            pkgJson = JSON.parse(fs.readFileSync(f, 'utf-8'));
-        }
-        if (pkgJson && typeof pkgJson.rman === 'object')
-            merge(result, pkgJson.rman, { deep: true });
-        let filename = path.resolve(dirname, '.rman.yml');
-        if (fs.existsSync(filename)) {
-            const obj = yaml.load(fs.readFileSync(filename, 'utf-8'));
-            if (obj && typeof obj === 'object')
-                merge(result, obj, { deep: true });
-        }
-        filename = path.resolve(dirname, '.rmanrc');
-        if (fs.existsSync(filename)) {
-            const obj = JSON.parse(fs.readFileSync(filename, 'utf-8'));
-            if (obj && typeof obj === 'object')
-                merge(result, obj, { deep: true });
-        }
-        return result;
-    }
 }
 function topoSortPackages(packages) {
     packages.sort((a, b) => {

package/index.d.ts

@@ -1 +1,17 @@
-export * from './core/repository.js';
+/**
+ * Programmatic API - the same logic the CLI commands run, importable directly without going
+ * through yargs/argv. Each domain's logic lives in a `<Name>` namespace under `./services/*.ts`
+ * (e.g. `ChangelogService`, `CiService`, `CleanService`, `ListService`, `RunService`,
+ * `SystemInfo`, `VersionService`), re-exported here via `./services.js`. Purpose-specific functions, not one
+ * generic `run`/`get` per domain (see e.g. `SystemInfo.getSystemInfo`/`getRepositoryInfo`, kept
+ * separate since they're genuinely independent capabilities, not just steps of one operation) -
+ * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
+ * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ */
+export { Package } from './core/package.js';
+export { Repository } from './core/repository.js';
+export * from './services.js';
+export type { DetectChangeHashOptions } from './utils/change-hash.js';
+export { detectChangeHash } from './utils/change-hash.js';
+export type { LogLevel } from './utils/logger.js';
+export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';

package/index.js

@@ -1 +1,15 @@
-export * from './core/repository.js';
+/**
+ * Programmatic API - the same logic the CLI commands run, importable directly without going
+ * through yargs/argv. Each domain's logic lives in a `<Name>` namespace under `./services/*.ts`
+ * (e.g. `ChangelogService`, `CiService`, `CleanService`, `ListService`, `RunService`,
+ * `SystemInfo`, `VersionService`), re-exported here via `./services.js`. Purpose-specific functions, not one
+ * generic `run`/`get` per domain (see e.g. `SystemInfo.getSystemInfo`/`getRepositoryInfo`, kept
+ * separate since they're genuinely independent capabilities, not just steps of one operation) -
+ * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
+ * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ */
+export { Package } from './core/package.js';
+export { Repository } from './core/repository.js';
+export * from './services.js';
+export { detectChangeHash } from './utils/change-hash.js';
+export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "0.38.0",
+  "version": "1.0.1",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
     "@netlify/parse-npm-script": "^0.1.2",
     "ansi-colors": "^4.1.3",
-    "easy-table": "^1.2.0",
     "cross-dirname": "^0.1.0",
+    "easy-table": "^1.2.0",
     "envinfo": "^7.21.0",
     "fast-glob": "^3.3.3",
+    "fast-tokenizer": "^1.10.0",
     "ini": "^7.0.0",
     "is-ci": "^4.1.0",
     "js-yaml": "^5.4.1",
+    "micromatch": "^4.0.8",
     "npmlog": "^7.0.1",
     "power-tasks": "^1.14.2",
     "putil-merge": "^3.13.0",
@@ -55,5 +57,6 @@
     "repository",
     "build",
     "lerna"
-  ]
+  ],
+  "packageManager": "yarn@3.4.1+sha512.a333bf9c2557d71f5ba87dd1446cde24bb9c35301ec29dd2baba577b3f9d1ab61348b66a1324de9088c40a996c5b9203794da8bf14cab9fae6a6eccc00cb8078"
 }

package/services/changelog.service.d.ts

@@ -0,0 +1,99 @@
+import type { Package } from '../core/package.js';
+import type { Repository } from '../core/repository.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace ChangelogService {
+    /** Injectable dependencies shared by `getEntries`/`generate` - currently just the npm registry lookup
+     *  `detectChangeHash` otherwise makes for itself; overridable so tests (and advanced callers)
+     *  aren't forced through a real network call. */
+    interface Deps {
+        npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
+    }
+    interface Options extends PackageFilterOptions {
+        /** Generate the changelog since this commit/hash - applied the same way to every package.
+         *  Default (also `"npm"` explicitly): auto-detect it per package instead, from that package's
+         *  currently-published npm version (see `detectChangeHash`); a package this can't be resolved
+         *  for (unpublished, no network, no matching tag) falls back to its own commits not yet
+         *  pushed to the current branch's upstream (same reference point `--changed`/
+         *  `--changed-since` use). */
+        from?: string;
+        /** Generate for the whole repository even when the current directory is inside a single
+         *  package (which otherwise scopes it to just that package) - see `Repository.currentPackage`. */
+        root?: boolean;
+        /** Where a package's changelog file lives, relative to *that package's own* directory -
+         *  default `'CHANGELOG.md'`. Applies the same way to every package; for a package that wants
+         *  its own filename instead, use `.rmanrc changelog.filePath` (cascaded, per-package
+         *  overridable) rather than this option - see `resolveFilePath`. Consulted even without
+         *  `write`: when auto-detecting, if this file already exists its own last-modifying commit
+         *  also lower-bounds the boundary, so a stale file (last updated for an older version than
+         *  what's actually published) doesn't get changes silently skipped over - see
+         *  `detectChangeHash`'s `catchUpFile`. */
+        filePath?: string;
+    }
+    /** One package's (root included) generated changelog entry - what `getEntries`/`generate`
+     *  return. */
+    interface Entry {
+        package: Package;
+        /** Display name for this entry's heading - `"<repo dir name> repository"` for the root
+         *  package, its own name otherwise (see `getEntries`'s doc comment on `{{package}}`). */
+        label: string;
+        /** Resolved from git tags, not package.json - see `resolveVersion`. */
+        version: string;
+        features: string[];
+        fixes: string[];
+        other: string[];
+        /** The fully rendered entry, via `.rmanrc changelog.template` (or the built-in default). */
+        content: string;
+        /** Where this entry would be (or, with `options.write`, was) written, relative to the
+         *  package's own directory - see `GetOptions.filePath`. */
+        filePath: string;
+    }
+    /**
+     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
+     * set - prepends `entry.content` into that package's own changelog file (see `Entry.filePath`).
+     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
+     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
+     * the CLI command - printing what happened is the command's job.
+     */
+    function generateToFile(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    /**
+     * Computes a changelog entry per package (root included) from real commits only - either
+     * everything since a given `--from <hash>` (applied the same way to every package), or, by
+     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
+     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
+     *
+     * A commit is attributed to every package its files fall under (root included, for anything
+     * outside every package) - unless it's broad enough to count as a repo-wide change (see
+     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
+     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
+     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
+     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
+     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
+     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
+     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
+     * `VERSION_BUMP_PATTERN`.
+     *
+     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
+     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
+     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
+     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
+     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
+     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
+     * only have their commits fetched once, not once per package.
+     *
+     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
+     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
+     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
+     * (their bullet lists alone, for templates that want their own headings/order) - see
+     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
+     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
+     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
+     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
+     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
+     * changelog.tagPattern`.
+     *
+     * Run from inside a single package's own directory, it only covers that package unless
+     * `options.root` says otherwise (see `Repository.currentPackage`).
+     */
+    function getEntries(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+}