@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/skills/tech-stack-evaluator/assets/sample_input_structured.json

@@ -0,0 +1,39 @@
+{
+  "comparison": {
+    "technologies": [
+      {
+        "name": "PostgreSQL",
+        "performance": {"score": 85},
+        "scalability": {"score": 90},
+        "developer_experience": {"score": 75},
+        "ecosystem": {"score": 95},
+        "learning_curve": {"score": 70},
+        "documentation": {"score": 90},
+        "community_support": {"score": 95},
+        "enterprise_readiness": {"score": 95}
+      },
+      {
+        "name": "MongoDB",
+        "performance": {"score": 80},
+        "scalability": {"score": 95},
+        "developer_experience": {"score": 85},
+        "ecosystem": {"score": 85},
+        "learning_curve": {"score": 80},
+        "documentation": {"score": 85},
+        "community_support": {"score": 85},
+        "enterprise_readiness": {"score": 75}
+      }
+    ],
+    "use_case": "SaaS application with complex queries",
+    "weights": {
+      "performance": 20,
+      "scalability": 20,
+      "developer_experience": 15,
+      "ecosystem": 15,
+      "learning_curve": 10,
+      "documentation": 10,
+      "community_support": 5,
+      "enterprise_readiness": 5
+    }
+  }
+}

package/engineering-team/skills/tech-stack-evaluator/assets/sample_input_tco.json

@@ -0,0 +1,42 @@
+{
+  "tco_analysis": {
+    "technology": "AWS",
+    "team_size": 10,
+    "timeline_years": 5,
+    "initial_costs": {
+      "licensing": 0,
+      "training_hours_per_dev": 40,
+      "developer_hourly_rate": 100,
+      "training_materials": 1000,
+      "migration": 50000,
+      "setup": 10000,
+      "tooling": 5000
+    },
+    "operational_costs": {
+      "annual_licensing": 0,
+      "monthly_hosting": 5000,
+      "annual_support": 20000,
+      "maintenance_hours_per_dev_monthly": 20
+    },
+    "scaling_params": {
+      "initial_users": 5000,
+      "annual_growth_rate": 0.30,
+      "initial_servers": 10,
+      "cost_per_server_monthly": 300
+    },
+    "productivity_factors": {
+      "productivity_multiplier": 1.2,
+      "time_to_market_reduction_days": 15,
+      "avg_feature_time_days": 45,
+      "avg_feature_value": 15000,
+      "technical_debt_percentage": 0.12,
+      "vendor_lock_in_risk": "medium",
+      "security_incidents_per_year": 0.3,
+      "avg_security_incident_cost": 30000,
+      "downtime_hours_per_year": 4,
+      "downtime_cost_per_hour": 8000,
+      "annual_turnover_rate": 0.12,
+      "cost_per_new_hire": 35000
+    }
+  }
+}

package/engineering-team/skills/tech-stack-evaluator/assets/sample_input_text.json

@@ -0,0 +1,4 @@
+{
+  "format": "text",
+  "input": "Compare React vs Vue for building a SaaS dashboard with real-time collaboration features. Our team has 8 developers, and we need to consider developer experience, ecosystem maturity, and performance."
+}

package/engineering-team/skills/tech-stack-evaluator/references/examples.md

