aihand 0.0.1 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,461 @@
+export { RepodexPluginOptions, aihand } from './vite.js';
+import { Parser, Language, Tree } from 'web-tree-sitter';
+import { Project, VariableDeclaration } from 'ts-morph';
+import { PluginObj } from '@babel/core';
+import 'vite';
+
+declare const SEPARATOR = "\u22EE----";
+declare const IMPORT_QUERY = "\n(import_statement\n  source: (string (string_fragment) @source))\n";
+declare const TS_QUERY = "\n(export_statement (function_declaration)) @fn\n(export_statement (lexical_declaration (variable_declarator value: (arrow_function)))) @fn\n(export_statement (generator_function_declaration)) @fn\n(type_alias_declaration) @internal_type\n(export_statement (type_alias_declaration)) @type\n(interface_declaration) @internal_type\n(export_statement (interface_declaration)) @type\n(enum_declaration) @internal_type\n(export_statement (enum_declaration)) @type\n(class_declaration) @class\n(export_statement (class_declaration)) @class\n(export_statement value: (assignment_expression)) @export_val\n(export_statement (lexical_declaration)) @export_val\n(export_statement source: (string)) @reexport\n(comment) @comment\n";
+declare function getLang(ext: string, wasmDir?: string): Promise<Language | null>;
+declare function cleanFnSignature(text: string): string;
+interface CompactFlags {
+    skipNoParamFn?: boolean;
+}
+declare function compact(code: string, parser: Parser, lang: Language, flags?: CompactFlags, existingTree?: Tree): string;
+declare function extractImports(code: string, parser: Parser, lang: Language, existingTree?: Tree): string[];
+
+interface SymbolNode {
+    uid: string;
+    name: string;
+    kind: 'function' | 'method' | 'class';
+    filePath: string;
+    startLine: number;
+    endLine: number;
+}
+interface CallGraph {
+    symbols: Record<string, SymbolNode>;
+    out: Record<string, string[]>;
+    in: Record<string, string[]>;
+}
+declare function buildCallGraph(filePaths: string[], contents?: Map<string, string>): Promise<CallGraph>;
+
+type FileDetailLevel = 'tree' | 'compact' | 'full';
+/** read module: the codemap that gets injected into CLAUDE.md/AGENTS.md. */
+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;
+}
+type ModuleSwitch<O> = boolean | O;
+/** runtime module: the browser probe + store discovery. */
+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;
+}
+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>;
+}
+interface ResolvedRead extends Required<ReadOptions> {
+    enabled: boolean;
+}
+interface Config {
+    read: ResolvedRead;
+    refactor: {
+        enabled: boolean;
+    };
+    runtime: {
+        enabled: boolean;
+    } & Required<RuntimeOptions>;
+}
+declare const DEFAULT_CONFIG: Config;
+interface RepodexData {
+    overview: string;
+    panel?: string;
+    state?: string;
+    tree: string;
+    signatures: string;
+    full?: string;
+}
+interface FileBlock {
+    path: string;
+    level: FileDetailLevel;
+    content: string;
+    /** Resolved relative import specifiers (TS/JS files only, used for import graph) */
+    imports?: string[];
+}
+declare function defineConfig(config: AidevConfig): AidevConfig;
+/**
+ * Config template body (between `defineConfig({` and `})`) shared by initConfig and README.
+ * Three module switches are the main surface; tuning knobs live inside `read: {...}`.
+ */
+declare function configTemplate(): string;
+
+type EnsureMarkersResult = 'created' | 'marked' | 'skipped';
+declare function ensureMarkers(filePath: string): EnsureMarkersResult;
+declare function injectFile(config: Config, data: RepodexData, filePath: string): boolean;
+declare function injectAll(config: Config, data: RepodexData, files?: string[]): string[];
+
+declare function symbolAtLine(g: CallGraph, file: string, line: number): SymbolNode | undefined;
+declare function parseInspPath(p: string): {
+    file: string;
+    line: number;
+};
+interface LocateResult {
+    symbol: SymbolNode;
+    callers: SymbolNode[];
+    callees: SymbolNode[];
+}
+declare function locate(g: CallGraph, file: string, line: number): LocateResult | null;
+declare function renderLocate(r: LocateResult, json?: boolean): string;
+declare function sourcePanelHtml(r: LocateResult, esc?: (s: string) => string): string;
+
+interface Transition {
+    field: string;
+    to: string;
+    args?: string;
+}
+interface Knob {
+    label: string | null;
+    tag: string;
+    event: string;
+    transitions: Transition[];
+    store: string;
+    filePath: string;
+    line: number;
+}
+declare function extractKnobs(filePath: string, code: string, lang: Language): Knob[];
+declare function fmtTransitions(ts: Transition[]): string;
+declare function buildPanel(filePaths: string[], contents?: Map<string, string>): Promise<Knob[]>;
+
+interface RuntimeKnob {
+    label: string;
+    files: string[];
+    tag: string;
+}
+interface LiveKnob extends Knob {
+    live: boolean;
+}
+declare function fileOfInspPath(inspPath: string): string;
+declare function joinPanel(staticKnobs: Knob[], runtime: RuntimeKnob[]): LiveKnob[];
+declare function fetchRuntimeKnobs(port: number): Promise<RuntimeKnob[]>;
+
+interface StateField {
+    name: string;
+    init: string;
+    domain: string[] | null;
+}
+interface StoreState {
+    store: string;
+    filePath: string;
+    fields: StateField[];
+}
+declare function buildState(paths?: string[], marker?: string): Promise<StoreState[]>;
+declare function formatState(states: StoreState[]): string;
+
+interface Field {
+    name: string;
+    type: string;
+    domain: string[];
+    line: number;
+}
+interface Grown {
+    store: string;
+    anchor: string;
+    fields: Field[];
+}
+declare function grow(code: string, file: string): Promise<Grown[]>;
+
+interface StateNode extends Grown {
+    refs: number;
+    files: number;
+    rank: number;
+}
+declare function openProject(cwd?: string): Promise<Project>;
+declare function classify(v: VariableDeclaration, marker?: string): 'state' | 'view' | null;
+interface StoreFieldRaw {
+    name: string;
+    init: string;
+    type: string;
+    domain: string[];
+    line: number;
+}
+declare function extractStoreFields(v: VariableDeclaration, marker?: string): StoreFieldRaw[];
+declare function growFromDecl(v: VariableDeclaration, file: string, marker?: string): Grown;
+declare function buildStateGraph(project: Project, fileFor?: (absPath: string) => string, marker?: string): {
+    nodes: StateNode[];
+};
+
+/** Pre-compile fileDetailLevel patterns into a fast per-path classifier. */
+declare function buildClassifier(detail: Record<string, FileDetailLevel>, defaultLevel?: FileDetailLevel): (path: string) => FileDetailLevel;
+declare function buildBlocks(paths: string[], config: Config, wasmDir?: string, classifyFn?: (path: string) => FileDetailLevel, contents?: Map<string, string>): Promise<FileBlock[]>;
+interface TreeOptions {
+    /** When a Signatures section already lists every path, drop filenames here — show dir + count. */
+    skeletonOnly?: boolean;
+    /** Files/dir headers that fit the token budget and stay expanded. Empty/undefined = expand all. */
+    kept?: Set<string>;
+    /** Dir prefixes whose whole subtree collapsed to a `name/ (N files, M dirs)` summary line. */
+    collapsedDirs?: Set<string>;
+    /** Paths the control panel references (knob/state filePaths) → marked ★ "关键" and never folded away. */
+    starred?: Set<string>;
+}
+declare function formatTree(paths: string[], foldThreshold?: number, opts?: TreeOptions): string;
+declare function formatXml(blocks: FileBlock[], levels?: Map<string, FileDetailLevel>): string;
+
+declare function scan(config: Config): string[];
+
+interface SecretMatch {
+    path: string;
+    line: number;
+    pattern: string;
+}
+declare function scanSecrets(blocks: FileBlock[]): SecretMatch[];
+
+/** Score files by how recently they were committed: 2 = last 5, 1 = last 20, 0 = beyond */
+declare function computeRecency(files: string[], cwd?: string): Map<string, number>;
+/** Build a reverse import graph: file → Set of files that import it */
+declare function buildImportGraph(blocks: FileBlock[], cwd?: string): Map<string, Set<string>>;
+/** Score files by import in-degree: 2 = 20+ importers, 1 = 5–19, 0 = <5 */
+declare function computeCentrality(files: string[], graph: Map<string, Set<string>>): Map<string, number>;
+interface ExpandResult {
+    /** Paths (files + dir headers) that fit within budget and stay expanded. */
+    kept: Set<string>;
+    /** Directory prefixes whose whole subtree collapsed to a one-line summary. */
+    collapsedDirs: Set<string>;
+}
+/**
+ * Top-down expansion: walk the tree breadth-first by signal, charging each kept node's
+ * tokens, until the budget runs out. Nodes never reached stay folded — a collapsed dir
+ * renders as `dir/ (N files, M dirs)`, leftover files under a kept dir fold to `.ext ×N`.
+ *
+ * Dir signal = max(subtree file scores), so a single hot file keeps its whole dir reachable.
+ * score(file) = recency + centrality (0–4), same scale as allocate().
+ */
+declare function expandByBudget(paths: string[], scores: Map<string, number>, contentTokens: Map<string, number>, budget: number, treeEntryTokens?: number): ExpandResult;
+interface AllocationResult {
+    levels: Map<string, FileDetailLevel>;
+    totalBefore: number;
+    totalAfter: number;
+    downgraded: number;
+    /** Tokens still over budget after compact→tree. >0 means the tree must collapse subtrees. */
+    deficit: number;
+    /** file → recency+centrality (0–4), reused by expandByBudget for top-down collapse. */
+    scores: Map<string, number>;
+    /** file → tokens to keep its content visible, reused by expandByBudget. */
+    contentTokens: Map<string, number>;
+    treeEntryTokens: number;
+}
+/**
+ * Given scored blocks and a token budget, downgrade low-scoring files compact → tree
+ * until content fits. What's still over budget surfaces as `deficit` — the tree side
+ * (expandByBudget) then collapses whole low-signal subtrees instead of dropping files.
+ */
+declare function allocate(blocks: FileBlock[], recency: Map<string, number>, centrality: Map<string, number>, budget: number, pinned?: Set<string>, isTreeDisplay?: (path: string) => boolean): AllocationResult;
+
+declare function moveFile(src: string, dest: string, dry?: boolean): Promise<void>;
+declare function moveSymbol(from: string, name: string, to: string, dry?: boolean): Promise<void>;
+declare function renameSymbol(file: string, oldName: string, newName: string, dry?: boolean): Promise<void>;
+
+/**
+ * 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
+ */
+declare function lineProfilerPlugin(): PluginObj;
+
+interface LogEntry$1 {
+    level: 'error' | 'warn' | 'info' | 'debug' | 'log';
+    text: string;
+    timestamp?: number;
+    source?: string;
+}
+interface NetworkRequest {
+    method: string;
+    url: string;
+    status: number;
+    duration: number;
+    resourceType: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: string;
+    requestSample?: string;
+    responseBody?: string;
+    responseSample?: string;
+    failed?: boolean;
+    failureText?: string;
+}
+interface ErrorEntry {
+    message: string;
+    stack?: string;
+    source?: string;
+    line?: number;
+    column?: number;
+}
+interface ActionEntry {
+    type: string;
+    target: string;
+    value?: string;
+    trusted: boolean;
+    view?: string;
+    modal?: string;
+    focus?: string;
+    ts: number;
+    tab?: string;
+}
+interface RawState {
+    tab?: string;
+    url: string;
+    title?: string;
+    visible?: boolean;
+    ui: string;
+    console: LogEntry$1[];
+    network: NetworkRequest[];
+    errors: ErrorEntry[];
+    actions?: ActionEntry[];
+    actionsDropped?: number;
+    state: Record<string, unknown>;
+    performance?: PerformanceData;
+    timestamp: number;
+}
+interface PerfStat {
+    total: number;
+    n: number;
+    max: number;
+}
+interface PerfBucketData {
+    name: string;
+    components: Record<string, PerfStat>;
+    frames: {
+        total: number;
+        long: number;
+        max: number;
+        samples: number[];
+    };
+    lines: Record<string, PerfStat>;
+}
+interface PerformanceData {
+    windowMs: number;
+    hiddenFrames: number;
+    mobxPatched: boolean;
+    buckets: PerfBucketData[];
+    longtasks: {
+        count: number;
+        max: number;
+    };
+}
+interface CompactState {
+    url: string;
+    ui: string;
+    console: string;
+    network: string;
+    errors: string;
+    state: string;
+    performance?: string;
+    timestamp: number;
+    counts: {
+        console: number;
+        network: number;
+        errors: number;
+        state: number;
+    };
+}
+interface Assertion {
+    name: string;
+    pass: boolean;
+    detail?: string;
+}
+interface CheckResult {
+    pass: boolean;
+    assertions: Assertion[];
+}
+interface DiffResult {
+    newErrors: LogEntry$1[];
+    newExceptions: ErrorEntry[];
+    newFailedRequests: NetworkRequest[];
+    uiGone: boolean;
+    clean: boolean;
+}
+
+declare function check(raw: RawState): CheckResult;
+
+declare function diffState(prev: RawState | null, curr: RawState): DiffResult;
+
+declare function emitSummary(raw: RawState): string;
+declare function emitCheck(result: CheckResult): string;
+declare function emitDiff(diff: DiffResult): string;
+
+interface Self {
+    view: string;
+    modal: string | null;
+    focus: string | null;
+    state: Record<string, unknown>;
+    anchor: string;
+}
+declare function screen(self: Self): Self;
+interface LogEntry {
+    channel: 'console' | 'fetch' | 'xhr' | 'sse' | 'error';
+    detail: string;
+    ts: number;
+}
+declare function log(seq: LogEntry[], entry: LogEntry): LogEntry[];
+
+declare function act(before: Self, after: Self): string[];
+
+declare function discover(roots: string | string[], marker?: string): Promise<Grown[]>;
+
+interface Sink {
+    seq: LogEntry[];
+    now: () => number;
+}
+declare function installSelfLog(win: Window & typeof globalThis, sink: Sink): () => void;
+
+type Snapshot = Record<string, unknown>;
+declare function synth(schema: Grown, snapshot: Snapshot): Self;
+
+interface StoreSnap {
+    schema: Grown;
+    snapshot: Snapshot;
+}
+interface ScreenHook {
+    view: string;
+    domain: Record<string, unknown>;
+}
+declare function screenHook(stores: StoreSnap[]): ScreenHook;
+
+interface Options {
+    roots: string | string[];
+    storeMarker?: string;
+}
+declare function storeSchema(options: Options): {
+    name: string;
+    resolveId(id: string): string | undefined;
+    load(id: string): Promise<string | undefined>;
+    handleHotUpdate(ctx: {
+        file: string;
+    }): void;
+};
+
+export { type AidevConfig, type CallGraph, type CheckResult, type CompactState, type Config, DEFAULT_CONFIG, type DiffResult, type Field, type FileBlock, type FileDetailLevel, type Grown, IMPORT_QUERY, type Knob, type LiveKnob, type LocateResult, type LogEntry, type ModuleSwitch, type RawState, type ReadOptions, type RepodexData, type RuntimeKnob, type RuntimeOptions, SEPARATOR, type ScreenHook, type Self, type Sink, type Snapshot, type StateField, type StateNode, type StoreFieldRaw, type StoreSnap, type StoreState, type SymbolNode, TS_QUERY, type Transition, act, allocate, buildBlocks, buildCallGraph, buildClassifier, buildImportGraph, buildPanel, buildState, buildStateGraph, check, classify, cleanFnSignature, compact, computeCentrality, computeRecency, configTemplate, defineConfig, diffState, discover, emitCheck, emitDiff, emitSummary, ensureMarkers, expandByBudget, extractImports, extractKnobs, extractStoreFields, fetchRuntimeKnobs, fileOfInspPath, fmtTransitions, formatState, formatTree, formatXml, getLang, grow, growFromDecl, injectAll, injectFile, installSelfLog, joinPanel, lineProfilerPlugin, locate, log, moveFile, moveSymbol, openProject, parseInspPath, renameSymbol, renderLocate, scan, scanSecrets, screen, screenHook, sourcePanelHtml, storeSchema, symbolAtLine, synth };