android-sdd 1.0.0

package/skills/Developer Experience/Detekt/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: detekt
+description: >
+  Detekt static analysis for Kotlin Android projects.
+  Load this skill when setting up Detekt, configuring rules,
+  writing custom Detekt rules, suppressing false positives,
+  integrating Detekt into CI, or generating reports.
+---
+
+# Detekt
+
+## Overview
+Detekt is a static code analysis tool for Kotlin. It detects code smells, complexity issues, style violations, and potential bugs. Unlike Android Lint (which targets Android-specific patterns), Detekt focuses on general Kotlin code quality. Both should be used together.
+
+---
+
+## Core Principles
+
+- Detekt runs on **Kotlin source** — not bytecode; catches issues before compilation
+- Configure via **`detekt.yml`** — enable/disable rules, set thresholds
+- **Baseline** for existing codebases — suppress existing violations, only check new code
+- Run in **CI** — fail the build on new violations
+- **Type resolution** mode gives more accurate results but is slower
+
+---
+
+## Setup
+
+```kotlin
+// root build.gradle.kts
+plugins {
+    alias(libs.plugins.detekt) apply false
+}
+
+// app/build.gradle.kts (or in convention plugin)
+plugins {
+    alias(libs.plugins.detekt)
+}
+
+detekt {
+    config.setFrom(files("$rootDir/config/detekt/detekt.yml"))
+    baseline = file("$rootDir/config/detekt/baseline.xml")
+    buildUponDefaultConfig = true    // start from default, override in yml
+    allRules = false                 // don't enable all rules by default
+    autoCorrect = false              // set true to auto-fix style issues
+}
+
+dependencies {
+    detektPlugins(libs.detekt.formatting)   // ktlint-based formatting rules
+}
+```
+
+```toml
+# libs.versions.toml
+[versions]
+detekt = "1.23.6"
+
+[libraries]
+detekt-formatting = { module = "io.gitlab.arturbosch.detekt:detekt-formatting", version.ref = "detekt" }
+
+[plugins]
+detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
+```
+
+---
+
+## detekt.yml Configuration
+
+```yaml
+# config/detekt/detekt.yml
+
+build:
+  maxIssues: 0           # fail on any new issue
+
+complexity:
+  LongMethod:
+    threshold: 40        # max lines per function
+  LongParameterList:
+    functionThreshold: 6
+    constructorThreshold: 7
+  TooManyFunctions:
+    thresholdInFiles: 20
+    thresholdInClasses: 15
+  CyclomaticComplexMethod:
+    threshold: 15
+
+naming:
+  FunctionNaming:
+    functionPattern: '[a-z][a-zA-Z0-9]*'
+    excludes: ['**/test/**', '**/androidTest/**']
+  ClassNaming:
+    classPattern: '[A-Z][a-zA-Z0-9]*'
+  VariableNaming:
+    variablePattern: '[a-z][A-Za-z0-9]*'
+
+style:
+  MagicNumber:
+    active: true
+    ignoreNumbers: ['-1', '0', '1', '2']
+    ignoreHashCodeFunction: true
+    ignorePropertyDeclaration: true
+  WildcardImport:
+    active: true
+  UnusedPrivateMember:
+    active: true
+  ForbiddenComment:
+    active: true
+    values: ['FIXME:', 'STOPSHIP:']
+
+exceptions:
+  TooGenericExceptionCaught:
+    active: true
+    exceptionNames: ['Exception', 'Throwable']
+    allowedExceptionNameRegex: '_|(ignore|expected).*'
+  SwallowedException:
+    active: true
+
+coroutines:
+  GlobalCoroutineUsage:
+    active: true
+  RedundantSuspendModifier:
+    active: true
+  SuspendFunWithFlowReturnType:
+    active: true
+
+formatting:
+  MaximumLineLength:
+    maxLineLength: 120
+  NoUnusedImports:
+    active: true
+  TrailingCommaOnCallSite:
+    active: false
+```
+
+---
+
+## Running Detekt
+
+```bash
+# ✅ Run all checks
+./gradlew detekt
+
+# ✅ Run with type resolution (more accurate, slower)
+./gradlew detektMain
+
+# ✅ Auto-fix formatting issues
+./gradlew detekt --auto-correct
+
+# ✅ Generate HTML report
+./gradlew detekt
+# Report at: app/build/reports/detekt/detekt.html
+```
+
+---
+
+## Baseline (for existing projects)
+
+```bash
+# ✅ Generate baseline from current violations
+./gradlew detektBaseline
+
+# This creates baseline.xml with all current issues
+# Future runs only fail on NEW violations
+```
+
+---
+
+## Suppressing Violations
+
+```kotlin
+// ✅ Suppress a specific rule inline
+@Suppress("MagicNumber")
+val timeout = 30_000L
+
+// ✅ Suppress multiple rules
+@Suppress("LongMethod", "ComplexMethod")
+fun complexLegacyFunction() { ... }
+
+// ✅ Suppress in detekt.yml for entire paths
+style:
+  MagicNumber:
+    excludes: ['**/test/**', '**/androidTest/**', '**/Preview*.kt']
+```
+
+---
+
+## Custom Detekt Rule
+
+```kotlin
+// ✅ Custom rule — detect hardcoded strings in Compose
+class HardcodedStringInComposeRule(config: Config) : Rule(config) {
+
+    override val issue = Issue(
+        id = "HardcodedStringInCompose",
+        severity = Severity.Warning,
+        description = "Hardcoded strings in Compose should use string resources",
+        debt = Debt.FIVE_MINS
+    )
+
+    override fun visitCallExpression(expression: KtCallExpression) {
+        super.visitCallExpression(expression)
+
+        // Check if it's a Text() composable with a hardcoded string
+        if (expression.calleeExpression?.text == "Text") {
+            val firstArg = expression.valueArguments.firstOrNull()
+            val argText = firstArg?.getArgumentExpression()?.text
+            if (argText != null && argText.startsWith("\"")) {
+                report(CodeSmell(
+                    issue = issue,
+                    entity = Entity.from(expression),
+                    message = "Use stringResource() instead of hardcoded string: $argText"
+                ))
+            }
+        }
+    }
+}
+
+// Register in custom rule set provider
+class CustomRuleSetProvider : RuleSetProvider {
+    override val ruleSetId: String = "custom-rules"
+    override fun instance(config: Config) = RuleSet(
+        ruleSetId,
+        listOf(HardcodedStringInComposeRule(config))
+    )
+}
+```
+
+---
+
+## CI Integration
+
+```yaml
+# .github/workflows/quality.yml
+- name: Run Detekt
+  run: ./gradlew detekt
+
+- name: Upload Detekt report
+  if: failure()
+  uses: actions/upload-artifact@v3
+  with:
+    name: detekt-report
+    path: '**/build/reports/detekt/'
+```
+
+---
+
+## Detekt vs Lint
+
+| | Detekt | Android Lint |
+|---|---|---|
+| Target | Kotlin code quality | Android-specific issues |
+| Runs on | JVM, CI, pre-commit | Build, CI |
+| Custom rules | Kotlin DSL | PSI/UAST |
+| Auto-fix | ✅ (formatting) | Limited |
+| Best for | Code smells, complexity | Android anti-patterns |
+
+---
+
+## Anti-Patterns
+
+- Ignoring all violations with a baseline — baseline is for migration, not ongoing suppression
+- `allRules = true` — too noisy; causes over-suppression
+- Not running Detekt in CI — violations accumulate silently
+- Per-file `@Suppress` without a comment explaining why — future maintainers won't understand
+- Skipping `detekt-formatting` plugin — misses import order and whitespace issues
+
+---
+
+## Related Skills
+- `lint-rule` — Android Lint for Android-specific checks
+- `gradle` — build integration
+- `convention-plugin` — sharing Detekt config across modules

