Doto

Turn TODO comments into a Markdown task database.

• Status: pre‑alpha
• Audience: developers
• Platforms: macOS (primary), Windows and Linux expected
• Requires: .NET SDK 9.0

Overview

Doto scans your codebase for TODO comments, assigns stable numeric IDs, and maintains a Markdown “task vault” with one file per task. It can be used as:

• A CLI tool you run as part of your workflow (Doto.Cli).
• A library you can integrate into your own tools (Doto.Core).

Features

• Scan code for TODO comments and auto‑assign IDs.
• Generate per‑task Markdown files with YAML front‑matter.
• Keep titles in sync and mark tasks as done when the TODO line disappears.
• Extract tags from leading tag blocks like [ui, backend] or (ui, backend).
• Configure output directory, skipped directories, and file extensions via .doto.json.
• Minimal external dependencies.

How it works

1. Run a scan at your project root.
2. For each TODO without an ID, Doto assigns the next ID and updates the source line to include it.
3. A Markdown file (todo-<id>.md) is created/updated in the tasks vault directory.
4. If a previously indexed TODO is removed from code, its Markdown state is marked as done on the next scan.

Quick Start

Install

Not yet published to NuGet. Until then, install locally from source.

Option A — local .NET tool (recommended during development):

git clone https://github.com/MichalDulski/doto
cd doto
dotnet new tool-manifest
dotnet pack -c Release
dotnet tool install --local <Doto.Cli.PackageId> --add-source ./nupkg

Option B — run directly from source:

git clone https://github.com/MichalDulski/doto
cd doto
dotnet build -c Release
dotnet run --project <path-to-Doto.Cli.csproj> -- scan -p <path-to-your-project>;

Once published to NuGet (planned), you will be able to install globally:

dotnet tool install -g <Doto.Cli.PackageId>

Verify

doto --help
doto --version

Usage

Basic scan:

# Scan current directory
doto scan

# Scan a specific directory
doto scan -p <path-to-project>
# or
doto scan --path <path-to-project>

Notes:

• Recognizes single-line comments: //, #, --.
• Accepts TODO, TODO: or TODO <id> forms.
• Leading tag blocks are supported:
  • // TODO [ui,backend] implement feature

  • TODO (ui,backend) implement feature

When a new ID is assigned, Doto writes a Markdown file under the vault directory.

Configuration (.doto.json)

Place a .doto.json file at your project root to customize behavior.

Defaults (current example):

{
"todosDir": "../todo-vault",
"skipDirs": ["bin", "obj", ".git"],
"extensions": [".cs", ".ts", ".tsx", ".sql"]
}

• todosDir: Folder where Markdown tasks are stored.
• skipDirs: Directory names to skip while scanning.
• extensions: File extensions to include in the scan.

Markdown task format

Each task is stored as todo-<id>.md with YAML front‑matter.

Example:

---
id: 1
title: (ui) [test] add new styles
date: 2025-09-12
state: todo
source_path: ui/button.js
source_line: 4
---

# : (ui) [test] add new styles

Origin: `ui/button.js:4`

Fields:

• id: Numeric (for now, enough for single dev usage) ID assigned by the scanner.
• title: The TODO text (kept in sync with source).
• date: Creation date (YYYY-MM-DD).
• tags: Optional YAML list if tags are detected.
• state: todo | done.
• done_date: Added when state becomes done.
• source_path, source_line: Pointers back to the originating file/line.

Development

Build:

dotnet build -c Debug
dotnet build -c Release

Run tests (if/when available):

dotnet test

Local tool workflow:

dotnet new tool-manifest
dotnet pack -c Release
dotnet tool install --local <Doto.Cli.PackageId> --add-source ./nupkg

Code style:

dotnet format

Roadmap

Work-in-progress. Track issues and milestones in the repository.

Contributing

Contributions are welcome!

• Commit style: Conventional Commits (e.g., feat:, fix:, chore:, docs:, refactor:).
• Open issues/PRs on GitHub with clear reproduction steps or before/after examples.
• Please include tests where applicable.

Guidelines will be added in a future CONTRIBUTING.md. No CODE_OF_CONDUCT.md yet.

Versioning and Releases

• Versioning: SemVer.
• Releases: Manual for now; planned automation later.
• Changelog: Derived from Conventional Commits in commit history.
• Breaking changes: None formalized yet; will be called out in release notes when automation is in place.

Support

Use GitHub Issues for questions, bug reports, and feature requests.

License

See LICENSE for details.