create-appraisejs 0.2.0-alpha.6 → 0.3.0-alpha.0

package/templates/default/scripts/lib/jsdoc-parser.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import { parseGroupJSDoc } from './jsdoc-parser'
+
+describe('parseGroupJSDoc', () => {
+  it('parses ACTION group metadata', () => {
+    const content = `/**
+ * @name Auth Actions
+ * @description auth flows
+ * @type ACTION
+ */`
+    expect(parseGroupJSDoc(content)).toEqual({
+      name: 'Auth Actions',
+      description: 'auth flows',
+      type: 'ACTION',
+    })
+  })
+
+  it('parses VALIDATION group metadata', () => {
+    const content = `/**
+ * @name Auth Validations
+ * @type VALIDATION
+ */`
+    expect(parseGroupJSDoc(content)).toEqual({
+      name: 'Auth Validations',
+      description: null,
+      type: 'VALIDATION',
+    })
+  })
+
+  it('returns null when @type is missing', () => {
+    const content = `/**
+ * @name Missing Type
+ */`
+    expect(parseGroupJSDoc(content)).toBeNull()
+  })
+
+  it('returns null when @name is missing', () => {
+    const content = `/**
+ * @type ACTION
+ */`
+    expect(parseGroupJSDoc(content)).toBeNull()
+  })
+
+  it('returns null for empty content', () => {
+    expect(parseGroupJSDoc('')).toBeNull()
+  })
+
+  it('parses when imports are before jsdoc', () => {
+    const content = `import { x } from 'y'
+/**
+ * @name Imported Group
+ * @type ACTION
+ */`
+    expect(parseGroupJSDoc(content)?.name).toBe('Imported Group')
+  })
+
+  it('returns null for malformed close', () => {
+    const content = `/**
+ * @name Broken
+ * @type ACTION`
+    expect(parseGroupJSDoc(content)).toBeNull()
+  })
+})

package/templates/default/scripts/lib/jsdoc-parser.ts

@@ -0,0 +1,88 @@
+import { TemplateStepGroupType } from '@prisma/client'
+
+export interface StepGroupJSDoc {
+  name: string
+  description: string | null
+  type: TemplateStepGroupType
+}
+
+/**
+ * Parses JSDoc comment to extract top-of-file step group metadata.
+ * Returns null if no valid group JSDoc is found.
+ */
+export 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
+}

package/templates/default/scripts/lib/step-file-parser.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import { mapTypeToParameterType, parseStepFile, parseStepJSDoc } from './step-file-parser'
+
+describe('parseStepJSDoc', () => {
+  it('parses valid step jsdoc', () => {
+    const content = `/**
+ * @name Click Save
+ * @description clicks save button
+ * @icon MOUSE
+ */
+When("click save", async function () {})`
+    expect(parseStepJSDoc(content, 5)).toEqual({
+      name: 'Click Save',
+      description: 'clicks save button',
+      icon: 'MOUSE',
+    })
+  })
+
+  it('returns null when @icon is missing', () => {
+    const content = `/**
+ * @name Click Save
+ */
+When("click save", async function () {})`
+    expect(parseStepJSDoc(content, 4)).toBeNull()
+  })
+
+  it('returns null when @name is missing', () => {
+    const content = `/**
+ * @icon MOUSE
+ */
+When("click save", async function () {})`
+    expect(parseStepJSDoc(content, 4)).toBeNull()
+  })
+})
+
+describe('mapTypeToParameterType', () => {
+  it('maps SelectorName', () => expect(mapTypeToParameterType('SelectorName')).toBe('LOCATOR'))
+  it('maps string', () => expect(mapTypeToParameterType('string')).toBe('STRING'))
+  it('maps number', () => expect(mapTypeToParameterType('number')).toBe('NUMBER'))
+  it('maps int', () => expect(mapTypeToParameterType('int')).toBe('NUMBER'))
+  it('maps boolean', () => expect(mapTypeToParameterType('boolean')).toBe('BOOLEAN'))
+  it('maps Date', () => expect(mapTypeToParameterType('Date')).toBe('DATE'))
+  it('throws on unsupported type', () => expect(() => mapTypeToParameterType('unknown')).toThrow())
+})
+
+describe('parseStepFile', () => {
+  it('parses minimal valid step file with one When step', () => {
+    const content = `/**
+ * @name Auth Steps
+ * @type ACTION
+ */
+import { When } from "@cucumber/cucumber";
+/**
+ * @name Enter Email
+ * @description fills email
+ * @icon MOUSE
+ */
+When("enter {string}", async function (value: string) {
+  // no-op
+});`
+
+    const parsed = parseStepFile(content, 'automation/steps/actions/auth.step.ts')
+    expect(parsed).not.toBeNull()
+    expect(parsed?.group.name).toBe('Auth Steps')
+    expect(parsed?.steps).toHaveLength(1)
+    expect(parsed?.steps[0].signature).toBe('enter {string}')
+    expect(parsed?.steps[0].keyword).toBe('When')
+    expect(parsed?.steps[0].source).toContain('@name Enter Email')
+    expect(parsed?.steps[0].source).toContain('When("enter {string}"')
+  })
+})

package/templates/default/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/default/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)
+  })
+})