Merge pull request #1 from NordCoderd/reversed-package-rules

1.0.7 added many rules and supression mechanism

Author: NordCoderd

.gitignore

@@ -45,3 +45,6 @@ bin/
 
 ### Mac OS ###
 .DS_Store
+.grepai/
+.claude
+konsist-sources/

AGENTS.md

@@ -0,0 +1,67 @@
+# Spring Boot Code Guard
+
+Konsist-based static analysis library for Spring Boot. Rules run as JUnit 5 tests. Kotlin + Gradle (Kotlin DSL), JVM 17. Published to Maven Central as `dev.protsenko:spring-boot-code-guard`.
+
+## Tools (mandatory)
+
+- **File & coding tasks**: use the **mcpc idea** tools (skill: /skill:mcpc-idea-strict-workflow) for every read, edit, create, rename, reformat, inspection, build, and run operation — do not use generic shell fallbacks when an mcpc @idea equivalent exists.
+- **Project lookup (when mcpc failed)**: use the **GrepAI** skills (`grepai search`, `grepai trace callers|callees|graph`, `grepai status`) for all code search, symbol discovery, and call-graph questions.
+
+## Layout
+
+```
+src/main/kotlin/dev/protsenko/codeguard/
+  core/                 # SpringBootRule, DSL entry, suppression, RuleBuilder
+  rules/{general,jpa,naming,packages,web}/   # rule objects + DSL contexts
+src/test/kotlin/
+  dev/protsenko/codeguard/coverage/   # violation tests per rule group
+  fixtures/violations/                # fixture classes triggered by tests
+```
+
+Entry point: `springBootRules { }.verify()` (`core/SpringBootRulesConfiguration.kt`).
+
+## Rule anatomy
+
+Each rule is an `object : SpringBootRule` with `description`, `suppressKey`, `verify(scope)`. Per-class silence: `@Suppress("CodeGuard:<key>")`. DSL-wide opt-out: `exclude("CodeGuard:<key>")`.
+
+## Adding a new rule — mandatory checklist
+
+Follow every step in order. Do not skip.
+
+### 1. TDD — fixtures and tests first (use `/simplify` skill after)
+
+Use `/skill:mcpc-idea-strict-workflow` to create fixture classes under `src/test/kotlin/fixtures/violations/<category>/<rule>/`:
+- `*Negative.kt` — class that triggers the violation (one per interesting failure case)
+- `*Positive.kt` — class that must pass (one per interesting pass case)
+
+Then add test methods to the matching `*ViolationTest.kt` in `src/test/kotlin/dev/protsenko/codeguard/coverage/`. Each negative test must assert the exact error message. Each positive test just calls `rule.verify(scope)` without `assertFailsWith`.
+
+Typical cases to cover per rule:
+- Wrong stereotype alone in the constrained location → fail
+- Correct stereotype alone → pass
+- Correct stereotype with file-level helpers in same file → pass
+- Unannotated class alone in constrained location → fail
+
+### 2. Implement the rule
+
+Add the rule `object` to the relevant `*Rules.kt` in `src/main/kotlin/.../rules/<category>/`. Use `hasAnnotationWithName(SpringAnnotations.*)` (not `hasAnnotationOf`). Group by `containingFile` when file-level helper exemptions are needed.
+
+### 3. Register in `all*Rules` list
+
+Every `*Rules.kt` file exposes a `val all*Rules: List<SpringBootRule>` at the bottom. Add the new rule there. `AllRulesTest` asserts exact counts — update `allPackageRules contains N rules` (or equivalent) to match.
+
+### 4. Expose in DSL context and `AllRulesTest` individual block
+
+Add a DSL function to the matching `*RuleContext.kt`. Then add the call to the `withIndividual` block in `AllRulesTest.kt` alongside existing peers (e.g. `entitiesInEntityPackage()`).
+
+### 5. Register in `UsageExampleTest`
+
+Add the new DSL call next to its category peers in `src/test/kotlin/dev/protsenko/codeguard/usage/UsageExampleTest.kt`.
+
+### 6. Update README.md
+
+Add one bullet to the matching section in `README.md` under `## Rule Set`. Format: `` - `CodeGuard:<key>`: <what it enforces and why>. Exception: <if any>. ``
+
+### 7. Run `./gradlew codeBaseline`
+
+Must pass clean: tests + detekt + 90% coverage floor.

README.md

@@ -11,7 +11,7 @@ Maven Central: https://central.sonatype.com/artifact/dev.protsenko/spring-boot-c
 Add dependency to your `build.gradle.kts` or `build.gradle`:
 
 ```kotlin
-implementation("dev.protsenko:spring-boot-code-guard:1.0.4")
+implementation("dev.protsenko:spring-boot-code-guard:1.0.7")
 ```
 
 ## Usage
@@ -150,6 +150,13 @@ Passing an unknown key throws an error listing all registered rule keys. Excludi
 - `CodeGuard:propertiesValidation`: `@ConfigurationProperties` classes must reside in a `..property..` package segment.
 - `CodeGuard:configurationPropertiesPrefixKebabCase`: `@ConfigurationProperties` prefixes must use lowercase kebab-case segments separated by dots, such as `app.mail` or `app-mail.client`.
 - `CodeGuard:entityPackage`: `@Entity` classes must reside in a `..domain..` or `..entity..` package segment.
