@rettangoli/vt 0.0.14 → 1.0.0-rc12

package/src/capture/spec-loader.js

@@ -0,0 +1,119 @@
+import { appendViewportToBaseName, resolveViewports } from "../viewport.js";
+
+const removeExtension = (filePath) => filePath.replace(/\.[^/.]+$/, "");
+
+const toHtmlPath = (filePath) => {
+  if (filePath.endsWith(".html")) {
+    return filePath;
+  }
+  return `${removeExtension(filePath)}.html`;
+};
+
+function normalizePathForUrl(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+
+function toAbsoluteUrl(rawUrl, serverUrl) {
+  if (rawUrl.startsWith("http://") || rawUrl.startsWith("https://")) {
+    return rawUrl;
+  }
+  return new URL(rawUrl, serverUrl).href;
+}
+
+function resolveWaitStrategy(frontMatter, defaults) {
+  if (frontMatter.waitStrategy) {
+    return frontMatter.waitStrategy;
+  }
+  if (frontMatter.waitEvent) {
+    return "event";
+  }
+  if (frontMatter.waitSelector) {
+    return "selector";
+  }
+  if (defaults.waitStrategy) {
+    return defaults.waitStrategy;
+  }
+  if (defaults.waitEvent) {
+    return "event";
+  }
+  if (defaults.waitSelector) {
+    return "selector";
+  }
+  return "networkidle";
+}
+
+function estimateTaskCost(steps, resolvedWaitStrategy) {
+  const strategyBase = {
+    networkidle: 30,
+    load: 10,
+    event: 20,
+    selector: 15,
+  };
+  const stepCost = Array.isArray(steps) ? steps.length * 25 : 0;
+  return 100 + stepCost + (strategyBase[resolvedWaitStrategy] ?? 0);
+}
+
+export function createCaptureTasks(generatedFiles, options) {
+  const {
+    serverUrl,
+    configUrl,
+    waitEvent,
+    waitSelector,
+    waitStrategy,
+    viewport,
+  } = options;
+
+  const tasks = [];
+  let taskIndex = 0;
+
+  generatedFiles.forEach((file, fileIndex) => {
+    const frontMatter = file.frontMatter || {};
+    const normalizedPath = normalizePathForUrl(file.path);
+    const constructedUrl = toHtmlPath(`${serverUrl}/candidate/${normalizedPath}`);
+    const resolvedConfigUrl = configUrl ? toAbsoluteUrl(configUrl, serverUrl) : null;
+    const urlResolutionBase = resolvedConfigUrl || serverUrl;
+    const rawUrl = frontMatter.url ?? resolvedConfigUrl ?? constructedUrl;
+    const url = toAbsoluteUrl(rawUrl, urlResolutionBase);
+    const resolvedWaitEvent = frontMatter.waitEvent ?? waitEvent;
+    const resolvedWaitSelector = frontMatter.waitSelector ?? waitSelector;
+
+    const resolvedWaitStrategy = resolveWaitStrategy(frontMatter, {
+      waitEvent,
+      waitSelector,
+      waitStrategy,
+    });
+
+    const resolvedViewports = resolveViewports(frontMatter.viewport, viewport);
+    resolvedViewports.forEach((resolvedViewport) => {
+      const viewportId = resolvedViewport.id;
+      const task = {
+        id: `${fileIndex}:${file.path}:${viewportId ?? "default"}`,
+        index: taskIndex,
+        path: file.path,
+        url,
+        baseName: appendViewportToBaseName(removeExtension(file.path), viewportId),
+        frontMatter,
+        steps: frontMatter.steps || [],
+        waitStrategy: resolvedWaitStrategy,
+        estimatedCost: estimateTaskCost(frontMatter.steps || [], resolvedWaitStrategy),
+        viewport: {
+          id: viewportId,
+          width: resolvedViewport.width,
+          height: resolvedViewport.height,
+        },
+      };
+
+      if (resolvedWaitEvent !== undefined && resolvedWaitEvent !== null) {
+        task.waitEvent = resolvedWaitEvent;
+      }
+      if (resolvedWaitSelector !== undefined && resolvedWaitSelector !== null) {
+        task.waitSelector = resolvedWaitSelector;
+      }
+
+      tasks.push(task);
+      taskIndex += 1;
+    });
+  });
+
+  return tasks;
+}

package/src/capture/worker-plan.js

@@ -0,0 +1,66 @@
+import os from "node:os";
+
+const GIGABYTE = 1024 * 1024 * 1024;
+
+function normalizeFinite(value, fallback) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  return fallback;
+}
+
+function normalizeCpuCount(cpuCount) {
+  const normalized = Math.floor(normalizeFinite(cpuCount, 1));
+  return Math.max(1, normalized);
+}
+
+function normalizeMemoryGb(totalMemoryGb) {
+  const normalized = normalizeFinite(totalMemoryGb, 1);
+  return Math.max(0.1, normalized);
+}
+
+export function resolveWorkerPlan(requestedWorkers, system = {}) {
+  if (requestedWorkers !== undefined && requestedWorkers !== null) {
+    if (!Number.isInteger(requestedWorkers) || requestedWorkers < 1) {
+      throw new Error(
+        `workerCount must be an integer >= 1, got ${requestedWorkers}.`,
+      );
+    }
+  }
+
+  const cpuCount = normalizeCpuCount(
+    system.cpuCount ?? os.cpus()?.length ?? 1,
+  );
+  const cpuBound = Math.max(1, cpuCount - 1);
+
+  const totalMemoryGb = normalizeMemoryGb(
+    system.totalMemoryGb ?? (os.totalmem() / GIGABYTE),
+  );
+  const memoryBound = Math.max(1, Math.floor(totalMemoryGb / 1.5));
+  const autoWorkers = Math.max(1, Math.min(cpuBound, memoryBound, 16));
+
+  const baseAdaptivePolicy = {
+    cpuCount,
+    cpuBound,
+    totalMemoryGb: Number(totalMemoryGb.toFixed(2)),
+    memoryBound,
+  };
+
+  if (requestedWorkers !== undefined && requestedWorkers !== null) {
+    return {
+      workerCount: requestedWorkers,
+      adaptivePolicy: {
+        mode: "manual",
+        ...baseAdaptivePolicy,
+      },
+    };
+  }
+
+  return {
+    workerCount: autoWorkers,
+    adaptivePolicy: {
+      mode: "auto",
+      ...baseAdaptivePolicy,
+    },
+  };
+}

