@planningcenter/tapestry-migration-cli 2.3.0-rc.8 → 2.3.0

package/src/reportGenerator.ts

@@ -0,0 +1,450 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from "fs"
+import { join, relative } from "path"
+
+type Weight = 1 | 2 | 3 | 4 | 5
+export interface WeightConfig {
+  [scope: string]: Weight
+  default: Weight
+}
+
+interface CommentData {
+  file: string
+  line: number
+  scope: string
+  text: string
+}
+
+interface CommentStats {
+  count: number
+  examples: string[]
+  files: string[]
+  normalizedText: string
+  scope: string
+  weight: number
+}
+
+export const WEIGHT_CONFIGS: { [key: string]: WeightConfig } = {
+  button: {
+    default: 1,
+    hover: 4,
+    href: 2,
+    mediaQueries: 4,
+    spreadAttribute: 5,
+    style: 3,
+    styleProps: 3,
+    "theme/variant": 2,
+    tooltip: 2,
+    unsupported: 3,
+  },
+}
+
+/**
+ * Extracts tapestry-migration comments from a file
+ */
+function extractCommentsFromFile(filePath: string): CommentData[] {
+  const content = readFileSync(filePath, "utf-8")
+  const comments: CommentData[] = []
+
+  // Match both JSX and regular comment formats:
+  // {/* TODO: tapestry-migration (scope): text */}
+  // /* TODO: tapestry-migration (scope): text */
+  // Use lazy matching with [\s\S]*? to capture everything including * until we hit the closing */
+  const commentRegex =
+    /(?:\{\/\*|\/\*)\s*TODO:\s*tapestry-migration\s*\(([^)]+)\):\s*([\s\S]*?)\s*\*\/\}?/g
+
+  let match
+  while ((match = commentRegex.exec(content)) !== null) {
+    const scope = match[1].trim()
+    const text = match[2].trim()
+
+    // Calculate line number
+    const beforeMatch = content.substring(0, match.index)
+    const line = beforeMatch.split("\n").length
+
+    comments.push({
+      file: filePath,
+      line,
+      scope,
+      text,
+    })
+  }
+
+  return comments
+}
+
+/**
+ * Recursively scans a directory for files with specific extensions
+ */
+function scanDirectory(
+  dirPath: string,
+  extensions: string[] = [".js", ".jsx", ".ts", ".tsx"]
+): string[] {
+  const files: string[] = []
+
+  function scan(currentPath: string) {
+    const entries = readdirSync(currentPath)
+
+    for (const entry of entries) {
+      const fullPath = join(currentPath, entry)
+      const stat = statSync(fullPath)
+
+      if (stat.isDirectory()) {
+        // Skip node_modules and other common ignore patterns
+        if (
+          !entry.startsWith(".") &&
+          entry !== "node_modules" &&
+          entry !== "dist" &&
+          entry !== "build"
+        ) {
+          scan(fullPath)
+        }
+      } else if (
+        stat.isFile() &&
+        extensions.some((ext) => entry.endsWith(ext))
+      ) {
+        files.push(fullPath)
+      }
+    }
+  }
+
+  const stat = statSync(dirPath)
+  if (stat.isFile()) {
+    files.push(dirPath)
+  } else {
+    scan(dirPath)
+  }
+
+  return files
+}
+
+/**
+ * Finds and replaces attribute values with balanced braces
+ */
+function replaceBalancedBraces(text: string): string {
+  const attrPattern = /(\w+)=\{/g
+  let result = text
+  let match
+
+  // Find all attribute={...} patterns
+  const replacements: Array<{
+    end: number
+    replacement: string
+    start: number
+  }> = []
+
+  while ((match = attrPattern.exec(text)) !== null) {
+    const attrName = match[1]
+    const startPos = match.index
+    const braceStartPos = match.index + match[0].length - 1 // Position of opening {
+
+    // Count balanced braces
+    let braceCount = 1
+    let i = braceStartPos + 1
+
+    while (i < text.length && braceCount > 0) {
+      if (text[i] === "{") braceCount++
+      else if (text[i] === "}") braceCount--
+      i++
+    }
+
+    if (braceCount === 0) {
+      // Found balanced braces
+      replacements.push({
+        end: i,
+        replacement: `${attrName}="..."`,
+        start: startPos,
+      })
+    }
+  }
+
+  // Apply replacements in reverse order to maintain positions
+  for (let i = replacements.length - 1; i >= 0; i--) {
+    const { end, replacement, start } = replacements[i]
+    result = result.substring(0, start) + replacement + result.substring(end)
+  }
+
+  return result
+}
+
+/**
+ * Normalizes comment text by replacing specific values with placeholders
+ * to group similar comments together
+ */
+function normalizeCommentText(text: string): string {
+  let normalized = text
+
+  // Replace attribute values in curly braces (handling nested braces)
+  normalized = replaceBalancedBraces(normalized)
+
+  // Replace attribute values in quotes
+  normalized = normalized.replace(/(\w+)="[^"]*"/g, '$1="..."')
+
+  // Replace standalone numbers with "..."
+  normalized = normalized.replace(/\b\d+\b/g, '"..."')
+
+  return normalized
+}
+
+/**
+ * Gets the weight for a given scope
+ */
+function getScopeWeight(scope: string, config: WeightConfig): number {
+  // Try exact match first
+  if (scope in config) {
+    return config[scope]
+  }
+
+  // Try partial match (e.g., "theme/variant" would match if scope contains "theme")
+  for (const [key, weight] of Object.entries(config)) {
+    if (scope.includes(key)) {
+      return weight
+    }
+  }
+
+  // Default weight
+  return config.default || 1
+}
+
+/**
+ * Aggregates comment data by scope and normalized text
+ */
+function aggregateComments(
+  comments: CommentData[],
+  weightConfig: WeightConfig
+): CommentStats[] {
+  const statsMap = new Map<string, CommentStats>()
+
+  for (const comment of comments) {
+    const normalizedText = normalizeCommentText(comment.text)
+    const key = `${comment.scope}|||${normalizedText}`
+
+    if (statsMap.has(key)) {
+      const stats = statsMap.get(key)!
+      stats.count++
+      if (!stats.files.includes(comment.file)) {
+        stats.files.push(comment.file)
+      }
+      // Keep a few examples of the original text (max 5)
+      if (stats.examples.length < 5 && !stats.examples.includes(comment.text)) {
+        stats.examples.push(comment.text)
+      }
+    } else {
+      const weight = getScopeWeight(comment.scope, weightConfig)
+      statsMap.set(key, {
+        count: 1,
+        examples: [comment.text],
+        files: [comment.file],
+        normalizedText,
+        scope: comment.scope,
+        weight,
+      })
+    }
+  }
+
+  return Array.from(statsMap.values()).sort((a, b) => {
+    // Sort by total effort (weight * count) descending, then by scope
+    const effortA = a.weight * a.count
+    const effortB = b.weight * b.count
+    if (effortA !== effortB) {
+      return effortB - effortA
+    }
+    return a.scope.localeCompare(b.scope)
+  })
+}
+
+/**
+ * Generates a markdown report from comment statistics
+ */
+function generateMarkdownReport(
+  stats: CommentStats[],
+  allComments: CommentData[],
+  basePath: string
+): string {
+  const totalComments = allComments.length
+  const uniqueCommentTypes = stats.length
+  const affectedFiles = new Set(allComments.map((c) => c.file)).size
+
+  // Calculate effort breakdown by type (scope)
+  const effortByScope = new Map<string, { count: number; effort: number }>()
+  for (const stat of stats) {
+    if (!effortByScope.has(stat.scope)) {
+      effortByScope.set(stat.scope, { count: 0, effort: 0 })
+    }
+    const data = effortByScope.get(stat.scope)!
+    data.count += stat.count
+    data.effort += stat.weight * stat.count
+  }
+
+  const lines: string[] = [
+    "# Tapestry Migration Report",
+    "",
+    `**Generated:** ${new Date().toISOString()}`,
+    "",
+    "## Overview",
+    "",
+  ]
+
+  // Add overview table sorted by effort
+  lines.push("| Type | Count | Effort Points |")
+  lines.push("|------|-------|---------------|")
+
+  for (const [scope, data] of Array.from(effortByScope.entries()).sort(
+    (a, b) => b[1].effort - a[1].effort
+  )) {
+    lines.push(`| ${scope} | ${data.count} | ${data.effort} |`)
+  }
+
+  lines.push("")
+  lines.push("## Summary")
+  lines.push("")
+  lines.push(`- **Total Comments:** ${totalComments}`)
+  lines.push(`- **Unique Comment Types:** ${uniqueCommentTypes}`)
+  lines.push(`- **Affected Files:** ${affectedFiles}`)
+  lines.push("")
+  lines.push("### Effort by Difficulty")
+  lines.push("")
+
+  // Calculate effort breakdown by difficulty level
+  const effortByDifficulty = new Map<
+    string,
+    { count: number; effort: number }
+  >()
+  for (const stat of stats) {
+    let difficulty: string
+    if (stat.weight >= 5) difficulty = "High (5+ pts)"
+    else if (stat.weight >= 3) difficulty = "Medium (3-4 pts)"
+    else difficulty = "Low (1-2 pts)"
+
+    if (!effortByDifficulty.has(difficulty)) {
+      effortByDifficulty.set(difficulty, { count: 0, effort: 0 })
+    }
+    const data = effortByDifficulty.get(difficulty)!
+    data.count += stat.count
+    data.effort += stat.weight * stat.count
+  }
+
+  for (const [difficulty, data] of Array.from(
+    effortByDifficulty.entries()
+  ).sort((a, b) => b[1].effort - a[1].effort)) {
+    lines.push(`- **${difficulty}:** ${data.count} occurrences`)
+  }
+
+  lines.push("")
+  lines.push("## Comments by Effort (sorted by total effort)")
+  lines.push("")
+  lines.push(
+    "_Items are sorted by total effort (weight × occurrences) to help prioritize migration work._"
+  )
+  lines.push("")
+
+  // Group by scope
+  const byScope = new Map<string, CommentStats[]>()
+  for (const stat of stats) {
+    if (!byScope.has(stat.scope)) {
+      byScope.set(stat.scope, [])
+    }
+    byScope.get(stat.scope)!.push(stat)
+  }
+
+  for (const [scope, scopeStats] of Array.from(byScope.entries()).sort(
+    (a, b) => {
+      // Sort by total effort within scope
+      const effortA = a[1].reduce((sum, s) => sum + s.weight * s.count, 0)
+      const effortB = b[1].reduce((sum, s) => sum + s.weight * s.count, 0)
+      return effortB - effortA
+    }
+  )) {
+    const scopeTotal = scopeStats.reduce((sum, s) => sum + s.count, 0)
+    lines.push(`### ${scope} (${scopeTotal} occurrences)`)
+    lines.push("")
+
+    for (const stat of scopeStats) {
+      lines.push(`#### ${stat.normalizedText}`)
+      lines.push("")
+      lines.push(`- **Occurrences:** ${stat.count}`)
+      lines.push(`- **Files affected:** ${stat.files.length}`)
+      lines.push("")
+
+      // Show examples if we have variations
+      if (
+        stat.examples.length > 1 ||
+        stat.examples[0] !== stat.normalizedText
+      ) {
+        lines.push("**Example variations:**")
+        for (const example of stat.examples) {
+          lines.push(`- ${example}`)
+        }
+        lines.push("")
+      }
+
+      if (stat.files.length <= 10) {
+        lines.push("**Files:**")
+        for (const file of stat.files) {
+          lines.push(`- \`${relative(basePath, file)}\``)
+        }
+      } else {
+        lines.push("**Sample files (first 10):**")
+        for (const file of stat.files.slice(0, 10)) {
+          lines.push(`- \`${relative(basePath, file)}\``)
+        }
+        lines.push(`- _(and ${stat.files.length - 10} more)_`)
+      }
+      lines.push("")
+    }
+  }
+
+  return lines.join("\n")
+}
+
+/**
+ * Main function to generate and save the migration report
+ */
+export function generateMigrationReport({
+  targetPath,
+  outputPath,
+  weightConfig,
+}: {
+  outputPath?: string
+  targetPath: string
+  weightConfig: WeightConfig
+}): void {
+  console.log("📊 Generating migration report...")
+
+  // Scan for files
+  const files = scanDirectory(targetPath)
+  console.log(`📁 Scanning ${files.length} files...`)
+
+  // Extract all comments
+  const allComments: CommentData[] = []
+  for (const file of files) {
+    const comments = extractCommentsFromFile(file)
+    allComments.push(...comments)
+  }
+
+  if (allComments.length === 0) {
+    console.log("✅ No migration comments found!")
+    return
+  }
+
+  // Aggregate statistics
+  const stats = aggregateComments(allComments, weightConfig)
+
+  // Generate markdown report
+  const report = generateMarkdownReport(stats, allComments, targetPath)
+
+  // Determine output path
+  const finalOutputPath =
+    outputPath || join(process.cwd(), "MIGRATION_REPORT.md")
+
+  // Write report
+  writeFileSync(finalOutputPath, report, "utf-8")
+
+  const totalEffort = stats.reduce((sum, s) => sum + s.weight * s.count, 0)
+  console.log(`✅ Report generated: ${finalOutputPath}`)
+  console.log(`   Total comments: ${allComments.length}`)
+  console.log(`   Unique types: ${stats.length}`)
+  console.log(
+    `   Affected files: ${new Set(allComments.map((c) => c.file)).size}`
+  )
+  console.log(`   Estimated effort: ${totalEffort} points`)
+}

package/src/shared/types.ts

@@ -2,5 +2,6 @@ export interface Options {
   fix?: boolean
   jsTheme?: string
   path: string
+  reportPath?: string
   verbose?: boolean
 }