Refactor: engine <-> client interface implementation

.github/workflows/ci.yml

@@ -33,6 +33,7 @@ jobs:
  tree-sitter-xpath: ${{ steps.changes.outputs.tree-sitter-xpath }}
  xforms-engine: ${{ steps.changes.outputs.xforms-engine }}
  xpath: ${{ steps.changes.outputs.xpath }}
+ scenario: ${{ steps.changes.outputs.scenario }}
  ui-solid: ${{ steps.changes.outputs.ui-solid }}
  ui-vue: ${{ steps.changes.outputs.ui-vue }}
 
@@ -57,6 +58,9 @@ jobs:
  xforms-engine:
  - 'packages/xforms-engine/**'
 
+ scenario:
+ - 'packages/scenario/**'
+
  xpath:
  - 'packages/xpath/**'
 
@@ -295,6 +299,71 @@ jobs:
  - if: ${{ matrix.target == 'Web' }}
  run: 'yarn workspace @odk-web-forms/xforms-engine test-browser:${{ matrix.browser }}'
 
+ scenario:
+ name: 'scenario'
+ needs: ['install-and-build', 'changes']
+ if: needs.changes.outputs.root == 'true' || needs.changes.outputs.scenario == 'true'
+ runs-on: 'ubuntu-latest'
+
+ strategy:
+ matrix:
+ target: ['Node']
+ node-version: ['18.19.1', '20.11.1']
+ include:
+ - target: 'Web'
+ node-version: '20.11.1'
+ browser: chromium
+ - target: 'Web'
+ node-version: '20.11.1'
+ browser: firefox
+ - target: 'Web'
+ node-version: '20.11.1'
+ browser: webkit
+
+ steps:
+ - uses: 'actions/checkout@v3'
+
+ - uses: 'volta-cli/action@v4'
+ with:
+ node-version: '${{ matrix.node-version }}'
+ yarn-version: '1.22.19'
+
+ - uses: 'actions/cache@v3'
+ id: cache-install
+ with:
+ path: |
+ node_modules
+ **/node_modules
+ key: install-${{ matrix.node-version }}-${{ hashFiles('yarn.lock', 'examples/*/yarn.lock', 'packages/*/yarn.lock') }}
+ fail-on-cache-miss: true
+
+ - uses: 'actions/cache@v3'
+ id: cache-build
+ with:
+ path: |
+ examples/*/dist
+ packages/*/dist
+ packages/tree-sitter-xpath/grammar.js
+ packages/tree-sitter-xpath/src/grammar.json
+ packages/tree-sitter-xpath/src/parser.c
+ packages/tree-sitter-xpath/src/tree_sitter/parser.h
+ packages/tree-sitter-xpath/tree-sitter-xpath.wasm
+ packages/tree-sitter-xpath/types
+ key: build-${{ matrix.node-version }}-${{ github.sha }}
+ fail-on-cache-miss: true
+
+ - if: ${{ matrix.target == 'Node' }}
+ run: 'yarn workspace @odk-web-forms/scenario test:types'
+
+ - if: ${{ matrix.target == 'Node' }}
+ run: 'yarn workspace @odk-web-forms/scenario test-node:jsdom'
+
+ - if: ${{ matrix.target == 'Web' }}
+ run: 'yarn playwright install ${{ matrix.browser }} --with-deps'
+
+ - if: ${{ matrix.target == 'Web' }}
+ run: 'yarn workspace @odk-web-forms/scenario test-browser:${{ matrix.browser }}'
+
  xpath:
  name: '@odk-web-forms/xpath'
  needs: ['install-and-build', 'changes']

.gitignore

@@ -21,6 +21,9 @@ dist/
 examples/**/dist
 packages/**/dist
 
