create-appraisejs 0.3.0 → 0.3.1-alpha.0

package/templates/starter/src/lib/utils/template-step-file-manager-intelligent.ts

@@ -1,5 +1,5 @@
 import { promises as fs } from 'fs'
-import { TemplateStep, TemplateStepGroupType } from '@prisma/client'
+import { TemplateStepGroupType } from '@prisma/client'
 import { ensureStepsDirectory, getFilePath, formatFileContent } from './template-step-file-generator'
 
 /**
@@ -91,176 +91,6 @@ export function ensureGroupJSDoc(
   }
 }
 
-/**
- * Generates JSDoc comments for a template step
- */
-function generateJSDocComment(templateStep: TemplateStep): string {
-  const lines = ['/**']
-  lines.push(` * @name ${templateStep.name}`)
-  if (templateStep.description) {
-    lines.push(` * @description ${templateStep.description}`)
-  }
-  lines.push(` * @icon ${templateStep.icon}`)
-  lines.push(' */')
-  return lines.join('\n')
-}
-
-/**
- * Wraps a function definition with JSDoc comments
- * If the function already has JSDoc comments, replaces them
- */
-function wrapFunctionWithJSDoc(functionDefinition: string, templateStep: TemplateStep): string {
-  const jsdoc = generateJSDocComment(templateStep)
-
-  // Remove existing JSDoc comments if present
-  const cleanedDefinition = functionDefinition.replace(/\/\*\*[\s\S]*?\*\/\s*/g, '').trim()
-
-  // Prepend JSDoc and return
-  return `${jsdoc}\n${cleanedDefinition}`
-}
-
-/**
- * Checks if a template step update requires file changes
- * Signature, parameter, and metadata (name, description, icon) changes require file updates
- */
-function requiresFileUpdate(oldStep: TemplateStep, newStep: TemplateStep): boolean {
-  // Check if signature changed
-  if (oldStep.signature !== newStep.signature) {
-    return true
-  }
-
-  // Check if function definition changed (this includes parameter changes)
-  if (oldStep.functionDefinition !== newStep.functionDefinition) {
-    return true
-  }
-
-  // Check if metadata changed (name, description, icon) - these affect JSDoc comments
-  if (oldStep.name !== newStep.name) {
-    return true
-  }
-
-  if (oldStep.description !== newStep.description) {
-    return true
-  }
-
-  if (oldStep.icon !== newStep.icon) {
-    return true
-  }
-
-  // No file changes needed for other updates
-  return false
-}
-
-/**
- * Finds the start and end lines of a step definition function in the file
- * Uses flexible signature matching to handle prettier formatting variations
- * Handles JSDoc comments that may precede the function
- */
-function findStepFunctionBounds(content: string, signature: string): { startLine: number; endLine: number } | null {
-  const lines = content.split('\n')
-
-  // Search for the signature content across multiple lines (handles prettier formatting)
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    const trimmedLine = line.trim()
-
-    // Skip JSDoc comment lines (but not the function definition itself)
-    if (
-      trimmedLine.startsWith('/**') ||
-      trimmedLine === '*/' ||
-      (trimmedLine.startsWith('*') && !trimmedLine.startsWith('When(') && !trimmedLine.startsWith('Then('))
-    ) {
-      continue
-    }
-
-    // Check if this line starts a step definition
-    if (trimmedLine.startsWith('When(') || trimmedLine.startsWith('Then(')) {
-      // Look ahead to find the complete signature across multiple lines
-      let signatureFound = false
-      let currentSignature = ''
-
-      // Collect signature content from current and following lines until we hit the function start
-      for (let j = i; j < lines.length; j++) {
-        const currentLine = lines[j]
-        currentSignature += currentLine
-
-        // Check if we've found our signature
-        if (currentSignature.includes(signature)) {
-          signatureFound = true
-          break
-        }
-
-        // If we hit the function opening brace, stop looking for signature
-        if (currentLine.includes('async function') || currentLine.includes('function(')) {
-          break
-        }
-      }
-
-      if (signatureFound) {
-        // Found the start, now find the end using bracket and parenthesis counting
-        // Also check backwards for JSDoc comments to include them in the bounds
-        let functionStartLine = i
-        let braceCount = 0
-        let parenCount = 0
-        let startParenFound = false
-
-        // Check if there are JSDoc comments before this function
-        if (i > 0) {
-          let jsdocStart = i - 1
-          // Look backwards for JSDoc comment block
-          // First, check if the previous line is the end of a JSDoc block
-          if (lines[jsdocStart].trim() === '*/') {
-            // Found end of JSDoc, continue looking backwards for the start
-            jsdocStart--
-            while (jsdocStart >= 0) {
-              const prevLine = lines[jsdocStart].trim()
-              if (prevLine.startsWith('/**')) {
-                // Found start of JSDoc block
-                functionStartLine = jsdocStart
-                break
-              } else if (prevLine.startsWith('*') || prevLine === '') {
-                jsdocStart--
-              } else {
-                break
-              }
-            }
-          }
-        }
-
-        for (let j = i; j < lines.length; j++) {
-          const currentLine = lines[j]
-
-          // Count opening and closing parentheses and braces
-          for (const char of currentLine) {
-            if (char === '(') {
-              parenCount++
-              startParenFound = true
-            } else if (char === ')') {
-              parenCount--
-            } else if (char === '{') {
-              braceCount++
-            } else if (char === '}') {
-              braceCount--
-            }
-          }
-
-          // If we found the opening parenthesis and both parentheses and braces are balanced, we're done
-          // This ensures we capture the complete When(...) or Then(...) call including the closing )
-          if (startParenFound && parenCount === 0 && braceCount === 0) {
-            return { startLine: functionStartLine, endLine: j }
-          }
-        }
-
-        // If we reach here, something went wrong with bracket counting
-        console.warn(`Could not find end of function for signature: ${signature}`)
-        return null
-      }
-    }
-  }
-
-  return null
-}
-
 /**
  * Required import definitions
  */
