@jsenv/core 41.4.0 → 41.4.2

package/src/plugins/page_switcher/jsenv_plugin_page_switcher.js

@@ -0,0 +1,42 @@
+/*
+ * cmd+K (ctrl+K elsewhere) on any page the dev server serves opens a list of
+ * the .html files it serves, filter as you type, Enter to go there.
+ *
+ * The list is the one the filesystem plugin already publishes for everyone
+ * (GET /.internal/pages.json, see protocol_file/html_pages.js) — this only adds
+ * the way to reach it without leaving the page one is working on.
+ *
+ * Registered with the dev server rather than among the core plugins, next to
+ * the other things that inject a client script: the script it adds is a
+ * reference like any other, and it has to be added while references are still
+ * being resolved — added later it stays a file:// url the browser refuses.
+ *
+ * A shortcut on every page is a shortcut taken from every page, so the page
+ * comes first: the key is watched on the document, in the bubble phase, and
+ * anything that called preventDefault on its way there keeps it. A page with
+ * its own cmd+K owes nothing to this one.
+ */
+
+import { injectJsenvScript, parseHtml, stringifyHtmlAst } from "@jsenv/ast";
+
+const clientFileUrl = new URL("./client/page_switcher.js", import.meta.url)
+  .href;
+
+export const jsenvPluginPageSwitcher = () => {
+  return {
+    name: "jsenv:page_switcher",
+    // Dev only: it is a way around the source tree, which a built app has no
+    // business carrying.
+    appliesDuring: "dev",
+    transformUrlContent: {
+      html: (urlInfo) => {
+        const htmlAst = parseHtml({ html: urlInfo.content, url: urlInfo.url });
+        injectJsenvScript(htmlAst, {
+          src: clientFileUrl,
+          pluginName: "jsenv:page_switcher",
+        });
+        return stringifyHtmlAst(htmlAst);
+      },
+    },
+  };
+};

package/src/plugins/protocol_file/html_pages.js

@@ -0,0 +1,122 @@
+/*
+ * The .html files under the served directory, as urls one can navigate to.
+ *
+ * Lives here, next to the plugin that owns the filesystem, because more than
+ * one feature wants the same list: the client dashboard sends a browser to one
+ * of them, the page switcher (cmd+K) opens one in the current tab. Whoever asks
+ * gets the same answer.
+ *
+ * Each page comes with what kind of page it is, read from where it sits and
+ * what it is called — the two conventions this repo already follows:
+ * - "experiment": something tried out, under a lab/ directory or named
+ *   *_experiment.html;
+ * - "demo": something shown, under a demos/ directory or named *_demo.html;
+ * - "page": everything else.
+ *
+ * Scanned on demand rather than watched: the list is asked for when a human
+ * opens a picker, which is rare and never on a hot path, and a short cache is
+ * enough to keep a burst of asks from walking the tree twice.
+ */
+
+import { collectFiles } from "@jsenv/filesystem";
+import { existsSync } from "node:fs";
+
+const SCAN_TTL_MS = 5000;
+
+// What to walk and what to skip, in the shape @jsenv/url-meta reads: the last
+// matching pattern wins, so the exclusions come after the "every .html" rule.
+// Dependencies, build output and jsenv's own caches hold no page worth going to.
+const HTML_PAGE_ASSOCIATIONS = {
+  page: {
+    "**/*.html": true,
+    "**/.*/": false,
+    "**/node_modules/": false,
+    "**/dist/": false,
+    "**/build/": false,
+    "**/coverage/": false,
+    "**/git_ignored/": false,
+    "**/old/": false,
+  },
+  experiment: {
+    "**/lab/**/*.html": true,
+    "**/*_experiment.html": true,
+  },
+  demo: {
+    "**/demos/**/*.html": true,
+    "**/*_demo.html": true,
+  },
+};
+
+// An experiment inside a demos/ directory is an experiment: the more specific
+// of the two wins, and "shown" is the weaker claim.
+const readKind = (meta) => {
+  if (meta.experiment) {
+    return "experiment";
+  }
+  if (meta.demo) {
+    return "demo";
+  }
+  return "page";
+};
+
+// Which package a page belongs to: the nearest directory above it holding a
+// package.json, said as a url so whoever draws a tree can mark that very node.
+// Not the root itself — everything is under it, and "the whole repo" is not a
+// package one distinguishes from another. Memoized per directory: a scan asks
+// the same question once per file and there are hundreds of them.
+const createPackageDirectoryFinder = (rootDirectoryUrl) => {
+  const cache = new Map();
+  const find = (directoryUrl) => {
+    if (cache.has(directoryUrl)) {
+      return cache.get(directoryUrl);
+    }
+    let result = null;
+    if (directoryUrl.length > String(rootDirectoryUrl).length) {
+      result = existsSync(new URL("./package.json", directoryUrl))
+        ? directoryUrl
+        : find(new URL("../", directoryUrl).href);
+    }
+    cache.set(directoryUrl, result);
+    return result;
+  };
+  return find;
+};
+
+export const createHtmlPageLister = ({ rootDirectoryUrl }) => {
+  let cache = null;
+  let cachedAt = 0;
+
+  return async () => {
+    if (!rootDirectoryUrl) {
+      return [];
+    }
+    const now = Date.now();
+    if (cache && now - cachedAt < SCAN_TTL_MS) {
+      return cache;
+    }
+    const fileResultArray = await collectFiles({
+      directoryUrl: rootDirectoryUrl,
+      associations: HTML_PAGE_ASSOCIATIONS,
+      predicate: (meta) => Boolean(meta.page),
+    });
+    const findPackageDirectory = createPackageDirectoryFinder(rootDirectoryUrl);
+    const pages = fileResultArray.map(({ relativeUrl, meta }) => {
+      const fileUrl = new URL(relativeUrl, rootDirectoryUrl).href;
+      const packageDirectoryUrl = findPackageDirectory(
+        new URL("./", fileUrl).href,
+      );
+      return {
+        url: `/${relativeUrl}`,
+        kind: readKind(meta),
+        // Relative to the root and without its trailing slash, which is how a
+        // tree names its own nodes.
+        packageUrl: packageDirectoryUrl
+          ? `/${packageDirectoryUrl.slice(String(rootDirectoryUrl).length).replace(/\/$/, "")}`
+          : null,
+      };
+    });
+    cache = pages;
+    cachedAt = now;
+    return pages;
+  };
+};

