feat: add build and plugin-{check,vite,wasm,worker} packages (#206)

Fixes #203

examples/hello-world/.gitignore

@@ -0,0 +1 @@
+sde-prep

examples/hello-world/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Climate Interactive / New Venture Fund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

examples/hello-world/README.md

@@ -0,0 +1,61 @@
+# hello-world
+
+This package contains a simple Vensim model and associated tests that can be
+used to exercise the `sde` command line tool.
+
+## Quick Start
+
+The quickest way to get started using the `hello-world` example is to copy
+it into a separate directory (outside of the `SDEverywhere` working copy).
+This will allow you to install the `@sdeverywhere/*` packages using your
+package manager of choice (npm, yarn, or pnpm).
+
+```sh
+# Change to the parent of your SDEverywhere working copy
+cd <parentdir>
+
+# Copy the example to a separate directory
+cp -rf SDEverywhere/examples/hello-world .
+
+# Change to the copied directory
+cd ./hello-world
+
+# Install dependencies (you can also use yarn or pnpm here, if preferred)
+npm install
+
+# Enter development mode for the sample model.  This will start a live
+# development environment that will build a WebAssembly version of the
+# sample model and run checks on it any time you make changes to the
+# Vensim model file (sample.mdl) or the checks file (sample.check.yaml).
+npm run dev
+```
+
+## For Developers
+
+If you are modifying SDEverywhere (the packages in this repository) and want
+to use this `hello-world` example to test your changes, you can use it directly
+without copying to a separate directory (as in the instructions above).
+
+Note that this example is already configured in `pnpm-workspace.yaml`, which
+means that its dependencies (e.g., `@sdeverywhere/cli`) are already linked to
+the ones from the `packages` directory in this repository; no separate linking
+step is necessary.
+
+The following assumes that you have already run `pnpm install` in the top-level
+directory, and have built the local packages with `pnpm build`.
+
+```sh
+# Enter local development mode for the sample model (this uses `sde dev`)
+pnpm dev
+
+# Or, build the model, run the checks (on the command line), and generate
+# the model-check report (this uses `sde bundle`)
+pnpm build
+
+# Open the generated report in a browser
+pnpm serve
+```
+
+## License
+
+SDEverywhere is distributed under the MIT license. See `LICENSE` for more details.

examples/hello-world/model/sample.check.yaml

@@ -0,0 +1,12 @@
+# yaml-language-server: $schema=../node_modules/@sdeverywhere/plugin-check/node_modules/@sdeverywhere/check-core/schema/check.schema.json
+
+- describe: Z
+  tests:
+    - it: should be in the range [1990,2110] for all input scenarios
+      scenarios:
+        - preset: matrix
+      datasets:
+        - name: Z
+      predicates:
+        - gte: 1990
+          lte: 2110

examples/hello-world/model/sample.mdl

@@ -0,0 +1,16 @@
+{UTF-8}
+
+X = TIME ~~|
+
+Y = 0
+  ~ [-10,10,0.1]
+  ~
+  |
+
+Z = X + Y
+  ~~|
+
+INITIAL TIME = 2000 ~~|
+FINAL TIME = 2100 ~~|
+TIME STEP = 1 ~~|
+SAVEPER = TIME STEP ~~|

examples/hello-world/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@sdeverywhere/hello-world",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "sde bundle",
+    "dev": "sde dev",
+    "serve": "sirv ./sde-prep/check-report"
+  },
+  "dependencies": {
+    "@sdeverywhere/cli": "^0.7.0",
+    "@sdeverywhere/plugin-check": "^0.1.0",
+    "@sdeverywhere/plugin-wasm": "^0.1.0",
+    "@sdeverywhere/plugin-worker": "^0.1.0",
+    "sirv-cli": "^2.0.2"
+  }
+}

examples/hello-world/sde.config.js

@@ -0,0 +1,30 @@
+import { checkPlugin } from '@sdeverywhere/plugin-check'
+import { wasmPlugin } from '@sdeverywhere/plugin-wasm'
+import { workerPlugin } from '@sdeverywhere/plugin-worker'
+
+export async function config() {
+  return {
+    modelFiles: ['model/sample.mdl'],
+
+    modelSpec: async () => {
+      return {
+        startTime: 2000,
+        endTime: 2100,
+        inputs: [{ varName: 'Y', defaultValue: 0, minValue: -10, maxValue: 10 }],
+        outputs: [{ varName: 'Z' }],
+        datFiles: []
+      }
+    },
+
+    plugins: [
+      // Generate a `wasm-model.js` file containing the Wasm model
+      wasmPlugin(),
+
+      // Generate a `worker.js` file that runs the Wasm model in a worker
+      workerPlugin(),
+
+      // Run model check
+      checkPlugin()
+    ]
+  }
+}

