ci: persist staged mining candidates (#1171)

Author: carstenartur

.github/workflows/mining-core.yml

@@ -38,6 +38,14 @@ jobs:
           mvn install -pl sandbox_common_core -DskipTests -q
           mvn package -pl sandbox_mining_core -DskipTests -q
 
+      - name: Snapshot known rules before mining
+        run: |
+          if [ -f docs/mining-report/known-rules.json ]; then
+            cp docs/mining-report/known-rules.json "$RUNNER_TEMP/known-rules-before.json"
+          else
+            printf '{"version":1,"rules":[]}' > "$RUNNER_TEMP/known-rules-before.json"
+          fi
+
       - name: Run Commit Mining
         continue-on-error: true
         env:
@@ -64,6 +72,71 @@ jobs:
             --output docs/mining-report/ \
             ${{ github.event.inputs.llm_provider != '' && format('--llm-provider {0}', github.event.inputs.llm_provider) || '' }}
 
+      - name: Reconcile staged mining candidates
+        if: always()
+        run: |
+          BEFORE_KNOWN="$RUNNER_TEMP/known-rules-before.json"
+          CURRENT_KNOWN="docs/mining-report/known-rules.json"
+          CANDIDATE_DIR="mining-candidates"
+          if [ ! -f "$CURRENT_KNOWN" ]; then
+            echo "No known-rules.json found after mining; skipping candidate reconciliation."
+            exit 0
+          fi
+          python3 - "$BEFORE_KNOWN" "$CURRENT_KNOWN" "$CANDIDATE_DIR" <<'PY'
+          import json
+          import pathlib
+          import sys
+
+          before_path = pathlib.Path(sys.argv[1])
+          known_path = pathlib.Path(sys.argv[2])
+          candidate_dir = pathlib.Path(sys.argv[3])
+
+          def load_rules(path):
+              if not path.exists():
+                  return {"version": 1, "rules": []}
+              with path.open(encoding="utf-8") as handle:
+                  return json.load(handle)
+
+          before = load_rules(before_path)
+          current = load_rules(known_path)
+          before_commits = {
+              rule.get("sourceCommit")
+              for rule in before.get("rules", [])
+              if rule.get("sourceCommit")
+          }
+
+          candidate_commits = set()
+          if candidate_dir.exists():
+              for candidate_path in candidate_dir.glob("*-candidate.json"):
+                  try:
+                      with candidate_path.open(encoding="utf-8") as handle:
+                          candidate = json.load(handle)
+                      commit = candidate.get("sourceCommit")
+                      if commit:
+                          candidate_commits.add(commit)
+                  except Exception as exc:
+                      print(f"Warning: could not read candidate {candidate_path}: {exc}", file=sys.stderr)
+
+          rules = current.get("rules", [])
+          kept = [
+              rule for rule in rules
+              if rule.get("sourceCommit") in before_commits
+              or rule.get("sourceCommit") in candidate_commits
+          ]
+          removed = len(rules) - len(kept)
+          if removed:
+              current["rules"] = kept
+              with known_path.open("w", encoding="utf-8") as handle:
+                  json.dump(current, handle, indent=2)
+                  handle.write("\n")
+          print(
+              "Candidate reconciliation: "
+              f"kept {len(kept)} known rules, "
+              f"removed {removed} non-staged new rules, "
+              f"candidate commits {len(candidate_commits)}"
+          )
+          PY
+
       - name: Post-run diagnostics
         if: always()
         run: |
@@ -99,6 +172,11 @@ jobs:
           if [ -f docs/mining-report/known-rules.json ]; then
             git add docs/mining-report/known-rules.json
           fi
+          # Include staged mining candidates if they were created/updated
+          CANDIDATE_DIR="mining-candidates"
+          if [ -d "$CANDIDATE_DIR" ]; then
+            git add "$CANDIDATE_DIR"/*.json 2>/dev/null || true
+          fi
           # Include auto-generated .sandbox-hint files from HintFileUpdater
           HINT_DIR="sandbox_common_core/src/main/resources/org/sandbox/jdt/triggerpattern/internal"
           if [ -d "$HINT_DIR" ]; then
@@ -129,11 +207,15 @@ jobs:
           if [ -f docs/mining-report/known-rules.json ]; then
             git add docs/mining-report/known-rules.json
           fi
+          # Re-add staged mining candidates after stash pop
+          if [ -d "$CANDIDATE_DIR" ]; then
+            git add "$CANDIDATE_DIR"/*.json 2>/dev/null || true
+          fi
           # Re-add hint files after stash pop
           if [ -d "$HINT_DIR" ]; then
             git add $HINT_DIR/*.sandbox-hint 2>/dev/null || true
           fi
-          git commit -m "mining: Update state + known rules + hints $(date +%Y-%m-%d)"
+          git commit -m "mining: Update state + known rules + candidates $(date +%Y-%m-%d)"
           git push origin "$BRANCH" --force
           echo "state_updated=true" >> "$GITHUB_OUTPUT"
 
@@ -298,4 +380,7 @@ jobs:
         if: always()
         with:
           name: mining-report-${{ github.run_number }}
-          path: docs/mining-report/
+          path: |
+            docs/mining-report/
+            mining-candidates/
+          if-no-files-found: ignore

docs/mining-candidate-integration-tests.md

@@ -0,0 +1,79 @@
+# Mining candidate integration tests
+
+This note outlines a safe way to add optional integration tests for the staged mining pipeline.
+
+## Goal
+
+The normal test suite should remain deterministic and offline. Gemini-backed checks should be opt-in and only run when explicitly requested with credentials.
+
+A useful integration test should verify the complete path for a small, known commit:
+
+1. check out or clone the configured source repository,
+2. extract the diff for a pinned commit,
+3. build the mining prompt,
+4. call the configured LLM provider,
+5. validate the returned DSL rule,
+6. stage a `MiningCandidate`,
+7. assert that `known-rules.json` is only updated for the persisted candidate.
+
+## FQN-aware DSL style
+
+Candidate rules should normally express concrete APIs with fully qualified names. The matcher should accept target code that uses imports or simple names when imports or bindings prove that the code refers to the same API.
+
+For example, a rule written for `java.util.Collections.emptyList()` should also match source code that imports `java.util.Collections` and calls `Collections.emptyList()`.
+
+The same principle should apply to constructors, type references, method receivers, argument types, return types and overload-sensitive API migrations wherever the equivalence is knowable. This keeps mined rules readable and avoids duplicating rules for different source-code presentation forms.
+
+## Suggested execution model
+
+Use a JUnit 5 tag such as `@Tag("gemini-integration")` and gate the test with environment variables:
+
+- `GEMINI_API_KEY`
+- `RUN_GEMINI_INTEGRATION=true`
+- optionally `GEMINI_MODEL`, defaulting to the model used by the workflow
+
+The Maven invocation should be explicit, for example:
+
+```bash
+RUN_GEMINI_INTEGRATION=true \
+GEMINI_API_KEY=... \
+mvn -pl sandbox_mining_core \
+  -Dgroups=gemini-integration \
+  -DskipTests=false \
+  test
+```
+
+The CI default must not run this tag.
+
+## Recommended fixtures
+
+Use a small set of pinned commits that are known to contain generalizable rules and keep each fixture narrow. Good candidates are rules already represented in `docs/mining-report/known-rules.json`, for example:
+
+- Vector constructor modernization to ArrayList, guarded by local assignment context.
+- `String.replaceAll("\\n", replacement)` to `String.replace("\\n", replacement)` for literal non-regex replacement.
+- Deprecated wrapper constructors such as `new Float(x)` or `new Double(x)` to `valueOf(x)`.
+
+Each fixture should define expected properties rather than exact prose:
+
+- expected traffic light: `GREEN`
+- expected `dslValidationResult`: `VALID`
+- expected target hint file or category
+- required DSL fragments, not the entire exact LLM response
+- before/after/negative examples when available
+
+## Reproducibility notes
+
+LLM responses are probabilistic, so the assertions should not depend on exact wording. The useful measurement is whether the model still finds a valid, general rule under the current prompt and budget.
+
+For cognitive-load/regression tracking, store a small JSON summary as a build artifact:
+
+- model name
+- prompt size
+- diff size
+- latency
+- token usage if available
+- traffic light
+- DSL validation result
+- candidate ID
+
+This makes prompt regressions visible without committing live LLM output into the repository.

sandbox_common_core/src/main/java/org/sandbox/jdt/triggerpattern/api/PatternIndex.java

@@ -32,6 +32,7 @@
 import org.eclipse.jdt.core.dom.MethodInvocation;
 import org.eclipse.jdt.core.dom.Statement;
 import org.eclipse.jdt.core.dom.VariableDeclarationStatement;
+import org.sandbox.jdt.triggerpattern.internal.FqnAwarePlaceholderAstMatcher;
 import org.sandbox.jdt.triggerpattern.internal.PatternParser;
 import org.sandbox.jdt.triggerpattern.internal.PlaceholderAstMatcher;
 
@@ -204,7 +205,7 @@ private void matchAgainstKind(ASTNode node, PatternKind kind,
 		}
 
 		for (IndexEntry entry : entries) {
-			PlaceholderAstMatcher matcher = new PlaceholderAstMatcher();
+			PlaceholderAstMatcher matcher = new FqnAwarePlaceholderAstMatcher();
 			matcher.setCaseInsensitive(caseInsensitive);
 			if (entry.patternNode().subtreeMatch(matcher, node)) {
 				Match match = new Match(node, matcher.getBindings(),
@@ -239,35 +240,25 @@ private void matchStatementSequences(Block block,
 				continue;
 			}
 
-			// Sliding window
-			for (int i = 0; i <= statements.size() - patternSize; i++) {
-				boolean allMatch = true;
-				PlaceholderAstMatcher combinedMatcher = new PlaceholderAstMatcher();
-				combinedMatcher.setCaseInsensitive(caseInsensitive);
-				for (int j = 0; j < patternSize; j++) {
-					PlaceholderAstMatcher matcher = new PlaceholderAstMatcher();
-					matcher.setCaseInsensitive(caseInsensitive);
-					if (!patternStatements.get(j).subtreeMatch(matcher, statements.get(i + j))) {
-						allMatch = false;
-						break;
-					}
-					combinedMatcher.mergeBindings(matcher);
+			for (int start = 0; start <= statements.size() - patternSize; start++) {
+				Block syntheticBlock = block.getAST().newBlock();
+				for (int i = 0; i < patternSize; i++) {
+					syntheticBlock.statements().add(ASTNode.copySubtree(block.getAST(), statements.get(start + i)));
 				}
-				if (allMatch) {
-					Statement first = statements.get(i);
-					Statement last = statements.get(i + patternSize - 1);
-					int offset = first.getStartPosition();
-					int length = (last.getStartPosition() + last.getLength()) - offset;
-					Match match = new Match(first, combinedMatcher.getBindings(), offset, length);
+
+				PlaceholderAstMatcher matcher = new FqnAwarePlaceholderAstMatcher();
+				matcher.setCaseInsensitive(caseInsensitive);
+				if (patternBlock.subtreeMatch(matcher, syntheticBlock)) {
+					int offset = statements.get(start).getStartPosition();
+					Statement last = statements.get(start + patternSize - 1);
+					int length = last.getStartPosition() + last.getLength() - offset;
+					Match match = new Match(block, matcher.getBindings(), offset, length);
 					results.computeIfAbsent(entry.rule(), r -> new ArrayList<>()).add(match);
 				}
 			}
 		}
 	}
 
-	/**
-	 * An entry in the pattern index, containing a rule and its pre-parsed pattern node.
-	 */
 	private record IndexEntry(TransformationRule rule, Pattern sourcePattern, ASTNode patternNode) {
 	}
 }