feat(archive): add yearly/monthly archive folder options

[fnune]

Fixes #900

⚠️ I'm a Kotlin newbie. Posting for initial feedback on the approach before investing more time.

Adds yearly and monthly archive folder organization matching Desktop's behavior. Eliminates the need to manually switch archive folders each year. Does this with an "Archive options" preference with three modes: Single folder, Yearly folders (Archive/2025), or Monthly folders (Archive/2025/03). Matches Desktop's two-setting approach and uses the same archiveGranularity property. Year/month subfolders are created automatically based on message date. Existing accounts default to single folder mode for backward compatibility.

Design decisions

Two settings: matches Desktop's "which folder?" + "how to organize?" rather than a flat list of "Archive-Yearly", "CustomFolder-Monthly", etc. Avoids combinatorial explosion and works with any base folder.

Automatic subfolder creation: year/month folders are created automatically based on granularity setting, not manually selected. This avoids yearly updates and matches Desktop behavior.

Defaults: new accounts default to yearly (matching Desktop). Existing accounts migrated to single folder to preserve current behavior.

Potential follow-up

Issue #905 folder structure preservation, automatic yearly (or yearly + monthly) detection, translations...

Questions for reviewers

1. How can I test this properly? I'd love to add some integration or UI tests, would like to hear suggestions
2. Should folder creation failures show user notifications, or is logging acceptable?
3. Is PER_YEAR_ARCHIVE_FOLDERS the right default (keeping SINGLE_ARCHIVE_FOLDER for existing accounts)? This matches Desktop, but is a new default for Thunderbird Android

Screenshots

[fnune]

I think that after doing this it might be good to resync the folders (basically whatever the button on the screenshot does) because the new folder will not show up on the UI otherwise.

[fnune]

I tried to match Thunderbird Desktop here but really there's only one option, so maybe this copy should be thought through once more. This is more stable if the area does get more features, and in that case "Archive options" would be fine, but currently it's a bit meh.

[fnune]

Hi @rafaeltonholo! Anything I can do to help get this chugging along? I keep refreshing this PR to see if anything's happened 😄

[rafaeltonholo]

Hi @rafaeltonholo! Anything I can do to help get this chugging along? I keep refreshing this PR to see if anything's happened 😄

Hi there! I started the review, but I didn't have time to finish it yet, and I forgot to send the comments I have already made. Sorry about that!

I'll try to finish the review this week, but here are the initial comments

[rafaeltonholo]

Please, try to not suppressing detekt issues that can be addressed. Here, you could use the ?.let {} scope function, together with the elvis operator (?:), to avoid the ReturnCount issue:

Suggested change

	@Suppress("ReturnCount")
	fun resolveArchiveFolder(
	account: LegacyAccountDto,
	message: LocalMessage,
	): Long? {
	val baseFolderId = account.archiveFolderId ?: return null
	return when (account.archiveGranularity) {
	ArchiveGranularity.SINGLE_ARCHIVE_FOLDER -> {
	baseFolderId
	}
	ArchiveGranularity.PER_YEAR_ARCHIVE_FOLDERS -> {
	val year = getYear(getMessageDate(message))
	findOrCreateSubfolder(account, baseFolderId, year.toString())
	}
	ArchiveGranularity.PER_MONTH_ARCHIVE_FOLDERS -> {
	val date = getMessageDate(message)
	val year = getYear(date)
	val month = String.format(Locale.ROOT, "%02d", getMonth(date))
	val yearFolderId = findOrCreateSubfolder(account, baseFolderId, year.toString())
	?: return baseFolderId
	findOrCreateSubfolder(account, yearFolderId, month)
	}
	}
	}
	fun resolveArchiveFolder(
	account: LegacyAccountDto,
	message: LocalMessage,
	): Long? {
	val baseFolderId = account.archiveFolderId ?: return null
	return when (account.archiveGranularity) {
	ArchiveGranularity.SINGLE_ARCHIVE_FOLDER -> {
	baseFolderId
	}
	ArchiveGranularity.PER_YEAR_ARCHIVE_FOLDERS -> {
	val year = getYear(getMessageDate(message))
	findOrCreateSubfolder(account, baseFolderId, year.toString())
	}
	ArchiveGranularity.PER_MONTH_ARCHIVE_FOLDERS -> {
	val date = getMessageDate(message)
	val year = getYear(date)
	val month = String.format(Locale.ROOT, "%02d", getMonth(date))
	findOrCreateSubfolder(
	account,
	baseFolderId,
	year.toString(),
	)?.let { yearFolderId ->
	findOrCreateSubfolder(account, yearFolderId, month)
	} ?: baseFolderId
	}
	}
	}

