rman 2.12.0 → 2.14.0

package/core/interfaces/dependency-updater.d.ts

@@ -0,0 +1,114 @@
+import type { RmanApplication } from '../application.js';
+import type { Package } from '../classes/package.js';
+import type { Repository } from '../classes/repository.js';
+/**
+ * **How one technology answers "are this package's dependencies current, and what may they move
+ * to"** - the half of `rman deps` that is an ecosystem's.
+ *
+ * The command owns the repository's half: which packages are asked, printing the plan, `--json`,
+ * writing only under `--upgrade`, and undoing the writes when `verify` refuses them.
+ */
+export interface DependencyUpdater {
+    /** What each dependency of `packages` would move to - never writes. */
+    getPlan(ctx: DependencyUpdater.Context, packages: readonly Package[]): Promise<DependencyUpdater.Entry[]>;
+    /** Writes every `'update'` entry of `plan` to its manifest, and returns how to take that back. */
+    applyPlan(ctx: DependencyUpdater.Context, plan: readonly DependencyUpdater.Entry[]): Promise<DependencyUpdater.Applied>;
+    /**
+     * Asks the ecosystem's own resolver whether the manifests as they now stand can be installed,
+     * once `applyPlan` has written them. Returns why not, or `undefined` when they can.
+     *
+     * Omit it when the ecosystem has no resolver to ask; the plan's own checks then stand alone.
+     */
+    verify?(ctx: DependencyUpdater.Context, packages: readonly Package[]): Promise<string | undefined>;
+}
+export declare namespace DependencyUpdater {
+    /** What one call is handed. */
+    interface Context {
+        readonly app: RmanApplication;
+        readonly repository: Repository;
+        readonly options: Options;
+    }
+    /** The run's own settings, read off the command line. A package's `.rmanrc "deps"` block supplies
+     *  the rest - see `settingsFor`. */
+    interface Options {
+        /** Only the dependencies whose names match one of these globs. */
+        names?: string[];
+        /** Overrides every package's `deps.target`. */
+        target?: string;
+        /** Added to every package's `deps.reject`. */
+        reject?: string[];
+        /** Overrides every package's `deps.minAge`. */
+        minAge?: number;
+        /** How many registry lookups run at once. */
+        concurrency: number;
+        /** Reported as each dependency name's registry lookup finishes. */
+        onProgress?(done: number, total: number): void;
+    }
+    /** One package's settings, once the command line has been laid over its config. */
+    interface Settings {
+        /** The largest move allowed, as one of the package's version scheme's `bumpNames` - `minor`
+         *  keeps every dependency inside its major. */
+        target: string;
+        /** `deps.targets`: a dependency-name glob, and the largest move for the names it matches -
+         *  ahead of `target`. Empty when `--target` was given, which overrides both. */
+        targets: Record<string, string>;
+        reject: string[];
+        minAge: number;
+        /** The dependency kinds to look at, in the ecosystem's own words - `undefined` is every one. */
+        types?: string[];
+    }
+    /**
+     * One dependency of one package.
+     *
+     * - `'update'`: `target` is the new range; `reason` says why it is lower than `latest`, if it is.
+     * - `'held'`: a newer version exists and is allowed, but another dependency's rule refuses it -
+     *   `reason` names that rule.
+     * - `'skipped'`: a newer version exists, and the package's own settings leave it out - a major
+     *   under `target: minor`, or one younger than `minAge`. `reason` says which.
+     * - `'up-to-date'`: nothing newer exists.
+     * - `'error'`: the registry gave no answer.
+     */
+    interface Entry {
+        package: Package;
+        /** The dependency's name. */
+        name: string;
+        /** Where the package declares it, in the ecosystem's own words - `devDependencies`. */
+        types: string[];
+        /** The range as the manifest declares it. */
+        current: string;
+        status: 'update' | 'held' | 'skipped' | 'up-to-date' | 'error';
+        /** The range it is rewritten to, on an `'update'`. */
+        target?: string;
+        /** The newest version the package's own settings allow, before any other dependency's rule. */
+        latest?: string;
+        /** The newest version there is, whatever the settings say - what a reader compares against to
+         *  see what was left behind. */
+        available?: string;
+        /** How far `target` moves, in the version scheme's own words - `major`. */
+        bump?: string;
+        reason?: string;
+    }
+    /** What `applyPlan` wrote. */
+    interface Applied {
+        /** Every file it changed, absolute. */
+        files: string[];
+        /** Puts every one of them back as it was. */
+        restore(): void;
+    }
+    /**
+     * Every move but the largest - `minor` under semver. The largest is the one a scheme reserves for a
+     * break, and taking a break is a decision a person makes, not a default.
+     */
+    function defaultTarget(bumps: readonly string[]): string;
+    /**
+     * The largest move `settings` allow for the dependency `name`, and the key that said so - the
+     * **last** `deps.targets` glob matching it, else `deps.target`.
+     */
+    function targetFor(settings: Settings, name: string): {
+        size: string;
+        from: string;
+    };
+    /** The settings `pkg` is planned with: `options` from the command line over its `.rmanrc "deps"`,
+     *  and the defaults under both. */
+    function settingsFor(pkg: Package, options: Options): Settings;
+}

