create-appraisejs 0.2.0 → 0.3.0-alpha.0

package/templates/default/scripts/sync-template-steps.ts

@@ -6,54 +6,19 @@
  * Filesystem is the source of truth - steps in DB but not in FS will be deleted
  * Run this after merging changes to ensure template step sync
  *
- * Usage: npx tsx scripts/template-step-sync.ts
+ * Usage: npx tsx scripts/sync-template-steps.ts
  */
 
 import { promises as fs } from 'fs'
 import { join } from 'path'
 import { glob } from 'glob'
-import { parse } from '@babel/parser'
-import * as t from '@babel/types'
-import _traverse from '@babel/traverse'
-import type { NodePath } from '@babel/traverse'
 import prettier from 'prettier'
 
-// Handle both ESM and CJS exports
-const traverse = (_traverse as { default?: typeof _traverse }).default ?? _traverse
 import prisma from '../src/config/db-config'
-import { TemplateStepGroupType, TemplateStepType, TemplateStepIcon, StepParameterType } from '@prisma/client'
-
-interface StepGroupJSDoc {
-  name: string
-  description: string | null
-  type: TemplateStepGroupType
-}
-
-interface StepJSDoc {
-  name: string
-  description: string | null
-  icon: TemplateStepIcon
-}
-
-interface StepParameter {
-  name: string
-  type: StepParameterType
-  order: number
-}
-
-interface ParsedStep {
-  jsdoc: StepJSDoc
-  signature: string
-  functionDefinition: string
-  parameters: StepParameter[]
-  keyword: 'When' | 'Then' | 'Given'
-}
-
-interface StepData {
-  group: StepGroupJSDoc
-  steps: ParsedStep[]
-  filePath: string
-}
+import { TemplateStepGroupType, TemplateStepType } from '@prisma/client'
+import { parseStepFile, ParsedStep } from './lib/step-file-parser'
+import { printSyncSummary } from './lib/sync-summary'
+import { runSyncScript } from './lib/sync-script-runner'
 
 interface SyncResult {
   stepsScanned: number
@@ -79,6 +44,8 @@ async function normalizeFunctionDefinition(functionDefinition: string | null | u
   }
 
   try {
+    // Persisting a normalized definition avoids false-positive updates caused by
+    // formatting-only drift between source files and stored DB representation.
     return (
       await prettier.format(source, {
         parser: 'typescript',
@@ -94,399 +61,6 @@ async function normalizeFunctionDefinition(functionDefinition: string | null | u
   }
 }
 
-/**
- * Parses JSDoc comment to extract step group metadata
- * Reused from template-step-group-sync.ts
- */
-function parseGroupJSDoc(content: string): StepGroupJSDoc | null {
-  const lines = content.split('\n')
-
-  if (lines.length === 0) {
-    return null
-  }
-
-  let startLine = 0
-  while (startLine < lines.length) {
-    const line = lines[startLine].trim()
-    if (line === '' || line.startsWith('import ')) {
-      startLine++
-      continue
-    }
-    break
-  }
-
-  if (startLine >= lines.length || !lines[startLine].trim().startsWith('/**')) {
-    return null
-  }
-
-  let hasType = false
-  let endLine = -1
-  let name: string | null = null
-  let description: string | null = null
-  let type: string | null = null
-
-  const maxLines = Math.min(lines.length, startLine + 50)
-  for (let i = startLine; i < maxLines; i++) {
-    const line = lines[i].trim()
-
-    if (line.includes('*/')) {
-      const beforeClose = line.split('*/')[0].trim()
-
-      if (beforeClose.startsWith('* @name') || beforeClose.startsWith('*@name')) {
-        const match = beforeClose.match(/@name\s+(.+)/)
-        if (match) {
-          name = match[1].trim()
-        }
-      } else if (beforeClose.startsWith('* @description') || beforeClose.startsWith('*@description')) {
-        const match = beforeClose.match(/@description\s+(.+)/)
-        if (match) {
-          description = match[1].trim() || null
-        }
-      } else if (beforeClose.startsWith('* @type') || beforeClose.startsWith('*@type')) {
-        hasType = true
-        const match = beforeClose.match(/@type\s+(.+)/)
-        if (match) {
-          type = match[1].trim()
-        }
-      }
-
-      endLine = i
-      break
-    } else if (line.startsWith('* @name') || line.startsWith('*@name')) {
-      const match = line.match(/@name\s+(.+)/)
-      if (match) {
-        name = match[1].trim()
-      }
-    } else if (line.startsWith('* @description') || line.startsWith('*@description')) {
-      const match = line.match(/@description\s+(.+)/)
-      if (match) {
-        description = match[1].trim() || null
-      }
-    } else if (line.startsWith('* @type') || line.startsWith('*@type')) {
-      hasType = true
-      const match = line.match(/@type\s+(.+)/)
-      if (match) {
-        type = match[1].trim()
-      }
-    }
-  }
-
-  if (hasType && endLine >= 0 && name && type) {
-    const normalizedType = type.toUpperCase()
-    if (normalizedType !== 'ACTION' && normalizedType !== 'VALIDATION') {
-      throw new Error(`Invalid @type value: ${type}. Must be ACTION or VALIDATION`)
-    }
-
-    return {
-      name: name.trim(),
-      description: description ? description.trim() : null,
-      type: normalizedType as TemplateStepGroupType,
-    }
-  }
-
-  return null
-}
-
-/**
- * Parses JSDoc comment to extract step metadata
- */
-function parseStepJSDoc(content: string, startLine: number): StepJSDoc | null {
-  const lines = content.split('\n')
-
-  // Look backwards from startLine for JSDoc comment
-  // startLine is 0-based (line number - 1)
-  let jsdocStart = -1
-  for (let i = startLine - 1; i >= 0 && i >= startLine - 20; i--) {
-    const line = lines[i]?.trim()
-    // Check for end of JSDoc (could be on its own line or with content)
-    if (line?.includes('*/')) {
-      // Found end, now find start
-      jsdocStart = i
-      // Look backwards for the start
-      for (let j = i - 1; j >= 0 && j >= i - 10; j--) {
-        const prevLine = lines[j]?.trim()
-        if (prevLine?.startsWith('/**')) {
-          jsdocStart = j
-          break
-        }
-      }
-      break
-    } else if (line?.startsWith('/**')) {
-      jsdocStart = i
-      break
-    }
-  }
-
-  if (jsdocStart === -1) {
-    return null
-  }
-
-  let name: string | null = null
-  let description: string | null = null
-  let icon: string | null = null
-  let foundJSDoc = false
-
-  for (let i = jsdocStart; i < Math.min(lines.length, jsdocStart + 20); i++) {
-    const line = lines[i]?.trim()
-
-    if (line?.startsWith('/**')) {
-      foundJSDoc = true
-      continue
-    }
-
-    if (line?.includes('*/')) {
-      const beforeClose = line.split('*/')[0].trim()
-      if (beforeClose.startsWith('* @name') || beforeClose.startsWith('*@name')) {
-        const match = beforeClose.match(/@name\s+(.+)/)
-        if (match) {
-          name = match[1].trim()
-        }
-      } else if (beforeClose.startsWith('* @description') || beforeClose.startsWith('*@description')) {
-        const match = beforeClose.match(/@description\s+(.+)/)
-        if (match) {
-          description = match[1].trim() || null
-        }
-      } else if (beforeClose.startsWith('* @icon') || beforeClose.startsWith('*@icon')) {
-        const match = beforeClose.match(/@icon\s+(.+)/)
-        if (match) {
-          icon = match[1].trim()
-        }
-      }
-      break
-    }
-
-    if (foundJSDoc) {
-      if (line?.startsWith('* @name') || line?.startsWith('*@name')) {
-        const match = line.match(/@name\s+(.+)/)
-        if (match) {
-          name = match[1].trim()
-        }
-      } else if (line?.startsWith('* @description') || line?.startsWith('*@description')) {
-        const match = line.match(/@description\s+(.+)/)
-        if (match) {
-          description = match[1].trim() || null
-        }
-      } else if (line?.startsWith('* @icon') || line?.startsWith('*@icon')) {
-        const match = line.match(/@icon\s+(.+)/)
-        if (match) {
-          icon = match[1].trim()
-        }
-      }
-    }
-  }
-
-  if (!name || !icon) {
-    return null
-  }
-
-  // Validate icon
-  const iconUpper = icon.toUpperCase()
-  const validIcons = Object.values(TemplateStepIcon)
-  if (!validIcons.includes(iconUpper as TemplateStepIcon)) {
-    throw new Error(`Invalid @icon value: ${icon}. Must be one of: ${validIcons.join(', ')}`)
-  }
-
-  return {
-    name: name.trim(),
-    description: description ? description.trim() : null,
-    icon: iconUpper as TemplateStepIcon,
-  }
-}
-
-/**
- * Maps TypeScript type to StepParameterType
- * Strict mode - throws error for unsupported types
- */
-function mapTypeToParameterType(typeName: string): StepParameterType {
-  const normalized = typeName.trim()
-
-  if (normalized === 'SelectorName') {
-    return StepParameterType.LOCATOR
-  }
-  if (normalized === 'string') {
-    return StepParameterType.STRING
-  }
-  if (normalized === 'number' || normalized === 'int') {
-    return StepParameterType.NUMBER
-  }
-  if (normalized === 'boolean') {
-    return StepParameterType.BOOLEAN
-  }
-  if (normalized === 'Date') {
-    return StepParameterType.DATE
-  }
-
-  throw new Error(
-    `Unsupported parameter type: ${typeName}. Supported types: SelectorName, string, number, int, boolean, Date`,
-  )
-}
-
-/**
- * Extracts function definition code from AST node
- * Returns the complete When/Then/Given call with function, without JSDoc
- * Format: When('pattern', async function(this:CustomWorld, param: type){})
- */
-function extractFunctionDefinition(callExpr: t.CallExpression, keyword: string, sourceCode: string): string {
-  // Get the source code for the entire call expression
-  const start = callExpr.start
-  const end = callExpr.end
-
-  if (start == null || end == null) {
-    throw new Error('Cannot extract function definition: missing position information')
-  }
-
-  // Extract the code - Babel's end position includes the closing parenthesis
-  // After the null check, TypeScript knows start and end are numbers
-  let code = sourceCode.slice(start, end).trim()
-
-  // Check if there's a semicolon immediately after (some files have it, some don't)
-  // Only add if it's clearly there in the source
-  const afterEnd = sourceCode.slice(end, end + 10).trim()
-  if (afterEnd.startsWith(';')) {
-    code += ';'
-  }
-
-  return code
-}
-
-/**
- * Parses a step definition file to extract steps
- */
-function parseStepFile(content: string, filePath: string): StepData | null {
-  const group = parseGroupJSDoc(content)
-  if (!group) {
-    return null
-  }
-
-  // Parse TypeScript AST
-  let ast
-  try {
-    ast = parse(content, {
-      sourceType: 'module',
-      plugins: ['typescript', 'decorators-legacy'],
-    })
-  } catch (error) {
-    throw new Error(`Failed to parse TypeScript: ${error}`)
-  }
-
-  const steps: ParsedStep[] = []
-
-  // Traverse the AST to find When/Then/Given calls
-  traverse(ast, {
-    CallExpression(path: NodePath<t.CallExpression>) {
-      const node = path.node
-      const callee = node.callee
-
-      // Check if this is a When, Then, or Given call
-      let keyword: 'When' | 'Then' | 'Given' | null = null
-      if (t.isIdentifier(callee)) {
-        if (callee.name === 'When' || callee.name === 'Then' || callee.name === 'Given') {
-          keyword = callee.name as 'When' | 'Then' | 'Given'
-        }
-      }
-
-      if (!keyword || node.arguments.length < 2) {
-        return
-      }
-
-      // Extract Gherkin pattern (first argument - should be a string)
-      const patternArg = node.arguments[0]
-      if (!t.isStringLiteral(patternArg)) {
-        return
-      }
-      const signature = patternArg.value
-
-      // Extract function (second argument)
-      const funcArg = node.arguments[1]
-      if (!t.isFunction(funcArg)) {
-        return
-      }
-
-      // Get line number for JSDoc lookup (Babel uses 1-based line numbers)
-      const lineNumber = node.loc?.start?.line
-      if (lineNumber === undefined) {
-        return
-      }
-
-      // Parse step JSDoc (convert to 0-based for array indexing)
-      const jsdoc = parseStepJSDoc(content, lineNumber - 1)
-      if (!jsdoc) {
-        return // Skip steps without JSDoc
-      }
-
-      // Extract parameters
-      const parameters: StepParameter[] = []
-      if (t.isFunction(funcArg) && funcArg.params) {
-        let order = 0
-        for (const param of funcArg.params) {
-          // Skip 'this: CustomWorld' parameter
-          if (t.isIdentifier(param) && param.name === 'this') {
-            continue
-          }
-          if (t.isObjectPattern(param) && param.properties.length === 1) {
-            const prop = param.properties[0]
-            if (t.isObjectProperty(prop) && t.isIdentifier(prop.key) && prop.key.name === 'this') {
-              continue
-            }
-          }
-
-          let paramName: string | null = null
-          let paramType: string | null = null
-
-          if (t.isIdentifier(param)) {
-            paramName = param.name
-            if (param.typeAnnotation && t.isTSTypeAnnotation(param.typeAnnotation)) {
-              const typeAnnotation = param.typeAnnotation.typeAnnotation
-              if (t.isTSTypeReference(typeAnnotation) && t.isIdentifier(typeAnnotation.typeName)) {
-                paramType = typeAnnotation.typeName.name
-              } else if (t.isTSStringKeyword(typeAnnotation)) {
-                paramType = 'string'
-              } else if (t.isTSNumberKeyword(typeAnnotation)) {
-                paramType = 'number'
-              } else if (t.isTSBooleanKeyword(typeAnnotation)) {
-                paramType = 'boolean'
-              }
-            }
-          } else if (t.isObjectPattern(param)) {
-            // Handle destructured parameters (unlikely but possible)
-            continue
-          }
-
-          if (paramName && paramType) {
-            try {
-              const mappedType = mapTypeToParameterType(paramType)
-              parameters.push({
-                name: paramName,
-                type: mappedType,
-                order: order++,
-              })
-            } catch (error) {
-              throw new Error(`Error mapping parameter type in step "${signature}": ${error}`)
-            }
-          }
-        }
-      }
-
-      // Extract function definition
-      const functionDefinition = extractFunctionDefinition(node, keyword, content)
-
-      steps.push({
-        jsdoc,
-        signature,
-        functionDefinition,
-        parameters,
-        keyword,
-      })
-    },
-  })
-
-  return {
-    group,
-    steps,
-    filePath,
-  }
-}
-
 /**
  * Scans step definition files
  */
@@ -522,7 +96,7 @@ async function syncStepsToDatabase(
     deletedSteps: [],
   }
 
-  // Track signatures from filesystem
+  // Signature is treated as the stable sync identity for template steps.
   const fsSignatures = new Set<string>()
 
   // Process each step
@@ -692,49 +266,7 @@ async function syncStepsToDatabase(
 /**
  * Generates and displays sync summary
  */
-function generateSummary(result: SyncResult): void {
-  console.log('\n📊 Sync Summary:')
-  console.log(`   📁 Steps scanned: ${result.stepsScanned}`)
-  console.log(`   ✅ Steps existing: ${result.stepsExisting}`)
-  console.log(`   ➕ Steps created: ${result.stepsCreated}`)
-  console.log(`   🔄 Steps updated: ${result.stepsUpdated}`)
-  console.log(`   🗑️  Steps deleted: ${result.stepsDeleted}`)
-  console.log(`   ❌ Errors: ${result.errors.length}`)
-
-  if (result.createdSteps.length > 0) {
-    console.log('\n   Created steps:')
-    result.createdSteps.forEach((step, index) => {
-      console.log(`      ${index + 1}. ${step.name} (${step.signature}) [${step.group}]`)
-    })
-  }
-
-  if (result.updatedSteps.length > 0) {
-    console.log('\n   Updated steps:')
-    result.updatedSteps.forEach((step, index) => {
-      console.log(`      ${index + 1}. ${step.name} (${step.signature}) [${step.group}]`)
-    })
-  }
-
-  if (result.deletedSteps.length > 0) {
-    console.log('\n   Deleted steps:')
-    result.deletedSteps.forEach((step, index) => {
-      console.log(`      ${index + 1}. ${step.name} (${step.signature}) [${step.group}]`)
-    })
-  }
-
-  if (result.errors.length > 0) {
-    console.log('\n   Errors:')
-    result.errors.forEach((error, index) => {
-      console.log(`      ${index + 1}. ${error}`)
-    })
-  }
-}
-
-/**
- * Main function
- */
-async function main() {
-  try {
+async function main(): Promise<SyncResult | void> {
     console.log('🔄 Starting template step sync...')
     console.log('This will scan step definition files and sync template steps to database.')
     console.log('Filesystem is the source of truth - steps in DB but not in FS will be deleted.\n')
@@ -823,21 +355,32 @@ async function main() {
     // Add parsing errors to result
     result.errors.push(...errors)
 
-    // Generate summary
-    generateSummary(result)
-
-    if (result.errors.length === 0) {
-      console.log('\n✅ Sync completed successfully!')
-    } else {
-      console.log('\n⚠️  Sync completed with errors. Please review the errors above.')
-      process.exit(1)
-    }
-  } catch (error) {
-    console.error('\n❌ Error during sync:', error)
-    process.exit(1)
-  } finally {
-    await prisma.$disconnect()
-  }
+    printSyncSummary(
+      [
+        { label: '📁 Steps scanned', value: result.stepsScanned },
+        { label: '✅ Steps existing', value: result.stepsExisting },
+        { label: '➕ Steps created', value: result.stepsCreated },
+        { label: '🔄 Steps updated', value: result.stepsUpdated },
+        { label: '🗑️  Steps deleted', value: result.stepsDeleted },
+        { label: '❌ Errors', value: result.errors.length },
+      ],
+      [
+        {
+          title: 'Created steps',
+          items: result.createdSteps.map(step => `${step.name} (${step.signature}) [${step.group}]`),
+        },
+        {
+          title: 'Updated steps',
+          items: result.updatedSteps.map(step => `${step.name} (${step.signature}) [${step.group}]`),
+        },
+        {
+          title: 'Deleted steps',
+          items: result.deletedSteps.map(step => `${step.name} (${step.signature}) [${step.group}]`),
+        },
+        { title: 'Errors', items: result.errors },
+      ],
+    )
+    return result
 }
 
-main()
+runSyncScript(main)