+# Generated documentation
+packages/*/api-docs
+
 ## Specific to tree-sitter and/or @odk-web-forms/tree-sitter-xpath
 packages/tree-sitter-xpath/bindings/
 packages/tree-sitter-xpath/build/

eslint.config.js

@@ -21,6 +21,7 @@
 import { FlatCompat } from '@eslint/eslintrc';
 import eslint from '@eslint/js';
 import eslintConfigPrettier from 'eslint-config-prettier';
+import jsdoc from 'eslint-plugin-jsdoc';
 import noOnlyTestsPlugin from 'eslint-plugin-no-only-tests';
 import vuePlugin from 'eslint-plugin-vue';
 import vueBase from 'eslint-plugin-vue/lib/configs/base.js';
@@ -104,6 +105,19 @@ export default tseslint.config(
  ],
  },
 
+ {
+ plugins: { jsdoc },
+ rules: {
+ 'jsdoc/no-undefined-types': [
+ 'error',
+ {
+ markVariablesAsUsed: true,
+ disableReporting: true,
+ },
+ ],
+ },
+ },
+
  {
  extends: [
  eslint.configs.recommended,

package.json

@@ -46,6 +46,7 @@
  "@vue/tsconfig": "^0.5.1",
  "eslint": "^8.57.0",
  "eslint-config-prettier": "^9.1.0",
+ "eslint-plugin-jsdoc": "^48.2.1",
  "eslint-plugin-no-only-tests": "^3.1.0",
  "eslint-plugin-prettier": "^5.1.3",
  "eslint-plugin-vue": "^9.22.0",

packages/common/src/lib/array/insert.ts

@@ -0,0 +1,23 @@
+export const insertAtIndex = <T>(
+ currentValues: readonly T[],
+ insertionIndex: number,
+ newValue: T
+): readonly T[] => {
+ const { length } = currentValues;
+
+ if (insertionIndex > length) {
+ throw new Error(
+ 'Failed to insert value: specified insertion index is greater than the current array length, which would introduce empty array slots'
+ );
+ }
+
+ if (insertionIndex === length) {
+ return currentValues.concat(newValue);
+ }
+
+ return [
+ ...currentValues.slice(0, insertionIndex),
+ newValue,
+ ...currentValues.slice(insertionIndex),
+ ];
+};

packages/common/src/lib/identity.ts

@@ -0,0 +1 @@
+export const identity = <T>(value: T): T => value;

packages/common/src/lib/objects/structure.ts

@@ -0,0 +1,23 @@
+export type PropertyKeys<T> = ReadonlyArray<string & keyof T>;
+
+export const getPropertyKeys = <T extends object>(object: T): PropertyKeys<T> => {
+ return Object.keys(object) as Array<string & keyof T>;
+};
+
+export type PropertyDescriptorEntry<T> = readonly [string & keyof T, PropertyDescriptor];
+
+export type PropertyDescriptors<T> = Array<PropertyDescriptorEntry<T>>;
+
+export const getPropertyDescriptors = <T extends object>(object: T): PropertyDescriptors<T> => {
+ const keys = getPropertyKeys(object);
+
+ return keys.map((key) => {
+ const descriptor = Object.getOwnPropertyDescriptor(object, key);
+
+ if (descriptor == null) {
+ throw new Error(`Could not get property descriptor for key ${key}`);
+ }
+
+ return [key, descriptor];
+ });
+};

packages/common/src/lib/web-compat/blob.ts

@@ -0,0 +1,60 @@
+/**
+ * Gets the text content of a {@link Blob} (or {@link File}).
+ *
+ * Why does this exist when there's a standard way to get the text of a `Blob`
+ * (or `File`)? Because
+ * {@link https:/jsdom/jsdom/issues/2555 | jsdom} considers it out
+ * of spec... to implement the spec.
+ */
+let getBlobText: (blob: Blob) => Promise<string>;
+
+const isBlobBrokenByDesign = async (): Promise<boolean> => {
+ try {
+ const blob = new Blob(['a']);
+ const text = await blob.text();
+
+ return text !== 'a';
+ } catch {
+ return true;
+ }
+};
+
+if (await isBlobBrokenByDesign()) {
+ getBlobText = (blob) => {
+ return new Promise((resolve, reject) => {
+ let isDone = false;
+
+ const reader = new FileReader();
+
+ const complete = () => {
+ if (isDone) {
+ throw new Error('Cannot complete FileReader read twice!');
+ }
+
+ isDone = true;
+
+ const { error, result } = reader;
+
+ if (typeof result === 'string') {
+ resolve(result);
+ } else if (error != null) {
+ reject(error);
+ } else {
+ throw new Error('Unknown FileReader state');
+ }
+
+ reader.removeEventListener('error', complete);
+ reader.removeEventListener('load', complete);
+ };
+
+ reader.addEventListener('error', complete);
+ reader.addEventListener('load', complete);
+
+ reader.readAsText(blob);
+ });
+ };
+} else {
+ getBlobText = (blob) => blob.text();
+}
+
+export { getBlobText };

packages/common/test/lib/array/insert.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { insertAtIndex } from '../../../src/lib/array/insert.ts';
+
+describe('Array insertion', () => {
+ describe('at a specified index', () => {
+ it.each([
+ { currentValues: [0, 1, 2], value: 3, insertionIndex: 3, expected: [0, 1, 2, 3] },
+ { currentValues: [0, 1, 2], value: 3, insertionIndex: 1, expected: [0, 3, 1, 2] },
+ ])(
+ 'produces an array $expected with the inserted value $value at the specified index $insertionIndex',
+ ({ currentValues, value, insertionIndex, expected }) => {
+ const result = insertAtIndex(currentValues, insertionIndex, value);
+
+ expect(result).toEqual(expected);
+ }
+ );
+
+ it("fails to insert a value at an index past the array's current length", () => {
+ const fn = () => {
+ insertAtIndex([0, 1, 2], 4, 3);
+ };
+
+ expect(fn).toThrow();
+ });
+ });
+});

