create-appraisejs 0.2.0 → 0.3.0-alpha.1

package/templates/blank/scripts/install-template-step.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env tsx
+
+import path from 'path'
+import { existsSync, promises as fs } from 'fs'
+import { spawn } from 'child_process'
+import { installTemplateStepPayload, type TemplateStepInstallPayload } from './lib/template-step-installer'
+
+type CliOptions = {
+  payloadFile: string
+  overwrite: boolean
+  dryRun: boolean
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  let payloadFile = ''
+  let overwrite = false
+  let dryRun = false
+
+  for (let index = 0; index < argv.length; index++) {
+    const current = argv[index]
+    if (current === '--payload-file') {
+      payloadFile = argv[index + 1] ?? ''
+      index++
+      continue
+    }
+    if (current === '--overwrite') {
+      overwrite = true
+      continue
+    }
+    if (current === '--dry-run') {
+      dryRun = true
+      continue
+    }
+  }
+
+  if (!payloadFile) {
+    throw new Error('Missing required --payload-file argument.')
+  }
+
+  return {
+    payloadFile,
+    overwrite,
+    dryRun,
+  }
+}
+
+function detectPackageManager(projectRoot: string): 'npm' | 'pnpm' | 'yarn' | 'bun' {
+  const userAgent = process.env.npm_config_user_agent ?? ''
+  if (userAgent.startsWith('pnpm/')) return 'pnpm'
+  if (userAgent.startsWith('yarn/')) return 'yarn'
+  if (userAgent.startsWith('bun/')) return 'bun'
+  if (userAgent.startsWith('npm/')) return 'npm'
+
+  if (existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn'
+  if (existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun'
+  return 'npm'
+}
+
+function getRunArgs(packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun', scriptName: string): string[] {
+  if (packageManager === 'npm' || packageManager === 'pnpm' || packageManager === 'bun') {
+    return ['run', scriptName]
+  }
+
+  return ['run', scriptName]
+}
+
+async function runScript(projectRoot: string, packageManager: 'npm' | 'pnpm' | 'yarn' | 'bun', scriptName: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(packageManager, getRunArgs(packageManager, scriptName), {
+      cwd: projectRoot,
+      stdio: 'inherit',
+      env: process.env,
+    })
+
+    child.on('error', reject)
+    child.on('close', code => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      reject(new Error(`${packageManager} run ${scriptName} exited with code ${code}`))
+    })
+  })
+}
+
+async function readPayload(payloadFile: string): Promise<TemplateStepInstallPayload> {
+  const raw = await fs.readFile(payloadFile, 'utf8')
+  return JSON.parse(raw) as TemplateStepInstallPayload
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2))
+  const projectRoot = process.cwd()
+  const payloadFile = path.resolve(projectRoot, options.payloadFile)
+  const payload = await readPayload(payloadFile)
+
+  const result = await installTemplateStepPayload(payload, {
+    projectRoot,
+    overwrite: options.overwrite,
+    dryRun: options.dryRun,
+  })
+
+  console.log(result.reason)
+  console.log(`Target file: ${path.relative(projectRoot, result.targetFilePath)}`)
+
+  if (options.dryRun) {
+    if (result.changed) {
+      console.log('Dry run: would run sync-template-step-groups')
+      console.log('Dry run: would run sync-template-steps')
+    }
+    return
+  }
+
+  if (!result.changed) {
+    return
+  }
+
+  const packageManager = detectPackageManager(projectRoot)
+  await runScript(projectRoot, packageManager, 'sync-template-step-groups')
+  await runScript(projectRoot, packageManager, 'sync-template-steps')
+}
+
+main().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/templates/blank/scripts/lib/filename-utils.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { extractLocatorGroupName, extractTestSuiteNameFromFilename } from './filename-utils'
+
+describe('filename utils', () => {
+  it('extractTestSuiteNameFromFilename handles .feature extension', () => {
+    expect(extractTestSuiteNameFromFilename('login.feature')).toBe('login')
+  })
+
+  it('extractTestSuiteNameFromFilename handles nested unix path', () => {
+    expect(extractTestSuiteNameFromFilename('/a/b/login-validation.feature')).toBe('login-validation')
+  })
+
+  it('extractTestSuiteNameFromFilename handles windows path', () => {
+    expect(extractTestSuiteNameFromFilename('a\\b\\suite.feature')).toBe('suite')
+  })
+
+  it('extractLocatorGroupName handles json extension', () => {
+    expect(extractLocatorGroupName('buttons.json')).toBe('buttons')
+  })
+
+  it('extractLocatorGroupName handles nested path', () => {
+    expect(extractLocatorGroupName('/a/b/users.json')).toBe('users')
+  })
+})

package/templates/blank/scripts/lib/filename-utils.ts

@@ -0,0 +1,24 @@
+import { extractModulePathFromAutomationFile } from '../../src/lib/template-sync-utils'
+
+/**
+ * Extracts test-suite identity from a `.feature` filename.
+ */
+export function extractTestSuiteNameFromFilename(filePath: string): string {
+  const fileName = filePath.split(/[/\\]/).pop() || ''
+  return fileName.replace(/\.feature$/, '')
+}
+
+/**
+ * Extracts locator group name from a locator `.json` file path.
+ */
+export function extractLocatorGroupName(filePath: string): string {
+  const fileName = filePath.split(/[/\\]/).pop() || ''
+  return fileName.replace('.json', '')
+}
+
+/**
+ * Resolves module path from a locator file under `automation/locators`.
+ */
+export function extractModulePathFromLocatorFile(filePath: string, baseDir: string): string {
+  return extractModulePathFromAutomationFile(filePath, baseDir, 'locators')
+}

package/templates/blank/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/blank/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/blank/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}"')
+  })
+})