@sun-asterisk/sunlint 1.3.39 → 1.3.41

package/skill-assets/sunlint-code-quality/rules/kotlin/C023-no-duplicate-names.md

@@ -0,0 +1,47 @@
+---
+title: No Duplicate Variable Names In Scope
+impact: HIGH
+impactDescription: prevents shadowing bugs and improves code clarity
+tags: variables, shadowing, scope, quality, kotlin
+---
+
+## No Duplicate Variable Names In Scope
+
+Variable shadowing occurs when a variable declared within a certain scope has the same name as a variable declared in an outer scope. This leads to subtle bugs and confusion about which variable is being accessed.
+
+**Incorrect (shadowed variables):**
+
+```kotlin
+val user = getCurrentUser()
+
+fun processOrder(order: Order) {
+    val user = order.user // Shadows outer 'user'!
+    
+    // Which user is this?
+    println(user.name)
+}
+
+// Shadowing in lambdas
+items.forEach { item ->
+    val item = transform(item) // Shadows lambda parameter!
+}
+```
+
+**Correct (unique names):**
+
+```kotlin
+val currentUser = getCurrentUser()
+
+fun processOrder(order: Order) {
+    val orderUser = order.user // Distinct name
+    
+    println(orderUser.name)
+}
+
+// Different names in nested scope
+items.forEach { item ->
+    val transformedItem = transform(item)
+}
+```
+
+**Tools:** detekt (VariableShadowing), Android Studio Linter, Manual Review

package/skill-assets/sunlint-code-quality/rules/kotlin/C024-centralize-constants.md

@@ -0,0 +1,58 @@
+---
+title: Centralize Constants
+impact: HIGH
+impactDescription: makes values easy to find, update, and understand
+tags: constants, magic-numbers, configuration, quality, kotlin
+---
+
+## Centralize Constants
+
+Magic numbers or strings scattered throughout the code are difficult to manage and prone to errors. Centralizing constants makes the codebase more maintainable and self-documenting.
+
+**Incorrect (magic numbers and strings):**
+
+```kotlin
+if (password.length < 8) { }
+if (retryCount > 3) { }
+if (status == 1) { }
+Handler().postDelayed(callback, 300000)
+if (user.role == "admin") { }
+```
+
+**Correct (centralized constants):**
+
+```kotlin
+// Constants.kt or within an object
+object Config {
+    const val PASSWORD_MIN_LENGTH = 8
+    const val MAX_RETRY_ATTEMPTS = 3
+    const val SESSION_TIMEOUT_MS = 5 * 60 * 1000L // 5 minutes
+}
+
+enum class OrderStatus(val value: Int) {
+    PENDING(1),
+    APPROVED(2),
+    SHIPPED(3)
+}
+
+object UserRoles {
+    const val ADMIN = "admin"
+    const val USER = "user"
+    const val GUEST = "guest"
+}
+
+// Usage
+if (password.length < Config.PASSWORD_MIN_LENGTH) { }
+if (retryCount > Config.MAX_RETRY_ATTEMPTS) { }
+if (status == OrderStatus.PENDING.value) { }
+Handler().postDelayed(callback, Config.SESSION_TIMEOUT_MS)
+if (user.role == UserRoles.ADMIN) { }
+```
+
+**Benefits:**
+- Single source of truth.
+- Improved readability and domain expression.
+- Avoids duplication and "search-and-replace" errors.
+- Type safety (especially when using Enums or Sealed Classes).
+
+**Tools:** detekt (MagicNumber), Android Studio Linter, Manual Review

package/skill-assets/sunlint-code-quality/rules/kotlin/C029-catch-log-root-cause.md