+- `CodeGuard:onlyServicesInServicePackage`: Only `@Service` classes may reside in a `..service..` package segment — other stereotypes (`@Component`, `@Repository`, etc.) and plain classes must not be placed there. Exception: non-`@Service` classes declared in the same file as a `@Service` class are treated as file-level helpers and are permitted; nested helper classes are ignored.
+- `CodeGuard:onlyEntitiesInEntityPackage`: Only `@Entity` classes may reside in `..domain..` or `..entity..` package segments — non-entity stereotypes and plain classes must not be placed there. Exception: JPA `@MappedSuperclass` and `@Embeddable` types are also permitted, classes referenced from an entity's `@IdClass` are permitted, and non-`@Entity` classes declared in the same file as an `@Entity` class or a class inheriting from `@Entity` are treated as file-level helpers and are permitted.
+- `CodeGuard:onlyControllersInControllerPackage`: Only `@Controller`/`@RestController` classes may reside in `..controller..` or `..web..` package segments — other stereotypes and plain classes must not be placed there. Exception: non-controller classes declared in the same file as a controller are treated as file-level helpers and are permitted.
+- `CodeGuard:onlyConfigurationsInConfigPackage`: Only `@Configuration`, `@ControllerAdvice`, and `@RestControllerAdvice` classes may reside in `..config..` or `..configuration..` package segments — other stereotypes and plain classes must not be placed there. Exception: other classes declared in the same file as one of these allowed types are treated as file-level helpers and are permitted.
+- `CodeGuard:onlyPropertiesInPropertyPackage`: Only `@ConfigurationProperties` classes may reside in `..property..` package segments — other stereotypes and plain classes must not be placed there. Exception: non-`@ConfigurationProperties` classes declared in the same file as a `@ConfigurationProperties` class are treated as file-level helpers and are permitted.
+- `CodeGuard:repositoryPackage`: `@Repository` classes and Spring Data repository interfaces (e.g. extending `JpaRepository`) must reside in a `..repository..` package segment.
+- `CodeGuard:onlyRepositoriesInRepositoryPackage`: Only `@Repository` classes may reside in `..repository..` package segments — other stereotypes and plain classes must not be placed there. Exception: non-`@Repository` classes declared in the same file as a `@Repository` class are treated as file-level helpers and are permitted.
 
 ### Web
 

build.gradle.kts

@@ -1,5 +1,6 @@
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.SourcesJar
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
     kotlin("jvm") version "2.3.0"
@@ -10,7 +11,7 @@ plugins {
 }
 
 group = "dev.protsenko"
