tech-stack-evaluator（技术堆栈评估器）

Technology Stack Evaluator

Evaluate and compare technologies, frameworks, and cloud providers with data-driven analysis and actionable recommendations.

Table of Contents

• Capabilities
• Quick Start
• Input Formats
• Analysis Types
• Scripts
• References

Capabilities

Quick Start

Compare Two Technologies

Compare React vs Vue for a SaaS dashboard.
Priorities: developer productivity (40%), ecosystem (30%), performance (30%).

Calculate TCO

Calculate 5-year TCO for Next.js on Vercel.
Team: 8 developers. Hosting: $2500/month. Growth: 40%/year.

Assess Migration

Evaluate migrating from Angular.js to React.
Codebase: 50,000 lines, 200 components. Team: 6 developers.

Input Formats

The evaluator accepts three input formats:

Text - Natural language queries

Compare PostgreSQL vs MongoDB for our e-commerce platform.

YAML - Structured input for automation

comparison:
  technologies: ["React", "Vue"]
  use_case: "SaaS dashboard"
  weights:
    ecosystem: 30
    performance: 25
    developer_experience: 45

JSON - Programmatic integration

{
  "technologies": ["React", "Vue"],
  "use_case": "SaaS dashboard"
}

Analysis Types

Quick Comparison (200-300 tokens)

• Weighted scores and recommendation
• Top 3 decision factors
• Confidence level

Standard Analysis (500-800 tokens)

• Comparison matrix
• TCO overview
• Security summary

Full Report (1200-1500 tokens)

• All metrics and calculations
• Migration analysis
• Detailed recommendations

Scripts

stack_comparator.py

Compare technologies with customizable weighted criteria.

python scripts/stack_comparator.py --help

tco_calculator.py

Calculate total cost of ownership over multi-year projections.

python scripts/tco_calculator.py --input assets/sample_input_tco.json

ecosystem_analyzer.py

Analyze ecosystem health from GitHub, npm, and community metrics.

python scripts/ecosystem_analyzer.py --technology react

security_assessor.py

Evaluate security posture and compliance readiness.

python scripts/security_assessor.py --technology express --compliance soc2,gdpr

migration_analyzer.py

Estimate migration complexity, effort, and risks.

python scripts/migration_analyzer.py --from angular-1.x --to react

References

Confidence Levels

When to Use

• Comparing frontend/backend frameworks for new projects
• Evaluating cloud providers for specific workloads
• Planning technology migrations with risk assessment
• Calculating build vs. buy decisions with TCO
• Assessing open-source library viability

When NOT to Use

• Trivial decisions between similar tools (use team preference)
• Mandated technology choices (decision already made)
• Emergency production issues (use monitoring tools)

Troubleshooting

Success Criteria

• TCO variance under 15%: Calculated TCO deviates less than 15% from actual costs when validated against real-world spending data over the projection period.
• Security score above 80/100: Technologies recommended for production use achieve a minimum overall security score of 80, corresponding to grade B or higher.
• Ecosystem health score above 65/100: Recommended technologies demonstrate viable long-term ecosystem health with a risk level no worse than "Low-Medium."
• Migration effort estimate within 20%: Person-hours and timeline estimates land within 20% of actual migration effort when measured post-completion.
• Comparison confidence above 70%: Final technology recommendations carry a confidence score of 70% or higher, indicating a meaningful score gap between top candidates.
• Compliance readiness at "Mostly Ready" or above: Technologies targeting regulated environments achieve at least 70% feature coverage against required compliance standards (GDPR, SOC2, HIPAA, PCI-DSS).
• Report generation under 5 seconds: All report types (executive summary, full report) render within 5 seconds for evaluations comparing up to 5 technologies.

Scope & Limitations

Covers:

• Weighted multi-criteria comparison of frameworks, libraries, and cloud providers
• Multi-year TCO projections including hidden costs (technical debt, vendor lock-in, turnover)
• Ecosystem viability assessment using GitHub, npm, and community metrics
• Security posture scoring and compliance readiness for GDPR, SOC2, HIPAA, PCI-DSS

Does NOT cover:

• Live data fetching from GitHub API, npm registry, or vulnerability databases (all data must be provided as input dictionaries)
• Performance benchmarking or load testing (use engineering/senior-qa for test execution)
• Licensing legal review or contract negotiation (use ra-qm-team compliance skills for regulatory guidance)
• Team hiring or organizational design decisions (use hr-operations/talent-acquisition for staffing analysis)

Integration Points

Tool Reference

stack_comparator.py

Purpose: Compare technologies with customizable weighted criteria across 8 evaluation categories: performance, scalability, developer experience, ecosystem, learning curve, documentation, community support, and enterprise readiness.

Usage:

from stack_comparator import StackComparator

