@sdeverywhere/plugin-check 0.3.1 → 0.3.2

package/README.md

@@ -1,11 +1,32 @@
 # @sdeverywhere/plugin-check
 
-This package provides a plugin that runs model checks and comparison tests for a
-given SDEverywhere-generated system dynamics model.
+This package provides a plugin that runs model checks and comparison tests for a given System Dynamics model generated by [SDEverywhere](https://github.com/climateinteractive/SDEverywhere).
+
+## Quick Start
+
+The best way to get started with SDEverywhere is to follow the [Quick Start](https://github.com/climateinteractive/SDEverywhere#quick-start) instructions.
+If you follow those instructions, the `@sdeverywhere/plugin-check` package will be added to your project automatically, in which case you can skip the next section and jump straight to the ["Usage"](#usage) section below.
+
+## Install
+
+```sh
+# npm
+npm install --save-dev @sdeverywhere/plugin-check
+
+# pnpm
+pnpm add -D @sdeverywhere/plugin-check
+
+# yarn
+yarn add -D @sdeverywhere/plugin-check
+```
+
+## Usage
+
+_TODO: This section needs to be fleshed out. In the meantime, you can refer to the API documentation below for the options used to configure this plugin._
 
 ## Documentation
 
-TODO
+API documentation (for plugin configuration options) is available in the [`docs`](./docs/index.md) directory.
 
 ## License
 

package/dist/index.cjs

@@ -17,6 +17,10 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
@@ -29,6 +33,10 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// ../../node_modules/.pnpm/tsup@7.2.0_typescript@5.2.2/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL("file:" + __filename).href : document.currentScript && document.currentScript.src || new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
 // src/plugin.ts
 var import_fs2 = require("fs");
 var import_promises = require("fs/promises");
@@ -177,9 +185,8 @@ function sdeNameForVensimVarName(varName) {
 }
 
 // src/vite-config-for-bundle.ts
-var import_meta = {};
-var __filename = (0, import_url.fileURLToPath)(import_meta.url);
-var __dirname = (0, import_path.dirname)(__filename);
+var __filename2 = (0, import_url.fileURLToPath)(importMetaUrl);
+var __dirname = (0, import_path.dirname)(__filename2);
 function injectModelSpec(prepDir, modelSpec) {
   const inputSpecs = modelSpec.inputs.map((i) => {
     const varId = sdeNameForVensimVarName(i.varName);
@@ -228,20 +235,58 @@ export const dataSizeInBytes = ${dataSizeInBytes};
     }
   };
 }
+function overrideViteResolvePlugin(viteConfig) {
+  const resolvePlugin = viteConfig.plugins.find((p) => p.name === "vite:resolve");
+  if (resolvePlugin === void 0) {
+    throw new Error("Failed to locate the built-in vite:resolve plugin");
+  }
+  const originalResolveId = resolvePlugin.resolveId;
+  resolvePlugin.resolveId = async function resolveId(id, importer, options) {
+    if (id.startsWith("./implementation") && importer.includes("threads/dist-esm")) {
+      const idFileName = id.replace("./", "");
+      const importerFileName = (0, import_path.basename)(importer);
+      const resolvedId = importer.replace(importerFileName, `${idFileName}.js`);
+      return {
+        id: resolvedId,
+        moduleSideEffects: false
+      };
+    }
+    return originalResolveId.call(this, id, importer, options);
+  };
+}
 async function createViteConfigForBundle(prepDir, modelSpec) {
   const root = (0, import_path.resolve)(__dirname, "..", "template-bundle");
   const outDir = (0, import_path.relative)(root, prepDir);
   const modelWorkerPath = (0, import_path.join)(prepDir, "staged", "model", "worker.js?raw");
   return {
+    // Don't use an external config file
     configFile: false,
+    // Use the root directory configured above
     root,
+    // Don't clear the screen in dev mode so that we can see builder output
     clearScreen: false,
+    // TODO: Disable vite output by default?
+    // logLevel: 'silent',
+    // Configure path aliases
     resolve: {
       alias: [
+        // Inject the configured model worker
         {
           find: "@_model_worker_",
           replacement: modelWorkerPath
         },
+        // XXX: Prevent Vite from using the `browser` section of `threads/package.json`
+        // since we want to force the use of the general module (under dist-esm) that chooses
+        // the correct implementation (Web Worker vs worker_threads) at runtime.  Currently
+        // Vite's library mode is browser focused and generally chooses the right imports,
+        // except in the case of the threads package where we want to use the generic
+        // `implementation.js` that chooses between Web Worker and worker_threads at runtime.
+        // Note that we could in theory set `resolve.browserField` to false, but that would
+        // make Vite not use the browser field for all other packages, and there is not
+        // currently a way to tell Vite to use the browser field on a case-by-case basis.
+        // So for now we need this workaround here to make it resolve to `dist-esm`, and then
+        // a second workaround in `overrideViteResolvePlugin` to prevent the resolver from
+        // using the browser field when resolving the threads package.
         {
           find: "threads",
           replacement: "threads",
@@ -258,18 +303,40 @@ async function createViteConfigForBundle(prepDir, modelSpec) {
       ]
     },
     plugins: [
-      injectModelSpec(prepDir, modelSpec)
+      // Use a virtual module plugin to inject the model spec values
+      injectModelSpec(prepDir, modelSpec),
+      // XXX: Install a wrapper around the built-in `vite:resolve` plugin so that we can
+      // override the default resolver behavior that tries to resolve the `browser` section
+      // of the `package.json` for the threads package.
+      {
+        name: "vite-plugin-override-resolve",
+        configResolved(viteConfig) {
+          overrideViteResolvePlugin(viteConfig);
+        }
+      }
     ],
     build: {
+      // Write output files to the configured directory (instead of the default `dist`);
+      // note that this must be relative to the project `root`
       outDir,
       emptyOutDir: false,
+      // Uncomment for debugging purposes
+      // minify: false,
       lib: {
         entry: "./src/index.ts",
         formats: ["es"],
         fileName: () => "check-bundle.js"
       },
       rollupOptions: {
+        // Don't transform Node imports used by threads.js
         external: ["events", "os", "path", "url"],
+        // XXX: Insert custom code at the top of the generated bundle that defines
+        // the special `__non_webpack_require__` function that is used by threads.js
+        // in its Node implementation.  This import ensures that threads.js uses
+        // the native `worker_threads` implementation when using the bundle in a
+        // Node environment.  When importing the bundle for use in the browser,
+        // Vite will transform this import into an empty module due to the empty
+        // polyfill that is configured in `vite-config-for-report.ts`.
         output: {
           banner: `
 import * as worker_threads from 'worker_threads'
@@ -292,18 +359,16 @@ let __non_webpack_require__ = () => {
 var import_path2 = require("path");
 var import_url2 = require("url");
 var import_plugin_replace = __toESM(require("@rollup/plugin-replace"), 1);
-var import_meta2 = {};
-var __filename2 = (0, import_url2.fileURLToPath)(import_meta2.url);
-var __dirname2 = (0, import_path2.dirname)(__filename2);
+var __filename3 = (0, import_url2.fileURLToPath)(importMetaUrl);
+var __dirname2 = (0, import_path2.dirname)(__filename3);
 function createViteConfigForReport(options, projDir, prepDir, currentBundleName, currentBundlePath, testConfigPath, suiteSummary) {
-  var _a;
   const root = (0, import_path2.resolve)(__dirname2, "..", "template-report");
   const templateSrcDir = (0, import_path2.resolve)(root, "src");
   const relProjDir = (0, import_path2.relative)(templateSrcDir, projDir);
   const relProjDirPath = relProjDir.replaceAll("\\", "/");
   const baselinesPath = `${relProjDirPath}/baselines/*.js`;
   let reportPath;
-  if (options == null ? void 0 : options.reportPath) {
+  if (options?.reportPath) {
     reportPath = options.reportPath;
   } else {
     reportPath = (0, import_path2.join)(prepDir, "check-report");
@@ -323,57 +388,113 @@ function createViteConfigForReport(options, projDir, prepDir, currentBundleName,
     };
   };
   return {
+    // Don't use an external config file
     configFile: false,
+    // Use the root directory configured above
     root,
+    // Use `.` as the base directory (instead of the default `/`); this controls
+    // how the path to the js/css files are generated in `index.html`
     base: "",
+    // Use a custom cache directory under `prepDir`, as otherwise Vite will use
+    // `packages/plugin-check/template-report/node_modules/.vite`, and we want to
+    // avoid generating files in `template-report` (which should be read-only)
     cacheDir: (0, import_path2.join)(prepDir, ".vite-check-report"),
+    // Load static files from `static` (instead of the default `public`)
+    // publicDir: 'static',
+    // Don't clear the screen in dev mode so that we can see builder output
     clearScreen: false,
+    // TODO
+    // logLevel: 'silent',
     optimizeDeps: {
+      // Prevent Vite from examining other html files when scanning entrypoints
+      // for dependency optimization
       entries: ["index.html"],
+      // XXX: When plugin-check is installed via pnpm, the Vite dev server seems
+      // to have no trouble resolving other dependencies using the optimizeDeps
+      // mechanism.  However, this fails when the package is installed via yarn
+      // or npm (probably due to the fact that the `template-report` directory
+      // is located under the top-level `node_modules` directory); in the browser,
+      // there will be "import not found" errors for the packages referenced below.
+      // As a terrible workaround, explicitly include the direct dependencies so
+      // that Vite optimizes them; this works for pnpm, yarn, and npm.  We should
+      // find a less fragile solution.
       include: [
-        "assert-never",
-        "ajv",
-        "neverthrow",
-        "yaml",
-        "fontfaceobserver",
-        "copy-text-to-clipboard",
-        "chart.js"
+        // from check-core
+        "@sdeverywhere/check-core > assert-never",
+        "@sdeverywhere/check-core > ajv",
+        "@sdeverywhere/check-core > neverthrow",
+        "@sdeverywhere/check-core > yaml",
+        // from check-ui-shell
+        "@sdeverywhere/check-ui-shell > fontfaceobserver",
+        "@sdeverywhere/check-ui-shell > copy-text-to-clipboard",
+        "@sdeverywhere/check-ui-shell > chart.js"
       ],
       exclude: [
-        "tiny-worker",
-        "moment"
+        // XXX: The threads.js implementation references `tiny-worker` as an optional
+        // dependency, but it doesn't get used at runtime, so we can just exclude it
+        // so that Vite doesn't complain in dev mode
+        "tiny-worker"
+        // XXX: Similarly, chart.js treats `moment` as an optional dependency, but we
+        // don't use it at runtime; we need to exclude it here, otherwise Vite will
+        // complain about missing dependencies in dev mode
+        // 'moment'
       ]
     },
+    // Configure path aliases
     resolve: {
       alias: [
-        alias("@_baseline_bundle_", (options == null ? void 0 : options.baseline) ? options.baseline.path : "/src/empty-bundle.ts"),
+        // Use the configured "baseline" bundle if defined, otherwise use the "empty" bundle
+        // (which will cause comparison tests to be skipped)
+        alias("@_baseline_bundle_", options?.baseline ? options.baseline.path : "/src/empty-bundle.ts"),
+        // Use the configured "current" bundle
         alias("@_current_bundle_", currentBundlePath),
+        // Use the configured test config file
         alias("@_test_config_", testConfigPath),
+        // Make the overlay use the `messages.html` file that is written to the prep directory
         alias("@_prep_", prepDir),
+        // XXX: Include no-op polyfills for these modules that are used in the Node-specific
+        // implementation of threads.js; this allows us to use one bundle that works in both
+        // Node and browser environments
         noopPolyfillAlias("events"),
+        noopPolyfillAlias("fs"),
         noopPolyfillAlias("os"),
         noopPolyfillAlias("path"),
-        noopPolyfillAlias("url")
+        noopPolyfillAlias("url"),
+        noopPolyfillAlias("worker_threads")
       ]
     },
+    // Inject special values into the generated JS
     define: {
+      // Inject the summary JSON into the build
       __SUITE_SUMMARY_JSON__: JSON.stringify(suiteSummaryJson),
-      __BASELINE_NAME__: JSON.stringify(((_a = options == null ? void 0 : options.baseline) == null ? void 0 : _a.name) || ""),
+      // Inject the baseline branch name
+      __BASELINE_NAME__: JSON.stringify(options?.baseline?.name || ""),
+      // Inject the current branch name
       __CURRENT_NAME__: JSON.stringify(currentBundleName)
     },
     plugins: [
+      // Inject special values into the generated JS
+      // TODO: We currently have to use `@rollup/plugin-replace` instead of Vite's
+      // built-in `define` feature because the latter does not seem to run before
+      // the glob handler (which requires the glob to be injected as a literal)
       (0, import_plugin_replace.default)({
         preventAssignment: true,
+        delimiters: ["", ""],
         values: {
-          __BASELINE_BUNDLES_PATH__: JSON.stringify(baselinesPath)
+          // Inject the path for baseline bundles
+          "./__BASELINE_BUNDLES_PATH__": baselinesPath
         }
       })
     ],
     build: {
+      // Write output files to the configured directory (instead of the default `dist`);
+      // note that this must be relative to the project `root`
       outDir,
+      // Write js/css files to `public` (instead of the default `<outDir>/assets`)
       assetsDir: "",
       rollupOptions: {
         output: {
+          // XXX: Prevent vite from creating a separate `vendor.js` file
           manualChunks: void 0
         },
         onwarn: (warning, warn) => {
@@ -384,8 +505,14 @@ function createViteConfigForReport(options, projDir, prepDir, currentBundleName,
       }
     },
     server: {
-      port: (options == null ? void 0 : options.serverPort) || 8081,
+      // Run the dev server at `localhost:8081` by default
+      port: options?.serverPort || 8081,
+      // Open the app in the browser by default
       open: "/index.html",
+      // XXX: Add a small delay, otherwise on macOS we sometimes get multiple
+      // change events when a file is saved just once.  That is a relatively
+      // harmless issue except that it causes redundant messages in the console
+      // and can cause extra churn when refreshing the app.
       watch: {
         awaitWriteFinish: {
           stabilityThreshold: 100
@@ -398,9 +525,9 @@ function createViteConfigForReport(options, projDir, prepDir, currentBundleName,
 // src/vite-config-for-tests.ts
 var import_path3 = require("path");
 var import_url3 = require("url");
-var import_meta3 = {};
-var __filename3 = (0, import_url3.fileURLToPath)(import_meta3.url);
-var __dirname3 = (0, import_path3.dirname)(__filename3);
+var import_plugin_replace2 = __toESM(require("@rollup/plugin-replace"), 1);
+var __filename4 = (0, import_url3.fileURLToPath)(importMetaUrl);
+var __dirname3 = (0, import_path3.dirname)(__filename4);
 function createViteConfigForTests(projDir, prepDir, mode) {
   const root = (0, import_path3.resolve)(__dirname3, "..", "template-tests");
   const templateSrcDir = (0, import_path3.resolve)(root, "src");
@@ -409,13 +536,31 @@ function createViteConfigForTests(projDir, prepDir, mode) {
   const yamlPath = `${relProjDirPath}/**/*.check.yaml`;
   const outDir = (0, import_path3.relative)(root, prepDir);
   return {
+    // Don't use an external config file
     configFile: false,
+    // Use the root directory configured above
     root,
+    // Don't clear the screen in dev mode so that we can see builder output
     clearScreen: false,
-    define: {
-      __YAML_PATH__: JSON.stringify(yamlPath)
-    },
+    // TODO: Disable vite output by default?
+    // logLevel: 'silent',
+    plugins: [
+      // Inject special values into the generated JS
+      // TODO: We currently have to use `@rollup/plugin-replace` instead of Vite's
+      // built-in `define` feature because the latter does not seem to run before
+      // the glob handler (which requires the glob to be injected as a literal)
+      (0, import_plugin_replace2.default)({
+        preventAssignment: true,
+        delimiters: ["", ""],
+        values: {
+          // Inject the glob pattern for matching check yaml files
+          "./__YAML_PATH__": yamlPath
+        }
+      })
+    ],
     build: {
+      // Write output files to the configured directory (instead of the default `dist`);
+      // note that this must be relative to the project `root`
       outDir,
       emptyOutDir: false,
       lib: {
@@ -423,14 +568,24 @@ function createViteConfigForTests(projDir, prepDir, mode) {
         formats: ["es"],
         fileName: () => "check-tests.js"
       },
+      // Enable watch mode if requested
       watch: mode === "watch" && {},
-      rollupOptions: {}
+      rollupOptions: {
+        // Prevent dependencies from being included in packaged library
+        // TODO: For now we include check-core in the packaged library so that its
+        // dependencies are correctly resolved at runtime.  Ideally this would only
+        // include a couple functions that are used for defining tests, but Vite 2.x
+        // does not implement tree shaking for ES libraries, which means the generated
+        // library is much larger than it needs to be.  Once we upgrade to Vite 3.x,
+        // the generated library should be smaller; see related fix:
+        //   https://github.com/vitejs/vite/pull/8737
+        // external: Object.keys(pkg.dependencies)
+      }
     }
   };
 }
 
 // src/plugin.ts
-var import_meta4 = {};
 function checkPlugin(options) {
   return new CheckPlugin(options);
 }
@@ -440,8 +595,7 @@ var CheckPlugin = class {
     this.firstBuild = true;
   }
   async watch(config) {
-    var _a;
-    if (((_a = this.options) == null ? void 0 : _a.testConfigPath) === void 0) {
+    if (this.options?.testConfigPath === void 0) {
       await this.genTestConfig(config, "watch");
     }
     const testOptions = this.resolveTestOptions(config);
@@ -450,8 +604,12 @@ var CheckPlugin = class {
     await server.listen();
     const baselinesDir = "baselines";
     const watcher = import_chokidar.default.watch(baselinesDir, {
+      // Watch paths are resolved relative to the project root directory
       cwd: config.rootDir,
+      // Don't send initial "file added" events
       ignoreInitial: true,
+      // XXX: Include a delay, otherwise on macOS we sometimes get multiple
+      // change events when a file is saved just once
       awaitWriteFinish: {
         stabilityThreshold: 200
       }
@@ -459,18 +617,22 @@ var CheckPlugin = class {
     watcher.on("add", () => server.restart());
     watcher.on("unlink", () => server.restart());
   }
+  // TODO: Note that this plugin runs as a `postBuild` step because it currently
+  // needs to run after other plugins, and those plugins need to run after the
+  // staged files are copied to their final destination(s).  We should probably
+  // make it configurable so that it can either be run as a `postGenerate` or a
+  // `postBuild` step.
   async postBuild(context, modelSpec) {
-    var _a, _b;
     const firstBuild = this.firstBuild;
     this.firstBuild = false;
-    if (((_a = this.options) == null ? void 0 : _a.current) === void 0) {
+    if (this.options?.current === void 0) {
       if (context.config.mode === "development") {
         await this.copyPreviousBundle(context.config);
       }
       context.log("info", "Generating model check bundle...");
       await this.genCurrentBundle(context.config, modelSpec);
     }
-    if (((_b = this.options) == null ? void 0 : _b.testConfigPath) === void 0) {
+    if (this.options?.testConfigPath === void 0) {
       if (context.config.mode === "production" || firstBuild) {
         context.log("info", "Generating model check test configuration...");
         await this.genTestConfig(context.config, "build");
@@ -506,14 +668,13 @@ var CheckPlugin = class {
     await (0, import_vite.build)(viteConfig);
   }
   async runChecks(context, testOptions) {
-    var _a;
     context.log("info", "Running model checks...");
     const moduleR = await import(relativeToSourcePath(testOptions.currentBundlePath));
     const bundleR = moduleR.createBundle();
     const bundleNameR = testOptions.currentBundleName;
     let bundleL;
     let bundleNameL;
-    if ((_a = this.options) == null ? void 0 : _a.baseline) {
+    if (this.options?.baseline) {
       const moduleL = await import(relativeToSourcePath(this.options.baseline.path));
       const rawBundleL = moduleL.createBundle();
       if (rawBundleL.version === bundleR.version) {
@@ -528,17 +689,21 @@ var CheckPlugin = class {
     };
     const configOptions = await testConfigModule.getConfigOptions(bundleL, bundleR, configInitOptions);
     const checkConfig = await (0, import_check_core2.createConfig)(configOptions);
-    const result = await runTestSuite(context, checkConfig, false);
+    const result = await runTestSuite(
+      context,
+      checkConfig,
+      /*verbose=*/
+      false
+    );
     context.log("info", "Building model check report");
     const viteConfig = this.createViteConfigForReport(context.config, testOptions, result.suiteSummary);
     await (0, import_vite.build)(viteConfig);
     return result.allChecksPassed;
   }
   resolveTestOptions(config) {
-    var _a, _b;
     let currentBundleName;
     let currentBundlePath;
-    if (((_a = this.options) == null ? void 0 : _a.current) === void 0) {
+    if (this.options?.current === void 0) {
       currentBundleName = "current";
       currentBundlePath = (0, import_path4.join)(config.prepDir, "check-bundle.js");
     } else {
@@ -546,7 +711,7 @@ var CheckPlugin = class {
       currentBundlePath = this.options.current.path;
     }
     let testConfigPath;
-    if (((_b = this.options) == null ? void 0 : _b.testConfigPath) === void 0) {
+    if (this.options?.testConfigPath === void 0) {
       testConfigPath = (0, import_path4.join)(config.prepDir, "check-tests.js");
     } else {
       testConfigPath = this.options.testConfigPath;
@@ -570,7 +735,7 @@ var CheckPlugin = class {
   }
 };
 function relativeToSourcePath(filePath) {
-  const srcDir = (0, import_path4.dirname)((0, import_url4.fileURLToPath)(import_meta4.url));
+  const srcDir = (0, import_path4.dirname)((0, import_url4.fileURLToPath)(importMetaUrl));
   const relPath = (0, import_path4.relative)(srcDir, filePath);
   return relPath.replaceAll("\\", "/");
 }