package/src/cli/generate-options.js

@@ -0,0 +1,94 @@
+import { join } from "node:path";
+import { validateFiniteNumber } from "../validation.js";
+import { normalizeSelectors } from "../selector-filter.js";
+
+export function resolveGenerateOptions(options = {}, configData = {}) {
+  const {
+    skipScreenshots: cliSkipScreenshots,
+    captureScreenshots,
+    vtPath: cliVtPath,
+    port: cliPort,
+    concurrency: cliConcurrency,
+    timeout: cliTimeout,
+    waitEvent: cliWaitEvent,
+    folder: cliFolder,
+    group: cliGroup,
+    item: cliItem,
+    headless: cliHeadless,
+    url: cliUrl,
+  } = options;
+
+  const waitEvent = cliWaitEvent ?? configData.waitEvent;
+  const timeout = cliTimeout ?? configData.timeout ?? 30000;
+  const selectors = normalizeSelectors({
+    folder: cliFolder,
+    group: cliGroup,
+    item: cliItem,
+  });
+
+  let resolvedSkipScreenshots;
+  if (captureScreenshots === true) {
+    resolvedSkipScreenshots = false;
+  } else if (captureScreenshots === false) {
+    resolvedSkipScreenshots = true;
+  } else if (cliSkipScreenshots === true) {
+    resolvedSkipScreenshots = true;
+  } else {
+    resolvedSkipScreenshots = configData.skipScreenshots ?? false;
+  }
+
+  const resolvedOptions = {
+    vtPath: cliVtPath ?? configData.path ?? "./vt",
+    skipScreenshots: resolvedSkipScreenshots,
+    port: cliPort ?? configData.port ?? 3001,
+    waitEvent,
+    headless: cliHeadless ?? true,
+    configUrl: cliUrl ?? configData.url,
+    ...(configData.viewport !== undefined ? { viewport: configData.viewport } : {}),
+    ...(configData.service?.start ? { serviceStart: configData.service.start } : {}),
+    selectors,
+
+    // Internal capture defaults (not user-configurable).
+    screenshotWaitTime: 0,
+    waitStrategy: waitEvent ? "event" : "load",
+    workerCount: cliConcurrency ?? configData.concurrency ?? undefined, // adaptive worker planning
+    isolationMode: "fast",
+    navigationTimeout: timeout,
+    readyTimeout: timeout,
+    screenshotTimeout: timeout,
+    maxRetries: 1,
+    recycleEvery: 25,
+    metricsPath: join(".rettangoli", "vt", "metrics.json"),
+  };
+
+  if (typeof resolvedOptions.vtPath !== "string" || resolvedOptions.vtPath.trim().length === 0) {
+    throw new Error(
+      `Invalid vtPath: expected a non-empty string, got "${resolvedOptions.vtPath}".`,
+    );
+  }
+  if (typeof resolvedOptions.skipScreenshots !== "boolean") {
+    throw new Error(
+      `Invalid skipScreenshots: expected a boolean, got ${typeof resolvedOptions.skipScreenshots}.`,
+    );
+  }
+  validateFiniteNumber(resolvedOptions.port, "port", { integer: true, min: 1, max: 65535 });
+  if (resolvedOptions.workerCount !== undefined && resolvedOptions.workerCount !== null) {
+    validateFiniteNumber(resolvedOptions.workerCount, "concurrency", { integer: true, min: 1 });
+  }
+  validateFiniteNumber(resolvedOptions.navigationTimeout, "timeout", { integer: true, min: 1 });
+  if (typeof resolvedOptions.headless !== "boolean") {
+    throw new Error(`Invalid headless: expected a boolean, got ${typeof resolvedOptions.headless}.`);
+  }
+  if (resolvedOptions.waitEvent !== undefined && resolvedOptions.waitEvent !== null) {
+    if (typeof resolvedOptions.waitEvent !== "string" || resolvedOptions.waitEvent.trim().length === 0) {
+      throw new Error(`Invalid waitEvent: expected a non-empty string, got ${typeof resolvedOptions.waitEvent}.`);
+    }
+  }
+  if (resolvedOptions.configUrl !== undefined && resolvedOptions.configUrl !== null) {
+    if (typeof resolvedOptions.configUrl !== "string" || resolvedOptions.configUrl.trim().length === 0) {
+      throw new Error(`Invalid url: expected a non-empty string, got ${typeof resolvedOptions.configUrl}.`);
+    }
+  }
+
+  return resolvedOptions;
+}

