trickle-observe 0.1.0

package/dist/auto-codegen.js

@@ -0,0 +1,999 @@
+"use strict";
+/**
+ * Lightweight inline codegen for `trickle/auto`.
+ *
+ * Reads .trickle/observations.jsonl and generates .d.ts sidecar files
+ * next to source files. Runs entirely inside the user's process —
+ * no CLI or backend required.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectTypes = injectTypes;
+exports.generateTypes = generateTypes;
+exports.generateCoverageReport = generateCoverageReport;
+exports.generateTypeSummary = generateTypeSummary;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ── Type merging (same logic as CLI local-codegen) ──
+function typeNodeKey(node) {
+    switch (node.kind) {
+        case 'primitive': return `p:${node.name}`;
+        case 'unknown': return 'unknown';
+        case 'array': return `a:${typeNodeKey(node.element)}`;
+        case 'tuple': return `t:[${(node.elements || []).map(typeNodeKey).join(',')}]`;
+        case 'object': {
+            const props = node.properties || {};
+            const entries = Object.keys(props).sort().map(k => `${k}:${typeNodeKey(props[k])}`);
+            return `o:{${entries.join(',')}}`;
+        }
+        case 'union': return `u:(${(node.members || []).map(typeNodeKey).sort().join('|')})`;
+        default: return JSON.stringify(node);
+    }
+}
+function mergeTypeNodes(a, b) {
+    if (typeNodeKey(a) === typeNodeKey(b))
+        return a;
+    if (a.kind === 'object' && b.kind === 'object') {
+        const aP = a.properties || {}, bP = b.properties || {};
+        const allKeys = new Set([...Object.keys(aP), ...Object.keys(bP)]);
+        const merged = {};
+        for (const k of allKeys) {
+            const inA = k in aP, inB = k in bP;
+            if (inA && inB)
+                merged[k] = mergeTypeNodes(aP[k], bP[k]);
+            else if (inA)
+                merged[k] = makeOptional(aP[k]);
+            else
+                merged[k] = makeOptional(bP[k]);
+        }
+        return { kind: 'object', properties: merged };
+    }
+    if (a.kind === 'array' && b.kind === 'array' && a.element && b.element) {
+        return { kind: 'array', element: mergeTypeNodes(a.element, b.element) };
+    }
+    if (a.kind === 'tuple' && b.kind === 'tuple') {
+        const aE = a.elements || [], bE = b.elements || [];
+        if (aE.length === bE.length) {
+            return { kind: 'tuple', elements: aE.map((el, i) => mergeTypeNodes(el, bE[i])) };
+        }
+        // Different lengths: merge common prefix, make extra elements optional
+        const shorter = aE.length < bE.length ? aE : bE;
+        const longer = aE.length < bE.length ? bE : aE;
+        const merged = [];
+        for (let i = 0; i < longer.length; i++) {
+            if (i < shorter.length) {
+                merged.push(mergeTypeNodes(shorter[i], longer[i]));
+            }
+            else {
+                merged.push(makeOptional(longer[i]));
+            }
+        }
+        return { kind: 'tuple', elements: merged };
+    }
+    return deduplicateUnion([
+        ...(a.kind === 'union' ? (a.members || []) : [a]),
+        ...(b.kind === 'union' ? (b.members || []) : [b]),
+    ]);
+}
+function makeOptional(node) {
+    if (node.kind === 'primitive' && node.name === 'undefined')
+        return node;
+    if (node.kind === 'union') {
+        const members = node.members || [];
+        if (members.some(m => m.kind === 'primitive' && m.name === 'undefined'))
+            return node;
+        return { kind: 'union', members: [...members, { kind: 'primitive', name: 'undefined' }] };
+    }
+    return { kind: 'union', members: [node, { kind: 'primitive', name: 'undefined' }] };
+}
+function deduplicateUnion(members) {
+    const seen = new Set();
+    const unique = [];
+    for (const m of members) {
+        if (m.kind === 'union') {
+            for (const inner of m.members || []) {
+                const k = typeNodeKey(inner);
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    unique.push(inner);
+                }
+            }
+        }
+        else {
+            const k = typeNodeKey(m);
+            if (!seen.has(k)) {
+                seen.add(k);
+                unique.push(m);
+            }
+        }
+    }
+    return unique.length === 1 ? unique[0] : { kind: 'union', members: unique };
+}
+// ── Read + merge observations ──
+function readAndMerge(jsonlPath) {
+    if (!fs.existsSync(jsonlPath))
+        return [];
+    const content = fs.readFileSync(jsonlPath, 'utf-8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    const byFunc = new Map();
+    for (const line of lines) {
+        try {
+            const obs = JSON.parse(line);
+            if (obs.functionName && obs.argsType && obs.returnType) {
+                if (!byFunc.has(obs.functionName))
+                    byFunc.set(obs.functionName, []);
+                byFunc.get(obs.functionName).push(obs);
+            }
+        }
+        catch { /* skip */ }
+    }
+    const results = [];
+    for (const [name, observations] of byFunc) {
+        let args = observations[0].argsType;
+        let ret = observations[0].returnType;
+        for (let i = 1; i < observations.length; i++) {
+            if (observations[i].typeHash !== observations[0].typeHash) {
+                args = mergeTypeNodes(args, observations[i].argsType);
+                ret = mergeTypeNodes(ret, observations[i].returnType);
+            }
+        }
+        // Use paramNames from the latest observation that has them
+        const paramNames = observations.reduce((acc, obs) => obs.paramNames && obs.paramNames.length > 0 ? obs.paramNames : acc, undefined);
+        // Use sample data from the first observation that has it
+        const sampleObs = observations.find(obs => obs.sampleInput != null || obs.sampleOutput != null);
+        // isAsync if any observation marked it as async
+        const isAsync = observations.some(obs => obs.isAsync === true);
+        // Collect unique type variants (by typeHash) for overload generation
+        const seenHashes = new Set();
+        const variants = [];
+        for (const obs of observations) {
+            if (!seenHashes.has(obs.typeHash)) {
+                seenHashes.add(obs.typeHash);
+                variants.push({
+                    argsType: obs.argsType,
+                    returnType: obs.returnType,
+                    paramNames: obs.paramNames,
+                    isAsync: obs.isAsync || undefined,
+                });
+            }
+        }
+        results.push({
+            name, argsType: args, returnType: ret,
+            module: observations[observations.length - 1].module,
+            isAsync: isAsync || undefined,
+            paramNames,
+            sampleInput: sampleObs?.sampleInput,
+            sampleOutput: sampleObs?.sampleOutput,
+            // Only include variants if there are 2-5 distinct patterns (overload-worthy)
+            variants: variants.length >= 2 && variants.length <= 5 ? variants : undefined,
+        });
+    }
+    return results;
+}
+// ── TypeScript generation ──
+function toPascalCase(name) {
+    return name
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .trim().split(/\s+/)
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join('');
+}
+function extractOptional(node) {
+    if (node.kind !== 'union')
+        return { isOptional: false, innerType: node };
+    const members = node.members || [];
+    const hasUndef = members.some(m => m.kind === 'primitive' && m.name === 'undefined');
+    if (!hasUndef)
+        return { isOptional: false, innerType: node };
+    const without = members.filter(m => !(m.kind === 'primitive' && m.name === 'undefined'));
+    if (without.length === 0)
+        return { isOptional: true, innerType: { kind: 'primitive', name: 'undefined' } };
+    if (without.length === 1)
+        return { isOptional: true, innerType: without[0] };
+    return { isOptional: true, innerType: { kind: 'union', members: without } };
+}
+function typeToTS(node, ext, parent, prop, indent) {
+    switch (node.kind) {
+        case 'primitive': return node.name === 'integer' ? 'number' : (node.name || 'unknown');
+        case 'unknown': return 'unknown';
+        case 'array': {
+            const inner = typeToTS(node.element, ext, parent, prop, indent);
+            return node.element.kind === 'union' ? `Array<${inner}>` : `${inner}[]`;
+        }
+        case 'tuple':
+            return `[${(node.elements || []).map((e, i) => typeToTS(e, ext, parent, `${prop || 'el'}${i}`, indent)).join(', ')}]`;
+        case 'union':
+            return (node.members || []).map(m => typeToTS(m, ext, parent, prop, indent)).join(' | ');
+        case 'map': return `Map<${typeToTS(node.key, ext, parent, 'key', indent)}, ${typeToTS(node.value, ext, parent, 'value', indent)}>`;
+        case 'set': return `Set<${typeToTS(node.element, ext, parent, prop, indent)}>`;
+        case 'promise': return `Promise<${typeToTS(node.resolved, ext, parent, prop, indent)}>`;
+        case 'function': {
+            const params = (node.params || []).map((p, i) => `arg${i}: ${typeToTS(p, ext, parent, `p${i}`, indent)}`);
+            return `(${params.join(', ')}) => ${typeToTS(node.returnType, ext, parent, 'ret', indent)}`;
+        }
+        case 'object': {
+            const keys = Object.keys(node.properties || {});
+            if (keys.length === 0)
+                return 'Record<string, never>';
+            if (keys.length > 2 && prop) {
+                const iName = toPascalCase(parent) + toPascalCase(prop);
+                if (!ext.some(e => e.name === iName))
+                    ext.push({ name: iName, node });
+                return iName;
+            }
+            const pad = '  '.repeat(indent + 1), close = '  '.repeat(indent);
+            const entries = keys.map(k => {
+                const { isOptional, innerType } = extractOptional(node.properties[k]);
+                const val = typeToTS(innerType, ext, parent, k, indent + 1);
+                return isOptional ? `${pad}${k}?: ${val};` : `${pad}${k}: ${val};`;
+            });
+            return `{\n${entries.join('\n')}\n${close}}`;
+        }
+        default: return 'unknown';
+    }
+}
+function renderInterface(name, node, ext) {
+    const keys = Object.keys(node.properties || {});
+    const lines = [`export interface ${name} {`];
+    for (const k of keys) {
+        const { isOptional, innerType } = extractOptional(node.properties[k]);
+        const val = typeToTS(innerType, ext, name, k, 1);
+        lines.push(isOptional ? `  ${k}?: ${val};` : `  ${k}: ${val};`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+function formatSampleValue(val, depth = 0) {
+    if (val === null || val === undefined)
+        return String(val);
+    if (typeof val === 'string')
+        return depth === 0 && val.length > 60 ? `"${val.slice(0, 57)}..."` : `"${val}"`;
+    if (typeof val === 'number' || typeof val === 'boolean')
+        return String(val);
+    if (Array.isArray(val)) {
+        if (val.length === 0)
+            return '[]';
+        if (depth > 1)
+            return '[...]';
+        const items = val.slice(0, 5).map(v => formatSampleValue(v, depth + 1));
+        return val.length > 5 ? `[${items.join(', ')}, ...]` : `[${items.join(', ')}]`;
+    }
+    if (typeof val === 'object') {
+        const entries = Object.entries(val);
+        if (entries.length === 0)
+            return '{}';
+        if (depth > 1)
+            return '{...}';
+        const items = entries.slice(0, 6).map(([k, v]) => `${k}: ${formatSampleValue(v, depth + 1)}`);
+        return entries.length > 6 ? `{ ${items.join(', ')}, ... }` : `{ ${items.join(', ')} }`;
+    }
+    return String(val);
+}
+function buildExampleComment(fn) {
+    if (fn.sampleInput == null && fn.sampleOutput == null)
+        return [];
+    const paramNames = fn.paramNames || [];
+    const lines = [];
+    // Format args
+    let argsStr = '';
+    if (Array.isArray(fn.sampleInput)) {
+        argsStr = fn.sampleInput.map(v => formatSampleValue(v)).join(', ');
+    }
+    else if (fn.sampleInput != null) {
+        argsStr = formatSampleValue(fn.sampleInput);
+    }
+    // Format return value
+    const retStr = fn.sampleOutput != null ? formatSampleValue(fn.sampleOutput) : undefined;
+    lines.push('/**');
+    lines.push(` * @example`);
+    if (retStr) {
+        lines.push(` * ${fn.name}(${argsStr})`);
+        lines.push(` * // => ${retStr}`);
+    }
+    else {
+        lines.push(` * ${fn.name}(${argsStr})`);
+    }
+    lines.push(' */');
+    return lines;
+}
+function generateClassDts(className, methods) {
+    const sections = [];
+    const ext = [];
+    const classLines = [`export declare class ${className} {`];
+    for (const fn of methods) {
+        const methodName = fn.name.split('.')[1] || fn.name;
+        const base = toPascalCase(className) + toPascalCase(methodName);
+        // Generate overloads if we have multiple distinct type patterns
+        if (fn.variants && fn.variants.length >= 2) {
+            for (const variant of fn.variants) {
+                const vNames = variant.paramNames || fn.paramNames || [];
+                let vArgEntries = [];
+                if (variant.argsType.kind === 'tuple') {
+                    vArgEntries = (variant.argsType.elements || []).map((el, i) => ({
+                        paramName: vNames[i] || `arg${i}`,
+                        typeNode: el,
+                    })).filter(e => e.paramName !== 'this' && e.paramName !== 'self');
+                }
+                let vRet = typeToTS(variant.returnType, ext, base, undefined, 1);
+                if (variant.isAsync)
+                    vRet = `Promise<${vRet}>`;
+                const vParams = vArgEntries.map(e => `${e.paramName}: ${typeToTS(e.typeNode, ext, base, e.paramName, 1)}`);
+                classLines.push(`  ${methodName}(${vParams.join(', ')}): ${vRet};`);
+            }
+        }
+        else {
+            // Build params (skip 'this' if present)
+            let argEntries = [];
+            if (fn.argsType.kind === 'tuple') {
+                const names = fn.paramNames || [];
+                argEntries = (fn.argsType.elements || []).map((el, i) => ({
+                    paramName: names[i] || `arg${i}`,
+                    typeNode: el,
+                })).filter(e => e.paramName !== 'this');
+            }
+            // Return type
+            let retType = typeToTS(fn.returnType, ext, base, undefined, 1);
+            if (fn.isAsync)
+                retType = `Promise<${retType}>`;
+            // Build params string (handle optional params)
+            const params = argEntries.map(e => {
+                const { isOptional, innerType } = extractOptional(e.typeNode);
+                if (isOptional) {
+                    return `${e.paramName}?: ${typeToTS(innerType, ext, base, e.paramName, 1)}`;
+                }
+                return `${e.paramName}: ${typeToTS(e.typeNode, ext, base, e.paramName, 1)}`;
+            });
+            classLines.push(`  ${methodName}(${params.join(', ')}): ${retType};`);
+        }
+    }
+    classLines.push('}');
+    // Emit extracted interfaces before the class
+    const emitted = new Set();
+    let cursor = 0;
+    while (cursor < ext.length) {
+        const iface = ext[cursor++];
+        if (emitted.has(iface.name))
+            continue;
+        emitted.add(iface.name);
+        sections.push(renderInterface(iface.name, iface.node, ext));
+        sections.push('');
+    }
+    sections.push(...classLines);
+    sections.push('');
+    return sections;
+}
+function generateDts(functions) {
+    const sections = [
+        '// Auto-generated by trickle/auto from runtime observations',
+        `// Generated at ${new Date().toISOString()}`,
+        '// Do not edit — types update automatically as your code runs',
+        '',
+    ];
+    // Separate class methods from standalone functions
+    const classMethods = new Map();
+    const standaloneFunctions = [];
+    for (const fn of functions) {
+        if (fn.name.includes('.')) {
+            const className = fn.name.split('.')[0];
+            if (!classMethods.has(className))
+                classMethods.set(className, []);
+            classMethods.get(className).push(fn);
+        }
+        else {
+            standaloneFunctions.push(fn);
+        }
+    }
+    // Generate class declarations
+    for (const [className, methods] of classMethods) {
+        sections.push(...generateClassDts(className, methods));
+    }
+    for (const fn of standaloneFunctions) {
+        const base = toPascalCase(fn.name);
+        const ext = [];
+        const lines = [];
+        // Args
+        let argEntries = [];
+        if (fn.argsType.kind === 'tuple') {
+            const names = fn.paramNames || [];
+            argEntries = (fn.argsType.elements || []).map((el, i) => ({
+                paramName: names[i] || `arg${i}`,
+                typeNode: el,
+            }));
+        }
+        else if (fn.argsType.kind === 'object') {
+            argEntries = Object.keys(fn.argsType.properties || {}).map(k => ({ paramName: k, typeNode: fn.argsType.properties[k] }));
+        }
+        else {
+            argEntries = [{ paramName: 'input', typeNode: fn.argsType }];
+        }
+        const singleObj = argEntries.length === 1 && argEntries[0].typeNode.kind === 'object';
+        if (singleObj) {
+            lines.push(renderInterface(`${base}Input`, argEntries[0].typeNode, ext));
+            lines.push('');
+        }
+        // Return
+        const outName = `${base}Output`;
+        if (fn.returnType.kind === 'object' && Object.keys(fn.returnType.properties || {}).length > 0) {
+            lines.push(renderInterface(outName, fn.returnType, ext));
+            lines.push('');
+        }
+        else {
+            lines.push(`export type ${outName} = ${typeToTS(fn.returnType, ext, base, undefined, 0)};`);
+            lines.push('');
+        }
+        // Extracted interfaces
+        const emitted = new Set();
+        const extLines = [];
+        let cursor = 0;
+        while (cursor < ext.length) {
+            const iface = ext[cursor++];
+            if (emitted.has(iface.name))
+                continue;
+            emitted.add(iface.name);
+            extLines.push(renderInterface(iface.name, iface.node, ext));
+            extLines.push('');
+        }
+        // Function declaration
+        const ident = base.charAt(0).toLowerCase() + base.slice(1);
+        if (extLines.length > 0)
+            sections.push(...extLines);
+        sections.push(...lines);
+        // Add @example JSDoc if sample data is available
+        const exampleLines = buildExampleComment(fn);
+        if (exampleLines.length > 0)
+            sections.push(...exampleLines);
+        // Generate overloads if we have multiple distinct type patterns
+        if (fn.variants && fn.variants.length >= 2) {
+            for (const variant of fn.variants) {
+                const vExt = [];
+                const vRet = typeToTS(variant.returnType, vExt, base, undefined, 0);
+                const vRetDecl = variant.isAsync ? `Promise<${vRet}>` : vRet;
+                const vNames = variant.paramNames || fn.paramNames || [];
+                let vArgEntries = [];
+                if (variant.argsType.kind === 'tuple') {
+                    vArgEntries = (variant.argsType.elements || []).map((el, i) => ({
+                        paramName: vNames[i] || `arg${i}`,
+                        typeNode: el,
+                    }));
+                }
+                const vParams = vArgEntries.map(e => `${e.paramName}: ${typeToTS(e.typeNode, vExt, base, e.paramName, 0)}`);
+                sections.push(`export declare function ${ident}(${vParams.join(', ')}): ${vRetDecl};`);
+            }
+        }
+        else {
+            const retDecl = fn.isAsync ? `Promise<${outName}>` : outName;
+            let decl;
+            if (singleObj) {
+                decl = `export declare function ${ident}(input: ${base}Input): ${retDecl};`;
+            }
+            else {
+                const params = argEntries.map(e => {
+                    if (e.typeNode.kind === 'object' && Object.keys(e.typeNode.properties || {}).length > 0)
+                        return `${e.paramName}: ${base}${toPascalCase(e.paramName)}`;
+                    // Check if parameter is optional (union with undefined)
+                    const { isOptional, innerType } = extractOptional(e.typeNode);
+                    if (isOptional) {
+                        return `${e.paramName}?: ${typeToTS(innerType, ext, base, e.paramName, 0)}`;
+                    }
+                    return `${e.paramName}: ${typeToTS(e.typeNode, ext, base, e.paramName, 0)}`;
+                });
+                decl = `export declare function ${ident}(${params.join(', ')}): ${retDecl};`;
+            }
+            sections.push(decl);
+        }
+        sections.push('');
+    }
+    return sections.join('\n').trimEnd() + '\n';
+}
+// ── JSDoc type formatting ──
+function typeToJSDoc(node) {
+    switch (node.kind) {
+        case 'primitive': return node.name === 'integer' ? 'number' : (node.name || '*');
+        case 'unknown': return '*';
+        case 'array': {
+            const inner = typeToJSDoc(node.element);
+            return `${inner}[]`;
+        }
+        case 'tuple':
+            return `[${(node.elements || []).map(typeToJSDoc).join(', ')}]`;
+        case 'union':
+            return (node.members || []).map(typeToJSDoc).join(' | ');
+        case 'map': return `Map<${typeToJSDoc(node.key)}, ${typeToJSDoc(node.value)}>`;
+        case 'set': return `Set<${typeToJSDoc(node.element)}>`;
+        case 'promise': return `Promise<${typeToJSDoc(node.resolved)}>`;
+        case 'function': {
+            const params = (node.params || []).map((p, i) => `arg${i}: ${typeToJSDoc(p)}`);
+            return `function(${params.join(', ')}): ${typeToJSDoc(node.returnType)}`;
+        }
+        case 'object': {
+            const props = node.properties || {};
+            const keys = Object.keys(props);
+            if (keys.length === 0)
+                return 'Object';
+            const entries = keys.map(k => {
+                const { isOptional, innerType } = extractOptional(props[k]);
+                return isOptional ? `${k}?: ${typeToJSDoc(innerType)}` : `${k}: ${typeToJSDoc(innerType)}`;
+            });
+            return `{ ${entries.join(', ')} }`;
+        }
+        default: return '*';
+    }
+}
+// ── JSDoc injection into source files ──
+const funcDeclRe = /^(\s*(?:export\s+)?(?:async\s+)?function\s+)(\w+)\s*(?:<[^>]*>)?\s*\(/;
+const arrowRe = /^(\s*(?:export\s+)?(?:const|let|var)\s+)(\w+)\s*=\s*(?:async\s+)?\(/;
+const methodRe = /^(\s+)(\w+)\s*\(([^)]*)\)\s*\{/;
+function injectJSDocIntoFile(filePath, functions) {
+    const source = fs.readFileSync(filePath, 'utf-8');
+    const lines = source.split('\n');
+    const fnMap = new Map(functions.map(f => [f.name, f]));
+    const result = [];
+    let changed = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trimStart();
+        // Try to match a function declaration
+        let fnName = null;
+        let m = trimmed.match(funcDeclRe);
+        if (m)
+            fnName = m[2];
+        if (!fnName) {
+            m = trimmed.match(arrowRe);
+            if (m)
+                fnName = m[2];
+        }
+        if (!fnName) {
+            m = trimmed.match(methodRe);
+            if (m)
+                fnName = m[2];
+        }
+        if (!fnName || !fnMap.has(fnName)) {
+            result.push(line);
+            continue;
+        }
+        // Check if there's already a JSDoc comment above
+        const prevIdx = result.length - 1;
+        if (prevIdx >= 0) {
+            const prev = result[prevIdx].trim();
+            if (prev === '*/' || prev.endsWith('*/')) {
+                let j = prevIdx;
+                while (j >= 0 && !result[j].trim().startsWith('/**'))
+                    j--;
+                if (j >= 0) {
+                    const block = result.slice(j, prevIdx + 1).join('\n');
+                    if (block.includes('@param') || block.includes('@returns') || block.includes('@trickle')) {
+                        result.push(line);
+                        continue;
+                    }
+                }
+            }
+        }
+        const fn = fnMap.get(fnName);
+        const indent = line.match(/^(\s*)/)?.[1] || '';
+        // Build JSDoc
+        const jsdocLines = [`${indent}/** @trickle — auto-generated from runtime observations`];
+        // Params
+        const argElements = fn.argsType.kind === 'tuple' ? (fn.argsType.elements || []) : [];
+        const paramNames = fn.paramNames || [];
+        for (let pi = 0; pi < argElements.length; pi++) {
+            const pName = paramNames[pi] || `arg${pi}`;
+            const pType = typeToJSDoc(argElements[pi]);
+            jsdocLines.push(`${indent} * @param {${pType}} ${pName}`);
+        }
+        // Return type
+        const retType = typeToJSDoc(fn.returnType);
+        if (retType !== 'undefined' && retType !== 'void') {
+            jsdocLines.push(`${indent} * @returns {${retType}}`);
+        }
+        jsdocLines.push(`${indent} */`);
+        if (jsdocLines.length > 2) {
+            result.push(...jsdocLines);
+            changed = true;
+        }
+        result.push(line);
+    }
+    if (changed) {
+        fs.writeFileSync(filePath, result.join('\n'), 'utf-8');
+    }
+    return changed;
+}
+/**
+ * Inject JSDoc comments into JS source files based on observations.
+ * Only runs when TRICKLE_INJECT=1.
+ */
+function injectTypes() {
+    if (process.env.TRICKLE_INJECT !== '1')
+        return 0;
+    const trickleDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    const jsonlPath = path.join(trickleDir, 'observations.jsonl');
+    if (!fs.existsSync(jsonlPath))
+        return 0;
+    const functions = readAndMerge(jsonlPath);
+    if (functions.length === 0)
+        return 0;
+    const byModule = new Map();
+    for (const fn of functions) {
+        const mod = fn.module || '_default';
+        if (!byModule.has(mod))
+            byModule.set(mod, []);
+        byModule.get(mod).push(fn);
+    }
+    let injected = 0;
+    for (const [mod, fns] of byModule) {
+        if (mod.includes('.') && !mod.includes('/') && !mod.includes('\\'))
+            continue;
+        const sourceFile = findSourceFile(mod);
+        if (!sourceFile)
+            continue;
+        const ext = path.extname(sourceFile);
+        // Only inject into JS files (not .ts — those already have types)
+        if (!['.js', '.jsx', '.mjs', '.cjs'].includes(ext))
+            continue;
+        try {
+            if (injectJSDocIntoFile(sourceFile, fns)) {
+                injected += fns.length;
+            }
+        }
+        catch { /* don't crash user's app */ }
+    }
+    return injected;
+}
+// ── Public API ──
+let lastSize = 0;
+let lastContent = '';
+/**
+ * Read observations and generate .d.ts files next to source files.
+ * Returns the number of functions typed.
+ */
+function generateTypes() {
+    const trickleDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    const jsonlPath = path.join(trickleDir, 'observations.jsonl');
+    if (!fs.existsSync(jsonlPath))
+        return 0;
+    // Skip if file hasn't changed
+    try {
+        const stat = fs.statSync(jsonlPath);
+        if (stat.size === lastSize)
+            return -1; // -1 = no change
+        lastSize = stat.size;
+    }
+    catch {
+        return 0;
+    }
+    const functions = readAndMerge(jsonlPath);
+    if (functions.length === 0)
+        return 0;
+    // Group by module and generate .d.ts next to source files
+    const byModule = new Map();
+    for (const fn of functions) {
+        const mod = fn.module || '_default';
+        if (!byModule.has(mod))
+            byModule.set(mod, []);
+        byModule.get(mod).push(fn);
+    }
+    let totalFunctions = 0;
+    for (const [mod, fns] of byModule) {
+        // Skip HTTP route observations (module is hostname like "localhost")
+        if (mod.includes('.') && !mod.includes('/') && !mod.includes('\\'))
+            continue;
+        const dts = generateDts(fns);
+        if (dts === lastContent)
+            continue;
+        // Find source file for this module
+        const sourceFile = findSourceFile(mod);
+        if (!sourceFile)
+            continue;
+        const ext = path.extname(sourceFile);
+        const dir = path.dirname(sourceFile);
+        const baseName = path.basename(sourceFile, ext);
+        // For .ts/.tsx files, use .trickle.d.ts to avoid conflicts (TS ignores .d.ts next to .ts)
+        const isTs = ext === '.ts' || ext === '.tsx';
+        const dtsPath = path.join(dir, `${baseName}${isTs ? '.trickle' : ''}.d.ts`);
+        try {
+            fs.writeFileSync(dtsPath, dts, 'utf-8');
+            lastContent = dts;
+            totalFunctions += fns.length;
+        }
+        catch { /* don't crash user's app */ }
+    }
+    return totalFunctions;
+}
+// ── Type coverage report ──
+const jsFuncDeclRe = /^(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*(?:<[^>]*>)?\s*\(/;
+const jsArrowRe = /^(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(/;
+const jsMethodRe = /^\s+(\w+)\s*\([^)]*\)\s*\{/;
+function extractFunctionNames(source, ext) {
+    const names = [];
+    const lines = source.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trimStart();
+        // Skip comments
+        if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*'))
+            continue;
+        let m = trimmed.match(jsFuncDeclRe);
+        if (m && m[1] !== 'constructor') {
+            names.push(m[1]);
+            continue;
+        }
+        m = trimmed.match(jsArrowRe);
+        if (m) {
+            names.push(m[1]);
+            continue;
+        }
+        // Methods only for class-based files
+        m = trimmed.match(jsMethodRe);
+        if (m && m[1] !== 'constructor' && m[1] !== 'if' && m[1] !== 'for' && m[1] !== 'while' && m[1] !== 'switch' && m[1] !== 'catch') {
+            names.push(m[1]);
+        }
+    }
+    return [...new Set(names)];
+}
+/**
+ * Generate a type coverage report comparing observed types against
+ * all function declarations found in source files.
+ * Only runs when TRICKLE_COVERAGE=1.
+ */
+function generateCoverageReport() {
+    if (process.env.TRICKLE_COVERAGE !== '1')
+        return null;
+    const trickleDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    const jsonlPath = path.join(trickleDir, 'observations.jsonl');
+    if (!fs.existsSync(jsonlPath))
+        return null;
+    const functions = readAndMerge(jsonlPath);
+    if (functions.length === 0)
+        return null;
+    // Group observed functions by module
+    const observedByModule = new Map();
+    for (const fn of functions) {
+        const mod = fn.module || '_default';
+        if (!observedByModule.has(mod))
+            observedByModule.set(mod, new Set());
+        observedByModule.get(mod).add(fn.name);
+    }
+    const entries = [];
+    let totalAll = 0;
+    let typedAll = 0;
+    for (const [mod, observedNames] of observedByModule) {
+        // Skip HTTP route observations
+        if (mod.includes('.') && !mod.includes('/') && !mod.includes('\\'))
+            continue;
+        const sourceFile = findSourceFile(mod);
+        if (!sourceFile)
+            continue;
+        let source;
+        try {
+            source = fs.readFileSync(sourceFile, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const ext = path.extname(sourceFile);
+        const allFunctions = extractFunctionNames(source, ext);
+        if (allFunctions.length === 0)
+            continue;
+        const typed = allFunctions.filter(n => observedNames.has(n));
+        const untyped = allFunctions.filter(n => !observedNames.has(n));
+        totalAll += allFunctions.length;
+        typedAll += typed.length;
+        const relPath = path.relative(process.cwd(), sourceFile);
+        entries.push({
+            file: relPath,
+            total: allFunctions.length,
+            typed: typed.length,
+            untyped,
+        });
+    }
+    if (entries.length === 0)
+        return null;
+    // Sort: incomplete files first, then by coverage
+    entries.sort((a, b) => {
+        const aRatio = a.typed / a.total;
+        const bRatio = b.typed / b.total;
+        return aRatio - bRatio;
+    });
+    const lines = ['[trickle/auto] Type coverage:'];
+    for (const entry of entries) {
+        const pct = Math.round((entry.typed / entry.total) * 100);
+        const marker = pct === 100 ? ' ✓' : '';
+        lines.push(`  ${entry.file}: ${entry.typed}/${entry.total} (${pct}%)${marker}`);
+        if (entry.untyped.length > 0) {
+            lines.push(`    Untyped: ${entry.untyped.join(', ')}`);
+        }
+    }
+    const totalPct = totalAll > 0 ? Math.round((typedAll / totalAll) * 100) : 0;
+    lines.push(`  Total: ${typedAll}/${totalAll} functions (${totalPct}%)`);
+    return lines.join('\n');
+}
+// ── Type summary with change detection ──
+const SNAPSHOT_FILE = '.trickle/type-snapshot.json';
+function typeToCompact(node, depth = 0) {
+    if (depth > 2)
+        return '...';
+    switch (node.kind) {
+        case 'primitive': return node.name === 'integer' ? 'number' : (node.name || 'unknown');
+        case 'unknown': return 'unknown';
+        case 'array': return `${typeToCompact(node.element, depth + 1)}[]`;
+        case 'tuple': return `[${(node.elements || []).map(e => typeToCompact(e, depth + 1)).join(', ')}]`;
+        case 'union': return (node.members || []).map(m => typeToCompact(m, depth)).join(' | ');
+        case 'promise': return `Promise<${typeToCompact(node.resolved, depth + 1)}>`;
+        case 'map': return `Map<${typeToCompact(node.key, depth + 1)}, ${typeToCompact(node.value, depth + 1)}>`;
+        case 'set': return `Set<${typeToCompact(node.element, depth + 1)}>`;
+        case 'function': return `(...) => ${typeToCompact(node.returnType, depth + 1)}`;
+        case 'object': {
+            const props = node.properties || {};
+            const keys = Object.keys(props);
+            if (keys.length === 0)
+                return '{}';
+            if (keys.length > 4) {
+                const shown = keys.slice(0, 3).map(k => `${k}: ${typeToCompact(props[k], depth + 1)}`);
+                return `{ ${shown.join(', ')}, ... }`;
+            }
+            return `{ ${keys.map(k => `${k}: ${typeToCompact(props[k], depth + 1)}`).join(', ')} }`;
+        }
+        default: return 'unknown';
+    }
+}
+function buildSignature(fn) {
+    const paramNames = fn.paramNames || [];
+    let params = '';
+    if (fn.argsType.kind === 'tuple') {
+        const elements = fn.argsType.elements || [];
+        params = elements.map((el, i) => {
+            const name = paramNames[i] || `arg${i}`;
+            return `${name}: ${typeToCompact(el)}`;
+        }).join(', ');
+    }
+    const ret = typeToCompact(fn.returnType);
+    const retDisplay = fn.isAsync ? `Promise<${ret}>` : ret;
+    const prefix = fn.isAsync ? 'async ' : '';
+    return `${prefix}${fn.name}(${params}) → ${retDisplay}`;
+}
+function loadSnapshot() {
+    const trickleDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    const snapshotPath = path.join(trickleDir, SNAPSHOT_FILE.split('/').pop());
+    try {
+        const content = fs.readFileSync(snapshotPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function saveSnapshot(snapshot) {
+    const trickleDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    const snapshotPath = path.join(trickleDir, SNAPSHOT_FILE.split('/').pop());
+    try {
+        fs.mkdirSync(trickleDir, { recursive: true });
+        fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+    }
+    catch { /* don't crash */ }
+}
+/**
+ * Generate a type summary showing discovered function signatures.
+ * When a previous snapshot exists, highlights new and changed functions.
+ * Only runs when TRICKLE_SUMMARY=1.
+ */
+function generateTypeSummary() {
+    if (process.env.TRICKLE_SUMMARY !== '1')
+        return null;
+    const trickleDir = process.env.TRICKLE_LOCAL_DIR || path.join(process.cwd(), '.trickle');
+    const jsonlPath = path.join(trickleDir, 'observations.jsonl');
+    if (!fs.existsSync(jsonlPath))
+        return null;
+    const functions = readAndMerge(jsonlPath);
+    if (functions.length === 0)
+        return null;
+    // Filter out HTTP route observations
+    const userFunctions = functions.filter(fn => {
+        const mod = fn.module || '';
+        return !(mod.includes('.') && !mod.includes('/') && !mod.includes('\\'));
+    });
+    if (userFunctions.length === 0)
+        return null;
+    // Build current signatures
+    const currentSigs = {};
+    for (const fn of userFunctions) {
+        currentSigs[fn.name] = buildSignature(fn);
+    }
+    // Load previous snapshot for diff
+    const prevSnapshot = loadSnapshot();
+    const prevSigs = prevSnapshot?.functions || {};
+    // Compute diff
+    let newCount = 0;
+    let changedCount = 0;
+    const entries = [];
+    // Sort functions by module then name for clean output
+    const sorted = [...userFunctions].sort((a, b) => {
+        if (a.module !== b.module)
+            return a.module.localeCompare(b.module);
+        return a.name.localeCompare(b.name);
+    });
+    for (const fn of sorted) {
+        const sig = currentSigs[fn.name];
+        if (!(fn.name in prevSigs)) {
+            entries.push({ sig, status: 'new' });
+            newCount++;
+        }
+        else if (prevSigs[fn.name] !== sig) {
+            entries.push({ sig, status: 'changed' });
+            changedCount++;
+        }
+        else {
+            entries.push({ sig, status: 'same' });
+        }
+    }
+    // Save new snapshot
+    saveSnapshot({ functions: currentSigs });
+    // Build output
+    const header = newCount > 0 || changedCount > 0
+        ? `[trickle/auto] Discovered types (${newCount} new, ${changedCount} changed):`
+        : `[trickle/auto] Discovered types:`;
+    const lines = [header];
+    for (const entry of entries) {
+        const prefix = entry.status === 'new' ? '  + ' : entry.status === 'changed' ? '  ~ ' : '    ';
+        const suffix = entry.status === 'new' ? '  NEW' : entry.status === 'changed' ? '  CHANGED' : '';
+        lines.push(`${prefix}${entry.sig}${suffix}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Try to find the source file for a given module name.
+ */
+function findSourceFile(moduleName) {
+    const cwd = process.cwd();
+    const exts = ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'];
+    // Try direct match in cwd
+    for (const ext of exts) {
+        const candidate = path.join(cwd, moduleName + ext);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    // Try with dashes/underscores replaced
+    const normalized = moduleName.replace(/[-_]/g, '');
+    for (const ext of exts) {
+        const candidate = path.join(cwd, normalized + ext);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    // Try as subdirectory/index
+    for (const ext of exts) {
+        const candidate = path.join(cwd, moduleName, `index${ext}`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}