@sdeverywhere/compile 0.7.32 → 0.7.33

package/README.md

@@ -1,6 +1,6 @@
 # @sdeverywhere/compile
 
-This package contains the core [SDEverywhere](https://github.com/climateinteractive/SDEverywhere) compiler that takes a Vensim model as input and generates C code as output.
+This package contains the core [SDEverywhere](https://github.com/climateinteractive/SDEverywhere) compiler that takes a Vensim or Stella model as input and generates JavaScript or C code as output.
 
 ## Quick Start
 
@@ -32,7 +32,7 @@ More usage details will be included here at a later time when the interfaces sta
 ## Documentation
 
 The `compile` package is currently treated as an implementation detail of the `cli` package.
-As such, there is no public API documentation at this time, but we hope to expose a public API once the interfaces stabilize.
+As such, there is no generated API documentation at this time, but we hope to expose a public API once the interfaces stabilize.
 
 ## License
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@sdeverywhere/compile",
-  "version": "0.7.32",
+  "version": "0.7.33",
   "description": "The core Vensim to C compiler for the SDEverywhere tool suite.",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "@sdeverywhere/parse": "^0.1.5",
+    "@sdeverywhere/parse": "^0.1.6",
     "byline": "^5.0.0",
     "csv-parse": "^5.3.3",
     "fflate": "^0.8.3",
@@ -24,6 +25,8 @@
     "url": "https://github.com/climateinteractive/SDEverywhere/issues"
   },
   "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsup",
     "lint": "eslint . --max-warnings 0",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",
@@ -32,6 +35,6 @@
     "test": "vitest run",
     "test:watch": "vitest --hideSkippedTests",
     "test:ci": "vitest run",
-    "ci:build": "run-s lint prettier:check type-check test:ci"
+    "ci:build": "run-s clean lint prettier:check type-check build test:ci"
   }
 }

package/src/_shared/helpers.js

@@ -37,11 +37,18 @@ export function resetHelperState() {
   resetXlsxCache()
 }
 
