react-detective 0.0.0-stage → 0.1.1

package/dist/server.d.ts

@@ -0,0 +1,292 @@
+import http, { IncomingMessage, ServerResponse } from 'node:http';
+import { z } from 'zod';
+
+interface DetectiveServerOptions {
+    /** Project root; source paths and the agent's working directory are relative to it. */
+    root: string;
+    /**
+     * Model for explanations: an alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID.
+     * Default `"sonnet"`.
+     */
+    model?: string;
+    maxTurns?: number;
+    /** Knowledge folder name inside the project root. Default `.react-detective`. */
+    storeDir?: string;
+    /** URL prefix the handler answers on. */
+    base?: string;
+}
+type Next = (err?: unknown) => void;
+/**
+ * Connect-style middleware shared by the Vite plugin (mounted on Vite's own
+ * server) and the standalone server used for Next.js and other bundlers.
+ */
+declare function createDetectiveHandler(opts: DetectiveServerOptions): (req: IncomingMessage, res: ServerResponse, next?: Next) => Promise<void>;
+
+interface CommitInfo {
+    sha: string;
+    author: string;
+    date: string;
+    subject: string;
+}
+interface HeadInfo {
+    commit: string;
+    branch: string;
+}
+/** Thin, read-only, never-throwing wrapper around the git CLI. */
+declare class Git {
+    private repo;
+    private readonly cwd;
+    constructor(cwd: string);
+    isRepo(): Promise<boolean>;
+    head(): Promise<HeadInfo | null>;
+    /** True if any of the files have uncommitted changes (or are untracked). */
+    isDirty(files: string[]): Promise<boolean>;
+    catBlob(sha: string): Promise<string | null>;
+    recentCommits(file: string, limit?: number): Promise<CommitInfo[]>;
+    logText(file: string, limit: number): Promise<string>;
+    blameText(file: string, start: number, end: number): Promise<string>;
+    showText(commit: string): Promise<string>;
+    private run;
+}
+
+/** One prop as a call site passes it: `title="Kitchen sink"`, `count={count}`, `{...rest}`. */
+interface PassedProp {
+    /** The prop's name; "..." for a spread, "children" for what's written between the tags. */
+    name: string;
+    /** As written: `"Kitchen sink"`, `count`, `() => save(id)`, `true` for a bare attribute. */
+    value: string;
+    /** When the value is a name (`{query}`, `{user.name}`): the line in the same file where that name is declared. */
+    line?: number;
+}
+/** Where a component is rendered, with what it's given there. */
+interface UsedIn {
+    /** `path:line`. */
+    ref: string;
+    /** The component that renders it there, e.g. "App". */
+    parent?: string;
+    props?: PassedProp[];
+}
+
+declare const CardSchema: z.ZodObject<{
+    summary: z.ZodString;
+    props: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        optional: z.ZodBoolean;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+    outline: z.ZodArray<z.ZodObject<{
+        children: z.ZodArray<z.ZodObject<{
+            children: z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    function: "function";
+                    state: "state";
+                    ref: "ref";
+                    context: "context";
+                    store: "store";
+                    hook: "hook";
+                    derived: "derived";
+                    memo: "memo";
+                    callback: "callback";
+                    effect: "effect";
+                    render: "render";
+                    constant: "constant";
+                }>;
+                name: z.ZodString;
+                line: z.ZodNumber;
+                type: z.ZodString;
+                initial: z.ZodString;
+                returns: z.ZodString;
+                when: z.ZodString;
+                explanation: z.ZodString;
+            }, z.core.$strip>>;
+            kind: z.ZodEnum<{
+                function: "function";
+                state: "state";
+                ref: "ref";
+                context: "context";
+                store: "store";
+                hook: "hook";
+                derived: "derived";
+                memo: "memo";
+                callback: "callback";
+                effect: "effect";
+                render: "render";
+                constant: "constant";
+            }>;
+            name: z.ZodString;
+            line: z.ZodNumber;
+            type: z.ZodString;
+            initial: z.ZodString;
+            returns: z.ZodString;
+            when: z.ZodString;
+            explanation: z.ZodString;
+        }, z.core.$strip>>;
+        kind: z.ZodEnum<{
+            function: "function";
+            state: "state";
+            ref: "ref";
+            context: "context";
+            store: "store";
+            hook: "hook";
+            derived: "derived";
+            memo: "memo";
+            callback: "callback";
+            effect: "effect";
+            render: "render";
+            constant: "constant";
+        }>;
+        name: z.ZodString;
+        line: z.ZodNumber;
+        type: z.ZodString;
+        initial: z.ZodString;
+        returns: z.ZodString;
+        when: z.ZodString;
+        explanation: z.ZodString;
+    }, z.core.$strip>>;
+    usedIn: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strip>>;
+    history: z.ZodArray<z.ZodObject<{
+        commit: z.ZodString;
+        date: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        why: z.ZodString;
+    }, z.core.$strip>>;
+    fileNotes: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        summary: z.ZodString;
+        exports: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type OutlineFields = {
+    type?: string;
+    initial?: string;
+    when?: string;
+    returns?: string;
+    /** For a name a custom hook gives (from source only): the returned property, or array position ("0"), it reads. */
+    reads?: string;
+    /** For context and stores (from source only): what it reads, e.g. "ThemeContext" or "navigator.onLine". */
+    from?: string;
+    /** For an effect (from source only): the built-in that runs it, e.g. "useLayoutEffect". */
+    hook?: string;
+};
+type RawCard = Omit<z.infer<typeof CardSchema>, "fileNotes">;
+type RawItem = RawCard["outline"][number];
+/** Any depth: built from source, renders follow the JSX tree. (The model's schema allows two levels.) */
+type OutlineItem = Omit<RawItem, "type" | "initial" | "when" | "returns" | "children"> & OutlineFields & {
+    children: OutlineItem[];
+};
+/** Call sites carry what they pass (read from source), on top of the model's `path:line`. */
+type Card = Omit<RawCard, "outline" | "usedIn"> & {
+    outline: OutlineItem[];
+    usedIn: UsedIn[];
+    v?: number;
+};
+
+interface ExplainRequest {
+    component: string;
+    /** Project-relative path, e.g. `src/components/UserCard.tsx`. May be absent for parents we only know by name. */
+    file?: string;
+    line?: number;
+    /** Outer → inner component names, as seen in the page. */
+    chain?: string[];
+    /** Serialized live props / state from the running app (client components only). */
+    props?: unknown;
+    state?: unknown;
+    /** Text of the element the developer pointed at, to anchor "this button" style questions. */
+    elementText?: string;
+    /** Free-form follow-up question about this component. */
+    question?: string;
+}
+/** What we already know, so the agent can skip work. */
+interface ExplainContext {
+    /** Summaries of files whose content is verified unchanged since they were written. */
+    notes?: Record<string, string>;
+    /** A previous explanation that is outdated because some files it relied on changed. */
+    previous?: {
+        markdown: string;
+        changes: FileChange[];
+        unchanged: string[];
+    };
+    /** Recent commits touching the component's file, newest first. */
+    history?: CommitInfo[];
+    /** The current (fresh) explanation of the component, as background for a question. */
+    explanation?: string;
+    /** Still-valid Q&A about this component, then about related ones (those have `component` set). */
+    pastQuestions?: {
+        question: string;
+        answer: string;
+        component?: string;
+    }[];
+    /** Full source of files the agent would open first (the component's own file, imports without notes). Counts as read. */
+    sources?: Record<string, string>;
+    /** Where the component is rendered, from a text search: `path:line`. */
+    usages?: string[];
+    /** What the component's file imports from project files, with saved descriptions still valid for the current code. */
+    imports?: ImportedExport[];
+}
+interface ImportedExport {
+    /** Name as imported (`default` for a default import). */
+    name: string;
+    /** The file the import statement points at. */
+    from: string;
+    /** Where it is declared, when that differs from `from` (re-exported through a barrel file). */
+    declaredIn?: string;
+    line: number;
+    kind: string;
+    signature: string;
+    description: string;
+}
+interface FileChange {
+    file: string;
+    /** Unified diff from the explained version to now, when the old version could be recovered. */
+    diff?: string;
+    deleted?: boolean;
+}
+interface ExplainOptions {
+    root: string;
+    model?: string;
+    maxTurns?: number;
+    signal?: AbortSignal;
+    onProgress?: (text: string) => void;
+    context?: ExplainContext;
+    /** When set, the agent also gets read-only git history tools. */
+    git?: Git;
+    /** Anthropic API key the agent signs in with. */
+    apiKey: string;
+}
+interface ExplainResult {
+    /** Markdown answer (questions) or a markdown rendering of the card (explanations). */
+    markdown: string;
+    /** Structured explanation, rendered as visual sections by the panel. */
+    card?: Card;
+    /** Project-relative files the agent opened. */
+    filesRead: string[];
+    /** Per-file summaries the agent wrote for the files it read. */
+    notes: Record<string, string>;
+    /** Per-file descriptions of each export (file → export name → description). */
+    exports: Record<string, Record<string, string>>;
+    costUsd?: number;
+    /** Agent steps (model calls) the run took. */
+    turns?: number;
+    /** The model that actually answered (resolved from an alias like "sonnet"). */
+    model?: string;
+}
+declare function explainComponent(req: ExplainRequest, opts: ExplainOptions): Promise<ExplainResult>;
+
+declare const DEFAULT_PORT = 5899;
+/**
+ * Starts the explain server on 127.0.0.1. Resolves to `null` (without throwing)
+ * if the port is already taken, which happens when frameworks evaluate their
+ * config in several processes. The first one wins and the others reuse it.
+ */
+declare function startDetectiveServer(opts: DetectiveServerOptions & {
+    port?: number;
+    silent?: boolean;
+}): Promise<http.Server | null>;
+
+export { DEFAULT_PORT, type DetectiveServerOptions, type ExplainRequest, createDetectiveHandler, explainComponent, startDetectiveServer };

