JBRes-8425: Add memory for renaming transformations

[dragoi75]

Changes

• Addition of RenameMemory
  • Responsible for loading / writing the memory file.
  • Creates one memory file per project.
• Addition of MemoryAwareTransformation:
  • Extends SelfManagedTransformation.
  • Acts as middleware between the transformations and RenameMemory
• Addition of PsiSignatureGenerator`
  • Generates a unique signature for (a subset of) PSI elements.
• Modifications to the three RenameTransformations to use memory.

Design questions

1. For now, the useMemory is an individual config under the transformation. Should we make it a global flag?

[github-actions]

Qodana Community for JVM

1 new problem were found

Inspection name	Severity	Problems
Leaking 'this' in constructor	🔶 Warning	1

💡 Qodana analysis was run in the pull request mode: only the changed files were checked

View the detailed Qodana report

To be able to view the detailed Qodana report, you can either:

• Register at Qodana Cloud and configure the action
• Use GitHub Code Scanning with Qodana
• Host Qodana report at GitHub Pages
• Inspect and use qodana.sarif.json (see the Qodana SARIF format for details)

To get *.log files or any other Qodana artifacts, run the action with upload-result option set to true,
so that the action will upload the files as the job artifacts:

      - name: 'Qodana Scan'
        uses: JetBrains/qodana-action@v2025.1.1
        with:
          upload-result: true

Contact Qodana team

Contact us at qodana-support@jetbrains.com

• Or via our issue tracker: https://jb.gg/qodana-issue
• Or share your feedback: https://jb.gg/qodana-discussions

[Vladislav0Art]

There is a major comment about the selected architecture and a better alternative: here.

[Vladislav0Art]

You can reduce the control-flow complexity:

val memory =  RenameMemory(projectName)
// all operations you do in `also` block.

imho, let is semantically more suitable here.

[Vladislav0Art]

[NOTE, no modifications requested]

This entire method can be reduced to a lazy block over the cachedMemory instance.

private val cachedMemory: RenameMemory = lazy {
   // TODO: need access to a `project` instance.
}

[Vladislav0Art]

In all places where you return emptyList in this getNameSuggestions function, you should return generateNewClassNames(psiClass).

Otherwise, this solution doesn't map all valid inputs into a successful rename (although the previous solution without any memory would).

[Vladislav0Art]

Here, also. Not emptyList but the implementation generateNewMethodNames.

[Vladislav0Art]

Looking at these getNameSuggestions(psiComponent, memory), it's apparent that you can reduce it into a "cached-or-call-method" semantic:

[suspend] fun <R> Memory.cachedOrCall(signature: String?, callback: [suspend] () -> R): R {
    val memory = this
    if (signature != null && memory.has(signature)) return memory.getValue(signature)
    
    // otherwise, when missing, execute a callback
    val result = callback()
    if (signature != null) memory.store(signature, result)
    return result
}

// How To Use:
// inside your transformation
val methodSignature = readAction { SignatureGenerator.signatureOf(psiMethod) }

val suggestions = memory.cachedOrCall(methodSignature) {
    suggestNewMethodNamesByAI(/* whatever */)
}

return suggestions

This way, your memory can be used not only for renames, but for everything; which is needed by my PR as well.

[Vladislav0Art]

1. private data class?

2. It's not really a file but rather a state of the memory: A file (i.e., the fle system itself) is an implementation detail used for persistent saving (kinda one of many options where/how to save a memory state); it could have been a database also). I'd rename to MemoryState or alike.

[Vladislav0Art]

‼️ This hard-coded setup of memoryBaseDir makes the save location very rigid.

It should be a caller's responsibility to define where this memory instance saves its data.

I'd place this folder selection logic somewhere to the upper layer of the project (HeadlessStarter or ExecutionService), and make the memoryBaseDir a constructor parameter of a memory instance.

---

I'd make it optionally parameterizable from the CLI: Useful for the eval pipeline to decide where to store the memory (i.e., creating and parsing this filepath somewhere in the HeadlessStarter).

[Vladislav0Art]

❗️MAJOR API Concern about RenameMemory and MemoryAwareTransformation ❗️

This comment addresses some architectural caveats of how memory API is current integrated with transformations.

---

You don't need this RenameMemory class be rename-specific; in fact, it doesn't need to know what type of information it stores whatsoever.

What you have is a general-purpose interface of any persistent storage, like Redis/Database or even a simple in-memory Map<String, String>.

I suggest turning this API into an interface Memory with a single implementation that stores entries under a filepath given by the caller:

// you only need these 4 methods (maybe you don't even need `size` method)
interface Memory<K, V> {
    fun get(key: K): V?
    // returns the previous value if present, otherwise `null`
    fun put(key: K, value: V): V?
    fun dump(): Unit // or `save`
    fun size(): Int/Long
}

Even better approach is to make it AutoCloseable, since you always need to "save" your memory once you're done with it. Do it as:

interface Memory<K, V> : AutoCloseable {
    // ... as above ...

    fun close() {
     // we kinda know how to close it already:
     this.save() // or this.dump()
    }
}

Given this interface, you write an implementation that stores data on disk:

class PersistentProjectMemory(
   filepath: String, // base directory where to store/from where to load the JSON file with cached entries
   projectName: String,
) : Memory<String, String> {
     // ...
}

This gives you a high level of freedom of how to integrate this memory with transformations; you can:

1. Create a single globally defined Memory instance shared by all transformations (somewhere in the TransformationService or HeadlessStarter).
2. Create a memory instance for every transformation applied (I think this is the approach you currently have with MemoryAwareTransformation).

Next, you can create a memory instance either project-wide or per-transformation in the TransformationService:

// inside `TransformationService`

class TransformationService {

   fun applyTransformations() {

         // ...
         // (1): define a memory instance here -> you get a single memory for an entire project under transformation
         val globalMemory = PersistentProjectMemory(baseDir, projectName)

         for (tr in transformations) {
             // (2): define memory instance here -> you get a per-transformation memory instance
             val memory = PersistentProjectMemory(baseDir, projectName)
             try {
                 executor.execute(tr, context, memory)
             } finally {
                  // IMPORTANT: we successfully "close" the resource, i.e. dump data on disk/save in the db or Redis, etc.
                  memory.close() // aka `memory.save()/memory.dump()`
             }
         }

    }
}

As for the transformations (namely, IntelliJAwareTransformation interface), I'd simply add another parameter memory: Memory into apply method. The transformations that can benefit from memory, will do so; otherwise, it'll be a no-op parameter, which is fine for us.

---

Problems with MemoryAwareTransformation:

1. It removes the freedom of selecting a scope for your memory (i.e., you always have it per-transformation; you cannot make it project-scoped, or place anywhere else). This is because MemoryAwareTransformation uses inheritance, which in this case is inferior to the compositional approach.
2. It tightly couples transformation and persistent memory.
3. Besides, we spawned quite a lot of transformation-related classes; making it even larger hinders maintainability.

In other words, the main problem with MemoryAwareTransformation is that it uses inheritance and couples memory and transformations way too strongly.

[Vladislav0Art]

Looks like you can have both as val:

private val memoryFile: File = run {
        // Sanitize project name for use in filename
        val sanitizedName = sanitizeProjectName(projectName)

        // Ensure memory directory exists
        if (!memoryBaseDir.exists()) {
            memoryBaseDir.mkdirs()
        }

        memoryFile = File(memoryBaseDir, "$sanitizedName.json")
}

private val memoryData: RenameMemoryFile = loadFileFromDisk(memoryFile)



// where
companion object {
     fun loadFileFromDisk(from: File) { ... }
}

[Vladislav0Art]

You use these methods once for logging only. Do you need them in public API then? you can log in the init block as well.

Especially getMemoryFilePath: it is an implementation detail; callers should not know how the Memory class manages its storage.