@@ -409,189 +239,6 @@ export function ensureRequiredImports(content: string): string {
   return newImportStatements + content
 }
 
-/**
- * Intelligently adds a new template step to the file
- * Preserves existing content including imports, types, and other code
- */
-export async function addTemplateStepToFile(
-  groupName: string,
-  templateStep: TemplateStep,
-  type: TemplateStepGroupType | string,
-): Promise<void> {
-  try {
-    await ensureStepsDirectory()
-    const filePath = getFilePath(groupName, type)
-
-    let existingContent = ''
-    try {
-      existingContent = await fs.readFile(filePath, 'utf8')
-    } catch {
-      // File doesn't exist, start with empty content
-      existingContent = ''
-    }
-
-    // Ensure required imports are present
-    existingContent = ensureRequiredImports(existingContent)
-
-    // Check if step with this signature already exists
-    const bounds = findStepFunctionBounds(existingContent, templateStep.signature)
-
-    let newContent: string
-
-    if (bounds) {
-      // Replace existing step - replace the entire function with JSDoc comments
-      const lines = existingContent.split('\n')
-      const beforeStep = lines.slice(0, bounds.startLine).join('\n')
-      const afterStep = lines.slice(bounds.endLine + 1).join('\n')
-
-      // Wrap the function definition with JSDoc comments
-      const wrappedStepDefinition = wrapFunctionWithJSDoc(templateStep.functionDefinition || '', templateStep)
-      newContent =
-        beforeStep +
-        (beforeStep.trim() ? '\n\n' : '') +
-        wrappedStepDefinition +
-        (afterStep.trim() ? '\n' : '') +
-        afterStep
-    } else {
-      // Add new step at the end - wrap with JSDoc comments
-      const wrappedStepDefinition = wrapFunctionWithJSDoc(templateStep.functionDefinition || '', templateStep)
-      newContent = existingContent + (existingContent ? '\n\n' : '') + wrappedStepDefinition
-    }
-
-    // Format and write the file
-    const formattedContent = await formatFileContent(newContent)
-    await fs.writeFile(filePath, formattedContent, 'utf8')
-
-    console.log(`Template step added to file: ${filePath}`)
-  } catch (error) {
-    console.error(`Failed to add template step to file for group "${groupName}":`, error)
-    throw new Error(`File update failed: ${error}`)
-  }
-}
-
-/**
- * Intelligently removes a template step from the file
- * Only removes the specific step, preserves everything else including imports and types
- */
-export async function removeTemplateStepFromFile(
-  groupName: string,
-  templateStep: TemplateStep,
-  type: TemplateStepGroupType | string,
-): Promise<void> {
-  try {
-    await ensureStepsDirectory()
-    const filePath = getFilePath(groupName, type)
-
-    let existingContent = ''
-    try {
-      existingContent = await fs.readFile(filePath, 'utf8')
-    } catch {
-      // File doesn't exist, nothing to remove
-      return
-    }
-
-    // Ensure required imports are present
-    existingContent = ensureRequiredImports(existingContent)
-
-    // Find the step to remove
-    const bounds = findStepFunctionBounds(existingContent, templateStep.signature)
-
-    if (!bounds) {
-      // Step not found, nothing to remove
-      return
-    }
-
-    // Remove the entire function block
-    const lines = existingContent.split('\n')
-    const beforeStep = lines.slice(0, bounds.startLine).join('\n')
-    const afterStep = lines.slice(bounds.endLine + 1).join('\n')
-
-    // Combine content, handling empty sections
-    let newContent = ''
-    if (beforeStep.trim()) {
-      newContent += beforeStep.trim()
-    }
-    if (afterStep.trim()) {
-      if (newContent) newContent += '\n'
-      newContent += afterStep.trim()
-    }
-
-    // Format and write the file
-    const formattedContent = await formatFileContent(newContent)
-    await fs.writeFile(filePath, formattedContent, 'utf8')
-
-    console.log(`Template step removed from file: ${filePath}`)
-  } catch (error) {
-    console.error(`Failed to remove template step from file for group "${groupName}":`, error)
-    throw new Error(`File update failed: ${error}`)
-  }
-}
-
-/**
- * Intelligently updates a template step in the file
- * Only updates the specific step, preserves everything else including imports and types
- */
-export async function updateTemplateStepInFile(
-  groupName: string,
-  templateStep: TemplateStep,
-  type: TemplateStepGroupType | string,
-  oldStep?: TemplateStep,
-): Promise<void> {
-  try {
-    // If we have the old step data, check if file changes are needed
-    if (oldStep && !requiresFileUpdate(oldStep, templateStep)) {
-      console.log(`No file changes needed for template step update: ${templateStep.signature}`)
-      return
-    }
-
-    await ensureStepsDirectory()
-    const filePath = getFilePath(groupName, type)
-
-    let existingContent = ''
-    try {
-      existingContent = await fs.readFile(filePath, 'utf8')
-    } catch {
-      // File doesn't exist, create it with the updated step
-      await addTemplateStepToFile(groupName, templateStep, type)
-      return
-    }
-
-    // Ensure required imports are present
-    existingContent = ensureRequiredImports(existingContent)
-
-    // Find the step to update
-    const bounds = findStepFunctionBounds(existingContent, oldStep!.signature)
-
-    if (bounds) {
-      // Update existing step - replace the entire function with JSDoc comments
-      const lines = existingContent.split('\n')
-      const beforeStep = lines.slice(0, bounds.startLine).join('\n')
-      const afterStep = lines.slice(bounds.endLine + 1).join('\n')
-
-      // Wrap the function definition with JSDoc comments
-      const wrappedStepDefinition = wrapFunctionWithJSDoc(templateStep.functionDefinition || '', templateStep)
-      const newContent =
-        beforeStep +
-        (beforeStep.trim() ? '\n\n' : '') +
-        wrappedStepDefinition +
-        (afterStep.trim() ? '\n' : '') +
-        afterStep
-
-      // Format and write the file
-      const formattedContent = await formatFileContent(newContent)
-      await fs.writeFile(filePath, formattedContent, 'utf8')
-
-      console.log(`Template step updated in file: ${filePath}`)
-    } else {
-      // Step not found, add it
-      await addTemplateStepToFile(groupName, templateStep, type)
-    }
-  } catch (error) {
-    console.error(`Failed to update template step in file for group "${groupName}":`, error)
-    throw new Error(`File update failed: ${error}`)
-  }
-}
-
 /**
  * Creates a placeholder file for a new template step group
  */
