@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/identity-gate-rule.js

@@ -0,0 +1,75 @@
+/**
+ * The `identity.gates` rule as data and one pure function (#3862).
+ *
+ * A gate the declaration names under `identity.gates` passes only on an
+ * approval sealed by a signer at base, from the class the gate names when it
+ * names one (#3163, ws-080). chant's `gateAdmissionFrom` (`./identity.ts`)
+ * builds a {@link GateAdmissionRule} from what `scopeSource` reads and judges
+ * every approval with {@link admitApprover}. `@intentius/chant/gate-decision`
+ * builds the same rule from a bare clone at a base commit
+ * (`identityGateAdmissionAt`) and judges with the same function, so a tool
+ * counts approvals as chant's wave gate does.
+ *
+ * The module imports node:crypto through `./trust/gate-seal.ts` and nothing
+ * else: no zod, no ajv, no package loading, so it bundles small.
+ */
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, verifySshSignatureWith } from "./trust/gate-seal.js";
+/** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
+export const CORE_PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"];
+export const CORE_CLASSES = [
+    { name: "human", description: "a principal holding none of the roles of another class", role: null, source: "core" },
+    { name: "agent", description: "a principal holding the agent role, or a write naming an agent session", role: "agent", source: "core" },
+    { name: "runner", description: "a principal holding the runner role, such as a CI job's signing identity", role: "runner", source: "core" },
+    { name: "service", description: "a principal holding the service role", role: "service", source: "core" },
+];
+const normalise = (name) => name.normalize("NFKC").trim().toLowerCase();
+/** Every class `principal`'s role grants put it in, in `classes` order: what `classesOf` in `./principal-classes.ts` answers. */
+export function grantedClasses(classes, roles, principal) {
+    if (principal === null)
+        return [];
+    const name = normalise(principal);
+    return classes.filter((c) => c.role !== null && (roles[c.role] ?? []).some((p) => normalise(p) === name)).map((c) => c.name);
+}
+/**
+ * Why `a` does not count toward the gate, or null when it does. An approval
+ * counts only when its seal verifies for its approver against the signers at
+ * base and, when the rule names a class, the role grants at base put the
+ * approver in it (`human`: in no other class). A class the rule does not
+ * know lets nothing through.
+ */
+export function admitApprover(rule, a) {
+    const { gate, signers } = rule;
+    const want = rule.class;
+    if (want !== null && !rule.classes.some((c) => c.name === want)) {
+        return `identity.gates.${gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no approval can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
+    }
+    if (!signers.active)
+        return `gate ${gate} needs a signed approval, and there is no signers file (${signers.signersPath}) at base to check one against`;
+    const seal = sealRefusal(gate, signers, a);
+    if (seal !== null)
+        return seal;
+    if (want === null)
+        return null;
+    const granted = grantedClasses(rule.classes, rule.roles, a.resolvedBy);
+    const inClass = want === "human" ? granted.length === 0 : granted.includes(want);
+    return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
+}
+/** The seal step, worded as `checkGateSeal` (`./trust/seal.ts`) words it against an active signers file at base. */
+function sealRefusal(gate, signers, a) {
+    const what = `the approval of gate ${a.gate} by ${a.resolvedBy}`;
+    if (a.seal === undefined || a.seal === null)
+        return `the approval by ${a.resolvedBy} is not signed; gate ${gate} needs chant approve --sign`;
+    const seal = a.seal;
+    if (typeof seal !== "object" || Array.isArray(seal) || typeof seal.signer !== "string" || typeof seal.signature !== "string") {
+        return `the seal on ${what} is malformed: it needs signer and signature`;
+    }
+    if (normalise(seal.signer) !== normalise(a.resolvedBy))
+        return `the seal on ${what} is by ${seal.signer}, and its approver is ${a.resolvedBy || "empty"}`;
+    const where = `${signers.signersPath} at base`;
+    const listed = signers.signers.filter((s) => normalise(s.principal) === normalise(a.resolvedBy));
+    if (listed.length === 0)
+        return `${a.resolvedBy} has no key in ${where}, so the seal can't count`;
+    const keys = listed.filter((s) => namespaceAllowed(s.namespaces, GATE_SEAL_NAMESPACE)).map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
+    const r = verifySshSignatureWith(seal.signature, gateSealPayload(a), GATE_SEAL_NAMESPACE, keys);
+    return r.ok ? null : `the seal does not verify for ${a.resolvedBy} against ${where}: ${r.reason}`;
+}

package/dist/workspace/identity.js

@@ -0,0 +1,126 @@
+/**
+ * Who a person-attributed record or gate approval names (#3163, ws-080).
+ *
+ * chant never authenticates a person (ws-052): hud, studio or behold signs a
+ * person in and maps the session to one of the identities below, then passes
+ * it to chant's write commands (`--by`, `--actor`). chant records what it is
+ * given and says which form it is:
+ *
+ * - `signer`: a principal `.chant/allowed_signers` lists at base. A seal made
+ *   with that principal's key (`--sign`) attests it.
+ * - `forge`: a forge identity, `github:<login>`, `gitlab:<login>`, or
+ *   `<forge>@<host>:<login>` (forgejo, gitea, or a self-hosted github or
+ *   gitlab). The surface that signed the person in vouches for it; nothing
+ *   here checks it, and only a seal verified against the signers at base
+ *   attests it. The signers file and the role grants name people this way, so
+ *   one string is the person in the record, the key list and the classes.
+ * - `role`: a principal holding the agent, runner or service role at base, or
+ *   listed by a declared agent session: not a person, and named by a grant an
+ *   admin controls.
+ * - `name`: anything else, such as a hud roster name or `$USER`.
+ *
+ * The declaration's `identity` block, read at base, turns this into rules:
+ * `attribution: "identified"` refuses a `name` on every person-attributed
+ * write, and `gates.<gate>` lets a gate of that name pass only on an approval
+ * sealed by a signer, from a class when it names one.
+ */
+import { admitApprover } from "./identity-gate-rule.js";
+import { classesOf, coreClassRegistry, roleGrants } from "./principal-classes.js";
+import { normalisePrincipal } from "./records.js";
+import { scopeSource } from "./write-scope.js";
+/** The forges a forge identity can name. */
+export const FORGES = ["github", "gitlab", "forgejo", "gitea"];
+/** The host a forge identity means when it names none. Forgejo and gitea have no default: name the host. */
+const DEFAULT_HOST = { github: "github.com", gitlab: "gitlab.com", forgejo: null, gitea: null };
+const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const FORGE_PRINCIPAL = new RegExp(`^(${FORGES.join("|")})(?:@(${LABEL}(?:\\.${LABEL})+))?:([a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9_])?)$`);
+/**
+ * Read `principal` as a forge identity, or null when it is not one. Case and
+ * surrounding space are folded as {@link normalisePrincipal} folds them.
+ */
+export function parseForgeIdentity(principal) {
+    const m = FORGE_PRINCIPAL.exec(normalisePrincipal(principal));
+    if (!m)
+        return null;
+    const forge = m[1];
+    const host = m[2] ?? DEFAULT_HOST[forge];
+    if (host === null)
+        return null;
+    return { forge, host, login: m[3] };
+}
+/** The principal string of a forge identity: `<forge>:<login>` on the forge's default host, else `<forge>@<host>:<login>`. */
+export function forgePrincipal(id) {
+    return id.host === DEFAULT_HOST[id.forge] ? `${id.forge}:${id.login}` : `${id.forge}@${id.host}:${id.login}`;
+}
+const NON_PERSON_CLASSES = new Set(["agent", "runner", "service"]);
+/**
+ * What `principal` is, under the policy and declaration read at base. A
+ * principal the signers file lists is a `signer` even when it is also a
+ * forge identity, since a seal can attest it.
+ */
+export function identify(principal, policy, declaration = null) {
+    const name = normalisePrincipal(principal);
+    const forge = parseForgeIdentity(principal);
+    if (policy.active && policy.signers.some((s) => normalisePrincipal(s.principal) === name))
+        return { principal, form: "signer", forge };
+    if (forge)
+        return { principal, form: "forge", forge };
+    const session = (declaration?.agents ?? []).some((a) => a.principals.some((p) => normalisePrincipal(p) === name));
+    if (session || classesOf(coreClassRegistry(), policy, principal).some((c) => NON_PERSON_CLASSES.has(c)))
+        return { principal, form: "role", forge: null };
+    return { principal, form: "name", forge: null };
+}
+/** Why a write naming a person was refused. Closed. */
+export const IDENTITY_CODES = ["principal-unidentified"];
+export class IdentityError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = "principal-unidentified";
+        this.name = "IdentityError";
+    }
+}
+/**
+ * Refuse a person-attributed write that names someone by a bare name, when
+ * the declaration at base sets `identity.attribution` to `identified`.
+ * `flag` names where the name came from (`--by`, `--actor`). A write in a
+ * declared agent session (`CHANT_AGENT`) names the session, not a person,
+ * and is not judged here. Throws an {@link IdentityError}.
+ */
+export function refuseUnidentified(source, names, flag, opts = {}) {
+    if (source.declaration?.identity?.attribution !== "identified")
+        return;
+    if (opts.agent !== undefined && opts.agent !== null && source.declaration.agents.some((a) => a.name === opts.agent))
+        return;
+    for (const name of names) {
+        if (identify(name, source.policy, source.declaration).form !== "name")
+            continue;
+        throw new IdentityError(`${flag} ${JSON.stringify(name)} names no identity the workspace can check: chant.workspace.json at base sets identity.attribution to identified, so a person is named by a forge identity (github:<login>, gitlab:<login>, or <forge>@<host>:<login>) or by a principal ${source.policy.signersPath} lists at base`);
+    }
+}
+/**
+ * The rule for `gate`, or null when the declaration at base names none. An
+ * approval counts only when its seal verifies for its approver against the
+ * signers at base and, when the rule names a class, the approver's role
+ * grants at base put it in that class. A class no pinned package supplies
+ * lets nothing through. The judge is {@link admitApprover}, which
+ * `@intentius/chant/gate-decision` also judges with (#3862). The policy is
+ * the one at base, never a returned work's copy.
+ */
+export function gateAdmissionFrom(source, gate) {
+    const requirement = source.declaration?.identity?.gates[gate];
+    if (!requirement)
+        return null;
+    const { policy, classes } = source;
+    const rule = { gate, class: requirement.class, signers: policy, roles: roleGrants(policy), classes: classes.all() };
+    return { requirement, refuses: (a) => admitApprover(rule, a) };
+}
+/**
+ * The rule for `gate` in the workspace holding `cwd`, read at base (the
+ * target branch tip), or null when there is no declaration or it names none.
+ * What a run, `chant approve` and `workspace status` ask before counting an
+ * approval. `base` names the commit to read at instead, as an op wave reads
+ * every rule at its `--base` (#3841).
+ */
+export function gateAdmission(cwd, gate, base) {
+    return gateAdmissionFrom(scopeSource(cwd, base), gate);
+}

