@rettangoli/vt 0.0.14 → 1.0.0-rc2

package/src/selector-filter.js

@@ -0,0 +1,139 @@
+import path from "path";
+import { stripViewportSuffix } from "./viewport.js";
+
+function toList(value) {
+  if (value === undefined || value === null) return [];
+  if (Array.isArray(value)) return value;
+  return [value];
+}
+
+function normalizePathValue(value) {
+  return String(value)
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "")
+    .replace(/\/+$/, "");
+}
+
+function normalizeItemKey(value) {
+  const normalized = normalizePathValue(value);
+  return normalized.replace(/\.(html?|ya?ml|md)$/i, "");
+}
+
+export function normalizeSelectors(raw = {}) {
+  const folders = toList(raw.folder)
+    .map(normalizePathValue)
+    .filter((item) => item.length > 0);
+  const groups = toList(raw.group)
+    .map((item) => String(item).trim().toLowerCase())
+    .filter((item) => item.length > 0);
+  const items = toList(raw.item)
+    .map(normalizeItemKey)
+    .filter((item) => item.length > 0);
+
+  return {
+    folders: [...new Set(folders)],
+    groups: [...new Set(groups)],
+    items: [...new Set(items)],
+  };
+}
+
+export function hasSelectors(selectors) {
+  return (
+    selectors.folders.length > 0
+    || selectors.groups.length > 0
+    || selectors.items.length > 0
+  );
+}
+
+function matchesFolderPrefix(filePath, folderPrefix) {
+  return filePath === folderPrefix || filePath.startsWith(`${folderPrefix}/`);
+}
+
+function resolveGroupFolders(configSections = [], groupSelectors = []) {
+  if (groupSelectors.length === 0) {
+    return [];
+  }
+
+  const groupFolderMap = new Map();
+  for (const section of configSections) {
+    if (section.type === "groupLabel" && Array.isArray(section.items)) {
+      for (const item of section.items) {
+        groupFolderMap.set(String(item.title).toLowerCase(), normalizePathValue(item.files));
+      }
+      continue;
+    }
+    if (section.files) {
+      groupFolderMap.set(String(section.title).toLowerCase(), normalizePathValue(section.files));
+    }
+  }
+
+  const missing = [];
+  const folders = [];
+  for (const selector of groupSelectors) {
+    const folder = groupFolderMap.get(selector);
+    if (!folder) {
+      missing.push(selector);
+      continue;
+    }
+    folders.push(folder);
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `Unknown group selector(s): ${missing.join(", ")}.`,
+    );
+  }
+  return [...new Set(folders)];
+}
+
+function toGeneratedFileItemKey(filePath) {
+  const normalized = normalizePathValue(filePath);
+  const ext = path.extname(normalized);
+  return normalized.slice(0, normalized.length - ext.length);
+}
+
+export function filterGeneratedFilesBySelectors(generatedFiles, selectors, configSections = []) {
+  if (!hasSelectors(selectors)) {
+    return generatedFiles;
+  }
+
+  const folderSelectors = [
+    ...selectors.folders,
+    ...resolveGroupFolders(configSections, selectors.groups),
+  ];
+
+  return generatedFiles.filter((file) => {
+    const normalizedPath = normalizePathValue(file.path);
+    const itemKey = toGeneratedFileItemKey(normalizedPath);
+
+    if (selectors.items.includes(itemKey)) {
+      return true;
+    }
+    return folderSelectors.some((folder) => matchesFolderPrefix(normalizedPath, folder));
+  });
+}
+
+function toScreenshotItemKey(relativeScreenshotPath) {
+  const normalized = normalizePathValue(relativeScreenshotPath).replace(/\.webp$/i, "");
+  const withoutOrdinal = normalized.replace(/-\d{1,3}$/i, "");
+  return stripViewportSuffix(withoutOrdinal);
+}
+
+export function filterRelativeScreenshotPathsBySelectors(relativePaths, selectors, configSections = []) {
+  if (!hasSelectors(selectors)) {
+    return relativePaths;
+  }
+
+  const folderSelectors = [
+    ...selectors.folders,
+    ...resolveGroupFolders(configSections, selectors.groups),
+  ];
+
+  return relativePaths.filter((relativePath) => {
+    const itemKey = toScreenshotItemKey(relativePath);
+    if (selectors.items.includes(itemKey)) {
+      return true;
+    }
+    return folderSelectors.some((folder) => matchesFolderPrefix(itemKey, folder));
+  });
+}

package/src/step-commands.js

