@jsenv/snapshot 2.6.0 → 2.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/snapshot",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "Snapshot testing",
   "license": "MIT",
   "author": {
@@ -34,11 +34,11 @@
     "test": "node --conditions=development ./scripts/test.mjs"
   },
   "dependencies": {
-    "@jsenv/assert": "4.1.6",
-    "@jsenv/ast": "6.2.7",
-    "@jsenv/exception": "1.0.0",
-    "@jsenv/filesystem": "4.9.4",
-    "@jsenv/urls": "2.4.0",
+    "@jsenv/assert": "4.1.7",
+    "@jsenv/ast": "6.2.9",
+    "@jsenv/exception": "1.0.1",
+    "@jsenv/filesystem": "4.9.5",
+    "@jsenv/urls": "2.4.1",
     "@jsenv/utils": "2.1.2",
     "pixelmatch": "6.0.0",
     "prettier": "3.3.3",

package/src/filesystem_well_known_values.js

@@ -0,0 +1,249 @@
+import {
+  ensurePathnameTrailingSlash,
+  removePathnameTrailingSlash,
+} from "@jsenv/urls";
+import { escapeRegexpSpecialChars } from "@jsenv/utils/src/string/escape_regexp_special_chars.js";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// remember this: https://stackoverflow.com/a/31976060/24573072
+// when deciding which replacement to use and willBeWrittenOnFilesystem is true
+const WELL_KNOWN_ROOT = {
+  name: "root",
+  getReplacement: ({ preferFileUrl }) => {
+    if (preferFileUrl) {
+      return "file:///[root]";
+    }
+    return "[root]";
+  },
+};
+const WELL_KNOWN_HOMEDIR = {
+  name: "homedir",
+  getReplacement: ({ willBeWrittenOnFilesystem, preferFileUrl }) => {
+    if (willBeWrittenOnFilesystem) {
+      if (preferFileUrl) {
+        return "file:///[homedir]";
+      }
+      return "[homedir]";
+    }
+    if (preferFileUrl) {
+      return "file:///~";
+    }
+    return "~";
+  },
+};
+const WELL_KNOWN_CWD = {
+  name: "cwd",
+  getReplacement: ({ preferFileUrl }) => {
+    if (preferFileUrl) {
+      return "file:///cwd()";
+    }
+    return "cwd()";
+  },
+};
+const createWellKnownPackage = (name) => {
+  return {
+    name,
+    getReplacement: () => name,
+  };
+};
+export const createWellKnown = (name, replacement = name) => {
+  return {
+    name,
+    getReplacement: () => replacement,
+  };
+};
+
+export const createReplaceFilesystemWellKnownValues = ({
+  rootDirectoryUrl,
+  // for unit tests
+  isWindows = process.platform === "win32",
+  ancestorPackagesDisabled,
+  ancestorPackagesRootDirectoryUrl = "file:///",
+  homedirDisabled,
+  cwdDisabled,
+  cwdUrl,
+  cwdPath = process.cwd(),
+} = {}) => {
+  const wellKownUrlArray = [];
+  const wellKnownPathArray = [];
+  const addWellKnownFileUrl = (url, wellKnown, { position = "end" } = {}) => {
+    url = new URL(url);
+    const urlWithoutTrailingSlash = String(removePathnameTrailingSlash(url));
+    const wellKnownUrl = {
+      url: urlWithoutTrailingSlash,
+      replace: (string, { willBeWrittenOnFilesystem }) => {
+        const replacement = wellKnown.getReplacement({
+          preferFileUrl: true,
+          willBeWrittenOnFilesystem,
+        });
+        return string.replaceAll(urlWithoutTrailingSlash, replacement);
+      },
+    };
+    const path =
+      String(url) === String(cwdUrl)
+        ? cwdPath
+        : fileURLToPath(urlWithoutTrailingSlash);
+    const windowPathRegex = new RegExp(
+      `${escapeRegexpSpecialChars(path)}(((?:\\\\(?:[\\w !#()-]+|[.]{1,2})+)*)(?:\\\\)?)`,
+      "gm",
+    );
+    const wellKnownPath = {
+      path,
+      replace: isWindows
+        ? (string, { willBeWrittenOnFilesystem }) => {
+            const replacement = wellKnown.getReplacement({
+              willBeWrittenOnFilesystem,
+            });
+            return string.replaceAll(windowPathRegex, (match, after) => {
+              return `${replacement}${after.replaceAll("\\", "/")}`;
+            });
+          }
+        : (string, { willBeWrittenOnFilesystem }) => {
+            const replacement = wellKnown.getReplacement({
+              willBeWrittenOnFilesystem,
+            });
+            return string.replaceAll(path, replacement);
+          },
+    };
+    if (position === "start") {
+      wellKownUrlArray.unshift(wellKnownUrl);
+      wellKnownPathArray.unshift(wellKnownPath);
+    } else {
+      wellKownUrlArray.push(wellKnownUrl);
+      wellKnownPathArray.push(wellKnownPath);
+    }
+  };
+  if (rootDirectoryUrl) {
+    addWellKnownFileUrl(rootDirectoryUrl, WELL_KNOWN_ROOT);
+  }
+  /*
+   * When running code inside a node project ancestor packages
+   * should make things super predictible because
+   * it will use a package.json name field
+   * to replace files urls
+   * And uses the highest ancestor package so that even if the file
+   * is executed once within a package then outside that package
+   * the replace value remains predictible as the highest package is used
+   * The highest package is used because it's pushed first by
+   * addWellKnownFileUrl
+   */
+  ancestor_packages: {
+    if (ancestorPackagesDisabled) {
+      break ancestor_packages;
+    }
+    const ancestorPackages = [];
+    const cwd = cwdPath || process.cwd();
+    const cwdUrl = ensurePathnameTrailingSlash(pathToFileURL(cwd));
+    let currentUrl = cwdUrl;
+    while (currentUrl.href !== ancestorPackagesRootDirectoryUrl) {
+      const packageFileUrl = new URL("package.json", currentUrl);
+      const packageDirectoryUrl = currentUrl;
+      currentUrl = new URL(getParentUrl(currentUrl));
+      let packageFileContent;
+      try {
+        packageFileContent = readFileSync(packageFileUrl);
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          continue;
+        }
+        throw e;
+      }
+      let packageObject;
+      try {
+        packageObject = JSON.parse(packageFileContent);
+      } catch (e) {
+        continue;
+      }
+      const packageName = packageObject.name;
+      ancestorPackages.unshift({
+        packageDirectoryUrl,
+        packageName,
+      });
+    }
+    for (const ancestorPackage of ancestorPackages) {
+      addWellKnownFileUrl(
+        ancestorPackage.packageDirectoryUrl,
+        createWellKnownPackage(ancestorPackage.packageName),
+      );
+    }
+  }
+  home_dir: {
+    if (homedirDisabled) {
+      break home_dir;
+    }
+    const homedirPath = homedir();
+    const homedirUrl = pathToFileURL(homedirPath);
+    addWellKnownFileUrl(homedirUrl, WELL_KNOWN_HOMEDIR);
+  }
+  process_cwd: {
+    if (cwdDisabled) {
+      break process_cwd;
+    }
+    // we fallback on process.cwd()
+    // but it's brittle because a file might be execute from anywhere
+    // so it should be the last resort
+    cwdUrl = cwdUrl || pathToFileURL(cwdPath);
+    addWellKnownFileUrl(cwdUrl, WELL_KNOWN_CWD);
+  }
+
+  const replaceFileUrls = (string, { willBeWrittenOnFilesystem }) => {
+    for (const wellKownUrl of wellKownUrlArray) {
+      const replaceResult = wellKownUrl.replace(string, {
+        willBeWrittenOnFilesystem,
+      });
+      if (replaceResult !== string) {
+        return replaceResult;
+      }
+    }
+    return string;
+  };
+  const replaceFilePaths = (string, { willBeWrittenOnFilesystem }) => {
+    for (const wellKownPath of wellKnownPathArray) {
+      const replaceResult = wellKownPath.replace(string, {
+        willBeWrittenOnFilesystem,
+      });
+      if (replaceResult !== string) {
+        return replaceResult;
+      }
+    }
+    return string;
+  };
+
+  const replaceFilesystemWellKnownValues = (
+    string,
+    { willBeWrittenOnFilesystem = true } = {},
+  ) => {
+    const isUrl = typeof string === "object" && typeof string.href === "string";
+    if (isUrl) {
+      string = string.href;
+    }
+    string = replaceFileUrls(string, { willBeWrittenOnFilesystem });
+    string = replaceFilePaths(string, { willBeWrittenOnFilesystem });
+    return string;
+  };
+  replaceFilesystemWellKnownValues.addWellKnownFileUrl = addWellKnownFileUrl;
+  return replaceFilesystemWellKnownValues;
+};
+
+const getParentUrl = (url) => {
+  url = String(url);
+  // With node.js new URL('../', 'file:///C:/').href
+  // returns "file:///C:/" instead of "file:///"
+  const resource = url.slice("file://".length);
+  const slashLastIndex = resource.lastIndexOf("/");
+  if (slashLastIndex === -1) {
+    return url;
+  }
+  const lastCharIndex = resource.length - 1;
+  if (slashLastIndex === lastCharIndex) {
+    const slashBeforeLastIndex = resource.lastIndexOf("/", slashLastIndex - 1);
+    if (slashBeforeLastIndex === -1) {
+      return url;
+    }
+    return `file://${resource.slice(0, slashBeforeLastIndex + 1)}`;
+  }
+
+  return `file://${resource.slice(0, slashLastIndex + 1)}`;
+};

