create-appraisejs 0.3.0 → 0.3.1-alpha.0

package/templates/starter/src/lib/gherkin-parser.ts

@@ -1,5 +1,6 @@
 import { promises as fs } from 'fs'
-import { join, relative } from 'path'
+import { join } from 'path'
+import { getFeatureModulePath } from '@/lib/path-helpers/feature-path'
 
 /**
  * Represents a parsed feature file with its scenarios and steps
@@ -31,122 +32,149 @@ export interface ParsedStep {
   order: number
 }
 
-/**
- * Parses a Gherkin feature file and extracts scenarios and steps
- * @param filePath - Path to the feature file
- * @returns Promise<ParsedFeature | null> - Parsed feature data or null if parsing fails
- */
-export async function parseFeatureFile(filePath: string): Promise<ParsedFeature | null> {
-  try {
-    const content = await fs.readFile(filePath, 'utf-8')
+const STEP_KEYWORDS = ['Given', 'When', 'Then', 'And', 'But'] as const
 
-    // Simple Gherkin parser implementation
-    const lines = content.split('\n').map(line => line.trim())
-    const scenarios: ParsedScenario[] = []
-
-    let featureName = ''
-    let featureDescription = ''
-    const featureTags: string[] = []
-    let currentScenario: ParsedScenario | null = null
-    let stepOrder = 1
-
-    // Find feature line and extract tags before it
-    for (let i = 0; i < lines.length; i++) {
-      if (lines[i].startsWith('Feature:')) {
-        // Look backwards for tags (skip comments and empty lines)
-        for (let j = i - 1; j >= 0; j--) {
-          const prevLine = lines[j]
-          if (prevLine === '' || prevLine.startsWith('#')) {
-            continue
-          }
-          if (prevLine.startsWith('@')) {
-            featureTags.unshift(prevLine) // Add to beginning to maintain order
-          } else {
-            break // Stop when we hit a non-tag line
-          }
-        }
-        break
-      }
+type ParsedScenarioHeader = Pick<ParsedScenario, 'name' | 'description'>
+
+function normalizeGherkinLines(content: string) {
+  return content.split('\n').map(line => line.trim())
+}
+
+function isSkippableLine(line: string) {
+  return line === '' || line.startsWith('#')
+}
+
+function collectPrecedingTags(lines: string[], startIndex: number) {
+  const tags: string[] = []
+
+  for (let i = startIndex - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (isSkippableLine(line)) {
+      continue
     }
 
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i]
+    if (line.startsWith('@')) {
+      tags.unshift(line)
+      continue
+    }
 
-      // Skip comments and empty lines
-      if (line.startsWith('#') || line === '') {
-        continue
-      }
+    break
+  }
 
-      // Parse Feature line
-      if (line.startsWith('Feature:')) {
-        const featureLineText = line.replace('Feature:', '').trim()
-        featureName = featureLineText
-        featureDescription = featureLineText
-        continue
-      }
+  return tags
+}
 
-      // Parse Scenario line
-      if (line.startsWith('Scenario:')) {
-        // Save previous scenario if exists
-        if (currentScenario) {
-          scenarios.push(currentScenario)
-        }
+function getFeatureTags(lines: string[]) {
+  const featureIndex = lines.findIndex(line => line.startsWith('Feature:'))
+  return featureIndex === -1 ? [] : collectPrecedingTags(lines, featureIndex)
+}
 
-        // Extract tags before this scenario
-        const scenarioTags: string[] = []
-        for (let j = i - 1; j >= 0; j--) {
-          const prevLine = lines[j]
-          if (prevLine === '' || prevLine.startsWith('#')) {
-            continue
-          }
-          if (prevLine.startsWith('@')) {
-            scenarioTags.unshift(prevLine) // Add to beginning to maintain order
-          } else {
-            break // Stop when we hit a non-tag line
-          }
-        }
+function parseScenarioHeader(line: string): ParsedScenarioHeader {
+  const scenarioText = line.replace('Scenario:', '').trim()
+  const [descriptionPart, ...nameParts] = scenarioText.split(']')
 
-        const scenarioText = line.replace('Scenario:', '').trim()
-        const [name, description] =
-          scenarioText.split(']').length > 1
-            ? [scenarioText.split(']')[1].trim(), scenarioText.split(']')[0].replace('[', '').trim()]
-            : [scenarioText, '']
-
-        currentScenario = {
-          name: name,
-          description: description || undefined,
-          tags: scenarioTags,
-          steps: [],
-        }
-        stepOrder = 1
-        continue
-      }
+  if (nameParts.length === 0) {
+    return { name: scenarioText }
+  }
+
+  const name = nameParts.join(']').trim()
+  const description = descriptionPart.replace('[', '').trim()
+
+  return {
+    name,
+    description: description || undefined,
+  }
+}
+
+function parseStep(line: string, order: number): ParsedStep | null {
+  const keyword = STEP_KEYWORDS.find(keyword => line.startsWith(`${keyword} `))
+  if (!keyword) {
+    return null
+  }
+
+  return {
+    keyword,
+    text: line.substring(keyword.length).trim(),
+    order,
+  }
+}
+
+function parseFeatureLine(line: string) {
+  return line.replace('Feature:', '').trim()
+}
+
+function startScenario(lines: string[], index: number): ParsedScenario {
+  const { name, description } = parseScenarioHeader(lines[index])
+
+  return {
+    name,
+    description,
+    tags: collectPrecedingTags(lines, index),
+    steps: [],
+  }
+}
 
-      // Parse steps (Given, When, Then, And, But)
-      if (
-        currentScenario &&
-        (line.startsWith('Given ') ||
-          line.startsWith('When ') ||
-          line.startsWith('Then ') ||
-          line.startsWith('And ') ||
-          line.startsWith('But '))
-      ) {
-        const keyword = line.split(' ')[0]
-        const text = line.substring(keyword.length).trim()
-
-        currentScenario.steps.push({
-          keyword: keyword,
-          text: text,
-          order: stepOrder++,
-        })
+function parseGherkinLines(lines: string[]) {
+  const scenarios: ParsedScenario[] = []
+  let featureName = ''
+  let featureDescription = ''
+  let currentScenario: ParsedScenario | null = null
+  let stepOrder = 1
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    if (isSkippableLine(line)) {
+      continue
+    }
+
+    if (line.startsWith('Feature:')) {
+      const featureLineText = parseFeatureLine(line)
+      featureName = featureLineText
+      featureDescription = featureLineText
+      continue
+    }
+
+    if (line.startsWith('Scenario:')) {
+      if (currentScenario) {
+        scenarios.push(currentScenario)
       }
+
+      currentScenario = startScenario(lines, i)
+      stepOrder = 1
+      continue
     }
 
-    // Add the last scenario
-    if (currentScenario) {
-      scenarios.push(currentScenario)
+    if (!currentScenario) {
+      continue
     }
 
+    const step = parseStep(line, stepOrder)
+    if (step) {
+      currentScenario.steps.push(step)
+      stepOrder++
+    }
+  }
+
+  if (currentScenario) {
+    scenarios.push(currentScenario)
+  }
+
+  return { featureName, featureDescription, scenarios }
+}
+
+/**
+ * Parses a Gherkin feature file and extracts scenarios and steps
+ * @param filePath - Path to the feature file
+ * @returns Promise<ParsedFeature | null> - Parsed feature data or null if parsing fails
+ */
+export async function parseFeatureFile(filePath: string): Promise<ParsedFeature | null> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    const lines = normalizeGherkinLines(content)
+    const featureTags = getFeatureTags(lines)
+    const { featureName, featureDescription, scenarios } = parseGherkinLines(lines)
+
     if (!featureName) {
       console.warn(`No feature found in file: ${filePath}`)
       return null
@@ -206,46 +234,5 @@ export async function scanFeatureFiles(directoryPath: string): Promise<ParsedFea
  * @returns string - Module path (e.g., "/module1/submodule")
  */
 export function extractModulePathFromFilePath(featureFilePath: string, featuresBaseDir: string): string {
-  // Use path.relative for cross-platform path handling
-  const relativePath = relative(featuresBaseDir, featureFilePath)
-
-  // Normalize to forward slashes for module path format (database uses /)
-  const normalizedPath = relativePath.replace(/\\/g, '/')
-  const pathParts = normalizedPath.split('/').filter(part => part && part !== '')
-
-  // Remove the filename and join the remaining parts
-  const moduleParts = pathParts.slice(0, -1)
-  return moduleParts.length > 0 ? '/' + moduleParts.join('/') : '/'
-}
-
-/**
- * Generates a safe test suite name from feature name
- * @param featureName - Name of the feature
- * @returns string - Safe test suite name
- */
-export function generateSafeTestSuiteName(featureName: string): string {
-  return featureName
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]+/g, '')
-    .replace(/\s+/g, ' ')
-    .trim()
-}
-
-/**
- * Generates a safe test case name from scenario name
- * @param scenarioName - Name of the scenario
- * @returns string - Safe test case name
- */
-export function generateSafeTestCaseName(scenarioName: string): string {
-  // Remove scenario prefix if present and clean up the name
-  const cleanName = scenarioName
-    .replace(/^Scenario:\s*/i, '')
-    .replace(/^\[.*?\]\s*/, '') // Remove [brackets] prefix
-    .trim()
-
-  return cleanName
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]+/g, '')
-    .replace(/\s+/g, ' ')
-    .trim()
+  return getFeatureModulePath(featureFilePath, featuresBaseDir)
 }

package/templates/starter/src/lib/gherkin-step-format.ts

@@ -0,0 +1,80 @@
+type OrderedGherkinStep = {
+  gherkinStep?: string | null
+  order: number
+}
+
+const GHERKIN_KEYWORDS = ['given', 'when', 'then', 'and', 'but'] as const
+const THEN_LIKE_PREFIXES = ['should', 'must', 'will'] as const
+
+type StepFormatState = {
+  hasThenInPrevious: boolean
+  hasWhenInPrevious: boolean
+}
+
+function splitGherkinStep(gherkinStep: string) {
+  const trimmedStep = gherkinStep.trim()
+  const [firstWord = '', ...rest] = trimmedStep.split(' ')
+  const normalizedFirstWord = firstWord.toLowerCase()
+
+  return {
+    firstWord: normalizedFirstWord,
+    text: GHERKIN_KEYWORDS.includes(normalizedFirstWord as (typeof GHERKIN_KEYWORDS)[number])
+      ? rest.join(' ')
+      : trimmedStep,
+  }
+}
+
+function isThenStatement(firstWord: string, stepText: string) {
+  const normalizedStep = stepText.toLowerCase()
+  return firstWord === 'then' || THEN_LIKE_PREFIXES.some(prefix => normalizedStep.startsWith(prefix))
+}
+
+function formatFollowingStep(
+  stepText: string,
+  isThenLike: boolean,
+  state: StepFormatState,
+  resetWhenAfterThen: boolean,
+) {
+  if (!state.hasThenInPrevious) {
+    if (isThenLike) {
+      state.hasThenInPrevious = true
+      return `Then ${stepText}`
+    }
+
+    if (!state.hasWhenInPrevious) {
+      state.hasWhenInPrevious = true
+      return `When ${stepText}`
+    }
+
+    return `And ${stepText}`
+  }
+
+  if (isThenLike) {
+    return `And ${stepText}`
+  }
+
+  state.hasThenInPrevious = false
+  state.hasWhenInPrevious = !resetWhenAfterThen
+  return `When ${stepText}`
+}
+
+export function formatOrderedGherkinSteps(
+  steps: OrderedGherkinStep[],
+  options: { resetWhenAfterThen?: boolean } = {},
+): string[] {
+  const sortedSteps = [...steps].sort((left, right) => left.order - right.order)
+  const state: StepFormatState = {
+    hasThenInPrevious: false,
+    hasWhenInPrevious: false,
+  }
+
+  return sortedSteps.map((step, index) => {
+    const { firstWord, text } = splitGherkinStep(step.gherkinStep ?? '')
+
+    if (index === 0) {
+      return `Given ${text}`
+    }
+
+    return formatFollowingStep(text, isThenStatement(firstWord, text), state, options.resetWhenAfterThen ?? false)
+  })
+}

package/templates/starter/src/lib/jsdoc/template-step-jsdoc.ts

@@ -0,0 +1,262 @@
+import { TemplateStepGroupType, TemplateStepIcon } from '@prisma/client'
+
+export interface StepGroupJSDoc {
+  name: string
+  description: string | null
+  type: TemplateStepGroupType
+}
+
+export interface StepJSDoc {
+  name: string
+  description: string | null
+  icon: TemplateStepIcon
+}
+
+export function readJSDocTag(line: string, tagName: string): string | null {
+  const trimmed = line.trim()
+  const prefix = `@${tagName}`
+  const withoutCommentMarker = trimmed.replace(/^\*\s?/, '')
+
+  if (!withoutCommentMarker.startsWith(prefix)) {
+    return null
+  }
+
+  const value = withoutCommentMarker.slice(prefix.length).trim()
+  return value || null
+}
+
+function findTopLevelJSDocStart(lines: string[]): number | null {
+  let startLine = 0
+  let isInsideImportBlock = false
+
+  while (startLine < lines.length) {
+    const line = lines[startLine].trim()
+
+    if (isInsideImportBlock) {
+      if (line.includes('from ') || line.endsWith(';')) {
+        isInsideImportBlock = false
+      }
+      startLine++
+      continue
+    }
+
+    if (line === '') {
+      startLine++
+      continue
+    }
+
+    if (line.startsWith('import ')) {
+      isInsideImportBlock = line.includes('{') && !line.includes('from ')
+      startLine++
+      continue
+    }
+
+    break
+  }
+
+  return startLine < lines.length && lines[startLine].trim().startsWith('/**') ? startLine : null
+}
+
+export function findNearestJSDocStart(lines: string[], startLine: number): number | null {
+  for (let i = startLine - 1; i >= 0 && i >= startLine - 20; i--) {
+    const line = lines[i]?.trim()
+
+    if (line?.startsWith('/**')) {
+      return i
+    }
+
+    if (!line?.includes('*/')) {
+      continue
+    }
+
+    for (let j = i - 1; j >= 0 && j >= i - 10; j--) {
+      if (lines[j]?.trim().startsWith('/**')) {
+        return j
+      }
+    }
+
+    return i
+  }
+
+  return null
+}
+
+function readGroupMetadataLine(
+  line: string,
+  metadata: { name: string | null; description: string | null; type: string | null },
+) {
+  metadata.name = readJSDocTag(line, 'name') ?? metadata.name
+  metadata.description = readJSDocTag(line, 'description') ?? metadata.description
+  metadata.type = readJSDocTag(line, 'type') ?? metadata.type
+}
+
+function readStepMetadataLine(
+  line: string,
+  metadata: { name: string | null; description: string | null; icon: string | null },
+) {
+  metadata.name = readJSDocTag(line, 'name') ?? metadata.name
+  metadata.description = readJSDocTag(line, 'description') ?? metadata.description
+  metadata.icon = readJSDocTag(line, 'icon') ?? metadata.icon
+}
+
+function normalizeGroupTypeStrict(type: string): TemplateStepGroupType {
+  const normalizedType = type.toUpperCase()
+  if (normalizedType !== 'ACTION' && normalizedType !== 'VALIDATION') {
+    throw new Error(`Invalid @type value: ${type}. Must be ACTION or VALIDATION`)
+  }
+
+  return normalizedType as TemplateStepGroupType
+}
+
+/**
+ * Parses top-of-file group JSDoc. Invalid @type throws (CLI / step registry).
+ */
+export function parseGroupJSDocStrict(content: string): StepGroupJSDoc | null {
+  const lines = content.split('\n')
+  const startLine = findTopLevelJSDocStart(lines)
+  if (startLine == null) return null
+
+  const metadata = { name: null as string | null, description: null as string | null, type: null as string | null }
+  const maxLines = Math.min(lines.length, startLine + 50)
+  for (let i = startLine; i < maxLines; i++) {
+    const line = lines[i] ?? ''
+
+    if (line.includes('*/')) {
+      const beforeClose = line.split('*/')[0].trim()
+      readGroupMetadataLine(beforeClose, metadata)
+      return metadata.name && metadata.type
+        ? {
+            name: metadata.name.trim(),
+            description: metadata.description ? metadata.description.trim() : null,
+            type: normalizeGroupTypeStrict(metadata.type),
+          }
+        : null
+    }
+
+    readGroupMetadataLine(line, metadata)
+  }
+
+  return null
+}
+
+/**
+ * Same shape as strict parsing; unknown @type yields null (sync / DB projection).
+ */
+export function parseGroupJSDocLenient(content: string): StepGroupJSDoc | null {
+  const lines = content.split('\n')
+  const startLine = findTopLevelJSDocStart(lines)
+  if (startLine == null) return null
+
+  const metadata = { name: null as string | null, description: null as string | null, type: null as string | null }
+  const maxLines = Math.min(lines.length, startLine + 50)
+  for (let i = startLine; i < maxLines; i++) {
+    const line = lines[i] ?? ''
+
+    if (line.includes('*/')) {
+      const beforeClose = line.split('*/')[0].trim()
+      readGroupMetadataLine(beforeClose, metadata)
+      break
+    }
+
+    readGroupMetadataLine(line, metadata)
+  }
+
+  if (!metadata.name || !metadata.type) {
+    return null
+  }
+
+  const normalizedType = metadata.type.toUpperCase()
+  if (normalizedType !== 'ACTION' && normalizedType !== 'VALIDATION') {
+    return null
+  }
+
+  return {
+    name: metadata.name.trim(),
+    description: metadata.description ? metadata.description.trim() : null,
+    type: normalizedType as TemplateStepGroupType,
+  }
+}
+
+/**
+ * Nearest step JSDoc before a line. Invalid @icon throws (CLI).
+ */
+export function parseStepJSDocStrict(content: string, startLine: number): StepJSDoc | null {
+  const lines = content.split('\n')
+  const jsdocStart = findNearestJSDocStart(lines, startLine)
+  if (jsdocStart == null) return null
+
+  const metadata = { name: null as string | null, description: null as string | null, icon: null as string | null }
+  for (let i = jsdocStart; i < Math.min(lines.length, jsdocStart + 20); i++) {
+    const line = lines[i] ?? ''
+
+    if (line.trim().startsWith('/**')) {
+      continue
+    }
+
+    if (line.includes('*/')) {
+      const beforeClose = line.split('*/')[0].trim()
+      readStepMetadataLine(beforeClose, metadata)
+      break
+    }
+
+    readStepMetadataLine(line, metadata)
+  }
+
+  if (!metadata.name || !metadata.icon) {
+    return null
+  }
+
+  const iconUpper = metadata.icon.toUpperCase()
+  const validIcons = Object.values(TemplateStepIcon)
+  if (!validIcons.includes(iconUpper as TemplateStepIcon)) {
+    throw new Error(`Invalid @icon value: ${metadata.icon}. Must be one of: ${validIcons.join(', ')}`)
+  }
+
+  return {
+    name: metadata.name.trim(),
+    description: metadata.description ? metadata.description.trim() : null,
+    icon: iconUpper as TemplateStepIcon,
+  }
+}
+
+/**
+ * Invalid @icon yields null (filesystem sync).
+ */
+export function parseStepJSDocLenient(content: string, startLine: number): StepJSDoc | null {
+  const lines = content.split('\n')
+  const jsdocStart = findNearestJSDocStart(lines, startLine)
+  if (jsdocStart == null) return null
+
+  const metadata = { name: null as string | null, description: null as string | null, icon: null as string | null }
+  for (let i = jsdocStart; i < Math.min(lines.length, jsdocStart + 20); i++) {
+    const line = lines[i] ?? ''
+
+    if (line.trim().startsWith('/**')) {
+      continue
+    }
+
+    if (line.includes('*/')) {
+      const beforeClose = line.split('*/')[0].trim()
+      readStepMetadataLine(beforeClose, metadata)
+      break
+    }
+
+    readStepMetadataLine(line, metadata)
+  }
+
+  if (!metadata.name || !metadata.icon) {
+    return null
+  }
+
+  const iconUpper = metadata.icon.toUpperCase()
+  const validIcons = Object.values(TemplateStepIcon)
+  if (!validIcons.includes(iconUpper as TemplateStepIcon)) {
+    return null
+  }
+
+  return {
+    name: metadata.name.trim(),
+    description: metadata.description ? metadata.description.trim() : null,
+    icon: iconUpper as TemplateStepIcon,
+  }
+}