@@ -0,0 +1,50 @@
+---
+title: All Catch Blocks Must Log Root Cause
+impact: HIGH
+impactDescription: enables debugging and incident response
+tags: error-handling, logging, debugging, observability, quality, kotlin
+---
+
+## All Catch Blocks Must Log Root Cause
+
+Silent failures make debugging impossible. Without proper logging, you cannot trace issues in production.
+
+**Incorrect (silent or minimal logging):**
+
+```kotlin
+try {
+    processPayment(order)
+} catch (e: Exception) {
+    // Empty catch - silent failure!
+}
+
+try {
+    saveUser(user)
+} catch (e: Exception) {
+    return null // No logging, no context
+}
+```
+
+**Correct (comprehensive error logging):**
+
+```kotlin
+try {
+    processPayment(order)
+} catch (error: Exception) {
+    logger.error("Payment processing failed", error) {
+        payload("orderId" to order.id)
+        payload("userId" to order.userId)
+        payload("amount" to order.amount)
+    }
+    throw PaymentFailedException("Payment could not be processed", error)
+}
+```
+
+**Log context should include:**
+- Error message and stack trace
+- Relevant entity IDs (order, user, etc.)
+- Request/correlation ID
+- Input that caused the error
+- Timing information
+
+**Tools:** Static analyzer, detekt, PR review

package/skill-assets/sunlint-code-quality/rules/kotlin/C030-custom-error-classes.md

@@ -0,0 +1,72 @@
+---
+title: Use Custom Error Classes
+impact: HIGH
+impactDescription: enables proper error categorization, structured logging, and precise handling
+tags: error-handling, custom-errors, exceptions, patterns, quality, kotlin
+---
+
+## Use Custom Error Classes
+
+Custom exception classes enable structured error handling, meaningful categorization, and better observability. They allow the application to provide clear diagnostic information and programmatic error codes.
+
+**Incorrect (generic exceptions):**
+
+```kotlin
+throw Exception("User not found")
+throw RuntimeException("Invalid input")
+throw IllegalStateException("Database connection failed")
+```
+
+**Correct (custom exception hierarchy):**
+
+```kotlin
+// Base application exception
+open class AppException(
+    val code: String,
+    override val message: String,
+    val statusCode: Int = 500,
+    val context: Map<String, Any?>? = null,
+    cause: Throwable? = null
+) : RuntimeException(message, cause)
+
+// Specific domain exceptions
+class UserNotFoundException(userId: String) : AppException(
+    code = "USER_NOT_FOUND",
+    message = "User $userId not found",
+    statusCode = 404,
+    context = mapOf("userId" to userId)
+)
+
+class ValidationException(field: String, message: String) : AppException(
+    code = "VALIDATION_ERROR",
+    message = message,
+    statusCode = 400,
+    context = mapOf("field" to field)
+)
+
+// Usage
+throw UserNotFoundException(userId)
+```
+
+**Using Sealed Classes for Error Handling (Functional Style):**
+
+```kotlin
+sealed class Result<out T> {
+    data class Success<out T>(val data: T) : Result<T>()
+    data class Failure(val error: AppException) : Result<Nothing>()
+}
+
+// Logic returning a result instead of throwing
+fun findUser(id: String): Result<User> {
+    val user = db.find(id)
+    return user?.let { Result.Success(it) } ?: Result.Failure(UserNotFoundException(id))
+}
+```
+
+**Benefits:**
+- Type-safe error handling logic.
+- Structured context for logging systems (ELK, Sentry).
+- Automatic mapping to API response formats.
+- Clearer domain modeling.
+
+**Tools:** detekt (TooGenericExceptionThrown), Manual Review, PR rules

package/skill-assets/sunlint-code-quality/rules/kotlin/C033-separate-data-access.md