[rafaeltonholo]

You could avoid the ReturnCount issue by using the following approach:

Suggested change

	@Suppress("ReturnCount")
	private fun findOrCreateSubfolder(
	account: LegacyAccountDto,
	parentFolderId: Long,
	subfolderName: String,
	): Long? {
	val parentServerId = folderIdResolver.getFolderServerId(account, parentFolderId) ?: return null
	val delimiter = FOLDER_DEFAULT_PATH_DELIMITER
	val subfolderServerId = "$parentServerId$delimiter$subfolderName"
	folderIdResolver.getFolderId(account, subfolderServerId)?.let { return it }
	val folderInfo = FolderInfo(
	serverId = subfolderServerId,
	name = subfolderServerId,
	type = LegacyFolderType.ARCHIVE,
	)
	return folderCreator.createFolder(account, folderInfo)
	}
	private fun findOrCreateSubfolder(
	account: LegacyAccountDto,
	parentFolderId: Long,
	subfolderName: String,
	): Long? {
	val parentServerId = folderIdResolver.getFolderServerId(account, parentFolderId) ?: return null
	val delimiter = FOLDER_DEFAULT_PATH_DELIMITER
	val subfolderServerId = "$parentServerId$delimiter$subfolderName"
	val id = folderIdResolver.getFolderId(account, subfolderServerId)
	return if (id != null) {
	id
	} else {
	val folderInfo = FolderInfo(
	serverId = subfolderServerId,
	name = subfolderServerId,
	type = LegacyFolderType.ARCHIVE,
	)
	folderCreator.createFolder(account, folderInfo)
	}
	}

[rafaeltonholo]

Don't assume the default path delimiter will be the same for all accounts. Many email providers use different path delimiters. Use account.folderPathDelimiter instead.

Suggested change

	val delimiter = FOLDER_DEFAULT_PATH_DELIMITER
	val delimiter = account.folderPathDelimiter

[rafaeltonholo]

Whenever possible, we should try to use kotlinx.datetime when dealing with dates. The reason is that it will make it easier to migrate, in a possible future, to KMP.

Here is how you could achieve the same, but using kotlinx.datetime:

Suggested change

	private fun getMessageDate(message: LocalMessage): Date {
	return message.internalDate ?: message.sentDate ?: Date()
	}
	private fun getYear(date: Date): Int {
	val calendar = Calendar.getInstance()
	calendar.time = date
	return calendar.get(Calendar.YEAR)
	}
	private fun getMonth(date: Date): Int {
	val calendar = Calendar.getInstance()
	calendar.time = date
	return calendar.get(Calendar.MONTH) + 1
	}
	private fun getMessageDate(message: LocalMessage): LocalDate {
	val instant = (message.internalDate ?: message.sentDate)?.time?.let(Instant::fromEpochMilliseconds)
	val timeZone = TimeZone.currentSystemDefault()
	val now = Clock.System.now().toLocalDateTime(timeZone)
	return instant?.toLocalDateTime(timeZone)?.date ?: now.date
	}

Additionally, you could use a more idiomatic way by using extension functions:

Suggested change

	private fun getMessageDate(message: LocalMessage): Date {
	return message.internalDate ?: message.sentDate ?: Date()
	}
	private fun getYear(date: Date): Int {
	val calendar = Calendar.getInstance()
	calendar.time = date
	return calendar.get(Calendar.YEAR)
	}
	private fun getMonth(date: Date): Int {
	val calendar = Calendar.getInstance()
	calendar.time = date
	return calendar.get(Calendar.MONTH) + 1
	}
	private val LocalMessage.messageDate: LocalDate
	get() {
	val instant = (message.internalDate ?: message.sentDate)?.time?.let(Instant::fromEpochMilliseconds)
	val timeZone = TimeZone.currentSystemDefault()
	val now = Clock.System.now().toLocalDateTime(timeZone)
	return instant?.toLocalDateTime(timeZone)?.date ?: now.date
	}

Then, on line 31, you can just use .year to retrieve the year from the LocalDate:

- val year = getYear(getMessageDate(message))
+ val year = getMessageDate(message).year

or in case you pick the extension function approach:

- val year = getYear(getMessageDate(message))
+ val year = message.messageDate.year

Pick the approach you feel better about.