debtlens 0.1.0

package/dist/utils/git.js

@@ -0,0 +1,68 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+function git(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function gitSafe(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return "";
+    }
+}
+export function isGitRepo(cwd) {
+    try {
+        return git(cwd, ["rev-parse", "--is-inside-work-tree"]) === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Collect changed files as absolute paths. Returns `null` when `cwd` is not inside a
+ * git work tree, so the caller can degrade gracefully.
+ *
+ * - With `base`, includes the committed diff `base...HEAD` (merge-base — the PR's own
+ *   changes). An unknown `base` throws a clear error.
+ * - Always unions in uncommitted working-tree changes vs HEAD and untracked files.
+ * - Deletions are excluded (`--diff-filter=d`) since deleted files cannot be scanned.
+ */
+export function getChangedFiles(cwd, base) {
+    if (!isGitRepo(cwd))
+        return null;
+    let root;
+    try {
+        root = git(cwd, ["rev-parse", "--show-toplevel"]);
+    }
+    catch {
+        return null;
+    }
+    const relative = new Set();
+    const add = (output) => {
+        for (const line of output.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed)
+                relative.add(trimmed);
+        }
+    };
+    if (base) {
+        try {
+            add(git(cwd, ["diff", "--name-only", "--diff-filter=d", `${base}...HEAD`]));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Could not diff against base ref "${base}": ${message}`);
+        }
+    }
+    // Uncommitted changes vs HEAD (staged + unstaged) and untracked files. Best-effort:
+    // a brand-new repo with no commits has no HEAD, which is fine.
+    add(gitSafe(cwd, ["diff", "--name-only", "--diff-filter=d", "HEAD"]));
+    add(gitSafe(cwd, ["ls-files", "--others", "--exclude-standard"]));
+    return { root, files: [...relative].map((path) => resolve(root, path)) };
+}
+//# sourceMappingURL=git.js.map

package/dist/utils/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,SAAS,GAAG,CAAC,GAAW,EAAE,IAAc;IACtC,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;QAC/B,GAAG;QACH,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;KACpC,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,OAAO,CAAC,GAAW,EAAE,IAAc;IAC1C,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC,KAAK,MAAM,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAOD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,IAAa;IACxD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjC,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,GAAG,GAAG,CAAC,MAAc,EAAE,EAAE;QAC7B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,OAAO;gBAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,GAAG,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAI,MAAM,OAAO,EAAE,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IAED,oFAAoF;IACpF,+DAA+D;IAC/D,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACtE,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAElE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;AAC3E,CAAC"}

package/dist/utils/hostComponents.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in UI primitives that are PascalCase but are *not* user-defined child
+ * components. Forwarding props to these (e.g. `onPress` to a `Pressable`, `style` to a
+ * `View`) is ordinary composition, not prop drilling. Covers React Native core plus the
+ * common icon/gradient/blur libraries used across the RN/Expo ecosystem.
+ */
+export declare const HOST_COMPONENTS: Set<string>;
+/**
+ * Returns true if a JSX tag name refers to a host primitive (so it should be ignored
+ * as a "child component"). Handles namespaced tags like `Animated.View`.
+ */
+export declare function isHostComponent(tagName: string): boolean;

package/dist/utils/hostComponents.js

@@ -0,0 +1,57 @@
+/**
+ * Built-in UI primitives that are PascalCase but are *not* user-defined child
+ * components. Forwarding props to these (e.g. `onPress` to a `Pressable`, `style` to a
+ * `View`) is ordinary composition, not prop drilling. Covers React Native core plus the
+ * common icon/gradient/blur libraries used across the RN/Expo ecosystem.
+ */
+export const HOST_COMPONENTS = new Set([
+    // React Native core
+    "View",
+    "Text",
+    "Image",
+    "ImageBackground",
+    "ScrollView",
+    "FlatList",
+    "SectionList",
+    "VirtualizedList",
+    "Pressable",
+    "TouchableOpacity",
+    "TouchableHighlight",
+    "TouchableWithoutFeedback",
+    "TouchableNativeFeedback",
+    "TextInput",
+    "Switch",
+    "Modal",
+    "ActivityIndicator",
+    "Button",
+    "RefreshControl",
+    "StatusBar",
+    "SafeAreaView",
+    "KeyboardAvoidingView",
+    "Animated",
+    // Common ecosystem libraries
+    "LinearGradient",
+    "BlurView",
+    "MaterialIcons",
+    "MaterialCommunityIcons",
+    "Ionicons",
+    "Feather",
+    "FontAwesome",
+    "FontAwesome5",
+    "AntDesign",
+    "Entypo",
+    "Octicons",
+    "SimpleLineIcons",
+    "Fontisto",
+    "Foundation",
+    "Zocial",
+]);
+/**
+ * Returns true if a JSX tag name refers to a host primitive (so it should be ignored
+ * as a "child component"). Handles namespaced tags like `Animated.View`.
+ */
+export function isHostComponent(tagName) {
+    const base = tagName.split(".").pop() ?? tagName;
+    return HOST_COMPONENTS.has(base) || HOST_COMPONENTS.has(tagName);
+}
+//# sourceMappingURL=hostComponents.js.map

package/dist/utils/hostComponents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostComponents.js","sourceRoot":"","sources":["../../src/utils/hostComponents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAS;IAC7C,oBAAoB;IACpB,MAAM;IACN,MAAM;IACN,OAAO;IACP,iBAAiB;IACjB,YAAY;IACZ,UAAU;IACV,aAAa;IACb,iBAAiB;IACjB,WAAW;IACX,kBAAkB;IAClB,oBAAoB;IACpB,0BAA0B;IAC1B,yBAAyB;IACzB,WAAW;IACX,QAAQ;IACR,OAAO;IACP,mBAAmB;IACnB,QAAQ;IACR,gBAAgB;IAChB,WAAW;IACX,cAAc;IACd,sBAAsB;IACtB,UAAU;IACV,6BAA6B;IAC7B,gBAAgB;IAChB,UAAU;IACV,eAAe;IACf,wBAAwB;IACxB,UAAU;IACV,SAAS;IACT,aAAa;IACb,cAAc;IACd,WAAW;IACX,QAAQ;IACR,UAAU;IACV,iBAAiB;IACjB,UAAU;IACV,YAAY;IACZ,QAAQ;CACT,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC;IACjD,OAAO,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACnE,CAAC"}

package/dist/utils/identifiers.d.ts

@@ -0,0 +1,3 @@
+export declare function splitIdentifier(value: string): string[];
+export declare function isPascalCase(value: string): boolean;
+export declare function isHookName(value: string): boolean;

package/dist/utils/identifiers.js

@@ -0,0 +1,20 @@
+const stopWords = new Set([
+    "get", "set", "use", "is", "has", "with", "from", "to", "by", "for", "and", "or", "the", "a", "an",
+    "component", "props", "state", "data", "item", "items", "value", "values", "result", "results"
+]);
+export function splitIdentifier(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_\-./]/g, " ")
+        .toLowerCase()
+        .split(/\s+/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 2 && !stopWords.has(part));
+}
+export function isPascalCase(value) {
+    return /^[A-Z][A-Za-z0-9]*$/.test(value);
+}
+export function isHookName(value) {
+    return /^use[A-Z0-9]/.test(value);
+}
+//# sourceMappingURL=identifiers.js.map

package/dist/utils/identifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.js","sourceRoot":"","sources":["../../src/utils/identifiers.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI;IAClG,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS;CAC/F,CAAC,CAAC;AAEH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK;SACT,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,WAAW,EAAE;SACb,KAAK,CAAC,KAAK,CAAC;SACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/utils/lines.d.ts

@@ -0,0 +1,8 @@
+import type { Node } from "ts-morph";
+export declare function nodeLineSpan(node: Node): {
+    startLine: number;
+    endLine: number;
+    lines: number;
+};
+export declare function lineAt(content: string, lineNumber: number): string;
+export declare function countLines(text: string): number;

package/dist/utils/lines.js

@@ -0,0 +1,19 @@
+export function nodeLineSpan(node) {
+    const source = node.getSourceFile();
+    const start = source.getLineAndColumnAtPos(node.getStart());
+    const end = source.getLineAndColumnAtPos(node.getEnd());
+    return {
+        startLine: start.line,
+        endLine: end.line,
+        lines: Math.max(1, end.line - start.line + 1),
+    };
+}
+export function lineAt(content, lineNumber) {
+    return content.split(/\r?\n/)[lineNumber - 1] ?? "";
+}
+export function countLines(text) {
+    if (!text)
+        return 0;
+    return text.split(/\r?\n/).length;
+}
+//# sourceMappingURL=lines.js.map

package/dist/utils/lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lines.js","sourceRoot":"","sources":["../../src/utils/lines.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,IAAI;QACrB,OAAO,EAAE,GAAG,CAAC,IAAI;QACjB,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAe,EAAE,UAAkB;IACxD,OAAO,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;AACpC,CAAC"}

package/dist/utils/similarity.d.ts

@@ -0,0 +1,8 @@
+export declare function normalizeSnippet(source: string): string;
+export declare function shingle(value: string, size?: number): Set<string>;
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+/**
+ * Cosine similarity between two token-count vectors (multisets). Used to compare the
+ * structural fingerprints of two functions before the more expensive text-shingle step.
+ */
+export declare function cosineSimilarity(a: Map<string, number>, b: Map<string, number>): number;

package/dist/utils/similarity.js

@@ -0,0 +1,63 @@
+export function normalizeSnippet(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, " ")
+        .replace(/\/\/.*$/gm, " ")
+        .replace(/(['"`])(?:\\.|(?!\1).)*\1/g, "__str__")
+        .replace(/\b\d+(?:\.\d+)?\b/g, "__num__")
+        .replace(/\b[A-Za-z_$][\w$]*\b/g, (token) => keywordSet.has(token) ? token : "__id__")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function shingle(value, size = 5) {
+    const tokens = value.split(/\s+/).filter(Boolean);
+    const shingles = new Set();
+    for (let i = 0; i <= tokens.length - size; i += 1) {
+        shingles.add(tokens.slice(i, i + size).join(" "));
+    }
+    if (shingles.size === 0 && tokens.length > 0) {
+        shingles.add(tokens.join(" "));
+    }
+    return shingles;
+}
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection += 1;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Cosine similarity between two token-count vectors (multisets). Used to compare the
+ * structural fingerprints of two functions before the more expensive text-shingle step.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (const [key, value] of a) {
+        normA += value * value;
+        const other = b.get(key);
+        if (other)
+            dot += value * other;
+    }
+    for (const value of b.values()) {
+        normB += value * value;
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dot / denominator;
+}
+const keywordSet = new Set([
+    "if", "else", "for", "while", "do", "switch", "case", "break", "continue", "return", "const", "let", "var",
+    "function", "class", "extends", "implements", "interface", "type", "import", "export", "default", "from", "async",
+    "await", "try", "catch", "finally", "throw", "new", "this", "super", "true", "false", "null", "undefined",
+    "useState", "useEffect", "useMemo", "useCallback", "useReducer", "useRef"
+]);
+//# sourceMappingURL=similarity.js.map

package/dist/utils/similarity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.js","sourceRoot":"","sources":["../../src/utils/similarity.ts"],"names":[],"mappings":"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"}

package/docs/architecture.md

@@ -0,0 +1,68 @@
+# DebtLens Architecture
+
+DebtLens has four layers:
+
+1. CLI input parsing
+2. scan orchestration
+3. detectors
+4. reporters
+
+## CLI
+
+`src/cli/index.ts` uses Commander to parse command-line options. It loads JSON config, merges CLI overrides, runs the scanner, renders the selected report format, and handles `--fail-on` exit behavior.
+
+## Scanner
+
+`src/core/scan.ts` resolves files with `fast-glob`, creates a `ts-morph` project, loads source files, runs selected detectors, filters by minimum severity, and returns a stable `ScanResult` object.
+
+The scanner does not execute project code.
+
+## Detectors
+
+A detector implements:
+
+```ts
+export interface Detector {
+  id: string;
+  name: string;
+  description: string;
+  defaultSeverity: Severity;
+  tags: string[];
+  detect: (context: DetectorContext) => Promise<DebtIssue[]> | DebtIssue[];
+}
+```
+
+Each detector receives parsed `ts-morph` source files plus threshold helpers. The rule should return reviewable issues with evidence and a suggestion.
+
+Current detectors live in `src/detectors`.
+
+## Reporters
+
+Reporters convert `ScanResult` to terminal text, JSON, or Markdown.
+
+Future reporters should use the same `ScanResult` object so downstream integrations can remain stable.
+
+Planned reporters:
+
+- SARIF
+- GitHub PR comment
+- compact CI summary
+
+## Why JSON config only?
+
+DebtLens intentionally starts with JSON config rather than JavaScript config. Static-analysis tools should avoid executing arbitrary project code by default. A plugin API can come later with clear security boundaries.
+
+## Future plugin model
+
+Potential design:
+
+```ts
+export default defineDebtLensPlugin({
+  rules: [myDetector],
+  vocabulary: {
+    "commerce-entity": ["product", "sku", "item", "listing"]
+  }
+});
+```
+
+Plugin loading should be explicit and disabled in untrusted CI contexts.

package/docs/example-report.md

@@ -0,0 +1,141 @@
+# DebtLens Report
+
+Scanned **3** files with **8** rules in **174ms**.
+
+## Summary
+
+- Total issues: **10**
+- High: **2**
+- Medium: **2**
+- Low: **4**
+- Info: **2**
+
+## High severity
+
+### Prop drilling — `src/Dashboard.tsx:13`
+
+Dashboard forwards 7 props across 3 child components.
+
+Confidence: **73%**
+
+Evidence:
+- ReleaseHero: movie, userId, region, theme, onSelect, onSave
+- ReleaseGrid: movie, userId, region, theme, onSelect, onSave, onShare
+- ReleaseFooter: movie, userId, region, theme, onShare
+
+Suggestion: Consider colocating the data owner closer to consumers, using a composition slot, or extracting a focused context for stable cross-cutting values.
+
+### Duplicate logic — `src/duplicateOne.ts:1`
+
+normalizeMovieRelease is 100% structurally similar to normalizeGameRelease.
+
+Confidence: **100%**
+
+Evidence:
+- src/duplicateOne.ts:1-18 (18 lines)
+- src/duplicateTwo.ts:1-18 (18 lines)
+
+Suggestion: Compare the two implementations. Extract shared behavior only if the variation is intentional and stable; otherwise delete the weaker duplicate.
+
+
+## Medium severity
+
+### State sprawl — `src/Dashboard.tsx:13`
+
+Dashboard manages 7 stateful hook calls. This often means one component is coordinating several unrelated workflows.
+
+Confidence: **82%**
+
+Evidence:
+- Stateful hooks: useState, useState, useState, useState, useState, useState, useState
+
+Suggestion: Group related state in a reducer, extract state machines into a hook, or move server/cache state out of component state.
+
+### Effect complexity — `src/Dashboard.tsx:23`
+
+This useEffect spans 26 lines, has 9 dependencies, 3 branches, and 14 nested calls.
+
+Confidence: **80%**
+
+Evidence:
+- Lines: 26 / 30
+- Dependencies: 9 / 8
+- Branches: 3
+- Contains async work
+
+Suggestion: Split unrelated effects, move imperative workflows into named functions, or replace derived state effects with memoized values.
+
+
+## Low severity
+
+### Debt marker comment — `src/Dashboard.tsx:22`
+
+Comment contains a todo marker.
+
+Confidence: **90%**
+
+Evidence:
+- // TODO: split this when the launch rush is over.
+
+Suggestion: Convert the marker into a tracked issue, add a removal condition, or fix it before more code depends on it.
+
+### Dead abstraction — `src/Dashboard.tsx:67`
+
+ReleaseHero looks like a thin wrapper: it only forwards to a single JSX element.
+
+Confidence: **68%**
+
+Evidence:
+- { return <section>{props.movie.title}</section>; }
+
+Suggestion: Keep the wrapper only if it creates a stable domain boundary. Otherwise inline it or add the missing behavior where this abstraction belongs.
+
+### Dead abstraction — `src/Dashboard.tsx:71`
+
+ReleaseGrid looks like a thin wrapper: it only forwards to a single JSX element.
+
+Confidence: **68%**
+
+Evidence:
+- { return <section>{props.movie.releaseDate}</section>; }
+
+Suggestion: Keep the wrapper only if it creates a stable domain boundary. Otherwise inline it or add the missing behavior where this abstraction belongs.
+
+### Dead abstraction — `src/Dashboard.tsx:75`
+
+ReleaseFooter looks like a thin wrapper: it only forwards to a single JSX element.
+
+Confidence: **68%**
+
+Evidence:
+- { return <footer>{props.region}</footer>; }
+
+Suggestion: Keep the wrapper only if it creates a stable domain boundary. Otherwise inline it or add the missing behavior where this abstraction belongs.
+
+
+## Info severity
+
+### Naming drift — `src/duplicateOne.ts:1`
+
+This file uses 4 competing terms for release timing: date, air, launch, release.
+
+Confidence: **62%**
+
+Evidence:
+- Concept group: time-of-release
+- Variants found: date, air, launch, release
+
+Suggestion: Pick a canonical domain name and rename adapters at system boundaries instead of mixing boundary names throughout the feature.
+
+### Naming drift — `src/duplicateTwo.ts:1`
+
+This file uses 4 competing terms for release timing: date, air, launch, release.
+
+Confidence: **62%**
+
+Evidence:
+- Concept group: time-of-release
+- Variants found: date, air, launch, release
+
+Suggestion: Pick a canonical domain name and rename adapters at system boundaries instead of mixing boundary names throughout the feature.
+

package/docs/good-first-issues.md

@@ -0,0 +1,63 @@
+# Good first issues
+
+Scoped, self-contained tasks for new contributors. Each lists where to start and how to
+verify. Open these as GitHub issues (label `good-first-rule` / `good-first-issue`) once
+the repo is public. See [`CONTRIBUTING.md`](../CONTRIBUTING.md) for setup.
+
+## Rules
+
+### 1. Make the `prop-drilling` host-component list configurable
+The ignore list of UI primitives lives in [`src/utils/hostComponents.ts`](../src/utils/hostComponents.ts).
+Add an optional config key (e.g. `propDrilling.ignoreComponents`) that extends it, so
+teams can register their own design-system primitives.
+- Touch: `src/core/types.ts`, `src/config/*`, `src/detectors/propDrilling.ts`, schema.
+- Verify: a test where a custom-ignored component is not counted.
+
+### 2. Teach `large-component` to recognize more component forms
+Today it only classifies PascalCase function/arrow components
+([`src/utils/ast.ts`](../src/utils/ast.ts) `collectFunctionLikes`). It misses
+`memo(function X(){})`, `forwardRef(...)`, and class components.
+- Verify: fixtures for each form in `tests/detectors/largeComponent.test.ts`.
+
+### 3. Reduce `naming-drift` false positives on domain-rich apps
+The built-in media vocabulary treats distinct domain entities (e.g. `movie` vs `show`)
+as "competing names." Options: raise the default `minVariants`, add a config switch to
+disable the built-in pack, or require co-occurrence in the same identifier.
+- Touch: [`src/detectors/namingDrift.ts`](../src/detectors/namingDrift.ts).
+- Verify: a media-style fixture that should NOT fire by default.
+
+### 4. Configurable markers for `todo-comment`
+Allow projects to add/replace the marker patterns
+([`src/detectors/todoComment.ts`](../src/detectors/todoComment.ts)) via config.
+- Verify: a custom marker fires; a removed default does not.
+
+## Reporters & integrations
+
+### 5. Add `helpUri` to SARIF rules
+In [`src/reporters/sarifReporter.ts`](../src/reporters/sarifReporter.ts), point each
+rule's `helpUri` at its section in `docs/rules.md` so code-scanning links to docs.
+- Verify: extend `tests/reporters/sarifReporter.test.ts`.
+
+### 6. Snapshot test for the Markdown reporter
+Add a fixture-based test that scans `examples/react` and asserts the Markdown matches a
+committed snapshot (normalizing the elapsed-ms line), guarding `docs/example-report.md`.
+
+### 7. Publish the config JSON schema to a stable URL
+The schema is generated to `schema/debtlens.config.schema.json`
+([`src/config/schema.ts`](../src/config/schema.ts)). Wire up hosting (e.g. GitHub Pages
+or SchemaStore) and confirm the `$schema` URL in the `init` template resolves.
+
+## CLI / DX
+
+### 8. Add a summary-only / `--quiet` output mode
+Print just the counts line and exit code, useful for CI logs.
+- Touch: `src/cli/index.ts`, `src/reporters/terminalReporter.ts`.
+
+### 9. Respect `.gitignore` when resolving files
+Optionally skip files ignored by git during a scan, in addition to the configured
+`exclude` globs.
+- Touch: `src/core/scan.ts` (file resolution).
+
+### 10. Document each rule's false-positive guidance
+Expand [`docs/rules.md`](./rules.md) with a "When this is a false positive" note per
+rule, mirroring the guards in the detector tests.