{"id":37228889,"url":"https://github.com/igorescodro/tech-debt","last_synced_at":"2026-02-02T01:08:29.741Z","repository":{"id":331729641,"uuid":"1131845466","full_name":"igorescodro/tech-debt","owner":"igorescodro","description":"A lightweight KSP annotation processor that generates reports to track technical debt in Kotlin projects.","archived":false,"fork":false,"pushed_at":"2026-01-11T02:33:17.000Z","size":511,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T08:14:15.959Z","etag":null,"topics":["annotations","kotlin","ksp","library","tech-debt"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igorescodro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T20:05:37.000Z","updated_at":"2026-01-11T01:28:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/igorescodro/tech-debt","commit_stats":null,"previous_names":["igorescodro/tech-debt"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/igorescodro/tech-debt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorescodro%2Ftech-debt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorescodro%2Ftech-debt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorescodro%2Ftech-debt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorescodro%2Ftech-debt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorescodro","download_url":"https://codeload.github.com/igorescodro/tech-debt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorescodro%2Ftech-debt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","kotlin","ksp","library","tech-debt"],"created_at":"2026-01-15T03:30:04.867Z","updated_at":"2026-02-02T01:08:29.734Z","avatar_url":"https://github.com/igorescodro.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 💸 TechDebt\n\n[![Build status](https://github.com/igorescodro/tech-debt/actions/workflows/build.yml/badge.svg)](https://github.com/igorescodro/tech-debt/actions/workflows/build.yml)\n\nTechDebt is a Kotlin Symbol Processing (KSP) tool designed to help developers track and visualize technical debt\ndirectly within their codebase. By using the `@TechDebt` annotation, you can document technical debt, link it to\ntickets, and assign priority levels. The tool then generates a comprehensive HTML report summarizing all marked\ntechnical debt.\n\n## Goal\n\nThe primary goal of TechDebt is to make technical debt visible and manageable. Instead of letting TODOs get lost in the\ncode, TechDebt allows you to:\n- Formally document technical debt at the file, class, function, or property level.\n- Categorize debt by priority (Low, Medium, High).\n- Link code smells or shortcuts to issue tracker tickets.\n- Generate a visual report to share with the team or stakeholders.\n\n## How it Works\n\nTechDebt uses **KSP (Kotlin Symbol Processing)** to scan your source code for the `@TechDebt` annotation during the\ncompilation process. Each module generates its own local report, which is then collected and consolidated by the\n**TechDebt Gradle Plugin** into a single, comprehensive HTML report.\n\n## Report example\n\n\u003cimg src=\"assets/screenshot-report-example.png\" alt=\"Screenshot of TechDebt report example\"\u003e\n\n### 🧾 [Link to example](https://htmlpreview.github.io/?https://github.com/igorescodro/tech-debt/blob/main/samples/sample-jvm/assets/report.html)\n\n## Quick Start\n\n### 1. Apply the Gradle Plugin\n\nIn your `build.gradle.kts`:\n\n#### Latest version: [![Maven Central](https://img.shields.io/maven-central/v/io.github.igorescodro/techdebt-annotations.svg)](https://central.sonatype.com/search?q=g:io.github.igorescodro+techdebt)\n\n```kotlin\nplugins {\n    id(\"io.github.igorescodro.techdebt\") version \"\u003clatest-version\u003e\"\n}\n```\n\n### 2. Annotate your code\n\nUse the `@TechDebt` annotation to mark areas of technical debt:\n\n```kotlin\n@TechDebt(\n    description = \"Quick fix to handle edge case, needs proper refactoring.\",\n    ticket = \"JIRA-123\",\n    priority = Priority.HIGH\n)\nfun complexMethod() {\n    // ...\n}\n```\n\nThe annotation can be applied to:\n- Files\n- Classes\n- Functions\n- Properties\n\n### 3. Generate the report\n\nThe report is generated by the `generateTechDebtReport` task. Simply run:\n\n```bash\n./gradlew generateTechDebtReport\n```\n\nThe consolidated HTML report will be generated in the root build directory:\n`build/reports/techdebt/consolidated-report.html`\n\n## Configuration (Optional)\n\nYou can customize the output file path and other options in your root `build.gradle.kts`:\n\n```kotlin\ntechDebtReport {\n    // Customize the output file path (Optional)\n    outputFile.set(layout.buildDirectory.file(\"custom/path/report.html\"))\n\n    // Enable the collection of @Suppress annotations (Optional, default is false)\n    collectSuppress.set(true)\n\n    // Enable the collection of TODO and FIXME comments (Optional, default is false)\n    collectComments.set(true)\n\n    // Set a base URL for tickets to automatically generate links (Optional)\n    baseTicketUrl.set(\"https://jira.myproject.com/tickets/\")\n}\n```\n\n## Features\n\n- **Consolidated HTML Report**: A clean, easy-to-read summary of all technical debt from all modules in your project.\n- **Suppress Support**: Optionally collect and visualize suppressed rules (e.g., `@Suppress(\"MagicNumber\")`) in the report.\n- **TODO/FIXME Comments Support**: Optionally collect and visualize `TODO` and `FIXME` comments from your source code.\n- **Priority Levels**: Support for `LOW`, `MEDIUM`, and `HIGH` priority levels (and `NONE`).\n- **Ticket Linking**: Keep track of related tickets in your issue tracking system. If `baseTicketUrl` is configured, \ntickets will automatically become clickable links in the report.\n- **Multi-module Support**: Automatically collects data from all subprojects.\n\n## License\n\n```\nCopyright 2026 Igor Escodro\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorescodro%2Ftech-debt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorescodro%2Ftech-debt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorescodro%2Ftech-debt/lists"}