feat: add experimental build-tag support

bindings/java/java/src/main/java/com/sensmetry/sysand/Sysand.java

@@ -194,8 +194,12 @@ public static void setProjectIndex(java.nio.file.Path projectPath, java.util.Lin
      *
      * @param outputPath  The path to the output file.
      * @param projectPath The path to the project.
+     * @param compression The compression method.
+     * @param buildTag    Optional pre-release build tag appended to the version
+     *                    (e.g. {@code "42"} turns {@code 1.2.3} into {@code 1.2.3-dev.42}).
+     *                    Pass {@code null} to leave the version unchanged.
      */
-    private static native void buildProject(String outputPath, String projectPath, String compression)
+    private static native void buildProject(String outputPath, String projectPath, String compression, String buildTag)
             throws com.sensmetry.sysand.exceptions.SysandException;
 
     /**
@@ -204,31 +208,73 @@ private static native void buildProject(String outputPath, String projectPath, S
      *
      * @param outputPath  The path to the output file.
      * @param projectPath The path to the project.
+     * @param compression The compression method.
      */
     public static void buildProject(java.nio.file.Path outputPath, java.nio.file.Path projectPath, com.sensmetry.sysand.model.CompressionMethod compression)
             throws com.sensmetry.sysand.exceptions.SysandException {
-        buildProject(outputPath.toString(), projectPath.toString(), compression.toString());
+        buildProject(outputPath.toString(), projectPath.toString(), compression.toString(), null);
     }
 
     /**
-     * Build Model Project Interchange file (.kpar) from the workspace at the given
+     * Build Model Project Interchange file (.kpar) from the project at the given
      * path.
      *
+     * <p><b>Experimental:</b> This API is subject to change in future releases.
+     *
      * @param outputPath  The path to the output file.
+     * @param projectPath The path to the project.
+     * @param compression The compression method.
+     * @param buildTag    Pre-release build tag appended to the version
+     *                    (e.g. {@code "42"} turns {@code 1.2.3} into {@code 1.2.3-dev.42}).
+     */
+    public static void buildProject(java.nio.file.Path outputPath, java.nio.file.Path projectPath, com.sensmetry.sysand.model.CompressionMethod compression, String buildTag)
+            throws com.sensmetry.sysand.exceptions.SysandException {
+        buildProject(outputPath.toString(), projectPath.toString(), compression.toString(), buildTag);
+    }
+
+    /**
+     * Build Model Project Interchange file (.kpar) from the workspace at the given
+     * path.
+     *
+     * @param outputPath    The path to the output directory.
      * @param workspacePath The path to the workspace.
+     * @param compression   The compression method.
+     * @param buildTag      Optional pre-release build tag appended to each project's version
+     *                      (e.g. {@code "42"} turns {@code 1.2.3} into {@code 1.2.3-dev.42}).
+     *                      {@code versionConstraint} fields that exactly pin a sibling workspace
+     *                      project's version are updated to include the tag as well.
+     *                      Pass {@code null} to leave versions unchanged.
      */
-    private static native void buildWorkspace(String outputPath, String workspacePath, String compression)
+    private static native void buildWorkspace(String outputPath, String workspacePath, String compression, String buildTag)
             throws com.sensmetry.sysand.exceptions.SysandException;
 
     /**
      * Build Model Project Interchange file (.kpar) from the workspace at the given
      * path.
      *
-     * @param outputPath  The path to the output file.
+     * @param outputPath    The path to the output directory.
      * @param workspacePath The path to the workspace.
+     * @param compression   The compression method.
      */
     public static void buildWorkspace(java.nio.file.Path outputPath, java.nio.file.Path workspacePath, com.sensmetry.sysand.model.CompressionMethod compression)
             throws com.sensmetry.sysand.exceptions.SysandException {
-        buildWorkspace(outputPath.toString(), workspacePath.toString(), compression.toString());
+        buildWorkspace(outputPath.toString(), workspacePath.toString(), compression.toString(), null);
+    }
+
+    /**
+     * Build Model Project Interchange file (.kpar) from the workspace at the given
+     * path.
+     *
+     * <p><b>Experimental:</b> This API is subject to change in future releases.
+     *
+     * @param outputPath    The path to the output directory.
+     * @param workspacePath The path to the workspace.
+     * @param compression   The compression method.
+     * @param buildTag      Pre-release build tag appended to each project's version
+     *                      (e.g. {@code "42"} turns {@code 1.2.3} into {@code 1.2.3-dev.42}).
+     */
+    public static void buildWorkspace(java.nio.file.Path outputPath, java.nio.file.Path workspacePath, com.sensmetry.sysand.model.CompressionMethod compression, String buildTag)
+            throws com.sensmetry.sysand.exceptions.SysandException {
+        buildWorkspace(outputPath.toString(), workspacePath.toString(), compression.toString(), buildTag);
     }
 }

