fix(details): describe imported complaints in words, without repeats

Number details, Lookup and the block explanation showed the database's
description as stored: "FCC: Unwanted Calls; FCC callback_business: Unwanted
Calls (Live Voice); FCC caller_id: Unwanted Calls; FTC caller ID: Computer
& technical support" for +13152328257. SourceDescriptions turns the
importers' segments into one line per kind of complaint (FCC about the
caller ID, FCC giving it as the number to call back, FCC before the role
split, FTC about the caller ID), drops the pre-split "FCC:" subject when a
role already names it, collapses stray spaces and passes other sources
through once. Formatting twice changes nothing.

The database checker's verdict carries the readable text, Number details
formats the stored row, and the explanation lists the lines as bullets
instead of "Type on file: <raw text>" (reasoning_type_on_file goes). The
stored description and report count don't change.

Author: SysAdminDoc

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to CallShield will be documented in this file.
 
 ## Unreleased
 
+- Number details, Lookup and the block explanation describe FCC and FTC
+  complaints in words, one line per kind, instead of the importer's field names
+  ("FCC callback_business") and the same complaint repeated.
 - The database is also published as data/spam_numbers.txt, one number per
   line under a short header, signed like the app's feeds, for projects that
   only want the list rather than the 51 MB JSON.

README.md

