https://github.com/igorescodro/tech-debt
A lightweight KSP annotation processor that generates reports to track technical debt in Kotlin projects.
https://github.com/igorescodro/tech-debt
annotations kotlin ksp library tech-debt
Last synced: 5 months ago
JSON representation
A lightweight KSP annotation processor that generates reports to track technical debt in Kotlin projects.
- Host: GitHub
- URL: https://github.com/igorescodro/tech-debt
- Owner: igorescodro
- License: apache-2.0
- Created: 2026-01-10T20:05:37.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-11T02:33:17.000Z (5 months ago)
- Last Synced: 2026-01-11T08:14:15.959Z (5 months ago)
- Topics: annotations, kotlin, ksp, library, tech-debt
- Language: Kotlin
- Homepage:
- Size: 499 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 💸 TechDebt
[](https://github.com/igorescodro/tech-debt/actions/workflows/build.yml)
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](https://htmlpreview.github.io/?https://github.com/igorescodro/tech-debt/blob/main/samples/sample-jvm/assets/report.html)
## Quick Start
### 1. Apply the Gradle Plugin
In your `build.gradle.kts`:
#### Latest version: [](https://central.sonatype.com/search?q=g:io.github.igorescodro+techdebt)
```kotlin
plugins {
id("io.github.igorescodro.techdebt") version ""
}
```
### 2. Annotate your code
Use the `@TechDebt` annotation to mark areas of technical debt:
```kotlin
@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
### 3. Generate the report
The report is generated by the `generateTechDebtReport` task. Simply run:
```bash
./gradlew generateTechDebtReport
```
The consolidated HTML report will be generated in the root build directory:
`build/reports/techdebt/consolidated-report.html`
## Configuration (Optional)
You can customize the output file path and other options in your root `build.gradle.kts`:
```kotlin
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/")
}
```
## Features
- **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.
- **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.
## 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.
```