@@ -0,0 +1,33 @@
+export const STEP_COMMANDS = Object.freeze([
+  "assert",
+  "blur",
+  "check",
+  "clear",
+  "click",
+  "customEvent",
+  "dblclick",
+  "focus",
+  "goto",
+  "hover",
+  "keypress",
+  "mouseDown",
+  "mouseUp",
+  "move",
+  "rclick",
+  "rightMouseDown",
+  "rightMouseUp",
+  "setViewport",
+  "screenshot",
+  "scroll",
+  "select",
+  "selectOption",
+  "uncheck",
+  "upload",
+  "wait",
+  "waitFor",
+  "write",
+]);
+
+export const BLOCK_COMMANDS = Object.freeze([
+  "select",
+]);

package/src/validation.js

@@ -0,0 +1,304 @@
+import { normalizeViewportField } from "./viewport.js";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function valueType(value) {
+  if (Array.isArray(value)) return "array";
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function validateOptionalString(value, path, options = {}) {
+  const { allowEmpty = false } = options;
+  if (value === undefined || value === null) {
+    return;
+  }
+  assert(typeof value === "string", `"${path}" must be a string, got ${valueType(value)}.`);
+  if (!allowEmpty) {
+    assert(value.trim().length > 0, `"${path}" cannot be empty.`);
+  }
+}
+
+function validateOptionalBoolean(value, path) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  assert(typeof value === "boolean", `"${path}" must be a boolean, got ${valueType(value)}.`);
+}
+
+function validateOptionalNumber(value, path, options = {}) {
+  const { integer = false, min, max } = options;
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  assert(
+    typeof value === "number" && Number.isFinite(value),
+    `"${path}" must be a finite number, got ${valueType(value)} (${String(value)}).`,
+  );
+
+  if (integer) {
+    assert(Number.isInteger(value), `"${path}" must be an integer, got ${value}.`);
+  }
+  if (min !== undefined) {
+    assert(value >= min, `"${path}" must be >= ${min}, got ${value}.`);
+  }
+  if (max !== undefined) {
+    assert(value <= max, `"${path}" must be <= ${max}, got ${value}.`);
+  }
+}
+
+function validateOptionalEnum(value, path, allowedValues) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  validateOptionalString(value, path);
+  assert(
+    allowedValues.includes(value),
+    `"${path}" must be one of: ${allowedValues.join(", ")}. Got "${value}".`,
+  );
+}
+
+function validateCaptureConfig(captureConfig, sourcePath) {
+  if (captureConfig === undefined || captureConfig === null) {
+    return;
+  }
+
+  assert(
+    isPlainObject(captureConfig),
+    `Invalid VT config in ${sourcePath}: "vt.capture" must be an object when provided, got ${valueType(captureConfig)}.`,
+  );
+  assert(
+    Object.keys(captureConfig).length === 0,
+    `Invalid VT config in ${sourcePath}: "vt.capture" is internal and no longer user-configurable. Remove this section.`,
+  );
+}
+
+const LEGACY_CAPTURE_FIELDS = {
+  screenshotWaitTime: true,
+  waitSelector: true,
+  waitStrategy: true,
+  workerCount: true,
+  isolationMode: true,
+  navigationTimeout: true,
+  readyTimeout: true,
+  screenshotTimeout: true,
+  maxRetries: true,
+  recycleEvery: true,
+  metricsPath: true,
+  headless: true,
+};
+
+const SECTION_PAGE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+function assertNoLegacyCaptureFields(vtConfig, sourcePath) {
+  for (const legacyField of Object.keys(LEGACY_CAPTURE_FIELDS)) {
+    if (Object.prototype.hasOwnProperty.call(vtConfig, legacyField)) {
+      throw new Error(
+        `Invalid VT config in ${sourcePath}: "vt.${legacyField}" was removed and is no longer user-configurable.`,
+      );
+    }
+  }
+}
+
+function assertValidSectionPageKey(value, path) {
+  assert(
+    typeof value === "string" && value.trim().length > 0,
+    `"${path}" is required.`,
+  );
+  assert(
+    SECTION_PAGE_KEY_PATTERN.test(value),
+    `"${path}" must contain only letters, numbers, "-" or "_", and cannot include spaces.`,
+  );
+}
+
+function validateSection(section, index) {
+  const sectionPath = `vt.sections[${index}]`;
+  assert(isPlainObject(section), `"${sectionPath}" must be an object, got ${valueType(section)}.`);
+
+  validateOptionalString(section.title, `${sectionPath}.title`);
+  assert(typeof section.title === "string" && section.title.trim().length > 0, `"${sectionPath}.title" is required.`);
+  validateOptionalString(section.description, `${sectionPath}.description`, { allowEmpty: true });
+
+  if (section.type !== undefined) {
+    validateOptionalString(section.type, `${sectionPath}.type`);
+    assert(
+      section.type === "groupLabel",
+      `"${sectionPath}.type" must be "groupLabel" when provided, got "${section.type}".`,
+    );
+  }
+
+  if (section.type === "groupLabel") {
+    assert(Array.isArray(section.items), `"${sectionPath}.items" must be an array for groupLabel sections.`);
+    assert(section.items.length > 0, `"${sectionPath}.items" cannot be empty.`);
+
+    section.items.forEach((item, itemIndex) => {
+      const itemPath = `${sectionPath}.items[${itemIndex}]`;
+      assert(isPlainObject(item), `"${itemPath}" must be an object, got ${valueType(item)}.`);
+      validateOptionalString(item.title, `${itemPath}.title`);
+      validateOptionalString(item.files, `${itemPath}.files`);
+      validateOptionalString(item.description, `${itemPath}.description`, { allowEmpty: true });
+
+      assert(typeof item.title === "string" && item.title.trim().length > 0, `"${itemPath}.title" is required.`);
+      assert(typeof item.files === "string" && item.files.trim().length > 0, `"${itemPath}.files" is required.`);
+      assertValidSectionPageKey(item.title, `${itemPath}.title`);
+    });
+    return;
+  }
+
+  validateOptionalString(section.files, `${sectionPath}.files`);
+  assert(typeof section.files === "string" && section.files.trim().length > 0, `"${sectionPath}.files" is required.`);
+  assertValidSectionPageKey(section.title, `${sectionPath}.title`);
+}
+
+function collectSectionPageKeys(vtConfig) {
+  const keys = [];
+  vtConfig.sections.forEach((section) => {
+    if (section.type === "groupLabel" && Array.isArray(section.items)) {
+      section.items.forEach((item) => keys.push(item.title));
+      return;
+    }
+    if (section.files) {
+      keys.push(section.title);
+    }
+  });
+  return keys;
+}
+
+function assertUniqueSectionPageKeys(vtConfig, sourcePath) {
+  const seen = new Map();
+  const pageKeys = collectSectionPageKeys(vtConfig);
+
+  pageKeys.forEach((pageKey) => {
+    const canonicalKey = pageKey.toLowerCase();
+    const existing = seen.get(canonicalKey);
+    if (existing) {
+      throw new Error(
+        `Invalid VT config in ${sourcePath}: section page key "${pageKey}" conflicts with "${existing}". Page keys must be unique (case-insensitive).`,
+      );
+    }
+    seen.set(canonicalKey, pageKey);
+  });
+}
+
+function validateStepObject(step, stepPath) {
+  assert(isPlainObject(step), `"${stepPath}" must be an object with one key or a string.`);
+  const keys = Object.keys(step);
+  assert(
+    keys.length === 1,
+    `"${stepPath}" must have exactly one key (e.g. "select my-id"), got ${keys.length}.`,
+  );
+
+  const [blockCommand] = keys;
+  validateOptionalString(blockCommand, `${stepPath} key`);
+
+  const nestedSteps = step[blockCommand];
+  assert(Array.isArray(nestedSteps), `"${stepPath}.${blockCommand}" must be an array of step strings.`);
+  nestedSteps.forEach((nestedStep, nestedIndex) => {
+    const nestedPath = `${stepPath}.${blockCommand}[${nestedIndex}]`;
+    assert(typeof nestedStep === "string", `"${nestedPath}" must be a string step command.`);
+    assert(nestedStep.trim().length > 0, `"${nestedPath}" cannot be empty.`);
+  });
+}
+
+export function validateVtConfig(vtConfig, sourcePath = "rettangoli.config.yaml") {
+  assert(
+    isPlainObject(vtConfig),
+    `Invalid VT config in ${sourcePath}: "vt" must be an object, got ${valueType(vtConfig)}.`,
+  );
+
+  validateOptionalString(vtConfig.path, "vt.path");
+  validateOptionalString(vtConfig.url, "vt.url");
+  validateOptionalString(vtConfig.name, "vt.name", { allowEmpty: true });
+  validateOptionalString(vtConfig.description, "vt.description", { allowEmpty: true });
+  validateOptionalString(vtConfig.compareMethod, "vt.compareMethod");
+  validateOptionalBoolean(vtConfig.skipScreenshots, "vt.skipScreenshots");
+  validateOptionalNumber(vtConfig.port, "vt.port", { integer: true, min: 1, max: 65535 });
+  validateOptionalNumber(vtConfig.concurrency, "vt.concurrency", { integer: true, min: 1 });
+  validateOptionalNumber(vtConfig.timeout, "vt.timeout", { integer: true, min: 1 });
+  validateOptionalString(vtConfig.waitEvent, "vt.waitEvent");
+  normalizeViewportField(vtConfig.viewport, "vt.viewport");
+  validateOptionalNumber(vtConfig.colorThreshold, "vt.colorThreshold", { min: 0, max: 1 });
+  validateOptionalNumber(vtConfig.diffThreshold, "vt.diffThreshold", { min: 0, max: 100 });
+  assertNoLegacyCaptureFields(vtConfig, sourcePath);
+  validateCaptureConfig(vtConfig.capture, sourcePath);
+
+  assert(Array.isArray(vtConfig.sections), `Invalid VT config in ${sourcePath}: "vt.sections" is required and must be an array.`);
+  assert(vtConfig.sections.length > 0, `Invalid VT config in ${sourcePath}: "vt.sections" cannot be empty.`);
+  vtConfig.sections.forEach(validateSection);
+  assertUniqueSectionPageKeys(vtConfig, sourcePath);
+
+  return vtConfig;
+}
+
+export function validateFrontMatter(frontMatter, specPath) {
+  if (frontMatter === null || frontMatter === undefined) {
+    return;
+  }
+
+  assert(
+    isPlainObject(frontMatter),
+    `Invalid front matter in "${specPath}": expected an object, got ${valueType(frontMatter)}.`,
+  );
+
+  validateOptionalString(frontMatter.title, `${specPath}: frontMatter.title`, { allowEmpty: true });
+  validateOptionalString(frontMatter.description, `${specPath}: frontMatter.description`, { allowEmpty: true });
+  validateOptionalString(frontMatter.template, `${specPath}: frontMatter.template`);
+  validateOptionalString(frontMatter.url, `${specPath}: frontMatter.url`);
+  validateOptionalString(frontMatter.waitEvent, `${specPath}: frontMatter.waitEvent`);
+  validateOptionalString(frontMatter.waitSelector, `${specPath}: frontMatter.waitSelector`);
+  normalizeViewportField(frontMatter.viewport, `${specPath}: frontMatter.viewport`);
+  validateOptionalEnum(
+    frontMatter.waitStrategy,
+    `${specPath}: frontMatter.waitStrategy`,
+    ["networkidle", "load", "event", "selector"],
+  );
+  validateOptionalBoolean(frontMatter.skipScreenshot, `${specPath}: frontMatter.skipScreenshot`);
+
+  if (frontMatter.waitStrategy === "event") {
+    assert(
+      typeof frontMatter.waitEvent === "string" && frontMatter.waitEvent.trim().length > 0,
+      `"${specPath}: frontMatter.waitEvent" is required when waitStrategy is "event".`,
+    );
+  }
+  if (frontMatter.waitStrategy === "selector") {
+    assert(
+      typeof frontMatter.waitSelector === "string" && frontMatter.waitSelector.trim().length > 0,
+      `"${specPath}: frontMatter.waitSelector" is required when waitStrategy is "selector".`,
+    );
+  }
+
+  if (frontMatter.specs !== undefined) {
+    assert(Array.isArray(frontMatter.specs), `"${specPath}: frontMatter.specs" must be an array of strings.`);
+    frontMatter.specs.forEach((spec, index) => {
+      const specPathField = `${specPath}: frontMatter.specs[${index}]`;
+      assert(typeof spec === "string", `"${specPathField}" must be a string.`);
+      assert(spec.trim().length > 0, `"${specPathField}" cannot be empty.`);
+    });
+  }
+
+  if (frontMatter.steps !== undefined) {
+    assert(Array.isArray(frontMatter.steps), `"${specPath}: frontMatter.steps" must be an array.`);
+    frontMatter.steps.forEach((step, index) => {
+      const stepPath = `${specPath}: frontMatter.steps[${index}]`;
+      if (typeof step === "string") {
+        assert(step.trim().length > 0, `"${stepPath}" cannot be empty.`);
+        return;
+      }
+      validateStepObject(step, stepPath);
+    });
+  }
+}
+
+export function validateFiniteNumber(value, fieldName, options = {}) {
+  validateOptionalNumber(value, fieldName, options);
+  return value;
+}

