flecto 3.0.2 → 4.0.0

package/src/config.js

@@ -1,5 +1,14 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'fs';
-import { basename, dirname, join, relative, resolve, sep } from 'path';
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
 import fg from 'fast-glob';
 import yaml from 'js-yaml';
 import { isEnvFilename, parseContent } from './parser.js';
@@ -152,6 +161,22 @@ function isInside(candidate, root) {
   return candidate === root || candidate.startsWith(root + sep);
 }
 
+/**
+ * Containment decided on the paths as written, with no symlink resolution and
+ * no canonicalization.
+ *
+ * Used for "was this named inside the project?", where following a link is
+ * exactly the thing that must not happen -- and where canonicalizing one side
+ * but not the other silently breaks on Windows.
+ * @param {string} candidate
+ * @param {string} root both already absolute, from the same base
+ * @returns {boolean}
+ */
+function isLexicallyInside(candidate, root) {
+  const rel = relative(root, candidate);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
 /**
  * Refuse a path that lives inside the project but reads from outside it through
  * a symlink.
@@ -202,7 +227,25 @@ export function assertTargetContained(file, cwd = process.cwd()) {
   // there.
   const nominal = join(canonical(dirname(given)), basename(given));
   // Named from outside the project: nothing was escaped, it was never inside.
-  if (!isInside(nominal, root)) return;
+  //
+  // That judgement must also be made on the path *as given*, not only on a
+  // canonicalized parent -- the parent is a component an untrusted pull request
+  // controls. With a directory symlink (`repo/b -> /outside`),
+  // `canonical(dirname(given))` already points outside, so `nominal` looked
+  // externally-named and this returned without checking anything:
+  // `repo/b/baseline.json` read straight out of the project. Replacing the
+  // *file* with a link was refused; replacing its *directory* was the same
+  // effort and was not.
+  //
+  // That second judgement is deliberately **lexical** -- `resolve(cwd)` against
+  // `resolve(file)`, neither canonicalized. Comparing an as-given path against
+  // a *canonicalized* root is what made the first attempt at this fail on
+  // Windows and leak: `process.cwd()` reports the 8.3 short form
+  // (`C:\Users\RUNNER~1\...`) while `canonical()` returns the long one, so the
+  // two never shared a prefix, the check decided the path was externally named,
+  // and returned. Both sides here derive from the same `process.cwd()` spelling,
+  // so no normalization is needed and none can go wrong.
+  if (!isInside(nominal, root) && !isLexicallyInside(given, resolve(cwd))) return;
 
   const real = canonical(given);
   if (isInside(real, root)) return;
@@ -216,6 +259,329 @@ export function assertTargetContained(file, cwd = process.cwd()) {
   );
 }
 
+/**
+ * Has the operator explicitly opted in to write destinations that `.flectorc`
+ * points outside the project?
+ * @returns {boolean}
+ */
+function rcWritesAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_WRITES;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Refuse a *write* destination that leaves the project.
+ *
+ * The read rule ({@link assertTargetContained}) is about escape, and treats a
+ * path named from outside the project as operator intent. A write cannot be read
+ * that way, because the path is not always the operator's: `output` and
+ * `baseline` can be declared in `.flectorc`, and on an untrusted pull request
+ * `.flectorc` is attacker-controlled. Both destinations carry content the
+ * attacker partly controls — the report embeds config values and file names, a
+ * baseline embeds rule ids, paths, and messages — so an unconstrained
+ * destination is an arbitrary file overwrite with partly chosen content, which
+ * on a CI runner is a shell profile, a workflow file, or an SSH config.
+ *
+ * Two rules, matching the provenance:
+ *
+ * - **Declared in `.flectorc`** — must resolve inside the project.
+ *   `FLECTO_ALLOW_RC_WRITES=1` opts out, for a repository that genuinely
+ *   configures a destination elsewhere.
+ * - **Any source** — must not leave the project through a symlink, on the path
+ *   itself or on the directory it is written into. That is the shape a pull
+ *   request can author without touching the workflow, and it is refused for the
+ *   same reason a symlinked *target* is; `FLECTO_ALLOW_SYMLINK_TARGETS=1` opts
+ *   out of this half, as it does for reads.
+ *
+ * Refusing loudly rather than falling back to a default path is deliberate: a
+ * report that silently went somewhere else is worse than one that was not
+ * written.
+ * @param {string} file destination path, already resolved against the cwd
+ * @param {{ option: string, fromCli?: boolean, cwd?: string }} context
+ * @throws {Error} when the destination escapes the project
+ */
+export function assertWriteDestinationContained(file, context) {
+  const { option, fromCli = false } = context;
+  const cwd = context.cwd ?? process.cwd();
+  const lexicalRoot = resolve(cwd);
+  const root = canonical(lexicalRoot);
+  const given = resolve(cwd, file);
+  const shown = relative(lexicalRoot, given).split(sep).join('/') || given;
+
+  // A destination need not exist yet, and neither need the directories above it,
+  // so normalize from the nearest ancestor that does: canonical() cannot resolve
+  // a path that is not there, and its fallback leaves the spelling as written —
+  // which on Windows is an 8.3 short name that compares as a different directory
+  // from the long form `root` carries, making an in-project path look external.
+  const { base, rest } = nearestExistingDir(dirname(given));
+  const nominal = join(canonical(base), ...rest, basename(given));
+  // Either spelling counts as inside: the lexical form covers a path derived
+  // from the cwd, the canonical form a path named some other way.
+  const insideProject = isInside(given, lexicalRoot) || isInside(nominal, root);
+
+  if (!fromCli && !rcWritesAllowed() && !insideProject) {
+    throw new Error(
+      `Refusing to write "${option}" to ${given}: .flectorc points it outside the project.\n`
+      + '.flectorc is attacker-controlled on an untrusted pull request, and this file carries '
+      + 'config values and file names into whatever it overwrites.\n'
+      + `Pass ${option} on the command line for a destination outside the project, or set `
+      + 'FLECTO_ALLOW_RC_WRITES=1 if this repository genuinely configures one.',
+    );
+  }
+
+  if (symlinkTargetsAllowed()) return;
+
+  // Two ways a write leaves through a link: the destination is itself a link, or
+  // the nearest directory that exists on the way to it is. The second covers a
+  // path several levels deep whose parents have not been created yet.
+  for (const candidate of [given, base]) {
+    const real = linkDestination(candidate);
+    // Nothing there at all: no link to follow, so nothing to refuse.
+    if (real === null) continue;
+    // Named from outside the project: nothing escaped, it was never inside.
+    if (!isInside(candidate, lexicalRoot)) continue;
+    if (isInside(real, root)) continue;
+    throw new Error(
+      `Refusing to write "${option}" to "${shown}": it is a link out of the project, `
+      + `resolving to ${real}.\n`
+      + 'File names and links are attacker-controlled on an untrusted pull request, and '
+      + 'writing through one would overwrite a file outside the repository.\n'
+      + 'Set FLECTO_ALLOW_SYMLINK_TARGETS=1 if this link is intentional.',
+    );
+  }
+}
+
+/**
+ * How many links to walk before giving up. The OS gives up around 40; this only
+ * needs to outlast any chain a repository would legitimately contain.
+ */
+const MAX_LINK_HOPS = 32;
+
+/**
+ * Where a path actually lands, following links even when the chain ends
+ * somewhere that does not exist yet.
+ *
+ * `existsSync` follows links, so it reports *nothing* for a link whose target is
+ * missing — and `realpathSync` fails on one, leaving {@link canonical} to fall
+ * back to the path as written, which is still inside the project. So a link to a
+ * file the runner does not have yet reads as contained twice over. That is not
+ * the weaker half of this attack but the stronger one: overwriting needs the
+ * file to already be there, while a link to a file the runner does *not* have
+ * yet has Flecto create it. `~/.ssh/authorized_keys` is the one that stings,
+ * because sshd skips lines it cannot parse, so HTML wrapped around one
+ * attacker-authored line is still a usable key file.
+ *
+ * So the link is resolved by hand, hop by hop, and judged wherever it ends up.
+ * @param {string} path
+ * @param {number} [depth]
+ * @returns {string | null} null when there is nothing at `path` at all
+ */
+function linkDestination(path, depth = 0) {
+  const stats = lstatSync(path, { throwIfNoEntry: false });
+  if (!stats) return null;
+  if (!stats.isSymbolicLink()) return canonical(path);
+
+  const target = resolve(dirname(path), readlinkSync(path));
+  // A cycle, or a chain long enough that the write would fail with ELOOP
+  // anyway: judge the hop we have rather than walking forever.
+  if (depth >= MAX_LINK_HOPS) return target;
+  // The next hop may not exist; normalize what is there and keep the rest as
+  // written, the same way an ordinary destination is normalized above.
+  const { base, rest } = nearestExistingDir(dirname(target));
+  return linkDestination(target, depth + 1) ?? join(canonical(base), ...rest, basename(target));
+}
+
+/**
+ * The nearest ancestor of a path that exists on disk, plus the segments below it
+ * that do not.
+ * @param {string} path
+ * @returns {{ base: string, rest: string[] }}
+ */
+function nearestExistingDir(path) {
+  let current = resolve(path);
+  /** @type {string[]} */
+  const rest = [];
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) break;
+    rest.unshift(basename(current));
+    current = parent;
+  }
+  return { base: current, rest };
+}
+
+/**
+ * Has the operator explicitly opted in to alert actions declared in `.flectorc`?
+ * @returns {boolean}
+ */
+function rcAlertsAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_ALERTS;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Options a pull request can turn into an action or corrupt an existing one,
+ * once it controls `.flectorc`, together with the reason and the CLI flag that
+ * names each one.
+ *
+ * `onAlertFailure` and `deliveryMode` are deliberately not here: `flecto init`
+ * writes them into the generated `.flectorc` itself, they only ever tune how
+ * an alert *already chosen by the operator* responds to failure, and they draw
+ * the same line `failOn` does elsewhere — a setting a repository is meant to
+ * delegate, not an action a settings file grants itself.
+ */
+const ALERT_ACTION_OPTIONS = [
+  ['command', '--command', 'it spawns a shell command on every change'],
+  ['webhook', '--webhook', 'it sends change data to a URL'],
+  ['webhookHeader', '--webhook-header', 'it rides along on every request an operator-approved --webhook makes, and can override headers such as Content-Type'],
+];
+
+/**
+ * Refuse an alert action declared in `.flectorc` rather than on the command
+ * line.
+ *
+ * `watch --command` spawns a shell command on every change, with diff data
+ * injected as `FLECTO_*` environment variables; `--webhook` POSTs that same
+ * data to a URL; `--webhook-header` rides along on that request. All three are
+ * actions, not settings — the same distinction `--update-baseline` draws — and
+ * all three merge through `resolveEffectiveOptions` with no other gate, so a
+ * `.flectorc` (or profile) naming one runs it on the next `flecto watch`. On an
+ * untrusted pull request `.flectorc` is a file the attacker wrote, which makes
+ * an rc-declared `command` unconstrained shell execution, an rc-declared
+ * `webhook` an exfiltration destination the attacker chose, and an rc-declared
+ * `webhookHeader` a way to override what an *operator-approved* webhook call
+ * sends — reachable even when `command`/`webhook` themselves came from the CLI.
+ *
+ * Any of the three named on the CLI is operator intent and unrestricted:
+ * `flecto watch config.yaml --command './notify.sh'` still works exactly as
+ * before. `FLECTO_ALLOW_RC_ALERTS=1` opts out for a repository that genuinely
+ * configures one in `.flectorc`. Refusing loudly rather than skipping silently
+ * is deliberate, for the same reason a stripped plugin or write destination is
+ * loud: an alert that quietly stopped firing would look like "nothing
+ * happened" instead of "this was refused".
+ * @param {Record<string, unknown>} effective
+ * @param {Record<string, unknown>} cliOverrides
+ * @throws {Error} when an alert action came from `.flectorc`/a profile
+ */
+export function assertAlertActionsFromCli(effective, cliOverrides) {
+  if (rcAlertsAllowed()) return;
+  for (const [option, flag, reason] of ALERT_ACTION_OPTIONS) {
+    if (effective[option] === undefined || cliOverrides[option] !== undefined) continue;
+    const declared = Array.isArray(effective[option]) ? effective[option].join(', ') : effective[option];
+    throw new Error(
+      `Refusing "${option}" declared in .flectorc: ${reason}, `
+      + 'and .flectorc is attacker-controlled on an untrusted pull request.\n'
+      + `Declared: ${declared}\n`
+      + `Pass ${flag} on the command line instead, or set FLECTO_ALLOW_RC_ALERTS=1 `
+      + 'if this config is trusted.',
+    );
+  }
+}
+
+/**
+ * Has the operator explicitly opted in to a baseline selected by `.flectorc`?
+ * @returns {boolean}
+ */
+function rcBaselineAllowed() {
+  const raw = process.env.FLECTO_ALLOW_RC_BASELINE;
+  return raw === '1' || String(raw).toLowerCase() === 'true';
+}
+
+/**
+ * Refuse a `snapshotRef` declared in `.flectorc` rather than on the command
+ * line.
+ *
+ * `snapshotRef` names the baseline every change is measured against, so
+ * whoever sets it decides what "changed" means. That makes it an action in the
+ * same sense `--update-baseline` is one: a pull request that controls it can
+ * turn its own failing gate green without touching a policy, a suppression, or
+ * the gate's own `--fail-on`.
+ *
+ * The cheapest exploit needs no crafted value at all. A committed `.flectorc`
+ * carrying `{"defaults": {"snapshotRef": "HEAD"}}` points the baseline at the
+ * pull request's own tip, so every file is compared against itself, every diff
+ * is empty, and `flecto ci` exits 0 no matter what the change did. Confirmed
+ * end to end: a config that disables TLS and raises a pool size 100x fails the
+ * gate against the operator's ref and passes against an rc-declared `HEAD`.
+ *
+ * A ref named on the command line is operator intent and unrestricted, so
+ * `flecto ci config.yaml --snapshot-ref origin/main` is untouched. A repository
+ * that genuinely wants its baseline in the rc file sets
+ * `FLECTO_ALLOW_RC_BASELINE=1`, which is a statement that `.flectorc` is
+ * trusted there. Refusing loudly rather than falling back to a default baseline
+ * is deliberate, for the reason every other gate here refuses loudly: a gate
+ * that quietly measured against something else would still print a clean run.
+ * @param {Record<string, unknown>} effective
+ * @param {Record<string, unknown>} cliOverrides
+ * @throws {Error} when the baseline ref came from `.flectorc`/a profile
+ */
+export function assertSnapshotRefFromCli(effective, cliOverrides) {
+  if (rcBaselineAllowed()) return;
+  // `snapshotFile` picks the baseline just as directly, so it is gated with it
+  // rather than left as the way around it.
+  for (const option of ['snapshotRef', 'snapshotFile']) {
+    if (effective[option] === undefined || cliOverrides[option] !== undefined) continue;
+    throw new Error(
+      `Refusing "${option}" declared in .flectorc: it chooses the baseline every change is`
+      + ' measured against, so a pull request that edits it decides what counts as changed --'
+      + ' pointing it at "HEAD", or at a file it committed, compares every file against itself'
+      + ' and exits 0.\n'
+      + `Declared: ${JSON.stringify(effective[option])}\n`
+      + `Pass --${option === 'snapshotRef' ? 'snapshot-ref' : 'snapshot-file'} on the command line`
+      + ' instead, or set FLECTO_ALLOW_RC_BASELINE=1 if this config is trusted.',
+    );
+  }
+}
+
+/**
+ * Refuse a baseline ref that git would read as an option rather than a
+ * revision.
+ *
+ * The ref reaches `git show <rev>:<path>` as a single argv entry. `execFile`
+ * keeps it out of a shell, so there is no command injection here, but argv is
+ * not the same boundary as a shell: a ref beginning with `-` is still parsed by
+ * git as one of *its* options. `--output=pwned` turns the baseline read into a
+ * file write, and because the read then yields nothing, the baseline parses as
+ * an empty document, every key looks newly `added`, and the default
+ * `--fail-on changed,policy,error` never fires — an arbitrary write and a
+ * silent gate bypass from one string.
+ *
+ * Callers also pass `--end-of-options` so git itself refuses to read any
+ * operand as an option. This check is the belt to that suspenders: it names the
+ * problem in a message a human can act on, and it holds on a git too old for
+ * `--end-of-options` (added in 2.24).
+ * @param {string} ref
+ * @returns {string} the ref, unchanged, when it is safe to pass to git
+ * @throws {Error} when git would read the ref as an option
+ */
+export function assertSafeGitRef(ref) {
+  if (typeof ref !== 'string') {
+    throw new Error('Refusing snapshot ref: it must be a string.');
+  }
+  if (ref.includes('..')) {
+    // `git show A..B` is a *range*: it succeeds and prints nothing, so the
+    // baseline parses empty, every key reads as `added`, and the default
+    // `--fail-on` never fires. Callers resolve refs through
+    // `rev-parse --verify <ref>^{commit}`, which already refuses a range; this
+    // refuses it by name, because "Needed a single revision" explains less. A
+    // valid ref cannot contain `..` in any case (git-check-ref-format).
+    throw new Error(
+      `Refusing snapshot ref "${ref}": ".." makes it a commit range rather than a single`
+      + ' revision, which git reads as an empty diff.',
+    );
+  }
+  if (ref.startsWith('-')) {
+    throw new Error(
+      `Refusing snapshot ref "${ref}": it starts with "-", so git would read it as an option`
+      + ' rather than a revision.',
+    );
+  }
+  if (/[\0\n\r]/.test(ref)) {
+    throw new Error('Refusing snapshot ref: it contains a newline or NUL byte.');
+  }
+  return ref;
+}
+
 /**
  * Split a policy list that may arrive as an array or a comma-separated string.
  * @param {unknown} raw

package/src/differ.js

@@ -179,6 +179,49 @@ function matchParts(patternParts, pathParts) {
   return true;
 }
 
+/**
+ * The containers on the path currently being compared, one set per side.
+ *
+ * A cyclic tree makes the walk reach a node it is already inside. Descending
+ * again cannot find anything the in-progress comparison will not already report
+ * at a shorter path, so the back-edge is dropped rather than followed. Same
+ * ancestor-tracking pattern as `normalizeParsedValue` in parser.js and
+ * `collectLeaves` in policy.js: added on the way in, removed on the way out, so
+ * a value merely reached twice by separate branches (a DAG, not a cycle) is
+ * still compared in full on each branch.
+ *
+ * Either side repeating is enough to stop. Tracking the *pair* instead would be
+ * more precise -- it would keep descending where one side cycles and the other
+ * does not -- but two cyclic trees have |before| x |after| distinct pairs, so
+ * precision there buys a quadratic worst case. This is a guard against a walk
+ * that will not end; bounding it by the size of the input is the property worth
+ * having.
+ *
+ * Nothing downstream of the parser holds a cycle -- `normalizeParsedValue`
+ * replaces one with its circular sentinel before a tree ever gets here -- so
+ * this is a second line rather than the first. Without it the walk recurses
+ * until the stack overflows, which costs real time on the way down (the path
+ * string is rebuilt at every level) before throwing.
+ *
+ * This covers the structural walk only. `arraySignature` canonicalizes without
+ * it -- that runs per array element, where the same tracking cost ~15% on a
+ * 5000-element diff, and its `catch` already contains a cyclic element by
+ * falling back to identity comparison.
+ *
+ * It is not free: the set writes cost ~20% of `diffTrees`, which the benchmark
+ * puts at ~17% of a run, so ~3% end to end. Gating it behind a depth threshold
+ * removes that, and was tried -- but then a cycle is followed as far as the
+ * threshold, and every level of it emits a duplicate event under a
+ * `self.self.self...` path. Paying 3% to keep the output right is the better
+ * trade for a tool whose output is read on a pull request.
+ * @typedef {{ before: Set<object>, after: Set<object> }} Ancestors
+ */
+
+/** @returns {Ancestors} */
+function newAncestors() {
+  return { before: new Set(), after: new Set() };
+}
+
 /**
  * Recursively diff two values at a given key path.
  * @param {unknown} before
@@ -186,8 +229,9 @@ function matchParts(patternParts, pathParts) {
  * @param {string} path
  * @param {ChangeEvent[]} events  accumulator
  * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
+ * @param {Ancestors} ancestors  containers on the current path
  */
