mnehmos.trace.mcp 1.0.0

package/dist/languages/typescript.d.ts

@@ -0,0 +1,272 @@
+/**
+ * 🔷 TypeScript Language Parser
+ *
+ * Extracts MCP schemas from TypeScript source files using ts-morph.
+ * This is an enhanced parser that supports multiple extraction patterns
+ * for both producer schemas (tool definitions) and type definitions.
+ *
+ * Supported extraction patterns:
+ * 1. **server.tool()** - FastMCP / MCP SDK pattern
+ * 2. **Registry Pattern** - Object literal with ToolDefinition entries (ChatRPG)
+ * 3. **Exported Zod Schemas** - Named *Schema exports for tracing
+ * 4. **TypeScript Interfaces** - Exported interface declarations
+ * 5. **Type Aliases** - Exported type definitions
+ * 6. **Enums** - Exported enum declarations
+ *
+ * @module languages/typescript
+ *
+ * @example
+ * ```typescript
+ * import { TypeScriptParser } from './languages/typescript.js';
+ *
+ * const parser = new TypeScriptParser();
+ *
+ * // Extract tool definitions (Zod schemas)
+ * const producers = await parser.extractSchemas({ rootDir: './src' });
+ *
+ * // Extract interfaces and types
+ * const interfaces = await parser.extractInterfaces({ rootDir: './src' });
+ *
+ * // Extract all schemas
+ * const all = await parser.extractAll({ rootDir: './src' });
+ * ```
+ */
+import type { LanguageParser, ExtractOptions, TraceOptions } from './base.js';
+import type { ProducerSchema, ConsumerSchema } from '../types.js';
+import type { NormalizedSchema } from '../core/types.js';
+export declare class TypeScriptParser implements LanguageParser {
+    readonly name = "typescript";
+    readonly filePatterns: string[];
+    private zodSchemaCache;
+    extractSchemas(options: ExtractOptions): Promise<ProducerSchema[]>;
+    private findToolCalls;
+    private parseToolCall;
+    private extractFromRegistry;
+    private parseRegistryObject;
+    private parseToolDefinition;
+    /**
+     * Infer registry pattern from object shape
+     * Checks if object entries look like tool definitions
+     */
+    private inferRegistryFromShape;
+    /**
+     * Detect the shape of a tool definition from an object literal
+     */
+    private detectToolDefinitionShape;
+    /**
+     * Extract input schema from various formats
+     */
+    private extractInputSchema;
+    /**
+     * Parse a JSON Schema object literal
+     */
+    private parseJsonSchemaLiteral;
+    /**
+     * Collect all exported Zod schemas for cross-reference
+     */
+    private collectZodSchemas;
+    /**
+     * Extract tool definitions from exports
+     */
+    private extractFromExports;
+    private parseZodSchema;
+    private parseZodObjectContent;
+    private parseZodUnion;
+    private parseZodType;
+    /**
+     * Standard MCP tool output schema
+     */
+    private getMcpOutputSchema;
+    traceUsage(options: TraceOptions): Promise<ConsumerSchema[]>;
+    private traceFile;
+    private parseCallToolExpression;
+    private parseObjectLiteral;
+    private traceResultUsage;
+    private getPropertyChain;
+    /**
+     * Extract interfaces, type aliases, and enums from TypeScript files.
+     *
+     * Scans TypeScript source files and extracts all exported type definitions,
+     * converting them to NormalizedSchema format for schema comparison.
+     *
+     * Supports extraction of:
+     * - **Interfaces** - Including inherited properties from extends
+     * - **Type Aliases** - Object types, unions, intersections, Records
+     * - **Enums** - Both const and regular enums
+     *
+     * @param options - Extraction options specifying root directory and file patterns
+     * @param options.rootDir - Root directory to search for TypeScript files
+     * @param options.include - Optional glob patterns to include (default: `['*.ts', '*.tsx']`)
+     * @param options.exclude - Optional glob patterns to exclude (default: excludes node_modules and dist)
+     * @returns Promise resolving to array of NormalizedSchema for all exported declarations
+     *
+     * @example
+     * ```typescript
+     * const parser = new TypeScriptParser();
+     * const schemas = await parser.extractInterfaces({
+     *   rootDir: './src/types',
+     *   include: ['*.ts'],
+     *   exclude: ['*.test.ts']
+     * });
+     *
+     * // schemas[0] = {
+     * //   name: 'UserProfile',
+     * //   properties: { id: {...}, name: {...} },
+     * //   required: ['id', 'name'],
+     * //   source: { source: 'typescript', id: 'interface:UserProfile@...' },
+     * //   location: { file: '...', line: 10 }
+     * // }
+     * ```
+     */
+    extractInterfaces(options: ExtractOptions): Promise<NormalizedSchema[]>;
+    /**
+     * Extract all schemas from TypeScript files.
+     *
+     * Comprehensive extraction that combines interface/type extraction.
+     * This is the recommended entry point for extracting TypeScript type
+     * definitions for schema comparison workflows.
+     *
+     * @param options - Extraction options specifying root directory and file patterns
+     * @param options.rootDir - Root directory to search for TypeScript files
+     * @param options.include - Optional glob patterns to include
+     * @param options.exclude - Optional glob patterns to exclude
+     * @returns Promise resolving to array of NormalizedSchema
+     *
+     * @remarks
+     * Currently returns interface/type/enum schemas only.
+     * Future enhancement: Convert ProducerSchema to NormalizedSchema
+     * for Zod schema inclusion.
+     *
+     * @example
+     * ```typescript
+     * const parser = new TypeScriptParser();
+     * const schemas = await parser.extractAll({ rootDir: './src' });
+     *
+     * // Returns all exported interfaces, type aliases, and enums
+     * console.log(`Found ${schemas.length} type definitions`);
+     * ```
+     */
+    extractAll(options: ExtractOptions): Promise<NormalizedSchema[]>;
+    /**
+     * Convert a TypeScript interface declaration to NormalizedSchema.
+     *
+     * Handles all interface features:
+     * - Direct properties with type annotations
+     * - Inherited properties from extends clauses
+     * - Optional properties (marked with ?)
+     * - Readonly properties
+     * - Nullable types (T | null)
+     * - JSDoc descriptions and @deprecated tags
+     *
+     * @param iface - The ts-morph InterfaceDeclaration to convert
+     * @param filePath - Path to the source file for location tracking
+     * @returns NormalizedSchema representation of the interface
+     */
+    private convertInterfaceToSchema;
+    /**
+     * Get all properties from an interface, including inherited ones.
+     *
+     * Uses ts-morph's type resolution to flatten the property list,
+     * ensuring all properties from extended interfaces are included.
+     *
+     * @param iface - The interface declaration
+     * @returns Array of ts-morph Symbol objects representing all properties
+     */
+    private getInterfaceProperties;
+    /**
+     * Convert a TypeScript type alias to NormalizedSchema.
+     *
+     * Handles various type alias patterns:
+     * - Object types: `type Foo = { bar: string }`
+     * - Intersection types: `type Foo = A & B`
+     * - Record types: `type Dict = Record<string, T>`
+     * - Union types: `type Status = 'active' | 'inactive'`
+     *
+     * @param typeAlias - The ts-morph TypeAliasDeclaration to convert
+     * @param filePath - Path to the source file for location tracking
+     * @returns NormalizedSchema representation of the type alias
+     */
+    private convertTypeAliasToSchema;
+    /**
+     * Extract properties from a ts-morph Type object.
+     *
+     * Helper method for extracting property definitions from resolved types.
+     * Used by both interface and type alias conversion to handle object types.
+     *
+     * @param type - The ts-morph Type to extract properties from
+     * @param properties - Output record to populate with PropertyDef entries
+     * @param required - Output array to populate with required property names
+     */
+    private extractPropertiesFromType;
+    /**
+     * Convert a TypeScript enum to NormalizedSchema.
+     *
+     * Enums are represented as schemas with empty properties,
+     * since they don't have traditional object properties.
+     * The enum values are not currently extracted to the schema.
+     *
+     * @param enumDecl - The ts-morph EnumDeclaration to convert
+     * @param filePath - Path to the source file for location tracking
+     * @returns NormalizedSchema representation of the enum
+     *
+     * @remarks
+     * Future enhancement: Include enum members as values or properties.
+     */
+    private convertEnumToSchema;
+    /**
+     * Analyze nullability of a TypeScript type.
+     *
+     * Examines union types to determine if they include null or undefined,
+     * and extracts the "base" type after removing null/undefined.
+     *
+     * @param type - The ts-morph Type to analyze
+     * @returns Object containing:
+     *   - `baseType`: The type with null/undefined removed
+     *   - `isNullable`: True if type includes `| null`
+     *   - `hasUndefined`: True if type includes `| undefined`
+     *
+     * @example
+     * ```typescript
+     * // For type: string | null | undefined
+     * // Returns: { baseType: string, isNullable: true, hasUndefined: true }
+     * ```
+     */
+    private analyzeNullability;
+    /**
+     * Convert a ts-morph Type to NormalizedType.
+     *
+     * Recursively converts TypeScript types to the normalized type system:
+     * - Primitives: string, number, boolean, null
+     * - Literals: 'active', 42, true
+     * - Arrays: `string[]`, `Array<T>`
+     * - Tuples: `[string, number]`
+     * - Unions: `string | number`
+     * - Intersections: `A & B`
+     * - Objects: `{ foo: string }`
+     * - References: named interfaces
+     *
+     * @param type - The ts-morph Type to convert
+     * @param visitingTypes - Set of type names currently being visited (for cycle detection)
+     * @returns NormalizedType representation
+     */
+    private convertTypeToNormalized;
+    /**
+     * Check if a property declaration is readonly.
+     *
+     * @param decl - The property declaration node
+     * @returns True if the property has the readonly modifier
+     */
+    private isPropertyReadonly;
+    /**
+     * Extract JSDoc information from a declaration.
+     *
+     * Parses JSDoc comments to extract:
+     * - Description text
+     * - @deprecated tag presence
+     *
+     * @param decl - The declaration node to extract JSDoc from
+     * @returns Object with description and deprecated flag
+     */
+    private getJSDocInfo;
+}
+//# sourceMappingURL=typescript.d.ts.map

