@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/e2e/svg-artifact-inspection.ts

@@ -0,0 +1,331 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+
+import type { Download, Page } from "@playwright/test";
+import {
+  TOOLCRAFT_FORBIDDEN_SVG_ELEMENTS,
+  TOOLCRAFT_SVG_BACKGROUND_ATTRIBUTE,
+  TOOLCRAFT_SVG_NAMESPACE,
+  TOOLCRAFT_SVG_NON_RENDERING_CONTAINERS,
+  TOOLCRAFT_SVG_PRODUCT_SCENE_ATTRIBUTE,
+  TOOLCRAFT_SVG_VECTOR_PRIMITIVES,
+} from "@repo/toolcraft-runtime";
+
+import type { ToolcraftSvgArtifactInspection } from "./export-artifact-helpers";
+
+export type ToolcraftInspectedSvgArtifact = Readonly<{
+  inspection: ToolcraftSvgArtifactInspection;
+  source: string;
+}>;
+
+const inspectedSvgArtifacts = new WeakSet<object>();
+
+export function assertToolcraftInspectedSvgArtifact(
+  inspection: ToolcraftSvgArtifactInspection,
+): void {
+  if (!inspectedSvgArtifacts.has(inspection)) {
+    throw new Error(
+      "Infinity SVG evidence requires an artifact from inspectToolcraftSvgDownload.",
+    );
+  }
+}
+
+export async function inspectToolcraftSvgDownload({
+  download,
+  page,
+}: Readonly<{
+  download: Download;
+  page: Page;
+}>): Promise<ToolcraftInspectedSvgArtifact> {
+  const fileName = download.suggestedFilename();
+  if (!fileName.toLowerCase().endsWith(".svg")) {
+    throw new Error("Downloaded SVG artifact must use the .svg extension.");
+  }
+  const downloadPath = await download.path();
+  if (!downloadPath) {
+    throw new Error("Playwright did not expose the downloaded SVG path.");
+  }
+  const bytes = await fs.readFile(downloadPath);
+  if (bytes.byteLength === 0) {
+    throw new Error("Downloaded SVG artifact is empty.");
+  }
+
+  let source: string;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error("Downloaded SVG artifact is not valid UTF-8.");
+  }
+
+  const decoded = await page.evaluate(
+    async ({
+      backgroundAttribute,
+      forbiddenNames,
+      namespace,
+      nonRenderingNames,
+      primitiveNames,
+      productSceneAttribute,
+      svgSource,
+    }) => {
+      const parsed = new DOMParser().parseFromString(
+        svgSource,
+        "image/svg+xml",
+      );
+      if (parsed.querySelector("parsererror")) {
+        throw new Error("Downloaded SVG artifact is not valid XML.");
+      }
+      if (parsed.doctype) {
+        throw new Error("Downloaded SVG artifact cannot contain a doctype.");
+      }
+      const root = parsed.documentElement;
+      if (root.localName !== "svg" || root.namespaceURI !== namespace) {
+        throw new Error(
+          "Downloaded SVG artifact must have a namespaced <svg> root.",
+        );
+      }
+
+      const parseDimension = (name: "height" | "width"): number => {
+        const raw = root.getAttribute(name)?.trim() ?? "";
+        if (!/^(?:\d+\.?\d*|\.\d+)$/u.test(raw)) {
+          throw new Error(`Downloaded SVG artifact needs numeric ${name}.`);
+        }
+        const value = Number(raw);
+        if (!Number.isFinite(value) || value <= 0) {
+          throw new Error(`Downloaded SVG artifact needs positive ${name}.`);
+        }
+        return value;
+      };
+      const width = parseDimension("width");
+      const height = parseDimension("height");
+      const viewBox = (root.getAttribute("viewBox") ?? "")
+        .trim()
+        .split(/[\s,]+/u)
+        .map(Number);
+      if (
+        viewBox.length !== 4 ||
+        viewBox.some((value) => !Number.isFinite(value)) ||
+        Number(viewBox[2]) <= 0 ||
+        Number(viewBox[3]) <= 0 ||
+        Number(viewBox[2]) !== width ||
+        Number(viewBox[3]) !== height
+      ) {
+        throw new Error(
+          "Downloaded SVG artifact needs a coherent positive viewBox.",
+        );
+      }
+
+      const productScenes = Array.from(
+        root.querySelectorAll(`[${productSceneAttribute}]`),
+      );
+      const productScene = productScenes[0] ?? null;
+      if (
+        productScenes.length !== 1 ||
+        productScene?.localName !== "g" ||
+        productScene.getAttribute(productSceneAttribute) !== "true" ||
+        !productScene.parentElement?.isSameNode(root)
+      ) {
+        throw new Error(
+          "Downloaded SVG artifact needs one runtime-owned product scene.",
+        );
+      }
+
+      const backgrounds = Array.from(
+        root.querySelectorAll(`[${backgroundAttribute}]`),
+      );
+      if (backgrounds.length > 1) {
+        throw new Error("Downloaded SVG artifact has duplicate runtime backgrounds.");
+      }
+      const background = backgrounds[0] ?? null;
+      let backgroundColor: string | null = null;
+      if (background) {
+        const backgroundFrame = ["x", "y", "width", "height"].map((name) =>
+          Number(background.getAttribute(name)),
+        );
+        if (
+          background.getAttribute(backgroundAttribute) !== "true" ||
+          background.localName !== "rect" ||
+          !background.parentElement?.isSameNode(root) ||
+          root.children[0] !== background ||
+          backgroundFrame.some((value) => !Number.isFinite(value)) ||
+          backgroundFrame.some((value, index) => value !== viewBox[index])
+        ) {
+          throw new Error(
+            "Downloaded SVG artifact has an invalid runtime background frame.",
+          );
+        }
+        backgroundColor = background.getAttribute("fill")?.trim() || null;
+        if (!backgroundColor) {
+          throw new Error(
+            "Downloaded SVG artifact runtime background needs a fill color.",
+          );
+        }
+      }
+      const expectedRootChildCount = background ? 2 : 1;
+      if (
+        root.children.length !== expectedRootChildCount ||
+        root.children[expectedRootChildCount - 1] !== productScene
+      ) {
+        throw new Error(
+          "Downloaded SVG artifact has unexpected root-owned content.",
+        );
+      }
+
+      const forbidden = new Set(forbiddenNames);
+      const primitives = new Set(primitiveNames);
+      const nonRendering = new Set(nonRenderingNames);
+      const elements = [root, ...root.querySelectorAll("*")];
+      const definedIds = new Set<string>();
+      const referencedIds = new Set<string>();
+      let vectorElementCount = 0;
+      for (const element of elements) {
+        for (const node of element.childNodes) {
+          if (
+            node.nodeType !== Node.ELEMENT_NODE &&
+            node.nodeType !== Node.TEXT_NODE
+          ) {
+            throw new Error(
+              "Downloaded SVG artifact may contain only elements and text nodes.",
+            );
+          }
+        }
+        if (element.namespaceURI !== namespace) {
+          throw new Error("Downloaded SVG artifact mixes XML namespaces.");
+        }
+        const name = element.localName.toLowerCase();
+        if (forbidden.has(name)) {
+          throw new Error(
+            `Downloaded SVG artifact contains forbidden <${element.localName}> content.`,
+          );
+        }
+        if (
+          primitives.has(name) &&
+          productScene.contains(element)
+        ) {
+          let ancestor = element.parentElement;
+          let hiddenDefinition = false;
+          while (ancestor && !ancestor.isSameNode(root)) {
+            hiddenDefinition ||= nonRendering.has(ancestor.localName.toLowerCase());
+            ancestor = ancestor.parentElement;
+          }
+          if (!hiddenDefinition) vectorElementCount += 1;
+        }
+
+        for (const attribute of element.attributes) {
+          const attributeName = attribute.localName.toLowerCase();
+          const value = attribute.value.trim();
+          if (attributeName === "id") {
+            if (!value || definedIds.has(value)) {
+              throw new Error(
+                "Downloaded SVG artifact ids must be non-empty and unique.",
+              );
+            }
+            definedIds.add(value);
+          }
+          if (attributeName.startsWith("on")) {
+            throw new Error(
+              `Downloaded SVG artifact contains event attribute ${attribute.name}.`,
+            );
+          }
+          if (
+            attributeName === "href" ||
+            attributeName === "src"
+          ) {
+            if (!value.startsWith("#")) {
+              throw new Error(
+                `Downloaded SVG artifact contains external ${attribute.name}.`,
+              );
+            }
+            const referencedId = value.slice(1).trim();
+            if (!referencedId) {
+              throw new Error(
+                `Downloaded SVG artifact ${attribute.name} must name a local element.`,
+              );
+            }
+            referencedIds.add(referencedId);
+          }
+          const urlPattern = /url\(\s*(['"]?)(.*?)\1\s*\)/giu;
+          for (const match of value.matchAll(urlPattern)) {
+            const reference = match[2]?.trim() ?? "";
+            if (!reference.startsWith("#")) {
+              throw new Error(
+                `Downloaded SVG artifact contains an external url() in ${attribute.name}.`,
+              );
+            }
+            const referencedId = reference.slice(1).trim();
+            if (!referencedId) {
+              throw new Error(
+                `Downloaded SVG artifact url() in ${attribute.name} must name a local element.`,
+              );
+            }
+            referencedIds.add(referencedId);
+          }
+        }
+      }
+      for (const referencedId of referencedIds) {
+        if (!definedIds.has(referencedId)) {
+          throw new Error(
+            `Downloaded SVG artifact local reference #${referencedId} has no target.`,
+          );
+        }
+      }
+      if (vectorElementCount === 0) {
+        throw new Error(
+          "Downloaded SVG artifact contains no visible vector primitive.",
+        );
+      }
+
+      const objectUrl = URL.createObjectURL(
+        new Blob([svgSource], { type: "image/svg+xml" }),
+      );
+      const image = new Image();
+      try {
+        image.src = objectUrl;
+        await image.decode();
+        if (image.naturalWidth <= 0 || image.naturalHeight <= 0) {
+          throw new Error("Downloaded SVG artifact decoded with empty bounds.");
+        }
+      } finally {
+        URL.revokeObjectURL(objectUrl);
+      }
+
+      return {
+        backgroundColor,
+        height,
+        vectorElementCount,
+        viewBox: [
+          Number(viewBox[0]),
+          Number(viewBox[1]),
+          Number(viewBox[2]),
+          Number(viewBox[3]),
+        ] as const,
+        width,
+      };
+    },
+    {
+      backgroundAttribute: TOOLCRAFT_SVG_BACKGROUND_ATTRIBUTE,
+      forbiddenNames: TOOLCRAFT_FORBIDDEN_SVG_ELEMENTS,
+      namespace: TOOLCRAFT_SVG_NAMESPACE,
+      nonRenderingNames: TOOLCRAFT_SVG_NON_RENDERING_CONTAINERS,
+      primitiveNames: TOOLCRAFT_SVG_VECTOR_PRIMITIVES,
+      productSceneAttribute: TOOLCRAFT_SVG_PRODUCT_SCENE_ATTRIBUTE,
+      svgSource: source,
+    },
+  );
+
+  const inspection = Object.freeze({
+    byteLength: bytes.byteLength,
+    backgroundColor: decoded.backgroundColor,
+    contentHash: createHash("sha256").update(bytes).digest("hex"),
+    height: decoded.height,
+    kind: "svg",
+    mediaType: "image/svg+xml",
+    vectorElementCount: decoded.vectorElementCount,
+    viewBox: decoded.viewBox,
+    width: decoded.width,
+  });
+  inspectedSvgArtifacts.add(inspection);
+  return Object.freeze({
+    inspection,
+    source,
+  });
+}

package/templates/starter/e2e/svg-download-test-fixtures.ts

@@ -0,0 +1,34 @@
+import type { Download, Page } from "@playwright/test";
+
+export async function createToolcraftSvgFixtureDownload(
+  page: Page,
+  source: string,
+  fileName = "column-graph.svg",
+): Promise<Download> {
+  await page.setContent('<button id="svg-download">Download SVG</button>');
+  await page.evaluate(
+    ({ downloadFileName, svgSource }) => {
+      const button = document.querySelector<HTMLButtonElement>("#svg-download");
+      if (!button) throw new Error("SVG fixture download button is missing.");
+      button.addEventListener(
+        "click",
+        () => {
+          const url = URL.createObjectURL(
+            new Blob([svgSource], { type: "image/svg+xml;charset=utf-8" }),
+          );
+          const anchor = document.createElement("a");
+          anchor.download = downloadFileName;
+          anchor.href = url;
+          anchor.click();
+          setTimeout(() => URL.revokeObjectURL(url), 0);
+        },
+        { once: true },
+      );
+    },
+    { downloadFileName: fileName, svgSource: source },
+  );
+
+  const downloadPromise = page.waitForEvent("download");
+  await page.locator("#svg-download").click();
+  return downloadPromise;
+}

package/templates/starter/e2e/toolcraft-delivery-catalog-reporter.ts

@@ -1,28 +1,211 @@
-import type { FullConfig, Reporter, Suite } from "@playwright/test/reporter";
+import type {
+  FullConfig,
+  FullResult,
+  Reporter,
+  Suite,
+} from "@playwright/test/reporter";
+import path from "node:path";
 
 import { deriveToolcraftPerformancePaths } from "@repo/toolcraft-runtime";
 
 import { createToolcraftDeliveryCatalog } from "../scripts/playwright-test-title-selection.mjs";
 import { getToolcraftPlaywrightContainingFile } from "../scripts/playwright-containing-file.mjs";
-import { starterAcceptance } from "../src/app/starter-acceptance-data";
+import { getToolcraftMotionReferenceArtifactErrors } from "../scripts/toolcraft-motion-reference-artifacts.mjs";
+import type { ToolcraftAcceptanceValidationInput } from "../src/app/acceptance/validate-coverage";
+import {
+  starterAcceptance,
+  starterControlSectionInventory,
+  starterProductReadiness,
+  starterTransferMode,
+  validateToolcraftAcceptanceCoverage,
+} from "../src/app/starter-acceptance";
 import { starterPerformance } from "../src/app/starter-performance";
 import { starterSchema } from "../src/app/starter-schema";
 
+type ToolcraftDeliveryCatalogReferenceValidationInput =
+  ToolcraftAcceptanceValidationInput & { rootDir: string };
+
+type ToolcraftMotionReferenceArtifactValidator =
+  typeof getToolcraftMotionReferenceArtifactErrors;
+
+type ToolcraftDeliveryCatalogFactoryInput = Readonly<{
+  acceptance: typeof starterAcceptance;
+  availableTests: readonly Readonly<{ file: string; testName: string }>[];
+  derivePerformancePaths: typeof deriveToolcraftPerformancePaths;
+  performance: typeof starterPerformance;
+  rootDir: string;
+  schema: typeof starterSchema;
+}>;
+
+type ToolcraftDeliveryCatalogFactory = (
+  input: ToolcraftDeliveryCatalogFactoryInput,
+) => unknown;
+
+type ToolcraftDeliveryCatalogReporterState =
+  | Readonly<{ kind: "idle" }>
+  | Readonly<{ error: unknown; kind: "preparation-failed" }>
+  | Readonly<{
+      catalogInput: ToolcraftDeliveryCatalogFactoryInput;
+      kind: "ready";
+      referenceValidationInput: ToolcraftDeliveryCatalogReferenceValidationInput;
+    }>;
+
+type ToolcraftDeliveryCatalogReporterOptions = Readonly<{
+  createCatalog?: ToolcraftDeliveryCatalogFactory;
+  validateReferences?: typeof validateToolcraftDeliveryCatalogReferences;
+  writeError?: (source: string) => void;
+  writeOutput?: (source: string) => void;
+}>;
+
+function getToolcraftPlaywrightProjectRoot(config: FullConfig): string {
+  if (
+    typeof config.configFile !== "string" ||
+    config.configFile.length === 0 ||
+    !path.isAbsolute(config.configFile)
+  ) {
+    throw new Error(
+      "Toolcraft delivery catalog requires an absolute Playwright configFile so project-relative reference artifacts resolve from the app root.",
+    );
+  }
+  return path.dirname(config.configFile);
+}
+
+class ToolcraftReferenceValidationError extends Error {
+  override readonly name = "ToolcraftReferenceValidationError";
+}
+
+function describeUnexpectedError(
+  error: unknown,
+  seen: ReadonlySet<unknown> = new Set(),
+): string {
+  if (!(error instanceof Error)) return String(error);
+  if (seen.has(error)) return "[circular error cause]";
+  const nextSeen = new Set(seen).add(error);
+  const description = error.stack ?? `${error.name}: ${error.message}`;
+  return error.cause === undefined
+    ? description
+    : `${description}\nCaused by: ${describeUnexpectedError(error.cause, nextSeen)}`;
+}
+
+function describeReporterError(error: unknown): string {
+  return error instanceof ToolcraftReferenceValidationError
+    ? error.message
+    : describeUnexpectedError(error);
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unexpected Toolcraft catalog reporter state: ${String(value)}`);
+}
+
+export async function validateToolcraftDeliveryCatalogReferences(
+  {
+    acceptance,
+    productReadiness,
+    rootDir,
+    schema,
+    sectionInventory,
+    transferMode,
+  }: ToolcraftDeliveryCatalogReferenceValidationInput,
+  validateArtifacts: ToolcraftMotionReferenceArtifactValidator =
+    getToolcraftMotionReferenceArtifactErrors,
+): Promise<void> {
+  const semanticErrors = validateToolcraftAcceptanceCoverage({
+    acceptance,
+    productReadiness,
+    schema,
+    sectionInventory,
+    transferMode,
+  });
+  const artifactErrors = transferMode.referenceInputs.length === 0
+    ? []
+    : await validateArtifacts({
+        referenceInputs: transferMode.referenceInputs,
+        rootDir,
+      });
+  const errors = [...semanticErrors, ...artifactErrors];
+  if (errors.length > 0) {
+    throw new ToolcraftReferenceValidationError(
+      `Toolcraft reference validation failed:\n${errors.join("\n")}`,
+    );
+  }
+}
+
 export default class ToolcraftDeliveryCatalogReporter implements Reporter {
-  onBegin(config: FullConfig, suite: Suite): void {
-    const availableTests = suite.allTests().map((entry) => ({
-      file: getToolcraftPlaywrightContainingFile(entry, config.rootDir),
-      testName: entry.title,
-    }));
-    const catalog = createToolcraftDeliveryCatalog({
-      acceptance: starterAcceptance,
-      availableTests,
-      derivePerformancePaths: deriveToolcraftPerformancePaths,
-      performance: starterPerformance,
-      rootDir: config.rootDir,
-      schema: starterSchema,
+  private readonly createCatalog: ToolcraftDeliveryCatalogFactory;
+  private state: ToolcraftDeliveryCatalogReporterState = { kind: "idle" };
+  private readonly validateReferences: typeof validateToolcraftDeliveryCatalogReferences;
+  private readonly writeError: (source: string) => void;
+  private readonly writeOutput: (source: string) => void;
+
+  constructor(options: ToolcraftDeliveryCatalogReporterOptions = {}) {
+    this.createCatalog = options.createCatalog ?? createToolcraftDeliveryCatalog;
+    this.validateReferences =
+      options.validateReferences ?? validateToolcraftDeliveryCatalogReferences;
+    this.writeError = options.writeError ?? ((source) => {
+      process.stderr.write(source);
+    });
+    this.writeOutput = options.writeOutput ?? ((source) => {
+      process.stdout.write(source);
     });
-    process.stdout.write(`${JSON.stringify(catalog)}\n`);
+  }
+
+  onBegin(config: FullConfig, suite: Suite): void {
+    try {
+      const projectRoot = getToolcraftPlaywrightProjectRoot(config);
+      const referenceValidationInput = {
+        acceptance: starterAcceptance,
+        productReadiness: starterProductReadiness,
+        rootDir: projectRoot,
+        schema: starterSchema,
+        sectionInventory: starterControlSectionInventory,
+        transferMode: starterTransferMode,
+      };
+      const availableTests = suite.allTests().map((entry) => ({
+        file: getToolcraftPlaywrightContainingFile(entry, config.rootDir),
+        testName: entry.title,
+      }));
+      const catalogInput = {
+        acceptance: starterAcceptance,
+        availableTests,
+        derivePerformancePaths: deriveToolcraftPerformancePaths,
+        performance: starterPerformance,
+        rootDir: config.rootDir,
+        schema: starterSchema,
+      };
+      this.state = { catalogInput, kind: "ready", referenceValidationInput };
+    } catch (error) {
+      this.state = { error, kind: "preparation-failed" };
+    }
+  }
+
+  async onEnd(_result: FullResult): Promise<{ status: "failed" } | void> {
+    const state = this.state;
+    switch (state.kind) {
+      case "idle":
+        return this.reportFailure(new Error(
+          "Toolcraft delivery catalog reporter did not receive a complete onBegin lifecycle.",
+        ));
+      case "preparation-failed":
+        return this.reportFailure(state.error);
+      case "ready":
+        try {
+          await this.validateReferences(state.referenceValidationInput);
+          const catalog = this.createCatalog(state.catalogInput);
+          this.writeOutput(`${JSON.stringify(catalog)}\n`);
+          return;
+        } catch (error) {
+          return this.reportFailure(error);
+        }
+      default:
+        return assertNever(state);
+    }
+  }
+
+  private reportFailure(error: unknown): { status: "failed" } {
+    this.writeError(
+      `Toolcraft delivery catalog collection failed:\n${describeReporterError(error)}\n`,
+    );
+    return { status: "failed" };
   }
 
   printsToStdio(): boolean {