package/core/interfaces/dependency-updater.js

@@ -0,0 +1,61 @@
+import micromatch from 'micromatch';
+export var DependencyUpdater;
+(function (DependencyUpdater) {
+    /**
+     * Every move but the largest - `minor` under semver. The largest is the one a scheme reserves for a
+     * break, and taking a break is a decision a person makes, not a default.
+     */
+    /* **It was `latest` - every move - and that was the wrong default**, measured the moment it ran:
+     * a `^5.3.0` came back as `^7.0.2`. The values are the scheme's own `bumpNames` rather than a list
+     * written here, for the reason `version` gives: `patch`/`minor`/`major` are semver's words, and a
+     * four-part scheme would offer four. */
+    function defaultTarget(bumps) {
+        return bumps[Math.max(0, bumps.length - 2)];
+    }
+    DependencyUpdater.defaultTarget = defaultTarget;
+    /**
+     * The largest move `settings` allow for the dependency `name`, and the key that said so - the
+     * **last** `deps.targets` glob matching it, else `deps.target`.
+     */
+    /* Last rather than first, because that is how two `"[selector]"` blocks layer: what is written
+     * later wins. */
+    function targetFor(settings, name) {
+        let found;
+        for (const [glob, size] of Object.entries(settings.targets)) {
+            if (micromatch.isMatch(name, glob))
+                found = { size, from: `deps.targets["${glob}"]` };
+        }
+        return found ?? { size: settings.target, from: 'deps.target' };
+    }
+    DependencyUpdater.targetFor = targetFor;
+    /** The settings `pkg` is planned with: `options` from the command line over its `.rmanrc "deps"`,
+     *  and the defaults under both. */
+    function settingsFor(pkg, options) {
+        const config = pkg.config.deps ?? {};
+        const bumps = pkg.versionScheme.bumpNames;
+        const target = options.target ?? config.target ?? defaultTarget(bumps);
+        if (!bumps.includes(target)) {
+            throw new Error(`Invalid "deps.target" for "${pkg.name}": "${target}" (expected one of: ${bumps.join(', ')}, ` +
+                `the "${pkg.versionScheme.name}" scheme's own sizes)`);
+        }
+        const targets = options.target ? {} : { ...(config.targets ?? {}) };
+        for (const [glob, size] of Object.entries(targets)) {
+            if (!bumps.includes(size)) {
+                throw new Error(`Invalid "deps.targets" entry "${glob}" for "${pkg.name}": "${size}" (expected one of: ${bumps.join(', ')})`);
+            }
+        }
+        return {
+            target,
+            targets,
+            reject: [...toList(config.reject), ...(options.reject ?? [])],
+            minAge: options.minAge ?? config.minAge ?? 0,
+            types: config.types?.length ? [...config.types] : undefined,
+        };
+    }
+    DependencyUpdater.settingsFor = settingsFor;
+})(DependencyUpdater || (DependencyUpdater = {}));
+function toList(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? [...value] : [value];
+}

package/core/interfaces/plugin.d.ts

@@ -4,6 +4,7 @@ import type { BinPath } from '../../utils/bin-path.js';
 import type { RmanApplication } from '../application.js';
 import type { Repository } from '../classes/repository.js';
 import type { Workspace } from '../classes/workspace.js';
