Interlinearization model

README.md

@@ -95,19 +95,20 @@ The general file structure for an extension is as follows:
 - `src/` contains the source code for the extension
   - `src/main.ts` is the main entry file for the extension (registers commands and wires interlinear XML)
   - `src/types/interlinearizer.d.ts` is this extension's types file that defines how other extensions can use this extension through the `papi`. It is copied into the build folder
-  - `src/parsers/interlinearXmlParser.ts` parses interlinear XML into structured data (uses fast-xml-parser). The PT9 XML schema and parsed output are documented in `src/parsers/pt9-xml.md`
+  - `src/types/` also holds shared enums and type modules (e.g. `interlinearizer-enums.ts`). Use the path alias `types/interlinearizer-enums` in imports instead of relative paths (see `tsconfig.json` paths).
+  - `src/parsers/` contains all parsers and converters used when importing external data models sorted by source (e.g. Paratext 9 XML Files). Use the path alias `parsers/...` in imports instead of relative paths (see `tsconfig.json` paths).
   - `*.web-view.tsx` files will be treated as React WebViews
   - `*.web-view.scss` files provide styles for WebViews
   - `*.web-view.html` files are a conventional way to provide HTML WebViews (no special functionality)
   - `src/__tests__/` contains unit tests (Jest) for the extension, including parser tests (valid and invalid XML, edge cases) and web-view tests
-- `__mocks__/` contains Jest mocks for the PAPI, file modules, and test fixtures used by tests in `src/__tests__/`. The `@papi/backend` and `@papi/frontend` mocks are used mutually exclusively (backend for main.ts tests, frontend for WebView tests); each mock file ends with `export {}` so TypeScript treats it as a module.
+- `__mocks__/` (project root) contains Jest mocks for the PAPI, file modules, and test fixtures used by tests in `src/__tests__/`. Manual mocks for the Paratext 9 parser, converter, and lexicon used by `interlinearizer.web-view.test.tsx` live in `src/parsers/paratext-9/__mocks__/` (adjacent to the modules) so that `jest.mock('parsers/paratext-9/...')` picks them up.
 - `assets/` contains asset files the extension and its WebViews can retrieve using the `papi-extension:` protocol, as well as textual descriptions in various languages. It is copied into the build folder
   - `assets/displayData.json` contains (optionally) a path to the extension's icon file as well as text for the extension's display name, short summary, and path to the full description file
   - `assets/descriptions/` contains textual descriptions of the extension in various languages
     - `assets/descriptions/description-<locale>.md` contains a brief description of the extension in the language specified by `<locale>`
 - `contributions/` contains JSON files the platform uses to extend data structures for things like menus and settings. The JSON files are referenced from the manifest
 - `public/` contains other static files that are copied into the build folder
