create-appraisejs 0.3.0 → 0.3.1-alpha.1

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

@@ -1,88 +1,5 @@
-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
-}
+export {
+  readJSDocTag,
+  parseGroupJSDocStrict as parseGroupJSDoc,
+  type StepGroupJSDoc,
+} from '@/lib/jsdoc/template-step-jsdoc'

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

@@ -2,16 +2,19 @@ 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'
+import { StepParameterType } from '@prisma/client'
+import {
+  findNearestJSDocStart,
+  parseGroupJSDocStrict as parseGroupJSDoc,
+  parseStepJSDocStrict as parseStepJSDoc,
+  type StepGroupJSDoc,
+  type StepJSDoc,
+} from '@/lib/jsdoc/template-step-jsdoc'
 
 const traverse = (_traverse as { default?: typeof _traverse }).default ?? _traverse
 
-export interface StepJSDoc {
-  name: string
-  description: string | null
-  icon: TemplateStepIcon
-}
+export type { StepJSDoc }
+export { parseStepJSDoc }
 
 export interface StepParameter {
   name: string
@@ -36,112 +39,13 @@ export interface StepData {
   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,
-  }
-}
+type StepKeyword = ParsedStep['keyword']
 
 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
-    }
-  }
+  const jsdocStart = findNearestJSDocStart(lines, startLine)
 
-  if (jsdocStart === -1) {
+  if (jsdocStart == null) {
     return null
   }
 
@@ -218,6 +122,102 @@ export function extractStepSourceRange(
   return { start, end }
 }
 
+function getStepKeyword(node: t.CallExpression): StepKeyword | null {
+  const callee = node.callee
+  return t.isIdentifier(callee) && (callee.name === 'When' || callee.name === 'Then' || callee.name === 'Given')
+    ? callee.name
+    : null
+}
+
+function getStepSignature(node: t.CallExpression): string | null {
+  const patternArg = node.arguments[0]
+  return t.isStringLiteral(patternArg) ? patternArg.value : null
+}
+
+function getStepFunction(node: t.CallExpression): t.Function | null {
+  const funcArg = node.arguments[1]
+  return t.isFunction(funcArg) ? funcArg : null
+}
+
+function isCucumberWorldParam(param: t.Function['params'][number]): boolean {
+  if (t.isIdentifier(param)) {
+    return param.name === 'this'
+  }
+
+  if (!t.isObjectPattern(param) || param.properties.length !== 1) {
+    return false
+  }
+
+  const prop = param.properties[0]
+  return t.isObjectProperty(prop) && t.isIdentifier(prop.key) && prop.key.name === 'this'
+}
+
+function getIdentifierParamType(param: t.Identifier): string | null {
+  if (!param.typeAnnotation || !t.isTSTypeAnnotation(param.typeAnnotation)) {
+    return null
+  }
+
+  const typeAnnotation = param.typeAnnotation.typeAnnotation
+  if (t.isTSTypeReference(typeAnnotation) && t.isIdentifier(typeAnnotation.typeName)) {
+    return typeAnnotation.typeName.name
+  }
+
+  if (t.isTSStringKeyword(typeAnnotation)) return 'string'
+  if (t.isTSNumberKeyword(typeAnnotation)) return 'number'
+  if (t.isTSBooleanKeyword(typeAnnotation)) return 'boolean'
+  return null
+}
+
+function parseStepParameters(params: t.Function['params']): StepParameter[] {
+  const parameters: StepParameter[] = []
+
+  for (const param of params) {
+    if (isCucumberWorldParam(param) || !t.isIdentifier(param)) {
+      continue
+    }
+
+    const paramType = getIdentifierParamType(param)
+    if (!paramType) {
+      continue
+    }
+
+    parameters.push({
+      name: param.name,
+      type: mapTypeToParameterType(paramType),
+      order: parameters.length,
+    })
+  }
+
+  return parameters
+}
+
+function parseStepCall(node: t.CallExpression, content: string): ParsedStep | null {
+  const keyword = getStepKeyword(node)
+  if (!keyword || node.arguments.length < 2) return null
+
+  const signature = getStepSignature(node)
+  const funcArg = getStepFunction(node)
+  const lineNumber = node.loc?.start?.line
+  if (!signature || !funcArg || lineNumber === undefined) return null
+
+  const jsdoc = parseStepJSDoc(content, lineNumber - 1)
+  if (!jsdoc) return null
+
+  const functionDefinition = extractFunctionDefinition(node, content)
+  const { start, end } = extractStepSourceRange(node, content, lineNumber - 1)
+
+  return {
+    jsdoc,
+    signature,
+    source: content.slice(start, end).trim(),
+    start,
+    end,
+    functionDefinition,
+    parameters: parseStepParameters(funcArg.params),
+    keyword,
+  }
+}
+
 /**
  * Parses a `.step.ts` file into group + step definitions from AST.
  */
@@ -239,75 +239,8 @@ export function parseStepFile(content: string, filePath: string): StepData | nul
 
   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,
-      })
+      const step = parseStepCall(path.node, content)
+      if (step) steps.push(step)
     },
   })
 

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