package/src/viewport.js

@@ -0,0 +1,99 @@
+const VIEWPORT_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+export const DEFAULT_VIEWPORT = Object.freeze({
+  width: 1280,
+  height: 720,
+});
+
+function valueType(value) {
+  if (Array.isArray(value)) return "array";
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function validateViewportEntry(entry, path) {
+  assert(
+    entry !== null && typeof entry === "object" && !Array.isArray(entry),
+    `"${path}" must be an object, got ${valueType(entry)}.`,
+  );
+
+  assert(
+    typeof entry.id === "string" && entry.id.trim().length > 0,
+    `"${path}.id" is required and must be a non-empty string.`,
+  );
+  assert(
+    VIEWPORT_ID_PATTERN.test(entry.id),
+    `"${path}.id" must contain only letters, numbers, "-" or "_".`,
+  );
+  assert(
+    typeof entry.width === "number" && Number.isInteger(entry.width) && entry.width >= 1,
+    `"${path}.width" must be an integer >= 1.`,
+  );
+  assert(
+    typeof entry.height === "number" && Number.isInteger(entry.height) && entry.height >= 1,
+    `"${path}.height" must be an integer >= 1.`,
+  );
+
+  return {
+    id: entry.id,
+    width: entry.width,
+    height: entry.height,
+  };
+}
+
+export function normalizeViewportField(rawViewport, path = "viewport") {
+  if (rawViewport === undefined || rawViewport === null) {
+    return undefined;
+  }
+
+  const rawEntries = Array.isArray(rawViewport) ? rawViewport : [rawViewport];
+  assert(rawEntries.length > 0, `"${path}" cannot be an empty array.`);
+
+  const entries = rawEntries.map((entry, index) =>
+    validateViewportEntry(entry, `${path}[${index}]`),
+  );
+
+  const seen = new Map();
+  entries.forEach((entry, index) => {
+    const canonicalId = entry.id.toLowerCase();
+    const existingIndex = seen.get(canonicalId);
+    assert(
+      existingIndex === undefined,
+      `"${path}[${index}].id" duplicates "${path}[${existingIndex}].id" (case-insensitive).`,
+    );
+    seen.set(canonicalId, index);
+  });
+
+  return entries;
+}
+
+export function resolveViewports(frontMatterViewport, configViewport) {
+  const selected = frontMatterViewport ?? configViewport;
+  if (selected === undefined || selected === null) {
+    return [
+      {
+        id: null,
+        width: DEFAULT_VIEWPORT.width,
+        height: DEFAULT_VIEWPORT.height,
+      },
+    ];
+  }
+  return normalizeViewportField(selected, "viewport");
+}
+
+export function appendViewportToBaseName(baseName, viewportId) {
+  if (!viewportId) {
+    return baseName;
+  }
+  return `${baseName}--${viewportId}`;
+}
+
+export function stripViewportSuffix(itemKey) {
+  return itemKey.replace(/--[A-Za-z0-9_-]+$/, "");
+}

package/docker/Dockerfile

@@ -1,21 +0,0 @@
-FROM mcr.microsoft.com/playwright:v1.57.0-noble
-
-# Install dependencies for Bun
-RUN apt-get update && apt-get install -y unzip curl && rm -rf /var/lib/apt/lists/*
-
-# Install Bun to system location directly (latest version)
-RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash
-
-# Install rtgl globally
-RUN bun install -g rtgl@0.0.36
-
-# Copy bun global packages to /usr/local/lib/rtgl (accessible to all users)
-RUN mkdir -p /usr/local/lib/rtgl && \
-    cp -r /root/.bun/install/global /usr/local/lib/rtgl/ && \
-    chmod -R a+rx /usr/local/lib/rtgl/
-
-# Create wrapper script that uses copied packages
-RUN echo "#!/bin/sh" > /usr/local/bin/rtgl && \
-    echo "BUN_INSTALL_LOCKFILE=/usr/local/lib/rtgl/bun/install/cache/bun-install.lock" >> /usr/local/bin/rtgl && \
-    echo "exec bun /usr/local/lib/rtgl/global/node_modules/rtgl/cli.js \"\$@\"" >> /usr/local/bin/rtgl && \
-    chmod +x /usr/local/bin/rtgl

package/docker/build-and-push.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-IMAGE_NAME="playwright-v1.57.0-rtgl-v0.0.36"
-REGISTRY="${REGISTRY:-docker.io}"
-REPO="${REPO:-han4wluc/rtgl}"
-
-FULL_TAG="$REGISTRY/$REPO:$IMAGE_NAME"
-
-docker build -t "$IMAGE_NAME" "$SCRIPT_DIR"
-echo "Built image: $IMAGE_NAME"
-
-docker tag "$IMAGE_NAME" "$FULL_TAG"
-docker push "$FULL_TAG"
-echo "Pushed: $FULL_TAG"