comparator = StackComparator({
    "technologies": ["React", "Vue"],
    "use_case": "SaaS dashboard",
    "weights": {"developer_experience": 40, "performance": 30, "ecosystem": 30}
})

results = comparator.compare_technologies(tech_data_list)

Constructor Parameters (comparison_data dict):

Default Weights: performance 15, scalability 15, developer_experience 20, ecosystem 15, learning_curve 10, documentation 10, community_support 10, enterprise_readiness 5.

Key Methods:

• compare_technologies(tech_data_list) -- Full comparison with scores, recommendation, confidence, and decision factors
• score_technology(tech_name, tech_data) -- Score a single technology across all categories
• calculate_weighted_score(category_scores) -- Calculate weighted total from category scores
• generate_pros_cons(tech_name, tech_scores) -- Generate pros/cons lists from scores

Example Output:

{
  "technologies": {"React": {"weighted_total": 78.5, "strengths": [...], "weaknesses": [...]}},
  "recommendation": "React",
  "confidence": 72.0,
  "decision_factors": [{"category": "developer_experience", "importance": "40.0%", "best_performer": "React"}],
  "comparison_matrix": [{"category": "performance", "weight": "15.0%", "scores": {"React": "82.0", "Vue": "79.0"}}]
}

Output Format: Python dictionary (serialize with json.dumps() for JSON output).

tco_calculator.py

Purpose: Calculate comprehensive Total Cost of Ownership over multi-year projections, including initial costs, operational costs, scaling costs, hidden costs (technical debt, vendor lock-in, security incidents, downtime, turnover), and developer productivity impact.

Usage:

from tco_calculator import TCOCalculator

calculator = TCOCalculator({
    "technology": "Next.js",
    "team_size": 8,
    "timeline_years": 5,
    "initial_costs": {"licensing": 0, "migration": 15000, "developer_hourly_rate": 100},
    "operational_costs": {"monthly_hosting": 2500, "annual_licensing": 0, "maintenance_hours_per_dev_monthly": 20},
    "scaling_params": {"annual_growth_rate": 0.40, "initial_users": 5000}
})

tco = calculator.calculate_total_tco()
summary = calculator.generate_tco_summary()

Constructor Parameters (tco_data dict):

Key Methods:

• calculate_total_tco() -- Complete TCO with all cost components
• generate_tco_summary() -- Executive summary with formatted dollar amounts
• calculate_initial_costs() -- One-time cost breakdown
• calculate_operational_costs() -- Year-by-year operational costs
• calculate_scaling_costs() -- User projections and cost-per-user analysis
• calculate_hidden_costs() -- Technical debt, vendor lock-in, security, downtime, turnover
• calculate_productivity_impact() -- Productivity gains and feature velocity

Output Format: Python dictionary (all monetary values as floats; generate_tco_summary() returns pre-formatted dollar strings).

ecosystem_analyzer.py

Purpose: Analyze technology ecosystem health and long-term viability by scoring GitHub activity, npm adoption, community strength, corporate backing, and maintenance responsiveness on a 0-100 scale.

Usage:

from ecosystem_analyzer import EcosystemAnalyzer

analyzer = EcosystemAnalyzer({
    "technology": "React",
    "github": {"stars": 220000, "forks": 45000, "contributors": 1500, "commits_last_month": 120},
    "npm": {"weekly_downloads": 20000000, "version": "18.2.0", "dependencies_count": 3},
    "community": {"stackoverflow_questions": 400000, "job_postings": 15000},
    "corporate_backing": {"type": "major_tech_company"}
})

report = analyzer.generate_ecosystem_report()
viability = analyzer.assess_viability()

Constructor Parameters (ecosystem_data dict):

Health Score Weights: github_health 25%, npm_health 20%, community_health 20%, corporate_backing 15%, maintenance_health 20%.

Key Methods:

• generate_ecosystem_report() -- Complete report with health scores, viability, and formatted metrics
• calculate_health_score() -- Component scores and weighted overall score
• assess_viability() -- Viability level, risk assessment, strengths, and recommendation

Output Format: Python dictionary with nested health scores, viability assessment, and formatted metrics.

security_assessor.py

Purpose: Evaluate security posture and compliance readiness for technology stacks. Scores vulnerabilities, patch responsiveness, built-in security features, and track record. Assesses compliance against GDPR, SOC2, HIPAA, and PCI-DSS.

Usage:

from security_assessor import SecurityAssessor

assessor = SecurityAssessor({
    "technology": "Express",
    "vulnerabilities": {
        "critical_last_12m": 0, "high_last_12m": 2,
        "avg_critical_patch_days": 7, "has_security_team": True
    },
    "security_features": {
        "encryption_in_transit": True, "authentication": True,
        "input_validation": True, "csrf_protection": True
    },
    "compliance_requirements": ["SOC2", "GDPR"]
})