-- `test-data/` contains sample interlinear XML (e.g. `Interlinear_en_MAT.xml`) for development and tests
+- `test-data/` contains sample interlinear XML (e.g. `Interlinear_en_MAT.xml`) for development and tests. In tests, resolve paths via `getTestDataPath('Interlinear_en_MAT.xml')` from `src/__tests__/test-helpers`.
 - `.github/` contains files to facilitate integration with GitHub
   - `.github/workflows` contains [GitHub Actions](https://github.com/features/actions) workflows for automating various processes in this repo (e.g. **Test** and **Lint** on push/PR to main, release-prep, hotfix-\*; **Publish** and **Bump Versions** manual dispatch; **CodeQL** for security)
   - `.github/assets/release-body.md` combined with a generated changelog becomes the body of [releases published using GitHub Actions](#publishing)
@@ -118,6 +119,10 @@ The general file structure for an extension is as follows:
 
 ## To install
 
+### Requirements
+
+- **Node.js >= 18** is required. The test suite uses the Web Crypto API (`globalThis.crypto.subtle`) for hashing in `paratext9Converter` tests (e.g. the `sha256HexWebCrypto` path in `src/__tests__/parsers/paratext-9/paratext9Converter.test.ts` when `convertParatext9ToInterlinearization` is called without the `hashSha256Hex` option). Node 18+ provides this API; older versions will cause those tests to fail. The same requirement is enforced in `package.json` via `engines.node` and is used by CI.
+
 ### Install dependencies:
 
 1. Follow the instructions to install [`paranext-core`](https://github.com/paranext/paranext-core#developer-install). We recommend you clone `paranext-core` in the same parent directory in which you cloned this repository so you do not have to [reconfigure paths](#configure-paths-to-paranext-core-repo) to `paranext-core`.

__mocks__/lexiconXmlContent.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Jest mock for webpack ?raw XML import. Exports the contents of test-data/Lexicon.xml
+ * so interlinearizer.web-view.tsx can parse it in unit tests without webpack.
+ */
+import fs from 'fs';
+import path from 'path';
+
+const xmlPath = path.join(__dirname, '..', 'test-data', 'Lexicon.xml');
+module.exports = fs.readFileSync(xmlPath, 'utf-8');

cspell.json

@@ -8,6 +8,7 @@
     "node_modules",
     "package.json",
     "package-lock.json",
+    "test-data",
     "vscode-extension"
   ],
   "dictionaryDefinitions": [],
@@ -16,18 +17,25 @@
     "appdata",
     "asyncs",
     "autodocs",
+    "BCVWP",
+    "behaviour",
     "dockbox",
+    "Eflomal",
     "electronmon",
     "endregion",
     "finalizer",
     "Fragmenter",
     "guids",
     "hopkinson",
     "iframes",
+    "interlineardata",
     "interlinearization",
+    "interlinearizations",
     "interlinearizer",
+    "jsmith",
     "localstorage",
     "maximizable",
+    "Morphosyntactic",
     "networkable",
     "Newtonsoft",
     "nodebuffer",
@@ -40,22 +48,26 @@
     "pdps",
     "plusplus",
     "proxied",
+    "punc",
     "reinitializing",
     "reserialized",
     "sillsdev",
     "steenwyk",
     "stringifiable",
     "Stylesheet",
     "typedefs",
+    "unanalyzed",
     "unregistering",
     "unregisters",
+    "unreviewed",
     "unsub",
     "unsubs",
     "unsubscriber",
     "unsubscribers",
     "usfm",
     "verseref",
-    "versification"
+    "versification",
+    "wordform"
   ],
   "ignoreWords": [],
   "import": []

jest.config.ts

@@ -27,7 +27,7 @@ const config: Config = {
     'src/parsers/**/*.ts',
     'src/main.ts',
     'src/**/*.web-view.tsx',
-    '!src/parsers/**/*.d.ts',
+    '!src/parsers/**/*-types.ts',
     '!src/**/__tests__/**',
     '!src/**/*.test.{ts,tsx}',
     '!src/**/*.spec.{ts,tsx}',
@@ -70,11 +70,12 @@ const config: Config = {
    */
   moduleNameMapper: {
     /**
-     * Resolve src-rooted path aliases so tests can use e.g. "@main" or "parsers/..." instead of
-     * relative paths. Must match tsconfig.json "paths" and webpack resolve.alias.
+     * Resolve src-rooted path aliases so tests can use e.g. "@main", "parsers/...", or "types/..."
+     * instead of relative paths. Must match tsconfig.json "paths" and webpack resolve.alias.
      */
     '^@main$': '<rootDir>/src/main',
     '^parsers/(.*)$': '<rootDir>/src/parsers/$1',
+    '^types/(.*)$': '<rootDir>/src/types/$1',
     '\\.(sa|sc|c)ss$': '<rootDir>/__mocks__/styleMock.ts',
     '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':
       '<rootDir>/__mocks__/fileMock.ts',
@@ -94,6 +95,8 @@ const config: Config = {
     '^(.+)\\.(scss|sass|css)\\?inline$': '<rootDir>/__mocks__/styleInlineMock.ts',
     /** Resolve webpack ?raw import for test XML in web-view. */
     '^(.+)/Interlinear_en_MAT\\.xml\\?raw$': '<rootDir>/__mocks__/interlinearXmlContent.ts',
+    /** Resolve webpack ?raw import for Lexicon XML in web-view. */
+    '^(.+)/Lexicon\\.xml\\?raw$': '<rootDir>/__mocks__/lexiconXmlContent.ts',
   },
 
   /** Exclude dist from module resolution to avoid Haste naming collision with root package.json. */

package.json

@@ -6,6 +6,9 @@
   "types": "src/types/interlinearizer.d.ts",
   "author": "SIL Global",
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build:web-view": "webpack --config ./webpack/webpack.config.web-view.ts",
     "build:main": "webpack --config ./webpack/webpack.config.main.ts",