+import type { DependencyUpdater } from './dependency-updater.js';
 import type { ManifestProvider } from './manifest.js';
 /**
  * **One technology, as a whole** - Node, Cargo, Maven. Everything rman needs in order to treat a
@@ -75,6 +76,9 @@ export interface Platform {
     /** How this technology's releases are planned - where a package's change boundary comes from
      *  when it has no release tag, and how far into its group a bump reaches. */
     versionPlanner?: VersionPlanService;
+    /** How this technology's dependencies are checked against their registry and moved forward -
+     *  what `rman deps` asks. Absent, `deps` leaves this technology's packages alone. */
+    dependencyUpdater?: DependencyUpdater;
 }
 /**
  * **A plugin is whatever a package contributes; a platform is one of the things it can contribute.**

package/core/interfaces/publish-target.d.ts

@@ -69,6 +69,11 @@ export interface PublishTarget {
      * only what is its own, such as npm's `private`.
      */
     skipReason?(pkg: Package): string | undefined;
+    /**
+     * The name `rman list` shows for this package when it says more than `name` does - npm's is the
+     * registry's host, `npm.pkg.github.com` for GitHub Packages. `undefined` shows `name`.
+     */
+    labelFor?(pkg: Package): string | undefined;
     /** What this target *would* do - never publishes. Called even under `--dry-run`, which is the
      *  whole point of the split. */
     getPlan(ctx: PublishTarget.Context): Promise<PublishTarget.Entry[]>;

package/index.d.ts

@@ -65,6 +65,8 @@ export { Manifest } from './core/interfaces/manifest.js';
 export { Registry } from './core/classes/registry.js';
 export { Repository } from './core/classes/repository.js';
 export { Service, type ServiceFactory, type ServiceMap } from './core/classes/service.js';
+/** The `deps` seam: how a technology checks its dependencies against a registry and moves them. */
+export { DependencyUpdater } from './core/interfaces/dependency-updater.js';
 export { declaredTargets, type PublishTarget, shipsTo, skipReasonFor, targetsOf, unknownTargets, } from './core/interfaces/publish-target.js';
 export type { RunConditionFn, RunStepContext, RunStepFn, RunStepObject, RunStepValue, } from './core/interfaces/run-step.js';
 /**

package/index.js

@@ -71,6 +71,8 @@ export { Manifest } from './core/interfaces/manifest.js';
 export { Registry } from './core/classes/registry.js';
 export { Repository } from './core/classes/repository.js';
 export { Service } from './core/classes/service.js';
+/** The `deps` seam: how a technology checks its dependencies against a registry and moves them. */
+export { DependencyUpdater } from './core/interfaces/dependency-updater.js';
 export { declaredTargets, shipsTo, skipReasonFor, targetsOf, unknownTargets, } from './core/interfaces/publish-target.js';
 export { basePlatform, definePlatform, definePlugin, isPlatform, } from './core/interfaces/plugin.js';
 /** The numbering seam. `VersionScheme` is abstract - `highestVersion`/`highestBump`/`smallestBump`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {

package/services/changelog.service.d.ts

@@ -1,6 +1,7 @@
 import type { Package } from '../core/classes/package.js';
 import type { Repository } from '../core/classes/repository.js';
 import { Service } from '../core/classes/service.js';
+import { GitHelper } from '../utils/git.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 /**
  * A service class - see `ListService` for the shape and `Service` for the three measured
@@ -55,6 +56,12 @@ export declare class ChangelogService extends Service {
      * `options.fromRoot` says otherwise (see `Repository.currentPackage`).
      */
     getEntries(options?: ChangelogService.Options): Promise<ChangelogService.Entry[]>;
+    /**
+     * Where each member package's directory was over time, newest first - `since` is the commit that
+     * moved it there, absent for the oldest. A package that never moved has one entry, its own
+     * directory. Read from the moves of the package's manifest (`GitHelper.moveHistory`).
+     */
+    protected packageHomes(git: GitHelper): Promise<PackageHomes>;
 }
 /**
  * What one changelog file is about - `.rmanrc changelog.groupBy`, `'package'` when nothing says.
@@ -68,6 +75,13 @@ export declare class ChangelogService extends Service {
  * per package - the same entry prepended once per member otherwise.
  */
 export declare function changelogGroupBy(repository: Repository, options?: ChangelogService.Options): 'package' | 'group';