package/skills/Developer Experience/Lint Rule/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: lint-rule
+description: >
+  Custom Android Lint rules for enforcing project conventions.
+  Load this skill when writing custom Lint checks, detecting forbidden
+  patterns in code, enforcing naming conventions automatically,
+  or integrating custom rules into the build pipeline.
+---
+
+# Lint Rule
+
+## Overview
+Android Lint is a static analysis tool that inspects source code for bugs, style violations, and custom project conventions. You can write custom Lint rules to enforce patterns specific to your project — preventing anti-patterns before they reach code review.
+
+---
+
+## Core Principles
+
+- Custom rules run at **build time** — catch issues before they reach review
+- Rules target **PSI (Program Structure Interface)** — the AST of Kotlin/Java files
+- **UAST (Universal AST)** works for both Kotlin and Java — prefer it over PSI
+- Each rule has a unique **Issue ID** — used in `@SuppressLint` and baseline files
+- Rules are packaged in a separate **lint module** — consumed by the app module
+
+---
+
+## Module Setup
+
+```
+project/
+├── app/
+├── lint/                    # custom lint rules module
+│   ├── build.gradle.kts
+│   └── src/main/kotlin/
+│       └── com/example/lint/
+│           ├── MyDetector.kt
+│           └── MyIssueRegistry.kt
+```
+
+```kotlin
+// lint/build.gradle.kts
+plugins {
+    alias(libs.plugins.kotlin.jvm)
+}
+
+dependencies {
+    compileOnly(libs.lint.api)
+    compileOnly(libs.lint.checks)
+    testImplementation(libs.lint.tests)
+    testImplementation(libs.junit)
+}
+```
+
+```kotlin
+// app/build.gradle.kts
+dependencies {
+    lintChecks(project(":lint"))
+}
+```
+
+---
+
+## Basic Detector Structure
+
+```kotlin
+// ✅ Detector that finds a forbidden pattern
+class ForbiddenCallDetector : Detector(), Detector.UastScanners {
+
+    override fun getApplicableMethodNames(): List<String> = listOf("printStackTrace")
+
+    override fun visitMethodCall(
+        context: JavaContext,
+        node: UCallExpression,
+        method: PsiMethod
+    ) {
+        context.report(
+            issue = ISSUE,
+            scope = node,
+            location = context.getLocation(node),
+            message = "Use structured logging instead of `printStackTrace()`"
+        )
+    }
+
+    companion object {
+        val ISSUE = Issue.create(
+            id = "ForbiddenPrintStackTrace",
+            briefDescription = "Use structured logging",
+            explanation = """
+                `printStackTrace()` logs to stdout which is not captured by crash reporters.
+                Use the project's Logger instead.
+            """.trimIndent(),
+            category = Category.CORRECTNESS,
+            priority = 7,
+            severity = Severity.ERROR,
+            implementation = Implementation(
+                ForbiddenCallDetector::class.java,
+                Scope.JAVA_FILE_SCOPE
+            )
+        )
+    }
+}
+```
+
+---
+
+## Issue Registry
+
+```kotlin
+// ✅ Register all custom issues
+class MyIssueRegistry : IssueRegistry() {
+    override val issues: List<Issue> = listOf(
+        ForbiddenCallDetector.ISSUE,
+        DirectColorUsageDetector.ISSUE,
+        MissingTestTagDetector.ISSUE
+    )
+
+    override val api: Int = CURRENT_API
+    override val minApi: Int = 8
+}
+```
+
+```
+# lint/src/main/resources/META-INF/services/
+# File: com.android.tools.lint.client.api.IssueRegistry
+com.example.lint.MyIssueRegistry
+```
+
+---
+
+## Practical Examples
+
+```kotlin
+// ✅ Detect direct color usage (enforce design tokens)
+class DirectColorUsageDetector : ResourceXmlDetector() {
+
+    override fun getApplicableAttributes(): Collection<String> =
+        listOf("textColor", "background", "backgroundTint", "tint")
+
+    override fun visitAttribute(context: XmlContext, attribute: Attr) {
+        val value = attribute.value
+        if (value.startsWith("#") || value.startsWith("@android:color/")) {
+            context.report(
+                issue = ISSUE,
+                location = context.getLocation(attribute),
+                message = "Use design token colors instead of direct color values (`$value`)"
+            )
+        }
+    }
+
+    companion object {
+        val ISSUE = Issue.create(
+            id = "DirectColorUsage",
+            briefDescription = "Use design token colors",
+            explanation = "Direct color values bypass the design system. Use theme attributes.",
+            category = Category.CORRECTNESS,
+            priority = 6,
+            severity = Severity.WARNING,
+            implementation = Implementation(
+                DirectColorUsageDetector::class.java,
+                Scope.RESOURCE_FILE_SCOPE
+            )
+        )
+    }
+}
+
+// ✅ Detect GlobalScope usage
+class GlobalScopeDetector : Detector(), Detector.UastScanners {
+
+    override fun getApplicableReferenceNames(): List<String> = listOf("GlobalScope")
+
+    override fun visitReference(
+        context: JavaContext,
+        reference: UReferenceExpression,
+        referenced: PsiElement
+    ) {
+        context.report(
+            issue = ISSUE,
+            scope = reference,
+            location = context.getLocation(reference),
+            message = "Avoid `GlobalScope` — use `viewModelScope`, `lifecycleScope`, or an injected scope instead"
+        )
+    }
+
+    companion object {
+        val ISSUE = Issue.create(
+            id = "GlobalScopeUsage",
+            briefDescription = "Avoid GlobalScope",
+            explanation = "GlobalScope creates unstructured coroutines that leak and can't be cancelled.",
+            category = Category.CORRECTNESS,
+            priority = 8,
+            severity = Severity.ERROR,
+            implementation = Implementation(
+                GlobalScopeDetector::class.java,
+                Scope.JAVA_FILE_SCOPE
+            )
+        )
+    }
+}
+```
+
+---
+
+## Testing Lint Rules
+
+```kotlin
+// ✅ Test a custom lint rule
+class ForbiddenCallDetectorTest {
+
+    @Test
+    fun `detects printStackTrace call`() {
+        lint()
+            .files(
+                kotlin("""
+                    fun example() {
+                        Exception("test").printStackTrace()
+                    }
+                """).indented()
+            )
+            .issues(ForbiddenCallDetector.ISSUE)
+            .run()
+            .expect("""
+                src/test.kt:2: Error: Use structured logging instead of `printStackTrace()` [ForbiddenPrintStackTrace]
+                        Exception("test").printStackTrace()
+                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+                1 errors, 0 warnings
+            """.trimIndent())
+    }
+
+    @Test
+    fun `clean code passes`() {
+        lint()
+            .files(
+                kotlin("""
+                    fun example() {
+                        Logger.e("Something failed")
+                    }
+                """).indented()
+            )
+            .issues(ForbiddenCallDetector.ISSUE)
+            .run()
+            .expectClean()
+    }
+}
+```
+
+---
+
+## Suppressing Rules
+
+```kotlin
+// ✅ Suppress per call site when genuinely needed
+@SuppressLint("GlobalScopeUsage")
+fun legacyCode() {
+    GlobalScope.launch { /* unavoidable */ }
+}
+
+// ✅ Suppress in lint.xml (project-wide baseline)
+// lint.xml
+<lint>
+    <issue id="GlobalScopeUsage" severity="ignore">
+        <ignore path="src/legacy/**" />
+    </issue>
+</lint>
+```
+
+---
+
+## Anti-Patterns
+
+- Writing rules that are too strict — rules with too many false positives get suppressed everywhere
+- Not writing tests for lint rules — untested rules break silently on API changes
+- One giant detector class — one detector per concern
+- Severity `ERROR` for style issues — use `WARNING`; save `ERROR` for correctness issues
+- Forgetting to register the rule in `IssueRegistry` — rule silently never runs
+
+---
+
+## Related Skills
+- `detekt` — static analysis for Kotlin code style
+- `gradle` — integrating lint into the build pipeline
+- `convention-plugin` — sharing lint config across modules