Align interoperability and role docs with the implementation by haphantran · Pull Request #48 · micss-lab/SpatialDSLStudio

haphantran · 2026-10-12T02:21:37Z

Summary

Depends on #45 (its construct table lists the spatial rules annotation); this branch contains that commit. Review the commits after "Add declarative spatial rules and yaw-aware spatial geometry". Documentation only.

README: said .aird export was not implemented. The code (exportAird, project ZIP export) and both Sirius reference docs say otherwise; the README now matches them.
Ecore/XMI construct table: docs/reference/sirius-file-compatibility.md gains a construct-by-construct table of what import and export support, report, or ignore (packages and sub-packages, interfaces, inheritance, datatypes, enums, bounds, defaults, opposites, cross-resource references, operations, generics, feature flags, annotations including spatialdsl/spatialRules, xmi:id handling, many-valued attribute values, presentation data). It was derived from ecore.service.ts, the model XMI import/export services, and the Sirius project export, and checked against them. The metamodel guide links to it.
New accounts and projects: a newly registered account has the platform role VIEWER, which the roles guide described as unable to create anything. I verified on a local stack that a VIEWER can create a project, becomes its OWNER with all 26 project capabilities, and can create metamodels (with spatial rules), models, and checkpoints there; only artifacts outside a project are refused (403). The roles guide and the project lifecycle guide now say so. No code change is needed for the "reviewers can do very little" complaint.

Spatial geometry now honours rotationZ. A shared oriented-box module (shared/spatial-geometry.ts, mirrored in frontend/src/services/spatial) builds each placed element's rotated footprint extruded over its vertical interval. The JS/OCL spatial helpers keep their names and signatures but use separating-axis overlap tests and exact convex-polygon clearance, so rotated elements no longer get axis-aligned answers. Metamodels gain spatialRules: noOverlap, minClearance, maxDistance, within, and adjacentTo over placed instances of a source and a target metaclass (subclasses included), in plan or volume mode. A pure evaluator (shared/spatial-rules.ts plus the frontend mirror) runs in browser validation, which marks both elements of an offending pair in 2D and 3D, and in the backend validation engine used by the headless pipeline. A parity test keeps the two copies identical and checks that they report the same issues. Rules are persisted in a new metamodels.spatialRules column, validated on create and update, carried through checkpoints and metamodel evolution (a rule on a removed class blocks the evolution), removed with a deleted class, and exported to Ecore as the EPackage annotation spatialdsl/spatialRules. The metamodel editor gains a Spatial Rules section with an add/edit dialog. The Smart Warehouse example declares a FixedEquipment supertype and four rules that its bundled model satisfies, and its unbounded controller references now use '*'.

The README still said .aird export was not implemented, while the code and the Sirius reference docs support exporting views to the .aird subset and a complete single-model Sirius project ZIP. The README now matches them. The Sirius file compatibility reference gains a construct-by-construct table of what Ecore and XMI import and export support, report, or ignore (packages, classes, inheritance, datatypes, enums, bounds, opposites, operations, generics, feature flags, annotations including spatial rules, xmi:id handling, cross-resource references, many-valued attribute values, and presentation data), derived from the import and export services. The metamodel guide links to it.

A newly registered account has the platform role VIEWER, which the roles guide described as unable to create or edit anything. Under project workspaces any signed-in user can create a project, becomes its OWNER, and holds every project capability there. Both guides now say so.

Copilot

🟡 Changes recommended

Several update, evolution, and Ecore-import paths can persist or accept invalid spatial rules.

3 open findings

What changed in this PR

Adds spatial-rule infrastructure from dependency #45 and aligns interoperability, role, lifecycle, and API documentation with implemented behavior.

Changes:

Adds yaw-aware spatial geometry and declarative rule evaluation across frontend and backend.
Persists, edits, validates, checkpoints, and exports spatial rules.
Updates Sirius compatibility and project-role documentation.

