tuffgal 0.1.0-alpha.0

package/src/runner/coverage.ts

@@ -0,0 +1,76 @@
+import { join } from 'node:path';
+import type { Page } from 'playwright';
+import type MCR from 'monocart-coverage-reports';
+
+type CoverageReportInstance = MCR.CoverageReport;
+
+const PLAYWRIGHT_COVERAGE_OPTIONS = { resetOnNavigation: false } as const;
+
+/**
+ * Collects V8 JS + CSS coverage from every Playwright page the harness
+ * opens during a run, then hands the aggregate to monocart-coverage-reports
+ * for V8, Istanbul, and console summary output. Disabled by default — turn
+ * on with `tuffgal run --coverage`.
+ *
+ * Two stages:
+ *   1. `startForPage(page)` — call after every `newPage` so coverage spans
+ *      every navigation the story performs.
+ *   2. `stopForPage(page)` — call before `context.close()` to drain the
+ *      entries into the aggregate.
+ *
+ * `generate()` runs once at end-of-run.
+ */
+export class CoverageCollector {
+  private mcr: CoverageReportInstance | undefined;
+  private readonly outputDir: string;
+  private initialised = false;
+
+  constructor(reportDir: string) {
+    this.outputDir = join(reportDir, 'coverage');
+  }
+
+  private async ensureInitialised(): Promise<void> {
+    if (this.initialised) return;
+    const monocartModule = await import('monocart-coverage-reports');
+    // `export = MCR` (CommonJS) becomes `.default` under ESM interop.
+    const createReport = monocartModule.default;
+    this.mcr = createReport({
+      name: 'tuffgal coverage',
+      outputDir: this.outputDir,
+      reports: ['v8', 'console-summary'],
+    });
+    await this.mcr.cleanCache();
+    this.initialised = true;
+  }
+
+  async startForPage(page: Page): Promise<void> {
+    await this.ensureInitialised();
+    await Promise.all([
+      page.coverage.startJSCoverage(PLAYWRIGHT_COVERAGE_OPTIONS),
+      page.coverage.startCSSCoverage(PLAYWRIGHT_COVERAGE_OPTIONS),
+    ]);
+  }
+
+  async stopForPage(page: Page): Promise<void> {
+    if (!this.mcr) return;
+    try {
+      const [js, css] = await Promise.all([
+        page.coverage.stopJSCoverage(),
+        page.coverage.stopCSSCoverage(),
+      ]);
+      await this.mcr.add([...js, ...css]);
+    } catch (error) {
+      // A page may already be closing when we stop — best effort, do not
+      // fail the run because we missed coverage on one tab.
+      process.stderr.write(
+        `coverage: stopForPage failed — ${error instanceof Error ? error.message : String(error)}\n`,
+      );
+    }
+  }
+
+  async generate(): Promise<string> {
+    if (!this.mcr) return this.outputDir;
+    await this.mcr.generate();
+    return this.outputDir;
+  }
+}

package/src/runner/interpolate.ts

@@ -0,0 +1,36 @@
+import type { Hint } from '../schema/action.ts';
+
+/**
+ * Expands `${name}` placeholders in a string from a parameter map. Throws when
+ * a placeholder has no matching parameter so a typo in a story or action fails
+ * loudly instead of silently leaving a literal `${url}` in a URL field.
+ */
+export function interpolate(
+  template: string,
+  parameters: Record<string, string>,
+): string {
+  return template.replace(/\$\{([a-zA-Z0-9_]+)\}/g, (_match, name: string) => {
+    const value = parameters[name];
+    if (value === undefined) {
+      throw new Error(`Missing parameter "${name}" for template "${template}"`);
+    }
+    return value;
+  });
+}
+
+/**
+ * Returns a new Hint with `text` and `selector` interpolated against the
+ * supplied parameter map. `role` and `position` are enums and pass through.
+ */
+export function interpolateHint(
+  hint: Hint,
+  parameters: Record<string, string>,
+): Hint {
+  return {
+    ...hint,
+    text: hint.text ? interpolate(hint.text, parameters) : hint.text,
+    selector: hint.selector
+      ? interpolate(hint.selector, parameters)
+      : hint.selector,
+  };
+}

