@jsenv/snapshot 2.6.6 → 2.6.8

package/src/side_effects/filesystem/filesystem_side_effects.js

@@ -0,0 +1,323 @@
+import { setUrlBasename, urlIsInsideOf, urlToRelativeUrl } from "@jsenv/urls";
+import { CONTENT_TYPE } from "@jsenv/utils/src/content_type/content_type.js";
+import { pathToFileURL } from "node:url";
+import { createWellKnown } from "../../filesystem_well_known_values.js";
+import { renderFileContent } from "../render_side_effects.js";
+import { groupFileSideEffectsPerDirectory } from "./group_file_side_effects_per_directory.js";
+import { spyFilesystemCalls } from "./spy_filesystem_calls.js";
+
+const filesystemSideEffectsOptionsDefault = {
+  include: null,
+  preserve: false,
+  baseDirectory: "",
+  textualFilesIntoDirectory: false,
+};
+const INLINE_MAX_LINES = 20;
+const INLINE_MAX_LENGTH = 2000;
+
+export const filesystemSideEffects = (
+  filesystemSideEffectsOptions,
+  { replaceFilesystemWellKnownValues },
+) => {
+  filesystemSideEffectsOptions = {
+    ...filesystemSideEffectsOptionsDefault,
+    ...filesystemSideEffectsOptions,
+  };
+  let baseDirectory;
+  let removeBaseDirectoryWellKnown = () => {};
+  const setBaseDirectory = (value) => {
+    removeBaseDirectoryWellKnown();
+    baseDirectory = value;
+    if (baseDirectory) {
+      removeBaseDirectoryWellKnown =
+        replaceFilesystemWellKnownValues.addWellKnownFileUrl(
+          baseDirectory,
+          createWellKnown("base"),
+          { position: "start" },
+        );
+    }
+  };
+
+  return {
+    name: "filesystem",
+    setBaseDirectory,
+    install: (addSideEffect, { addSkippableHandler, addFinallyCallback }) => {
+      let { include, preserve, textualFilesIntoDirectory } =
+        filesystemSideEffectsOptions;
+      if (filesystemSideEffectsOptions.baseDirectory) {
+        setBaseDirectory(filesystemSideEffectsOptions.baseDirectory);
+      }
+      const getUrlRelativeToBase = (url) => {
+        if (baseDirectory) {
+          return urlToRelativeUrl(url, baseDirectory, {
+            preferRelativeNotation: true,
+          });
+        }
+        return url;
+      };
+      const getUrlInsideOutDirectory = (url, outDirectoryUrl) => {
+        if (baseDirectory) {
+          if (
+            url.href === baseDirectory.href ||
+            urlIsInsideOf(url, baseDirectory)
+          ) {
+            const outRelativeUrl = urlToRelativeUrl(url, baseDirectory);
+            return new URL(outRelativeUrl, outDirectoryUrl);
+          }
+        }
+        // otherwise we replace the url with well known
+        const toRelativeUrl = replaceFilesystemWellKnownValues(url);
+        return new URL(toRelativeUrl, outDirectoryUrl);
+      };
+
+      addSkippableHandler((sideEffect) => {
+        // 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
+        if (sideEffect.code === "write_directory") {
+          return (nextSideEffect, { skip, stop }) => {
+            if (
+              (nextSideEffect.code === "write_file" ||
+                nextSideEffect.code === "write_directory") &&
+              urlIsInsideOf(nextSideEffect.value.url, sideEffect.value.url)
+            ) {
+              skip();
+              stop();
+              return;
+            }
+            if (
+              nextSideEffect.code === "remove_directory" &&
+              nextSideEffect.value.url === sideEffect.value.url
+            ) {
+              stop();
+              return;
+            }
+          };
+        }
+        return null;
+      });
+      addSkippableHandler((sideEffect) => {
+        // on llinux writing to a file with the same content
+        // is ignored somehow
+        // let's make this consistent on other platforms
+        if (sideEffect.code === "write_file") {
+          return (nextSideEffect, { skip, stop }) => {
+            if (
+              nextSideEffect.code === "write_file" &&
+              nextSideEffect.value.url === sideEffect.value.url &&
+              !Buffer.compare(
+                nextSideEffect.value.buffer,
+                sideEffect.value.buffer,
+              )
+            ) {
+              skip();
+            }
+            stop();
+          };
+        }
+        return null;
+      });
+
+      addFinallyCallback((sideEffects) => {
+        // gather all file side effect next to each other
+        // collapse them if they have a shared ancestor
+        groupFileSideEffectsPerDirectory(sideEffects, {
+          createWriteFileGroupSideEffect: (fileSideEffectArray, commonPath) => {
+            let commonUrl = pathToFileURL(commonPath);
+            let commonDirectoryUrl;
+            if (commonUrl.href.endsWith("/")) {
+              commonDirectoryUrl = commonUrl;
+            } else {
+              commonDirectoryUrl = new URL("./", commonUrl);
+            }
+
+            return {
+              code: "write_file_group",
+              type: `write_file_group ${commonDirectoryUrl}`,
+              value: {},
+              render: {
+                md: (options) => {
+                  let allFilesInsideOutDirectory = true;
+                  let groupMd = "";
+                  let numberOfFiles = 0;
+                  for (const fileSideEffect of fileSideEffectArray) {
+                    numberOfFiles++;
+                    if (groupMd) {
+                      groupMd += "\n\n";
+                    }
+                    const { url, outDirectoryReason } = fileSideEffect.value;
+                    const { text } = fileSideEffect.render.md(options);
+                    const urlRelativeToCommonDirectory = urlToRelativeUrl(
+                      url,
+                      commonDirectoryUrl,
+                    );
+                    if (outDirectoryReason) {
+                      const outUrlRelativeToCommonDirectory = urlToRelativeUrl(
+                        text.urlInsideOutDirectory,
+                        options.sideEffectFileUrl,
+                      );
+                      groupMd += `${"#".repeat(2)} ${urlRelativeToCommonDirectory}
+${renderFileContent(
+  {
+    ...text,
+    relativeUrl: urlRelativeToCommonDirectory,
+    outRelativeUrl: outUrlRelativeToCommonDirectory,
+  },
+  {
+    ...options,
+    sideEffect: fileSideEffect,
+  },
+)}`;
+                      continue;
+                    }
+                    allFilesInsideOutDirectory = false;
+                    groupMd += `${"#".repeat(2)} ${urlRelativeToCommonDirectory}
+${renderFileContent(
+  {
+    ...text,
+    relativeUrl: urlRelativeToCommonDirectory,
+  },
+  {
+    ...options,
+    sideEffect: fileSideEffect,
+  },
+)}`;
+                  }
+                  const commonDirectoryRelativeUrl =
+                    getUrlRelativeToBase(commonDirectoryUrl);
+                  if (allFilesInsideOutDirectory) {
+                    const commonDirectoryOutUrl = getUrlInsideOutDirectory(
+                      commonDirectoryUrl,
+                      options.outDirectoryUrl,
+                    );
+                    const commonDirectoryOutRelativeUrl = urlToRelativeUrl(
+                      commonDirectoryOutUrl,
+                      options.sideEffectFileUrl,
+                      { preferRelativeNotation: true },
+                    );
+                    return {
+                      label: `write ${numberOfFiles} files into "${commonDirectoryRelativeUrl}"`,
+                      text: `see [${commonDirectoryOutRelativeUrl}](${commonDirectoryOutRelativeUrl})`,
+                    };
+                  }
+                  return {
+                    label: `write ${numberOfFiles} files into "${commonDirectoryRelativeUrl}"`,
+                    text: groupMd,
+                  };
+                },
+              },
+            };
+          },
+        });
+      });
+
+      const filesystemSpy = spyFilesystemCalls(
+        {
+          onWriteFile: (url, buffer) => {
+            const contentType = CONTENT_TYPE.fromUrlExtension(url);
+            const isTextual = CONTENT_TYPE.isTextual(contentType);
+            let outDirectoryReason;
+            if (isTextual) {
+              if (textualFilesIntoDirectory) {
+                outDirectoryReason = "textual_in_directory_option";
+              } else if (String(buffer).split("\n").length > INLINE_MAX_LINES) {
+                outDirectoryReason = "lot_of_lines";
+              } else if (buffer.size > INLINE_MAX_LENGTH) {
+                outDirectoryReason = "lot_of_chars";
+              }
+            } else {
+              outDirectoryReason = "binary";
+            }
+            const writeFileSideEffect = {
+              code: "write_file",
+              type: `write_file:${url}`,
+              value: {
+                url,
+                buffer,
+                contentType,
+                isTextual,
+                outDirectoryReason,
+              },
+              render: {
+                md: ({ sideEffectFileUrl, outDirectoryUrl }) => {
+                  const urlRelativeToBase = getUrlRelativeToBase(url);
+                  if (outDirectoryReason) {
+                    const urlInsideOutDirectory = getUrlInsideOutDirectory(
+                      url,
+                      outDirectoryUrl,
+                    );
+                    if (writeFileSideEffect.counter) {
+                      setUrlBasename(
+                        urlInsideOutDirectory,
+                        (basename) =>
+                          `${basename}_${writeFileSideEffect.counter}`,
+                      );
+                    }
+                    let textValue;
+                    if (outDirectoryReason === "lot_of_chars") {
+                      textValue = String(buffer.slice(0, INLINE_MAX_LENGTH));
+                    } else if (outDirectoryReason === "lot_of_lines") {
+                      textValue = String(buffer)
+                        .split("\n")
+                        .slice(0, INLINE_MAX_LINES)
+                        .join("\n");
+                    } else {
+                      textValue = buffer;
+                    }
+                    const outRelativeUrl = urlToRelativeUrl(
+                      urlInsideOutDirectory,
+                      sideEffectFileUrl,
+                      {
+                        preferRelativeNotation: true,
+                      },
+                    );
+                    return {
+                      label: `write file "${urlRelativeToBase}"`,
+                      text: {
+                        type: "file_content",
+                        value: textValue,
+                        relativeUrl: urlRelativeToBase,
+                        outRelativeUrl,
+                        urlInsideOutDirectory,
+                      },
+                    };
+                  }
+                  return {
+                    label: `write file "${urlRelativeToBase}"`,
+                    text: {
+                      type: "file_content",
+                      value: String(buffer),
+                    },
+                  };
+                },
+              },
+            };
+            addSideEffect(writeFileSideEffect);
+          },
+          onWriteDirectory: (url) => {
+            addSideEffect({
+              code: "write_directory",
+              type: `write_directory:${url}`,
+              value: { url },
+              render: {
+                md: () => {
+                  return {
+                    label: `write directory "${getUrlRelativeToBase(url)}"`,
+                  };
+                },
+              },
+            });
+          },
+        },
+        {
+          include,
+          undoFilesystemSideEffects: !preserve,
+        },
+      );
+      return () => {
+        filesystemSpy.restore();
+      };
+    },
+  };
+};

