@jsenv/snapshot 2.6.5 → 2.6.7

package/src/function_side_effects/function_side_effects_collector.js

@@ -1,160 +0,0 @@
-import { createException } from "@jsenv/exception";
-import { replaceFluctuatingValues } from "../replace_fluctuating_values.js";
-import { wrapIntoMarkdownBlock } from "./function_side_effects_renderer.js";
-
-const RETURN_PROMISE = {};
-
-let functionExecutingCount = 0;
-
-export const collectFunctionSideEffects = (
-  fn,
-  sideEffectDetectors,
-  { rootDirectoryUrl },
-) => {
-  const sideEffects = [];
-  const addSideEffect = (sideEffect) => {
-    sideEffects.push(sideEffect);
-    return sideEffect;
-  };
-  const finallyCallbackSet = new Set();
-  for (const sideEffectDetector of sideEffectDetectors) {
-    const uninstall = sideEffectDetector.install(addSideEffect);
-    finallyCallbackSet.add(() => {
-      uninstall();
-    });
-  }
-  if (functionExecutingCount) {
-    // The reason for this warning:
-    // 1. fs side effect detectors is not yet fully compatible with that because
-    //    callback.oncomplete redefinition might be wrong for open, mkdir etc
-    //    (at least this is to be tested)
-    // 2. It's usually a sign code forgets to put await in front of
-    //    collectFunctionSideEffects or snapshotFunctionSideEffects
-    // 3. collectFunctionSideEffects is meant to collect a function side effect
-    //    during unit test. So in unit test the function being tested should be analyized
-    //    and should not in turn analyze an other one
-    console.warn(
-      `collectFunctionSideEffects called while other function(s) side effects are collected`,
-    );
-  }
-
-  const onCatch = (valueThrow) => {
-    sideEffects.push({
-      type: "throw",
-      value: valueThrow,
-      label: "throw",
-      text: wrapIntoMarkdownBlock(
-        renderValueThrownOrRejected(
-          createException(valueThrow, { rootDirectoryUrl }),
-          { rootDirectoryUrl },
-        ),
-      ),
-    });
-  };
-  const onReturn = (valueReturned) => {
-    if (valueReturned === RETURN_PROMISE) {
-      sideEffects.push({
-        type: "return",
-        value: valueReturned,
-        label: "return promise",
-        text: null,
-      });
-    } else {
-      sideEffects.push({
-        type: "return",
-        value: valueReturned,
-        label: "return",
-        text: wrapIntoMarkdownBlock(
-          renderReturnValueOrResolveValue(valueReturned, {
-            rootDirectoryUrl,
-          }),
-          "js",
-        ),
-      });
-    }
-  };
-  const onResolve = (value) => {
-    sideEffects.push({
-      type: "resolve",
-      value,
-      label: "resolve",
-      text: wrapIntoMarkdownBlock(
-        renderReturnValueOrResolveValue(value, { rootDirectoryUrl }),
-        "js",
-      ),
-    });
-  };
-  const onReject = (reason) => {
-    sideEffects.push({
-      type: "reject",
-      value: reason,
-      label: "reject",
-      text: wrapIntoMarkdownBlock(
-        renderValueThrownOrRejected(
-          createException(reason, { rootDirectoryUrl }),
-          { rootDirectoryUrl },
-        ),
-      ),
-    });
-  };
-  const onFinally = () => {
-    delete process.env.SNAPSHOTING_FUNCTION_SIDE_EFFECTS;
-    functionExecutingCount--;
-    for (const finallyCallback of finallyCallbackSet) {
-      finallyCallback();
-    }
-    finallyCallbackSet.clear();
-  };
-
-  process.env.SNAPSHOTING_FUNCTION_SIDE_EFFECTS = "1";
-  functionExecutingCount++;
-  let returnedPromise = false;
-  try {
-    const valueReturned = fn();
-    if (valueReturned && typeof valueReturned.then === "function") {
-      onReturn(RETURN_PROMISE);
-      returnedPromise = valueReturned.then(
-        (value) => {
-          onResolve(value);
-          onFinally();
-          return sideEffects;
-        },
-        (e) => {
-          onReject(e);
-          onFinally();
-          return sideEffects;
-        },
-      );
-      return returnedPromise;
-    }
-    onReturn(valueReturned);
-    return sideEffects;
-  } catch (e) {
-    onCatch(e);
-    return sideEffects;
-  } finally {
-    if (!returnedPromise) {
-      onFinally();
-    }
-  }
-};
-
-const renderReturnValueOrResolveValue = (value, { rootDirectoryUrl }) => {
-  if (value === undefined) {
-    return "undefined";
-  }
-  return replaceFluctuatingValues(JSON.stringify(value, null, "  "), {
-    stringType: "json",
-    rootDirectoryUrl,
-  });
-};
-
-const renderValueThrownOrRejected = (value, { rootDirectoryUrl }) => {
-  return replaceFluctuatingValues(
-    value ? value.stack || value.message || value : String(value),
-    {
-      stringType: "error",
-      rootDirectoryUrl,
-    },
-  );
-};

