@mat3ra/esse 2026.7.14-0 → 2026.8.13-0

package/.cursor/rules/resolve-generated-merge-conflicts.mdc

@@ -0,0 +1,36 @@
+---
+description: Resolve ESSE merge conflicts by merging source schemas and regenerating derived artifacts
+globs: "{schema,example,manifest,dist/js,src/py}/**/*"
+alwaysApply: false
+---
+
+# ESSE generated merge conflicts
+
+Treat `schema/**`, `example/**`, and `manifest/**` as sources of truth. These outputs are generated:
+
+- `dist/js/**`
+- `src/py/mat3ra/esse/data/**`
+- `src/py/mat3ra/esse/models/**` (`dist/py` points here)
+
+When merging:
+
+1. Merge source schemas, examples, and manifests first, preserving intentional changes from both branches.
+2. Do not hand-merge generated Python enum suffixes such as `Name631`, `Units284`, or `Value137`; their numbering is unstable and regeneration determines it.
+3. Resolve generated files temporarily if Git requires it, then regenerate all derived artifacts from the merged sources:
+
+```bash
+npm run transpile-and-build-assets
+pre-commit run generate-python-modules --all-files
+```
+
+The Python hook only runs when a staged path contains `schema`, so stage the resolved source schema changes before invoking it. Its canonical command and pinned generator options live in `.pre-commit-config.yaml`.
+
+After generation, stage the generated outputs and verify:
+
+```bash
+git diff --name-only --diff-filter=U
+rg -n '^(<<<<<<<|=======|>>>>>>>)' .
+git diff --check
+```
+
+Do not blindly choose `ours` or `theirs` for generated files when source schemas differ. A side may contain real additions (for example, a new property) while the other contains unrelated schema fixes; the regenerated result must include both.

package/dist/js/esse/JSONSchemasInterface.d.ts

@@ -9,6 +9,10 @@ export default class JSONSchemasInterface {
     static setSchemas(schema: JSONSchema[]): void;
     static addSchema(schema: JSONSchema): void;
     static getSchemaById(schemaId: string): import("json-schema").JSONSchema7 | undefined;
+    /**
+     * Like {@link getSchemaById}, but throws if the schema is not registered.
+     */
+    static getRequiredSchemaById(schemaId: string): JSONSchema;
     /**
      * @example <caption>Search by $id regex</caption>
      * JSONSchemasInterface.matchSchema({

package/dist/js/esse/JSONSchemasInterface.js

@@ -13,6 +13,16 @@ class JSONSchemasInterface {
     static getSchemaById(schemaId) {
         return this.schemasCache.get(schemaId);
     }
+    /**
+     * Like {@link getSchemaById}, but throws if the schema is not registered.
+     */
+    static getRequiredSchemaById(schemaId) {
+        const schema = this.getSchemaById(schemaId);
+        if (!schema) {
+            throw new Error(`ESSE schema not found: ${schemaId}`);
+        }
+        return schema;
+    }
     /**
      * @example <caption>Search by $id regex</caption>
      * JSONSchemasInterface.matchSchema({

package/dist/js/example/properties_directory/scalar/defect_formation_energy.json

@@ -0,0 +1,5 @@
+{
+    "name": "defect_formation_energy",
+    "units": "eV",
+    "value": 3.5
+}