specweave 2.2.3 → 3.0.0

package/plugins/specweave/lib/external-sync/permission-gate.ts

@@ -1,109 +0,0 @@
-/**
- * Shared permission gate for external sync operations (GitHub, JIRA, ADO)
- * Extracts the identical permission checking pattern from all sync plugins.
- */
-
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-
-export interface SyncPermissionResult {
-  canRead: boolean;
-  canWrite: boolean;
-  message: string;
-  configPath: string;
-}
-
-export interface SyncConfig {
-  sync?: {
-    enabled?: boolean;
-    settings?: {
-      canUpdateExternalItems?: boolean;
-    };
-  };
-}
-
-/**
- * Check if external sync operations are permitted.
- * Used by GitHub, JIRA, and ADO sync commands.
- *
- * @param projectRoot - Root directory of the project
- * @param toolName - Display name of the tool (e.g., "GitHub", "JIRA", "Azure DevOps")
- * @returns Permission result with read/write capabilities
- */
-export function checkSyncPermissions(
-  projectRoot: string,
-  toolName: string
-): SyncPermissionResult {
-  const configPath = join(projectRoot, '.specweave', 'config.json');
-
-  // Default: read-only
-  const result: SyncPermissionResult = {
-    canRead: true,
-    canWrite: false,
-    message: '',
-    configPath
-  };
-
-  if (!existsSync(configPath)) {
-    result.message = `Config not found at ${configPath}`;
-    return result;
-  }
-
-  try {
-    const config: SyncConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
-    result.canWrite = config?.sync?.settings?.canUpdateExternalItems ?? false;
-
-    if (!result.canWrite) {
-      result.message = formatPermissionDeniedMessage(toolName);
-    }
-  } catch {
-    result.message = `Failed to read config at ${configPath}`;
-  }
-
-  return result;
-}
-
-/**
- * Format a consistent permission denied message for all external tools.
- */
-export function formatPermissionDeniedMessage(toolName: string): string {
-  const toolLower = toolName.toLowerCase().replace(/\s+/g, '-');
-
-  return `
-❌ Permission Denied: ${toolName} Write Operations Disabled
-
-Cannot push changes to ${toolName} (sync.settings.canUpdateExternalItems = false).
-
-Options:
-1. Enable writes: Set canUpdateExternalItems to true in config.json
-   {
-     "sync": {
-       "settings": {
-         "canUpdateExternalItems": true
-       }
-     }
-   }
-
-2. Pull-only mode: sw-${toolLower}:sync \${incrementId} --direction from-${toolLower}
-
-3. View status: sw-${toolLower}:status \${incrementId}
-`.trim();
-}
-
-/**
- * Check if sync is enabled at all for this project.
- */
-export function isSyncEnabled(projectRoot: string): boolean {
-  const configPath = join(projectRoot, '.specweave', 'config.json');
-
-  if (!existsSync(configPath)) {
-    return false;
-  }
-
-  try {
-    const config: SyncConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
-    return config?.sync?.enabled !== false; // Default to enabled
-  } catch {
-    return false;
-  }
-}

package/plugins/specweave/lib/features/release/dashboard-generator.js