package/src/function_side_effects/function_side_effects_renderer.js

@@ -1,29 +0,0 @@
-export const renderSideEffects = (sideEffects) => {
-  let string = "";
-  let index = 0;
-  for (const sideEffect of sideEffects) {
-    if (sideEffect.skippable) {
-      continue;
-    }
-    if (string) {
-      string += "\n\n";
-    }
-    let label = `${index + 1}. ${sideEffect.label}`;
-    let text = sideEffect.text;
-    string += label;
-    if (text) {
-      string += "\n";
-      string += text;
-    }
-    index++;
-  }
-  return string;
-};
-
-export const wrapIntoMarkdownBlock = (value, blockName = "") => {
-  const start = "```";
-  const end = "```";
-  return `${start}${blockName}
-${value}
-${end}`;
-};

package/src/function_side_effects/function_side_effects_snapshot.js

@@ -1,302 +0,0 @@
-import { readDirectorySync, writeFileSync } from "@jsenv/filesystem";
-import {
-  ensurePathnameTrailingSlash,
-  urlIsInsideOf,
-  urlToExtension,
-  urlToRelativeUrl,
-} from "@jsenv/urls";
-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";
-
-const filesystemEffectsDefault = {
-  outDirectory: null,
-  preserve: false,
-};
-const consoleEffectsDefault = {
-  prevent: true,
-};
-
-export const snapshotFunctionSideEffects = (
-  fn,
-  sideEffectFileUrl,
-  { consoleEffects = true, filesystemEffects = true, rootDirectoryUrl } = {},
-) => {
-  if (consoleEffects === true) {
-    consoleEffects = {};
-  }
-  if (filesystemEffects === true) {
-    filesystemEffects = {};
-  }
-  const replaceFilesystemWellKnownValues =
-    createReplaceFilesystemWellKnownValues({
-      rootDirectoryUrl,
-    });
-  const sideEffectFileSnapshot = takeFileSnapshot(sideEffectFileUrl);
-  const callbackSet = new Set();
-  const sideEffectDetectors = [
-    ...(consoleEffects
-      ? [
-          {
-            name: "console",
-            install: (addSideEffect) => {
-              consoleEffects = { ...consoleEffectsDefault, ...consoleEffects };
-              const { prevent } = consoleEffects;
-              const onConsole = (methodName, message) => {
-                addSideEffect({
-                  type: `console:${methodName}`,
-                  value: message,
-                  label: `console.${methodName}`,
-                  text: wrapIntoMarkdownBlock(
-                    replaceFluctuatingValues(message, {
-                      stringType: "console",
-                      replaceFilesystemWellKnownValues,
-                    }),
-                    "console",
-                  ),
-                });
-              };
-              const consoleSpy = spyConsoleCalls(
-                {
-                  error: (message) => {
-                    onConsole("error", message);
-                  },
-                  warn: (message) => {
-                    onConsole("warn", message);
-                  },
-                  info: (message) => {
-                    onConsole("info", message);
-                  },
-                  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,
-                },
-              );
-              return () => {
-                consoleSpy.restore();
-              };
-            },
-          },
-        ]
-      : []),
-    ...(filesystemEffects
-      ? [
-          {
-            name: "filesystem",
-            install: (addSideEffect) => {
-              filesystemEffects = {
-                ...filesystemEffectsDefault,
-                ...filesystemEffects,
-              };
-              let writeFile;
-              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),
-                );
-                const fsEffectsOutDirectorySnapshot = takeDirectorySnapshot(
-                  fsEffectsOutDirectoryUrl,
-                );
-                const writeFileCallbackSet = new Set();
-                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();
-                  }
-                  writeFileCallbackSet.clear();
-                  fsEffectsOutDirectorySnapshot.compare();
-                });
-                writeFile = (url, content) => {
-                  const { toUrl, label } = getFilesystemActionInfo(
-                    "write file",
-                    url,
-                  );
-                  writeFileCallbackSet.add(() => {
-                    writeFileSync(toUrl, content);
-                  });
-                  addSideEffect({
-                    type: "fs:write_file",
-                    value: { url: String(url), content },
-                    label,
-                    text: null,
-                  });
-                };
-              } else {
-                writeFile = (url, content) => {
-                  let urlDisplayed = url;
-                  if (baseDirectory) {
-                    urlDisplayed = urlToRelativeUrl(url, baseDirectory, {
-                      preferRelativeNotation: true,
-                    });
-                  }
-                  addSideEffect({
-                    type: "fs:write_file",
-                    value: { url: String(url), content },
-                    label: renderLabel(`write file "${urlDisplayed}"`),
-                    text: wrapIntoMarkdownBlock(
-                      content,
-                      urlToExtension(url).slice(1),
-                    ),
-                  });
-                };
-              }
-              const filesystemSpy = spyFilesystemCalls(
-                {
-                  writeFile,
-                  writeDirectory: (url) => {
-                    const writeDirectorySideEffect = addSideEffect({
-                      type: "fs:write_directory",
-                      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,
-                },
-              );
-              return () => {
-                filesystemSpy.restore();
-              };
-            },
-          },
-        ]
-      : []),
-  ];
-  const onSideEffectsCollected = (sideEffects) => {
-    for (const callback of callbackSet) {
-      callback(sideEffects);
-    }
-    callbackSet.clear();
-    sideEffectFileSnapshot.update(renderSideEffects(sideEffects), {
-      mockFluctuatingValues: false,
-    });
-  };
-  const returnValue = collectFunctionSideEffects(fn, sideEffectDetectors, {
-    rootDirectoryUrl,
-  });
-  if (returnValue && typeof returnValue.then === "function") {
-    return returnValue.then((sideEffects) => {
-      onSideEffectsCollected(sideEffects);
-    });
-  }
-  onSideEffectsCollected(returnValue);
-  return undefined;
-};

