@devds1989/t-rush 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devesh Chandra Srivastava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@devds1989/t-rush",
+  "version": "1.0.0",
+  "description": "Speedrun your TODOs, FIXMEs, and BUGs.",
+  "type": "module",
+  "bin": {
+    "trush": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "todo",
+    "fixme",
+    "cli",
+    "productivity",
+    "speedrun",
+    "developer-tools"
+  ],
+  "author": "Devesh",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/confirm": "^5.1.9",
+    "@inquirer/search": "^4.1.9",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "nanospinner": "^1.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "tsx": "^4.22.1",
+    "typescript": "^6.0.3"
+  }
+}

package/src/commands/history.ts

@@ -0,0 +1,107 @@
+import chalk from "chalk";
+import { loadData } from "../store.js";
+import { badge } from "../ui.js";
+import type { RunRecord } from "../types/types.js";
+
+function formatDate(iso: string): string {
+  const d = new Date(iso);
+  return d.toLocaleDateString("en-GB", {
+    day: "2-digit",
+    month: "short",
+    year: "numeric",
+  });
+}
+
+function formatDuration(seconds: number): string {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  if (m > 0) return `${m}m ${s}s`;
+  return `${s}s`;
+}
+
+function statusIcon(completed: boolean): string {
+  return completed ? chalk.green("✔") : chalk.red("✘");
+}
+
+function printRow(run: RunRecord): void {
+  const date = chalk.dim(formatDate(run.startedAt));
+  const status = statusIcon(run.completed);
+  const type = badge(run.type);
+  const file = chalk.dim(run.file + ":" + run.line);
+  const text = chalk.white(
+    run.text.length > 40 ? run.text.slice(0, 40) + "…" : run.text,
+  );
+  const duration = chalk.cyan(formatDuration(run.duration));
+  const repo = chalk.gray(`[${run.repo}]`);
+
+  console.log(`  ${status}  ${date}  ${type}  ${duration}  ${file}`);
+  console.log(`        ${text}  ${repo}`);
+  console.log();
+}
+
+type HistoryOptions = {
+  limit?: number;
+  type?: string;
+  repo?: string;
+  completed?: boolean;
+};
+
+function filterRuns(runs: RunRecord[], opts: HistoryOptions): RunRecord[] {
+  let filtered = [...runs].reverse(); // most recent first
+
+  if (opts.type) {
+    const t = opts.type.toUpperCase();
+    filtered = filtered.filter((r) => r.type === t);
+  }
+
+  if (opts.repo) {
+    filtered = filtered.filter((r) => r.repo.includes(opts.repo!));
+  }
+
+  if (opts.completed !== undefined) {
+    filtered = filtered.filter((r) => r.completed === opts.completed);
+  }
+
+  if (opts.limit) {
+    filtered = filtered.slice(0, opts.limit);
+  }
+
+  return filtered;
+}
+
+export function history(opts: HistoryOptions = {}): void {
+  const data = loadData();
+
+  if (data.runs.length === 0) {
+    console.log();
+    console.log(chalk.gray("  No runs yet. Start one with: trush start"));
+    console.log();
+    return;
+  }
+
+  const runs = filterRuns(data.runs, { limit: 20, ...opts });
+
+  if (runs.length === 0) {
+    console.log();
+    console.log(chalk.gray("  No runs match that filter."));
+    console.log();
+    return;
+  }
+
+  const width = 50;
+  const line = chalk.gray("─".repeat(width));
+
+  console.log();
+  console.log(chalk.white.bold("  Run History"));
+  console.log(
+    chalk.gray(`  showing ${runs.length} of ${data.runs.length} total`),
+  );
+  console.log();
+  console.log(line);
+  console.log();
+
+  runs.forEach(printRow);
+
+  console.log(line);
+  console.log();
+}

package/src/commands/start.ts

