@sdeverywhere/build 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,30 @@
 # @sdeverywhere/build
 
-This package provides the core build and plugin API for SDEverywhere.
+This package provides the core build and plugin API for [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/build` package will be added to your project automatically, in which case you can skip the following section.
+
+## Install
+
+```sh
+# npm
+npm install --save-dev @sdeverywhere/build
+
+# pnpm
+pnpm add -D @sdeverywhere/build
+
+# yarn
+yarn add -D @sdeverywhere/build
+```
+
+## Usage
+
+Most users do not need to interact with the `@sdeverywhere/build` package directly; it is primarily used in the implementation of the `sde` command line tool (from the `@sdeverywhere/cli` package).
+
+However, if you are building a custom plugin or a tool that drives the build process programmatically, you can refer to the API documentation below for more details.
 
 ## Documentation
 

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/build/build.ts
 var import_path7 = require("path");
 var import_neverthrow3 = require("neverthrow");
@@ -38,7 +46,6 @@ var import_fs = require("fs");
 var import_path = require("path");
 var import_url = require("url");
 var import_neverthrow = require("neverthrow");
-var import_meta = {};
 async function loadConfig(mode, config, sdeDir, sdeCmdPath) {
   let userConfig;
   if (typeof config === "object") {
@@ -126,7 +133,7 @@ function resolveUserConfig(userConfig, mode, sdeDir, sdeCmdPath) {
   };
 }
 function relativeToSourcePath(filePath) {
-  const srcDir = (0, import_path.dirname)((0, import_url.fileURLToPath)(import_meta.url));
+  const srcDir = (0, import_path.dirname)((0, import_url.fileURLToPath)(importMetaUrl));
   const relPath = (0, import_path.relative)(srcDir, filePath);
   return relPath.replaceAll("\\", "/");
 }
@@ -210,7 +217,7 @@ var import_neverthrow2 = require("neverthrow");
 var import_cross_spawn = require("cross-spawn");
 function spawnChild(cwd, command, args, abortSignal, opts) {
   return new Promise((resolve, reject) => {
-    if (abortSignal == null ? void 0 : abortSignal.aborted) {
+    if (abortSignal?.aborted) {
       reject(new Error("ABORT"));
       return;
     }
@@ -229,12 +236,12 @@ function spawnChild(cwd, command, args, abortSignal, opts) {
       }
       reject(new Error("ABORT"));
     };
-    abortSignal == null ? void 0 : abortSignal.addEventListener("abort", abortHandler, { once: true });
+    abortSignal?.addEventListener("abort", abortHandler, { once: true });
     const stdoutMessages = [];
     const stderrMessages = [];
     const logMessage = (msg, err4) => {
       let includeMessage = true;
-      if ((opts == null ? void 0 : opts.ignoredMessageFilter) && msg.trim().startsWith(opts.ignoredMessageFilter)) {
+      if (opts?.ignoredMessageFilter && msg.trim().startsWith(opts.ignoredMessageFilter)) {
         includeMessage = false;
       }
       if (includeMessage) {
@@ -249,19 +256,19 @@ function spawnChild(cwd, command, args, abortSignal, opts) {
     });
     childProc.stdout.on("data", (data) => {
       const msg = data.toString();
-      if ((opts == null ? void 0 : opts.captureOutput) === true) {
+      if (opts?.captureOutput === true) {
         stdoutMessages.push(msg);
       }
-      if ((opts == null ? void 0 : opts.logOutput) !== false) {
+      if (opts?.logOutput !== false) {
         logMessage(msg, false);
       }
     });
     childProc.stderr.on("data", (data) => {
       const msg = data.toString();
-      if ((opts == null ? void 0 : opts.captureOutput) === true) {
+      if (opts?.captureOutput === true) {
         stderrMessages.push(msg);
       }
-      if ((opts == null ? void 0 : opts.logOutput) !== false) {
+      if (opts?.logOutput !== false) {
         logMessage(msg, true);
       }
     });
@@ -269,7 +276,7 @@ function spawnChild(cwd, command, args, abortSignal, opts) {
       localLog(`Process error: ${err4}`, true);
     });
     childProc.on("close", (code, signal) => {
-      abortSignal == null ? void 0 : abortSignal.removeEventListener("abort", abortHandler);
+      abortSignal?.removeEventListener("abort", abortHandler);
       childProc = void 0;
       if (signal) {
         return;
@@ -282,7 +289,7 @@ function spawnChild(cwd, command, args, abortSignal, opts) {
       if (code === 0) {
         resolve(processOutput);
       } else if (!signal) {
-        if ((opts == null ? void 0 : opts.ignoreError) === true) {
+        if (opts?.ignoreError === true) {
           resolve(processOutput);
         } else {
           reject(new Error(`Child process failed (code=${code})`));
@@ -294,20 +301,69 @@ function spawnChild(cwd, command, args, abortSignal, opts) {
 
 // src/context/context.ts
 var BuildContext = class {
+  /**
+   * @param config The resolved configuration.
+   * @hidden
+   */
   constructor(config, stagedFiles, abortSignal) {
     this.config = config;
     this.stagedFiles = stagedFiles;
     this.abortSignal = abortSignal;
   }
+  /**
+   * Log a message to the console and/or the in-browser overlay panel.
+   *
+   * @param level The log level (verbose, info, error).
+   * @param msg The message.
+   */
   log(level, msg) {
     log(level, msg);
   }
+  /**
+   * Prepare for writing a file to the staged directory.
+   *
+   * This will add the path to the array of tracked files and will create the
+   * staged directory if needed.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file will be written (this must be a relative path).
+   * @param srcFile The name of the file as written to the `staged` directory.
+   * @param dstDir The absolute path to the destination directory where the staged
+   * file will be copied when the build has completed.
+   * @param dstFile The name of the file as written to the destination directory.
+   * @return The absolute path to the staged file.
+   */
   prepareStagedFile(srcDir, srcFile, dstDir, dstFile) {
     return this.stagedFiles.prepareStagedFile(srcDir, srcFile, dstDir, dstFile);
   }
+  /**
+   * Write a file to the staged directory.
+   *
+   * This file will be copied (along with other staged files) into the destination
+   * directory only after the build process has completed.  Copying all staged files
+   * at once helps improve the local development experience by making it so that
+   * live reloading tools only need to refresh once instead of every time a build
+   * file is written.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file will be written (this must be a relative path).
+   * @param dstDir The absolute path to the destination directory where the staged
+   * file will be copied when the build has completed.
+   * @param filename The name of the file.
+   * @param content The file content.
+   */
   writeStagedFile(srcDir, dstDir, filename, content) {
     this.stagedFiles.writeStagedFile(srcDir, dstDir, filename, content);
   }
+  /**
+   * Spawn a child process that runs the given command.
+   *
+   * @param cwd The directory in which the command will be executed.
+   * @param command The command to execute.
+   * @param args The arguments to pass to the command.
+   * @param opts Additional options to configure the process.
+   * @returns The output of the process.
+   */
   spawnChild(cwd, command, args, opts) {
     return spawnChild(cwd, command, args, this.abortSignal, opts);
   }
@@ -321,6 +377,20 @@ var StagedFiles = class {
     this.stagedFiles = [];
     this.baseStagedDir = (0, import_path2.join)(prepDir, "staged");
   }
+  /**
+   * Prepare for writing a file to the staged directory.
+   *
+   * This will add the path to the array of tracked files and will create the
+   * staged directory if needed.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file will be written (this must be a relative path).
+   * @param srcFile The name of the file as written to the `staged` directory.
+   * @param dstDir The absolute path to the destination directory where the staged
+   * file will be copied when the build has completed.
+   * @param dstFile The name of the file as written to the destination directory.
+   * @return The absolute path to the staged file.
+   */
   prepareStagedFile(srcDir, srcFile, dstDir, dstFile) {
     const stagedFile = {
       srcDir,
@@ -337,17 +407,54 @@ var StagedFiles = class {
     }
     return (0, import_path2.join)(stagedDir, srcFile);
   }
+  /**
+   * Write a file to the staged directory.
+   *
+   * This file will be copied (along with other staged files) into the destination
+   * directory only after the build process has completed.  Copying all staged files
+   * at once helps improve the local development experience by making it so that
+   * live reloading tools only need to refresh once instead of every time a build
+   * file is written.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file will be written (this must be a relative path).
+   * @param dstDir The absolute path to the destination directory where the staged
+   * file will be copied when the build has completed.
+   * @param filename The name of the file.
+   * @param content The file content.
+   */
   writeStagedFile(srcDir, dstDir, filename, content) {
     const stagedFilePath = this.prepareStagedFile(srcDir, filename, dstDir, filename);
     (0, import_fs3.writeFileSync)(stagedFilePath, content);
   }
+  /**
+   * Return the absolute path to the staged file for the given source directory and file name.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file would be written initially (this must be a relative path).
+   * @param srcFile The name of the file.
+   */
   getStagedFilePath(srcDir, srcFile) {
     return (0, import_path2.join)(this.baseStagedDir, srcDir, srcFile);
   }
+  /**
+   * Return true if the staged file exists for the given source directory and file name.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file would be written initially (this must be a relative path).
+   * @param srcFile The name of the file.
+   */
   stagedFileExists(srcDir, srcFile) {
     const fullSrcPath = this.getStagedFilePath(srcDir, srcFile);
     return (0, import_fs3.existsSync)(fullSrcPath);
   }
+  /**
+   * Return true if the destination file exists for the given source directory and file name.
+   *
+   * @param srcDir The directory underneath the configured `staged` directory where
+   * the file would be written initially (this must be a relative path).
+   * @param srcFile The name of the file.
+   */
   destinationFileExists(srcDir, srcFile) {
     const f = this.stagedFiles.find((f2) => f2.srcDir === srcDir && f2.srcFile === srcFile);
     if (f === void 0) {
@@ -356,6 +463,12 @@ var StagedFiles = class {
     const fullDstPath = (0, import_path2.join)(f.dstDir, f.dstFile);
     return (0, import_fs3.existsSync)(fullDstPath);
   }
+  /**
+   * Copy staged files to their destination; this will only copy the staged
+   * files if they are different than the existing destination files.  We
+   * copy the files in a batch like this so that hot module reload is only
+   * triggered once at the end of the whole build process.
+   */
   copyChangedFiles() {
     log("info", "Copying changed files into place...");
     for (const f of this.stagedFiles) {
@@ -363,6 +476,13 @@ var StagedFiles = class {
     }
     log("info", "Done copying files");
   }
+  /**
+   * Copy a file from the `staged` directory to its destination.  If the file already
+   * exists in the destination directory and has the same contents as the source file,
+   * the file will not be copied and this function will return false.
+   *
+   * @param f The staged file entry.
+   */
   copyStagedFile(f) {
     if (!(0, import_fs3.existsSync)(f.dstDir)) {
       (0, import_fs3.mkdirSync)(f.dstDir, { recursive: true });
@@ -489,8 +609,14 @@ async function flattenMdls(context, sdeCmdPath, prepDir, modelFiles) {
 async function generateC(context, sdeDir, sdeCmdPath, prepDir) {
   log("verbose", "  Generating C code");
   const command = sdeCmdPath;
-  const args = ["generate", "--genc", "--spec", "spec.json", "processed"];
-  await context.spawnChild(prepDir, command, args, {});
+  const gencArgs = ["generate", "--genc", "--spec", "spec.json", "processed"];
+  await context.spawnChild(prepDir, command, gencArgs, {
+    // By default, ignore lines that start with "WARNING: Data for" since these are often harmless
+    // TODO: Don't filter by default, but make it configurable
+    // ignoredMessageFilter: 'WARNING: Data for'
+  });
+  const listArgs = ["generate", "--list", "--spec", "spec.json", "processed"];
+  await context.spawnChild(prepDir, command, listArgs, {});
   const buildDir = (0, import_path3.join)(prepDir, "build");
   const sdeCDir = (0, import_path3.join)(sdeDir, "src", "c");
   const files = await (0, import_promises.readdir)(sdeCDir);
@@ -662,7 +788,10 @@ function watch(config, userConfig, plugins) {
     watchPaths = config.modelFiles;
   }
   const watcher = import_chokidar.default.watch(watchPaths, {
+    // Watch paths are resolved relative to the project root directory
     cwd: config.rootDir,
+    // XXX: Include a delay, otherwise on macOS we sometimes get multiple
+    // change events when the csv file is saved just once
     awaitWriteFinish: {
       stabilityThreshold: 200
     }