@@ -0,0 +1,69 @@
+---
+title: Separate Processing And Data Access
+impact: HIGH
+impactDescription: enables testable business logic and better maintenance
+tags: separation, repository, service, architecture, quality, kotlin
+---
+
+## Separate Processing And Data Access
+
+Mixing business logic with raw database queries or data access logic creates tight coupling. This makes testing difficult (requiring a database) and makes the code harder to maintain and refactor.
+
+**Incorrect (mixed concerns):**
+
+```kotlin
+class OrderService {
+    fun calculateDiscount(userId: String): Double {
+        // Business logic mixed with raw SQL or data access
+        val user = db.query("SELECT * FROM users WHERE id = ?", userId)
+        val orders = db.query("SELECT * FROM orders WHERE user_id = ?", userId)
+        
+        var discount = 0.0
+        if (orders.size > 10) discount += 0.05
+        if (user.getBoolean("isPremium")) discount += 0.10
+        
+        return discount
+    }
+}
+```
+
+**Correct (separated layers using Repository Pattern):**
+
+```kotlin
+// Repository - focus on data mapping and retrieval
+interface UserRepository {
+    fun findById(userId: String): User?
+}
+
+interface OrderRepository {
+    fun findByUserId(userId: String): List<Order>
+}
+
+// Service - focus on business rules and orchestration
+class DiscountService(
+    private val userRepository: UserRepository,
+    private val orderRepository: OrderRepository
+) {
+    fun calculateDiscount(userId: String): Double {
+        val user = userRepository.findById(userId)
+        val orders = orderRepository.findByUserId(userId)
+        
+        return computeDiscount(user, orders)
+    }
+
+    // Business logic is pure and easily testable
+    private fun computeDiscount(user: User?, orders: List<Order>): Double {
+        var discount = 0.0
+        if (orders.size > 10) discount += 0.05
+        if (user?.isPremium == true) discount += 0.10
+        return discount
+    }
+}
+```
+
+**Benefits:**
+- Business logic can be unit-tested without a database.
+- Data sources can be swapped (e.g., migrating from SQL to NoSQL) without changing business rules.
+- Improved readability and clear separation of concerns.
+
+**Tools:** Architectural Review, Code Review, Manual Audit

package/skill-assets/sunlint-code-quality/rules/kotlin/C035-error-context-logging.md

@@ -0,0 +1,47 @@
+---
+title: Log All Relevant Context On Errors
+impact: HIGH
+impactDescription: enables quick debugging and accurate incident response
+tags: error-handling, logging, context, debugging, quality, kotlin
+---
+
+## Log All Relevant Context On Errors
+
+Logs without context are nearly useless for production troubleshooting. Comprehensive context-rich logs allow developers to reconstruct the state that led to an error.
+
+**Incorrect (minimal context):**
+
+```kotlin
+logger.error("Error occurred")
+logger.error(exception.message)
+```
+
+**Correct (comprehensive context):**
+
+```kotlin
+logger.error("Failed to process order", exception) {
+    // What happened
+    payload("errorCode" to exception.code)
+    
+    // Core Business Context
+    payload("orderId" to order.id)
+    payload("userId" to user.id)
+    payload("requestId" to MDC.get("requestId")) // Assuming MDC use
+    
+    // Input/State that caused the issue
+    payload("itemsCount" to order.items.size)
+    payload("totalAmount" to order.total)
+    
+    // Timing information
+    payload("processingTimeMs" to System.currentTimeMillis() - startTime)
+}
+```
+
+**Essential log context should include:**
+- Error details (Exception name, full stack trace).
+- Entity IDs (user ID, order ID, account ID).
+- Coordination IDs (Request ID, Correlation ID, Trace ID).
+- Summarized input data (avoid PII - Personal Identifiable Information).
+- System state hints (environment, version).
+
+**Tools:** SLF4J with Logback/Log4j2, Structured Logging (KLogging, Logstash Logback Encoder), Sentry

package/skill-assets/sunlint-code-quality/rules/kotlin/C041-no-hardcoded-secrets.md

