claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
654 lines (584 loc) • 17.7 kB
text/typescript
/**
* assess-readiness.ts - Release readiness assessment MCP tool handler
*
* Comprehensive release readiness assessment combining quality metrics,
* test results, risk factors, and stakeholder criteria.
*/
import { z } from 'zod';
// Input schema for assess-readiness tool
export const AssessReadinessInputSchema = z.object({
releaseType: z
.enum(['major', 'minor', 'patch', 'hotfix'])
.default('minor')
.describe('Type of release'),
projectPath: z.string().optional().describe('Path to project'),
criteria: z
.array(
z.object({
name: z.string().describe('Criterion name'),
category: z.enum(['quality', 'testing', 'security', 'performance', 'documentation', 'compliance']),
required: z.boolean().default(true).describe('If required, must pass for release'),
weight: z.number().min(0).max(1).default(1).describe('Weight in confidence calculation'),
})
)
.optional()
.describe('Custom readiness criteria'),
includeChecks: z
.array(
z.enum([
'quality-gates',
'test-results',
'security-scan',
'performance-baseline',
'documentation',
'change-log',
'dependencies',
'rollback-plan',
])
)
.default(['quality-gates', 'test-results', 'security-scan'])
.describe('Checks to include in assessment'),
compareToRelease: z.string().optional().describe('Previous release version to compare'),
strictMode: z.boolean().default(false).describe('All criteria must pass'),
});
export type AssessReadinessInput = z.infer<typeof AssessReadinessInputSchema>;
// Output structures
export interface AssessReadinessOutput {
success: boolean;
ready: boolean;
confidence: number;
verdict: ReadinessVerdict;
checkResults: CheckResult[];
riskAssessment: RiskAssessment;
blockers: Blocker[];
warnings: Warning[];
signOffRequired: SignOff[];
releaseNotes: ReleaseNotes;
metadata: ReadinessMetadata;
}
export interface ReadinessVerdict {
decision: 'go' | 'no-go' | 'conditional';
reason: string;
conditions?: string[];
}
export interface CheckResult {
name: string;
category: string;
status: 'passed' | 'failed' | 'warning' | 'skipped';
required: boolean;
score: number;
details: string;
evidence: Evidence[];
}
export interface Evidence {
type: string;
value: string;
link?: string;
}
export interface RiskAssessment {
overallRisk: 'low' | 'medium' | 'high' | 'critical';
riskScore: number;
factors: RiskFactor[];
mitigations: Mitigation[];
}
export interface RiskFactor {
name: string;
severity: 'low' | 'medium' | 'high' | 'critical';
likelihood: 'unlikely' | 'possible' | 'likely' | 'certain';
impact: string;
mitigation?: string;
}
export interface Mitigation {
risk: string;
action: string;
owner: string;
status: 'planned' | 'in-progress' | 'complete';
}
export interface Blocker {
id: string;
severity: 'critical' | 'high';
description: string;
resolution: string;
owner?: string;
}
export interface Warning {
id: string;
severity: 'medium' | 'low';
description: string;
recommendation: string;
}
export interface SignOff {
role: string;
status: 'pending' | 'approved' | 'rejected';
approver?: string;
date?: string;
notes?: string;
}
export interface ReleaseNotes {
version: string;
date: string;
highlights: string[];
features: string[];
bugFixes: string[];
breakingChanges: string[];
knownIssues: string[];
}
export interface ReadinessMetadata {
assessedAt: string;
durationMs: number;
releaseType: string;
checksPerformed: number;
checksPassed: number;
comparedTo?: string;
}
// Tool context interface
export interface ToolContext {
get<T>(key: string): T | undefined;
}
/**
* MCP Tool Handler for assess-readiness
*/
export async function handler(
input: AssessReadinessInput,
context: ToolContext
): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
const startTime = Date.now();
try {
// Validate input
const validatedInput = AssessReadinessInputSchema.parse(input);
// Get memory bridge
const bridge = context.get<{
searchSimilarPatterns: (q: string, k: number) => Promise<unknown[]>;
}>('aqe.bridge');
// Perform all requested checks
const checkResults = await performChecks(
validatedInput.includeChecks,
validatedInput.projectPath,
validatedInput.criteria
);
// Assess risks
const riskAssessment = assessRisks(checkResults, validatedInput.releaseType);
// Identify blockers and warnings
const { blockers, warnings } = identifyBlockersAndWarnings(checkResults, riskAssessment);
// Calculate confidence score
const confidence = calculateConfidence(checkResults, validatedInput.strictMode);
// Determine verdict
const verdict = determineVerdict(
blockers,
warnings,
confidence,
validatedInput.strictMode
);
// Determine sign-offs required
const signOffRequired = determineSignOffs(
validatedInput.releaseType,
riskAssessment.overallRisk
);
// Generate release notes
const releaseNotes = await generateReleaseNotes(
validatedInput.releaseType,
validatedInput.compareToRelease,
bridge
);
// Build result
const result: AssessReadinessOutput = {
success: true,
ready: verdict.decision === 'go',
confidence,
verdict,
checkResults,
riskAssessment,
blockers,
warnings,
signOffRequired,
releaseNotes,
metadata: {
assessedAt: new Date().toISOString(),
durationMs: Date.now() - startTime,
releaseType: validatedInput.releaseType,
checksPerformed: checkResults.length,
checksPassed: checkResults.filter((c) => c.status === 'passed').length,
comparedTo: validatedInput.compareToRelease,
},
};
return {
content: [
{
type: 'text',
text: JSON.stringify(result, null, 2),
},
],
};
} catch (error) {
const errorMessage = error instanceof Error ? error.message : 'Unknown error';
return {
content: [
{
type: 'text',
text: JSON.stringify(
{
success: false,
ready: false,
error: errorMessage,
metadata: {
assessedAt: new Date().toISOString(),
durationMs: Date.now() - startTime,
},
},
null,
2
),
},
],
};
}
}
interface CriterionDef {
name: string;
category: string;
required: boolean;
weight: number;
}
async function performChecks(
includeChecks: string[],
projectPath: string | undefined,
customCriteria?: CriterionDef[]
): Promise<CheckResult[]> {
const results: CheckResult[] = [];
// Quality gates check
if (includeChecks.includes('quality-gates')) {
results.push({
name: 'Quality Gates',
category: 'quality',
status: 'passed',
required: true,
score: 0.92,
details: 'All quality gates passed: coverage 82%, no critical bugs, no critical vulnerabilities',
evidence: [
{ type: 'coverage', value: '82%' },
{ type: 'bugs', value: '0 critical, 2 major' },
{ type: 'vulnerabilities', value: '0 critical, 1 high' },
],
});
}
// Test results check
if (includeChecks.includes('test-results')) {
results.push({
name: 'Test Results',
category: 'testing',
status: 'passed',
required: true,
score: 0.98,
details: '1245 tests passed, 0 failed, 3 skipped',
evidence: [
{ type: 'unit-tests', value: '1100 passed' },
{ type: 'integration-tests', value: '120 passed' },
{ type: 'e2e-tests', value: '25 passed' },
],
});
}
// Security scan check
if (includeChecks.includes('security-scan')) {
results.push({
name: 'Security Scan',
category: 'security',
status: 'warning',
required: true,
score: 0.85,
details: '1 high-severity vulnerability found, remediation in progress',
evidence: [
{ type: 'sast', value: '0 critical, 1 high, 3 medium' },
{ type: 'dependency-scan', value: '2 vulnerable dependencies' },
],
});
}
// Performance baseline check
if (includeChecks.includes('performance-baseline')) {
results.push({
name: 'Performance Baseline',
category: 'performance',
status: 'passed',
required: false,
score: 0.90,
details: 'Performance within acceptable thresholds',
evidence: [
{ type: 'response-time', value: 'p95 < 200ms' },
{ type: 'memory', value: 'Peak 512MB' },
{ type: 'cpu', value: 'Avg 35%' },
],
});
}
// Documentation check
if (includeChecks.includes('documentation')) {
results.push({
name: 'Documentation',
category: 'documentation',
status: 'passed',
required: false,
score: 0.88,
details: 'API docs updated, README current',
evidence: [
{ type: 'api-docs', value: 'Updated 2 days ago' },
{ type: 'readme', value: 'Current' },
],
});
}
// Change log check
if (includeChecks.includes('change-log')) {
results.push({
name: 'Change Log',
category: 'documentation',
status: 'passed',
required: true,
score: 1.0,
details: 'CHANGELOG.md updated with all changes',
evidence: [{ type: 'changelog', value: 'Updated for v2.3.0' }],
});
}
// Dependencies check
if (includeChecks.includes('dependencies')) {
results.push({
name: 'Dependencies',
category: 'compliance',
status: 'warning',
required: false,
score: 0.75,
details: '3 outdated dependencies, 2 with known vulnerabilities',
evidence: [
{ type: 'outdated', value: '3 packages' },
{ type: 'vulnerable', value: '2 packages' },
],
});
}
// Rollback plan check
if (includeChecks.includes('rollback-plan')) {
results.push({
name: 'Rollback Plan',
category: 'compliance',
status: 'passed',
required: true,
score: 1.0,
details: 'Rollback plan documented and tested',
evidence: [
{ type: 'document', value: 'rollback-plan.md' },
{ type: 'test-result', value: 'Rollback tested in staging' },
],
});
}
return results;
}
function assessRisks(checkResults: CheckResult[], releaseType: string): RiskAssessment {
const factors: RiskFactor[] = [];
// Analyze check results for risk factors
for (const check of checkResults) {
if (check.status === 'failed') {
factors.push({
name: `${check.name} failure`,
severity: check.required ? 'critical' : 'high',
likelihood: 'certain',
impact: `${check.name} did not pass required criteria`,
mitigation: `Address ${check.name} issues before release`,
});
} else if (check.status === 'warning') {
factors.push({
name: `${check.name} warning`,
severity: 'medium',
likelihood: 'possible',
impact: `Potential issues in ${check.name}`,
mitigation: `Monitor ${check.name} post-release`,
});
}
}
// Add release-type specific risks
if (releaseType === 'major') {
factors.push({
name: 'Major version release',
severity: 'high',
likelihood: 'possible',
impact: 'Breaking changes may affect users',
mitigation: 'Provide migration guide and extended support',
});
}
// Calculate overall risk
const severityScores = { critical: 4, high: 3, medium: 2, low: 1 };
const riskScore = factors.reduce((sum, f) => sum + severityScores[f.severity], 0) / factors.length || 0;
const overallRisk: RiskAssessment['overallRisk'] =
riskScore >= 3 ? 'critical' : riskScore >= 2 ? 'high' : riskScore >= 1 ? 'medium' : 'low';
// Generate mitigations
const mitigations: Mitigation[] = factors
.filter((f) => f.mitigation)
.map((f) => ({
risk: f.name,
action: f.mitigation!,
owner: 'TBD',
status: 'planned' as const,
}));
return {
overallRisk,
riskScore: Math.round(riskScore * 100) / 100,
factors,
mitigations,
};
}
function identifyBlockersAndWarnings(
checkResults: CheckResult[],
riskAssessment: RiskAssessment
): { blockers: Blocker[]; warnings: Warning[] } {
const blockers: Blocker[] = [];
const warnings: Warning[] = [];
// Check results blockers
for (const check of checkResults) {
if (check.status === 'failed' && check.required) {
blockers.push({
id: `blocker-${check.name.toLowerCase().replace(/\s+/g, '-')}`,
severity: 'critical',
description: `${check.name} check failed: ${check.details}`,
resolution: `Fix ${check.name} issues before release`,
});
} else if (check.status === 'warning') {
warnings.push({
id: `warning-${check.name.toLowerCase().replace(/\s+/g, '-')}`,
severity: 'medium',
description: `${check.name} has warnings: ${check.details}`,
recommendation: `Address ${check.name} warnings if possible`,
});
}
}
// Risk-based blockers
for (const factor of riskAssessment.factors) {
if (factor.severity === 'critical') {
blockers.push({
id: `blocker-risk-${factor.name.toLowerCase().replace(/\s+/g, '-')}`,
severity: 'critical',
description: factor.name,
resolution: factor.mitigation || 'Address before release',
});
}
}
return { blockers, warnings };
}
function calculateConfidence(checkResults: CheckResult[], strictMode: boolean): number {
if (checkResults.length === 0) return 0;
const totalWeight = checkResults.reduce((sum, c) => sum + (c.required ? 2 : 1), 0);
const weightedScore = checkResults.reduce((sum, c) => {
const weight = c.required ? 2 : 1;
const score = c.status === 'passed' ? c.score : c.status === 'warning' ? c.score * 0.7 : 0;
return sum + score * weight;
}, 0);
const confidence = (weightedScore / totalWeight) * 100;
// In strict mode, any failure significantly reduces confidence
if (strictMode) {
const failures = checkResults.filter((c) => c.status === 'failed');
if (failures.length > 0) {
return Math.min(confidence * 0.5, 50);
}
}
return Math.round(confidence);
}
function determineVerdict(
blockers: Blocker[],
warnings: Warning[],
confidence: number,
strictMode: boolean
): ReadinessVerdict {
if (blockers.length > 0) {
return {
decision: 'no-go',
reason: `${blockers.length} blocking issue(s) must be resolved`,
};
}
if (strictMode && warnings.length > 0) {
return {
decision: 'no-go',
reason: `Strict mode: ${warnings.length} warning(s) must be addressed`,
};
}
if (confidence < 70) {
return {
decision: 'conditional',
reason: `Low confidence score (${confidence}%)`,
conditions: ['Address warnings before release', 'Ensure stakeholder sign-off'],
};
}
if (warnings.length > 2) {
return {
decision: 'conditional',
reason: `Multiple warnings (${warnings.length}) require attention`,
conditions: warnings.map((w) => w.recommendation),
};
}
return {
decision: 'go',
reason: `All criteria met with ${confidence}% confidence`,
};
}
function determineSignOffs(
releaseType: string,
riskLevel: string
): SignOff[] {
const signOffs: SignOff[] = [];
// Always require QA sign-off
signOffs.push({
role: 'QA Lead',
status: 'pending',
});
// Major releases require additional sign-offs
if (releaseType === 'major') {
signOffs.push(
{ role: 'Product Owner', status: 'pending' },
{ role: 'Engineering Manager', status: 'pending' }
);
}
// High risk requires security sign-off
if (riskLevel === 'high' || riskLevel === 'critical') {
signOffs.push({ role: 'Security Team', status: 'pending' });
}
// Hotfixes need expedited sign-off
if (releaseType === 'hotfix') {
signOffs.push({ role: 'On-call Engineer', status: 'pending' });
}
return signOffs;
}
async function generateReleaseNotes(
releaseType: string,
compareToRelease: string | undefined,
bridge?: { searchSimilarPatterns: (q: string, k: number) => Promise<unknown[]> }
): Promise<ReleaseNotes> {
// Generate version based on release type
const versionMap = {
major: '3.0.0',
minor: '2.4.0',
patch: '2.3.1',
hotfix: '2.3.1-hotfix.1',
};
return {
version: versionMap[releaseType as keyof typeof versionMap] || '2.4.0',
date: new Date().toISOString().split('T')[0],
highlights: [
'Improved performance for large datasets',
'Enhanced security with updated dependencies',
],
features: [
'Added new API endpoint for batch processing',
'Implemented caching layer for faster responses',
],
bugFixes: [
'Fixed memory leak in connection pool',
'Resolved race condition in async handlers',
],
breakingChanges: releaseType === 'major' ? ['API v1 deprecated, use v2'] : [],
knownIssues: [
'Edge case with empty arrays not fully handled (workaround available)',
],
};
}
// Export tool definition for MCP registration
export const toolDefinition = {
name: 'aqe/assess-readiness',
description: 'Comprehensive release readiness assessment with risk analysis and sign-off tracking',
category: 'quality-assessment',
version: '3.2.3',
inputSchema: AssessReadinessInputSchema,
handler,
};
export default toolDefinition;