create-cmp-cli 0.8.0 → 0.10.0

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewSemanticsJson.kt

@@ -19,7 +19,8 @@ import kotlin.math.roundToInt
  * inspector contract (schemaVersion 1, source "headless-jvm"). Every node carries pixel,
  * root-relative `bounds` and a (possibly empty) `children` array; testTag / text /
  * contentDescription / designToken are nullable; `role` / `clickable` / `disabled` are the
- * additive interaction fields.
+ * additive interaction fields, and `size` is the additive full-composed-size field (see
+ * [sizeJson]).
  *
  * This dumper reads THIS project's [DesignTokenKey], so the resolved design tokens the
  * component kit self-reports (Modifier.designToken) appear in the dump — which is what
@@ -54,10 +55,22 @@ object PreviewSemanticsJson {
         put("clickable", JsonPrimitive(node.config.contains(SemanticsActions.OnClick)))
         put("disabled", JsonPrimitive(node.config.contains(SemanticsProperties.Disabled)))
         put("bounds", node.boundsJson())
+        put("size", node.sizeJson())
         put("designToken", node.designTokenJson())
         put("children", buildJsonArray { node.children.forEach { add(nodeToJson(it)) } })
     }
 
+    /**
+     * Full composed (UNCLIPPED) size. `bounds` is the visible slice after ancestor clipping —
+     * a scroll container's fold truncates it — while `size` is what the node actually
+     * measures. Additive contract field (consumers treat it as optional); the a11y audit
+     * judges touch targets on it so a fold-clipped list row is never a false violation.
+     */
+    private fun SemanticsNode.sizeJson(): JsonObject = buildJsonObject {
+        put("width", JsonPrimitive(size.width))
+        put("height", JsonPrimitive(size.height))
+    }
+
     private fun SemanticsNode.boundsJson(): JsonObject {
         val rect = boundsInRoot
         return buildJsonObject {

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -28,16 +28,23 @@ class ArchitectureConformanceTest {
         file.readLines().filter { it.trimStart().startsWith("import ") }.map { it.trim() }
 
     /**
-     * Source lines with comment lines stripped. Layer-boundary rules scan these for BOTH
-     * `import x.y.` statements AND fully-qualified inline references (`x.y.Type(...)`) —
-     * import-only matching leaves a one-edit evasion open: delete the import, qualify the
-     * name inline, and the gate goes green while the violation remains.
+     * Source lines with comments stripped — whole comment lines AND trailing `// …` tails
+     * (a `(?<!:)` guard keeps `https://` URLs inside strings intact). Layer-boundary rules
+     * scan these for BOTH `import x.y.` statements AND fully-qualified inline references
+     * (`x.y.Type(...)`) — import-only matching leaves a one-edit evasion open: delete the
+     * import, qualify the name inline, and the gate goes green while the violation remains.
+     * Stripping trailing comments closes the inverse hole: prose like
+     * `get() // wires com.app.data.ItemRepositoryImpl` must not fail a boundary gate.
      */
+    private val trailingLineComment = Regex("""(?<!:)//.*""")
+
     private fun nonCommentLines(file: File): List<String> =
-        file.readLines().filterNot {
-            val t = it.trimStart()
-            t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")
-        }
+        file.readLines()
+            .filterNot {
+                val t = it.trimStart()
+                t.startsWith("//") || t.startsWith("*") || t.startsWith("/*")
+            }
+            .map { it.replace(trailingLineComment, "") }
 
     private fun bannedReference(file: File, banned: List<String>): Boolean =
         nonCommentLines(file).any { line -> banned.any { line.contains(it) } }
@@ -113,8 +120,26 @@ class ArchitectureConformanceTest {
     }
 
     // SPEC: ARCH-04
+    // Component-derived tags (component-system-deep-dive.md §6.4) count as tag provenance:
+    // a screen built entirely from registry components (ScreenColumn/AppHeader/
+    // ContentStateContainer/…) is automation-reachable through the tags THOSE components
+    // emit from their required `screenTag` parameter, even with no literal `testTag` of its
+    // own. The acceptance is narrow by design (mitigates the risk table's sloppy-scan
+    // concern): `screenTag\s*=` in a call-argument position AND the file actually imports
+    // from `presentation.components` — a file that merely contains the substring
+    // "screenTag" in a comment, or that never touches the registry, still fails.
+    private val screenTagArgument = Regex("""screenTag\s*=""")
+
+    private fun hasTagProvenance(file: File): Boolean {
+        val text = file.readText()
+        val importsComponents = text.lines().any {
+            it.trimStart().startsWith("import ") && it.contains(".presentation.components.")
+        }
+        return text.contains("testTag") || (importsComponents && screenTagArgument.containsMatchIn(text))
+    }
+
     @Test
-    fun `ARCH-04 every feature composable file declares a testTag`() {
+    fun `ARCH-04 every feature composable file is automation-reachable - literal testTag or screenTag provenance`() {
         // Scoped by CONTENT (contains @Composable), not by *Screen.kt filename: real apps
         // split features into Screen.kt (often ViewModel-only) and Content.kt (the UI).
         // Filename scoping produced both false negatives (untagged FooContent.kt slid
@@ -123,14 +148,36 @@ class ArchitectureConformanceTest {
             .filter { inPresentationFeatureDir(it) }
             .filterNot { under(it, "components") || under(it, "navigation") || under(it, "theme") }
             .filter { it.readText().contains("@Composable") }
-            .filterNot { it.readText().contains("testTag") }
+            .filterNot { hasTagProvenance(it) }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
                 "ARCH-04", "every feature UI file is automation-reachable: files containing a " +
-                    "@Composable declare at least one testTag.",
+                    "@Composable declare at least one literal testTag OR pass screenTag = to a " +
+                    "registry component imported from presentation.components.",
+                offenders,
+                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the file's key nodes, " +
+                    "or compose it from registry components (e.g. ScreenColumn(screenTag = \"<feature>\") { … }).",
+            )
+        )
+    }
+
+    // SPEC: ARCH-11
+    @Test
+    fun `ARCH-11 screens present loading through the components registry, never a hand-rolled indicator`() {
+        val banned = listOf("CircularProgressIndicator", "LinearProgressIndicator")
+        val offenders = sources(commonMain)
+            .filter { inPresentationFeatureDir(it) }
+            .filterNot { under(it, "components") || under(it, "navigation") || under(it, "theme") }
+            .filter { bannedReference(it, banned) }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-11", "screens never reference CircularProgressIndicator/LinearProgressIndicator " +
+                    "directly — loading is presented through ContentStateContainer/ContentStateDefaults.",
                 offenders,
-                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the file's key nodes.",
+                "bind the screen's loading arm to ContentStateContainer(state = …, screenTag = …) instead " +
+                    "of drawing a progress indicator by hand (see the exemplar HomeScreen).",
             )
         )
     }
@@ -141,7 +188,7 @@ class ArchitectureConformanceTest {
         val colorLiteral = Regex("""Color\(0x""")
         val offenders = sources(commonMain)
             .filterNot { under(it, "theme") }
-            .filter { colorLiteral.containsMatchIn(it.readText()) }
+            .filter { file -> nonCommentLines(file).any { colorLiteral.containsMatchIn(it) } }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(
@@ -152,6 +199,185 @@ class ArchitectureConformanceTest {
         )
     }
 
+    /**
+     * Each `suspend fun` declaration in [file] as one whitespace-normalized signature —
+     * from the keyword through its balanced parameter list to the end of that line, so a
+     * multiline (trailing-comma style) signature is judged by its return type, not by
+     * whichever fragment happens to share a line with `suspend fun`.
+     */
+    private fun suspendFunSignatures(file: File): List<String> {
+        val text = nonCommentLines(file).joinToString("\n")
+        val signatures = mutableListOf<String>()
+        var start = text.indexOf("suspend fun")
+        while (start >= 0) {
+            val open = text.indexOf('(', start)
+            if (open == -1) break
+            var depth = 0
+            var i = open
+            while (i < text.length) {
+                val c = text[i]
+                if (c == '(') depth += 1
+                if (c == ')') {
+                    depth -= 1
+                    if (depth == 0) break
+                }
+                i += 1
+            }
+            val end = text.indexOf('\n', i).let { if (it == -1) text.length else it }
+            signatures.add(text.substring(start, end).replace(Regex("\\s+"), " ").trim())
+            start = text.indexOf("suspend fun", end)
+        }
+        return signatures
+    }
+
+    // SPEC: ARCH-06
+    @Test
+    fun `ARCH-06 repository interfaces return AppResult - exceptions never cross the boundary`() {
+        val offenders = sources(commonMain)
+            .filter { under(it, "domain") && under(it, "repository") }
+            .flatMap { file ->
+                suspendFunSignatures(file)
+                    .filterNot { it.contains(": AppResult<") }
+                    .map { "${file.path} — $it" }
+            }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-06", "every one-shot repository operation (suspend fun) declares an AppResult<…> " +
+                    "return type — failures cross the data boundary as typed DomainError values, never as exceptions.",
+                offenders,
+                "return AppResult<T> and translate exceptions inside the data implementation via suspendRunCatching.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-07
+    @Test
+    fun `ARCH-07 ViewModels contain no exception handling`() {
+        // Syntactic forms only (`try {`, `catch (`, `runCatching`) — a bare-word scan would
+        // false-positive on user-facing copy like "…try again." inside the ViewModel's strings.
+        val exceptionHandling = Regex("""\btry\s*\{|\bcatch\s*[({]|\brunCatching\b""")
+        val offenders = sources(commonMain)
+            .filter { under(it, "presentation") && it.name.endsWith("ViewModel.kt") }
+            .filter { file -> nonCommentLines(file).any { exceptionHandling.containsMatchIn(it) } }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-07", "ViewModels contain no try/catch/runCatching — they fold over AppResult " +
+                    "and map DomainError kinds to user copy; exception translation is the data layer's job.",
+                offenders,
+                "remove the exception handling; `when` over the use case's AppResult instead (see the exemplar ViewModel).",
+            )
+        )
+    }
+
+    // SPEC: ARCH-08
+    @Test
+    fun `ARCH-08 the data layer's only catch mechanism is suspendRunCatching with its cancellation guard`() {
+        val helperName = "AppResultCatching.kt"
+        val catching = Regex("""\bcatch\s*\(|\brunCatching\b""")
+        val dataFiles = sources(commonMain).filter { under(it, "data") }
+
+        val offenders = dataFiles
+            .filterNot { it.name == helperName }
+            .filter { file -> nonCommentLines(file).any { catching.containsMatchIn(it) } }
+            .map { it.path }
+            .toMutableList()
+
+        // The helper itself must keep the guard that makes the convention safe:
+        // CancellationException is rethrown, never mapped to a Failure.
+        val helper = dataFiles.firstOrNull { it.name == helperName }
+        if (helper != null) {
+            val text = helper.readText()
+            if (!text.contains("catch (e: CancellationException)") || !text.contains("throw e")) {
+                offenders.add("${helper.path} (the CancellationException rethrow guard is missing)")
+            }
+        }
+
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-08", "the ONLY exception-catching mechanism in the data layer is the shared " +
+                    "suspendRunCatching helper ($helperName), which always rethrows CancellationException — " +
+                    "ad-hoc catch blocks can silently swallow cancellation.",
+                offenders,
+                "wrap the I/O in suspendRunCatching { … } (with a mapError classifier) instead of catching directly.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-09
+    @Test
+    fun `ARCH-09 data never references presentation or di`() {
+        val offenders = sources(commonMain)
+            .filter { under(it, "data") }
+            .filter { bannedReference(it, listOf("__PACKAGE__.presentation.", "__PACKAGE__.di.")) }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-09", "data serves domain contracts — it never references presentation or di " +
+                    "(neither imports nor fully-qualified inline names).",
+                offenders,
+                "move the presentation/di-touching code out of data; data implements domain's repository " +
+                    "interfaces and stops there.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-10
+    @Test
+    fun `ARCH-10 core is leaf utility code - imports domain at most`() {
+        val banned = listOf("__PACKAGE__.presentation.", "__PACKAGE__.data.", "__PACKAGE__.di.")
+        val offenders = sources(commonMain)
+            .filter { under(it, "core") }
+            .filter { bannedReference(it, banned) }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-10", "core is leaf utility code, importable by every other layer — it references " +
+                    "nothing in presentation, data, or di (neither imports nor fully-qualified inline names).",
+                offenders,
+                "move the app-layer-touching code out of core; core stays a leaf (domain types at most).",
+            )
+        )
+    }
+
+    // SPEC: ARCH-12
+    @Test
+    fun `ARCH-12 sample fixtures never cross into production wiring`() {
+        // The UI-first pattern's hazard gate. A stateless screen may default its own state
+        // parameter to a `sample*` fixture — that same-file default IS the preview seam —
+        // and the preview registry / stories / tests (desktopMain, commonTest) render it
+        // freely. But the moment ANOTHER commonMain file references the fixture (a nav
+        // host resolving entities from sample data, a repository seeding from it), fake
+        // data is driving production behavior. Proven drift: the Fuelled dogfood run's
+        // AppNavHost read `sampleFoods.firstOrNull { it.id == foodId }` for a real route.
+        val sampleDecl = Regex("""\bval\s+(sample[A-Z][A-Za-z0-9]*)""")
+        val declarations = mutableMapOf<String, File>() // symbol -> declaring file
+        for (file in sources(commonMain)) {
+            for (m in sampleDecl.findAll(file.readText())) declarations[m.groupValues[1]] = file
+        }
+        if (declarations.isEmpty()) return
+        val offenders = mutableListOf<String>()
+        for (file in sources(commonMain)) {
+            val lines = nonCommentLines(file)
+            for ((symbol, declaring) in declarations) {
+                if (file == declaring) continue
+                if (lines.any { Regex("""\b$symbol\b""").containsMatchIn(it) }) {
+                    offenders.add("${file.path} (references $symbol from ${declaring.name})")
+                }
+            }
+        }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-12", "a sample*/fixture symbol is never referenced outside its declaring file, " +
+                    "the preview registry, or test sources — sample data is a preview seam, not " +
+                    "production wiring.",
+                offenders.distinct(),
+                "wire the real path (repository → use case → ViewModel) and keep the sample only as " +
+                    "the stateless screen's default parameter.",
+            )
+        )
+    }
+
     // SPEC: SHELL-05
     @Test
     fun `SHELL-05 every non-shell nav destination wraps its content in BaseScreen`() {
@@ -159,9 +385,17 @@ class ArchitectureConformanceTest {
         // insets at all (bare Column at the nav layer) passes that rule while rendering
         // under the status bar. Tab screens are exempt — AppShell wraps them — so the rule
         // targets exactly the destinations registered directly on the NavHost.
-        val navHost = sources(commonMain).firstOrNull { it.name == "AppNavHost.kt" } ?: return
+        // Filename first; a renamed nav host is still found by content (the `composable(`
+        // registrations this rule parses) so the gate cannot go silently vacuous.
+        val navHost = sources(commonMain).firstOrNull { it.name == "AppNavHost.kt" }
+            ?: sources(commonMain).firstOrNull { under(it, "navigation") && it.readText().contains("composable(") }
+            ?: return
         val text = navHost.readText()
-        val screenCall = Regex("""([A-Z][A-Za-z0-9]*Screen)\s*\(""")
+        // Both destination shapes: the plain `XScreen(...)` AND the UI-first seam's
+        // VM-backed `XRoute(...)` wrapper — keying on `Screen(` alone left every *Route
+        // destination uninspected, passing the gate vacuously (dogfood finding: the
+        // invariant held in Fuelled, but only by convention, not because this asserted it).
+        val screenCall = Regex("""([A-Z][A-Za-z0-9]*(?:Screen|Route))\s*\(""")
         // A call with only a trailing lambda has no paren — `BaseScreen { … }` — so match both.
         val baseScreenCall = Regex("""BaseScreen\s*[({]""")
         val allSources = sources(commonMain)
@@ -201,7 +435,7 @@ class ArchitectureConformanceTest {
         val offenders = sources(commonMain)
             .filterNot { under(it, "components") }
             .filterNot { under(it, "navigation") }
-            .filter { insetApi.containsMatchIn(it.readText()) }
+            .filter { file -> nonCommentLines(file).any { insetApi.containsMatchIn(it) } }
             .map { it.path }
         if (offenders.isNotEmpty()) fail(
             violation(

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ComponentConformanceTest.kt

@@ -0,0 +1,84 @@
+package __PACKAGE__.conformance
+
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.assertHeightIsAtLeast
+import androidx.compose.ui.test.assertWidthIsAtLeast
+import androidx.compose.ui.test.hasTestTag
+import androidx.compose.ui.test.hasText
+import androidx.compose.ui.test.onNodeWithTag
+import androidx.compose.ui.test.runComposeUiTest
+import androidx.compose.ui.unit.dp
+import __PACKAGE__.domain.model.DomainError
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.home.HomeViewModel
+import __PACKAGE__.testing.awaitNode
+import __PACKAGE__.testing.fakes.FakeItemRepository
+import kotlin.test.Test
+
+/**
+ * The COMP clauses (`specs/app-base.spec.md`) as executable checks — the component
+ * vocabulary's runtime contract, proven against the exemplar screen the same way the
+ * ARCH/SHELL conformance gates prove the architecture. Component substructure/tag
+ * stability is additionally pinned by the golden-tree baseline (`qa/golden/`); this class
+ * proves the STATE/A11Y contract every registry consumer inherits for free.
+ */
+@OptIn(ExperimentalTestApi::class)
+class ComponentConformanceTest {
+
+    // SPEC: COMP-01
+    @Test
+    fun `a failed load is presented by ContentStateContainer with the screen-derived error tag`() = runComposeUiTest {
+        val repository = FakeItemRepository().apply { failure = DomainError.Network }
+        setContent {
+            MaterialTheme {
+                HomeScreen(onItemClick = {}, viewModel = HomeViewModel(GetItemsUseCase(repository)))
+            }
+        }
+        awaitNode(hasTestTag("home_error"))
+    }
+
+    // SPEC: COMP-01
+    @Test
+    fun `a zero-item load is presented by ContentStateContainer with the screen-derived empty tag`() = runComposeUiTest {
+        val repository = FakeItemRepository().apply { items = emptyList() }
+        setContent {
+            MaterialTheme {
+                HomeScreen(onItemClick = {}, viewModel = HomeViewModel(GetItemsUseCase(repository)))
+            }
+        }
+        awaitNode(hasTestTag("home_empty"))
+    }
+
+    // SPEC: COMP-02
+    @Test
+    fun `a recoverable error renders a retry control of at least 48dp`() = runComposeUiTest {
+        val repository = FakeItemRepository().apply { failure = DomainError.Network }
+        setContent {
+            MaterialTheme {
+                HomeScreen(onItemClick = {}, viewModel = HomeViewModel(GetItemsUseCase(repository)))
+            }
+        }
+        awaitNode(hasTestTag("home_retry"))
+        onNodeWithTag("home_retry")
+            .assertWidthIsAtLeast(48.dp)
+            .assertHeightIsAtLeast(48.dp)
+    }
+
+    // SPEC: COMP-03
+    @Test
+    fun `every ListItemCard row clears the 48dp minimum pointer target`() = runComposeUiTest {
+        val repository = FakeItemRepository().apply {
+            items = listOf(Item(id = "1", title = "Row", subtitle = "sub"))
+        }
+        setContent {
+            MaterialTheme {
+                HomeScreen(onItemClick = {}, viewModel = HomeViewModel(GetItemsUseCase(repository)))
+            }
+        }
+        awaitNode(hasText("Row"))
+        onNodeWithTag("home_item_1").assertHeightIsAtLeast(48.dp)
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/presentation/home/HomeScreenTest.kt

@@ -10,6 +10,7 @@ import androidx.compose.ui.test.onFirst
 import androidx.compose.ui.test.onNodeWithTag
 import androidx.compose.ui.test.performClick
 import androidx.compose.ui.test.runComposeUiTest
+import __PACKAGE__.domain.model.DomainError
 import __PACKAGE__.domain.model.Item
 import __PACKAGE__.domain.usecase.GetItemsUseCase
 import __PACKAGE__.testing.awaitNode
@@ -47,16 +48,27 @@ class HomeScreenTest {
 
     // SPEC: HOME-03
     @Test
-    fun `shows the error message when loading fails`() = runComposeUiTest {
-        repository.shouldFail = true
-        repository.failureMessage = "network down"
+    fun `shows presentation-mapped error copy when loading fails`() = runComposeUiTest {
+        repository.failure = DomainError.Network
 
         setContent {
             MaterialTheme { HomeScreen(onItemClick = {}, viewModel = viewModel()) }
         }
 
         awaitNode(hasTestTag("home_error"))
-        onAllNodesWithText("network down").assertCountEquals(1)
+        onAllNodesWithText(DomainError.Network.toUserMessage()).assertCountEquals(1)
+    }
+
+    // SPEC: HOME-07
+    @Test
+    fun `shows the empty state when the repository returns no items`() = runComposeUiTest {
+        repository.items = emptyList()
+
+        setContent {
+            MaterialTheme { HomeScreen(onItemClick = {}, viewModel = viewModel()) }
+        }
+
+        awaitNode(hasTestTag("home_empty"))
     }
 
     // SPEC: HOME-05
@@ -74,4 +86,24 @@ class HomeScreenTest {
         waitUntil(timeoutMillis = 5_000) { clickedId != null }
         kotlin.test.assertEquals("item-42", clickedId)
     }
+
+    // SPEC: HOME-04
+    @Test
+    fun `tapping retry after a failure reloads and shows recovered items`() = runComposeUiTest {
+        repository.failure = DomainError.Network
+        val vm = viewModel()
+
+        setContent {
+            MaterialTheme { HomeScreen(onItemClick = {}, viewModel = vm) }
+        }
+
+        awaitNode(hasTestTag("home_error"))
+        onNodeWithTag("home_retry", useUnmergedTree = true).assertExists()
+
+        repository.failure = null
+        repository.items = listOf(Item(id = "1", title = "Recovered", subtitle = "sub"))
+        onNodeWithTag("home_retry").performClick()
+
+        awaitNode(hasText("Recovered"))
+    }
 }