@@ -0,0 +1,47 @@
+---
+title: No Hardcoded Secrets In Repo
+impact: CRITICAL
+impactDescription: prevents sensitive credential exposure and security breaches
+tags: secrets, credentials, security, git, quality, kotlin
+---
+
+## No Hardcoded Secrets In Repo
+
+Hardcoding sensitive credentials (API keys, DB passwords, private keys) in the source code or configuration files is a major security risk. Once committed, they are visible to anyone with access to the repo and historical versions.
+
+**Incorrect (secrets in code):**
+
+```kotlin
+const val STRIPE_API_KEY = "sk_live_abc123"
+val dbPassword = "root_password"
+
+// HARDCODED in resource files or code
+val connection = DriverManager.getConnection("jdbc:mysql://localhost/db", "admin", "secret123")
+```
+
+**Correct (environment/secrets manager):**
+
+```kotlin
+// Load from Environment Variables
+val apiKey = System.getenv("API_KEY")
+
+// Load from a secure property file (not committed to git)
+val properties = Properties().apply {
+    val inputStream = FileInputStream("secrets.properties")
+    load(inputStream)
+}
+val dbPassword = properties.getProperty("DB_PASSWORD")
+
+// Using a cloud secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault)
+val stripeKey = secretsClient.getSecret("stripe/live-key")
+
+// Validate presence at startup
+checkNotNull(apiKey) { "API_KEY environment variable must be set" }
+```
+
+**Protecting Secrets:**
+- Add `.env`, `secrets.properties`, `*.jks`, `*.pem` to `.gitignore`.
+- Use CI/CD secrets for deployment.
+- Avoid printing secrets to log files.
+
+**Tools:** Gitleaks, TruffleHog, SonarQube, detekt (HardcodedSecret)

package/skill-assets/sunlint-code-quality/rules/kotlin/C042-boolean-naming.md

@@ -0,0 +1,42 @@
+---
+title: Boolean Names Is/Has/Should Prefix
+impact: LOW
+impactDescription: makes conditional logic instantly readable and self-documenting
+tags: naming, booleans, readability, conventions, quality, kotlin
+---
+
+## Boolean Names Is/Has/Should Prefix
+
+Boolean variables and function names should start with a prefix that makes their true/false nature obvious. This improves readability of `if` statements and logical expressions.
+
+**Incorrect (unclear boolean names):**
+
+```kotlin
+val active = user.status == "active"
+val admin = checkAdminRole(user)
+val items = cart.isNotEmpty()
+val update = needsRefresh()
+```
+
+**Correct (clear boolean prefixes):**
+
+```kotlin
+val isActive = user.status == "active"
+val isAdmin = checkAdminRole(user)
+val hasItems = cart.isNotEmpty()
+val shouldUpdate = needsRefresh()
+val canEdit = user.hasPermission("edit")
+val willExpire = expirationDate.isBefore(tomorrow)
+```
+
+**Common Boolean Prefixes:**
+
+| Prefix | Use Case | Example |
+|--------|----------|---------|
+| `is` | Status or State | `isActive`, `isEmpty`, `isReady` |
+| `has` | Possession or Collection | `hasItems`, `hasPermission`, `hasMetadata` |
+| `should` | Recommendations or Tasks | `shouldRetry`, `shouldSkip`, `shouldNotify` |
+| `can` | Permissions or Capabilities | `canExecute`, `canSubmit`, `canDelete` |
+| `will` | Future State | `willChange`, `willExpire`, `willSync` |
+
+**Tools:** detekt, Android Studio Linter (Naming conventions), Code Review

package/skill-assets/sunlint-code-quality/rules/kotlin/C052-controller-parsing.md

