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.

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.

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.

In your build.gradle.kts:

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

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

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

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

techDebtReport {
    // Customize the output file path (Optional)
    outputFile.set(layout.buildDirectory.file("custom/path/report.html"))

    // Enable the collection of @Suppress annotations (Optional, default is false)
    collectSuppress.set(true)

    // Enable the collection of TODO and FIXME comments (Optional, default is false)
    collectComments.set(true)

    // Set a base URL for tickets to automatically generate links (Optional)
    baseTicketUrl.set("https://jira.myproject.com/tickets/")

    // Enable Git metadata like last modified date and author (Optional, default is false)
    enableGitMetadata.set(true)
}

• Consolidated HTML Report: A clean, easy-to-read summary of all technical debt from all modules in your project.
• Suppress Support: Optionally collect and visualize suppressed rules (e.g., @Suppress("MagicNumber")) in the report.
• TODO/FIXME Comments Support: Optionally collect and visualize TODO and FIXME comments from your source code.
• Git Metadata Support: Optionally collect and visualize Git information (Author and Last Modified date) for each tech debt item.
• Priority Levels: Support for LOW, MEDIUM, and HIGH priority levels (and NONE).
• Ticket Linking: Keep track of related tickets in your issue tracking system. If baseTicketUrl is configured, tickets will automatically become clickable links in the report.
• Multi-module Support: Automatically collects data from all subprojects.

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.