@@ -697,4 +344,3 @@ export async function renameTemplateStepGroupFile(
     throw new Error(`File rename failed: ${error}`)
   }
 }
-

package/templates/starter/src/lib/utils/template-step-function-bounds.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import { findStepFunctionBounds } from './template-step-function-bounds'
+
+describe('findStepFunctionBounds', () => {
+  it('finds a single-line step definition with its JSDoc block', () => {
+    const content = [
+      'import { When } from "runtime"',
+      '',
+      '/**',
+      ' * @name Login',
+      ' */',
+      'When("I log in", async function () {',
+      '  await this.page.click("button")',
+      '})',
+      '',
+      'const untouched = true',
+    ].join('\n')
+
+    expect(findStepFunctionBounds(content, 'When("I log in"')).toEqual({
+      startLine: 2,
+      endLine: 7,
+    })
+  })
+
+  it('finds prettier-wrapped step signatures and balanced nested blocks', () => {
+    const content = [
+      'Then(',
+      '  "I should see {string}",',
+      '  async function (label: string) {',
+      '    if (label) {',
+      '      await expect(this.page.getByText(label)).toBeVisible()',
+      '    }',
+      '  },',
+      ')',
+    ].join('\n')
+
+    expect(findStepFunctionBounds(content, 'Then(  "I should see {string}"')).toEqual({
+      startLine: 0,
+      endLine: 7,
+    })
+  })
+
+  it('returns null when the signature is not present or the call is incomplete', () => {
+    expect(findStepFunctionBounds('When("other", async function () {})', 'Then("missing"')).toBeNull()
+    expect(findStepFunctionBounds('When("incomplete", async function () {', 'When("incomplete"')).toBeNull()
+  })
+})