@@ -0,0 +1,71 @@
+---
+title: Separate Data Mapping From Controllers
+impact: MEDIUM
+impactDescription: keeps controllers thin, focused on HTTP concerns, and makes mapping logic reusable
+tags: controller, parsing, transformation, mapping, patterns, quality, kotlin
+---
+
+## Separate Data Mapping From Controllers
+
+Controllers should be thin and only responsible for handling HTTP requests, orchestrating service calls, and returning responses. Complex data transformations or mapping logic should be extracted into separate Mapper classes or Extension functions.
+
+**Incorrect (mapping logic in controller):**
+
+```kotlin
+@RestController
+class UserController(private val userService: UserService) {
+    
+    @GetMapping("/users/{id}")
+    fun getUser(@PathVariable id: String): ResponseEntity<UserResponse> {
+        val user = userService.findById(id) ?: throw NotFoundException()
+        
+        // Complex mapping logic inside controller
+        val response = UserResponse(
+            id = user.id,
+            fullName = "${user.firstName} ${user.lastName}",
+            email = user.email.lowercase(),
+            formattedDate = user.createdAt.format(DateTimeFormatter.ISO_DATE)
+        )
+        
+        return ResponseEntity.ok(response)
+    }
+}
+```
+
+**Correct (using Mappers or Extension Functions):**
+
+```kotlin
+// Option 1: Using a dedicated Mapper
+object UserMapper {
+    fun toResponse(user: User): UserResponse = UserResponse(
+        id = user.id,
+        fullName = "${user.firstName} ${user.lastName}",
+        email = user.email.lowercase(),
+        formattedDate = user.createdAt.format(DateTimeFormatter.ISO_DATE)
+    )
+}
+
+// Option 2: Using Kotlin Extension Functions
+fun User.toResponse(): UserResponse = UserResponse(
+    id = id,
+    fullName = "$firstName $lastName",
+    email = email.lowercase(),
+    formattedDate = createdAt.format(DateTimeFormatter.ISO_DATE)
+)
+
+// Clean and focused controller
+@RestController
+class UserController(private val userService: UserService) {
+    @GetMapping("/users/{id}")
+    fun getUser(@PathVariable id: String): UserResponse {
+        return userService.findById(id)?.toResponse() ?: throw NotFoundException()
+    }
+}
+```
+
+**Benefits:**
+- **Reusability:** The same mapping logic can be used across multiple controllers or background jobs.
+- **Testability:** Mappers can be unit-tested in isolation without mocking HTTP infrastructure.
+- **Maintainability:** Changes to API formats are centralized.
+
+**Tools:** MapStruct, Kotlin Extension Functions, ModelMapper, Architectural Review

package/skill-assets/sunlint-code-quality/rules/kotlin/C060-superclass-logic.md

@@ -0,0 +1,60 @@
+---
+title: Do Not Ignore Superclass Logic
+impact: HIGH
+impactDescription: ensures proper inheritance behavior and execution of base class contracts
+tags: inheritance, override, superclass, oop, quality, kotlin
+---
+
+## Do Not Ignore Superclass Logic
+
+When overriding methods in Kotlin, it is crucial to call the `super` implementation unless you explicitly intend to replace it entirely. Ignoring superclass logic often leads to missing validations, hooks, or lifecycle events defined in the base class.
+
+**Incorrect (ignoring superclass):**
+
+```kotlin
+open class BaseService {
+    open fun save(entity: Entity) {
+        validate(entity)
+        db.save(entity)
+        logger.info("Entity saved")
+    }
+}
+
+class UserService : BaseService() {
+    override fun save(user: User) {
+        // BUG: Skips validation and logging from the base class!
+        db.save(user)
+    }
+}
+```
+
+**Correct (calling super):**
+
+```kotlin
+class UserService : BaseService() {
+    override fun save(user: User) {
+        // Perform user-specific logic
+        user.lastModified = Instant.now()
+        
+        // Ensure base class logic (validation, etc.) is executed
+        super.save(user)
+        
+        // Add additional post-save logic
+        notifyAdmins(user)
+    }
+}
+```
+
+**Exception (intentional replacement):**
+
+```kotlin
+class AdminService : BaseService() {
+    // Override: Admins bypass standard validation logic
+    override fun save(admin: User) {
+        // Intentionally skip super.save()
+        db.save(admin)
+    }
+}
+```
+
+**Tools:** Android Studio / IntelliJ IDEA hints, detekt, Code Review

package/skill-assets/sunlint-code-quality/rules/kotlin/C067-no-hardcoded-config.md