bindings/java/plugin/pom.xml

@@ -113,6 +113,7 @@ SPDX-FileCopyrightText: © 2025 Sysand contributors <opensource@sensmetry.com>
           <showVersion>true</showVersion>
           <streamLogs>true</streamLogs>
           <filterPom>true</filterPom>
+          <postBuildHookScript>verify</postBuildHookScript>
         </configuration>
         <executions>
           <execution>

bindings/java/plugin/src/it/workspace-build-tag-env-set/.workspace.json

@@ -0,0 +1,8 @@
+{
+  "projects": [
+    {
+      "path": "project1",
+      "iris": ["urn:kpar:project1"]
+    }
+  ]
+}

bindings/java/plugin/src/it/workspace-build-tag-env-set/invoker.properties

@@ -0,0 +1,3 @@
+invoker.goals = -B -V package
+invoker.buildResult = success
+invoker.environmentVariables.BUILD_TAG = 99

bindings/java/plugin/src/it/workspace-build-tag-env-set/pom.xml

@@ -0,0 +1,66 @@
+<!--
+SPDX-License-Identifier: MIT OR Apache-2.0
+SPDX-FileCopyrightText: © 2026 Sysand contributors <opensource@sensmetry.com>
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.sensmetry.sysand.it</groupId>
+  <artifactId>workspace-build-tag-env-set-project</artifactId>
+  <version>1.0.0</version>
+  <packaging>jar</packaging>
+  <name>workspace-build-tag-env-set-project</name>
+  <properties>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <maven.compiler.target>1.8</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <sysand.buildTag></sysand.buildTag>
+  </properties>
+  <profiles>
+    <!-- maven.compiler.release is only available in Java 9+, but it is required
+    to disallow usage of Java >8 APIs when building with Java >8 -->
+    <profile>
+      <id>java-8-api</id>
+      <activation>
+        <jdk>[9,)</jdk>
+      </activation>
+      <properties>
+        <maven.compiler.release>8</maven.compiler.release>
+      </properties>
+    </profile>
+    <profile>
+      <id>build-tag-from-env</id>
+      <activation>
+        <property>
+          <name>env.BUILD_TAG</name>
+        </property>
+      </activation>
+      <properties>
+        <sysand.buildTag>${env.BUILD_TAG}</sysand.buildTag>
+      </properties>
+    </profile>
+  </profiles>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.sensmetry</groupId>
+        <artifactId>sysand-maven-plugin</artifactId>
+        <version>@project.version@</version>
+        <executions>
+          <execution>
+            <goals>
+              <goal>build-kpar</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <workspacePath>${project.basedir}</workspacePath>
+          <outputPath>${project.basedir}/output</outputPath>
+          <buildTag>${sysand.buildTag}</buildTag>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

bindings/java/plugin/src/it/workspace-metamodel/project1/.project.json → bindings/java/plugin/src/it/workspace-build-tag-env-set/project1/.project.json

@@ -1,5 +1,5 @@
 {
   "name": "project1",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "usage": []
 }

bindings/java/plugin/src/it/workspace-build-tag-env-set/verify.groovy

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+// SPDX-FileCopyrightText: © 2026 Sysand contributors <opensource@sensmetry.com>
+
+import java.util.zip.ZipFile
+import groovy.json.JsonSlurper
+
+def kparFile = new File(basedir, "output/project1-1.0.0-dev.99.kpar")
+assert kparFile.exists() : "Expected tagged kpar not found: ${kparFile}"
+
+def zip = new ZipFile(kparFile)
+try {
+    def infoEntry = zip.getEntry(".project.json")
+    assert infoEntry != null : ".project.json entry not found in kpar"
+
+    def infoJson = new JsonSlurper().parse(zip.getInputStream(infoEntry))
+    assert infoJson.version == "1.0.0-dev.99" :
+        "Expected version '1.0.0-dev.99' in kpar but got '${infoJson.version}'"
+} finally {
+    zip.close()
+}
+
+// Source .project.json must not have been modified by the build
+def sourceInfo = new JsonSlurper().parse(new File(basedir, "project1/.project.json"))
+assert sourceInfo.version == "1.0.0" :
+    "Source .project.json was unexpectedly modified: version is '${sourceInfo.version}'"

bindings/java/plugin/src/it/workspace-build-tag-env-unset/.workspace.json

@@ -0,0 +1,8 @@
+{
+  "projects": [
+    {
+      "path": "project1",
+      "iris": ["urn:kpar:project1"]
+    }
+  ]
+}

bindings/java/plugin/src/it/workspace-build-tag-env-unset/pom.xml

