aihand 0.0.1 → 0.1.0

package/src/read/stategraph.ts

@@ -0,0 +1,205 @@
+// 神经图引擎 —— 用 ts-morph 的类型检查器把 App 的「状态空间」从全量引用流里长出来。
+//
+// 坍缩两处独立的 `const X = create({...})` 词法硬编码（state.ts 的 CREATE_QUERY、grow.ts
+// 的 callee.text==='create'）。它俩本质是同一真理（状态空间）的两个投影,却退化成两份匹配器,
+// 换工厂名/换 import 别名/store 挪窝两边各自静默漏。这里一处取代,且回答了局部匹配答不出的
+// 问题:**哪些是控制大局的中心状态点**——从引用流的位置(中心性)涌现,不是看节点长什么样。
+//
+// 引擎离线:跑在 `aihand read` / build 时,绝不进浏览器、绝不进 per-HMR 热路径(ts-morph 拖
+// 整个 tsconfig Project,冷启 ~2s)。grow 的 tree-sitter 路径作浏览器零-AST 兜底保留。
+//
+// 节点分类(两条正交静态信号,零正则):module-level VariableDeclaration —
+//   ① 初值 CallExpression ∧ 绑定类型含响应式 marker 字段 → STATE(store)
+//   ② 初值 arrow/fn/class                              → VIEW(纯函数/组件,排除;Button/Dialog/Card 落这里)
+// 中心性只在 STATE 子图上算:findReferencesAsNodes → 引用次数 + 跨文件辐射,rank 降序。
+//
+// 信号① 是【构造无关】判据(给整个前端世界用的兑现):身份来自返回类型的【结构特征】——
+// 工厂调用造出的对象带一个框架注入的响应式指纹字段(MobX 本仓 `_loading`、zustand `getState`、
+// valtio 的 proxy symbol)——不来自工厂【名字】。`v.getType().getProperty(marker)` 命中即 store,
+// 不看 callee 叫 create / createStore / defineStore / 任意名,换框架/换别名/挪窝全不漏。
+// marker 默认 `_loading`(本仓 lib/mobx.ts 约定),由 config.runtime.storeMarker 覆盖。
+//
+// 三条被证伪的弯路(实跑本仓 284 文件 ts-morph 探针,化石留此免重走):
+//  · callee 名 ==='create':局部名字匹配,换框架瞎——这是本判据取代掉的旧实现。
+//  · 读写图 writes-count(被多处写=状态枢纽):既漏(topicStore/bot.data 等 5 个 getter-only
+//    派生 store 外部 writes=0)又纳(dbPromise/syncing 等 6 个私有缓存 writes≥2)。写不写是
+//    使用模式不是身份。
+//  · 中心性硬阈值 files≥N:topicStore 跨 20 文件 vs bot.data 仅 1 文件,与 defineSkill/
+//    createBrowserRouter 同辐射层,纯图位置切不开真 store 与另类工厂。中心性只配作排序,非身份。
+//
+// 曾有第三信号「let/var → state」实跑全仓证伪砍掉:抓 17 个私有缓存/标志 0 个真 store。
+
+import type { Node, Project, VariableDeclaration } from 'ts-morph'
+import type { Field, Grown } from '../ui/self/grow.js'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import process from 'node:process'
+import { Node as TsNode, SyntaxKind } from 'ts-morph'
+
+// 一个状态节点 = 它的静态结构(Grown) + 在状态子图里的中心性度量。
+export interface StateNode extends Grown {
+    refs: number  // findReferencesAsNodes 总引用数(引用密度)
+    files: number // 引用去重源文件数(跨文件辐射)
+    rank: number  // refs + files*3 —— 辐射加权,实跑足以让 store 置顶、组件出局
+}
+
+// 镜像 refactor.ts 的 openProject:带 compilerOptions.paths + 真 include 的 tsconfig。
+// solution-style 根 tsconfig(files:[] + references)没有源图,优先 app 那份。
+export async function openProject(cwd: string = process.cwd()): Promise<Project> {
+    const { Project } = await import('ts-morph')
+    const tsConfigFilePath = ['tsconfig.app.json', 'tsconfig.json'].map(f => resolve(cwd, f)).find(existsSync)
+    // 抛错而非 process.exit:openProject 是导出库函数,被 discover() 在 vite 插件(storeSchema.load)
+    // 里调——process.exit 会静默杀掉用户 dev server,连 catch 机会都没有(违诊断纤维律:把可恢复的
+    // 配置缺失坍缩成杀进程死局)。抛 Error 让调用者(CLI 入口 / vite)各自决定如何报。
+    if (!tsConfigFilePath)
+        throw new Error(`stategraph: no tsconfig.json (or tsconfig.app.json) found under ${cwd}`)
+    return new Project({ tsConfigFilePath })
+}
+
+// 只看 module-level(变量语句的直接父是 SourceFile)——局部变量不是 App 的状态空间。
+function isModuleLevel(v: VariableDeclaration): boolean {
+    const stmt = v.getVariableStatement()
+    return !!stmt && stmt.getParent()?.getKind() === SyntaxKind.SourceFile
+}
+
+const DEFAULT_STORE_MARKER = '_loading'
+
+// 构造无关的 store 判据:绑定 v 的初值是工厂【调用】,且 v 的【类型】含响应式指纹字段 marker。
+// 不看 callee 名——身份来自返回类型的结构特征(框架注入的 `_loading`/`getState`/…),换工厂名/
+// 换 import 别名/挪窝全命中。判据要 v 的类型而非 init 本身:`create(state, opts)` 的 init 是
+// CallExpression,其【返回类型】(即 v 的类型)才带 marker。getProperty 走 checker,解推断/交叉类型。
+function isStateFactory(v: VariableDeclaration, marker: string): boolean {
+    const init = v.getInitializer()
+    if (!init || !TsNode.isCallExpression(init))
+        return false
+    return !!v.getType().getProperty(marker)
+}
+
+// 两信号分类。null = 既非状态也非视图(普通 const 数据/re-export/hook/let 缓存等),不进任何子图。
+export function classify(v: VariableDeclaration, marker: string = DEFAULT_STORE_MARKER): 'state' | 'view' | null {
+    const init = v.getInitializer()
+    if (!init)
+        return null
+    const k = init.getKind()
+    if (k === SyntaxKind.ArrowFunction || k === SyntaxKind.FunctionExpression || k === SyntaxKind.ClassExpression)
+        return 'view' // 纯函数/组件
+    if (isStateFactory(v, marker))
+        return 'state' // 工厂调用造出带响应式 marker 的对象 = store
+    return null
+}
+
+// store 的一个状态字段从 create 第一个对象字面量长出的全部静态信息。两个投影各取所需:
+//   运行时 Grown.Field 取 {name,type,domain,line}; 读面板 StoreState 取 {name,init,domain}。
+// 单一提取点,取代 grow.typeOf(as_expression 文本走法) + state.domainOf(union 递归摊平)。
+export interface StoreFieldRaw {
+    name: string
+    init: string      // 初值原文('false' / '0' / "'chat'");`x as T` 取 x 那侧
+    type: string      // checker 解出的类型文本('boolean' / 'string | null' / "'chat' | 'im'")
+    domain: string[]  // 可枚举值域:字符串字面量联合的成员;非枚举 → []
+    line: number      // 1-based 声明行
+}
+
+// 一个属性赋值 → StoreFieldRaw。domain/type 走 type checker:严格强于文本走法
+// (解推断/别名 union、解被截断 union、TS 子类型吸收 `'foo'|string`→string、统一 `as T` 与 `let x:'a'`)。
+function fieldOf(pa: Node): StoreFieldRaw | null {
+    if (!TsNode.isPropertyAssignment(pa))
+        return null // 跳过展开/方法/简写等非数据项
+    const valueInit = pa.getInitializer()
+    if (!valueInit)
+        return null
+    // 初值原文:`x as T` 取 as 左侧的值表达式,否则整个初值文本。
+    const init = TsNode.isAsExpression(valueInit) ? valueInit.getExpression().getText() : valueInit.getText()
+    const t = valueInit.getType()
+    // 值域 = 字符串字面量「联合」(≥2 档,可枚举的离散态机)。单个裸字面量(error='')不是值域 ——
+    // 它只是初值,TS 把它窄化成单字面量类型,语义上仍是普通 string。只认 union(与旧 domainOf 同)。
+    const domain = t.isUnion()
+        ? t.getUnionTypes().filter(u => u.isStringLiteral()).map(u => u.getLiteralValue() as string)
+        : []
+    return { name: pa.getName(), init, type: t.getText(valueInit), domain, line: pa.getStartLineNumber() }
+}
+
+// create 的第一个参数解成对象字面量。内联 `create({...})` 直接是;`create(state, …)`
+// (state 是变量,如 schedulerStore)经 checker 跟到符号的 value declaration 的初值 ——
+// 这正是引擎比 tree-sitter 强的兑现点(后者只会找内联 object,标识符引用全漏)。
+function resolveStateObject(arg: Node): Node | null {
+    if (TsNode.isObjectLiteralExpression(arg))
+        return arg
+    if (TsNode.isIdentifier(arg)) {
+        const decl = arg.getSymbol()?.getDeclarations()?.[0]
+        if (decl && TsNode.isVariableDeclaration(decl)) {
+            const di = decl.getInitializer()
+            if (di && TsNode.isObjectLiteralExpression(di))
+                return di
+        }
+    }
+    return null
+}
+
+// 一个被分类为 state 的 store 声明 → 它暴露的字段全集。
+// 字段从工厂第一个对象字面量参数长(marker 是工厂注入的、不在源对象里,故天然不进 fields)。
+export function extractStoreFields(v: VariableDeclaration, marker: string = DEFAULT_STORE_MARKER): StoreFieldRaw[] {
+    if (!isStateFactory(v, marker))
+        return [] // 非 store(无响应式 marker)没有可投影的状态字段
+    const init = v.getInitializer() as Node // isStateFactory 已确认是 CallExpression
+    if (!TsNode.isCallExpression(init))
+        return []
+    const arg = init.getArguments()[0]
+    const stateObj = arg && resolveStateObject(arg)
+    if (!stateObj || !TsNode.isObjectLiteralExpression(stateObj))
+        return []
+    const out: StoreFieldRaw[] = []
+    for (const pa of stateObj.getProperties()) {
+        const f = fieldOf(pa)
+        if (f)
+            out.push(f)
+    }
+    return out
+}
+
+// 一个 state 声明 → Grown(运行时投影:name/type/domain/line + anchor)。
+export function growFromDecl(v: VariableDeclaration, file: string, marker: string = DEFAULT_STORE_MARKER): Grown {
+    const fields: Field[] = extractStoreFields(v, marker).map(f => ({
+        name: f.name,
+        type: f.type,
+        domain: f.domain,
+        line: f.line,
+    }))
+    return {
+        store: v.getName(),
+        anchor: `${file}:${v.getStartLineNumber()}`,
+        fields,
+    }
+}
+
+// 整仓 → 状态子图。扫每个源文件的 module-level 变量声明,classify,对 state 节点测中心性。
+// fileFor 把绝对路径归一成 anchor 用的相对/短路径(默认取末两段,与 discover 的 anchor 同形)。
+export function buildStateGraph(
+    project: Project,
+    fileFor: (absPath: string) => string = p => p.split('/').slice(-2).join('/'),
+    marker: string = DEFAULT_STORE_MARKER,
+): { nodes: StateNode[] } {
+    const nodes: StateNode[] = []
+    for (const sf of project.getSourceFiles()) {
+        const fp = sf.getFilePath()
+        if (fp.endsWith('.d.ts') || fp.includes('/node_modules/'))
+            continue
+        const file = fileFor(fp)
+        for (const v of sf.getVariableDeclarations()) {
+            if (!isModuleLevel(v) || classify(v, marker) !== 'state')
+                continue
+            const grown = growFromDecl(v, file, marker)
+            const seen = new Set<string>()
+            let refs = 0
+            try {
+                for (const ref of v.findReferencesAsNodes()) {
+                    refs++
+                    seen.add(ref.getSourceFile().getFilePath())
+                }
+            }
+            catch { /* checker hiccup on a single binding → 0 refs, still a node */ }
+            nodes.push({ ...grown, refs, files: seen.size, rank: refs + seen.size * 3 })
+        }
+    }
+    nodes.sort((a, b) => b.rank - a.rank)
+    return { nodes }
+}

