@xctrace-analyzer/core 0.1.0

package/dist/analyzer/recommendation-engine.js

@@ -0,0 +1,306 @@
+/**
+ * RecommendationEngine - Generates actionable optimization recommendations
+ */
+const RECOMMENDATION_RULES = [
+    // Image processing
+    {
+        pattern: /image|bitmap|cgimage|uiimage|resize|scale/i,
+        type: 'caching',
+        priority: 'high',
+        title: 'Implement Image Caching',
+        descriptionTemplate: 'Frequent image operations detected. Consider implementing NSCache or disk-based caching to avoid repeated processing.',
+        potentialImprovement: '50-70% reduction in image processing time',
+        codeExample: `let imageCache = NSCache<NSString, UIImage>()
+
+func cachedImage(for key: String) -> UIImage? {
+    if let cached = imageCache.object(forKey: key as NSString) {
+        return cached
+    }
+    let image = processImage(key)
+    imageCache.setObject(image, forKey: key as NSString)
+    return image
+}`,
+    },
+    // JSON parsing
+    {
+        pattern: /json|parse|decode|jsonSerialization/i,
+        type: 'async',
+        priority: 'high',
+        title: 'Move JSON Parsing to Background Thread',
+        descriptionTemplate: 'JSON parsing is blocking the main thread. Consider using async/await or background queues for parsing.',
+        potentialImprovement: 'Improved UI responsiveness',
+        codeExample: `Task {
+    let data = await fetchData()
+    let decoded = try JSONDecoder().decode(Model.self, from: data)
+    await MainActor.run {
+        updateUI(with: decoded)
+    }
+}`,
+    },
+    // Database operations
+    {
+        pattern: /database|sql|query|fetch|coredata|realm/i,
+        type: 'optimization',
+        priority: 'high',
+        title: 'Optimize Database Queries',
+        descriptionTemplate: 'Database operations are taking significant time. Consider adding indexes, batching queries, or using query optimization techniques.',
+        potentialImprovement: '40-60% faster queries',
+        codeExample: `// Add index
+entity.index(on: \\.propertyName)
+
+// Batch fetching
+let request = NSFetchRequest<Entity>(entityName: "Entity")
+request.fetchBatchSize = 20`,
+    },
+    // Network operations
+    {
+        pattern: /network|http|request|url|download|upload/i,
+        type: 'caching',
+        priority: 'medium',
+        title: 'Implement Response Caching',
+        descriptionTemplate: 'Frequent network requests detected. Consider implementing request caching or batching multiple requests.',
+        potentialImprovement: 'Reduced network calls and faster response times',
+    },
+    // Sorting/filtering
+    {
+        pattern: /sort|filter|search|find/i,
+        type: 'algorithm',
+        priority: 'medium',
+        title: 'Optimize Collection Operations',
+        descriptionTemplate: 'Frequent collection operations detected. Consider using more efficient algorithms or pre-computed indexes.',
+        potentialImprovement: '30-50% faster operations',
+        codeExample: `// Use Set for O(1) lookups instead of Array.contains
+let idSet = Set(ids)
+let filtered = items.filter { idSet.contains($0.id) }`,
+    },
+    // View layout
+    {
+        pattern: /layout|constraint|autolayout|updateConstraints|layoutSubviews/i,
+        type: 'optimization',
+        priority: 'medium',
+        title: 'Simplify View Hierarchy',
+        descriptionTemplate: 'Auto Layout is consuming significant time. Consider simplifying view hierarchy or using manual layout for performance-critical views.',
+        potentialImprovement: 'Faster view updates and animations',
+    },
+    // Cryptography
+    {
+        pattern: /crypto|encrypt|decrypt|hash|hmac|aes/i,
+        type: 'async',
+        priority: 'high',
+        title: 'Move Cryptographic Operations Off Main Thread',
+        descriptionTemplate: 'Cryptographic operations are blocking. These should always run on background threads.',
+        potentialImprovement: 'Improved UI responsiveness',
+    },
+    // File I/O
+    {
+        pattern: /file|read|write|fileManager|document/i,
+        type: 'async',
+        priority: 'high',
+        title: 'Perform File I/O Asynchronously',
+        descriptionTemplate: 'File operations are blocking the main thread. Use async I/O or background queues.',
+        potentialImprovement: 'Non-blocking I/O operations',
+    },
+];
+/**
+ * Generates optimization recommendations from analysis
+ */
+export class RecommendationEngine {
+    /**
+     * Generate recommendations for an analysis
+     */
+    generateRecommendations(analysis) {
+        const recommendations = [];
+        // Generate recommendations from bottlenecks
+        for (const bottleneck of analysis.bottlenecks) {
+            const recommendation = this.generateRecommendationForBottleneck(bottleneck);
+            if (recommendation) {
+                recommendations.push(recommendation);
+            }
+        }
+        // Add general recommendations based on stats
+        recommendations.push(...this.generateGeneralRecommendations(analysis));
+        recommendations.push(...this.generateInstrumentRecommendations(analysis));
+        // Remove duplicates and prioritize
+        return this.deduplicateAndPrioritize(recommendations);
+    }
+    /**
+     * Generate recommendation for a specific bottleneck
+     */
+    generateRecommendationForBottleneck(bottleneck) {
+        const functionName = `${bottleneck.module || ''}${bottleneck.function}`;
+        // Try to match against patterns
+        for (const rule of RECOMMENDATION_RULES) {
+            if (rule.pattern.test(functionName)) {
+                return {
+                    type: rule.type,
+                    priority: this.adjustPriority(rule.priority, bottleneck.impact),
+                    title: rule.title,
+                    description: rule.descriptionTemplate,
+                    affectedFunctions: [bottleneck.function],
+                    potentialImprovement: rule.potentialImprovement || `~${bottleneck.duration.toFixed(0)}ms`,
+                    codeExample: rule.codeExample,
+                };
+            }
+        }
+        // Generic recommendation if no pattern matches
+        if (bottleneck.impact === 'critical' || bottleneck.impact === 'high') {
+            return {
+                type: 'optimization',
+                priority: bottleneck.impact === 'critical' ? 'high' : 'medium',
+                title: `Optimize ${bottleneck.function}`,
+                description: bottleneck.suggestion,
+                affectedFunctions: [bottleneck.function],
+                potentialImprovement: `~${bottleneck.duration.toFixed(0)}ms (${bottleneck.percentage.toFixed(1)}% of total time)`,
+            };
+        }
+        return null;
+    }
+    /**
+     * Generate general recommendations based on overall stats
+     */
+    generateGeneralRecommendations(analysis) {
+        const recommendations = [];
+        // Too many slow functions
+        if (analysis.stats.slowFunctions > 10) {
+            recommendations.push({
+                type: 'architecture',
+                priority: 'medium',
+                title: 'Consider Architectural Refactoring',
+                description: `Found ${analysis.stats.slowFunctions} slow functions. This suggests the need for broader architectural improvements rather than individual function optimizations.`,
+                affectedFunctions: [],
+                potentialImprovement: 'Overall better performance and maintainability',
+            });
+        }
+        // High thread contention (many threads but poor performance)
+        if (analysis.stats.threadCount > 8 && analysis.stats.avgFunctionTime > 100) {
+            recommendations.push({
+                type: 'architecture',
+                priority: 'medium',
+                title: 'Review Thread Management',
+                description: `High thread count (${analysis.stats.threadCount}) but slow performance suggests thread contention or over-parallelization. Consider reducing concurrent operations.`,
+                affectedFunctions: [],
+                potentialImprovement: 'Reduced thread contention and context switching',
+            });
+        }
+        return recommendations;
+    }
+    /**
+     * Generate recommendations from non-Time-Profiler instrument findings.
+     */
+    generateInstrumentRecommendations(analysis) {
+        const recommendations = [];
+        for (const instrument of analysis.instrumentAnalyses ?? []) {
+            for (const finding of instrument.findings) {
+                switch (instrument.kind) {
+                    case 'memory':
+                        recommendations.push({
+                            type: 'memory',
+                            priority: this.priorityFromFinding(finding.severity),
+                            title: 'Investigate Memory Usage',
+                            description: finding.description,
+                            affectedFunctions: [],
+                            potentialImprovement: 'Lower peak memory and fewer memory pressure events',
+                        });
+                        break;
+                    case 'allocations':
+                        recommendations.push({
+                            type: 'memory',
+                            priority: this.priorityFromFinding(finding.severity),
+                            title: 'Reduce Allocation Churn',
+                            description: finding.description,
+                            affectedFunctions: [],
+                            potentialImprovement: 'Fewer allocations and less allocator overhead',
+                        });
+                        break;
+                    case 'leaks':
+                        recommendations.push({
+                            type: 'memory',
+                            priority: this.priorityFromFinding(finding.severity),
+                            title: 'Investigate Memory Leaks',
+                            description: finding.description,
+                            affectedFunctions: [],
+                            potentialImprovement: 'Recovered leaked memory and improved long-session stability',
+                        });
+                        break;
+                    case 'network':
+                        recommendations.push({
+                            type: 'caching',
+                            priority: this.priorityFromFinding(finding.severity),
+                            title: 'Review Network Reliability',
+                            description: finding.description,
+                            affectedFunctions: [],
+                            potentialImprovement: 'Fewer failed requests and less redundant transfer',
+                        });
+                        break;
+                    case 'energy':
+                        recommendations.push({
+                            type: 'optimization',
+                            priority: this.priorityFromFinding(finding.severity),
+                            title: 'Reduce Energy Impact',
+                            description: finding.description,
+                            affectedFunctions: [],
+                            potentialImprovement: 'Lower battery usage and less background activity',
+                        });
+                        break;
+                }
+            }
+        }
+        return recommendations;
+    }
+    priorityFromFinding(severity) {
+        if (severity === 'critical' || severity === 'high') {
+            return 'high';
+        }
+        if (severity === 'medium') {
+            return 'medium';
+        }
+        return 'low';
+    }
+    /**
+     * Adjust priority based on bottleneck impact
+     */
+    adjustPriority(basePriority, impact) {
+        if (impact === 'critical') {
+            return 'high';
+        }
+        if (impact === 'high' && basePriority === 'medium') {
+            return 'high';
+        }
+        if (impact === 'low' && basePriority === 'high') {
+            return 'medium';
+        }
+        return basePriority;
+    }
+    /**
+     * Remove duplicate recommendations and prioritize
+     */
+    deduplicateAndPrioritize(recommendations) {
+        // Use title as deduplication key
+        const seen = new Map();
+        for (const rec of recommendations) {
+            const existing = seen.get(rec.title);
+            if (!existing) {
+                seen.set(rec.title, rec);
+            }
+            else {
+                // Merge affected functions
+                const combined = {
+                    ...existing,
+                    affectedFunctions: [...new Set([...existing.affectedFunctions, ...rec.affectedFunctions])],
+                };
+                seen.set(rec.title, combined);
+            }
+        }
+        // Sort by priority
+        const priorityOrder = { high: 0, medium: 1, low: 2 };
+        return Array.from(seen.values()).sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+    }
+}
+/**
+ * Convenience function to generate recommendations
+ */
+export function generateRecommendations(analysis) {
+    const engine = new RecommendationEngine();
+    return engine.generateRecommendations(analysis);
+}
+//# sourceMappingURL=recommendation-engine.js.map

