po4yka/RIPDPI / .agents/skills/detekt-custom-rules
detekt-custom-rules
VerifiedRegister, activate, and test a custom detekt rule in :quality:detekt-rules. Use when adding a DI/privacy/suppression guardrail rule or debugging a false positive.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.8 KB |
SKILL.md
View on GitHub---
name: detekt-custom-rules
description: Register, activate, and test a custom detekt rule in :quality:detekt-rules. Use when adding a DI/privacy/suppression guardrail rule or debugging a false positive.
---
# Custom Detekt Rules
Custom rule set `diGuardrails` in module `:quality:detekt-rules`. Enforces DI, Hilt, suppression, and resolver-log privacy conventions at compile time.
## Existing Rules
`scripts/ci/check_harness_manifests.py` (`validate_factual_ground_truth`) mechanically checks that every rule registered in `RipDpiRuleSetProvider.kt` appears in this table -- omitting a rule here fails CI rather than silently drifting.
| Rule | What It Catches | Why |
|------|-----------------|-----|
| `InjectConstructorDefaultParameter` | Default values on `@Inject` constructor params | Hilt ignores defaults, causing silent behavior mismatch |
| `HiltViewModelApplicationContext` | `@ApplicationContext` in `@HiltViewModel` constructors | Forces narrower abstractions, improves testability |
| `DisallowNewSuppression` | `@Suppress` without an adjacent `ROADMAP-architecture-refactor` allowlist comment | Prevents new lint debt from becoming invisible |
| `NoResolverIpInLogs` | Resolver or upstream IP identifiers interpolated into log calls | Keeps user-visible network state out of logs |
## Module Structure
```
quality/detekt-rules/
src/main/kotlin/com/poyka/ripdpi/quality/detekt/
RipDpiRuleSetProvider.kt -- Registers all rules (id: "diGuardrails")
AnnotationMatchers.kt -- Shared helpers: hasAnnotation(), findAnnotation()
InjectConstructorDefaultParameter.kt
HiltViewModelApplicationContext.kt
DisallowNewSuppression.kt
NoResolverIpInLogs.kt
src/test/kotlin/com/poyka/ripdpi/quality/detekt/
InjectConstructorDefaultParameterTest.kt
HiltViewModelApplicationContextTest.kt
DisallowNewSuppressionTest.kt
NoResolverIpInLogsTest.kt
```
## Creating a New Rule
### Step 1: Write the Rule Class
Create `src/main/kotlin/com/poyka/ripdpi/quality/detekt/<YourRuleName>.kt`:
```kotlin
package com.poyka.ripdpi.quality.detekt
import io.gitlab.arturbosch.detekt.api.CodeSmell
import io.gitlab.arturbosch.detekt.api.Config
import io.gitlab.arturbosch.detekt.api.Debt
import io.gitlab.arturbosch.detekt.api.Entity
import io.gitlab.arturbosch.detekt.api.Issue
import io.gitlab.arturbosch.detekt.api.Rule
import io.gitlab.arturbosch.detekt.api.Severity
import org.jetbrains.kotlin.psi.KtClass
class YourRuleName(config: Config) : Rule(config) {
override val issue: Issue =
Issue(
id = "YourRuleName",
severity = Severity.Defect,
description = "One-line description of what this catches.",
debt = Debt.FIVE_MINS,
)
override fun visitClass(klass: KtClass) {
super.visitClass(klass)
// Use hasAnnotation() from AnnotationMatchers.kt
if (!klass.hasAnnotation("SomeAnnotation")) return
// Check condition and report
report(
CodeSmell(
issue = issue,
entity = Entity.from(klass),
message = "Actionable message: what to do instead.",
),
)
}
}
```
### Step 2: Register in RuleSetProvider
Add to `RipDpiRuleSetProvider.kt`:
```kotlin
override fun instance(config: Config): RuleSet =
RuleSet(
ruleSetId,
listOf(
InjectConstructorDefaultParameter(config),
HiltViewModelApplicationContext(config),
DisallowNewSuppression(config),
NoResolverIpInLogs(config),
YourRuleName(config), // <-- add here
),
)
```
### Step 3: Activate in detekt.yml
Add to `config/detekt/detekt.yml`:
```yaml
diGuardrails:
active: true
InjectConstructorDefaultParameter:
active: true
HiltViewModelApplicationContext:
active: true
NoResolverIpInLogs:
active: true
YourRuleName: # <-- add here
active: true
```
`DisallowNewSuppression` is registered in `RipDpiRuleSetProvider` and inherits the active `diGuardrails` rule-set setting; it has no per-rule override in the current config.
### Step 4: Write Tests
Create `src/test/kotlin/com/poyka/ripdpi/quality/detekt/<YourRuleName>Test.kt`:
```kotlin
package com.poyka.ripdpi.quality.detekt
import io.gitlab.arturbosch.detekt.api.Config
import io.gitlab.arturbosch.detekt.test.compileAndLint
import org.junit.jupiter.api.Test
import kotlin.test.assertEquals
class YourRuleNameTest {
private val rule = YourRuleName(Config.empty)
@Test
fun `reports violation on annotated class`() {
val code = """
@SomeAnnotation
class Bad { /* violating pattern */ }
""".trimIndent()
val findings = rule.compileAndLint(code)
assertEquals(1, findings.size)
}
@Test
fun `allows non-annotated class`() {
val code = """
class Fine { /* same pattern but no annotation */ }
""".trimIndent()
val findings = rule.compileAndLint(code)
assertEquals(0, findings.size)
}
}
```
Cover: positive detection, negative (no false positive), edge cases (primary vs secondary constructors, nested classes).
## Annotation Matching
Use the shared helpers from `AnnotationMatchers.kt`:
```kotlin
// Check if a KtAnnotated element has an annotation by simple name
klass.hasAnnotation("HiltViewModel") // matches @HiltViewModel
constructor.hasAnnotation("Inject") // matches @Inject
// Find the annotation entry (for Entity.from targeting)
parameter.findAnnotation("ApplicationContext") // returns KtAnnotationEntry?
```
**Important:** These match by **simple name**, not fully-qualified name. `hasAnnotation("Inject")` matches both `@javax.inject.Inject` and `@com.google.inject.Inject`.
## Common PSI Visitor Methods
| Method | When To Use |
|--------|-------------|
| `visitClass(KtClass)` | Checking class-level patterns |
| `visitPrimaryConstructor(KtPrimaryConstructor)` | Constructor parameter rules |
| `visitSecondaryConstructor(KtSecondaryConstructor)` | Must handle alongside primary |
| `visitNamedFunction(KtNamedFunction)` | Function-level rules |
| `visitProperty(KtProperty)` | Property declaration rules |
Use `getStrictParentOfType<KtClassOrObject>()` to navigate from a constructor to its owning class.
## Convention Plugin
`ripdpi.android.detekt.gradle.kts` configures detekt for all modules:
- **Parallel:** true
- **Config:** `config/detekt/detekt.yml`
- **Reports:** HTML + XML
- **JVM target:** 17
- **Excludes:** `**/build/**`, `**/generated/**`, `**/jni/**`, `**/cpp/**`
- **Baseline:** Auto-detected from `detekt-baseline.xml` if present in module
- **Plugin deps:** Custom rules (`:quality:detekt-rules`) + `detekt-compose-rules`
Run detekt:
```bash
./gradlew staticAnalysis # detekt + ktlint + lint
./gradlew detektDebug # detekt only (single variant)
```
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| Forgetting to register in `RipDpiRuleSetProvider` | Rule exists but never runs. Add to the `listOf(...)` in `instance()`. |
| Using FQN for annotation matching | `hasAnnotation("javax.inject.Inject")` won't match. Use simple name: `"Inject"`. |
| Not activating in `detekt.yml` | Rule is registered but inactive. Add `YourRuleName: { active: true }` under `diGuardrails:`. |
| Testing only primary constructors | Many rules apply to both primary and secondary. Override both visitor methods. |
| Reporting on wrong entity | Use `Entity.from(specificElement)` not `Entity.from(constructor)` -- highlights the exact problem location. |
| Missing `super.visitX()` call | Always call `super.visitPrimaryConstructor(constructor)` etc. to continue traversal. |
## See Also
- `config/detekt/detekt.yml` -- Full detekt configuration
- `build-logic/convention/src/main/kotlin/ripdpi.android.detekt.gradle.kts` -- Convention plugin
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |