create-appraisejs 0.3.0-alpha.0 → 0.3.0-alpha.1

package/templates/starter/scripts/lib/step-file-parser.ts

@@ -0,0 +1,315 @@
+import { parse } from '@babel/parser'
+import _traverse from '@babel/traverse'
+import type { NodePath } from '@babel/traverse'
+import * as t from '@babel/types'
+import { StepParameterType, TemplateStepIcon } from '@prisma/client'
+import { parseGroupJSDoc, StepGroupJSDoc } from './jsdoc-parser'
+
+const traverse = (_traverse as { default?: typeof _traverse }).default ?? _traverse
+
+export interface StepJSDoc {
+  name: string
+  description: string | null
+  icon: TemplateStepIcon
+}
+
+export interface StepParameter {
+  name: string
+  type: StepParameterType
+  order: number
+}
+
+export interface ParsedStep {
+  jsdoc: StepJSDoc
+  signature: string
+  source: string
+  start: number
+  end: number
+  functionDefinition: string
+  parameters: StepParameter[]
+  keyword: 'When' | 'Then' | 'Given'
+}
+
+export interface StepData {
+  group: StepGroupJSDoc
+  steps: ParsedStep[]
+  filePath: string
+}
+
+/**
+ * Reads the nearest preceding JSDoc block for a step call and extracts metadata.
+ */
+export function parseStepJSDoc(content: string, startLine: number): StepJSDoc | null {
+  const lines = content.split('\n')
+  let jsdocStart = -1
+  for (let i = startLine - 1; i >= 0 && i >= startLine - 20; i--) {
+    const line = lines[i]?.trim()
+    if (line?.includes('*/')) {
+      jsdocStart = i
+      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
+
+  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,
+  }
+}
+
+function findStepJSDocStartOffset(content: string, startLine: number): number | null {
+  const lines = content.split('\n')
+  let jsdocStart = -1
+
+  for (let i = startLine - 1; i >= 0 && i >= startLine - 20; i--) {
+    const line = lines[i]?.trim()
+    if (line?.includes('*/')) {
+      jsdocStart = i
+      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 offset = 0
+  for (let i = 0; i < jsdocStart; i++) {
+    offset += (lines[i]?.length ?? 0) + 1
+  }
+  return offset
+}
+
+/**
+ * Maps TypeScript parameter annotations to persisted step-parameter enum values.
+ */
+export 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 exact source for a step definition call expression.
+ */
+export function extractFunctionDefinition(callExpr: t.CallExpression, sourceCode: string): string {
+  const start = callExpr.start
+  const end = callExpr.end
+  if (start == null || end == null) {
+    throw new Error('Cannot extract function definition: missing position information')
+  }
+
+  let code = sourceCode.slice(start, end).trim()
+  const afterEnd = sourceCode.slice(end, end + 10).trim()
+  if (afterEnd.startsWith(';')) code += ';'
+  return code
+}
+
+/**
+ * Extracts exact source for a step definition including its leading step JSDoc.
+ */
+export function extractStepSource(callExpr: t.CallExpression, sourceCode: string, startLine?: number): string {
+  const { start, end } = extractStepSourceRange(callExpr, sourceCode, startLine)
+  return sourceCode.slice(start, end).trim()
+}
+
+/**
+ * Finds the byte range for a step definition including its leading step JSDoc and trailing semicolon.
+ */
+export function extractStepSourceRange(
+  callExpr: t.CallExpression,
+  sourceCode: string,
+  startLine?: number,
+): { start: number; end: number } {
+  const callStart = callExpr.start
+  const callEnd = callExpr.end
+  if (callStart == null || callEnd == null) {
+    throw new Error('Cannot extract step source: missing position information')
+  }
+
+  const jsdocStart = startLine == null ? null : findStepJSDocStartOffset(sourceCode, startLine)
+  const start = jsdocStart ?? callStart
+
+  let end = callEnd
+  const trailing = sourceCode.slice(callEnd)
+  const semicolonMatch = trailing.match(/^\s*;/)
+  if (semicolonMatch) {
+    end += semicolonMatch[0].length
+  }
+
+  return { start, end }
+}
+
+/**
+ * Parses a `.step.ts` file into group + step definitions from AST.
+ */
+export function parseStepFile(content: string, filePath: string): StepData | null {
+  const group = parseGroupJSDoc(content)
+  if (!group) return null
+
+  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(ast, {
+    CallExpression(path: NodePath<t.CallExpression>) {
+      const node = path.node
+      const callee = node.callee
+      let keyword: 'When' | 'Then' | 'Given' | null = null
+      if (t.isIdentifier(callee) && (callee.name === 'When' || callee.name === 'Then' || callee.name === 'Given')) {
+        keyword = callee.name as 'When' | 'Then' | 'Given'
+      }
+
+      if (!keyword || node.arguments.length < 2) return
+
+      const patternArg = node.arguments[0]
+      if (!t.isStringLiteral(patternArg)) return
+      const signature = patternArg.value
+
+      const funcArg = node.arguments[1]
+      if (!t.isFunction(funcArg)) return
+
+      const lineNumber = node.loc?.start?.line
+      if (lineNumber === undefined) return
+
+      const jsdoc = parseStepJSDoc(content, lineNumber - 1)
+      if (!jsdoc) return
+
+      const parameters: StepParameter[] = []
+      let order = 0
+      for (const param of funcArg.params) {
+        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'
+            }
+          }
+        }
+
+        if (paramName && paramType) {
+          const mappedType = mapTypeToParameterType(paramType)
+          parameters.push({ name: paramName, type: mappedType, order: order++ })
+        }
+      }
+
+      const functionDefinition = extractFunctionDefinition(node, content)
+      const { start, end } = extractStepSourceRange(node, content, lineNumber - 1)
+      const source = content.slice(start, end).trim()
+      steps.push({
+        jsdoc,
+        signature,
+        source,
+        start,
+        end,
+        functionDefinition,
+        parameters,
+        keyword,
+      })
+    },
+  })
+
+  return { group, steps, filePath }
+}