package/templates/starter/src/lib/locator-group-file-utils.ts

@@ -29,7 +29,7 @@ export async function getLocatorGroupFilePath(locatorGroupId: string): Promise<s
   }
 }
 
-export async function generateLocatorGroupContent(locatorGroupId: string): Promise<Record<string, string>> {
+async function generateLocatorGroupContent(locatorGroupId: string): Promise<Record<string, string>> {
   try {
     const locatorGroup = await prisma.locatorGroup.findUnique({
       where: { id: locatorGroupId },
@@ -51,7 +51,7 @@ export async function generateLocatorGroupContent(locatorGroupId: string): Promi
   }
 }
 
-export async function ensureDirectoryExists(filePath: string): Promise<void> {
+async function ensureDirectoryExists(filePath: string): Promise<void> {
   await ensureAutomationWorkspaceReady()
   await fs.mkdir(path.dirname(filePath), { recursive: true })
 }
@@ -176,24 +176,6 @@ export async function createEmptyLocatorGroupFile(locatorGroupId: string): Promi
   }
 }
 
-export async function readLocatorGroupFile(
-  locatorGroupId: string,
-): Promise<{ filePath: string; content: Record<string, string> } | null> {
-  try {
-    await ensureAutomationWorkspaceReady()
-    const filePath = await getLocatorGroupFilePath(locatorGroupId)
-    if (!filePath) {
-      return null
-    }
-
-    const fileContent = await fs.readFile(filePath, 'utf-8')
-    return { filePath, content: JSON.parse(fileContent) }
-  } catch (error) {
-    console.error('Error reading locator group file:', error)
-    return null
-  }
-}
-
 export async function updateLocatorMapFile(
   currentLocatorGroupRoute: string,
   newLocatorGroupRoute: string,