@@ -0,0 +1,51 @@
+---
+title: Do Not Hardcode Configuration
+impact: HIGH
+impactDescription: enables environment-specific deployments without code changes
+tags: configuration, environment, deployment, quality, kotlin
+---
+
+## Do Not Hardcode Configuration
+
+Configuration values that change between environments (Development, Staging, Production) should never be hardcoded in the source code. Hardcoding necessitates re-compilation and re-deployment for simple configuration changes and risks exposing production settings in lower environments.
+
+**Incorrect (hardcoded config):**
+
+```kotlin
+const val API_URL = "https://api.production.sun-asterisk.vn"
+const val TIMEOUT_MS = 5000
+const val MAX_RETRIES = 3
+```
+
+**Correct (externalized configuration):**
+
+```kotlin
+// In Spring Boot: use application.yml/properties with placeholders
+// api.url: ${API_URL:http://localhost:8080}
+
+@ConfigurationProperties(prefix = "app")
+data class AppConfig(
+    val apiUrl: String,
+    val timeoutMs: Int = 5000,
+    val maxRetries: Int = 3
+)
+
+// In Ktor: use HOCON configuration (application.conf)
+// storage {
+//    bucket = ${?STORAGE_BUCKET}
+// }
+
+val bucket = environment.config.propertyOrNull("storage.bucket")?.getString() 
+    ?: "default-dev-bucket"
+
+// Manual Environment Access
+val dbUrl = System.getenv("DATABASE_URL") ?: "jdbc:h2:mem:test"
+```
+
+**Best Practices:**
+- Use environment variables for sensitive or environment-specific values.
+- Provide sensible defaults for local development.
+- Validate required configuration values at application startup (fail-fast).
+- Avoid "magic strings" for configuration keys; use typesafe configuration classes.
+
+**Tools:** Spring Boot `@ConfigurationProperties`, Ktor `HoconApplicationConfig`, `dotenv-kotlin`, Manual Review

package/skill-assets/sunlint-code-quality/rules/kotlin/S003-open-redirect.md

@@ -0,0 +1,66 @@
+---
+title: URL Redirects Must Be In Allow List
+impact: MEDIUM
+impactDescription: prevents open redirect vulnerabilities used in phishing attacks
+tags: redirect, url, allow-list, validation, security, kotlin
+---
+
+## URL Redirects Must Be In Allow List
+
+Open redirect vulnerabilities allow attackers to use your trusted domain to redirect users to malicious sites. This is commonly used in phishing campaigns to make malicious URLs look legitimate.
+
+**Incorrect (unvalidated redirect URL):**
+
+```kotlin
+// Open redirect vulnerability
+@GetMapping("/redirect")
+fun redirect(request: HttpServletRequest, response: HttpServletResponse) {
+    val url = request.getParameter("url")
+    response.sendRedirect(url) // Attacker: ?url=https://evil.com
+}
+
+// Partial validation (bypassable)
+if (url.contains("sun-asterisk.vn")) {
+    response.sendRedirect(url) // Bypass: https://attacker.com?sun-asterisk.vn
+}
+```
+
+**Correct (allow list or relative path validation):**
+
+```kotlin
+import java.net.URI
+
+private val ALLOWED_HOSTS = setOf("sun-asterisk.vn", "app.sun-asterisk.vn")
+
+@GetMapping("/redirect")
+fun safeRedirect(@RequestParam url: String, response: HttpServletResponse) {
+    try {
+        val uri = URI(url)
+        val host = uri.host
+
+        // 1. Validate against allow list (for absolute URLs)
+        if (host != null && !ALLOWED_HOSTS.contains(host)) {
+            throw SecurityException("Host not allowed")
+        }
+
+        // 2. Or enforce relative paths only (safe for internal navigation)
+        if (host == null) {
+            if (!url.startsWith("/") || url.startsWith("//")) {
+                throw SecurityException("Invalid relative path")
+            }
+        }
+
+        response.sendRedirect(url)
+    } catch (e: Exception) {
+        response.sendError(400, "Invalid URL")
+    }
+}
+```
+
+**Security Best Practices:**
+- Prefer relative URLs over absolute URLs for internal redirects.
+- If absolute URLs are required, strictly validate the `host` against an allow list.
+- Reject URLs that use the `//` shorthand (protocol-relative) to avoid cross-domain redirects.
+- Display a transition page for redirects to external unlisted sites.
+
+**Tools:** SonarQube (S5144, S1134), Semgrep, Manual Security Audit