mnehmos.trace.mcp 1.0.0

package/dist/patterns/rest/response-inference.js

@@ -0,0 +1,218 @@
+/**
+ * Response Inference
+ *
+ * Infers response schema from handler function implementations.
+ *
+ * @module patterns/rest/response-inference
+ * @see .context/ADR-P2-2-REST-DETECTION.md
+ */
+import { Node } from 'ts-morph';
+/* ═══════════════════════════════════════════════════════════════════════════
+ * 🔍 Public API
+ * ═══════════════════════════════════════════════════════════════════════════ */
+/**
+ * Infer the response schema from a handler function.
+ *
+ * Uses multiple strategies:
+ * 1. Explicit return type annotation
+ * 2. Generic type parameter on res.json<T>()
+ * 3. Analysis of res.json() argument structure
+ *
+ * @param handler - The handler function AST node
+ * @returns Response inference result with method and optional schema node
+ *
+ * @example
+ * ```typescript
+ * // Handler: (req, res) => res.json<ProfileResponse>({ id: '123', name: 'John' })
+ * const inference = inferResponseSchema(handler);
+ * // { method: 'generic-param', node: <ProfileResponse node> }
+ * ```
+ */
+export function inferResponseSchema(handler) {
+    if (!handler) {
+        return { method: 'unknown' };
+    }
+    // Check for explicit return type annotation
+    const returnType = getExplicitReturnType(handler);
+    if (returnType) {
+        return { method: 'explicit-return', node: returnType };
+    }
+    // Look for res.json<T>() generic parameter
+    const genericParam = findResJsonGenericParam(handler);
+    if (genericParam) {
+        return { method: 'generic-param', node: genericParam };
+    }
+    // Analyze body of res.json() calls
+    const jsonArg = findResJsonArgument(handler);
+    if (jsonArg) {
+        return { method: 'body-analysis', node: jsonArg };
+    }
+    return { method: 'unknown' };
+}
+/**
+ * Detect multiple response schemas by status code.
+ *
+ * @param handler - The handler function AST node
+ * @returns Map of status codes to response schema nodes
+ *
+ * @example
+ * ```typescript
+ * // Handler with res.status(200).json(ok) and res.status(400).json(error)
+ * const responses = detectMultipleResponses(handler);
+ * // Map { 200 => <ok node>, 400 => <error node> }
+ * ```
+ */
+export function detectMultipleResponses(handler) {
+    const responses = new Map();
+    if (!handler) {
+        return responses;
+    }
+    // Find all call expressions in the handler
+    handler.forEachDescendant(node => {
+        if (!Node.isCallExpression(node))
+            return;
+        // Check for res.status(code).json(body) or res.json(body)
+        const statusAndBody = extractStatusAndBody(node);
+        if (statusAndBody) {
+            responses.set(statusAndBody.status, statusAndBody.body);
+        }
+    });
+    return responses;
+}
+/**
+ * Get explicit return type annotation from a function
+ */
+function getExplicitReturnType(handler) {
+    if (Node.isFunctionDeclaration(handler) ||
+        Node.isFunctionExpression(handler) ||
+        Node.isArrowFunction(handler) ||
+        Node.isMethodDeclaration(handler)) {
+        const returnTypeNode = handler.getReturnTypeNode();
+        if (returnTypeNode) {
+            return returnTypeNode;
+        }
+    }
+    return undefined;
+}
+/**
+ * Find res.json<T>() generic type parameter
+ */
+function findResJsonGenericParam(handler) {
+    let result;
+    handler.forEachDescendant(node => {
+        if (result)
+            return; // Already found
+        if (!Node.isCallExpression(node))
+            return;
+        const expression = node.getExpression();
+        if (!Node.isPropertyAccessExpression(expression))
+            return;
+        const methodName = expression.getName();
+        if (methodName !== 'json')
+            return;
+        // Check if caller is 'res' or a chain containing 'res'
+        if (!isResponseObject(expression.getExpression()))
+            return;
+        // Check for generic type argument
+        const typeArgs = node.getTypeArguments();
+        if (typeArgs.length > 0) {
+            result = typeArgs[0];
+        }
+    });
+    return result;
+}
+/**
+ * Find the argument passed to res.json()
+ */
+function findResJsonArgument(handler) {
+    let result;
+    handler.forEachDescendant(node => {
+        if (result)
+            return; // Already found
+        if (!Node.isCallExpression(node))
+            return;
+        const expression = node.getExpression();
+        if (!Node.isPropertyAccessExpression(expression))
+            return;
+        const methodName = expression.getName();
+        if (methodName !== 'json' && methodName !== 'send')
+            return;
+        // Check if caller is 'res' or a chain containing 'res'
+        if (!isResponseObject(expression.getExpression()))
+            return;
+        // Get the first argument
+        const args = node.getArguments();
+        if (args.length > 0) {
+            result = args[0];
+        }
+    });
+    return result;
+}
+/**
+ * Extract status code and body from a response chain
+ * Handles: res.status(200).json(body), res.json(body), res.sendStatus(200)
+ */
+function extractStatusAndBody(call) {
+    const expression = call.getExpression();
+    if (!Node.isPropertyAccessExpression(expression))
+        return undefined;
+    const methodName = expression.getName();
+    const calleeExpr = expression.getExpression();
+    // Case: res.json(body) - default 200
+    if ((methodName === 'json' || methodName === 'send') && isResponseObject(calleeExpr)) {
+        const args = call.getArguments();
+        if (args.length > 0) {
+            return { status: 200, body: args[0] };
+        }
+    }
+    // Case: res.status(code).json(body)
+    if (methodName === 'json' || methodName === 'send') {
+        // Check if callee is a status() call
+        if (Node.isCallExpression(calleeExpr)) {
+            const statusExpr = calleeExpr.getExpression();
+            if (Node.isPropertyAccessExpression(statusExpr) &&
+                (statusExpr.getName() === 'status' || statusExpr.getName() === 'code')) {
+                const statusArgs = calleeExpr.getArguments();
+                if (statusArgs.length > 0) {
+                    const statusValue = getNumericValue(statusArgs[0]);
+                    const bodyArgs = call.getArguments();
+                    if (statusValue !== undefined && bodyArgs.length > 0) {
+                        return { status: statusValue, body: bodyArgs[0] };
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if an expression is likely the response object ('res', 'reply')
+ */
+function isResponseObject(expr) {
+    if (Node.isIdentifier(expr)) {
+        const name = expr.getText();
+        return name === 'res' || name === 'reply' || name === 'response';
+    }
+    // Could be a chain like res.status(200)
+    if (Node.isCallExpression(expr)) {
+        const callExpr = expr.getExpression();
+        if (Node.isPropertyAccessExpression(callExpr)) {
+            return isResponseObject(callExpr.getExpression());
+        }
+    }
+    if (Node.isPropertyAccessExpression(expr)) {
+        return isResponseObject(expr.getExpression());
+    }
+    return false;
+}
+/**
+ * Extract numeric value from a literal or identifier
+ */
+function getNumericValue(node) {
+    if (Node.isNumericLiteral(node)) {
+        return parseInt(node.getText(), 10);
+    }
+    // Could be a constant reference, but we'd need to resolve it
+    return undefined;
+}
+//# sourceMappingURL=response-inference.js.map

package/dist/patterns/rest/response-inference.js.map

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

package/dist/patterns/rest/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * REST Pattern Matcher Types
+ *
+ * Types for Express and Fastify REST endpoint detection.
+ *
+ * @module patterns/rest/types
+ * @see .context/ADR-P2-2-REST-DETECTION.md
+ */
+import type { Node } from 'ts-morph';
+import type { MatchCaptures } from '../types.js';
+/**
+ * HTTP methods supported by REST frameworks
+ */
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'ALL';
+/**
+ * Path parameter extracted from route paths
+ *
+ * @example
+ * For path `/users/:id(\\d+)?`:
+ * ```typescript
+ * {
+ *   name: 'id',
+ *   position: 1,
+ *   optional: true,
+ *   pattern: '\\d+',
+ *   inferredType: 'number'
+ * }
+ * ```
+ */
+export interface PathParameter {
+    /** Parameter name (without leading :) */
+    name: string;
+    /** Position in path segments (0-indexed) */
+    position: number;
+    /** Whether parameter is optional (:id?) */
+    optional: boolean;
+    /** Regex constraint if present (:id(\\d+)) */
+    pattern?: string;
+    /** Type inferred from pattern or default to string */
+    inferredType: 'string' | 'number' | 'any';
+}
+/**
+ * Validation middleware detected in route
+ */
+export interface ValidationMiddleware {
+    /** Validation library used */
+    library: 'zod' | 'joi' | 'celebrate' | 'express-validator' | 'yup' | 'unknown';
+    /** What is being validated */
+    target: 'body' | 'query' | 'params' | 'headers';
+    /** AST node containing the schema */
+    schemaNode: Node;
+    /** Position in middleware chain */
+    middlewareIndex?: number;
+}
+/**
+ * Fastify schema definition extracted from route options
+ */
+export interface FastifySchemas {
+    /** Body schema (for POST, PUT, PATCH) */
+    body?: Node;
+    /** Query string schema */
+    querystring?: Node;
+    /** Path params schema */
+    params?: Node;
+    /** Headers schema */
+    headers?: Node;
+    /** Response schemas by status code */
+    response?: Map<number, Node>;
+}
+/**
+ * Extended captures for REST pattern matches
+ */
+export interface RESTMatchCaptures extends MatchCaptures {
+    /** HTTP method for this route */
+    httpMethod: HTTPMethod;
+    /** Route path (e.g., '/users/:id') */
+    routePath: string;
+    /** Parsed path parameters */
+    pathParameters: PathParameter[];
+    /** Router/app instance name (e.g., 'app', 'router', 'userRouter') */
+    routerName?: string;
+    /** Detected validation middleware */
+    validationMiddleware?: ValidationMiddleware[];
+    /** The handler function node */
+    handlerNode?: Node;
+    /** Fastify-specific schemas */
+    schemas?: FastifySchemas;
+}
+/**
+ * Schema format detected in Fastify routes
+ */
+export type SchemaFormat = 'json-schema' | 'typebox' | 'zod' | 'unknown';
+/**
+ * Response inference result
+ */
+export interface ResponseInference {
+    /** How the schema was inferred */
+    method: 'explicit-return' | 'generic-param' | 'body-analysis' | 'unknown';
+    /** The AST node containing the response type (if found) */
+    node?: Node;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/patterns/rest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/patterns/rest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,KAAK,GACL,MAAM,GACN,KAAK,GACL,QAAQ,GACR,OAAO,GACP,SAAS,GACT,MAAM,GACN,KAAK,CAAC;AAMV;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAElB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,sDAAsD;IACtD,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,OAAO,EAAE,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,mBAAmB,GAAG,KAAK,GAAG,SAAS,CAAC;IAE/E,8BAA8B;IAC9B,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEhD,qCAAqC;IACrC,UAAU,EAAE,IAAI,CAAC;IAEjB,mCAAmC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,CAAC,EAAE,IAAI,CAAC;IAEZ,0BAA0B;IAC1B,WAAW,CAAC,EAAE,IAAI,CAAC;IAEnB,yBAAyB;IACzB,MAAM,CAAC,EAAE,IAAI,CAAC;IAEd,qBAAqB;IACrB,OAAO,CAAC,EAAE,IAAI,CAAC;IAEf,sCAAsC;IACtC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,iCAAiC;IACjC,UAAU,EAAE,UAAU,CAAC;IAEvB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAElB,6BAA6B;IAC7B,cAAc,EAAE,aAAa,EAAE,CAAC;IAEhC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,oBAAoB,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAE9C,gCAAgC;IAChC,WAAW,CAAC,EAAE,IAAI,CAAC;IAEnB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAAG,eAAe,GAAG,SAAS,CAAC;IAE1E,2DAA2D;IAC3D,IAAI,CAAC,EAAE,IAAI,CAAC;CACb"}

package/dist/patterns/rest/types.js

@@ -0,0 +1,10 @@
+/**
+ * REST Pattern Matcher Types
+ *
+ * Types for Express and Fastify REST endpoint detection.
+ *
+ * @module patterns/rest/types
+ * @see .context/ADR-P2-2-REST-DETECTION.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/patterns/rest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/patterns/rest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/patterns/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Pattern Matcher Types
+ *
+ * Core types for the pattern matcher abstraction that enables pluggable
+ * framework-agnostic API detection.
+ *
+ * @module patterns/types
+ * @see .context/ADR-P2-1-PATTERN-MATCHER.md
+ */
+import type { Node } from 'ts-morph';
+import type { SourceLocation } from '../core/types.js';
+/**
+ * Types of AST patterns that can be matched
+ */
+export type PatternType = 'call' | 'decorator' | 'property' | 'export' | 'chain';
+/**
+ * Where to find the schema in the matched pattern
+ */
+export type SchemaLocation = {
+    type: 'arg';
+    index: number;
+} | {
+    type: 'arg-named';
+    name: string;
+} | {
+    type: 'return';
+} | {
+    type: 'type-param';
+    index: number;
+} | {
+    type: 'body';
+} | {
+    type: 'chain-method';
+    method: string;
+} | {
+    type: 'decorator-arg';
+    index: number;
+};
+/**
+ * Definition of a single matchable pattern
+ */
+export interface PatternDef {
+    /** Pattern type identifier */
+    readonly type: PatternType;
+    /**
+     * Signature to match against
+     * - String: exact method/decorator name (e.g., 'get', 'Get')
+     * - RegExp: pattern match (e.g., /^(get|post|put|delete)$/i)
+     */
+    readonly signature: string | RegExp;
+    /**
+     * Optional: Object path prefix (e.g., 'app', 'router', 'server')
+     * For method calls, matches the receiver object
+     */
+    readonly receiver?: string | RegExp;
+    /**
+     * Where to extract the input schema from
+     */
+    readonly inputSchemaLocation?: SchemaLocation;
+    /**
+     * Where to extract the output schema from
+     */
+    readonly outputSchemaLocation?: SchemaLocation;
+    /**
+     * Optional: Additional validation predicates
+     */
+    readonly validate?: (node: Node) => boolean;
+}
+/**
+ * Data captured during pattern matching
+ */
+export interface MatchCaptures {
+    /** HTTP method for REST endpoints */
+    httpMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'ALL';
+    /** Route path for REST endpoints */
+    routePath?: string;
+    /** Procedure type for tRPC */
+    procedureType?: 'query' | 'mutation' | 'subscription';
+    /** Description from JSDoc or argument */
+    description?: string;
+    /** Input schema AST node (for extraction) */
+    inputSchemaNode?: Node;
+    /** Output schema AST node (for extraction) */
+    outputSchemaNode?: Node;
+    /** Additional framework-specific captures */
+    [key: string]: unknown;
+}
+/**
+ * Result of a successful pattern match
+ */
+export interface MatchResult {
+    /** The pattern that matched */
+    readonly pattern: PatternDef;
+    /** The AST node that was matched */
+    readonly node: Node;
+    /** Framework that produced this match */
+    readonly framework: string;
+    /** Extracted identifier (tool name, route path, etc.) */
+    readonly identifier: string;
+    /** Source location for error reporting */
+    readonly location: SourceLocation;
+    /** Captured data from the match */
+    readonly captures: MatchCaptures;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/patterns/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,WAAW,GACX,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAEpC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,cAAc,CAAC;IAE9C;;OAEG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,cAAc,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC;IAEtF,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,cAAc,CAAC;IAEtD,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,IAAI,CAAC;IAEvB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,IAAI,CAAC;IAExB,6CAA6C;IAC7C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAE7B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC"}

package/dist/patterns/types.js

@@ -0,0 +1,11 @@
+/**
+ * Pattern Matcher Types
+ *
+ * Core types for the pattern matcher abstraction that enables pluggable
+ * framework-agnostic API detection.
+ *
+ * @module patterns/types
+ * @see .context/ADR-P2-1-PATTERN-MATCHER.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/patterns/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/patterns/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/report/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Trace MCP - Reporter (Stub)
+ * Formats TraceResult into various output formats
+ */
+import type { TraceResult } from '../types.js';
+export type OutputFormat = 'json' | 'markdown' | 'summary';
+/**
+ * Format trace results for output
+ */
+export declare function formatResult(result: TraceResult, format?: OutputFormat): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/report/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/report/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3D;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EACnB,MAAM,GAAE,YAAqB,GAC5B,MAAM,CAcR"}

package/dist/report/index.js

@@ -0,0 +1,55 @@
+/**
+ * Trace MCP - Reporter (Stub)
+ * Formats TraceResult into various output formats
+ */
+/**
+ * Format trace results for output
+ */
+export function formatResult(result, format = 'json') {
+    switch (format) {
+        case 'json':
+            return JSON.stringify(result, null, 2);
+        case 'markdown':
+            return formatMarkdown(result);
+        case 'summary':
+            return formatSummary(result);
+        default:
+            return JSON.stringify(result, null, 2);
+    }
+}
+function formatMarkdown(result) {
+    const lines = [
+        '# Trace MCP Analysis Report',
+        '',
+        `**Generated**: ${result.timestamp}`,
+        '',
+        '## Summary',
+        '',
+        `| Metric | Count |`,
+        `|--------|-------|`,
+        `| Total Tools | ${result.summary.totalTools} |`,
+        `| Total Calls | ${result.summary.totalCalls} |`,
+        `| Matches | ${result.summary.matchCount} |`,
+        `| Mismatches | ${result.summary.mismatchCount} |`,
+        '',
+    ];
+    if (result.mismatches.length > 0) {
+        lines.push('## Mismatches', '');
+        for (const m of result.mismatches) {
+            lines.push(`### ${m.toolName}`);
+            lines.push(`- **Type**: ${m.issueType}`);
+            lines.push(`- **Description**: ${m.description}`);
+            lines.push(`- **Consumer**: ${m.consumerLocation.file}:${m.consumerLocation.line}`);
+            if (m.producerLocation) {
+                lines.push(`- **Producer**: ${m.producerLocation.file}:${m.producerLocation.line}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+function formatSummary(result) {
+    const status = result.mismatches.length === 0 ? '✅ PASS' : '❌ FAIL';
+    return `${status} - ${result.summary.matchCount} matches, ${result.summary.mismatchCount} mismatches`;
+}
+//# sourceMappingURL=index.js.map

package/dist/report/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/report/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAmB,EACnB,SAAuB,MAAM;IAE7B,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAEzC,KAAK,UAAU;YACb,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;QAEhC,KAAK,SAAS;YACZ,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;QAE/B;YACE,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,MAAmB;IACzC,MAAM,KAAK,GAAa;QACtB,6BAA6B;QAC7B,EAAE;QACF,kBAAkB,MAAM,CAAC,SAAS,EAAE;QACpC,EAAE;QACF,YAAY;QACZ,EAAE;QACF,oBAAoB;QACpB,oBAAoB;QACpB,mBAAmB,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI;QAChD,mBAAmB,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI;QAChD,eAAe,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI;QAC5C,kBAAkB,MAAM,CAAC,OAAO,CAAC,aAAa,IAAI;QAClD,EAAE;KACH,CAAC;IAEF,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAClD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;YACpF,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAC;gBACvB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;YACtF,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,aAAa,CAAC,MAAmB;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpE,OAAO,GAAG,MAAM,MAAM,MAAM,CAAC,OAAO,CAAC,UAAU,aAAa,MAAM,CAAC,OAAO,CAAC,aAAa,aAAa,CAAC;AACxG,CAAC"}

package/dist/tools/contract-comments.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Contract Comments Tool
+ * Adds cross-reference comments to producer and consumer code
+ * when a contract is validated as working.
+ */
+import type { ProducerSchema, ConsumerSchema, Match } from '../types.js';
+export interface ContractCommentOptions {
+    /** The validated match to document */
+    match: Match;
+    /** Producer schema details */
+    producer: ProducerSchema;
+    /** Consumer schema details */
+    consumer: ConsumerSchema;
+    /** Comment style */
+    style?: 'jsdoc' | 'inline' | 'block';
+    /** Include timestamp */
+    includeTimestamp?: boolean;
+    /** Custom prefix for comments */
+    prefix?: string;
+}
+export interface CommentResult {
+    success: boolean;
+    producerFile: string;
+    consumerFile: string;
+    producerComment: string;
+    consumerComment: string;
+    error?: string;
+}
+/**
+ * Generate cross-reference comments for a validated contract
+ */
+export declare function generateContractComments(options: ContractCommentOptions): {
+    producerComment: string;
+    consumerComment: string;
+};
+/**
+ * Add contract comments to source files
+ * WARNING: This modifies files! Use with caution.
+ */
+export declare function addContractComments(options: ContractCommentOptions): Promise<CommentResult>;
+/**
+ * Preview what comments would be added without modifying files
+ */
+export declare function previewContractComments(options: ContractCommentOptions): {
+    producerPreview: string;
+    consumerPreview: string;
+};
+//# sourceMappingURL=contract-comments.d.ts.map

package/dist/tools/contract-comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-comments.d.ts","sourceRoot":"","sources":["../../src/tools/contract-comments.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC,sCAAsC;IACtC,KAAK,EAAE,KAAK,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,cAAc,CAAC;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,cAAc,CAAC;IACzB,oBAAoB;IACpB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACrC,wBAAwB;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB,CA+BA;AAmBD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC,CA+CjG;AAuBD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB,CAQA"}