@@ -0,0 +1,383 @@
+# Technology Evaluation Examples
+
+Concrete examples showing input formats and expected outputs.
+
+---
+
+## Table of Contents
+
+- [Quick Comparison Example](#quick-comparison-example)
+- [TCO Analysis Example](#tco-analysis-example)
+- [Ecosystem Analysis Example](#ecosystem-analysis-example)
+- [Migration Assessment Example](#migration-assessment-example)
+- [Multi-Technology Comparison](#multi-technology-comparison)
+
+---
+
+## Quick Comparison Example
+
+### Input (Text Format)
+
+```
+Compare React vs Vue for building a SaaS dashboard.
+Focus on: developer productivity, ecosystem maturity, performance.
+```
+
+### Output
+
+```
+TECHNOLOGY COMPARISON: React vs Vue for SaaS Dashboard
+=======================================================
+
+RECOMMENDATION: React
+Confidence: 78% (Medium-High)
+
+COMPARISON MATRIX
+-----------------
+| Category             | Weight | React | Vue  |
+|----------------------|--------|-------|------|
+| Performance          | 15%    | 82.0  | 85.0 |
+| Scalability          | 15%    | 88.0  | 80.0 |
+| Developer Experience | 20%    | 85.0  | 90.0 |
+| Ecosystem            | 15%    | 92.0  | 78.0 |
+| Learning Curve       | 10%    | 70.0  | 85.0 |
+| Documentation        | 10%    | 88.0  | 82.0 |
+| Community Support    | 10%    | 90.0  | 75.0 |
+| Enterprise Readiness | 5%     | 85.0  | 72.0 |
+|----------------------|--------|-------|------|
+| WEIGHTED TOTAL       | 100%   | 85.2  | 81.1 |
+
+KEY DECISION FACTORS
+--------------------
+1. Ecosystem (15%): React leads with 92.0 - larger npm ecosystem
+2. Developer Experience (20%): Vue leads with 90.0 - gentler learning curve
+3. Community Support (10%): React leads with 90.0 - more Stack Overflow resources
+
+PROS/CONS SUMMARY
+-----------------
+React:
+  ✓ Excellent ecosystem (92.0/100)
+  ✓ Strong community support (90.0/100)
+  ✓ Excellent scalability (88.0/100)
+  ✗ Steeper learning curve (70.0/100)
+
+Vue:
+  ✓ Excellent developer experience (90.0/100)
+  ✓ Good performance (85.0/100)
+  ✓ Easier learning curve (85.0/100)
+  ✗ Smaller enterprise presence (72.0/100)
+```
+
+---
+
+## TCO Analysis Example
+
+### Input (JSON Format)
+
+```json
+{
+  "technology": "Next.js on Vercel",
+  "team_size": 8,
+  "timeline_years": 5,
+  "initial_costs": {
+    "licensing": 0,
+    "training_hours_per_dev": 24,
+    "developer_hourly_rate": 85,
+    "migration": 15000,
+    "setup": 5000
+  },
+  "operational_costs": {
+    "monthly_hosting": 2500,
+    "annual_support": 0,
+    "maintenance_hours_per_dev_monthly": 16
+  },
+  "scaling_params": {
+    "initial_users": 5000,
+    "annual_growth_rate": 0.40,
+    "initial_servers": 3,
+    "cost_per_server_monthly": 150
+  }
+}
+```
+
+### Output
+
+```
+TCO ANALYSIS: Next.js on Vercel (5-Year Projection)
+====================================================
+
+EXECUTIVE SUMMARY
+-----------------
+Total TCO: $1,247,320
+Net TCO (after productivity gains): $987,320
+Average Yearly Cost: $249,464
+
+INITIAL COSTS (One-Time)
+------------------------
+| Component      | Cost      |
+|----------------|-----------|
+| Licensing      | $0        |
+| Training       | $16,820   |
+| Migration      | $15,000   |
+| Setup          | $5,000    |
+|----------------|-----------|
+| TOTAL INITIAL  | $36,820   |
+
+OPERATIONAL COSTS (Per Year)
+----------------------------
+| Year | Hosting  | Maintenance | Total     |
+|------|----------|-------------|-----------|
+| 1    | $30,000  | $130,560    | $160,560  |
+| 2    | $42,000  | $130,560    | $172,560  |
+| 3    | $58,800  | $130,560    | $189,360  |
+| 4    | $82,320  | $130,560    | $212,880  |
+| 5    | $115,248 | $130,560    | $245,808  |
+
+SCALING ANALYSIS
+----------------
+User Projections: 5,000 → 7,000 → 9,800 → 13,720 → 19,208
+Cost per User: $32.11 → $24.65 → $19.32 → $15.52 → $12.79
+Scaling Efficiency: Excellent - economies of scale achieved
+
+KEY COST DRIVERS
+----------------
+1. Developer maintenance time ($652,800 over 5 years)
+2. Infrastructure/hosting ($328,368 over 5 years)
+
+OPTIMIZATION OPPORTUNITIES
+--------------------------
+• Consider automation to reduce maintenance hours
+• Evaluate reserved capacity pricing for hosting
+```
+
+---
+
+## Ecosystem Analysis Example
+
+### Input
+
+```yaml
+technology: "Svelte"
+github:
+  stars: 78000
+  forks: 4100
+  contributors: 680
+  commits_last_month: 45
+  avg_issue_response_hours: 36
+  issue_resolution_rate: 0.72
+  releases_per_year: 8
+  active_maintainers: 5
+npm:
+  weekly_downloads: 420000
+  version: "4.2.8"
+  dependencies_count: 0
+  days_since_last_publish: 21
+community:
+  stackoverflow_questions: 8500
+  job_postings: 1200
+  tutorials_count: 350
+  forum_members: 25000
+corporate_backing:
+  type: "community_led"
+  funding_millions: 0
+```
+
+### Output
+
+```
+ECOSYSTEM ANALYSIS: Svelte
+==========================
+
+OVERALL HEALTH SCORE: 71.5/100
+
+HEALTH SCORE BREAKDOWN
+----------------------
+| Category           | Score | Assessment        |
+|--------------------|-------|-------------------|
+| GitHub Health      | 78.0  | Strong            |
+| npm Health         | 72.0  | Good              |
+| Community Health   | 58.0  | Moderate          |
+| Corporate Backing  | 40.0  | Community-led     |
+| Maintenance Health | 75.0  | Active            |
+
+VIABILITY ASSESSMENT
+--------------------
+Overall: Good - Solid viability with minor concerns
+Risk Level: Low-Medium
+
+Strengths:
+• Strong GitHub presence with active community
+• Active maintenance with responsive issue resolution
+• High npm adoption with stable releases
+
+Risks:
+• Weak corporate backing - sustainability concerns
+• Smaller community - limited enterprise resources
+
+RECOMMENDATION
+--------------
+Suitable for adoption - monitor corporate backing situation.
+Consider alternative with stronger backing for mission-critical enterprise apps.
+
+KEY METRICS
+-----------
+GitHub: 78,000 stars, 680 contributors, 45 commits/month
+npm: 420,000 weekly downloads, v4.2.8
+Community: 8,500 SO questions, 1,200 job postings
+```
+
+---
+
+## Migration Assessment Example
+
+### Input
+
+```
+Assess migration from Angular.js (1.x) to React.
+Application: 50,000 lines of code, 200 components.
+Team: 6 developers, 2 have React experience.
+Timeline: Need completion within 8 months.
+```
+
+### Output
+
+```
+MIGRATION ASSESSMENT: Angular.js 1.x → React
+=============================================
+
+COMPLEXITY SCORE: 7.8/10 (High)
+
+COMPLEXITY BREAKDOWN
+--------------------
+| Factor              | Score | Impact      |
+|---------------------|-------|-------------|
+| Code Changes        | 8/10  | 50K LOC     |
+| Architecture Impact | 9/10  | Complete    |
+| Data Migration      | 5/10  | State only  |
+| Downtime Risk       | 6/10  | Mitigatable |
+
+EFFORT ESTIMATION
+-----------------
+| Phase                    | Hours  | Duration |
+|--------------------------|--------|----------|
+| Planning & Prototyping   | 240    | 3 weeks  |
+| Core Migration           | 2,400  | 16 weeks |
+| Testing & Validation     | 480    | 5 weeks  |
+| Deployment & Monitoring  | 160    | 2 weeks  |
+|--------------------------|--------|----------|
+| TOTAL                    | 3,280  | 26 weeks |
+
+Timeline Assessment: 26 weeks exceeds 8-month target (32 weeks)
+Recommendation: Feasible with buffer
+
+RISK ASSESSMENT
+---------------
+Technical Risks:
+• High - Two-way binding to unidirectional data flow
+• Medium - Dependency injection to hooks/context
+• Medium - Performance regression during transition
+
+Business Risks:
+• Medium - Feature freeze during migration
+• Low - Customer impact with phased approach
+
+Team Risks:
+• High - 4 of 6 developers need React training
+• Medium - Learning curve affects velocity initially
+
+MIGRATION STRATEGY
+------------------
+Recommended Approach: Strangler Fig Pattern
+
+Phase 1 (Weeks 1-8): Strangler setup
+• Create React shell application
+• Set up micro-frontend routing
+• Migrate shared utilities
+
+Phase 2 (Weeks 9-18): Component migration
+• Migrate components by feature area
+• Maintain Angular.js for untouched areas
+• Continuous integration testing
+
+Phase 3 (Weeks 19-24): Completion
+• Migrate remaining components
+• Remove Angular.js dependencies
+• Performance optimization
+
+Phase 4 (Weeks 25-26): Stabilization
+• Production deployment
+• Monitoring and fixes
+```
+
+---
+
+## Multi-Technology Comparison
+
+### Input
+
+```
+Compare: React, Vue, Svelte, Angular for enterprise SaaS.
+Use case: Large team (20+ developers), complex state management.
+Generate comprehensive decision matrix.
+```
+
+### Output
+
+```
+MULTI-TECHNOLOGY COMPARISON: Enterprise SaaS Platform
+======================================================
+
+RECOMMENDATION: React
+Confidence: 72% (Medium)
+Runner-up: Angular (close second for enterprise)
+
+DECISION MATRIX
+---------------
+| Category             | Wt   | React | Vue  | Svelte | Angular |
+|----------------------|------|-------|------|--------|---------|
+| Performance          | 15%  | 82    | 85   | 95     | 78      |
+| Scalability          | 15%  | 90    | 82   | 75     | 92      |
+| Developer Experience | 20%  | 85    | 90   | 88     | 75      |
+| Ecosystem            | 15%  | 95    | 80   | 65     | 88      |
+| Learning Curve       | 10%  | 70    | 85   | 80     | 60      |
+| Documentation        | 10%  | 90    | 85   | 75     | 92      |
+| Community Support    | 10%  | 92    | 78   | 55     | 85      |
+| Enterprise Readiness | 5%   | 88    | 72   | 50     | 95      |
+|----------------------|------|-------|------|--------|---------|
+| WEIGHTED TOTAL       | 100% | 86.3  | 83.1 | 76.2   | 83.0    |
+
+FRAMEWORK PROFILES
+------------------
+React: Best for large ecosystem, hiring pool
+Angular: Best for enterprise structure, TypeScript-first
+Vue: Best for developer experience, gradual adoption
+Svelte: Best for performance, smaller bundles
+
+RECOMMENDATION RATIONALE
+------------------------
+For 20+ developer team with complex state management:
+
+1. React (Recommended)
+   • Largest talent pool for hiring
+   • Extensive enterprise libraries (Redux, React Query)
+   • Meta backing ensures long-term support
+   • Most Stack Overflow resources
+
+2. Angular (Strong Alternative)
+   • Built-in structure for large teams
+   • TypeScript-first reduces bugs
+   • Comprehensive CLI and tooling
+   • Google enterprise backing
+
+3. Vue (Consider for DX)
+   • Excellent documentation
+   • Easier onboarding
+   • Growing enterprise adoption
+   • Consider if DX is top priority
+
+4. Svelte (Not Recommended for This Use Case)
+   • Smaller ecosystem for enterprise
+   • Limited hiring pool
+   • State management options less mature
+   • Better for smaller teams/projects
+```

package/engineering-team/skills/tech-stack-evaluator/references/metrics.md

@@ -0,0 +1,242 @@
+# Technology Evaluation Metrics
+
+Detailed metrics and calculations used in technology stack evaluation.
+
+---
+
+## Table of Contents
+
+- [Scoring and Comparison](#scoring-and-comparison)
+- [Financial Calculations](#financial-calculations)
+- [Ecosystem Health Metrics](#ecosystem-health-metrics)
+- [Security Metrics](#security-metrics)
+- [Migration Metrics](#migration-metrics)
+- [Performance Benchmarks](#performance-benchmarks)
+
+---
+
+## Scoring and Comparison
+
+### Technology Comparison Matrix
+
+| Metric | Scale | Description |
+|--------|-------|-------------|
+| Feature Completeness | 0-100 | Coverage of required features |
+| Learning Curve | Easy/Medium/Hard | Time to developer proficiency |
+| Developer Experience | 0-100 | Tooling, debugging, workflow quality |
+| Documentation Quality | 0-10 | Completeness, clarity, examples |
+
+### Weighted Scoring Algorithm
+
+The comparator uses normalized weighted scoring:
+
+```python
+# Default category weights (sum to 100%)
+weights = {
+    "performance": 15,
+    "scalability": 15,
+    "developer_experience": 20,
+    "ecosystem": 15,
+    "learning_curve": 10,
+    "documentation": 10,
+    "community_support": 10,
+    "enterprise_readiness": 5
+}
+
+# Final score calculation
+weighted_score = sum(category_score * weight / 100 for each category)
+```
+
+### Confidence Scoring
+
+Confidence is calculated based on score gap between top options:
+
+| Score Gap | Confidence Level |
+|-----------|------------------|
+| < 5 points | Low (40-50%) |
+| 5-15 points | Medium (50-70%) |
+| > 15 points | High (70-100%) |
+
+---
+
+## Financial Calculations
+
+### TCO Components
+
+**Initial Costs (One-Time)**
+- Licensing fees
+- Training: `team_size * hours_per_dev * hourly_rate + materials`
+- Migration costs
+- Setup and tooling
+
+**Operational Costs (Annual)**
+- Licensing renewals
+- Hosting: `base_cost * (1 + growth_rate)^(year - 1)`
+- Support contracts
+- Maintenance: `team_size * hours_per_dev_monthly * hourly_rate * 12`
+
+**Scaling Costs**
+- Infrastructure: `servers * cost_per_server * 12`
+- Cost per user: `total_yearly_cost / user_count`
+
+### ROI Calculations
+
+```
+productivity_value = additional_features_per_year * avg_feature_value
+net_tco = total_cost - (productivity_value * years)
+roi_percentage = (benefits - costs) / costs * 100
+```
+
+### Cost Per Metric Reference
+
+| Metric | Description |
+|--------|-------------|
+| Cost per user | Monthly or yearly per active user |
+| Cost per API request | Average cost per 1000 requests |
+| Cost per GB | Storage and transfer costs |
+| Cost per compute hour | Processing time costs |
+
+---
+
+## Ecosystem Health Metrics
+
+### GitHub Health Score (0-100)
+
+| Metric | Max Points | Thresholds |
+|--------|------------|------------|
+| Stars | 30 | 50K+: 30, 20K+: 25, 10K+: 20, 5K+: 15, 1K+: 10 |
+| Forks | 20 | 10K+: 20, 5K+: 15, 2K+: 12, 1K+: 10 |
+| Contributors | 20 | 500+: 20, 200+: 15, 100+: 12, 50+: 10 |
+| Commits/month | 30 | 100+: 30, 50+: 25, 25+: 20, 10+: 15 |
+
+### npm Health Score (0-100)
+
+| Metric | Max Points | Thresholds |
+|--------|------------|------------|
+| Weekly downloads | 40 | 1M+: 40, 500K+: 35, 100K+: 30, 50K+: 25, 10K+: 20 |
+| Major version | 20 | v5+: 20, v3+: 15, v1+: 10 |
+| Dependencies | 20 | ≤10: 20, ≤25: 15, ≤50: 10 (fewer is better) |
+| Days since publish | 20 | ≤30: 20, ≤90: 15, ≤180: 10, ≤365: 5 |
+
+### Community Health Score (0-100)
+
+| Metric | Max Points | Thresholds |
+|--------|------------|------------|
+| Stack Overflow questions | 25 | 50K+: 25, 20K+: 20, 10K+: 15, 5K+: 10 |
+| Job postings | 25 | 5K+: 25, 2K+: 20, 1K+: 15, 500+: 10 |
+| Tutorials | 25 | 1K+: 25, 500+: 20, 200+: 15, 100+: 10 |
+| Forum/Discord members | 25 | 50K+: 25, 20K+: 20, 10K+: 15, 5K+: 10 |
+
+### Corporate Backing Score
+
+| Backing Type | Score |
+|--------------|-------|
+| Major tech company (Google, Microsoft, Meta) | 100 |
+| Established company (Vercel, HashiCorp) | 80 |
+| Funded startup | 60 |
+| Community-led (strong community) | 40 |
+| Individual maintainers | 20 |
+
+---
+
+## Security Metrics
+
+### Security Scoring Components
+
+| Metric | Description |
+|--------|-------------|
+| CVE Count (12 months) | Known vulnerabilities in last year |
+| CVE Count (3 years) | Longer-term vulnerability history |
+| Severity Distribution | Critical/High/Medium/Low counts |
+| Patch Frequency | Average days to patch vulnerabilities |
+
+### Compliance Readiness Levels
+
+| Level | Score Range | Description |
+|-------|-------------|-------------|
+| Ready | 90-100% | Meets compliance requirements |
+| Mostly Ready | 70-89% | Minor gaps to address |
+| Partial | 50-69% | Significant work needed |
+| Not Ready | < 50% | Major gaps exist |
+
+### Compliance Framework Coverage
+
+**GDPR**
+- Data privacy features
+- Consent management
+- Data portability
+- Right to deletion
+
+**SOC2**
+- Access controls
+- Encryption at rest/transit
+- Audit logging
+- Change management
+
+**HIPAA**
+- PHI handling
+- Encryption standards
+- Access controls
+- Audit trails
+
+---
+
+## Migration Metrics
+
+### Complexity Scoring (1-10 Scale)
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| Code Changes | 30% | Lines of code affected |
+| Architecture Impact | 25% | Breaking changes, API compatibility |
+| Data Migration | 25% | Schema changes, data transformation |
+| Downtime Requirements | 20% | Zero-downtime possible vs planned outage |
+
+### Effort Estimation
+
+| Phase | Components |
+|-------|------------|
+| Development | Hours per component * complexity factor |
+| Testing | Unit + integration + E2E hours |
+| Training | Team size * learning curve hours |
+| Buffer | 20-30% for unknowns |
+
+### Risk Assessment Matrix
+
+| Risk Category | Factors Evaluated |
+|---------------|-------------------|
+| Technical | API incompatibilities, performance regressions |
+| Business | Downtime impact, feature parity gaps |
+| Team | Learning curve, skill gaps |
+
+---
+
+## Performance Benchmarks
+
+### Throughput/Latency Metrics
+
+| Metric | Description |
+|--------|-------------|
+| RPS | Requests per second |
+| Avg Response Time | Mean response latency (ms) |
+| P95 Latency | 95th percentile response time |
+| P99 Latency | 99th percentile response time |
+| Concurrent Users | Maximum simultaneous connections |
+
+### Resource Usage Metrics
+
+| Metric | Unit |
+|--------|------|
+| Memory | MB/GB per instance |
+| CPU | Utilization percentage |
+| Storage | GB required |
+| Network | Bandwidth MB/s |
+
+### Scalability Characteristics
+
+| Type | Description |
+|------|-------------|
+| Horizontal | Add more instances, efficiency factor |
+| Vertical | CPU/memory limits per instance |
+| Cost per Performance | Dollar per 1000 RPS |
+| Scaling Inflection | Point where cost efficiency changes |