trickle-observe 0.2.2 → 0.2.4

package/src/auto-codegen.ts

@@ -258,6 +258,12 @@ function typeToTS(node: TypeNode, ext: Extracted[], parent: string, prop: string
     case 'object': {
       const keys = Object.keys(node.properties || {});
       if (keys.length === 0) return 'Record<string, never>';
+      // Recognize special marker objects from type-inference
+      if (keys.length === 1 && keys[0] === '__date') return 'Date';
+      if (keys.length === 1 && keys[0] === '__buffer') return 'Buffer';
+      if (keys.length === 1 && keys[0] === '__typedArray') return 'TypedArray';
+      if (keys.includes('__regexp')) return 'RegExp';
+      if (keys.includes('__error')) return 'Error';
       if (keys.length > 2 && prop) {
         const iName = toPascalCase(parent) + toPascalCase(prop);
         if (!ext.some(e => e.name === iName)) ext.push({ name: iName, node });
@@ -563,6 +569,11 @@ function typeToJSDoc(node: TypeNode): string {
       const props = node.properties || {};
       const keys = Object.keys(props);
       if (keys.length === 0) return 'Object';
+      // Recognize special marker objects from type-inference
+      if (keys.length === 1 && keys[0] === '__date') return 'Date';
+      if (keys.length === 1 && keys[0] === '__buffer') return 'Buffer';
+      if (keys.includes('__regexp')) return 'RegExp';
+      if (keys.includes('__error')) return 'Error';
       const entries = keys.map(k => {
         const { isOptional, innerType } = extractOptional(props[k]);
         return isOptional ? `${k}?: ${typeToJSDoc(innerType)}` : `${k}: ${typeToJSDoc(innerType)}`;
@@ -707,10 +718,147 @@ export function injectTypes(): number {
 // ── Public API ──
 
 let lastSize = 0;
-let lastContent = '';
+const lastContentByModule = new Map<string, string>();
+let tsconfigPatched = false;
 
 /**
- * Read observations and generate .d.ts files next to source files.
+ * Generate a typed Express route definitions file from route observations.
+ * Each route (e.g., "GET /users") becomes a typed interface.
+ */
+function generateRoutesDts(routeFunctions: FunctionData[]): string {
+  const sections: string[] = [
+    '// Auto-generated by trickle — Express route types from runtime observations',
+    `// Generated at ${new Date().toISOString()}`,
+    '// Do not edit — types update automatically as your code runs',
+    '',
+  ];
+
+  const ext: Extracted[] = [];
+
+  for (const fn of routeFunctions) {
+    // Route name like "GET /users" → GetUsers
+    const routeName = fn.name;
+    const baseName = toPascalCase(routeName);
+
+    // Input type (body, params, query)
+    const inputProps = fn.argsType.kind === 'object' ? fn.argsType.properties || {} : {};
+    const hasInput = Object.keys(inputProps).length > 0;
+
+    if (hasInput) {
+      sections.push(renderInterface(`${baseName}Input`, fn.argsType, ext));
+      sections.push('');
+    }
+
+    // Output type
+    if (fn.returnType.kind === 'object' && Object.keys(fn.returnType.properties || {}).length > 0) {
+      sections.push(renderInterface(`${baseName}Output`, fn.returnType, ext));
+    } else {
+      sections.push(`export type ${baseName}Output = ${typeToTS(fn.returnType, ext, baseName, undefined, 0)};`);
+    }
+    sections.push('');
+  }
+
+  // Emit extracted interfaces
+  const emitted = new Set<string>();
+  const extLines: string[] = [];
+  for (const iface of ext) {
+    if (emitted.has(iface.name)) continue;
+    emitted.add(iface.name);
+    extLines.push(renderInterface(iface.name, iface.node, ext));
+    extLines.push('');
+  }
+  if (extLines.length > 0) {
+    // Insert extracted interfaces after the header, before route types
+    sections.splice(4, 0, ...extLines);
+  }
+
+  // Route map type for typed middleware/client usage
+  sections.push('/** All observed routes with their input/output types */');
+  sections.push('export interface TrickleRoutes {');
+  for (const fn of routeFunctions) {
+    const baseName = toPascalCase(fn.name);
+    const inputProps = fn.argsType.kind === 'object' ? fn.argsType.properties || {} : {};
+    const hasInput = Object.keys(inputProps).length > 0;
+    const inputType = hasInput ? `${baseName}Input` : 'Record<string, never>';
+    sections.push(`  '${fn.name}': { input: ${inputType}; output: ${baseName}Output };`);
+  }
+  sections.push('}');
+  sections.push('');
+
+  return sections.join('\n');
+}
+
+/**
+ * Ensure .trickle/types/ directory exists.
+ */
+function ensureTypesDir(trickleDir: string): string {
+  const typesDir = path.join(trickleDir, 'types');
+  try {
+    fs.mkdirSync(typesDir, { recursive: true });
+  } catch { /* already exists */ }
+  return typesDir;
+}
+
+/**
+ * Auto-patch tsconfig.json to include .trickle/types so generated
+ * types are visible in VSCode and tsc. Only runs once per process.
+ */
+function patchTsConfig(): void {
+  if (tsconfigPatched) return;
+  tsconfigPatched = true;
+
+  const tsconfigPath = path.join(process.cwd(), 'tsconfig.json');
+  try {
+    if (!fs.existsSync(tsconfigPath)) return;
+
+    const raw = fs.readFileSync(tsconfigPath, 'utf-8');
+    // Strip JSON comments safely (skip strings to avoid breaking paths like "@/*")
+    let stripped = '';
+    let i = 0;
+    while (i < raw.length) {
+      if (raw[i] === '"') {
+        // Skip string content
+        let j = i + 1;
+        while (j < raw.length && raw[j] !== '"') {
+          if (raw[j] === '\\') j++; // skip escaped char
+          j++;
+        }
+        stripped += raw.slice(i, j + 1);
+        i = j + 1;
+      } else if (raw[i] === '/' && i + 1 < raw.length && raw[i + 1] === '/') {
+        // Line comment — skip to end of line
+        while (i < raw.length && raw[i] !== '\n') i++;
+      } else if (raw[i] === '/' && i + 1 < raw.length && raw[i + 1] === '*') {
+        // Block comment — skip to */
+        i += 2;
+        while (i < raw.length - 1 && !(raw[i] === '*' && raw[i + 1] === '/')) i++;
+        i += 2;
+      } else {
+        stripped += raw[i];
+        i++;
+      }
+    }
+    // Also strip trailing commas (common in tsconfig)
+    const cleaned = stripped.replace(/,(\s*[}\]])/g, '$1');
+    const config = JSON.parse(cleaned);
+
+    const include = config.include as string[] | undefined;
+    if (include && include.some((p: string) => p === '.trickle' || p.startsWith('.trickle/'))) {
+      return; // Already configured
+    }
+
+    if (include) {
+      include.push('.trickle/types');
+    } else {
+      config.include = ['.trickle/types'];
+    }
+
+    fs.writeFileSync(tsconfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  } catch { /* don't crash — tsconfig patching is best-effort */ }
+}
+
+/**
+ * Read observations and generate .d.ts type files in .trickle/types/.
  * Returns the number of functions typed.
  */
 export function generateTypes(): number {
@@ -729,36 +877,55 @@ export function generateTypes(): number {
   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<string, FunctionData[]>();
+  // Separate Express route observations from regular functions
+  const routeFunctions: FunctionData[] = [];
+  const regularFunctions: FunctionData[] = [];
   for (const fn of functions) {
+    if (fn.module === 'express' && /^(GET|POST|PUT|DELETE|PATCH|ALL)\s/.test(fn.name)) {
+      routeFunctions.push(fn);
+    } else {
+      regularFunctions.push(fn);
+    }
+  }
+
+  // Group regular functions by module
+  const byModule = new Map<string, FunctionData[]>();
+  for (const fn of regularFunctions) {
     const mod = fn.module || '_default';
     if (!byModule.has(mod)) byModule.set(mod, []);
     byModule.get(mod)!.push(fn);
   }
 
+  // Write all types to .trickle/types/ so TypeScript picks them up via tsconfig include
+  const typesDir = ensureTypesDir(trickleDir);
+  patchTsConfig();
+
   let totalFunctions = 0;
+
+  // Generate Express route types
+  if (routeFunctions.length > 0) {
+    const routesDts = generateRoutesDts(routeFunctions);
+    if (routesDts !== lastContentByModule.get('__routes')) {
+      const routesDtsPath = path.join(typesDir, 'routes.d.ts');
+      try {
+        fs.writeFileSync(routesDtsPath, routesDts, 'utf-8');
+        lastContentByModule.set('__routes', routesDts);
+        totalFunctions += routeFunctions.length;
+      } catch { /* don't crash */ }
+    }
+  }
+
   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`);
+    if (dts === lastContentByModule.get(mod)) continue;
 
+    const dtsPath = path.join(typesDir, `${mod}.d.ts`);
     try {
       fs.writeFileSync(dtsPath, dts, 'utf-8');
-      lastContent = dts;
+      lastContentByModule.set(mod, dts);
       totalFunctions += fns.length;
     } catch { /* don't crash user's app */ }
   }
@@ -902,6 +1069,10 @@ function typeToCompact(node: TypeNode, depth = 0): string {
       const props = node.properties || {};
       const keys = Object.keys(props);
       if (keys.length === 0) return '{}';
+      if (keys.length === 1 && keys[0] === '__date') return 'Date';
+      if (keys.length === 1 && keys[0] === '__buffer') return 'Buffer';
+      if (keys.includes('__regexp')) return 'RegExp';
+      if (keys.includes('__error')) return 'Error';
       if (keys.length > 4) {
         const shown = keys.slice(0, 3).map(k => `${k}: ${typeToCompact(props[k], depth + 1)}`);
         return `{ ${shown.join(', ')}, ... }`;
@@ -1028,6 +1199,39 @@ export function generateTypeSummary(): string | null {
   return lines.join('\n');
 }
 
+/**
+ * Cached recursive file index: maps basename (without ext) → full path.
+ * Built once on first call, then reused.
+ */
+let fileIndex: Map<string, string> | null = null;
+
+function buildFileIndex(): Map<string, string> {
+  const cwd = process.cwd();
+  const exts = new Set(['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs']);
+  const index = new Map<string, string>();
+
+  // Common source directories to scan
+  const dirs = ['src', 'dist', 'lib', 'app', '.'];
+  for (const dir of dirs) {
+    const absDir = path.join(cwd, dir);
+    try {
+      const entries = fs.readdirSync(absDir, { recursive: true, withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const ext = path.extname(entry.name);
+        if (!exts.has(ext)) continue;
+        const baseName = entry.name.replace(/\.[^.]+$/, '');
+        const fullPath = path.join(absDir, (entry as any).parentPath ? path.relative(absDir, (entry as any).parentPath) : '', entry.name);
+        // Prefer src/ over dist/ for the same basename
+        if (!index.has(baseName) || fullPath.includes('/src/')) {
+          index.set(baseName, fullPath);
+        }
+      }
+    } catch { /* dir doesn't exist */ }
+  }
+  return index;
+}
+
 /**
  * Try to find the source file for a given module name.
  */
@@ -1054,5 +1258,9 @@ function findSourceFile(moduleName: string): string | null {
     if (fs.existsSync(candidate)) return candidate;
   }
 
-  return null;
+  // Recursive search using cached file index
+  if (!fileIndex) {
+    fileIndex = buildFileIndex();
+  }
+  return fileIndex.get(moduleName) || null;
 }

package/src/auto-register.ts

@@ -48,7 +48,7 @@ function runGeneration(isFinal: boolean): void {
     }
 
     if (isFinal && lastFunctionCount > 0) {
-      console.log(`[trickle/auto] ${lastFunctionCount} function type(s) written to .d.ts`);
+      console.log(`[trickle/auto] ${lastFunctionCount} function type(s) written to .trickle/types/`);
       // Inject JSDoc into source files if TRICKLE_INJECT=1
       try {
         const injected = injectTypes();

package/src/express.d.ts

@@ -0,0 +1,387 @@
+// Auto-generated by trickle from runtime type observations
+// Generated at 2026-03-12T09:51:12.160Z
+// Do not edit manually — re-run `trickle codegen` to update
+
+export interface GetApiProductsOutputProducts {
+  id: number;
+  name: string;
+  price: number;
+  category: string;
+}
+
+/**
+ * Output type for `GET /api/products` — express module, observed in node, 40m ago
+ */
+export interface GetApiProductsOutput {
+  products: GetApiProductsOutputProducts[];
+  total: number;
+  page: number;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {}
+ * // Sample output:
+ * {
+ *   "products": [
+ *     {
+ *       "id": "[truncated]",
+ *       "name": "[truncated]",
+ *       "price": "[truncated]",
+ *       "category": "[truncated]"
+ *     },
+ *     {
+ *       "id": "[truncated]",
+ *       "name": "[truncated]",
+ *       "price": "[truncated]",
+ *       "category": "[truncated]"
+ *     },
+ *     {
+ *       "id": "[truncated]",
+ *       "name": "[truncated]",
+ *       "price": "[truncated]",
+ *       "category": "[truncated]"
+ *     }
+ *   ],
+ *   "total": 3,
+ *   "page": 1
+ * }
+ */
+export declare function getApiProducts(): GetApiProductsOutput;
+
+/**
+ * Input type for `GET /api/products/:id` — express module, observed in node, 40m ago
+ */
+export interface GetApiProductsIdInput {
+  id: string;
+}
+
+/**
+ * Output type for `GET /api/products/:id` — express module, observed in node, 40m ago
+ */
+export interface GetApiProductsIdOutput {
+  id: number;
+  name: string;
+  price: number;
+  category: string;
+  description: string;
+  reviews: {
+    rating: number;
+    comment: string;
+  }[];
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "params": {
+ *     "id": "1"
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "id": 1,
+ *   "name": "Widget",
+ *   "price": 29.99,
+ *   "category": "electronics",
+ *   "description": "A fine widget for all your widgeting needs",
+ *   "reviews": [
+ *     {
+ *       "rating": "[truncated]",
+ *       "comment": "[truncated]"
+ *     },
+ *     {
+ *       "rating": "[truncated]",
+ *       "comment": "[truncated]"
+ *     }
+ *   ]
+ * }
+ */
+export declare function getApiProductsId(input: GetApiProductsIdInput): GetApiProductsIdOutput;
+
+export interface PostApiCartAddOutputItems {
+  productId: number;
+  quantity: number;
+  price: number;
+}
+
+/**
+ * Input type for `POST /api/cart/add` — express module, observed in node, 40m ago
+ */
+export interface PostApiCartAddInput {
+  productId: number;
+  quantity: number;
+}
+
+/**
+ * Output type for `POST /api/cart/add` — express module, observed in node, 40m ago
+ */
+export interface PostApiCartAddOutput {
+  cartId: string;
+  items: PostApiCartAddOutputItems[];
+  subtotal: number;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "body": {
+ *     "productId": 1,
+ *     "quantity": 2
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "cartId": "CART-12345",
+ *   "items": [
+ *     {
+ *       "productId": "[truncated]",
+ *       "quantity": "[truncated]",
+ *       "price": "[truncated]"
+ *     }
+ *   ],
+ *   "subtotal": 59.98
+ * }
+ */
+export declare function postApiCartAdd(input: PostApiCartAddInput): PostApiCartAddOutput;
+
+/**
+ * Input type for `DELETE /api/cart/:cartId` — express module, observed in node, 40m ago
+ */
+export interface DeleteApiCartCartIdInput {
+  cartId: string;
+}
+
+/**
+ * Output type for `DELETE /api/cart/:cartId` — express module, observed in node, 40m ago
+ */
+export interface DeleteApiCartCartIdOutput {
+  deleted: boolean;
+  cartId: string;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "params": {
+ *     "cartId": "CART-999"
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "deleted": true,
+ *   "cartId": "CART-999"
+ * }
+ */
+export declare function deleteApiCartCartId(input: DeleteApiCartCartIdInput): DeleteApiCartCartIdOutput;
+
+export interface GetApiUsersOutputUsers {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+}
+
+/**
+ * Output type for `GET /api/users` — express module, observed in node, 41m ago
+ */
+export interface GetApiUsersOutput {
+  users: GetApiUsersOutputUsers[];
+  total: number;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {}
+ * // Sample output:
+ * {
+ *   "users": [
+ *     {
+ *       "id": "[truncated]",
+ *       "name": "[truncated]",
+ *       "email": "[truncated]",
+ *       "role": "[truncated]"
+ *     },
+ *     {
+ *       "id": "[truncated]",
+ *       "name": "[truncated]",
+ *       "email": "[truncated]",
+ *       "role": "[truncated]"
+ *     }
+ *   ],
+ *   "total": 2
+ * }
+ */
+export declare function getApiUsers(): GetApiUsersOutput;
+
+/**
+ * Input type for `GET /api/users/:id` — express module, observed in node, 41m ago
+ */
+export interface GetApiUsersIdInput {
+  id: string;
+}
+
+/**
+ * Output type for `GET /api/users/:id` — express module, observed in node, 41m ago
+ */
+export interface GetApiUsersIdOutput {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+  metadata: {
+    lastLogin: string;
+    loginCount: number;
+  };
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "params": {
+ *     "id": "1"
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "id": 1,
+ *   "name": "Alice",
+ *   "email": "alice@example.com",
+ *   "role": "admin",
+ *   "metadata": {
+ *     "lastLogin": "2026-03-10T10:00:00Z",
+ *     "loginCount": 42
+ *   }
+ * }
+ */
+export declare function getApiUsersId(input: GetApiUsersIdInput): GetApiUsersIdOutput;
+
+export interface PostApiOrdersInputItems {
+  name: string;
+  price: number;
+  quantity: number;
+}
+
+/**
+ * Input type for `POST /api/orders` — express module, observed in node, 41m ago
+ */
+export interface PostApiOrdersInput {
+  customer: string;
+  items: PostApiOrdersInputItems[];
+}
+
+/**
+ * Output type for `POST /api/orders` — express module, observed in node, 41m ago
+ */
+export interface PostApiOrdersOutput {
+  orderId: string;
+  customer: string;
+  total: number;
+  status: string;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "body": {
+ *     "customer": "Alice",
+ *     "items": [
+ *       "[truncated]",
+ *       "[truncated]"
+ *     ]
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "orderId": "ORD-1773306555867",
+ *   "customer": "Alice",
+ *   "total": 109.97,
+ *   "status": "created"
+ * }
+ */
+export declare function postApiOrders(input: PostApiOrdersInput): PostApiOrdersOutput;
+
+export interface PutApiUsersIdBody {
+  name: string;
+  email: string;
+}
+
+export interface PutApiUsersIdParams {
+  id: string;
+}
+
+/**
+ * Output type for `PUT /api/users/:id` — express module, observed in node, 41m ago
+ */
+export interface PutApiUsersIdOutput {
+  id: number;
+  name: string;
+  email: string;
+  updated: boolean;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "body": {
+ *     "name": "Alice Updated",
+ *     "email": "alice2@example.com"
+ *   },
+ *   "params": {
+ *     "id": "1"
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "id": 1,
+ *   "name": "Alice Updated",
+ *   "email": "alice2@example.com",
+ *   "updated": true
+ * }
+ */
+export declare function putApiUsersId(body: PutApiUsersIdBody, params: PutApiUsersIdParams): PutApiUsersIdOutput;
+
+/**
+ * Input type for `POST /api/cart` — express module, observed in node, 41m ago
+ */
+export interface PostApiCartInput {
+  productId: number;
+  quantity: number;
+}
+
+/**
+ * Output type for `POST /api/cart` — express module, observed in node, 41m ago
+ */
+export interface PostApiCartOutput {
+  cartId: string;
+  productId: number;
+  quantity: number;
+  added: boolean;
+}
+
+/**
+ * @example
+ * // Sample input:
+ * {
+ *   "body": {
+ *     "productId": 1,
+ *     "quantity": 3
+ *   }
+ * }
+ * // Sample output:
+ * {
+ *   "cartId": "CART-1773306558041",
+ *   "productId": 1,
+ *   "quantity": 3,
+ *   "added": true
+ * }
+ */
+export declare function postApiCart(input: PostApiCartInput): PostApiCartOutput;