@kenjura/ursa 0.95.0 → 0.97.0

package/src/helper/mdxRenderer.js

@@ -3,9 +3,9 @@ import { getMDXComponent } from "mdx-bundler/client/index.js";
 import React from "react";
 import { renderToString } from "react-dom/server";
 import * as esbuild from "esbuild";
-import { dirname, join, resolve } from "path";
-import { existsSync } from "fs";
-import { writeFile, mkdir } from "fs/promises";
+import { dirname, extname, join, resolve, sep } from "path";
+import { existsSync } from "./build/tracedFs.js";
+import { readFile, writeFile, mkdir } from "fs/promises";
 import remarkDirective from "remark-directive";
 import { remarkDefinitionList, defListHastHandlers } from "remark-definition-list";
 import remarkSupersub from "remark-supersub";
@@ -47,6 +47,160 @@ function remarkAsideContainers() {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Island hydration
+//
+// Components imported directly into an .mdx file are wrapped in an island: the
+// server renders each inside <ursa-island data-island="N">, and the client
+// hydrates each of those elements as its own React root. The markdown around
+// them is never handed to React, so the template is free to restructure it
+// (sectionify.js wraps H1 sections, breadcrumbs are injected, etc.) without
+// causing a hydration mismatch. See docs/changes/island-hydration.md.
+// ---------------------------------------------------------------------------
+
+const ISLAND_MODULE = "ursa:island";
+const ISLAND_NAMESPACE = "ursa-island";
+const ISLAND_RUNTIME_NAMESPACE = "ursa-island-runtime";
+const ISLAND_TAG = "ursa-island";
+
+// Extensions that are wrapped when imported from the .mdx entry. .js/.ts are
+// only wrapped when they live in a _components/ directory, since a plain .js
+// import from MDX is as likely to be data or a helper as a component.
+const ISLAND_COMPONENT_EXTS = new Set([".jsx", ".tsx"]);
+const ISLAND_COMPONENT_DIR_EXTS = new Set([".js", ".ts"]);
+
+/**
+ * Source of the `ursa:island` virtual module. Both variants assign island ids
+ * with a lazy useState initializer so each mount takes exactly one id, in tree
+ * order — which is what lets the client match the server's numbering.
+ */
+function islandRuntimeSource(platform) {
+  const shared = `
+    import React from 'react';
+    let counter = 0;
+    function useIslandId() {
+      const [id] = React.useState(() => counter++);
+      return id;
+    }
+  `;
+  if (platform === "node") {
+    return `${shared}
+      export function island(Component, name) {
+        if (typeof Component !== 'function') return Component;
+        function Island(props) {
+          const id = useIslandId();
+          return React.createElement(
+            ${JSON.stringify(ISLAND_TAG)},
+            { 'data-island': String(id), 'data-component': name, style: { display: 'contents' } },
+            React.createElement(Component, props)
+          );
+        }
+        Island.displayName = 'Island(' + name + ')';
+        return Island;
+      }
+    `;
+  }
+  return `${shared}
+    import * as ReactDOM from 'react-dom';
+    export function island(Component, name) {
+      if (typeof Component !== 'function') return Component;
+      function Island(props) {
+        const id = useIslandId();
+        React.useEffect(() => {
+          const target = document.querySelector(${JSON.stringify(ISLAND_TAG)} + '[data-island="' + id + '"]');
+          if (!target) {
+            console.warn('[ursa] island #' + id + ' (' + name + ') not found in document; skipping hydration');
+            return undefined;
+          }
+          const root = ReactDOM.hydrateRoot(target, React.createElement(Component, props));
+          return () => root.unmount();
+        }, []);
+        return null;
+      }
+      Island.displayName = 'Island(' + name + ')';
+      return Island;
+    }
+  `;
+}
+
+function isIslandCandidate(resolvedPath) {
+  const ext = extname(resolvedPath);
+  if (ISLAND_COMPONENT_EXTS.has(ext)) return true;
+  if (ISLAND_COMPONENT_DIR_EXTS.has(ext)) {
+    return resolvedPath.split(sep).includes("_components");
+  }
+  return false;
+}
+
+/**
+ * esbuild plugin that turns direct component imports of the .mdx entry into
+ * islands. Must be registered ahead of mdx-bundler's own resolvers so it sees
+ * the import first; it defers to them (via build.resolve) for the actual lookup.
+ */
+function islandPlugin(platform) {
+  return {
+    name: "ursa-island",
+    setup(build) {
+      // The runtime module itself
+      build.onResolve({ filter: /^ursa:island$/ }, () => ({
+        path: ISLAND_MODULE,
+        namespace: ISLAND_RUNTIME_NAMESPACE,
+      }));
+      build.onLoad({ filter: /.*/, namespace: ISLAND_RUNTIME_NAMESPACE }, () => ({
+        contents: islandRuntimeSource(platform),
+        loader: "js",
+        resolveDir: process.cwd(),
+      }));
+
+      // Imports from the .mdx entry
+      build.onResolve({ filter: /.*/ }, async (args) => {
+        if (args.pluginData?.ursaIsland) return undefined; // our own build.resolve
+        if (args.namespace !== "file" || !args.importer.endsWith(".mdx")) return undefined;
+        if (args.path === ISLAND_MODULE || /^react(\/|$)|^react-dom(\/|$)/.test(args.path)) return undefined;
+
+        const resolved = await build.resolve(args.path, {
+          importer: args.importer,
+          resolveDir: args.resolveDir,
+          kind: args.kind,
+          pluginData: { ursaIsland: true },
+        });
+        if (resolved.errors.length > 0 || resolved.external || resolved.namespace !== "file") return undefined;
+        if (!isIslandCandidate(resolved.path)) return undefined;
+
+        return {
+          path: resolved.path,
+          namespace: ISLAND_NAMESPACE,
+          pluginData: { name: args.path.split("/").pop().replace(/\.[jt]sx?$/, "") },
+        };
+      });
+      build.onLoad({ filter: /.*/, namespace: ISLAND_NAMESPACE }, (args) => {
+        const real = JSON.stringify(args.path);
+        const name = JSON.stringify(args.pluginData?.name || "Component");
+        return {
+          contents: `
+            import __ursaInner from ${real};
+            export * from ${real};
+            import { island } from ${JSON.stringify(ISLAND_MODULE)};
+            export default island(__ursaInner, ${name});
+          `,
+          loader: "js",
+          resolveDir: dirname(args.path),
+        };
+      });
+    },
+  };
+}
+
+/**
+ * React 19's renderToString hoists a <link rel="preload"> for images ahead of
+ * the content. It carries the un-rewritten relative href (so it preloads
+ * nothing useful) and, sitting before the first <h1>, defeats the template's
+ * "body starts with a heading" check, which then injects a duplicate title.
+ */
+function stripHoistedPreloads(html) {
+  return html.replace(/<link rel="preload"[^>]*>/g, "");
+}
+
 /**
  * Find _components directories by walking up from the MDX file to the source root.
  * Returns paths from most specific (nearest) to most general (root).
@@ -91,11 +245,29 @@ function findComponentDirs(startDir, sourceRoot) {
  * @param {string} options.filePath - Absolute path to the MDX file (used for import resolution)
  * @param {string} [options.sourceRoot] - Root directory of the source files (for absolute imports)
  * @param {boolean} [options.hydrate=false] - If true, includes client bundle for hydration
- * @returns {Promise<{ html: string, frontmatter: Record<string, any>, clientCode?: string }>}
+ * @returns {Promise<{ html: string, frontmatter: Record<string, any>, clientCode?: string, inputs: string[] }>}
+ *   `inputs` is every file esbuild loaded while bundling (components, their
+ *   imports, anything under `_components`), excluding node_modules — the
+ *   document's real dependency set, so the build can re-render exactly the
+ *   pages that import an edited component.
  */
 export async function renderMDX({ source, filePath, sourceRoot, hydrate = false }) {
   const cwd = dirname(filePath);
   const componentDirs = findComponentDirs(cwd, sourceRoot);
+  const inputs = new Set();
+
+  /** Records every file esbuild loads; returns nothing so the real loaders still run. */
+  const inputRecorderPlugin = {
+    name: "ursa-input-recorder",
+    setup(build) {
+      build.onLoad({ filter: /.*/ }, (args) => {
+        if (args.namespace === "file" && !args.path.includes(`${sep}node_modules${sep}`)) {
+          inputs.add(args.path);
+        }
+        return undefined;
+      });
+    },
+  };
 
   /**
    * Create esbuild options for the given platform
@@ -121,7 +293,10 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
       const parentDirs = componentDirs.map(d => dirname(d));
       options.nodePaths = [...(options.nodePaths || []), ...parentDirs];
     }
-    
+
+    // Island plugin goes first so it sees component imports before mdx-bundler's resolvers
+    options.plugins = [inputRecorderPlugin, islandPlugin(platform), ...(options.plugins || [])];
+
     return options;
   };
 
@@ -170,11 +345,11 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
     const Component = getMDXComponent(serverCode);
 
     // Render to HTML with hydration markers (renderToString vs renderToStaticMarkup)
-    const html = renderToString(React.createElement(Component));
+    const html = stripHoistedPreloads(renderToString(React.createElement(Component)));
 
     // If hydration is not requested, return without client code
     if (!hydrate) {
-      return { html, frontmatter: frontmatter || {} };
+      return { html, frontmatter: frontmatter || {}, inputs: [...inputs].sort() };
     }
 
     // Client-side bundle (for hydration)
@@ -191,9 +366,13 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
       html, 
       frontmatter: frontmatter || {},
       clientCode: clientResult.code,
+      inputs: [...inputs].sort(),
     };
   } catch (error) {
-    throw formatMDXError(error, filePath);
+    const formatted = formatMDXError(error, filePath);
+    formatted.inputs = [...inputs].sort();
+    formatted.componentDirs = componentDirs;
+    throw formatted;
   }
 }
 
@@ -279,11 +458,18 @@ function formatMDXError(error, filePath) {
  * @param {string} publicDir - Absolute path to the output public/ directory
  * @returns {Promise<void>}
  */
+// Bump when the runtime's contents change; an older runtime left in
+// output/public/ is then rebuilt instead of reused.
+const REACT_RUNTIME_MARKER = 'ursa-react-runtime/2';
+
 export async function buildReactRuntime(publicDir) {
   const outfile = join(publicDir, 'react-runtime.js');
 
-  // Skip rebuild if already exists (for incremental builds)
-  if (existsSync(outfile)) return;
+  // Skip rebuild if an up-to-date runtime already exists (for incremental builds)
+  if (existsSync(outfile)) {
+    const existing = await readFile(outfile, 'utf8');
+    if (existing.includes(REACT_RUNTIME_MARKER)) return;
+  }
 
   await mkdir(publicDir, { recursive: true });
 
@@ -292,11 +478,12 @@ export async function buildReactRuntime(publicDir) {
       contents: `
         import React from 'react';
         import * as ReactDOM from 'react-dom';
-        import { hydrateRoot } from 'react-dom/client';
+        import { hydrateRoot, createRoot } from 'react-dom/client';
         import * as _jsx_runtime from 'react/jsx-runtime';
         window.React = React;
-        window.ReactDOM = { ...ReactDOM, hydrateRoot };
+        window.ReactDOM = { ...ReactDOM, hydrateRoot, createRoot };
         window._jsx_runtime = _jsx_runtime;
+        window.__ursaReactRuntime = ${JSON.stringify(REACT_RUNTIME_MARKER)};
       `,
       resolveDir: dirname(new URL(import.meta.url).pathname),
       loader: 'js',
@@ -313,12 +500,17 @@ export async function buildReactRuntime(publicDir) {
 /**
  * Generate the hydration script tags for an MDX page.
  * References the locally-built React runtime instead of CDN.
- * 
+ *
+ * The bundled MDX module is rendered into a detached root purely to run the
+ * component tree: every island in it hydrates its own <ursa-island> element in
+ * the live document (see islandRuntimeSource). Nothing outside those elements
+ * is handed to React, so the template's DOM post-processing (sectionify,
+ * breadcrumbs, TOC) cannot cause a hydration mismatch.
+ *
  * @param {string} clientCode - The bundled MDX client code from renderMDX
- * @param {string} [containerId='main-content'] - The ID of the container element to hydrate
  * @returns {string} HTML script tags to include in the page
  */
-export function generateHydrationScript(clientCode, containerId = 'main-content') {
+export function generateHydrationScript(clientCode) {
   // Escape the code for embedding in a script tag
   const escapedCode = clientCode
     .replace(/\\/g, '\\\\')
@@ -330,7 +522,7 @@ export function generateHydrationScript(clientCode, containerId = 'main-content'
     <!-- React runtime for MDX hydration (built from node_modules) -->
     <script src="/public/react-runtime.js"></script>
     
-    <!-- MDX Hydration -->
+    <!-- MDX island hydration -->
     <script>
     (function() {
       // getMDXComponent: matches mdx-bundler/client calling convention.
@@ -344,23 +536,30 @@ export function generateHydrationScript(clientCode, containerId = 'main-content'
         var mdxExport = fn(React, ReactDOM, _jsx_runtime);
         return mdxExport.default;
       }
-      
-      // Hydrate when DOM is ready
+
+      // Hydrate when DOM is ready. Running after the template's own
+      // DOMContentLoaded handlers is fine: islands are found by id, so it
+      // does not matter where sectionify has moved them.
       function hydrate() {
         try {
-          var container = document.getElementById('${containerId}');
-          if (!container) {
-            console.error('MDX hydration: container #${containerId} not found');
+          if (!window.ReactDOM || !window.ReactDOM.createRoot) {
+            console.error('MDX hydration: React runtime not loaded');
+            return;
+          }
+          var islands = document.querySelectorAll('${ISLAND_TAG}[data-island]');
+          if (islands.length === 0) {
+            console.log('MDX hydration: no islands on this page');
             return;
           }
-          
+
           // MDX bundled code (compiled by mdx-bundler)
           var mdxCode = \`${escapedCode}\`;
           var Component = getMDXComponent(mdxCode);
-          
-          // Use hydrateRoot (React 18+)
-          window.ReactDOM.hydrateRoot(container, window.React.createElement(Component));
-          console.log('MDX hydration complete');
+
+          // Render into a detached root; each island hydrates itself in place.
+          var detached = document.createElement('div');
+          window.ReactDOM.createRoot(detached).render(window.React.createElement(Component));
+          console.log('MDX hydration: ' + islands.length + ' island(s)');
         } catch (err) {
           console.error('MDX hydration error:', err);
         }

package/src/helper/menuLabels.js

@@ -7,9 +7,9 @@
  * resolution rules here is what makes `menu-label: 'BNW - Brave New World'`
  * show up in both places instead of only in the sidebar.
  */
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, currentRecorder } from "./build/tracedFs.js";
 import { basename, extname, join } from "path";
-import { extractMetadata } from "./metadataExtractor.js";
+import { extractMetadata, isMetadataOnly } from "./metadataExtractor.js";
 import { stripHtml } from "./stripHtml.js";
 
 // Index file extensions to check for folder metadata
@@ -29,6 +29,32 @@ export function toDisplayName(filename) {
     .replace(/\b\w/g, c => c.toUpperCase());  // Capitalize first letter of each word
 }
 
+/**
+ * A document's frontmatter and whether it is metadata-only, or null when the
+ * file does not exist.
+ *
+ * When a build-graph node is computing, it may have pre-loaded this from the
+ * document's `docMeta` node into the active recorder's `frontmatter` map. A
+ * hit there records nothing further — the edge to `docMeta` already exists,
+ * and it is a projection that a body edit leaves unchanged. That is what
+ * keeps a paragraph edit from reaching the menu, the auto-indices and every
+ * breadcrumb beneath the folder. A miss reads the file (and records it).
+ *
+ * @param {string} filePath - Path to the source file
+ * @returns {{meta: object|null, isMetadataOnly: boolean}|null}
+ */
+export function readFrontmatterInfo(filePath) {
+  const cached = currentRecorder()?.frontmatter?.get(filePath);
+  if (cached !== undefined) return cached;
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf8');
+    return { meta: extractMetadata(content), isMetadataOnly: isMetadataOnly(content) };
+  } catch (e) {
+    return null;
+  }
+}
+
 /**
  * Read a single frontmatter key from a file, with HTML stripped.
  * @param {string} filePath - Path to the source file
@@ -37,9 +63,8 @@ export function toDisplayName(filename) {
  */
 function getFrontmatterString(filePath, key) {
   try {
-    if (!existsSync(filePath)) return null;
-    const content = readFileSync(filePath, 'utf8');
-    const metadata = extractMetadata(content);
+    const info = readFrontmatterInfo(filePath);
+    const metadata = info?.meta;
     if (metadata && metadata[key]) {
       return stripHtml(String(metadata[key]));
     }

package/src/helper/sourceTimestamps.js

@@ -0,0 +1,139 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { realpath, stat } from "fs/promises";
+import { relative, resolve, sep } from "path";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// When was a source document last edited?
+//
+// The recent-activity feed needs a per-document "last edited" time that does
+// not depend on when ursa happened to run. Two sources, in order:
+//
+// 1. git: the commit date of the last commit that touched the file. One
+//    `git log --name-only` pass over the source directory yields every file's
+//    latest commit in a single process, which is far cheaper than a `git log`
+//    per file. Files with uncommitted changes (per `git status`) are taken
+//    from the working tree instead, since the commit time predates the edit.
+// 2. filesystem mtime, for sources that are not in a git work tree, files git
+//    does not know about, and the uncommitted files above.
+//
+// A shallow clone (CI checkouts default to depth 1) truncates history, so
+// every file appears to have been edited in the one fetched commit. That is
+// detected and warned about; the fix is on the checkout side (fetch-depth: 0).
+// ---------------------------------------------------------------------------
+
+async function git(cwd, args) {
+  const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+/**
+ * Parse `git log --format=%x00%ct --name-only` output into a map of
+ * repo-relative path → last-commit time in ms. The log is newest-first, so the
+ * first commit a path appears under is its latest.
+ * @param {string} log
+ * @returns {Map<string, number>}
+ */
+export function parseGitLog(log) {
+  const times = new Map();
+  let current = 0;
+  for (const line of log.split("\n")) {
+    if (line.startsWith("\0")) {
+      current = Number(line.slice(1)) * 1000;
+    } else if (line && !times.has(line)) {
+      times.set(line, current);
+    }
+  }
+  return times;
+}
+
+/**
+ * Parse `git status --porcelain -z` output into the set of repo-relative paths
+ * with uncommitted changes (modified, added, untracked, renamed — any status).
+ * @param {string} status
+ * @returns {Set<string>}
+ */
+export function parseGitStatus(status) {
+  const dirty = new Set();
+  const entries = status.split("\0");
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    dirty.add(entry.slice(3));
+    // A rename entry ("R  new\0old") is followed by the original path
+    if (code[0] === "R" || code[0] === "C") i++;
+  }
+  return dirty;
+}
+
+/**
+ * Build a lookup of last-edited times for files under `sourceDir`.
+ *
+ * @param {string} sourceDir - Absolute path to the source directory
+ * @param {object} [options]
+ * @param {(msg: string) => void} [options.log] - Receives one-line status/warnings
+ * @returns {Promise<{ get: (file: string) => Promise<number>, source: 'git'|'mtime' }>}
+ */
+export async function buildSourceTimestampIndex(sourceDir, { log = () => {} } = {}) {
+  const dir = resolve(sourceDir);
+
+  async function mtime(file) {
+    try {
+      return (await stat(file)).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  // git reports the real path of the work tree; resolve symlinks (macOS
+  // /var → /private/var, for one) so paths line up with what git prints.
+  let realDir = dir;
+  let toplevel = null;
+  try {
+    realDir = await realpath(dir);
+    toplevel = (await git(realDir, ["rev-parse", "--show-toplevel"])).trim();
+  } catch {
+    // Not a git work tree, or git is not installed
+  }
+  if (!toplevel) {
+    return { get: mtime, source: "mtime" };
+  }
+
+  let committed;
+  let dirty;
+  const relSource = relative(toplevel, realDir) || ".";
+  try {
+    const [logOut, statusOut, shallow] = await Promise.all([
+      git(toplevel, ["log", "--format=%x00%ct", "--name-only", "--", relSource]),
+      git(toplevel, ["status", "--porcelain", "-z", "--untracked-files=all", "--", relSource]),
+      git(toplevel, ["rev-parse", "--is-shallow-repository"]),
+    ]);
+    committed = parseGitLog(logOut);
+    dirty = parseGitStatus(statusOut);
+    if (shallow.trim() === "true") {
+      log(
+        "⚠️  Source is a shallow git clone: every document appears last edited in the one fetched commit, " +
+          "so recent activity will be inaccurate. Fetch full history (e.g. actions/checkout fetch-depth: 0)."
+      );
+    }
+  } catch (e) {
+    log(`⚠️  git history unavailable (${e.message.split("\n")[0]}); using file mtimes for recent activity`);
+    return { get: mtime, source: "mtime" };
+  }
+
+  return {
+    source: "git",
+    async get(file) {
+      // Repo-relative path as git prints it: forward slashes on every platform
+      const fromSource = relative(dir, resolve(file));
+      const rel = (relSource === "." ? fromSource : `${relSource}/${fromSource}`).split(sep).join("/");
+      if (dirty.has(rel) || !committed.has(rel)) return mtime(file);
+      return committed.get(rel);
+    },
+  };
+}

package/src/helper/ursaConfig.js

@@ -56,56 +56,10 @@ export function getAndIncrementBuildId(sourceDir) {
   const newBuildId = currentBuildId + 1;
   
   config.buildId = newBuildId;
+  // Dropped in 0.96.0: last-edited times now come from git/mtime, not the
+  // build. Remove the stale map so it stops taking up the file.
+  delete config.contentTimestamps;
   saveUrsaConfig(sourceDir, config);
   
   return newBuildId;
 }
-
-/**
- * Load content timestamps from .ursa.json
- * These track when each file's content actually changed (not filesystem mtime)
- * @param {string} sourceDir - The source directory path
- * @returns {Map<string, number>} Map of relative file paths to timestamps
- */
-export function loadContentTimestamps(sourceDir) {
-  const config = loadUrsaConfig(sourceDir);
-  const timestamps = config.contentTimestamps || {};
-  return new Map(Object.entries(timestamps));
-}
-
-/**
- * Save content timestamps to .ursa.json
- * @param {string} sourceDir - The source directory path
- * @param {Map<string, number>} timestampMap - Map of relative file paths to timestamps
- */
-export function saveContentTimestamps(sourceDir, timestampMap) {
-  const config = loadUrsaConfig(sourceDir);
-  config.contentTimestamps = Object.fromEntries(timestampMap);
-  saveUrsaConfig(sourceDir, config);
-}
-
-/**
- * Update the content timestamp for a single file
- * @param {string} sourceDir - The source directory path
- * @param {string} relativePath - The relative file path
- * @param {number} timestamp - The timestamp when content changed
- */
-export function updateContentTimestamp(sourceDir, relativePath, timestamp) {
-  const config = loadUrsaConfig(sourceDir);
-  if (!config.contentTimestamps) {
-    config.contentTimestamps = {};
-  }
-  config.contentTimestamps[relativePath] = timestamp;
-  saveUrsaConfig(sourceDir, config);
-}
-
-/**
- * Get the content timestamp for a file, or null if not tracked
- * @param {string} sourceDir - The source directory path
- * @param {string} relativePath - The relative file path
- * @returns {number|null} The timestamp or null
- */
-export function getContentTimestamp(sourceDir, relativePath) {
-  const config = loadUrsaConfig(sourceDir);
-  return config.contentTimestamps?.[relativePath] || null;
-}

package/src/helper/whitelistFilter.js

@@ -1,6 +1,5 @@
-import { readFile } from 'fs/promises';
+import { readFile, existsSync } from './build/tracedFs.js';
 import { resolve, relative } from 'path';
-import { existsSync } from 'fs';
 
 /**
  * Creates a filter function based on a whitelist file