package/dist/workspace/import.js

@@ -0,0 +1,283 @@
+/**
+ * `chant workspace import`: bring an export back into the workspace it came
+ * from (#2552, #2524 D10, requirements X3 and X5, ws-004, ws-073).
+ *
+ * The source is the export member, or a directory holding a copy of an
+ * export, such as the repository a hosted copy was kept in. Its
+ * `.chant/export.json` names the workspace and the members that went, and the
+ * hash each file had on both sides when it went: the merge base.
+ *
+ * For each file, three hashes decide. A file the copy did not change is left
+ * alone. A file the copy changed is written when the workspace did not
+ * change it since the export. A file both changed differently is a conflict,
+ * and any conflict refuses the whole import, which then writes nothing. The
+ * same holds for removed and added files. Only paths inside the members that
+ * went, and the record directories of a whole export, are written: a copy
+ * that holds anything else is refused, so an import never writes into another
+ * member.
+ *
+ * Host values switch back (X3): the host-bound values the export recorded
+ * are put back in the files the lineage lists, and in the lock. Each lineage
+ * scope merges the same way as a file, with the scope's digest as the base.
+ *
+ * Every write is recorded in `.chant/returns/<id>.json` (./returns.ts). When
+ * the copy is a git repository of its own, each written file also carries the
+ * commit that last changed it there, with the original signature, and the
+ * tree objects that tie that commit to the bytes. Records keep their seals,
+ * since their bytes are copied as they are.
+ *
+ * Last, the export member is written again from the workspace as it now
+ * stands (the default), or removed with its declaration entry (`--remove`).
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { readDeclaration } from "./declaration.js";
+import { EXPORT_MANIFEST, ExportError, exportMember, exportWorkspace, gitTopOf, isLockPath, lineageDigest, listFiles, lockDir, rawDeclaration, readManifestAt, scopedPath, switchHostValues, under, } from "./export.js";
+import { fileHash, LOCK_FILE, parseLock, renderLock } from "./lineage-lock.js";
+import { buildOrigin, originSigners, RETURNS_DIR, writeReturn } from "./returns.js";
+import { workingTree } from "./tree.js";
+/** Paths the copy may hold besides member and record files. */
+function ignoredInCopy(path) {
+    return path === EXPORT_MANIFEST || path === "chant.workspace.json" || path === "chant.workspace.jsonc" || path.startsWith(`${RETURNS_DIR}/`);
+}
+function readOr(abs) {
+    return existsSync(abs) ? readFileSync(abs) : undefined;
+}
+/** Plan the import, and apply it unless `dryRun` or a conflict. Throws an {@link ExportError}. */
+export async function importWorkspace(o) {
+    const root = resolve(o.root);
+    const decl = readDeclaration(workingTree(root));
+    const fromDir = o.from !== undefined ? resolve(o.from) : join(root, exportMember(decl).dir);
+    const manifest = readManifestAt(fromDir);
+    if (!manifest)
+        throw new ExportError(`${fromDir} holds no ${EXPORT_MANIFEST}: it is not an export`);
+    if (manifest.from.workspace !== decl.name) {
+        throw new ExportError(`the export came from workspace ${manifest.from.workspace}, and this one is ${decl.name}`);
+    }
+    const memberDirs = manifest.members.map((name) => {
+        const m = decl.members.find((x) => x.name === name);
+        if (!m)
+            throw new ExportError(`member ${name} went with the export, and this workspace no longer declares it`);
+        return m.dir;
+    });
+    const allowed = [...memberDirs, ...manifest.dirs];
+    const others = decl.members.filter((m) => !manifest.members.includes(m.name) && m.dir !== ".");
+    // The copy's files and locks.
+    const copyFiles = new Map();
+    const copyLocks = new Map();
+    const outside = [];
+    for (const path of listFiles(fromDir)) {
+        if (ignoredInCopy(path))
+            continue;
+        if (path === LOCK_FILE) {
+            copyLocks.set(path, parseLock(readFileSync(join(fromDir, path), "utf-8")));
+            continue;
+        }
+        if (!allowed.some((d) => under(path, d)) || others.some((m) => under(path, m.dir))) {
+            outside.push(path);
+            continue;
+        }
+        if (isLockPath(path))
+            copyLocks.set(path, parseLock(readFileSync(join(fromDir, path), "utf-8")));
+        else
+            copyFiles.set(path, readFileSync(join(fromDir, path)));
+    }
+    // Each scope's digest as the copy holds it, before host values go back.
+    const copyDigests = new Map();
+    for (const [path, lock] of copyLocks)
+        for (const [scope, lineage] of Object.entries(lock.scopes))
+            copyDigests.set(`${path}#${scope}`, lineageDigest(lineage));
+    // Host values back (X3), in the files and in each lock.
+    const exportForm = new Map(copyFiles);
+    const hostValues = new Set();
+    for (const [path, lock] of copyLocks) {
+        for (const [scope, lineage] of Object.entries(lock.scopes)) {
+            const values = manifest.hostValues[`${path}#${scope}`];
+            if (!values)
+                continue;
+            const back = Object.fromEntries(Object.entries(values).map(([n, v]) => [n, { from: v.export, to: v.host }]));
+            for (const p of switchHostValues(lineage, lockDir(path), scope, back, copyFiles))
+                hostValues.add(p);
+        }
+    }
+    const conflicts = [];
+    const writes = new Map();
+    const removes = [];
+    for (const path of [...new Set([...Object.keys(manifest.files), ...copyFiles.keys()])].sort()) {
+        if (!allowed.some((d) => under(path, d)))
+            continue;
+        const base = manifest.files[path];
+        const copy = exportForm.get(path);
+        const changedThere = copy === undefined ? base !== undefined : base === undefined || fileHash(copy) !== base.export;
+        if (!changedThere)
+            continue;
+        const here = readOr(join(root, path));
+        const changedHere = here === undefined ? base !== undefined : base === undefined || fileHash(here) !== base.host;
+        if (copy === undefined) {
+            if (here === undefined)
+                continue;
+            if (changedHere)
+                conflicts.push({ path, reason: "the copy removed it, and it changed here since the export" });
+            else
+                removes.push(path);
+            continue;
+        }
+        const target = copyFiles.get(path);
+        if (here !== undefined && here.equals(target))
+            continue;
+        if (changedHere) {
+            conflicts.push({ path, reason: here === undefined ? "the copy changed it, and it was removed here since the export" : base === undefined ? "the copy added it, and a different file was added here" : "the copy and this workspace both changed it since the export" });
+            continue;
+        }
+        writes.set(path, target);
+    }
+    // Locks, scope by scope.
+    const lockWrites = new Map();
+    for (const path of [...new Set([...Object.keys(manifest.locks), ...copyLocks.keys()])].sort()) {
+        const there = copyLocks.get(path);
+        const hereText = readOr(join(root, path));
+        const here = hereText ? parseLock(hereText.toString("utf-8")) : null;
+        const next = here ? JSON.parse(JSON.stringify(here)) : { lockVersion: 1, scopes: {} };
+        let changed = false;
+        const recorded = manifest.locks[path] ?? {};
+        for (const scope of [...new Set([...Object.keys(recorded), ...Object.keys(there?.scopes ?? {})])].sort()) {
+            const base = recorded[scope];
+            const theirs = there?.scopes[scope];
+            const ours = here?.scopes[scope];
+            const theirDigest = copyDigests.get(`${path}#${scope}`);
+            const changedThere = theirDigest === undefined ? base !== undefined : base === undefined || theirDigest !== base.export;
+            if (!changedThere)
+                continue;
+            const changedHere = ours === undefined ? base !== undefined : base === undefined || lineageDigest(ours) !== base.host;
+            const where = `${path} scope ${scope}`;
+            if (changedHere) {
+                conflicts.push({ path: where, reason: "the copy and this workspace both changed the lineage since the export" });
+                continue;
+            }
+            if (!theirs) {
+                delete next.scopes[scope];
+                changed = true;
+                continue;
+            }
+            if (base?.partial && ours) {
+                // Only part of the scope went: take the copy's files, and nothing that would move the rest.
+                const { files: _f, manualSteps: _m, repinned: _r, ...a } = ours;
+                const { files: _f2, manualSteps: _m2, repinned: _r2, ...b } = theirs;
+                if (JSON.stringify(a) !== JSON.stringify(b)) {
+                    conflicts.push({ path: where, reason: "the copy upgraded a scope only part of which went with the export; upgrade it here instead" });
+                    continue;
+                }
+                const dir = lockDir(path);
+                const went = (f) => manifest.files[scopedPath(dir, scope, f)] !== undefined || theirs.files[f] !== undefined;
+                const files = Object.fromEntries(Object.entries(ours.files).filter(([f]) => !went(f)));
+                next.scopes[scope] = {
+                    ...ours,
+                    files: { ...files, ...theirs.files },
+                    manualSteps: [...ours.manualSteps.filter((s) => !went(s.path)), ...theirs.manualSteps],
+                };
+            }
+            else {
+                next.scopes[scope] = theirs;
+            }
+            changed = true;
+        }
+        if (changed)
+            lockWrites.set(path, next);
+    }
+    const result = {
+        export: manifest.id,
+        from: fromDir,
+        written: [...writes.keys()],
+        removed: removes,
+        locks: [...lockWrites.keys()],
+        hostValues: [...hostValues].filter((p) => writes.has(p)).sort(),
+        conflicts,
+        outside,
+        returnRecord: null,
+        return: null,
+        member: null,
+        applied: false,
+    };
+    if (outside.length > 0 || conflicts.length > 0)
+        return result;
+    const nothing = writes.size === 0 && removes.length === 0 && lockWrites.size === 0;
+    // The return record: what came back, and where each file was made.
+    const ownRepo = gitTopOf(fromDir);
+    const own = ownRepo !== undefined && realpathSync(ownRepo) === realpathSync(fromDir);
+    let head = null;
+    if (own) {
+        try {
+            head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: fromDir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        }
+        catch {
+            head = null;
+        }
+    }
+    const paths = {};
+    for (const [path, data] of writes) {
+        const origin = own && head && !hostValues.has(path) ? buildOrigin(fromDir, path, data) : undefined;
+        paths[path] = { sha256: fileHash(data), ...(origin ? { origin } : {}) };
+    }
+    for (const path of lockWrites.keys())
+        paths[path] = { sha256: fileHash(renderLock(lockWrites.get(path))) };
+    const origins = Object.values(paths).flatMap((p) => (p.origin ? [p.origin] : []));
+    const idBody = JSON.stringify({ export: manifest.id, head, paths: Object.fromEntries(Object.entries(paths).map(([p, v]) => [p, v.sha256])), removes });
+    const ret = {
+        schema: 1,
+        id: `ret-${createHash("sha256").update(idBody).digest("hex").slice(0, 12)}`,
+        export: { id: manifest.id, workspace: manifest.from.workspace, revision: manifest.from.revision },
+        head,
+        paths,
+        removed: removes,
+        hostValues: result.hostValues,
+        signers: originSigners(origins),
+    };
+    if (!nothing)
+        result.return = ret;
+    if (o.dryRun)
+        return result;
+    // Apply.
+    for (const [path, data] of writes) {
+        const abs = join(root, path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, data);
+    }
+    for (const path of removes)
+        rmSync(join(root, path), { force: true });
+    for (const [path, lock] of lockWrites) {
+        const abs = join(root, path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, renderLock(lock));
+    }
+    if (!nothing)
+        result.returnRecord = writeReturn(root, ret);
+    result.applied = true;
+    // The export member: written again from the workspace as it stands, or removed.
+    result.member = await settleExportMember(root, decl, manifest, o.remove === true, fromDir);
+    return result;
+}
+async function settleExportMember(root, decl, manifest, remove, fromDir) {
+    const m = decl.members.find((x) => x.name === manifest.member);
+    if (!m)
+        return null;
+    if (!remove) {
+        const again = await exportWorkspace({
+            root,
+            to: m.name,
+            ...(manifest.whole ? {} : { members: manifest.members }),
+            params: Object.fromEntries(Object.values(manifest.hostValues).flatMap((v) => Object.entries(v).map(([n, x]) => [n, x.export]))),
+        });
+        return { name: m.name, action: "regenerated", note: `${again.manifest.id}, ${again.files} file(s)` };
+    }
+    rmSync(join(root, m.dir), { recursive: true, force: true });
+    const { file, obj } = rawDeclaration(root);
+    if (file.endsWith(".jsonc")) {
+        return { name: m.name, action: "removed", note: `removed ${m.dir}; ${file} keeps comments, so drop the entry for ${m.name} by hand` };
+    }
+    obj.members = obj.members.filter((e) => e.name !== m.name);
+    writeFileSync(join(root, file), JSON.stringify(obj, null, 2) + "\n");
+    const inside = resolve(fromDir) === resolve(root, m.dir);
+    return { name: m.name, action: "removed", note: `removed ${m.dir} and its entry in ${file}${inside ? "" : `; the copy at ${relative(root, fromDir) || "."} is left as it is`}` };
+}