@@ -553,7 +553,7 @@ language in [issue #7](https://github.com/SysAdminDoc/CallShield/issues/7).
 | URL Safety | Local spam-domain data; optional PhishTank and OpenPhish |
 | Verification | Local Gradle, lint, and release-artifact checks |
 | Tests | 1594 JVM unit tests (JUnit) |
-| Strings | 1665 string resources and 38 plural groups (translation-ready) |
+| Strings | 1668 string resources and 38 plural groups (translation-ready) |
 | Accessibility | 100+ content descriptions, 48dp touch targets |
 | Min SDK | 29 (Android 10) |
 | Target SDK | 36 |

app/src/main/java/com/sysadmindoc/callshield/data/BlockReasoning.kt

@@ -300,7 +300,11 @@ object BlockReasoning {
         ): Reasoning? =
             when (reasonCode) {
                 BlockReasonCode.DATABASE -> {
-                    reasoning(s(R.string.reasoning_database_headline), description.labeled(R.string.reasoning_type_on_file))
+                    // The description is the database's own text, one line per kind of complaint.
+                    Reasoning(
+                        headline = s(R.string.reasoning_database_headline),
+                        bullets = SourceDescriptions.readable(context, description).lines().filter { it.isNotBlank() },
+                    )
                 }
 
                 BlockReasonCode.DB_PREFIX_EXPANSION -> {

app/src/main/java/com/sysadmindoc/callshield/data/SourceDescriptions.kt

@@ -0,0 +1,63 @@
+package com.sysadmindoc.callshield.data
+
+import android.content.Context
+import androidx.annotation.StringRes
+import com.sysadmindoc.callshield.R
+
+/**
+ * A spam database description in words. The importers write their own field
+ * names into it ("FCC callback_business: Unwanted Calls"), and a row that
+ * several sources or complaint roles reported repeats itself, so Number details
+ * and Lookup showed raw keys and the same complaint twice. The stored text and
+ * its report count don't change; this is only how it reads, one line per kind
+ * of complaint, and running it twice changes nothing.
+ */
+internal object SourceDescriptions {
+    private val complaint = Regex("""^(FCC|FTC)(?:\s+(caller_id|callback_business|caller ID))?:\s*(.+)$""")
+    private val separator = Regex("""\s*[;\n]\s*""")
+    private val whitespace = Regex("""\s+""")
+
+    private enum class Kind(
+        @param:StringRes val format: Int,
+    ) {
+        FCC_CALLER_ID(R.string.source_fcc_caller_id),
+        FCC_CALLBACK(R.string.source_fcc_callback),
+        FCC_UNSPECIFIED(R.string.source_fcc_unspecified),
+        FTC_CALLER_ID(R.string.source_ftc_caller_id),
+    }
+
+    fun readable(
+        context: Context,
+        raw: String,
+    ): String {
+        val subjects = linkedMapOf<Kind, LinkedHashSet<String>>()
+        val other = LinkedHashSet<String>()
+        for (segment in raw.split(separator)) {
+            val text = segment.replace(whitespace, " ").trim()
+            if (text.isEmpty()) continue
+            val match = complaint.matchEntire(text)
+            if (match == null) {
+                other += text
+                continue
+            }
+            val (source, role, subject) = match.destructured
+            val kind =
+                when {
+                    source == "FTC" -> Kind.FTC_CALLER_ID
+                    role == "callback_business" -> Kind.FCC_CALLBACK
+                    role == "caller_id" -> Kind.FCC_CALLER_ID
+                    else -> Kind.FCC_UNSPECIFIED
+                }
+            subjects.getOrPut(kind) { LinkedHashSet() } += subject
+        }
+        // "FCC: X" predates the importer splitting complaints by role, and it
+        // repeats a subject one of the roles already names.
+        val named = subjects[Kind.FCC_CALLER_ID].orEmpty() + subjects[Kind.FCC_CALLBACK].orEmpty()
+        subjects[Kind.FCC_UNSPECIFIED]?.removeAll(named)
+        val lines =
+            Kind.entries.mapNotNull { kind ->
+                subjects[kind]?.takeIf { it.isNotEmpty() }?.let { context.getString(kind.format, it.joinToString(", ")) }
+            }
+        return (lines + other).joinToString("\n")
+    }
+}

app/src/main/java/com/sysadmindoc/callshield/data/checker/Checkers.kt

@@ -15,6 +15,7 @@ import com.sysadmindoc.callshield.data.RegionRules
 import com.sysadmindoc.callshield.data.RegulatoryPrefix
 import com.sysadmindoc.callshield.data.SmsContentAnalyzer
 import com.sysadmindoc.callshield.data.SmsContextChecker
+import com.sysadmindoc.callshield.data.SourceDescriptions
 import com.sysadmindoc.callshield.data.SourceEvidenceCodec
 import com.sysadmindoc.callshield.data.SpamHeuristics
 import com.sysadmindoc.callshield.data.SpamMLScorer
@@ -416,7 +417,7 @@ internal class DatabaseChecker(
     override suspend fun check(ctx: CheckContext): BlockResult? {
         val entry = ctx.lookupForms.firstNotNullOfOrNull { form -> repo.findByNumberInternal(form)?.takeUnless { it.isUserBlocked } }
         return if (entry != null) {
-            BlockResult.block("database", entry.type, entry.description)
+            BlockResult.block("database", entry.type, SourceDescriptions.readable(ctx.appContext, entry.description))
         } else {
             null
         }

app/src/main/java/com/sysadmindoc/callshield/ui/screens/details/NumberDetailScreen.kt

@@ -33,6 +33,7 @@ import com.sysadmindoc.callshield.R
 import com.sysadmindoc.callshield.data.BlockReasoning
 import com.sysadmindoc.callshield.data.PhoneFormatter
 import com.sysadmindoc.callshield.data.SmsBodyRedactor
+import com.sysadmindoc.callshield.data.SourceDescriptions
 import com.sysadmindoc.callshield.data.SpamRepository
 import com.sysadmindoc.callshield.data.areacodes.AreaCodeLookup
 import com.sysadmindoc.callshield.data.model.BlockedCall
@@ -388,7 +389,11 @@ fun NumberDetailScreen(
                         }
                         if (databaseEntry.description.isNotEmpty()) {
                             Spacer(Modifier.height(8.dp))
-                            Text(databaseEntry.description, color = CatSubtext, style = MaterialTheme.typography.bodyMedium)
+                            Text(
+                                SourceDescriptions.readable(context, databaseEntry.description),
+                                color = CatSubtext,
+                                style = MaterialTheme.typography.bodyMedium,
+                            )
                         }
                     }
                 }

app/src/main/res/values-zh-rCN/strings.xml

@@ -1310,7 +1310,10 @@
     <string name="reasoning_hidden_number_headline">来电未附带电话号码。</string>
     <string name="reasoning_hidden_number_detail">已按你的“拦截未知号码”设置拦截。</string>
     <string name="reasoning_database_headline">此号码在 CallShield 垃圾号码库中。</string>
-    <string name="reasoning_type_on_file">记录类型：%1$s</string>
+    <string name="source_fcc_caller_id">FCC 投诉（针对来电号码）：%1$s</string>
+    <string name="source_fcc_callback">FCC 投诉（作为回拨号码）：%1$s</string>
+    <string name="source_fcc_unspecified">FCC 投诉：%1$s</string>
+    <string name="source_ftc_caller_id">FTC 投诉（针对来电号码）：%1$s</string>
     <string name="reasoning_db_prefix_headline">此号码与已确认的垃圾号码相邻。</string>
     <string name="reasoning_db_prefix_detail">除最后两位外，它与垃圾号码库中的号码完全相同，且号码库前缀扩展已开启。</string>
     <string name="reasoning_prefix_tag">前缀标记：%1$s</string>

app/src/main/res/values/strings.xml

@@ -1809,7 +1809,10 @@
     <string name="reasoning_hidden_number_headline">Call came in with no phone number attached.</string>
     <string name="reasoning_hidden_number_detail">Blocked by your \"block unknown numbers\" setting.</string>
     <string name="reasoning_database_headline">This number is in CallShield\'s spam database.</string>
-    <string name="reasoning_type_on_file">Type on file: %1$s</string>
+    <string name="source_fcc_caller_id">FCC complaints about the caller ID: %1$s</string>
+    <string name="source_fcc_callback">FCC complaints giving it as the number to call back: %1$s</string>
+    <string name="source_fcc_unspecified">FCC complaints: %1$s</string>
+    <string name="source_ftc_caller_id">FTC complaints about the caller ID: %1$s</string>
     <string name="reasoning_db_prefix_headline">This number sits next to confirmed spam numbers.</string>
     <string name="reasoning_db_prefix_detail">It shares all but its last two digits with numbers in the spam database, and database prefix expansion is on.</string>
     <string name="reasoning_prefix_tag">Prefix tag: %1$s</string>

app/src/test/java/com/sysadmindoc/callshield/data/SourceDescriptionsTest.kt

@@ -0,0 +1,62 @@
+package com.sysadmindoc.callshield.data
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import com.sysadmindoc.callshield.domain.model.BlockReasonCode
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Number details showed the importers' raw field names and the same complaint
+ * twice for bundled number +13152328257.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class SourceDescriptionsTest {
+    private val context: Context = ApplicationProvider.getApplicationContext()
+
+    // The stored description of +13152328257 in database v49.
+    private val stored =
+        "FCC: Unwanted Calls; FCC callback_business: Unwanted Calls (Live Voice); " +
+            "FCC caller_id: Unwanted Calls; FTC caller ID: Computer  & technical support"
+
+    @Test
+    fun `complaints read as words, one line per kind, without repeats`() {
+        assertEquals(
+            listOf(
+                "FCC complaints about the caller ID: Unwanted Calls",
+                "FCC complaints giving it as the number to call back: Unwanted Calls (Live Voice)",
+                "FTC complaints about the caller ID: Computer & technical support",
+            ),
+            SourceDescriptions.readable(context, stored).lines(),
+        )
+    }
+
+    @Test
+    fun `no raw field name survives, and formatting twice changes nothing`() {
+        val once = SourceDescriptions.readable(context, stored)
+
+        assertFalse(once, once.contains("caller_id") || once.contains("callback_business"))
+        assertEquals(once, SourceDescriptions.readable(context, once))
+    }
+
+    @Test
+    fun `other sources pass through once each`() {
+        assertEquals(
+            listOf("FCC complaints: Robocalls", "Community reported", "Saracroche: Opérateur"),
+            SourceDescriptions.readable(context, "FCC: Robocalls; Community reported; Saracroche: Opérateur; Community reported").lines(),
+        )
+        assertEquals("", SourceDescriptions.readable(context, ""))
+    }
+
+    @Test
+    fun `the block explanation lists the complaints instead of the raw text`() {
+        val reasoning = BlockReasoning.explain(context, reasonCode = BlockReasonCode.DATABASE, description = stored, confidence = 100)
+
+        assertEquals(SourceDescriptions.readable(context, stored).lines(), reasoning.bullets)
+    }
+}