@@ -1,232 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import {
-  readHistory,
-  calculateTrend,
-  detectDegradation,
-  getLatestSnapshot
-} from "./dora-tracker.js";
-const SPECWEAVE_ROOT = process.cwd();
-const DASHBOARD_PATH = path.join(
-  SPECWEAVE_ROOT,
-  ".specweave",
-  "docs",
-  "internal",
-  "delivery",
-  "dora-dashboard.md"
-);
-function getTierIcon(tier) {
-  switch (tier) {
-    case "elite":
-      return "\u2705";
-    case "high":
-      return "\u{1F7E2}";
-    case "medium":
-      return "\u{1F7E1}";
-    case "low":
-      return "\u{1F534}";
-    default:
-      return "\u26AA";
-  }
-}
-function formatTrendChange(change) {
-  if (change > 0) {
-    return `\u2191 +${change.toFixed(1)}%`;
-  } else if (change < 0) {
-    return `\u2193 ${change.toFixed(1)}%`;
-  } else {
-    return `\u2192 0%`;
-  }
-}
-function getOverallTier(snapshot) {
-  const tiers = [
-    snapshot.deploymentFrequency.tier,
-    snapshot.leadTime.tier,
-    snapshot.changeFailureRate.tier,
-    snapshot.mttr.tier === "n/a" ? "elite" : snapshot.mttr.tier
-    // Treat N/A as elite (no incidents)
-  ];
-  const count = {
-    elite: tiers.filter((t) => t === "elite").length,
-    high: tiers.filter((t) => t === "high").length,
-    medium: tiers.filter((t) => t === "medium").length,
-    low: tiers.filter((t) => t === "low").length
-  };
-  let overallTier = "elite";
-  if (count.low > 0) overallTier = "low";
-  else if (count.medium > 0) overallTier = "medium";
-  else if (count.high > 0) overallTier = "high";
-  return {
-    tier: overallTier,
-    icon: getTierIcon(overallTier),
-    count
-  };
-}
-function generateDashboard() {
-  const latest = getLatestSnapshot();
-  if (!latest) {
-    return `# DORA Metrics Dashboard
-
-**Status**: No metrics data available
-
-Run \`npm run metrics:dora\` to calculate DORA metrics.
-`;
-  }
-  const overall = getOverallTier(latest);
-  const alerts = detectDegradation();
-  let markdown = `# DORA Metrics Dashboard
-
-**Last Updated**: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]} ${(/* @__PURE__ */ new Date()).toTimeString().split(" ")[0]} UTC
-**Overall Rating**: ${overall.icon} **${overall.tier.charAt(0).toUpperCase() + overall.tier.slice(1)}** (${overall.count.elite} Elite, ${overall.count.high} High, ${overall.count.medium} Medium, ${overall.count.low} Low)
-
----
-
-## Current Metrics
-
-`;
-  const metrics = [
-    {
-      name: "Deployment Frequency",
-      key: "deploymentFrequency",
-      current: `${latest.deploymentFrequency.value} ${latest.deploymentFrequency.unit}`,
-      tier: latest.deploymentFrequency.tier
-    },
-    {
-      name: "Lead Time for Changes",
-      key: "leadTime",
-      current: `${latest.leadTime.value} ${latest.leadTime.unit}`,
-      tier: latest.leadTime.tier
-    },
-    {
-      name: "Change Failure Rate",
-      key: "changeFailureRate",
-      current: `${latest.changeFailureRate.value}%`,
-      tier: latest.changeFailureRate.tier
-    },
-    {
-      name: "Time to Restore Service (MTTR)",
-      key: "mttr",
-      current: latest.mttr.tier === "n/a" ? "N/A (No incidents)" : `${latest.mttr.value} ${latest.mttr.unit}`,
-      tier: latest.mttr.tier
-    }
-  ];
-  markdown += `| Metric | Current | 7-Day Trend | 30-Day Trend | 90-Day Trend | Tier |
-`;
-  markdown += `|--------|---------|-------------|--------------|--------------|------|
-`;
-  metrics.forEach((metric) => {
-    const trend = calculateTrend(metric.key);
-    const sevenDay = trend ? formatTrendChange(trend.sevenDayChange) : "-";
-    const thirtyDay = trend ? formatTrendChange(trend.thirtyDayChange) : "-";
-    const ninetyDay = trend ? formatTrendChange(trend.ninetyDayChange) : "-";
-    markdown += `| **${metric.name}** | ${metric.current} | ${sevenDay} | ${thirtyDay} | ${ninetyDay} | ${getTierIcon(metric.tier)} ${metric.tier.charAt(0).toUpperCase() + metric.tier.slice(1)} |
-`;
-  });
-  markdown += `
-`;
-  if (alerts.length > 0) {
-    markdown += `## \u26A0\uFE0F Degradation Alerts
-
-`;
-    alerts.forEach((alert) => {
-      const icon = alert.severity === "critical" ? "\u{1F534}" : "\u{1F7E0}";
-      markdown += `${icon} **${alert.metric}**: ${alert.message}
-`;
-      markdown += `- Previous (30-day avg): ${alert.previousValue.toFixed(2)}
-`;
-      markdown += `- Current: ${alert.currentValue.toFixed(2)}
-`;
-      markdown += `- Change: ${alert.percentageChange.toFixed(1)}%
-
-`;
-    });
-  } else {
-    markdown += `## \u2705 No Degradation Detected
-
-All metrics are stable or improving compared to 30-day averages.
-
-`;
-  }
-  markdown += `---
-
-## DORA Performance Tiers
-
-| Metric | Elite | High | Medium | Low |
-|--------|-------|------|--------|-----|
-| **Deployment Frequency** | On-demand (multiple/day) | Weekly - Monthly | Monthly - 6 months | < 6 months |
-| **Lead Time for Changes** | < 1 hour | 1 day - 1 week | 1 week - 1 month | 1-6 months |
-| **Change Failure Rate** | 0-15% | 16-30% | 31-45% | > 45% |
-| **Time to Restore Service** | < 1 hour | < 1 day | 1 day - 1 week | > 1 week |
-
-**Source**: [DORA State of DevOps Research](https://dora.dev/)
-
----
-
-## Historical Trends
-
-**Total Snapshots**: ${readHistory().length}
-
-**Data Retention**: All snapshots stored in \`.specweave/metrics/dora-history.jsonl\`
-
-**Calculation Frequency**: After every increment completion (automated via hooks)
-
----
-
-## Related Documentation
-
-- [DORA Metrics (Detailed)](./dora-metrics.md) - Full methodology and measurement details
-- [Release Process](./release-process.md) - Release workflow and best practices
-- [Testing Strategy](./guides/testing-strategy.md) - Testing approach linked to change failure rate
-- [Branch Strategy](./branch-strategy.md) - Git workflow linked to lead time
-
----
-
-## Actions
-
-**If metrics are degrading**:
-
-1. **Review Recent Changes** - What changed in the last 30 days?
-2. **Analyze Root Cause** - Use incident reports, test failures, deployment logs
-3. **Create ADR** - Document decision to address degradation
-4. **Implement Improvements** - Create increment to fix underlying issues
-5. **Monitor Progress** - Track metrics recovery over next 30 days
-
-**If metrics are improving**:
-
-1. **Document Success** - What practices led to improvement?
-2. **Share Knowledge** - Update team playbooks with learnings
-3. **Maintain Momentum** - Continue proven practices
-4. **Set New Goals** - Aim for next tier (High \u2192 Elite)
-
----
-
-**Dashboard Auto-Generated**: ${(/* @__PURE__ */ new Date()).toISOString()}
-**Generator**: \`plugins/specweave-release/lib/dashboard-generator.ts\`
-`;
-  return markdown;
-}
-function writeDashboard() {
-  const markdown = generateDashboard();
-  const dir = path.dirname(DASHBOARD_PATH);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  fs.writeFileSync(DASHBOARD_PATH, markdown, "utf-8");
-  console.log(`\u2713 Dashboard generated: ${DASHBOARD_PATH}`);
-}
-async function main() {
-  try {
-    writeDashboard();
-    console.log("\u2705 DORA dashboard generated successfully");
-  } catch (error) {
-    console.error("\u274C Failed to generate dashboard:", error);
-    process.exit(1);
-  }
-}
-if (require.main === module) {
-  main().catch(console.error);
-}
-export {
-  generateDashboard,
-  writeDashboard
-};