package/src/function_side_effects/group_file_side_effects_per_directory.js

@@ -1,114 +0,0 @@
-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,89 +0,0 @@
-import { hookIntoMethod } from "./hook_into_method.js";
-
-export const spyConsoleCalls = (
-  { error, warn, info, log, trace, stdout, stderr },
-  { preventConsoleSideEffects },
-) => {
-  const restoreCallbackSet = new Set();
-  const errorHook = hookIntoMethod(console, "error", (message) => {
-    return {
-      preventOriginalCall: preventConsoleSideEffects,
-      return: () => {
-        error(message);
-      },
-    };
-  });
-  const warnHook = hookIntoMethod(console, "warn", (message) => {
-    return {
-      preventOriginalCall: preventConsoleSideEffects,
-      return: () => {
-        warn(message);
-      },
-    };
-  });
-  const infoHook = hookIntoMethod(console, "info", (message) => {
-    return {
-      preventOriginalCall: preventConsoleSideEffects,
-      return: () => {
-        info(message);
-      },
-    };
-  });
-  const logHook = hookIntoMethod(console, "log", (message) => {
-    return {
-      preventOriginalCall: preventConsoleSideEffects,
-      return: () => {
-        log(message);
-      },
-    };
-  });
-  const traceHook = hookIntoMethod(console, "trace", (message) => {
-    return {
-      preventOriginalCall: preventConsoleSideEffects,
-      return: () => {
-        trace(message);
-      },
-    };
-  });
-  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: () => {
-      for (const restoreCallback of restoreCallbackSet) {
-        restoreCallback();
-      }
-      restoreCallbackSet.clear();
-    },
-  };
-};