@sdeverywhere/build 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -0,0 +1,440 @@
+import { Result } from 'neverthrow';
+
+type LogLevel = 'error' | 'info' | 'verbose';
+
+/**
+ * The mode used for the build process, either 'development' for local "dev mode"
+ * (with live reload, etc) or 'production' for generating a production-ready build.
+ */
+type BuildMode = 'development' | 'production';
+
+/**
+ * Describes a model input variable.
+ */
+interface InputSpec {
+    /**
+     * The stable input identifier.  It is recommended to set this to a value (for example, a
+     * numeric string like what `plugin-config` uses) that is separate from `varName` and is
+     * stable between two versions of the model.  This way, if an input variable is renamed
+     * between two versions of the model, comparisons can still be performed between the two.
+     * If a distinct `inputId` is not available, plugins can infer one from `varName`, but
+     * note that this approach will be less resilient to renames.
+     */
+    inputId?: string;
+    /** The variable name (as used in the modeling tool). */
+    varName: string;
+    /** The default value for the input. */
+    defaultValue: number;
+    /** The minimum value for the input. */
+    minValue: number;
+    /** The maximum value for the input. */
+    maxValue: number;
+}
+/**
+ * Describes a model output variable.
+ */
+interface OutputSpec {
+    /** The variable name (as used in the modeling tool). */
+    varName: string;
+}
+/**
+ * Describes a model (e.g., a Vensim mdl file) and the input/output variables
+ * that should be included in the model generated by SDE.
+ */
+interface ModelSpec {
+    /** The input variable specs. */
+    inputs: InputSpec[];
+    /** The output variable specs. */
+    outputs: OutputSpec[];
+    /** The dat files to be included with the SDE `spec.json` file. */
+    datFiles: string[];
+    /** Additional options included with the SDE `spec.json` file. */
+    options?: {
+        [key: string]: any;
+    };
+}
+
+/**
+ * The sde configuration derived from a `UserConfig` that has been resolved (i.e.,
+ * paths have been checked).  This is the config object that will be passed to
+ * plugin functions.  It contains a subset of the original `UserConfig` (to disallow
+ * access to the `plugins` field of the original config).
+ */
+interface ResolvedConfig {
+    /**
+     * The mode used for the build process, either 'development' or 'production'.
+     */
+    mode: BuildMode;
+    /**
+     * The absolute path to the project root directory, which has been confirmed to exist.
+     */
+    rootDir: string;
+    /**
+     * The absolute path to the directory used to prepare the model.  This directory has
+     * been created if it did not previously exist.
+     */
+    prepDir: string;
+    /**
+     * The mdl files to be built.
+     */
+    modelFiles: string[];
+    /**
+     * Paths to files that are considered to be inputs to the model build process.
+     * These can be paths to files or glob patterns (relative to the project directory).
+     */
+    modelInputPaths: string[];
+    /**
+     * Paths to files that when changed will trigger a rebuild in watch mode.  These
+     * can be paths to files or glob patterns (relative to the project directory).
+     */
+    watchPaths: string[];
+    /**
+     * The path to the `@sdeverywhere/cli` package.  This is currently only used to get
+     * access to the files in the `src/c` directory.
+     * @hidden This should be removed once we have tighter integration with the `cli` package.
+     */
+    sdeDir: string;
+    /**
+     * The path to the `sde` command.
+     * @hidden This should be removed once we have tighter integration with the `cli` package.
+     */
+    sdeCmdPath: string;
+}
+
+/**
+ * @hidden This isn't ready to be included in the public API just yet.
+ */
+interface ProcessOptions {
+    logOutput?: boolean;
+    ignoredMessageFilter?: string;
+    captureOutput?: boolean;
+    ignoreError?: boolean;
+}
+/**
+ * @hidden This isn't ready to be included in the public API just yet.
+ */
+interface ProcessOutput {
+    exitCode: number;
+    stdoutMessages: string[];
+    stderrMessages: string[];
+}
+
+declare class StagedFiles {
+    private readonly baseStagedDir;
+    private readonly stagedFiles;
+    constructor(prepDir: string);
+    /**
+     * 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: string, srcFile: string, dstDir: string, dstFile: string): string;
+    /**
+     * 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: string, dstDir: string, filename: string, content: string): void;
+    /**
+     * 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: string, srcFile: string): string;
+    /**
+     * 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: string, srcFile: string): boolean;
+    /**
+     * 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: string, srcFile: string): boolean;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private copyStagedFile;
+}
+
+/**
+ * Provides access to common functionality that is needed during the build process.
+ * This is passed to most plugin functions.
+ */
+declare class BuildContext {
+    readonly config: ResolvedConfig;
+    private readonly stagedFiles;
+    private readonly abortSignal;
+    /**
+     * @param config The resolved configuration.
+     * @hidden
+     */
+    constructor(config: ResolvedConfig, stagedFiles: StagedFiles, abortSignal: AbortSignal | undefined);
+    /**
+     * 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: LogLevel, msg: string): void;
+    /**
+     * 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: string, srcFile: string, dstDir: string, dstFile: string): string;
+    /**
+     * 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: string, dstDir: string, filename: string, content: string): void;
+    /**
+     * 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: string, command: string, args: string[], opts?: ProcessOptions): Promise<ProcessOutput>;
+}
+
+/**
+ * The plugin interface that can be implemented to customize the model
+ * generation and build process.
+ *
+ * These functions are all optional.
+ *
+ * These functions will be called during the build process in the order
+ * listed below:
+ *   - init (only called once before initial build steps)
+ *   - preGenerate
+ *       - preProcessMdl
+ *       - postProcessMdl
+ *       - preGenerateC
+ *       - postGenerateC
+ *   - postGenerate
+ *   - postBuild
+ *   - watch (only called once after initial build steps when mode==development)
+ */
+interface Plugin {
+    /**
+     * Called after the user configuration has been resolved, but before the
+     * model is generated and other build steps.
+     *
+     * @param config The build configuration.
+     */
+    init?(config: ResolvedConfig): Promise<void>;
+    /**
+     * Called before the "generate model" steps are performed.
+     *
+     * @param context The build context (for logging, etc).
+     * @param modelSpec The spec that controls how the model is generated.
+     */
+    preGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<void>;
+    /**
+     * Called before SDE preprocesses the mdl file (in the case of one mdl file),
+     * or before SDE flattens the mdl files (in the case of multiple mdl files).
+     *
+     * @param context The build context (for logging, etc).
+     */
+    preProcessMdl?(context: BuildContext): Promise<void>;
+    /**
+     * Called after SDE preprocesses the mdl file (in the case of one mdl file),
+     * or after SDE flattens the mdl files (in the case of multiple mdl files).
+     *
+     * @param context The build context (for logging, etc).
+     * @param mdlContent The resulting mdl file content.
+     * @return The modified mdl file content (if postprocessing was needed).
+     */
+    postProcessMdl?(context: BuildContext, mdlContent: string): Promise<string>;
+    /**
+     * Called before SDE generates a C file from the mdl file.
+     *
+     * @param context The build context (for logging, etc).
+     */
+    preGenerateC?(context: BuildContext): Promise<void>;
+    /**
+     * Called after SDE generates a C file from the mdl file.
+     *
+     * @param context The build context (for logging, etc).
+     * @param cContent The resulting C file content.
+     * @return The modified C file content (if postprocessing was needed).
+     */
+    postGenerateC?(context: BuildContext, cContent: string): Promise<string>;
+    /**
+     * Called after the "generate model" process has completed (but before the staged
+     * files are copied to their destination).
+     *
+     * @param context The build context (for logging, etc).
+     * @param modelSpec The spec that controls how the model is generated.
+     * @return Whether the plugin succeeded (for example, a plugin that runs tests can
+     * return false to indicate that one or more tests failed).
+     */
+    postGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
+    /**
+     * Called after the model has been generated and after the staged files
+     * have been copied to their destination.
+     *
+     * @param context The build context (for logging, etc).
+     * @param modelSpec The spec that controls how the model is generated.
+     * @return Whether the plugin succeeded (for example, a plugin that runs tests can
+     * return false to indicate that one or more tests failed).
+     */
+    postBuild?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
+    /**
+     * Called in development/watch mode after the initial build has completed
+     * (i.e., after the model has been generated and after the staged files
+     * have been copied to their destination).
+     *
+     * @param config The build configuration.
+     */
+    watch?(config: ResolvedConfig): Promise<void>;
+}
+
+/**
+ * The sde configuration as defined by the user, either inline or in a `sde.config.js` file.
+ */
+interface UserConfig {
+    /**
+     * The project root directory.  If undefined, the current directory is
+     * assumed to be the project root.  This directory should contain all the
+     * model and config files referenced during the build process.
+     */
+    rootDir?: string;
+    /**
+     * The directory used to prepare the model.  If undefined, an 'sde-prep'
+     * directory will be created under the resolved `rootDir`.
+     */
+    prepDir?: string;
+    /**
+     * The mdl files to be built (must provide one or more).
+     */
+    modelFiles: string[];
+    /**
+     * Paths to files that are considered to be inputs to the model build process.
+     * These can be paths to files or glob patterns (relative to the project directory).
+     * If left undefined, this will resolve to the `modelFiles` array.
+     */
+    modelInputPaths?: string[];
+    /**
+     * Paths to files that when changed will trigger a rebuild in watch mode.  These
+     * can be paths to files or glob patterns (relative to the project directory).
+     * If left undefined, this will resolve to the `modelFiles` array.
+     */
+    watchPaths?: string[];
+    /**
+     * The array of plugins that are used to customize the build process.  These will be
+     * executed in the order defined here.
+     */
+    plugins?: Plugin[];
+    /**
+     * Called before the "generate model" steps are performed.
+     *
+     * You must implement this function so that the generated model is
+     * configured with the desired inputs and outputs.
+     *
+     * @return A `ModelSpec` that defines the model inputs and outputs.
+     */
+    modelSpec: (context: BuildContext) => Promise<ModelSpec>;
+}
+
+interface BuildOptions {
+    /** The path to an `sde.config.js` file, or a `UserConfig` object. */
+    config?: string | UserConfig;
+    /**
+     * The log levels to include.  If undefined, the default 'info' and 'error' levels
+     * will be active.
+     */
+    logLevels?: LogLevel[];
+    /**
+     * The path to the `@sdeverywhere/cli` package.  This is currently only used to get
+     * access to the files in the `src/c` directory.
+     * @hidden This should be removed once we have tighter integration with the `cli` package.
+     */
+    sdeDir: string;
+    /**
+     * The path to the `sde` command.
+     * @hidden This should be removed once we have tighter integration with the `cli` package.
+     */
+    sdeCmdPath: string;
+}
+interface BuildResult {
+    /**
+     * The exit code that should be set by the process.  This will be undefined
+     * if `mode` is 'development', indicating that the process should be kept alive.
+     */
+    exitCode?: number;
+}
+/**
+ * Initiate the build process, which can either be a single build if `mode` is
+ * 'production', or a live development environment if `mode` is 'development'.
+ *
+ * @param mode The build mode.
+ * @param options The build options.
+ * @return An `ok` result if the build completed, otherwise an `err` result.
+ */
+declare function build(mode: BuildMode, options: BuildOptions): Promise<Result<BuildResult, Error>>;
+
+export { BuildContext, BuildMode, BuildOptions, BuildResult, InputSpec, LogLevel, ModelSpec, OutputSpec, Plugin, ResolvedConfig, UserConfig, build };

package/dist/index.d.ts

@@ -1,17 +1,26 @@
 import { Result } from 'neverthrow';
 
-declare type LogLevel = 'error' | 'info' | 'verbose';
+type LogLevel = 'error' | 'info' | 'verbose';
 
 /**
  * The mode used for the build process, either 'development' for local "dev mode"
  * (with live reload, etc) or 'production' for generating a production-ready build.
  */
-declare type BuildMode = 'development' | 'production';
+type BuildMode = 'development' | 'production';
 
 /**
  * Describes a model input variable.
  */
 interface InputSpec {
+    /**
+     * The stable input identifier.  It is recommended to set this to a value (for example, a
+     * numeric string like what `plugin-config` uses) that is separate from `varName` and is
+     * stable between two versions of the model.  This way, if an input variable is renamed
+     * between two versions of the model, comparisons can still be performed between the two.
+     * If a distinct `inputId` is not available, plugins can infer one from `varName`, but
+     * note that this approach will be less resilient to renames.
+     */
+    inputId?: string;
     /** The variable name (as used in the modeling tool). */
     varName: string;
     /** The default value for the input. */
@@ -283,14 +292,14 @@ interface Plugin {
      * @param context The build context (for logging, etc).
      * @param modelSpec The spec that controls how the model is generated.
      */
-    preGenerate?: (context: BuildContext, modelSpec: ModelSpec) => Promise<void>;
+    preGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<void>;
     /**
      * Called before SDE preprocesses the mdl file (in the case of one mdl file),
      * or before SDE flattens the mdl files (in the case of multiple mdl files).
      *
      * @param context The build context (for logging, etc).
      */
-    preProcessMdl?: (context: BuildContext) => Promise<void>;
+    preProcessMdl?(context: BuildContext): Promise<void>;
     /**
      * Called after SDE preprocesses the mdl file (in the case of one mdl file),
      * or after SDE flattens the mdl files (in the case of multiple mdl files).
@@ -299,13 +308,13 @@ interface Plugin {
      * @param mdlContent The resulting mdl file content.
      * @return The modified mdl file content (if postprocessing was needed).
      */
-    postProcessMdl?: (context: BuildContext, mdlContent: string) => Promise<string>;
+    postProcessMdl?(context: BuildContext, mdlContent: string): Promise<string>;
     /**
      * Called before SDE generates a C file from the mdl file.
      *
      * @param context The build context (for logging, etc).
      */
-    preGenerateC?: (context: BuildContext) => Promise<void>;
+    preGenerateC?(context: BuildContext): Promise<void>;
     /**
      * Called after SDE generates a C file from the mdl file.
      *
@@ -313,7 +322,7 @@ interface Plugin {
      * @param cContent The resulting C file content.
      * @return The modified C file content (if postprocessing was needed).
      */
-    postGenerateC?: (context: BuildContext, cContent: string) => Promise<string>;
+    postGenerateC?(context: BuildContext, cContent: string): Promise<string>;
     /**
      * Called after the "generate model" process has completed (but before the staged
      * files are copied to their destination).
@@ -323,7 +332,7 @@ interface Plugin {
      * @return Whether the plugin succeeded (for example, a plugin that runs tests can
      * return false to indicate that one or more tests failed).
      */
-    postGenerate?: (context: BuildContext, modelSpec: ModelSpec) => Promise<boolean>;
+    postGenerate?(context: BuildContext, modelSpec: ModelSpec): Promise<boolean>;
     /**
      * Called after the model has been generated and after the staged files
      * have been copied to their destination.