memento-mcp-server 1.15.0-c → 1.16.0-a

package/dist/services/quality-assurance/quality-evaluator.js

@@ -0,0 +1,256 @@
+/**
+ * Quality Evaluator
+ *
+ * 품질 평가 서비스
+ *
+ * 주요 기능:
+ * - 임계값 비교 및 품질 평가
+ * - 상태 결정: pass/warning/fail
+ * - 경고 정보 생성
+ *
+ * PRD FR-1.1: Evaluator 역할 - 임계값 비교 및 품질 평가
+ * PRD FR-4.2: 품질 측정 시 임계값을 검증해야 함
+ */
+import Database from 'better-sqlite3';
+import fsPromises from 'fs/promises';
+import path from 'path';
+import { QualityThresholdManager } from './quality-threshold-manager.js';
+import { logger } from '../../shared/utils/logger.js';
+/**
+ * Quality Evaluator
+ *
+ * PRD FR-1.1: Evaluator 역할 - 임계값 비교 및 품질 평가
+ */
+export class QualityEvaluator {
+    db;
+    thresholdManager;
+    constructor(db) {
+        this.db = db;
+        if (!db) {
+            throw new Error('Database instance is required');
+        }
+        this.thresholdManager = new QualityThresholdManager(db);
+    }
+    /**
+     * 단일 지표 평가
+     *
+     * @param namespace - 네임스페이스
+     * @param key - 지표 키
+     * @param value - 측정값
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @returns 지표 평가 결과
+     */
+    evaluateMetric(namespace, key, value, context = 'default') {
+        const validation = this.thresholdManager.validateThreshold(namespace, key, value, context);
+        let difference = null;
+        if (validation.threshold) {
+            if (validation.threshold.threshold_type === 'min') {
+                // min 타입: value - threshold_value (양수면 여유, 음수면 부족)
+                difference = value - validation.threshold.threshold_value;
+            }
+            else if (validation.threshold.threshold_type === 'max') {
+                // max 타입: threshold_value - value (양수면 여유, 음수면 부족)
+                difference = validation.threshold.threshold_value - value;
+            }
+        }
+        return {
+            namespace,
+            key,
+            value,
+            threshold: validation.threshold,
+            passed: validation.passed,
+            difference,
+            message: validation.message
+        };
+    }
+    /**
+     * 품질 지표 평가
+     *
+     * PRD FR-4.2: 품질 측정 시 임계값을 검증해야 함
+     *
+     * @param metrics - 수집된 품질 지표
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @returns 품질 평가 결과
+     */
+    async evaluateMetrics(metrics, context = 'default') {
+        const metricResults = [];
+        const warnings = [];
+        // 각 지표를 평가
+        for (const [key, value] of Object.entries(metrics.metrics)) {
+            const result = this.evaluateMetric(metrics.namespace, key, value, context);
+            metricResults.push(result);
+            // 임계값 미달 시 경고 추가
+            if (!result.passed && result.threshold) {
+                warnings.push({
+                    metric_key: key,
+                    value,
+                    threshold_value: result.threshold.threshold_value,
+                    difference: result.difference || 0,
+                    message: result.message
+                });
+            }
+        }
+        // 상태 결정
+        const passedCount = metricResults.filter(r => r.passed).length;
+        const failedCount = metricResults.filter(r => !r.passed).length;
+        const totalCount = metricResults.length;
+        // 상태 결정 로직:
+        // - pass: 모든 지표가 통과
+        // - warning: 일부 지표가 실패했지만 심각하지 않음 (임계값이 설정되지 않은 경우는 제외)
+        // - fail: 중요한 지표가 실패 (임계값이 설정된 지표 중 실패)
+        let status = 'pass';
+        if (failedCount > 0) {
+            // 임계값이 설정된 지표 중 실패한 것이 있으면 fail
+            const failedWithThreshold = metricResults.filter(r => !r.passed && r.threshold !== null).length;
+            if (failedWithThreshold > 0) {
+                status = 'fail';
+            }
+            else {
+                // 임계값이 설정되지 않은 지표만 실패한 경우는 warning
+                status = 'warning';
+            }
+        }
+        // 평가 결과 생성
+        const evaluationResult = {
+            namespace: metrics.namespace,
+            context,
+            status,
+            metricResults,
+            passedCount,
+            failedCount,
+            totalCount,
+            warnings,
+            evaluated_at: new Date().toISOString()
+        };
+        // PRD FR-4.2: 경고 로그 기록
+        if (warnings.length > 0) {
+            logger.warn(`품질 저하 감지: ${metrics.namespace} (${context})`, {
+                namespace: metrics.namespace,
+                context,
+                warnings: warnings.map(w => ({
+                    metric: w.metric_key,
+                    value: w.value,
+                    threshold: w.threshold_value,
+                    difference: w.difference
+                }))
+            });
+            // PRD FR-4.3: 구조화된 JSON 로그 파일 기록
+            await this.logWarningToFile(evaluationResult);
+        }
+        return evaluationResult;
+    }
+    /**
+     * 여러 네임스페이스의 품질 지표 평가
+     *
+     * @param metricsList - 수집된 품질 지표 목록
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @returns 품질 평가 결과 목록
+     */
+    async evaluateAllMetrics(metricsList, context = 'default') {
+        return Promise.all(metricsList.map(metrics => this.evaluateMetrics(metrics, context)));
+    }
+    /**
+     * 전체 상태 결정
+     *
+     * 여러 네임스페이스의 평가 결과를 종합하여 전체 상태를 결정
+     *
+     * @param evaluationResults - 평가 결과 목록
+     * @returns 전체 상태: 'pass', 'warning', 'fail'
+     */
+    determineOverallStatus(evaluationResults) {
+        if (evaluationResults.length === 0) {
+            return 'pass';
+        }
+        // fail이 하나라도 있으면 전체 fail
+        if (evaluationResults.some(r => r.status === 'fail')) {
+            return 'fail';
+        }
+        // warning이 하나라도 있으면 전체 warning
+        if (evaluationResults.some(r => r.status === 'warning')) {
+            return 'warning';
+        }
+        // 모두 pass면 전체 pass
+        return 'pass';
+    }
+    /**
+     * 경고 정보 생성
+     *
+     * PRD FR-4.2: 경고 로그에 상세 정보 포함 (지표명, 측정값, 임계값, 차이)
+     *
+     * @param evaluationResult - 평가 결과
+     * @returns 경고 정보 (JSON 형식)
+     */
+    generateWarningInfo(evaluationResult) {
+        if (evaluationResult.warnings.length === 0) {
+            return JSON.stringify({ warnings: [] });
+        }
+        const warningInfo = {
+            namespace: evaluationResult.namespace,
+            context: evaluationResult.context,
+            status: evaluationResult.status,
+            evaluated_at: evaluationResult.evaluated_at,
+            warnings: evaluationResult.warnings.map(w => ({
+                metric_key: w.metric_key,
+                value: w.value,
+                threshold_value: w.threshold_value,
+                threshold_type: evaluationResult.metricResults.find(r => r.key === w.metric_key)?.threshold?.threshold_type || 'unknown',
+                difference: w.difference,
+                message: w.message
+            }))
+        };
+        return JSON.stringify(warningInfo, null, 2);
+    }
+    /**
+     * 경고 로그를 파일에 기록
+     *
+     * PRD FR-4.3: 품질 저하 발생 시 구조화된 JSON 로그 기록
+     * `logs/quality-warnings-{date}.log` 형식으로 저장
+     *
+     * @param evaluationResult - 평가 결과
+     */
+    async logWarningToFile(evaluationResult) {
+        try {
+            const logDir = path.join(process.cwd(), 'logs');
+            // 로그 디렉토리 생성
+            try {
+                await fsPromises.access(logDir);
+            }
+            catch {
+                await fsPromises.mkdir(logDir, { recursive: true });
+            }
+            // 날짜별 로그 파일명 생성 (YYYY-MM-DD 형식)
+            const today = new Date().toISOString().split('T')[0];
+            const logFilePath = path.join(logDir, `quality-warnings-${today}.log`);
+            // 구조화된 JSON 로그 엔트리 생성
+            const logEntry = {
+                timestamp: evaluationResult.evaluated_at,
+                namespace: evaluationResult.namespace,
+                context: evaluationResult.context,
+                status: evaluationResult.status,
+                passed_count: evaluationResult.passedCount,
+                failed_count: evaluationResult.failedCount,
+                total_count: evaluationResult.totalCount,
+                warnings: evaluationResult.warnings.map(w => ({
+                    metric_key: w.metric_key,
+                    value: w.value,
+                    threshold_value: w.threshold_value,
+                    threshold_type: evaluationResult.metricResults.find(r => r.key === w.metric_key)?.threshold?.threshold_type || 'unknown',
+                    difference: w.difference,
+                    message: w.message
+                }))
+            };
+            // JSON Lines 형식으로 파일에 추가
+            const logLine = JSON.stringify(logEntry) + '\n';
+            await fsPromises.appendFile(logFilePath, logLine, 'utf-8');
+        }
+        catch (error) {
+            // 파일 로깅 실패는 콘솔 로거에 위임
+            logger.error('품질 경고 로그 파일 기록 실패', {
+                namespace: evaluationResult.namespace,
+                context: evaluationResult.context,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+}
+//# sourceMappingURL=quality-evaluator.js.map

package/dist/services/quality-assurance/quality-evaluator.js.map

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

package/dist/services/quality-assurance/quality-metrics-collector.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Quality Metrics Collector
+ *
+ * 품질 지표 수집 서비스
+ *
+ * 주요 기능:
+ * - 기존 품질 검증 시스템들을 호출하여 지표 수집
+ * - namespace 단위 수집 메서드 제공 (search, relation, consolidation, storage)
+ * - 수집된 지표를 구조화된 형태로 반환
+ *
+ * PRD FR-1.1: Collector 역할 - 품질 지표 수집 (기존 검증 시스템 호출)
+ */
+import Database from 'better-sqlite3';
+import { type SearchResult, type GroundTruth } from '../../test/helpers/search-quality-metrics.js';
+import { type SearchResultPair } from '../../test/helpers/vector-search-quality-metrics.js';
+import { type ExpectedRelation, type ExtractedRelation } from '../../domains/relation/services/relation-quality-validator.js';
+/**
+ * 품질 지표 수집 결과
+ */
+export interface CollectedMetrics {
+    /**
+     * 네임스페이스 (예: 'search', 'relation', 'consolidation', 'storage')
+     */
+    namespace: string;
+    /**
+     * 컨텍스트 (예: 'default', 'ci', 'nightly')
+     */
+    context: string;
+    /**
+     * 측정 시간
+     */
+    measured_at: string;
+    /**
+     * 지표 데이터 (키-값 쌍)
+     * 예: { 'precision_at_5': 0.85, 'recall_at_5': 0.72, ... }
+     */
+    metrics: Record<string, number>;
+    /**
+     * 메타데이터 (선택적)
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * 검색 품질 지표
+ */
+export interface SearchQualityMetrics {
+    precision_at_5?: number;
+    precision_at_10?: number;
+    recall_at_5?: number;
+    recall_at_10?: number;
+    ndcg_at_5?: number;
+    ndcg_at_10?: number;
+    mrr?: number;
+    kendalls_tau?: number;
+    top_5_retention?: number;
+    top_10_retention?: number;
+    vector_similarity_mean?: number;
+    vector_similarity_std?: number;
+    consolidation_score_mean?: number;
+    consolidation_score_std?: number;
+}
+/**
+ * 관계 추출 품질 지표
+ */
+export interface RelationQualityMetrics {
+    precision?: number;
+    recall?: number;
+    f1_score?: number;
+    true_positives?: number;
+    false_positives?: number;
+    false_negatives?: number;
+    confidence_compliance_rate?: number;
+    type_precision?: Record<string, number>;
+    type_recall?: Record<string, number>;
+    type_f1_score?: Record<string, number>;
+}
+/**
+ * Consolidation 점수 품질 지표
+ */
+export interface ConsolidationQualityMetrics {
+    score_stability?: number;
+    order_preservation?: number;
+    score_mean?: number;
+    score_std?: number;
+    kendalls_tau?: number;
+}
+/**
+ * 저장 품질 지표
+ */
+export interface StorageQualityMetrics {
+    duplication_rate?: number;
+    data_integrity?: number;
+    schema_compliance?: number;
+    data_loss_rate?: number;
+}
+/**
+ * Quality Metrics Collector
+ *
+ * PRD FR-1.1: Collector 역할 - 품질 지표 수집 (기존 검증 시스템 호출)
+ */
+export declare class QualityMetricsCollector {
+    private db;
+    constructor(db: Database.Database);
+    /**
+     * MRR (Mean Reciprocal Rank) 계산
+     * 첫 번째 관련 결과의 역순위의 평균
+     *
+     * @param queryResults 쿼리별 검색 결과
+     * @param groundTruths 쿼리별 Ground Truth
+     * @returns MRR (0-1)
+     */
+    private calculateMRR;
+    /**
+     * 검색 품질 지표 수집
+     *
+     * PRD FR-2.1: 검색 품질 지표 정의
+     * - Precision@K, Recall@K, NDCG@K, MRR, Kendall's Tau 등
+     *
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @param options - 옵션 (Ground Truth 데이터, 검색 결과 등)
+     * @returns 검색 품질 지표
+     *
+     * Note: Ground Truth 데이터가 제공되면 실제 측정을 수행하고,
+     * 없으면 기본값(0)을 반환합니다.
+     */
+    collectSearchMetrics(context?: string, options?: {
+        /**
+         * Ground Truth 데이터 (선택적)
+         * 제공되면 실제 측정을 수행합니다.
+         */
+        groundTruths?: GroundTruth[];
+        /**
+         * 검색 결과 (선택적)
+         * 쿼리 ID를 키로 하는 Map
+         */
+        queryResults?: Map<string, SearchResult[]>;
+        /**
+         * 순서 보존 검증용 검색 결과 쌍 (선택적)
+         * 벡터-only와 Consolidation 반영 후 결과 비교
+         */
+        searchResultPairs?: SearchResultPair[];
+    }): Promise<CollectedMetrics>;
+    /**
+     * 관계 추출 품질 지표 수집
+     *
+     * PRD FR-2.4: 관계 추출 품질 지표 정의
+     * - Precision, Recall, F1-Score, 관계 유형별 정확도
+     *
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @param options - 옵션 (예상 관계, 추출된 관계 등)
+     * @returns 관계 추출 품질 지표
+     *
+     * Note: 예상 관계와 추출된 관계가 제공되면 실제 측정을 수행하고,
+     * 없으면 기본값(0)을 반환합니다.
+     */
+    collectRelationMetrics(context?: string, options?: {
+        /**
+         * 예상 관계 목록 (Ground Truth, 선택적)
+         * 제공되면 실제 측정을 수행합니다.
+         */
+        expectedRelations?: ExpectedRelation[];
+        /**
+         * 추출된 관계 목록 (선택적)
+         * 제공되면 실제 측정을 수행합니다.
+         */
+        extractedRelations?: ExtractedRelation[];
+    }): Promise<CollectedMetrics>;
+    /**
+     * Consolidation 점수 품질 지표 수집
+     *
+     * PRD FR-2.5: Consolidation 점수 안정성 지표 정의
+     * - 점수 분포, 순서 보존 검증
+     *
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @param options - 옵션 (검색 결과 쌍, 점수 샘플 등)
+     * @returns Consolidation 점수 품질 지표
+     *
+     * Note: 검색 결과 쌍이나 점수 샘플이 제공되면 실제 측정을 수행하고,
+     * 없으면 기본값(0)을 반환합니다.
+     */
+    collectConsolidationMetrics(context?: string, options?: {
+        /**
+         * 순서 보존 검증용 검색 결과 쌍 (선택적)
+         * 벡터-only와 Consolidation 반영 후 결과 비교
+         */
+        searchResultPairs?: SearchResultPair[];
+        /**
+         * Consolidation 점수 샘플 (선택적)
+         * 점수 분포 분석을 위한 샘플 데이터
+         */
+        consolidationScores?: number[];
+    }): Promise<CollectedMetrics>;
+    /**
+     * 저장 품질 지표 수집
+     *
+     * PRD FR-2.5: 기억 저장 품질 지표 정의
+     * - 중복 비율, 데이터 무결성, 스키마 준수율, 데이터 손실률
+     *
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @returns 저장 품질 지표
+     */
+    collectStorageMetrics(context?: string): Promise<CollectedMetrics>;
+    /**
+     * 모든 네임스페이스의 품질 지표 수집
+     *
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @returns 모든 네임스페이스의 품질 지표
+     */
+    collectAllMetrics(context?: string): Promise<CollectedMetrics[]>;
+    /**
+     * 특정 네임스페이스의 품질 지표 수집
+     *
+     * @param namespace - 네임스페이스 ('search', 'relation', 'consolidation', 'storage')
+     * @param context - 컨텍스트 (기본값: 'default')
+     * @returns 품질 지표
+     */
+    collectMetricsByNamespace(namespace: string, context?: string): Promise<CollectedMetrics>;
+}
+//# sourceMappingURL=quality-metrics-collector.d.ts.map

package/dist/services/quality-assurance/quality-metrics-collector.d.ts.map

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