+/** Where a package's directory was over time, newest first - see `ChangelogService.packageHomes`. */
+type PackageHomes = Map<Package, Home[]>;
+interface Home {
+    dir: string;
+    /** The commit that moved the package here; absent for its first directory. */
+    since?: string;
+}
 export declare namespace ChangelogService {
     interface Options extends PackageFilterOptions {
         /** Generate the changelog since this commit/hash - applied the same way to every package.
@@ -212,3 +226,4 @@ declare module '../core/classes/service.js' {
         changelog: ChangelogService;
     }
 }
+export {};

package/services/changelog.service.js

@@ -154,6 +154,9 @@ export class ChangelogService extends Service {
             progress?.step(group.label, 'commits');
             return listCommitsCached(from, group.label);
         }));
+        /** Where each package's directory was over time - so a commit made before a package moved is
+         *  still its own. See `packageHomes`. */
+        const homes = await this.packageHomes(git);
         const entries = [];
         for (let i = 0; i < groups.length; i++) {
             const group = groups[i];
@@ -177,6 +180,7 @@ export class ChangelogService extends Service {
              * falls inside the range and there is exactly one segment - which is what `version
              * --changelog` and `github-release` see too, since both pass an explicit boundary.
              */
+            const dirsAt = homesAt(homes, commitsByTarget[i]);
             const floor = await resolveStartingPoint(git, pkg, options);
             const floorIndex = floor?.sha ? commitsByTarget[i].findIndex(c => c.sha === floor.sha) : -1;
             const withUnreleased = resolveUnreleased(pkg, options);
@@ -189,7 +193,7 @@ export class ChangelogService extends Service {
                     continue;
                 /** A commit belongs to a group when it belongs to **any** of its members - one line for a
                  *  commit touching two of them, which is the whole reason a group shares a file. */
-                const ownCommits = dropVersionBumps(segment.commits).filter(c => [...ownersOf(repository, c)].some(owner => group.members.has(owner)));
+                const ownCommits = dropVersionBumps(segment.commits).filter(c => [...ownersOf(repository, c, dirsAt(c))].some(owner => group.members.has(owner)));
                 if (!ownCommits.length)
                     continue;
                 const sections = groupCommits(ownCommits, ignoreTypesConfig(pkg), titles, order, withCommitHash(pkg, options));
@@ -219,6 +223,33 @@ export class ChangelogService extends Service {
         }
         return entries;
     }
+    /**
+     * Where each member package's directory was over time, newest first - `since` is the commit that
+     * moved it there, absent for the oldest. A package that never moved has one entry, its own
+     * directory. Read from the moves of the package's manifest (`GitHelper.moveHistory`).
+     */
+    /* **Why a commit cannot simply be matched against today's directories**: measured on
+     * `panates/syncbridge`, whose last commit moved every package under `packages/<scope>/`. Every
+     * earlier commit touched the old paths, which no package sits at any more, so all of them were
+     * attributed to the root - `changelog --write` under `groupBy: package` wrote one root file and
+     * nothing for any package, while git still held 259 commits of hl7's and 283 of iomt's.
+     *
+     * **The manifest, not the files**: one file per package says where its directory was, so this is
+     * one `git log --follow` per package, run at once - 40ms each there, 120ms on `panates/sqb`. A
+     * single-package repository has nothing to follow: its package is the root, which does not move. */
+    async packageHomes(git) {
+        const homes = new Map();
+        const packages = this.repository.monorepo ? this.repository.packages : [];
+        await Promise.all(packages.map(async (pkg) => {
+            if (!pkg.manifestFileName)
+                return;
+            const moves = await git.moveHistory(pkg.manifestFileName);
+            const periods = [{ dir: pkg.dirname, since: moves[0]?.sha }];
+            moves.forEach((move, k) => periods.push({ dir: path.dirname(move.from), since: moves[k + 1]?.sha }));
+            homes.set(pkg, periods);
+        }));
+        return homes;
+    }
 }
 /**
  * What one changelog file is about - `.rmanrc changelog.groupBy`, `'package'` when nothing says.
@@ -856,16 +887,45 @@ async function splitByRelease(git, pkg, commits) {
  *  fallback for anything outside every package (e.g. root-level config files). Mirrors
  *  `Repository.currentPackage`'s longest-prefix logic, but always resolves to *something*
  *  (root), rather than `undefined`, since every file belongs to some changelog. */
-function owningPackage(repository, file) {
+function owningPackage(repository, file, dirOf) {
     let best = repository.rootPackage;
+    let bestDir = repository.rootPackage.dirname;
     for (const pkg of repository.packages) {
-        const rel = path.relative(pkg.dirname, file);
+        const dir = dirOf(pkg);
+        const rel = path.relative(dir, file);
         const isSelfOrDescendant = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-        if (isSelfOrDescendant && pkg.dirname.length > best.dirname.length)
+        if (isSelfOrDescendant && dir.length > bestDir.length) {
             best = pkg;
+            bestDir = dir;
+        }
     }
     return best;
 }
+/**
+ * For one fetched commit list, the function that answers where each package's directory was when a
+ * given commit was made.
+ */
+/* **Ordered by position in the list, not by asking git**: the list is oldest first and runs to HEAD,
+ * so a move inside it is compared by index, and a move *not* in it happened at or before the range's
+ * boundary - every commit in the range is after it. One `merge-base --is-ancestor` per commit and
+ * package would be the exact answer and costs a process each; this costs a Map. */
+function homesAt(homes, commits) {
+    const index = new Map(commits.map((c, i) => [c.sha, i]));
+    return commit => pkg => {
+        const periods = homes.get(pkg);
+        if (!periods)
+            return pkg.dirname;
+        const at = index.get(commit.sha) ?? commits.length;
+        for (const period of periods) {
+            if (!period.since)
+                return period.dir;
+            const movedAt = index.get(period.since);
+            if (movedAt === undefined || movedAt <= at)
+                return period.dir;
+        }
+        return periods[periods.length - 1].dir;
+    };
+}
 /** A commit touching more than this fraction of all packages (a repo-wide relicense, a doc
  *  update stamped into every package's README, ...) is treated as a repo-wide change rather than
  *  attributed to each of them - see `ownersOf`. Without this, one such commit would show up
@@ -883,10 +943,10 @@ const BROAD_COMMIT_MIN_PACKAGES = 3;
  * doc pass across every package, ...), not something that belongs in each package's own release
  * notes individually - it's attributed to the root alone.
  */
-function ownersOf(repository, commit) {
+function ownersOf(repository, commit, dirOf) {
     const owners = new Set();
     for (const f of commit.files)
-        owners.add(owningPackage(repository, f));
+        owners.add(owningPackage(repository, f, dirOf));
     const totalPackages = repository.packages.length;
     const nonRootOwners = [...owners].filter(p => p !== repository.rootPackage).length;
     if (totalPackages > 0 &&

package/services/list.service.d.ts

@@ -63,6 +63,15 @@ export declare namespace ListService {
          * `--toposort` - which reorders the rows and leaves the nesting where it is.
          */
         depth: number;
+        /**
+         * Which release group the package versions with - `.rmanrc group`, the key `version` batches its
+         * plan by: `default` for the implicit repo-wide group, `named:<name>` for a named one,
+         * `solo:<package>` for `group: false`, and `__root__` for a monorepo's root, which belongs to
+         * none. The same spelling `version --json` reports.
+         */
+        groupKey: string;
+        /** `groupKey`'s name - the group's own name, `default`, the package's for a solo one, `root`. */
+        group: string;
         /** Whether this row *is* the root package - present only when `includeRoot` asked for it, or in
          *  a single-package repository where the root is the one member. */
         isRoot: boolean;
@@ -81,6 +90,10 @@ export declare namespace ListService {
          *  registry, so `{}` means "a candidate", not "will publish": whether the version is already out
          *  there is `publish --dry-run`'s answer. */
         skippedTargets: Record<PublishTargetName, string>;
+        /** What the table shows in place of a target's name, where the target says more for this
+         *  package - npm's registry host when `publishConfig.registry` names one other than npm's own
+         *  (`{ npm: 'npm.pkg.github.com' }`). A label only: `publishTargets` and `--target` keep the name. */
+        targetLabels: Record<PublishTargetName, string>;
         /** Present only when `"docker"` is one of `publishTargets` and `publish.docker` is configured -
          *  the raw `.rmanrc` config, unresolved (no namespace prefixing - see `DockerPublishService`). */
         docker?: DockerPublishOptions;

package/services/list.service.js

@@ -2,6 +2,7 @@ import path from 'path';
 import { Service } from '../core/classes/service.js';
 import { skipReasonFor, targetsOf } from '../core/interfaces/publish-target.js';
 import { filterPackages } from '../utils/package-filter.js';
+import { groupKeyOf, isNamedGroupKey, isSoloGroupKey, ROOT_GROUP_KEY } from '../utils/version-group.js';
 /**
  * **A class, and the shape every service follows now.**
  *
@@ -36,13 +37,21 @@ export class ListService extends Service {
             /** **A monorepo's root ships nowhere**: `publish` never makes it a candidate
              *  (`repository.getPackages()` leaves it out), so listing the target a root *would* claim
              *  says something no command does. */
-            const targets = p === repository.rootPackage && repository.monorepo ? [] : targetsOf(this.app, p);
+            const monorepoRoot = p === repository.rootPackage && repository.monorepo;
+            const targets = monorepoRoot ? [] : targetsOf(this.app, p);
+            /** The root's own key, as in `version`'s plan: a monorepo's root is never a group member - its
+             *  number is the repository's identity. */
+            const groupKey = monorepoRoot ? ROOT_GROUP_KEY : groupKeyOf(p);
             const publishTargets = targets.map(t => t.name);
             const skippedTargets = {};
+            const targetLabels = {};
             for (const target of targets) {
                 const reason = skipReasonFor(p, target);
                 if (reason)
                     skippedTargets[target.name] = reason;
+                const label = target.labelFor?.(p);
+                if (label && label !== target.name)
+                    targetLabels[target.name] = label;
             }
             return {
                 name: p.name,
@@ -50,6 +59,8 @@ export class ListService extends Service {
                 version: p.version,
                 platform: p.provider,
                 depth: depthOf(p),
+                groupKey,
+                group: groupNameOf(groupKey),
                 isRoot: p === repository.rootPackage,
                 location: path.relative(repository.dirname, p.dirname) || '.',
                 private: p.isPrivate,
@@ -57,6 +68,7 @@ export class ListService extends Service {
                 dependencies: p.dependencies.map(d => d.name),
                 publishTargets: [...publishTargets],
                 skippedTargets,
+                targetLabels,
                 docker: publishTargets.includes('docker') ? p.config.publish?.docker : undefined,
             };
         };
@@ -90,3 +102,13 @@ function depthOf(pkg) {
         depth++;
     return depth;
 }
+/** The name behind a group key - the same reading `VersionPlanService.groupLabel` makes. */
+function groupNameOf(key) {
+    if (key === ROOT_GROUP_KEY)
+        return 'root';
+    if (isNamedGroupKey(key))
+        return key.slice('named:'.length);
+    if (isSoloGroupKey(key))
+        return key.slice('solo:'.length);
+    return key;
+}

package/utils/git.d.ts

@@ -12,6 +12,8 @@ export interface CommitInfo {
 }
 export declare class GitHelper {
     cwd: string;
+    /** `movedShare`'s per-commit rename lists. */
+    private _renames;
     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. */
@@ -67,6 +69,21 @@ export declare class GitHelper {
      *  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>;
+    /**
+     * Every time `file` was **moved together with its directory**, newest first - `{ sha, from, to }`,
+     * absolute paths of the file, and the commit that moved it. Empty for a file that never moved, or
+     * one git has no history of. Meant for a package manifest: where it went, its package went.
+     */
+    moveHistory(file: string): Promise<{
+        sha: string;
+        from: string;
+        to: string;
+    }[]>;
+    /**
+     * Of the files `fromDir` held just before `sha`, the share `sha` renamed into `toDir` - `0` to `1`.
+     * Both directories relative to `cwd`, in git's `/` form.
+     */
+    movedShare(sha: string, fromDir: string, toDir: string): Promise<number>;
     /** 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>;

package/utils/git.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 export class GitHelper {
     cwd;
+    /** `movedShare`'s per-commit rename lists. */
+    _renames = new Map();
     constructor(options) {
         this.cwd = options?.cwd || process.cwd();
     }
@@ -203,6 +205,88 @@ export class GitHelper {
             return undefined;
         }
     }
+    /**
+     * Every time `file` was **moved together with its directory**, newest first - `{ sha, from, to }`,
+     * absolute paths of the file, and the commit that moved it. Empty for a file that never moved, or
+     * one git has no history of. Meant for a package manifest: where it went, its package went.
+     */
+    /* **Renames only, and the walk stops at the first copy.** `git log --follow` also crosses a *copy*
+     * (`C`), and for a manifest that is the dangerous case: package manifests resemble one another, so a
+     * new package created from an old one's `package.json` is followed into that package's history.
+     * Measured on `panates/syncbridge`: `@syncbridge/hl7`'s manifest came back as `C054` from
+     * `packages/common/package.json` - a different package, `@panates-prv/syncbridge-common`, which was
+     * not even deleted in that commit - and following it would have handed hl7 137 commits of another
+     * package's history. A rename (`R`) means the old file is gone, which a copy does not.
+     *
+     * **And a rename counts only where the directory went too** - more than half of the files the old
+     * directory held landing in the new one (`movedShare`). Two manifests are similar enough to pair
+     * when a directory is *split*: in the same repository `packages/builtins` was broken into ten
+     * packages in one commit, git paired its `package.json` with `packages-ext/serialport`'s at
+     * `R052`, and serialport had received 3 of its 43 files. The old directory belongs to no one of
+     * them, so the walk stops there and its history stays the root's - unattributed rather than
+     * guessed. A real move clears this easily: `iomt-connectors` took 101 of its 110 files. */
+    async moveHistory(file) {
+        let stdout;
+        try {
+            ({ stdout } = await execFileAsync('git', ['log', '--follow', '--format=%x00%H', '--name-status', '--', path.relative(this.cwd, file)], { cwd: this.cwd, maxBuffer: 64 * 1024 * 1024 }));
+        }
+        catch {
+            return [];
+        }
+        const moves = [];
+        for (const entry of stdout.split('\0').filter(Boolean)) {
+            const [sha, ...lines] = entry.split(/\r?\n/).filter(Boolean);
+            const [status = '', from, to] = (lines[0] ?? '').split('\t');
+            if (status.startsWith('R') && from && to) {
+                const fromDir = path.posix.dirname(from);
+                const toDir = path.posix.dirname(to);
+                /** Renamed within its own directory: the package did not move. */
+                if (fromDir === toDir)
+                    continue;
+                if ((await this.movedShare(sha.trim(), fromDir, toDir)) <= 0.5)
+                    break;
+                moves.push({ sha: sha.trim(), from: path.join(this.cwd, from), to: path.join(this.cwd, to) });
+            }
+            else if (status.startsWith('C') || status === 'A')
+                break;
+        }
+        return moves;
+    }
+    /**
+     * Of the files `fromDir` held just before `sha`, the share `sha` renamed into `toDir` - `0` to `1`.
+     * Both directories relative to `cwd`, in git's `/` form.
+     */
+    /* The rename list is cached per commit: a commit that moves every package is asked about once per
+     * package, and it is one `git show` however many ask. */
+    async movedShare(sha, fromDir, toDir) {
+        let renames = this._renames.get(sha);
+        if (!renames) {
+            renames = execFileAsync('git', ['show', '-M', '--name-status', '--format=', sha], {
+                cwd: this.cwd,
+                maxBuffer: 64 * 1024 * 1024,
+            }).then(({ stdout }) => stdout
+                .split(/\r?\n/)
+                .map(line => line.split('\t'))
+                .filter(([status, from, to]) => status?.startsWith('R') && from && to)
+                .map(([, from, to]) => ({ from, to })), () => []);
+            this._renames.set(sha, renames);
+        }
+        let held;
+        try {
+            const { stdout } = await execFileAsync('git', ['ls-tree', '-r', '--name-only', `${sha}^`, '--', `${fromDir}/`], {
+                cwd: this.cwd,
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            held = stdout.split(/\r?\n/).filter(Boolean);
+        }
+        catch {
+            return 0;
+        }
+        if (!held.length)
+            return 0;
+        const into = (await renames).filter(r => r.from.startsWith(`${fromDir}/`) && r.to.startsWith(`${toDir}/`)).length;
+        return into / held.length;
+    }
     /** The best common ancestor of `a` and `b` - `undefined` if none exists (unrelated histories,
      *  an invalid ref, ...). */
     async mergeBase(a, b) {