mnehmos.trace.mcp 1.0.0

package/dist/adapters/trpc/extractor.js

@@ -0,0 +1,708 @@
+/**
+ * 🔧 tRPC Router/Procedure Extractor
+ *
+ * AST-based extraction of tRPC router definitions and Zod schemas.
+ * This module provides utilities to:
+ * - Parse TypeScript files containing tRPC routers
+ * - Extract procedure definitions (query, mutation, subscription)
+ * - Convert Zod schemas to NormalizedSchema format
+ *
+ * Uses ts-morph for AST analysis, supporting patterns like:
+ * - `t.router({ ... })` - Standard tRPC v10+ pattern
+ * - `createTRPCRouter({ ... })` - Next.js/T3 pattern
+ * - Nested routers via object composition
+ *
+ * @module adapters/trpc/extractor
+ */
+import { Project, Node, } from 'ts-morph';
+// ============================================================================
+// Project Creation
+// ============================================================================
+/**
+ * Create a new ts-morph Project instance for AST analysis.
+ *
+ * Configures the project without tsconfig to allow standalone
+ * file analysis without project-wide compilation context.
+ *
+ * @returns A new ts-morph Project instance
+ *
+ * @example
+ * ```typescript
+ * const project = createProject();
+ * const sourceFile = project.addSourceFileAtPath('./router.ts');
+ * const procedures = extractProcedures(sourceFile);
+ * ```
+ */
+export function createProject() {
+    return new Project({
+        tsConfigFilePath: undefined,
+        skipAddingFilesFromTsConfig: true,
+    });
+}
+// ============================================================================
+// Procedure Extraction
+// ============================================================================
+/**
+ * Extract all procedures from a tRPC router source file.
+ *
+ * Scans the file for router definitions and extracts all procedure
+ * definitions, including those in nested routers. Each procedure
+ * is returned with its full path, type, and schema nodes.
+ *
+ * Supported patterns:
+ * - `t.router({ user: t.procedure.query(...) })`
+ * - `createTRPCRouter({ users: userRouter })`
+ * - `createRouter({ nested: { deep: procedure } })`
+ *
+ * @param sourceFile - The ts-morph SourceFile to analyze
+ * @returns Array of ProcedureInfo objects for all found procedures
+ *
+ * @example
+ * ```typescript
+ * const project = createProject();
+ * const file = project.addSourceFileAtPath('./server/routers/index.ts');
+ * const procedures = extractProcedures(file);
+ *
+ * for (const proc of procedures) {
+ *   console.log(`${proc.path.join('.')} - ${proc.type}`);
+ *   // Output: "users.getById - query"
+ * }
+ * ```
+ */
+export function extractProcedures(sourceFile) {
+    const procedures = [];
+    const filePath = sourceFile.getFilePath();
+    // Find all router calls and extract procedures
+    sourceFile.forEachDescendant((node) => {
+        if (Node.isCallExpression(node) && isRouterCall(node)) {
+            const procs = parseRouterObject(node, [], filePath);
+            procedures.push(...procs);
+        }
+    });
+    return procedures;
+}
+/**
+ * Check if a call expression is a tRPC router call.
+ *
+ * Matches patterns like:
+ * - `t.router(...)` - Method call on object
+ * - `trpc.router(...)` - Namespaced call
+ * - `createRouter(...)` - Function call
+ * - `createTRPCRouter(...)` - T3/Next.js pattern
+ *
+ * @param node - The AST node to check
+ * @returns True if the node is a router call expression
+ *
+ * @example
+ * ```typescript
+ * sourceFile.forEachDescendant((node) => {
+ *   if (Node.isCallExpression(node) && isRouterCall(node)) {
+ *     // Process router definition
+ *   }
+ * });
+ * ```
+ */
+export function isRouterCall(node) {
+    if (!Node.isCallExpression(node))
+        return false;
+    const expr = node.getExpression();
+    // Match patterns like: t.router(), trpc.router(), createRouter(), createTRPCRouter()
+    if (Node.isPropertyAccessExpression(expr)) {
+        return expr.getName() === 'router';
+    }
+    // Match direct function calls
+    if (Node.isIdentifier(expr)) {
+        const name = expr.getText();
+        return name === 'createRouter' || name === 'createTRPCRouter';
+    }
+    return false;
+}
+/**
+ * Check if a node is a tRPC procedure chain.
+ *
+ * Procedure chains are method chains that terminate in `.query()`,
+ * `.mutation()`, or `.subscription()`. This function walks up the
+ * chain to find these terminal methods.
+ *
+ * @param node - The AST node to check
+ * @returns True if the node is a procedure chain
+ *
+ * @example
+ * ```typescript
+ * // These would return true:
+ * // t.procedure.input(z.string()).query(...)
+ * // t.procedure.mutation(...)
+ * // publicProcedure.subscription(...)
+ * ```
+ */
+export function isProcedureChain(node) {
+    if (!node)
+        return false;
+    // Walk up the call chain to find terminal methods
+    let current = node;
+    while (Node.isCallExpression(current)) {
+        const expr = current.getExpression();
+        if (Node.isPropertyAccessExpression(expr)) {
+            const methodName = expr.getName();
+            if (methodName === 'query' || methodName === 'mutation' || methodName === 'subscription') {
+                return true;
+            }
+        }
+        // Move to inner expression to keep checking
+        if (Node.isPropertyAccessExpression(expr)) {
+            const inner = expr.getExpression();
+            if (Node.isCallExpression(inner)) {
+                current = inner;
+                continue;
+            }
+        }
+        break;
+    }
+    return false;
+}
+/**
+ * Parse a router object literal and extract all procedures.
+ *
+ * Recursively processes router definitions, handling:
+ * - Direct procedure definitions
+ * - Nested router references
+ * - Inline nested routers
+ *
+ * @param routerCall - The router call expression node
+ * @param currentPath - Current path prefix for nested routers
+ * @param filePath - Path to the source file
+ * @returns Array of ProcedureInfo for all found procedures
+ */
+export function parseRouterObject(routerCall, currentPath, filePath) {
+    const procedures = [];
+    const args = routerCall.getArguments();
+    if (args.length === 0)
+        return procedures;
+    const routerObj = args[0];
+    if (!Node.isObjectLiteralExpression(routerObj))
+        return procedures;
+    for (const prop of routerObj.getProperties()) {
+        if (!Node.isPropertyAssignment(prop))
+            continue;
+        const propName = prop.getName();
+        const init = prop.getInitializer();
+        if (!init)
+            continue;
+        // Check if it's a nested router
+        if (isNestedRouter(init)) {
+            // Recursively parse nested router
+            const nestedCall = extractRouterCall(init);
+            if (nestedCall) {
+                const nested = parseRouterObject(nestedCall, [...currentPath, propName], filePath);
+                procedures.push(...nested);
+            }
+        }
+        else if (isProcedureChain(init)) {
+            // Parse procedure definition
+            const procInfo = parseProcedureChain(init, [...currentPath, propName], filePath);
+            if (procInfo) {
+                procedures.push(procInfo);
+            }
+        }
+    }
+    return procedures;
+}
+/**
+ * Check if a node represents a nested router.
+ *
+ * @param node - The AST node to check
+ * @returns True if the node is a nested router definition or reference
+ */
+function isNestedRouter(node) {
+    // Direct router call
+    if (Node.isCallExpression(node) && isRouterCall(node)) {
+        return true;
+    }
+    // Identifier referencing a router (e.g., userRouter)
+    if (Node.isIdentifier(node)) {
+        const name = node.getText();
+        return name.endsWith('Router') || name.endsWith('router');
+    }
+    return false;
+}
+/**
+ * Extract the router call from a node.
+ *
+ * Handles both direct router calls and identifier references
+ * to router variables.
+ *
+ * @param node - The AST node to extract from
+ * @returns The router CallExpression, or null if not found
+ */
+function extractRouterCall(node) {
+    if (Node.isCallExpression(node) && isRouterCall(node)) {
+        return node;
+    }
+    // For identifier references, we need to follow the variable declaration
+    if (Node.isIdentifier(node)) {
+        const symbol = node.getSymbol();
+        if (symbol) {
+            const declarations = symbol.getDeclarations();
+            for (const decl of declarations) {
+                if (Node.isVariableDeclaration(decl)) {
+                    const init = decl.getInitializer();
+                    if (init && Node.isCallExpression(init) && isRouterCall(init)) {
+                        return init;
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse a procedure method chain to extract input/output schemas.
+ *
+ * Walks the method chain (`.input().output().query()`) and extracts:
+ * - Input schema from `.input(zodSchema)`
+ * - Output schema from `.output(zodSchema)`
+ * - Procedure type from terminal method (`.query()`, `.mutation()`, `.subscription()`)
+ *
+ * @param node - The procedure chain call expression
+ * @param path - Full path to this procedure
+ * @param filePath - Path to the source file
+ * @returns ProcedureInfo or null if parsing fails
+ *
+ * @example
+ * ```typescript
+ * // For: t.procedure.input(z.object({ id: z.string() })).query(...)
+ * // Returns: { path: ['getById'], type: 'query', inputSchema: <Node>, ... }
+ * ```
+ */
+export function parseProcedureChain(node, path, filePath) {
+    if (!Node.isCallExpression(node))
+        return null;
+    const location = {
+        file: filePath,
+        line: node.getStartLineNumber(),
+    };
+    let inputSchema;
+    let outputSchema;
+    let procedureType = 'query';
+    // Walk up the method chain to collect .input(), .output(), etc.
+    let current = node;
+    while (current && Node.isCallExpression(current)) {
+        const expr = current.getExpression();
+        if (Node.isPropertyAccessExpression(expr)) {
+            const methodName = expr.getName();
+            const args = current.getArguments();
+            switch (methodName) {
+                case 'input':
+                    if (args.length > 0)
+                        inputSchema = args[0];
+                    break;
+                case 'output':
+                    if (args.length > 0)
+                        outputSchema = args[0];
+                    break;
+                case 'query':
+                    procedureType = 'query';
+                    break;
+                case 'mutation':
+                    procedureType = 'mutation';
+                    break;
+                case 'subscription':
+                    procedureType = 'subscription';
+                    break;
+            }
+            // Move up the chain
+            const inner = expr.getExpression();
+            if (Node.isCallExpression(inner)) {
+                current = inner;
+            }
+            else {
+                break;
+            }
+        }
+        else {
+            break;
+        }
+    }
+    return {
+        path,
+        type: procedureType,
+        inputSchema,
+        outputSchema,
+        location,
+    };
+}
+// ============================================================================
+// Zod Schema Conversion
+// ============================================================================
+/**
+ * Convert a Zod schema AST node to NormalizedSchema.
+ *
+ * Parses Zod schema definitions and converts them to the framework's
+ * NormalizedSchema format. Supports common Zod types:
+ * - Primitives: `z.string()`, `z.number()`, `z.boolean()`
+ * - Objects: `z.object({ ... })`
+ * - Arrays: `z.array(...)`
+ * - Unions: `z.union([...])`, `z.enum([...])`
+ * - Modifiers: `.optional()`, `.nullable()`, `.default()`
+ * - Constraints: `.min()`, `.max()`, `.email()`, etc.
+ *
+ * @param node - The AST node containing the Zod schema
+ * @param ref - The SchemaRef for source tracking
+ * @param location - Source location for error reporting
+ * @param name - Optional schema name
+ * @returns The converted NormalizedSchema
+ *
+ * @example
+ * ```typescript
+ * const schema = zodToNormalizedSchema(
+ *   inputSchemaNode,
+ *   { source: 'trpc', id: 'trpc:users.create@./router.ts' },
+ *   { file: './router.ts', line: 42 },
+ *   'users.create.input'
+ * );
+ * ```
+ */
+export function zodToNormalizedSchema(node, ref, location, name) {
+    const properties = {};
+    const required = [];
+    // Parse z.object({...})
+    if (Node.isCallExpression(node)) {
+        const expr = node.getExpression();
+        const exprText = expr.getText();
+        if (exprText === 'z.object' || exprText.endsWith('.object')) {
+            const args = node.getArguments();
+            if (args.length > 0 && Node.isObjectLiteralExpression(args[0])) {
+                parseZodObjectProperties(args[0], properties, required);
+            }
+        }
+    }
+    // Handle identifier references to named schemas
+    if (Node.isIdentifier(node)) {
+        const schema = resolveZodSchemaReference(node);
+        if (schema) {
+            return zodToNormalizedSchema(schema, ref, location, name);
+        }
+    }
+    return {
+        name: name || ref.id.split('@')[0].split(':')[1],
+        properties,
+        required,
+        source: ref,
+        location,
+    };
+}
+/**
+ * Resolve a Zod schema reference (identifier) to its definition.
+ *
+ * Follows variable declarations to find the actual schema definition.
+ * Used for patterns like `const UserSchema = z.object({ ... })`.
+ *
+ * @param node - The identifier node to resolve
+ * @returns The resolved schema AST node, or null if not found
+ */
+function resolveZodSchemaReference(node) {
+    if (!Node.isIdentifier(node))
+        return null;
+    const symbol = node.getSymbol();
+    if (!symbol)
+        return null;
+    const declarations = symbol.getDeclarations();
+    for (const decl of declarations) {
+        if (Node.isVariableDeclaration(decl)) {
+            const init = decl.getInitializer();
+            if (init)
+                return init;
+        }
+    }
+    return null;
+}
+/**
+ * Parse properties from a `z.object({ ... })` call.
+ *
+ * Extracts each property definition and determines which are required.
+ * Properties with `.optional()`, `.nullish()`, or `.default()` are
+ * considered optional.
+ *
+ * @param obj - The object literal expression node
+ * @param properties - Map to populate with property definitions
+ * @param required - Array to populate with required property names
+ */
+function parseZodObjectProperties(obj, properties, required) {
+    for (const prop of obj.getProperties()) {
+        if (!Node.isPropertyAssignment(prop))
+            continue;
+        const propName = prop.getName();
+        const init = prop.getInitializer();
+        if (!init)
+            continue;
+        const propDef = parseZodTypeToPropDef(init);
+        properties[propName] = propDef;
+        const initText = init.getText();
+        // Check if not optional and not with default
+        if (!initText.includes('.optional()') &&
+            !initText.includes('.nullish()') &&
+            !initText.includes('.default(')) {
+            required.push(propName);
+        }
+    }
+}
+/**
+ * Parse a Zod type expression to PropertyDef.
+ *
+ * Converts a single property's Zod schema to PropertyDef format,
+ * extracting type, optionality, nullability, and constraints.
+ *
+ * @param node - The Zod type expression node
+ * @returns The converted PropertyDef
+ */
+function parseZodTypeToPropDef(node) {
+    const text = node.getText();
+    const type = parseZodTypeToNormalized(node);
+    const constraints = extractZodConstraints(text);
+    const isOptional = text.includes('.optional()') || text.includes('.nullish()') || text.includes('.default(');
+    const isNullable = text.includes('.nullable()') || text.includes('.nullish()');
+    return {
+        type,
+        optional: isOptional,
+        nullable: isNullable,
+        readonly: false,
+        deprecated: false,
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
+    };
+}
+/**
+ * Parse a Zod type to NormalizedType.
+ *
+ * Recursively converts Zod types to the framework's NormalizedType format.
+ * Handles nested types (arrays, objects, unions) and method chains.
+ *
+ * Supported Zod types:
+ * - `z.string()` → `{ kind: 'primitive', value: 'string' }`
+ * - `z.number()` → `{ kind: 'primitive', value: 'number' }`
+ * - `z.boolean()` → `{ kind: 'primitive', value: 'boolean' }`
+ * - `z.array(T)` → `{ kind: 'array', element: T }`
+ * - `z.object({})` → `{ kind: 'object', schema: {...} }`
+ * - `z.enum([])` → `{ kind: 'union', variants: [...] }`
+ * - `z.literal(v)` → `{ kind: 'literal', value: v }`
+ *
+ * @param node - The Zod type AST node
+ * @returns The converted NormalizedType
+ */
+function parseZodTypeToNormalized(node) {
+    const text = node.getText();
+    const trimmedText = text.trim();
+    // First, resolve identifier references
+    if (Node.isIdentifier(node)) {
+        const resolved = resolveZodSchemaReference(node);
+        if (resolved) {
+            return parseZodTypeToNormalized(resolved);
+        }
+        return { kind: 'ref', name: node.getText() };
+    }
+    // Handle chained methods (e.g., z.string().optional())
+    // Must check BEFORE primitive types to unwrap the chain
+    if (Node.isCallExpression(node)) {
+        const expr = node.getExpression();
+        if (Node.isPropertyAccessExpression(expr)) {
+            const methodName = expr.getName();
+            // Skip over .optional(), .nullable(), .default(), etc. and parse inner
+            if (['optional', 'nullable', 'nullish', 'default', 'describe',
+                'min', 'max', 'int', 'positive', 'email', 'uuid', 'url'].includes(methodName)) {
+                const inner = expr.getExpression();
+                return parseZodTypeToNormalized(inner);
+            }
+        }
+    }
+    // z.string()
+    if (trimmedText.startsWith('z.string()') || trimmedText.startsWith('z.string(')) {
+        return { kind: 'primitive', value: 'string' };
+    }
+    // z.number()
+    if (trimmedText.startsWith('z.number()') || trimmedText.startsWith('z.number(')) {
+        return { kind: 'primitive', value: 'number' };
+    }
+    // z.boolean()
+    if (trimmedText.startsWith('z.boolean()') || trimmedText.startsWith('z.boolean(')) {
+        return { kind: 'primitive', value: 'boolean' };
+    }
+    // z.date()
+    if (trimmedText.startsWith('z.date()') || trimmedText.startsWith('z.date(')) {
+        return { kind: 'primitive', value: 'string' }; // Date serialized as string
+    }
+    // z.enum([...])
+    if (trimmedText.startsWith('z.enum(')) {
+        const enumMatch = text.match(/z\.enum\(\[(.*?)\]\)/s);
+        if (enumMatch) {
+            const values = enumMatch[1]
+                .split(',')
+                .map(v => v.trim().replace(/['"]/g, ''))
+                .filter(v => v.length > 0);
+            const variants = values.map(v => ({
+                kind: 'literal',
+                value: v,
+            }));
+            return { kind: 'union', variants };
+        }
+    }
+    // z.array(...)
+    if (trimmedText.startsWith('z.array(')) {
+        if (Node.isCallExpression(node)) {
+            const args = node.getArguments();
+            if (args.length > 0) {
+                const elementType = parseZodTypeToNormalized(args[0]);
+                return { kind: 'array', element: elementType };
+            }
+        }
+        return { kind: 'array', element: { kind: 'unknown' } };
+    }
+    // z.object(...) - check multiple patterns
+    if (trimmedText.startsWith('z.object(') || trimmedText.startsWith('z.object({')) {
+        if (Node.isCallExpression(node)) {
+            const args = node.getArguments();
+            if (args.length > 0 && Node.isObjectLiteralExpression(args[0])) {
+                const properties = {};
+                const required = [];
+                parseZodObjectProperties(args[0], properties, required);
+                return {
+                    kind: 'object',
+                    schema: {
+                        properties,
+                        required,
+                        source: { source: 'trpc', id: 'inline' },
+                    },
+                };
+            }
+        }
+        return { kind: 'object', schema: { properties: {}, required: [], source: { source: 'trpc', id: 'inline' } } };
+    }
+    // z.literal(...)
+    if (trimmedText.startsWith('z.literal(')) {
+        const match = text.match(/z\.literal\(['"](.+?)['"]\)/);
+        if (match) {
+            return { kind: 'literal', value: match[1] };
+        }
+        const numMatch = text.match(/z\.literal\((\d+)\)/);
+        if (numMatch) {
+            return { kind: 'literal', value: parseInt(numMatch[1]) };
+        }
+        const boolMatch = text.match(/z\.literal\((true|false)\)/);
+        if (boolMatch) {
+            return { kind: 'literal', value: boolMatch[1] === 'true' };
+        }
+    }
+    // z.union([...])
+    if (trimmedText.startsWith('z.union(')) {
+        if (Node.isCallExpression(node)) {
+            const args = node.getArguments();
+            if (args.length > 0 && Node.isArrayLiteralExpression(args[0])) {
+                const variants = args[0].getElements().map(el => parseZodTypeToNormalized(el));
+                return { kind: 'union', variants };
+            }
+        }
+    }
+    // Fallback: Check if this is a CallExpression that looks like z.X pattern
+    if (Node.isCallExpression(node)) {
+        const expr = node.getExpression();
+        if (Node.isPropertyAccessExpression(expr)) {
+            const objExpr = expr.getExpression();
+            if (Node.isIdentifier(objExpr) && objExpr.getText() === 'z') {
+                const methodName = expr.getName();
+                if (methodName === 'object') {
+                    const args = node.getArguments();
+                    if (args.length > 0 && Node.isObjectLiteralExpression(args[0])) {
+                        const properties = {};
+                        const required = [];
+                        parseZodObjectProperties(args[0], properties, required);
+                        return {
+                            kind: 'object',
+                            schema: {
+                                properties,
+                                required,
+                                source: { source: 'trpc', id: 'inline' },
+                            },
+                        };
+                    }
+                }
+            }
+        }
+    }
+    return { kind: 'unknown' };
+}
+/**
+ * Extract validation constraints from a Zod type chain.
+ *
+ * Parses the Zod method chain text to extract constraints like:
+ * - String: `.min(n)`, `.max(n)`, `.email()`, `.uuid()`, `.url()`
+ * - Number: `.min(n)`, `.max(n)`, `.int()`, `.positive()`
+ *
+ * @param text - The Zod type chain as text
+ * @returns Extracted constraints object
+ *
+ * @example
+ * ```typescript
+ * extractZodConstraints('z.string().min(1).max(100).email()')
+ * // { minLength: 1, maxLength: 100, format: 'email' }
+ * ```
+ */
+function extractZodConstraints(text) {
+    const constraints = {};
+    // String constraints
+    const minLengthMatch = text.match(/\.min\((\d+)\)/);
+    const maxLengthMatch = text.match(/\.max\((\d+)\)/);
+    // For strings
+    if (text.includes('z.string()')) {
+        if (minLengthMatch)
+            constraints.minLength = parseInt(minLengthMatch[1]);
+        if (maxLengthMatch)
+            constraints.maxLength = parseInt(maxLengthMatch[1]);
+        // Format constraints
+        if (text.includes('.email()'))
+            constraints.format = 'email';
+        if (text.includes('.uuid()'))
+            constraints.format = 'uuid';
+        if (text.includes('.url()'))
+            constraints.format = 'url';
+    }
+    // Number constraints
+    if (text.includes('z.number()')) {
+        if (minLengthMatch)
+            constraints.minimum = parseInt(minLengthMatch[1]);
+        if (maxLengthMatch)
+            constraints.maximum = parseInt(maxLengthMatch[1]);
+    }
+    return constraints;
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Create an empty NormalizedSchema.
+ *
+ * Used for procedures without explicit input or output schemas.
+ * Returns a valid schema with empty properties.
+ *
+ * @param ref - The SchemaRef for source tracking
+ * @param location - Source location for error reporting
+ * @param name - Optional schema name
+ * @returns An empty NormalizedSchema
+ *
+ * @example
+ * ```typescript
+ * // For a procedure with no .input() call
+ * const emptyInput = createEmptySchema(
+ *   ref,
+ *   { file: './router.ts', line: 10 },
+ *   'users.list.input'
+ * );
+ * ```
+ */
+export function createEmptySchema(ref, location, name) {
+    return {
+        name: name || ref.id.split('@')[0].split(':')[1],
+        properties: {},
+        required: [],
+        source: ref,
+        location,
+    };
+}
+//# sourceMappingURL=extractor.js.map