package/src/read/types.ts

@@ -0,0 +1,162 @@
+export type FileDetailLevel = 'tree' | 'compact' | 'full'
+
+// ── User-facing config schema (what `defineConfig({...})` accepts) ──────────────
+// aihand = three capability modules: read ⊕ refactor ⊕ ui. The config IS that structure.
+// Each module is tri-state: undefined/true → on with defaults · false → off ·
+// object → on + override that module's sub-options. Tuning knobs live INSIDE a module —
+// an off module's knobs never appear.
+
+/** read module: the codemap that gets injected into CLAUDE.md/AGENTS.md. */
+export interface ReadOptions {
+    include?: string[]
+    ignore?: string[]
+    /** Per-glob detail level overrides. Unmatched files default to 'compact'. */
+    fileDetailLevel?: Record<string, FileDetailLevel>
+    /** Detail level used when injecting into target files (default: tree) */
+    injectDetailLevel?: FileDetailLevel
+    /** Files to inject the codemap into (default: CLAUDE.md, AGENTS.md) */
+    injectTargetFiles?: string[]
+    /** Include zero-parameter function signatures (default: false) */
+    showNoParamFn?: boolean
+    /** Non-code file count per directory in file tree that triggers folding (default: 8) */
+    treeFoldThreshold?: number
+    /** Inject the one-line `aihand` dev-tool pointer into target files (default: true) */
+    injectDevToolInstructions?: boolean
+    /** Inject the full codemap (panel/state/tree). false → Overview + a pointer to `aihand read --stdout`, so the map isn't resident every session (default: true) */
+    injectCodemap?: boolean
+    /** Max tokens to inject. Enables smart allocation via git recency + import centrality. (default: 5000) */
+    maxTokens?: number
+}
+
+export type ModuleSwitch<O> = boolean | O
+
+/** runtime module: the browser probe + store discovery. */
+export interface RuntimeOptions {
+    /** Reactive fingerprint field the store factory injects into its return type — the
+     * construction-agnostic store criterion (a binding `const X = factory(...)` is a store iff
+     * `X`'s type has this property), so discovery never hardcodes the factory name `create`.
+     * MobX (this repo) → `_loading`; zustand → `getState`; valtio → its proxy symbol. (default: '_loading') */
+    storeMarker?: string
+}
+
+export interface AidevConfig {
+    /** Codemap injection into CLAUDE.md/AGENTS.md. */
+    read?: ModuleSwitch<ReadOptions>
+    /** AST refactor commands (move-file/rename/move-symbol). Stateless → plain on/off. */
+    refactor?: boolean
+    /** Runtime browser probe + knob projection — inspect & drive the running app.
+     * Store discovery is automatic (scans read.include, grows every binding whose type carries
+     * the reactive marker); the only knob is `storeMarker` for non-MobX factories. */
+    runtime?: ModuleSwitch<RuntimeOptions>
+}
+
+// ── Internal resolved config (what loadConfig produces, what the pipeline consumes) ──
+// Same nested shape, fully populated (no undefined), each module carrying `enabled`.
+
+export interface ResolvedRead extends Required<ReadOptions> {
+    enabled: boolean
+}
+
+export interface Config {
+    read: ResolvedRead
+    refactor: { enabled: boolean }
+    runtime: { enabled: boolean } & Required<RuntimeOptions>
+}
+
+const READ_DEFAULTS: Required<ReadOptions> = {
+    include: [
+        'package.json',
+        'index.html',
+        'tsconfig.json',
+        'tsconfig.*.json',
+        '*.config.{js,ts,mjs,cjs}',
+    ],
+    ignore: [],
+    fileDetailLevel: {
+        'package-lock.json': 'tree',
+        'pnpm-lock.yaml': 'tree',
+        'yarn.lock': 'tree',
+        'bun.lock': 'tree',
+        '**/*.test.ts': 'tree',
+        '**/*.test.tsx': 'tree',
+        '**/*.spec.ts': 'tree',
+        '**/*.spec.tsx': 'tree',
+    },
+    injectDetailLevel: 'tree',
+    injectTargetFiles: ['CLAUDE.md', 'AGENTS.md'],
+    showNoParamFn: false,
+    treeFoldThreshold: 8,
+    injectDevToolInstructions: true,
+    injectCodemap: true,
+    maxTokens: 5_000,
+}
+
+export const DEFAULT_CONFIG: Config = {
+    read: { enabled: true, ...READ_DEFAULTS },
+    refactor: { enabled: true },
+    runtime: { enabled: true, storeMarker: '_loading' },
+}
+
+/**
+ * Tri-state module switch → resolved {enabled, ...options}. Shared by all three modules.
+ * undefined/true → on with defaults · false → off (defaults retained, just gated) ·
+ * object → on + shallow-override the module's options.
+ */
+export function resolveModule<O extends object>(
+    sw: ModuleSwitch<O> | undefined,
+    defaults: O,
+): { enabled: boolean } & O {
+    if (sw === false)
+        return { enabled: false, ...defaults }
+    if (sw === undefined || sw === true)
+        return { enabled: true, ...defaults }
+    return { enabled: true, ...defaults, ...sw }
+}
+
+export interface RepodexData {
+    overview: string
+    panel?: string // 控制面旋钮（输入端）：拨它把哪个 store 状态推向什么。排在 tree 前
+    state?: string // 状态显示（输出端/可观测量）：系统由哪些状态量构成、初值、值域。与 panel 配成洗衣机面板
+    tree: string
+    signatures: string
+    full?: string
+}
+
+export interface FileBlock {
+    path: string
+    level: FileDetailLevel
+    content: string
+    /** Resolved relative import specifiers (TS/JS files only, used for import graph) */
+    imports?: string[]
+}
+
+export function defineConfig(config: AidevConfig): AidevConfig {
+    return config
+}
+
+/**
+ * Config template body (between `defineConfig({` and `})`) shared by initConfig and README.
+ * Three module switches are the main surface; tuning knobs live inside `read: {...}`.
+ */
+export function configTemplate(): string {
+    return `    // aihand = three capability modules. Each: true (on, defaults) · false (off) · { ...overrides }.
+    // Most repos only need the three switches below — tuning knobs have smart defaults.
+
+    // Codemap injection into CLAUDE.md/AGENTS.md
+    read: true,
+    // AST refactor commands (move-file / rename / move-symbol)
+    refactor: true,
+    // Inspect & drive the running app (runtime browser probe — needs the vite plugin);
+    // set false on repos without a dev server.
+    // Non-MobX store factory? runtime: { storeMarker: 'getState' } — the reactive
+    // fingerprint field on the store's return type (zustand 'getState', default '_loading').
+    runtime: true,
+
+    // Need to tune read? Open it up (all optional, shown with defaults):
+    // read: {
+    //   include: ['src/**'],          // what to scan (root config files always included)
+    //   ignore: [],                    // extra skips (.gitignore already applied)
+    //   maxTokens: 5_000,              // budget — auto-downgrades less important files
+    //   injectCodemap: true,           // false → Overview + a pointer to \`aihand read --stdout\`
+    // },`
+}

