Skip to content
PoCInnovationPublic

About

No description, website, or topics provided.

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

Debtlint logo

Debtlint

Debtlint is a technical debt detection tool focused on duplicated logic, built for the era of AI code generation. It identifies repeated or near-duplicate code segments across a codebase and reports them for refactoring.

Vision

As coding assistants become mainstream, "silent" duplication appears quickly:

  • existing utility functions get rewritten,
  • business patterns are repeated,
  • logic becomes fragmented across multiple files.

Debtlint provides a programmatic, fast, and cost-efficient way to prevent this drift and keep architecture healthy over time.

Objectives

  • Detect exact duplications and structural similarities.
  • Surface duplicated blocks with file and line locations.
  • Provide actionable reports (terminal + JSON) for local use and CI.
  • Integrate easily into team workflows (local, CI, agents).
  • Stay as language-agnostic as possible.

Install

cargo install debtlint

Or from the repository:

cargo install --path .

Quick start

  1. Optionally add .debtlint/debtlint.config.json (built-in defaults apply if missing):
{
  "dir": ".",
  "excludes": ["target", "node_modules", "build", "*.json", "*.md"]
}
  1. Run Debtlint:
debtlint

On first run, BPE trains and writes .debtlint/debtlint.vocab.json. Later runs reuse that cache when BPE parameters match and the corpus has not changed enough (file count at least doubled with ≥100 new files, or majority-language share shifted by more than 50 points / majority language changed). Pass --vocab-size or --save-vocab to force a retrain.

How It Works

The Debtlint pipeline follows four main steps:

  1. Code ingestion Recursively discover source files under dir from .debtlint/debtlint.config.json (or . by default). The CLI DIR argument overrides dir when provided. Discovery is Git-independent. .gitignore still applies, and excludes lists directories and extension globs to skip (via ignore overrides). Symbolic links are not followed.

  2. BPE encoding Train a Byte Pair Encoding vocabulary on first run and persist it under .debtlint/debtlint.vocab.json, or reuse a compatible cached vocabulary.

  3. Winnowing-based duplicate detection Build hashed shingles over the token stream, select fingerprints with a sliding window, then extend matching regions into duplicated blocks.

  4. Reporting Print a human-readable summary by default, or JSON for CI and agents (--report-format json).

Why BPE

BPE is historically a compression and tokenization technique, notably used to segment large amounts of text efficiently. In Debtlint, this logic helps highlight repetitive structures and grammatical blocks of code.

Core reference: Byte pair encoding - Wikipedia

More detail: doc/bpe.md

CLI

debtlint [DIR] [OPTIONS]
Flag Default Description
DIR config / . Directory to analyze (overrides dir in config)
--vocab-size <N> 1000 Max vocabulary size; forces retrain when set
--min-frequency 2 Min pair frequency to create a merge
--load-vocab <PATH> — Load a vocabulary JSON and skip cache/training
--save-vocab <PATH> — Force retrain; also write a legacy export to PATH
--output-encoded <PATH> — Write encoded token sequences as JSON
--shingle-size 50 Shingle size in tokens (Winnowing)
--window-size 3 Sliding window size in shingles
--min-tokens 20 Minimum duplicated block length in tokens
--report-format text text or json

Examples:

# Human-readable report (current directory; uses vocab cache)
debtlint

# Analyze a specific directory
debtlint src

# JSON for CI / agents
debtlint --report-format json

# Force retrain with a larger vocabulary
debtlint --vocab-size 2000

Configuration lives in .debtlint/debtlint.config.json (optional). The vocabulary cache is .debtlint/debtlint.vocab.json. excludes accepts directory names (target) and globs (*.json).

GitHub Actions Integration

Use the action in this repository (action.yml at the root) to analyze pull requests. See action/README.md for inputs and details.

name: Check duplication

on:
  pull_request:
    branches: [main]

jobs:
  debtlint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Run debtlint
        uses: PoCInnovation/Debtlint@v1
        with:
          vocab-path: .debtlint-vocab.json

Agent integration

Debtlint can sit in an agent loop after code generation:

  • generate code,
  • run debtlint --report-format json,
  • refactor reported duplicates,
  • re-run until clean (or after a fixed number of iterations).

An agent skill lives in skills/debtlint.

License

This project is licensed under the Apache License 2.0.

Contributing

Contributions are welcome. Read the guide: CONTRIBUTING.md

Project presentation video

Our PoC team ❤️

Developers


Enzo Ruffino

Loan Riyanto

Rayan

Manager


Laurent Gonzalez

Lohan

Organization

LinkedIn logo Instagram logo Twitter logo Discord logo

Website logo

🚀 Don't hesitate to follow us on our different networks, and put a star 🌟 on PoC's repositories

Made with ❤️ by PoC

About

No description, website, or topics provided.

Resources

Contributing

Stars

7 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages