Merge pull request #4 from EntryDSM/test/2-code-convaintion

Feature/2 code convention

Author: qkrwndnjs1075

build-logic/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    `kotlin-dsl`
+    id("casper.documentation-convention")
+}
+
+group = "io.casper.build"
+version = "1.0.0"
+
+repositories {
+    mavenCentral()
+}

build-logic/settings.gradle.kts

@@ -0,0 +1,17 @@
+rootProject.name = "build-logic"
+
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+
+    // convention 모듈 참조
+    includeBuild("../casper-convention")
+}
+
+dependencyResolutionManagement {
+    repositories {
+        mavenCentral()
+    }
+}

build-logic/src/main/kotlin/io/casper/build/TestClass.kt

@@ -0,0 +1,16 @@
+package io.casper.build
+
+/**
+ * 이 클래스는 KDoc 주석 검사 테스트를 위한 용도입니다.
+ * 이제 올바른 KDoc 주석 형식을 사용합니다.
+ */
+class TestClass {
+    /**
+     * 이 함수는 KDoc 주석 검사 테스트를 위한 용도입니다.
+     *
+     * @return 항상 Unit을 반환합니다.
+     */
+    fun testFunction() {
+        println("이 함수는 문서화 검사를 테스트하기 위한 용도입니다.")
+    }
+}

build.gradle.kts

@@ -8,6 +8,27 @@ plugins {
     id("casper.documentation-convention")
 }
 
+// 모든 프로젝트(루트 및 서브프로젝트)에 공통 설정 적용
+allprojects {
+    repositories {
+        mavenCentral()
+    }
+
+    // 모든 프로젝트에 플러그인 적용
+    apply(plugin = "casper.documentation-convention")
+}
+
+tasks.register("checkAll") {
+    group = "verification"
+    description = "모든 모듈(includeBuild 포함)에 대해 check 태스크를 실행합니다"
+
+    // 루트 프로젝트의 check 태스크에 의존
+    dependsOn(tasks.named("check"))
+
+    // build-logic, convention 등 includeBuild 모듈의 check 태스크에 의존
+    dependsOn(gradle.includedBuilds.map { it.task(":check") })
+}
+
 group = "hs.kr.entrydsm"
 version = "0.0.1-SNAPSHOT"
 
@@ -17,10 +38,6 @@ java {
     }
 }
 