package/templates/starter/src/lib/utils/template-step-function-bounds.ts

@@ -0,0 +1,138 @@
+export type StepFunctionBounds = {
+  startLine: number
+  endLine: number
+}
+
+type DelimiterCounts = {
+  braceCount: number
+  parenCount: number
+  startParenFound: boolean
+}
+
+const STEP_DEFINITION_PREFIXES = ['When(', 'Then(']
+
+function isStepDefinitionStart(trimmedLine: string) {
+  return STEP_DEFINITION_PREFIXES.some(prefix => trimmedLine.startsWith(prefix))
+}
+
+function isJSDocLine(trimmedLine: string) {
+  return (
+    trimmedLine.startsWith('/**') ||
+    trimmedLine === '*/' ||
+    (trimmedLine.startsWith('*') && !isStepDefinitionStart(trimmedLine))
+  )
+}
+
+function containsFunctionStart(line: string) {
+  return line.includes('async function') || line.includes('function(')
+}
+
+function hasMatchingSignature(lines: string[], startLine: number, signature: string) {
+  let currentSignature = ''
+
+  for (let lineIndex = startLine; lineIndex < lines.length; lineIndex++) {
+    const currentLine = lines[lineIndex]
+    currentSignature += currentLine
+
+    if (currentSignature.includes(signature)) {
+      return true
+    }
+
+    if (containsFunctionStart(currentLine)) {
+      return false
+    }
+  }
+
+  return false
+}
+
+function findJSDocStartLine(lines: string[], functionLine: number) {
+  const lineBeforeFunction = functionLine - 1
+  if (lineBeforeFunction < 0 || lines[lineBeforeFunction].trim() !== '*/') {
+    return functionLine
+  }
+
+  for (let lineIndex = lineBeforeFunction - 1; lineIndex >= 0; lineIndex--) {
+    const previousLine = lines[lineIndex].trim()
+
+    if (previousLine.startsWith('/**')) {
+      return lineIndex
+    }
+
+    if (!previousLine.startsWith('*') && previousLine !== '') {
+      return functionLine
+    }
+  }
+
+  return functionLine
+}
+
+function countLineDelimiters(line: string, counts: DelimiterCounts) {
+  for (const char of line) {
+    if (char === '(') {
+      counts.parenCount++
+      counts.startParenFound = true
+    } else if (char === ')') {
+      counts.parenCount--
+    } else if (char === '{') {
+      counts.braceCount++
+    } else if (char === '}') {
+      counts.braceCount--
+    }
+  }
+}
+
+function isBalancedStepCall(counts: DelimiterCounts) {
+  return counts.startParenFound && counts.parenCount === 0 && counts.braceCount === 0
+}
+
+function findStepCallEndLine(lines: string[], functionLine: number) {
+  const counts: DelimiterCounts = {
+    braceCount: 0,
+    parenCount: 0,
+    startParenFound: false,
+  }
+
+  for (let lineIndex = functionLine; lineIndex < lines.length; lineIndex++) {
+    countLineDelimiters(lines[lineIndex], counts)
+
+    if (isBalancedStepCall(counts)) {
+      return lineIndex
+    }
+  }
+
+  return null
+}
+
+/**
+ * Finds the start and end lines of a step definition function in the file.
+ * Handles prettier-wrapped signatures and a JSDoc block directly above the step.
+ */
+export function findStepFunctionBounds(content: string, signature: string): StepFunctionBounds | null {
+  const lines = content.split('\n')
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const trimmedLine = lines[lineIndex].trim()
+
+    if (isJSDocLine(trimmedLine) || !isStepDefinitionStart(trimmedLine)) {
+      continue
+    }
+
+    if (!hasMatchingSignature(lines, lineIndex, signature)) {
+      continue
+    }
+
+    const endLine = findStepCallEndLine(lines, lineIndex)
+    if (endLine === null) {
+      console.warn(`Could not find end of function for signature: ${signature}`)
+      return null
+    }
+
+    return {
+      startLine: findJSDocStartLine(lines, lineIndex),
+      endLine,
+    }
+  }
+
+  return null
+}