packages/common/src/lib/collections/UpsertableMap.test.ts → packages/common/test/lib/collections/UpsertableMap.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { UpsertableMap } from './UpsertableMap.ts';
+import { UpsertableMap } from '../../../src/lib/collections/UpsertableMap.ts';
 
 describe('UpsertableMap', () => {
  class Key {

packages/common/src/lib/collections/UpsertableWeakMap.test.ts → packages/common/test/lib/collections/UpsertableWeakMap.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { UpsertableWeakMap } from './UpsertableWeakMap.ts';
+import { UpsertableWeakMap } from '../../../src/lib/collections/UpsertableWeakMap.ts';
 
 describe('UpsertableWeakMap', () => {
  class Key {

packages/common/src/lib/dom/compatibility.test.ts → packages/common/test/lib/dom/compatibility.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it } from 'vitest';
-import { ScopedElementLookup } from './compatibility.ts';
+import { ScopedElementLookup } from '../../../src/lib/dom/compatibility.ts';
 
 describe('DOM compatibility library functions', () => {
  describe('querying direct children of an element', () => {

packages/common/test/lib/web-compat/blob.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { getBlobText } from '../../../src/lib/web-compat/blob.ts';
+
+describe('Blob compatibility', () => {
+ it('gets the text of a blob', async () => {
+ const blob = new Blob(['a']);
+ const text = await getBlobText(blob);
+
+ expect(text).toBe('a');
+ });
+});

packages/common/tsconfig.json

@@ -1,6 +1,6 @@
 {
  "extends": "../../tsconfig.json",
- "include": ["src/**/*.ts", "test/**/*.ts", "types/**/*.ts", "vite-env.d.ts"],
+ "include": ["src/**/*.ts", "test", "types/**/*.ts", "vite-env.d.ts"],
  "compilerOptions": {
  "lib": ["ES2022", "DOM", "DOM.Iterable"],
  "skipLibCheck": true

packages/common/types/Primitive.ts

@@ -0,0 +1,13 @@
+/**
+ * Any primitive runtime value.
+ */
+// prettier-ignore
+export type Primitive =
+ // eslint-disable-next-line @typescript-eslint/sort-type-constituents
+ | boolean
+ | bigint
+ | number
+ | string
+ | symbol
+ | null
+ | undefined;

packages/common/types/helpers.d.ts

@@ -1,5 +1,36 @@
+/**
+ * Potentially useful for simplifying some types, as exposed by TypeScript
+ * diagnostics and in-editor documentation.
+ */
 export type Identity<T> = T;
 
+/**
+ * Simplifies complex types like intersections and interface extensions, as
+ * exposed by TypeScript diagnostics and in-editor documentation.
+ *
+ * Warnings:
+ *
+ * - Simplifications are not applied recursively
+ * -
+ */
 export type Merge<T> = Identity<{
  [K in keyof T]: T[K];
 }>;
+
+/**
+ * May be used to simplify union types, as exposed by TypeScript diagnostics and
+ * in-editor documentation.
+ */
+export type ExpandUnion<T> = Exclude<T, never>;
+
+/**
+ * Maps an object type to a shallowly-mutable type otherwise of the same shape
+ * and type.
+ *
+ * {@link T} should be a {@link Record}-like object. This type is **NOT
+ * SUITABLE** for producing mutable versions of built-in collections like
+ * `readonly T[]` -> `T[]` or `ReadonlyMap<T>` -> `Map<T>`.
+ */
+type ShallowMutable<T extends object> = {
+ -readonly [K in keyof T]: T[K];
+};

packages/scenario/README.md

@@ -0,0 +1,25 @@
+# @odk-web-forms/scenario (private package)
+
+This package implements a client of [`@odk-web-forms/xforms-engine`](../xforms-engine/), and a suite of tests against that engine. These tests are either:
+
+- Directly ported from [JavaRosa](https:/getodk/javarosa)
+- Derived from those ported tests, where some environment-specific adaptation is necessary/appropriate
+- Expand on JavaRosa's existing coverage using the same general testing approach
+
+The client's name is taken from JavaRosa's [`Scenario`](https:/getodk/javarosa/blob/master/src/test/java/org/javarosa/core/test/Scenario.java). Its interface is designed to match that of JavaRosa's as well, to maximize compatibility as tests are ported updated.
+
+## Status
+
+Currently, very few of JavaRosa's tests have been ported. But our goal in setting up this package is to rapidly port all of the remaining tests that are appropriate for the ODK web-forms engine.
+
+## Usage and development
+
+As with [`@odk-web-forms/common`](../common/), this internal package is not intended to be built. Unlike that package, this one is also not intended to be used as a dependency in other packages. Usage should consist entirely of running the test suite. These tests will be run automatically in CI along with tests throughout [web-forms monorepo](../../).
+
+To run in development, run this command at the monorepo root:
+
+```sh
+yarn workspace @odk-web-forms/scenario test
+```
+
+Individual test environments, and their corresponding watch modes, also have separate commands which can be found in [`package.json`](./package.json).

packages/scenario/do-not-import.js

@@ -0,0 +1 @@
+throw new Error('Do not import from @odk-web-forms/scenario!');