File-Based Ownership

[handstandsam]

The initial "unit" was "modules" in #invert and Code References was bolted on later. Code References DO support owner which overrides that of the module it's in (Was required for @Testowner).

I agree that based on where we are today, we should actually lean towards file-based ownership instead of module based as a default.

Proposed logic:

• If a CodeReference has an explicit owner attached to it, use it (Nice for custom situations that override file/module based ownership methods).
• After collection, if no owner is manually added, compute file-based ownership.
• If file-based ownership doesn't come back to anything, then fall back to module ownership.

Thoughts about a required owner field for CodeReference:

Right now owner :String? is nullable. We could change that to non-null, but it would require updating all collectors to have explicit awareness to add file-based ownership.
Based on this "breaking" change, and because it makes authoring Collectors more complex, I would lean towards keeping it nullable, and use the proposed logic above.

[handstandsam]

This seems logical but there is a lot of disk I/O and processing (depending on the type of InvertOwnershipCollector specified). Because of this, it isn't default still, but in theory if feels like the right thing.

Pragmatic approach: For any CodeReference Collectors that require more ownership than just module, go ahead and manually calculate ownership and attach to the code reference.

Here is an example of how to do that:

Custom Collector

  override fun collect(
    invertCollectContext: InvertCollectContext,
  ): List<CollectedStat>? {
    return super.collect(invertCollectContext)?.map { collectedStat: CollectedStat ->
      OwnersUtils.addExplicitFileBasedOwnershipForCodeReferences(
        collectedStat,
        invertCollectContext.gitCloneDir,
        invertCollectContext.ownershipCollector,
      )
    }
  }

Utility

object OwnersUtils {
  fun addExplicitFileBasedOwnershipForCodeReferences(
    collectedStat: CollectedStat,
    rootProjectDir: File,
    ownershipCollector: InvertOwnershipCollector,
  ): CollectedStat {
    val updatedCodeReferences = mutableListOf<Stat.CodeReferencesStat.CodeReference>()
    val stat = collectedStat.stat
    return when (stat) {
      is Stat.CodeReferencesStat -> {
        stat.value.forEach { codeReference ->
          val updatedCodeReference = if (codeReference.owner != null) {
            // Already has a specified/overridden owner, leaving as-is
            codeReference
          } else {
            val ownerNameForFile = ownershipCollector.collect(
              rootProjectDir,
              File(rootProjectDir, codeReference.filePath)
            )
            codeReference.copy(
              owner = ownerNameForFile
            )
          }
          synchronized(updatedCodeReferences) { updatedCodeReferences.add(updatedCodeReference) }
        }
        collectedStat.copy(
          stat = stat.copy(
            value = updatedCodeReferences
          )
        )
      }

      else -> {
        collectedStat
      }
    }
  }
}