debtlens 0.1.0

package/docs/rules.md

@@ -0,0 +1,139 @@
+# DebtLens Rules
+
+DebtLens rules are heuristics. They should produce review prompts, not absolute judgments. Every issue includes confidence, evidence, and a suggested maintainer action.
+
+## `large-component`
+
+Flags React-style PascalCase functions that exceed line, hook, or branch thresholds.
+
+Default thresholds:
+
+- `large-component.maxLines`: 250
+- `large-component.maxBranches`: 16
+- `large-component.maxHooks`: 10
+
+Why it matters: large components often combine rendering, data loading, state coordination, and business rules. AI-assisted edits can make this worse because adding code is easier than preserving boundaries.
+
+Good fixes:
+
+- extract rendering subcomponents
+- move derived state to `useMemo`
+- move imperative workflows to named hooks
+- split independent features behind composition boundaries
+
+## `state-sprawl`
+
+Flags components/hooks with many calls to local stateful hooks such as `useState`, `useReducer`, and `useRef`.
+
+Default threshold:
+
+- `state-sprawl.maxStatefulHooks`: 6
+
+Why it matters: many independent state variables usually mean a component is coordinating several workflows. This raises the cost of every future change.
+
+Good fixes:
+
+- consolidate related transitions in a reducer
+- extract a domain hook
+- move server/cache state into the data layer
+- delete unused state before adding new state
+
+## `effect-complexity`
+
+Flags long, branchy, or overloaded `useEffect` calls.
+
+Default thresholds:
+
+- `effect-complexity.maxLines`: 30
+- `effect-complexity.maxDependencies`: 8
+
+Why it matters: effects are common hiding places for race conditions, duplicated fetching, stale dependencies, and side effects that should be modeled explicitly.
+
+Good fixes:
+
+- split unrelated effects
+- replace derived-state effects with memoized values
+- move async workflows into named functions
+- use framework data loading where appropriate
+
+## `duplicate-logic`
+
+Finds structurally similar functions/components after comments, identifiers, strings, and numeric literals are normalized.
+
+Default thresholds:
+
+- `duplicate-logic.minSimilarity`: 0.86
+- `duplicate-logic.minLines`: 8
+- `duplicate-logic.maxSnippets`: 450
+
+Why it matters: AI assistants can produce plausible variants of the same logic in multiple files. Duplicate implementations make bug fixes and behavior changes harder.
+
+Good fixes:
+
+- compare the two implementations manually
+- extract shared behavior if the variation is stable
+- delete the weaker duplicate if it was accidental
+- keep duplication only when coupling would be worse than repetition
+
+## `dead-abstraction`
+
+Flags short wrappers that delegate to one call, return one value, or render one JSX element without meaningful behavior.
+
+Default threshold:
+
+- `dead-abstraction.maxWrapperLines`: 8
+
+Why it matters: unnecessary wrappers create names and files that future maintainers must understand, even when they add no durable boundary.
+
+Good fixes:
+
+- inline the wrapper
+- keep it only if it is a stable domain boundary
+- add the missing behavior that justifies the abstraction
+
+## `prop-drilling`
+
+Flags components that forward many props to child components.
+
+Default threshold:
+
+- `prop-drilling.maxForwardedProps`: 4
+
+Why it matters: prop drilling can make components into pass-through plumbing instead of meaningful boundaries.
+
+Good fixes:
+
+- colocate data ownership closer to consumers
+- use composition slots
+- extract a stable context for cross-cutting values
+- reduce prop surface area
+
+## `todo-comment`
+
+Flags debt markers in comments, including TODO, FIXME, HACK, temporary, placeholder, and assistant-generation markers.
+
+Why it matters: a comment can be a legitimate marker, but untracked markers often become permanent.
+
+Good fixes:
+
+- create a tracked issue
+- add a removal condition
+- fix the debt before more code depends on it
+- delete stale comments that no longer describe reality
+
+## `naming-drift`
+
+Flags files where related domain concepts are represented by many competing names.
+
+Default threshold:
+
+- `naming-drift.minVariants`: 4
+
+Why it matters: inconsistent names create translation work for every maintainer and can hide duplicate domain models.
+
+Good fixes:
+
+- pick one canonical domain term
+- rename adapters at system boundaries
+- document vocabulary in a module README
+- add typed domain models where possible

package/docs/showcase-expensify-app.md