package/src/side_effects/filesystem/group_file_side_effects_per_directory.js

@@ -0,0 +1,30 @@
+import { groupSideEffectsPer, IGNORE } from "../utils/group_side_effects.js";
+import { findCommonAncestorPath } from "./common_ancestor_path.js";
+
+export const groupFileSideEffectsPerDirectory = (
+  allSideEffects,
+  { createWriteFileGroupSideEffect },
+) => {
+  return groupSideEffectsPer(
+    allSideEffects,
+    (sideEffect) => {
+      if (sideEffect.code === "write_directory") {
+        return IGNORE;
+      }
+      return sideEffect.code === "write_file";
+    },
+    {
+      createGroupSideEffect: (sideEffects) => {
+        const commonAncestorPath = findCommonAncestorPath(
+          sideEffects,
+          convertToPathname,
+        );
+        return createWriteFileGroupSideEffect(sideEffects, commonAncestorPath);
+      },
+    },
+  );
+};
+
+const convertToPathname = (writeFileSideEffect) => {
+  return new URL(writeFileSideEffect.value.url).pathname;
+};

package/src/{function_side_effects → side_effects/filesystem}/spy_filesystem_calls.js

@@ -9,20 +9,21 @@ import {
   writeFileSync,
 } from "@jsenv/filesystem";
 import { URL_META } from "@jsenv/url-meta";
