@sun-asterisk/sungen 2.4.5 → 2.5.0

package/src/cli/commands/generate.ts

@@ -58,6 +58,7 @@ export function registerGenerateCommand(program: Command): void {
     .option('-s, --screen <name>', 'Generate tests for a specific screen')
     .option('--all', 'Generate tests for all screens')
     .option('--framework <name>', 'Test framework (default: playwright)', 'playwright')
+    .option('--inline-data', 'Hardcode test data at compile time instead of runtime loading')
     .action(async (options) => {
       try {
         const screenName = options.screen;
@@ -89,6 +90,7 @@ export function registerGenerateCommand(program: Command): void {
           framework: options.framework || 'playwright',
           screenName,
           verbose: program.opts().verbose,
+          runtimeData: !options.inlineData,
         });
 
         const results = await generator.generateAllTests(

package/src/cli/commands/update.ts

@@ -1,12 +1,52 @@
 import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+
+/**
+ * `sungen update` does two jobs in sequence:
+ *
+ *  1. Reinstall `@sun-asterisk/sungen@latest` globally via npm so the bundled
+ *     AI templates are refreshed.
+ *  2. Re-execute `sungen update` with the env var `SUNGEN_UPDATE_SKIP_NPM=1`
+ *     so the AI rules / commands / skills inside the project get overwritten
+ *     from the *new* templates.
+ *
+ * We use an environment variable (not a CLI flag) for the internal hand-off
+ * because Commander throws "unknown option" if the currently-installed
+ * published version doesn't recognise the flag yet. Env vars are silently
+ * ignored by older versions — the worst case is one extra (idempotent) npm
+ * install, never a crash.
+ *
+ * The public `--skip-npm-install` flag is still available for users who
+ * already installed the binary by other means (CI pipelines, corporate
+ * mirror, manual download) and only want to refresh the project AI assets.
+ */
+
+const SKIP_NPM_ENV = 'SUNGEN_UPDATE_SKIP_NPM';
 
 export function registerUpdateCommand(program: Command): void {
   program
     .command('update')
-    .description('Update AI rules, commands, and skills to the latest version')
+    .description(
+      'Reinstall @sun-asterisk/sungen@latest + refresh AI rules, commands, and skills',
+    )
     .option('--dry-run', 'Show what would be updated without making changes')
-    .action(async (options: { dryRun?: boolean }) => {
+    .option(
+      '--skip-npm-install',
+      'Skip the `npm install -g @sun-asterisk/sungen@latest` step (refresh project AI assets only)',
+      false,
+    )
+    .action(async (options: { dryRun?: boolean; skipNpmInstall?: boolean }) => {
       try {
+        const skipNpm =
+          Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
+
+        if (!skipNpm) {
+          reinstallLatestSungen();
+          printCurrentVersion();
+          reExecUpdateForAIAssets(options.dryRun ?? false);
+          return;
+        }
+
         const { AIRulesUpdater } = require('../../orchestrator/ai-rules-updater');
         const updater = new AIRulesUpdater(process.cwd());
         await updater.update(options.dryRun ?? false);
@@ -16,3 +56,45 @@ export function registerUpdateCommand(program: Command): void {
       }
     });
 }
+
+function reinstallLatestSungen(): void {
+  console.log('📦 Installing @sun-asterisk/sungen@latest...');
+  const result = spawnSync('npm', ['install', '-g', '@sun-asterisk/sungen@latest'], {
+    stdio: 'inherit',
+    shell: true,
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      'npm install -g @sun-asterisk/sungen@latest failed. Run it manually or check your npm setup.',
+    );
+  }
+}
+
+function printCurrentVersion(): void {
+  console.log('\n🔎 Installed version:');
+  spawnSync('sungen', ['--version'], { stdio: 'inherit', shell: true });
+  console.log('');
+}
+
+function reExecUpdateForAIAssets(dryRun: boolean): void {
+  const args = ['update'];
+  if (dryRun) args.push('--dry-run');
+
+  const result = spawnSync('sungen', args, {
+    stdio: 'inherit',
+    shell: true,
+    env: { ...process.env, [SKIP_NPM_ENV]: '1' },
+  });
+
+  if (result.status !== 0) {
+    console.error(
+      '\n⚠️  AI-rules refresh step returned a non-zero exit code.\n' +
+        `   If the newly installed version is older and didn't recognise this flow,\n` +
+        '   run the refresh manually:\n\n' +
+        '       sungen update --skip-npm-install' +
+        (dryRun ? ' --dry-run' : '') +
+        '\n',
+    );
+  }
+  process.exit(result.status ?? 0);
+}

package/src/cli/index.ts

@@ -10,6 +10,7 @@ import { registerAddCommand } from './commands/add';
 import { registerGenerateCommand } from './commands/generate';
 import { registerMakeauthCommand } from './commands/makeauth';
 import { registerUpdateCommand } from './commands/update';
+import { registerDeliveryCommand } from './commands/delivery';
 
 async function main() {
   const program = new Command();
@@ -17,18 +18,19 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.4.5');
+    .version('2.5.0');
 
   // Global options
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (5 only)
+  // Register commands (6)
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
   registerMakeauthCommand(program);
   registerUpdateCommand(program);
+  registerDeliveryCommand(program);
 
   await program.parseAsync(process.argv);
 }

package/src/exporters/csv-exporter.ts

@@ -0,0 +1,304 @@
+/**
+ * Assemble CSV rows from merged scenarios + test data + playwright results.
+ * Outputs a CSV file matching the BM-2-901-13 test case template format.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getPackageVersion } from './package-info';
+import { MergedScenario } from './scenario-merger';
+import {
+  extractAuthRole,
+  extractPriority,
+  extractTestcaseType,
+  generateTcId,
+  mapVpToCategory2,
+  splitVpAndName,
+} from './feature-parser';
+import { formatNumberedSteps, formatPrecondition, cleanStepLine } from './step-formatter';
+import { formatTestData } from './test-data-resolver';
+import {
+  formatExecutedDate,
+  formatNote,
+  statusToTestResult,
+} from './playwright-report-parser';
+import { EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
+
+export interface BuildCsvInput {
+  screen: string;
+  featureName: string;
+  merged: MergedScenario[];
+  testData: Record<string, string>;
+  results: Map<string, PlaywrightResult> | null;
+  env: EnvironmentInfo;
+}
+
+/**
+ * Build CSV test case rows from merged scenarios.
+ */
+export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
+  const rows: TestCaseRow[] = [];
+  let fallbackIndex = 1;
+
+  for (const m of input.merged) {
+    const { vpId, category1 } = splitVpAndName(m.feature.name);
+    const tcId = generateTcId(input.screen, vpId, fallbackIndex);
+    if (!vpId) fallbackIndex++;
+
+    const category2 = mapVpToCategory2(vpId);
+    const priority = extractPriority(m.feature.tags);
+    const testcaseType = extractTestcaseType(m.feature.tags);
+    const authRole = extractAuthRole(m.feature.tags);
+
+    // Prefer .spec.ts resolved comments for Steps/Expected if available
+    let steps: string;
+    let expectedResults: string;
+    let precondition: string;
+
+    if (m.spec) {
+      precondition = formatPrecondition(authRole, m.spec.precondition);
+      steps = formatNumberedSteps(m.spec.steps);
+      expectedResults = formatNumberedSteps(m.spec.expectations);
+    } else {
+      // Fallback to .feature raw steps
+      precondition = formatPrecondition(authRole, m.feature.rawGivenSteps);
+      steps = formatNumberedSteps(m.feature.rawWhenSteps);
+      expectedResults = formatNumberedSteps(m.feature.rawThenSteps);
+    }
+
+    const testData = formatTestData(m.feature.referencedVars, input.testData);
+
+    // Match Playwright result by test title (from .spec.ts) OR by scenarioName
+    let result: PlaywrightResult | undefined;
+    if (input.results && m.spec) {
+      result = input.results.get(m.spec.testTitle);
+    }
+
+    // Determine Test Result
+    let testResult: string;
+    let executedDate = '';
+    let note = '';
+    let environment = '';
+    let executor = '';
+
+    if (!m.spec) {
+      // Scenario not compiled → Manual if @manual, else Not compiled
+      testResult = testcaseType === 'Manual' ? 'Pending' : 'N/A';
+      if (testcaseType !== 'Manual') {
+        note = 'Scenario not compiled — re-run `sungen generate --screen ' + input.screen + '`';
+      }
+    } else if (!result) {
+      // Compiled but no execution record → Pending
+      testResult = 'Pending';
+    } else {
+      testResult = statusToTestResult(result.status);
+      executedDate = formatExecutedDate(result.startTime);
+      note = formatNote(result);
+      environment = `${input.env.baseURL} (${input.env.projectName})`;
+      executor = input.env.executor;
+    }
+
+    // If we have environment info and the test actually ran, populate env + executor
+    if (testResult !== 'Pending' && testResult !== 'N/A') {
+      if (!environment) environment = `${input.env.baseURL} (${input.env.projectName})`;
+      if (!executor) executor = input.env.executor;
+    }
+
+    rows.push({
+      tcId,
+      category1,
+      category2,
+      category3: input.featureName,
+      category4: input.screen,
+      precondition,
+      testData,
+      steps,
+      expectedResults,
+      priority,
+      testcaseType: m.spec ? testcaseType : testcaseType === 'Manual' ? 'Manual' : 'Not compiled',
+      testResult,
+      executedDate,
+      testExecutor: executor,
+      testEnvironment: environment,
+      note,
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Calculate summary statistics from rows.
+ */
+export function buildSummary(screen: string, rows: TestCaseRow[], outputFile: string): ScreenSummary {
+  const summary: ScreenSummary = {
+    screen,
+    total: rows.length,
+    passed: 0,
+    failed: 0,
+    pending: 0,
+    na: 0,
+    notCompiled: 0,
+    outputFile,
+  };
+  for (const r of rows) {
+    if (r.testResult === 'Passed') summary.passed++;
+    else if (r.testResult === 'Failed') summary.failed++;
+    else if (r.testResult === 'Pending') summary.pending++;
+    else if (r.testResult === 'N/A') summary.na++;
+    if (r.testcaseType === 'Not compiled') summary.notCompiled++;
+  }
+  return summary;
+}
+
+// ----------------------------------------------------------------------------
+// CSV writer
+// ----------------------------------------------------------------------------
+
+/**
+ * Escape a CSV cell per RFC 4180.
+ * Wrap in quotes if contains: comma, newline, quote. Escape embedded " as "".
+ */
+function csvCell(v: string | number | undefined | null): string {
+  if (v === null || v === undefined) return '';
+  const s = String(v);
+  if (/[",\n\r]/.test(s)) {
+    return '"' + s.replace(/"/g, '""') + '"';
+  }
+  return s;
+}
+
+function csvRow(cells: Array<string | number | undefined | null>): string {
+  return cells.map(csvCell).join(',');
+}
+
+/**
+ * Compose the full CSV file content matching the BM-2-901-13 template.
+ */
+export function renderCsv(summary: ScreenSummary, rows: TestCaseRow[], specLink: string): string {
+  const issueDate = (() => {
+    const d = new Date();
+    return `${String(d.getDate()).padStart(2, '0')}/${String(d.getMonth() + 1).padStart(2, '0')}/${d.getFullYear()}`;
+  })();
+
+  const total = summary.total || 1; // avoid div by zero
+  const pct = (n: number) => `${Math.round((n / total) * 100)}%`;
+
+  // UTF-8 BOM for Excel compatibility with Vietnamese
+  const BOM = '\ufeff';
+  const lines: string[] = [];
+
+  // Header metadata block (mirrors sample)
+  const titleLabel = `${summary.screen.toUpperCase()} TESTCASE`;
+  lines.push(csvRow(['', '', '', titleLabel, '', '', 'No: BM-2-901-13', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', '', '', '', '', `Version: ${getPackageVersion()}`, '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', '', '', '', '', `Issue Date: ${issueDate}`, '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['SUN ASTERISK VIETNAM CO., LTD', '', '', '', '', '', 'ISO/IEC 27001:2022 & ISO 9001:2015', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', 'Total TCs', 'Passed', 'Failed', 'Pending', 'N/A', 'Remaining', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', summary.total, summary.passed, summary.failed, summary.pending, summary.na, summary.pending + summary.na, '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', '', pct(summary.passed), pct(summary.failed), pct(summary.pending), pct(summary.na), pct(summary.pending + summary.na), '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['Spec/Design link:', specLink, '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow(['*: Mandatory', '', '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+  lines.push(csvRow([
+    'TC ID*',
+    '{Category 1}',
+    '{Category 2}',
+    '{Category 3}',
+    '{Category 4}',
+    'Pre-condition',
+    'Test Data',
+    'Steps*',
+    'Expected results*',
+    'Priority',
+    'Testcase type',
+    'Test Result*',
+    'Executed Date*',
+    'Test Executor*',
+    'Test Environment',
+    'Note\n(Test evidence, DefectID, Actual result)',
+  ]));
+
+  // Group rows by Category 2 (in stable order)
+  const order = ['Accessing', 'GUI', 'Function'];
+  const grouped = new Map<string, TestCaseRow[]>();
+  for (const row of rows) {
+    const g = grouped.get(row.category2) || [];
+    g.push(row);
+    grouped.set(row.category2, g);
+  }
+  const emittedGroups = new Set<string>();
+  for (const group of order) {
+    const groupRows = grouped.get(group);
+    if (!groupRows || groupRows.length === 0) continue;
+    emittedGroups.add(group);
+    // Section header row (empty Category 1, group name in Category 2 column? sample puts it differently — empty row then category marker)
+    lines.push(csvRow(['', group, '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+    for (const row of groupRows) {
+      lines.push(csvRow([
+        row.tcId,
+        row.category1,
+        '',
+        '',
+        '',
+        row.precondition,
+        row.testData,
+        row.steps,
+        row.expectedResults,
+        row.priority,
+        row.testcaseType,
+        row.testResult,
+        row.executedDate,
+        row.testExecutor,
+        row.testEnvironment,
+        row.note,
+      ]));
+    }
+  }
+  // Emit any groups not in the predefined order
+  for (const [group, groupRows] of grouped.entries()) {
+    if (emittedGroups.has(group)) continue;
+    lines.push(csvRow(['', group, '', '', '', '', '', '', '', '', '', '', '', '', '', '']));
+    for (const row of groupRows) {
+      lines.push(csvRow([
+        row.tcId,
+        row.category1,
+        '',
+        '',
+        '',
+        row.precondition,
+        row.testData,
+        row.steps,
+        row.expectedResults,
+        row.priority,
+        row.testcaseType,
+        row.testResult,
+        row.executedDate,
+        row.testExecutor,
+        row.testEnvironment,
+        row.note,
+      ]));
+    }
+  }
+
+  return BOM + lines.join('\n') + '\n';
+}
+
+/**
+ * Write the CSV to disk at qa/deliverables/<screen>-testcases.csv.
+ * Creates directory if needed.
+ */
+export function writeCsv(cwd: string, screen: string, csvContent: string): string {
+  const outDir = path.join(cwd, 'qa', 'deliverables');
+  if (!fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+  const outPath = path.join(outDir, `${screen}-testcases.csv`);
+  fs.writeFileSync(outPath, csvContent, 'utf-8');
+  return outPath;
+}
+
+// mark unused import to silence TS if needed
+void cleanStepLine;

package/src/exporters/feature-parser.ts

@@ -0,0 +1,168 @@
+/**
+ * Parse .feature files to extract scenario metadata for CSV export.
+ * Reuses the existing GherkinParser.
+ */
+
+import { GherkinParser, ParsedFeature, ParsedScenario } from '../generators/gherkin-parser';
+import { FeatureMetadata, ScenarioMetadata } from './types';
+
+/**
+ * Variables referenced in a scenario: find all {{var_name}} in step text.
+ */
+function extractReferencedVars(scenario: ParsedScenario): string[] {
+  const vars = new Set<string>();
+  for (const step of scenario.steps) {
+    const matches = step.text.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g);
+    for (const match of matches) {
+      vars.add(match[1]);
+    }
+    // Also check inline DataTable cells
+    if (step.dataTable) {
+      for (const row of step.dataTable.rows) {
+        for (const cell of row.cells) {
+          const cellMatches = cell.matchAll(/\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g);
+          for (const match of cellMatches) {
+            vars.add(match[1]);
+          }
+        }
+      }
+    }
+  }
+  return Array.from(vars);
+}
+
+/**
+ * Classify each step into Given / When / Then bucket based on its preceding
+ * explicit keyword. "And" inherits from the previous explicit keyword.
+ */
+function classifySteps(scenario: ParsedScenario): { given: string[]; when: string[]; then: string[] } {
+  const given: string[] = [];
+  const when: string[] = [];
+  const then: string[] = [];
+  let currentBucket: 'given' | 'when' | 'then' = 'given';
+
+  for (const step of scenario.steps) {
+    const keyword = step.keyword.trim();
+    if (keyword === 'Given') currentBucket = 'given';
+    else if (keyword === 'When') currentBucket = 'when';
+    else if (keyword === 'Then') currentBucket = 'then';
+    // And / But → inherit currentBucket
+
+    if (currentBucket === 'given') given.push(step.text);
+    else if (currentBucket === 'when') when.push(step.text);
+    else then.push(step.text);
+  }
+
+  return { given, when, then };
+}
+
+/**
+ * Parse .feature file → structured metadata ready for CSV assembly.
+ */
+export function parseFeatureMetadata(featureFilePath: string): FeatureMetadata {
+  const parser = new GherkinParser();
+  const parsed: ParsedFeature = parser.parseFeatureFile(featureFilePath);
+
+  const scenarios: ScenarioMetadata[] = parsed.scenarios.map((sc) => {
+    const { given, when, then } = classifySteps(sc);
+
+    return {
+      name: sc.name,
+      tags: [...parsed.tags, ...sc.tags],
+      stepsName: sc.stepsName,
+      extendsName: sc.extendsName,
+      referencedVars: extractReferencedVars(sc),
+      rawGivenSteps: given,
+      rawWhenSteps: when,
+      rawThenSteps: then,
+    };
+  });
+
+  return {
+    featureName: parsed.name,
+    featurePath: parsed.path,
+    featureTags: parsed.tags,
+    scenarios,
+  };
+}
+
+/**
+ * Return true if this scenario is a @steps:<name> base scenario that should
+ * be excluded from the CSV (it's only used for @extend inheritance).
+ */
+export function isStepsBaseScenario(sc: ScenarioMetadata): boolean {
+  return !!sc.stepsName;
+}
+
+/**
+ * Return true if this is the default scaffold sample scenario (not real).
+ */
+export function isSampleScaffoldScenario(sc: ScenarioMetadata): boolean {
+  return /^Sample scenario for /i.test(sc.name);
+}
+
+/**
+ * Extract priority from scenario tags.
+ */
+export function extractPriority(tags: string[]): string {
+  if (tags.includes('@critical')) return 'Critical';
+  if (tags.includes('@high')) return 'High';
+  if (tags.includes('@normal')) return 'Normal';
+  if (tags.includes('@low')) return 'Low';
+  return 'Normal';
+}
+
+/**
+ * Extract testcase type from scenario tags.
+ */
+export function extractTestcaseType(tags: string[]): 'Auto' | 'Manual' {
+  return tags.includes('@manual') ? 'Manual' : 'Auto';
+}
+
+/**
+ * Extract auth role from tags. Returns 'no-auth' if @no-auth, else role name or null.
+ */
+export function extractAuthRole(tags: string[]): string | null {
+  if (tags.includes('@no-auth')) return 'no-auth';
+  const authTag = tags.find((t) => t.startsWith('@auth:'));
+  if (authTag) return authTag.replace('@auth:', '');
+  return null;
+}
+
+/**
+ * Extract VP ID and human-readable name from scenario name like
+ * "VP-UI-001 Modal displays all required fields" →
+ *   { vpId: "VP-UI-001", category1: "Modal displays all required fields" }
+ */
+export function splitVpAndName(scenarioName: string): { vpId?: string; category1: string } {
+  const match = scenarioName.match(/^(VP-[A-Z]+-\d+[a-zA-Z]?)\s+(.+)$/);
+  if (match) {
+    return { vpId: match[1], category1: match[2] };
+  }
+  return { category1: scenarioName };
+}
+
+/**
+ * Map VP prefix to Category 2.
+ */
+export function mapVpToCategory2(vpId: string | undefined): string {
+  if (!vpId) return 'Function';
+  if (vpId.startsWith('VP-SEC-')) return 'Accessing';
+  if (vpId.startsWith('VP-UI-')) return 'GUI';
+  if (vpId.startsWith('VP-VAL-')) return 'Function';
+  if (vpId.startsWith('VP-LOGIC-')) return 'Function';
+  return 'Function';
+}
+
+/**
+ * Generate TC ID: <SCREEN_UPPER>-<VP-part>-<NNN> OR <SCREEN_UPPER>-<NNN> if no VP.
+ */
+export function generateTcId(screen: string, vpId: string | undefined, fallbackIndex: number): string {
+  const screenUpper = screen.toUpperCase().replace(/[^A-Z0-9]/g, '-');
+  if (vpId) {
+    // VP-UI-001 → UI-001
+    const vpPart = vpId.replace(/^VP-/, '');
+    return `${screenUpper}-${vpPart}`;
+  }
+  return `${screenUpper}-${String(fallbackIndex).padStart(3, '0')}`;
+}

package/src/exporters/package-info.ts

@@ -0,0 +1,35 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+let cached: string | null = null;
+
+/**
+ * Read `version` from the sungen package.json at module-root so the delivery
+ * report always reflects the installed CLI version instead of a hardcoded
+ * string. The lookup walks up from __dirname (works under both src/ via ts-node
+ * and dist/ after compilation) until a package.json with a `name` starting
+ * with `@sun-asterisk/sungen` or `sungen` is found.
+ */
+export function getPackageVersion(): string {
+  if (cached) return cached;
+  let dir = __dirname;
+  for (let i = 0; i < 6; i++) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg && typeof pkg.version === 'string') {
+          cached = pkg.version;
+          return cached;
+        }
+      } catch {
+        // ignore and keep walking
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  cached = 'unknown';
+  return cached;
+}