@@ -79,8 +79,8 @@ describe('sameResolvedParameters', () => {
   })
 
   it('returns false for different values', () => {
-    expect(
-      sameResolvedParameters(sample, [{ name: 'x', value: '2', order: 0, type: StepParameterType.NUMBER }]),
-    ).toBe(false)
+    expect(sameResolvedParameters(sample, [{ name: 'x', value: '2', order: 0, type: StepParameterType.NUMBER }])).toBe(
+      false,
+    )
   })
 })

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

@@ -75,7 +75,11 @@ export function findMatchingTemplateStep(
   templateSteps: TemplateStepCandidate[],
 ): TemplateStepMatch | null {
   for (const templateStep of templateSteps) {
-    const parameters = extractParametersFromGherkinStep(gherkinStep.text, templateStep.signature, templateStep.parameters)
+    const parameters = extractParametersFromGherkinStep(
+      gherkinStep.text,
+      templateStep.signature,
+      templateStep.parameters,
+    )
     if (parameters) {
       return {
         templateStepId: templateStep.id,

package/templates/starter/scripts/lib/template-step-installer.test.ts

@@ -116,7 +116,7 @@ When('click {string}', async function () {})`),
     expect(result.status).toBe('installed')
     const content = await fs.readFile(path.join(workspace, 'automation/steps/actions/click.step.ts'), 'utf8')
     expect(content).toContain("import { helper } from './helper'")
-    expect(content).toContain("// Existing note")
+    expect(content).toContain('// Existing note')
     expect(content).toContain("When('existing click'")
     expect(content).toContain("When('click {string}'")
     expect(content).toContain('Then')
@@ -185,7 +185,9 @@ When('click {string}', async function () {
   await Promise.resolve('new')
 })`)
 
-    await expect(installTemplateStepPayload(payload, { projectRoot: workspace })).rejects.toThrow('Re-run with --overwrite')
+    await expect(installTemplateStepPayload(payload, { projectRoot: workspace })).rejects.toThrow(
+      'Re-run with --overwrite',
+    )
 
     const overwriteResult = await installTemplateStepPayload(payload, {
       projectRoot: workspace,

package/templates/starter/scripts/lib/template-step-installer.ts

@@ -33,7 +33,10 @@ type ExistingStepMatch = {
   source: string
 }
 
-const STEP_FILE_PATTERNS = ['automation/steps/actions/**/*.step.ts', 'automation/steps/validations/**/*.step.ts'] as const
+const STEP_FILE_PATTERNS = [
+  'automation/steps/actions/**/*.step.ts',
+  'automation/steps/validations/**/*.step.ts',
+] as const
 const RUNTIME_IMPORT_PATH = '../../../packages/cucumber-runtime/src/index.js'
 const REQUIRED_RUNTIME_IMPORTS = [
   'When',
@@ -46,7 +49,8 @@ const REQUIRED_RUNTIME_IMPORTS = [
   'generateRandomData',
   'RandomDataType',
 ] as const
-const PLACEHOLDER_COMMENT = '// This file is generated automatically. Add template steps to this group to generate content.'
+const PLACEHOLDER_COMMENT =
+  '// This file is generated automatically. Add template steps to this group to generate content.'
 
 function parseTypeScriptModule(content: string) {
   return parse(content, {
@@ -68,7 +72,13 @@ function getGroupDirectoryName(type: TemplateStepGroupType): 'actions' | 'valida
 }
 
 function getGroupFilePath(projectRoot: string, groupName: string, type: TemplateStepGroupType): string {
-  return path.join(projectRoot, 'automation', 'steps', getGroupDirectoryName(type), `${getGroupFileName(groupName)}.step.ts`)
+  return path.join(
+    projectRoot,
+    'automation',
+    'steps',
+    getGroupDirectoryName(type),
+    `${getGroupFileName(groupName)}.step.ts`,
+  )
 }
 
 function generateGroupJSDoc(name: string, description: string | null, type: TemplateStepGroupType): string {
@@ -289,7 +299,9 @@ async function buildUpdatedGroupFileContent(
     })
   }
 
-  const sections = [generateGroupJSDoc(payload.step.group.name, payload.step.group.description, payload.step.group.type)]
+  const sections = [
+    generateGroupJSDoc(payload.step.group.name, payload.step.group.description, payload.step.group.type),
+  ]
   const mergedImports = mergeImports(existingContent)
   if (mergedImports.trim()) {
     sections.push(mergedImports)

package/templates/starter/scripts/lib/template-step-registry.test.ts

@@ -73,7 +73,7 @@ When('click {string}', async function (this: CustomWorld, elementName: SelectorN
     expect(registry.fragments).toEqual([
       {
         path: 'fragments/click/click-element.ts',
-        content: expect.stringContaining("@name click element"),
+        content: expect.stringContaining('@name click element'),
       },
     ])
     expect(registry.fragments[0]?.content).toContain("When('click {string}'")

package/templates/starter/scripts/lib/template-step-registry.ts

@@ -37,7 +37,10 @@ export type BuiltStepRegistry = {
   fragments: StepRegistryFragment[]
 }
 
-const STEP_FILE_PATTERNS = ['automation/steps/actions/**/*.step.ts', 'automation/steps/validations/**/*.step.ts'] as const
+const STEP_FILE_PATTERNS = [
+  'automation/steps/actions/**/*.step.ts',
+  'automation/steps/validations/**/*.step.ts',
+] as const
 
 export function slugifyRegistryName(value: string): string {
   return value

package/templates/starter/scripts/lib/template-sync-utils.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  extractModulePathFromAutomationFile,
+  getAutomationLocatorMapPath,
+  shouldBackfillLegacyEnvironmentConfig,
+  shouldExcludeTemplatePath,
+} from '../../src/lib/template-sync-utils'
+
+describe('template sync utils', () => {
+  it('excludes generated and local-only template paths', () => {
+    expect(shouldExcludeTemplatePath('node_modules/react/index.js')).toBe(true)
+    expect(shouldExcludeTemplatePath('automation/reports/latest.json')).toBe(true)
+    expect(shouldExcludeTemplatePath('prisma/dev.sqlite3')).toBe(true)
+    expect(shouldExcludeTemplatePath('src/app/page.tsx')).toBe(false)
+  })
+
+  it('detects whether legacy environment config should be backfilled', () => {
+    expect(shouldBackfillLegacyEnvironmentConfig(false, true)).toBe(true)
+    expect(shouldBackfillLegacyEnvironmentConfig(true, true)).toBe(false)
+    expect(shouldBackfillLegacyEnvironmentConfig(false, false)).toBe(false)
+  })
+
+  it('builds automation paths and extracts module paths from automation files', () => {
+    expect(getAutomationLocatorMapPath('/repo')).toBe('/repo/automation/mapping/locator-map.json')
+    expect(
+      extractModulePathFromAutomationFile(
+        '/repo/automation/features/payments/refunds/test.feature',
+        '/repo',
+        'features',
+      ),
+    ).toBe('/payments/refunds')
+    expect(extractModulePathFromAutomationFile('/repo/automation/locators/root.ts', '/repo', 'locators')).toBe('/')
+  })
+})

package/templates/starter/scripts/run-fallow-commit.mjs

@@ -0,0 +1,21 @@
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const repoRoot = path.resolve(scriptDir, '..')
+// Invoke the package CLI via node — Windows cannot spawn extensionless .bin shims directly.
+const fallowCli = path.join(repoRoot, 'node_modules', 'fallow', 'bin', 'fallow')
+const fallowArgs = ['audit', '--base', 'HEAD', '--format', 'json', '--quiet', '--explain', '--fail-on-issues']
+
+const env = { ...process.env }
+delete env.GIT_INDEX_FILE
+
+const result = spawnSync(process.execPath, [fallowCli, ...fallowArgs], { cwd: repoRoot, env, stdio: 'inherit' })
+
+if (result.error) {
+  console.error(result.error)
+  process.exit(2)
+}
+
+process.exit(result.status ?? 1)

package/templates/starter/scripts/sync-all.ts

@@ -200,7 +200,7 @@ function displaySummary(summary: SyncSummary): void {
     const status = result.success ? '✅' : '❌'
     const duration = `${(result.duration / 1000).toFixed(2)}s`
     console.log(`   ${index + 1}. ${status} ${result.name} (${result.description}) - ${duration}`)
-    
+
     if (!result.success) {
       if (result.exitCode !== null) {
         console.log(`      Exit code: ${result.exitCode}`)
@@ -252,7 +252,7 @@ async function main(): Promise<number> {
   for (const scriptId of SYNC_SCRIPT_IDS) {
     const result = await executeSyncScript(scriptId)
     results.push(result)
-    
+
     // Continue execution even if script failed (as per user requirement)
     // The script will log the failure but continue with remaining scripts
   }
@@ -278,10 +278,11 @@ async function main(): Promise<number> {
 }
 
 // Run the main function
-main().catch(error => {
-  console.error('\n❌ Fatal error during sync orchestration:', error)
-  return 1
-})
+main()
+  .catch(error => {
+    console.error('\n❌ Fatal error during sync orchestration:', error)
+    return 1
+  })
   .then(exitCode => {
     process.exit(exitCode)
   })