@jsenv/core 36.3.1 → 37.0.0

package/src/kitchen/url_graph/references.js

@@ -0,0 +1,713 @@
+import {
+  getCallerPosition,
+  stringifyUrlSite,
+  generateInlineContentUrl,
+  urlToBasename,
+  urlToExtension,
+} from "@jsenv/urls";
+
+import { isWebWorkerEntryPointReference } from "../web_workers.js";
+import { prependContent } from "../prepend_content.js";
+import { GRAPH_VISITOR } from "./url_graph_visitor.js";
+
+export const createDependencies = (ownerUrlInfo) => {
+  const { referenceToOthersSet } = ownerUrlInfo;
+
+  const startCollecting = async (callback) => {
+    const prevReferenceToOthersSet = new Set(referenceToOthersSet);
+    referenceToOthersSet.clear();
+
+    const stopCollecting = () => {
+      for (const prevReferenceToOther of prevReferenceToOthersSet) {
+        applyDependencyRemovalEffects(prevReferenceToOther);
+      }
+      prevReferenceToOthersSet.clear();
+    };
+
+    try {
+      await callback();
+    } finally {
+      // finally to ensure reference are updated even in case of error
+      stopCollecting();
+    }
+  };
+
+  const createResolveAndFinalize = (props) => {
+    const originalReference = createReference({
+      ownerUrlInfo,
+      ...props,
+    });
+    const reference = originalReference.resolve();
+    reference.finalize();
+    return reference;
+  };
+
+  const found = ({ trace, ...rest }) => {
+    if (trace === undefined) {
+      trace = traceFromUrlSite(
+        adjustUrlSite(ownerUrlInfo, {
+          url: ownerUrlInfo.url,
+          line: rest.specifierLine,
+          column: rest.specifierColumn,
+        }),
+      );
+    }
+    const reference = createResolveAndFinalize({
+      trace,
+      ...rest,
+    });
+    return reference;
+  };
+  const foundInline = ({
+    isOriginalPosition,
+    specifierLine,
+    specifierColumn,
+    ...rest
+  }) => {
+    const parentUrl = isOriginalPosition
+      ? ownerUrlInfo.url
+      : ownerUrlInfo.generatedUrl;
+    const parentContent = isOriginalPosition
+      ? ownerUrlInfo.originalContent
+      : ownerUrlInfo.content;
+    const reference = createResolveAndFinalize({
+      trace: traceFromUrlSite({
+        url: parentUrl,
+        content: parentContent,
+        line: specifierLine,
+        column: specifierColumn,
+      }),
+      isOriginalPosition,
+      specifierLine,
+      specifierColumn,
+      isInline: true,
+      ...rest,
+    });
+    return reference;
+  };
+  // side effect file
+  const foundSideEffectFile = async ({ sideEffectFileUrl, trace, ...rest }) => {
+    if (trace === undefined) {
+      const { url, line, column } = getCallerPosition();
+      trace = traceFromUrlSite({
+        url,
+        line,
+        column,
+      });
+    }
+    const sideEffectFileReference = ownerUrlInfo.dependencies.inject({
+      trace,
+      type: "side_effect_file",
+      specifier: sideEffectFileUrl,
+      ...rest,
+    });
+    const parentUrlInfo = ownerUrlInfo.findParentIfInline() || ownerUrlInfo;
+
+    const associateIfReferencedBy = (urlInfo) => {
+      for (const referenceToOther of urlInfo.referenceToOthersSet) {
+        if (referenceToOther === sideEffectFileReference) {
+          continue;
+        }
+        if (referenceToOther.url === sideEffectFileUrl) {
+          // consider this reference becomes the last reference
+          // this ensure this ref is properly detected as inlined by urlInfo.isUsed()
+          sideEffectFileReference.next =
+            referenceToOther.next || referenceToOther;
+          return true;
+        }
+        if (
+          referenceToOther.original &&
+          referenceToOther.original.url === sideEffectFileUrl
+        ) {
+          // consider this reference becomes the last reference
+          // this ensure this ref is properly detected as inlined by urlInfo.isUsed()
+          sideEffectFileReference.next =
+            referenceToOther.next || referenceToOther;
+          return true;
+        }
+      }
+      return false;
+    };
+
+    const injectAsBannerCodeBeforeFinalize = (urlInfoReceiver) => {
+      const basename = urlToBasename(sideEffectFileUrl);
+      const inlineUrl = generateInlineContentUrl({
+        url: urlInfoReceiver.url,
+        basename,
+        extension: urlToExtension(sideEffectFileUrl),
+      });
+      const sideEffectFileReferenceInlined = sideEffectFileReference.inline({
+        ownerUrlInfo: urlInfoReceiver,
+        trace,
+        type: "side_effect_file",
+        specifier: inlineUrl,
+      });
+      urlInfoReceiver.addContentTransformationCallback(async () => {
+        await sideEffectFileReferenceInlined.urlInfo.cook();
+        await prependContent(
+          urlInfoReceiver,
+          sideEffectFileReferenceInlined.urlInfo,
+        );
+      });
+    };
+
+    // When possible we inject code inside the file in a common ancestor
+    // -> less duplication
+
+    // During dev:
+    // during dev cooking files is incremental
+    // so HTML/JS is already executed by the browser
+    // we can't late inject into entry point
+    if (ownerUrlInfo.context.dev) {
+      if (associateIfReferencedBy(ownerUrlInfo)) {
+        return;
+      }
+      const dependentReferencingThatFile = GRAPH_VISITOR.findDependent(
+        parentUrlInfo,
+        (ancestorUrlInfo) => {
+          if (ancestorUrlInfo.isRoot) {
+            return false;
+          }
+          return associateIfReferencedBy(ancestorUrlInfo);
+        },
+      );
+      if (dependentReferencingThatFile) {
+        return;
+      }
+      injectAsBannerCodeBeforeFinalize(parentUrlInfo);
+      return;
+    }
+
+    // During build:
+    // during build, files are not executed so it's
+    // possible to inject reference when discovering a side effect file
+    if (associateIfReferencedBy(ownerUrlInfo)) {
+      return;
+    }
+    // The thing to do here is to inject side effect file into entry point
+    // only when:
+    // - entry point does not already has it
+    // - nothing between entry point and the file has it
+    const entryPoints = parentUrlInfo.graph.getEntryPoints();
+    for (const entryPointUrlInfo of entryPoints) {
+      if (associateIfReferencedBy(entryPointUrlInfo)) {
+        continue;
+      }
+      if (parentUrlInfo.isEntryPoint) {
+        injectAsBannerCodeBeforeFinalize(entryPointUrlInfo);
+        continue;
+      }
+      let found = false;
+      GRAPH_VISITOR.findDependency(entryPointUrlInfo, (dependencyUrlInfo) => {
+        if (associateIfReferencedBy(dependencyUrlInfo)) {
+          found = true;
+          return true;
+        }
+        if (dependencyUrlInfo === parentUrlInfo) {
+          return true;
+        }
+        return false;
+      });
+      if (!found) {
+        injectAsBannerCodeBeforeFinalize(entryPointUrlInfo);
+      }
+    }
+  };
+
+  const inject = ({ trace, ...rest }) => {
+    if (trace === undefined) {
+      const { url, line, column } = getCallerPosition();
+      trace = traceFromUrlSite({
+        url,
+        line,
+        column,
+      });
+    }
+    const reference = createResolveAndFinalize({
+      trace,
+      injected: true,
+      ...rest,
+    });
+    return reference;
+  };
+
+  return {
+    startCollecting,
+    createResolveAndFinalize,
+    found,
+    foundInline,
+    foundSideEffectFile,
+    inject,
+  };
+};
+
+/*
+ * - "http_request"
+ * - "entry_point"
+ * - "link_href"
+ * - "style"
+ * - "script"
+ * - "a_href"
+ * - "iframe_src
+ * - "img_src"
+ * - "img_srcset"
+ * - "source_src"
+ * - "source_srcset"
+ * - "image_href"
+ * - "use_href"
+ * - "css_@import"
+ * - "css_url"
+ * - "js_import"
+ * - "js_import_script"
+ * - "js_url"
+ * - "js_inline_content"
+ * - "sourcemap_comment"
+ * - "webmanifest_icon_src"
+ * - "package_json"
+ * - "side_effect_file"
+ * */
+const createReference = ({
+  ownerUrlInfo,
+  data = {},
+  trace,
+  type,
+  subtype,
+  expectedContentType,
+  expectedType,
+  expectedSubtype,
+  filename,
+  integrity,
+  crossorigin,
+  specifier,
+  specifierStart,
+  specifierEnd,
+  specifierLine,
+  specifierColumn,
+  baseUrl,
+  isOriginalPosition,
+  isEntryPoint = false,
+  isResourceHint = false,
+  // implicit references are not real references
+  // they represent an abstract relationship
+  isImplicit = false,
+  // weak references cannot keep the corresponding url info alive
+  // there must be an other reference to keep the url info alive
+  // an url referenced solely by weak references is:
+  // - not written in build directory
+  // - can be removed from graph during dev/build
+  // - not cooked until referenced by a strong reference
+  isWeak = false,
+  hasVersioningEffect = false,
+  version = null,
+  injected = false,
+  isInline = false,
+  content,
+  contentType,
+  leadsToADirectory = false,
+  debug = false,
+  original = null,
+  prev = null,
+  next = null,
+  url = null,
+  searchParams = null,
+  generatedUrl = null,
+  generatedSpecifier = null,
+  urlInfo = null,
+  escape = null,
+  importAttributes,
+  astInfo = {},
+  mutation,
+}) => {
+  if (typeof specifier !== "string") {
+    if (specifier instanceof URL) {
+      specifier = specifier.href;
+    } else {
+      throw new TypeError(`"specifier" must be a string, got ${specifier}`);
+    }
+  }
+  const reference = {
+    ownerUrlInfo,
+    original,
+    prev,
+    next,
+    data,
+    trace,
+    url,
+    urlInfo,
+    searchParams,
+    generatedUrl,
+    generatedSpecifier,
+    type,
+    subtype,
+    expectedContentType,
+    expectedType,
+    expectedSubtype,
+    filename,
+    integrity,
+    crossorigin,
+    specifier,
+    specifierStart,
+    specifierEnd,
+    specifierLine,
+    specifierColumn,
+    isOriginalPosition,
+    baseUrl,
+    isEntryPoint,
+    isResourceHint,
+    isImplicit,
+    implicitReferenceSet: new Set(),
+    isWeak,
+    hasVersioningEffect,
+    version,
+    injected,
+    timing: {},
+    leadsToADirectory,
+    debug,
+    // for inline resources the reference contains the content
+    isInline,
+    content,
+    contentType,
+    escape,
+    // used mostly by worker and import assertions
+    astInfo,
+    importAttributes,
+    mutation,
+  };
+
+  reference.resolve = () => {
+    const resolvedReference =
+      reference.ownerUrlInfo.context.resolveReference(reference);
+    return resolvedReference;
+  };
+
+  reference.redirect = (url, props = {}) => {
+    const redirectedProps = getRedirectedReferenceProps(reference, url);
+    const referenceRedirected = createReference({
+      ...redirectedProps,
+      ...props,
+    });
+    reference.next = referenceRedirected;
+    return referenceRedirected;
+  };
+
+  reference.finalize = () => {
+    if (reference.urlInfo) {
+      return;
+    }
+    const kitchen = ownerUrlInfo.kitchen;
+    const urlInfo = kitchen.graph.reuseOrCreateUrlInfo(reference);
+    reference.urlInfo = urlInfo;
+    addDependency(reference);
+    ownerUrlInfo.context.finalizeReference(reference);
+  };
+
+  // "formatReferencedUrl" can be async BUT this is an exception
+  // for most cases it will be sync. We want to favor the sync signature to keep things simpler
+  // The only case where it needs to be async is when
+  // the specifier is a `data:*` url
+  // in this case we'll wait for the promise returned by
+  // "formatReferencedUrl"
+  reference.readGeneratedSpecifier = () => {
+    if (reference.generatedSpecifier.then) {
+      return reference.generatedSpecifier.then((value) => {
+        reference.generatedSpecifier = value;
+        return value;
+      });
+    }
+    return reference.generatedSpecifier;
+  };
+
+  reference.inline = ({
+    line,
+    column,
+    // when urlInfo is given it means reference is moved into an other file
+    ownerUrlInfo = reference.ownerUrlInfo,
+    ...props
+  }) => {
+    const trace = traceFromUrlSite({
+      url:
+        ownerUrlInfo === undefined
+          ? isOriginalPosition
+            ? reference.ownerUrlInfo.url
+            : reference.ownerUrlInfo.generatedUrl
+          : reference.ownerUrlInfo.url,
+      content:
+        ownerUrlInfo === undefined
+          ? isOriginalPosition
+            ? reference.ownerUrlInfo.originalContent
+            : reference.ownerUrlInfo.content
+          : ownerUrlInfo.content,
+      line,
+      column,
+    });
+    const inlineCopy = ownerUrlInfo.dependencies.createResolveAndFinalize({
+      isInline: true,
+      original: reference.original || reference,
+      prev: reference,
+      trace,
+      expectedType: reference.expectedType,
+      ...props,
+    });
+    // the previous reference stays alive so that even after inlining
+    // updating the file will invalidate the other file where it was inlined
+    reference.next = inlineCopy;
+    return inlineCopy;
+  };
+
+  reference.addImplicit = (props) => {
+    const implicitReference = ownerUrlInfo.dependencies.inject({
+      ...props,
+      isImplicit: true,
+    });
+    reference.implicitReferenceSet.add(implicitReference);
+    return implicitReference;
+  };
+
+  reference.remove = () => removeDependency(reference);
+
+  // Object.preventExtensions(reference) // useful to ensure all properties are declared here
+  return reference;
+};
+
+const addDependency = (reference) => {
+  const { ownerUrlInfo } = reference;
+  if (ownerUrlInfo.referenceToOthersSet.has(reference)) {
+    return;
+  }
+  if (!canAddOrRemoveReference(reference)) {
+    throw new Error(
+      `cannot add reference for content already sent to the browser
+--- reference url ---
+${reference.url}
+--- content url ---
+${ownerUrlInfo.url}`,
+    );
+  }
+  ownerUrlInfo.referenceToOthersSet.add(reference);
+  if (reference.isImplicit) {
+    // an implicit reference is a reference that does not explicitely appear in the file
+    // but has an impact on the file
+    // -> package.json on import resolution for instance
+    // in that case:
+    // - file depends on the implicit file (it must autoreload if package.json is modified)
+    // - cache validity for the file depends on the implicit file (it must be re-cooked if package.json is modified)
+    ownerUrlInfo.implicitUrlSet.add(reference.url);
+    if (ownerUrlInfo.isInline) {
+      const parentUrlInfo = ownerUrlInfo.graph.getUrlInfo(
+        ownerUrlInfo.inlineUrlSite.url,
+      );
+      parentUrlInfo.implicitUrlSet.add(reference.url);
+    }
+  }
+  const referencedUrlInfo = reference.urlInfo;
+  referencedUrlInfo.referenceFromOthersSet.add(reference);
+  applyReferenceEffectsOnUrlInfo(reference);
+  for (const implicitRef of reference.implicitReferenceSet) {
+    addDependency(implicitRef);
+  }
+};
+
+const removeDependency = (reference) => {
+  const { ownerUrlInfo } = reference;
+  if (!ownerUrlInfo.referenceToOthersSet.has(reference)) {
+    return false;
+  }
+  if (!canAddOrRemoveReference(reference)) {
+    throw new Error(
+      `cannot remove reference for content already sent to the browser
+--- reference url ---
+${reference.url}
+--- content url ---
+${ownerUrlInfo.url}`,
+    );
+  }
+  for (const implicitRef of reference.implicitReferenceSet) {
+    implicitRef.remove();
+  }
+  ownerUrlInfo.referenceToOthersSet.delete(reference);
+  return applyDependencyRemovalEffects(reference);
+};
+
+const canAddOrRemoveReference = (reference) => {
+  if (reference.isWeak || reference.isImplicit) {
+    // weak and implicit references have no restrictions
+    // because they are not actual references with an influence on content
+    return true;
+  }
+  const { ownerUrlInfo } = reference;
+  if (ownerUrlInfo.context.build) {
+    // during build url content is not executed
+    // it's still possible to mutate references safely
+    return true;
+  }
+  if (!ownerUrlInfo.contentFinalized) {
+    return true;
+  }
+  if (ownerUrlInfo.isRoot) {
+    // the root urlInfo is abstract, there is no real file behind it
+    return true;
+  }
+  if (reference.type === "http_request") {
+    // reference created to http requests are abstract concepts
+    return true;
+  }
+  return false;
+};
+
+const applyDependencyRemovalEffects = (reference) => {
+  const { ownerUrlInfo } = reference;
+  const { referenceToOthersSet } = ownerUrlInfo;
+
+  if (reference.isImplicit && !reference.isInline) {
+    let hasAnOtherImplicitRef = false;
+    for (const referenceToOther of referenceToOthersSet) {
+      if (
+        referenceToOther.isImplicit &&
+        referenceToOther.url === reference.url
+      ) {
+        hasAnOtherImplicitRef = true;
+        break;
+      }
+    }
+    if (!hasAnOtherImplicitRef) {
+      ownerUrlInfo.implicitUrlSet.delete(reference.url);
+    }
+  }
+
+  const prevReference = reference.prev;
+  const nextReference = reference.next;
+  if (prevReference && nextReference) {
+    nextReference.prev = prevReference;
+    prevReference.next = nextReference;
+  } else if (prevReference) {
+    prevReference.next = null;
+  } else if (nextReference) {
+    nextReference.original = null;
+    nextReference.prev = null;
+  }
+
+  const referencedUrlInfo = reference.urlInfo;
+  referencedUrlInfo.referenceFromOthersSet.delete(reference);
+
+  const firstReferenceFromOther =
+    referencedUrlInfo.getFirstReferenceFromOther();
+  if (firstReferenceFromOther) {
+    // either applying new ref should override old ref
+    // or we should first remove effects before adding new ones
+    // for now we just set firstReference to null
+    if (reference === referencedUrlInfo.firstReference) {
+      referencedUrlInfo.firstReference = null;
+      applyReferenceEffectsOnUrlInfo(firstReferenceFromOther);
+    }
+    return false;
+  }
+  if (reference.type !== "http_request") {
+    referencedUrlInfo.deleteFromGraph(reference);
+    return true;
+  }
+  return false;
+};
+
+const traceFromUrlSite = (urlSite) => {
+  return {
+    message: stringifyUrlSite(urlSite),
+    url: urlSite.url,
+    line: urlSite.line,
+    column: urlSite.column,
+  };
+};
+
+const adjustUrlSite = (urlInfo, { url, line, column }) => {
+  const isOriginal = url === urlInfo.url;
+  const adjust = (urlSite, urlInfo) => {
+    if (!urlSite.isOriginal) {
+      return urlSite;
+    }
+    const inlineUrlSite = urlInfo.inlineUrlSite;
+    if (!inlineUrlSite) {
+      return urlSite;
+    }
+    const parentUrlInfo = urlInfo.graph.getUrlInfo(inlineUrlSite.url);
+    return adjust(
+      {
+        isOriginal: true,
+        url: inlineUrlSite.url,
+        content: inlineUrlSite.content,
+        line:
+          inlineUrlSite.line === undefined
+            ? urlSite.line
+            : inlineUrlSite.line + urlSite.line,
+        column:
+          inlineUrlSite.column === undefined
+            ? urlSite.column
+            : inlineUrlSite.column + urlSite.column,
+      },
+      parentUrlInfo,
+    );
+  };
+  return adjust(
+    {
+      isOriginal,
+      url,
+      content: isOriginal ? urlInfo.originalContent : urlInfo.content,
+      line,
+      column,
+    },
+    urlInfo,
+  );
+};
+
+const getRedirectedReferenceProps = (reference, url) => {
+  const redirectedProps = {
+    ...reference,
+    specifier: url,
+    url,
+    original: reference.original || reference,
+    prev: reference,
+  };
+  return redirectedProps;
+};
+
+const applyReferenceEffectsOnUrlInfo = (reference) => {
+  const referencedUrlInfo = reference.urlInfo;
+
+  if (referencedUrlInfo.firstReference) {
+    return;
+  }
+  referencedUrlInfo.firstReference = reference;
+  referencedUrlInfo.originalUrl =
+    referencedUrlInfo.originalUrl || reference.url;
+
+  if (reference.isEntryPoint || isWebWorkerEntryPointReference(reference)) {
+    referencedUrlInfo.isEntryPoint = true;
+  }
+  Object.assign(referencedUrlInfo.data, reference.data);
+  Object.assign(referencedUrlInfo.timing, reference.timing);
+  if (reference.injected) {
+    referencedUrlInfo.injected = true;
+  }
+  if (reference.filename && !referencedUrlInfo.filename) {
+    referencedUrlInfo.filename = reference.filename;
+  }
+  if (reference.isInline) {
+    referencedUrlInfo.isInline = true;
+    referencedUrlInfo.inlineUrlSite = {
+      url: reference.ownerUrlInfo.url,
+      content: reference.isOriginalPosition
+        ? reference.ownerUrlInfo.originalContent
+        : reference.ownerUrlInfo.content,
+      line: reference.specifierLine,
+      column: reference.specifierColumn,
+    };
+  }
+
+  if (reference.debug) {
+    referencedUrlInfo.debug = true;
+  }
+  if (reference.expectedType) {
+    referencedUrlInfo.typeHint = reference.expectedType;
+  }
+  if (reference.expectedSubtype) {
+    referencedUrlInfo.subtypeHint = reference.expectedSubtype;
+  }
+};

package/src/kitchen/url_graph/sort_by_dependencies.js

@@ -14,8 +14,8 @@ export const sortByDependencies = (nodes) => {
       }
     } else {
       visited.push(url);
-      nodes[url].dependencies.forEach((dependencyUrl) => {
-        visit(dependencyUrl, url);
+      nodes[url].referenceToOthersSet.forEach((referenceToOther) => {
+        visit(referenceToOther.url, url);
       });
       sorted.push(url);
     }