@@ -0,0 +1,145 @@
+import { createSpinner } from "nanospinner";
+import search from "@inquirer/search";
+import chalk from "chalk";
+import path from "path";
+
+import { scanRepo } from "../scanner.js";
+import { openEditor } from "../editor.js";
+import { validateTodo } from "../validator.js";
+import { createTimer } from "../timer.js";
+import { addRun, generateId, getRepoName } from "../store.js";
+import { incrementStreak, resetStreak, getStats } from "../streak.js";
+import {
+  badge,
+  formatTodoChoice,
+  formatValidation,
+  printResult,
+  printNoTodos,
+  warn,
+} from "../ui.js";
+import type { TodoItem } from "../types/types.js";
+
+async function pickTodo(items: TodoItem[]): Promise<TodoItem> {
+  const answer = await search<TodoItem>({
+    message: "Pick a TODO, FIXME, or BUG to fix",
+    source: async (input) => {
+      const term = (input ?? "").toLowerCase();
+      return items
+        .filter(
+          (item) =>
+            item.text.toLowerCase().includes(term) ||
+            item.file.toLowerCase().includes(term) ||
+            item.type.toLowerCase().includes(term),
+        )
+        .map((item) => ({
+          name: formatTodoChoice(item),
+          value: item,
+        }));
+    },
+  });
+
+  return answer;
+}
+
+async function confirmComplete(): Promise<boolean> {
+  const confirm = (await import("@inquirer/confirm")).default;
+  return confirm({ message: "Did you complete it?" });
+}
+
+async function confirmAnyway(): Promise<boolean> {
+  const confirm = (await import("@inquirer/confirm")).default;
+  return confirm({
+    message: chalk.yellow("TODO still present. Mark as complete anyway?"),
+    default: false,
+  });
+}
+
+export async function start(cwd: string = process.cwd()): Promise<void> {
+  // 1. scan
+  const scanSpinner = createSpinner("Scanning repo...").start();
+  const items = await scanRepo(cwd);
+
+  if (items.length === 0) {
+    scanSpinner.success({ text: "Scan complete" });
+    printNoTodos();
+    return;
+  }
+
+  scanSpinner.success({
+    text: `Found ${chalk.white.bold(items.length)} items`,
+  });
+
+  // 2. pick
+  const picked = await pickTodo(items);
+  const filePath = path.resolve(cwd, picked.file);
+
+  console.log();
+  console.log(
+    `  ${badge(picked.type)} ${chalk.dim(picked.file)}${chalk.dim(":") + chalk.cyan(picked.line)}`,
+  );
+  console.log(`  ${chalk.gray('"' + picked.text + '"')}`);
+  console.log();
+
+  // 3. open editor + timer
+  const timerSpinner = createSpinner(
+    "Timer running — close editor to stop",
+  ).start();
+  const timer = createTimer();
+  openEditor(filePath, picked.line);
+  const timerResult = timer.stop();
+  timerSpinner.success({ text: chalk.white(timerResult.formatted) });
+
+  // 4. validate
+  const validateSpinner = createSpinner("Validating...").start();
+  await new Promise((res) => setTimeout(res, 600)); // brief pause so it feels intentional
+  const validation = validateTodo(
+    filePath,
+    picked.line,
+    picked.rawLine,
+    picked.type,
+  );
+  validateSpinner.stop();
+
+  console.log(`  ${formatValidation(validation)}`);
+  console.log();
+
+  // 5. confirm
+  let completed = false;
+
+  if (validation.status === "done") {
+    completed = await confirmComplete();
+  } else if (validation.status === "unchanged") {
+    console.log(`  ${warn("Still seeing the " + picked.type)}`);
+    completed = await confirmAnyway();
+  } else if (validation.status === "missing") {
+    completed = await confirmComplete();
+  }
+
+  // 6. update streak + stats
+  const streak = completed ? incrementStreak(picked.type) : resetStreak();
+
+  const stats = getStats();
+
+  // 7. save run
+  addRun({
+    id: generateId(),
+    repo: getRepoName(cwd),
+    file: picked.file,
+    line: picked.line,
+    text: picked.text,
+    type: picked.type,
+    startedAt: timerResult.startedAt,
+    finishedAt: timerResult.finishedAt,
+    duration: timerResult.duration,
+    completed,
+  });
+
+  // 8. result card
+  printResult({
+    item: picked,
+    duration: timerResult.formatted,
+    streak,
+    stats,
+    completed,
+  });
+}

package/src/commands/stats.ts