package/src/runner/resolveLocator.ts

@@ -0,0 +1,47 @@
+import type { Locator, Page } from 'playwright';
+import type { Hint } from '../schema/action.ts';
+
+/**
+ * Resolves a hint to a Playwright Locator using a precedence chain. The MVP
+ * intentionally stays literal — no LLM fallback. When this throws,
+ * `runAction` records `LocatorNotFound` and the parent story fails fast.
+ *
+ * Order:
+ *  1. `role + text`  — strongest ARIA contract.
+ *  2. `role` alone   — when no name is supplied.
+ *  3. `selector`     — explicit escape hatch / cached resolution.
+ *  4. `text` alone   — last resort because text-only locators are noisy.
+ */
+export function resolveLocator(page: Page, hint: Hint): Locator {
+  if (hint.role && hint.text) {
+    return page.getByRole(hint.role, { name: hint.text, exact: false });
+  }
+  if (hint.role) {
+    return page.getByRole(hint.role);
+  }
+  if (hint.selector) {
+    return page.locator(hint.selector);
+  }
+  if (hint.text) {
+    return page.getByText(hint.text, { exact: false });
+  }
+  throw new LocatorHintError(
+    'hint has no role, selector, or text — cannot resolve',
+  );
+}
+
+export class LocatorHintError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'LocatorHintError';
+  }
+}
+
+export class LocatorNotFoundError extends Error {
+  override readonly cause?: unknown;
+  constructor(hint: Hint, cause?: unknown) {
+    super(`No element matched hint ${JSON.stringify(hint)}`);
+    this.name = 'LocatorNotFoundError';
+    this.cause = cause;
+  }
+}

package/src/runner/run.ts

