`), re-including it.
+
+- [ ] **Step 2: Verify the default build skips tagged tests (no perf test yet — use a temporary probe)**
+
+Create a throwaway probe to prove exclusion works before writing the real test. Create `java/src/test/java/com/ibm/plugin/perf/TagExclusionProbe.java`:
+
+```java
+package com.ibm.plugin.perf;
+
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+class TagExclusionProbe {
+ @Tag("performance")
+ @Test
+ void taggedTestMustBeExcludedByDefault() {
+ throw new AssertionError("this @Tag(performance) test must NOT run in the default build");
+ }
+}
+```
+
+Run (default build must NOT execute it, so it must stay green):
+`mvn test -pl java -Dtest=TagExclusionProbe`
+Expected: BUILD SUCCESS with "No tests were executed" (or 0 run) — the tag is excluded.
+
+Then confirm it DOES run when exclusion is cleared, and fails as written:
+`mvn test -pl java -DexcludedGroups= -Dtest=TagExclusionProbe`
+Expected: FAIL with the `AssertionError` above — proving `-DexcludedGroups=` re-includes tagged tests.
+
+Delete the probe: `rm java/src/test/java/com/ibm/plugin/perf/TagExclusionProbe.java`
+
+- [ ] **Step 3: Commit the surefire change**
+
+```bash
+mvn spotless:apply
+git add pom.xml
+git commit -m "build: exclude @Tag(performance) tests from default surefire run"
+```
+
+- [ ] **Step 4: Write the perf harness test**
+
+Create `java/src/test/java/com/ibm/plugin/perf/CallStackHeapPerfTest.java`. Starting thresholds are intentionally loose (`detachedRatio >= 0.5`, `retainedWithTree <= units`); Step 6 tightens them against observed numbers.
+
+```java
+package com.ibm.plugin.perf;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.ibm.engine.callstack.CallContextStats;
+import com.ibm.engine.detection.DetectionStore;
+import com.ibm.mapper.model.INode;
+import com.ibm.plugin.JavaAggregator;
+import com.ibm.plugin.TestBase;
+import com.ibm.rules.issue.Issue;
+import java.io.File;
+import java.lang.management.ManagementFactory;
+import java.lang.management.MemoryMXBean;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import javax.annotation.Nonnull;
+import javax.tools.JavaCompiler;
+import javax.tools.ToolProvider;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.sonar.java.checks.verifier.CheckVerifier;
+import org.sonar.plugins.java.api.JavaCheck;
+import org.sonar.plugins.java.api.JavaFileScannerContext;
+import org.sonar.plugins.java.api.semantic.Symbol;
+import org.sonar.plugins.java.api.tree.Tree;
+
+/**
+ * Manual heap/perf harness for the call-stack AST-detach mechanism. Generates a synthetic
+ * cross-file crypto corpus (scale via {@code -Dperf.corpus.files}, default 200), scans it in-process
+ * through {@link CheckVerifier} (compiled to a classpath dir so callee types resolve and cross-file
+ * detections fire), then asserts the recorded calls were detached (ASTs released) at {@code
+ * leaveFile}. Heap delta and wall-time are printed for manual comparison, never asserted.
+ *
+ * Excluded from the default build via {@code @Tag("performance")}. Run with:
+ * {@code mvn test -pl java -DexcludedGroups= -Dtest=CallStackHeapPerfTest} (add
+ * {@code -Dperf.corpus.files=3000} for a heavy soak). This does NOT reproduce the full-project ~7 GB
+ * keycloak number — that remains the documented manual {@code mvn sonar:sonar} route in
+ * {@code docs/superpowers/plans/2026-07-05-callstack-hooks-heap-reduction.md}.
+ */
+@Tag("performance")
+class CallStackHeapPerfTest extends TestBase {
+
+ private static final int FILES = Integer.getInteger("perf.corpus.files", 200);
+
+ /** Raise no SonarQube issues, so the harness is decoupled from {@code // Noncompliant} lines. */
+ @Override
+ public List> report(@Nonnull Tree markerTree, @Nonnull List translatedNodes) {
+ return List.of();
+ }
+
+ @Override
+ public void asserts(
+ int findingId,
+ @Nonnull DetectionStore detectionStore,
+ @Nonnull List nodes) {
+ // no per-finding assertions; the harness asserts on aggregate CallContextStats below
+ }
+
+ @Test
+ void detachesRecordedCallsAtScale(@TempDir Path tmp) throws Exception {
+ int units = Math.max(1, FILES / 2);
+ List sources = CryptoCorpusGenerator.generate(tmp, units);
+ File classes = compileToClasspath(sources);
+
+ MemoryMXBean mem = ManagementFactory.getMemoryMXBean();
+ long heapBefore = usedHeapAfterGc(mem);
+ long start = System.nanoTime();
+
+ CheckVerifier.newVerifier()
+ .onFiles(absolutePaths(sources))
+ .withClassPath(List.of(classes))
+ .withChecks(this)
+ .verifyNoIssues();
+
+ long elapsedMs = (System.nanoTime() - start) / 1_000_000L;
+ long heapAfter = usedHeapAfterGc(mem);
+
+ CallContextStats stats = JavaAggregator.getLanguageSupport().callContextStats();
+
+ // REPORT (never asserted)
+ System.out.printf(
+ "%n[callstack-perf] files=%d units=%d time=%dms heapDeltaMB=%d "
+ + "retainedWithTree=%d detached=%d total=%d buckets=%d ratio=%.3f%n",
+ sources.size(),
+ units,
+ elapsedMs,
+ (heapAfter - heapBefore) / (1024L * 1024L),
+ stats.retainedWithTree(),
+ stats.detached(),
+ stats.total(),
+ stats.buckets(),
+ stats.detachedRatio());
+
+ // ASSERT (deterministic gate — object-variant counts, no heap/time dependence)
+ assertThat(stats.total())
+ .as("detections must fire (compiled classpath) or the harness proves nothing")
+ .isPositive();
+ assertThat(stats.detachedRatio())
+ .as("most recorded calls must be detached (ASTs released at leaveFile)")
+ .isGreaterThanOrEqualTo(0.5d);
+ assertThat(stats.retainedWithTree())
+ .as("tree-pinning calls must stay bounded, not grow ~1:1 with detached")
+ .isLessThanOrEqualTo(units);
+ }
+
+ private static File compileToClasspath(@Nonnull List sources) throws Exception {
+ Path out = Files.createTempDirectory("perf-corpus-classes");
+ JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
+ List args = new ArrayList<>(List.of("-d", out.toString()));
+ for (Path s : sources) {
+ args.add(s.toAbsolutePath().toString());
+ }
+ int rc = compiler.run(null, null, null, args.toArray(new String[0]));
+ if (rc != 0) {
+ throw new IllegalStateException("corpus compilation failed rc=" + rc);
+ }
+ return out.toFile();
+ }
+
+ @Nonnull
+ private static List absolutePaths(@Nonnull List sources) {
+ List paths = new ArrayList<>(sources.size());
+ for (Path s : sources) {
+ paths.add(s.toAbsolutePath().toString());
+ }
+ return paths;
+ }
+
+ private static long usedHeapAfterGc(@Nonnull MemoryMXBean mem) {
+ System.gc();
+ try {
+ Thread.sleep(50L);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ }
+ return mem.getHeapMemoryUsage().getUsed();
+ }
+}
+```
+
+Note: `report(...)` overrides `JavaInventoryRule.report(Tree, List)` which returns `List>` (`java/src/main/java/com/ibm/plugin/rules/JavaInventoryRule.java:49`), so the import above is `com.ibm.rules.issue.Issue`. Returning `List.of()` raises no issues, so `verifyNoIssues()` passes regardless of detections.
+
+- [ ] **Step 5: Run the perf test to verify it passes on this branch (detach live)**
+
+Run: `mvn spotless:apply -pl java && mvn test -pl java -DexcludedGroups= -Dtest=CallStackHeapPerfTest`
+Expected: PASS. Capture the printed `[callstack-perf] ...` line. Sanity-check it: `total` positive (detections fired), `detached` is the large majority, `retainedWithTree` small.
+
+If `total == 0`: types did not resolve — verify `withClassPath(classes)` is present and the corpus compiled (the `compileToClasspath` step threw nothing). If `onFiles` rejects the absolute temp paths, generate under a module-relative dir instead (e.g. `Path root = Path.of("target", "perf-corpus");` cleaned at start) and pass module-relative paths.
+
+- [ ] **Step 6: Tighten thresholds to the observed numbers**
+
+Using the captured line, tighten the two assertions so they still pass comfortably on this branch but leave no room for a regression to slip through:
+- Set `detachedRatio` lower bound just below the observed ratio (e.g. observed 0.98 → assert `>= 0.9`).
+- Set the `retainedWithTree` bound to a small multiple of the observed value, still well under `units` and NOT proportional to `total` (e.g. observed 3 with units 100 → assert `<= 20`).
+
+Edit the two `assertThat` bounds accordingly. Re-run Step 5's command; expected PASS.
+
+- [ ] **Step 7: Validate the assertion discriminates (neutralize detach → must FAIL)**
+
+This proves the test is worth committing. Temporarily make detach a no-op — comment out the body of `CallStackAgent.detachCallsForFile` (or of `JavaLanguageSupport.notifyLeaveFile`) so no call is ever swapped to its detached form:
+
+Run: `mvn test -pl java -DexcludedGroups= -Dtest=CallStackHeapPerfTest`
+Expected: **FAIL** — `retainedWithTree` now grows with the corpus (≈ `total`) and `detachedRatio` collapses toward 0, tripping both assertions. Capture the failing line to confirm.
+
+**Revert the neutralization** (`git checkout -- engine/src/main/java/com/ibm/engine/callstack/CallStackAgent.java`) and re-run Step 5 to confirm PASS again. The neutralization is a local sanity check and is **NOT committed**.
+
+- [ ] **Step 8: Confirm the default build still skips it, then commit**
+
+Run: `mvn test -pl java -Dtest=CallStackHeapPerfTest` (default build)
+Expected: BUILD SUCCESS, 0 tests run (tag excluded) — CI-safe.
+
+```bash
+mvn checkstyle:check -pl java
+git add java/src/test/java/com/ibm/plugin/perf/CallStackHeapPerfTest.java
+git commit -m "test(java): manual call-stack heap/perf harness (@Tag performance)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Self-contained JUnit, no docker/network → Tasks 3–4 (generator + in-process `CheckVerifier`). ✓
+- Not keycloak; synthetic corpus, scale knob → Task 3 generator, `-Dperf.corpus.files` (Task 4). ✓
+- Types must resolve → Task 4 `compileToClasspath` + `withClassPath` (mirrors `CrossFileHookDetachTest`). ✓
+- Wrapper/caller cross-file pattern with literal + field-constant (detachable) args → Task 3 templates. ✓ (Note: the design's `new byte[]` retained case is intentionally omitted from the generator — the primary signal is a high detach ratio + bounded tree-pinning; the retained path is already covered functionally by `CrossFileHookDetachTest`. Recorded in the spec's assertion section.)
+- Structural assert (`retainedWithTree` bounded, `detachedRatio` high) via `callContextStats()` → Tasks 1–2 accessor, Task 4 asserts. ✓
+- Heap/time report-only, never asserted → Task 4 `System.out.printf`, no assertion on `heapDelta`/`elapsedMs`. ✓
+- Small `callContextStats()` accessor, not reflection → Tasks 1–2. ✓
+- Manual only, `@Tag("performance")` + surefire `excludedGroups` → Task 4 Steps 1–3, 8. ✓
+- Placement (`com.ibm.plugin.perf`, engine `callstack`/`detection`/`language`) → matches approved layout. ✓
+- Harness self-validation (passes with detach, fails without) → Task 4 Step 7. ✓
+- Pointer to the manual keycloak `mvn sonar:sonar` route, not automated → Task 4 test javadoc. ✓
+
+**Placeholder scan:** No TBD/TODO. The two threshold values are concrete starting numbers (`0.5`, `units`) with an explicit, evidence-based tightening step (Task 4 Step 6) — not placeholders. All imports are exact (`Issue` verified as `com.ibm.rules.issue.Issue`).
+
+**Type consistency:** `callContextStats()` returns `CallContextStats` at every layer (`CallStackAgent`, `Handler`, `ILanguageSupport`, `JavaLanguageSupport`). `CallContextStats.from(Collection>>)` matches `invokedCallStack.values()`'s type (`Collection>>`). `generate(Path, int) -> List` consumed consistently in Tasks 3 and 4. `detachedRatio()`, `retainedWithTree()`, `detached()`, `total()`, `buckets()` accessor names consistent between Task 1 definition and Task 4 use.
diff --git a/docs/superpowers/specs/2026-07-05-callstack-detach-heap-reduction-design.md b/docs/superpowers/specs/2026-07-05-callstack-detach-heap-reduction-design.md
new file mode 100644
index 000000000..7d9fc47ec
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-05-callstack-detach-heap-reduction-design.md
@@ -0,0 +1,124 @@
+# Call-stack Detach — Heap Reduction Design Spec
+
+**Status:** Draft for review
+**Date:** 2026-07-05
+**Supersedes / refines:** `docs/superpowers/plans/2026-07-05-callstack-hooks-heap-reduction.md` (Phase 2 section)
+**Decision this spec records:** go straight to the structural fix (detach recorded calls from the AST), skipping the plan's incremental Phase 1 filter/caps.
+
+## Goal
+
+Cut the project-lifetime heap held by `com.ibm.engine.callstack` on large scans — measured at ~179k retained `CallContext`s driving ~7 GB and climbing on a near-full keycloak scan, growing linearly and unbounded with project size — **without regressing cross-file detection**. Cross-file detection has no CI coverage today (every `CheckVerifier` test is single-file), so correctness preservation is the dominant constraint.
+
+## Root cause (verified against current code)
+
+One static `CallStackAgent` per language accumulates a `CallContext(tree, scanContext)` for **every recorded method invocation / enum access** across the whole scan and is released only at end-of-scan. `CallStackAgent.invokedCallStack` (`CallStackAgent.java:42`) is the holder.
+
+The heap is dominated not by the *count* of `CallContext`s but by **per-file AST pinning**. Each `CallContext`:
+- holds a `Tree` whose `parent()` chain reaches the file's `CompilationUnitTree`, and
+- holds `JavaScanContext`, a `record(JavaFileScannerContext)` (`JavaScanContext.java:29`) that pins the whole file's AST a second way.
+
+So a *single* surviving `CallContext` pins its entire file AST for the whole scan. Retained heap ≈ (distinct files with ≥1 recorded call) × (avg file AST size). Reducing the *count* (the plan's Phase 1 filter/caps) does not unpin a file that has even one surviving call — which is why this spec goes straight to detaching trees.
+
+### The tree is load-bearing in three distinct places
+
+A recorded call's tree is read at three points. All three must be handled to hold zero trees:
+
+1. **Match** — `MethodMatcher.match(callContext.tree(), …)` in `onNewHookSubscription` (`CallStackAgent.java:107`) and via `HookRepository.update` → `hook.isInvocationOn(callContext, …)` (`HookRepository.java:117`). Reads invoked-object type, method name, parameter types off the tree.
+ - *Snapshot-able at record time* — these three keys are all derivable while the file is live.
+
+2. **Resolution input** — at fire time, `DetectionStoreWithHook.handleMethodInvocationHookWithParameterResolvement` (`DetectionStoreWithHook.java:124`) runs `extractArgumentFromMethodCaller` (`JavaDetectionEngine.java:121`) + `resolveValuesInInnerScope` (`:169`) on the **live** call-site argument tree and file symbol table.
+ - *Verified narrowing (Java):* the parameter hook is always built with the 4-arg constructor (`JavaDetectionEngine.java:477`), so `expressionToResolve` is always `null` (`MethodInvocationHookWithParameterResolvement.java:43`). The cross-boundary branch never fires for Java. Fire-time resolution is therefore always "resolve the call-site argument directly," which is **fully reproducible at record time** because the file is live then.
+ - *Verified narrowing (factory influence):* `valueFactory` steers traversal in exactly one place — `if (valueFactory instanceof SizeFactory)` for `NEW_ARRAY` args (`JavaDetectionEngine.java:275`). Everywhere else the factory is threaded but not inspected; the raw `ResolvedValue` list is factory-independent, and the factory is applied *afterward* (`DetectionStoreWithHook.java:185`, `ValueDetection.toValue`).
+
+3. **Detection output (location)** — the produced `IValue.getLocation()` returns the tree (`IValue.java:26`; each of 27 model value classes stores its own `T location`). The sole production consumer is the translator: `JavaTranslator.getDetectionContextFrom` (`JavaTranslator.java:170`) reduces the tree to `DetectionLocation(filePath, lineNumber, columnOffset, keywords, bundle)` — every field derivable at record time.
+ - *Consequence:* the produced `IValue`'s location must not pin the AST. We satisfy this **without changing the value model** by using a synthetic detached `SyntaxToken` (see §4).
+
+## Keeping `T = Tree` (no value-model change)
+
+An earlier reading of point 3 suggested every model value would need a `Location` abstraction (re-typing 27 model classes + 27 factories). That is **not necessary**. The value model's location `T` stays `Tree`; we supply a **synthetic detached `Tree`** for cross-file detections:
+
+- `org.sonar.plugins.java.api.location.Position.at(int,int)` and `Range.at(...)` are public static factories producing AST-free coordinate objects; `SyntaxToken` is a small interface (`text/trivias/line/column/range` + `Tree`'s `is/accept/parent/firstToken/lastToken/kind`).
+- A `DetachedSyntaxToken implements SyntaxToken` backed by captured primitives (line, column offsets, and the record-time keywords) returns `parent() == null` and `firstToken()/lastToken() == this`, so it pins nothing.
+- The existing factories build `IValue` with this token as the location, unchanged. Scope stays essentially within callstack/hooks + one new token class + a single translator branch. The plan's "strictly callstack/hooks" spirit holds.
+
+## Chosen architecture: Hybrid detach with tree-fallback
+
+Detach (store a tree-free record) **only** for calls whose fire-time behavior is provably reproducible from a record-time snapshot; **keep the live tree** (today's behavior, that file stays pinned) for the residual. This guarantees no Java detection loss while unpinning the common case.
+
+### 1. Detachability predicate (record time, Java)
+
+At `addCall`, run the existing resolution over each argument with a `null` factory and record whether resolution descended into a `NEW_ARRAY`. A recorded call is **detachable** iff:
+- it is a method invocation whose argument resolution did **not** touch a `NEW_ARRAY` (the only factory-steered case; a future `SizeFactory` hook would want the array size, not its elements), and
+- (Java) always — since `expressionToResolve` is always null, there is no cross-boundary case.
+
+Otherwise the call is **non-detachable** → keep the live `Tree` (fallback path, unchanged behavior). Python/Go are **always non-detachable** in this iteration (they use `expressionToResolve`; their semantics are out of scope) → they keep the tree exactly as today. The predicate lives in the language layer so the generic engine stays language-agnostic.
+
+### 2. Detached record shape
+
+Replace `CallContext(tree, scanContext)` with a sealed shape:
+- `RetainedCall(T tree, IScanContext scanContext)` — the fallback (non-detachable) case, identical to today.
+- `DetachedCall` — tree-free, holding:
+ - **match keys:** invoked-object `IType`, method name, parameter `IType`s (for `MethodMatcher` without a tree);
+ - **pre-resolved arguments:** for each argument index, the raw resolved value(s) (`Object`) plus captured location primitives (line, offset, keywords) for a `DetachedSyntaxToken` (see §4). If *any* argument fails to pre-resolve at record time, the call is treated as non-detachable and keeps its tree (fallback) — never a silent per-argument drop;
+ - for enum accesses: the enum class name plus a snapshot map `{constantName → resolvedValue + location primitives}` (fire-time `EnumHook` selection picks by name).
+
+Match uses the keys; the argument/enum snapshots feed fire-time replay. No `Tree` and no `JavaFileScannerContext` are retained → the file AST becomes GC-eligible after `leaveFile`.
+
+### 3. Fire-time replay
+
+`onNewHookSubscription` and `HookRepository.update` match against the record's keys instead of a tree. On a match of a `DetachedCall`, `DetectionStoreWithHook` skips `extractArgumentFromMethodCaller`/`resolveValuesInInnerScope` and instead takes the pre-resolved snapshot for the hook's parameter index, applies the hook's factory to it, and proceeds through `handleNextRulesForMethodHooks` as today (that path visits `hook.methodDefinition()`, from the hook's own file, and is unaffected by detachment). `RetainedCall`s replay exactly as today.
+
+### 4. Detached location via synthetic `SyntaxToken` (no model change)
+
+`getLocation()` keeps returning `Tree`; for a detached call we hand the factory a `DetachedSyntaxToken` instead of a real leaf tree:
+
+- **New class** `DetachedSyntaxToken implements SyntaxToken` (engine, `com.ibm.engine…`): fields = start/end line + column offsets and the record-time `keywords`. `range()` → `Range.at(Position.at(line, col), Position.at(endLine, endCol))`; `firstToken()/lastToken()` → `this`; `kind()` → `Tree.Kind.TOKEN`; `parent()` → `null`; `accept()` → no-op; `text()` → the resolved value string; `trivias()` → empty. Value `equals/hashCode` over the fields (model `equals` compares `getLocation()`).
+- **Record time:** while the argument's leaf tree is live, capture (line, columnOffset, end position, keywords) — computed by the *same* logic `JavaTranslator.getDetectionContextFrom` uses (`JavaTranslator.java:170`) — and store the primitives in the `DetachedCall`. No `Tree`/`Range`/`Position` object is retained (store ints), so nothing pins the AST.
+- **Fire time:** build `new ResolvedValue<>(rawValue, new DetachedSyntaxToken(...))` and run the existing factory unchanged → `IValue` whose location pins nothing.
+- **One translator branch:** `JavaTranslator.getDetectionContextFrom` gets a leading `if (location instanceof DetachedSyntaxToken d) return new DetectionLocation(filePath, d.line(), d.offset(), d.keywords(), bundle);`. This preserves `keywords`/`additionalContext` fidelity exactly (they were computed from the live tree at record time). Python/Go never produce a `DetachedSyntaxToken`, so their translators are untouched.
+
+Zero edits to the 27 model classes, 27 factories, and `ResolvedValue`. The change is one new class + one translator branch, plus the record/replay wiring.
+
+### 5. Lossless cleanups folded in
+
+- Delete the redundant `visitedTreeObjects` set (`CallStackAgent.java:45`); dedup within the per-name bucket (buckets are small once keys index them). Measured 100% redundant with `invokedCallStack`.
+- Key-indexed subscription lookup in `onNewHookSubscription` (`CallStackAgent.java:101`): derive the name key from the hook value and scan only that bucket, with a fallback scan for multi-name/`ANY` matchers.
+
+## Bounded, documented loss
+
+- **Java:** zero detection loss by construction — the only non-reproducible cases (`NEW_ARRAY`/`SizeFactory`, cross-boundary `expressionToResolve`) are kept on the tree-fallback path. If measurement later shows the array-fallback set is large enough to matter for heap, a follow-up can pre-resolve both interpretations; not in this iteration.
+- **Python/Go:** unchanged (always tree-fallback). No detach, no loss, no heap win for those languages yet.
+- Any record-time resolution failure logs at DEBUG and falls back to keeping the tree, never to silent loss.
+
+## Blast radius / files
+
+- `engine/.../callstack/CallStackAgent.java` — key-indexed lookup; drop `visitedTreeObjects`; record `DetachedCall` vs `RetainedCall`; match against keys.
+- `engine/.../callstack/CallContext.java` — becomes the sealed record family (`RetainedCall`/`DetachedCall`).
+- `engine/.../callstack/DetachedSyntaxToken.java` — NEW (synthetic `SyntaxToken`, §4).
+- `engine/.../detection/DetectionStoreWithHook.java` — detached replay branch (build `ResolvedValue` from snapshot + `DetachedSyntaxToken`, skip `extractArgumentFromMethodCaller`/`resolveValuesInInnerScope`).
+- `engine/.../language/java/JavaDetectionEngine.java` — record-time pre-resolution + `NEW_ARRAY` detection + capture location primitives.
+- `engine/.../language/ILanguageSupport.java` (or `ILanguageTranslation.java`) — `isDetachableCall` predicate (default: not detachable → Python/Go keep trees).
+- `java/.../translation/translator/JavaTranslator.java` — leading `DetachedSyntaxToken` branch in `getDetectionContextFrom` (Python/Go translators untouched).
+- `java/src/test/files/...` + a new multi-file `CheckVerifier` test — NEW (see Verification).
+
+No edits to the 27 `engine/.../model/*.java`, the 27 `engine/.../model/factory/*.java`, `ResolvedValue.java`, or the Python/Go engines/translators.
+
+## Verification
+
+- **Cross-file regression guard (new, does not exist today):** a multi-file `CheckVerifier` test where a hook created in file B resolves a call recorded in file A. Must cover **both** a detached argument (literal / constant / field / nested-call) **and** a tree-fallback argument (`NEW_ARRAY`/size), asserting both still detect.
+- `mvn test -pl engine` and `mvn test -pl java` stay green throughout (run `mvn spotless:apply` before commits; restore `JsonCipherSuites` if Spotless truncates it).
+- **Heap profile:** scan a large project (e.g. keycloak via `mvn sonar:sonar`, or supply `sonar.java.libraries`) under a constrained `MAVEN_OPTS="-Xmx"`; capture `jmap -histo` before/after and record the drop in retained `CallContext`/AST and peak heap. Types must resolve (source-only scans fire `addCall` zero times).
+
+## Risks & open implementation questions
+
+- **`DetachedSyntaxToken` consumer safety (top risk):** the synthetic token returns `parent() == null` and a no-op `accept()`. This is safe only if every consumer of a value's `getLocation()` reads at most `firstToken()/lastToken()/kind()/range()`. Verified today: the sole *production* consumer is `getDetectionContextFrom`; production CBOM output does not `reportIssue` on value locations (that path is test-only). **Task:** audit all `IValue.getLocation()` consumers to confirm none navigate `parent()`/`accept()`/children, and make the new multi-file test's `asserts()` tolerant of detached locations.
+- **Record-time pre-resolution fidelity:** must produce exactly the raw `ResolvedValue`s fire-time would, minus the `NEW_ARRAY`/`SizeFactory` case (kept on tree-fallback). Guard with a test that resolves the same argument both ways and asserts equality.
+- **Enum snapshot completeness:** pre-resolving all enum constants at record time must match `resolveEnumValue`'s selection semantics; verify against existing enum-hook tests.
+- **Location fidelity:** `keywords`/line/offset captured at record time must match what `getDetectionContextFrom` derives from the live tree, so CBOM occurrences (incl. `additionalContext`) are identical for detached vs. non-detached detections. Verify via an output-level test.
+- **`filePath` origin for cross-file values:** confirm the translator receives file A's (call-site) path for a detached value, matching today's tree-derived behavior — this is independent of the token but must be checked on the cross-file path.
+
+## Explicitly out of scope
+
+- Python/Go detachment (kept on tree-fallback).
+- The rule-graph construction OOM (`MethodMatcher.`, tracked in #476/#477).
+- Retention caps / lossy bounding from the original plan's Phase 1 (Task 5) — the detach makes them unnecessary; revisit only if post-detach record *count* itself proves a problem.
diff --git a/docs/superpowers/specs/2026-07-06-callstack-heap-attribution-trim-design.md b/docs/superpowers/specs/2026-07-06-callstack-heap-attribution-trim-design.md
new file mode 100644
index 000000000..6414edbb5
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-06-callstack-heap-attribution-trim-design.md
@@ -0,0 +1,191 @@
+# Call-stack Heap: Attribution & Trim — Design
+
+**Date:** 2026-07-06
+**Status:** Approved (brainstorming) — ready for `writing-plans`
+**Scope:** `engine` + Java language support + perf harness/docs. Heap track of the performance backlog.
+
+## Summary
+
+The AST-detach work (`feat/callstack-ast-detach`) removed the dominant heap term on large
+scans — whole-file AST pinning by the call-stack (the measured ~7 GB on Keycloak). A smaller
+residual remains: the post-GC heap floor still grows over a scan (observed ~1.6 → ~3.4 GB).
+That growth was *hypothesized* to be `JavaAggregator.detectedNodes`, but it was never
+attributed, and the now-uncapped detached call-stack population is an equally plausible
+source.
+
+This design does two things, in order:
+
+1. **H1 — Attribute the floor (the gate).** Measure what actually grows the post-detach
+ floor, split across three buckets: retained CBOM `INode`s, detached call-stack records,
+ and hooks. The result decides how much of H2 to build and whether `detectedNodes` earns
+ its own future spec.
+2. **H2 — Trim the call-stack.** Land the *deferred* Phase-1 work from
+ `docs/superpowers/plans/2026-07-05-callstack-hooks-heap-reduction.md`: an eligibility
+ filter that stops recording library calls (Tasks 1–2, done regardless), and — **only if
+ H1 shows the detached population is still material** — a retention cap (Task 5).
+
+Measure first, so we don't trim a term that no longer dominates.
+
+## Background / Why now
+
+The original heap plan phased the work as: Phase 1 (trim + bound what enters the call-stack)
+→ Phase 2 (detach recorded calls from the AST). In practice **Phase 2 shipped first** and
+some of Phase 1 shipped alongside it:
+
+| Original Phase-1 task | Status |
+|---|---|
+| Task 3 — drop redundant `visitedTreeObjects` | **Done** |
+| Task 4 — key-indexed subscription lookup | **Done** |
+| Task 1–2 — `isHookEligibleCall` filter (skip library calls) | **Not done** |
+| Task 5 — retention caps / overflow WARN | **Not done** |
+| Phase 2 — AST detach | **Done** (out of order) |
+
+Because detach landed, the old Task-6 measurement (pre-detach, ~7 GB, AST-pinning-dominated)
+no longer describes the current heap. H1 re-measures the *post-detach* residual; H2 finishes
+the deferred trim.
+
+### Load-bearing facts (verified in the original plan, still hold post-detach)
+
+- The call-stack (`CallStackAgent.invokedCallStack`) is project-lifetime: one record per
+ distinct recorded invocation, released only by the end-of-scan `ScannerManager.reset()`.
+ Measured growth is **linear and unbounded** in project size (~179k records at ~63M calls
+ on Keycloak). Detach shrank each record's footprint (no AST pin) but **not the count**.
+- Method hooks are created only from **user methods with a source declaration**
+ (`JavaDetectionEngine`, `declaration() != null`). A hook's matcher encodes a **specific
+ user-class FQN** and matches only `invokedObjectType.is(userClassFQN) AND name AND params`.
+ ⇒ A recorded **library** call (library owner type, no source declaration) can never match
+ any method hook. Recording it is pure waste. **Enum** accesses match a separate `EnumHook`
+ path and must stay recorded.
+- Cross-file resolution replays the *entire accumulated* call-stack (a hook created in file B
+ resolves a call in file A), so retention **cannot** be scoped per file. This is why the
+ trim is an eligibility filter (never record the useless calls) rather than per-file
+ clearing.
+
+## H1 — Attribute the floor
+
+**Problem.** The perf harness (`CallStackHeapPerfTest`) prints `heapDeltaMB` and
+`CallContextStats` (retained-with-tree vs. detached counts), but nothing attributes retained
+*bytes* to a source. We can't currently tell call-stack from `detectedNodes` from hooks.
+
+**Approach — two signals:**
+
+1. **In-process object counts (cheap, always-on).** Extend the end-of-scan reporting to emit,
+ alongside `CallContextStats`:
+ - `JavaAggregator.getDetectedNodes().size()` (retained CBOM node count),
+ - detached call-stack record count (already in `CallContextStats.detached()`),
+ - hook-subscription counts (`HookRepository` / `HookDetectionObservable`).
+
+ Surface these in two places: the `CallStackHeapPerfTest` report line, and a single DEBUG
+ log at end-of-scan (in `ScannerManager` or the aggregator) so they appear on a real
+ Keycloak run too. These are counts, not bytes — they size *populations*, not footprint.
+
+2. **True byte attribution (manual, decisive).** On a constrained-heap Keycloak scan using the
+ existing `jmap -histo:live` protocol in `docs/PERFORMANCE_TESTING.md`, attribute retained
+ bytes across three buckets:
+ - CBOM model: `com.ibm.mapper.model.*` `INode` subclasses (Algorithm, Key, Property, …),
+ - Call-stack: `DetachedCall`, `ArgSnapshot`, `ResolvedSnapshotValue`,
+ - Residual `Tree`/hooks: any `org.sonar.*` Tree still retained + hook structures.
+
+**Deliverable.** A short attribution table appended to `docs/PERFORMANCE_TESTING.md` (or a
+dated note) plus a one-paragraph **decision**:
+- Residual floor is **call-stack-dominated** → build H2's cap (Task 5) as well as the filter.
+- Residual floor is **`detectedNodes`-dominated** → build only H2's filter (still a lossless
+ trim + CPU assist); open a *separate* spec for `detectedNodes` (dedup / incremental
+ emission). That spec is explicitly **out of scope here**.
+- Residual floor is **hooks-dominated** → open a hooks-pruning spec (was Tier-3 item H3).
+
+H1 has no acceptance test beyond "the numbers are captured and the decision is written."
+
+## H2 — Trim the call-stack
+
+### Eligibility filter (Tasks 1–2) — build regardless of H1
+
+Add a language-layer predicate that mirrors the existing `isDetachableCall` sibling:
+
+- **`engine/.../language/ILanguageSupport.java` (or `ILanguageTranslation`)** — add
+ `default boolean isHookEligibleCall(T tree) { return true; }`. Keeping it a defaulted method
+ leaves Python/Go on record-all (unchanged behavior).
+- **`engine/.../language/java/JavaLanguageSupport.java`** — implement for Java: `true` for
+ enum accesses (must stay recorded for `EnumHook`) and for calls whose invoked-object owner
+ type *could* be a user class; `false` for library calls. **Predicate premise correction:**
+ the discriminator is **not** `methodSymbol().declaration() != null` — cross-file *user* calls
+ resolve their callee via `sonar.java.binaries` and have a null declaration too (see the
+ comment in `JavaLanguageSupport.isDetachableCall`, `:165-172`), so that predicate would drop
+ exactly the cross-file detections we must keep. There may be no clean intrinsic AST/symbol
+ signal separating a binary-resolved user class from a library class; the real discriminator
+ must be **pinned empirically** against the `crossfile/` fixtures (a characterization test)
+ before the filter body is written, and may end up coarser (e.g. a library-package check).
+ DEBUG-log skips.
+- **`engine/.../language/java/JavaDetectionEngine.java`** — gate at the **top of
+ `recordCall` (`:135`)**, i.e. *before* `isDetachableCall`/`buildDetachedCall`. Returning
+ early for library calls means they are neither recorded **nor** put through the expensive
+ translate + argument-snapshot in `buildDetachedCall` — a free assist to the C2 throughput
+ finding (that snapshot currently runs per root-rule per invocation).
+
+**Losslessness.** A library call cannot match any method hook (matcher requires a specific
+user-class owner). The single bounded edge — a user class that *overrides* a library method
+and is hooked via that override — is documented and DEBUG-logged. Everything else is a strict
+no-op change to detections.
+
+### Retention cap (Task 5) — build only if H1 says so
+
+If H1 shows the detached population is a material heap term:
+- Per-name-bucket cap **and** a global `invokedCallStack` cap, with sensible defaults,
+ overridable via a plugin property.
+- On overflow, stop recording new calls for that bucket and emit a **single** WARN naming the
+ method + cap, so the (bounded, measurable) detection loss is explicit.
+
+If H1 shows the call-stack is *not* a material term post-detach, defer the cap with a written
+note (the filter alone suffices, and adds no loss).
+
+## Components & data flow
+
+```
+recordCall (JavaDetectionEngine:135)
+ └─ isHookEligibleCall(invocation)? ← NEW gate (Task 1–2)
+ false → return (skip record + skip buildDetachedCall) [library call]
+ true → isDetachableCall? → buildDetachedCall (unchanged)
+ addRecordedCall → CallStackAgent.add
+ └─ (optional) cap check ← NEW (Task 5, conditional)
+```
+
+Reporting/attribution (H1) reads existing accessors: `callContextStats()`,
+`JavaAggregator.getDetectedNodes()`, hook repositories — no data-flow changes, read-only.
+
+## Testing
+
+- **Cross-file regression guard (reuse existing).** `CrossFileHookDetachTest` and
+ `IsDetachableCallTest` already exercise cross-file hook resolution and the
+ detach-eligibility predicate. Add a sibling assertion (or a focused test) proving a
+ cross-file detection whose call site is a **user** method still resolves *with the filter
+ on*, and that a purely-library call is correctly skipped. This is the guard CI otherwise
+ lacks (all rule tests are single-file).
+- **Filter unit coverage.** Table-style test of `isHookEligibleCall` on: library invocation
+ (false), user-declared invocation (true), enum access (true), the override edge (true,
+ documented).
+- **Regression.** `mvn test -pl engine` and `mvn test -pl java` stay green.
+- **Perf validation.** Re-run `CallStackHeapPerfTest` (`-Dtest=CallStackHeapPerfTest
+ -DexcludedGroups=`) and confirm detached counts drop by the library-call fraction; re-run
+ the Keycloak `jmap` attribution from H1 and record the floor delta.
+
+## Constraints
+
+- Java 17; changes confined to `engine` + Java language support + `java` test/perf + docs.
+- Apache 2.0 header in every new `.java` file. `mvn spotless:apply` before commit (restore
+ `JsonCipherSuites` if Spotless truncates it — known issue).
+- Keep the generic engine language-agnostic: eligibility goes through the language layer, not
+ into generic engine code. Python/Go remain on the `true` default.
+
+## Out of scope
+
+- `JavaAggregator.detectedNodes` dedup / incremental CBOM emission — H1 only decides whether
+ it earns its own spec.
+- C1 root pre-filtering and the other CPU/throughput items — separate "throughput track" spec.
+- Hooks-subscription pruning (H3) — only opened if H1 finds hooks material.
+
+## Sequencing
+
+1. H1 in-process counts + one-shot Keycloak `jmap` attribution → write the decision.
+2. H2 eligibility filter (Tasks 1–2) + cross-file/unit tests.
+3. H2 cap (Task 5) **iff** H1 said call-stack is material.
+4. Re-measure; record the floor delta.
diff --git a/docs/superpowers/specs/2026-07-06-callstack-heap-perf-harness-design.md b/docs/superpowers/specs/2026-07-06-callstack-heap-perf-harness-design.md
new file mode 100644
index 000000000..2117e8fb0
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-06-callstack-heap-perf-harness-design.md
@@ -0,0 +1,208 @@
+# Call-Stack Heap/Perf Harness — Design
+
+**Date:** 2026-07-06
+**Branch context:** `feat/callstack-ast-detach`
+**Status:** Approved (design), pending implementation plan.
+
+## Goal
+
+A single, **manual-on-demand** JUnit test that stresses the `CallStackAgent` call
+retention mechanism at scale and **deterministically asserts** that recorded calls get
+detached (per-file ASTs released) at `leaveFile` — the observable signature of the
+`feat/callstack-ast-detach` fix — while also **reporting** heap and wall-time for manual
+inspection.
+
+Constraints, from brainstorming:
+
+- **Self-contained JUnit** — no keycloak checkout, no docker/SonarQube, no network. The
+ corpus is generated in-process into a temp dir.
+- **Not keycloak** — a synthetic corpus of similar *shape* (cross-file crypto calls), with
+ scale as a tunable knob, standing in for a large real project.
+- **Types must resolve** — the heap term only appears when detections actually fire. A
+ source-only scan resolves nothing → `addCall` fires 0 times → the term is 0 (see
+ `docs/superpowers/plans/2026-07-05-callstack-hooks-heap-reduction.md`, "Measured"
+ section, and the `callstack-heap-term-measured` project memory). So the harness must
+ compile the corpus and put it on the semantic classpath, exactly as
+ `CrossFileHookDetachTest` does.
+- **Deterministic gate, no heap-threshold flake** — assert on a *structural* invariant
+ (how many recorded calls still pin a live AST after the scan), not on measured MB. Heap
+ MB is reported only, never asserted.
+- **Manual only** — `@Tag("performance")`, excluded from the default build. It does not
+ gate CI. It is run explicitly when validating a change.
+
+## Why this shape (context)
+
+The `CallStackAgent` records a `CallContext` per matched invocation for the whole scan so
+that a hook created in file B can resolve a call recorded in file A (cross-file detection).
+Before the detach work, every retained `CallContext` held a live sonar-java `Tree`, and any
+`Tree` pins its whole file's AST (parent chain → `CompilationUnitTree`), so the retained set
+pinned effectively the whole project's AST at once — measured at ~179k `CallContext`s /
+~7 GB on a near-full keycloak scan, growing linearly and unbounded.
+
+The fix (`feat/callstack-ast-detach`): at `leaveFile`, each retained call that is detachable
+is swapped for a tree-free `DetachedCall` (`CallStackAgent.detachCallsForFile`), so the
+file's AST becomes GC-eligible while cross-file matching continues from an AST-free snapshot.
+
+This harness proves that mechanism works at scale without needing the full keycloak route.
+It does **not** try to reproduce the literal 7 GB number; that remains the documented manual
+`mvn sonar:sonar` measurement (pointer kept in the test's javadoc).
+
+## Components
+
+### 1. `CryptoCorpusGenerator` (test helper)
+
+Programmatically writes `N` `.java` source files into a temp dir. It emits the exact pattern
+the retention mechanism keys on — a cross-file wrapper/caller shape mirroring the
+`CrossFileHookDetachTest` fixtures (`KeyGeneratorWrapper` / `KeyGeneratorCaller`) — not flat
+single-file crypto calls, because:
+
+- Cross-file wrapper calls are what create **method hooks** (user method with a source
+ declaration) and cause calls to be **recorded and later replayed** — the code path that
+ accumulates `CallContext`s.
+- **Distinct** class/method names per unit keep call sites distinct so retention grows with
+ corpus size (a flat corpus with one repeated call site would dedup to ~nothing and not
+ stress the term).
+
+Per generated "unit" (parameterized, repeated `N` times with unique names):
+
+- A **wrapper** class exposing a crypto factory method that internally calls a resolvable JCA
+ API (`Cipher.getInstance` / `KeyGenerator.getInstance` / `MessageDigest.getInstance`,
+ rotated across units so multiple rules fire).
+- A **caller** class that invokes the wrapper across the file boundary with:
+ - a **string literal** argument (→ detachable),
+ - a **field-constant** argument (→ detachable),
+ - a **`new byte[]`** argument (→ retained; stays on the tree path by design — this is the
+ known non-detachable case).
+
+Scale knob: `-Dperf.corpus.files` (integer, default small — see Open Parameters). "Files"
+counts source files; each unit is 2 files (wrapper + caller), so units = files / 2.
+
+The generator returns the list of generated file paths (for `onFiles`) so the test does not
+hard-code fixture names.
+
+### 2. Driver (the test)
+
+`CallStackHeapPerfTest extends TestBase`, `@Tag("performance")`. Reuses
+`CrossFileHookDetachTest`'s proven driving path verbatim, at scale:
+
+1. Generate the corpus (component 1) into a temp dir.
+2. Compile all generated sources to a classpath output dir via
+ `ToolProvider.getSystemJavaCompiler` (same helper shape as
+ `CrossFileHookDetachTest.compileToClasspath`).
+3. `CheckVerifier.newVerifier().onFiles(allGeneratedFiles).withClassPath(List.of(classes))
+ .withChecks(this).verifyIssues()` — compiling + classpath is what makes the callee types
+ resolve at the call sites so cross-file detections fire and `addCall` runs.
+
+`verifyIssues()` is used (not a bare scan) to stay on the exact, supported CheckVerifier code
+path the rest of the suite uses; the harness does not assert specific issue lines (the
+corpus is generated, so issue positions are not hand-authored). The perf assertions come
+from the call-context stats, not from CheckVerifier issue matching.
+
+### 3. Inspection accessor (small production addition)
+
+`CallStackAgent.invokedCallStack` is `private` with no accessor. Add a minimal read-only
+introspection method rather than using reflection (clearer, and legitimate test-support
+surface):
+
+- `CallStackAgent`: add a `CallContextStats callContextStats()` that walks
+ `invokedCallStack` once and returns counts:
+ - `retainedWithTree` — `RetainedCall` entries whose `tree() != null` (i.e. still pinning an
+ AST),
+ - `detached` — `DetachedCall` entries,
+ - `total`, `buckets`.
+- `CallContextStats` — a small immutable value type (record) in
+ `com.ibm.engine.callstack`.
+- Thread the accessor out so the test can reach it after the scan:
+ `CallStackAgent.callContextStats()` → `Handler.callContextStats()` →
+ `ILanguageSupport` (a `callContextStats()` method) → reachable from the test via
+ `JavaAggregator.getLanguageSupport()`.
+
+This is production code but purely additive and read-only; it computes on demand and retains
+nothing.
+
+### 4. Metrics + report
+
+After the scan completes (all files have been left, so detach has run for every file):
+
+**ASSERT — deterministic gate (the point of the test):**
+
+- `retainedWithTree <= bound`, where `bound` accounts only for the intentionally-retained
+ `new byte[]` cases plus any non-detachable calls (i.e. roughly proportional to units, not
+ to total recorded calls). The precise bound formula is derived during implementation from
+ the generator's known unit count and validated empirically (see "Validating the harness").
+- `detachedRatio = detached / (detached + retainedWithTree) >= threshold` (a high ratio,
+ e.g. most recorded calls detached). Exact threshold pinned during implementation.
+
+Both are pure counts of object variants in `invokedCallStack` after the scan — no GC, no
+timing, no MB. They fail iff detach did not happen (AST pinning reintroduced).
+
+**REPORT — never asserted (manual-inspection view):**
+
+- `System.gc()` (best-effort) then `MemoryMXBean` heap-used delta across the scan.
+- Wall-clock time for the scan phase.
+- Raw `CallContextStats` (`retainedWithTree`, `detached`, `total`, `buckets`) and the corpus
+ size (`files`, `units`).
+
+Printed to stdout in a single clearly-labelled block so a human can compare runs across
+branches. No assertion references these values.
+
+## Build configuration
+
+Add `performance` to the `maven-surefire-plugin`
+configuration in the parent `pom.xml` (currently declared with no ``). Effect:
+
+- `mvn test` / `mvn package` — skips the `performance`-tagged test (CI unaffected).
+- `mvn test -Dgroups=performance -pl java` — runs it.
+
+## Placement
+
+- `java/src/test/java/com/ibm/plugin/perf/CallStackHeapPerfTest.java`
+- `java/src/test/java/com/ibm/plugin/perf/CryptoCorpusGenerator.java`
+
+The `java` module is required because the corpus uses JCA/BouncyCastle APIs (must be on the
+test classpath to resolve) and the test uses sonar-java `CheckVerifier`.
+
+## Data flow
+
+```
+CryptoCorpusGenerator.generate(N) -> temp dir of .java (wrapper+caller units)
+ -> compileToClasspath(sources) -> classes dir
+ -> CheckVerifier.onFiles(...).withClassPath(classes).withChecks(this).verifyIssues()
+ -> engine records CallContexts (RetainedCall) as detections fire
+ -> at each leaveFile, detachCallsForFile swaps detachable calls -> DetachedCall
+ -> JavaAggregator.getLanguageSupport().callContextStats()
+ -> ASSERT retainedWithTree <= bound, detachedRatio >= threshold
+ -> REPORT heap delta, time, raw counts (stdout, not asserted)
+```
+
+## Validating the harness itself
+
+The structural assertion is only worth committing if it actually discriminates:
+
+1. **Passes on `feat/callstack-ast-detach`** — with detach live, `retainedWithTree` stays
+ bounded and `detachedRatio` is high.
+2. **Would fail if detach were disabled** — during development only, temporarily neutralize
+ `CallStackAgent.detachCallsForFile` (make it a no-op) and confirm the test **fails**
+ (`retainedWithTree` grows with corpus size). This neutralization is a local sanity check,
+ **not committed**.
+
+Both are recorded as explicit implementation steps in the plan.
+
+## Out of scope
+
+- Reproducing the literal ~7 GB keycloak number — remains the documented manual
+ `mvn sonar:sonar` route; the test's javadoc points to
+ `docs/superpowers/plans/2026-07-05-callstack-hooks-heap-reduction.md` for that.
+- Any assertion on measured heap MB (report-only, to avoid machine/GC flake).
+- Python and Go corpora — Java-only, where the term was measured and where the detach fix
+ lives.
+- Automating docker/SonarQube end-to-end.
+
+## Open parameters (pinned during implementation)
+
+- Default `perf.corpus.files` (small enough for a few-seconds manual run, large enough to
+ make retention visible — candidate ~200).
+- Exact `retainedWithTree` bound formula and `detachedRatio` threshold (derived from the
+ generator's unit count and confirmed empirically in the harness-validation step).
+- Which JCA APIs to rotate across units (at least `Cipher`, `KeyGenerator`, `MessageDigest`
+ — all already covered by existing Java detection rules).
diff --git a/engine/src/main/java/com/ibm/engine/callstack/ArgSnapshot.java b/engine/src/main/java/com/ibm/engine/callstack/ArgSnapshot.java
new file mode 100644
index 000000000..733576f4b
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/ArgSnapshot.java
@@ -0,0 +1,34 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import java.util.List;
+import javax.annotation.Nonnull;
+
+/**
+ * Tree-free snapshot of one argument of a detached recorded call: the value(s) it resolved to at
+ * record time (while the file was still live) plus, for each, an AST-free location to report on.
+ */
+public record ArgSnapshot(int index, @Nonnull List values) {
+
+ /** A single resolved value plus its detached location. */
+ public record ResolvedSnapshotValue(
+ @Nonnull Object value, @Nonnull DetachedSyntaxToken location) {}
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/CallContext.java b/engine/src/main/java/com/ibm/engine/callstack/CallContext.java
index 713cc0169..8534977f9 100644
--- a/engine/src/main/java/com/ibm/engine/callstack/CallContext.java
+++ b/engine/src/main/java/com/ibm/engine/callstack/CallContext.java
@@ -21,5 +21,21 @@
import com.ibm.engine.language.IScanContext;
import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
-public record CallContext(@Nonnull T tree, @Nonnull IScanContext publisher) {}
+/**
+ * A recorded call site accumulated by the {@link CallStackAgent} for later cross-file hook
+ * matching.
+ *
+ * {@link RetainedCall} keeps the live AST tree (today's behavior); {@link DetachedCall} holds a
+ * tree-free snapshot so the file's AST can be garbage-collected after analysis.
+ */
+public sealed interface CallContext permits RetainedCall, DetachedCall {
+
+ /** The recorded call tree, or {@code null} for a detached record that holds no AST. */
+ @Nullable T tree();
+
+ /** The scan context of the file the call was recorded in. */
+ @Nonnull
+ IScanContext publisher();
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/CallContextStats.java b/engine/src/main/java/com/ibm/engine/callstack/CallContextStats.java
new file mode 100644
index 000000000..77c8f45af
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/CallContextStats.java
@@ -0,0 +1,63 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2026 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import java.util.Collection;
+import java.util.List;
+import javax.annotation.Nonnull;
+
+/**
+ * Immutable snapshot of the {@link CallStackAgent}'s recorded-call population, used by the
+ * performance/heap harness to assert that calls were detached (ASTs released) at {@code leaveFile}.
+ *
+ * @param retainedWithTree number of {@link RetainedCall}s still pinning a live AST tree
+ * @param detached number of tree-free {@link DetachedCall}s
+ * @param total {@code retainedWithTree + detached}
+ * @param buckets number of hash buckets in the call stack
+ */
+public record CallContextStats(int retainedWithTree, int detached, int total, int buckets) {
+
+ /** A zero-valued snapshot (used as the language-agnostic default). */
+ public static final CallContextStats EMPTY = new CallContextStats(0, 0, 0, 0);
+
+ /** Fraction of recorded calls that are detached; {@code 1.0} when nothing was recorded. */
+ public double detachedRatio() {
+ return total == 0 ? 1.0d : (double) detached / (double) total;
+ }
+
+ /** Counts retained-with-tree vs. detached calls across all call-stack buckets. */
+ @Nonnull
+ public static CallContextStats from(
+ @Nonnull Collection>> buckets) {
+ int retainedWithTree = 0;
+ int detached = 0;
+ for (List> bucket : buckets) {
+ for (CallContext call : bucket) {
+ if (call instanceof DetachedCall) {
+ detached++;
+ } else if (call instanceof RetainedCall retained && retained.tree() != null) {
+ retainedWithTree++;
+ }
+ }
+ }
+ return new CallContextStats(
+ retainedWithTree, detached, retainedWithTree + detached, buckets.size());
+ }
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/CallStackAgent.java b/engine/src/main/java/com/ibm/engine/callstack/CallStackAgent.java
index 2a8a0121e..42ded8e7a 100644
--- a/engine/src/main/java/com/ibm/engine/callstack/CallStackAgent.java
+++ b/engine/src/main/java/com/ibm/engine/callstack/CallStackAgent.java
@@ -27,13 +27,14 @@
import com.ibm.engine.language.ILanguageSupport;
import com.ibm.engine.language.IScanContext;
import java.util.ArrayList;
+import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Optional;
-import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import javax.annotation.Nonnull;
+import org.sonar.api.batch.fs.InputFile;
public class CallStackAgent
implements INotifyWhenNewCallWasAddedOntoTheCallStack,
@@ -42,7 +43,6 @@ public class CallStackAgent
private final ConcurrentMap>> invokedCallStack =
new ConcurrentHashMap<>();
- @Nonnull private final Set visitedTreeObjects = ConcurrentHashMap.newKeySet();
@Nonnull private final List>> listeners = new ArrayList<>();
@Nonnull private final ILanguageSupport languageSupport;
@@ -51,18 +51,54 @@ public CallStackAgent(@Nonnull ILanguageSupport languageSupport) {
}
public void addCall(@Nonnull T tree, @Nonnull IScanContext scanContext) {
- Optional keyOptional = getKeyFormT(tree);
+ add(new RetainedCall<>(tree, scanContext, null));
+ }
+
+ /**
+ * Detaches the just-analyzed file's still-retained calls: each {@link RetainedCall} for {@code
+ * inputFile} that carries a pre-built {@link RetainedCall#detachedForm()} is replaced by that
+ * tree-free form, so the file's AST becomes garbage-collectable while cross-file matching
+ * continues from the snapshot. Same-file detections have already fired (with the live context)
+ * before this runs, so their SonarQube issues are unaffected.
+ */
+ public void detachCallsForFile(@Nonnull InputFile inputFile) {
+ for (List> bucket : invokedCallStack.values()) {
+ for (int i = 0; i < bucket.size(); i++) {
+ if (bucket.get(i) instanceof RetainedCall retained
+ && retained.detachedForm() != null
+ && inputFile.equals(retained.publisher().getInputFile())) {
+ bucket.set(i, retained.detachedForm());
+ }
+ }
+ }
+ }
+
+ /** Read-only snapshot of the recorded-call population (retained-with-tree vs. detached). */
+ @Nonnull
+ public CallContextStats callContextStats() {
+ return CallContextStats.from(invokedCallStack.values());
+ }
+
+ /** Records a call (retained or detached) and notifies live hook subscriptions. */
+ public void add(@Nonnull CallContext callContext) {
+ final Optional keyOptional = keyOf(callContext);
if (keyOptional.isEmpty()) {
return;
}
-
- int key = keyOptional.get();
- final CallContext callContext = new CallContext<>(tree, scanContext);
- if (addedToCallContext(key, callContext)) {
+ if (addedToCallContext(keyOptional.get(), callContext)) {
this.notify(callContext);
}
}
+ @Nonnull
+ private Optional keyOf(@Nonnull CallContext callContext) {
+ if (callContext instanceof DetachedCall detached) {
+ return Optional.of(detached.methodName().hashCode());
+ }
+ final T tree = callContext.tree();
+ return tree == null ? Optional.empty() : getKeyFormT(tree);
+ }
+
@Override
public void subscribe(@Nonnull IObserver> listener) {
listeners.add(listener);
@@ -98,14 +134,13 @@ public void onNewHookSubscription(
}
final List> stackCalls = new ArrayList<>();
- final Iterator>> iterator = invokedCallStack.values().iterator();
+ final Iterator>> iterator = bucketsToScan(methodMatcher).iterator();
while (iterator.hasNext()) {
final List> callContexts = iterator.next();
final Iterator> callContextIterator = callContexts.iterator();
while (callContextIterator.hasNext()) {
final CallContext callContext = callContextIterator.next();
- if (methodMatcher.match(
- callContext.tree(), languageSupport.translation(), hook.matchContext())) {
+ if (matches(methodMatcher, callContext, hook)) {
stackCalls.add(callContext);
}
}
@@ -120,24 +155,56 @@ public void onNewHookSubscription(
}
}
- private boolean addedToCallContext(int key, @Nonnull CallContext callContext) {
- if (visitedTreeObjects.contains(callContext.tree())) {
- return false;
+ /**
+ * The call-stack buckets a hook's matcher could match. Recorded calls are keyed by their
+ * invoked method name's hash, so a single-name matcher only needs that one bucket; {@code
+ * ANY}/multi-name matchers fall back to scanning every bucket.
+ */
+ @Nonnull
+ private Collection>> bucketsToScan(
+ @Nonnull MethodMatcher methodMatcher) {
+ final List methodNames = methodMatcher.getMethodNamesSerializable();
+ if (methodNames.size() == 1 && !MethodMatcher.ANY.equals(methodNames.get(0))) {
+ final List> bucket =
+ invokedCallStack.get(methodNames.get(0).hashCode());
+ return bucket == null ? List.of() : List.of(bucket);
}
- visitedTreeObjects.add(callContext.tree());
+ return invokedCallStack.values();
+ }
+
+ private boolean matches(
+ @Nonnull MethodMatcher methodMatcher,
+ @Nonnull CallContext callContext,
+ @Nonnull IHook hook) {
+ if (callContext instanceof DetachedCall detached) {
+ return methodMatcher.matchKeys(
+ detached.invokedObjectType(), detached.methodName(), detached.parameterTypes());
+ }
+ final T tree = callContext.tree();
+ return tree != null
+ && methodMatcher.match(tree, languageSupport.translation(), hook.matchContext());
+ }
+
+ private boolean addedToCallContext(int key, @Nonnull CallContext callContext) {
+ final T tree = callContext.tree();
+ final boolean[] added = {true};
invokedCallStack.compute(
key,
(k, v) -> {
- if (v == null) {
- final ArrayList> callContexts = new ArrayList<>();
- callContexts.add(callContext);
- return callContexts;
- } else {
- v.add(callContext);
- return v;
+ final List> callContexts =
+ (v == null) ? new ArrayList<>() : v;
+ if (tree != null) {
+ for (CallContext existing : callContexts) {
+ if (tree.equals(existing.tree())) {
+ added[0] = false;
+ return callContexts;
+ }
+ }
}
+ callContexts.add(callContext);
+ return callContexts;
});
- return true;
+ return added[0];
}
@Nonnull
diff --git a/engine/src/main/java/com/ibm/engine/callstack/DetachedCall.java b/engine/src/main/java/com/ibm/engine/callstack/DetachedCall.java
new file mode 100644
index 000000000..cc8894c2d
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/DetachedCall.java
@@ -0,0 +1,53 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import com.ibm.engine.detection.IType;
+import com.ibm.engine.language.IScanContext;
+import java.util.List;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * A recorded call stored tree-free: the match keys and pre-resolved argument snapshots are captured
+ * at record time while the file is live, so the file's AST becomes garbage-collectable afterwards.
+ *
+ * Matching uses {@link #invokedObjectType()} / {@link #methodName()} / {@link #parameterTypes()}
+ * via {@code MethodMatcher.matchKeys}; hook replay reads {@link #arguments()}.
+ */
+public record DetachedCall(
+ @Nonnull IType invokedObjectType,
+ @Nonnull String methodName,
+ @Nonnull List parameterTypes,
+ @Nonnull List arguments,
+ @Nonnull DetachedScanContext detachedPublisher)
+ implements CallContext {
+
+ @Nullable @Override
+ public T tree() {
+ return null;
+ }
+
+ @Nonnull
+ @Override
+ public IScanContext publisher() {
+ return detachedPublisher;
+ }
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/DetachedScanContext.java b/engine/src/main/java/com/ibm/engine/callstack/DetachedScanContext.java
new file mode 100644
index 000000000..b533e233f
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/DetachedScanContext.java
@@ -0,0 +1,69 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import com.ibm.engine.language.IScanContext;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.sonar.api.batch.fs.InputFile;
+
+/**
+ * AST-free {@link IScanContext}: retains only the file handle, path and a non-AST-pinning issue
+ * reporter captured at record time, never the language-specific file scanner context (e.g. {@code
+ * JavaFileScannerContext}, which holds the compilation unit). A detached recorded call carries this
+ * so that replaying it does not pin the file's AST while still supporting CBOM translation and
+ * cross-file SonarQube issue reporting.
+ *
+ * {@link #reportIssue} raises the issue through {@link #issueReporter} when the location is a
+ * {@link DetachedSyntaxToken}; if no reporter is available it logs and skips (the CBOM node is
+ * still produced via translation).
+ */
+public record DetachedScanContext(
+ @Nonnull InputFile inputFile,
+ @Nonnull String filePath,
+ @Nullable IDetachedIssueReporter issueReporter)
+ implements IScanContext {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(DetachedScanContext.class);
+
+ @Override
+ public void reportIssue(@Nonnull R currentRule, @Nonnull T tree, @Nonnull String message) {
+ if (issueReporter != null && tree instanceof DetachedSyntaxToken location) {
+ issueReporter.report(currentRule, location, message);
+ return;
+ }
+ LOGGER.debug(
+ "Skipping issue on detached cross-file detection in {}: {}", filePath, message);
+ }
+
+ @Nonnull
+ @Override
+ public InputFile getInputFile() {
+ return inputFile;
+ }
+
+ @Nonnull
+ @Override
+ public String getFilePath() {
+ return filePath;
+ }
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/DetachedSyntaxToken.java b/engine/src/main/java/com/ibm/engine/callstack/DetachedSyntaxToken.java
new file mode 100644
index 000000000..913dcab62
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/DetachedSyntaxToken.java
@@ -0,0 +1,172 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import java.util.List;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import org.sonar.plugins.java.api.location.Position;
+import org.sonar.plugins.java.api.location.Range;
+import org.sonar.plugins.java.api.tree.SyntaxToken;
+import org.sonar.plugins.java.api.tree.SyntaxTrivia;
+import org.sonar.plugins.java.api.tree.Tree;
+import org.sonar.plugins.java.api.tree.TreeVisitor;
+
+/**
+ * AST-free {@link SyntaxToken} used as the location of a detached cross-file detection value.
+ *
+ * It holds only primitives captured at record time, so it never pins a compilation unit ({@link
+ * #parent()} is {@code null}). The Java translator reads {@link #line()}, {@link #offset()} and
+ * {@link #keywords()} from it directly to build a {@code DetectionLocation} without touching a live
+ * tree. Column offsets are stored 0-based (matching {@link Position#columnOffset()}); {@link
+ * Position#at(int, int)} takes a 1-based column, so {@link #range()} adds one.
+ */
+public final class DetachedSyntaxToken implements SyntaxToken {
+
+ private final int line;
+ private final int columnOffset;
+ private final int endLine;
+ private final int endColumnOffset;
+ @Nonnull private final String text;
+ @Nonnull private final List keywords;
+
+ public DetachedSyntaxToken(
+ int line,
+ int columnOffset,
+ int endLine,
+ int endColumnOffset,
+ @Nonnull String text,
+ @Nonnull List keywords) {
+ this.line = line;
+ this.columnOffset = columnOffset;
+ this.endLine = endLine;
+ this.endColumnOffset = endColumnOffset;
+ this.text = text;
+ this.keywords = List.copyOf(keywords);
+ }
+
+ @Nonnull
+ public List keywords() {
+ return keywords;
+ }
+
+ /** 0-based start column offset, matching {@code DetectionLocation}'s offset field. */
+ public int offset() {
+ return columnOffset;
+ }
+
+ /** 1-based end line of the captured range. */
+ public int endLine() {
+ return endLine;
+ }
+
+ /** 0-based end column offset of the captured range. */
+ public int endOffset() {
+ return endColumnOffset;
+ }
+
+ @Override
+ public String text() {
+ return text;
+ }
+
+ @Override
+ public List trivias() {
+ return List.of();
+ }
+
+ @Override
+ public int line() {
+ return line;
+ }
+
+ @Override
+ public int column() {
+ return columnOffset;
+ }
+
+ @Override
+ public Range range() {
+ return Range.at(
+ Position.at(line, columnOffset + 1), Position.at(endLine, endColumnOffset + 1));
+ }
+
+ @Override
+ public boolean is(Tree.Kind... kinds) {
+ for (Tree.Kind kind : kinds) {
+ if (kind == Tree.Kind.TOKEN) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ @Override
+ public void accept(TreeVisitor visitor) {
+ // Detached: not part of an AST, nothing to traverse.
+ }
+
+ @Nullable @Override
+ public Tree parent() {
+ return null;
+ }
+
+ @Override
+ public SyntaxToken firstToken() {
+ return this;
+ }
+
+ @Override
+ public SyntaxToken lastToken() {
+ return this;
+ }
+
+ @Override
+ public Tree.Kind kind() {
+ return Tree.Kind.TOKEN;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) {
+ return true;
+ }
+ if (!(o instanceof DetachedSyntaxToken that)) {
+ return false;
+ }
+ return line == that.line
+ && columnOffset == that.columnOffset
+ && endLine == that.endLine
+ && endColumnOffset == that.endColumnOffset
+ && text.equals(that.text)
+ && keywords.equals(that.keywords);
+ }
+
+ @Override
+ public int hashCode() {
+ int result = line;
+ result = 31 * result + columnOffset;
+ result = 31 * result + endLine;
+ result = 31 * result + endColumnOffset;
+ result = 31 * result + text.hashCode();
+ result = 31 * result + keywords.hashCode();
+ return result;
+ }
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/IDetachedIssueReporter.java b/engine/src/main/java/com/ibm/engine/callstack/IDetachedIssueReporter.java
new file mode 100644
index 000000000..f3e30a70b
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/IDetachedIssueReporter.java
@@ -0,0 +1,36 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Raises a SonarQube issue for a detached (tree-free) cross-file detection, at the location
+ * captured in the {@link DetachedSyntaxToken}. Implemented per language over a shared,
+ * non-AST-pinning reporting channel (for Java, {@code SonarComponents} + the file's {@code
+ * InputFile}), so a detached record can report an issue without retaining the file's AST.
+ *
+ * @param the language's rule/check type
+ */
+@FunctionalInterface
+public interface IDetachedIssueReporter {
+
+ void report(@Nonnull R rule, @Nonnull DetachedSyntaxToken location, @Nonnull String message);
+}
diff --git a/engine/src/main/java/com/ibm/engine/callstack/RetainedCall.java b/engine/src/main/java/com/ibm/engine/callstack/RetainedCall.java
new file mode 100644
index 000000000..ac408a250
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/callstack/RetainedCall.java
@@ -0,0 +1,40 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.callstack;
+
+import com.ibm.engine.language.IScanContext;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * A recorded call that retains its live AST tree and scan context — today's behavior. While the
+ * call's file is being analyzed, this form is used so same-file hook detections resolve and report
+ * SonarQube issues through the live context.
+ *
+ * If the call is detachable, {@link #detachedForm} carries a pre-built tree-free {@link
+ * DetachedCall} (its arguments resolved at record time). When the call's file finishes analysis,
+ * the {@link CallStackAgent} swaps this entry for {@link #detachedForm}, dropping the tree so the
+ * file's AST becomes garbage-collectable while cross-file matching continues from the snapshot.
+ */
+public record RetainedCall(
+ @Nonnull T tree,
+ @Nonnull IScanContext publisher,
+ @Nullable DetachedCall detachedForm)
+ implements CallContext {}
diff --git a/engine/src/main/java/com/ibm/engine/detection/DetectionStore.java b/engine/src/main/java/com/ibm/engine/detection/DetectionStore.java
index 7cac4e199..1b0e703c2 100644
--- a/engine/src/main/java/com/ibm/engine/detection/DetectionStore.java
+++ b/engine/src/main/java/com/ibm/engine/detection/DetectionStore.java
@@ -19,6 +19,7 @@
*/
package com.ibm.engine.detection;
+import com.ibm.engine.callstack.CallContext;
import com.ibm.engine.executive.IStatusReporting;
import com.ibm.engine.hooks.IHook;
import com.ibm.engine.hooks.IHookDetectionObserver;
@@ -397,22 +398,20 @@ public void onNewHookRegistration(@Nonnull IHook hook) {
@Override
public void onHookInvocation(
- @Nonnull T invocationTree,
- @Nonnull IHook hook,
- @Nonnull IScanContext scanContext) {
+ @Nonnull CallContext callContext, @Nonnull IHook hook) {
final DetectionStoreWithHook newDetectionStore =
new DetectionStoreWithHook<>(
level + 1,
detectionRule,
- scanContext,
+ callContext.publisher(),
handler,
statusReporting,
- invocationTree);
+ callContext);
if (hook instanceof IMethodInvocationHook methodInvocationHook) {
this.attach(methodInvocationHook.getParameter().getIndex(), newDetectionStore);
}
// TODO: Enum Hook
- newDetectionStore.onHookInvocation(invocationTree, hook);
+ newDetectionStore.onHookInvocation(hook);
}
@Override
diff --git a/engine/src/main/java/com/ibm/engine/detection/DetectionStoreWithHook.java b/engine/src/main/java/com/ibm/engine/detection/DetectionStoreWithHook.java
index 6414d0b44..6dcb53ec4 100644
--- a/engine/src/main/java/com/ibm/engine/detection/DetectionStoreWithHook.java
+++ b/engine/src/main/java/com/ibm/engine/detection/DetectionStoreWithHook.java
@@ -19,6 +19,9 @@
*/
package com.ibm.engine.detection;
+import com.ibm.engine.callstack.ArgSnapshot;
+import com.ibm.engine.callstack.CallContext;
+import com.ibm.engine.callstack.DetachedCall;
import com.ibm.engine.executive.IStatusReporting;
import com.ibm.engine.hooks.*;
import com.ibm.engine.language.IScanContext;
@@ -31,7 +34,7 @@
public final class DetectionStoreWithHook extends DetectionStore {
@Nonnull private final DetectionStoreWithHook hookRootDetectionStore;
- @Nonnull private final T invocationTree;
+ @Nonnull private final CallContext callContext;
public DetectionStoreWithHook(
final int level,
@@ -39,16 +42,16 @@ public DetectionStoreWithHook(
@Nonnull final IScanContext scanContext,
@Nonnull final Handler handler,
@Nonnull final IStatusReporting statusReporting,
- @Nonnull final T invocationTree) {
+ @Nonnull final CallContext callContext) {
super(level, detectionRule, scanContext, handler, statusReporting);
- this.invocationTree = invocationTree;
+ this.callContext = callContext;
this.hookRootDetectionStore = this;
}
public DetectionStoreWithHook(
final int level,
@Nonnull final IDetectionRule detectionRule,
- @Nonnull final T invocationTree,
+ @Nonnull final CallContext callContext,
@Nonnull final DetectionStoreWithHook hookRootDetectionStore) {
super(
level,
@@ -56,17 +59,16 @@ public DetectionStoreWithHook(
hookRootDetectionStore.scanContext,
hookRootDetectionStore.handler,
hookRootDetectionStore.statusReporting);
- this.invocationTree = invocationTree;
+ this.callContext = callContext;
this.hookRootDetectionStore = hookRootDetectionStore;
}
- public void onHookInvocation(
- @Nonnull final T invocationTree, @Nonnull final IHook hook) {
- onHookInvocation(invocationTree, hook, false);
+ public void onHookInvocation(@Nonnull final IHook hook) {
+ onHookInvocation(hook, false);
}
public void onSuccessiveHook(@Nonnull final IHook hook) {
- if (!hook.isInvocationOn(invocationTree, handler.getLanguageSupport())) {
+ if (!hook.isInvocationOn(callContext, handler.getLanguageSupport())) {
// Add a hook to the hook repository
if (handler.addHookToHookRepository(hook)) {
/*
@@ -76,20 +78,17 @@ public void onSuccessiveHook(@Nonnull final IHook hook) {
handler.subscribeToHookDetectionObservable(hook, hookRootDetectionStore);
}
} else {
- onHookInvocation(invocationTree, hook, true);
+ onHookInvocation(hook, true);
}
}
- private void onHookInvocation(
- @Nonnull final T invocationTree,
- @Nonnull final IHook hook,
- boolean isSuccessive) {
+ private void onHookInvocation(@Nonnull final IHook hook, boolean isSuccessive) {
if (hook
instanceof
MethodInvocationHookWithParameterResolvement
methodInvocationHookWithParameterResolvement) {
handleMethodInvocationHookWithParameterResolvement(
- invocationTree, methodInvocationHookWithParameterResolvement, isSuccessive);
+ methodInvocationHookWithParameterResolvement, isSuccessive);
} else if (hook
instanceof
MethodInvocationHookWithReturnResolvement
@@ -97,7 +96,7 @@ private void onHookInvocation(
handleMethodInvocationHookWithReturnResolvement(
methodInvocationHookWithReturnResolvement, isSuccessive);
} else if (hook instanceof EnumHook enumHook) {
- handleEnumHook(invocationTree, enumHook);
+ handleEnumHook(callContext.tree(), enumHook);
}
}
@@ -122,11 +121,19 @@ private void handleMethodInvocationHookWithReturnResolvement(
}
private void handleMethodInvocationHookWithParameterResolvement(
- @Nonnull final T methodInvocation,
@Nonnull
final MethodInvocationHookWithParameterResolvement
methodInvocationHookWithParameterResolvement,
boolean isSuccessive) {
+ if (callContext instanceof DetachedCall detachedCall) {
+ replayDetachedParameterHook(
+ detachedCall, methodInvocationHookWithParameterResolvement, isSuccessive);
+ return;
+ }
+ final T methodInvocation = callContext.tree();
+ if (methodInvocation == null) {
+ return;
+ }
final IDetectionEngine detectionEngine =
handler.getLanguageSupport().createDetectionEngineInstance(hookRootDetectionStore);
final T argument =
@@ -202,6 +209,37 @@ private void handleMethodInvocationHookWithParameterResolvement(
isSuccessive);
}
+ /**
+ * Fire-time replay for a {@link DetachedCall}: the argument was already resolved at record
+ * time, so we skip {@code extractArgumentFromMethodCaller}/{@code resolveValuesInInnerScope}
+ * and feed the pre-resolved snapshot (with its {@code DetachedSyntaxToken} location) straight
+ * to the hook's value factory. (Java parameter hooks never set {@code expressionToResolve}, so
+ * the cross-boundary path is not needed here.)
+ */
+ private void replayDetachedParameterHook(
+ @Nonnull final DetachedCall detachedCall,
+ @Nonnull final MethodInvocationHookWithParameterResolvement hook,
+ boolean isSuccessive) {
+ final int index =
+ handler.getLanguageSupport()
+ .parameterIndexOf(hook.methodDefinition(), hook.methodParameter());
+ if (index >= 0
+ && index < detachedCall.arguments().size()
+ && hook.getParameter() instanceof DetectableParameter detectableParameter) {
+ for (ArgSnapshot.ResolvedSnapshotValue snapshot :
+ detachedCall.arguments().get(index).values()) {
+ @SuppressWarnings("unchecked")
+ final T location = (T) snapshot.location();
+ final ResolvedValue resolvedValue =
+ new ResolvedValue<>(snapshot.value(), location);
+ new ValueDetection<>(resolvedValue, detectableParameter, location, null)
+ .toValue(detectableParameter.getiValueFactory())
+ .ifPresent(iValue -> addValue(detectableParameter.getIndex(), iValue));
+ }
+ }
+ handleNextRulesForMethodHooks(hook, null, isSuccessive);
+ }
+
private void handleNextRulesForMethodHooks(
@Nonnull final IMethodInvocationHook hook,
@Nullable final TraceSymbol traceSymbolForParameter,
@@ -215,7 +253,7 @@ private void handleNextRulesForMethodHooks(
new DetectionStoreWithHook<>(
level + 1,
iDetectionRule,
- invocationTree,
+ callContext,
hookRootDetectionStore))
.forEach(
newDetectionStore -> {
@@ -239,7 +277,7 @@ private void handleNextRulesForMethodHooks(
new DetectionStoreWithHook<>(
level + 1,
iDetectionRule,
- invocationTree,
+ callContext,
hookRootDetectionStore))
.forEach(
newDetectionStore -> {
diff --git a/engine/src/main/java/com/ibm/engine/detection/Handler.java b/engine/src/main/java/com/ibm/engine/detection/Handler.java
index 045a5ae05..015464960 100644
--- a/engine/src/main/java/com/ibm/engine/detection/Handler.java
+++ b/engine/src/main/java/com/ibm/engine/detection/Handler.java
@@ -21,6 +21,7 @@
import com.ibm.common.IObserver;
import com.ibm.engine.callstack.CallContext;
+import com.ibm.engine.callstack.CallContextStats;
import com.ibm.engine.callstack.CallStackAgent;
import com.ibm.engine.hooks.HookDetectionObservable;
import com.ibm.engine.hooks.HookRepository;
@@ -29,6 +30,7 @@
import com.ibm.engine.language.ILanguageSupport;
import com.ibm.engine.language.IScanContext;
import javax.annotation.Nonnull;
+import org.sonar.api.batch.fs.InputFile;
public class Handler {
@Nonnull private final ILanguageSupport languageSupport;
@@ -77,10 +79,21 @@ public void unsubscribeFormHookDetectionObservable(
}
public void notifyAllHookDetectionObservers(
- @Nonnull T invocationTree,
- @Nonnull IHook hook,
- @Nonnull IScanContext scanContext) {
- this.hookDetectionObservable.notify(invocationTree, hook, scanContext);
+ @Nonnull CallContext callContext, @Nonnull IHook hook) {
+ this.hookDetectionObservable.notify(callContext, hook);
+ }
+
+ public void addRecordedCall(@Nonnull CallContext recordedCall) {
+ this.callStackAgent.add(recordedCall);
+ }
+
+ public void detachCallsForFile(@Nonnull InputFile inputFile) {
+ this.callStackAgent.detachCallsForFile(inputFile);
+ }
+
+ @Nonnull
+ public CallContextStats callContextStats() {
+ return this.callStackAgent.callContextStats();
}
public void subscribeToCallStackAgent(@Nonnull IObserver> listener) {
diff --git a/engine/src/main/java/com/ibm/engine/detection/MethodMatcher.java b/engine/src/main/java/com/ibm/engine/detection/MethodMatcher.java
index 846f12972..dc59a5884 100644
--- a/engine/src/main/java/com/ibm/engine/detection/MethodMatcher.java
+++ b/engine/src/main/java/com/ibm/engine/detection/MethodMatcher.java
@@ -169,8 +169,33 @@ public boolean match(
return false;
}
- boolean typeMatches = this.invokedObjectTypeString.test(invokedObjectType.get());
- boolean nameMatches = this.methodName.test(invokedMethodName.get());
+ return matchKeysInternal(
+ invokedObjectType.get(),
+ invokedMethodName.get(),
+ param,
+ translation.supportsSubsetParameterMatching());
+ }
+
+ /**
+ * Tree-free equivalent of {@link #match}: matches against the invoked-object type, method name
+ * and parameter types extracted at record time, so a detached recorded call can be matched
+ * without retaining its AST. Subset (constructor) parameter matching is not applicable to
+ * detached calls, so it is disabled here.
+ */
+ public boolean matchKeys(
+ @Nonnull IType invokedObjectType,
+ @Nonnull String methodName,
+ @Nonnull List parameterTypes) {
+ return matchKeysInternal(invokedObjectType, methodName, parameterTypes, false);
+ }
+
+ private boolean matchKeysInternal(
+ @Nonnull IType invokedObjectType,
+ @Nonnull String invokedMethodName,
+ @Nonnull List param,
+ boolean supportsSubsetParameterMatching) {
+ boolean typeMatches = this.invokedObjectTypeString.test(invokedObjectType);
+ boolean nameMatches = this.methodName.test(invokedMethodName);
if (!typeMatches || !nameMatches) {
return false;
@@ -178,9 +203,9 @@ public boolean match(
// For languages supporting subset parameter matching (e.g., Go composite literals),
// the rule matches if at least one expected parameter exists in the actual fields.
- if (invokedMethodName.get().equals("")
+ if (invokedMethodName.equals("")
&& !parameterTypesSerializable.isEmpty()
- && translation.supportsSubsetParameterMatching()) {
+ && supportsSubsetParameterMatching) {
return anyParameterMatches(param);
}
diff --git a/engine/src/main/java/com/ibm/engine/hooks/EnumHook.java b/engine/src/main/java/com/ibm/engine/hooks/EnumHook.java
index 4022bb6c0..976b152fe 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/EnumHook.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/EnumHook.java
@@ -43,7 +43,9 @@ public T hookValue() {
public boolean isInvocationOn(
@Nonnull CallContext callContext,
@Nonnull ILanguageSupport languageSupport) {
- return isInvocationOn(callContext.tree(), languageSupport);
+ // Enum accesses are never detached, so a detached record can never be an enum invocation.
+ final T tree = callContext.tree();
+ return tree != null && isInvocationOn(tree, languageSupport);
}
@Override
diff --git a/engine/src/main/java/com/ibm/engine/hooks/HookDetectionObservable.java b/engine/src/main/java/com/ibm/engine/hooks/HookDetectionObservable.java
index f17f81ae8..3e3e0886e 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/HookDetectionObservable.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/HookDetectionObservable.java
@@ -19,8 +19,8 @@
*/
package com.ibm.engine.hooks;
+import com.ibm.engine.callstack.CallContext;
import com.ibm.engine.detection.Handler;
-import com.ibm.engine.language.IScanContext;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
@@ -55,10 +55,7 @@ public void unsubscribe(
}
@Override
- public void notify(
- @Nonnull T invocationTree,
- @Nonnull IHook hook,
- @Nonnull IScanContext scanContext) {
+ public void notify(@Nonnull CallContext callContext, @Nonnull IHook hook) {
List> subscribers = listeners.get(hook.hookValue());
if (subscribers == null) {
return;
@@ -71,7 +68,7 @@ public void notify(
* Iterator to traverse the elements of a Collection, it does not cause a ConcurrentModificationException.
*/
for (int i = 0; i < subscribers.size(); i++) {
- subscribers.get(i).onHookInvocation(invocationTree, hook, scanContext);
+ subscribers.get(i).onHookInvocation(callContext, hook);
}
}
}
diff --git a/engine/src/main/java/com/ibm/engine/hooks/HookRepository.java b/engine/src/main/java/com/ibm/engine/hooks/HookRepository.java
index cfd2b53a9..7e3975950 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/HookRepository.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/HookRepository.java
@@ -115,9 +115,6 @@ public void notify(@Nonnull Event event, @Nonnull IHook object) {
public void update(@Nonnull final CallContext callContext) {
hookSet.stream()
.filter(hook -> hook.isInvocationOn(callContext, handler.getLanguageSupport()))
- .forEach(
- hook ->
- handler.notifyAllHookDetectionObservers(
- callContext.tree(), hook, callContext.publisher()));
+ .forEach(hook -> handler.notifyAllHookDetectionObservers(callContext, hook));
}
}
diff --git a/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObservable.java b/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObservable.java
index 23a19bd92..623c26641 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObservable.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObservable.java
@@ -19,7 +19,7 @@
*/
package com.ibm.engine.hooks;
-import com.ibm.engine.language.IScanContext;
+import com.ibm.engine.callstack.CallContext;
import javax.annotation.Nonnull;
public interface IHookDetectionObservable {
@@ -30,8 +30,5 @@ void subscribe(
void unsubscribe(
@Nonnull IHook hook, @Nonnull IHookDetectionObserver listener);
- void notify(
- @Nonnull T invocationTree,
- @Nonnull IHook hook,
- @Nonnull IScanContext scanContext);
+ void notify(@Nonnull CallContext callContext, @Nonnull IHook hook);
}
diff --git a/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObserver.java b/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObserver.java
index a0b3358d5..9a28ebddc 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObserver.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/IHookDetectionObserver.java
@@ -19,14 +19,11 @@
*/
package com.ibm.engine.hooks;
-import com.ibm.engine.language.IScanContext;
+import com.ibm.engine.callstack.CallContext;
import javax.annotation.Nonnull;
public interface IHookDetectionObserver {
- void onHookInvocation(
- @Nonnull T invocationTree,
- @Nonnull IHook hook,
- @Nonnull IScanContext scanContext);
+ void onHookInvocation(@Nonnull CallContext callContext, @Nonnull IHook hook);
boolean isRootHook();
}
diff --git a/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithParameterResolvement.java b/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithParameterResolvement.java
index 497ce7bbb..b9dde7084 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithParameterResolvement.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithParameterResolvement.java
@@ -20,6 +20,7 @@
package com.ibm.engine.hooks;
import com.ibm.engine.callstack.CallContext;
+import com.ibm.engine.callstack.DetachedCall;
import com.ibm.engine.detection.MatchContext;
import com.ibm.engine.detection.MethodMatcher;
import com.ibm.engine.language.ILanguageSupport;
@@ -59,7 +60,17 @@ public Parameter getParameter() {
public boolean isInvocationOn(
@Nonnull CallContext callContext,
@Nonnull ILanguageSupport languageSupport) {
- return isInvocationOn(callContext.tree(), languageSupport);
+ if (callContext instanceof DetachedCall detached) {
+ final MethodMatcher methodMatcher =
+ languageSupport.createMethodMatcherBasedOn(methodDefinition);
+ return methodMatcher != null
+ && methodMatcher.matchKeys(
+ detached.invokedObjectType(),
+ detached.methodName(),
+ detached.parameterTypes());
+ }
+ final T tree = callContext.tree();
+ return tree != null && isInvocationOn(tree, languageSupport);
}
@Override
diff --git a/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithReturnResolvement.java b/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithReturnResolvement.java
index 8a8093577..7859ffe71 100644
--- a/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithReturnResolvement.java
+++ b/engine/src/main/java/com/ibm/engine/hooks/MethodInvocationHookWithReturnResolvement.java
@@ -20,6 +20,7 @@
package com.ibm.engine.hooks;
import com.ibm.engine.callstack.CallContext;
+import com.ibm.engine.callstack.DetachedCall;
import com.ibm.engine.detection.MatchContext;
import com.ibm.engine.detection.MethodMatcher;
import com.ibm.engine.language.ILanguageSupport;
@@ -47,7 +48,17 @@ public Parameter getParameter() {
public boolean isInvocationOn(
@Nonnull CallContext callContext,
@Nonnull ILanguageSupport languageSupport) {
- return isInvocationOn(callContext.tree(), languageSupport);
+ if (callContext instanceof DetachedCall detached) {
+ final MethodMatcher methodMatcher =
+ languageSupport.createMethodMatcherBasedOn(methodDefinition);
+ return methodMatcher != null
+ && methodMatcher.matchKeys(
+ detached.invokedObjectType(),
+ detached.methodName(),
+ detached.parameterTypes());
+ }
+ final T tree = callContext.tree();
+ return tree != null && isInvocationOn(tree, languageSupport);
}
@Override
diff --git a/engine/src/main/java/com/ibm/engine/language/ILanguageSupport.java b/engine/src/main/java/com/ibm/engine/language/ILanguageSupport.java
index 64fef24e6..4de5f9084 100644
--- a/engine/src/main/java/com/ibm/engine/language/ILanguageSupport.java
+++ b/engine/src/main/java/com/ibm/engine/language/ILanguageSupport.java
@@ -19,6 +19,7 @@
*/
package com.ibm.engine.language;
+import com.ibm.engine.callstack.CallContextStats;
import com.ibm.engine.detection.DetectionStore;
import com.ibm.engine.detection.EnumMatcher;
import com.ibm.engine.detection.IBaseMethodVisitorFactory;
@@ -117,4 +118,55 @@ IDetectionEngine createDetectionEngineInstance(
*/
@Nullable EnumMatcher createSimpleEnumMatcherFor(
@Nonnull T enumIdentifier, @Nonnull MatchContext matchContext);
+
+ /**
+ * Whether a recorded call may be stored tree-free (detached) instead of retaining its AST for
+ * the whole scan. Detaching lets the file's AST be garbage-collected after analysis.
+ *
+ * Default: conservative {@code false} (retain the tree, today's behavior). Only languages
+ * that can faithfully pre-resolve a call's arguments at record time override this.
+ *
+ * @param tree the recorded call
+ * @return {@code true} if the call can be recorded as a detached, tree-free record
+ */
+ default boolean isDetachableCall(@Nonnull T tree) {
+ return false;
+ }
+
+ /**
+ * Index of a hook's target parameter within the method definition's parameter list, used to
+ * pick the matching pre-resolved argument snapshot when replaying a detached call. Returns
+ * {@code -1} if it cannot be determined.
+ *
+ * @param methodDefinition the hooked method definition
+ * @param methodParameter the hook's target parameter identifier
+ * @return the zero-based parameter index, or {@code -1}
+ */
+ default int parameterIndexOf(@Nonnull T methodDefinition, @Nonnull T methodParameter) {
+ return -1;
+ }
+
+ /**
+ * Called when a source file has finished being analyzed. Languages that detach recorded calls
+ * use this to drop the just-analyzed file's retained ASTs (its same-file detections have
+ * already fired). Default: no-op.
+ *
+ * @param inputFile the file that finished analysis
+ */
+ default void notifyLeaveFile(@Nonnull org.sonar.api.batch.fs.InputFile inputFile) {
+ // no-op by default
+ }
+
+ /**
+ * Diagnostics-only: a read-only snapshot of the language's recorded-call population, exposed
+ * for the performance/heap harness and scan-floor attribution. This is not part of the
+ * detection contract — no detection behaviour depends on it, and languages that do not
+ * accumulate a call stack simply return {@link CallContextStats#EMPTY}.
+ *
+ * @return the current call-context stats; never {@code null}
+ */
+ @Nonnull
+ default CallContextStats callContextStats() {
+ return CallContextStats.EMPTY;
+ }
}
diff --git a/engine/src/main/java/com/ibm/engine/language/java/JavaDetachedIssueReporter.java b/engine/src/main/java/com/ibm/engine/language/java/JavaDetachedIssueReporter.java
new file mode 100644
index 000000000..d7169476d
--- /dev/null
+++ b/engine/src/main/java/com/ibm/engine/language/java/JavaDetachedIssueReporter.java
@@ -0,0 +1,95 @@
+/*
+ * Sonar Cryptography Plugin
+ * Copyright (C) 2024 PQCA
+ *
+ * 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.
+ */
+package com.ibm.engine.language.java;
+
+import com.ibm.engine.callstack.DetachedSyntaxToken;
+import com.ibm.engine.callstack.IDetachedIssueReporter;
+import java.lang.reflect.Field;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.sonar.api.batch.fs.InputFile;
+import org.sonar.java.SonarComponents;
+import org.sonar.java.model.DefaultModuleScannerContext;
+import org.sonar.java.reporting.AnalyzerMessage;
+import org.sonar.plugins.java.api.JavaCheck;
+import org.sonar.plugins.java.api.JavaFileScannerContext;
+
+/**
+ * Raises a SonarQube issue for a detached (tree-free) cross-file detection through {@link
+ * SonarComponents}, which is shared per scan and does not pin any file's AST. It is captured while
+ * the file is live (at record time) together with the file's {@link InputFile}, so the issue can be
+ * reported at the original call site later without keeping the file's {@code
+ * JavaFileScannerContext}.
+ *
+ *
{@code SonarComponents} is an internal sonar-java type not exposed by the public {@code
+ * JavaFileScannerContext} API, so it is read reflectively from {@link DefaultModuleScannerContext}
+ * (extended by both the production context and the CheckVerifier test context). If it cannot be
+ * obtained, {@link #create} returns {@code null} and issue reporting degrades to CBOM-only.
+ */
+public final class JavaDetachedIssueReporter implements IDetachedIssueReporter {
+
+ private static final Logger LOGGER = LoggerFactory.getLogger(JavaDetachedIssueReporter.class);
+
+ @Nonnull private final SonarComponents sonarComponents;
+ @Nonnull private final InputFile inputFile;
+
+ private JavaDetachedIssueReporter(
+ @Nonnull SonarComponents sonarComponents, @Nonnull InputFile inputFile) {
+ this.sonarComponents = sonarComponents;
+ this.inputFile = inputFile;
+ }
+
+ @Nullable static JavaDetachedIssueReporter create(@Nonnull JavaFileScannerContext context) {
+ final SonarComponents sonarComponents = extractSonarComponents(context);
+ if (sonarComponents == null) {
+ return null;
+ }
+ return new JavaDetachedIssueReporter(sonarComponents, context.getInputFile());
+ }
+
+ @Override
+ public void report(
+ @Nonnull JavaCheck rule,
+ @Nonnull DetachedSyntaxToken location,
+ @Nonnull String message) {
+ final AnalyzerMessage.TextSpan span =
+ new AnalyzerMessage.TextSpan(
+ location.line(),
+ location.offset(),
+ location.endLine(),
+ location.endOffset());
+ sonarComponents.reportIssue(new AnalyzerMessage(rule, inputFile, span, message, 0));
+ }
+
+ @SuppressWarnings("java:S3011")
+ @Nullable private static SonarComponents extractSonarComponents(@Nonnull JavaFileScannerContext context) {
+ try {
+ final Field field =
+ DefaultModuleScannerContext.class.getDeclaredField("sonarComponents");
+ field.setAccessible(true);
+ return (SonarComponents) field.get(context);
+ } catch (ReflectiveOperationException | RuntimeException e) {
+ LOGGER.debug("Detached issue reporting unavailable: {}", e.getMessage());
+ return null;
+ }
+ }
+}
diff --git a/engine/src/main/java/com/ibm/engine/language/java/JavaDetectionEngine.java b/engine/src/main/java/com/ibm/engine/language/java/JavaDetectionEngine.java
index 3d7c84915..99e800e46 100644
--- a/engine/src/main/java/com/ibm/engine/language/java/JavaDetectionEngine.java
+++ b/engine/src/main/java/com/ibm/engine/language/java/JavaDetectionEngine.java
@@ -19,10 +19,16 @@
*/
package com.ibm.engine.language.java;
+import com.ibm.engine.callstack.ArgSnapshot;
+import com.ibm.engine.callstack.DetachedCall;
+import com.ibm.engine.callstack.DetachedScanContext;
+import com.ibm.engine.callstack.DetachedSyntaxToken;
+import com.ibm.engine.callstack.RetainedCall;
import com.ibm.engine.detection.DetectionStore;
import com.ibm.engine.detection.DetectionStoreWithHook;
import com.ibm.engine.detection.Handler;
import com.ibm.engine.detection.IDetectionEngine;
+import com.ibm.engine.detection.IType;
import com.ibm.engine.detection.MatchContext;
import com.ibm.engine.detection.MethodDetection;
import com.ibm.engine.detection.MethodMatcher;
@@ -32,6 +38,8 @@
import com.ibm.engine.hooks.EnumHook;
import com.ibm.engine.hooks.MethodInvocationHookWithParameterResolvement;
import com.ibm.engine.hooks.MethodInvocationHookWithReturnResolvement;
+import com.ibm.engine.language.ILanguageTranslation;
+import com.ibm.engine.language.IScanContext;
import com.ibm.engine.model.factory.IValueFactory;
import com.ibm.engine.model.factory.SizeFactory;
import com.ibm.engine.rule.DetectableParameter;
@@ -53,6 +61,7 @@
import org.sonar.java.model.ExpressionUtils;
import org.sonar.plugins.java.api.JavaCheck;
import org.sonar.plugins.java.api.JavaFileScannerContext;
+import org.sonar.plugins.java.api.location.Position;
import org.sonar.plugins.java.api.semantic.Symbol;
import org.sonar.plugins.java.api.tree.Arguments;
import org.sonar.plugins.java.api.tree.ArrayDimensionTree;
@@ -69,6 +78,7 @@
import org.sonar.plugins.java.api.tree.NewArrayTree;
import org.sonar.plugins.java.api.tree.NewClassTree;
import org.sonar.plugins.java.api.tree.ReturnStatementTree;
+import org.sonar.plugins.java.api.tree.SyntaxToken;
import org.sonar.plugins.java.api.tree.Tree;
import org.sonar.plugins.java.api.tree.TypeTree;
import org.sonar.plugins.java.api.tree.VariableTree;
@@ -97,7 +107,7 @@ public void run(@Nonnull Tree tree) {
public void run(@Nonnull TraceSymbol traceSymbol, @Nonnull Tree tree) {
if (tree.is(Tree.Kind.METHOD_INVOCATION)) {
MethodInvocationTree methodInvocationTree = (MethodInvocationTree) tree;
- handler.addCallToCallStack(methodInvocationTree, detectionStore.getScanContext());
+ recordCall(methodInvocationTree);
if (detectionStore
.getDetectionRule()
.match(methodInvocationTree, handler.getLanguageSupport().translation())) {
@@ -116,6 +126,126 @@ public void run(@Nonnull TraceSymbol traceSymbol, @Nonnull Tree tree) {
}
}
+ /**
+ * Records a method invocation for later cross-file hook matching, detaching it from the AST
+ * when possible (its arguments are pre-resolved here while the file is live). Falls back to
+ * retaining the tree when the call is not detachable or an argument cannot be faithfully
+ * snapshotted.
+ */
+ private void recordCall(@Nonnull MethodInvocationTree invocation) {
+ final IScanContext scanContext = detectionStore.getScanContext();
+ // Record retained (with the live tree) so same-file hook detections resolve and report
+ // through the live context. If detachable, pre-build the tree-free form now, while the file
+ // is live; CallStackAgent swaps to it at leaveFile so the AST can be collected.
+ DetachedCall detachedForm = null;
+ if (handler.getLanguageSupport().isDetachableCall(invocation)) {
+ detachedForm = buildDetachedCall(invocation, scanContext);
+ }
+ handler.addRecordedCall(new RetainedCall<>(invocation, scanContext, detachedForm));
+ }
+
+ @Nullable private DetachedCall buildDetachedCall(
+ @Nonnull MethodInvocationTree invocation,
+ @Nonnull IScanContext scanContext) {
+ // A detached call is only ever matched in hook context (MethodMatcher.matchKeys), so its
+ // type keys must be snapshotted with hook-context semantics (exact type matching) to
+ // reproduce the live retained-call path, which matches via the hook's isHookContext=true
+ // MatchContext. Using record-context (isHookContext=false) here would make cross-file
+ // matching subtype-permissive and diverge from the same-file result.
+ final MatchContext matchContext = MatchContext.createForHookContext();
+ final ILanguageTranslation translation = handler.getLanguageSupport().translation();
+ final Optional invokedType =
+ translation.getInvokedObjectTypeString(matchContext, invocation);
+ final Optional name = translation.getMethodName(matchContext, invocation);
+ if (invokedType.isEmpty() || name.isEmpty()) {
+ return null;
+ }
+ final List parameterTypes =
+ translation.getMethodParameterTypes(matchContext, invocation);
+
+ final List arguments = new ArrayList<>();
+ final List actualArguments = invocation.arguments();
+ for (int i = 0; i < actualArguments.size(); i++) {
+ final List> resolved =
+ resolveValuesInInnerScope(Object.class, actualArguments.get(i), null);
+ final List snapshots = new ArrayList<>();
+ for (ResolvedValue resolvedValue : resolved) {
+ final DetachedSyntaxToken location =
+ captureLocation(resolvedValue.tree(), resolvedValue.value().toString());
+ if (location == null) {
+ return null; // cannot faithfully snapshot -> fall back to retaining the tree
+ }
+ snapshots.add(
+ new ArgSnapshot.ResolvedSnapshotValue(resolvedValue.value(), location));
+ }
+ arguments.add(new ArgSnapshot(i, snapshots));
+ }
+
+ final JavaDetachedIssueReporter issueReporter =
+ scanContext instanceof JavaScanContext javaScanContext
+ ? JavaDetachedIssueReporter.create(javaScanContext.javaFileScannerContext())
+ : null;
+ final DetachedScanContext detachedScanContext =
+ new DetachedScanContext<>(
+ scanContext.getInputFile(), scanContext.getFilePath(), issueReporter);
+ return new DetachedCall<>(
+ invokedType.get(), name.get(), parameterTypes, arguments, detachedScanContext);
+ }
+
+ /**
+ * Captures a value's location as an AST-free {@link DetachedSyntaxToken}, mirroring {@code
+ * JavaTranslator.getDetectionContextFrom} so a detached detection's CBOM occurrence is
+ * identical to a non-detached one.
+ */
+ @Nullable private DetachedSyntaxToken captureLocation(@Nonnull Tree location, @Nonnull String text) {
+ final SyntaxToken firstToken = location.firstToken();
+ final SyntaxToken lastToken = location.lastToken();
+ if (firstToken == null || lastToken == null) {
+ return null;
+ }
+ SyntaxToken locationToken = firstToken;
+ List keywords = List.of();
+ switch (location.kind()) {
+ case NEW_CLASS:
+ final NewClassTree newClassTree = (NewClassTree) location;
+ final SyntaxToken identifierToken = newClassTree.identifier().firstToken();
+ if (identifierToken != null) {
+ locationToken = identifierToken;
+ }
+ keywords =
+ List.of(
+ newClassTree.methodSymbol().signature(),
+ newClassTree.methodSymbol().name(),
+ newClassTree.identifier().toString());
+ break;
+ case METHOD_INVOCATION:
+ final MethodInvocationTree methodInvocationTree = (MethodInvocationTree) location;
+ final SyntaxToken methodSelectToken =
+ methodInvocationTree.methodSelect().firstToken();
+ if (methodSelectToken != null) {
+ locationToken = methodSelectToken;
+ }
+ keywords =
+ List.of(
+ methodInvocationTree.methodSymbol().signature(),
+ methodInvocationTree.methodSymbol().name());
+ break;
+ case ENUM_CONSTANT:
+ final EnumConstantTree enumConstantTree = (EnumConstantTree) location;
+ keywords =
+ List.of(
+ enumConstantTree.initializer().methodSymbol().signature(),
+ enumConstantTree.initializer().methodSymbol().name());
+ break;
+ default:
+ break;
+ }
+ final Position start = locationToken.range().start();
+ final Position end = lastToken.range().end();
+ return new DetachedSyntaxToken(
+ start.line(), start.columnOffset(), end.line(), end.columnOffset(), text, keywords);
+ }
+
@SuppressWarnings("java:S3776")
@Nullable @Override
public Tree extractArgumentFromMethodCaller(
diff --git a/engine/src/main/java/com/ibm/engine/language/java/JavaLanguageSupport.java b/engine/src/main/java/com/ibm/engine/language/java/JavaLanguageSupport.java
index bf7a28ced..1ad83ad9e 100644
--- a/engine/src/main/java/com/ibm/engine/language/java/JavaLanguageSupport.java
+++ b/engine/src/main/java/com/ibm/engine/language/java/JavaLanguageSupport.java
@@ -19,6 +19,7 @@
*/
package com.ibm.engine.language.java;
+import com.ibm.engine.callstack.CallContextStats;
import com.ibm.engine.detection.DetectionStore;
import com.ibm.engine.detection.EnumMatcher;
import com.ibm.engine.detection.Handler;
@@ -33,6 +34,7 @@
import com.ibm.engine.rule.IDetectionRule;
import java.util.Arrays;
import java.util.LinkedList;
+import java.util.List;
import java.util.Optional;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
@@ -42,11 +44,15 @@
import org.sonar.plugins.java.api.JavaCheck;
import org.sonar.plugins.java.api.JavaFileScannerContext;
import org.sonar.plugins.java.api.semantic.Symbol;
+import org.sonar.plugins.java.api.tree.BaseTreeVisitor;
import org.sonar.plugins.java.api.tree.ClassTree;
import org.sonar.plugins.java.api.tree.ExpressionTree;
+import org.sonar.plugins.java.api.tree.MethodInvocationTree;
import org.sonar.plugins.java.api.tree.MethodTree;
+import org.sonar.plugins.java.api.tree.NewArrayTree;
import org.sonar.plugins.java.api.tree.Tree;
import org.sonar.plugins.java.api.tree.TypeTree;
+import org.sonar.plugins.java.api.tree.VariableTree;
public final class JavaLanguageSupport
implements ILanguageSupport {
@@ -138,4 +144,73 @@ public EnumMatcher createSimpleEnumMatcherFor(
translation().getEnumIdentifierName(matchContext, enumIdentifier);
return enumIdentifierName.>map(EnumMatcher::new).orElse(null);
}
+
+ @Override
+ public void notifyLeaveFile(@Nonnull org.sonar.api.batch.fs.InputFile inputFile) {
+ this.handler.detachCallsForFile(inputFile);
+ }
+
+ @Override
+ @Nonnull
+ public CallContextStats callContextStats() {
+ return this.handler.callContextStats();
+ }
+
+ @Override
+ public boolean isDetachableCall(@Nonnull Tree tree) {
+ if (!(tree instanceof MethodInvocationTree invocation)) {
+ // Enum accesses and other kinds stay retained in this iteration.
+ return false;
+ }
+ // NB: we deliberately do NOT require methodSymbol().declaration() != null. Cross-file calls
+ // resolve their callee via the compiled classpath (sonar.java.binaries), so declaration()
+ // is
+ // null for exactly the cross-file calls that drive the heap retention. Detachability
+ // depends
+ // on argument pre-resolvability (checked when building the record, with a retained-tree
+ // fallback) and on matchKeys (record-time type/name/params), neither of which needs the
+ // callee's source declaration.
+ for (ExpressionTree argument : invocation.arguments()) {
+ if (containsNewArray(argument)) {
+ // NEW_ARRAY resolution is value-factory dependent (SizeFactory returns the array
+ // size, otherwise its elements). We cannot reproduce that generically at record
+ // time, so keep such calls on the retained-tree fallback path.
+ return false;
+ }
+ }
+ return true;
+ }
+
+ @Override
+ public int parameterIndexOf(@Nonnull Tree methodDefinition, @Nonnull Tree methodParameter) {
+ if (!(methodDefinition instanceof MethodTree method)) {
+ return -1;
+ }
+ final Optional