@@ -0,0 +1,66 @@
+<!--
+SPDX-License-Identifier: MIT OR Apache-2.0
+SPDX-FileCopyrightText: © 2026 Sysand contributors <opensource@sensmetry.com>
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.sensmetry.sysand.it</groupId>
+  <artifactId>workspace-build-tag-env-unset-project</artifactId>
+  <version>1.0.0</version>
+  <packaging>jar</packaging>
+  <name>workspace-build-tag-env-unset-project</name>
+  <properties>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <maven.compiler.target>1.8</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <sysand.buildTag></sysand.buildTag>
+  </properties>
+  <profiles>
+    <!-- maven.compiler.release is only available in Java 9+, but it is required
+    to disallow usage of Java >8 APIs when building with Java >8 -->
+    <profile>
+      <id>java-8-api</id>
+      <activation>
+        <jdk>[9,)</jdk>
+      </activation>
+      <properties>
+        <maven.compiler.release>8</maven.compiler.release>
+      </properties>
+    </profile>
+    <profile>
+      <id>build-tag-from-env</id>
+      <activation>
+        <property>
+          <name>env.BUILD_TAG</name>
+        </property>
+      </activation>
+      <properties>
+        <sysand.buildTag>${env.BUILD_TAG}</sysand.buildTag>
+      </properties>
+    </profile>
+  </profiles>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.sensmetry</groupId>
+        <artifactId>sysand-maven-plugin</artifactId>
+        <version>@project.version@</version>
+        <executions>
+          <execution>
+            <goals>
+              <goal>build-kpar</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <workspacePath>${project.basedir}</workspacePath>
+          <outputPath>${project.basedir}/output</outputPath>
+          <buildTag>${sysand.buildTag}</buildTag>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

bindings/java/plugin/src/it/workspace-build-tag-env-unset/project1/.meta.json

@@ -0,0 +1,12 @@
+{
+  "index": {
+    "A": "a.sysml"
+  },
+  "created": "2025-10-31T17:01:00.414506000Z",
+  "checksum": {
+    "a.sysml": {
+      "value": "",
+      "algorithm": "NONE"
+    }
+  }
+}

bindings/java/plugin/src/it/workspace-build-tag-env-unset/project1/.project.json

@@ -0,0 +1,5 @@
+{
+  "name": "project1",
+  "version": "1.0.0",
+  "usage": []
+}

bindings/java/plugin/src/it/workspace-build-tag-env-unset/project1/a.sysml

@@ -0,0 +1 @@
+package A;

bindings/java/plugin/src/it/workspace-build-tag-env-unset/verify.groovy

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+// SPDX-FileCopyrightText: © 2026 Sysand contributors <opensource@sensmetry.com>
+
+import groovy.json.JsonSlurper
+
+// Without BUILD_TAG env var, only the untagged kpar should be produced
+def taggedKpar = new File(basedir, "output/project1-1.0.0-dev.99.kpar")
+assert !taggedKpar.exists() : "Unexpected tagged kpar found: ${taggedKpar}"
+
+def kparFile = new File(basedir, "output/project1-1.0.0.kpar")
+assert kparFile.exists() : "Expected untagged kpar not found: ${kparFile}"

bindings/java/plugin/src/it/workspace-build-tag/.workspace.json

@@ -0,0 +1,8 @@
+{
+  "projects": [
+    {
+      "path": "project1",
+      "iris": ["urn:kpar:project1"]
+    }
+  ]
+}

bindings/java/plugin/src/it/workspace-build-tag/invoker.properties

@@ -0,0 +1,2 @@
+invoker.goals = -B -V package
+invoker.buildResult = success

bindings/java/plugin/src/it/workspace-build-tag/pom.xml

@@ -0,0 +1,54 @@
+<!--
+SPDX-License-Identifier: MIT OR Apache-2.0
+SPDX-FileCopyrightText: © 2026 Sysand contributors <opensource@sensmetry.com>
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.sensmetry.sysand.it</groupId>
+  <artifactId>workspace-build-tag-project</artifactId>
+  <version>1.0.0</version>
+  <packaging>jar</packaging>
+  <name>workspace-build-tag-project</name>
+  <properties>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <maven.compiler.target>1.8</maven.compiler.target>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+  <profiles>
+    <!-- maven.compiler.release is only available in Java 9+, but it is required
+    to disallow usage of Java >8 APIs when building with Java >8 -->
+    <profile>
+      <id>java-8-api</id>
+      <activation>
+        <jdk>[9,)</jdk>
+      </activation>
+      <properties>
+        <maven.compiler.release>8</maven.compiler.release>
+      </properties>
+    </profile>
+  </profiles>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.sensmetry</groupId>
+        <artifactId>sysand-maven-plugin</artifactId>
+        <version>@project.version@</version>
+        <executions>
+          <execution>
+            <goals>
+              <goal>build-kpar</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <workspacePath>${project.basedir}</workspacePath>
+          <outputPath>${project.basedir}/output</outputPath>
+          <buildTag>42</buildTag>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>