@@ -0,0 +1,177 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { cpus } from 'node:os';
+import { join } from 'node:path';
+import type { ResolvedConfig } from '../config.ts';
+import type { Action } from '../schema/action.ts';
+import type { RunResult, StoryResult } from '../schema/result.ts';
+import { loadActions, loadStories } from '../schema/load.ts';
+import { writeReport } from '../reporter/writeReport.ts';
+import { computeFlowCoverage } from '../coverage/flows.ts';
+import { computeScreenCoverage } from '../coverage/screens.ts';
+import { resetDatabase } from './bridges/database.ts';
+import {
+  startManagedDevServers,
+  type ManagedDevServers,
+} from './bridges/devServers.ts';
+import { CoverageCollector } from './coverage.ts';
+import { runStory } from './runStory.ts';
+import {
+  buildSchedule,
+  drainSchedule,
+  type ScheduledStory,
+} from './scheduler.ts';
+
+export interface RunCliOptions {
+  storyFilter?: string;
+  headed: boolean;
+  workers?: number;
+  manageServers?: boolean;
+  coverage?: boolean;
+}
+
+const HEARTBEAT_FILE = '.heartbeat';
+
+/**
+ * Loads every action and story from the configured paths, resets the
+ * consumer-supplied test database, schedules stories according to their
+ * needs/produces DAG, and drives execution across a fixed worker pool.
+ * Returns the aggregate `RunResult` so the CLI can set the process exit
+ * code.
+ */
+export async function runAll(
+  config: ResolvedConfig,
+  options: RunCliOptions,
+): Promise<RunResult> {
+  const startedAt = new Date();
+  let managedServers: ManagedDevServers | undefined;
+  if (options.manageServers) {
+    managedServers = await startManagedDevServers(config);
+  }
+  // Heartbeat is opportunistic. A sibling supervisor process can poll this
+  // file to know whether the dev servers are still in active use.
+  await touchHeartbeat(config);
+  const coverage = options.coverage
+    ? new CoverageCollector(config.paths.report)
+    : undefined;
+  try {
+    if (config.database?.reset) {
+      process.stdout.write('Resetting test database…\n');
+      await resetDatabase(config);
+    }
+    const actions = await loadActions(config.paths.actions);
+    const allStories = await loadStories(config.paths.stories);
+    const scheduled = buildSchedule(allStories);
+    const subset = options.storyFilter
+      ? scheduled.filter((item) => matchesFilter(item, options.storyFilter!))
+      : scheduled;
+
+    if (options.storyFilter && subset.length === 0) {
+      throw new Error(`No story matched filter "${options.storyFilter}"`);
+    }
+
+    const workerCount = resolveWorkerCount(config, options.workers);
+    process.stdout.write(
+      `Scheduling ${subset.length} stories on ${workerCount} worker${workerCount === 1 ? '' : 's'}.\n`,
+    );
+
+    const results = await drainSchedule(
+      subset,
+      workerCount,
+      (item) => runScheduledStory(item, actions, config, options.headed, coverage),
+      (item) => process.stdout.write(`▶ ${item.file}\n`),
+      (item, result) =>
+        process.stdout.write(
+          `  ${result.status.toUpperCase()} ${item.file} (${result.actions.length} actions, ${result.durationMs} ms)\n`,
+        ),
+    );
+
+    const finishedAt = new Date();
+    const [screens, flows] = await Promise.all([
+      computeScreenCoverage(config.paths.actions, config.paths.baselines),
+      computeFlowCoverage(config.flowInventory, allStories),
+    ]);
+    const runResult: RunResult = {
+      startedAt: startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
+      durationMs: finishedAt.getTime() - startedAt.getTime(),
+      totals: summarise(results),
+      customCoverage: { screens, flows },
+      stories: results,
+    };
+    const reportPath = await writeReport(config.paths.report, runResult);
+    process.stdout.write(`\nReport: ${reportPath}\n`);
+    if (coverage) {
+      const coveragePath = await coverage.generate();
+      process.stdout.write(`Coverage: ${coveragePath}\n`);
+    }
+    return runResult;
+  } finally {
+    if (managedServers) {
+      await managedServers.stop();
+    }
+  }
+}
+
+function runScheduledStory(
+  item: ScheduledStory,
+  actions: Map<string, Action>,
+  config: ResolvedConfig,
+  headed: boolean,
+  coverage: CoverageCollector | undefined,
+): Promise<StoryResult> {
+  return runStory({
+    story: item.story,
+    file: item.file,
+    needs: item.needs,
+    produces: item.produces,
+    actions,
+    config,
+    headed,
+    coverage,
+  });
+}
+
+function matchesFilter(item: ScheduledStory, filter: string): boolean {
+  return (
+    item.file === filter ||
+    item.file === `${filter}.json` ||
+    item.story.story === filter
+  );
+}
+
+function resolveWorkerCount(
+  config: ResolvedConfig,
+  requested: number | undefined,
+): number {
+  if (requested && requested > 0) {
+    return requested;
+  }
+  if (config.workers && config.workers > 0) {
+    return config.workers;
+  }
+  const half = Math.floor(cpus().length / 2);
+  return Math.max(1, Math.min(half, 4));
+}
+
+async function touchHeartbeat(config: ResolvedConfig): Promise<void> {
+  try {
+    await mkdir(config.paths.report, { recursive: true });
+    await writeFile(
+      join(config.paths.report, HEARTBEAT_FILE),
+      new Date().toISOString(),
+      'utf8',
+    );
+  } catch {
+    // The heartbeat is opportunistic — a missing parent dir or a disk
+    // hiccup should not fail the entire run.
+  }
+}
+
+function summarise(results: StoryResult[]): RunResult['totals'] {
+  return {
+    stories: results.length,
+    passed: results.filter((result) => result.status === 'pass').length,
+    changed: results.filter((result) => result.status === 'changed').length,
+    failed: results.filter((result) => result.status === 'failed').length,
+  };
+}