package/plugins/specweave/lib/features/release/dashboard-generator.ts

@@ -1,294 +0,0 @@
-/**
- * DORA Dashboard Generator
- *
- * Generates living docs dashboard with trends and visual indicators
- *
- * Output: .specweave/docs/internal/delivery/dora-dashboard.md
- *
- * Features:
- * - Current metrics with tier indicators (✅ Elite, 🟢 High, 🟡 Medium, 🔴 Low)
- * - 7-day, 30-day, 90-day trend charts
- * - Percentage changes with up/down arrows
- * - Degradation alerts
- * - Links to detailed reports and ADRs
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import {
-  DORASnapshot,
-  TrendData,
-  DegradationAlert,
-  readHistory,
-  calculateTrend,
-  detectDegradation,
-  getLatestSnapshot,
-} from './dora-tracker.js';
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-const SPECWEAVE_ROOT = process.cwd();
-const DASHBOARD_PATH = path.join(
-  SPECWEAVE_ROOT,
-  '.specweave',
-  'docs',
-  'internal',
-  'delivery',
-  'dora-dashboard.md'
-);
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-/**
- * Get tier indicator icon
- */
-function getTierIcon(tier: string): string {
-  switch (tier) {
-    case 'elite': return '✅';
-    case 'high': return '🟢';
-    case 'medium': return '🟡';
-    case 'low': return '🔴';
-    default: return '⚪';
-  }
-}
-
-/**
- * Format trend change with arrow
- */
-function formatTrendChange(change: number): string {
-  if (change > 0) {
-    return `↑ +${change.toFixed(1)}%`;
-  } else if (change < 0) {
-    return `↓ ${change.toFixed(1)}%`;
-  } else {
-    return `→ 0%`;
-  }
-}
-
-/**
- * Get overall tier (worst of all 4 metrics)
- */
-function getOverallTier(snapshot: DORASnapshot): { tier: string; icon: string; count: Record<string, number> } {
-  const tiers = [
-    snapshot.deploymentFrequency.tier,
-    snapshot.leadTime.tier,
-    snapshot.changeFailureRate.tier,
-    snapshot.mttr.tier === 'n/a' ? 'elite' : snapshot.mttr.tier, // Treat N/A as elite (no incidents)
-  ];
-
-  // Count metrics at each tier
-  const count = {
-    elite: tiers.filter(t => t === 'elite').length,
-    high: tiers.filter(t => t === 'high').length,
-    medium: tiers.filter(t => t === 'medium').length,
-    low: tiers.filter(t => t === 'low').length,
-  };
-
-  // Overall tier = worst tier (prioritize low > medium > high > elite)
-  let overallTier = 'elite';
-  if (count.low > 0) overallTier = 'low';
-  else if (count.medium > 0) overallTier = 'medium';
-  else if (count.high > 0) overallTier = 'high';
-
-  return {
-    tier: overallTier,
-    icon: getTierIcon(overallTier),
-    count,
-  };
-}
-
-// ============================================================================
-// Dashboard Generation
-// ============================================================================
-
-/**
- * Generate DORA dashboard markdown
- */
-export function generateDashboard(): string {
-  const latest = getLatestSnapshot();
-  if (!latest) {
-    return `# DORA Metrics Dashboard
-
-**Status**: No metrics data available
-
-Run \`npm run metrics:dora\` to calculate DORA metrics.
-`;
-  }
-
-  const overall = getOverallTier(latest);
-  const alerts = detectDegradation();
-
-  // Header
-  let markdown = `# DORA Metrics Dashboard
-
-**Last Updated**: ${new Date().toISOString().split('T')[0]} ${new Date().toTimeString().split(' ')[0]} UTC
-**Overall Rating**: ${overall.icon} **${overall.tier.charAt(0).toUpperCase() + overall.tier.slice(1)}** (${overall.count.elite} Elite, ${overall.count.high} High, ${overall.count.medium} Medium, ${overall.count.low} Low)
-
----
-
-## Current Metrics
-
-`;
-
-  // Metrics table
-  const metrics = [
-    {
-      name: 'Deployment Frequency',
-      key: 'deploymentFrequency' as const,
-      current: `${latest.deploymentFrequency.value} ${latest.deploymentFrequency.unit}`,
-      tier: latest.deploymentFrequency.tier,
-    },
-    {
-      name: 'Lead Time for Changes',
-      key: 'leadTime' as const,
-      current: `${latest.leadTime.value} ${latest.leadTime.unit}`,
-      tier: latest.leadTime.tier,
-    },
-    {
-      name: 'Change Failure Rate',
-      key: 'changeFailureRate' as const,
-      current: `${latest.changeFailureRate.value}%`,
-      tier: latest.changeFailureRate.tier,
-    },
-    {
-      name: 'Time to Restore Service (MTTR)',
-      key: 'mttr' as const,
-      current: latest.mttr.tier === 'n/a' ? 'N/A (No incidents)' : `${latest.mttr.value} ${latest.mttr.unit}`,
-      tier: latest.mttr.tier,
-    },
-  ];
-
-  markdown += `| Metric | Current | 7-Day Trend | 30-Day Trend | 90-Day Trend | Tier |\n`;
-  markdown += `|--------|---------|-------------|--------------|--------------|------|\n`;
-
-  metrics.forEach(metric => {
-    const trend = calculateTrend(metric.key);
-    const sevenDay = trend ? formatTrendChange(trend.sevenDayChange) : '-';
-    const thirtyDay = trend ? formatTrendChange(trend.thirtyDayChange) : '-';
-    const ninetyDay = trend ? formatTrendChange(trend.ninetyDayChange) : '-';
-
-    markdown += `| **${metric.name}** | ${metric.current} | ${sevenDay} | ${thirtyDay} | ${ninetyDay} | ${getTierIcon(metric.tier)} ${metric.tier.charAt(0).toUpperCase() + metric.tier.slice(1)} |\n`;
-  });
-
-  markdown += `\n`;
-
-  // Degradation Alerts
-  if (alerts.length > 0) {
-    markdown += `## ⚠️ Degradation Alerts\n\n`;
-    alerts.forEach(alert => {
-      const icon = alert.severity === 'critical' ? '🔴' : '🟠';
-      markdown += `${icon} **${alert.metric}**: ${alert.message}\n`;
-      markdown += `- Previous (30-day avg): ${alert.previousValue.toFixed(2)}\n`;
-      markdown += `- Current: ${alert.currentValue.toFixed(2)}\n`;
-      markdown += `- Change: ${alert.percentageChange.toFixed(1)}%\n\n`;
-    });
-  } else {
-    markdown += `## ✅ No Degradation Detected\n\nAll metrics are stable or improving compared to 30-day averages.\n\n`;
-  }
-
-  // Tier Reference
-  markdown += `---
-
-## DORA Performance Tiers
-
-| Metric | Elite | High | Medium | Low |
-|--------|-------|------|--------|-----|
-| **Deployment Frequency** | On-demand (multiple/day) | Weekly - Monthly | Monthly - 6 months | < 6 months |
-| **Lead Time for Changes** | < 1 hour | 1 day - 1 week | 1 week - 1 month | 1-6 months |
-| **Change Failure Rate** | 0-15% | 16-30% | 31-45% | > 45% |
-| **Time to Restore Service** | < 1 hour | < 1 day | 1 day - 1 week | > 1 week |
-
-**Source**: [DORA State of DevOps Research](https://dora.dev/)
-
----
-
-## Historical Trends
-
-**Total Snapshots**: ${readHistory().length}
-
-**Data Retention**: All snapshots stored in \`.specweave/metrics/dora-history.jsonl\`
-
-**Calculation Frequency**: After every increment completion (automated via hooks)
-
----
-
-## Related Documentation
-
-- [DORA Metrics (Detailed)](./dora-metrics.md) - Full methodology and measurement details
-- [Release Process](./release-process.md) - Release workflow and best practices
-- [Testing Strategy](./guides/testing-strategy.md) - Testing approach linked to change failure rate
-- [Branch Strategy](./branch-strategy.md) - Git workflow linked to lead time
-
----
-
-## Actions
-
-**If metrics are degrading**:
-
-1. **Review Recent Changes** - What changed in the last 30 days?
-2. **Analyze Root Cause** - Use incident reports, test failures, deployment logs
-3. **Create ADR** - Document decision to address degradation
-4. **Implement Improvements** - Create increment to fix underlying issues
-5. **Monitor Progress** - Track metrics recovery over next 30 days
-
-**If metrics are improving**:
-
-1. **Document Success** - What practices led to improvement?
-2. **Share Knowledge** - Update team playbooks with learnings
-3. **Maintain Momentum** - Continue proven practices
-4. **Set New Goals** - Aim for next tier (High → Elite)
-
----
-
-**Dashboard Auto-Generated**: ${new Date().toISOString()}
-**Generator**: \`plugins/specweave-release/lib/dashboard-generator.ts\`
-`;
-
-  return markdown;
-}
-
-/**
- * Write dashboard to file
- */
-export function writeDashboard(): void {
-  const markdown = generateDashboard();
-
-  // Ensure directory exists
-  const dir = path.dirname(DASHBOARD_PATH);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  // Write dashboard
-  fs.writeFileSync(DASHBOARD_PATH, markdown, 'utf-8');
-
-  console.log(`✓ Dashboard generated: ${DASHBOARD_PATH}`);
-}
-
-// ============================================================================
-// CLI Entry Point
-// ============================================================================
-
-/**
- * CLI tool for dashboard generation
- *
- * Usage: npm run dora:dashboard
- */
-async function main() {
-  try {
-    writeDashboard();
-    console.log('✅ DORA dashboard generated successfully');
-  } catch (error) {
-    console.error('❌ Failed to generate dashboard:', error);
-    process.exit(1);
-  }
-}
-
-// Run CLI if executed directly
-if (require.main === module) {
-  main().catch(console.error);
-}