Add bidirectional index/codec compatibility harness for Lucene, #270

.github/workflows/Lucene-Net-Index-Compatibility.yml

@@ -0,0 +1,174 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Verifies two-way index/codec compatibility between Lucene.NET and Apache
+# Lucene 4.8.1 (Java), per issue #270. Each runtime writes an index that the
+# other reads back and validates with CheckIndex. See src/java/index-compat.
+#
+# This workflow is hand-maintained (NOT generated by Generate-TestWorkflows.ps1),
+# because it needs a JDK and runs a Maven <-> dotnet orchestration that does not
+# fit the generated per-project test template.
+
+name: 'Index Compatibility'
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+    # The compatibility harness itself
+    - 'src/java/index-compat/**/*'
+    - 'src/Lucene.Net.Tests/Support/Index/CompatDocs.cs'
+    - 'src/Lucene.Net.Tests/Support/Index/TestJavaCompatibility.cs'
+    # Production code whose on-disk format the harness validates
+    - 'src/Lucene.Net/Codecs/**/*'
+    - 'src/Lucene.Net/Index/**/*'
+    - 'src/Lucene.Net/Store/**/*'
+    # Build/runtime inputs that can affect the produced index
+    - 'src/Lucene.Net.Analysis.Common/**/*'
+    - 'src/Lucene.Net.TestFramework/**/*'
+    - 'TestTargetFrameworks.*'
+    - 'Directory.Build.*'
+    - 'src/Directory.Build.*'
+    - '.github/workflows/Lucene-Net-Index-Compatibility.yml'
+    - '!**/*.md'
+
+env:
+  DOTNET_CLI_TELEMETRY_OPTOUT: 1
+  DOTNET_NOLOGO: 1
+  NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages
+  BUILD_FOR_ALL_TEST_TARGET_FRAMEWORKS: 'true'
+  # The _J-S shard owns Support/Index/*.cs, so it contains TestJavaCompatibility.
+  project_path: './src/Lucene.Net.Tests._J-S/Lucene.Net.Tests._J-S.csproj'
+  compat_dir: './src/java/index-compat'
+  # The codec under test. Both sides name their index folders after it, and both
+  # default to their own stock default codec when it is not supplied, so this is
+  # the single place to change when the default codec of the port moves.
+  codec_name: 'Lucene46'
+
+jobs:
+
+  Compatibility:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+        framework: [net10.0, net8.0, net48, net472]
+        platform: [x64]
+        configuration: [Release]
+        exclude:
+          - os: ubuntu-latest
+            framework: net48
+          - os: ubuntu-latest
+            framework: net472
+
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Setup Java (JDK)
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          distribution: 'zulu'
+          java-version: '21'
+
+      - name: Setup .NET 8 SDK
+        uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
+        with:
+          dotnet-version: '8.0.x'
+        if: ${{ startswith(matrix.framework, 'net8.') }}
+
+      - name: Setup .NET 10 SDK
+        uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Cache NuGet Packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          # Use a 'compat-' prefixed key so this cache lives in its own namespace.
+          # This job only restores the _J-S project, a smaller package closure than
+          # the generated workflows' full-solution restore. Sharing their 'nuget-...'
+          # key would let whichever job runs first populate a partial cache the other
+          # then gets a (wrong-sized) hit on. A separate key avoids that interaction.
+          key: compat-nuget-${{ runner.os }}-${{ env.BUILD_FOR_ALL_TEST_TARGET_FRAMEWORKS }}-${{ hashFiles('**/*.*proj', '**/*.props', '**/*.targets', '**/*.sln', '*.sln', 'global.json') }}
+          path: ${{ env.NUGET_PACKAGES }}
+
+      - name: Cache Maven Packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          key: maven-${{ runner.os }}-${{ hashFiles('src/java/index-compat/pom.xml') }}
+          restore-keys: |
+            maven-${{ runner.os }}-
+          path: ~/.m2/repository
+
+      - name: Restore .NET
+        run: dotnet restore "${{ env.project_path }}" /p:TestFrameworks=${{ env.BUILD_FOR_ALL_TEST_TARGET_FRAMEWORKS }}
+
+      - name: Build .NET test shard
+        run: dotnet build "${{ env.project_path }}" --configuration "${{ matrix.configuration }}" --framework "${{ matrix.framework }}" --no-restore -p:TestFrameworks=${{ env.BUILD_FOR_ALL_TEST_TARGET_FRAMEWORKS }}
+        shell: bash
+
+      # ---------------------------------------------------------------------
+      # Direction 1: .NET writes, Java reads
+      # ---------------------------------------------------------------------
+      # dotnet test exits 0 when a --filter matches nothing or a test is skipped,
+      # which would hide a misconfiguration. Capture the output and fail unless
+      # exactly the expected test ran and passed.
+      - name: '.NET writes index'
+        # The test reads its target via the env var "lucenenet.compat.write.dir".
+        # Names with dots are not valid bash identifiers, so we apply it with `env`
+        # rather than a plain assignment. Using `shell: bash` keeps this identical
+        # on Windows (Git Bash) and Linux.
+        run: |
+          set -o pipefail
+          out=$(env "lucenenet.compat.write.dir=$WRITE_DIR" dotnet test "${{ env.project_path }}" --configuration "${{ matrix.configuration }}" --framework "${{ matrix.framework }}" --no-build --no-restore --logger:"console;verbosity=normal" --filter "FullyQualifiedName~TestJavaCompatibility.TestWriteIndexForJava" -- "TestRunParameters.Parameter(name=\"compat.codec.name\", value=\"${{ env.codec_name }}\")" 2>&1)
+          echo "$out"
+          echo "$out" | grep -Eq 'Passed:[[:space:]]*1\b' || { echo "::error::TestWriteIndexForJava did not run/pass"; exit 1; }
+        shell: bash
+        env:
+          WRITE_DIR: ${{ github.workspace }}/src/java/index-compat/work/dotnet
+
+      - name: 'Java reads .NET index (nocfs)'
+        run: ./mvnw -q test "-Dlucenenet.index.dir=work/dotnet/index.${{ env.codec_name }}.nocfs"
+        working-directory: ${{ env.compat_dir }}
+        shell: bash
+
+      - name: 'Java reads .NET index (cfs)'
+        run: ./mvnw -q test "-Dlucenenet.index.dir=work/dotnet/index.${{ env.codec_name }}.cfs"
+        working-directory: ${{ env.compat_dir }}
+        shell: bash
+
+      # ---------------------------------------------------------------------
+      # Direction 2: Java writes, .NET reads
+      # ---------------------------------------------------------------------
+      - name: 'Java writes index'
+        run: ./mvnw -q compile exec:java "-Dexec.args=work/java" "-Dcompat.codec.name=${{ env.codec_name }}"
+        working-directory: ${{ env.compat_dir }}
+        shell: bash
+
+      # Guard against a false green: TestReadJavaIndex self-skips (Inconclusive) when
+      # it can't find the index, and a skipped test still exits 0. Require Passed: 1.
+      - name: '.NET reads Java index'
+        run: |
+          set -o pipefail
+          out=$(env "lucenenet.compat.read.dir=$READ_DIR" dotnet test "${{ env.project_path }}" --configuration "${{ matrix.configuration }}" --framework "${{ matrix.framework }}" --no-build --no-restore --logger:"console;verbosity=normal" --filter "FullyQualifiedName~TestJavaCompatibility.TestReadJavaIndex" -- "TestRunParameters.Parameter(name=\"compat.codec.name\", value=\"${{ env.codec_name }}\")" 2>&1)
+          echo "$out"
+          echo "$out" | grep -Eq 'Passed:[[:space:]]*1\b' || { echo "::error::TestReadJavaIndex did not run/pass (skipped or filtered out)"; exit 1; }
+        shell: bash
+        env:
+          READ_DIR: ${{ github.workspace }}/src/java/index-compat/work/java

.gitignore

@@ -67,3 +67,11 @@ svn-*/
 
 # Visual Studio Code/Rider files
 .vscode/
+
+# Index compatibility harness (src/java/index-compat): generated, never committed
+src/java/**/target/
+src/java/**/work/
+
+# macOS files
+.DS_Store
+

.rat-excludes

@@ -16,6 +16,11 @@ _site/*
 svn-dev/*
 svn-release/*
 
+# Maven wrapper scripts (src/java/index-compat) - generated, no ASF header
+mvnw
+mvnw\.cmd
+maven-wrapper\.properties
+
 # Exclude auto-generated designers
 .*\.Designer\.cs