@equilateral_ai/mindmeld 3.5.3 → 4.0.1

package/src/handlers/analytics/coachingGet.js

@@ -1,361 +0,0 @@
-/**
- * Developer Coaching Recommendations Handler
- * LLM-powered coaching insights per developer
- *
- * GET /api/analytics/coaching?user_id=xxx&project_id=xxx
- * Query params:
- *   - user_id (required) - Developer email to generate coaching for
- *   - project_id (required) - Project to scope coaching data
- *
- * Returns:
- *   - user_email: developer email
- *   - recommendations: LLM-generated coaching items with categories and evidence
- *   - strengths: identified developer strengths
- *   - generated_at: timestamp
- *
- * Auth: Cognito JWT required, Manager or Admin role (or self)
- */
-
-const { wrapHandler, executeQuery, createSuccessResponse, createErrorResponse } = require('./helpers');
-const { LLMPatternDetector } = require('./core/LLMPatternDetector');
-
-async function getCoachingRecommendations({ requestContext, queryStringParameters }) {
-    const email = requestContext.authorizer?.claims?.email || requestContext.authorizer?.jwt?.claims?.email;
-
-    if (!email) {
-        return createErrorResponse(401, 'Unauthorized');
-    }
-
-    const params = queryStringParameters || {};
-    const projectId = params.project_id;
-    const targetUserId = params.user_id;
-
-    if (!projectId) {
-        return createErrorResponse(400, 'project_id is required');
-    }
-
-    if (!targetUserId) {
-        return createErrorResponse(400, 'user_id is required');
-    }
-
-    // Check access: self-access or manager/admin
-    const isSelf = email.toLowerCase() === targetUserId.toLowerCase();
-
-    if (!isSelf) {
-        const accessCheck = await executeQuery(`
-            SELECT ue.company_id
-            FROM rapport.user_entitlements ue
-            JOIN rapport.projects p ON p.company_id = ue.company_id
-            WHERE ue.email_address = $1
-            AND p.project_id = $2
-            AND (ue.admin = true OR ue.manager = true)
-            LIMIT 1
-        `, [email, projectId]);
-
-        if (accessCheck.rows.length === 0) {
-            return createErrorResponse(403, 'Manager or Admin access required to view other developers');
-        }
-    }
-
-    // Verify target user exists and belongs to the project's company
-    const userResult = await executeQuery(`
-        SELECT
-            u.email_address as user_email,
-            CONCAT(u.first_name, ' ', u.last_name) as display_name
-        FROM rapport.users u
-        JOIN rapport.user_entitlements ue ON ue.email_address = u.email_address
-        JOIN rapport.projects p ON p.company_id = ue.company_id
-        WHERE u.email_address = $1
-        AND p.project_id = $2
-        LIMIT 1
-    `, [targetUserId, projectId]);
-
-    if (userResult.rows.length === 0) {
-        return createErrorResponse(404, 'Developer not found in this project');
-    }
-
-    const targetUser = userResult.rows[0];
-
-    // Fetch violation data for the developer (last 90 days for comprehensive coaching)
-    const lookbackDate = new Date();
-    lookbackDate.setDate(lookbackDate.getDate() - 90);
-
-    const violationResult = await executeQuery(`
-        SELECT
-            pv.category,
-            pv.severity,
-            pv.description,
-            pv.standard_name,
-            pv.detected_at,
-            COUNT(*) OVER (PARTITION BY pv.category) as category_count
-        FROM rapport.pattern_violations pv
-        WHERE pv.developer_email = $1
-        AND pv.project_id = $2
-        AND pv.detected_at >= $3
-        ORDER BY pv.detected_at DESC
-    `, [targetUserId, projectId, lookbackDate]);
-
-    // Fetch pattern usage data
-    const patternResult = await executeQuery(`
-        SELECT
-            p.intent,
-            p.maturity,
-            COUNT(DISTINCT pu.session_id) as sessions_used,
-            MAX(pu.used_at) as last_used
-        FROM rapport.pattern_usage pu
-        JOIN rapport.patterns p ON pu.pattern_id = p.pattern_id
-        WHERE pu.email_address = $1
-        AND pu.project_id = $2
-        AND pu.used_at >= $3
-        GROUP BY p.intent, p.maturity
-        ORDER BY sessions_used DESC
-    `, [targetUserId, projectId, lookbackDate]);
-
-    // Fetch compliance metrics
-    const metricsResult = await executeQuery(`
-        SELECT
-            AVG(dm.compliance_score) as avg_compliance,
-            SUM(dm.commit_count) as total_commits,
-            SUM(dm.standards_compliant_commits) as compliant_commits
-        FROM rapport.developer_metrics dm
-        WHERE dm.developer_email = $1
-        AND dm.project_id = $2
-        AND dm.period_start >= $3
-    `, [targetUserId, projectId, lookbackDate]);
-
-    const metrics = metricsResult.rows[0] || {};
-    const violations = violationResult.rows;
-    const patterns = patternResult.rows;
-
-    // Attempt LLM-based coaching recommendations
-    let recommendations = [];
-    let strengths = [];
-
-    const detector = new LLMPatternDetector();
-
-    if (detector.isAvailable()) {
-        try {
-            const coachingResult = await generateLLMCoaching(detector, {
-                userEmail: targetUserId,
-                displayName: targetUser.display_name,
-                violations,
-                patterns,
-                metrics,
-                projectId
-            });
-
-            recommendations = coachingResult.recommendations || [];
-            strengths = coachingResult.strengths || [];
-        } catch (error) {
-            console.error('[CoachingGet] LLM coaching generation failed, falling back to rule-based:', error.message);
-            const fallback = generateRuleBasedCoaching(violations, patterns, metrics);
-            recommendations = fallback.recommendations;
-            strengths = fallback.strengths;
-        }
-    } else {
-        // Fallback: rule-based recommendations from violation patterns
-        const fallback = generateRuleBasedCoaching(violations, patterns, metrics);
-        recommendations = fallback.recommendations;
-        strengths = fallback.strengths;
-    }
-
-    return createSuccessResponse({
-        user_email: targetUser.user_email,
-        recommendations,
-        strengths,
-        generated_at: new Date().toISOString()
-    }, 'Coaching recommendations generated');
-}
-
-exports.handler = wrapHandler(getCoachingRecommendations);
-
-/**
- * Generate coaching recommendations using LLM
- */
-async function generateLLMCoaching(detector, context) {
-    const violationSummary = summarizeViolations(context.violations);
-    const patternSummary = summarizePatterns(context.patterns);
-    const complianceAvg = parseFloat(context.metrics.avg_compliance || 0).toFixed(1);
-
-    const transcript = `
-Developer Coaching Analysis for ${context.displayName || context.userEmail}:
-
-COMPLIANCE METRICS:
-- Average compliance score: ${complianceAvg}%
-- Total commits: ${context.metrics.total_commits || 0}
-- Standards-compliant commits: ${context.metrics.compliant_commits || 0}
-
-VIOLATIONS (last 90 days):
-${violationSummary}
-
-PATTERN USAGE (last 90 days):
-${patternSummary}
-
-Generate coaching recommendations with:
-1. Specific, actionable items categorized by area (security, performance, architecture, etc.)
-2. Priority level (high, medium, low) based on violation frequency and severity
-3. Suggested standards to review
-4. Evidence from their actual violation and pattern data
-5. Identified strengths based on pattern adoption and compliance
-
-Respond with JSON:
-{
-  "recommendations": [
-    {
-      "category": "category_name",
-      "priority": "high|medium|low",
-      "title": "Short coaching title",
-      "description": "Detailed coaching recommendation",
-      "suggested_standards": ["standard1", "standard2"],
-      "evidence": { "violations": 0, "most_recent": "date" }
-    }
-  ],
-  "strengths": ["Strength 1", "Strength 2"]
-}`;
-
-    const result = await detector.analyzeSessionTranscript(transcript, {
-        projectName: `Project ${context.projectId}`,
-        techStack: 'Node.js, AWS Lambda, PostgreSQL, React'
-    });
-
-    // Parse LLM response for coaching-specific format
-    if (result.success && result.recommendations) {
-        return {
-            recommendations: Array.isArray(result.recommendations)
-                ? result.recommendations.map(rec => ({
-                    category: rec.category || 'general',
-                    priority: rec.priority || 'medium',
-                    title: rec.title || rec.action || 'Recommendation',
-                    description: rec.description || rec.details || '',
-                    suggested_standards: rec.suggested_standards || [],
-                    evidence: rec.evidence || {}
-                }))
-                : [],
-            strengths: result.strengths || []
-        };
-    }
-
-    // If LLM returned patterns instead of coaching format, adapt
-    return generateRuleBasedCoaching(context.violations, context.patterns, context.metrics);
-}
-
-/**
- * Generate rule-based coaching recommendations from violation patterns
- */
-function generateRuleBasedCoaching(violations, patterns, metrics) {
-    const recommendations = [];
-    const strengths = [];
-
-    // Group violations by category
-    const violationsByCategory = {};
-    for (const v of violations) {
-        if (!violationsByCategory[v.category]) {
-            violationsByCategory[v.category] = [];
-        }
-        violationsByCategory[v.category].push(v);
-    }
-
-    // Generate recommendations from violations
-    for (const [category, categoryViolations] of Object.entries(violationsByCategory)) {
-        const count = categoryViolations.length;
-        const mostRecent = categoryViolations[0]?.detected_at;
-        const uniqueStandards = [...new Set(categoryViolations.map(v => v.standard_name).filter(Boolean))];
-
-        let priority = 'low';
-        if (count >= 5 || categoryViolations.some(v => v.severity === 'critical')) {
-            priority = 'high';
-        } else if (count >= 2 || categoryViolations.some(v => v.severity === 'warning')) {
-            priority = 'medium';
-        }
-
-        const titles = {
-            security: 'Improve security practices',
-            performance: 'Address performance anti-patterns',
-            database: 'Strengthen database access patterns',
-            api: 'Align with API design standards',
-            architecture: 'Follow architectural guidelines',
-            'error-handling': 'Enhance error handling consistency'
-        };
-
-        const descriptions = {
-            security: `This developer has ${count} security-related violation(s) in the last 90 days. Review input validation, secrets management, and authorization patterns.`,
-            performance: `${count} performance issue(s) detected. Focus on connection management, caching strategies, and avoiding runtime SSM lookups.`,
-            database: `${count} database-related violation(s) found. Ensure use of cached single client pattern and parameterized queries.`,
-            api: `${count} API design violation(s). Review response formatting, CORS configuration, and handler patterns.`,
-            architecture: `${count} architectural violation(s). Check adherence to business-scoped IDs, module boundaries, and code organization.`,
-            'error-handling': `${count} error handling issue(s). Ensure consistent use of wrapHandler and proper error response patterns.`
-        };
-
-        recommendations.push({
-            category,
-            priority,
-            title: titles[category] || `Improve ${category} practices`,
-            description: descriptions[category] || `This developer has ${count} violation(s) related to ${category} in the last 90 days.`,
-            suggested_standards: uniqueStandards.length > 0 ? uniqueStandards : [category],
-            evidence: {
-                violations: count,
-                most_recent: mostRecent ? new Date(mostRecent).toISOString().split('T')[0] : null
-            }
-        });
-    }
-
-    // Sort recommendations by priority
-    const priorityOrder = { high: 0, medium: 1, low: 2 };
-    recommendations.sort((a, b) => (priorityOrder[a.priority] || 2) - (priorityOrder[b.priority] || 2));
-
-    // Identify strengths from pattern usage
-    const highAdoptionPatterns = patterns.filter(p => parseInt(p.sessions_used) >= 5);
-    if (highAdoptionPatterns.length > 0) {
-        strengths.push(`Consistent use of ${highAdoptionPatterns.length} team pattern(s)`);
-    }
-
-    const validatedPatterns = patterns.filter(p => p.maturity === 'validated' || p.maturity === 'reinforced');
-    if (validatedPatterns.length > 0) {
-        strengths.push(`Active contributor to ${validatedPatterns.length} validated pattern(s)`);
-    }
-
-    const complianceScore = parseFloat(metrics.avg_compliance || 0);
-    if (complianceScore >= 80) {
-        strengths.push('Strong standards adherence above 80%');
-    }
-
-    const totalCommits = parseInt(metrics.total_commits || 0);
-    const compliantCommits = parseInt(metrics.compliant_commits || 0);
-    if (totalCommits > 0 && (compliantCommits / totalCommits) >= 0.9) {
-        strengths.push('Over 90% of commits meet standards compliance');
-    }
-
-    if (violations.length === 0 && totalCommits > 0) {
-        strengths.push('Zero violations in the last 90 days');
-    }
-
-    return { recommendations, strengths };
-}
-
-/**
- * Summarize violations for LLM context
- */
-function summarizeViolations(violations) {
-    if (violations.length === 0) return 'No violations detected in the last 90 days.';
-
-    const byCategory = {};
-    for (const v of violations) {
-        if (!byCategory[v.category]) byCategory[v.category] = 0;
-        byCategory[v.category]++;
-    }
-
-    return Object.entries(byCategory)
-        .map(([cat, count]) => `- ${cat}: ${count} violation(s)`)
-        .join('\n');
-}
-
-/**
- * Summarize patterns for LLM context
- */
-function summarizePatterns(patterns) {
-    if (patterns.length === 0) return 'No pattern usage recorded.';
-
-    return patterns.slice(0, 10)
-        .map(p => `- ${p.intent} (${p.maturity}): used in ${p.sessions_used} session(s)`)
-        .join('\n');
-}