+import { yieldAncestorUrls } from "@jsenv/urls";
 import { readFileSync, statSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import {
   disableHooksWhileCalling,
   hookIntoMethod,
   METHOD_EXECUTION_NODE_CALLBACK,
-} from "./hook_into_method.js";
+} from "../hook_into_method.js";
 
 export const spyFilesystemCalls = (
   {
-    readFile = () => {}, // TODO
-    writeFile = () => {},
-    writeDirectory = () => {},
-    removeFile = () => {}, // TODO
+    onReadFile = () => {}, // TODO
+    onWriteFile = () => {},
+    onWriteDirectory = () => {},
+    onRemoveFile = () => {}, // TODO
     // removeDirectory = () => {},
   },
   { include, undoFilesystemSideEffects } = {},
@@ -40,15 +41,19 @@ export const spyFilesystemCalls = (
     // - writing file for the 1st time
     // - updating file content
     // the important part is the file content in the end of the function execution
-    if (
-      (!stateBefore.found && stateAfter.found) ||
-      stateBefore.content !== stateAfter.content ||
-      stateBefore.mtimeMs !== stateAfter.mtimeMs
-    ) {
+    const reason =
+      !stateBefore.found && stateAfter.found
+        ? "created"
+        : Buffer.compare(stateBefore.buffer, stateAfter.buffer)
+          ? "content_modified"
+          : stateBefore.mtimeMs === stateAfter.mtimeMs
+            ? ""
+            : "mtime_modified";
+    if (reason) {
       if (undoFilesystemSideEffects && !fileRestoreMap.has(fileUrl)) {
         if (stateBefore.found) {
           fileRestoreMap.set(fileUrl, () => {
-            writeFileSync(fileUrl, stateBefore.content);
+            writeFileSync(fileUrl, stateBefore.buffer);
           });
         } else {
           fileRestoreMap.set(fileUrl, () => {
@@ -57,17 +62,14 @@ export const spyFilesystemCalls = (
         }
       }
       if (shouldReport(fileUrl)) {
-        writeFile(fileUrl, stateAfter.content);
+        onWriteFile(fileUrl, stateAfter.buffer, reason);
         return;
       }
     }
     // file is exactly the same
     // function did not have any effect on the file
   };
-  const onWriteDirectoryDone = (directoryUrl, stateBefore) => {
-    if (stateBefore.found) {
-      return;
-    }
+  const onWriteDirectoryDone = (directoryUrl) => {
     if (undoFilesystemSideEffects && !fileRestoreMap.has(directoryUrl)) {
       fileRestoreMap.set(directoryUrl, () => {
         removeDirectorySync(directoryUrl, {
@@ -77,7 +79,7 @@ export const spyFilesystemCalls = (
       });
     }
     if (shouldReport(directoryUrl)) {
-      writeDirectory(directoryUrl);
+      onWriteDirectory(directoryUrl);
     }
   };
   const beforeUndoCallbackSet = new Set();
@@ -93,13 +95,34 @@ export const spyFilesystemCalls = (
   const mkdirHook = hookIntoMethod(
     _internalFs,
     "mkdir",
-    (directoryPath) => {
+    (directoryPath, mode, recursive) => {
       const directoryUrl = pathToFileURL(directoryPath);
       const stateBefore = getDirectoryState(directoryPath);
+      if (!stateBefore.found && recursive) {
+        const ancestorNotFoundArray = [];
+        for (const ancestorUrl of yieldAncestorUrls(directoryUrl)) {
+          const ancestorState = getDirectoryState(new URL(ancestorUrl));
+          if (ancestorState.found) {
+            break;
+          }
+          ancestorNotFoundArray.unshift(ancestorUrl);
+        }
+        return {
+          return: (fd) => {
+            fileDescriptorPathMap.set(fd, directoryPath);
+            for (const ancestorNotFoundUrl of ancestorNotFoundArray) {
+              onWriteDirectoryDone(ancestorNotFoundUrl);
+            }
+            onWriteDirectoryDone(String(directoryUrl));
+          },
+        };
+      }
       return {
         return: (fd) => {
           fileDescriptorPathMap.set(fd, directoryPath);
-          onWriteDirectoryDone(directoryUrl, stateBefore, { found: true });
+          if (!stateBefore.found) {
+            onWriteDirectoryDone(String(directoryUrl));
+          }
         },
       };
     },
@@ -140,12 +163,12 @@ export const spyFilesystemCalls = (
           }
           const fileUrl = pathToFileURL(filePath);
           if (buffer) {
-            readFile(fileUrl);
+            onReadFile(String(fileUrl));
           }
           fileDescriptorPathMap.delete(fileDescriptor);
           filesystemStateInfoMap.delete(filePath);
           const stateAfter = getFileStateWithinHook(fileUrl);
-          onWriteFileDone(fileUrl, stateBefore, stateAfter);
+          onWriteFileDone(String(fileUrl), stateBefore, stateAfter);
         },
       };
     },
@@ -160,7 +183,7 @@ export const spyFilesystemCalls = (
       return {
         return: () => {
           const stateAfter = getFileStateWithinHook(fileUrl);
-          onWriteFileDone(fileUrl, stateBefore, stateAfter);
+          onWriteFileDone(String(fileUrl), stateBefore, stateAfter);
         },
       };
     },
@@ -168,7 +191,7 @@ export const spyFilesystemCalls = (
   const unlinkHook = hookIntoMethod(_internalFs, "unlink", (filePath) => {
     return {
       return: () => {
-        removeFile(filePath); // TODO eventually split in removeFile/removeDirectory
+        onRemoveFile(filePath); // TODO eventually split in removeFile/removeDirectory
       },
     };
   });
@@ -202,12 +225,12 @@ export const spyFilesystemCalls = (
 
 const getFileState = (file) => {
   try {
-    const fileContent = readFileSync(file);
+    const fileBuffer = readFileSync(file);
     const { mtimeMs } = statSync(file);
     return {
       found: true,
       mtimeMs,
-      content: String(fileContent),
+      buffer: fileBuffer,
     };
   } catch (e) {
     if (e.code === "ENOENT") {

package/src/side_effects/log/group_log_side_effects.js

@@ -0,0 +1,29 @@
+import { groupSideEffectsPer } from "../utils/group_side_effects.js";
+
+export const groupLogSideEffects = (
+  allSideEffects,
+  { createLogGroupSideEffect },
+) => {
+  return groupSideEffectsPer(
+    allSideEffects,
+    (sideEffect) => {
+      if (
+        sideEffect.code === "console.trace" ||
+        sideEffect.code === "console.log" ||
+        sideEffect.code === "console.info" ||
+        sideEffect.code === "console.warn" ||
+        sideEffect.code === "console.error" ||
+        sideEffect.code === "process.stdout" ||
+        sideEffect.code === "process.stderr"
+      ) {
+        return true;
+      }
+      return false;
+    },
+    {
+      createGroupSideEffect: (sideEffects) => {
+        return createLogGroupSideEffect(sideEffects);
+      },
+    },
+  );
+};

package/src/side_effects/log/log_side_effects.js

@@ -0,0 +1,156 @@
+import { hookIntoMethod } from "../hook_into_method.js";
+import { renderConsole } from "../render_side_effects.js";
+import { groupLogSideEffects } from "./group_log_side_effects.js";
+
+const logSideEffectsOptionsDefault = {
+  prevent: true,
+  group: false,
+};
+
+export const logSideEffects = (logSideEffectsOptions) => {
+  logSideEffectsOptions = {
+    ...logSideEffectsOptionsDefault,
+    ...logSideEffectsOptions,
+  };
+  return {
+    name: "console",
+    install: (addSideEffect, { addFinallyCallback }) => {
+      const { prevent, group } = logSideEffectsOptions;
+      if (group) {
+        addFinallyCallback((sideEffects) => {
+          groupLogSideEffects(sideEffects, {
+            createLogGroupSideEffect: (logSideEffectArray) => {
+              const logGroupSideEffect = {
+                code: "log_group",
+                type: `log_group`,
+                value: {},
+                render: {
+                  md: (options) => {
+                    const renderLogGroup = () => {
+                      let logs = "";
+                      let i = 0;
+                      while (i < logSideEffectArray.length) {
+                        const logSideEffect = logSideEffectArray[i];
+                        i++;
+                        const { text } = logSideEffect.render.md(options);
+                        logs += text.value;
+                        if (
+                          i !== logSideEffectArray.length &&
+                          logSideEffect.type.startsWith("console")
+                        ) {
+                          logs += "\n";
+                        }
+                      }
+                      const logGroupMd = renderConsole(logs, {
+                        sideEffect: logGroupSideEffect,
+                        ...options,
+                      });
+                      return logGroupMd;
+                    };
+                    return {
+                      label: `logs`,
+                      text: renderLogGroup(),
+                    };
+                  },
+                },
+              };
+              return logGroupSideEffect;
+            },
+          });
+        });
+      }
+      const addLogSideEffect = (type, message) => {
+        addSideEffect({
+          code: type,
+          type,
+          value: message,
+          render: {
+            md: () => {
+              return {
+                label: type,
+                text: {
+                  type: "console",
+                  value: message,
+                },
+              };
+            },
+          },
+        });
+      };
+
+      const errorHook = hookIntoMethod(console, "error", (message) => {
+        return {
+          preventOriginalCall: prevent,
+          return: () => {
+            addLogSideEffect("console.error", message);
+          },
+        };
+      });
+      const warnHook = hookIntoMethod(console, "warn", (message) => {
+        return {
+          preventOriginalCall: prevent,
+          return: () => {
+            addLogSideEffect("console.warn", message);
+          },
+        };
+      });
+      const infoHook = hookIntoMethod(console, "info", (message) => {
+        return {
+          preventOriginalCall: prevent,
+          return: () => {
+            addLogSideEffect("console.info", message);
+          },
+        };
+      });
+      const logHook = hookIntoMethod(console, "log", (message) => {
+        return {
+          preventOriginalCall: prevent,
+          return: () => {
+            addLogSideEffect("console.log", message);
+          },
+        };
+      });
+      const traceHook = hookIntoMethod(console, "trace", (message) => {
+        return {
+          preventOriginalCall: prevent,
+          return: () => {
+            addLogSideEffect("console.trace", message);
+          },
+        };
+      });
+      const processStdouthook = hookIntoMethod(
+        process.stdout,
+        "write",
+        (message) => {
+          return {
+            preventOriginalCall: prevent,
+            return: () => {
+              addLogSideEffect("process.stdout", message);
+            },
+          };
+        },
+      );
+      const processStderrHhook = hookIntoMethod(
+        process.stderr,
+        "write",
+        (message) => {
+          return {
+            preventOriginalCall: prevent,
+            return: () => {
+              addLogSideEffect("process.stderr", message);
+            },
+          };
+        },
+      );
+      return () => {
+        errorHook.remove();
+        warnHook.remove();
+        infoHook.remove();
+        logHook.remove();
+        traceHook.remove();
+        processStdouthook.remove();
+        processStderrHhook.remove();
+      };
+    },
+  };
+};