package/templates/starter/scripts/lib/step-matcher.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { StepParameterType } from '@prisma/client'
+import {
+  determineStepTypeAndIcon,
+  extractParametersFromGherkinStep,
+  sameResolvedParameters,
+  signatureToRegex,
+} from './step-matcher'
+
+describe('signatureToRegex', () => {
+  it('matches {string} placeholder', () => {
+    expect(signatureToRegex('click {string}').test('click "submit"')).toBe(true)
+  })
+
+  it('matches {int} placeholder', () => {
+    expect(signatureToRegex('wait {int} seconds').test('wait 15 seconds')).toBe(true)
+  })
+
+  it('matches {boolean} placeholder', () => {
+    expect(signatureToRegex('flag is {boolean}').test('flag is true')).toBe(true)
+  })
+
+  it('matches {number} placeholder', () => {
+    expect(signatureToRegex('value is {number}').test('value is 4.25')).toBe(true)
+  })
+
+  it('matches mixed placeholders', () => {
+    expect(signatureToRegex('set {string} to {int}').test('set "count" to 2')).toBe(true)
+  })
+
+  it('matches no placeholder signature', () => {
+    expect(signatureToRegex('open home').test('open home')).toBe(true)
+  })
+})
+
+describe('extractParametersFromGherkinStep', () => {
+  it('extracts parameters for matching text', () => {
+    const result = extractParametersFromGherkinStep('set "count" to 2', 'set {string} to {int}', [
+      { name: 'name', order: 0, type: StepParameterType.STRING },
+      { name: 'value', order: 1, type: StepParameterType.NUMBER },
+    ])
+    expect(result).toEqual([
+      { name: 'name', value: 'count', order: 0, type: StepParameterType.STRING },
+      { name: 'value', value: '2', order: 1, type: StepParameterType.NUMBER },
+    ])
+  })
+
+  it('returns null for non-matching text', () => {
+    expect(extractParametersFromGherkinStep('open dashboard', 'set {string} to {int}', [])).toBeNull()
+  })
+
+  it('handles parameter count mismatch by truncating to template params', () => {
+    const result = extractParametersFromGherkinStep('set "a" to 2', 'set {string} to {int}', [
+      { name: 'onlyOne', order: 0, type: StepParameterType.STRING },
+    ])
+    expect(result).toEqual([{ name: 'onlyOne', value: 'a', order: 0, type: StepParameterType.STRING }])
+  })
+})
+
+describe('determineStepTypeAndIcon', () => {
+  it('maps Given', () => expect(determineStepTypeAndIcon('Given')).toEqual({ type: 'ACTION', icon: 'NAVIGATION' }))
+  it('maps When', () => expect(determineStepTypeAndIcon('When')).toEqual({ type: 'ACTION', icon: 'MOUSE' }))
+  it('maps Then', () => expect(determineStepTypeAndIcon('Then')).toEqual({ type: 'ASSERTION', icon: 'VALIDATION' }))
+  it('maps And', () => expect(determineStepTypeAndIcon('And')).toEqual({ type: 'ACTION', icon: 'MOUSE' }))
+  it('maps But', () => expect(determineStepTypeAndIcon('But')).toEqual({ type: 'ACTION', icon: 'MOUSE' }))
+  it('maps unknown keyword to default', () =>
+    expect(determineStepTypeAndIcon('Unknown')).toEqual({ type: 'ACTION', icon: 'MOUSE' }))
+})
+
+describe('sameResolvedParameters', () => {
+  const sample = [{ name: 'x', value: '1', order: 0, type: StepParameterType.NUMBER }]
+
+  it('returns true for equal arrays', () => {
+    expect(sameResolvedParameters(sample, [...sample])).toBe(true)
+  })
+
+  it('returns false for different length', () => {
+    expect(sameResolvedParameters(sample, [])).toBe(false)
+  })
+
+  it('returns false for different values', () => {
+    expect(
+      sameResolvedParameters(sample, [{ name: 'x', value: '2', order: 0, type: StepParameterType.NUMBER }]),
+    ).toBe(false)
+  })
+})