-function diffValues(before, after, path, events, options = {}) {
+function diffValues(before, after, path, events, options = {}, ancestors = newAncestors()) {
   const beforeIsObj = isPlainObject(before);
   const afterIsObj = isPlainObject(after);
   const beforeIsArr = Array.isArray(before);
@@ -195,13 +239,23 @@ function diffValues(before, after, path, events, options = {}) {
 
   // Both plain objects → recurse into keys
   if (beforeIsObj && afterIsObj) {
-    diffObjects(before, after, path, events, options);
+    if (ancestors.before.has(before) || ancestors.after.has(after)) return;
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffObjects(before, after, path, events, options, ancestors);
+    ancestors.before.delete(before);
+    ancestors.after.delete(after);
     return;
   }
 
   // Both arrays → diff by index or identity key
   if (beforeIsArr && afterIsArr) {
-    diffArrays(before, after, path, events, options);
+    if (ancestors.before.has(before) || ancestors.after.has(after)) return;
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffArrays(before, after, path, events, options, ancestors);
+    ancestors.before.delete(before);
+    ancestors.after.delete(after);
     return;
   }
 
@@ -247,8 +301,9 @@ function diffValues(before, after, path, events, options = {}) {
  * @param {string} basePath
  * @param {ChangeEvent[]} events
  * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
+ * @param {Ancestors} [ancestors]
  */
-function diffObjects(before, after, basePath, events, options = {}) {
+function diffObjects(before, after, basePath, events, options = {}, ancestors = newAncestors()) {
   const beforeKeys = new Set(Object.keys(before));
   const afterKeys = new Set(Object.keys(after));
 
@@ -272,7 +327,7 @@ function diffObjects(before, after, basePath, events, options = {}) {
   for (const key of beforeKeys) {
     if (afterKeys.has(key)) {
       const childPath = basePath ? `${basePath}.${key}` : key;
-      diffValues(before[key], after[key], childPath, events, options);
+      diffValues(before[key], after[key], childPath, events, options, ancestors);
     }
   }
 }
@@ -366,8 +421,9 @@ function arraySignature(value) {
  * @param {string} basePath
  * @param {ChangeEvent[]} events
  * @param {{ arrayIdKey?: string | null, arrayIdentity?: boolean, arrayIgnoreOrder?: boolean }} [options]
+ * @param {Ancestors} [ancestors]
  */
-function diffArrays(before, after, basePath, events, options = {}) {
+function diffArrays(before, after, basePath, events, options = {}, ancestors = newAncestors()) {
   const idKey = resolveArrayIdKey(before, after, options);
 
   if (idKey) {
@@ -380,7 +436,7 @@ function diffArrays(before, after, basePath, events, options = {}) {
         if (!beforeMap.has(key)) {
           events.push({ type: 'added', path: childPath, after: afterItem.value });
         } else {
-          diffValues(beforeMap.get(key).value, afterItem.value, childPath, events, options);
+          diffValues(beforeMap.get(key).value, afterItem.value, childPath, events, options, ancestors);
         }
       }
       for (const [key, beforeItem] of beforeMap) {
@@ -424,7 +480,7 @@ function diffArrays(before, after, basePath, events, options = {}) {
     } else if (i >= after.length) {
       events.push({ type: 'removed', path: childPath, before: before[i] });
     } else {
-      diffValues(before[i], after[i], childPath, events, options);
+      diffValues(before[i], after[i], childPath, events, options, ancestors);
     }
   }
 }
@@ -447,14 +503,22 @@ export function diffTrees(before, after, options = {}) {
     arrayIgnoreOrder: Boolean(options.arrayIgnoreOrder),
   };
 
-  // Root handling: avoid assuming object roots.
+  // Root handling: avoid assuming object roots. The roots are recorded here
+  // because these two calls bypass `diffValues`, which is where every other
+  // container is recorded -- without it a cycle back to the root would be
+  // caught one level deeper than it should be.
+  const ancestors = newAncestors();
   if (isPlainObject(before) && isPlainObject(after)) {
-    diffObjects(before, after, '', events, diffOpts);
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffObjects(before, after, '', events, diffOpts, ancestors);
   } else if (Array.isArray(before) && Array.isArray(after)) {
-    diffArrays(before, after, '', events, diffOpts);
+    ancestors.before.add(before);
+    ancestors.after.add(after);
+    diffArrays(before, after, '', events, diffOpts, ancestors);
   } else {
     // Compare as a single root value. Use "<root>" so we can still ignore it if desired.
-    diffValues(before, after, '<root>', events, diffOpts);
+    diffValues(before, after, '<root>', events, diffOpts, ancestors);
   }
 
   // Encrypted files carry signals a key-by-key walk cannot express: the file