@@ -0,0 +1,119 @@
+# Showcase: Maintainability signals in a large production React Native codebase (Expensify/App)
+
+This report shows DebtLens running against [Expensify/App](https://github.com/Expensify/App), a large, real-world React Native application. It is a curated sample of the most useful findings, intended to demonstrate the kinds of maintainability signals DebtLens surfaces in a mature production codebase.
+
+## Why this repo?
+
+- **MIT-licensed and public** — freely available to scan and quote.
+- **Production-scale** — ~6,200 TypeScript/TSX files under `src/` alone.
+- **Actively maintained** — a high-traffic repo with continuous contributions.
+- **Real-world React Native** — exactly the kind of app DebtLens is built for (React Native, TypeScript, hooks-heavy UI).
+
+It is a great showcase precisely *because* it is large, active, and well-engineered: maintainability signals in a codebase this size are about managing scale and review burden, not about code quality in any pejorative sense.
+
+## Important disclaimer
+
+**DebtLens findings are heuristic signals, not proof of defects.** Every item below is a prompt for human review — "this might be worth a look" — not a verdict. Large components, forwarded props, and duplicated structure are often deliberate, justified, and perfectly correct in context. DebtLens does not execute code, does not understand intent, and makes **no claim about how any code was written or generated**. Treat these as conversation starters for maintainers, weighted by the confidence score shown.
+
+## How this report was generated
+
+```bash
+# Cloned Expensify/App and scanned a scoped subset (the component library),
+# not the whole repository.
+debtlens scan src/components --min-severity info --format markdown
+```
+
+- **Scope:** `src/components/` only (1,681 files scanned) — a representative slice, not the full repo.
+- **Repo revision:** `c59a4ce` (2026-06-01).
+- **DebtLens:** v0.1, 8 rules, ~3.8s to scan the subset.
+
+### Signal volume in the scanned subset
+
+| Rule | Count |
+| --- | --- |
+| prop-drilling | 361 |
+| large-component | 184 |
+| todo-comment | 144 |
+| effect-complexity | 60 |
+| dead-abstraction | 58 |
+| state-sprawl | 38 |
+| duplicate-logic | 5 |
+| naming-drift | 1 |
+
+In a codebase this size, the raw counts matter less than the *shape* of the signal. The curated findings below are the ones a maintainer is most likely to find worth a look. (For real adoption, DebtLens's `--write-baseline` mode records existing signals so a team only sees newly introduced ones on each PR.)
+
+---
+
+## Curated findings
+
+### Near-duplicate structure (consider sharing)
+
+These are high-confidence structural matches — pairs of functions/components with the same shape. Sometimes that is intentional parallelism; sometimes it is an opportunity to share one implementation.
+
+**`Checkbox.tsx` ≈ `RadioButton.tsx`** — confidence **100%**
+> `Checkbox` is structurally near-identical to `RadioButton` (29 vs 28 lines). Two selection controls that may share more than they currently do.
+
+**`AnchorForAttachmentsOnly/index.tsx` ≈ `AnchorForCommentsOnly/index.tsx`** — confidence **100%**
+> Two anchor variants with the same 9-line shape. A candidate for a single parameterized component.
+
+**`Icon/ExpensifyIconLoader.ts` ≈ `Icon/IllustrationLoader.ts`** — confidence **100%** (two matched pairs)
+> `loadExpensifyIconsChunk` ≈ `loadIllustrationsChunk` and `loadExpensifyIcon` ≈ `loadIllustration` — parallel lazy-loaders that could potentially share a generic loader.
+
+**`SentrySendToggle` ≈ `SentryDebugToggle`** (`SentryDebugToolMenu.tsx`) — confidence **100%**
+> Two 13-line toggles in the same file with identical structure.
+
+### Components carrying many responsibilities
+
+These are the largest component bodies in the subset by line count, hook usage, and branch points. Large components are common and often justified in feature-rich screens; DebtLens simply flags the extremes as candidates for extraction.
+
+| Component | File | Signal |
+| --- | --- | --- |
+| `Search` | `Search/index.tsx:274` | ~1,611-line body, 121 hooks, 135 branch points |
+| `MoneyRequestView` | `ReportActionItem/MoneyRequestView.tsx:180` | ~1,191-line body, 46 hooks, 102 branches |
+| `MoneyRequestReportTransactionList` | `MoneyRequestReportView/MoneyRequestReportTransactionList.tsx:170` | ~791-line body, 75 hooks |
+| `TimePicker` | `TimePicker/TimePicker.tsx:118` | ~778-line body, 101 branches |
+
+*(Line counts are DebtLens-measured component-body spans; `--threshold large-component.maxLines` is tunable per project.)*
+
+### Local state concentrated in one component
+
+High counts of stateful hooks can indicate a component coordinating several workflows — sometimes a good candidate for a reducer or an extracted hook.
+
+- **`BaseVideoPlayer`** (`VideoPlayer/BaseVideoPlayer.tsx:35`) — 19 stateful hook calls (confidence 82%).
+- **`MoneyRequestReportActionsList`** (`MoneyRequestReportView/MoneyRequestReportActionsList.tsx:87`) — 16 stateful hook calls.
+
+### Overloaded effects
+
+`useEffect` blocks that are long or carry many dependencies can be harder to reason about and re-run more often than intended.
+
+- **`useSearchFocusSync.ts:64`** — a 46-line effect with 14 dependencies and 6 branches (confidence 80%).
+- **`DistanceRequestController.tsx:183`** — a 25-line effect with 14 dependencies.
+
+### Wide prop surfaces
+
+These components forward many props onward. A wide forwarding surface can be a deliberate, well-typed API for a flexible primitive — or, at the extreme, a sign that data is threading through several layers. Worth a glance either way.
+
+- **`MenuItem.tsx:609`** — forwards 63 props across 13 child components (confidence 73%).
+- **`Button/index.tsx:302`** — forwards 43 props across 3 children.
+
+> Note: for highly configurable primitives like `MenuItem` and `Button`, a broad prop surface is frequently intentional. This is exactly the kind of signal that benefits from human judgment rather than an automated verdict.
+
+### Debt-marker comments
+
+DebtLens surfaces `TODO`/`FIXME`/`HACK`/workaround markers that the authors themselves left in the code — useful for tracking and triage. A few honest examples (quoted verbatim):
+
+- `ChronosTimerHeaderButton.tsx:61` — *"There is still a possible bug where if you are offline, the button could reflect the wrong state. However, there is really no way to fix this without breaking the offline experience."*
+- `Attachments/AttachmentCarousel/extractAttachments.ts:76` — *"We apply this small hack to add an image extension and ensure AttachmentView renders the image."*
+- `AvatarCropModal/Slider.tsx:70` — *"pointerEventsNone is a workaround to make sure the pan gesture works correctly on mobile safari."*
+
+These are normal, responsible engineering breadcrumbs — DebtLens just makes them easy to find and convert into tracked issues.
+
+---
+
+## Takeaways
+
+- In a production React Native codebase of this scale, the highest-value signals were **near-duplicate components** (clear, actionable) and a small number of **very large components** concentrating responsibilities.
+- The breadth of `prop-drilling` and `todo-comment` counts reflects the size of the codebase; in practice a team would adopt with `--write-baseline` and review only newly introduced signals on each PR.
+- Every finding here is a **heuristic prompt for review**, not a defect report, and says nothing about how the code was authored.
+
+*Generated with [DebtLens](https://github.com/ColumbusLabs/debtlens). Thresholds and rules are configurable; see the README.*

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "debtlens",
+  "version": "0.1.0",
+  "description": "Find maintainability debt common in fast-moving AI-assisted TypeScript, React, React Native, Expo, and Next.js codebases.",
+  "type": "module",
+  "homepage": "https://github.com/ColumbusLabs/DebtLens#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ColumbusLabs/DebtLens.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ColumbusLabs/DebtLens/issues"
+  },
+  "bin": {
+    "debtlens": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts scan examples/react --format terminal",
+    "scan:example": "tsx src/cli/index.ts scan examples/react --format markdown",
+    "test": "node scripts/test.mjs",
+    "test:all": "npm run typecheck && npm run typecheck:tests && npm run test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
+    "schema:generate": "node --import tsx scripts/generate-schema.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "technical-debt",
+    "static-analysis",
+    "react",
+    "react-native",
+    "typescript",
+    "ai-code-review",
+    "cli",
+    "maintainability"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "fast-glob": "^3.3.3",
+    "ts-morph": "^28.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}

package/schema/debtlens.config.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/ColumbusLabs/debtlens/main/schema/debtlens.config.schema.json",
+  "title": "DebtLens configuration",
+  "description": "Configuration for the DebtLens static-analysis CLI.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "include": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Glob patterns to scan."
+    },
+    "exclude": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Glob patterns to skip."
+    },
+    "minSeverity": {
+      "enum": [
+        "info",
+        "low",
+        "medium",
+        "high"
+      ],
+      "description": "Lowest severity to report."
+    },
+    "rules": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "large-component",
+          "state-sprawl",
+          "effect-complexity",
+          "duplicate-logic",
+          "dead-abstraction",
+          "prop-drilling",
+          "todo-comment",
+          "naming-drift"
+        ]
+      },
+      "description": "Rule ids to run. Omit to run all rules."
+    },
+    "maxFiles": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Maximum number of files to scan."
+    },
+    "thresholds": {
+      "type": "object",
+      "description": "Per-rule numeric threshold overrides.",
+      "properties": {
+        "large-component.maxLines": {
+          "type": "number"
+        },
+        "large-component.maxBranches": {
+          "type": "number"
+        },
+        "large-component.maxHooks": {
+          "type": "number"
+        },
+        "state-sprawl.maxStatefulHooks": {
+          "type": "number"
+        },
+        "effect-complexity.maxLines": {
+          "type": "number"
+        },
+        "effect-complexity.maxDependencies": {
+          "type": "number"
+        },
+        "duplicate-logic.minSimilarity": {
+          "type": "number"
+        },
+        "duplicate-logic.minLines": {
+          "type": "number"
+        },
+        "duplicate-logic.maxSnippets": {
+          "type": "number"
+        },
+        "dead-abstraction.maxWrapperLines": {
+          "type": "number"
+        },
+        "prop-drilling.maxForwardedProps": {
+          "type": "number"
+        },
+        "naming-drift.minVariants": {
+          "type": "number"
+        },
+        "duplicate-logic.minStructuralSimilarity": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": {
+        "type": "number"
+      }
+    },
+    "vocabulary": {
+      "type": "object",
+      "description": "Naming-drift concept groups (concept id -> competing terms).",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}