package/src/read/vite.ts

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export interface RepodexPluginOptions {
+    /** 透传给 `repodex --watch` 的额外参数 */
+    args?: string[]
+    /** stdio 模式，默认 'inherit'，嫌吵改 'ignore' */
+    stdio?: 'inherit' | 'ignore'
+}
+
+/**
+ * 解析顺序，从最近的源码到线上包（aihand 统一入口在上一级 src/cli.ts）：
+ *   1. ../cli.ts —— dev 用 tsx 跑源码，改完即生效，免编译
+ *   2. ../cli.js / ../../dist/cli.js —— 已编译产物
+ *   3. npx aihand —— 线上发布包
+ * 返回 args 已带 `read` 模块段，调用方再补 `--watch`。
+ */
+function resolveCliCmd(): { cmd: string, args: string[] } {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url))
+        // this file is src/read/vite.ts; the unified entry sits one level up at src/cli.ts
+        const src = resolve(here, '..', 'cli.ts')
+        if (existsSync(src)) {
+            // node --import tsx：父子直连，无 .bin/tsx wrapper 中间进程，
+            // 让 cli.ts 的父进程守卫能精确监测 vite 存活。
+            return { cmd: process.execPath, args: ['--import', 'tsx', src, 'read'] }
+        }
+        for (const rel of ['../cli.js', '../../dist/cli.js']) {
+            const p = resolve(here, rel)
+            if (existsSync(p))
+                return { cmd: process.execPath, args: [p, 'read'] }
+        }
+    }
+    catch {}
+    return { cmd: 'npx', args: ['aihand', 'read'] }
+}
+
+export function repodexWatchPlugin(opts: RepodexPluginOptions = {}) {
+    const { args = [], stdio = 'inherit' } = opts
+    return {
+        name: 'aihand-read-watch',
+        apply: 'serve' as const,
+        configureServer(server: any) {
+            // setup：spawn 唯一的 watch 子进程（叶子进程，无孙进程）
+            const { cmd, args: prefix } = resolveCliCmd()
+            const child = spawn(cmd, [...prefix, '--watch', ...args], {
+                stdio,
+                env: { ...process.env, FORCE_COLOR: process.env.FORCE_COLOR ?? '1' },
+            })
+
+            // teardown：精准 kill 这一个 child，幂等只跑一次，绝不波及其它进程
+            let done = false
+            const cleanup = () => {
+                if (done)
+                    return
+                done = true
+                if (!child.killed)
+                    child.kill()
+            }
+
+            // 子进程先死则无需再清；覆盖 vite 正常关闭与各类进程退出（含被强杀前的最后机会）
+            child.once('exit', () => {
+                done = true
+            })
+            server.httpServer?.once('close', cleanup)
+            process.once('exit', cleanup)
+            for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
+                process.once(sig, () => {
+                    cleanup()
+                    process.kill(process.pid, sig) // 清完重抛信号，不吞掉 vite 的退出
+                })
+            }
+        },
+    }
+}