package/dist/server.js

@@ -0,0 +1,15 @@
+import {
+  DEFAULT_PORT,
+  startDetectiveServer
+} from "./chunk-6EJCTAJS.js";
+import {
+  createDetectiveHandler,
+  explainComponent
+} from "./chunk-5TDNB3DH.js";
+import "./chunk-E23QXCCY.js";
+export {
+  DEFAULT_PORT,
+  createDetectiveHandler,
+  explainComponent,
+  startDetectiveServer
+};

package/dist/vite.d.ts

@@ -0,0 +1,17 @@
+import { Plugin } from 'vite';
+
+interface DetectiveViteOptions {
+    /** Model for explanations: an alias (`"sonnet"`, `"haiku"`, `"opus"`) or a full model ID. Default `"sonnet"`. */
+    model?: string;
+    maxTurns?: number;
+    /** Knowledge folder inside the project root. Default `.react-detective`. */
+    storeDir?: string;
+    /** Inject the overlay into index.html automatically. Default true. */
+    injectClient?: boolean;
+    /** Show the Detective badge in the corner. Default true. */
+    showLauncher?: boolean;
+}
+/** Vite plugin: dev-only. Production builds are left completely untouched. */
+declare function detective(options?: DetectiveViteOptions): Plugin;
+
+export { type DetectiveViteOptions, detective as default, detective };

