hyntx 3.0.2 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.d.ts CHANGED
@@ -1,441 +1,2 @@
1
- /**
2
- * Hyntx - TypeScript Type Definitions
3
- *
4
- * This module contains all shared type definitions for the Hyntx system.
5
- * All types are designed to be composable and type-safe.
6
- */
7
1
 
8
- /**
9
- * Data extracted from Claude Code messages.
10
- * Contains the sanitized prompt and metadata.
11
- */
12
- type ExtractedPrompt = {
13
- readonly content: string;
14
- readonly timestamp: string;
15
- readonly sessionId: string;
16
- readonly project: string;
17
- readonly date: string;
18
- };
19
- /**
20
- * Result of reading logs from the filesystem.
21
- */
22
- type LogReadResult = {
23
- readonly prompts: readonly ExtractedPrompt[];
24
- readonly warnings: readonly string[];
25
- };
26
- /**
27
- * Before/after rewrite example for a pattern.
28
- * Shows concrete improvement for a detected issue.
29
- */
30
- type BeforeAfter = {
31
- readonly before: string;
32
- readonly after: string;
33
- };
34
- /**
35
- * Severity levels for detected patterns.
36
- */
37
- type PatternSeverity = 'low' | 'medium' | 'high';
38
- /**
39
- * Detected improvement pattern from analysis.
40
- * Each pattern includes concrete examples and actionable suggestions.
41
- */
42
- type AnalysisPattern = {
43
- readonly id: string;
44
- readonly name: string;
45
- readonly frequency: number;
46
- readonly severity: PatternSeverity;
47
- readonly examples: readonly string[];
48
- readonly suggestion: string;
49
- readonly beforeAfter: BeforeAfter;
50
- };
51
- /**
52
- * Statistics from the analysis.
53
- */
54
- type AnalysisStats = {
55
- readonly totalPrompts: number;
56
- readonly promptsWithIssues: number;
57
- readonly overallScore: number;
58
- };
59
- /**
60
- * Complete analysis result from a provider.
61
- * Contains patterns, statistics, and top suggestion.
62
- */
63
- type AnalysisResult = {
64
- readonly date: string;
65
- readonly patterns: readonly AnalysisPattern[];
66
- readonly stats: AnalysisStats;
67
- readonly topSuggestion: string;
68
- };
69
- /**
70
- * Context limits for each provider.
71
- * Used for intelligent batching of prompts.
72
- */
73
- type ProviderLimits = {
74
- readonly maxTokensPerBatch: number;
75
- readonly maxPromptsPerBatch?: number;
76
- readonly prioritization: 'longest-first' | 'chronological';
77
- };
78
- /**
79
- * Configuration for a single analysis rule.
80
- * Allows enabling/disabling rules and overriding their severity.
81
- */
82
- type RuleConfig = {
83
- readonly enabled?: boolean;
84
- readonly severity?: PatternSeverity;
85
- };
86
- /**
87
- * Configuration for all analysis rules.
88
- * Maps rule IDs to their configuration.
89
- */
90
- type RulesConfig = Record<string, RuleConfig>;
91
- /**
92
- * Project-specific context information.
93
- * Loaded from .hyntxrc.json files to provide additional context during analysis.
94
- */
95
- type ProjectContext = {
96
- readonly role?: string;
97
- readonly techStack?: readonly string[];
98
- readonly domain?: string;
99
- readonly guidelines?: readonly string[];
100
- readonly projectType?: string;
101
- };
102
- /**
103
- * Interface for AI analysis providers.
104
- * All providers must implement this interface.
105
- */
106
- type AnalysisProvider = {
107
- readonly name: string;
108
- isAvailable(): Promise<boolean>;
109
- analyze(prompts: readonly string[], date: string, context?: ProjectContext): Promise<AnalysisResult>;
110
- getBatchLimits?(): ProviderLimits;
111
- };
112
- /**
113
- * Descriptive statistics for a dataset.
114
- * Provides comprehensive statistical measures beyond simple averages.
115
- */
116
- type DescriptiveStats = {
117
- readonly count: number;
118
- readonly mean: number;
119
- readonly median: number;
120
- readonly stdDev: number;
121
- readonly variance: number;
122
- readonly min: number;
123
- readonly max: number;
124
- readonly range: number;
125
- readonly percentiles: {
126
- readonly p25: number;
127
- readonly p50: number;
128
- readonly p75: number;
129
- readonly p90: number;
130
- readonly p95: number;
131
- };
132
- readonly skewness: number;
133
- readonly kurtosis: number;
134
- };
135
- /**
136
- * A single cluster from clustering analysis.
137
- */
138
- type Cluster = {
139
- readonly id: number;
140
- readonly indices: readonly number[];
141
- readonly size: number;
142
- };
143
- /**
144
- * A labeled cluster with interpretation.
145
- */
146
- type LabeledCluster = Cluster & {
147
- readonly label: string;
148
- readonly keywords: readonly string[];
149
- readonly representativePrompt: string;
150
- readonly dominantIssue?: string;
151
- };
152
- /**
153
- * Complete cluster analysis with labeled clusters.
154
- */
155
- type ClusterAnalysis = {
156
- readonly clusters: readonly LabeledCluster[];
157
- readonly metrics: {
158
- readonly silhouetteScore: number;
159
- readonly inertia: number;
160
- readonly optimalK: number;
161
- };
162
- readonly summary: {
163
- readonly totalPrompts: number;
164
- readonly avgClusterSize: number;
165
- readonly largestCluster: number;
166
- readonly smallestCluster: number;
167
- };
168
- };
169
- /**
170
- * Result of trend analysis using linear regression.
171
- */
172
- type TrendAnalysis = {
173
- readonly slope: number;
174
- readonly intercept: number;
175
- readonly rSquared: number;
176
- readonly direction: 'improving' | 'stable' | 'declining';
177
- readonly confidence: 'high' | 'medium' | 'low';
178
- readonly projectedScore: (days: number) => number;
179
- };
180
- /**
181
- * Enhanced statistics extending the basic AnalysisStats.
182
- * Backward compatible - all enhanced fields are optional.
183
- */
184
- type EnhancedAnalysisStats = AnalysisStats & {
185
- readonly descriptive?: DescriptiveStats;
186
- readonly specificity?: {
187
- readonly mean: number;
188
- readonly distribution: readonly number[];
189
- };
190
- readonly lexical?: {
191
- readonly avgComplexity: number;
192
- readonly avgWordCount: number;
193
- };
194
- readonly timing?: {
195
- readonly analysisStarted: number;
196
- readonly analysisCompleted: number;
197
- readonly durationMs: number;
198
- readonly tokensProcessed: number;
199
- };
200
- };
201
- /**
202
- * Enhanced analysis result with optional data science features.
203
- * Backward compatible - all enhanced fields are optional.
204
- */
205
- type EnhancedAnalysisResult = AnalysisResult & {
206
- readonly enhancedStats?: EnhancedAnalysisStats;
207
- readonly clusters?: ClusterAnalysis;
208
- readonly trend?: TrendAnalysis;
209
- };
210
-
211
- /**
212
- * Terminal reporter for analysis results.
213
- *
214
- * This module provides formatted terminal output for analysis results,
215
- * including patterns, statistics, and suggestions.
216
- */
217
-
218
- /**
219
- * Entry for a rule in the rules list.
220
- * Includes metadata about the rule and its current status.
221
- */
222
- type RuleListEntry = {
223
- readonly id: string;
224
- readonly name: string;
225
- readonly description: string;
226
- readonly defaultSeverity: PatternSeverity;
227
- readonly currentSeverity: PatternSeverity;
228
- readonly enabled: boolean;
229
- readonly overridden: boolean;
230
- };
231
-
232
- /**
233
- * Hyntx - CLI Entry Point
234
- *
235
- * Main entry point for the Hyntx CLI that analyzes Claude Code prompts
236
- * and generates improvement suggestions.
237
- */
238
-
239
- /**
240
- * Parsed command-line arguments.
241
- */
242
- type ParsedArgs = {
243
- readonly date: string;
244
- readonly from?: string;
245
- readonly to?: string;
246
- readonly project?: string;
247
- readonly output?: string;
248
- readonly dryRun: boolean;
249
- readonly checkReminder: boolean;
250
- readonly help: boolean;
251
- readonly version: boolean;
252
- readonly verbose: boolean;
253
- readonly checkConfig: boolean;
254
- readonly format: 'terminal' | 'json';
255
- readonly compact: boolean;
256
- readonly compareWith?: string;
257
- readonly compareWeek: boolean;
258
- readonly compareMonth: boolean;
259
- readonly history: boolean;
260
- readonly historySummary: boolean;
261
- readonly noHistory: boolean;
262
- readonly watch: boolean;
263
- readonly quiet: boolean;
264
- readonly clearCache: boolean;
265
- readonly noCache: boolean;
266
- readonly mcpServer: boolean;
267
- readonly listRules: boolean;
268
- readonly analysisMode: 'batch' | 'individual';
269
- readonly detailedStats: boolean;
270
- readonly showClusters: boolean;
271
- readonly trendAnalysis: boolean;
272
- readonly noEmbeddings: boolean;
273
- };
274
- /**
275
- * Parses command-line arguments.
276
- *
277
- * @returns Parsed arguments
278
- * @throws Error if arguments are invalid
279
- */
280
- declare function parseArguments(): ParsedArgs;
281
- /**
282
- * Validates parsed arguments for logical conflicts and requirements.
283
- *
284
- * @param args - Parsed arguments to validate
285
- * @throws Error if arguments are invalid or conflicting
286
- */
287
- declare function validateArguments(args: ParsedArgs): void;
288
- /**
289
- * Gets the output file path for a given date.
290
- * For multi-day scenarios, appends the date to the filename.
291
- *
292
- * @param basePath - Base output path from args
293
- * @param date - Date string (YYYY-MM-DD) or undefined for single-day
294
- * @returns Adjusted output file path
295
- */
296
- declare function getOutputFilePath(basePath: string, date?: string): string;
297
- /**
298
- * Writes a single analysis result to a file.
299
- *
300
- * @param filePath - File path to write to
301
- * @param result - Analysis result
302
- * @param format - Output format ('md' or 'json')
303
- * @param compact - Whether to use compact JSON (only for json format)
304
- * @throws Error if write fails
305
- */
306
- declare function writeOutputFile(filePath: string, result: AnalysisResult, format: 'md' | 'json', compact: boolean): Promise<void>;
307
- /**
308
- * Writes multi-day results to a JSON array file.
309
- *
310
- * @param filePath - File path to write to
311
- * @param results - Array of analysis results
312
- * @param compact - Whether to use compact JSON
313
- * @throws Error if write fails
314
- */
315
- declare function writeMultiDayJsonOutput(filePath: string, results: readonly AnalysisResult[], compact: boolean): Promise<void>;
316
- /**
317
- * Displays a dry-run summary without performing analysis.
318
- *
319
- * @param prompts - Array of extracted prompts
320
- * @param args - Parsed arguments
321
- */
322
- declare function displayDryRunSummary(prompts: readonly ExtractedPrompt[], args: ParsedArgs): void;
323
- /**
324
- * Displays reminder status and exits.
325
- */
326
- declare function showReminderStatus(): void;
327
- /**
328
- * Builds the list of rule entries with current configuration status.
329
- *
330
- * @param rulesConfig - Rules configuration from .hyntxrc.json
331
- * @returns Array of rule list entries
332
- */
333
- declare function buildRulesList(rulesConfig: RulesConfig | undefined): RuleListEntry[];
334
- /**
335
- * Displays available analysis rules and exits.
336
- *
337
- * @param format - Output format ('terminal' or 'json')
338
- * @param compact - Whether to use compact JSON
339
- * @param rulesConfig - Rules configuration from .hyntxrc.json
340
- */
341
- declare function showRulesList(format: 'terminal' | 'json', compact: boolean, rulesConfig: RulesConfig | undefined): void;
342
- /**
343
- * Displays help message and exits.
344
- */
345
- declare function showHelp(): void;
346
- /**
347
- * Displays version information and exits.
348
- */
349
- declare function showVersion(): void;
350
- /**
351
- * Runs configuration health check and exits.
352
- *
353
- * Validates all configured providers and tests their connectivity.
354
- * Exits with 0 if all providers are valid, 1 if any issues found.
355
- */
356
- declare function runConfigCheck(): Promise<void>;
357
- /**
358
- * Checks if this is the first run and runs setup if needed.
359
- *
360
- * @param isJsonMode - Whether JSON output mode is active
361
- */
362
- declare function checkAndRunSetup(isJsonMode: boolean): Promise<void>;
363
- /**
364
- * Reads logs with filters from parsed arguments.
365
- *
366
- * @param args - Parsed command-line arguments
367
- * @param isJsonMode - Whether JSON output mode is active
368
- * @returns Log read result with prompts and warnings
369
- */
370
- declare function readLogsWithSpinner(args: ParsedArgs, isJsonMode: boolean): Promise<LogReadResult>;
371
- /**
372
- * Connects to an available provider with automatic fallback.
373
- *
374
- * Uses the multi-provider factory to get the first available provider
375
- * from the configured services list, with fallback support.
376
- *
377
- * @param isJsonMode - Whether JSON output mode is active
378
- * @param analysisMode - Optional analysis mode override ('batch' or 'individual')
379
- * @returns Available provider instance
380
- */
381
- declare function connectProviderWithSpinner(isJsonMode: boolean, analysisMode?: 'batch' | 'individual'): Promise<AnalysisProvider>;
382
- /**
383
- * Analyzes prompts with progress tracking.
384
- *
385
- * @param provider - Analysis provider
386
- * @param prompts - Array of prompt strings
387
- * @param date - Date context
388
- * @param context - Optional project context
389
- * @param rules - Optional rules configuration
390
- * @param isJsonMode - Whether JSON output mode is active
391
- * @param noCache - Whether to bypass cache
392
- * @param extractedPrompts - Optional extracted prompts for cache lookup
393
- * @returns Analysis result
394
- */
395
- declare function analyzeWithProgress(provider: AnalysisProvider, prompts: readonly string[], date: string, context: ProjectContext | undefined, rules: RulesConfig | undefined, isJsonMode: boolean, noCache?: boolean, extractedPrompts?: readonly ExtractedPrompt[]): Promise<AnalysisResult>;
396
- /**
397
- * Runs watch mode for real-time prompt analysis.
398
- *
399
- * This function runs indefinitely, monitoring log files for new prompts.
400
- * It only exits when explicitly terminated (Ctrl+C) or an unhandled error occurs.
401
- *
402
- * @param provider - Analysis provider
403
- * @param args - Parsed arguments
404
- * @param context - Optional project context
405
- * @param rules - Optional rules configuration
406
- * @returns Promise that never resolves naturally (runs until terminated)
407
- */
408
- declare function runWatchMode(provider: AnalysisProvider, args: ParsedArgs, context: ProjectContext | undefined, rules: RulesConfig | undefined): Promise<never>;
409
- /**
410
- * Displays analysis results.
411
- *
412
- * @param result - Analysis result (can be enhanced)
413
- * @param format - Output format
414
- * @param compact - Whether to use compact JSON (only relevant for JSON format)
415
- * @param args - Parsed arguments to determine if enhanced features are enabled
416
- */
417
- declare function displayResults(result: AnalysisResult | EnhancedAnalysisResult, format: 'terminal' | 'json', compact: boolean, args?: ParsedArgs): void;
418
- /**
419
- * Handles errors and exits with appropriate code.
420
- *
421
- * @param error - Error to handle
422
- * @param isJsonMode - Whether JSON output mode is active
423
- */
424
- declare function handleError(error: Error, isJsonMode: boolean): void;
425
- /**
426
- * Runs the MCP server mode.
427
- *
428
- * This function initializes and starts the MCP server for stdio-based
429
- * JSON-RPC communication. It loads configuration, connects to a provider,
430
- * and starts the server with graceful shutdown handling.
431
- *
432
- * CRITICAL: Never write to stdout in this mode - only stderr for logging.
433
- * Stdout is reserved for JSON-RPC protocol messages.
434
- */
435
- declare function runMcpServer(): Promise<never>;
436
- /**
437
- * Main entry point for the CLI.
438
- */
439
- declare function cli(): Promise<void>;
440
-
441
- export { type ParsedArgs, analyzeWithProgress, buildRulesList, checkAndRunSetup, cli, connectProviderWithSpinner, displayDryRunSummary, displayResults, getOutputFilePath, handleError, parseArguments, readLogsWithSpinner, runConfigCheck, runMcpServer, runWatchMode, showHelp, showReminderStatus, showRulesList, showVersion, validateArguments, writeMultiDayJsonOutput, writeOutputFile };
2
+ export { }