package/templates/starter/src/lib/utils.ts

@@ -4,10 +4,6 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
 
-export function calculateCompletionPercentage(total: number, completed: number) {
-  return Math.round((completed / total) * 100)
-}
-
 /**
  * Formats a date to show only date and time (without seconds/milliseconds)
  * @param date - Date string or Date object

package/templates/starter/src/services/locator/locator-service.ts

@@ -13,8 +13,6 @@ import { promises as fs } from 'fs'
 import path from 'path'
 import { glob } from 'glob'
 
-export { extractLocatorGroupName, extractModulePathFromLocatorFile } from '@/services/locator/locator-path-utils'
-
 export async function listLocators() {
   return prisma.locator.findMany({
     include: {
@@ -44,8 +42,6 @@ async function updateLocatorGroupFile(locatorGroupId: string | null): Promise<vo
   }
 }
 
-export { updateLocatorGroupFile }
-
 export async function deleteLocators(ids: string[]) {
   const locatorsToDelete = await prisma.locator.findMany({
     where: { id: { in: ids } },
@@ -342,7 +338,18 @@ const savePickedLocatorSchema = z.object({
 })
 
 export type SavePickedLocatorOutcome =
-  | { kind: 'success'; locatorId: string; locatorGroupId: string; message: string; wasUpdate: boolean }
+  | {
+      kind: 'success'
+      locatorId: string
+      locatorName: string
+      locatorGroupId: string
+      locatorGroupName: string
+      selector: string
+      route: string
+      moduleId: string
+      message: string
+      wasUpdate: boolean
+    }
   | { kind: 'error'; status: number; message: string }
 
 export async function savePickedLocatorFromRequest(request: SavePickedLocatorRequest): Promise<SavePickedLocatorOutcome> {
@@ -358,7 +365,8 @@ export async function savePickedLocatorFromRequest(request: SavePickedLocatorReq
 
   let locatorGroupId = value.existingLocatorGroupId
   let locatorGroupName = ''
-  const route = normalizeRoute(value.route || session?.currentPathname)
+  let route = normalizeRoute(value.route || session?.currentPathname)
+  let moduleId = value.moduleId ?? ''
   const locatorName = value.locatorName.trim()
   const selector = value.selector.trim()
   const currentLocator = value.locatorId
@@ -388,6 +396,8 @@ export async function savePickedLocatorFromRequest(request: SavePickedLocatorReq
     }
 
     locatorGroupName = locatorGroup.name
+    route = locatorGroup.route
+    moduleId = locatorGroup.moduleId
   } else {
     if (!value.newLocatorGroupName || value.newLocatorGroupName.trim() === '') {
       return fail(400, 'Locator group name is required when creating a new group.')
@@ -417,6 +427,7 @@ export async function savePickedLocatorFromRequest(request: SavePickedLocatorReq
 
     locatorGroupId = newLocatorGroup.id
     locatorGroupName = newLocatorGroup.name
+    moduleId = newLocatorGroup.moduleId
 
     await automationProjectionService.createEmptyLocatorGroup(newLocatorGroup.id)
     await automationProjectionService.syncLocatorMap(newLocatorGroup.name, route)
@@ -472,7 +483,12 @@ export async function savePickedLocatorFromRequest(request: SavePickedLocatorReq
   return {
     kind: 'success',
     locatorId: locator.id,
+    locatorName: locator.name,
     locatorGroupId,
+    locatorGroupName,
+    selector: locator.value,
+    route,
+    moduleId,
     message: value.locatorId ? 'Locator updated successfully.' : 'Locator saved successfully.',
     wasUpdate: Boolean(value.locatorId),
   }