package/dist/analyzer/recommendation-engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @xctrace-analyzer/core
+ *
+ * Core analysis library for Xcode Instruments traces
+ */
+export * from './types.js';
+export { TraceParser, parseTrace, type TraceExporter, type TraceParserOptions } from './parser/trace-parser.js';
+export { PerformanceAnalyzer, analyzeTrace } from './analyzer/performance-analyzer.js';
+export { ComparativeAnalyzer, compareTraces } from './analyzer/comparative-analyzer.js';
+export { RecommendationEngine, generateRecommendations } from './analyzer/recommendation-engine.js';
+export * from './utils/xctrace-runner.js';
+import { Analysis, AnalysisOptions } from './types.js';
+export declare function analyzeTraceFile(tracePath: string, options?: AnalysisOptions): Promise<Analysis>;
+import { Comparison, ComparisonOptions } from './types.js';
+export declare function compareTraceFiles(baselinePath: string, currentPath: string, analysisOptions?: AnalysisOptions, comparisonOptions?: ComparisonOptions): Promise<Comparison>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGhH,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAGpG,cAAc,2BAA2B,CAAC;AAQ1C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAMD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3D,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,eAAe,EACjC,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,UAAU,CAAC,CASrB"}

package/dist/index.js

@@ -0,0 +1,46 @@
+/**
+ * @xctrace-analyzer/core
+ *
+ * Core analysis library for Xcode Instruments traces
+ */
+// Export types
+export * from './types.js';
+// Export parser
+export { TraceParser, parseTrace } from './parser/trace-parser.js';
+// Export analyzers
+export { PerformanceAnalyzer, analyzeTrace } from './analyzer/performance-analyzer.js';
+export { ComparativeAnalyzer, compareTraces } from './analyzer/comparative-analyzer.js';
+export { RecommendationEngine, generateRecommendations } from './analyzer/recommendation-engine.js';
+// Export utilities
+export * from './utils/xctrace-runner.js';
+/**
+ * High-level convenience function: parse and analyze a trace in one call
+ */
+import { parseTrace } from './parser/trace-parser.js';
+import { analyzeTrace } from './analyzer/performance-analyzer.js';
+import { generateRecommendations } from './analyzer/recommendation-engine.js';
+export async function analyzeTraceFile(tracePath, options) {
+    // Parse the trace
+    const parsed = await parseTrace(tracePath, options?.timeRangeMs ? { timeRangeMs: options.timeRangeMs } : undefined);
+    // Analyze it
+    const analysis = analyzeTrace(parsed, options);
+    // Add recommendations
+    if (options?.includeRecommendations !== false) {
+        analysis.recommendations = generateRecommendations(analysis);
+    }
+    return analysis;
+}
+/**
+ * High-level convenience function: compare two traces
+ */
+import { compareTraces } from './analyzer/comparative-analyzer.js';
+export async function compareTraceFiles(baselinePath, currentPath, analysisOptions, comparisonOptions) {
+    // Parse and analyze both traces
+    const [baselineAnalysis, currentAnalysis] = await Promise.all([
+        analyzeTraceFile(baselinePath, analysisOptions),
+        analyzeTraceFile(currentPath, analysisOptions),
+    ]);
+    // Compare them
+    return compareTraces(baselineAnalysis, currentAnalysis, comparisonOptions);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAe;AACf,cAAc,YAAY,CAAC;AAE3B,gBAAgB;AAChB,OAAO,EAAE,WAAW,EAAE,UAAU,EAA+C,MAAM,0BAA0B,CAAC;AAEhH,mBAAmB;AACnB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAEpG,mBAAmB;AACnB,cAAc,2BAA2B,CAAC;AAE1C;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAG9E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAiB,EACjB,OAAyB;IAEzB,kBAAkB;IAClB,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,SAAS,EACT,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CACxE,CAAC;IAEF,aAAa;IACb,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C,sBAAsB;IACtB,IAAI,OAAO,EAAE,sBAAsB,KAAK,KAAK,EAAE,CAAC;QAC9C,QAAQ,CAAC,eAAe,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGnE,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,YAAoB,EACpB,WAAmB,EACnB,eAAiC,EACjC,iBAAqC;IAErC,gCAAgC;IAChC,MAAM,CAAC,gBAAgB,EAAE,eAAe,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC5D,gBAAgB,CAAC,YAAY,EAAE,eAAe,CAAC;QAC/C,gBAAgB,CAAC,WAAW,EAAE,eAAe,CAAC;KAC/C,CAAC,CAAC;IAEH,eAAe;IACf,OAAO,aAAa,CAAC,gBAAgB,EAAE,eAAe,EAAE,iBAAiB,CAAC,CAAC;AAC7E,CAAC"}

package/dist/parser/trace-parser.d.ts

@@ -0,0 +1,154 @@
+/**
+ * TraceParser - Parses Xcode Instruments trace files
+ */
+import { ParsedTrace, TimeRangeMs } from '../types.js';
+export interface TraceExporter {
+    exportTOC(tracePath: string): Promise<string>;
+    exportTable(tracePath: string, schema: string, runNumber?: number): Promise<string>;
+    exportXPath?(tracePath: string, xpath: string): Promise<string>;
+    exportHAR?(tracePath: string): Promise<string>;
+}
+export interface TraceParserOptions {
+    timeRangeMs?: TimeRangeMs;
+}
+/**
+ * Main parser class for Xcode Instruments traces
+ */
+export declare class TraceParser {
+    private xmlParser;
+    private exporter;
+    private exportAttempts;
+    constructor(exporter?: TraceExporter);
+    /**
+     * Parse a complete trace file
+     */
+    parseTrace(tracePath: string, options?: TraceParserOptions): Promise<ParsedTrace>;
+    /**
+     * Validate that the trace file exists and is readable
+     */
+    private validateTraceFile;
+    /**
+     * Extract metadata from trace file
+     */
+    private extractMetadataAndSchemas;
+    /**
+     * Parse Time Profiler data from trace
+     */
+    private parseTimeProfile;
+    /**
+     * Parse supported non-Time-Profiler instrument data.
+     */
+    private parseInstrumentAnalyses;
+    /**
+     * Parse main-thread hang events from `potential-hangs` and `hang-risks`.
+     *
+     * xctrace exposes these schemas in every macOS/iOS trace; each row carries a
+     * `start-time`, `duration`, and `hang-type` (`Hang` / `Severe Hang` /
+     * `Microhang`), plus thread/process metadata. Returns `undefined` when no
+     * hang schemas are present (most empty traces).
+     */
+    private parseHangs;
+    private parseHangRow;
+    private summarizeHangs;
+    private filterSamplesByTimeRange;
+    private filterHangEventsByTimeRange;
+    private timeProfileTotalDuration;
+    /**
+     * xctrace XML interns repeated values: the first occurrence has `id="N"`
+     * with full data, every subsequent occurrence is `<element ref="N"/>`.
+     * Without resolution every row after the first loses its thread/process
+     * info. Walk the rows once collecting `id -> node`, then deep-clone each
+     * row substituting any `ref` for its captured node.
+     */
+    private resolveIdRefs;
+    /**
+     * Read the duration of a `<start-time>` / `<duration>` element, in
+     * milliseconds. xctrace emits the raw nanosecond count as the element's
+     * text content and a pretty form (e.g. `"817.10 ms"` or `"00:01.326.520"`)
+     * as `@_fmt`. Prefer the text (always ns); fall back to fmt parsing.
+     */
+    private readDurationFieldMs;
+    private readTextField;
+    private readFmtField;
+    private readNumericField;
+    private parseNetworkAnalysis;
+    private tryExportHAR;
+    private analyzeRowsForKind;
+    private buildSupportStatus;
+    private exportAttemptsForSupportKind;
+    private statusFromExportAttempts;
+    private supportReason;
+    private unsupportedReason;
+    private instrumentSectionName;
+    private analyzeMemoryRows;
+    private analyzeAllocationRows;
+    private analyzeLeakRows;
+    private analyzeNetworkRows;
+    private analyzeNetworkHAR;
+    private analyzeEnergyRows;
+    private extractSchemas;
+    private extractGuiTrackNamesByKind;
+    private extractUserProcessNames;
+    private isAttachedTargetNode;
+    private processPath;
+    private processNameFromNode;
+    private isSystemProcessPath;
+    private extractTableDescriptors;
+    private unexportableFinding;
+    private matchSchemasForKind;
+    private exportRowsForSchemas;
+    private networkSchemasSafeForRawExport;
+    private unexportedRowsForSchemas;
+    private parseTableRows;
+    private parseXml;
+    private assertInputSize;
+    private limitRows;
+    private rowsFromTableNode;
+    private flattenRow;
+    private writeNestedValue;
+    private findFirstKey;
+    private findFirstKeyAtDepth;
+    private cleanKey;
+    private arrayOf;
+    private nodeName;
+    private xpathSegment;
+    private safeXPathElementName;
+    private xpathStringLiteral;
+    private parseScalar;
+    private parseNumeric;
+    private maxMetric;
+    private firstMetric;
+    private firstString;
+    private sumMatchingMetrics;
+    private pushByteMetric;
+    private pushNumberMetric;
+    private topRowByBytes;
+    private topMapEntry;
+    private hostFromURL;
+    private formatBytes;
+    /**
+     * Parse a single sample row from XML
+     */
+    private parseSampleRow;
+    private parseSampleTimestamp;
+    private parseSampleThreadId;
+    private parseSampleWeight;
+    private nodeScalar;
+    /**
+     * Aggregate function profiles from samples
+     */
+    private aggregateFunctionProfiles;
+    /**
+     * Parse function name to extract module and function
+     */
+    private parseFunctionName;
+    /**
+     * Parse duration string to milliseconds
+     */
+    private parseDuration;
+}
+/**
+ * Convenience function to parse a trace
+ */
+export declare function parseTrace(tracePath: string, options?: TraceParserOptions): Promise<ParsedTrace>;
+//# sourceMappingURL=trace-parser.d.ts.map

package/dist/parser/trace-parser.d.ts.map

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