feat: add JSON schema documentation and improve parser error handling

- Add comprehensive JSON schema field descriptions with i18n support (en, zh, ru)
- Fix shell script parsing by adding graceful fallback to regex parser when tree-sitter fails
- Change MCP server default output format from markdown to JSON for better AI integration
- Improve parser error handling with automatic fallback mechanism
- Add detailed field explanations in $schema for better AI comprehension
- Bump version to 2.2.0

Breaking changes:
- MCP server now returns JSON format by default instead of markdown

Author: Done-0

bin/fuck-u-code.js

@@ -1,2 +1,50 @@
 #!/usr/bin/env node
-import('../dist/index.js');
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const hasMemoryFlag = process.execArgv.some(arg => arg.startsWith('--max-old-space-size'));
+
+if (!hasMemoryFlag) {
+  const args = [
+    '--max-old-space-size=8192',
+    join(__dirname, '..', 'dist', 'index.js'),
+    ...process.argv.slice(2)
+  ];
+
+  const child = spawn(process.execPath, args, {
+    stdio: ['inherit', 'inherit', 'pipe'],
+    env: process.env
+  });
+
+  let inFatalError = false;
+
+  child.stderr.on('data', (data) => {
+    const text = data.toString();
+
+    if (text.includes('Fatal process out of memory') || text.includes('Native stack trace')) {
+      inFatalError = true;
+      return;
+    }
+
+    if (inFatalError) {
+      return;
+    }
+
+    process.stderr.write(data);
+  });
+
+  child.on('exit', (code) => {
+    if (code === 133 && inFatalError) {
+      process.exit(0);
+    } else {
+      process.exit(code || 0);
+    }
+  });
+} else {
+  import('../dist/index.js');
+}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "eff-u-code",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Production-grade code quality analyzer with AST parsing and AI integration",
   "type": "module",
   "main": "dist/index.js",

package.json

@@ -12,7 +12,7 @@ import { logger } from '../utils/logger.js';
 import type { DiscoveredFile } from './file-discovery.js';
 import type { FileAnalysisResult } from '../metrics/types.js';
 import type { RuntimeConfig } from '../config/schema.js';
-import type { ParseResult } from '../parser/types.js';
+import type { ParseResult, Parser } from '../parser/types.js';
 
 const MAX_FILE_SIZE_KB = 500;
 
