💸 TechDebt

TechDebt is a Kotlin Symbol Processing (KSP) tool designed to help developers track and visualize technical debt directly within their codebase. By using the @TechDebt annotation, you can document technical debt, link it to tickets, and assign priority levels. The tool then generates a comprehensive HTML report summarizing all marked technical debt.

Goal

The primary goal of TechDebt is to make technical debt visible and manageable. Instead of letting TODOs get lost in the code, TechDebt allows you to:

• Formally document technical debt at the file, class, function, or property level.
• Categorize debt by priority (Low, Medium, High).
• Link code smells or shortcuts to issue tracker tickets.
• Generate a visual report to share with the team or stakeholders.

How it Works

TechDebt uses KSP (Kotlin Symbol Processing) to scan your source code for the @TechDebt annotation during the compilation process. Each module generates its own local report, which is then collected and consolidated by the TechDebt Gradle Plugin into a single, comprehensive HTML report.

Report example

🧾 Link to example

Download

TechDebt is available in Maven Central. To use it in your project, you need to apply the Gradle plugin and add the following dependencies.

Latest version:

1. Apply the Gradle Plugin

In your root build.gradle.kts:

plugins {
    id("io.github.igorescodro.techdebt") version "<latest-version>"
}

2. Add dependencies

In the modules where you want to track technical debt:

repositories {
    mavenCentral()
}

// For Kotlin Multiplatform projects
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.igorescodro:techdebt-annotations:<latest-version>")
        }
    }
}

dependencies {
    add("kspAndroid", "io.github.igorescodro:techdebt-processor:<latest-version>")
    add("kspIosSimulatorArm64", "io.github.igorescodro:techdebt-processor:<latest-version>")
    add("kspIosX64", "io.github.igorescodro:techdebt-processor:<latest-version>")
    add("kspIosArm64", "io.github.igorescodro:techdebt-processor:<latest-version>")
    // Add any other platform target you use in your project, for example kspDesktop
}

// For Android or JVM only projects
dependencies {
    implementation("io.github.igorescodro:techdebt-annotations:<latest-version>")
    ksp("io.github.igorescodro:techdebt-processor:<latest-version>")
}

How to Use

1. Annotate your code

Use the @TechDebt annotation to mark areas of technical debt:

@TechDebt(
    description = "Quick fix to handle edge case, needs proper refactoring.",
    ticket = "JIRA-123",
    priority = Priority.HIGH
)
fun complexMethod() {
    // ...
}

The annotation can be applied to:

• Files
• Classes
• Functions
• Properties

2. Generate the report

The report is generated by the generateTechDebtReport task. Simply run:

./gradlew generateTechDebtReport

The consolidated HTML report will be generated in the root build directory: build/reports/techdebt/consolidated-report.html

3. Configuration (Optional)

You can customize the output file path in your root build.gradle.kts:

techDebtReport {
    outputFile.set(layout.buildDirectory.file("custom/path/report.html"))
}

Features

• Consolidated HTML Report: A clean, easy-to-read summary of all technical debt from all modules in your project.
• Priority Levels: Support for LOW, MEDIUM, and HIGH priority levels (and NONE).
• Ticket Linking: Keep track of related tickets in your issue tracking system.
• Multi-module Support: Automatically collects data from all subprojects.

License

Copyright 2026 Igor Escodro

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.