-repositories {
-    mavenCentral()
-}
-
 dependencies {
     implementation("org.springframework.boot:spring-boot-starter")
     implementation("org.jetbrains.kotlin:kotlin-reflect")

casper-convention/build.gradle.kts

@@ -0,0 +1,39 @@
+plugins {
+    `kotlin-dsl`
+}
+
+group = "io.casper.convention"
+version = "1.0.0"
+
+repositories {
+    mavenCentral()
+}
+
+
+// 중복 파일 처리 전략 설정
+tasks.withType<ProcessResources> {
+    duplicatesStrategy = DuplicatesStrategy.EXCLUDE
+}
+
+// 빌드 클린업 태스크
+tasks.register("cleanBuildDirs") {
+    doLast {
+        delete("build/pluginDescriptors")
+        delete("build/resources/main/META-INF/gradle-plugins")
+    }
+}
+
+// processResources 태스크 전에 클린업 실행
+tasks.processResources {
+    dependsOn("cleanBuildDirs")
+}
+
+gradlePlugin {
+    plugins {
+        // 문서화 컨벤션 플러그인
+        register("documentationConvention") {
+            id = "casper.documentation-convention"
+            implementationClass = "io.casper.convention.plugins.DocumentationConventionPlugin"
+        }
+    }
+}

casper-convention/src/main/kotlin/io/casper/convention/exception/DocumentationException.kt

@@ -0,0 +1,33 @@
+package io.casper.convention.exception
+
+import io.casper.convention.model.CodeElement
+import org.gradle.api.GradleException
+
+
+/**
+ * 문서화 관련 예외를 처리하기 위한 예외 클래스
+ * KDoc 문서화 검사 실패 시 발생
+ * gradle 플러그인 모듈은 global Exception을 만들기 어려워서 따로 클래스로 만듦
+ *
+ * @param element 검사 대상 코드 요소
+ * @param message 예외 메시지
+ */
+class DocumentationException(
+    val element: CodeElement,
+    message: String
+) : GradleException(message) {
+    companion object {
+        /**
+         * 문서화 부재 예외를 생성
+         *
+         * @param element 문서화가 부재한 코드 요소
+         * @return 생성된 DocumentationException 인스턴스
+         */
+        fun missingDocumentation(element: CodeElement): DocumentationException {
+            return DocumentationException(
+                element = element,
+                message = "일부 ${element.friendlyName}에 KDoc 주석이 없습니다. 자세한 내용은 로그를 확인하세요."
+            )
+        }
+    }
+}

casper-convention/src/main/kotlin/io/casper/convention/model/CodeElement.kt

@@ -0,0 +1,56 @@
+package io.casper.convention.model
+
+/**
+ * 코드 요소 종류를 정의하는 열거형 클래스입니다.
+ * 각 코드 요소는 KDoc 검사 대상이 됩니다.
+ */
+enum class CodeElement(
+    val friendlyName: String,
+    val difficulty: Int,
+    val helpMessage: String
+) {
+    /**
+     * Kotlin 클래스 정의
+     */
+    CLASS(
+        "클래스",
+        3,
+        "클래스 '%s'에 KDoc 주석이 없습니다."
+    ),
+    
+    /**
+     * Kotlin 객체 정의
+     */
+    OBJECT(
+        "객체",
+        3,
+        "객체 '%s'에 KDoc 주석이 없습니다."
+    ),
+    
+    /**
+     * Kotlin 인터페이스 정의
+     */
+    INTERFACE(
+        "인터페이스",
+        3,
+        "인터페이스 '%s'에 KDoc 주석이 없습니다."
+    ),
+    
+    /**
+     * Kotlin 함수 정의
+     */
+    FUNCTION(
+        "함수",
+        4,
+        "함수 '%s'에 KDoc 주석이 없습니다."
+    ),
+    
+    /**
+     * Kotlin 속성 정의
+     */
+    PROPERTY(
+        "속성",
+        5,
+        "속성 '%s'에 KDoc 주석이 없습니다."
+    );
+}

casper-convention/src/main/kotlin/io/casper/convention/model/DocCheckTaskType.kt

@@ -0,0 +1,32 @@
+package io.casper.convention.model
+
+import org.gradle.internal.impldep.org.yaml.snakeyaml.TypeDescription
+
+enum class DocCheckTaskType(
+
+    val taskName : String,
+    val description: String,
+    val codeElement: CodeElement
+) {
+
+    CLASS_DOC(
+        taskName = "checkClassDocs",
+        description = "클래스에 KDoc 주석이 있는지 확인합니다",
+        codeElement = CodeElement.CLASS
+    ),
+    OBJECT_DOC(
+        taskName = "checkObjectDocs",
+        description = "객체에 KDoc 주석이 있는지 확인합니다",
+        codeElement = CodeElement.OBJECT
+    ),
+    INTERFACE_DOC(
+        taskName = "checkInterfaceDocs",
+        description = "인터페이스에 KDoc 주석이 있는지 확인합니다",
+        codeElement = CodeElement.INTERFACE
+    ),
+    FUNCTION_DOC(
+        taskName = "checkFunctionDocs",
+        description = "함수에 KDoc 주석이 있는지 확인합니다",
+        codeElement = CodeElement.FUNCTION
+    ),
+}

casper-convention/src/main/kotlin/io/casper/convention/model/DocumentationProblem.kt

@@ -0,0 +1,60 @@
+package io.casper.convention.model
+
+/**
+ * 문서화 문제를 나타내는 데이터 클래스입니다.
+ * 코드 베이스에서 KDoc 주석이 누락된 요소에 대한 정보를 저장합니다.
+ */
+data class DocumentationProblem(
+    /**
+     * 문제가 발견된 코드 요소 유형
+     */
+    val element: CodeElement,
+
+    /**
+     * 요소의 이름 (클래스명, 함수명 등)
+     */
+    val elementName: String,
+
+    /**
+     * 파일의 전체 경로
+     */
+    val filePath: String,
+
+    /**
+     * 파일의 이름 (경로 제외)
+     */
+    val fileName: String,
+
+    /**
+     * 코드 요소가 선언된 줄 번호
+     */
+    val lineNumber: Int
+) {
+    /**
+     * 사용자 친화적인 오류 메시지를 생성합니다.
+     * 
+     * @return 파일명과 줄 번호가 포함된 형식화된 오류 메시지
+     */
+    fun toUserFriendlyMessage(): String {
+        val message = element.helpMessage.format(elementName)
+        return "[$fileName:$lineNumber] $message"
+    }
+    
+    /**
+     * 개발자를 위한 상세 오류 메시지를 생성합니다.
+     * 
+     * @return 파일 경로와 줄 번호가 포함된 상세 오류 메시지
+     */
+    fun toDetailedMessage(): String {
+        return "${element.friendlyName} '$elementName'에 KDoc 주석이 없습니다. (파일: $filePath, 라인: $lineNumber)"
+    }
+    
+    /**
+     * 로그 출력용 짧은 메시지를 생성합니다.
+     * 
+     * @return 간결한 형식의 로그 메시지
+     */
+    fun toLogMessage(): String {
+        return "문서화 필요: ${element.friendlyName} '$elementName' ($fileName:$lineNumber)"
+    }
+}

casper-convention/src/main/kotlin/io/casper/convention/plugins/DocumentationConventionPlugin.kt

@@ -0,0 +1,57 @@
+package io.casper.convention.plugins
+
+import io.casper.convention.tasks.DocCheckTask
+import io.casper.convention.model.DocCheckTaskType
+import io.casper.convention.util.DocConstants
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.Task
+import org.gradle.api.tasks.TaskProvider
+import org.gradle.kotlin.dsl.register
+
+/**
+ * Casper 프로젝트의 KDoc 문서화 규칙을 정의하는 Gradle 플러그인입니다.
+ */
+class DocumentationConventionPlugin : Plugin<Project> {
+    override fun apply(project: Project) {
+        with(project) {
+            // 현재 프로젝트에 태스크 등록
+            registerDocTasks(this)
+
+            // 모든 서브프로젝트에도 태스크 등록
+            subprojects {
+                registerDocTasks(this)
+            }
+        }
+    }
+
+
+    private fun Project.registerDocTasks(project: Project) {
+        with(project) {
+            val registeredTasks = mutableListOf<TaskProvider<out Task>>()
+
+            DocCheckTaskType.values().forEach { taskType ->
+                val task = tasks.register<DocCheckTask>(taskType.taskName) {
+                    group = DocConstants.DOC_GROUP
+                    description = taskType.description
+                    codeElement.set(taskType.codeElement)
+                }
+                registeredTasks.add(task)
+            }
+
+            // 모든 문서화 검사를 한 번에 실행하는 태스크
+    tasks.register("checkAllDocs") {
+        group = DocConstants.CHECK_GROUP
+        description = "모든 코드 요소의 KDoc 주석 여부를 확인합니다"
+
+        // 등록된 모든 검사 태스크에 의존
+        dependsOn(registeredTasks)
+    }
+
+    // 빌드 검증 과정에 문서화 검사 포함
+    tasks.named("check") {
+        dependsOn("checkAllDocs")
+    }
+}
+}
+}