+/**
+ * Format a model variable or subscript/dimension name into a valid C identifier.
+ *
+ * In the case where you have a full variable name that includes subscripts/dimensions
+ * (e.g., 'Variable name[DimA,B2]'), use `canonicalVensimName` to convert the base
+ * variable name and subscript/dimension parts to canonical form indepdendently.
+ *
+ * @param {import('./model-spec.js').VarName} name The variable name as used in the
+ * modeling tool.
+ * @return {import('./model-spec.js').VarId} The canonical variable identifier.
+ */
 export let canonicalName = name => {
-  // Format a model variable or subscript/dimension name into a valid C identifier.
-  // In the case where you have a full variable name that includes subscripts/dimensions
-  // (e.g., 'Variable name[DimA,B2]'), use `canonicalVensimName` to convert the
-  // base variable name and subscript/dimension parts to canonical form indepdendently.
   return canonicalId(name)
 }
 export let decanonicalize = name => {

package/src/_shared/model-spec.js

@@ -0,0 +1,174 @@
+// Copyright (c) 2026 Climate Interactive / New Venture Fund
+
+/**
+ * A variable name as used in the modeling tool, for example `Some Var[DimA]` as used in
+ * a Vensim model.
+ *
+ * @typedef {string} VarName
+ */
+
+/**
+ * A variable identifier in the canonical format used internally by SDEverywhere, for
+ * example `_some_var`.  These are derived from a `VarName` by lowercasing the name and
+ * replacing special characters with underscores.
+ *
+ * @typedef {string} VarId
+ */
+
+/**
+ * A dimension (subscript range) identifier in the canonical format used internally by
+ * SDEverywhere, for example `_dima`.
+ *
+ * @typedef {string} DimId
+ */
+
+/**
+ * Describes a `dat` file that provides data for exogenous data variables in the model.
+ *
+ * This can either be:
+ *   - a plain file name (relative to the model directory), for example `data.dat`, or
+ *   - an object with a single key/value pair, where the key is a prefix that is prepended
+ *     to each variable name read from the file, and the value is the file name, for
+ *     example `{ "prefix ": "data.dat" }`.
+ *
+ * @typedef {string | { [varNamePrefix: string]: string }} DatFileSpec
+ */
+
+/**
+ * Describes a model (e.g., a Vensim mdl file) and the input/output variables that should
+ * be included in the model generated by SDEverywhere.
+ *
+ * This is the type of the object that is parsed from a `spec.json` file (as passed to the
+ * `sde generate` command using the `--spec` argument) and that is accepted by the
+ * `parseAndGenerate` function.
+ *
+ * All properties are optional.  If neither `inputVarNames` nor `outputVarNames` is
+ * provided, the generated model will include all variables from the model and will not
+ * allow any inputs to be set at runtime.
+ *
+ * @typedef {Object} ModelSpec
+ *
+ * @property {VarName[]} [inputVarNames] The input variables for the model, using the
+ * variable names as they appear in the modeling tool.
+ *
+ * When this is provided, only the listed variables can be set at runtime, and any
+ * variables that are not needed to compute the configured `outputVarNames` will be pruned
+ * from the generated model.
+ *
+ * @property {VarName[]} [outputVarNames] The output variables for the model, using the
+ * variable names as they appear in the modeling tool.
+ *
+ * It is customary to include `Time` as the first output variable.
+ *
+ * When this is provided, only the listed variables (plus the variables needed to compute
+ * them) will be included in the generated model.
+ *
+ * @property {DatFileSpec[]} [datFiles] The `dat` files that provide the data for exogenous
+ * data variables in the model.
+ *
+ * Each entry is resolved relative to the model directory (i.e., the directory that is
+ * passed using the `--datadir` argument, which defaults to the directory that contains the
+ * model file).
+ *
+ * @property {{ [dataTag: string]: string }} [directData] The mapping of data tag to
+ * Excel workbook file name, used to resolve the data for `GET DIRECT DATA`,
+ * `GET DIRECT CONSTANTS`, and `GET DIRECT LOOKUPS` calls in the model.
+ *
+ * Each key is the tag that appears in the model equation (for example, `?data`), and each
+ * value is the name of an `xlsx` file that is resolved relative to the model directory.
+ *
+ * @property {{ [dimName: string]: string }} [dimensionFamilies] The mapping of dimension
+ * name to family name, used when SDEverywhere cannot infer the family for a dimension
+ * from the model alone.
+ *
+ * Both the keys and the values use the dimension names as they appear in the modeling tool
+ * (they are converted to canonical form when the spec file is read).
+ *
+ * @property {{ [varId: VarId]: DimId | DimId[] }} [specialSeparationDims] The mapping of
+ * variable identifier to the dimension(s) on which that variable should be separated
+ * into one variable instance per subscript.
+ *
+ * Separating a variable is sometimes necessary to break a dependency cycle that would
+ * otherwise prevent the model from being evaluated.  Each value can be either a single
+ * dimension identifier or an array of dimension identifiers.
+ *
+ * @property {(DimId | DimId[])[]} [separateAllVarsWithDims] The dimensions for which all
+ * variables should be separated into one variable instance per subscript.
+ *
+ * This is a convenience alternative to `specialSeparationDims` that avoids the need to
+ * list each affected variable.  Each entry can be either a single dimension identifier or
+ * an array of dimension identifiers; a variable is separated only if every dimension in
+ * the entry appears on the left-hand side of its equation.
+ *
+ * @property {boolean} [bundleListing] Whether to bundle a model listing with the generated
+ * model.
+ *
+ * If undefined, defaults to false.
+ *
+ * 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.
+ *
+ * @property {boolean | VarName[]} [customConstants] Whether to allow constants to be
+ * overridden at runtime using `setConstant`.
+ *
+ * If undefined or false, the generated model will implement `setConstant` as a no-op,
+ * 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.
+ *
+ * @property {boolean | VarName[]} [customLookups] Whether to allow lookups to be
+ * overridden at runtime using `setLookup`.
+ *
+ * If undefined or false, the generated model will implement `setLookup` as a no-op,
+ * 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.
+ *
+ * @property {boolean | VarName[]} [customOutputs] Whether to allow for capturing the data
+ * for arbitrary variables at runtime (including variables that are not configured in the
+ * `outputVarNames` array).
+ *
+ * If undefined or false, the generated model will implement `storeOutput` as a no-op,
+ * 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.
+ *
+ * @property {DatFileSpec[]} [externalDatfiles] The `dat` files that provide the data for
+ * exogenous data variables in the model.
+ *
+ * DEPRECATED: Use `datFiles` instead.  This property is still honored (but is ignored if
+ * `datFiles` is also provided) and will be removed in a future release.
+ *
+ * @property {string} [name] An optional descriptive name for the model.
+ *
+ * This is not currently used by SDEverywhere, but is allowed (and is included in many
+ * existing `spec.json` files) as a way to document what the model is.
+ *
+ * @property {VarId[]} [inputVars] The input variable identifiers for the model, in
+ * canonical form.
+ *
+ * This is derived from `inputVarNames` while the model is being read, and is not intended
+ * to be set in a `spec.json` file.
+ *
+ * @property {VarId[]} [outputVars] The output variable identifiers for the model, in
+ * canonical form.
+ *
+ * This is derived from `outputVarNames` while the model is being read, and is not intended
+ * to be set in a `spec.json` file.
+ */
+
+// Note that this module only declares types (as JSDoc typedefs), so this empty export
+// is needed to make it a module (otherwise the typedefs would be declared globally).
+export {}

package/src/_shared/normalize-model-spec.js

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Climate Interactive / New Venture Fund
+
+/**
+ * Normalize the given model spec so that the rest of the compile package only needs
+ * to work with the preferred property names.
+ *
+ * Some `spec.json` properties have been renamed over time.  For each renamed property,
+ * this copies the value from the deprecated property to the preferred one, unless the
+ * preferred property is already defined (in which case the preferred one wins).  The
+ * deprecated properties are left in place so that the spec object is unchanged from
+ * the caller's point of view.
+ *
+ * Note that the given spec object is modified in place (and returned for convenience),
+ * which is consistent with how the spec object is treated elsewhere in this package.
+ * This function is idempotent, so it is safe to call it more than once on the same spec.
+ *
+ * @template {import('./model-spec.js').ModelSpec | undefined} T
+ * @param {T} spec The model spec to normalize, or undefined.
+ * @return {T} The same spec object that was provided.
+ */
+export function normalizeModelSpec(spec) {
+  if (spec === undefined) {
+    return spec
+  }
+
+  // The `externalDatfiles` property was renamed to `datFiles`
+  if (spec.datFiles === undefined && spec.externalDatfiles !== undefined) {
+    spec.datFiles = spec.externalDatfiles
+  }
+
+  return spec
+}

package/src/_shared/read-dat.js

@@ -5,14 +5,21 @@ import * as R from 'ramda'
 import B from './bufx.js'
 import { canonicalVensimName } from './helpers.js'
 
+/**
+ * The datasets read from external `dat` files, keyed by variable identifier.  Each
+ * dataset is a map of time to value.
+ *
+ * @typedef {Map<import('./model-spec.js').VarId, Map<number, number>>} ExtData
+ */
+
 /**
  * Read a Vensim `dat` file with static data and return a Map.
  * Each dataset consists of a key (the variable name in the canonical
  * format used by SDE) and a map of time/value pairs.
  *
- * @param pathname The absolute path to the dat file.
- * @param prefix An optional prefix string prepended to var names.
- * @return A Map containing the datasets.
+ * @param {string} pathname The absolute path to the dat file.
+ * @param {string} [prefix] An optional prefix string prepended to var names.
+ * @return {Promise<ExtData>} A promise that resolves with a Map containing the datasets.
  */
 export async function readDat(pathname, prefix = '') {
   let log = new Map()

package/src/generate/gen-code.js

@@ -4,23 +4,21 @@ import { generateJS } from './gen-code-js.js'
 /**
  * Generate code from the given parsed model.
  *
- * @param {*} parsedModel The parsed model structure.
+ * @param {import('../parse-and-generate.js').ParsedModel} parsedModel The parsed model structure.
  * @param {Object} opts The options that control code generation.
- * @param {Object} opts.spec The parsed `spec.json` object.
- * @param {string[]} opts.operations The array of operations to perform.
- * - If it has 'generateC', the generated C code will be written to `buildDir`.
- * - If it has 'generateJS', the generated JS code will be written to `buildDir`.
- * - If it has 'printRefIdTest', reference identifiers will be printed to the console.
- * - If it has 'convertNames', no output will be generated, but the results of model
- *   analysis will be available.
- * @param {Map<string, any>} opts.extData The map of datasets from external `.dat` files.
- * @param {Map<string, any>} opts.directData The mapping of dataset name used in a
+ * @param {import('../_shared/model-spec.js').ModelSpec} opts.spec The parsed `spec.json` object.
+ * @param {import('../parse-and-generate.js').GenerateOperation[]} opts.operations The array
+ * of operations to perform.
+ * @param {import('../_shared/read-dat.js').ExtData} [opts.extData] The map of datasets from
+ * external `.dat` files.
+ * @param {Map<string, any>} [opts.directData] The mapping of dataset name used in a
  * `GET DIRECT DATA` call (e.g., `?data`) to the tabular data contained in the loaded
  * data file.
- * @param {string} opts.modelDirname The absolute path to the directory containing data
+ * @param {string} [opts.modelDirname] The absolute path to the directory containing data
  * (dat, xlsx, csv) files that are referenced by the model.  This path is used for
  * resolving data files for `GET DIRECT SUBSCRIPT` calls.
- * @returns A string containing the generated code.
+ * @param {string} [opts.varname] The variable name passed to the `sde causes` command.
+ * @returns {string} A string containing the generated code.
  */
 export function generateCode(parsedModel, opts) {
   // Note that the two `generate` functions perform the same steps (other than the

package/src/generate/gen-expr.js

@@ -483,7 +483,7 @@ function generateLevelInit(callExpr, ctx) {
   const fnId = callExpr.fnId
 
   // Get the index of the argument holding the initial value expression
-  let initialArgIndex = 0
+  let initialArgIndex
   switch (fnId) {
     case '_ACTIVE_INITIAL':
     case '_INTEG':

package/src/index.js

@@ -1,14 +1,21 @@
 // Copyright (c) 2022 Climate Interactive / New Venture Fund
 
+//
+// Note that the types below are declared (as JSDoc typedefs) alongside the code that
+// defines and uses them.  We use `export *` here rather than re-declaring each typedef
+// so that the generated declarations refer to a single definition of each type.
+//
+export * from './_shared/model-spec.js'
+
 // XXX: For now we re-export the preprocess function from the parse package
 // mainly for use by the cli package (so that we don't need to have the cli
 // package directly depend on the parse package)
 export { preprocessVensimModel } from '@sdeverywhere/parse'
 
 export { canonicalName } from './_shared/helpers.js'
-export { readDat } from './_shared/read-dat.js'
+export * from './_shared/read-dat.js'
 export { generateCode } from './generate/gen-code.js'
-export { parseAndGenerate, parseModel, printNames } from './parse-and-generate.js'
+export * from './parse-and-generate.js'
 
 import { resetHelperState } from './_shared/helpers.js'
 import { resetSubscriptsAndDimensions } from './_shared/subscript.js'
@@ -29,8 +36,12 @@ export function resetState() {
 /**
  * @hidden This is not yet part of the public API; it is exposed only for use
  * in the experimental playground app.
+ *
+ * @param {string} mdlContent The string containing the Vensim model text.
+ * @param {string} [modelDir] The absolute path to the directory containing data files.
+ * @return {import('./parse-and-generate.js').ParsedModel} A parsed tree representation of the model.
  */
-export function parseInlineVensimModel(mdlContent /*: string*/, modelDir /*?: string*/) /*: ParsedModel*/ {
+export function parseInlineVensimModel(mdlContent, modelDir) {
   // For tests that parse inline model text, in the case of the legacy parser, don't run
   // the preprocess step, and in the case of the new parser (which implicitly runs the
   // preprocess step), don't sort the definitions.  This makes it easier to do apples
@@ -41,8 +52,12 @@ export function parseInlineVensimModel(mdlContent /*: string*/, modelDir /*?: st
 /**
  * @hidden This is not yet part of the public API; it is exposed only for use
  * in the experimental playground app.
+ *
+ * @param {string} mdlContent The string containing the XMILE model text.
+ * @param {string} [modelDir] The absolute path to the directory containing data files.
+ * @return {import('./parse-and-generate.js').ParsedModel} A parsed tree representation of the model.
  */
-export function parseInlineXmileModel(mdlContent /*: string*/, modelDir /*?: string*/) /*: ParsedModel*/ {
+export function parseInlineXmileModel(mdlContent, modelDir) {
   return parseModel(mdlContent, 'xmile', modelDir)
 }
 
@@ -50,6 +65,6 @@ export function parseInlineXmileModel(mdlContent /*: string*/, modelDir /*?: str
  * @hidden This is not yet part of the public API; it is exposed only for use
  * in the experimental playground app.
  */
-export function getModelListing() /*: string*/ {
+export function getModelListing() {
   return Model.jsonList()
 }

package/src/parse-and-generate.js

@@ -6,6 +6,7 @@ import { parseVensimModel, parseXmileModel } from '@sdeverywhere/parse'
 
 import B from './_shared/bufx.js'
 import { readXlsx } from './_shared/helpers.js'
+import { normalizeModelSpec } from './_shared/normalize-model-spec.js'
 import { readDat } from './_shared/read-dat.js'
 import { printSubscripts } from './_shared/subscript.js'
 import { cName } from './_shared/var-names.js'
@@ -13,6 +14,34 @@ import Model from './model/model.js'
 import { getDirectSubscripts } from './model/read-subscripts.js'
 import { generateCode } from './generate/gen-code.js'
 
+/**
+ * The kind of model that is being parsed.
+ *
+ * @typedef {'vensim' | 'xmile'} ModelKind
+ */
+
+/**
+ * A parsed tree representation of a model, along with the kind of model that was parsed.
+ *
+ * @typedef {Object} ParsedModel
+ * @property {ModelKind} kind The kind of model that was parsed.
+ * @property {import('@sdeverywhere/parse').Model} root The root of the parsed model AST.
+ */
+
+/**
+ * An operation that can be performed by `parseAndGenerate`.
+ *
+ * - `generateC` writes the generated C code to the build directory.
+ * - `generateJS` writes the generated JS code to the build directory.
+ * - `printVarList` writes variables and subscripts to txt and json files under the build
+ *   directory.
+ * - `printRefIdTest` prints reference identifiers to the console.
+ * - `printRefGraph` prints the variable dependency graph to the console.
+ * - `convertNames` generates no output, but makes the results of model analysis available.
+ *
+ * @typedef {'generateC' | 'generateJS' | 'printVarList' | 'printRefIdTest' | 'printRefGraph' | 'convertNames'} GenerateOperation
+ */
+
 /**
  * Parse a Vensim or XMILE model and generate C code.
  *
@@ -27,27 +56,30 @@ import { generateCode } from './generate/gen-code.js'
  *   analysis will be available.
  *
  * @param {string} input The preprocessed Vensim or XMILE model text.
- * @param {string} modelKind The kind of model to parse, either 'vensim' or 'xmile'.
- * @param {*} spec The model spec (from the JSON file).
- * @param {string[]} operations The set of operations to perform; can include 'generateC', 'generateJS',
- * 'printVarList', 'printRefIdTest', 'convertNames'.  If the array is empty, the model will be
- * read but no operation will be performed.
+ * @param {ModelKind} modelKind The kind of model to parse.
+ * @param {import('./_shared/model-spec.js').ModelSpec} spec The model spec (from the JSON file).
+ * @param {GenerateOperation[]} operations The set of operations to perform.  If the array is
+ * empty, the model will be read but no operation will be performed.
  * @param {string} modelDirname The absolute path to the directory containing data (dat, xlsx, csv)
  * files that are referenced by the model.  These files will be resolved relative to this directory.
  * @param {string} modelName The model name (without the mdl extension).
  * @param {string} buildDir The output directory where the C or list files will be written.
  * @param {string} [varname] The variable name passed to the 'sde causes' command.
- * @return A string containing the generated C code.
+ * @return {Promise<string>} A promise that resolves with the generated C or JS code.
  */
 export async function parseAndGenerate(input, modelKind, spec, operations, modelDirname, modelName, buildDir, varname) {
+  // Resolve any deprecated property names in the spec so that we only need to
+  // consult the preferred names below
+  normalizeModelSpec(spec)
+
   // Read time series from external DAT files into a single object.
-  // externalDatfiles is an array of either filenames or objects
-  // giving a variable name prefix as the key and a filename as the value.
+  // `datFiles` is an array of either filenames or objects giving a variable
+  // name prefix as the key and a filename as the value.
   let extData = new Map()
-  if (spec.externalDatfiles) {
-    for (let datfile of spec.externalDatfiles) {
+  if (spec.datFiles) {
+    for (let datfile of spec.datFiles) {
       let prefix = ''
-      let filename = ''
+      let filename
       if (typeof datfile === 'object') {
         prefix = Object.keys(datfile)[0]
         filename = datfile[prefix]
@@ -110,8 +142,9 @@ export async function parseAndGenerate(input, modelKind, spec, operations, model
  *
  * This is used only to implement the `sde names` command.
  *
- * @param namesPathname The path to the file containing variables names.
- * @param operation Either 'to-c' or 'to-vensim'.
+ * @param {string} namesPathname The path to the file containing variables names.
+ * @param {'to-c' | 'to-vensim'} operation The conversion to perform.
+ * @return {void}
  */
 export function printNames(namesPathname, operation) {
   let lines = B.lines(B.read(namesPathname))
@@ -130,15 +163,13 @@ export function printNames(namesPathname, operation) {
 /**
  * Read and parse the given model text and return the parsed model structure.
  *
- * TODO: Fix return type
- *
  * @param {string} input The string containing the model text.
- * @param {string} modelKind The kind of model to parse, either 'vensim' or 'xmile'.
- * @param {string} modelDir The absolute path to the directory containing data (dat, xlsx, csv)
+ * @param {ModelKind} modelKind The kind of model to parse.
+ * @param {string} [modelDir] The absolute path to the directory containing data (dat, xlsx, csv)
  * files that are referenced by the model.  These files will be resolved relative to this directory.
  * @param {Object} [options] The options that control parsing.
- * @param {boolean} options.sort Whether to sort definitions alphabetically in the preprocess step.
- * @return {*} A parsed tree representation of the model.
+ * @param {boolean} [options.sort] Whether to sort definitions alphabetically in the preprocess step.
+ * @return {ParsedModel} A parsed tree representation of the model.
  */
 export function parseModel(input, modelKind, modelDir, options) {
   if (modelKind === 'vensim') {