report = assessor.generate_security_report()
compliance = assessor.assess_compliance(["SOC2", "GDPR"])

Constructor Parameters (security_data dict):

Security Score Weights: vulnerability_score 30%, patch_responsiveness 25%, security_features 30%, track_record 15%.

Key Methods:

• generate_security_report() -- Full report with score, compliance, vulnerabilities, and recommendations
• calculate_security_score() -- Component scores with letter grade (A-F)
• assess_compliance(standards) -- Per-standard readiness with missing features list
• identify_vulnerabilities() -- Categorized vulnerability report with trend analysis

Output Format: Python dictionary with security scores, compliance assessments, and risk level.

migration_analyzer.py

Purpose: Analyze migration complexity, estimate effort in person-hours and calendar months, assess technical/business/team risks, and recommend a migration approach (direct, phased, or strangler pattern) based on complexity scoring.

Usage:

from migration_analyzer import MigrationAnalyzer

analyzer = MigrationAnalyzer({
    "source_technology": "Angular 1.x",
    "target_technology": "React",
    "codebase_stats": {
        "lines_of_code": 50000, "num_components": 200,
        "architecture_change_level": "significant",
        "current_test_coverage": 0.6
    },
    "team": {"team_size": 6, "target_tech_experience": "low"},
    "constraints": {"downtime_tolerance": "low"}
})

plan = analyzer.generate_migration_plan()
effort = analyzer.estimate_effort()
risks = analyzer.assess_risks()

Constructor Parameters (migration_data dict):

Complexity Score Weights: code_volume 20%, architecture_changes 25%, data_migration 20%, api_compatibility 15%, dependency_changes 10%, testing_requirements 10%.

Key Methods:

• generate_migration_plan() -- Complete plan with complexity, effort, risks, approach, and success criteria
• calculate_complexity_score() -- Per-factor complexity scores (1-10 scale)
• estimate_effort() -- Person-hours, person-months, phase breakdown, and calendar timeline
• assess_risks() -- Technical, business, and team risks with severity and mitigation strategies

Output Format: Python dictionary with nested complexity analysis, effort estimation, risk assessment, and recommended approach.

report_generator.py

Purpose: Generate context-aware evaluation reports with progressive disclosure. Auto-detects output context (Claude Desktop vs CLI) and renders rich markdown tables or ASCII-formatted output accordingly. Supports selective section generation.

Usage:

from report_generator import ReportGenerator

generator = ReportGenerator(report_data, output_context="desktop")

executive_summary = generator.generate_executive_summary(max_tokens=300)
full_report = generator.generate_full_report(sections=["executive_summary", "comparison_matrix", "tco_analysis"])
generator.export_to_file("evaluation_report.md")

Constructor Parameters:

Available Report Sections: executive_summary, comparison_matrix, tco_analysis, ecosystem_health, security_assessment, migration_analysis, performance_benchmarks.

Key Methods:

• generate_executive_summary(max_tokens=300) -- Concise summary with recommendation, strengths, concerns, and decision factors
• generate_full_report(sections=None) -- Complete report with selected sections (all if None)
• export_to_file(filename, sections=None) -- Write report to file, returns file path

Output Format: Markdown string (desktop context) or ASCII-formatted string (CLI context).

format_detector.py

Purpose: Automatically detect and parse input format (JSON, YAML, URL, or natural language text) for technology evaluation requests. Extracts technology names, use cases, priorities, and analysis types from unstructured text input.

Usage:

from format_detector import FormatDetector

detector = FormatDetector('Compare React vs Vue for a SaaS dashboard. Priorities: performance, ecosystem.')

format_type = detector.detect_format()   # Returns: "text"
parsed = detector.parse()                # Returns normalized dict
info = detector.get_format_info()        # Returns detection metadata

Constructor Parameters:

Supported Formats:

• JSON -- Valid JSON objects are detected and parsed directly
• YAML -- Detected when >50% of lines match key-value or list patterns (simplified parser, no PyYAML dependency)
• URL -- Detected when input contains http:// or https:// URLs; categorizes GitHub, npm, and other URLs
• Text -- Natural language fallback; extracts technologies from 30+ known keywords, identifies use cases, priorities, and analysis types

Key Methods:

• detect_format() -- Returns format string: "json", "yaml", "url", or "text"
• parse() -- Parse input and return normalized dictionary with standard keys: technologies, use_case, priorities, analysis_type, format
• get_format_info() -- Detection metadata: detected_format, input_length, line_count, parsing_successful

Output Format: Python dictionary normalized to a standard structure with keys: technologies (list), use_case (str), priorities (list), analysis_type (str), format (str).