package.json

@@ -34,13 +34,14 @@
     "typedoc": "^0.22.17",
     "typedoc-plugin-markdown": "^3.12.1",
     "typescript": "^4.7.3",
-    "vite": "^2.9.6",
-    "vitest": "^0.14.1"
+    "vite": "^2.9.12",
+    "vitest": "^0.16.0"
   },
   "pnpm": {
     "peerDependencyRules": {
       "ignoreMissing": [
         "eslint",
+        "rollup",
         "svelte",
         "vite"
       ]

packages/build/.eslintignore

@@ -0,0 +1 @@
+dist

packages/build/.eslintrc.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['../../.eslintrc-ts-common.cjs']
+}

packages/build/.gitignore

@@ -0,0 +1,3 @@
+dist
+docs/entry.md
+sde-prep

packages/build/.prettierignore

@@ -0,0 +1,4 @@
+dist
+docs
+sde-prep
+CHANGELOG.md

packages/build/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Climate Interactive / New Venture Fund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/build/README.md

@@ -0,0 +1,11 @@
+# @sdeverywhere/build
+
+This package provides the core build and plugin API for SDEverywhere.
+
+## Documentation
+
+API documentation is available in the [`docs`](./docs/index.md) directory.
+
+## License
+
+SDEverywhere is distributed under the MIT license. See `LICENSE` for more details.

packages/build/docs/classes/BuildContext.md

@@ -0,0 +1,107 @@
+[@sdeverywhere/build](../index.md) / BuildContext
+
+# Class: BuildContext
+
+Provides access to common functionality that is needed during the build process.
+This is passed to most plugin functions.
+
+## Properties
+
+### config
+
+ `Readonly` **config**: [`ResolvedConfig`](../interfaces/ResolvedConfig.md)
+
+## Methods
+
+### log
+
+**log**(`level`, `msg`): `void`
+
+Log a message to the console and/or the in-browser overlay panel.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `level` | [`LogLevel`](../types/LogLevel.md) | The log level (verbose, info, error). |
+| `msg` | `string` | The message. |
+
+#### Returns
+
+`void`
+
+___
+
+### prepareStagedFile
+
+**prepareStagedFile**(`srcDir`, `srcFile`, `dstDir`, `dstFile`): `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.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `srcDir` | `string` | The directory underneath the configured `staged` directory where the file will be written (this must be a relative path). |
+| `srcFile` | `string` | The name of the file as written to the `staged` directory. |
+| `dstDir` | `string` | The absolute path to the destination directory where the staged file will be copied when the build has completed. |
+| `dstFile` | `string` | The name of the file as written to the destination directory. |
+
+#### Returns
+
+`string`
+
+The absolute path to the staged file.
+
+___
+
+### writeStagedFile
+
+**writeStagedFile**(`srcDir`, `dstDir`, `filename`, `content`): `void`
+
+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.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `srcDir` | `string` | The directory underneath the configured `staged` directory where the file will be written (this must be a relative path). |
+| `dstDir` | `string` | The absolute path to the destination directory where the staged file will be copied when the build has completed. |
+| `filename` | `string` | The name of the file. |
+| `content` | `string` | The file content. |
+
+#### Returns
+
+`void`
+
+___
+
+### spawnChild
+
+**spawnChild**(`cwd`, `command`, `args`, `opts?`): `Promise`<`ProcessOutput`\>
+
+Spawn a child process that runs the given command.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `cwd` | `string` | The directory in which the command will be executed. |
+| `command` | `string` | The command to execute. |
+| `args` | `string`[] | The arguments to pass to the command. |
+| `opts?` | `ProcessOptions` | Additional options to configure the process. |
+
+#### Returns
+
+`Promise`<`ProcessOutput`\>
+
+The output of the process.

packages/build/docs/functions/build.md

@@ -0,0 +1,21 @@
+[@sdeverywhere/build](../index.md) / build
+
+# Function: build
+
+**build**(`mode`, `options`): `Promise`<`Result`<[`BuildResult`](../interfaces/BuildResult.md), `Error`\>\>
+
+Initiate the build process, which can either be a single build if `mode` is
+'production', or a live development environment if `mode` is 'development'.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `mode` | [`BuildMode`](../types/BuildMode.md) | The build mode. |
+| `options` | [`BuildOptions`](../interfaces/BuildOptions.md) | The build options. |
+
+#### Returns
+
+`Promise`<`Result`<[`BuildResult`](../interfaces/BuildResult.md), `Error`\>\>
+
+An `ok` result if the build completed, otherwise an `err` result.