@sdeverywhere/build 0.3.16 → 0.3.18

package/dist/index.d.cts

@@ -1,603 +0,0 @@
-import { ModelSpec as ModelSpec$1 } from '@sdeverywhere/compile';
-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';
-
-/** A variable name as used in the modeling tool. */
-type VarName = string;
-/**
- * Describes a model input variable.
- */
-interface InputSpec {
-    /** The variable name (as used in the modeling tool). */
-    varName: VarName;
-    /**
-     * 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 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: VarName;
-}
-/**
- * The model spec properties that are shared with (and passed through unchanged to) the
- * `ModelSpec` type from the compile package.
- *
- * The `inputVarNames` and `outputVarNames` properties are excluded because this package
- * declares higher-level `inputs` and `outputs` properties in their place, which accept
- * richer `InputSpec` and `OutputSpec` forms in addition to plain variable names.  The
- * deprecated and derived properties from the compile package are excluded because a
- * `sde.config.js` file should only use the preferred names.
- */
-type CommonModelSpecProps = Omit<ModelSpec$1, 'inputVarNames' | 'outputVarNames' | 'externalDatfiles' | 'inputVars' | 'outputVars' | 'name'>;
-/**
- * The `CommonModelSpecProps` properties that are filled in with a default value when a
- * `ModelSpec` is resolved, and are therefore always defined in a `ResolvedModelSpec`.
- * These are redeclared in `ResolvedModelSpec` so that they can be documented in terms of
- * the resolved (non-optional) values.
- */
-type ResolvedModelSpecProps = Omit<CommonModelSpecProps, 'datFiles' | 'bundleListing' | 'customConstants' | 'customLookups' | 'customOutputs'>;
-/**
- * Describes a model (e.g., a Vensim `mdl` or Stella `stmx` file) and the input/output variables
- * that should be included in the model generated by SDEverywhere.
- *
- * Aside from the `inputs` and `outputs` properties (which allow for richer `InputSpec`
- * and `OutputSpec` forms here), the properties of this interface are shared with the
- * `ModelSpec` type from the compile package, which describes the `spec.json` file format
- * used by the lower-level `sde` commands.
- */
-interface ModelSpec extends CommonModelSpecProps {
-    /**
-     * The input variables for the model.  This can either be a simple array of
-     * input variable names, or an array of `InputSpec` instances.
-     *
-     * The builder requires only variable names for the purposes of generating
-     * a model, but some plugins may require full `InputSpec` instances.
-     */
-    inputs: VarName[] | InputSpec[];
-    /**
-     * The output variables for the model.  This can either be a simple array of
-     * output variable names, or an array of `OutputSpec` instances.
-     */
-    outputs: VarName[] | OutputSpec[];
-    /**
-     * Additional properties to include in the generated `spec.json` file.
-     *
-     * @deprecated All properties that are supported in a `spec.json` file are now declared
-     * directly on this interface, so it is no longer necessary to use this escape hatch.
-     * Any properties provided here will be merged into the resolved model spec (a property
-     * that is configured directly on this interface takes precedence over the same property
-     * provided here), but this property will be removed in a future release.
-     */
-    options?: ModelSpec$1;
-}
-/**
- * Describes a model (e.g., a Vensim `mdl` or Stella `stmx` file) and the input/output variables
- * that should be included in the model generated by SDEverywhere.  This is
- * largely the same as the `ModelSpec` interface, except this one has been
- * fully resolved (paths have been validated, input and output variables have
- * been checked, etc).  This is the spec object that will be passed to plugin
- * functions.
- */
-interface ResolvedModelSpec extends ResolvedModelSpecProps {
-    /**
-     * The input variable names for the model.  This will be defined regardless
-     * of whether `ModelSpec.inputs` was defined as an array of variable names
-     * or an array of `InputSpec` instances.  (The input variable names are
-     * derived from the `InputSpec` instances as needed.)
-     */
-    inputVarNames: VarName[];
-    /**
-     * The input variable specs for the model.
-     */
-    inputs: InputSpec[];
-    /**
-     * The output variable names for the model.  This will be defined regardless
-     * of whether `ModelSpec.outputs` was defined as an array of variable names
-     * or an array of `OutputSpec` instances.  (The output variable names are
-     * derived from the `OutputSpec` instances as needed.)
-     */
-    outputVarNames: VarName[];
-    /**
-     * The output variable specs for the model.
-     */
-    outputs: OutputSpec[];
-    /**
-     * The dat files that provide the data for exogenous data variables in the
-     * model.
-     */
-    datFiles: NonNullable<ModelSpec$1['datFiles']>;
-    /**
-     * Whether to bundle a model listing with the generated model.
-     *
-     * When this is true, a model listing will be bundled with the generated
-     * model to allow the `runtime` package to resolve variables that are
-     * referenced by name or identifier.  This listing will increase the size
-     * of the generated model, so it is recommended to set this to true only
-     * if it is needed.
-     */
-    bundleListing: boolean;
-    /**
-     * Whether to allow constants to be overridden at runtime using `setConstant`.
-     *
-     * If false, the generated model will contain a `setConstant` function that
-     * throws an error, meaning that constants cannot be overridden at runtime.
-     *
-     * If true, all constants in the generated model will be available to be
-     * overridden.
-     *
-     * If an array is provided, only those variable names in the array will
-     * be available to be overridden.
-     */
-    customConstants: boolean | VarName[];
-    /**
-     * Whether to allow lookups to be overridden at runtime using `setLookup`.
-     *
-     * If false, the generated model will contain a `setLookup` function that
-     * throws an error, meaning that lookups cannot be overridden at runtime.
-     *
-     * If true, all lookups in the generated model will be available to be
-     * overridden.
-     *
-     * If an array is provided, only those variable names in the array will
-     * be available to be overridden.
-     */
-    customLookups: boolean | VarName[];
-    /**
-     * Whether to allow for capturing the data for arbitrary variables at
-     * runtime (including variables that are not configured in the `outputs`
-     * array).
-     *
-     * If false, the generated model will contain a `storeOutput` function
-     * that throws an error, meaning that the data for arbitrary variables
-     * cannot be captured at runtime.
-     *
-     * If true, all variables in the generated model will be available to be
-     * captured at runtime.
-     *
-     * If an array is provided, only those variable names in the array will
-     * be available to be captured at runtime.
-     */
-    customOutputs: boolean | VarName[];
-}
-
-/**
- * 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 code format to generate.  If 'js', the model will be compiled to a JavaScript
-     * file.  If 'c', the model will be compiled to a C file (in which case an additional
-     * plugin will be needed to convert the C code to a WebAssembly module).
-     */
-    genFormat: 'js' | 'c';
-    /**
-     * The absolute path to the JSON file that will be written by the build process that
-     * lists all dimensions and variables in the model.
-     */
-    outListingFile?: 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>;
-    /**
-     * Format a (subscripted or non-subscripted) model variable name into a canonical
-     * identifier (with special characters converted to underscore, and subscript/dimension
-     * parts separated by commas).
-     *
-     * @param name The name of the variable in the source model, e.g., `Variable name[DimA, B2]`.
-     * @returns The canonical identifier for the given name, e.g., `_variable_name[_dima,_b2]`.
-     */
-    canonicalVarId(name: string): string;
-}
-
-/**
- * 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
- *       - preGenerateCode
- *       - postGenerateCode
- *   - 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: ResolvedModelSpec): 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 JS or C file from the mdl file.
-     *
-     * @param context The build context (for logging, etc).
-     * @param format The generated code format, either 'js' or 'c'.
-     */
-    preGenerateCode?(context: BuildContext, format: 'js' | 'c'): Promise<void>;
-    /**
-     * Called after SDE generates a JS or C file from the mdl file.
-     *
-     * @param context The build context (for logging, etc).
-     * @param format The generated code format, either 'js' or 'c'.
-     * @param content The resulting JS or C file content.
-     * @return The modified JS or C file content (if postprocessing was needed).
-     */
-    postGenerateCode?(context: BuildContext, format: 'js' | 'c', content: 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: ResolvedModelSpec): 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: ResolvedModelSpec): 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 code format to generate.  If 'js', the model will be compiled to a JavaScript
-     * file.  If 'c', the model will be compiled to a C file (in which case an additional
-     * plugin will be needed to convert the C code to a WebAssembly module).  If undefined,
-     * defaults to 'js'.
-     */
-    genFormat?: 'js' | 'c';
-    /**
-     * If defined, the build process will write a JSON file to the provided path that lists
-     * all dimensions and variables in the model.  This can be an absolute path, or if it
-     * is a relative path it will be resolved relative to the `rootDir` for the project.
-     */
-    outListingFile?: 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, type BuildMode, type BuildOptions, type BuildResult, type InputSpec, type LogLevel, type ModelSpec, type OutputSpec, type Plugin, type ResolvedConfig, type ResolvedModelSpec, type UserConfig, type VarName, build };