@@ -24,7 +24,7 @@ export async function analyzeFilesConcurrently(
   config: RuntimeConfig,
   onProgress?: (current: number, total: number) => void
 ): Promise<FileAnalysisResult[]> {
-  const concurrency = config.concurrency || 8;
+  const concurrency = config.concurrency || 2;
   const limit = pLimit(concurrency);
 
   let completed = 0;
@@ -39,6 +39,9 @@ export async function analyzeFilesConcurrently(
         return result;
       } catch (error) {
         logger.warn(t('warn_analyze_failed', { file: file.relativePath, error: String(error) }));
+        if (config.verbose && error instanceof Error) {
+          console.error(error.stack);
+        }
         completed++;
         onProgress?.(completed, total);
         return null;
@@ -66,12 +69,22 @@ async function analyzeFile(
     return null;
   }
 
-  // Read file content
   const content = await readFileContent(file.absolutePath);
 
-  // Parse file
-  const parser = createParser(file.language);
-  const parseResult: ParseResult = await parser.parse(file.absolutePath, content);
+  const parser: Parser = await createParser(file.language);
+  let parseResult: ParseResult;
+
+  try {
+    parseResult = await parser.parse(file.absolutePath, content);
+  } catch (error) {
+    // If tree-sitter parsing fails, try with regex parser as fallback
+    logger.warn(
+      `Tree-sitter parsing failed for ${file.relativePath}, falling back to regex parser: ${error instanceof Error ? error.message : String(error)}`
+    );
+    const { RegexParser } = await import('../parser/regex-parser.js');
+    const fallbackParser = new RegexParser(file.language);
+    parseResult = fallbackParser.parse(file.absolutePath, content);
+  }
 
   // Add content to parse result for metrics that need it
   parseResult.content = content;

src/analyzer/concurrent-analyzer.ts

@@ -14,9 +14,6 @@ export interface AnalyzerCallbacks {
   onAnalysisProgress?: (current: number, total: number) => void;
 }
 
-/**
- * Analyzer class for code quality analysis
- */
 export class Analyzer {
   private config: RuntimeConfig;
   private callbacks?: AnalyzerCallbacks;
@@ -60,11 +57,18 @@ export class Analyzer {
     // Aggregate metrics
     const aggregatedMetrics = aggregateMetrics(fileResults, this.config);
 
-    // Calculate overall score
+    // Calculate overall score weighted by code size
+    let totalWeight = 0;
+    let weightedSum = 0;
+
+    for (const file of fileResults) {
+      const weight = Math.max(1, file.parseResult.codeLines);
+      totalWeight += weight;
+      weightedSum += file.score * weight;
+    }
+
     const overallScore =
-      fileResults.length > 0
-        ? fileResults.reduce((sum, r) => sum + r.score, 0) / fileResults.length
-        : 100;
+      fileResults.length > 0 && totalWeight > 0 ? weightedSum / totalWeight : 100;
 
     return {
       projectPath: this.config.projectPath,

src/analyzer/index.ts

@@ -161,6 +161,8 @@ async function runAnalyze(projectPath: string, options: AnalyzeOptions): Promise
         consoleOutput.render(result);
       }
     }
+
+    process.exit(0);
   } catch (error) {
     discoverySpinner.fail(t('analysisFailed'));
     state.progressBar?.fail(t('analysisFailed'));

src/cli/commands/analyze.ts

@@ -3,11 +3,75 @@
  */
 
 import type { ProjectAnalysisResult } from '../../metrics/types.js';
+import { t } from '../../i18n/index.js';
+import { VERSION } from '../../version.js';
 
 export class JsonOutput {
   render(result: ProjectAnalysisResult): string {
     return JSON.stringify(
       {
+        $schema: {
+          version: VERSION,
+          description: t('json_schema_description'),
+          fields: {
+            projectPath: t('json_field_projectPath'),
+            overallScore: t('json_field_overallScore'),
+            summary: {
+              description: t('json_field_summary'),
+              totalFiles: t('json_field_summary_totalFiles'),
+              analyzedFiles: t('json_field_summary_analyzedFiles'),
+              skippedFiles: t('json_field_summary_skippedFiles'),
+              analysisTime: t('json_field_summary_analysisTime'),
+            },
+            aggregatedMetrics: {
+              description: t('json_field_aggregatedMetrics'),
+              name: t('json_field_aggregatedMetrics_name'),
+              category: t('json_field_aggregatedMetrics_category'),
+              average: t('json_field_aggregatedMetrics_average'),
+              min: t('json_field_aggregatedMetrics_min'),
+              max: t('json_field_aggregatedMetrics_max'),
+              median: t('json_field_aggregatedMetrics_median'),
+            },
+            files: {
+              description: t('json_field_files'),
+              path: t('json_field_files_path'),
+              score: t('json_field_files_score'),
+              metrics: {
+                description: t('json_field_files_metrics'),
+                name: t('json_field_files_metrics_name'),
+                category: t('json_field_files_metrics_category'),
+                value: t('json_field_files_metrics_value'),
+                normalizedScore: t('json_field_files_metrics_normalizedScore'),
+                severity: t('json_field_files_metrics_severity'),
+                details: t('json_field_files_metrics_details'),
+              },
+              parseResult: {
+                description: t('json_field_files_parseResult'),
+                language: t('json_field_files_parseResult_language'),
+                totalLines: t('json_field_files_parseResult_totalLines'),
+                codeLines: t('json_field_files_parseResult_codeLines'),
+                commentLines: t('json_field_files_parseResult_commentLines'),
+                functionCount: t('json_field_files_parseResult_functionCount'),
+                classCount: t('json_field_files_parseResult_classCount'),
+              },
+            },
+          },
+          metricCategories: {
+            complexity: t('json_category_complexity'),
+            size: t('json_category_size'),
+            duplication: t('json_category_duplication'),
+            structure: t('json_category_structure'),
+            error: t('json_category_error'),
+            documentation: t('json_category_documentation'),
+            naming: t('json_category_naming'),
+          },
+          severityLevels: {
+            info: t('json_severity_info'),
+            warning: t('json_severity_warning'),
+            error: t('json_severity_error'),
+            critical: t('json_severity_critical'),
+          },
+        },
         projectPath: result.projectPath,
         overallScore: result.overallScore,
         summary: {

src/cli/output/json.ts

@@ -9,7 +9,7 @@ import type { AIConfig } from '../ai/types.js';
 export const configSchema = z.object({
   exclude: z.array(z.string()).optional().default([]),
   include: z.array(z.string()).optional().default(['**/*']),
-  concurrency: z.number().min(1).max(32).optional().default(8),
+  concurrency: z.number().min(1).max(32).optional().default(2),
   verbose: z.boolean().optional().default(false),
   output: z
     .object({
@@ -68,7 +68,7 @@ export interface RuntimeConfig extends Config {
 export const DEFAULT_CONFIG: Config = {
   exclude: [],
   include: ['**/*'],
-  concurrency: 8,
+  concurrency: 2,
   verbose: false,
   output: {
     format: 'console',

src/config/schema.ts

@@ -382,5 +382,49 @@
   "update_updating": "Updating eff-u-code...",
   "update_success": "Update successful!",
   "update_updated_to": "Updated to version",
-  "update_failed": "Update failed"
+  "update_failed": "Update failed",
+
+  "json_schema_description": "Code quality analysis report in JSON format",
+  "json_field_projectPath": "Absolute path to the analyzed project",
+  "json_field_overallScore": "Overall quality score (0-100, higher is better)",
+  "json_field_summary": "Summary statistics of the analysis",
+  "json_field_summary_totalFiles": "Total number of files discovered in the project",
+  "json_field_summary_analyzedFiles": "Number of files successfully analyzed",
+  "json_field_summary_skippedFiles": "Number of files skipped (too large, unsupported, etc.)",
+  "json_field_summary_analysisTime": "Total analysis time in milliseconds",
+  "json_field_aggregatedMetrics": "Aggregated metrics across all analyzed files",
+  "json_field_aggregatedMetrics_name": "Metric name (e.g., cyclomatic_complexity, cognitive_complexity)",
+  "json_field_aggregatedMetrics_category": "Metric category (complexity, size, duplication, structure, error, documentation, naming)",
+  "json_field_aggregatedMetrics_average": "Average score across all files (0-100)",
+  "json_field_aggregatedMetrics_min": "Minimum score among all files (0-100)",
+  "json_field_aggregatedMetrics_max": "Maximum score among all files (0-100)",
+  "json_field_aggregatedMetrics_median": "Median score across all files (0-100)",
+  "json_field_files": "Detailed analysis results for each file",
+  "json_field_files_path": "Relative path to the file from project root",
+  "json_field_files_score": "Overall quality score for this file (0-100)",
+  "json_field_files_metrics": "Detailed metrics for this file",
+  "json_field_files_metrics_name": "Metric name",
+  "json_field_files_metrics_category": "Metric category",
+  "json_field_files_metrics_value": "Raw metric value (e.g., complexity count, line count)",
+  "json_field_files_metrics_normalizedScore": "Normalized score (0-100, higher is better)",
+  "json_field_files_metrics_severity": "Issue severity (info, warning, error, critical)",
+  "json_field_files_metrics_details": "Human-readable details about the metric",
+  "json_field_files_parseResult": "Parse result for this file",
+  "json_field_files_parseResult_language": "Programming language detected",
+  "json_field_files_parseResult_totalLines": "Total lines including blank and comment lines",
+  "json_field_files_parseResult_codeLines": "Lines of actual code",
+  "json_field_files_parseResult_commentLines": "Lines of comments",
+  "json_field_files_parseResult_functionCount": "Number of functions/methods found",
+  "json_field_files_parseResult_classCount": "Number of classes/structs found",
+  "json_category_complexity": "Code complexity metrics (cyclomatic, cognitive, nesting)",
+  "json_category_size": "Size metrics (function length, file length, parameter count)",
+  "json_category_duplication": "Code duplication detection",
+  "json_category_structure": "Code structure analysis (nesting levels, organization)",
+  "json_category_error": "Error handling quality",
+  "json_category_documentation": "Comment and documentation coverage",
+  "json_category_naming": "Naming convention compliance",
+  "json_severity_info": "No issues detected, code quality is good",
+  "json_severity_warning": "Minor issues that should be addressed",
+  "json_severity_error": "Significant issues that need attention",
+  "json_severity_critical": "Critical issues that must be fixed"
 }

src/i18n/locales/en.json

@@ -382,5 +382,49 @@
   "update_updating": "Обновление eff-u-code...",
   "update_success": "Обновление успешно!",
   "update_updated_to": "Обновлено до версии",
-  "update_failed": "Обновление не удалось"
+  "update_failed": "Обновление не удалось",
+
+  "json_schema_description": "Отчет об анализе качества кода в формате JSON",
+  "json_field_projectPath": "Абсолютный путь к анализируемому проекту",
+  "json_field_overallScore": "Общая оценка качества (0-100, чем выше, тем лучше)",
+  "json_field_summary": "Сводная статистика анализа",
+  "json_field_summary_totalFiles": "Общее количество файлов, обнаруженных в проекте",
+  "json_field_summary_analyzedFiles": "Количество успешно проанализированных файлов",
+  "json_field_summary_skippedFiles": "Количество пропущенных файлов (слишком большие, неподдерживаемые и т.д.)",
+  "json_field_summary_analysisTime": "Общее время анализа в миллисекундах",
+  "json_field_aggregatedMetrics": "Агрегированные метрики по всем проанализированным файлам",
+  "json_field_aggregatedMetrics_name": "Название метрики (например, cyclomatic_complexity, cognitive_complexity)",
+  "json_field_aggregatedMetrics_category": "Категория метрики (complexity, size, duplication, structure, error, documentation, naming)",
+  "json_field_aggregatedMetrics_average": "Средняя оценка по всем файлам (0-100)",
+  "json_field_aggregatedMetrics_min": "Минимальная оценка среди всех файлов (0-100)",
+  "json_field_aggregatedMetrics_max": "Максимальная оценка среди всех файлов (0-100)",
+  "json_field_aggregatedMetrics_median": "Медианная оценка по всем файлам (0-100)",
+  "json_field_files": "Подробные результаты анализа для каждого файла",
+  "json_field_files_path": "Относительный путь к файлу от корня проекта",
+  "json_field_files_score": "Общая оценка качества для этого файла (0-100)",
+  "json_field_files_metrics": "Подробные метрики для этого файла",
+  "json_field_files_metrics_name": "Название метрики",
+  "json_field_files_metrics_category": "Категория метрики",
+  "json_field_files_metrics_value": "Исходное значение метрики (например, количество сложности, количество строк)",
+  "json_field_files_metrics_normalizedScore": "Нормализованная оценка (0-100, чем выше, тем лучше)",
+  "json_field_files_metrics_severity": "Серьезность проблемы (info, warning, error, critical)",
+  "json_field_files_metrics_details": "Читаемые детали о метрике",
+  "json_field_files_parseResult": "Результат парсинга для этого файла",
+  "json_field_files_parseResult_language": "Обнаруженный язык программирования",
+  "json_field_files_parseResult_totalLines": "Общее количество строк, включая пустые и комментарии",
+  "json_field_files_parseResult_codeLines": "Строки фактического кода",
+  "json_field_files_parseResult_commentLines": "Строки комментариев",
+  "json_field_files_parseResult_functionCount": "Количество найденных функций/методов",
+  "json_field_files_parseResult_classCount": "Количество найденных классов/структур",
+  "json_category_complexity": "Метрики сложности кода (цикломатическая, когнитивная, глубина вложенности)",
+  "json_category_size": "Метрики размера (длина функции, длина файла, количество параметров)",
+  "json_category_duplication": "Обнаружение дублирования кода",
+  "json_category_structure": "Анализ структуры кода (уровни вложенности, организация)",
+  "json_category_error": "Качество обработки ошибок",
+  "json_category_documentation": "Покрытие комментариями и документацией",
+  "json_category_naming": "Соответствие соглашениям об именовании",
+  "json_severity_info": "Проблем не обнаружено, качество кода хорошее",
+  "json_severity_warning": "Незначительные проблемы, которые следует устранить",
+  "json_severity_error": "Значительные проблемы, требующие внимания",
+  "json_severity_critical": "Критические проблемы, которые необходимо исправить"
 }