package/src/ui/babel/line-profiler.ts

@@ -0,0 +1,197 @@
+// Source both the types and the value namespace from @babel/core so they share one
+// module identity. Importing types separately from @babel/types pins them to a
+// different copy when multiple @babel/types versions resolve (NodePath variance error).
+import type { NodePath, PluginObj, types as BabelTypes } from '@babel/core'
+import { types as t } from '@babel/core'
+import path from 'path'
+
+type Statement = BabelTypes.Statement
+type VariableDeclaration = BabelTypes.VariableDeclaration
+type ReturnStatement = BabelTypes.ReturnStatement
+type ExpressionStatement = BabelTypes.ExpressionStatement
+
+/**
+ * Babel plugin: wrap statements with __line(label, () => ...) for line-level profiling.
+ *
+ * Only wraps statements that have measurable cost:
+ * - VariableDeclaration with initializer
+ * - ExpressionStatement (function calls, assignments)
+ * - ReturnStatement with argument
+ *
+ * Skips:
+ * - import/export (module syntax)
+ * - control flow (if/for/while/switch) — their bodies get wrapped, not the structure
+ * - empty statements, type declarations
+ */
+export function lineProfilerPlugin(): PluginObj {
+    return {
+        name: 'aihand-line-profiler',
+        visitor: {
+            VariableDeclaration(nodePath: NodePath<VariableDeclaration>, state) {
+                if (shouldSkip(nodePath, state)) return
+                const decl = nodePath.node.declarations[0]
+                if (!decl?.init) return // skip `let x;`
+                if (hasAwaitOrYield(decl.init)) return // wrapping in arrow fn breaks async semantics
+
+                const label = makeLabel(nodePath, state, decl.id.type === 'Identifier' ? decl.id.name : undefined)
+                const wrapped = wrapExpr(decl.init, label)
+                decl.init = wrapped
+            },
+
+            ExpressionStatement(nodePath: NodePath<ExpressionStatement>, state) {
+                if (shouldSkip(nodePath, state)) return
+                if (hasAwaitOrYield(nodePath.node.expression)) return
+
+                const label = makeLabel(nodePath, state)
+                const wrapped = wrapExpr(nodePath.node.expression, label)
+                nodePath.node.expression = wrapped
+            },
+
+            ReturnStatement(nodePath: NodePath<ReturnStatement>, state) {
+                if (shouldSkip(nodePath, state)) return
+                if (!nodePath.node.argument) return // skip `return;`
+                if (hasAwaitOrYield(nodePath.node.argument)) return
+
+                const label = makeLabel(nodePath, state)
+                const wrapped = wrapExpr(nodePath.node.argument, label)
+                nodePath.node.argument = wrapped
+            },
+        },
+    }
+}
+
+function shouldSkip(nodePath: NodePath<Statement>, state: any): boolean {
+    const filename: string = state.file?.opts?.filename ?? ''
+    // Skip node_modules — third-party cost isn't the app's to fix.
+    if (filename.includes('node_modules')) return true
+    // Skip aihand's own source: the profiler reads state by walking the React fiber tree
+    // (client.ts walkFiber/walkChildren) on every /ui|/dom|/screen. That's MEASUREMENT cost,
+    // not the app's — instrumenting it lets the observer dominate its own report (290ms self-top).
+    if (filename.includes('packages/aidev/')) return true
+
+    // Skip module syntax — import/export carry no runtime cost to measure
+    const node = nodePath.node
+    if (t.isImportDeclaration(node)) return true
+    if (t.isExportNamedDeclaration(node)) return true
+    if (t.isExportDefaultDeclaration(node)) return true
+    if (t.isExportAllDeclaration(node)) return true
+
+    // Skip if already wrapped
+    if (t.isExpressionStatement(node) && t.isCallExpression(node.expression)) {
+        const callee = node.expression.callee
+        if (t.isIdentifier(callee) && callee.name === '__line') return true
+    }
+
+    return false
+}
+
+function makeLabel(nodePath: NodePath<Statement>, state: any, varName?: string): string {
+    const filename = state.file.opts.filename ?? 'unknown'
+    const basename = path.basename(filename)
+    const line = resolveLine(nodePath)
+
+    if (varName) {
+        return `${basename}:${line}:${varName}`
+    }
+    return `${basename}:${line}`
+}
+
+// Resolve the source line a wrapped statement should point to.
+//
+// A node synthesized by an upstream transform (e.g. mobx-react-observer rewriting
+// `function Root(){…}` → `const Root = observer(function Root(){…})`) carries NO loc on the
+// outer declaration. Two recovery moves, in priority order:
+//
+//   1. descend — the synthesized wrapper still contains the user's ORIGINAL node
+//      (`function Root()` keeps its loc 59). The nearest loc-bearing descendant is the most
+//      specific real source location, so prefer it.
+//   2. climb — only if the whole subtree is synthetic (no loc anywhere inside) do we fall back
+//      to the nearest ancestor's loc.
+//
+// Without this, observer-wrapped components — the ones most worth profiling — collapse onto
+// `<file>:1` (climbing all the way to Program) or `<file>:0` (no loc at all).
+function resolveLine(nodePath: NodePath<Statement>): number {
+    if (nodePath.node.loc) return nodePath.node.loc.start.line
+
+    const descend = firstLocLine(nodePath.node)
+    if (descend != null) return descend
+
+    let p: NodePath | null = nodePath.parentPath
+    while (p) {
+        if (p.node.loc) return p.node.loc.start.line
+        p = p.parentPath
+    }
+    return 0
+}
+
+// Pre-order DFS for the first node carrying a loc. Skips the root itself (caller already
+// checked it). Source-order traversal so the earliest real line wins.
+function firstLocLine(node: t.Node): number | null {
+    for (const key of t.VISITOR_KEYS[node.type] ?? []) {
+        const child = (node as any)[key]
+        const children = Array.isArray(child) ? child : [child]
+        for (const c of children) {
+            if (!c || typeof c.type !== 'string') continue
+            if (c.loc) return c.loc.start.line
+            const deeper = firstLocLine(c)
+            if (deeper != null) return deeper
+        }
+    }
+    return null
+}
+
+// Emit: (globalThis.__line || ((_l, f) => f()))(label, () => expr)
+// NOT a bare `__line(...)`: instrumented modules eval their top-level statements at IMPORT time,
+// before client-patch installs window.__line — a bare identifier then throws ReferenceError and
+// kills the app. globalThis.__line is a member access (→ undefined, not a throw); the || fallback
+// just runs the original expr, so the instrumentation is inert until the runtime is present.
+function wrapExpr(expr: t.Expression, label: string): t.CallExpression {
+    const runtime = t.logicalExpression(
+        '||',
+        t.memberExpression(t.identifier('globalThis'), t.identifier('__line')),
+        t.arrowFunctionExpression(
+            [t.identifier('_l'), t.identifier('f')],
+            t.callExpression(t.identifier('f'), []),
+        ),
+    )
+    return t.callExpression(
+        runtime,
+        [
+            t.stringLiteral(label),
+            t.arrowFunctionExpression([], expr),
+        ]
+    )
+}
+
+// True if expr contains an await/yield at THIS function level (not inside a nested function).
+// Wrapping such an expr in `() => expr` would either be a syntax error (await in non-async
+// arrow) or silently change semantics (the arrow returns a Promise instead of awaiting).
+// Nested functions are their own scope, so we stop recursing at function boundaries.
+function hasAwaitOrYield(node: t.Node | null | undefined): boolean {
+    if (!node || typeof node !== 'object') return false
+    if (t.isAwaitExpression(node) || t.isYieldExpression(node)) return true
+    // Don't descend into nested functions — their await/yield belongs to their own scope.
+    if (
+        t.isFunctionExpression(node)
+        || t.isArrowFunctionExpression(node)
+        || t.isFunctionDeclaration(node)
+        || t.isObjectMethod(node)
+        || t.isClassMethod(node)
+    ) return false
+
+    for (const key of Object.keys(node)) {
+        if (key === 'loc' || key === 'start' || key === 'end' || key === 'leadingComments' || key === 'trailingComments') continue
+        const child = (node as any)[key]
+        if (Array.isArray(child)) {
+            for (const c of child) {
+                if (c && typeof c.type === 'string' && hasAwaitOrYield(c)) return true
+            }
+        }
+        else if (child && typeof child.type === 'string') {
+            if (hasAwaitOrYield(child)) return true
+        }
+    }
+    return false
+}
+
+export default lineProfilerPlugin