mnehmos.trace.mcp 1.0.0

package/dist/patterns/errors.js

@@ -0,0 +1,185 @@
+/**
+ * Pattern Matcher Errors
+ *
+ * Error types for pattern matching and extraction operations.
+ * Each error includes a machine-readable error code for programmatic handling.
+ *
+ * @module patterns/errors
+ * @see .context/ADR-P2-1-PATTERN-MATCHER.md
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const matcher = getPattern('unknown-framework');
+ * } catch (error) {
+ *   if (error instanceof PatternNotFoundError) {
+ *     console.log(`Code: ${error.code}`); // PATTERN_NOT_FOUND
+ *     console.log(`Available: ${error.available.join(', ')}`);
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Error codes for pattern matcher errors.
+ * Use these codes for machine-readable error handling.
+ */
+export const PatternErrorCodes = {
+    /** Base registry error */
+    REGISTRY_ERROR: 'PATTERN_REGISTRY_ERROR',
+    /** Pattern matcher not found in registry */
+    NOT_FOUND: 'PATTERN_NOT_FOUND',
+    /** Pattern matcher failed validation */
+    VALIDATION_FAILED: 'PATTERN_VALIDATION_FAILED',
+    /** Pattern matching operation failed */
+    MATCH_FAILED: 'PATTERN_MATCH_FAILED',
+    /** Schema extraction from pattern failed */
+    EXTRACTION_FAILED: 'PATTERN_EXTRACTION_FAILED',
+};
+/**
+ * Base error for pattern registry operations.
+ * All pattern-related errors extend this class.
+ *
+ * @example
+ * ```typescript
+ * if (error instanceof PatternRegistryError) {
+ *   console.log(`Pattern error: ${error.code}`);
+ * }
+ * ```
+ */
+export class PatternRegistryError extends Error {
+    /** Machine-readable error code */
+    code = PatternErrorCodes.REGISTRY_ERROR;
+    constructor(message) {
+        super(message);
+        this.name = 'PatternRegistryError';
+    }
+}
+/**
+ * Thrown when a pattern matcher is not found in the registry.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   getPattern('express');
+ * } catch (e) {
+ *   if (e instanceof PatternNotFoundError) {
+ *     console.log(`'${e.framework}' not found. Try: ${e.available.join(', ')}`);
+ *   }
+ * }
+ * ```
+ */
+export class PatternNotFoundError extends PatternRegistryError {
+    framework;
+    available;
+    code = PatternErrorCodes.NOT_FOUND;
+    constructor(
+    /** The framework name that was requested */
+    framework, 
+    /** List of available pattern matcher names */
+    available) {
+        const availableList = available.length > 0 ? available.join(', ') : 'none';
+        super(`Pattern matcher '${framework}' not found. Available matchers: ${availableList}`);
+        this.framework = framework;
+        this.available = available;
+        this.name = 'PatternNotFoundError';
+    }
+}
+/**
+ * Thrown when a pattern matcher fails validation during registration.
+ * This typically indicates a malformed matcher implementation.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   registerPattern(invalidMatcher);
+ * } catch (e) {
+ *   if (e instanceof PatternValidationError) {
+ *     console.error(`Validation failed: ${e.reason}`);
+ *   }
+ * }
+ * ```
+ */
+export class PatternValidationError extends PatternRegistryError {
+    matcher;
+    reason;
+    code = PatternErrorCodes.VALIDATION_FAILED;
+    constructor(
+    /** The matcher object that failed validation */
+    matcher, 
+    /** Human-readable description of why validation failed */
+    reason) {
+        super(`Invalid pattern matcher: ${reason}`);
+        this.matcher = matcher;
+        this.reason = reason;
+        this.name = 'PatternValidationError';
+    }
+}
+/**
+ * Thrown when pattern matching fails during AST analysis.
+ * This can occur when the AST structure doesn't match expectations.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   matcher.match(node);
+ * } catch (e) {
+ *   if (e instanceof PatternMatchError) {
+ *     console.error(`Match failed in ${e.matcher}: ${e.reason}`);
+ *   }
+ * }
+ * ```
+ */
+export class PatternMatchError extends PatternRegistryError {
+    matcher;
+    nodeSummary;
+    reason;
+    code = PatternErrorCodes.MATCH_FAILED;
+    constructor(
+    /** Name of the matcher that failed */
+    matcher, 
+    /** Summary of the AST node being matched */
+    nodeSummary, 
+    /** Human-readable description of why matching failed */
+    reason) {
+        super(`Pattern match failed in '${matcher}' for ${nodeSummary}: ${reason}`);
+        this.matcher = matcher;
+        this.nodeSummary = nodeSummary;
+        this.reason = reason;
+        this.name = 'PatternMatchError';
+    }
+}
+/**
+ * Thrown when schema extraction fails from a matched pattern.
+ * This occurs when the schema location cannot be resolved.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const schema = await matcher.extract(match);
+ * } catch (e) {
+ *   if (e instanceof PatternExtractionError) {
+ *     console.error(`Cannot extract from ${e.schemaLocation.type}`);
+ *   }
+ * }
+ * ```
+ */
+export class PatternExtractionError extends PatternRegistryError {
+    match;
+    schemaLocation;
+    reason;
+    code = PatternErrorCodes.EXTRACTION_FAILED;
+    constructor(
+    /** The match result that extraction was attempted on */
+    match, 
+    /** The schema location that could not be resolved */
+    schemaLocation, 
+    /** Human-readable description of why extraction failed */
+    reason) {
+        super(`Schema extraction failed for '${match.identifier}' at ${schemaLocation.type}: ${reason}`);
+        this.match = match;
+        this.schemaLocation = schemaLocation;
+        this.reason = reason;
+        this.name = 'PatternExtractionError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/patterns/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/patterns/errors.ts"],"names":[],"mappings":"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"}

package/dist/patterns/extractors.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Schema Extractors
+ *
+ * Utilities for extracting schema nodes based on {@link SchemaLocation} specifications.
+ * These functions navigate AST structures to locate schema definitions in various
+ * positions (arguments, return types, method chains, decorators, etc.).
+ *
+ * @module patterns/extractors
+ * @see .context/ADR-P2-1-PATTERN-MATCHER.md
+ *
+ * @example
+ * ```typescript
+ * import { extractSchemaNode } from './patterns';
+ *
+ * const schemaNode = extractSchemaNode(match, { type: 'arg', index: 0 });
+ * if (schemaNode) {
+ *   // Process the schema node
+ * }
+ * ```
+ */
+import { Node } from 'ts-morph';
+import type { SchemaLocation, MatchResult } from './types.js';
+/**
+ * Extract a schema AST node from a pattern match based on location specification.
+ *
+ * This is the primary entry point for schema extraction. It dispatches to
+ * specialized extractors based on the {@link SchemaLocation} type.
+ *
+ * @param match - The pattern match result containing the matched AST node
+ * @param location - Specification of where to find the schema in the AST
+ * @returns The schema AST node, or `null` if not found at the specified location
+ *
+ * @example
+ * ```typescript
+ * // Extract first argument from a call expression
+ * const inputSchema = extractSchemaNode(match, { type: 'arg', index: 0 });
+ *
+ * // Extract from method chain like .input(schema)
+ * const chainSchema = extractSchemaNode(match, {
+ *   type: 'chain-method',
+ *   method: 'input'
+ * });
+ * ```
+ */
+export declare function extractSchemaNode(match: MatchResult, location: SchemaLocation): Node | null;
+/**
+ * Extract a positional argument from a call expression.
+ *
+ * @param node - The call expression node
+ * @param index - Zero-based index of the argument to extract
+ * @returns The argument node at the specified index, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: app.get('/users', schema, handler)
+ * const routePath = extractFromArg(callNode, 0);  // '/users'
+ * const schema = extractFromArg(callNode, 1);     // schema
+ * ```
+ */
+export declare function extractFromArg(node: Node, index: number): Node | null;
+/**
+ * Extract a named property from an options object argument.
+ *
+ * Searches through all object literal arguments to find a property
+ * with the specified name.
+ *
+ * @param node - The call expression node
+ * @param name - Name of the property to find
+ * @returns The property's initializer node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: server.tool({ schema: z.object({...}), handler })
+ * const schemaNode = extractFromNamedArg(callNode, 'schema');
+ * ```
+ */
+export declare function extractFromNamedArg(node: Node, name: string): Node | null;
+/**
+ * Extract return type annotation from an enclosing function.
+ *
+ * Walks up the AST to find the nearest function declaration,
+ * method declaration, or arrow function, then extracts its return type.
+ *
+ * @param node - A node within a function body
+ * @returns The return type node, or `null` if no explicit return type
+ *
+ * @example
+ * ```typescript
+ * // For: function getUser(): UserSchema { ... }
+ * const returnType = extractFromReturn(bodyNode);  // UserSchema
+ * ```
+ */
+export declare function extractFromReturn(node: Node): Node | null;
+/**
+ * Extract a generic type parameter at a specified index.
+ *
+ * Works with both type references (`Foo<T, U>`) and call expressions
+ * with type arguments (`foo<T>()`).
+ *
+ * @param node - A type reference or call expression node
+ * @param index - Zero-based index of the type argument
+ * @returns The type argument node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: Response<UserSchema, ErrorSchema>
+ * const successType = extractFromTypeParam(typeRef, 0);  // UserSchema
+ * const errorType = extractFromTypeParam(typeRef, 1);    // ErrorSchema
+ * ```
+ */
+export declare function extractFromTypeParam(node: Node, index: number): Node | null;
+/**
+ * Extract schema from function body or variable initializer.
+ *
+ * For functions: finds return statements and extracts the returned expression.
+ * For arrow functions: returns the expression body directly.
+ * For variable declarations: returns the initializer.
+ *
+ * @param node - A function-like node or variable declaration
+ * @returns The inferred schema node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: const schema = z.object({ name: z.string() })
+ * const schemaValue = extractFromBody(varDecl);  // z.object(...)
+ *
+ * // For: const handler = () => z.object({})
+ * const returnValue = extractFromBody(arrowFn);  // z.object({})
+ * ```
+ */
+export declare function extractFromBody(node: Node): Node | null;
+/**
+ * Extract schema from a method in a call chain.
+ *
+ * Traverses a method chain (like tRPC's fluent API) to find a specific
+ * method call and extract its first argument.
+ *
+ * @param node - The call expression representing the chain
+ * @param methodName - Name of the method to find (e.g., 'input', 'output')
+ * @returns The first argument of the method, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: t.procedure.input(userSchema).query(...)
+ * const inputSchema = extractFromChainMethod(callNode, 'input');
+ *
+ * // For: router.route().output(responseSchema).get()
+ * const outputSchema = extractFromChainMethod(callNode, 'output');
+ * ```
+ */
+export declare function extractFromChainMethod(node: Node, methodName: string): Node | null;
+/**
+ * Extract an argument from a decorator's call expression.
+ *
+ * @param node - The decorator node
+ * @param index - Zero-based index of the argument
+ * @returns The argument node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: @Body(validationSchema)
+ * const schema = extractFromDecoratorArg(decoratorNode, 0);
+ *
+ * // For: @Param('id', ParseIntPipe)
+ * const paramName = extractFromDecoratorArg(decoratorNode, 0);  // 'id'
+ * const pipe = extractFromDecoratorArg(decoratorNode, 1);       // ParseIntPipe
+ * ```
+ */
+export declare function extractFromDecoratorArg(node: Node, index: number): Node | null;
+//# sourceMappingURL=extractors.d.ts.map

package/dist/patterns/extractors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.d.ts","sourceRoot":"","sources":["../../src/patterns/extractors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,IAAI,EAAc,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,GACvB,IAAI,GAAG,IAAI,CAiCb;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAczE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAczD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAc3E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CA0BvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmClF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAQ9E"}

package/dist/patterns/extractors.js

@@ -0,0 +1,305 @@
+/**
+ * Schema Extractors
+ *
+ * Utilities for extracting schema nodes based on {@link SchemaLocation} specifications.
+ * These functions navigate AST structures to locate schema definitions in various
+ * positions (arguments, return types, method chains, decorators, etc.).
+ *
+ * @module patterns/extractors
+ * @see .context/ADR-P2-1-PATTERN-MATCHER.md
+ *
+ * @example
+ * ```typescript
+ * import { extractSchemaNode } from './patterns';
+ *
+ * const schemaNode = extractSchemaNode(match, { type: 'arg', index: 0 });
+ * if (schemaNode) {
+ *   // Process the schema node
+ * }
+ * ```
+ */
+import { Node, SyntaxKind } from 'ts-morph';
+/**
+ * Extract a schema AST node from a pattern match based on location specification.
+ *
+ * This is the primary entry point for schema extraction. It dispatches to
+ * specialized extractors based on the {@link SchemaLocation} type.
+ *
+ * @param match - The pattern match result containing the matched AST node
+ * @param location - Specification of where to find the schema in the AST
+ * @returns The schema AST node, or `null` if not found at the specified location
+ *
+ * @example
+ * ```typescript
+ * // Extract first argument from a call expression
+ * const inputSchema = extractSchemaNode(match, { type: 'arg', index: 0 });
+ *
+ * // Extract from method chain like .input(schema)
+ * const chainSchema = extractSchemaNode(match, {
+ *   type: 'chain-method',
+ *   method: 'input'
+ * });
+ * ```
+ */
+export function extractSchemaNode(match, location) {
+    const { node, captures } = match;
+    switch (location.type) {
+        case 'arg':
+            return extractFromArg(node, location.index);
+        case 'arg-named':
+            return extractFromNamedArg(node, location.name);
+        case 'return':
+            return extractFromReturn(node);
+        case 'type-param':
+            return extractFromTypeParam(node, location.index);
+        case 'body':
+            return extractFromBody(node);
+        case 'chain-method':
+            // Check if already captured during matching
+            const capturedNode = captures[`${location.method}SchemaNode`];
+            if (capturedNode && Node.isNode(capturedNode)) {
+                return capturedNode;
+            }
+            return extractFromChainMethod(node, location.method);
+        case 'decorator-arg':
+            return extractFromDecoratorArg(node, location.index);
+        default:
+            return null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Individual Extractor Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Extract a positional argument from a call expression.
+ *
+ * @param node - The call expression node
+ * @param index - Zero-based index of the argument to extract
+ * @returns The argument node at the specified index, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: app.get('/users', schema, handler)
+ * const routePath = extractFromArg(callNode, 0);  // '/users'
+ * const schema = extractFromArg(callNode, 1);     // schema
+ * ```
+ */
+export function extractFromArg(node, index) {
+    if (!Node.isCallExpression(node))
+        return null;
+    const args = node.getArguments();
+    return args[index] ?? null;
+}
+/**
+ * Extract a named property from an options object argument.
+ *
+ * Searches through all object literal arguments to find a property
+ * with the specified name.
+ *
+ * @param node - The call expression node
+ * @param name - Name of the property to find
+ * @returns The property's initializer node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: server.tool({ schema: z.object({...}), handler })
+ * const schemaNode = extractFromNamedArg(callNode, 'schema');
+ * ```
+ */
+export function extractFromNamedArg(node, name) {
+    if (!Node.isCallExpression(node))
+        return null;
+    const args = node.getArguments();
+    for (const arg of args) {
+        if (Node.isObjectLiteralExpression(arg)) {
+            for (const prop of arg.getProperties()) {
+                if (Node.isPropertyAssignment(prop) && prop.getName() === name) {
+                    return prop.getInitializer() ?? null;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Extract return type annotation from an enclosing function.
+ *
+ * Walks up the AST to find the nearest function declaration,
+ * method declaration, or arrow function, then extracts its return type.
+ *
+ * @param node - A node within a function body
+ * @returns The return type node, or `null` if no explicit return type
+ *
+ * @example
+ * ```typescript
+ * // For: function getUser(): UserSchema { ... }
+ * const returnType = extractFromReturn(bodyNode);  // UserSchema
+ * ```
+ */
+export function extractFromReturn(node) {
+    // Walk up to find function declaration
+    const func = node.getFirstAncestorByKind(SyntaxKind.FunctionDeclaration)
+        ?? node.getFirstAncestorByKind(SyntaxKind.MethodDeclaration)
+        ?? node.getFirstAncestorByKind(SyntaxKind.ArrowFunction);
+    if (!func)
+        return null;
+    // Check if the node has getReturnTypeNode method
+    if ('getReturnTypeNode' in func && typeof func.getReturnTypeNode === 'function') {
+        return func.getReturnTypeNode() ?? null;
+    }
+    return null;
+}
+/**
+ * Extract a generic type parameter at a specified index.
+ *
+ * Works with both type references (`Foo<T, U>`) and call expressions
+ * with type arguments (`foo<T>()`).
+ *
+ * @param node - A type reference or call expression node
+ * @param index - Zero-based index of the type argument
+ * @returns The type argument node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: Response<UserSchema, ErrorSchema>
+ * const successType = extractFromTypeParam(typeRef, 0);  // UserSchema
+ * const errorType = extractFromTypeParam(typeRef, 1);    // ErrorSchema
+ * ```
+ */
+export function extractFromTypeParam(node, index) {
+    // Handle type references with type arguments
+    if (Node.isTypeReference(node)) {
+        const typeArgs = node.getTypeArguments();
+        return typeArgs[index] ?? null;
+    }
+    // Handle call expressions with type arguments
+    if (Node.isCallExpression(node)) {
+        const typeArgs = node.getTypeArguments();
+        return typeArgs[index] ?? null;
+    }
+    return null;
+}
+/**
+ * Extract schema from function body or variable initializer.
+ *
+ * For functions: finds return statements and extracts the returned expression.
+ * For arrow functions: returns the expression body directly.
+ * For variable declarations: returns the initializer.
+ *
+ * @param node - A function-like node or variable declaration
+ * @returns The inferred schema node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: const schema = z.object({ name: z.string() })
+ * const schemaValue = extractFromBody(varDecl);  // z.object(...)
+ *
+ * // For: const handler = () => z.object({})
+ * const returnValue = extractFromBody(arrowFn);  // z.object({})
+ * ```
+ */
+export function extractFromBody(node) {
+    // If node is a function-like, get its body
+    let body;
+    if (Node.isFunctionDeclaration(node) || Node.isMethodDeclaration(node)) {
+        body = node.getBody();
+    }
+    else if (Node.isArrowFunction(node)) {
+        body = node.getBody();
+    }
+    else if (Node.isVariableDeclaration(node)) {
+        // For variable declarations like `const schema = z.object(...)`
+        const initializer = node.getInitializer();
+        return initializer ?? null;
+    }
+    if (!body)
+        return node;
+    // If body is a block, find return statement
+    if (Node.isBlock(body)) {
+        const returnStmt = body.getFirstDescendantByKind(SyntaxKind.ReturnStatement);
+        if (returnStmt) {
+            return returnStmt.getExpression() ?? null;
+        }
+    }
+    // If body is an expression (arrow function), return it directly
+    return body;
+}
+/**
+ * Extract schema from a method in a call chain.
+ *
+ * Traverses a method chain (like tRPC's fluent API) to find a specific
+ * method call and extract its first argument.
+ *
+ * @param node - The call expression representing the chain
+ * @param methodName - Name of the method to find (e.g., 'input', 'output')
+ * @returns The first argument of the method, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: t.procedure.input(userSchema).query(...)
+ * const inputSchema = extractFromChainMethod(callNode, 'input');
+ *
+ * // For: router.route().output(responseSchema).get()
+ * const outputSchema = extractFromChainMethod(callNode, 'output');
+ * ```
+ */
+export function extractFromChainMethod(node, methodName) {
+    if (!Node.isCallExpression(node))
+        return null;
+    // Walk up the call chain to find the method
+    let current = node;
+    while (current) {
+        if (Node.isCallExpression(current)) {
+            const expr = current.getExpression();
+            if (Node.isPropertyAccessExpression(expr)) {
+                const name = expr.getName();
+                if (name === methodName) {
+                    // Found the method, return its first argument
+                    const args = current.getArguments();
+                    return args[0] ?? null;
+                }
+                // Move to the receiver
+                current = expr.getExpression();
+                continue;
+            }
+        }
+        break;
+    }
+    // Also check children (for cases where node is the start of chain)
+    const descendants = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const desc of descendants) {
+        const expr = desc.getExpression();
+        if (Node.isPropertyAccessExpression(expr) && expr.getName() === methodName) {
+            const args = desc.getArguments();
+            return args[0] ?? null;
+        }
+    }
+    return null;
+}
+/**
+ * Extract an argument from a decorator's call expression.
+ *
+ * @param node - The decorator node
+ * @param index - Zero-based index of the argument
+ * @returns The argument node, or `null` if not found
+ *
+ * @example
+ * ```typescript
+ * // For: @Body(validationSchema)
+ * const schema = extractFromDecoratorArg(decoratorNode, 0);
+ *
+ * // For: @Param('id', ParseIntPipe)
+ * const paramName = extractFromDecoratorArg(decoratorNode, 0);  // 'id'
+ * const pipe = extractFromDecoratorArg(decoratorNode, 1);       // ParseIntPipe
+ * ```
+ */
+export function extractFromDecoratorArg(node, index) {
+    if (!Node.isDecorator(node))
+        return null;
+    const callExpr = node.getCallExpression();
+    if (!callExpr)
+        return null;
+    const args = callExpr.getArguments();
+    return args[index] ?? null;
+}
+//# sourceMappingURL=extractors.js.map

package/dist/patterns/extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.js","sourceRoot":"","sources":["../../src/patterns/extractors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAkB,EAClB,QAAwB;IAExB,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAEjC,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,KAAK;YACR,OAAO,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QAE9C,KAAK,WAAW;YACd,OAAO,mBAAmB,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAElD,KAAK,QAAQ;YACX,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAEjC,KAAK,YAAY;YACf,OAAO,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QAEpD,KAAK,MAAM;YACT,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;QAE/B,KAAK,cAAc;YACjB,4CAA4C;YAC5C,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,QAAQ,CAAC,MAAM,YAAY,CAAC,CAAC;YAC9D,IAAI,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC9C,OAAO,YAAY,CAAC;YACtB,CAAC;YACD,OAAO,sBAAsB,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEvD,KAAK,eAAe;YAClB,OAAO,uBAAuB,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QAEvD;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,iCAAiC;AACjC,gFAAgF;AAEhF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,IAAU,EAAE,KAAa;IACtD,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAU,EAAE,IAAY;IAC1D,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;IAEjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,aAAa,EAAE,EAAE,CAAC;gBACvC,IAAI,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;oBAC/D,OAAO,IAAI,CAAC,cAAc,EAAE,IAAI,IAAI,CAAC;gBACvC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAU;IAC1C,uCAAuC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC,mBAAmB,CAAC;WACnE,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC,iBAAiB,CAAC;WACzD,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAE3D,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,iDAAiD;IACjD,IAAI,mBAAmB,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,iBAAiB,KAAK,UAAU,EAAE,CAAC;QAChF,OAAO,IAAI,CAAC,iBAAiB,EAAE,IAAI,IAAI,CAAC;IAC1C,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAU,EAAE,KAAa;IAC5D,6CAA6C;IAC7C,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACjC,CAAC;IAED,8CAA8C;IAC9C,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACjC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAU;IACxC,2CAA2C;IAC3C,IAAI,IAAsB,CAAC;IAE3B,IAAI,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QACvE,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;SAAM,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;SAAM,IAAI,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,gEAAgE;QAChE,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,WAAW,IAAI,IAAI,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,4CAA4C;IAC5C,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,IAAI,CAAC,wBAAwB,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;QAC7E,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,aAAa,EAAE,IAAI,IAAI,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAU,EAAE,UAAkB;IACnE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,4CAA4C;IAC5C,IAAI,OAAO,GAAS,IAAI,CAAC;IAEzB,OAAO,OAAO,EAAE,CAAC;QACf,IAAI,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;YACrC,IAAI,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC5B,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;oBACxB,8CAA8C;oBAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;oBACpC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;gBACzB,CAAC;gBACD,uBAAuB;gBACvB,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;gBAC/B,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM;IACR,CAAC;IAED,mEAAmE;IACnE,MAAM,WAAW,GAAG,IAAI,CAAC,oBAAoB,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;IACzE,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;YAC3E,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAU,EAAE,KAAa;IAC/D,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC1C,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE3B,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;AAC7B,CAAC"}