@@ -0,0 +1,109 @@
+import chalk from "chalk";
+import { loadData } from "../store.js";
+import { getStreak, getStats } from "../streak.js";
+import { CommentType } from "../types/types.js";
+import type { RunRecord } from "../types/types.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function avgDuration(runs: RunRecord[]): string {
+  const completed = runs.filter((r) => r.completed && r.duration > 0);
+  if (completed.length === 0) return "N/A";
+
+  const avg = Math.floor(
+    completed.reduce((acc, r) => acc + r.duration, 0) / completed.length,
+  );
+  const m = Math.floor(avg / 60);
+  const s = avg % 60;
+
+  if (m > 0) return `${m}m ${s}s`;
+  return `${s}s`;
+}
+
+function fastestRun(runs: RunRecord[]): string {
+  const completed = runs.filter((r) => r.completed && r.duration > 0);
+  if (completed.length === 0) return "N/A";
+
+  const fastest = completed.reduce((a, b) => (a.duration < b.duration ? a : b));
+  const m = Math.floor(fastest.duration / 60);
+  const s = fastest.duration % 60;
+
+  const time = m > 0 ? `${m}m ${s}s` : `${s}s`;
+  return `${time} ${chalk.dim(`(${fastest.file}:${fastest.line})`)}`;
+}
+
+function completionRate(runs: RunRecord[]): string {
+  if (runs.length === 0) return "N/A";
+  const rate = Math.round(
+    (runs.filter((r) => r.completed).length / runs.length) * 100,
+  );
+  const color =
+    rate >= 80 ? chalk.green : rate >= 50 ? chalk.yellow : chalk.red;
+  return color(`${rate}%`);
+}
+
+function topRepo(runs: RunRecord[]): string {
+  if (runs.length === 0) return "N/A";
+
+  const counts: Record<string, number> = {};
+  runs.forEach((r) => {
+    counts[r.repo] = (counts[r.repo] ?? 0) + 1;
+  });
+
+  const top = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
+  return `${chalk.white(top[0])} ${chalk.dim(`(${top[1]} runs)`)}`;
+}
+
+function row(label: string, value: string): void {
+  const padded = label.padEnd(20, " ");
+  console.log(`  ${chalk.dim(padded)} ${value}`);
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+export function stats(): void {
+  const data = loadData();
+  const streak = getStreak();
+  const s = getStats();
+  const runs = data.runs;
+
+  const width = 50;
+  const line = chalk.gray("─".repeat(width));
+
+  console.log();
+  console.log(chalk.white.bold("  Stats"));
+  console.log();
+  console.log(line);
+  console.log();
+
+  // streak
+  console.log(`  ${chalk.yellow.bold("Streak")}`);
+  row("Current", chalk.white.bold(String(streak.current)));
+  row("Last", chalk.white(String(streak.last)));
+  row("Longest", chalk.white(String(streak.longest)));
+  console.log();
+
+  // runs
+  console.log(`  ${chalk.cyan.bold("Runs")}`);
+  row("Completed", chalk.green(String(s.totalCompleted)));
+  row("Aborted", chalk.red(String(s.totalAborted)));
+  row("Completion rate", completionRate(runs));
+  console.log();
+
+  // by type
+  console.log(`  ${chalk.white.bold("By Type")}`);
+  row("TODO", chalk.blue(String(s.byType[CommentType.TODO])));
+  row("FIXME", chalk.yellow(String(s.byType[CommentType.FIXME])));
+  row("BUG", chalk.red(String(s.byType[CommentType.BUG])));
+  console.log();
+
+  // performance
+  console.log(`  ${chalk.white.bold("Performance")}`);
+  row("Avg time", chalk.white(avgDuration(runs)));
+  row("Fastest run", fastestRun(runs));
+  row("Top repo", topRepo(runs));
+  console.log();
+
+  console.log(line);
+  console.log();
+}

package/src/editor.ts

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+import type { SpawnSyncOptions } from "node:child_process";
+import { EditorConfig, SupportedEditors } from "./types/types";
+
+const EDITORS: Record<SupportedEditors, EditorConfig> = {
+  nvim: {
+    bin: {
+      linux: "nvim",
+      win32: "nvim.exe",
+    },
+    args: (file, line) => [`+${line}`, file],
+  },
+  code: {
+    bin: {
+      linux: "code",
+      win32: "code.cmd",
+    },
+    args: (file, line) => ["--goto", `${file}:${line}`],
+  },
+};
+type Platform = "linux" | "win32";
+
+function getPlatform(): Platform {
+  return process.platform === "win32" ? "win32" : "linux";
+}
+
+function detectEditor(): SupportedEditors {
+  const env = process.env.EDITOR ?? "";
+
+  if (env.includes("nvim")) return "nvim";
+  if (env.includes("code")) return "code";
+
+  // fallback: default per platform
+  return getPlatform() === "win32" ? "code" : "nvim";
+}
+
+function getBin(editor: SupportedEditors): string {
+  return EDITORS[editor].bin[getPlatform()];
+}
+
+function getArgs(
+  editor: SupportedEditors,
+  file: string,
+  line: number,
+): string[] {
+  return EDITORS[editor].args(file, line);
+}
+
+export function openEditor(file: string, line: number): void {
+  const editor = detectEditor();
+  const bin = getBin(editor);
+  const args = getArgs(editor, file, line);
+
+  const options: SpawnSyncOptions = {
+    stdio: "inherit",
+    // code on windows needs a shell to resolve .cmd
+    shell: getPlatform() === "win32" && editor === "code",
+  };
+
+  const result = spawnSync(bin, args, options);
+
+  if (result.error) {
+    throw new Error(`Failed to open editor: ${result.error.message}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env -S npx tsx
+
+import { Command } from "commander";
+import { start } from "./commands/start.js";
+import { history } from "./commands/history.js";
+import { stats } from "./commands/stats.js";
+
+const program = new Command();
+
+program
+  .name("t-rush")
+  .description("Speedrun your TODOs, FIXMEs, and BUGs")
+  .version("0.1.0");
+
+program
+  .command("start")
+  .description("scan repo, pick a TODO and start a speedrun")
+  .argument("[dir]", "directory to scan", process.cwd())
+  .action(async (dir: string) => {
+    await start(dir);
+  });
+
+program
+  .command("history")
+  .description("show past runs")
+  .option("-l, --limit <n>", "number of runs to show", "20")
+  .option("-t, --type <type>", "filter by type: TODO, FIXME, BUG")
+  .option("-r, --repo <name>", "filter by repo name")
+  .option("--completed", "show only completed runs")
+  .option("--aborted", "show only aborted runs")
+  .action((opts) => {
+    history({
+      limit: parseInt(opts.limit),
+      type: opts.type,
+      repo: opts.repo,
+      completed: opts.completed ? true : opts.aborted ? false : undefined,
+    });
+  });
+
+program
+  .command("stats")
+  .description("show streak, completion rate and performance")
+  .action(() => {
+    stats();
+  });
+
+program.parse();

package/src/scanner.ts

@@ -0,0 +1,136 @@
+import fg from "fast-glob";
+import ignore from "ignore";
+import fs from "fs";
+import path from "path";
+
+export type TodoItem = {
+  type: "TODO" | "FIXME";
+  file: string;
+  line: number;
+  text: string;
+  rawLine: string;
+};
+
+const ALWAYS_IGNORE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/coverage/**",
+  "**/*.min.js",
+  "**/*.lock",
+];
+
+const TODO_REGEX =
+  /(?:\/\/|#|--|%|;|\*)\s*(?:TODO|FIXME)(?:\(.*?\))?[:\s]+(.+)/i;
+
+const TODO_TYPE_REGEX = /(?:TODO|FIXME)/i;
+
+const BINARY_EXTENSIONS = new Set([
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "ico",
+  "svg",
+  "pdf",
+  "zip",
+  "tar",
+  "gz",
+  "rar",
+  "7z",
+  "exe",
+  "bin",
+  "dll",
+  "so",
+  "dylib",
+  "mp3",
+  "mp4",
+  "wav",
+  "mov",
+  "avi",
+  "ttf",
+  "woff",
+  "woff2",
+  "eot",
+  "lock",
+  "map",
+]);
+
+function isBinary(filePath: string): boolean {
+  const ext = path.extname(filePath).replace(".", "").toLowerCase();
+  return BINARY_EXTENSIONS.has(ext);
+}
+
+function loadGitignore(cwd: string): ReturnType<typeof ignore> {
+  const ig = ignore();
+  const gitignorePath = path.join(cwd, ".gitignore");
+
+  if (fs.existsSync(gitignorePath)) {
+    const content = fs.readFileSync(gitignorePath, "utf-8");
+    ig.add(content);
+  }
+
+  return ig;
+}
+
+function parseTodos(filePath: string, cwd: string): TodoItem[] {
+  const items: TodoItem[] = [];
+
+  if (isBinary(filePath)) return items;
+
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return items;
+  }
+
+  // skip if file looks binary despite extension
+  if (content.includes("\0")) return items;
+
+  const lines = content.split("\n");
+
+  lines.forEach((rawLine, index) => {
+    const match = TODO_REGEX.exec(rawLine);
+    if (!match) return;
+
+    const typeMatch = TODO_TYPE_REGEX.exec(rawLine);
+    if (!typeMatch) return;
+
+    items.push({
+      type: typeMatch[0].toUpperCase() as "TODO" | "FIXME",
+      file: path.relative(cwd, filePath),
+      line: index + 1,
+      text: match[1].trim(),
+      rawLine: rawLine.trim(),
+    });
+  });
+
+  return items;
+}
+
+export async function scanRepo(
+  cwd: string = process.cwd(),
+): Promise<TodoItem[]> {
+  const ig = loadGitignore(cwd);
+
+  const files = await fg("**/*", {
+    cwd,
+    absolute: true,
+    onlyFiles: true,
+    ignore: ALWAYS_IGNORE,
+    dot: false,
+  });
+
+  const filtered = files.filter((f) => {
+    const rel = path.relative(cwd, f);
+    return !ig.ignores(rel);
+  });
+
+  const todos = filtered.flatMap((f) => parseTodos(f, cwd));
+
+  return todos;
+}

package/src/store.ts

@@ -0,0 +1,66 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { RunRecord, AppData } from "./types/types";
+import { CommentType } from "./types/types";
+
+const DATA_DIR = path.join(os.homedir(), ".t-rush");
+const DATA_FILE = path.join(DATA_DIR, "data.json");
+
+const DEFAULT_DATA: AppData = {
+  runs: [],
+  streak: {
+    current: 0,
+    last: 0,
+    longest: 0,
+  },
+  stats: {
+    totalCompleted: 0,
+    totalAborted: 0,
+    byType: {
+      [CommentType.TODO]: 0,
+      [CommentType.FIXME]: 0,
+      [CommentType.BUG]: 0,
+    },
+  },
+};
+
+export function loadData(): AppData {
+  if (!fs.existsSync(DATA_DIR)) return structuredClone(DEFAULT_DATA);
+
+  try {
+    const content = fs.readFileSync(DATA_FILE, "utf-8");
+    return JSON.parse(content) as AppData;
+  } catch {
+    return structuredClone(DEFAULT_DATA);
+  }
+}
+
+export function saveData(data: AppData): void {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+
+  const tmp = DATA_FILE + ".tmp";
+
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+    fs.renameSync(tmp, DATA_FILE);
+  } catch (err) {
+    if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    throw err;
+  }
+}
+
+export function addRun(record: RunRecord): void {
+  const data = loadData();
+  data.runs.push(record);
+  saveData(data);
+}
+
+export function getRepoName(cwd: string = process.cwd()): string {
+  const parts = cwd.split(path.sep);
+  return parts[parts.length - 1] || "unknown-repo";
+}
+
+export function generateId(): string {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+}

package/src/streak.ts

@@ -0,0 +1,32 @@
+import { loadData, saveData } from "./store";
+import { CommentType } from "./types/types";
+import { StreakInfo, StatsInfo } from "./types/types";
+
+export function incrementStreak(type: CommentType): StreakInfo {
+  const data = loadData();
+  data.streak.current += 1;
+  data.streak.longest = Math.max(data.streak.longest, data.streak.current);
+  data.stats.totalCompleted += 1;
+  data.stats.byType[type] += 1;
+  saveData(data);
+  return { ...data.streak };
+}
+
+export function resetStreak(): StreakInfo {
+  const data = loadData();
+  data.streak.last = data.streak.current;
+  data.streak.current = 0;
+  data.stats.totalAborted += 1;
+  saveData(data);
+  return { ...data.streak };
+}
+
+export function getStreak(): StreakInfo {
+  const data = loadData();
+  return { ...data.streak };
+}
+
+export function getStats(): StatsInfo {
+  const data = loadData();
+  return { ...data.stats };
+}

package/src/timer.ts

@@ -0,0 +1,33 @@
+import { TimerResult } from "./types/types";
+
+export function formatDuration(seconds: number): string {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+
+  if (h > 0) {
+    return `${h}h ${m}m ${s}s`;
+  } else if (m > 0) {
+    return `${m}m ${s}s`;
+  }
+  return `${s}s`;
+}
+
+export function createTimer() {
+  const startedAt = new Date();
+  const startMs = Date.now();
+
+  function stop(): TimerResult {
+    const finishedAt = new Date();
+    const duration = Math.floor((Date.now() - startMs) / 1000);
+
+    return {
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      duration,
+      formatted: formatDuration(duration),
+    };
+  }
+
+  return { stop };
+}

package/src/types/types.ts

@@ -0,0 +1,70 @@
+export const CommentType = {
+  TODO: "TODO",
+  FIXME: "FIXME",
+  BUG: "BUG",
+} as const;
+
+export type CommentType = (typeof CommentType)[keyof typeof CommentType];
+
+export type TodoItem = {
+  type: CommentType;
+  file: string;
+  line: number;
+  text: string;
+  rawLine: string;
+};
+
+export type RunRecord = {
+  id: string;
+  repo: string;
+  file: string;
+  line: number;
+  text: string;
+  type: CommentType;
+  startedAt: string;
+  finishedAt: string;
+  duration: number;
+  completed: boolean;
+};
+
+export type StreakInfo = {
+  current: number;
+  last: number;
+  longest: number;
+};
+
+export type StatsInfo = {
+  totalCompleted: number;
+  totalAborted: number;
+  byType: Record<CommentType, number>;
+};
+
+export type AppData = {
+  runs: RunRecord[];
+  streak: StreakInfo;
+  stats: StatsInfo;
+};
+
+export type TimerResult = {
+  startedAt: string;
+  finishedAt: string;
+  duration: number;
+  formatted: string; // formatted like "1m 30s"
+};
+
+export type SupportedEditors = "code" | "nvim";
+
+export type EditorConfig = {
+  bin: {
+    linux: string;
+    win32: string;
+  };
+  args: (file: string, line: number) => string[];
+};
+
+export type ValidationStatus = "done" | "unchanged" | "missing";
+
+export type ValidationResult = {
+  status: ValidationStatus;
+  message: string;
+};

package/src/ui.ts

@@ -0,0 +1,124 @@
+import chalk from "chalk";
+import type {
+  StreakInfo,
+  StatsInfo,
+  TodoItem,
+  ValidationResult,
+} from "./types/types.js";
+import { CommentType } from "./types/types.js";
+
+// colors
+export function badge(type: TodoItem["type"]): string {
+  switch (type) {
+    case CommentType.TODO:
+      return chalk.bgBlue.white.bold(` TODO `);
+    case CommentType.FIXME:
+      return chalk.bgYellow.black.bold(` FIXME `);
+    case CommentType.BUG:
+      return chalk.bgRed.white.bold(` BUG `);
+  }
+}
+
+export function formatTodoChoice(item: TodoItem): string {
+  return `${badge(item.type)} ${chalk.dim(item.file)}${chalk.dim(":") + chalk.cyan(item.line)} ${chalk.white(item.text)}`;
+}
+
+export function label(text: string): string {
+  return chalk.gray(text);
+}
+
+export function success(text: string): string {
+  return chalk.green(`✔ ${text}`);
+}
+
+export function failure(text: string): string {
+  return chalk.red(`✘ ${text}`);
+}
+
+export function warn(text: string): string {
+  return chalk.yellow(`⚠ ${text}`);
+}
+
+export function info(text: string): string {
+  return chalk.cyan(`ℹ ${text}`);
+}
+
+export function formatValidation(result: ValidationResult): string {
+  switch (result.status) {
+    case "done":
+      return success(result.message);
+    case "unchanged":
+      return warn(result.message);
+    case "missing":
+      return info(result.message);
+  }
+}
+
+type ResultCardOptions = {
+  item: TodoItem;
+  duration: string;
+  streak: StreakInfo;
+  stats: StatsInfo;
+  completed: boolean;
+};
+
+export function printResult(opts: ResultCardOptions): void {
+  const { item, duration, streak, stats, completed } = opts;
+
+  const width = 50;
+  const line = chalk.gray("─".repeat(width));
+
+  console.log();
+  console.log(line);
+  console.log();
+
+  // status
+  if (completed) {
+    console.log(
+      `  ${chalk.green.bold("✔")}  ${badge(item.type)} ${chalk.white.bold("resolved")}`,
+    );
+  } else {
+    console.log(
+      `  ${chalk.red.bold("✘")}  ${badge(item.type)} ${chalk.white.bold("aborted")}`,
+    );
+  }
+
+  // file + text
+  console.log(`  ${chalk.dim(item.file + ":" + item.line)}`);
+  console.log(`  ${chalk.gray('"' + item.text + '"')}`);
+  console.log();
+
+  // time
+  console.log(`  ${chalk.cyan("⏱")}  ${chalk.white(duration)}`);
+  console.log();
+
+  // streak
+  if (completed) {
+    console.log(
+      `  ${chalk.yellow("")} Streak:   ${chalk.white.bold(streak.current)}  ${chalk.dim(`(longest: ${streak.longest})`)}`,
+    );
+  } else {
+    console.log(
+      `  ${chalk.gray("")} Streak reset  ${chalk.dim(`(last: ${streak.last}  longest: ${streak.longest})`)}`,
+    );
+  }
+
+  // stats
+  console.log();
+  console.log(
+    `  ${chalk.dim("TODO:")}   ${chalk.white(stats.byType[CommentType.TODO])}   ${chalk.dim("FIXME:")} ${chalk.white(stats.byType[CommentType.FIXME])}   ${chalk.dim("BUG:")} ${chalk.white(stats.byType[CommentType.BUG])}`,
+  );
+  console.log(
+    `  ${chalk.dim("Completed:")} ${chalk.green(stats.totalCompleted)}   ${chalk.dim("Aborted:")} ${chalk.red(stats.totalAborted)}`,
+  );
+
+  console.log();
+  console.log(line);
+  console.log();
+}
+
+export function printNoTodos(): void {
+  console.log();
+  console.log(success("No TODOs, FIXMEs, or BUGs found. Clean codebase!"));
+  console.log();
+}

package/src/validator.ts

@@ -0,0 +1,61 @@
+import fs from "fs";
+import { CommentType } from "./types/types.js";
+import { ValidationResult } from "./types/types.js";
+
+const COMMENT_REGEX = /(?:TODO|FIXME|BUG)(?:\(.*?\))?[:\s]/i;
+
+function scanWindow(
+  lines: string[],
+  line: number,
+  originalText: string,
+): boolean {
+  const start = Math.max(0, line - 10);
+  const end = Math.min(lines.length, line + 10);
+  const window = lines.slice(start, end);
+
+  return window.some((l) => l.includes(originalText.trim()));
+}
+
+export function validateTodo(
+  file: string,
+  line: number,
+  originalText: string,
+  type: CommentType,
+): ValidationResult {
+  // file missing or deleted
+  if (!fs.existsSync(file)) {
+    return {
+      status: "missing",
+      message: `${file} not found — was it deleted or moved?`,
+    };
+  }
+
+  const lines = fs.readFileSync(file, "utf-8").split("\n");
+  const exactLine = lines[line - 1]; // 1-indexed
+
+  // exact line no longer exists (file got shorter)
+  if (!exactLine) {
+    return {
+      status: "done",
+      message: `Line ${line} no longer exists — looks done.`,
+    };
+  }
+
+  // exact line still has a TODO/FIXME/BUG comment
+  if (COMMENT_REGEX.test(exactLine)) {
+    // check ±10 window in case user edited around it but didn't remove it
+    const foundInWindow = scanWindow(lines, line - 1, originalText);
+
+    if (foundInWindow) {
+      return {
+        status: "unchanged",
+        message: `${type} still present at ${file}:${line}`,
+      };
+    }
+  }
+
+  return {
+    status: "done",
+    message: `${type} resolved in ${file}`,
+  };
+}