package/src/cli/generate.js

@@ -8,38 +8,98 @@ import {
   generateOverview,
   readYaml,
 } from "../common.js";
+import { validateVtConfig } from "../validation.js";
+import { resolveGenerateOptions } from "./generate-options.js";
+import {
+  filterGeneratedFilesBySelectors,
+  hasSelectors,
+} from "../selector-filter.js";
+import {
+  startManagedService,
+  stopManagedService,
+  waitForServiceReady,
+} from "./service-runtime.js";
 
 const libraryTemplatesPath = new URL("./templates", import.meta.url).pathname;
 const libraryStaticPath = new URL("./static", import.meta.url).pathname;
 
-/**
- * Main function that orchestrates the entire process
- */
-async function main(options) {
+export function buildCaptureOptions({
+  filesToScreenshot,
+  port,
+  candidatePath,
+  resolvedOptions,
+}) {
   const {
-    skipScreenshots = false,
-    vtPath = "./vt",
-    screenshotWaitTime = 0,
-    port = 3001,
+    workerCount,
+    screenshotWaitTime,
+    configUrl,
+    waitEvent,
+    waitSelector,
+    waitStrategy,
+    navigationTimeout,
+    readyTimeout,
+    screenshotTimeout,
+    maxRetries,
+    recycleEvery,
+    isolationMode,
+    metricsPath,
+    headless,
+    viewport,
+  } = resolvedOptions;
+
+  return {
+    generatedFiles: filesToScreenshot,
+    serverUrl: `http://localhost:${port}`,
+    screenshotsDir: candidatePath,
+    workerCount,
+    screenshotWaitTime,
+    configUrl,
     waitEvent,
-    concurrency = 12,
-  } = options;
+    waitSelector,
+    waitStrategy,
+    navigationTimeout,
+    readyTimeout,
+    screenshotTimeout,
+    maxRetries,
+    recycleEvery,
+    isolationMode,
+    metricsPath,
+    headless,
+    viewport,
+  };
+}
 
