create-appraisejs 0.2.0-alpha.1 → 0.2.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-appraisejs",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
   "description": "Scaffold a new AppraiseJS app in your directory",
   "license": "Apache-2.0",
   "author": "Hasnat Jamil",

package/templates/default/.appraise-template-meta.json

@@ -1,5 +1,5 @@
 {
-  "preparedAt": "2026-03-23T05:51:28.888Z",
-  "inputHash": "538288241ebcec3d1c8efa09eaaba4e5aec5611c00011ab1ec6c2c6c31341fb5",
+  "preparedAt": "2026-03-23T19:35:53.852Z",
+  "inputHash": "165288718820de7247b9067d6c4f1a78057520fb791c4b28fa781f2c30c95ea3",
   "databasePath": "prisma/dev.db"
 }

package/templates/default/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appraise",
-  "version": "0.1.9-alpha",
+  "version": "0.2.0-alpha",
   "private": false,
   "type": "module",
   "scripts": {

package/templates/default/src/lib/gherkin-parser.test.ts

@@ -0,0 +1,44 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { promises as fs } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { parseFeatureFile } from '@/lib/gherkin-parser'
+
+async function withTempFeatureFile(content: string): Promise<string> {
+  const dir = await fs.mkdtemp(join(tmpdir(), 'gherkin-parser-'))
+  const filePath = join(dir, 'sample.feature')
+  await fs.writeFile(filePath, content, 'utf8')
+  return filePath
+}
+
+test('uses Feature line text as feature description', async () => {
+  const filePath = await withTempFeatureFile(`
+@smoke
+Feature: Login workflow
+
+Scenario: logs in
+  Given user opens app
+`)
+
+  const parsed = await parseFeatureFile(filePath)
+
+  assert.ok(parsed)
+  assert.equal(parsed?.featureName, 'Login workflow')
+  assert.equal(parsed?.featureDescription, 'Login workflow')
+})
+
+test('keeps Feature line as description even when free text follows', async () => {
+  const filePath = await withTempFeatureFile(`
+Feature: Checkout flow
+Legacy block text that should not override the description
+
+Scenario: buys item
+  Given user adds item to cart
+`)
+
+  const parsed = await parseFeatureFile(filePath)
+
+  assert.ok(parsed)
+  assert.equal(parsed?.featureDescription, 'Checkout flow')
+})

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

@@ -1,259 +1,253 @@
-import { promises as fs } from 'fs'
-import { join, relative } from 'path'
-
-/**
- * Represents a parsed feature file with its scenarios and steps
- */
-export interface ParsedFeature {
-  filePath: string
-  featureName: string
-  featureDescription?: string
-  tags: string[]
-  scenarios: ParsedScenario[]
-}
-
-/**
- * Represents a parsed scenario from a feature file
- */
-export interface ParsedScenario {
-  name: string
-  description?: string
-  tags: string[]
-  steps: ParsedStep[]
-}
-
-/**
- * Represents a parsed step from a feature file
- */
-export interface ParsedStep {
-  keyword: string
-  text: string
-  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')
-
-    // 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
-    let _featureLineIndex = -1
-    for (let i = 0; i < lines.length; i++) {
-      if (lines[i].startsWith('Feature:')) {
-        _featureLineIndex = i
-        // 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
-      }
-    }
-
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i]
-
-      // Skip comments and empty lines
-      if (line.startsWith('#') || line === '') {
-        continue
-      }
-
-      // Parse Feature line
-      if (line.startsWith('Feature:')) {
-        featureName = line.replace('Feature:', '').trim()
-        // Look for description in next lines
-        let j = i + 1
-        while (j < lines.length && lines[j] && !lines[j].startsWith('Scenario:') && !lines[j].startsWith('Feature:')) {
-          if (lines[j] && !lines[j].startsWith('#')) {
-            featureDescription += (featureDescription ? ' ' : '') + lines[j]
-          }
-          j++
-        }
-        continue
-      }
-
-      // Parse Scenario line
-      if (line.startsWith('Scenario:')) {
-        // Save previous scenario if exists
-        if (currentScenario) {
-          scenarios.push(currentScenario)
-        }
-
-        // 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
-          }
-        }
-
-        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
-      }
-
-      // 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++,
-        })
-      }
-    }
-
-    // Add the last scenario
-    if (currentScenario) {
-      scenarios.push(currentScenario)
-    }
-
-    if (!featureName) {
-      console.warn(`No feature found in file: ${filePath}`)
-      return null
-    }
-
-    return {
-      filePath,
-      featureName,
-      featureDescription: featureDescription || undefined,
-      tags: featureTags,
-      scenarios,
-    }
-  } catch (error) {
-    console.error(`Error parsing feature file ${filePath}:`, error)
-    return null
-  }
-}
-
-/**
- * Scans a directory for feature files and parses them
- * @param directoryPath - Path to scan for feature files
- * @returns Promise<ParsedFeature[]> - Array of parsed feature files
- */
-export async function scanFeatureFiles(directoryPath: string): Promise<ParsedFeature[]> {
-  const parsedFeatures: ParsedFeature[] = []
-
-  try {
-    const entries = await fs.readdir(directoryPath, { withFileTypes: true })
-
-    for (const entry of entries) {
-      const fullPath = join(directoryPath, entry.name)
-
-      if (entry.isDirectory()) {
-        // Recursively scan subdirectories
-        const subFeatures = await scanFeatureFiles(fullPath)
-        parsedFeatures.push(...subFeatures)
-      } else if (entry.isFile() && entry.name.endsWith('.feature')) {
-        // Parse feature file
-        const parsedFeature = await parseFeatureFile(fullPath)
-        if (parsedFeature) {
-          parsedFeatures.push(parsedFeature)
-        }
-      }
-    }
-  } catch (error) {
-    console.error(`Error scanning directory ${directoryPath}:`, error)
-  }
-
-  return parsedFeatures
-}
-
-/**
- * Extracts module path from feature file path
- * Works cross-platform (Windows, Mac, Linux)
- * @param featureFilePath - Full path to the feature file
- * @param featuresBaseDir - Base directory for features
- * @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()
-}
+import { promises as fs } from 'fs'
+import { join, relative } from 'path'
+
+/**
+ * Represents a parsed feature file with its scenarios and steps
+ */
+export interface ParsedFeature {
+  filePath: string
+  featureName: string
+  featureDescription?: string
+  tags: string[]
+  scenarios: ParsedScenario[]
+}
+
+/**
+ * Represents a parsed scenario from a feature file
+ */
+export interface ParsedScenario {
+  name: string
+  description?: string
+  tags: string[]
+  steps: ParsedStep[]
+}
+
+/**
+ * Represents a parsed step from a feature file
+ */
+export interface ParsedStep {
+  keyword: string
+  text: string
+  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')
+
+    // 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
+    let _featureLineIndex = -1
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].startsWith('Feature:')) {
+        _featureLineIndex = i
+        // 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
+      }
+    }
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+
+      // Skip comments and empty lines
+      if (line.startsWith('#') || line === '') {
+        continue
+      }
+
+      // Parse Feature line
+      if (line.startsWith('Feature:')) {
+        const featureLineText = line.replace('Feature:', '').trim()
+        featureName = featureLineText
+        featureDescription = featureLineText
+        continue
+      }
+
+      // Parse Scenario line
+      if (line.startsWith('Scenario:')) {
+        // Save previous scenario if exists
+        if (currentScenario) {
+          scenarios.push(currentScenario)
+        }
+
+        // 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
+          }
+        }
+
+        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
+      }
+
+      // 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++,
+        })
+      }
+    }
+
+    // Add the last scenario
+    if (currentScenario) {
+      scenarios.push(currentScenario)
+    }
+
+    if (!featureName) {
+      console.warn(`No feature found in file: ${filePath}`)
+      return null
+    }
+
+    return {
+      filePath,
+      featureName,
+      featureDescription: featureDescription || undefined,
+      tags: featureTags,
+      scenarios,
+    }
+  } catch (error) {
+    console.error(`Error parsing feature file ${filePath}:`, error)
+    return null
+  }
+}
+
+/**
+ * Scans a directory for feature files and parses them
+ * @param directoryPath - Path to scan for feature files
+ * @returns Promise<ParsedFeature[]> - Array of parsed feature files
+ */
+export async function scanFeatureFiles(directoryPath: string): Promise<ParsedFeature[]> {
+  const parsedFeatures: ParsedFeature[] = []
+
+  try {
+    const entries = await fs.readdir(directoryPath, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = join(directoryPath, entry.name)
+
+      if (entry.isDirectory()) {
+        // Recursively scan subdirectories
+        const subFeatures = await scanFeatureFiles(fullPath)
+        parsedFeatures.push(...subFeatures)
+      } else if (entry.isFile() && entry.name.endsWith('.feature')) {
+        // Parse feature file
+        const parsedFeature = await parseFeatureFile(fullPath)
+        if (parsedFeature) {
+          parsedFeatures.push(parsedFeature)
+        }
+      }
+    }
+  } catch (error) {
+    console.error(`Error scanning directory ${directoryPath}:`, error)
+  }
+
+  return parsedFeatures
+}
+
+/**
+ * Extracts module path from feature file path
+ * Works cross-platform (Windows, Mac, Linux)
+ * @param featureFilePath - Full path to the feature file
+ * @param featuresBaseDir - Base directory for features
+ * @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()
+}

package/templates/default/src/lib/sync/sync-pending-counts.test.ts

@@ -123,6 +123,30 @@ test('matches test suites by generated filesystem key instead of raw DB name', (
   assert.equal(count, 0)
 })
 
+test('matches test suites when DB description is null and feature uses suite name', () => {
+  const count = countTestSuiteMismatches(
+    [
+      {
+        name: 'user-login-suite',
+        description: 'User Login Suite',
+        modulePath: '/auth',
+        tags: [],
+      },
+    ],
+    [
+      {
+        name: 'User Login Suite',
+        description: null,
+        moduleId: 'module-auth',
+        tags: [],
+      },
+    ],
+    new Map([['module-auth', '/auth']]),
+  )
+
+  assert.equal(count, 0)
+})
+
 test('matches projected test cases against generated feature-file output', () => {
   const count = countTestCaseMismatches(
     [

package/templates/default/src/lib/sync/sync-pending-counts.ts

@@ -825,7 +825,7 @@ async function buildFilesystemSnapshot(baseDir: string): Promise<FilesystemSnaps
 
   const testSuites: TestSuiteFromFs[] = parsedFeatures.map(feature => ({
     name: extractTestSuiteNameFromFilename(feature.filePath),
-    description: feature.featureDescription ?? null,
+    description: feature.featureDescription ?? feature.featureName ?? null,
     modulePath: extractModulePathFromFilePath(feature.filePath, featuresDir),
     tags: extractFeatureLevelTags(feature),
   }))
@@ -1099,7 +1099,8 @@ export function countTestSuiteMismatches(
     const fsTagExpressions = suite.tags.map(normalizeTagExpression)
     const hasMatch = (dbByKey.get(suiteKey) ?? []).some(existing => {
       const dbTagExpressions = existing.tags.map(tag => normalizeTagExpression(tag.tagExpression))
-      return (existing.description ?? null) === (suite.description ?? null) && sameStringSet(dbTagExpressions, fsTagExpressions)
+      const expectedDescription = existing.description ?? existing.name
+      return expectedDescription === (suite.description ?? null) && sameStringSet(dbTagExpressions, fsTagExpressions)
     })
 
     if (!hasMatch) {