package/src/function_side_effects/common_ancestor_path.js

@@ -0,0 +1,13 @@
+import { getCommonPathname } from "@jsenv/urls";
+
+export const findCommonAncestorPath = (paths, castAsPath) => {
+  return paths.reduce((a, b) => {
+    if (typeof a !== "string" && castAsPath) a = castAsPath(a);
+    if (typeof b !== "string" && castAsPath) b = castAsPath(b);
+    if (a === b) {
+      return a;
+    }
+    const common = getCommonPathname(a, b);
+    return common;
+  });
+};

package/src/function_side_effects/common_ancestor_path.test.mjs

@@ -0,0 +1,14 @@
+import { assert } from "@jsenv/assert";
+import { findCommonAncestorPath } from "./common_ancestor_path.js";
+
+const test = (paths, expect) => {
+  const actual = findCommonAncestorPath(paths);
+  assert({ actual, expect });
+};
+
+test(["/a/b/c/d", "/a/b/c/d/"], "/a/b/c/d");
+test(["/a/b/c", "/a/b/d", "/a/x/y"], "/a/");
+test(["/a/b/", "/a/b/"], "/a/b/");
+test(["/a", "/a/b/c"], "/a");
+test(["/a/b/c", "/a"], "/a/");
+test(["/a/b/c"], "/a/b/c");