package/src/plugins/protocol_file/jsenv_plugin_protocol_file.js

@@ -3,6 +3,7 @@ import { ensurePathnameTrailingSlash } from "@jsenv/urls";
 import { CONTENT_TYPE } from "@jsenv/utils/src/content_type/content_type.js";
 import { readFileSync, readdirSync } from "node:fs";
 import { FILE_AND_SERVER_URLS_CONVERTER } from "../../kitchen/file_and_server_urls_converter.js";
+import { createHtmlPageLister } from "./html_pages.js";
 import { jsenvPluginDirectoryListing } from "./jsenv_plugin_directory_listing.js";
 import { jsenvPluginFsRedirection } from "./jsenv_plugin_fs_redirection.js";
 
@@ -19,6 +20,8 @@ export const jsenvPluginProtocolFile = ({
   packageDirectory,
   sourceFilesConfig,
 }) => {
+  const listHtmlPages = createHtmlPageLister({ rootDirectoryUrl });
+
   return [
     jsenvPluginFsRedirection({
       spa,
@@ -74,6 +77,27 @@ export const jsenvPluginProtocolFile = ({
         );
       },
     },
+    {
+      name: "jsenv:html_pages",
+      appliesDuring: "dev",
+      serverRoutes: [
+        {
+          endpoint: "GET /.internal/pages.json",
+          description:
+            "The .html files served under the source directory, as urls to navigate to.",
+          availableMediaTypes: ["application/json"],
+          declarationSource: import.meta.url,
+          fetch: async () => ({
+            status: 200,
+            headers: {
+              "content-type": "application/json",
+              "cache-control": "no-store",
+            },
+            body: JSON.stringify(await listHtmlPages()),
+          }),
+        },
+      ],
+    },
     ...(directoryListing
       ? [
           jsenvPluginDirectoryListing({

package/src/plugins/resolution_node_esm/node_esm_resolver.js

@@ -471,6 +471,11 @@ const addRelationshipWithPackageJson = ({
       String(packageJsonContentAsBuffer),
     );
   }
+  // Checked on disk at every validation rather than trusted to the watcher:
+  // what this file decides (the package version, hence the ?v= importers
+  // embed) ends up in the browser's immutable cache, so a request racing the
+  // watcher must never be answered from a stale package.json.
+  packageJsonReference.urlInfo.revalidateOnFileSystem = true;
 };
 
 const createResolverWithFallbackOnError = (mainResolver, fallbackResolver) => {