package/dist/vite.js

@@ -0,0 +1,132 @@
+import {
+  reloadingHandler
+} from "./chunk-5TDNB3DH.js";
+import "./chunk-E23QXCCY.js";
+
+// src/transform.ts
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import MagicString from "magic-string";
+import path from "path";
+var traverse = _traverse.default ?? _traverse;
+var LOC_ATTR = "data-rd-loc";
+var COMP_ATTR = "data-rd-comp";
+var FILE_RE = /\.[cm]?[jt]sx?$/;
+var SKIP_TAGS = /* @__PURE__ */ new Set(["html", "head", "meta", "title", "script", "style", "link", "base", "noscript"]);
+function transformJsx(code, id, root) {
+  const filename = id.split("?")[0];
+  if (!FILE_RE.test(filename) || filename.includes("node_modules")) return null;
+  if (!code.includes("<")) return null;
+  const isTs = /\.[cm]?tsx?$/.test(filename);
+  if (isTs && !filename.endsWith("x")) return null;
+  let ast;
+  try {
+    ast = parse(code, {
+      sourceType: "module",
+      errorRecovery: true,
+      plugins: isTs ? ["jsx", "typescript", "decorators-legacy"] : ["jsx", "decorators-legacy"]
+    });
+  } catch {
+    return null;
+  }
+  const rel = path.relative(root, filename).split(path.sep).join("/");
+  const s = new MagicString(code);
+  let changed = false;
+  traverse(ast, {
+    JSXOpeningElement(p) {
+      const name = p.node.name;
+      if (name.type !== "JSXIdentifier") return;
+      const tag = name.name;
+      if (!/^[a-z]/.test(tag) || SKIP_TAGS.has(tag)) return;
+      const hasAttr = p.node.attributes.some(
+        (a) => a.type === "JSXAttribute" && a.name.type === "JSXIdentifier" && a.name.name === LOC_ATTR
+      );
+      if (hasAttr || name.end == null || !p.node.loc) return;
+      const comp = findComponentName(p, filename);
+      const { line, column } = p.node.loc.start;
+      let attrs = ` ${LOC_ATTR}="${rel}:${line}:${column + 1}"`;
+      if (comp) attrs += ` ${COMP_ATTR}="${comp}"`;
+      s.appendLeft(name.end, attrs);
+      changed = true;
+    }
+  });
+  if (!changed) return null;
+  return { code: s.toString(), map: s.generateMap({ source: filename, hires: true, includeContent: true }) };
+}
+function findComponentName(p, filename) {
+  let cur = p.getFunctionParent();
+  while (cur) {
+    const name = functionName(cur);
+    if (name && /^[A-Z]/.test(name)) return name;
+    if (!name && isDefaultExport(cur)) return componentNameFromFile(filename);
+    cur = cur.parentPath?.getFunctionParent() ?? null;
+  }
+  return null;
+}
+function functionName(fn) {
+  const node = fn.node;
+  if ((node.type === "FunctionDeclaration" || node.type === "FunctionExpression") && node.id) return node.id.name;
+  if (node.type === "ClassMethod" || node.type === "ClassPrivateMethod") {
+    const cls = fn.parentPath?.parentPath?.node;
+    if (cls && (cls.type === "ClassDeclaration" || cls.type === "ClassExpression") && cls.id) return cls.id.name;
+  }
+  let parent = fn.parentPath;
+  while (parent && parent.node.type === "CallExpression") parent = parent.parentPath;
+  if (parent?.node.type === "VariableDeclarator" && parent.node.id.type === "Identifier") return parent.node.id.name;
+  return null;
+}
+function isDefaultExport(fn) {
+  let parent = fn.parentPath;
+  while (parent && parent.node.type === "CallExpression") parent = parent.parentPath;
+  return parent?.node.type === "ExportDefaultDeclaration";
+}
+function componentNameFromFile(filename) {
+  let base = path.basename(filename).replace(FILE_RE, "");
+  if (["page", "layout", "index", "template", "loading", "error", "not-found"].includes(base)) {
+    const dir = path.basename(path.dirname(filename));
+    const label = base[0].toUpperCase() + base.slice(1).replace(/-(\w)/g, (_, c) => c.toUpperCase());
+    return dir && !dir.startsWith("(") && dir !== "app" && dir !== "pages" ? `${pascal(dir)}${label}` : label;
+  }
+  return pascal(base);
+}
+function pascal(s) {
+  return s.replace(/[[\]]/g, "").replace(/(^|[-_.\s]+)(\w)/g, (_, __, c) => c.toUpperCase());
+}
+
+// src/vite.ts
+var VIRTUAL_ID = "virtual:react-detective";
+var BASE = "/__detective";
+function detective(options = {}) {
+  let root = process.cwd();
+  return {
+    name: "react-detective",
+    apply: "serve",
+    // Run before @vitejs/plugin-react so we see the original JSX.
+    enforce: "pre",
+    configResolved(config) {
+      root = config.root;
+    },
+    transform(code, id) {
+      return transformJsx(code, id, root);
+    },
+    configureServer(server) {
+      const opts = { root, model: options.model, maxTurns: options.maxTurns, storeDir: options.storeDir, base: BASE };
+      server.middlewares.use(reloadingHandler(opts, () => server.ws.send({ type: "full-reload" })));
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID || id === `/@id/${VIRTUAL_ID}`) return "\0" + VIRTUAL_ID;
+    },
+    load(id) {
+      if (id === "\0" + VIRTUAL_ID) return `import { init } from "react-detective/client";
+init({ endpoint: ${JSON.stringify(BASE)}, showLauncher: ${options.showLauncher !== false} });`;
+    },
+    transformIndexHtml() {
+      if (options.injectClient === false) return;
+      return [{ tag: "script", attrs: { type: "module", src: `/@id/${VIRTUAL_ID}` }, injectTo: "body" }];
+    }
+  };
+}
+export {
+  detective as default,
+  detective
+};

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "react-detective",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Hover any React component to see what it is, where it lives, and an AI explanation of what it does.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/headbranch/react-detective.git"
+  },
+  "homepage": "https://github.com/headbranch/react-detective#readme",
+  "bugs": {
+    "url": "https://github.com/headbranch/react-detective/issues"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "require": "./dist/next.cjs"
+    },
+    "./next/loader": {
+      "require": "./dist/loader.cjs",
+      "import": "./dist/loader.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "react-detective": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "dev": "tsup --watch",
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "release": "release-it"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.296",
+    "@babel/parser": "^8.0.7",
+    "@babel/traverse": "^8.0.7",
+    "diff": "^9.0.0",
+    "launch-editor": "^2.14.2",
+    "magic-string": "^1.4.3",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.28.0",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "release-it": "^20.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.4"
+  }
+}