-version = "1.0.5"
+version = "1.0.7"
 
 repositories {
     mavenCentral()
@@ -38,6 +39,13 @@ detekt {
     config.setFrom(files("detekt.yml"))
 }
 
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions {
+        allWarningsAsErrors.set(true)
+    }
+}
+
+
 kover {
     reports {
         verify {

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 #Sun Mar 08 00:12:25 AMT 2026
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.0-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

src/main/kotlin/dev/protsenko/codeguard/rules/SpringAnnotations.kt

@@ -1,5 +1,8 @@
 package dev.protsenko.codeguard.rules
 
+import com.lemonappdev.konsist.api.declaration.combined.KoClassAndInterfaceDeclaration
+import com.lemonappdev.konsist.api.provider.KoFullyQualifiedNameProvider
+
 /**
  * Fully-qualified annotation names and composite groups shared across all rule implementations.
  */
@@ -36,6 +39,12 @@ object SpringAnnotations {
     // ---- JPA ----
     const val ENTITY_JAKARTA = "jakarta.persistence.Entity"
     const val ENTITY_JAVAX = "javax.persistence.Entity"
+    const val MAPPED_SUPERCLASS_JAKARTA = "jakarta.persistence.MappedSuperclass"
+    const val MAPPED_SUPERCLASS_JAVAX = "javax.persistence.MappedSuperclass"
+    const val EMBEDDABLE_JAKARTA = "jakarta.persistence.Embeddable"
+    const val EMBEDDABLE_JAVAX = "javax.persistence.Embeddable"
+    const val ID_CLASS_JAKARTA = "jakarta.persistence.IdClass"
+    const val ID_CLASS_JAVAX = "javax.persistence.IdClass"
     const val ID_JAKARTA = "jakarta.persistence.Id"
     const val ID_JAVAX = "javax.persistence.Id"
 
@@ -64,9 +73,26 @@ object SpringAnnotations {
     /** @Entity (jakarta + javax). */
     val entityAnnotations = listOf(ENTITY_JAKARTA, ENTITY_JAVAX)
 
+    /** JPA types allowed in entity/domain packages. */
+    val entityPackageAnnotations =
+        listOf(
+            ENTITY_JAKARTA,
+            ENTITY_JAVAX,
+            MAPPED_SUPERCLASS_JAKARTA,
+            MAPPED_SUPERCLASS_JAVAX,
+            EMBEDDABLE_JAKARTA,
+            EMBEDDABLE_JAVAX,
+        )
+
     /** @Id (jakarta + javax). */
     val idAnnotations = listOf(ID_JAKARTA, ID_JAVAX)
 
+    /** @IdClass (jakarta + javax). */
+    val idClassAnnotations = listOf(ID_CLASS_JAKARTA, ID_CLASS_JAVAX)
+
+    /** Types allowed in config/configuration packages. */
+    val configurationPackageAnnotations = listOf(CONFIGURATION, CONTROLLER_ADVICE, REST_CONTROLLER_ADVICE)
+
     /** All @Transactional variants. */
     val transactionalAnnotations = listOf(TRANSACTIONAL, TRANSACTIONAL_JAKARTA, TRANSACTIONAL_JAVAX)
 
@@ -96,8 +122,19 @@ object SpringAnnotations {
     /** Annotations that rely on Spring AOP proxy and are silently ignored on private methods. */
     val proxyAnnotations =
         listOf(
-            TRANSACTIONAL, TRANSACTIONAL_JAKARTA, TRANSACTIONAL_JAVAX,
-            CACHEABLE, CACHE_EVICT, CACHE_PUT,
+            TRANSACTIONAL,
+            TRANSACTIONAL_JAKARTA,
+            TRANSACTIONAL_JAVAX,
+            CACHEABLE,
+            CACHE_EVICT,
+            CACHE_PUT,
             ASYNC,
         )
 }
+
+fun KoClassAndInterfaceDeclaration.isSpringDataRepository(): Boolean =
+    hasAnnotationWithName(SpringAnnotations.REPOSITORY) ||
+        hasExternalParent { parent ->
+            val fqn = (parent.sourceDeclaration as? KoFullyQualifiedNameProvider)?.fullyQualifiedName
+            fqn != null && fqn.startsWith("org.springframework.data") && fqn.contains(".repository.")
+        }

src/main/kotlin/dev/protsenko/codeguard/rules/naming/NamingRules.kt

@@ -6,6 +6,7 @@ import dev.protsenko.codeguard.core.SpringBootRule
 import dev.protsenko.codeguard.core.notSuppressedClasses
 import dev.protsenko.codeguard.core.notSuppressedClassesAndInterfaces
 import dev.protsenko.codeguard.rules.SpringAnnotations
+import dev.protsenko.codeguard.rules.isSpringDataRepository
 
 /**
  * Rules for naming conventions across Spring Boot layers.
@@ -46,7 +47,7 @@ object NamingRules {
             override fun verify(scope: KoScope) {
                 scope
                     .notSuppressedClassesAndInterfaces(suppressKey)
-                    .withAnnotationNamed(SpringAnnotations.REPOSITORY)
+                    .filter { it.isSpringDataRepository() }
                     .filterNot { it.name.endsWith("Repository") }
                     .also { violations ->
                         if (violations.isNotEmpty()) {

src/main/kotlin/dev/protsenko/codeguard/rules/packages/PackageRuleContext.kt

@@ -56,4 +56,53 @@ class PackageRuleContext : RuleContext() {
     fun entitiesInEntityPackage() {
         builder.addRule(PackageRules.entityPackageRule)
     }
+
+    /**
+     * Enforce that only @Service classes (or their file-level helpers) reside in .service package.
+     */
+    fun onlyServicesInServicePackage() {
+        builder.addRule(PackageRules.onlyServicesInServicePackageRule)
+    }
+
+    /**
+     * Enforce that only @Entity classes (or their file-level helpers) reside in .domain or .entity package.
+     */
+    fun onlyEntitiesInEntityPackage() {
+        builder.addRule(PackageRules.onlyEntitiesInEntityPackageRule)
+    }
+
+    /**
+     * Enforce that only @Controller/@RestController classes (or their file-level helpers) reside in .controller or .web package.
+     */
+    fun onlyControllersInControllerPackage() {
+        builder.addRule(PackageRules.onlyControllersInControllerPackageRule)
+    }
+
+    /**
+     * Enforce that only @Configuration classes (or their file-level helpers) reside in .config or .configuration package.
+     */
+    fun onlyConfigurationsInConfigPackage() {
+        builder.addRule(PackageRules.onlyConfigurationsInConfigPackageRule)
+    }
+
+    /**
+     * Enforce that only @ConfigurationProperties classes (or their file-level helpers) reside in .property package.
+     */
+    fun onlyPropertiesInPropertyPackage() {
+        builder.addRule(PackageRules.onlyPropertiesInPropertyPackageRule)
+    }
+
+    /**
+     * Enforce that @Repository classes and Spring Data repository interfaces reside in .repository package.
+     */
+    fun repositoryInRepositoryPackage() {
+        builder.addRule(PackageRules.repositoryPackageRule)
+    }
+
+    /**
+     * Enforce that only @Repository classes (or their file-level helpers) reside in .repository package.
+     */
+    fun onlyRepositoriesInRepositoryPackage() {
+        builder.addRule(PackageRules.onlyRepositoriesInRepositoryPackageRule)
+    }
 }