package/src/function_side_effects/function_side_effects_collector.js

@@ -14,6 +14,7 @@ export const collectFunctionSideEffects = (
   const sideEffects = [];
   const addSideEffect = (sideEffect) => {
     sideEffects.push(sideEffect);
+    return sideEffect;
   };
   const finallyCallbackSet = new Set();
   for (const sideEffectDetector of sideEffectDetectors) {
@@ -36,7 +37,6 @@ export const collectFunctionSideEffects = (
       `collectFunctionSideEffects called while other function(s) side effects are collected`,
     );
   }
-  functionExecutingCount++;
 
   const onCatch = (valueThrow) => {
     sideEffects.push({
@@ -98,6 +98,7 @@ export const collectFunctionSideEffects = (
     });
   };
   const onFinally = () => {
+    delete process.env.SNAPSHOTING_FUNCTION_SIDE_EFFECTS;
     functionExecutingCount--;
     for (const finallyCallback of finallyCallbackSet) {
       finallyCallback();
@@ -105,6 +106,8 @@ export const collectFunctionSideEffects = (
     finallyCallbackSet.clear();
   };
 
+  process.env.SNAPSHOTING_FUNCTION_SIDE_EFFECTS = "1";
+  functionExecutingCount++;
   let returnedPromise = false;
   try {
     const valueReturned = fn();

package/src/function_side_effects/function_side_effects_renderer.js

@@ -2,6 +2,9 @@ export const renderSideEffects = (sideEffects) => {
   let string = "";
   let index = 0;
   for (const sideEffect of sideEffects) {
+    if (sideEffect.skippable) {
+      continue;
+    }
     if (string) {
       string += "\n\n";
     }
@@ -17,7 +20,7 @@ export const renderSideEffects = (sideEffects) => {
   return string;
 };
 
-export const wrapIntoMarkdownBlock = (value, blockName) => {
+export const wrapIntoMarkdownBlock = (value, blockName = "") => {
   const start = "```";
   const end = "```";
   return `${start}${blockName}

package/src/function_side_effects/function_side_effects_snapshot.js

@@ -1,6 +1,7 @@
-import { writeFileSync } from "@jsenv/filesystem";
+import { readDirectorySync, writeFileSync } from "@jsenv/filesystem";
 import {
   ensurePathnameTrailingSlash,
+  urlIsInsideOf,
   urlToExtension,
   urlToRelativeUrl,
 } from "@jsenv/urls";
@@ -8,12 +9,17 @@ import {
   takeDirectorySnapshot,
   takeFileSnapshot,
 } from "../filesystem_snapshot.js";
+import {
+  createReplaceFilesystemWellKnownValues,
+  createWellKnown,
+} from "../filesystem_well_known_values.js";
 import { replaceFluctuatingValues } from "../replace_fluctuating_values.js";
 import { collectFunctionSideEffects } from "./function_side_effects_collector.js";
 import {
   renderSideEffects,
   wrapIntoMarkdownBlock,
 } from "./function_side_effects_renderer.js";
+import { groupFileSideEffectsPerDirectory } from "./group_file_side_effects_per_directory.js";
 import { spyConsoleCalls } from "./spy_console_calls.js";
 import { spyFilesystemCalls } from "./spy_filesystem_calls.js";
 
@@ -27,13 +33,8 @@ const consoleEffectsDefault = {
 
 export const snapshotFunctionSideEffects = (
   fn,
-  fnFileUrl,
-  sideEffectFileRelativeUrl,
-  {
-    rootDirectoryUrl = new URL("./", fnFileUrl),
-    consoleEffects = true,
-    filesystemEffects = true,
-  } = {},
+  sideEffectFileUrl,
+  { consoleEffects = true, filesystemEffects = true, rootDirectoryUrl } = {},
 ) => {
   if (consoleEffects === true) {
     consoleEffects = {};
@@ -41,7 +42,10 @@ export const snapshotFunctionSideEffects = (
   if (filesystemEffects === true) {
     filesystemEffects = {};
   }
-  const sideEffectFileUrl = new URL(sideEffectFileRelativeUrl, fnFileUrl);
+  const replaceFilesystemWellKnownValues =
+    createReplaceFilesystemWellKnownValues({
+      rootDirectoryUrl,
+    });
   const sideEffectFileSnapshot = takeFileSnapshot(sideEffectFileUrl);
   const callbackSet = new Set();
   const sideEffectDetectors = [
@@ -60,7 +64,7 @@ export const snapshotFunctionSideEffects = (
                   text: wrapIntoMarkdownBlock(
                     replaceFluctuatingValues(message, {
                       stringType: "console",
-                      rootDirectoryUrl,
+                      replaceFilesystemWellKnownValues,
                     }),
                     "console",
                   ),
@@ -80,6 +84,34 @@ export const snapshotFunctionSideEffects = (
                   log: (message) => {
                     onConsole("log", message);
                   },
+                  stdout: (message) => {
+                    addSideEffect({
+                      type: `process:stdout`,
+                      value: message,
+                      label: `process.stdout`,
+                      text: wrapIntoMarkdownBlock(
+                        replaceFluctuatingValues(message, {
+                          stringType: "console",
+                          replaceFilesystemWellKnownValues,
+                        }),
+                        "console",
+                      ),
+                    });
+                  },
+                  stderr: (message) => {
+                    addSideEffect({
+                      type: `process:stderr`,
+                      value: message,
+                      label: `process.stderr`,
+                      text: wrapIntoMarkdownBlock(
+                        replaceFluctuatingValues(message, {
+                          stringType: "console",
+                          replaceFilesystemWellKnownValues,
+                        }),
+                        "console",
+                      ),
+                    });
+                  },
                 },
                 {
                   preventConsoleSideEffects: prevent,
@@ -102,7 +134,21 @@ export const snapshotFunctionSideEffects = (
                 ...filesystemEffects,
               };
               let writeFile;
-              const { preserve, outDirectory } = filesystemEffects;
+              const { include, preserve, baseDirectory, outDirectory } =
+                filesystemEffects;
+              if (baseDirectory) {
+                replaceFilesystemWellKnownValues.addWellKnownFileUrl(
+                  baseDirectory,
+                  createWellKnown("base"),
+                  { position: "start" },
+                );
+              }
+              const renderLabel = (label) => {
+                return replaceFluctuatingValues(label, {
+                  replaceFilesystemWellKnownValues,
+                });
+              };
+
               if (outDirectory) {
                 const fsEffectsOutDirectoryUrl = ensurePathnameTrailingSlash(
                   new URL(outDirectory, sideEffectFileUrl),
@@ -110,12 +156,53 @@ export const snapshotFunctionSideEffects = (
                 const fsEffectsOutDirectorySnapshot = takeDirectorySnapshot(
                   fsEffectsOutDirectoryUrl,
                 );
-                const fsEffectsOutDirectoryRelativeUrl = urlToRelativeUrl(
-                  fsEffectsOutDirectoryUrl,
-                  sideEffectFileUrl,
-                );
                 const writeFileCallbackSet = new Set();
-                callbackSet.add(() => {
+                const getFilesystemActionInfo = (action, url) => {
+                  let toUrl;
+                  let urlDisplayed = url;
+                  if (baseDirectory) {
+                    urlDisplayed = urlToRelativeUrl(url, baseDirectory, {
+                      preferRelativeNotation: true,
+                    });
+                    if (
+                      url.href === baseDirectory.href ||
+                      urlIsInsideOf(url, baseDirectory)
+                    ) {
+                      const toRelativeUrl = urlToRelativeUrl(
+                        url,
+                        baseDirectory,
+                      );
+                      toUrl = new URL(toRelativeUrl, fsEffectsOutDirectoryUrl);
+                    } else {
+                      const toRelativeUrl =
+                        replaceFilesystemWellKnownValues(url);
+                      toUrl = new URL(toRelativeUrl, fsEffectsOutDirectoryUrl);
+                    }
+                    // otherwise we need to replace the url with well known
+                  } else {
+                    const toRelativeUrl = replaceFilesystemWellKnownValues(url);
+                    toUrl = new URL(toRelativeUrl, fsEffectsOutDirectoryUrl);
+                  }
+                  const toUrlDisplayed = urlToRelativeUrl(
+                    toUrl,
+                    sideEffectFileUrl,
+                    { preferRelativeNotation: true },
+                  );
+                  return {
+                    toUrl,
+                    label: renderLabel(
+                      `${action} "${urlDisplayed}" (see ${toUrlDisplayed})`,
+                    ),
+                  };
+                };
+
+                callbackSet.add((sideEffects) => {
+                  // gather all file side effect next to each other
+                  // collapse them if they have a shared ancestor
+                  groupFileSideEffectsPerDirectory(sideEffects, {
+                    baseDirectory,
+                    getFilesystemActionInfo,
+                  });
                   for (const writeFileCallback of writeFileCallbackSet) {
                     writeFileCallback();
                   }
@@ -123,25 +210,32 @@ export const snapshotFunctionSideEffects = (
                   fsEffectsOutDirectorySnapshot.compare();
                 });
                 writeFile = (url, content) => {
-                  const relativeUrl = urlToRelativeUrl(url, fnFileUrl);
-                  const toUrl = new URL(relativeUrl, fsEffectsOutDirectoryUrl);
+                  const { toUrl, label } = getFilesystemActionInfo(
+                    "write file",
+                    url,
+                  );
                   writeFileCallbackSet.add(() => {
                     writeFileSync(toUrl, content);
                   });
                   addSideEffect({
                     type: "fs:write_file",
-                    value: { relativeUrl, content },
-                    label: `write file "${relativeUrl}" (see ./${fsEffectsOutDirectoryRelativeUrl}${relativeUrl})`,
+                    value: { url: String(url), content },
+                    label,
                     text: null,
                   });
                 };
               } else {
                 writeFile = (url, content) => {
-                  const relativeUrl = urlToRelativeUrl(url, fnFileUrl);
+                  let urlDisplayed = url;
+                  if (baseDirectory) {
+                    urlDisplayed = urlToRelativeUrl(url, baseDirectory, {
+                      preferRelativeNotation: true,
+                    });
+                  }
                   addSideEffect({
                     type: "fs:write_file",
-                    value: { relativeUrl, content },
-                    label: `write file "${relativeUrl}"`,
+                    value: { url: String(url), content },
+                    label: renderLabel(`write file "${urlDisplayed}"`),
                     text: wrapIntoMarkdownBlock(
                       content,
                       urlToExtension(url).slice(1),
@@ -153,16 +247,28 @@ export const snapshotFunctionSideEffects = (
                 {
                   writeFile,
                   writeDirectory: (url) => {
-                    const relativeUrl = urlToRelativeUrl(url, fnFileUrl);
-                    addSideEffect({
+                    const writeDirectorySideEffect = addSideEffect({
                       type: "fs:write_directory",
-                      value: { relativeUrl },
-                      label: `write directory "${relativeUrl}"`,
+                      value: { url: String(url) },
+                      label: renderLabel(`write directory "${url}"`),
                       text: null,
                     });
+                    // if directory ends up with something inside we'll not report
+                    // this side effect because:
+                    // - it was likely created to write the file
+                    // - the file creation will be reported and implies directory creation
+                    filesystemSpy.addBeforeUndoCallback(() => {
+                      try {
+                        const dirContent = readDirectorySync(url);
+                        if (dirContent.length) {
+                          writeDirectorySideEffect.skippable = true;
+                        }
+                      } catch (e) {}
+                    });
                   },
                 },
                 {
+                  include,
                   undoFilesystemSideEffects: !preserve,
                 },
               );
@@ -176,7 +282,7 @@ export const snapshotFunctionSideEffects = (
   ];
   const onSideEffectsCollected = (sideEffects) => {
     for (const callback of callbackSet) {
-      callback();
+      callback(sideEffects);
     }
     callbackSet.clear();
     sideEffectFileSnapshot.update(renderSideEffects(sideEffects), {

package/src/function_side_effects/group_file_side_effects_per_directory.js

@@ -0,0 +1,114 @@
+import { pathToFileURL } from "node:url";
+import { findCommonAncestorPath } from "./common_ancestor_path.js";
+
+export const groupFileSideEffectsPerDirectory = (
+  sideEffects,
+  { getFilesystemActionInfo },
+) => {
+  const groupArray = groupFileTogether(sideEffects);
+
+  const convertToPathname = (writeFileSideEffect) => {
+    return new URL(writeFileSideEffect.value.url).pathname;
+  };
+
+  for (const group of groupArray) {
+    if (group.id !== "file") {
+      continue;
+    }
+    const fileEffectArray = group.values;
+    if (fileEffectArray.length < 2) {
+      continue;
+    }
+    const commonAncestorPath = findCommonAncestorPath(
+      fileEffectArray,
+      convertToPathname,
+    );
+    const firstEffect = fileEffectArray[0];
+    const firstEffectIndex = sideEffects.indexOf(firstEffect);
+    const commonAncestorUrl = pathToFileURL(commonAncestorPath);
+    const numberOfFiles = fileEffectArray.length;
+    const { label } = getFilesystemActionInfo(
+      `write ${numberOfFiles} files into`,
+      commonAncestorUrl,
+    );
+    for (const fileEffect of fileEffectArray) {
+      sideEffects.splice(sideEffects.indexOf(fileEffect), 1);
+    }
+    sideEffects.splice(firstEffectIndex, 0, {
+      type: "fs:write_file",
+      label,
+    });
+  }
+};
+
+const groupBy = (array, groupCallback) => {
+  let i = 0;
+  const groupArray = [];
+  let currentGroup = null;
+  while (i < array.length) {
+    const value = array[i];
+    i++;
+    let ignoreCalled = false;
+    let ignore = () => {
+      ignoreCalled = true;
+    };
+    const groupId = groupCallback(value, { ignore });
+    if (ignoreCalled) {
+      continue;
+    }
+    if (currentGroup === null) {
+      currentGroup = {
+        id: groupId,
+        values: [value],
+      };
+      groupArray.push(currentGroup);
+      continue;
+    }
+    if (groupId === currentGroup.id) {
+      currentGroup.values.push(value);
+      continue;
+    }
+    currentGroup = {
+      id: groupId,
+      values: [value],
+    };
+    groupArray.push(currentGroup);
+  }
+  return groupArray;
+};
+
+const groupFileTogether = (sideEffects) =>
+  groupBy(sideEffects, (sideEffect, { ignore }) => {
+    if (sideEffect.type === "fs:write_directory") {
+      ignore();
+      return null;
+    }
+    if (sideEffect.type === "fs:write_file") {
+      return "file";
+    }
+    return "other";
+  });
+
+// const groups = groupFileTogether([
+//   {
+//     name: "a",
+//     type: "fs:write_file",
+//   },
+//   {
+//     name: "b",
+//     type: "fs:write_directory",
+//   },
+//   {
+//     name: "c",
+//     type: "fs:write_file",
+//   },
+//   {
+//     name: "d",
+//     type: "other",
+//   },
+//   {
+//     name: "e",
+//     type: "fs:write_file",
+//   },
+// ]);
+// debugger;

package/src/function_side_effects/spy_console_calls.js

@@ -1,7 +1,7 @@
 import { hookIntoMethod } from "./hook_into_method.js";
 
 export const spyConsoleCalls = (
-  { error, warn, info, log, trace },
+  { error, warn, info, log, trace, stdout, stderr },
   { preventConsoleSideEffects },
 ) => {
   const restoreCallbackSet = new Set();
@@ -45,12 +45,38 @@ export const spyConsoleCalls = (
       },
     };
   });
+  const processStdouthook = hookIntoMethod(
+    process.stdout,
+    "write",
+    (message) => {
+      return {
+        preventOriginalCall: preventConsoleSideEffects,
+        return: () => {
+          stdout(message);
+        },
+      };
+    },
+  );
+  const processStderrHhook = hookIntoMethod(
+    process.stderr,
+    "write",
+    (message) => {
+      return {
+        preventOriginalCall: preventConsoleSideEffects,
+        return: () => {
+          stderr(message);
+        },
+      };
+    },
+  );
   restoreCallbackSet.add(() => {
     errorHook.remove();
     warnHook.remove();
     infoHook.remove();
     logHook.remove();
     traceHook.remove();
+    processStdouthook.remove();
+    processStderrHhook.remove();
   });
   return {
     restore: () => {

package/src/function_side_effects/spy_filesystem_calls.js

@@ -3,8 +3,13 @@
 // https://github.com/tschaub/mock-fs/blob/6e84d5bb320022624c7d770432e3322323ce043e/lib/binding.js#L353
 // https://github.com/tschaub/mock-fs/issues/348
 
-import { removeDirectorySync, removeFileSync } from "@jsenv/filesystem";
-import { readFileSync, statSync, writeFileSync } from "node:fs";
+import {
+  removeDirectorySync,
+  removeFileSync,
+  writeFileSync,
+} from "@jsenv/filesystem";
+import { URL_META } from "@jsenv/url-meta";
+import { readFileSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import {
   disableHooksWhileCalling,
@@ -20,8 +25,12 @@ export const spyFilesystemCalls = (
     removeFile = () => {}, // TODO
     // removeDirectory = () => {},
   },
-  { undoFilesystemSideEffects } = {},
+  { include, undoFilesystemSideEffects } = {},
 ) => {
+  const shouldReport = include
+    ? URL_META.createFilter(include, "file:///")
+    : () => true;
+
   const _internalFs = process.binding("fs");
   const filesystemStateInfoMap = new Map();
   const fileDescriptorPathMap = new Map();
@@ -47,8 +56,10 @@ export const spyFilesystemCalls = (
           });
         }
       }
-      writeFile(fileUrl, stateAfter.content);
-      return;
+      if (shouldReport(fileUrl)) {
+        writeFile(fileUrl, stateAfter.content);
+        return;
+      }
     }
     // file is exactly the same
     // function did not have any effect on the file
@@ -65,8 +76,11 @@ export const spyFilesystemCalls = (
         });
       });
     }
-    writeDirectory(directoryUrl);
+    if (shouldReport(directoryUrl)) {
+      writeDirectory(directoryUrl);
+    }
   };
+  const beforeUndoCallbackSet = new Set();
   const restoreCallbackSet = new Set();
 
   const getFileStateWithinHook = (fileUrl) => {
@@ -166,11 +180,18 @@ export const spyFilesystemCalls = (
     unlinkHook.remove();
   });
   return {
+    addBeforeUndoCallback: (callback) => {
+      beforeUndoCallbackSet.add(callback);
+    },
     restore: () => {
       for (const restoreCallback of restoreCallbackSet) {
         restoreCallback();
       }
       restoreCallbackSet.clear();
+      for (const beforeUndoCallback of beforeUndoCallbackSet) {
+        beforeUndoCallback();
+      }
+      beforeUndoCallbackSet.clear();
       for (const [, restore] of fileRestoreMap) {
         restore();
       }

package/src/main.js

@@ -2,5 +2,6 @@ export {
   takeDirectorySnapshot,
   takeFileSnapshot,
 } from "./filesystem_snapshot.js";
+export { createReplaceFilesystemWellKnownValues } from "./filesystem_well_known_values.js";
 export { snapshotFunctionSideEffects } from "./function_side_effects/function_side_effects_snapshot.js";
 export { replaceFluctuatingValues } from "./replace_fluctuating_values.js";

package/src/replace_fluctuating_values.js

@@ -11,168 +11,56 @@ import {
   stringifyHtmlAst,
   visitHtmlNodes,
 } from "@jsenv/ast";
-import {
-  ensurePathnameTrailingSlash,
-  removePathnameTrailingSlash,
-  urlToExtension,
-} from "@jsenv/urls";
-import { escapeRegexpSpecialChars } from "@jsenv/utils/src/string/escape_regexp_special_chars.js";
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { urlToExtension } from "@jsenv/urls";
 import stripAnsi from "strip-ansi";
+import { createReplaceFilesystemWellKnownValues } from "./filesystem_well_known_values.js";
 
 export const replaceFluctuatingValues = (
   string,
   {
     stringType,
+    rootDirectoryUrl,
     fileUrl,
     removeAnsi = true,
-    rootDirectoryUrl,
-    // for unit tests
-    ancestorPackagesDisabled,
-    ancestorPackagesRootDirectoryUrl = "file:///",
-    homedirDisabled,
-    cwdPath = process.cwd(),
-    cwdUrl,
-    isWindows = process.platform === "win32",
+    // for unit test
+    replaceFilesystemWellKnownValues = createReplaceFilesystemWellKnownValues({
+      rootDirectoryUrl,
+    }),
   } = {},
 ) => {
-  const wellKownUrlArray = [];
-  const wellKnownPathArray = [];
-  const addWellKnownFileUrl = (url, replacement) => {
-    const urlWithoutTrailingSlash = removePathnameTrailingSlash(url);
-    wellKownUrlArray.push({
-      url: urlWithoutTrailingSlash,
-      replacement,
-      replace: (string) =>
-        string.replaceAll(urlWithoutTrailingSlash, replacement),
-    });
-    const path =
-      url === cwdUrl ? cwdPath : fileURLToPath(urlWithoutTrailingSlash);
-    const windowPathRegex = new RegExp(
-      `${escapeRegexpSpecialChars(path)}(((?:\\\\(?:[\\w !#()-]+|[.]{1,2})+)*)(?:\\\\)?)`,
-      "gm",
-    );
-    const pathReplacement = replacement.startsWith("file:///")
-      ? replacement.slice("file:///".length)
-      : replacement;
-    wellKnownPathArray.push({
-      path,
-      replacement: pathReplacement,
-      replace: isWindows
-        ? (string) => {
-            return string.replaceAll(windowPathRegex, (match, after) => {
-              return `${pathReplacement}${after.replaceAll("\\", "/")}`;
-            });
-          }
-        : (string) => string.replaceAll(path, pathReplacement),
-    });
-  };
-  if (rootDirectoryUrl) {
-    addWellKnownFileUrl(rootDirectoryUrl, "file:///<root>");
-  }
-  /*
-   * When running code inside a node project ancestor packages
-   * should make things super predictible because
-   * it will use a package.json name field
-   * to replace files urls
-   * And uses the highest ancestor package so that even if the file
-   * is executed once within a package then outside that package
-   * the replace value remains predictible as the highest package is used
-   * The highest package is used because it's pushed first by
-   * addWellKnownFileUrl
-   */
-  ancestor_packages: {
-    if (ancestorPackagesDisabled) {
-      break ancestor_packages;
-    }
-    const ancestorPackages = [];
-    const cwd = cwdPath || process.cwd();
-    const cwdUrl = ensurePathnameTrailingSlash(pathToFileURL(cwd));
-    let currentUrl = cwdUrl;
-    while (currentUrl.href !== ancestorPackagesRootDirectoryUrl) {
-      const packageFileUrl = new URL("package.json", currentUrl);
-      const packageDirectoryUrl = currentUrl;
-      currentUrl = new URL(getParentUrl(currentUrl));
-      let packageFileContent;
-      try {
-        packageFileContent = readFileSync(packageFileUrl);
-      } catch (e) {
-        if (e.code === "ENOENT") {
-          continue;
-        }
-        throw e;
-      }
-      let packageObject;
-      try {
-        packageObject = JSON.parse(packageFileContent);
-      } catch (e) {
-        continue;
-      }
-      const packageName = packageObject.name;
-      ancestorPackages.unshift({
-        packageDirectoryUrl,
-        packageName,
-      });
-    }
-    for (const ancestorPackage of ancestorPackages) {
-      addWellKnownFileUrl(
-        ancestorPackage.packageDirectoryUrl,
-        ancestorPackage.packageName,
-      );
-    }
-  }
-  home_dir: {
-    if (!homedirDisabled) {
-      const homedirPath = homedir();
-      const homedirUrl = pathToFileURL(homedirPath);
-      addWellKnownFileUrl(homedirUrl, "file:///~");
+  if (fileUrl && stringType === undefined) {
+    const extension = urlToExtension(fileUrl);
+    if (extension === ".html") {
+      stringType = "html";
+    } else if (extension === ".svg") {
+      stringType = "svg";
     }
   }
-  process_cwd: {
-    // we fallback on process.cwd()
-    // but it's brittle because a file might be execute from anywhere
-    // so it should be the last resort
-    cwdUrl = cwdUrl || pathToFileURL(cwdPath);
-    addWellKnownFileUrl(cwdUrl, "file:///cwd()");
-  }
-  const replaceFileUrls = (value) => {
-    for (const wellKownUrl of wellKownUrlArray) {
-      const replaceResult = wellKownUrl.replace(value);
-      if (replaceResult !== value) {
-        return replaceResult;
-      }
-    }
-    return value;
-  };
-  const replaceFilePaths = (value) => {
-    for (const wellKownPath of wellKnownPathArray) {
-      const replaceResult = wellKownPath.replace(value);
-      if (replaceResult !== value) {
-        return replaceResult;
-      }
-    }
+  const replaceDurations = (value) => {
+    // https://stackoverflow.com/a/59202307/24573072
+    value = value.replace(
+      /(?<!\d|\.)\d+(?:\.\d+)?(\s*)(seconds|second|s)\b/g,
+      (match, space, unit) => {
+        if (unit === "seconds") unit = "second";
+        return `<X>${space}${unit}`;
+      },
+    );
     return value;
   };
   const replaceThings = (value) => {
+    if (stringType === "filesystem") {
+      return replaceFilesystemWellKnownValues(value);
+    }
     if (removeAnsi) {
       value = stripAnsi(value);
     }
-    value = replaceFileUrls(value);
-    value = replaceFilePaths(value);
+    value = replaceFilesystemWellKnownValues(value, {
+      willBeWrittenOnFilesystem: false,
+    });
     value = replaceHttpUrls(value);
+    value = replaceDurations(value);
     return value;
   };
-
-  if (fileUrl && stringType === undefined) {
-    const extension = urlToExtension(fileUrl);
-    if (extension === ".html") {
-      stringType = "html";
-    } else if (extension === ".svg") {
-      stringType = "svg";
-    }
-  }
   if (stringType === "html") {
     // do parse html
     const htmlAst =
@@ -204,27 +92,6 @@ export const replaceFluctuatingValues = (
   return replaceThings(string);
 };
 
-const getParentUrl = (url) => {
-  url = String(url);
-  // With node.js new URL('../', 'file:///C:/').href
-  // returns "file:///C:/" instead of "file:///"
-  const resource = url.slice("file://".length);
-  const slashLastIndex = resource.lastIndexOf("/");
-  if (slashLastIndex === -1) {
-    return url;
-  }
-  const lastCharIndex = resource.length - 1;
-  if (slashLastIndex === lastCharIndex) {
-    const slashBeforeLastIndex = resource.lastIndexOf("/", slashLastIndex - 1);
-    if (slashBeforeLastIndex === -1) {
-      return url;
-    }
-    return `file://${resource.slice(0, slashBeforeLastIndex + 1)}`;
-  }
-
-  return `file://${resource.slice(0, slashLastIndex + 1)}`;
-};
-
 const replaceHttpUrls = (source) => {
   return source.replace(/(?:https?|ftp):\/\/\S+[\w/]/g, (match) => {
     const lastChar = match[match.length - 1];