File	Description
`shared/types/index.ts`	Adds shared spatial-rule types.
`shared/spatial-rules.ts`	Implements shared rule validation and evaluation.
`shared/spatial-geometry.ts`	Implements oriented spatial geometry.
`README.md`	Updates spatial and Sirius capabilities.
`frontend/src/services/spatial/spatial-rules.ts`	Adds frontend rule evaluator mirror.
`frontend/src/services/spatial/spatial-geometry.ts`	Adds frontend geometry mirror.
`frontend/src/services/spatial/index.ts`	Exports spatial modules.
`frontend/src/services/model/model-validation.service.ts`	Integrates spatial-rule validation.
`frontend/src/services/metamodel/metamodel.service.ts`	Validates imported spatial rules.
`frontend/src/services/metamodel/metamodel-api-sync.service.ts`	Synchronizes spatial rules.
`frontend/src/services/metamodel/metaclass-crud.service.ts`	Removes rules for deleted classes.
`frontend/src/services/metamodel/ecore.service.ts`	Imports and exports rule annotations.
`frontend/src/services/diagram/view-validation.service.ts`	Marks all elements involved in issues.
`frontend/src/services/constraint/spatial.helpers.ts`	Makes constraint geometry rotation-aware.
`frontend/src/models/types.ts`	Adds frontend spatial-rule types.
`frontend/src/examples/data/smart-warehouse-metamodel.json`	Adds example hierarchy and rules.
`frontend/src/components/metamodel/SpatialRulesEditor.tsx`	Adds spatial-rule editor UI.
`frontend/src/components/metamodel/components/sidebar/MetamodelSidebar.tsx`	Exposes the editor in Constraints.
`frontend/src/__tests__/services/view-validation.test.ts`	Tests related-element markers.
`frontend/src/__tests__/services/spatial-rules.test.ts`	Tests rule semantics and configuration.
`frontend/src/__tests__/services/spatial-helpers.test.ts`	Tests rotation-aware helpers.
`frontend/src/__tests__/services/ecore-xmi-interop.test.ts`	Tests rule annotation interoperability.
`frontend/src/__tests__/components/SpatialRulesEditor.test.tsx`	Tests rule editor behavior.
`docs/user-guide/spatial-rules.md`	Documents spatial rules comprehensively.
`docs/user-guide/roles-and-sharing.md`	Clarifies new-account project rights.
`docs/user-guide/project-lifecycle.md`	Clarifies platform and project roles.
`docs/user-guide/metamodels.md`	Links spatial and compatibility guidance.
`docs/reference/sirius-file-compatibility.md`	Adds Ecore/XMI compatibility matrix.
`docs/reference/data-model.md`	Documents persisted rules.
`docs/reference/api.md`	Documents spatial-rule API fields.
`docs/README.md`	Adds spatial rules to documentation navigation.
`backend/src/services/sirius-interop.service.ts`	Exports rules in Sirius project Ecore.
`backend/src/services/pipeline/model-validation.engine.ts`	Evaluates rules headlessly.
`backend/src/services/pipeline/headless-pipeline.service.ts`	Maps persisted rules into pipelines.
`backend/src/services/metamodel.service.ts`	Persists and validates spatial rules.
`backend/src/services/lifecycle/project-checkpoint.service.ts`	Checkpoints and restores rules.
`backend/src/services/lifecycle/metamodel-evolution.service.ts`	Includes rules in evolution handling.
`backend/src/__tests__/services/spatial-rules-parity.test.ts`	Verifies frontend/backend parity.
`backend/src/__tests__/services/sirius-interop.service.test.ts`	Tests Sirius rule export.
`backend/src/__tests__/services/sharing.service.test.ts`	Updates metamodel fixtures.
`backend/src/__tests__/services/project-checkpoint.service.test.ts`	Tests rule checkpoint compatibility.
`backend/src/__tests__/services/pipeline-engines.test.ts`	Tests pipeline rule evaluation.
`backend/src/__tests__/services/metamodel.service.test.ts`	Tests persistence and validation.
`backend/src/__tests__/services/metamodel-evolution.service.test.ts`	Tests evolution impacts and hashes.
`backend/prisma/schema.prisma`	Adds the spatial-rules column.
`backend/prisma/migrations/20261011000000_add_metamodel_spatial_rules/migration.sql`	Migrates existing databases.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+    asArray<SpatialRule>(next.spatialRules).forEach(rule => {
+      [rule?.sourceClassId, rule?.targetClassId].forEach(classId => {
+        if (typeof classId !== 'string' || nextClassNames.has(classId)) return;
+        const removedName = currentClassNames.get(classId);
+        blockers.push(removedName
+          ? `Spatial rule ${rule.name} references removed class ${removedName}; update or delete the rule before applying this evolution`
+          : `Spatial rule ${rule?.name || rule?.id} references unknown class ${classId}`);
+      });


    if (data.classes !== undefined) {
      this.assertValidClassesVerticalPlacement(data.classes);
    }
+    if (data.spatialRules !== undefined) {
+      const classes = data.classes !== undefined
+        ? data.classes
+        : (await prisma.metamodel.findUnique({ where: { id }, select: { classes: true } }))?.classes;
+      this.assertValidSpatialRules(data.spatialRules, classes);
+    }


+          rules.push({
+            id: uuidv4(),
+            name,
+            kind: parsed.kind,
+            sourceClassId,
+            targetClassId,
+            ...(parsed.distanceMm !== undefined && { distanceMm: parsed.distanceMm }),
+            ...(parsed.mode !== undefined && { mode: parsed.mode }),
+            severity: parsed.severity || 'error',
+            ...(parsed.message !== undefined && { message: parsed.message }),
+            ...(parsed.enabled !== undefined && { enabled: parsed.enabled }),
+          });


The warehouse example said a violation could be provoked in the 2D view, but 2D moves only change the 3D pose that rules check when an element's 2D and 3D plan positions coincide, which is not the case for the bundled examples. Say so, and point to the 3D view and its Position & Rotation fields instead.

The backend Dockerfile compiles src/, tests included, with only backend/ and shared/ in the image. The spatial rules parity test imported the frontend mirror and the warehouse fixtures statically, so the image build failed. Load those files at run time instead, as the Sirius fixture test does.

Metamodel evolution now runs the full rule validation (kind, distance, mode, severity, duplicate IDs) before a preview can be applied, a classes-only update checks the stored rules against the new classes, and Ecore import skips annotation rules that are not valid rules with a warning instead of importing them.

…docs-consistency

haphantran added 3 commits October 11, 2026 21:36

Copilot AI balanced review requested due to automatic review settings October 12, 2026 02:21

Copilot started reviewing on behalf of haphantran October 12, 2026 02:22

View session

Copilot AI reviewed Oct 12, 2026

View reviewed changes

haphantran mentioned this pull request Oct 12, 2026

Add declarative spatial rules and yaw-aware spatial geometry #45

Merged

haphantran added 4 commits October 12, 2026 07:16

Merge remote-tracking branch 'origin/feature/spatial-rules' into fix/…

3e89ae3

…docs-consistency

Merge remote-tracking branch 'origin/main' into fix/docs-consistency

ea1b45b

haphantran merged commit 10f090e into main Oct 13, 2026
3 checks passed

Navigation Menu

Repository navigation

Align interoperability and role docs with the implementation - #48

Align interoperability and role docs with the implementation#48
haphantran merged 8 commits into
mainfrom
fix/docs-consistency

haphantran commented Oct 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

haphantran commented Oct 12, 2026

Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants