@sun-asterisk/sungen 2.6.1 → 2.6.3

package/src/dashboard/history-store.ts

@@ -0,0 +1,86 @@
+/**
+ * Persist dashboard snapshots under qa/dashboard/history/ and prune to a fixed
+ * max count (oldest by mtime are deleted). Used by `sungen dashboard` to
+ * accumulate runs for Trends / Compare views.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { DashboardSnapshot } from './types';
+
+export const DEFAULT_MAX_HISTORY = 20;
+
+export interface HistoryWriteResult {
+  written: string;                     // absolute path written
+  pruned: string[];                    // absolute paths removed
+  retained: string[];                  // absolute paths still on disk (newest → oldest)
+}
+
+export function historyDir(cwd: string): string {
+  return path.join(cwd, 'qa', 'dashboard', 'history');
+}
+
+/**
+ * Write `snapshot` as <runId>.json and prune older files until at most `max`
+ * files remain. Files are sorted by mtime so manual edits (rare) still work.
+ */
+export function writeSnapshotToHistory(
+  cwd: string,
+  snapshot: DashboardSnapshot,
+  max: number = DEFAULT_MAX_HISTORY
+): HistoryWriteResult {
+  const dir = historyDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const filename = `${snapshot.runId}.json`;
+  const target = path.join(dir, filename);
+  fs.writeFileSync(target, JSON.stringify(snapshot, null, 2), 'utf-8');
+
+  const pruned = pruneHistory(dir, max);
+
+  const retained = listHistoryFiles(dir);
+  return { written: target, pruned, retained };
+}
+
+/**
+ * Return absolute paths of every JSON file under history/, sorted newest → oldest.
+ */
+export function listHistoryFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => path.join(dir, f))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+}
+
+/**
+ * Read every history JSON, oldest → newest. Skips files that fail to parse.
+ */
+export function readHistory(cwd: string): DashboardSnapshot[] {
+  const dir = historyDir(cwd);
+  const files = listHistoryFiles(dir).reverse(); // oldest → newest
+  const out: DashboardSnapshot[] = [];
+  for (const f of files) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(f, 'utf-8')) as DashboardSnapshot;
+      out.push(parsed);
+    } catch {
+      // ignore malformed
+    }
+  }
+  return out;
+}
+
+/**
+ * Delete oldest files in `dir` until at most `max` remain.
+ * Returns the absolute paths removed.
+ */
+function pruneHistory(dir: string, max: number): string[] {
+  const files = listHistoryFiles(dir);              // newest first
+  if (files.length <= max) return [];
+  const toRemove = files.slice(max);
+  for (const f of toRemove) {
+    try { fs.unlinkSync(f); } catch { /* ignore */ }
+  }
+  return toRemove;
+}

package/src/dashboard/html-renderer.ts

@@ -0,0 +1,90 @@
+/**
+ * Inject a DashboardPayload into the pre-built single-file HTML template,
+ * then write the result to qa/dashboard/index.html.
+ *
+ * The template lives at src/dashboard/templates/index.html (built by
+ * dashboard/, then copied during `npm run build`). It must contain
+ * the placeholder line:
+ *
+ *     <script id="__SUNGEN_DASHBOARD__" type="application/json">{}</script>
+ *
+ * The renderer replaces the JSON content with the payload — no other
+ * mutation. This keeps the template itself fully static, so opening it
+ * directly (without running the CLI) shows an empty-state dashboard.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { DashboardPayload, DashboardSnapshot } from './types';
+import { readHistory } from './history-store';
+
+const PAYLOAD_TAG_OPEN = '<script id="__SUNGEN_DASHBOARD__" type="application/json">';
+const PAYLOAD_TAG_CLOSE = '</script>';
+
+/**
+ * Locate the bundled template. Looks first in dist/ (production), then src/
+ * (when running via tsx in dev).
+ */
+export function resolveTemplatePath(): string {
+  const candidates = [
+    // Compiled package: dist/dashboard/templates/index.html (copy-templates)
+    path.join(__dirname, 'templates', 'index.html'),
+    // Dev: src/dashboard/templates/index.html
+    path.join(__dirname, '..', '..', 'src', 'dashboard', 'templates', 'index.html'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  throw new Error(
+    'Dashboard HTML template not found. Build it via:\n' +
+    '    cd dashboard && npm install && npm run build\n' +
+    'then copy dashboard/dist/index.html → src/dashboard/templates/index.html'
+  );
+}
+
+export function buildPayload(cwd: string, current: DashboardSnapshot): DashboardPayload {
+  const all = readHistory(cwd);
+  // Exclude `current` from history if it's been written there already.
+  const history = all.filter((s) => s.runId !== current.runId);
+  return { current, history };
+}
+
+export interface RenderResult {
+  outputPath: string;
+  bytes: number;
+}
+
+/**
+ * Render `payload` into the template and write to qa/dashboard/index.html.
+ */
+export function renderDashboardHtml(cwd: string, payload: DashboardPayload): RenderResult {
+  const templatePath = resolveTemplatePath();
+  const template = fs.readFileSync(templatePath, 'utf-8');
+
+  const json = JSON.stringify(payload);
+  const replaced = injectPayload(template, json);
+
+  const outDir = path.join(cwd, 'qa', 'dashboard');
+  fs.mkdirSync(outDir, { recursive: true });
+  const outputPath = path.join(outDir, 'index.html');
+  fs.writeFileSync(outputPath, replaced, 'utf-8');
+
+  return { outputPath, bytes: Buffer.byteLength(replaced, 'utf-8') };
+}
+
+function injectPayload(template: string, json: string): string {
+  const start = template.indexOf(PAYLOAD_TAG_OPEN);
+  if (start === -1) {
+    throw new Error(
+      `Template is missing the payload placeholder ${PAYLOAD_TAG_OPEN}…${PAYLOAD_TAG_CLOSE}`
+    );
+  }
+  const contentStart = start + PAYLOAD_TAG_OPEN.length;
+  const contentEnd = template.indexOf(PAYLOAD_TAG_CLOSE, contentStart);
+  if (contentEnd === -1) {
+    throw new Error('Template payload placeholder is unterminated');
+  }
+  // Escape </script> inside JSON to prevent breaking the surrounding script tag.
+  const safe = json.replace(/<\/script>/gi, '<\\/script>');
+  return template.slice(0, contentStart) + safe + template.slice(contentEnd);
+}

package/src/dashboard/snapshot-builder.ts

@@ -0,0 +1,273 @@
+/**
+ * Orchestrate dashboard snapshot construction across all screens/flows.
+ *
+ * Inputs are read from the same on-disk sources used by `sungen delivery`:
+ *   qa/screens/<name>/...        feature, test-data, selectors, requirements
+ *   qa/flows/<name>/...
+ *   specs/generated/<...>/...    compiled .spec.ts + per-target test-result.json
+ *   test-results/results.json    global fallback
+ *
+ * Output is a DashboardSnapshot ready to be embedded in HTML or written as
+ * a history entry under qa/dashboard/history/<runId>.json.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { parseFeatureMetadata } from '../exporters/feature-parser';
+import { parseSpecFile } from '../exporters/spec-parser';
+import { loadTestData } from '../exporters/test-data-resolver';
+import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
+import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
+import { buildScreenSnapshot } from '../exporters/json-exporter';
+import { getPackageVersion } from '../exporters/package-info';
+import { EnvironmentInfo } from '../exporters/types';
+import {
+  AggregateSummary,
+  DashboardSnapshot,
+  ScenarioSnapshot,
+  ScreenSnapshot,
+  SNAPSHOT_VERSION,
+} from './types';
+
+export interface DashboardTarget {
+  name: string;
+  isFlow: boolean;
+}
+
+export interface BuildSnapshotOptions {
+  cwd: string;
+  targets: DashboardTarget[];
+  env: EnvironmentInfo;
+  /** Skip targets where the .feature/.spec.ts pair fails to parse. */
+  continueOnError?: boolean;
+}
+
+export function buildDashboardSnapshot(options: BuildSnapshotOptions): DashboardSnapshot {
+  const { cwd, targets, env } = options;
+  const screens: ScreenSnapshot[] = [];
+
+  for (const target of targets) {
+    try {
+      const screen = buildOneScreen(cwd, target, env);
+      if (screen) screens.push(screen);
+    } catch (err) {
+      if (!options.continueOnError) throw err;
+      // eslint-disable-next-line no-console
+      console.warn(`[dashboard] skipping ${target.name}: ${(err as Error).message}`);
+    }
+  }
+
+  const now = new Date();
+  return {
+    version: SNAPSHOT_VERSION,
+    runId: makeRunId(now),
+    generatedAt: toLocalIso(now),
+    environment: collectEnvironment(cwd, env),
+    summary: aggregateSummary(screens),
+    screens: screens.sort((a, b) => a.name.localeCompare(b.name)),
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Per-target build
+// ----------------------------------------------------------------------------
+
+function buildOneScreen(
+  cwd: string,
+  target: DashboardTarget,
+  env: EnvironmentInfo
+): ScreenSnapshot | null {
+  const base = qaDir(cwd, target);
+  const genBase = generatedDir(cwd, target);
+  const featureFile = path.join(base, 'features', `${target.name}.feature`);
+  const testDataFile = path.join(base, 'test-data', `${target.name}.yaml`);
+  const specFile = path.join(genBase, `${target.name}.spec.ts`);
+  const specMdFile = path.join(base, 'requirements', 'spec.md');
+  const resultsFile = resolveResultsPath(cwd, target);
+
+  if (!fs.existsSync(featureFile)) return null;
+
+  const feature = parseFeatureMetadata(featureFile);
+  const spec = fs.existsSync(specFile)
+    ? parseSpecFile(specFile)
+    : { tests: [] };
+  const testData = fs.existsSync(testDataFile) ? loadTestData(testDataFile) : {};
+  const results = resultsFile ? loadPlaywrightReport(resultsFile) : null;
+
+  const merged = mergeFeatureAndSpec(feature, spec);
+  const label = target.isFlow ? `flow/${target.name}` : target.name;
+  const specLink = fs.existsSync(specMdFile) ? path.relative(cwd, specMdFile) : undefined;
+
+  return buildScreenSnapshot({
+    screen: label,
+    isFlow: target.isFlow,
+    featureName: feature.featureName,
+    featurePath: feature.featurePath,
+    specLink,
+    merged,
+    testData,
+    results,
+    env,
+  });
+}
+
+// ----------------------------------------------------------------------------
+// Aggregate summary across all screens
+// ----------------------------------------------------------------------------
+
+function aggregateSummary(screens: ScreenSnapshot[]): AggregateSummary {
+  const summary: AggregateSummary = {
+    total: 0,
+    passed: 0,
+    failed: 0,
+    pending: 0,
+    na: 0,
+    notCompiled: 0,
+    passRate: 0,
+    byPriority: { Critical: 0, High: 0, Normal: 0, Low: 0 },
+    byCategory: { Accessing: 0, GUI: 0, Function: 0 },
+    byType: { Auto: 0, Manual: 0, 'Not compiled': 0 },
+  };
+
+  for (const screen of screens) {
+    summary.total += screen.summary.total;
+    summary.passed += screen.summary.passed;
+    summary.failed += screen.summary.failed;
+    summary.pending += screen.summary.pending;
+    summary.na += screen.summary.na;
+    summary.notCompiled += screen.summary.notCompiled;
+
+    for (const s of screen.scenarios) {
+      bumpKey(summary.byPriority, s.priority);
+      bumpKey(summary.byCategory, s.category2);
+      bumpKey(summary.byType, s.type);
+    }
+  }
+
+  const executed = summary.passed + summary.failed;
+  summary.passRate = executed > 0 ? summary.passed / executed : 0;
+  return summary;
+}
+
+function bumpKey(record: Record<string, number>, key: string): void {
+  record[key] = (record[key] ?? 0) + 1;
+}
+
+// ----------------------------------------------------------------------------
+// Path helpers (mirror delivery.ts to stay consistent)
+// ----------------------------------------------------------------------------
+
+function qaDir(cwd: string, target: DashboardTarget): string {
+  return path.join(cwd, 'qa', target.isFlow ? 'flows' : 'screens', target.name);
+}
+
+function generatedDir(cwd: string, target: DashboardTarget): string {
+  return target.isFlow
+    ? path.join(cwd, 'specs', 'generated', 'flows', target.name)
+    : path.join(cwd, 'specs', 'generated', target.name);
+}
+
+function resolveResultsPath(cwd: string, target: DashboardTarget): string | null {
+  const genDir = generatedDir(cwd, target);
+  const perTarget = path.join(genDir, `${target.name}-test-result.json`);
+  if (fs.existsSync(perTarget)) return perTarget;
+  const global = path.join(cwd, 'test-results', 'results.json');
+  if (fs.existsSync(global)) return global;
+  return null;
+}
+
+// ----------------------------------------------------------------------------
+// Discovery (also used by CLI)
+// ----------------------------------------------------------------------------
+
+export function listDashboardTargets(cwd: string): DashboardTarget[] {
+  const targets: DashboardTarget[] = [];
+
+  const screensDir = path.join(cwd, 'qa', 'screens');
+  if (fs.existsSync(screensDir)) {
+    for (const d of fs.readdirSync(screensDir, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push({ name: d.name, isFlow: false });
+    }
+  }
+
+  const flowsDir = path.join(cwd, 'qa', 'flows');
+  if (fs.existsSync(flowsDir)) {
+    for (const d of fs.readdirSync(flowsDir, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push({ name: d.name, isFlow: true });
+    }
+  }
+
+  return targets.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function resolveTargetType(cwd: string, name: string): DashboardTarget {
+  if (fs.existsSync(path.join(cwd, 'qa', 'flows', name))) {
+    return { name, isFlow: true };
+  }
+  return { name, isFlow: false };
+}
+
+// ----------------------------------------------------------------------------
+// Run ID + environment metadata (Vietnam Indochina Time, UTC+7, no DST)
+// ----------------------------------------------------------------------------
+
+const VN_OFFSET_MS = 7 * 60 * 60 * 1000;
+
+/**
+ * Filename-safe ISO timestamp in Vietnam time (UTC+7).
+ * Example: 2026-04-29T08-13-53+0700
+ *
+ * Colons in HH:MM:SS are replaced with `-` (filename-safe on Windows too).
+ * The `+0700` suffix makes the offset explicit so consumers don't need
+ * to assume a default timezone.
+ */
+function makeRunId(now: Date): string {
+  const vn = new Date(now.getTime() + VN_OFFSET_MS);
+  const yyyy = vn.getUTCFullYear();
+  const MM = String(vn.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(vn.getUTCDate()).padStart(2, '0');
+  const HH = String(vn.getUTCHours()).padStart(2, '0');
+  const mm = String(vn.getUTCMinutes()).padStart(2, '0');
+  const ss = String(vn.getUTCSeconds()).padStart(2, '0');
+  return `${yyyy}-${MM}-${dd}T${HH}-${mm}-${ss}+0700`;
+}
+
+/**
+ * Full ISO 8601 timestamp in Vietnam time, with milliseconds and `+07:00` offset.
+ * Example: 2026-04-29T08:13:53.495+07:00
+ */
+function toLocalIso(now: Date): string {
+  const vn = new Date(now.getTime() + VN_OFFSET_MS);
+  const yyyy = vn.getUTCFullYear();
+  const MM = String(vn.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(vn.getUTCDate()).padStart(2, '0');
+  const HH = String(vn.getUTCHours()).padStart(2, '0');
+  const mm = String(vn.getUTCMinutes()).padStart(2, '0');
+  const ss = String(vn.getUTCSeconds()).padStart(2, '0');
+  const ms = String(vn.getUTCMilliseconds()).padStart(3, '0');
+  return `${yyyy}-${MM}-${dd}T${HH}:${mm}:${ss}.${ms}+07:00`;
+}
+
+function collectEnvironment(cwd: string, env: EnvironmentInfo) {
+  let gitBranch: string | undefined;
+  let gitSha: string | undefined;
+  try {
+    gitBranch = execSync('git rev-parse --abbrev-ref HEAD', { cwd, encoding: 'utf-8' }).trim();
+  } catch { /* ignore */ }
+  try {
+    gitSha = execSync('git rev-parse --short HEAD', { cwd, encoding: 'utf-8' }).trim();
+  } catch { /* ignore */ }
+
+  return {
+    baseURL: env.baseURL,
+    projectName: env.projectName,
+    executor: env.executor,
+    sungenVersion: getPackageVersion(),
+    gitBranch,
+    gitSha,
+  };
+}
+
+// Helper for ScenarioSnapshot tree filters in UI (re-exported for callers)
+export type { ScenarioSnapshot };