package/templates/starter/scripts/lib/step-matcher.ts

@@ -0,0 +1,120 @@
+import { StepParameterType, TemplateStepIcon, TemplateStepType } from '@prisma/client'
+import { ParsedStep } from '../../src/lib/gherkin-parser'
+
+export interface ParameterMatch {
+  name: string
+  value: string
+  order: number
+  type: StepParameterType
+}
+
+export interface TemplateStepMatch {
+  templateStepId: string
+  signature: string
+  parameters: ParameterMatch[]
+}
+
+type TemplateStepCandidate = {
+  id: string
+  signature: string
+  parameters: Array<{ name: string; order: number; type: StepParameterType }>
+}
+
+/**
+ * Converts a template-step signature with placeholders to a regex matcher.
+ */
+export function signatureToRegex(signature: string): RegExp {
+  let pattern = signature.replace(/[.*+?^${}()|[\]\\]/g, match => {
+    if (match === '{' || match === '}') return match
+    return '\\' + match
+  })
+
+  pattern = pattern.replace(/\{string\}/g, '"([^"]+)"')
+  pattern = pattern.replace(/\{int\}/g, '(\\d+)')
+  pattern = pattern.replace(/\{boolean\}/g, '(true|false)')
+  pattern = pattern.replace(/\{number\}/g, '(\\d+(?:\\.\\d+)?)')
+  return new RegExp(`^${pattern}$`, 'i')
+}
+
+/**
+ * Resolves captured parameter values from a gherkin step against a signature.
+ */
+export function extractParametersFromGherkinStep(
+  gherkinText: string,
+  signature: string,
+  templateStepParameters: Array<{ name: string; order: number; type: StepParameterType }>,
+): ParameterMatch[] | null {
+  const regex = signatureToRegex(signature)
+  const match = gherkinText.match(regex)
+
+  if (!match) return null
+
+  const capturedValues = match.slice(1)
+  const parameters: ParameterMatch[] = []
+  for (let i = 0; i < capturedValues.length && i < templateStepParameters.length; i++) {
+    const param = templateStepParameters[i]
+    const value = capturedValues[i]
+    if (value !== undefined) {
+      parameters.push({
+        name: param.name,
+        value,
+        order: param.order,
+        type: param.type,
+      })
+    }
+  }
+
+  return parameters
+}
+
+/**
+ * Finds the first template step whose signature matches the gherkin step text.
+ */
+export function findMatchingTemplateStep(
+  gherkinStep: ParsedStep,
+  templateSteps: TemplateStepCandidate[],
+): TemplateStepMatch | null {
+  for (const templateStep of templateSteps) {
+    const parameters = extractParametersFromGherkinStep(gherkinStep.text, templateStep.signature, templateStep.parameters)
+    if (parameters) {
+      return {
+        templateStepId: templateStep.id,
+        signature: templateStep.signature,
+        parameters,
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Maps gherkin keyword semantics to template step type + icon.
+ */
+export function determineStepTypeAndIcon(keyword: string): { type: TemplateStepType; icon: TemplateStepIcon } {
+  const lowerKeyword = keyword.toLowerCase().trim()
+
+  if (lowerKeyword === 'given') return { type: 'ACTION', icon: 'NAVIGATION' }
+  if (lowerKeyword === 'when') return { type: 'ACTION', icon: 'MOUSE' }
+  if (lowerKeyword === 'then') return { type: 'ASSERTION', icon: 'VALIDATION' }
+  if (lowerKeyword === 'and' || lowerKeyword === 'but') return { type: 'ACTION', icon: 'MOUSE' }
+  return { type: 'ACTION', icon: 'MOUSE' }
+}
+
+/**
+ * Compares resolved parameter lists in order, including metadata fields.
+ */
+export function sameResolvedParameters(left: ParameterMatch[], right: ParameterMatch[]): boolean {
+  if (left.length !== right.length) {
+    return false
+  }
+
+  return left.every((parameter, index) => {
+    const other = right[index]
+    return (
+      parameter.name === other?.name &&
+      parameter.value === other?.value &&
+      parameter.order === other?.order &&
+      parameter.type === other?.type
+    )
+  })
+}

package/templates/starter/scripts/lib/sync-script-runner.ts

@@ -0,0 +1,23 @@
+import prisma from '../../src/config/db-config'
+
+/**
+ * Wraps sync script execution with standardized success/error logging,
+ * exit code handling, and Prisma disconnection in finally.
+ */
+export async function runSyncScript(run: () => Promise<{ errors: string[] } | void>): Promise<void> {
+  try {
+    const result = await run()
+    if (!result || result.errors.length === 0) {
+      console.log('\n✅ Sync completed successfully!')
+      return
+    }
+
+    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()
+  }
+}

package/templates/starter/scripts/lib/sync-summary.ts

@@ -0,0 +1,29 @@
+export type SummarySection = {
+  title: string
+  items: string[]
+}
+
+/**
+ * Prints a normalized "Sync Summary" block used by sync scripts.
+ * Keeping a single printer helps `sync-all.ts` parse output consistently.
+ */
+export function printSyncSummary(
+  metrics: Array<{ label: string; value: number }>,
+  sections: SummarySection[] = [],
+): void {
+  console.log('\n📊 Sync Summary:')
+  metrics.forEach(metric => {
+    console.log(`   ${metric.label}: ${metric.value}`)
+  })
+
+  sections.forEach(section => {
+    if (section.items.length === 0) {
+      return
+    }
+
+    console.log(`\n   ${section.title}:`)
+    section.items.forEach((item, index) => {
+      console.log(`      ${index + 1}. ${item}`)
+    })
+  })
+}

package/templates/starter/scripts/lib/tag-parsing.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { splitTagLine } from './tag-parsing'
+
+describe('splitTagLine', () => {
+  it('splits a single tag', () => {
+    expect(splitTagLine('@smoke')).toEqual(['@smoke'])
+  })
+
+  it('splits multiple tags with mixed whitespace', () => {
+    expect(splitTagLine('@smoke   @demo\t@regression')).toEqual(['@smoke', '@demo', '@regression'])
+  })
+
+  it('returns empty array for empty string', () => {
+    expect(splitTagLine('')).toEqual([])
+  })
+
+  it('filters values without @ prefix', () => {
+    expect(splitTagLine('smoke @demo abc')).toEqual(['@demo'])
+  })
+})

package/templates/starter/scripts/lib/tag-parsing.ts

@@ -0,0 +1,10 @@
+/**
+ * Splits a tag line that may contain multiple tags separated by spaces.
+ * Example: "@smoke @demo" -> ["@smoke", "@demo"]
+ */
+export function splitTagLine(tagLine: string): string[] {
+  return tagLine
+    .split(/\s+/)
+    .filter(tag => tag.trim().startsWith('@'))
+    .map(tag => tag.trim())
+}