package/src/handlers/analytics/convergenceGet.js

@@ -1,236 +0,0 @@
-/**
- * Team Convergence Analytics Handler
- * Measures how consistently team members adopt the same standards
- *
- * GET /api/analytics/convergence
- * Query: ?period=30d&Company_ID=xxx
- * Auth: Cognito JWT required, Manager or Admin role
- *
- * Returns convergence score, per-standard adoption rates,
- * per-developer alignment scores, and weekly trend.
- */
-
-const { wrapHandler, executeQuery, createSuccessResponse, createErrorResponse } = require('./helpers');
-
-async function getConvergence({ requestContext, queryStringParameters }) {
-    const email = requestContext.authorizer?.claims?.email || requestContext.authorizer?.jwt?.claims?.email;
-
-    if (!email) {
-        return createErrorResponse(401, 'Authentication required');
-    }
-
-    const params = queryStringParameters || {};
-    const period = params.period || '30d';
-    const companyId = params.Company_ID;
-
-    // Validate manager/admin access
-    const accessCheck = await executeQuery(`
-        SELECT ue.company_id
-        FROM rapport.user_entitlements ue
-        WHERE ue.email_address = $1
-        AND (ue.admin = true OR ue.manager = true)
-        ${companyId ? 'AND ue.company_id = $2' : ''}
-        LIMIT 1
-    `, companyId ? [email, companyId] : [email]);
-
-    if (accessCheck.rows.length === 0) {
-        return createErrorResponse(403, 'Manager or Admin access required for convergence analytics');
-    }
-
-    const userCompanyId = companyId || accessCheck.rows[0].company_id;
-    const periodDays = parsePeriod(period);
-    const periodStart = new Date();
-    periodStart.setDate(periodStart.getDate() - periodDays);
-
-    // Get all active developers (those with sessions in period)
-    let activeDevelopers = [];
-    try {
-        const devResult = await executeQuery(`
-            SELECT DISTINCT s.email_address
-            FROM rapport.sessions s
-            JOIN rapport.projects p ON s.project_id = p.project_id
-            WHERE p.company_id = $1
-            AND s.started_at >= $2
-            AND s.email_address IS NOT NULL
-        `, [userCompanyId, periodStart]);
-        activeDevelopers = devResult.rows.map(r => r.email_address);
-    } catch (e) {
-        console.log('[Convergence] Active developers query failed:', e.message);
-    }
-
-    if (activeDevelopers.length === 0) {
-        return createSuccessResponse({
-            convergence_score: 0,
-            trend: 'stable',
-            developer_count: 0,
-            standards_in_use: 0,
-            by_standard: [],
-            by_developer: [],
-            convergence_trend: []
-        }, 'No active developers in period');
-    }
-
-    // Per-standard adoption: how many active devs received each standard
-    let byStandard = [];
-    try {
-        const standardResult = await executeQuery(`
-            SELECT
-                ss.standard_id,
-                ss.standard_name,
-                COUNT(DISTINCT s.email_address) as developers_using,
-                COUNT(*) as total_injections,
-                ROUND(AVG(ss.relevance_score), 2) as avg_relevance
-            FROM rapport.session_standards ss
-            JOIN rapport.sessions s ON ss.session_id = s.session_id
-            JOIN rapport.projects p ON s.project_id = p.project_id
-            WHERE p.company_id = $1
-            AND ss.created_at >= $2
-            AND s.email_address IS NOT NULL
-            GROUP BY ss.standard_id, ss.standard_name
-            HAVING COUNT(DISTINCT s.email_address) >= 1
-            ORDER BY developers_using DESC, total_injections DESC
-        `, [userCompanyId, periodStart]);
-
-        byStandard = standardResult.rows.map(row => ({
-            standard_id: row.standard_id,
-            standard_name: row.standard_name,
-            adoption_rate: Math.round((parseInt(row.developers_using) / activeDevelopers.length) * 100),
-            developers_using: parseInt(row.developers_using),
-            total_injections: parseInt(row.total_injections),
-            avg_relevance: parseFloat(row.avg_relevance) || 0
-        }));
-    } catch (e) {
-        console.log('[Convergence] Per-standard query failed:', e.message);
-    }
-
-    // Per-developer: how many unique standards each dev uses
-    let byDeveloper = [];
-    try {
-        const devStandardsResult = await executeQuery(`
-            SELECT
-                s.email_address,
-                COALESCE(MAX(ue.display_name), s.email_address) as display_name,
-                COUNT(DISTINCT ss.standard_id) as unique_standards,
-                COUNT(*) as total_injections
-            FROM rapport.session_standards ss
-            JOIN rapport.sessions s ON ss.session_id = s.session_id
-            JOIN rapport.projects p ON s.project_id = p.project_id
-            LEFT JOIN rapport.user_entitlements ue ON s.email_address = ue.email_address AND ue.company_id = $1
-            WHERE p.company_id = $1
-            AND ss.created_at >= $2
-            AND s.email_address IS NOT NULL
-            GROUP BY s.email_address
-            ORDER BY unique_standards DESC
-        `, [userCompanyId, periodStart]);
-
-        const totalUniqueStandards = byStandard.length;
-
-        byDeveloper = devStandardsResult.rows.map(row => ({
-            email: row.email_address,
-            display_name: row.display_name,
-            unique_standards: parseInt(row.unique_standards),
-            total_injections: parseInt(row.total_injections),
-            alignment_score: totalUniqueStandards > 0
-                ? Math.round((parseInt(row.unique_standards) / totalUniqueStandards) * 100)
-                : 0
-        }));
-    } catch (e) {
-        console.log('[Convergence] Per-developer query failed:', e.message);
-    }
-
-    // Convergence score: average adoption rate across standards
-    // High score = most standards are used by most developers
-    const convergenceScore = byStandard.length > 0
-        ? Math.round(byStandard.reduce((sum, s) => sum + s.adoption_rate, 0) / byStandard.length)
-        : 0;
-
-    // Weekly convergence trend (last 8 weeks or period, whichever is shorter)
-    let convergenceTrend = [];
-    try {
-        const trendResult = await executeQuery(`
-            WITH weekly_adoption AS (
-                SELECT
-                    DATE_TRUNC('week', ss.created_at) as week,
-                    ss.standard_id,
-                    COUNT(DISTINCT s.email_address) as devs_using
-                FROM rapport.session_standards ss
-                JOIN rapport.sessions s ON ss.session_id = s.session_id
-                JOIN rapport.projects p ON s.project_id = p.project_id
-                WHERE p.company_id = $1
-                AND ss.created_at >= $2
-                AND s.email_address IS NOT NULL
-                GROUP BY DATE_TRUNC('week', ss.created_at), ss.standard_id
-            ),
-            weekly_devs AS (
-                SELECT
-                    DATE_TRUNC('week', s.started_at) as week,
-                    COUNT(DISTINCT s.email_address) as active_devs
-                FROM rapport.sessions s
-                JOIN rapport.projects p ON s.project_id = p.project_id
-                WHERE p.company_id = $1
-                AND s.started_at >= $2
-                AND s.email_address IS NOT NULL
-                GROUP BY DATE_TRUNC('week', s.started_at)
-            )
-            SELECT
-                wa.week,
-                ROUND(AVG(
-                    CASE WHEN wd.active_devs > 0
-                        THEN (wa.devs_using::numeric / wd.active_devs) * 100
-                        ELSE 0
-                    END
-                )) as score,
-                COUNT(DISTINCT wa.standard_id) as standards_count,
-                MAX(wd.active_devs) as developer_count
-            FROM weekly_adoption wa
-            JOIN weekly_devs wd ON wa.week = wd.week
-            GROUP BY wa.week
-            ORDER BY wa.week
-        `, [userCompanyId, periodStart]);
-
-        convergenceTrend = trendResult.rows.map(row => ({
-            week: row.week,
-            score: parseInt(row.score) || 0,
-            standards_count: parseInt(row.standards_count),
-            developer_count: parseInt(row.developer_count)
-        }));
-    } catch (e) {
-        console.log('[Convergence] Trend query failed:', e.message);
-    }
-
-    // Determine trend direction
-    let trend = 'stable';
-    if (convergenceTrend.length >= 2) {
-        const recent = convergenceTrend[convergenceTrend.length - 1].score;
-        const earlier = convergenceTrend[0].score;
-        if (recent > earlier + 5) trend = 'improving';
-        else if (recent < earlier - 5) trend = 'declining';
-    }
-
-    return createSuccessResponse({
-        convergence_score: convergenceScore,
-        trend,
-        developer_count: activeDevelopers.length,
-        standards_in_use: byStandard.length,
-        by_standard: byStandard,
-        by_developer: byDeveloper,
-        convergence_trend: convergenceTrend
-    }, 'Convergence analytics retrieved');
-}
-
-exports.handler = wrapHandler(getConvergence);
-
-function parsePeriod(period) {
-    const match = period.match(/^(\d+)([dwm])$/);
-    if (!match) return 30;
-
-    const [, num, unit] = match;
-    const n = parseInt(num);
-
-    switch (unit) {
-        case 'd': return n;
-        case 'w': return n * 7;
-        case 'm': return n * 30;
-        default: return 30;
-    }
-}