-  const specsPath = join(vtPath, "specs");
+/**
+ * Main function that orchestrates the entire process
+ */
+async function main(options = {}) {
   const mainConfigPath = "rettangoli.config.yaml";
   const siteOutputPath = join(".rettangoli", "vt", "_site");
-  const candidatePath = join(siteOutputPath, "candidate");
 
-  // Read VT config from main rettangoli.config.yaml
-  let configData = {};
+  let mainConfig;
   try {
-    const mainConfig = await readYaml(mainConfigPath);
-    configData = mainConfig.vt || {};
+    mainConfig = await readYaml(mainConfigPath);
   } catch (error) {
-    console.log("Main config file not found, using defaults");
+    throw new Error(`Unable to read "${mainConfigPath}": ${error.message}`, { cause: error });
+  }
+
+  const vtConfig = mainConfig?.vt;
+  if (!vtConfig) {
+    throw new Error(`Invalid "${mainConfigPath}": missing required "vt" section.`);
   }
 
-  const configUrl = configData.url;
+  const configData = validateVtConfig(vtConfig, mainConfigPath);
+  const resolvedOptions = resolveGenerateOptions(options, configData);
+  const {
+    vtPath,
+    skipScreenshots,
+    port,
+    configUrl,
+    serviceStart,
+  } = resolvedOptions;
+
+  const specsPath = join(vtPath, "specs");
+  const candidatePath = join(siteOutputPath, "candidate");
 
   // Clear candidate directory
   await rm(candidatePath, { recursive: true, force: true });
@@ -76,6 +136,16 @@ async function main(options) {
     templateConfig,
   );
 
+  const scopedFiles = filterGeneratedFilesBySelectors(
+    generatedFiles,
+    resolvedOptions.selectors,
+    configData.sections,
+  );
+  if (hasSelectors(resolvedOptions.selectors)) {
+    const excludedCount = generatedFiles.length - scopedFiles.length;
+    console.log(`Selector scope: ${scopedFiles.length} file(s) selected, ${excludedCount} excluded.`);
+  }
+
   // Generate overview page (includes all files, skipped or not)
   generateOverview(
     generatedFiles,
@@ -87,31 +157,51 @@ async function main(options) {
   // Take screenshots (only for non-skipped files)
   if (!skipScreenshots) {
     // Filter out files with skipScreenshot: true in frontmatter
-    const filesToScreenshot = generatedFiles.filter(
+    const filesToScreenshot = scopedFiles.filter(
       (file) => !file.frontMatter?.skipScreenshot
     );
 
-    const skippedCount = generatedFiles.length - filesToScreenshot.length;
+    const skippedCount = scopedFiles.length - filesToScreenshot.length;
     if (skippedCount > 0) {
       console.log(`Skipping screenshots for ${skippedCount} files`);
     }
+    if (filesToScreenshot.length === 0) {
+      console.log("No files selected for screenshot capture. Skipping Playwright run.");
+      return;
+    }
+
+    let server = null;
+    let managedService = null;
 
-    const server = configUrl ? null : startWebServer(siteOutputPath, vtPath, port);
     try {
+      if (serviceStart) {
+        if (!configUrl) {
+          throw new Error(
+            "vt.service.start requires vt.url (or --url) so VT can wait for readiness and capture against that URL.",
+          );
+        }
+        managedService = startManagedService({ command: serviceStart });
+        await waitForServiceReady({ url: configUrl, handle: managedService });
+      } else if (!configUrl) {
+        server = await startWebServer(siteOutputPath, vtPath, port);
+      }
+
       await takeScreenshots(
-        filesToScreenshot,
-        `http://localhost:${port}`,
-        candidatePath,
-        concurrency,
-        screenshotWaitTime,
-        configUrl,
-        waitEvent,
+        buildCaptureOptions({
+          filesToScreenshot,
+          port,
+          candidatePath,
+          resolvedOptions,
+        }),
       );
     } finally {
       if (server) {
         server.close();
         console.log("Server stopped");
       }
+      if (managedService) {
+        await stopManagedService(managedService);
+      }
     }
   }
 }

package/src/cli/index.js

@@ -1,9 +1,11 @@
 import generate from './generate.js';
+import screenshot from './screenshot.js';
 import report from './report.js';
 import accept from './accept.js';
 
 export {
   generate,
+  screenshot,
   report,
   accept,
-}
+}

package/src/cli/report-options.js

@@ -0,0 +1,43 @@
+import { validateFiniteNumber } from "../validation.js";
+import { normalizeSelectors } from "../selector-filter.js";
+
+const COMPARE_METHODS = ["pixelmatch", "md5"];
+
+export function resolveReportOptions(options = {}, configData = {}) {
+  const {
+    vtPath: cliVtPath,
+    compareMethod: cliCompareMethod,
+    colorThreshold: cliColorThreshold,
+    diffThreshold: cliDiffThreshold,
+    folder: cliFolder,
+    group: cliGroup,
+    item: cliItem,
+  } = options;
+
+  const selectors = normalizeSelectors({
+    folder: cliFolder,
+    group: cliGroup,
+    item: cliItem,
+  });
+
+  const resolvedOptions = {
+    vtPath: cliVtPath ?? configData.path ?? "./vt",
+    compareMethod: cliCompareMethod ?? configData.compareMethod ?? "pixelmatch",
+    colorThreshold: cliColorThreshold ?? configData.colorThreshold ?? 0.1,
+    diffThreshold: cliDiffThreshold ?? configData.diffThreshold ?? 0.3,
+    selectors,
+  };
+
+  if (typeof resolvedOptions.vtPath !== "string" || resolvedOptions.vtPath.trim().length === 0) {
+    throw new Error(`Invalid vtPath: expected a non-empty string, got "${resolvedOptions.vtPath}".`);
+  }
+  if (!COMPARE_METHODS.includes(resolvedOptions.compareMethod)) {
+    throw new Error(
+      `Invalid compareMethod "${resolvedOptions.compareMethod}". Expected "pixelmatch" or "md5".`,
+    );
+  }
+  validateFiniteNumber(resolvedOptions.colorThreshold, "colorThreshold", { min: 0, max: 1 });
+  validateFiniteNumber(resolvedOptions.diffThreshold, "diffThreshold", { min: 0, max: 100 });
+
+  return resolvedOptions;
+}