package/dist/languages/typescript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../src/languages/typescript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAA8B,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAA0C,MAAM,kBAAkB,CAAC;AA0DjG,qBAAa,gBAAiB,YAAW,cAAc;IACrD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,QAAQ,CAAC,YAAY,WAA2B;IAGhD,OAAO,CAAC,cAAc,CAA4E;IAM5F,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAgExE,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,aAAa;IAgDrB,OAAO,CAAC,mBAAmB;IAoC3B,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,mBAAmB;IAkD3B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA+C9B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA4BjC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAkD1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoD9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA0C1B,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,qBAAqB;IA2B7B,OAAO,CAAC,aAAa;IAmBrB,OAAO,CAAC,YAAY;IA+EpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAsBpB,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmClE,OAAO,CAAC,SAAS;IA0BjB,OAAO,CAAC,uBAAuB;IAoD/B,OAAO,CAAC,kBAAkB;IAoB1B,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAuD7E;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAetE;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,wBAAwB;IA0DhC;;;;;;;;OAQG;IACH,OAAO,CAAC,sBAAsB;IAS9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAkDhC;;;;;;;;;OASG;IACH,OAAO,CAAC,yBAAyB;IAyCjC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mBAAmB;IAyB3B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,uBAAuB;IAiK/B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;CA0BrB"}