@sdeverywhere/compile 0.7.31 → 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.31",
+  "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.4",
+    "@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/_shared/xlsx.js

@@ -278,10 +278,22 @@ function getAttr(attrs, name) {
   return end < 0 ? undefined : attrs.slice(start, end)
 }
 
+/**
+ * Normalize line endings the way a conformant XML parser (and SheetJS) does:
+ * `\r\n` and lone `\r` both become `\n`. Applied after entity decoding so a
+ * CR encoded as `&#13;` is normalized too.
+ *
+ * @param {string} s The text to normalize.
+ * @returns The normalized string.
+ */
+function normalizeEol(s) {
+  return s.indexOf('\r') === -1 ? s : s.replace(/\r\n?/g, '\n')
+}
+
 /**
  * Decode the standard XML entities (`&lt;`, `&gt;`, `&amp;`, `&quot;`,
  * `&apos;`) along with numeric character references (`&#NN;` and `&#xNN;`)
- * in the given text. Returns the input unchanged when no entities are present.
+ * in the given text, and normalize line endings to `\n`.
  *
  * @param {string} s The raw text from an XML element body or attribute.
  * @returns The decoded string.
@@ -289,20 +301,22 @@ function getAttr(attrs, name) {
 function decodeXmlText(s) {
   // Fast path: most cell text contains no entities, so skip the regex chain
   if (s.indexOf('&') === -1) {
-    return s
+    return normalizeEol(s)
   }
 
   // Decode the named entities, then decimal and hex numeric refs, and finally
   // `&amp;` — leaving `&amp;` last avoids accidentally producing `&lt;` etc.
   // from a literal `&amp;lt;` in the source
-  return s
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)))
-    .replace(/&amp;/g, '&')
+  return normalizeEol(
+    s
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)))
+      .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)))
+      .replace(/&amp;/g, '&')
+  )
 }
 
 //
@@ -392,6 +406,19 @@ function parseWorkbookRels(xml) {
   return rels
 }
 
+/**
+ * Extract the text content of the `<v>` element in a cell body, tolerating
+ * attributes on the tag (e.g. `<v xml:space="preserve">`). Returns undefined
+ * when there is no `<v>` element (e.g. an uncalculated formula cell).
+ *
+ * @param {string} body The inner XML of a `<c>` element.
+ * @returns The raw text between `<v...>` and `</v>`, or undefined.
+ */
+function getVText(body) {
+  const m = /<v\b[^>]*>([\s\S]*?)<\/v>/.exec(body)
+  return m ? m[1] : undefined
+}
+
 /**
  * Scan a worksheet's XML and build a sparse cell map shaped like the SheetJS
  * worksheet object: `{ [cellRef]: { v }, '!ref': 'A1:Z99' }`. Skips empty
@@ -429,16 +456,7 @@ function parseSheetXml(xml, sharedStrings) {
     const t = getAttr(attrs, 't')
 
     let value
-    if (t === 's') {
-      // Shared string: <v>N</v> where N indexes sharedStrings
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
-        continue
-      }
-      const vEnd = body.indexOf('</v>', vStart + 3)
-      const idx = parseInt(body.slice(vStart + 3, vEnd), 10)
-      value = sharedStrings[idx]
-    } else if (t === 'inlineStr') {
+    if (t === 'inlineStr') {
       // Inline string: <is><t>...</t></is>
       const tStart = body.indexOf('<t')
       if (tStart < 0) {
@@ -447,38 +465,35 @@ function parseSheetXml(xml, sharedStrings) {
       const tOpenEnd = body.indexOf('>', tStart)
       const tEnd = body.indexOf('</t>', tOpenEnd)
       value = decodeXmlText(body.slice(tOpenEnd + 1, tEnd))
-    } else if (t === 'str') {
-      // Formula result as string: <v>...</v>
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
-        continue
-      }
-      const vEnd = body.indexOf('</v>', vStart + 3)
-      value = decodeXmlText(body.slice(vStart + 3, vEnd))
-    } else if (t === 'b') {
-      // Boolean: <v>0</v> or <v>1</v>
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
-        continue
-      }
-      value = body.charCodeAt(vStart + 3) === 49 // '1'
     } else if (t === 'e') {
       // Error cell, skip
       continue
     } else {
-      // Numeric (t === 'n' or absent). Skip any <f> formula tag and read the
-      // cached <v> value. If <v> is missing (e.g. an uncalculated formula),
-      // skip the cell so the caller's missing-cell handling kicks in.
-      const vStart = body.indexOf('<v>')
-      if (vStart < 0) {
+      // The remaining cell types carry their value in a <v> element, which
+      // may have attributes (e.g. <v xml:space="preserve">). If <v> is
+      // missing (e.g. an uncalculated formula), skip the cell so the
+      // caller's missing-cell handling kicks in.
+      const vText = getVText(body)
+      if (vText === undefined) {
         continue
       }
-      const vEnd = body.indexOf('</v>', vStart + 3)
-      const num = +body.slice(vStart + 3, vEnd)
-      if (Number.isNaN(num)) {
-        continue
+      if (t === 's') {
+        // Shared string: <v>N</v> where N indexes sharedStrings
+        value = sharedStrings[parseInt(vText, 10)]
+      } else if (t === 'str') {
+        // Formula result as string: <v>...</v>
+        value = decodeXmlText(vText)
+      } else if (t === 'b') {
+        // Boolean: <v>0</v> or <v>1</v>
+        value = vText.charCodeAt(0) === 49 // '1'
+      } else {
+        // Numeric (t === 'n' or absent)
+        const num = +vText
+        if (Number.isNaN(num)) {
+          continue
+        }
+        value = num
       }
-      value = num
     }
 
     // Store the cell under its A1 ref, matching the SheetJS sheet shape

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-equation.js

@@ -128,6 +128,9 @@ export function generateEquation(variable, mode, extData, directData, modelDir,
     }
   }
 
+  // Keep a buffer of code that will be included before all subscript loops
+  const preLoopLines = []
+
   // Keep a buffer of code that will be included before the innermost loop
   const preInnerLoopLines = []
 
@@ -145,6 +148,7 @@ export function generateEquation(variable, mode, extData, directData, modelDir,
     cLhs,
     loopIndexVars,
     arrayIndexVars,
+    emitPreLoop: s => preLoopLines.push(s),
     emitPreInnerLoop: s => preInnerLoopLines.push(s),
     emitPreFormula: s => preFormulaLines.push(s),
     emitPostFormula: s => postFormulaLines.push(s),
@@ -161,7 +165,7 @@ export function generateEquation(variable, mode, extData, directData, modelDir,
   }
 
   // Combine all lines of comments and code into a single array
-  return [comment, ...openLoops, ...preFormulaLines, formula, ...postFormulaLines, ...closeLoops]
+  return [comment, ...preLoopLines, ...openLoops, ...preFormulaLines, formula, ...postFormulaLines, ...closeLoops]
 }
 
 /**